xuym-codex-collab 0.1.1 → 0.3.0

package/README.md

@@ -1,141 +1,92 @@
 # Codex Collab
 
-让同事的 Codex 通过一个 MCP + Skill 和可选本地 Runner 协作；使用**目标仓库** `agent-collab` 分支保存任务协议/事件，飞书/企业微信群通过一个 Bot 下达任务与查看状态。并不共享完整私有会话，也不能向任意已打开的桌面会话注入消息。
+把企业微信群的任务交给指定的已有 Codex 对话：管理员统一创建并分配机器人，同事导入个人接入包、绑定对话，即可接单、提交结果、通知真人审核并接力。每位成员只运行本机工具；共享任务协议和交接记录保存在业务仓库的 `agent-collab` 分支。
 
-## 运行状况
+## 安装与入口
 
-已实现 Git 签名账本、MCP、企微/飞书适配、后台 Codex SDK Runner，以及桌面手动交接。2026-10-09 已在真实企业微信群完成后台 SDK Alice → Bob 的准确 SHA 接力，最终测试通过并等待真人审核；这不等于绑定已有桌面对话，跨两台机器仍未验证。
-
-**指定已有桌面对话轮询模式 `desktop_poll` 已完成本机真实闭环验证**。据用户于 2026-10-10 确认，真实企业微信群任务已由 Alice 的既有 Codex 对话接单执行，再由 Bob 的既有 Codex 对话接力；本机适配器负责收群消息/发通知，MCP 提供对话绑定、原子接单、隔离工作树、续租、固定测试和交接，已有对话的 app heartbeat 负责轮询。跨两台机器部署仍未验证。当前全套自动测试 66 项通过。操作见 [`docs/desktop-poll.md`](docs/desktop-poll.md)。
-
-## 推荐：Peer 模式（不部署中心服务）
-
-如果不想运行共享 HTTP 服务，使用已实现的 Peer 模式：每位同事本机安装 Skill + stdio MCP，并运行自己的 Peer Runner；任务、签名事件、候补分配和交接 commit 直接写入目标仓库的 `agent-collab` 分支。企业微信机器人是可选的命令/通知适配器，不是调度真相。
-
-面向团队成员的 npm CLI 接入说明见 [`docs/onboarding.md`](docs/onboarding.md)。公开 npm 包名为 `xuym-codex-collab`，安装后使用 `codex-collab` 命令：
+需要 Node.js 20+、Git、Codex 桌面应用，以及业务仓库的读取和 push 权限。先 clone 业务仓库；成员无需 clone 本工具源码。
 
 ```sh
 npm install --global xuym-codex-collab
-codex-collab --help
+codex-collab setup
 ```
 
