xuym-codex-collab 0.4.0 → 0.4.1

package/docs/onboarding.md

@@ -5,7 +5,7 @@
 ## 每个人先准备一次
 
 1. 安装 Node.js 20+、Git 和支持对话 heartbeat 的 Codex 桌面应用。
-2. clone 要协作的业务仓库。仓库需有 `origin/main`，本机 Git 凭据能读取并 push `agent-collab` 及任务代码分支。
+2. 确认业务仓库已有远程 `main` 分支，本机 Git 凭据能读取并 push `agent-collab` 及任务代码分支。已有独立 clone 可以直接使用；没有 clone 时让向导从 Git 地址拉取。
 3. 打开终端执行：
 
 ```sh
@@ -13,38 +13,44 @@ npm install --global xuym-codex-collab
 codex-collab setup
 ```
 
-网页自动打开；若未打开，执行 `codex-collab setup --no-open`，复制终端打印的本机链接。保留此终端以使用工作台。团队成员只需 clone 业务仓库，无需 clone 工具仓库。
+网页自动打开；若未打开，执行 `codex-collab setup --no-open`，复制终端打印的本机链接。保留此终端以使用工作台。团队成员无需 clone 工具仓库。也可执行 `npx xuym-codex-collab@latest setup` 直接打开向导。
 
 同一台电脑模拟两位成员时，使用同一业务仓库的两个独立 clone、两个机器人、两个 Codex 对话；同一个 clone 只能接入一个身份。同一个企业微信账号可以拥有多个 Agent，每个 Agent 的机器人、签名身份、clone 和对话独立。真正同事使用自己的企业微信账号和 Git 凭据。
 
 ## 管理员操作
 
-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 对话启用。
+1. 在企业微信创建独立智能机器人，获取 Bot ID 和 Secret，拉进协作群。为每位成员分别创建机器人并加入同一个群；真人同事也加入群。
+2. 工作台选择“初始化团队”。填写团队名称，选择本机项目目录或 Git 地址与新目录。点击“检查项目并推荐验证命令”，确认或修改推荐命令，例如 `npm test`、`go test ./...` 或 `sh test.sh`。检查只读取常见测试入口，不执行项目脚本；实际任务使用确认后的固定程序与参数，不支持管道或命令拼接。
+3. 填写自己的显示名称、选择主要职责，输入自己的 Bot ID/Secret。名称可以是 `Alice` 或“张三”；内部 Agent ID 自动生成，自定义身份和标签可在折叠选项中调整。点击“创建团队并连接机器人”。
+4. 用自己的企业微信账号 @ 此机器人，发送页面显示的 `协作 接入 六位数字`。页面自动发现群 `chatid` 与本人 `userid`，创建身份、签名账本，配置项目 MCP/Skill 并启动本机机器人 Runner；无需再点击继续。群验证中刷新页面可以恢复进度。
+5. 项目页面“批量分配机器人给同事”：每行填写显示名称、选择职责、填写独立机器人的 Bot ID/Secret，点击“增加一位成员／机器人”添加更多行。默认设为该职责的首选执行者并允许所有者群命令；候补与自定义 ID/职责在折叠选项中调整。一次最多 25 行。
+6. 点击“生成全部接入包”。密码自动生成；在“已分配的机器人”逐个下载加密 JSON 文件、查看并复制接入说明。把文件和说明交给指定成员，密码通过另一条可信渠道单独发送。说明不包含密码或 Secret。包默认 7 天有效，同一成员或机器人不会同时分发多个有效邀请；重复 ID/Bot 的批次会在发布前拒绝。
+7. 成员群验证后，“待确认的成员”自动出现申请。核对内部 Agent ID、职责和 userid，明确点击“确认此成员入队”。成员页面自动等待批准并继续配置；批准不会由向导替你做。新的签名策略通过 Git 同步到其他在线成员。
+8. 管理员也按下文把自己的 Codex 对话启用。需要调整审核人时，展开“团队分工、审核与通知设置”，默认阶段审核由执行 Agent 的本人处理；可选管理员或已验证身份的同事。
 
-同一位同事可以领取多份接入包，用同一个企业微信账号分别验证不同机器人；每份包选择独立 clone，并绑定不同 Codex 对话，不需要关闭群命令权限。
+同一位同事可以领取多行分配，用同一个企业微信账号分别验证不同机器人；每份包选择独立 clone，并绑定不同 Codex 对话，不需要关闭群命令权限。
 
