@jesonliu/lark-claudecode-bridge 0.18.1 → 0.20.0

package/README.md

@@ -16,13 +16,15 @@
 - **多机器人**：一个进程同时跑 N 个飞书机器人，各自独立会话池、独立并发、独立人格（`append_system_prompt`）；共享同一套 Claude 配置
 - 写操作确认嵌在计时进度卡底部（允许 / 拒绝 / 本次会话不再询问，仅任务发起人可点；Write/Edit 直接展示红绿 diff；等待确认时正文自动收敛，决策后按钮消失、状态行显示结果）
 - **读操作免确认**：读工具（Read/Grep/Glob 等）与 Bash 读命令默认直通，危险命令黑名单兜底；白名单可通过 `permissions.allow_tools` 自定义（配置页可增删，新建配置默认预置完整默认值）
-- **开发场景工作流（`type: code-dev`）**：统一 plan mode——先出计划 → 飞书卡片批准/按意见修改/放弃 → 批准后自动执行；任务收尾发汇总 diff 卡片（红绿着色），不再整文件刷屏
+- **计划模式（/plan 命令）**：飞书里发 `/plan` 按通道切换——开启后每个任务先出计划 → 飞书卡片批准/按意见修改/放弃 → 批准后自动执行；git 仓库工作区任务收尾发汇总 diff 卡片（红绿着色），不再整文件刷屏
 - 流式进度卡片（打字机效果 + 工具调用 + 运行心跳，静默不等于卡死）
 - **接收图片与富文本**：直接给机器人发图片（下载到 `~/.lark-claudecode-bridge/inbox/`，Claude 用 Read 工具识图）；粘贴的多行/带格式内容（post 富文本）自动拍平为多行文本；不支持的类型（语音等）私聊会回复提示；入站消息按 message_id 去重（WS 重投不会导致任务跑两遍）
-- 结果文本 + 产出文件回传（图片预览、>10 文件自动 zip；generic 工作区）
+- 结果文本 + 产出文件回传（图片预览、>10 文件自动 zip）
 - 多工作区切换（/ws）、会话管理（/new /resume）、/stop 打断、模型切换（/model）、厂商档案切换（/model-profile）、加载清单查看（/skills /plugins /mcp）、插件管理（/plugin）
 - **后台子代理续跑**：主 Agent 派发的后台子代理在主回复结束后继续执行，完成后自动唤醒主循环汇总结果（进度卡可见「等待后台任务」与子代理输出）
 - **对话内容落盘**：用户消息与 Claude 回复全文存为 JSONL（`transcripts/`，为后续知识库挖掘打底；可选保留期）
+- **回复链上游自动拼入 prompt**：在飞书里「回复」某条消息再发新指令，上游最多 3 层消息文本会作为引用附在新消息前部一起发给 Claude（需 `im:message` 读取权限；失败降级只发当前消息）
+- **Skills / MCP 可视化管理页**：配置页新增「Skills」「MCP」两页——Skills 三来源（用户级·本机 / 用户级·bridge / 项目级·工作区） + zip 导入；MCP 三来源 + 命令方式（`claude mcp add`）/ JSON 配置 + 状态探测 + 抽屉查看 env 引用展开当前值。页面添加的 MCP 存 `~/.lark-claudecode-bridge/mcp/servers.json`，任务级热生效（无须重启）
 - 通道并发（默认 3），通道内串行
 
 ## 前置条件
@@ -46,7 +48,7 @@ lcb start
 ## 飞书应用配置（图文）
 
 1. https://open.feishu.cn → 创建企业自建应用 → 添加「机器人」能力