-```sh
-pnpm peer:create-team /abs/team.json repo-id alice frontend \
-  alice:admin:frontend,backend bob:member:frontend carol:member:backend
-pnpm peer:init-agent /abs/team.json /abs/bob.private.json \
-  /abs/work/repo /abs/private/bob-data /abs/private/bob-peer.json
-pnpm peer doctor /abs/private/bob-peer.json
-pnpm peer start /abs/private/bob-peer.json
+`setup` 打开本机网页工作台，所有接入操作集中在一个页面。管理员选择“初始化团队”，成员选择“加入团队”；已在使用旧配置的成员选择“导入已有配置”。终端保持运行即可继续使用工作台，关闭工作台后已启动的机器人连接仍运行。
+
+| 谁 | 在工作台做什么 | 接入后需要保留什么 |
+| --- | --- | --- |
+| 管理员 | 初始化业务仓库；在群里验证自己；分配各成员机器人与职责；下载加密接入包；确认成员申请；按职责设置真人审核规则 | 本机身份、管理员配置和机器人连接 |
+| 成员 | 导入个人接入包与密码；选择自己的业务仓库 clone；在群里发送验证码；等待管理员确认；复制启用指令到选定 Codex 对话 | 本机机器人连接，以及该对话的轮询自动化 |
+
+管理员先在企业微信创建**独立智能机器人**并加入协作群，再填写 Bot ID/Secret。工具通过群验证码发现群 `chatid` 和真人 `userid`，不需要成员手工寻找这些 ID、生成密钥或编辑 JSON。机器人 Secret 通过加密接入包交给指定成员，密码单独传递。
+
+完整步骤与旧配置迁移见 [团队接入指南](docs/onboarding.md)。
+
+## 一次任务如何接力
+
+```mermaid
+sequenceDiagram
+  participant H as 企业微信群
+  participant A as Alice 本机工具
+  participant C as Alice 已有 Codex 对话
+  participant R as 阶段审核人
+  participant G as 业务仓库 agent-collab
+  participant B as Bob 已有 Codex 对话
+  H->>A: @Alice 协作 创建 [frontend>backend] ...
+  A->>G: 签名任务与能力路由
+  C->>G: heartbeat 轮询并原子认领
+  C->>G: 代码 commit、测试证据、阶段总结
+  A->>H: 阶段结果、代码证据与审核命令
+  H->>R: 通知本人审核
+  R->>A: 通过（或退回并填写修改意见）
+  A->>G: 签名审核，通过后开放下一阶段
+  B->>G: 从交接 SHA 认领下一阶段
+  B->>G: 提交结果，等待真人审核
 ```
 
-MCP 创建的任务默认保留给当前桌面 Codex，完成并 push 后调用 `handoff_task`；旧自动模式下群任务路由给本地 Runner；配置 `desktop_poll` 后群任务等待指定已有对话的 heartbeat 认领。完整初始化、企业微信配置、候补和故障恢复见 [`docs/peer.md`](docs/peer.md)。
-
-**群 @ 后在新的后台 SDK 会话执行（不是已有桌面对话）**：见 [`docs/local-automatic-test.md`](docs/local-automatic-test.md)。新建 automatic 测试环境后，Alice/Bob Runner 都自动执行，按 frontend → backend 路由交接；可安全复用旧私有机器人配置，但启动前必须停旧连接。Bot 对应 Runner 创建的新 Codex SDK 会话，**不是已有桌面对话**。
-
-**本机用两个 Codex 对话和两个企业微信机器人手动模拟同事**：见 [`docs/local-peer-test.md`](docs/local-peer-test.md)。`peer:setup-local` 一次生成隔离 demo、副本身份和项目 MCP，不改 CC Switch、不推送 GitHub；第二个对话可用 `claim_desktop_task` 手动接力。本页不自动唤起对话；要让指定已有对话轮询接单，使用 [`docs/desktop-poll.md`](docs/desktop-poll.md)。
+例如在群里选中实际 Alice 机器人发送：
 
-以下为保留的**旧中心服务模式**操作；不要与上面的 Peer 测试混用机器人连接和命令。Peer 不使用 `localhost:38765`、HTTP 令牌或手工 `协作 分配` / `协作 交接` 命令。
-
-## Codex 之间的代码接力
-
-1. 已绑定身份的 Alice 在桌面 Codex 用 MCP `create_task` 创建任务（或在群里发 `协作 创建 ...`），无需先把任务分配给她；她也可以使用自己已被分配的任务。桌面 Codex 安装 Skill/MCP **不会自动被唤醒**。
-2. Alice 在目标仓库 `codex/*` 分支完成自己的部分，执行可信测试并提交 Git commit；跨机器时还要将分支推送到共同的 `origin`。不要将密钥、聊天全文写入仓库。
-3. Alice 用 `read_task` 获取最新 `state.seq`，调用 MCP `handoff_task`：传 `task_id`、`expected_seq`、`summary`（已完成与下一步）、`branch`、完整 `commit` SHA、真实 `tests` 结果。服务会核实分支 tip 与 commit，写入目标仓库的 `agent-collab` 账本，任务进入 `waiting`。
-4. Alice 作为管理员在同一个企微群 @机器人，发送 `协作 交接 T-... bob`；服务器验证身份后分配任务。Bob 本机持续运行的个人 Runner 领取任务，从交接 commit 建独立 worktree 和新的 Codex SDK 会话；完成后写代码分支、测试证据和 `review_requested`。只有真人审核可批准/完成。
-
-目前 `协作 交接` 只路由给一个已配置的企微 Bot；仅在**更新并重启中心服务**后生效。要显示两个不同的机器人身份并分别接受 @ 消息，还需增加同一中心服务的双 Bot 路由；不要运行两个服务并发写同一账本。MCP/Skill 负责桌面 Codex **主动发布交接**，Runner 才负责同事端的**自动领取和新建会话**。
-
-## 两个仓库本地测试
-
-Node.js >= 20，pnpm 11；在本仓库执行：
-
-```sh
-pnpm install --frozen-lockfile
-pnpm test
+```text
+@Alice 协作 创建 [frontend>backend] 给登录页增加密码显示切换 | npm test 通过
 ```
 
-演示目标仓库 `codex-collab-demo` 的 `main` 执行 `sh test.sh`，而任务事件在 `agent-collab`。示例任务 T-001 为故意未完成的编程任务；可用两个不同用户通过 API/MCP 和 Runner 测试。现有 T-001 未指定审核人，建议通过飞书命令创建**新任务**以获得默认管理员审核人。
+Alice 的绑定对话轮询到任务后在隔离 worktree 执行前端阶段，提交代码、运行固定验证命令、写入总结；群里收到分支、提交 SHA、测试结果和审核命令。默认由实际执行者本人审核，通过后才开放 Bob 的后端阶段。退回时必须填写修改意见，当前阶段从被退回的提交继续修改，重新提交后再次审核。管理员可在工作台按职责选择审核人、额外通知对象，或关闭中间阶段审核。候补从 Git 签名事件和租约判断，机器人 @ 消息本身不负责调度。群消息中的验收文字不会替换管理员设置的本机测试 argv。
 
-## 本地启动
+代码保存在独立 `codex/*` 分支；任务和签名策略保存在 `agent-collab`，两者不自动合并到 `main`。最后阶段始终等待真人审核，审核通过后由管理员完成任务。
 
-生成账号文件（不要放进 Git，执行完把终端输出的个人令牌安全地分发给对应用户）：
+审核人在群里 @ 自己绑定的机器人，复制最新通知中的任务 ID 和 `R-版本号`：
 
-```sh
-node scripts/create-accounts.mjs /tmp/collab-accounts.json alice:admin:ou_alice bob:member:ou_bob
-COLLAB_REPO=/path/to/codex-collab-demo \
-COLLAB_ACCOUNTS_FILE=/tmp/collab-accounts.json \
-COLLAB_DATA_DIR=/tmp/collab-service \
-COLLAB_REPO_ID=jack506255560/codex-collab-demo \
-node apps/server/main.mjs
+```text
+协作 审核 T-实际任务ID R-7 通过
+协作 审核 T-实际任务ID R-7 退回 | 请补充键盘操作和相关测试
 ```
 
-运行成功后 `curl http://127.0.0.1:38765/health`。`ou_alice` 与 `ou_bob` 需要换为飞书用户的**真实** `open_id`。管理员身份为默认审核人；编码负责人不能与审核人为同一人。如需自动领取任务，同事机器运行：
+每次重新提交都产生新的版本号，旧审核命令不能批准新结果。只有指定审核人能审核；通知对象不因此获得审核权限。默认没有本人群身份的测试机器人由管理员审核，方便一个真人模拟两个同事。
 
-```sh
-COLLAB_REPO=/path/to/codex-collab-demo \
-COLLAB_API=https://your-server \
-COLLAB_TOKEN=<bob的个人令牌> COLLAB_USER_ID=bob \
-COLLAB_DATA_DIR=/path/to/private-runner-data \
-COLLAB_TEST_ARGV='["sh","test.sh"]' \
-node apps/runner/main.mjs
-```
+群通知会列出审核人与通知对象，并尝试用已验证的 `userid` 生成提及。**智能机器人长连接中的原生 @ 提醒仍需实群验证**；不能把收到结果通知等同于已触发原生 @。部分机器人得到的是加密 userid，本工具尚未集成企业应用的明文 ID 转换。群里的人需要先加入同一协作群，并完成自己的接入验证。
 
-`COLLAB_API` 单机实验可用 `http://127.0.0.1:38765`；不同机器应提供 HTTPS，且每台机器的目标仓库含 `main` 和 `agent-collab` 分支。若跨机器分发代码分支，需要在服务和 Runner 均设置 `COLLAB_PUSH=1`，保证 origin 可访问且个人 Git 凭据已配置。服务向 `agent-collab` 推送账本，Runner 向 `codex/task-*` 推送代码；**没有凭据会失败**。不能直接把 localhost 地址给其他同事。
+## 状态与数据
 
-## 飞书接入
+工作台分别检查项目 MCP/Skill 配置、企微认证、目标对话绑定和实际轮询。机器人认证成功只能说明连接可用；还需要对话真实轮询才能执行任务。MCP 本身不能唤醒闲置对话，“启用指令”会要求在**当前选定对话**建立 heartbeat，应用需支持并运行该自动化。
 
-1. 飞书开放平台创建企业自建应用，启用机器人、申请“以应用身份发送消息”和接收群消息所需权限；启用 `im.message.receive_v1` 事件，选择**长连接**接收并发布/授权应用（具体权限以飞书控制台当前要求为准）。
-2. 将 Bot 加到群中，先在本机设置 `FEISHU_APP_ID`、`FEISHU_APP_SECRET` 并运行 `node scripts/discover-feishu.mjs`；在目标群发一条普通消息，终端只打印 `chat_id` 和 `sender_open_id`（不会保存正文），确认所有同事的 open_id 后停止该脚本，再填入账号文件与 `FEISHU_CHAT_IDS` 允许列表。**不要**写死或提交 App Secret。
-3. 启动中心服务时追加：`FEISHU_APP_ID=... FEISHU_APP_SECRET=... FEISHU_CHAT_IDS=oc_...`。看到 WebSocket 订阅日志后，在允许的群由已映射成员发：`协作 创建 写一个功能 | 验收一;验收二`，管理员 `协作 分配 T-... bob`，所有人 `协作 状态 T-...`。Runner 提交审核请求后审核人 `协作 审核 T-... 通过` 或 `协作 审核 T-... 退回`，最后管理员 `协作 完成 T-...`。
-4. 检查群回复、服务日志、目标仓库 `agent-collab` 事件与本机代码分支。未配置飞书凭据时可以跑本地模拟 E2E；模拟通过**不等于**真实群接通。
+成员私钥在成员本机生成。Git 记录公钥、成员职责、签名邀请/申请、任务事件、代码引用、测试和阶段总结；Secret、对话 ID、运行令牌及聊天全文留在本机。团队新增成员或修改审核规则后会发布新的签名策略版本；旧任务继续遵循创建时的策略，避免改写已运行任务的权限和候补。
 
-## 本机接企业微信群（已有隔离 demo 和两个 Runner 时）
+停止工作台或机器人连接不会自动暂停 Codex heartbeat；需要暂停协作时，应在对应对话暂停自动化，并检查在执行任务的状态。
 
-**先在企业微信管理端创建/配置支持 API 长连接的智能机器人**，获取 Bot ID 和**新** Secret，加入测试群。此前曾在聊天里暴露的 Secret 已不安全：必须先重置，不要再次发送到聊天或提交 Git。此处用的是「智能机器人 API 模式」，不是只有 webhook URL 的群机器人；连接通过官方 `@wecom/aibot-node-sdk` WebSocket 出站发起，不需要公网地址。确认组织管理员允许此类型机器人、目标群确实能收到其群消息。一个 Bot 足够；它通过账号映射和本地两个 Runner 分配身份，不对应两个桌面 Codex 会话。群消息能否到达以真机发现为准，尝试在群内 @ 机器人发送文本。
-
-当前单机测试目录可以这样找（不要打印里面的令牌或环境文件）：
+## 开发与兼容
 
 ```sh
-cd "$HOME/codex-collab"
-# 确保 Node.js >= 20 已安装并且 node 位于 PATH。
-root="$(cat "$HOME/.codex-collab-local-test/current")"
-# 仅在你的本机交互终端输入；不要把实际值放在命令行参数或聊天中。
-printf 'Bot ID: '; IFS= read -r WECOM_BOT_ID
-printf '新 Bot Secret（不回显）: '; IFS= read -rs WECOM_BOT_SECRET; echo
-export WECOM_BOT_ID WECOM_BOT_SECRET
-node scripts/discover-wecom.mjs
-```
-
-等待输出 `WeCom authenticated`，在目标群里向机器人发送文本，例如 `@机器人 协作 状态 T-NONE`；发现脚本仅输出 `{"chatid":"...","userid":"..."}`，**不会输出正文**。这一步如果只有认证而没有群消息，不代表群已接通：检查群是否已加入机器人、消息触发方式和企业管理员配置。在发现脚本按 `Ctrl-C` 关闭连接，再继续下面步骤；**同一个机器人不要让发现脚本和服务同时建立连接**。至少记下一个真实群 `chatid` 及你（管理员 alice）的 `userid`，若同事要在群里发命令，再收集其 `userid`。不要猜 ID、不要贴到 Git。以下命令的引号和交互输入要保留：
-
-```sh
-printf '刚发现的群 chatid: '; IFS= read -r WECOM_CHAT_IDS
-printf '你自己的 userid（alice）: '; IFS= read -r ALICE_WECOM_USERID
-export WECOM_CHAT_IDS
-node scripts/bind-wecom-users.mjs "$root/accounts.json" "$root/accounts.wecom.json" "alice:$ALICE_WECOM_USERID"
-# 可选：另一位真人需在群里操作时，用他的 userid 重建私有文件；不要把两人的 userid 填成同一个。
-# node scripts/bind-wecom-users.mjs "$root/accounts.json" "$root/accounts.team.json" "alice:$ALICE_WECOM_USERID" 'bob:<同事的真实userid>'
-# 新文件只保留原有的个人 token 哈希，原有 Runner 令牌不会变化。
-. "$root/private.env"
-export COLLAB_ACCOUNTS_FILE="$root/accounts.wecom.json"
-# 仅停原中心服务，保持两个 Runner；先确认旧 PID 确实是本工具的服务。
-old="$(cat "$root/server.pid")"
-ps -p "$old" -o command=
-# 仅在确认该进程属于当前仓库的 apps/server/main.mjs 后，才手动执行：kill "$old"
-node apps/server/main.mjs
+pnpm install --frozen-lockfile
+npm test
+node bin/codex-collab.mjs setup
 ```
 
-上面最后一条**前台运行**，该终端不要退出；另开终端 `curl http://127.0.0.1:38765/health` 检查服务。若提示端口占用，先核对旧服务 PID，勿盲目杀其他进程。若群中收到真实回复才算接通。群里的任务示例：
-
-1. `协作 创建 给 greet.sh 增加 --upper 行为 | sh test.sh 通过;sh greet.sh --upper 输出 HELLO, WORLD;保留原有默认输出`，记下新任务 `T-...`；不要重复使用历史任务。
-2. `协作 分配 T-... bob`；本机 Bob Runner 自动领取并在隔离副本创建 `codex/task-*` 代码分支。Alice Runner 可读取审查任务并写私有审查记录。
-3. `协作 状态 T-...`；人工核对 `git -C "$root/demo" branch --list 'codex/task-*'`、`sh test.sh`（需要在**任务分支**的 worktree 执行；`main` 故意未完成，不能直接把它的失败当任务失败）和 `$root/server-data` 的 Git 账本；不能把 Runner 记录当人工批准。
-4. 确认代码和测试证据后，由 **alice 真人**发 `协作 审核 T-... 通过`，再发 `协作 完成 T-...`；这两个动作不会由 Runner 自动执行。失败就 `协作 审核 T-... 退回`。
-
-**注意**：发现、认证、模拟 E2E、真实群消息送达、群回复、主动任务通知是不同的成功条件；逐项核实。这里使用 `$root/demo` 隔离副本，不修改或推送原始 demo 仓库。`COLLAB_PUSH` 单机保持默认关闭；源仓库与真实企业账号信息勿放入 Git。若之前本机 Runner 不在运行，查看 `ps` 与 `apps/runner/README.md`；不要以为启动 HTTP 服务就会自动启动 Runner。
-
-## 同事接入 MCP 和 Skill
+保留 `codex-collab setup --terminal`、`setup --role admin|member` 和原有 `start` / `stop` / `status` 等命令。终端模式沿用旧 `team.json` 工作流，网页向导使用签名团队版本与加密个人接入包，初始化 v3 人工审核策略。旧 v2 团队导入后仍保留原行为；保存审核规则才升级，升级前请先更新所有成员的工具并重启机器人和 MCP。不会改写全局 Codex、CC Switch 或模型账号设置。
 
-执行 `node scripts/install/install.mjs https://your-server/mcp`，将生成的 TOML 示例加入个人 Codex 配置，将 `COLLAB_TOKEN` 安全注入启动 Codex 的环境并重启。详见 `scripts/install/README.md`。安装 Skill 不会自动启动 Runner；只要桌面人工协作可不跑 Runner。MCP endpoint 用 Bearer 身份，未登录用户无法写任务。
+- [接入、迁移和首次验收](docs/onboarding.md)
+- [团队签名协议与目录](docs/team-registry.md)
+- [Peer 机制与底层命令](docs/peer.md)
+- [已有桌面对话轮询机制](docs/desktop-poll.md)
+- [旧中心服务与飞书接入](docs/legacy-center.md)
 
-实现细节和限制见 `docs/architecture.md`、`docs/protocol.md`、`apps/runner/README.md`。**单写服务**假设，不支持多个中心服务实例同时写 Git。
+2026-10-10 已由用户验证本机真实企业微信群 + Alice/Bob 两个已有 Codex 对话的接力闭环。网页向导与真人审核闭环通过临时 Git 仓库、模拟机器人和实际浏览器操作验证；2026-10-12 这轮测试没有连接真实机器人，原生 @ 尚未验证。跨两台机器的部署尚未验证。

package/apps/onboarding/bundle.mjs

@@ -0,0 +1,24 @@
+import { SetupError } from './errors.mjs';
+import { randomBytes, scryptSync, createCipheriv, createDecipheriv } from 'node:crypto';
+export function encryptBundle(value, password) {
+  if (typeof password !== 'string' || password.length < 12 || password.length > 256) throw new SetupError('接入包密码至少 12 个字符，请单独交给成员。');
+  const salt = randomBytes(16), iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', scryptSync(password, salt, 32), iv);
+  const ciphertext = Buffer.concat([cipher.update(JSON.stringify(value), 'utf8'), cipher.final()]);
+  return { schema_version: 1, kind: 'codex-collab-encrypted-invite', salt: salt.toString('base64'), iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), ciphertext: ciphertext.toString('base64') };
+}
+export function decryptBundle(value, password) {
+  try {
+    if (value?.schema_version !== 1 || value.kind !== 'codex-collab-encrypted-invite' || typeof password !== 'string' || password.length > 256) throw new Error();
+    const salt = Buffer.from(value.salt, 'base64'), iv = Buffer.from(value.iv, 'base64'), tag = Buffer.from(value.tag, 'base64');
+    if (salt.length !== 16 || iv.length !== 12 || tag.length !== 16 || typeof value.ciphertext !== 'string' || value.ciphertext.length > 500000) throw new Error();
+    const decipher = createDecipheriv('aes-256-gcm', scryptSync(password, salt, 32), iv); decipher.setAuthTag(tag);
+    return JSON.parse(Buffer.concat([decipher.update(Buffer.from(value.ciphertext, 'base64')), decipher.final()]).toString('utf8'));
+  } catch { throw new SetupError('接入包或密码无效，请确认文件完整且密码正确。'); }
+}
+export function remoteIdentity(remote) {
+  const scp = remote.match(/^(?:[^@/]+@)?([^:/]+):(.+)$/);
+  try { const url = new URL(remote); if (['https:', 'http:', 'ssh:'].includes(url.protocol)) return `${url.hostname.toLowerCase()}/${url.pathname.replace(/^\/+|\/+$/g, '').replace(/\.git$/, '')}`; } catch {}
+  if (scp && !remote.startsWith('/')) return `${scp[1].toLowerCase()}/${scp[2].replace(/\/+$/g, '').replace(/\.git$/, '')}`;
+  return remote;
+}

package/apps/onboarding/discovery.mjs

@@ -0,0 +1,44 @@
+import { SetupError } from './errors.mjs';
+import AiBot from '@wecom/aibot-node-sdk';
+import { randomInt, randomUUID } from 'node:crypto';
+import { wecomDiagnostic } from '../../scripts/wecom-diagnostic.mjs';
+
+/** Short-lived connection; credentials and group messages never enter HTTP output. */
+export class BotDiscovery {
+  constructor({ clientFactory = (options) => new AiBot.WSClient(options), now = Date.now } = {}) {
+    this.clientFactory = clientFactory; this.now = now; this.sessions = new Map();
+  }
+  begin({ bot_id, secret, chat_ids }) {
+    if (typeof bot_id !== 'string' || !bot_id.trim() || typeof secret !== 'string' || !secret) throw new SetupError('请填写机器人 Bot ID 和 Secret。');
+    this.closeAll();
+    const id = randomUUID(); const code = String(randomInt(100000, 1000000));
+    const state = { id, code, bot_id: bot_id.trim(), secret, expected_chats: chat_ids, expires: this.now() + 300000, status: 'connecting', proof: null, client: null, timer: null };
+    const logger = { debug() {}, info() {}, warn() {}, error() {} };
+    const client = this.clientFactory({ botId: state.bot_id, secret, logger }); state.client = client;
+    client.on('authenticated', () => { state.status = 'authenticated'; });
+    client.on('error', (error) => { state.status = 'failed'; state.error = wecomDiagnostic(error); });
+    client.on('disconnected', () => { if (!state.proof && !['expired', 'failed'].includes(state.status)) state.status = 'disconnected'; });
+    client.on('message.text', (frame) => {
+      if (this.now() > state.expires || state.proof || state.status !== 'authenticated') return;
+      const body = frame?.body;
+      const text = body?.text?.content?.trim().replace(/^(?:@[^\s@]{1,40}\s+)+/, '');
+      if (body?.chattype !== 'group' || !body.chatid || !body.from?.userid || text !== `协作 接入 ${code}` || state.expected_chats && !state.expected_chats.includes(body.chatid)) return;
+      state.proof = { chatid: body.chatid, userid: body.from.userid }; state.status = 'verified';
+      client.disconnect();
+    });
+    state.timer = setTimeout(() => { if (!state.proof) { state.status = 'expired'; client.disconnect(); } }, 300000); state.timer.unref();
+    this.sessions.set(id, state); client.connect(); return this.view(id);
+  }
+  view(id) {
+    const state = this.sessions.get(id); if (!state) throw new SetupError('验证连接已结束，请重新连接。');
+    if (this.now() > state.expires && !state.proof) { state.status = 'expired'; state.client.disconnect(); }
+    return { id, status: state.status, message: `协作 接入 ${state.code}`, proof: state.proof, ...(state.error ? { error: state.error } : {}) };
+  }
+  consume(id) {
+    this.view(id); const state = this.sessions.get(id);
+    if (!state.proof || this.now() > state.expires) throw new SetupError('请先在群里完成机器人验证。');
+    this.sessions.delete(id); clearTimeout(state.timer); state.client.disconnect();
+    return { bot_id: state.bot_id, secret: state.secret, ...state.proof };
+  }
+  closeAll() { for (const state of this.sessions.values()) { clearTimeout(state.timer); state.client.disconnect(); } this.sessions.clear(); }
+}

