From 73434653c11f9a0b93e8a1930414a026aa816d78 Mon Sep 17 00:00:00 2001
From: 7418 <7418@openclaw.ai>
Date: Sat, 14 Mar 2026 16:30:31 +0800
Subject: [PATCH] docs: update Feishu bridge setup guide for V2

- Add card.action.trigger callback requirement under Events & Callbacks
- Add long connection mode note (no Encrypt Key / Verification Token needed)
- Expand permissions table: cardkit:card:write/read, im:message:update,
  im:message.reactions:read/write_only, and optional future permissions
- Update CodePilot config section to reflect simplified UI (2 cards)
- Update message format section for streaming cards, tool progress, thinking state
- Add troubleshooting for permission buttons and streaming cards
- Sync English and Chinese versions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 apps/site/content/docs/en/bridge/feishu.mdx | 103 +++++++++++++++-----
 apps/site/content/docs/zh/bridge/feishu.mdx | 103 +++++++++++++++-----
 2 files changed, 162 insertions(+), 44 deletions(-)

diff --git a/apps/site/content/docs/en/bridge/feishu.mdx b/apps/site/content/docs/en/bridge/feishu.mdx
index 22209d1..b08e96c 100644
--- a/apps/site/content/docs/en/bridge/feishu.mdx
+++ b/apps/site/content/docs/en/bridge/feishu.mdx
@@ -5,7 +5,7 @@ description: Configure the Feishu / Lark bridge.
 
 # Feishu Bridge
 
-Chat with Claude through a Feishu (or Lark) app. Supports switching between the domestic and international editions, and group policy control.
+Chat with Claude through a Feishu (or Lark) app. Supports streaming card output, tool call progress display, permission approval buttons, and quick project switching.
 
 ## Create a Feishu App
 
@@ -17,15 +17,57 @@ Chat with Claude through a Feishu (or Lark) app. Supports switching between the
 4. On the app details page, under **Credentials & Basic Info**, obtain:
    - **App ID** (format: `cli_xxxxxxxxxx`)
    - **App Secret**
+
+### Add Capabilities
+
 5. In the left menu, select **Add Capabilities > Bot** to enable the bot capability
-6. Under **Event Subscriptions**, select **Long Connection Mode** (WebSocket, no public IP required):
-   - Long connection mode must be started before you can save the configuration — click enable and wait for the connection to be established
-   - Once connected, add the event: `im.message.receive_v1` (receive messages)
-   - Save the event subscription configuration
-7. Under **Permissions**, request the following:
-   - `im:message` (send messages)
-   - `im:message.group_at_msg` (receive group chat @messages)
-   - `im:message.p2p_msg` (receive DM messages)
+
+### Events & Callbacks
+
+6. Under **Events & Callbacks**, configure:
+   - Select **Long Connection Mode** (WebSocket, no public IP or Encrypt Key / Verification Token required)
+   - Add event: `im.message.receive_v1` (receive messages)
+   - Add callback: `card.action.trigger` (card interaction callback, used for permission approval buttons and project selection)
+   - Save the configuration
+
+### Permissions
+
+7. Under **Permissions**, add the following permissions (you can paste the scope list in "Batch Enable"):
+
+**App Permissions (tenant scope):**
+
+| Permission | Description |
+|------------|-------------|
+| `im:message:send_as_bot` | Send messages as Bot |
+| `im:message:readonly` | Read message content |
+| `im:message.p2p_msg:readonly` | Receive DM messages |
+| `im:message.group_at_msg:readonly` | Receive group chat @messages |
+| `im:message:update` | Update messages (streaming card updates) |
+| `im:message.reactions:read` | Read message reactions |
+| `im:message.reactions:write_only` | Add/remove reactions (typing indicator) |
+| `im:chat:read` | Read group chat info |
+| `im:resource` | Download message resources (images, etc.) |
+| `cardkit:card:write` | Create and update streaming cards |
+| `cardkit:card:read` | Read card status |
+
+The following permissions are optional, for future platform capability extensions:
+
+| Permission | Description |
+|------------|-------------|
+| `im:chat:update` | Update group chat settings |
+| `im:message.pins:read` | Read pinned messages |
+| `im:message.pins:write_only` | Pin/unpin messages |
+| `im:message:recall` | Recall messages |
+| `im:message:send_multi_users` | Send messages to multiple users |
+| `im:message:send_sys_msg` | Send system messages |
+| `contact:contact.base:readonly` | Read contacts basic info |
+| `docx:document:readonly` | Read document content |
+| `application:application:self_manage` | App self-management |
+
+**User Permissions (user scope)** — If you need user-level document/calendar/task capabilities, add the corresponding permissions as needed. See the Feishu Open Platform documentation for the full list.
+
+### Publish the App
+
 8. **Publish the app** — submit for review or self-approve
 
 ### International Edition (Lark)