-2. 权限管理开通：`im:message`、`im:message:send_as_bot`、`im:resource`（**接收用户图片时下载消息资源用，不开则图片任务会提示下载失败**）、`contact:user.base:readonly`、`application:app_slash_command:write` / `application:app_slash_command:read`（斜杠命令一键同步用，见下）
+2. 权限管理开通：`im:message`（**含读取单条消息：回复链上游内容拼接用，不开则回复消息时降级为只发当前消息**）、`im:message:send_as_bot`、`im:resource`（**接收用户图片时下载消息资源用，不开则图片任务会提示下载失败**）、`contact:user.base:readonly`、`application:app_slash_command:write` / `application:app_slash_command:read`（斜杠命令一键同步用，见下）、`cardkit:card:write`（**强烈建议开通：卡片实体模式，进度卡状态局部刷新、计划/提问表单输入不被心跳清空**。不开时自动降级为整卡更新——功能不缺，但任务运行中的状态刷新体验受限；0.20.0 起降级模式下挂起输入已有冻结保护，正在输入的意见/自定义答案不会被清掉）
 3. 事件与回调 → 事件配置 → 订阅方式选「使用长连接接收事件」→ 添加 `im.message.receive_v1`
 4. 事件与回调 → 回调配置 → 订阅方式选「使用长连接接收回调」→「已订阅的回调」点「添加回调」，添加「卡片回传交互」（`card.action.trigger`）
 5. 凭证与基础信息 → 复制 App ID / App Secret
@@ -88,7 +90,7 @@ lcb start
 配置页「概览」支持托管桥接器进程与自更新（源码 tsx 运行模式下自动降级为手动指引）：
 
 - **启停/重启**：概览「运行状态」卡显示桥接器进程状态（PID），可一键启动（后台守护进程）/ 停止 / 重启。`lcb start` 内嵌页面停止/重启时页面随进程短暂失联后自动恢复；`lcb ui` 独立页面则跨进程操作（Windows 下停止为硬终止，会话逐消息落盘不受影响）。
-- **后台运行日志**：经页面启动/重启的桥接器，输出落 `~/.lark-claudecode-bridge/bridge.log`（超 5MB 自动截断）；进程 PID 记录于同目录 `bridge.pid`（进程消亡后自动清理）。
+- **后台运行日志**：桥接器输出按天落 `~/.lark-claudecode-bridge/logs/bridge-YYYY-MM-DD.log`（自动跨天切换，保留 14 天）；进程 PID 记录于 `~/.lark-claudecode-bridge/bridge.pid`（进程消亡后自动清理）。
 - **版本更新**：概览「版本与更新」卡自动对比 npm registry（跟随本机 `.npmrc` 镜像配置）与当前版本；有新版时一键更新（`npm install -g`）并自动重启生效。
 
 ## 命令速查（飞书里发给机器人）
@@ -129,7 +131,7 @@ apps:                      # 多机器人：每个应用一条长连接
 workspaces:                # 工作区白名单（列表全局共享；「当前用哪个」per-app 隔离）
   - name: demo
     path: F:\workspace\demo
-    # type: code-dev       # 代码开发工作区：统一 plan mode + 收尾汇总 diff 卡片；缺省 generic
+    # 计划模式在飞书发 /plan 按通道切换；git 仓库工作区收尾自动发汇总 diff 卡片
 defaults:
   workspace: demo
 concurrency: 3             # 通道间并发上限（未单独配置的 app 沿用）
@@ -176,23 +178,23 @@ concurrency: 3             # 通道间并发上限（未单独配置的 app 沿
 
 **插件双目录（managed 模式）**：新装插件默认装到本机 `~/.claude`（与本机 claude CLI 共用一份），`/plugin install xxx --dir=managed` 或配置页安装框选「bridge 托管目录」可装到托管目录；启停/卸载自动按插件所在目录执行，两处清单在配置页「插件」tab 与 `/plugin list` 中均带来源标记。注意：**卸载按所选目录逐处执行**——同一插件在两个目录各装一份时，卸载一处不影响另一处（本机 CLI 的 `/plugins list` 看的是它自己的配置目录）；配置页卸载后会校验安装清单已清除，残留（仅被禁用）会显式报错并附 CLI 输出。配置页「管理市场」支持 git 地址与本机路径（本地路径市场按 CLI 语义不复制文件，登记原路径读取）。
 
