xuym-codex-collab 0.1.1 → 0.3.1

package/docs/desktop-poll.md

@@ -1,5 +1,7 @@
 # 企业微信任务 → 指定 Codex 桌面对话轮询执行
 
+日常团队使用 [本机网页接入向导](onboarding.md) 自动配置项目、群身份和机器人。本页保留隔离测试与底层轮询机制。已有配置可从网页导入，无需重绑对话。一个真人使用多个机器人建议走向导的“给自己增加机器人”，允许 Alice/Bob 共享 userid 并各自处理命令。本页的旧隔离测试脚本仍默认只给 Alice 设置群命令身份。
+
 本模式是 `desktop_poll`，不是后台 SDK 自动模式，也不是旧的手动 `desktop` 保留。企业微信适配器负责入口/通知，Git 保存协议，**指定已有 Codex 对话的 heartbeat**负责调用 MCP 接单并在该对话执行。
 
 ```text
@@ -8,12 +10,15 @@
   → Git agent-collab 写 desktop_poll 任务（open，未开始执行）
   → Alice 已有对话 heartbeat → MCP 原子认领、准备隔离工作树
   → 本对话修改/测试/明确提交 → finish_desktop_task
-  → 固定测试 + 租约/祖先校验 + push → handoff
-  → Alice Bot 通知结果和下一阶段
+  → 固定测试 + 租约/祖先校验 + push → stage_review_requested（v3 默认）
+  → Alice Bot 通知结果、本人审核与 R-版本号
+  → 指定真人通过 → waiting（退回则原阶段从该 SHA 修改）
   → Bob 已有对话 heartbeat → 从准确 checkpoint SHA 接力
-  → review_requested → Bob Bot 通知 → 真人审核/完成
+  → review_requested → Bob Bot 通知 → 指定真人审核 → 管理员完成
 ```
 
+此图采用网页向导 v3 默认审核规则。下文 `setup-local` 创建的隔离静态策略仍为 v2，中间提交直接 handoff，最终由管理员审核；若需测试阶段审核，使用网页向导初始化新团队，或导入旧配置后保存审核规则。
+
 通知不构成调度：机器人不必接收其他机器人的消息。下一位从 Git 发现工作，群里告知“优先 Bob”是人的可见提示，不是假冒成功 @ 或实时唤醒。
 
 ## 一次性配置
@@ -85,7 +90,7 @@ node scripts/peer/cli.mjs start "$root/alice-peer.json"
 node scripts/peer/cli.mjs start "$root/bob-peer.json"
 ```
 
-日志应显示 `notifications only; automatic code execution disabled` 和两次各自的 `Peer WeCom authenticated`。Alice 接本人的群命令；Bob 在单真人模拟中只发送自己的通知。真实多用户需独立 owner 身份，不能复制同一真人 userid 绕过权限。
+日志应显示 `notifications only; automatic code execution disabled` 和两次各自的 `Peer WeCom authenticated`。本页旧脚本默认 Alice 接本人的群命令，Bob 只发送通知。这是测试夹具的默认设置；新网页向导支持同一真人拥有两个可接群命令的 Agent，各自用独立机器人和密钥。真实同事应验证各自本人账号。
 
 可用 CLI 检查“进程在线”和“企微已鉴权”是否是两个独立状态：
 
@@ -110,8 +115,8 @@ node scripts/peer/cli.mjs status "$root/bob-peer.json"
 
 1. 群回复“等待绑定的 Codex 桌面对话轮询认领”，不是“后台 SDK 已开始”。
 2. 指定 Alice 对话出现任务 ID、当前阶段和实际修改/测试记录；Alice Bot 发 claimed。
-3. Alice `finish_desktop_task` 固定验证通过并 push；群里给出结果、SHA、测试与下一阶段优先 Bob。
-4. 指定 Bob 对话从 Alice 的准确 SHA 执行；Bob Bot 发 claimed、review_requested。
+3. Alice `finish_desktop_task` 固定验证通过并 push；群里给出结果、SHA、测试。v3 默认先等待 Alice 本人审核，通过后才显示下一阶段优先 Bob；v2 或关闭中间审核时直接交接。
+4. 指定 Bob 对话从 Alice 的准确 SHA 执行；Bob Bot 发 claimed、review_requested，并给出实际审核人与版本号。
 5. 四种行为通过，最终 checkpoint 包含两阶段代码；main 未自动改变，等待真人审核。
 
 仅测试通过、后台日志出现 claimed、或群里有回复，都不能代替“实际指定已有桌面对话自动执行”的验收。应用是否自动切到该对话不是验收条件，打开该对话应看到执行记录。
@@ -119,10 +124,13 @@ node scripts/peer/cli.mjs status "$root/bob-peer.json"
 审核仍由真人群命令完成：
 
 ```text
