@modelzen/feishu-codex-bridge 0.3.10 → 0.3.12-test.0

package/README.md

@@ -55,6 +55,21 @@
 
 ## 🚀 安装与启动
 
+### 0. 最省事：把一句话发给 Codex / Claude，让它帮你装
+
+不想碰命令行？如果你本机已经在用 **Codex** 或 **Claude Code**，直接把下面这句话发给它，它会帮你装好、起好后台，并给你一个本机网址——剩下的「扫码创建机器人」全部在浏览器里点完：
+
+```text
+帮我安装并启动「飞书 Codex 桥」：在终端执行 `npm i -g @modelzen/feishu-codex-bridge && feishu-codex-bridge start`，
+然后执行 `feishu-codex-bridge web` 取得本机控制台网址（形如 http://127.0.0.1:xxxxx/?token=...）发给我，
+我要在浏览器里扫码创建机器人。
+```
+
+> 原理：`start` 在「还没有机器人」时不会卡在终端扫码，而是直接起好后台 + 内嵌 **Web 引导控制台**；
+> 你打开网址后用飞书扫码即可创建并授权机器人，建完点「重启使其上线」就接入完成。全程不用懂命令行。
+
+如果你想自己装，往下看 👇
+
 ### 1. 安装
 
 ```bash
@@ -115,7 +130,7 @@ feishu-codex-bridge bot rm <名>     # 移除一个机器人配置
 
 ## 🔧 飞书开放平台后台配置（关键，必须手动一次）
 
-扫码向导只负责**创建应用 + 拿到凭据**。下面这些飞书**没有开放 API**，必须你在[开发者后台](https://open.feishu.cn/app)手动配一次（Lark 为 <https://open.larksuite.com/app>）：
+扫码向导只负责**创建应用 + 拿到凭据**。下面这些（事件 / 回调 / 权限勾选 / 版本发布）飞书**没有写入类 API**，必须你在[开发者后台](https://open.feishu.cn/app)手动配一次（Lark 为 <https://open.larksuite.com/app>）；不过配置**状态**可以通过 API 检测——本工具会在 `run` / `start` / `doctor` / 私聊「🩺 诊断」里自动诊断事件订阅（从未发布版本 / 缺 `im.message.receive_v1` / 配置齐全），不用你猜：
 
 ### 1）开通权限（Scope）
 
@@ -127,9 +142,13 @@ feishu-codex-bridge bot rm <名>     # 移除一个机器人配置
 
 > 「**把我加进已有群**」功能另需 `im:chat:readonly`（读群名）、`im:chat.members:write_only`（解绑时机器人退群）两项（见 `JOIN_GROUP_SCOPES`）。同样**已预勾选进同一个开通链接**、**不属于** `REQUIRED_SCOPES`，不开通只是该功能静默关闭。
 
+> 「**事件订阅自动诊断**」另需 `application:application.app_version:readonly`（读应用版本信息，见 `APP_VERSION_SCOPES`）。同样**已预勾选**、**不属于** `REQUIRED_SCOPES`，不开通则诊断降级为「未能自动检测」，其余照常。
+
+> 「**群内可发现性**」另需 `im:chat.menu_tree:write_only`（建群时挂「🤖 Codex」群菜单）、`im:message.reactions:read`（接收表情回复事件：终态卡 👍 续轮 / 运行卡 OK 终止，见 `DISCOVERY_SCOPES`）。同样**已预勾选**、**不属于** `REQUIRED_SCOPES`，不开通只是群菜单不出现 / 表情驱动静默关闭。
+
 ### 2）订阅事件 + 回调（长连接模式）
 
-`run` / `start` 初始化到这步会**自动打开**「**事件与回调**」页（`https://open.feishu.cn/app/<app_id>/event`）。这页顶部有「**事件配置**」「**回调配置**」两个独立标签，要分别配（飞书对事件/回调**既无开通 API、也无预选深链、连查询订阅状态的接口都没有**，只能手点）：
+`run` / `start` 初始化到这步会**自动打开**「**事件与回调**」页（`https://open.feishu.cn/app/<app_id>/event`）。这页顶部有「**事件配置**」「**回调配置**」两个独立标签，要分别配（飞书对事件/回调**既无开通 API、也无预选深链**，只能手点；但**事件**的订阅状态可经「获取应用版本信息」API 读到——你配完并发布版本后，前台 `run` 会自动确认并播报「**事件已生效**」。**回调**不在该 API 里，无法检测）：
 
 **「事件配置」标签** → 「订阅方式」改**长连接** → 点「添加事件」：
 