-### 开发场景工作流（`type: code-dev`）
+### 计划模式工作流（/plan 命令）
 
-给代码开发类工作区设置 `type: code-dev` 后，每个任务自动走「先计划、后执行」：
+在飞书会话里发 `/plan`（或 `/plan on`）即可为当前通道开启计划模式，每个任务自动走「先计划、后执行」（`/plan off` 关闭；开关是通道级偏好，跨重启保留，`/new` 不清除）：
 
 1. **计划审批**：任务以 plan mode 启动（期间只允许读操作），Claude 查阅代码后提交计划 → 飞书收到计划卡片：
    - **✅ 批准执行**：批准即授权——Claude 自动切入 acceptEdits 模式按计划开工，**后续写文件不再逐次弹确认卡**（对齐本机 CLI「批准计划 → accept edits on」语义；Bash 危险命令黑名单仍生效，命中照弹确认）
    - **📝 按意见修改**：在卡片输入框填修改意见后点击，Claude 修订计划重新提交（同一会话内循环，直到批准或放弃）
    - **❌ 放弃计划**：任务终止；10 分钟无操作自动放弃
-2. **收尾汇总 diff**：任务完成后不再把改动文件逐个上传，而是发**汇总 diff 卡片**（标题含文件数与 +X/-Y 行统计，正文红绿着色，超长自动拆多张）。改动以 `git diff HEAD` + untracked 新文件为准，因此 **code-dev 工作区需要是 git 仓库**（非 git 仓库自动回退为旧的文件上传行为，并提示 `git init`）
+2. **收尾汇总 diff**：任务完成后不再把改动文件逐个上传，而是发**汇总 diff 卡片**（标题含文件数与 +X/-Y 行统计，正文红绿着色，超长自动拆多张）。改动以 `git diff HEAD` + untracked 新文件为准——**git 仓库工作区都会自动发**（非 git 仓库天然跳过，无需任何配置）
 
 **执行器为 Streaming Input 模式**（0.14.0 起）：prompt 经持久输入流送入 CLI，stdin 全程保持打开——这是计划审批与提问卡片能稳定工作的前提（旧版单轮模式在轮次边界会触发 CLI 的 "Stream closed" 中断，属 Agent SDK 已知问题）。**提问卡片**：Claude 调用 AskUserQuestion 时飞书收到问题选项卡，点选项作答（多选题可多选）、全部作答后「提交答案」——答案直接回传模型继续任务。
 
 **读操作免确认**：读工具与 Bash 默认直通（`ls`/`cat`/`grep` 不再弹卡），命中 `dangerous_commands` 黑名单（`rm -rf`、`sudo`、`git push --force` 等）仍弹确认卡；「本次会话不再询问」的记忆同样绕不过黑名单。想放行其它工具（如 `Edit`）往 `permissions.allow_tools` 追加即可——注意配置即**整体替换**内置默认，需把内置读工具一并写上。**白名单/黑名单热生效**（0.18.0 起）：配置页保存后，已有会话通道的下一个工具调用即用新名单（旧版需新通道或重启）。
 
-**plan mode 下的白名单语义**：code-dev 工作区的计划阶段，Claude Code 内部对写操作强制走桥接的权限闸（官方语义：plan 模式无视 CLI 侧 allow 规则、写工具一律路由到宿主判定）——因此桥接白名单在计划阶段对写工具**依然生效**（命中直通执行，未命中弹确认卡嵌在计时卡上），直到计划批准切回可编辑模式。只读工具不经桥接直接执行。计时卡上工具行的 `✘` 表示该次工具调用**执行失败**（含首行失败原因），不代表「工具没权限」。
+**plan mode 下的白名单语义**：计划模式开启时的计划阶段，Claude Code 内部对写操作强制走桥接的权限闸（官方语义：plan 模式无视 CLI 侧 allow 规则、写工具一律路由到宿主判定）——因此桥接白名单在计划阶段对写工具**依然生效**（命中直通执行，未命中弹确认卡嵌在计时卡上），直到计划批准切回可编辑模式。只读工具不经桥接直接执行。计时卡上工具行的 `✘` 表示该次工具调用**执行失败**（含首行失败原因），不代表「工具没权限」。
 