-真人同事和机器人都应加入协作群。每位真人通过自己的企业微信账号验证接入，以便工具核对审核权限；额外通知对象不会因此获得审核权限。
+显示名称保存在本机和加密接入包中；团队签名和群协议仍用内部 Agent ID。真人通过自己的企业微信账号验证接入，以便核对审核权限；额外通知对象不会因此获得审核权限。
 
-机器人必须由一个本机 Runner 保持连接。同一个 Bot ID 不要同时运行旧服务、群发现命令和新 Runner。向导会检查可识别的本机重复连接；其他电脑上的连接需由团队自己核实。
+机器人必须由一个本机 Runner 保持连接。同一个 Bot ID 不要同时运行旧服务、群发现命令和新 Runner。向导检查可识别的本机重复连接；其他电脑上的连接需由团队核实。
 
 ## 成员操作
 
-1. 从管理员取得自己的加密接入包和密码，先 clone 对应业务仓库。
-2. 打开 `codex-collab setup`，选择“加入团队”。选择接入包文件、输入密码和业务仓库目录，点击“导入并连接机器人”。工具会核对 origin 仓库；允许同一 remote 的 SSH/HTTPS 表达，不会改写 origin。
-3. 用**自己的企业微信账号** @ 分配给你的机器人，发送页面显示的验证码；回网页点击“已发送，继续检查”。本机生成签名身份，并把带公钥的入队申请写进协作分支。
-4. 等管理员在自己的工作台确认，然后在项目页点击“继续接入”。工具检查 Git 权限、写入项目的本地 MCP 和 Skill、启动机器人连接。
-5. 在 Codex 打开这个业务项目，信任项目并加载 MCP。工作台点击“复制启用指令”，粘贴到要代表你的**已有对话**，让对话完成身份核对、绑定真实 thread ID、创建 heartbeat 和首次无任务轮询。
-6. 回工作台刷新状态，确认机器人认证、对话绑定、实际轮询均已观察到。
+1. 从管理员取得自己的加密接入包、接入说明和单独发送的密码，打开 `codex-collab setup` 或 `npx xuym-codex-collab@latest setup`，选择“加入团队”。
+2. 选择接入包文件、输入密码。可以点击“读取接入信息”查看团队、Agent、职责、仓库和建议目录。默认“帮我拉取到新目录”，可修改保存路径；也可切换“使用本机已有项目”。点击“接入我的机器人”。工具先验证接入包再 clone，使用本机 Git 登录；已有项目必须属于包内同一 remote，支持同一仓库的 SSH/HTTPS 表达。
+3. 用**自己的企业微信账号** @ 分配给你的机器人，发送页面验证码。页面自动生成签名身份，把带公钥的入队申请写进协作分支，并进入等待批准；无需返回点击确认。刷新页面可以恢复当前验证或申请进度。
+4. 管理员明确批准后，页面自动检查 Git 权限、写入项目本地 MCP 和 Skill、启动机器人连接。正常流程无需点击“继续接入”；Git/配置异常时会停在可恢复的步骤，处理后再明确重试。
+5. 在 Codex 打开页面上的业务项目，信任项目并加载 MCP/Skill。点击“复制启用指令”，粘贴到要代表你的**已有对话**，例如：
 
-启用指令不是 Secret。成员无需手工编辑 JSON、生成密钥或复制 userid。Codex 若没有暴露真实对话 ID，仍需本人提供该对话 ID/链接；工具不会猜测或访问应用私有数据库。若应用不支持 heartbeat，页面的启用指令会要求明确报告限制，不能当作已自动接单。
+```text
+使用 $team-collab-desktop，启用当前项目的团队协作，将 bob 机器人绑定到当前对话。项目：项目绝对路径
+```
+
+6. Skill 完成身份核对、绑定真实 thread ID、复用或创建该对话的 heartbeat，并立即做一次轮询。工作台自动更新状态；展开“连接检查详情”确认机器人认证、对话绑定和实际轮询。
 