@@ -138,6 +157,7 @@ feishu-codex-bridge bot rm <名>     # 移除一个机器人配置
 - `drive.notice.comment_add_v1` —— 云文档新增评论（**仅「文档评论回复」功能需要**；不加则该功能静默关闭，其余照常）
 - `im.chat.member.bot.added_v1` —— 机器人被加入群（**仅「把我加进已有群」功能需要**；触发私聊推送绑定卡，不加则拉我进群没反应）
 - `im.chat.member.bot.deleted_v1` —— 机器人被移出群（同上；触发自动解绑项目，不加则被踢后项目不会自动清理）
+- `im.message.reaction.created_v1` —— 新增消息表情回复（**仅「表情驱动」功能需要**：终态卡点 👍 续轮、运行卡点 OK 终止；不加则该功能静默关闭）
 
 **「回调配置」标签** → 「订阅方式」改**长连接** → 点「添加回调」：
 
@@ -153,7 +173,7 @@ feishu-codex-bridge bot rm <名>     # 移除一个机器人配置
 
 ### 4）发布版本
 
-在后台发布应用版本，机器人才真正上线。
+在后台发布应用版本，机器人才真正上线。发布通过后，跑着的 `run` 会经版本信息 API 自动确认并播报「**事件已生效**」。
 
 ---
 
@@ -165,6 +185,7 @@ feishu-codex-bridge bot rm <名>     # 移除一个机器人配置
   - **💬 单会话群**：整群就是**一条连续会话**（全程**免 @**、消息按序排队、无 `/resume`）。适合**个人单线深入**、像私聊一样直接聊。
 - **干活**：在项目群里 **@机器人** 描述需求；机器人在该群绑定的目录里跑 Codex，流式卡片回结果。
 - **话题 = 会话**：对某条消息开话题后，话题内可**免 @** 连续对话，是一条连贯的 Codex 会话。
+- **🎯 自主目标（`/goal`）**：发 `/goal <目标>`（主群区会新开话题；话题内 / 单会话群直接发），Codex **自主多轮**连续执行直到完成——每轮一张流式卡片，自然结束后出总结卡。运行中卡片上有 **⏹ 终止**（立刻停）和 **🎯 结束目标**（本轮跑完后停）两个按钮；goal 运行期间该会话不接收新消息（会收到提示，终止 / 结束目标后重发）。没有总时长上限，只有 30 分钟完全无事件的 idle 兜底。
 - **发图 / 发附件**：直接在消息里**发图片**，Codex 能看到（多模态读图）；**发文件附件**（日志 / PDF / 代码等），桥会把它下载到本地并把**绝对路径**告诉 Codex，让它用工具直接打开分析。⚠️ 附件落在桥的全局临时目录（`~/.feishu-codex-bridge/inbound`，1h 后自动清），**只有「完全访问」档**能读到——「项目内只读 / 读写」档的沙箱把读取锁在项目目录内，读不到该目录。单文件上限 50MB、单条消息最多 9 个；合并转发里的附件飞书官方不支持取，故不支持。
 - **文档评论 @机器人**：在飞书文档评论里 @ 它就回（前提：已开通文档评论权限 + 订阅 `drive.notice.comment_add_v1`，且机器人对该文档有访问权限）。只支持 doc/docx/sheet/file；评论框不渲染 markdown，回复为纯文本，超长会截断。
 - **终止**：卡片上的 **⏹** 随时终止当前轮；卡死超过 watchdog 阈值（默认 120s）自动中止并回收进程。
@@ -270,13 +291,38 @@ src/
 |------|------|
 | `✗ 未找到 codex CLI` | 装 Codex 并 `codex login`；或设 `CODEX_BIN`。`doctor` 会显示解析到的路径 |
 | `应用凭据校验失败` | 应用可能被禁用/未发布；重跑 `run` 重新校验，或 `bot rm <名>` 后 `bot init` 重新扫码 |
-| @ 机器人没反应 | 多半是**事件未订阅**（长连接模式）或**版本未发布**；按上面「后台配置」检查 |
+| @ 机器人没反应 | 多半是**事件未订阅**（长连接模式）或**版本未发布**；跑 `feishu-codex-bridge doctor`（或看启动日志）会精确诊断出是哪种，再按上面「后台配置」修 |
 | 提示某项「权限不足」 | 点 `run`/`start` 打印（或自动打开）的一键开通链接补齐权限（即时生效） |
 | 按钮「时灵时不灵」 | 检查是否**重复启动了两个 bridge 进程**抢回调；本桥有单实例锁，正常会拒绝第二个 |
 | 点 ⏹ 没反应 / 卡片不收尾 | 同群另一话题在跑长任务占住了串行队列；稍候或重连 |
 
 ---
 