package/apps/onboarding/errors.mjs

@@ -0,0 +1 @@
+export class SetupError extends Error {}

package/apps/onboarding/main.mjs

@@ -0,0 +1,32 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { startSetupServer } from './server.mjs';
+import { SetupManager } from './manager.mjs';
+import { alive } from '../peer/process.mjs';
+function openBrowser(url) {
+  const command = process.platform === 'darwin' ? ['open', url] : process.platform === 'win32' ? ['cmd', '/c', 'start', '', url] : ['xdg-open', url];
+  const child = spawn(command[0], command.slice(1), { stdio: 'ignore' }); child.on('error', () => {}); child.unref();
+}
+export async function runLocalSetup({ open = true, home = join(homedir(), '.config/codex-collab/workspace') } = {}) {
+  home = resolve(home); await mkdir(home, { recursive: true, mode: 0o700 });
+  const path = join(home, 'wizard.json'); let lock;
+  try { lock = await (await import('node:fs/promises')).open(path, 'wx', 0o600); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    let previous; try { previous = JSON.parse(await readFile(path, 'utf8')); } catch { throw new Error('本机向导正在初始化，请稍后重试。'); }
+    if (alive(previous.pid)) { console.log(`本机向导已运行：${previous.url}`); if (open) openBrowser(previous.url); return; }
+    await rm(path, { force: true }); return runLocalSetup({ open, home });
+  }
+  let app;
+  try {
+    app = await startSetupServer({ manager: new SetupManager({ home }) });
+    await lock.writeFile(JSON.stringify({ pid: process.pid, url: app.url }) + '\n'); await lock.close();
+    console.log(`Codex Collab 本机接入向导：${app.url}\n保持此终端运行。Ctrl-C 关闭向导；已启动的机器人 Runner 会继续运行。`);
+    if (open) openBrowser(app.url);
+    const stop = async () => { await app.close(); await rm(path, { force: true }); process.exit(0); };
+    process.once('SIGINT', stop); process.once('SIGTERM', stop);
+    return app;
+  } catch (error) { await lock.close().catch(() => {}); await rm(path, { force: true }); if (app) await app.close(); throw error; }
+}