-向导看到一次或近期轮询，只证明 MCP 实际被调用过，不代表已读取到应用自动化的开关。完成绑定后也应在当前对话核对 heartbeat 是否启用。默认指令尝试一分钟；周期以应用工具实际接受并运行的结果为准。
+启用指令不是 Secret。成员无需手工编辑 JSON、生成密钥或复制 userid；无法识别 Skill 时可展开详细指令作为备用。Codex 若没有暴露真实对话 ID，仍需本人提供该对话 ID/链接；工具不会猜测或访问应用私有数据库。若应用不支持 heartbeat，Skill 会明确说明尚未启用自动轮询，不能仅凭已绑定就认定能接单。
+
+工作台后台检查只在页面打开时推进向导进度；已经启动的 Runner 和已启用的对话 heartbeat 独立运行。关闭工作台后重新打开，可以从首页继续，不需要重建成员身份。
 
 ## 已有 Alice/Bob 配置如何迁移
 
@@ -87,7 +93,7 @@ codex-collab setup
 
 群通知会列出真人姓名对应的成员名称，并尝试带上已验证 userid 的提及。智能机器人长连接原生 @ 是否实际弹出提醒需要实群检查；加密 userid 转明文需要另接企业应用，目前没有集成。请同时检查群通知正文，不能仅以是否收到 @ 提醒判断任务是否在等待审核。
 
-群里“任务已创建”和“机器人已认证”不能代替 Codex 已接单证据。最终任务不会自动批准或合并 `main`；管理员需要检查代码、真实测试证据再决定如何合并。消息中的 `npm test 通过` 是验收描述，真正运行的是管理员在本机初始化时固定的 JSON argv。
+群里“任务已创建”和“机器人已认证”不能代替 Codex 已接单证据。最终任务不会自动批准或合并 `main`；管理员需要检查代码、真实测试证据再决定如何合并。消息中的 `npm test 通过` 是验收描述，真正运行的是管理员确认并固定的程序与参数（内部存为 argv）。
 
 ## 一个人使用多个机器人，或模拟两个同事
 
@@ -96,7 +102,7 @@ codex-collab setup
 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 的管理员角色。
+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 完成任务。以每次通知指定的审核身份和版本号为准。
 
@@ -114,8 +120,9 @@ codex-collab setup
 
 - 重复导入同一接入包：已验证或已接入的成员会直接打开原项目，继续原进度；不会重复启动群验证。
 - 项目接单状态：同时检查 MCP、Skill、认证连接、目标对话绑定和最近三分钟内实际轮询。配置文件存在不等于 Codex 已加载，自动化启用状态仍需在绑定对话确认。
-- 群验证断线/过期：点击“重新连接”，使用新的验证码。
-- Git/MCP 配置中断：从“我的项目”打开原项目，再点击“继续接入”；不要反复创建另一身份。
+- 群验证断线/过期：点击“重新连接”，使用新的验证码。接入进度保存于本机，页面刷新能恢复原验证码；工作台进程重启后临时连接失效，会重新连接。
+- 管理员群验证尚未完成：从首页“待完成群验证”打开“继续创建团队”，恢复保存的创建资料。
+- Git/MCP 配置中断：从“我的项目”打开原项目，若显示错误，处理后点击“继续接入”；不要反复创建另一身份。
 - 管理员生成邀请时网络失败：回项目页面刷新已生成接入包，再下载；本人机器人点击“继续接入我的机器人”。工具重试发布同一签名邀请。
 - 本机工作台关闭：重新运行 `codex-collab setup`；已启动的机器人 Runner 会继续运行。
 - 页面“停止机器人连接”只断开群机器人。暂停接单需在对应 Codex 对话暂停 heartbeat；已有任务仍需完成、报告失败或按租约恢复处理。
@@ -133,3 +140,19 @@ Secret 若曾发到聊天或 Git，应在企业微信重新生成后更新本机
 旧命令兼容：`codex-collab setup --terminal` 或 `setup --role admin|member` 继续使用 [旧终端工作流](terminal-onboarding.md)，不走加密包与动态签名入队。
 
 网页向导的逐项覆盖、故障恢复与功能遗漏见 [功能检查与测试记录](onboarding-audit.md)。
