@modelzen/feishu-codex-bridge 0.3.12-test.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +23 -17
  2. package/dist/cli.js +270 -1598
  3. package/dist/index.d.ts +2 -1
  4. package/dist/index.js +2 -1
  5. package/package.json +1 -3
package/README.md CHANGED
@@ -11,7 +11,7 @@
11
11
 
12
12
  一句话：你在飞书群里发「帮我加个登录接口」，机器人就在这个群绑定的代码目录里跑 Codex，边跑边把推理、命令、改动、结果更新到一张卡片上；点 ⏹ 可随时终止。
13
13
 
14
- > 🚀 **最快上手：把这个仓库链接 `https://github.com/modelzen/feishu-codex-bridge` 交给 Codex / Claude，照着本 README 它就能帮你把整套装好跑起来。**
14
+ > 🚀 **最快上手（推荐，全程浏览器点点点）：把这个仓库链接 `https://github.com/modelzen/feishu-codex-bridge` 交给你本机在用的 Codex / Claude Code，让它照下面 [「最省事」一节](#0-最省事让-codex--claude-帮你装剩下全在浏览器里点推荐) 帮你装好、起后台、并在浏览器里打开本机控制台——之后「扫码加机器人 / 启停 / 重启 / 更新」全在网页里点，不碰命令行。**
15
15
  >
16
16
  > 🎀 **想先看它在飞书里长啥样、能干嘛？** 看这篇图文介绍 👉 [《让 Codex 当你飞书里的同事》](https://my.feishu.cn/docx/AFKNdf4QaooL5OxSR8bc5H7vn7b)
17
17
 
@@ -55,20 +55,24 @@
55
55
 
56
56
  ## 🚀 安装与启动
57
57
 
58
- ### 0. 最省事：把一句话发给 Codex / Claude，让它帮你装
58
+ ### 0. 最省事：让 Codex / Claude 帮你装，剩下全在浏览器里点（推荐）
59
59
 
60
- 不想碰命令行？如果你本机已经在用 **Codex** 或 **Claude Code**，直接把下面这句话发给它，它会帮你装好、起好后台，并给你一个本机网址——剩下的「扫码创建机器人」全部在浏览器里点完：
60
+ 不想碰命令行？如果你本机已经在用 **Codex** 或 **Claude Code**，**直接把下面这段发给它**即可。它会帮你装好、起好后台，并**在浏览器里打开本机控制台**——之后**扫码加机器人、启动 / 停止 / 重启、检查更新**全部在网页里点完，你不用懂任何命令：
61
61
 
62
62
  ```text
63
- 帮我安装并启动「飞书 Codex 桥」：在终端执行 `npm i -g @modelzen/feishu-codex-bridge && feishu-codex-bridge start`，
64
- 然后执行 `feishu-codex-bridge web` 取得本机控制台网址（形如 http://127.0.0.1:xxxxx/?token=...）发给我，
65
- 我要在浏览器里扫码创建机器人。
63
+ 帮我安装并启动「飞书 Codex 桥」，让我之后全在浏览器里操作：
64
+ 1) 全局安装：npm i -g @modelzen/feishu-codex-bridge
65
+ 2) 起后台：feishu-codex-bridge start（没有机器人时它不会卡在终端扫码，会进引导控制台，这是正常的）
66
+ 3) 等约 3 秒，跑：feishu-codex-bridge web，从输出里取本机网址（形如 http://127.0.0.1:51847/?token=...，含 ?token= 不能丢）
67
+ 4) 用 open(macOS) / start(Windows) / xdg-open(Linux) 在我的浏览器里打开那条完整网址；打不开就把网址原样发我
68
+ 别替我登录 codex、也别替我改飞书后台配置——剩下的我在浏览器里点（扫码加机器人 / 启停 / 更新）。
66
69
  ```
67
70
 
68
- > 原理：`start` 在「还没有机器人」时不会卡在终端扫码，而是直接起好后台 + 内嵌 **Web 引导控制台**；
69
- > 你打开网址后用飞书扫码即可创建并授权机器人，建完点「重启使其上线」就接入完成。全程不用懂命令行。
71
+ > 原理：`start` 在「还没有机器人」时不会卡在终端扫码，而是直接起好后台 + 内嵌 **Web 控制台**；
72
+ > `web` 把带 token 的本机网址打印出来（daemon 在跑时立即返回、不占终端）。打开后用飞书扫码创建机器人，
73
+ > 按页面 checklist 开权限 / 订阅事件、点完成即上线。**整台机器的安装、加机器人、启停、更新都收敛进这一个网页**，全程不用懂命令行。
70
74
 
71
- 如果你想自己装，往下看 👇
75
+ 如果你想自己用命令行装，往下看 👇
72
76
 
73
77
  ### 1. 安装
74
78
 
@@ -298,28 +302,30 @@ src/
298
302
 
299
303
  ---
300
304
 
301
- ## 🌐 Web 控制台
305
+ ## 🌐 Web 控制台（推荐的管理入口）
302
306
 
303
- 本机浏览器里的管理面板，看 bot / 项目 / 话题 / 实时日志一屏全览：
307
+ 本机浏览器里的管理面板，**安装收尾、加机器人、启停 / 重启 / 更新、看 bot / 项目 / 话题 / 实时日志** 一屏全办——日常基本只跟它打交道，命令行是给爱折腾的人的备选。
304
308
 
305
309
  ```bash
306
- feishu-codex-bridge web # 默认 http://127.0.0.1:7866
310
+ feishu-codex-bridge web # 取控制台网址（daemon 在跑→直接给 51847 那条；没跑→只读预览）
307
311
  feishu-codex-bridge web --port 8080
308
312
  ```
309
313
 
310
- `run` / `start` 起来的 daemon 会**自动内嵌**控制台（多 bot 时由 supervisor 聚合所有机器人），此时 `web` 命令直接打开 daemon 的控制台——写操作可用、长连接状态实时；daemon 没跑时 `web` 退化为只读预览（直读本机数据文件）。前台启动会打印一行**带 token 的完整 URL**，用它打开即可（首跳自动换成 cookie，URL 上的 token 随即失效于地址栏）。
314
+ **从零到跑起来（浏览器路径）**：`npm i -g @modelzen/feishu-codex-bridge` → `feishu-codex-bridge start`（起后台，没机器人时进引导控制台）→ `feishu-codex-bridge web`（拿到 `http://127.0.0.1:51847/?token=…` 网址）→ 浏览器打开 → **➕ 添加机器人** 扫码 + 按 checklist 开权限/订阅 → 完成。之后启停、重启、检查更新都在「📊 总览」Tab 的按钮上。让 Codex/Claude 代劳整个流程的话，见上方 [「最省事」一节](#0-最省事让-codex--claude-帮你装剩下全在浏览器里点推荐) 的提示词。
315
+
316
+ `run` / `start` 起来的 daemon 会**自动内嵌**控制台（多 bot 时由 supervisor 聚合所有机器人），固定占规范端口 **51847**；此时 `web` 命令直接打开 daemon 的控制台——写操作可用、长连接状态实时；daemon 没跑时 `web` 退化为只读预览（直读本机数据文件，但仍放行「启动 daemon / 检查更新」两个动作，启动后页面自动跳到 51847 那条可写控制台）。启动会打印一行**带 token 的完整 URL**，用它打开即可（首跳自动换成 cookie，URL 上的 token 随即失效于地址栏；命令在有桌面的终端里会顺带自动弹浏览器）。
311
317
 
312
318
  **多 Tab 架构**（hash 路由，可刷新/可前进后退/可分享）：
313
319
 
314
- - **📊 总览 Tab**（全局维度，默认落地）：后台 daemon 状态/重启/升级、所有 bot 在线聚合 + 启用开关、🧠 **后端管理卡**（见下）、🩺 宿主机体检、📜 全局实时日志 SSE（`stream.timing` / `agent.*` 关键事件高亮，**整段 SSE 全程只连一次、切 Tab 不断连**）。
315
- - **每个机器人一个 Tab**：该 bot 的概览（运行 pid / 真实长连接状态）、🩺 接入诊断（事件订阅三态 + 各后端环境）、📁 项目列表（群形态 / 🔐 权限档 / 🧠 后端 / 🧵 话题数）+ ⚙️ 设置抽屉，以及停用/删除该 bot（下沉到 bot Tab 头部）。
320
+ - **📊 总览 Tab**（全局维度，默认落地）：后台 daemon 状态/重启/升级、所有 bot 在线聚合 + 启用开关、🩺 Codex 环境状态（在 PATH / 版本 / 未装时的安装提示）、🩺 宿主机体检、📜 全局实时日志 SSE（`stream.timing` / `agent.*` 关键事件高亮，**整段 SSE 全程只连一次、切 Tab 不断连**）。
321
+ - **每个机器人一个 Tab**：该 bot 的概览（运行 pid / 真实长连接状态）、🩺 接入诊断（事件订阅三态 + Codex 环境）、📁 项目列表（群形态 / 🔐 权限档 / 🧵 话题数）+ ⚙️ 设置抽屉，以及停用/删除该 bot（下沉到 bot Tab 头部）。
316
322
 
317
323
  **扫码添加机器人**（➕ 添加机器人 → 默认主入口）：点「➕ 添加机器人」走三步向导——① **扫码创建**（前端零依赖内嵌 QR 编码器把飞书返回的创建链接画成 SVG 二维码，飞书 App 扫一下自动建应用、拿密钥入库、把你设为管理员；带倒计时 + 过期重生成 + 「在浏览器打开」纯链接兜底）→ ② 接入检测 checklist（5 秒轮询事件订阅三态、缺失 scope 深链、长连接状态）→ ③ 完成并跳进该机器人的 Tab。**已有飞书应用？**向导里有「手动填 App ID/Secret」折叠次级入口（降级 fallback，覆盖扫码不可用的租户/接入既有应用）。
318
324
 
319
- **🧠 后端按需下载**：默认只装轻核心（codex 零依赖）。总览的「后端管理卡」按 agent 分组（Codex / Claude 下 SDK·ACP 两接入）列出每个后端的安装态——已装显 ✅ 就绪（含版本）；`claude-sdk` 这类重后端（自带约 224M Claude Code 二进制）未装时显 ⬇️ **下载**按钮，点击在控制台流式装到用户私装目录（带进度条，不写全局、零 sudo）；`claude-acp` 这类外部适配器给手动装法提示。项目设置抽屉里的后端 picker 同样按 agent 分组：未装的选项灰显并引导「去总览下载」，权限档不支持的灰显（沿用 `validateBackendSwitch` 语义），已装的可一键切换（只影响新话题）。
325
+ **🩺 Codex 环境状态**：后端就是本机的 **Codex CLI**（轻核心、零额外运行时依赖）。总览的后端卡只显示 Codex 的检测态——已就绪显 ✅（含版本），未装/未登录时给一句安装提示（`npm i -g @openai/codex` + `codex login`）。Codex 走 PATH 检测，不经控制台下载。
320
326
 
321
327
  - **安全模型**：只绑定 `127.0.0.1`（无任何远程访问配置项）+ 每次启动随机生成的 token 鉴权 + Host/Origin 校验防 DNS rebinding；daemon 控制台的地址记录在 `~/.feishu-codex-bridge/web-console.json`（0600 仅本用户可读，daemon 退出自动清理）。扫码会话的 client_secret 只在 server 内存流过即进 keystore，SSE 推给前端的 `done` 事件是白名单字段、**永不含密钥**。要远程管理请用飞书私聊控制台——那是带飞书身份鉴权的。
322
- - **与飞书卡片的关系**：体验对齐「Web 能操作的飞书也能操作」——Web 的方法清单严格对齐 DM 私聊卡片（🧠 后端 / 🔐 权限 / ✋ 免@ / 🗜️ 自动压缩 / 🩺 诊断…），两面**共享同一写入逻辑**（同样的校验、同样的会话驱逐、同样的落盘——`AdminService` + 共享写操作层），不会出现两套行为。Web 只补 DM 够不着的宿主机域（日志流 / 多 bot 聚合 / 后端按需下载），飞书域操作（建项目 / 建群 / 用量）仍在 DM 卡片。
328
+ - **与飞书卡片的关系**：体验对齐「Web 能操作的飞书也能操作」——Web 的方法清单严格对齐 DM 私聊卡片（🧠 后端 / 🔐 权限 / ✋ 免@ / 🗜️ 自动压缩 / 🩺 诊断…），两面**共享同一写入逻辑**（同样的校验、同样的会话驱逐、同样的落盘——`AdminService` + 共享写操作层），不会出现两套行为。Web 只补 DM 够不着的宿主机域（日志流 / 多 bot 聚合 / Codex 环境检测），飞书域操作（建项目 / 建群 / 用量）仍在 DM 卡片。
323
329
 
324
330
  ---
325
331