-@Alice 协作 审核 T-真实任务ID 通过
+@审核人自己的机器人 协作 审核 T-真实任务ID R-7 通过
+@审核人自己的机器人 协作 审核 T-真实任务ID R-7 退回 | 修改意见
 @Alice 协作 完成 T-真实任务ID
 ```
 
+示例 `R-7` 替换为最新通知版本；v2 任务仍兼容省略版本号的旧命令。本页旧夹具中没有群命令身份的 Bob 由 Alice 管理员审核；新向导中用相同本人账号验证的 Bob 默认通过 Bob 机器人审核，按当前通知操作。原生 @ 提醒需实群确认；审核与 Git 接力不依赖原生 @。
+
 ## MCP 与运行约束
 
 | 工具 | 作用 |
@@ -156,4 +164,4 @@ node scripts/peer/cli.mjs stop "$root/bob-peer.json"
 
 ## 验证范围
 
-2026-10-10 本轮全套 58 项自动测试通过，其中新增 7 项桌面对话轮询测试。本项目自动测试覆盖模拟群命令、真实 stdio MCP、真实 Git/worktree/固定测试、绑定防误用、双对话身份接力、精确 SHA、无闲置续租、过期候补及迟到发布拒绝；模型修改由测试夹具模拟，不冒充真实 Codex 桌面会话。据用户同日确认，本机真实企业微信群 + Alice/Bob 既有 Codex 对话的完整轮询接力已验证；跨两台机器部署尚未验证。
+2026-10-10 完成首批桌面对话轮询验证；2026-10-12 增加阶段审核、退回修订、过期审核拒绝和旧策略升级测试。本项目自动测试覆盖模拟群命令、真实 stdio MCP、真实 Git/worktree/固定测试、绑定防误用、双对话身份接力、精确 SHA、无闲置续租、过期候补及迟到发布拒绝；模型修改由测试夹具模拟，不冒充真实 Codex 桌面会话。据用户同日确认，本机真实企业微信群 + Alice/Bob 既有 Codex 对话的完整轮询接力已验证；跨两台机器部署尚未验证。

package/docs/legacy-center.md

@@ -0,0 +1,109 @@
+# 旧中心服务模式（源码兼容）
+
+日常团队接入请使用 [本机网页向导](onboarding.md)。本页保留旧 HTTP 服务操作，npm 包只分发 Peer 与本机向导；旧中心服务须从工具源码启动。
+
+以下为保留的**旧中心服务模式**操作；不要与上面的 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
+```
+
+演示目标仓库 `codex-collab-demo` 的 `main` 执行 `sh test.sh`，而任务事件在 `agent-collab`。示例任务 T-001 为故意未完成的编程任务；可用两个不同用户通过 API/MCP 和 Runner 测试。现有 T-001 未指定审核人，建议通过飞书命令创建**新任务**以获得默认管理员审核人。
+
+## 本地启动
+
+生成账号文件（不要放进 Git，执行完把终端输出的个人令牌安全地分发给对应用户）：
+
+```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
+```
+
+运行成功后 `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
+```
+
+`COLLAB_API` 单机实验可用 `http://127.0.0.1:38765`；不同机器应提供 HTTPS，且每台机器的目标仓库含 `main` 和 `agent-collab` 分支。若跨机器分发代码分支，需要在服务和 Runner 均设置 `COLLAB_PUSH=1`，保证 origin 可访问且个人 Git 凭据已配置。服务向 `agent-collab` 推送账本，Runner 向 `codex/task-*` 推送代码；**没有凭据会失败**。不能直接把 localhost 地址给其他同事。
+
+## 飞书接入
+
+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；模拟通过**不等于**真实群接通。
+
+## 本机接企业微信群（已有隔离 demo 和两个 Runner 时）
+
+**先在企业微信管理端创建/配置支持 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
+```
+
+上面最后一条**前台运行**，该终端不要退出；另开终端 `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
+
+执行 `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/architecture.md`、`docs/protocol.md`、`apps/runner/README.md`。**单写服务**假设，不支持多个中心服务实例同时写 Git。

package/docs/local-automatic-test.md

@@ -17,7 +17,7 @@
 | 企微连接 | Alice 接命令；Bob 发通知 | Alice 接命令并执行；Bob 不接命令但可执行并发通知 |
 | Git | 私有本机 bare remote | 另一个私有本机 bare remote，不推送 GitHub |
 