@@ -38,13 +80,13 @@ The process is the same as the domestic edition, but performed on [Lark Develope
 2. Select domain: **Feishu** (domestic) or **Lark** (international)
 3. Enter the **App ID** and **App Secret**
 4. Click **Test Connection** to verify the credentials
-5. Configure group policy:
-   - **Open** — Bot responds to @messages in all group chats
-   - **Allowlist** — Only responds in specified group chats (enter group chat_id values)
-   - **Disabled** — Only responds in DMs
-6. (Optional) **Require @mention** — When enabled, the Bot only responds to messages that @mention it in group chats
-7. (Optional) **Allowed Users** — Enter Feishu open_id or chat_id values to restrict who can use the Bot
-8. Click **Save**
+5. Configure Access & Behavior:
+   - **DM Policy** — Control who can DM the Bot (Open / Pairing / Allowlist / Disabled)
+   - **Allow From** — Enter Feishu open_id values to restrict allowed users, `*` for all
+   - **Group Policy** — Control how the Bot responds in group chats (Open / Allowlist / Disabled)
+   - **Require @mention** — When enabled, the Bot only responds to messages that @mention it in group chats
+   - **Thread Sessions** — When enabled, different threads have independent conversation contexts
+6. Click **Save**
 
 ## Enable the Bridge
 
@@ -55,11 +97,16 @@ The process is the same as the domestic edition, but performed on [Lark Develope
 
 ## Message Format
 
-The Feishu bridge converts Claude's replies into Feishu message format:
+The Feishu bridge uses streaming cards for Claude's replies:
 
-- Complex replies (containing code blocks, tables, etc.) → Interactive Card
-- Simple replies → Rich text message (Post)
-- Maximum 30,000 characters per message (splitting is usually not needed)
+- **Streaming cards** — Real-time display of the generation process, with Markdown rendering (code highlighting, tables, lists, etc.)
+- **Tool call progress** — Real-time display of 🔄 Running / ✅ Complete / ❌ Error
+- **Thinking state** — Shows 💭 Thinking... before text arrives
+- **Footer info** — Status indicator + elapsed time
+- **Permission approval** — Inline button cards, click to Allow / Deny
+- **Project switching** — `/cwd` command shows a project selector card
+
+Command responses and error messages use rich text messages (Post) with Markdown formatting.
 
 ## Troubleshooting
 
@@ -72,13 +119,25 @@ The Feishu bridge converts Claude's replies into Feishu message format:
 ### Bot not responding in group chats
 
 1. Confirm the bot capability has been added
-2. Confirm the `im:message.group_at_msg` permission has been granted
+2. Confirm the `im:message.group_at_msg:readonly` permission has been granted
 3. Confirm the group policy is not set to "Disabled"
 4. If the policy is set to "Allowlist", confirm the group chat ID is in the allowed list
 5. If "Require @mention" is enabled, make sure the message @mentions the Bot
 
 ### Bot not responding in DMs
 
-1. Confirm the `im:message.p2p_msg` permission has been granted
+1. Confirm the `im:message.p2p_msg:readonly` permission has been granted
 2. Confirm the app has been published
 3. Search for the Bot by name in Feishu and start a DM
+
+### Permission buttons not working
+
+1. Confirm you have added `card.action.trigger` callback under **Events & Callbacks**
+2. Confirm you are using **Long Connection Mode** (WSClient), not HTTP Webhook mode
+3. Check CodePilot logs for `[feishu/gateway] handleEventData type: card` output
+
+### Streaming cards not showing
+
+1. Confirm the `cardkit:card:write` and `cardkit:card:read` permissions have been granted
+2. Confirm the app has been re-published (permission changes require re-publishing)
+3. Check CodePilot logs for `[card-controller]` related output
diff --git a/apps/site/content/docs/zh/bridge/feishu.mdx b/apps/site/content/docs/zh/bridge/feishu.mdx
index d3724c6..0b04a68 100644
--- a/apps/site/content/docs/zh/bridge/feishu.mdx
+++ b/apps/site/content/docs/zh/bridge/feishu.mdx
@@ -5,7 +5,7 @@ description: 配置飞书 / Lark 桥接。
 
 # 飞书桥接
 
-通过飞书（或 Lark）应用与 Claude 对话。支持国内版和国际版切换、群组策略控制。
+通过飞书（或 Lark）应用与 Claude 对话。支持流式卡片输出、工具调用进度显示、权限审批按钮、项目快捷切换。
 
 ## 创建飞书应用
 
@@ -17,15 +17,57 @@ description: 配置飞书 / Lark 桥接。
 4. 进入应用详情页，在 **凭证与基础信息** 中获取：
    - **App ID**（格式：`cli_xxxxxxxxxx`）
    - **App Secret**
+
+### 添加应用能力
+
 5. 在左侧选择 **添加应用能力 > 机器人**，启用机器人功能
-6. 在 **事件订阅** 中，先选择 **使用长连接模式**（WebSocket，无需公网地址）：
-   - 长连接模式需要先启动才能保存配置 — 点击启用后等待连接建立
-   - 连接建立成功后，再添加事件：`im.message.receive_v1`（接收消息）
-   - 保存事件订阅配置
-7. 在 **权限管理** 中申请以下权限：
-   - `im:message`（发送消息）
-   - `im:message.group_at_msg`（接收群聊 @消息）
-   - `im:message.p2p_msg`（接收私聊消息）
+
+### 事件与回调
+
+6. 在 **事件与回调** 中配置：
+   - 选择 **使用长连接模式**（WebSocket，无需公网地址或 Encrypt Key / Verification Token）
+   - 添加事件：`im.message.receive_v1`（接收消息）
+   - 添加回调：`card.action.trigger`（卡片回传交互回调，用于权限审批按钮和项目选择）
+   - 保存配置
+
+### 权限管理
+
+7. 在 **权限管理** 中，批量添加以下权限（可在「批量开通」中粘贴 scope 列表）：
+
+**应用权限（tenant scope）：**
+
+| 权限 | 说明 |
+|------|------|
+| `im:message:send_as_bot` | 以 Bot 身份发送消息 |
+| `im:message:readonly` | 读取消息内容 |
+| `im:message.p2p_msg:readonly` | 接收私聊消息 |
+| `im:message.group_at_msg:readonly` | 接收群聊 @消息 |
+| `im:message:update` | 更新消息（流式卡片更新） |
+| `im:message.reactions:read` | 读取消息表情回复 |
+| `im:message.reactions:write_only` | 添加/删除表情回复（typing 指示器） |
+| `im:chat:read` | 读取群聊信息 |
+| `im:resource` | 下载消息中的资源（图片等） |
+| `cardkit:card:write` | 创建和更新流式卡片 |
+| `cardkit:card:read` | 读取卡片状态 |
+
+以下权限为可选，用于未来平台能力扩展：
+
+| 权限 | 说明 |
+|------|------|
+| `im:chat:update` | 更新群聊设置 |
+| `im:message.pins:read` | 读取置顶消息 |
+| `im:message.pins:write_only` | 置顶/取消置顶消息 |
+| `im:message:recall` | 撤回消息 |
+| `im:message:send_multi_users` | 向多人发送消息 |
+| `im:message:send_sys_msg` | 发送系统消息 |
+| `contact:contact.base:readonly` | 读取通讯录基础信息 |
+| `docx:document:readonly` | 读取文档内容 |
+| `application:application:self_manage` | 应用自管理 |
+
+**用户权限（user scope）** — 如需用户级别的文档/日历/任务等能力，可按需添加对应权限。完整列表请参考飞书开放平台文档。
+
+### 发布应用
+
 8. **发布应用** — 提交审核或自审通过
 
 ### 国际版（Lark）
@@ -38,13 +80,13 @@ description: 配置飞书 / Lark 桥接。
 2. 选择域名：**飞书**（国内版）或 **Lark**（国际版）
 3. 填写 **App ID** 和 **App Secret**
 4. 点击 **测试连接** 验证凭据
-5. 配置群组策略：
-   - **开放** — Bot 响应所有群聊中的 @消息
-   - **白名单** — 只响应指定群聊（填写群聊 chat_id）
-   - **禁用** — 只响应私聊
-6. （可选）**需要 @提及** — 开启后群聊中只响应 @Bot 的消息
-7. （可选）**允许的用户** — 填写飞书 open_id 或 chat_id，限制谁可以使用 Bot
-8. 点击 **保存**
+5. 配置访问与行为：
+   - **私信策略** — 控制谁可以向 Bot 发私信（开放 / 配对 / 白名单 / 禁用）
+   - **允许来源** — 填写飞书 open_id 限制可用用户，`*` 表示不限
+   - **群聊策略** — 控制 Bot 在群聊中的响应方式（开放 / 白名单 / 禁用）
+   - **需要 @提及** — 开启后群聊中只响应 @Bot 的消息
+   - **话题会话** — 启用后不同话题拥有独立的对话上下文
+6. 点击 **保存**
 
 ## 启用桥接
 
@@ -55,11 +97,16 @@ description: 配置飞书 / Lark 桥接。
 
 ## 消息格式
 
-飞书桥接会将 Claude 的回复转换为飞书消息格式：
+飞书桥接使用流式卡片输出 Claude 的回复：
 
-- 复杂回复（含代码块、表格等）→ 消息卡片（Interactive Card）
-- 简单回复 → 富文本消息（Post）
-- 单条消息最大 30000 字符（通常无需分片）
+- **流式卡片** — 实时显示生成过程，支持 Markdown 渲染（代码高亮、表格、列表等）
+- **工具调用进度** — 实时显示 🔄 Running / ✅ Complete / ❌ Error
+- **Thinking 状态** — 在文本到达前显示 💭 Thinking...
+- **页脚信息** — 状态指示 + 耗时显示
+- **权限审批** — 内联按钮卡片，点击即可 Allow / Deny
+- **项目切换** — `/cwd` 命令弹出项目选择器卡片
+
+命令响应和错误消息使用富文本消息（Post）+ Markdown 格式。
 
 ## 故障排除
 
@@ -72,13 +119,25 @@ description: 配置飞书 / Lark 桥接。
 ### Bot 不响应群聊
 
 1. 确认已添加机器人能力
-2. 确认已申请 `im:message.group_at_msg` 权限
+2. 确认已申请 `im:message.group_at_msg:readonly` 权限
 3. 确认群组策略不是"禁用"
 4. 如果策略为"白名单"，确认群聊 ID 在允许列表中
 5. 如果开启了"需要 @提及"，确保消息中 @了 Bot
 
 ### Bot 不响应私聊
 
-1. 确认已申请 `im:message.p2p_msg` 权限
+1. 确认已申请 `im:message.p2p_msg:readonly` 权限
 2. 确认应用已发布
 3. 在飞书中搜索 Bot 名称，发起私聊
+
+### 权限按钮无反应
+
+1. 确认已在 **事件与回调** 中添加了 `card.action.trigger` 回调
+2. 确认使用的是 **长连接模式**（WSClient），非 HTTP Webhook 模式
+3. 检查 CodePilot 日志中是否有 `[feishu/gateway] handleEventData type: card` 输出
+
+### 流式卡片不显示
+
+1. 确认已申请 `cardkit:card:write` 和 `cardkit:card:read` 权限
+2. 确认应用已重新发布（权限变更后需要重新发布）
+3. 检查 CodePilot 日志中是否有 `[card-controller]` 相关输出