+## 🌐 Web 控制台
+
+本机浏览器里的管理面板，看 bot / 项目 / 话题 / 实时日志一屏全览：
+
+```bash
+feishu-codex-bridge web            # 默认 http://127.0.0.1:7866
+feishu-codex-bridge web --port 8080
+```
+
+`run` / `start` 起来的 daemon 会**自动内嵌**控制台（多 bot 时由 supervisor 聚合所有机器人），此时 `web` 命令直接打开 daemon 的控制台——写操作可用、长连接状态实时；daemon 没跑时 `web` 退化为只读预览（直读本机数据文件）。前台启动会打印一行**带 token 的完整 URL**，用它打开即可（首跳自动换成 cookie，URL 上的 token 随即失效于地址栏）。
+
+**多 Tab 架构**（hash 路由，可刷新/可前进后退/可分享）：
+
+- **📊 总览 Tab**（全局维度，默认落地）：后台 daemon 状态/重启/升级、所有 bot 在线聚合 + 启用开关、🧠 **后端管理卡**（见下）、🩺 宿主机体检、📜 全局实时日志 SSE（`stream.timing` / `agent.*` 关键事件高亮，**整段 SSE 全程只连一次、切 Tab 不断连**）。
+- **每个机器人一个 Tab**：该 bot 的概览（运行 pid / 真实长连接状态）、🩺 接入诊断（事件订阅三态 + 各后端环境）、📁 项目列表（群形态 / 🔐 权限档 / 🧠 后端 / 🧵 话题数）+ ⚙️ 设置抽屉，以及停用/删除该 bot（下沉到 bot Tab 头部）。
+
+**扫码添加机器人**（➕ 添加机器人 → 默认主入口）：点「➕ 添加机器人」走三步向导——① **扫码创建**（前端零依赖内嵌 QR 编码器把飞书返回的创建链接画成 SVG 二维码，飞书 App 扫一下自动建应用、拿密钥入库、把你设为管理员；带倒计时 + 过期重生成 + 「在浏览器打开」纯链接兜底）→ ② 接入检测 checklist（5 秒轮询事件订阅三态、缺失 scope 深链、长连接状态）→ ③ 完成并跳进该机器人的 Tab。**已有飞书应用？**向导里有「手动填 App ID/Secret」折叠次级入口（降级 fallback，覆盖扫码不可用的租户/接入既有应用）。
+
+**🧠 后端按需下载**：默认只装轻核心（codex 零依赖）。总览的「后端管理卡」按 agent 分组（Codex / Claude 下 SDK·ACP 两接入）列出每个后端的安装态——已装显 ✅ 就绪（含版本）；`claude-sdk` 这类重后端（自带约 224M Claude Code 二进制）未装时显 ⬇️ **下载**按钮，点击在控制台流式装到用户私装目录（带进度条，不写全局、零 sudo）；`claude-acp` 这类外部适配器给手动装法提示。项目设置抽屉里的后端 picker 同样按 agent 分组：未装的选项灰显并引导「去总览下载」，权限档不支持的灰显（沿用 `validateBackendSwitch` 语义），已装的可一键切换（只影响新话题）。
+
+- **安全模型**：只绑定 `127.0.0.1`（无任何远程访问配置项）+ 每次启动随机生成的 token 鉴权 + Host/Origin 校验防 DNS rebinding；daemon 控制台的地址记录在 `~/.feishu-codex-bridge/web-console.json`（0600 仅本用户可读，daemon 退出自动清理）。扫码会话的 client_secret 只在 server 内存流过即进 keystore，SSE 推给前端的 `done` 事件是白名单字段、**永不含密钥**。要远程管理请用飞书私聊控制台——那是带飞书身份鉴权的。
+- **与飞书卡片的关系**：体验对齐「Web 能操作的飞书也能操作」——Web 的方法清单严格对齐 DM 私聊卡片（🧠 后端 / 🔐 权限 / ✋ 免@ / 🗜️ 自动压缩 / 🩺 诊断…），两面**共享同一写入逻辑**（同样的校验、同样的会话驱逐、同样的落盘——`AdminService` + 共享写操作层），不会出现两套行为。Web 只补 DM 够不着的宿主机域（日志流 / 多 bot 聚合 / 后端按需下载），飞书域操作（建项目 / 建群 / 用量）仍在 DM 卡片。
+
+---
+
 ## 💬 文档 & 交流
 
 - 🎀 **图文介绍（先看它能干嘛）**：<https://my.feishu.cn/docx/AFKNdf4QaooL5OxSR8bc5H7vn7b> —— 配大量截图，讲清它在飞书里长什么样、有哪些细节、可以怎么用。