+
+## 管理、重绑与移除本机接入
+
+在“我的项目”打开一个 Agent，展开“管理与重置”。所有操作先预览当前 Agent、clone、对话 ID 和影响，再输入当前 Agent 名称确认。重新绑定或移除时先在原对话暂停协作 heartbeat；网页无法控制 Codex 应用自动化，也不会删除聊天。
+
+**重新绑定对话**保留成员私钥和机器人配置，停止 Runner 并清除本机对话绑定及轮询观察状态。复制项目页面的启用指令到目标对话，完成绑定后启动连接。旧对话的轮询因绑定失效无法再领取任务。
+
+**更新机器人凭据**只修改当前 Bot ID 的 Secret。点击“验证新凭据”后，向导先停止原连接，再临时连接机器人；用原绑定本人账号在原协作群发送验证码。验证和确认成功后同步当前 Runner/MCP 实际使用的私有配置，并保留对话绑定。点击“启动机器人连接”恢复。取消验证会关闭临时连接，原配置不变，Runner 不会自动重启。
+
+**移除本机接入**用于当前 clone 重新接入或换身份。清除对话绑定、停用旧私有配置，仅移除可识别的生成 MCP 区块与 Skill，保留其他配置和业务文件。未完成接入的项目也可移除。首页“已移除的接入”可以恢复原成员身份；已绑定其他身份的 clone 会阻止恢复，避免覆盖新接入。恢复不会恢复旧对话绑定或启动 Runner。
+
+如果要换平台机器人、群或成员本人，先移除本机接入，再由管理员提供正确的新 Agent 接入包并按加入流程验证。移除不会撤销团队签名策略中的旧成员，管理员应另行管理分工；同一 Agent 不能通过重新初始化获得另一个已批准私钥。
+
+重置预览有效期为十分钟。绑定、任务或文件变化后需重新预览；空闲轮询不会影响新 Secret 的群验证。当前 Agent 有有效任务租约时会拒绝重置，需先结束本阶段或在原对话报告失败；Git 无法访问时也不强行清理。自定义 Skill、自定义 MCP、Git 已跟踪或符号链接文件会阻止自动移除。
+
+操作前的私有备份位于向导配置目录的 `reset-backups/`，完成提示会显示完整路径。它可能包含私钥、旧 Secret 与本机任务信息，权限为 `0600`；目录权限为 `0700`，不要分享或提交。业务代码、共享任务分支、未提交改动和任务 worktree 保留。页面“移除”提供可恢复的解绑，并非清除所有私人数据；不再需要恢复时按本机配置路径自行清理备份与旧身份。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xuym-codex-collab",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Git-backed collaboration tools for Codex teams, with MCP, WeCom, and local runners.",
   "repository": {
     "type": "git",

package/packages/codex-kit/templates/.agents/skills/team-collab-desktop/SKILL.md

@@ -7,11 +7,12 @@ description: Execute Git-backed collaboration stages in this bound Codex desktop
 
 ## Binding once in the intended conversation
 
-- Use this project's MCP `get_identity`; it must match the colleague this conversation represents. Never use another identity's visible MCP.
+- A request such as ‘启用当前项目协作，将机器人绑定到当前对话’ starts this binding workflow. Read the current project's generated `.codex/config.toml` to identify its `team-collab-<agent_id>` entry and private config path. Do not display secrets or modify unrelated configuration. Use that MCP's `get_identity`; verify the agent ID, project path and `execution_mode=desktop_poll`. If the project MCP is missing or stale, tell the user to trust the project and reload its MCP before continuing.
 - Obtain the actual current Codex conversation ID using a supported app context or the current shell's `CODEX_THREAD_ID` if exposed. If unavailable, ask the user for the target thread's copied ID/link. Do not guess an ID or scrape/modify app session databases.
 - Call `bind_desktop_thread(thread_id)` once. Binding is local client routing, not app-attested caller authentication. Other conversations with access to the same local credentials are not a security boundary.
-- Create a recurring **heartbeat attached to this existing conversation** using the app's automation tool. Use its supported minimum/selected interval (start with every minute when accepted). Do not create standalone cron/new SDK threads as a substitute. Keep the bound identity and thread ID in the saved prompt. Reuse/update this conversation’s existing collaboration heartbeat when present; avoid duplicate automations.
+- Inspect existing collaboration automations first. Create or update a recurring **heartbeat attached to this existing conversation** using the app's automation tool. Use its supported minimum/selected interval (start with every minute when accepted). Do not create standalone cron/new SDK threads as a substitute or modify unrelated automations or provider settings. Save a prompt containing the verified agent ID, actual bound thread ID, and absolute path to this Skill. The prompt must instruct each run to verify identity, poll, handle natural-language requests or the assigned stage according to this Skill, renew leases and report results; remain quiet when nothing actionable changes. Reuse this conversation's collaboration heartbeat to avoid duplicates.
 - If the automation tool/interval is unavailable, report that binding alone does not wake this conversation; do not claim automatic execution is enabled.
+- After configuring the heartbeat, immediately call `poll_desktop_task` with the verified thread ID and handle any returned work using the workflow below. Do not invent a test task. Report the verified agent ID, thread ID, heartbeat status and actual polling result so the local wizard can observe readiness.
 
 ## On each heartbeat
 

package/scripts/peer/refresh-project.mjs

@@ -6,7 +6,7 @@ import { readPeerConfig } from '../../apps/peer/runtime.mjs';
 import { git } from '../../packages/peer/store.mjs';
 import { bindingPrompt } from './setup-desktop-project.mjs';
 const root = fileURLToPath(new URL('../../', import.meta.url));
-const legacyHashes = new Set(['f98ad425e2ea3c8ab6fb86febef7d9cb288029ef55bea6937dda6de8b467fece']);
+const legacyHashes = new Set(['6e4d1ea6a644fb3078c541e40bcc9e8bf5069462994152f3ec2fc3aa5fedd5fa', 'f98ad425e2ea3c8ab6fb86febef7d9cb288029ef55bea6937dda6de8b467fece']);
 const hash = (value) => createHash('sha256').update(value).digest('hex');
 const inside = (parent, child) => { const path = relative(parent, child); return !path || path !== '..' && !path.startsWith('../') && !isAbsolute(path); };
 async function plainPath(base, path) {

package/scripts/peer/setup-desktop-project.mjs

@@ -8,6 +8,9 @@ const absent = async (path) => { try { await stat(path); return false; } catch (
 const readOptional = async (path) => { try { return await readFile(path, 'utf8'); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } };
 
 export function bindingPrompt(agentId, repo) {
+  return `使用 $team-collab-desktop，启用当前项目的团队协作，将 ${agentId} 机器人绑定到当前对话。项目：${repo}`;
+}
+export function detailedBindingPrompt(agentId, repo) {
   return `请把当前已有 Codex 对话设为 ${agentId} 的企微协作执行对话，不要新建独立执行线程。\n项目：${repo}\n读取 ${join(repo, '.agents/skills/team-collab-desktop/SKILL.md')}。\n1. 用本项目 MCP 的 get_identity 确认身份是 ${agentId}，execution_mode 是 desktop_poll；若不匹配，停止并提示重新加载 MCP。\n2. 获取当前真实对话 ID：优先使用已提供的应用上下文，或当前终端 CODEX_THREAD_ID（如果存在）；不可猜 ID 或读取/修改应用数据库。没有可用 ID 时请让我复制当前对话 ID/链接。\n3. 调用 bind_desktop_thread 绑定当前真实对话，然后用应用 automation_update 工具在当前已有对话创建一个 heartbeat：每分钟检查（仅当工具接受该周期；否则说明限制），不要创建 cron、新对话或后台 SDK。先查现有 automation，避免重复；不要修改无关 automation 或 CC Switch。\n4. heartbeat 的保存提示词必须包含 ${agentId}、当前真实 thread_id 和该 skill 路径；每次 get_identity → poll_desktop_task。job=null 且 requests 为空 时保持安静；有任务就只在本对话和返回的隔离 worktree 执行本阶段，主动续租、测试、明确提交，然后 finish_desktop_task；失败时按 skill 处理。requests 非空时按 Skill 理解群消息，调用 resolve_desktop_request 创建任务、追问或回答；使用 team_context 的现有路由、能力与默认分工，不能猜测不存在的同事。解决后再次 poll 开始工作。自然语言“通过／完成”不能代替人工审核命令。复用或更新当前对话已有的协作 heartbeat，避免重复创建。禁止启动 SDK/CLI 代替当前对话。仅新任务、结果、失败或需我操作时通知。\n5. 创建完成后立即调用一次 poll_desktop_task 验证，无任务应正常返回，不要创建测试任务。告诉我绑定身份、对话 ID 和 heartbeat 状态；若工具不可用明确说明未启用自动轮询。\n`;
 }