-> plan 卡片相关与 `workspaces[].type` 的改动需重启 bridge 进程生效（permissions 配置已支持热生效，见上）。
+> /plan 开关按通道即时生效（下一条任务起）；permissions 配置同样支持热生效（见上）。
 
 ### 配置继承（inherit 模式：本机 ~/.claude 一处配置，全机器人共享）
 
@@ -289,9 +291,9 @@ WantedBy=default.target
 6. **飞书 SDK 对非法 app_id 静默失败**：`ws.start()` 对形状不合法的 app_id 只打日志不报错，启动后请确认每条「✅ <应用名> 长连接已启动」状态行都出现了。
 7. **共享 ~/.claude 的副作用**：本机 user 级 hooks 也会在机器人任务里执行（含阻断型 PostToolUse hook）；`apps[].env` 的同名键会被 `~/.claude/settings.json` 的 `env` 覆盖（优先级：CLI flags（/model）> settings.json env > apps[].env > 进程环境）。插件加载失败 SDK 会静默跳过，实际加载情况以 `/plugins` 清单为准。
 8. **plan 卡片的「按意见修改」依赖飞书卡片输入框回传**：修改意见经卡片 input 组件随按钮回调传回；若个别客户端版本不回传输入值，点「按意见修改」会提示先填写意见——此时可改用「放弃计划」后在会话里直接发修改要求重新起任务。
-9. **code-dev 工作区的收尾 diff 基于 git**：`type: code-dev` 的工作区需要是 git 仓库（含未提交改动即可，无需 commit）；非 git 仓库自动回退为旧的整文件上传行为。untracked 新文件按全新增 diff 展示（目录级 untracked 与超过 20 个的 untracked 文件不展开）。
+9. **收尾 diff 基于 git**：工作区是 git 仓库（含未提交改动即可，无需 commit）且有改动时，任务收尾自动发汇总 diff 卡片；非 git 仓库天然跳过。untracked 新文件按全新增 diff 展示（目录级 untracked 与超过 20 个的 untracked 文件不展开）。
 10. **入站图片不清理**：用户发送的图片落盘 `~/.lark-claudecode-bridge/inbox/` 后不会自动删除（供会话内多次查看），长期使用可手动清理；Claude 是否能「看懂」图片取决于当前模型是否多模态（非多模态模型可配置识图 MCP 兜底）。富文本（post）中的超链接以 `[文字](链接)` 形式拍平进文本，@用户 被移除。
-11. **短回复不再单独发结果消息**：回复不超过进度卡正文上限（1200 字）时，结果就展示在进度卡终态里（避免同内容两条消息）；更长回复仍会单独发一条结果消息（进度卡只保留尾部）。
+11. **短回复不再单独发结果消息**：回复不超过进度卡终态上限（400 字）时，结果就展示在进度卡终态里（避免同内容两条消息）；更长回复仍会单独发一条结果消息（进度卡只保留尾部）。运行中的进度卡**不展示**过程文本与思考内容（主卡只留状态 / 当前工具 / 子代理 / 确认区 / 计时等关键信息）。
 12. **Web 配置页改 apps/workspaces 段会丢段内手写注释**：页面按整段替换写回（值未变的段落跳过重写、注释保留；`lcb ws add` 等增量命令不受影响）。手工注释建议写在段外或段头。
 13. **config.yaml 并发写**：配置页写盘为原子替换，但与 `lcb ws add` / `lcb app add` 等独立进程命令同时操作存在读-改-写窗口，请避免同时修改。
 14. **配置页默认仅本机可访问**（127.0.0.1）；改 `server.host` 放开到局域网意味着页面可读写全部凭证，请仅在可信网络使用。