-**Bob 的 `commands_enabled=false` 只禁用群命令入口，不禁用自动执行。** 它不需要收到 Alice Bot 的 @ 消息，直接读取 Git 中的已签名 handoff 就会接力。一个真人模拟两位 agent 时，仅把你的 userid 绑定给 Alice；Bob 不重复绑定。
+**Bob 的 `commands_enabled=false` 只禁用群命令入口，不禁用自动执行。** 它不需要收到 Alice Bot 的 @ 消息，直接读取 Git 中的已签名 handoff 就会接力。本页旧测试脚本仅给 Alice 绑定 userid，Bob 保持通知模式。新网页向导支持同一个 userid 拥有多个独立 Agent，并同时开启各机器人的群命令；模拟既有 Codex 对话接力请使用 [向导中的本人多机器人流程](onboarding.md#一个人使用多个机器人或模拟两个同事)。
 
 ## 1. 生成新的自动测试环境
 

package/docs/local-peer-test.md

@@ -18,7 +18,7 @@
 | 两个本地 Runner | `auto_execute=false`，只连接机器人和中继通知 |
 | `origin.git` | 本机共享 bare Git remote，不连接 GitHub |
 
-团队策略要求不同成员使用不同企业微信真人 `userid`。本次只有你一位真人，不能把你的 userid 同时绑定给 Alice 和 Bob；Bob 用 `--notify-only`，不会放宽审核权限。真实同事加入时，用独立真人身份建立新的团队策略。
+本页保留的旧测试脚本只给 Alice 绑定真人 `userid`，Bob 用 `--notify-only` 保持通知模式。新工具允许同一个真人拥有多个独立 Agent，并分别通过自己的机器人处理群命令；建议使用 [网页向导中的“给自己增加机器人”](onboarding.md#一个人使用多个机器人或模拟两个同事)，按新流程建立身份绑定，不直接修改旧任务的签名策略。真实同事使用各自的企业微信账号。
 
 ## 1. 只初始化一次
 

package/docs/onboarding-audit.md

@@ -0,0 +1,88 @@
+# 网页向导功能检查与测试记录
+
+检查日期：2026-10-13。对象是工具仓库中的网页向导源码，本记录对应 0.3.1 的发布前验证。
+
+## 测试范围
+
+使用独立的临时 Git 仓库、真实 Git 分支与签名协议、模拟企业微信连接进行验证。浏览器实际操作管理员与成员表单、文件下载/上传、状态与审核配置；自动测试覆盖接口鉴权、异常输入、任务接力、真人审核和失败候补。本次没有修改个人真实机器人凭据，没有停止原有 Alice/Bob Runner。
+
+浏览器中的“已认证”由模拟连接提供。测试中的对话绑定和轮询通过执行器 API 产生，不能据此宣称已完成真实企业微信群、桌面对话自动唤醒和多台电脑的联合验收。
+
+## 页面功能矩阵
+
+| 区域 | 功能 | 测试方式与结果 |
+| --- | --- | --- |
+| 启动与首页 | 终端链接换取本机会话、项目列表、打开项目 | 浏览器及 HTTP 测试通过；刷新后会话有效，已有项目保留 |
+| 访问控制 | 错误令牌、错误 Host/Origin、未登录接口、请求格式与体积 | HTTP 测试通过；拒绝未授权操作，返回安全提示 |
+| 管理员初始化 | 仓库目录、成员名称、职责、固定验证命令、机器人凭据 | 浏览器创建新管理员成功；无效 JSON/非字符串数组在连接前拦截 |
+| 仓库检查 | 缺少 origin、远程空仓库、缺少 main | 自动测试通过；给出具体的 origin/main 提示与推送指令 |
+| 群身份验证 | 连接、验证码、复制消息、继续检查 | 浏览器通过；未验证不能继续 |
+| 群身份约束 | 准确验证码、指定群、群消息发送人、连接认证前不得验证 | 自动测试通过；不匹配消息忽略 |
+| 验证恢复 | 连接失败重试、断开、验证码过期 | 失败与重试经浏览器验证；过期经自动测试验证 |
+| 团队初始化 | 生成本机身份、发布团队签名、安装 MCP/Skill、启动连接 | 浏览器与本地 Git 测试通过 |
+| 初始化中断 | 已保存项目重新打开、继续接入、启动失败重试 | 浏览器及自动测试通过；不会因页面恢复再次提交验证码 |
+| 分配机器人 | 独立机器人、职责、首选/候补、是否允许本人群命令 | 浏览器通过；取消两个选项后导出值均为 false |
+| 生成接入包 | 加密、密码、邀请有效期、重复成员/机器人约束 | 自动测试通过；浏览器生成并实际下载文件 |
+| 下载与保密 | 下载加密文件、文件不含明文 Secret | 浏览器下载后解密核验通过；Secret 仅存在加密正文 |
+| 邀请发布中断 | 找回同一份导出、重试发布、未发布邀请不得加入 | 自动测试通过 |
+| 成员导入 | 文件上传、密码、业务 clone 与 remote 一致性 | 浏览器正确文件/密码通过；错误密码能留在表单重试；remote 校验经自动测试覆盖 |
+| 文件错误 | 损坏的 JSON、错误密码、被篡改密文 | 自动测试通过；损坏 JSON 有明确重新下载提示 |
+| 重复导入 | 已验证、待批准、配置中、已就绪成员再次导入 | 自动测试通过；浏览器重复导入 ready 成员直接打开原项目，不再抢机器人连接 |
+| 入队申请 | 群身份自动生成 userid、提交签名申请、等待管理员 | 浏览器通过；成员页面显示待批准状态 |
+| 管理员批准 | 显示申请身份、确认入队、更新成员与职责路由 | 浏览器与协议测试通过；新增职责自动有审核规则 |
+| 成员完成配置 | 批准后继续、安装个人 MCP/Skill、启动机器人 | 浏览器通过 |
+| 旧项目导入 | 旧管理员先导入、保留身份/任务/绑定、重复导入 | 浏览器及自动测试通过；兼容原生成的 desktop MCP 配置路径 |
+| 项目状态 | MCP、Skill、机器人、对话绑定、实际轮询、综合就绪 | 浏览器与自动测试通过；缺失/禁用配置、未绑定或轮询过期不会显示综合就绪 |
+| 绑定指令 | 展示、复制、指定身份和项目 | 浏览器通过；桌面对话仍需执行指令，页面不能代替对话创建 heartbeat |
+| 连接操作 | 启动、停止、启动失败、安全错误保存、成功后清理错误 | 浏览器及自动测试通过 |
+| 团队分工 | 成员/职责列表、首选与候补顺序展示 | 浏览器通过；当前可查看，不能编辑既有顺序 |
+| 本人多机器人 | 管理员添加自己的新 Agent、独立 clone 与 Bot、同一真人验证 | 浏览器完成 Alice → 新 Bob 接入；无需下载接入包或设置接入包密码 |
+| 本人接入恢复 | 发布确认丢失、自动批准中断、首页重新打开已保存配置 | 自动测试通过；浏览器从已保存分配继续并打开 ready 项目，不重复创建身份 |
+| 普通同事多机器人 | 同一 userid 分别导入多个接入包、逐个批准 | 自动测试通过；两个 Agent 均保留群命令权限 |
+| 身份隔离 | 独立签名密钥、独立项目 MCP、错误真人/remote 拒绝 | 自动测试通过；同一所有者不合并 Agent 角色，Bob 仍不能签署管理员完成事件 |
+| 审核与通知 | 同一真人 @ 去重、明确审核 Agent 和对应机器人、错误审核机器人拒绝 | 自动测试通过；按 Alice/Bob 的独立签名身份进行审核和任务接力 |
+| 所有者与路由展示 | 显示同一真人的多个 Agent、首选与候补 | 浏览器确认“你的机器人：alice、bob”和 backend：bob → alice，无控制台错误 |
+| 真人审核规则 | 必须审核开关、审核人、额外通知、指定已验证同事、保存与刷新 | 浏览器及自动测试通过；版本校验拒绝过时配置，新规则只用于新任务 |
+| 协作执行 | 两位执行者接力固定提交、运行验证、发阶段通知、真人审批、完成 | 本地自动测试通过；真实群通知呈现仍需实群验证 |
+| 诊断提示 | 配置路径、失败说明、Git 同步失败本机状态回退 | 浏览器确认配置路径展示；安全错误与 Git 同步回退经自动测试覆盖，不输出 SDK 原始异常 |
+
+完整测试命令是 `npm test`，最终结果为 **108 passed, 0 failed**。新增加的页面事件测试运行实际交付的 `app.js`，使用最小 DOM 验证 API 调用顺序与恢复；它不能替代真实浏览器交互。本次已结合两种测试。
+
+## 本次修复
+
+1. 重复导入已接入成员的接入包时，按已有阶段打开项目，避免重复验证抢占 Runner；首次导入后连接失败也能看到已保存项目和重新连接入口。
+2. 项目状态独立显示 MCP 与 Skill，并识别旧版生成的 desktop 配置。综合就绪要求项目配置、认证连接、绑定和最近三分钟内实际轮询同时满足。显式禁用 MCP 会显示未就绪。
+3. 验证成功后页面加载失败，不再因为清空 pending 而报空对象错误；管理员中断恢复识别本次新建的项目，兼容规范化后的目录路径。
+4. 中断接入与 Runner 启停错误转换成可恢复的安全中文提示；保存错误供刷新查看，成功后清理。
+5. 缺失 Git `info/exclude` 时正常创建父目录与排除文件，失败时恢复原状。
+6. 无效验证命令在连接前拦截；损坏接入包 JSON 有具体文件错误提示。
+
+## 本人多机器人补充验证
+
+新增 8 项多所有者/多 Agent 自动测试、3 项网页事件测试、1 项企业微信审核通知测试和 1 项网页接口鉴权测试。完整测试通过后，没有修改执行逻辑；本记录补充了验证范围与结果。
+
+浏览器使用新建的临时 Git 仓库、模拟机器人连接和模拟 Runner 启停，实际填写第二个 clone、新 Agent 和机器人配置，验证群身份后完成本人入队、安装 MCP/Skill，并从管理员页面继续打开该配置。这里的 ready 表示向导完成配置；模拟 Runner 不构成真实群连接或桌面对话验收。浏览器截图保存于本机临时目录，未加入发布包。
+
+本人邀请带有签名保护的可选 `owner_userid`，要求群验证账号与已验证管理员一致；接入记录沿用正常签名申请和管理员批准。邀请与恢复资料保存在仓库外的 0600 私有文件中。普通同事可以通过多份接入包使用同一个真人账号，但仍需分别验证和批准。新客户端接受旧邀请；旧客户端不识别新所有者字段或共享所有者策略，采用此功能前应统一升级并重启 Runner/MCP。
+
+## 尚缺少的页面功能
+
+| 功能遗漏 | 当前影响 |
+| --- | --- |
+| 更换机器人、轮换 Secret、变更群 | 只能按本机配置与企业微信端操作；向导没有维护入口 |
+| 撤销邀请、禁用/移除成员、轮换签名身份 | 当前没有产品化入口；需要补签名协议、权限与历史兼容，不能仅删本机文件 |
+| 修改既有成员职责、重排首选与候补 | 页面只展示已有分工；生成邀请时可以指定新成员优先级 |
+| 缺失 MCP/Skill 的一键修复 | 当前能识别缺失，但现有 Skill、受版本管理的配置等需要检查；不会自动覆盖 |
+| 确认 heartbeat 持续启用、切换绑定对话 | 页面能观察绑定与最近轮询；不能控制 Codex 自动化，切换需要对话工具解除旧绑定 |
+| 页面内展示日志与详细 Git 诊断 | 当前只有安全错误提示、私有配置路径；详细日志仍需本机查看 |
+| 多管理员配置冲突的页面引导 | 后端按版本拒绝过时保存；页面需要刷新重新设置，不会自动合并 |
+| 页面刷新保留正在进行的管理员验证码步骤 | 管理员保存 profile 前的验证码状态在当前页面内存中；刷新需重新填写和验证；成员已导入的项目可从首页恢复 |
+
+## 仍需联合验收的环境场景
+
+- 两台不同电脑分别安装 npm 包，对同一远程仓库各自接入、绑定真实 Codex 对话。
+- 真实企业微信群中创建任务、自动轮询启动执行、阶段总结、真人审核、下一位接力。
+- 企业微信原生 @ 提醒效果，以及真实 WebSocket 断线/凭据轮换的提示和恢复。
+- 应用退出、电脑休眠、heartbeat 暂停与网络恢复后，候补接管与旧执行者的租约隔离。
+
+页面的“项目 MCP / Skill 已就绪”表示本机文件已配置，并非读取了 Codex 的实际加载状态。近期成功轮询是额外证据，仍不能保证未来自动化持续运行。Git 启动检查与任务执行中的 Git 失败属于不同时间点，初始化通过不代表未来的 push 永远成功。

package/docs/onboarding.md

@@ -1,117 +1,140 @@
 # 团队安装与首次接入
 
-Codex Collab 使用目标代码仓库的 `agent-collab` Git 分支保存任务协议，不需要团队部署中心 HTTP 服务。每位成员在自己的电脑安装 CLI、生成自己的签名身份、使用自己的 Git 凭据和企业微信机器人；指定已有 Codex 对话通过 app heartbeat 轮询并执行任务。
+管理员统一创建企业微信机器人、分配职责，再把加密个人接入包交给同事。成员不需要自行创建机器人、手工查群 ID/用户 ID，也不需要单独部署中心服务。每个人的本机工具直接通过共同的 Git remote 协作。
 
-机器人不会把消息直接注入 Codex。配置完成后，必须在要执行任务的 Codex 对话里完成身份绑定和 heartbeat。完整机制与限制见 [desktop-poll.md](desktop-poll.md)；团队协议和排查见 [peer.md](peer.md)。
+## 每个人先准备一次
 
-## 前置条件
-
-- macOS/Linux 或 Windows，Node.js 20+，Git。
-- 每位成员都能 clone 目标仓库、读取 `origin/main` 并推送自己的协作分支。
-- 管理员和参与接单的成员均使用支持本地项目级 MCP/Skill、已有对话 heartbeat 的 Codex 桌面环境。
-- 企业微信管理员已创建「智能机器人 API 模式」机器人，并把需要通知的机器人加入目标群。
-
-安装公开 npm 包并确认 CLI 可用：
+1. 安装 Node.js 20+、Git 和支持对话 heartbeat 的 Codex 桌面应用。
+2. clone 要协作的业务仓库。仓库需有 `origin/main`，本机 Git 凭据能读取并 push `agent-collab` 及任务代码分支。
+3. 打开终端执行：
 
 ```sh
 npm install --global xuym-codex-collab
-codex-collab --help
+codex-collab setup
 ```
 
-包名是 `xuym-codex-collab`，安装后提供的命令名是 `codex-collab`。不要把 npm 密码、OTP 或 access token 发给同事或放进 Git。
+网页自动打开；若未打开，执行 `codex-collab setup --no-open`，复制终端打印的本机链接。保留此终端以使用工作台。团队成员只需 clone 业务仓库，无需 clone 工具仓库。
 
-## 成员先生成公钥
+同一台电脑模拟两位成员时，使用同一业务仓库的两个独立 clone、两个机器人、两个 Codex 对话；同一个 clone 只能接入一个身份。同一个企业微信账号可以拥有多个 Agent，每个 Agent 的机器人、签名身份、clone 和对话独立。真正同事使用自己的企业微信账号和 Git 凭据。
 
-管理员创建团队策略前，需要收齐每位成员的公钥。每位成员（包括管理员）在自己的电脑、自己的 npm 安装环境运行：
-
-```sh
-codex-collab identity create alice
-```
+## 管理员操作
 
-默认生成到 `~/.config/codex-collab/identities/`。命令显示两个文件路径：
+1. 在企业微信创建独立智能机器人，获取 Bot ID 和 Secret，拉进协作群。为每位成员分别创建机器人并加入同一个群。
+2. 工作台选择“初始化团队”：输入业务仓库本机目录、自己的成员名称、职责标签、固定验证命令，以及自己的机器人 Bot ID/Secret。成员名称与职责用英文、数字、下划线或连字符，例如 `alice`、`frontend,backend`。
+3. 点击“连接机器人并验证群”，用自己的企业微信账号 @ 此机器人，发送页面显示的 `协作 接入 六位数字`。返回网页点击“已发送，继续检查”。工具自动发现群 `chatid` 与你的 `userid`，创建身份、签名账本和项目 MCP/Skill，并启动本机机器人 Runner。
+4. 项目页面“分配机器人给同事”：填写成员名称、职责、成员机器人 Bot ID/Secret，以及至少 12 字符的接入包密码。“首选执行者”决定新成员在职责路由中排第一还是候补；未使用的职责会新增路由。
+5. 生成并下载加密 JSON 接入包，交给指定成员；密码通过另一条可信渠道单独提供。包默认 7 天有效，同一成员或机器人不会同时分发多个有效邀请。
+6. 成员完成群验证后，刷新“待确认的成员”，核对成员名称、职责和 userid，点击“确认此成员入队”。新的签名策略通过 Git 同步到其他在线成员，无需重建已有任务。
+7. 项目页“真人审核与通知”按职责设置审核人和额外通知对象，默认需要阶段审核且由执行者本人处理。可选管理员或已经验证本人身份的指定同事。管理员也按下文把自己的 Codex 对话启用。
 
-- `alice.private.json` 是本机签名私钥，权限为 `0600`。不要发送、提交 Git 或复制到其他成员电脑。
-- `alice.public.pem` 是公钥，只把这个文件通过团队认可的安全渠道交给管理员。
+同一位同事可以领取多份接入包，用同一个企业微信账号分别验证不同机器人；每份包选择独立 clone，并绑定不同 Codex 对话，不需要关闭群命令权限。
 
-agent ID 是任务协议里的稳定成员标识，应由团队统一命名，且只能包含英文字母、数字、下划线和连字符。创建后不要为同一 ID 重新生成身份。
+真人同事和机器人都应加入协作群。每位真人通过自己的企业微信账号验证接入，以便工具核对审核权限；额外通知对象不会因此获得审核权限。
 
-## 管理员初始化团队
+机器人必须由一个本机 Runner 保持连接。同一个 Bot ID 不要同时运行旧服务、群发现命令和新 Runner。向导会检查可识别的本机重复连接；其他电脑上的连接需由团队自己核实。
 
-确认每位成员都完成上一步，并收齐所有 `.public.pem` 文件后，管理员运行：
+## 成员操作
 
-```sh
-codex-collab setup --role admin
-```
+1. 从管理员取得自己的加密接入包和密码，先 clone 对应业务仓库。
+2. 打开 `codex-collab setup`，选择“加入团队”。选择接入包文件、输入密码和业务仓库目录，点击“导入并连接机器人”。工具会核对 origin 仓库；允许同一 remote 的 SSH/HTTPS 表达，不会改写 origin。
+3. 用**自己的企业微信账号** @ 分配给你的机器人，发送页面显示的验证码；回网页点击“已发送，继续检查”。本机生成签名身份，并把带公钥的入队申请写进协作分支。
+4. 等管理员在自己的工作台确认，然后在项目页点击“继续接入”。工具检查 Git 权限、写入项目的本地 MCP 和 Skill、启动机器人连接。
+5. 在 Codex 打开这个业务项目，信任项目并加载 MCP。工作台点击“复制启用指令”，粘贴到要代表你的**已有对话**，让对话完成身份核对、绑定真实 thread ID、创建 heartbeat 和首次无任务轮询。
+6. 回工作台刷新状态，确认机器人认证、对话绑定、实际轮询均已观察到。
 
-向导会依次询问管理员 agent ID、能力标签、成员 agent ID 和公钥文件、每种能力的首选/候补顺序、人工审核管理员、默认能力、共享仓库标识（例如 `jack506255560/codex-collab-demo`），以及目标仓库 clone 路径。
+启用指令不是 Secret。成员无需手工编辑 JSON、生成密钥或复制 userid。Codex 若没有暴露真实对话 ID，仍需本人提供该对话 ID/链接；工具不会猜测或访问应用私有数据库。若应用不支持 heartbeat，页面的启用指令会要求明确报告限制，不能当作已自动接单。
 
-企业微信 userid 可在初始化团队时填写，用来授权该真人通过群机器人发送协作命令。暂时没有 userid 时可以留空；该成员机器人只能发通知，不能处理群命令。不要把不同成员的真人 userid 填成同一个值。
+向导看到一次或近期轮询，只证明 MCP 实际被调用过，不代表已读取到应用自动化的开关。完成绑定后也应在当前对话核对 heartbeat 是否启用。默认指令尝试一分钟；周期以应用工具实际接受并运行的结果为准。
 
-向导在本机创建公开团队策略文件（`team.json`）和管理员自己的私钥，不会替其他成员生成私钥。团队策略在首个签名任务写入账本后就被固定；新增成员、更换公钥或调整候补顺序应在正式建任务前完成。
+## 已有 Alice/Bob 配置如何迁移
 
-通过团队认可的渠道分发 `team.json`。它包含成员公钥、能力路由和仓库标识，不含私钥或企业微信 Secret。
+现有通过私有 `peer.json` 运行的项目无需重新生成身份或重绑对话。
 
-## 成员加入团队
+1. 用原配置停止该机器人的 Runner：`codex-collab stop /absolute/path/to/private-peer.json`。有正在执行的任务时先处理其租约/执行状态。
+2. 进入网页“导入已有配置”，填写原私有配置的完整路径。**旧团队由管理员先导入，然后其他成员分别导入**。
+3. 工具从原策略建立签名版本根，保留原身份、私有数据目录、Codex 对话绑定和任务，再通过原配置路径重启 Runner。
+4. 已有 heartbeat 可以继续使用原配置路径；仍在运行的 MCP 可重新加载以获取新版代码。以后统一在工作台查看状态、添加新成员。
+5. 原 v2 团队不会仅因导入就改变接力行为。所有成员更新工具并重启机器人和 MCP 后，管理员在“真人审核与通知”保存规则，发布 v3 策略。此后创建的新任务应用新规则；正在执行的旧任务继续遵循原策略。
 
-每位成员先 clone 目标仓库，确认 `origin/main` 可读且本机 Git 凭据有协作分支 push 权限。然后运行：
+升级会保留项目里已经复制的 Skill。已有对话如果还在沿用旧提示词，可补充：
 
-```sh
-codex-collab setup --role member
+```text
+阶段提交返回 stage_review 或 review 时等待指定真人审核。
+审核退回后，按 review_feedback 从工具指定的提交继续修改并重新提交。
+审核与完成命令由真人在企业微信群执行。
 ```
 
-输入管理员提供的 `team.json` 路径、本机私钥文件、目标仓库 clone 路径和固定验证命令 argv。验证命令必须是 JSON 字符串数组，例如 `["npm","test"]`；默认值是 `["sh","test.sh"]`。它不会经过 shell 拆词，群消息不能改变这条命令。
+原对话绑定可以继续使用；定制过的 Skill 由本人检查并更新。
 
-向导会生成 `0600` 本机配置和私有数据目录，检查 Git root、`origin/main` 与 push dry-run，可选写入该 clone 的本地 Codex MCP 配置和 Skill，并把本地文件加入 `.git/info/exclude`。不会改写 `origin`、全局 Codex 配置、CC Switch、业务文件或提交任何内容。
+导入要求原配置是 `desktop_poll` 且包含企微机器人。策略根与本机已经信任的旧策略不一致时会拒绝迁移。旧成员尚未导入签名版本前，不应混用旧客户端处理新增成员的任务。
 
-若该项目已有 `.codex/config.toml` 被 Git 跟踪，向导会拒绝自动接入；不要强行取消跟踪，应让管理员检查项目配置，再采用个人 Codex 配置中的 MCP 示例。
+## 首次验收
 
-## 连接企业微信
+管理员和成员都绑定对话并完成实际轮询后，在群里选中实际机器人发送一条**新任务**：
 
-每台需要接收群通知的电脑都配置自己的机器人。不要让同一个 Bot ID 同时连发现命令和 Runner。
+```text
+@Alice 协作 创建 [frontend>backend] 给登录页增加密码显示切换 | npm test 通过
+```
 
-1. 在企业微信管理端创建智能机器人，取得 Bot ID 和 Secret，并把机器人加入目标群。
-2. 在本机运行 `codex-collab wecom discover`，按提示在终端输入 Bot ID 和 Secret。Secret 不回显、不进入 shell history，也不会打印消息正文。
-3. 在目标群向机器人发送一条普通文本；发现命令只会显示真实 `chatid` 和发送人的 `userid`。按 `Ctrl-C` 关闭发现连接。
-4. 在成员的 `codex-collab setup --role member` 向导中输入群 `chatid`，并在管理员初始化团队时为有命令权限的真人 pin 对应 `userid`。
+默认验收顺序：群回复任务 ID → Alice 指定对话执行 → 群收到阶段总结、代码提交、测试和审核命令 → Alice 本人审核通过 → Bob 指定对话从获准的 SHA 接力 → Bob 本人审核最终结果 → 管理员完成任务。
 
-Secret 仅在交互终端隐藏输入并保存到个人 `0600` 配置。不要将 Secret 发送到 Codex 对话、群聊或 Git。若曾泄漏，先在企业微信后台重置，再更新本机配置。
+管理员也能通过已经允许群命令的成员机器人创建/查询任务。`@Bob 协作 创建 ...` 默认使用 Bob 接入包中的首个职责；实际领取仍由能力路由、占用和候补决定。审核由当前指定审核人通过自己的机器人发出；完成、取消、重试仍需管理员通过自己的机器人发出。成员机器人不会代签其他人的操作。
 
-群 ID 可在同一配置中添加多个，以逗号分隔。机器人认证成功只代表连接可用；要确认群接通，需要在目标群发消息并看到该群 `chatid`。
+```text
+@Alice 协作 状态 T-实际任务ID
+@Alice 协作 审核 T-实际任务ID R-7 通过
+@Alice 协作 审核 T-实际任务ID R-7 退回 | 请补充键盘操作和相关测试
+@Bob 协作 审核 T-实际任务ID R-12 通过
+@Alice 协作 完成 T-实际任务ID
+```
 
-## 绑定 Codex 对话并启动
+示例中的 `R-7`、`R-12` 要替换成最新审核通知中的真实版本号。退回后当前阶段从被退回的 SHA 重做，对话会收到修改意见；重新提交后须使用新的版本号，旧命令会被拒绝。需要审核的阶段没有通过前，下一位不会接单。若关闭某职责的中间审核，中间提交直接交接；该职责作为最后阶段时仍交给管理员审核。
 
-成员向导结束时会生成私有 `bind-prompt.txt`。分别在准备代表该成员执行任务的**已有 Codex 对话**中打开目标项目、重载 MCP，并按文件内容完成：
+群通知会列出真人姓名对应的成员名称，并尝试带上已验证 userid 的提及。智能机器人长连接原生 @ 是否实际弹出提醒需要实群检查；加密 userid 转明文需要另接企业应用，目前没有集成。请同时检查群通知正文，不能仅以是否收到 @ 提醒判断任务是否在等待审核。
 
-1. 调用 `get_identity`，确认身份、项目和 `desktop_poll` 模式正确。
-2. 获取该对话真实 thread ID；不可猜测或读取 Codex 私有数据库。
-3. 调用 `bind_desktop_thread`，并在当前对话创建 heartbeat automation。MCP 不能自行唤醒闲置对话。
-4. 立即执行一次无任务轮询，确认绑定和工具可用。
+群里“任务已创建”和“机器人已认证”不能代替 Codex 已接单证据。最终任务不会自动批准或合并 `main`；管理员需要检查代码、真实测试证据再决定如何合并。消息中的 `npm test 通过` 是验收描述，真正运行的是管理员在本机初始化时固定的 JSON argv。
 
-完成绑定后，成员可以在向导中选择立即启动 Runner；也可以之后在终端执行：
+## 一个人使用多个机器人，或模拟两个同事
 
-```sh
-codex-collab start /absolute/path/to/private-peer.json
-codex-collab status /absolute/path/to/private-peer.json
-codex-collab doctor /absolute/path/to/private-peer.json
-```
+准备同一业务仓库的两个独立 clone、两个企业微信机器人和两个 Codex 对话。管理员给自己增加 Agent 可以直接在同一工作台完成：
 
-desktop_poll 下 Runner 负责本机企业微信收发和 Git 事件通知，不启动另一个 Codex SDK 会话。实际代码由 heartbeat 所属的已有 Codex 对话执行。机器人和本机网络必须保持在线，Codex 应用也要能运行 heartbeat。
+1. 以 Alice 初始化团队，完成群验证并进入管理员项目。已有团队可直接打开已就绪的管理员项目。
+2. 点击“给自己增加机器人”，填写第二个 clone 的本机目录、新 Agent 名称 `bob`、职责 `backend`，以及新机器人的 Bot ID/Secret。
+3. 保留“首选执行者”时，Bob 成为 backend 首选；Alice 若也有 backend 能力则是候补。点击“连接我的新机器人”。无需包密码或下载接入包。
+4. 用初始化 Alice 时的**同一个企业微信账号** @Bob，发送页面验证码，再点击“已发送，继续检查”。工具校验本人身份，自动签名批准新 Agent、配置 Bob 项目的 MCP/Skill 并启动连接。Bob 仍是 member，不会继承 Alice 的管理员角色。
+5. 在 Alice clone 和 Bob clone 中分别打开要绑定的已有 Codex 对话，向各自对话粘贴该项目的“启用指令”。每个 Agent 各自创建 heartbeat，确认身份与最近轮询。
+6. 在群里 @Alice 创建包含两种职责的任务，例如 `[frontend>backend]`。默认 Alice 阶段提交后你 @Alice 审核，Bob 阶段提交后你 @Bob 审核，最后 @Alice 完成任务。以每次通知指定的审核身份和版本号为准。
 
-同一个机器人不可同时被旧服务、发现命令和新 Runner 连接。重复启动前先检查状态；停止命令是：
+两份配置都允许所有者发送群命令。同一个 userid 只表示是同一个真人；收消息的机器人决定签名 Agent，权限不会合并，发给 Bob 的管理员完成命令仍会被拒绝。审核人与通知对象属于同一个真人时，群通知只提及一次，同时列出所对应的 Agent 和必须使用的审核机器人。
 
-```sh
-codex-collab stop /absolute/path/to/private-peer.json
-```
+普通团队成员拥有多个机器人时，由管理员给他分配多份独立接入包；成员用自己的同一个账号验证，管理员逐个确认，其余操作与成员流程一致。“给自己增加机器人”的自动批准入口仅供已经验证、就绪的管理员使用。
 
-## 首次验收
+接入中断时，从管理员项目“已分配的机器人”找到 Bob，点击“继续接入我的机器人”，或从首页打开已经保存的 Bob 项目继续。不要重新生成同名 Agent。若误选 Alice 的 clone、另一个 remote 或已分配的 Bot ID，工具会拒绝。
 
-确认所有成员都完成 `get_identity`、绑定真实对话、heartbeat 无任务轮询和 Runner 状态检查后，在目标群由授权真人 @ 已配置为命令入口的机器人，发一条新任务：
+使用这个功能前，所有参与者需运行包含多 Agent 所有权支持的新工具，并重启旧 Runner/MCP。旧客户端会拒绝重复 owner userid 或新邀请的可选字段。旧策略里没有 userid 的通知机器人仍按旧规则由管理员审核；已签名的旧身份绑定不能直接手改成新绑定。
 
-```text
-@Alice 协作 创建 [frontend>backend] 给登录页增加密码显示切换 | npm test
+## 工作台、停止和恢复
+
+默认本机数据位于 `~/.config/codex-collab/workspace`，机器人 Secret、私钥、对话 ID、Runner 日志和接入状态均在业务仓库之外；私有 JSON 使用 `0600`。Git 只同步签名协议、公钥、职责、任务证据和必要结果摘要。
+
+- 重复导入同一接入包：已验证或已接入的成员会直接打开原项目，继续原进度；不会重复启动群验证。
+- 项目接单状态：同时检查 MCP、Skill、认证连接、目标对话绑定和最近三分钟内实际轮询。配置文件存在不等于 Codex 已加载，自动化启用状态仍需在绑定对话确认。
+- 群验证断线/过期：点击“重新连接”，使用新的验证码。
+- Git/MCP 配置中断：从“我的项目”打开原项目，再点击“继续接入”；不要反复创建另一身份。
+- 管理员生成邀请时网络失败：回项目页面刷新已生成接入包，再下载；本人机器人点击“继续接入我的机器人”。工具重试发布同一签名邀请。
+- 本机工作台关闭：重新运行 `codex-collab setup`；已启动的机器人 Runner 会继续运行。
+- 页面“停止机器人连接”只断开群机器人。暂停接单需在对应 Codex 对话暂停 heartbeat；已有任务仍需完成、报告失败或按租约恢复处理。
+- CC Switch 与模型账号设置保持原样；项目 MCP 使用本机 Node 的绝对执行路径。
+
+底层诊断命令仍可用，配置路径可在项目页面展开“查看本机配置路径”并复制：
+
+```sh
+codex-collab status /absolute/path/to/private-peer.json
+codex-collab doctor /absolute/path/to/private-peer.json
 ```
 
-完整验收至少检查：群回复任务 ID；Alice 的指定已有对话出现任务并提交阶段结果；Git 账本记录准确 commit SHA；下一位候补对话从该 SHA 接力；群里收到阶段通知；最终任务等待真人审核。不要把机器人在线或“任务已创建”误判为 Codex 已经开始执行。
+Secret 若曾发到聊天或 Git，应在企业微信重新生成后更新本机配置。工具只发布协作任务的阶段总结，不会把整个私有 Codex 对话发到群里；目前尚无任意普通对话完成后自动发群总结的独立工具。
 
-跨机器任务依赖同一可读写 Git remote。任务不会共享完整聊天记录，不自动批准、不合并 `main`。管理员仍需人工审查最终提交并决定是否合并。
+旧命令兼容：`codex-collab setup --terminal` 或 `setup --role admin|member` 继续使用 [旧终端工作流](terminal-onboarding.md)，不走加密包与动态签名入队。
 
+网页向导的逐项覆盖、故障恢复与功能遗漏见 [功能检查与测试记录](onboarding-audit.md)。

package/docs/peer.md

@@ -1,5 +1,7 @@
 # Peer 模式：无中心服务的 Codex 协作
 
+日常团队接入请使用 [本机网页向导](onboarding.md)：管理员分配机器人，成员导入加密包。本页保留底层静态策略与 CLI。新版签名团队历史及旧任务策略规则见 [团队登记协议](team-registry.md)。
+
 Peer 模式不部署共享 HTTP 服务。每位同事在自己的电脑上运行同一份工具仓库中的两个本地进程：
 
 1. **MCP stdio**：给当前桌面 Codex 调用，用于创建/读取/交接任务。
@@ -86,7 +88,7 @@ unset WECOM_BOT_SECRET
 
 不要把上面的真实 Secret 放在命令历史、聊天或 Git 中；如果曾经泄露，先在企业微信后台轮换，再使用新 Secret。
 
-同一个真人本机模拟两位 agent 时，第二个 Bot 可以在配置命令后加 `--notify-only`；它只发送该 agent 的事件，不接收群命令，不需要绑定第二个真人 userid。不得把同一个 userid 分配给两个团队成员。
+同一个真人可以拥有多个独立 Agent，并使用同一个已验证 `userid`；每个 Agent 仍需独立机器人、签名身份、clone 和对话。推荐通过 [网页向导](onboarding.md#一个人使用多个机器人或模拟两个同事) 添加。旧隔离测试也可以给第二个 Bot 加 `--notify-only`，让它只发送通知；这属于测试脚本的默认设置。不要手改既有签名任务的所有者绑定，旧客户端需要统一升级后再采用多 Agent 所有权。
 
 ## 安装当前 Codex 的 Skill 和 MCP
 
@@ -129,13 +131,13 @@ export PATH="$HOME/.cache/codex-runtimes/codex-primary-runtime/dependencies/node
 2. 当前 Codex 在自己的工作区完成 frontend，运行可信测试。
 3. 在目标仓库创建并 push `codex/*` 分支。
 4. `read_task` 获取最新 `seq`，调用 `handoff_task`，传完整 commit SHA、分支、测试证据和下一步摘要。
-5. Bob Runner 看到 `waiting` 状态，按 route 顺序和 lease 规则自动认领并创建新 Codex 会话。
+5. v3 必须审核的职责先进入 `stage_review`，由通知中的指定真人通过后才进入 `waiting`；关闭中间审核或 v2 时直接交接。Bob Runner 看到 `waiting` 状态，按 route 顺序和 lease 规则自动认领并创建新 Codex 会话。
 6. Bob 完成后若还有阶段继续 handoff；最后阶段调用 `request_review`。
-7. Alice 真人用自己的机器人或 CLI `review approved` 后再 `complete`。
+7. 最终指定审核人用自己的机器人或 CLI `review approved R-<seq>` 审核，再由管理员 `complete`。v2 最终审核人仍为管理员。
 
 ### B. 两个桌面对话手动接力
 
-给两个 agent 私有配置设置 `auto_execute: false`，Runner 仍可连接不同 Bot 中继通知，但不认领/执行代码。MCP 用 `get_identity` 确认本对话身份。Alice 创建 `desktop` 任务，push 后 handoff；Bob 在第二个项目对话读取最新任务，用 `claim_desktop_task(task_id, expected_seq)` 原子保留下一阶段，随后从准确 checkpoint SHA 创建自己的分支，完成并 `request_review`。
+给两个 agent 私有配置设置 `auto_execute: false`，Runner 仍可连接不同 Bot 中继通知，但不认领/执行代码。MCP 用 `get_identity` 确认本对话身份。Alice 创建 `desktop` 任务，push 后 handoff（v3 必须审核时先由真人通过）；Bob 在第二个项目对话读取最新任务，用 `claim_desktop_task(task_id, expected_seq)` 原子保留下一阶段，随后从准确 checkpoint SHA 创建自己的分支，完成并 `request_review`。
 
 桌面手动认领仅接受等待中的 `desktop` 工作流；遵循路由、候选顺序和并发容量。保留成功后状态为 `desktop`、assignee 为 Bob，不再由 Runner 自动认领。**此保留没有执行 lease，也没有下线自动候补**；需要真人继续对话，或管理员取消后创建新任务。若需要 lease/自动候补，使用自动 Runner 模式。
 
@@ -146,11 +148,12 @@ export PATH="$HOME/.cache/codex-runtimes/codex-primary-runtime/dependencies/node
 ```text
 @机器人 协作 创建 [frontend>backend] 增加登录页 | npm test 通过;登录页可访问
 @机器人 协作 状态 T-...
-@机器人 协作 审核 T-... 通过
+@审核人自己的机器人 协作 审核 T-... R-7 通过
+@审核人自己的机器人 协作 审核 T-... R-7 退回 | 修改意见
 @机器人 协作 完成 T-...
 ```
 
-群创建的任务是 `automatic`，两个接收方配置必须允许 `auto_execute`（默认开启；`false` 会禁用执行）。`commands_enabled=false` 只禁用 Bot 群命令入口，不禁用 Runner 执行。任务会按 `team.json` 的 route 自动分配，不需要手工 @ Bob 的机器人。候补规则是：首选 agent 在 claim timeout 内没有成功认领，或租约到期/运行失败，就由下一位候选人接管；所有候选失败后任务进入 `blocked`。管理员可发：
+本节默认底层 SDK 配置，群创建的任务是 `automatic`；网页向导的 `desktop_poll` 则由绑定的已有对话轮询。SDK 配置中，两个接收方配置必须允许 `auto_execute`（默认开启；`false` 会禁用执行）。`commands_enabled=false` 只禁用 Bot 群命令入口，不禁用 Runner 执行。任务会按 `team.json` 的 route 自动分配，不需要手工 @ Bob 的机器人。候补规则是：首选 agent 在 claim timeout 内没有成功认领，或租约到期/运行失败，就由下一位候选人接管；所有候选失败后任务进入 `blocked`。管理员可发：
 
 ```text
 @机器人 协作 重试 T-... 修复测试环境后重新执行
@@ -161,11 +164,14 @@ export PATH="$HOME/.cache/codex-runtimes/codex-primary-runtime/dependencies/node
 ```sh
 pnpm peer list /abs/private/alice-peer.json
 pnpm peer read /abs/private/alice-peer.json T-...
-pnpm peer review /abs/private/alice-peer.json T-... approved
+pnpm peer review /abs/private/reviewer-peer.json T-... approved R-7
+pnpm peer review /abs/private/reviewer-peer.json T-... changes_requested R-7 '请补充键盘操作和测试'
 pnpm peer complete /abs/private/alice-peer.json T-...
 pnpm peer reopen /abs/private/alice-peer.json T-... '修复测试环境后重试'
 ```
 
+v3 审核需要最新审核通知中的 R-版本号，退回必须附修改意见；旧 v2 任务仍兼容省略版本号。阶段审核规则、owner 回落和新旧任务策略见 [团队登记协议](team-registry.md)。
+
 `probe` 通过新建临时只读 SDK 会话向当前 provider 发一条极小请求（会产生一次模型调用），不连接机器人或写任务账本；结果保存在私有 `provider-probe.json`。例如 `pnpm peer probe /abs/private/bob-peer.json`。
 
 `doctor` 只检查本地配置和 Git 访问，不会把 Secret 打印出来；真实企业微信认证仍需看 Runner 私有日志中的 `Peer WeCom authenticated`。

package/docs/protocol.md

@@ -1,5 +1,7 @@
 # Task protocol v1 (draft)
 
+This is the legacy central-service protocol. Peer task v2 is documented in `peer.md` / `desktop-poll.md`, with signed enrollment v1 in `team-registry.md`.
+
 ## Location
 
 For each target repository, store `.agent-collab/tasks/<task-id>/spec.json` and `.agent-collab/tasks/<task-id>/events/<zero-padded-sequence>-<event-id>.json` on the dedicated `agent-collab` branch. Examples: `000001-evt-created.json`. The `main` branch keeps the versioned protocol docs and Skill. Do not merge `agent-collab` into `main`; code changes travel through separate feature branches and PRs.