xuym-codex-collab 0.3.1 → 0.4.1

package/README.md

@@ -4,24 +4,32 @@
 
 ## 安装与入口
 
-需要 Node.js 20+、Git、Codex 桌面应用，以及业务仓库的读取和 push 权限。先 clone 业务仓库；成员无需 clone 本工具源码。
+需要 Node.js 20+、Git、Codex 桌面应用，以及业务仓库的读取和 push 权限。业务仓库需已有 `main` 分支；可以使用独立的本机 clone，也可以让向导拉取新目录。成员无需 clone 本工具源码。
 
 ```sh
 npm install --global xuym-codex-collab
 codex-collab setup
 ```
 
-`setup` 打开本机网页工作台，所有接入操作集中在一个页面。管理员选择“初始化团队”，成员选择“加入团队”；已在使用旧配置的成员选择“导入已有配置”。终端保持运行即可继续使用工作台，关闭工作台后已启动的机器人连接仍运行。
+`setup` 打开本机网页工作台，所有接入操作集中在一个页面。管理员选择“初始化团队”，成员选择“加入团队”；群身份验证、等待审批和本机配置会自动衔接，页面显示当前进度。已在使用旧配置的成员选择“导入已有配置”。终端保持运行即可继续使用工作台，关闭工作台后已启动的机器人连接仍运行。
 
 | 谁 | 在工作台做什么 | 接入后需要保留什么 |
 | --- | --- | --- |
-| 管理员 | 初始化业务仓库；在群里验证自己；分配各成员机器人与职责；下载加密接入包；确认成员申请；按职责设置真人审核规则 | 本机身份、管理员配置和机器人连接 |
-| 成员 | 导入个人接入包与密码；选择自己的业务仓库 clone；在群里发送验证码；等待管理员确认；复制启用指令到选定 Codex 对话 | 本机机器人连接，以及该对话的轮询自动化 |
+| 管理员 | 选择或拉取项目，确认推荐的验证命令；在群里验证自己；批量分配机器人与职责；下载加密接入包并复制接入说明；确认自动出现的成员申请 | 本机身份、管理员配置和机器人连接 |
+| 成员 | 导入接入包与密码，使用已有 clone 或让向导拉取；在群里发送验证码；审批通过后自动配置；将一条启用指令发送到选定 Codex 对话 | 本机机器人连接，以及该对话的轮询自动化 |
 
-管理员先在企业微信创建**独立智能机器人**并加入协作群，再填写 Bot ID/Secret。工具通过群验证码发现群 `chatid` 和真人 `userid`，不需要成员手工寻找这些 ID、生成密钥或编辑 JSON。机器人 Secret 通过加密接入包交给指定成员，密码单独传递。
+管理员先在企业微信创建**独立智能机器人**并加入协作群，再填写 Bot ID/Secret。工具通过群验证码发现群 `chatid` 和真人 `userid`，不需要成员手工寻找这些 ID、生成密钥或编辑 JSON。机器人 Secret 通过加密接入包交给指定成员；批量分配自动生成密码，可在“已分配的机器人”查看并单独复制。接入说明不含密码和 Secret。显示名称支持中文，职责可从前端、后端、全栈、测试等预设中选择；内部 ID 和自定义标签放在高级选项中。
 
 同一个真人可以拥有多个 Agent，每个 Agent 使用独立机器人、签名身份、业务 clone 和 Codex 对话。管理员在项目页点击“给自己增加机器人”，验证同一个企业微信账号后自动接入，无需下载包或填写包密码；给同事分配时仍使用加密接入包，同事可以领取多份。相同 userid 不会合并 Agent 权限，审核通知会指明应使用的机器人。
 
+本机配置完成后，向导只要求在目标 Codex 对话发送一条指令，例如：
+
+```text
+使用 $team-collab-desktop，启用当前项目的团队协作，将 bob 机器人绑定到当前对话。项目：项目绝对路径
+```
+
+Skill 完成身份核对、对话绑定和 heartbeat 配置，页面自动观察实际轮询。管理员入队批准和选定对话启用仍由本人明确操作。群验证中刷新可恢复原进度；重启工作台后可从首页继续，失效验证码会重新连接。
+
 完整步骤与旧配置迁移见 [团队接入指南](docs/onboarding.md)。
 
 ## 一次任务如何接力
@@ -34,9 +42,12 @@ sequenceDiagram
   participant R as 阶段审核人
   participant G as 业务仓库 agent-collab
   participant B as Bob 已有 Codex 对话
-  H->>A: @Alice 协作 创建 [frontend>backend] ...
-  A->>G: 签名任务与能力路由
-  C->>G: heartbeat 轮询并原子认领
+  H->>A: @Alice 用自然语言描述需求与分工
+  A->>G: 签名保存原始需求
+  C->>G: heartbeat 读取需求与团队职责
+  C->>G: 理解或追问，原子创建结构化任务
+  A->>H: 需求与分工确认，或补充问题
+  C->>G: 轮询并原子认领
   C->>G: 代码 commit、测试证据、阶段总结
   A->>H: 阶段结果、代码证据与审核命令
   H->>R: 通知本人审核
@@ -49,10 +60,17 @@ sequenceDiagram
 例如在群里选中实际 Alice 机器人发送：
 
 ```text
-@Alice 协作 创建 [frontend>backend] 给登录页增加密码显示切换 | npm test 通过
+@Alice 给登录页增加密码显示切换，原有登录行为保持不变。
+你负责前端实现，Bob 补接口和测试，完成后在群里告诉我。
 ```
 
-Alice 的绑定对话轮询到任务后在隔离 worktree 执行前端阶段，提交代码、运行固定验证命令、写入总结；群里收到分支、提交 SHA、测试结果和审核命令。默认由实际执行者本人审核，通过后才开放 Bob 的后端阶段。退回时必须填写修改意见，当前阶段从被退回的提交继续修改，重新提交后再次审核。管理员可在工作台按职责选择审核人、额外通知对象，或关闭中间阶段审核。候补从 Git 签名事件和租约判断，机器人 @ 消息本身不负责调度。群消息中的验收文字不会替换管理员设置的本机测试 argv。
+机器人先回复收到需求；Alice 的绑定对话下一次轮询时理解需求，按已配置的职责生成任务、验收条件和分工，并在群里确认。需求不清楚时先追问，直接 @同一个机器人补充即可；有多条追问时带上通知中的 `N-需求ID`。状态问题或闲聊可以只回复，不创建任务。
+
+自然语言入口使用 `desktop_poll`，沿用本人身份和群权限。对话从团队路由选择职责，指定的同事不存在或分工不明确时需要追问；机器人显示名不决定调度。旧的 `协作 创建 ...` 命令仍兼容。
+
+Alice 的绑定对话认领后在隔离 worktree 执行前端阶段，提交代码、运行固定验证命令、写入总结；群里收到分支、提交 SHA、测试结果和审核命令。默认由实际执行者本人审核，通过后才开放 Bob 的后端阶段。退回时必须填写修改意见，当前阶段从被退回的提交继续修改，重新提交后再次审核。管理员可在工作台按职责选择审核人、额外通知对象，或关闭中间阶段审核。候补从 Git 签名事件和租约判断，机器人 @ 消息本身不负责调度。群消息中的验收文字不会替换管理员设置的本机测试 argv。
+
+自然语言“通过”或“完成”不会批准任务；真人审核仍复制通知中的明确命令。已有安装须同时更新工具、项目 Skill、MCP 和原对话的 heartbeat 提示词，步骤见 [已有项目升级](docs/desktop-poll.md#已有项目启用自然语言入口)。
 
 代码保存在独立 `codex/*` 分支；任务和签名策略保存在 `agent-collab`，两者不自动合并到 `main`。最后阶段始终等待真人审核，审核通过后由管理员完成任务。
 
@@ -73,10 +91,20 @@ Alice 的绑定对话轮询到任务后在隔离 worktree 执行前端阶段，
 
 工作台分别检查项目 MCP/Skill 配置、企微认证、目标对话绑定和实际轮询。机器人认证成功只能说明连接可用；还需要对话真实轮询才能执行任务。MCP 本身不能唤醒闲置对话，“启用指令”会要求在**当前选定对话**建立 heartbeat，应用需支持并运行该自动化。
 
-成员私钥在成员本机生成。Git 记录公钥、成员职责、签名邀请/申请、任务事件、代码引用、测试和阶段总结；Secret、对话 ID、运行令牌及聊天全文留在本机。团队新增成员或修改审核规则后会发布新的签名策略版本；旧任务继续遵循创建时的策略，避免改写已运行任务的权限和候补。
+成员私钥在成员本机生成。Git 记录公钥、成员职责、签名邀请/申请、原始群需求与解读结果、任务事件、代码引用、测试和阶段总结；Secret、对话 ID、运行令牌及完整私有 Codex 对话留在本机。团队新增成员或修改审核规则后会发布新的签名策略版本；旧任务继续遵循创建时的策略，避免改写已运行任务的权限和候补。
 
 停止工作台或机器人连接不会自动暂停 Codex heartbeat；需要暂停协作时，应在对应对话暂停自动化，并检查在执行任务的状态。
 
+项目页面展开 **管理与重置**，可以先查看影响，再选择：
+
+- **重新绑定对话**：先在原对话暂停协作 heartbeat，输入当前 Agent 名称确认。向导停止本机机器人连接、解除对话绑定，并提供启用指令；将指令发到目标对话，完成绑定后点击“启动机器人连接”。
+- **更新机器人凭据**：填写同一个 Bot ID 的新 Secret，用原企业微信本人账号在原群完成验证码验证，确认后保存。保留成员身份、群和对话绑定，机器人保持停止，点击“启动机器人连接”恢复。
+- **移除本机接入**：停止本机连接、解除绑定，移除当前 clone 生成的协作 MCP 和 Skill，停用旧私有配置。原成员身份和本机工作目录保留，项目出现在首页“已移除的接入”，可恢复原身份；此 clone 也可以导入其他 Agent 的新接入包。
+
+有运行中任务时会阻止重置；无法同步 Git 确认任务状态时也会停止操作。自定义、已跟踪或符号链接配置需要手动处理。操作前写入本机私有恢复记录，项目代码、其他 MCP、模型配置与共享 `agent-collab` 记录不受影响。恢复后重新加载项目 MCP、绑定对话并启动连接；若 clone 已接入另一个身份，需先处理当前接入。
+
+这里移除的是本机接入，企业微信平台机器人、团队成员和群中的历史消息仍保留。身份、Secret 的旧版本及恢复记录仅留在本机；不需要恢复时可手动清理工作台显示的私有配置与备份。更换平台机器人或真人所有者，使用管理员提供的新接入包重新验证。
+
 ## 开发与兼容
 
 ```sh
@@ -94,3 +122,7 @@ node bin/codex-collab.mjs setup
 - [旧中心服务与飞书接入](docs/legacy-center.md)
 
 2026-10-10 已由用户验证本机真实企业微信群 + Alice/Bob 两个已有 Codex 对话的接力闭环。网页向导与真人审核闭环通过临时 Git 仓库、模拟机器人和实际浏览器操作验证；2026-10-12 这轮测试没有连接真实机器人，原生 @ 尚未验证。跨两台机器的部署尚未验证。
+
+2026-10-13 自然语言入口通过全量 **122 项自动测试**，覆盖签名需求、追问补充、并发去重、绑定对话 MCP、Alice/Bob 固定 SHA 接力和通知重试；Skill 与 npm 打包检查通过。测试用固定解读结果模拟 Codex 的理解，没有调用真实模型或连接真实企业微信群；本轮自然语言实群验收仍待进行。
+
+2026-10-14 接入简化与管理重置通过全量 **154 项自动测试**、隔离仓库的实际浏览器接入流程、Skill 校验和 npm 打包检查。群验证后自动继续、成员批准后自动配置、批量机器人分配及刷新恢复均已验证；本轮使用模拟机器人，未新增真实企微或跨机器联合验收。具体范围见 [向导检查记录](docs/onboarding-audit.md)。

package/apps/onboarding/discovery.mjs

@@ -40,5 +40,9 @@ export class BotDiscovery {
     this.sessions.delete(id); clearTimeout(state.timer); state.client.disconnect();
     return { bot_id: state.bot_id, secret: state.secret, ...state.proof };
   }
+  cancel(id) {
+    const state = this.sessions.get(id); if (!state) return;
+    this.sessions.delete(id); clearTimeout(state.timer); state.client.disconnect();
+  }
   closeAll() { for (const state of this.sessions.values()) { clearTimeout(state.timer); state.client.disconnect(); } this.sessions.clear(); }
 }

package/apps/onboarding/guided.mjs

@@ -0,0 +1,105 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, readdir, realpath, rename, rm, rmdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { git } from '../../packages/peer/store.mjs';
+import { remoteIdentity } from './bundle.mjs';
+import { SetupError } from './errors.mjs';
+
+export const responsibilities = {
+  frontend: ['frontend'], backend: ['backend'], fullstack: ['frontend', 'backend'],
+  testing: ['testing'], docs: ['docs'], general: ['general'],
+};
+const idPattern = /^[a-zA-Z0-9_-]{1,64}$/;
+export function memberFields(input) {
+  if (input.display_name != null && typeof input.display_name !== 'string' || input.agent_id != null && typeof input.agent_id !== 'string') throw new SetupError('成员名称和内部 Agent ID 应是文字。');
+  const displayName = (input.display_name || input.agent_id || '').trim();
+  if (!displayName || displayName.length > 80 || /[\x00-\x1f\x7f]/.test(displayName)) throw new SetupError('请填写成员或机器人名称，最多 80 个字符。');
+  const agentId = input.agent_id?.trim() || displayName.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64) || `agent-${randomBytes(4).toString('hex')}`;
+  if (!idPattern.test(agentId)) throw new SetupError('内部 Agent ID 请使用英文、数字、下划线或连字符。');
+  const raw = input.capabilities || responsibilities[input.responsibility || 'general'];
+  const caps = typeof raw === 'string' ? raw.split(/[\s,，]+/).filter(Boolean) : raw;
+  if (!Array.isArray(caps) || !caps.length || caps.length > 16 || caps.some((cap) => typeof cap !== 'string' || !idPattern.test(cap))) throw new SetupError('自定义职责标签请使用英文、数字、下划线或连字符。');
+  return { agent_id: agentId, display_name: displayName, capabilities: [...new Set(caps)] };
+}
+
+// Convert a confirmed command to argv. Never add a shell or evaluate substitutions.
+export function commandArgv(command) {
+  if (typeof command !== 'string' || !command.trim() || command.length > 4000 || /[\x00\r\n]/.test(command)) throw new SetupError('请确认验证命令，例如 npm test 或 go test ./...。');
+  const argv = []; let word = '', quote = null, escaped = false, started = false;
+  for (const char of command.trim()) {
+    if (escaped) { word += char; escaped = false; started = true; continue; }
+    if (char === '\\' && quote !== "'") { escaped = true; started = true; continue; }
+    if (quote) { if (char === quote) quote = null; else word += char; continue; }
+    if (char === '"' || char === "'") { quote = char; started = true; continue; }
+    if (/\s/.test(char)) { if (started) { argv.push(word); word = ''; started = false; } continue; }
+    if (/[;&|<>`$()]/.test(char)) throw new SetupError('验证命令请填写一个程序及参数，不支持管道、重定向或命令拼接。多个检查请写进项目测试脚本。');
+    word += char; started = true;
+  }
+  if (quote || escaped) throw new SetupError('验证命令的引号或转义未闭合。');
+  if (started) argv.push(word);
+  if (!argv.length || argv.length > 32 || argv.some((part) => !part || part.length > 2000)) throw new SetupError('验证命令参数无效。');
+  return argv;
+}
+export function displayCommand(argv) {
+  return argv.map((part) => /^[\w./:@=-]+$/.test(part) ? part : `'${part.replaceAll("'", "'\\''")}'`).join(' ');
+}
+export async function recommendTests(repo) {
+  const files = new Set(await readdir(repo)); const commands = [];
+  if (files.has('test.sh')) commands.push(['sh', 'test.sh']);
+  if (files.has('package.json')) {
+    try { const value = JSON.parse(await readFile(join(repo, 'package.json'), 'utf8')); if (typeof value.scripts?.test === 'string' && value.scripts.test.trim()) commands.push(['npm', 'test']); } catch { /* A suggestion never executes or repairs project files. */ }
+  }
+  if (files.has('go.mod')) commands.push(['go', 'test', './...']);
+  if (files.has('Cargo.toml')) commands.push(['cargo', 'test']);
+  return commands.map((argv) => ({ argv, command: displayCommand(argv) }));
+}
+export function suggestedRepo(remote, agentId) {
+  const name = remote.split(/[/:]/).at(-1).replace(/\.git$/, '').replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 80) || 'project';
+  return join(homedir(), 'codex-projects', `${name}-${agentId}`);
+}
+function validCloneRemote(remote) {
+  if (typeof remote !== 'string' || !remote || remote.length > 4000 || /[\x00-\x1f\x7f]/.test(remote) || remote.startsWith('-')) throw new SetupError('仓库地址无效。');
+  if (isAbsolute(remote)) return;
+  if (/\s/.test(remote)) throw new SetupError('仓库地址不能包含空白字符。'); // Also supports a team's local/offline Git mirror.
+  if (/^[\w.-]+@[\w.-]+:[\w./-]+$/.test(remote)) return;
+  let url; try { url = new URL(remote); } catch { throw new SetupError('请使用 HTTPS 或 SSH 仓库地址。'); }
+  if (!['https:', 'http:', 'ssh:'].includes(url.protocol) || !url.hostname || url.password || url.search || url.hash || url.protocol !== 'ssh:' && url.username) throw new SetupError('请使用 HTTPS 或 SSH 仓库地址，并通过本机 Git 登录；不要在地址中填写 Token。');
+}
+const inside = (parent, child) => { const path = relative(parent, child); return !path || path !== '..' && !path.startsWith('../') && !isAbsolute(path); };
+export async function cloneRepository({ remote, destination, privateHome }) {
+  validCloneRemote(remote);
+  if (typeof destination !== 'string' || !isAbsolute(destination)) throw new SetupError('请选择新 clone 的本机绝对路径。');
+  const target = resolve(destination);
+  privateHome = await realpath(privateHome).catch((error) => { if (error.code === 'ENOENT') return resolve(privateHome); throw error; });
+  // Keep the private workspace outside the target repo and vice versa.
+  if (inside(target, privateHome) || inside(privateHome, target)) throw new SetupError('项目目录和本机私有配置目录不能相互包含。');
+  let existing; try { existing = await lstat(target); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (existing) {
+    if (existing.isSymbolicLink()) throw new SetupError('拉取目录不能是符号链接，请选择独立目录。');
+    try {
+      const actual = await realpath(target);
+      if (await git(actual, 'rev-parse', '--show-toplevel') === actual && remoteIdentity(await git(actual, 'remote', 'get-url', 'origin')) === remoteIdentity(remote)) return actual;
+    } catch { /* Reject existing unrelated folders instead of overwriting them. */ }
+    throw new SetupError('目标目录已存在，请选择新的目录，或切换到使用已有项目。');
+  }
+  await mkdir(dirname(target), { recursive: true });
+  const parent = await realpath(dirname(target)); const actualTarget = join(parent, basename(target));
+  if (inside(actualTarget, privateHome) || inside(privateHome, actualTarget)) throw new SetupError('项目目录和本机私有配置目录不能相互包含。');
+  await mkdir(actualTarget, { mode: 0o700 });
+  const staging = join(parent, `.collab-clone-${randomUUID()}`);
+  try {
+    await git(parent, '-c', 'protocol.ext.allow=never', 'clone', '--', remote, staging);
+    if ((await readdir(actualTarget)).length) throw new SetupError('拉取目录出现其他文件，请选择新目录后重试。');
+    await rename(staging, actualTarget);
+    return actualTarget;
+  } catch (error) {
+    if (error instanceof SetupError) throw error;
+    const detail = `${error.stderr || ''}\n${error.message || ''}`.toLowerCase();
+    if (/permission denied|authentication failed|could not read username|repository not found|403|401/.test(detail)) throw new SetupError('拉取仓库失败，请先完成本机 Git 登录并确认仓库读取权限。');
+    throw new SetupError('拉取仓库未完成，请检查仓库地址、网络和本机 Git 权限后重试。');
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+    await rmdir(actualTarget).catch(() => {}); // Only remove our empty reservation, never project files.
+  }
+}

package/apps/onboarding/manager.mjs

@@ -1,6 +1,6 @@
 import { defaultReviewRules } from '../../packages/peer/review.mjs';
 import { SetupError } from './errors.mjs';
-import { createPublicKey, randomUUID } from 'node:crypto';
+import { createPublicKey, randomBytes, randomUUID } from 'node:crypto';
 import { chmod, mkdir, readFile, readdir, realpath, rename, stat, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
@@ -10,12 +10,15 @@ import { canonical, digest, generateIdentity, readPrivateJson, validateTeam } fr
 import { PeerGitStore, git } from '../../packages/peer/store.mjs';
 import { approveEnrollment, enrollmentRequest, invitationFile, invitationRecord, policyVersion, recordHash, registryPath, requestFile, validateEnrollment, validateHistory, validateInvitation, versionFile, readRegistry } from '../../packages/peer/registry.mjs';
 import { attachProject, buildTeamPolicy, createMemberConfig, diagnosePeer, getOrCreateIdentityFiles } from '../../scripts/peer/onboarding.mjs';
-import { bindingPrompt } from '../../scripts/peer/setup-desktop-project.mjs';
+import { installedProjectConfig, refreshProject } from '../../scripts/peer/refresh-project.mjs';
+import { bindingPrompt, detailedBindingPrompt } from '../../scripts/peer/setup-desktop-project.mjs';
 import { readPeerConfig, loadRuntime } from '../peer/runtime.mjs';
 import { DesktopExecutor } from '../peer/desktop.mjs';
 import { alive, readRunnerLock } from '../peer/process.mjs';
 import { BotDiscovery } from './discovery.mjs';
+import { ResetActions } from './reset.mjs';
 import { encryptBundle, decryptBundle, remoteIdentity } from './bundle.mjs';
+import { cloneRepository, commandArgv, memberFields, recommendTests, suggestedRepo } from './guided.mjs';
 const packageRoot = fileURLToPath(new URL('../../', import.meta.url));
 const idPattern = /^[a-zA-Z0-9_-]{1,64}$/;
 const uuidPattern = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
@@ -109,7 +112,7 @@ function validateBundle(value) {
 
 export class SetupManager {
   constructor({ home = join(homedir(), '.config', 'codex-collab', 'workspace'), discovery = new BotDiscovery(), runCli } = {}) {
-    this.home = resolve(home); this.discovery = discovery; this.queue = Promise.resolve();
+    this.home = resolve(home); this.discovery = discovery; this.queue = Promise.resolve(); this.resets = new ResetActions(this);
     this.runCli = runCli || ((command, config) => {
       const result = spawnSync(process.execPath, [join(packageRoot, 'bin/codex-collab.mjs'), command, config], { encoding: 'utf8', timeout: 35000, maxBuffer: 200000 });
       if (result.status !== 0) throw new Error(`本机 ${command} 操作未完成，请检查项目 Git 权限或 Runner 日志。`);
@@ -129,12 +132,18 @@ export class SetupManager {
   async overview() {
     await mkdir(join(this.home, 'profiles'), { recursive: true, mode: 0o700 });
     const entries = (await readdir(join(this.home, 'profiles'))).filter((id) => uuidPattern.test(id));
-    const profiles = [];
+    const profiles = [], removed_profiles = [];
     for (const id of entries) {
       const state = await this.state(id);
-      profiles.push({ id, agent_id: state.agent_id, role: state.role, repo: state.repo, phase: state.phase, error: state.last_error || null });
+      (state.phase === 'removed' ? removed_profiles : profiles).push({ id, agent_id: state.agent_id, role: state.role, display_name: state.display_name || state.agent_id, repo: state.repo, phase: state.phase, error: state.last_error || null });
     }
-    return { profiles };
+    const drafts = [];
+    for (const file of await readdir(join(this.home, 'drafts')).catch((error) => error.code === 'ENOENT' ? [] : Promise.reject(error))) {
+      if (!uuidPattern.test(file.replace(/\.json$/, ''))) continue;
+      const draft = await readPrivateJson(join(this.home, 'drafts', file));
+      if (!draft.profile_id) drafts.push({ id: draft.id, agent_id: draft.input.agent_id, display_name: draft.input.display_name, repo: draft.input.repo });
+    }
+    return { profiles, removed_profiles, drafts };
   }
   async checkBotAvailable(botId) {
     for (const profile of (await this.overview()).profiles) {
@@ -147,6 +156,7 @@ export class SetupManager {
     let credentials = input;
     if (input.profile_id) {
       const state = await this.state(input.profile_id);
+      if (state.discovery_id && !input.reconnect) { try { const session = this.discovery.view(state.discovery_id); if (!['failed', 'expired', 'disconnected'].includes(session.status)) return session; } catch {} }
       if (!state.bundle) throw new SetupError('此项目没有待验证的接入包。');
       credentials = { ...state.bundle.wecom, chat_ids: state.bundle.invitation.chat_ids };
     }
@@ -162,11 +172,57 @@ export class SetupManager {
         } catch (error) { if (error instanceof SetupError) throw error; }
       }
     }
-    return this.discovery.begin(credentials);
+    const session = this.discovery.begin(credentials);
+    if (input.profile_id) { const state = await this.state(input.profile_id); state.discovery_id = session.id; await this.save(state); }
+    return session;
+  }
+  async prepareProject(input) {
+    const path = input.repo_mode === 'clone'
+      ? await cloneRepository({ remote: input.remote, destination: input.destination, privateHome: this.home }) : input.repo;
+    const selected = await ensureRepo(path);
+    if (inside(selected.repo, this.home)) throw new SetupError('本机配置目录必须在业务仓库之外。');
+    return { ...selected, tests: await recommendTests(selected.repo) };
+  }
+  draftPath(id) { if (!uuidPattern.test(id || '')) throw new SetupError('无效创建记录。'); return join(this.home, 'drafts', `${id}.json`); }
+  async prepareAdmin(input) {
+    const fields = memberFields(input);
+    if (typeof input.bot_id !== 'string' || !input.bot_id.trim() || typeof input.secret !== 'string' || !input.secret.trim()) throw new SetupError('请填写机器人 Bot ID 和 Secret。');
+    if (input.team_name != null && (typeof input.team_name !== 'string' || input.team_name.length > 80 || /[\x00-\x1f\x7f]/.test(input.team_name))) throw new SetupError('团队名称最多 80 个字符。');
+    const argv = input.test_command ? commandArgv(input.test_command) : testArgv(input.test_argv);
+    const selected = await this.prepareProject(input);
+    for (const profile of (await this.overview()).profiles) if (profile.repo === selected.repo) throw new SetupError('这个 clone 已接入其他身份，请选择独立 clone。');
+    const draft = { id: randomUUID(), input: { ...fields, repo: selected.repo, test_argv: argv, team_name: input.team_name?.trim() || null,
+      bot_id: input.bot_id, secret: input.secret } };
+    await savePrivate(this.draftPath(draft.id), draft);
+    return this.adminDraft({ id: draft.id });
+  }
+  async adminDraft({ id, reconnect = false }) {
+    const draft = await readPrivateJson(this.draftPath(id));
+    if (draft.profile_id) return { profile: await this.detail(draft.profile_id, { localOnly: true }) };
+    let session;
+    if (draft.discovery_id && !reconnect) { try { session = this.discovery.view(draft.discovery_id); if (['failed', 'expired', 'disconnected'].includes(session.status)) session = null; } catch {} }
+    if (!session) {
+      session = await this.beginDiscovery({ bot_id: draft.input.bot_id, secret: draft.input.secret, repo: draft.input.repo });
+      draft.discovery_id = session.id; await savePrivate(this.draftPath(id), draft);
+    }
+    return { ...session, draft_id: id, agent_id: draft.input.agent_id, repo: draft.input.repo };
+  }
+  async completeAdmin({ draft_id, discovery_id }) {
+    const draft = await readPrivateJson(this.draftPath(draft_id));
+    if (draft.profile_id) return this.detail(draft.profile_id, { localOnly: true });
+    if (draft.discovery_id !== discovery_id) throw new SetupError('请使用当前创建流程的群验证码。');
+    return this.createAdmin({ ...draft.input, discovery_id }, { onSaved: async (id) => {
+      draft.profile_id = id; delete draft.input.secret; await savePrivate(this.draftPath(draft_id), draft);
+    } });
   }
-  async createAdmin(input) {
-    const agentId = input.agent_id?.trim(); if (!idPattern.test(agentId || '')) throw new SetupError('请填写有效的成员名称。');
-    const caps = capabilities(input.capabilities); const argv = testArgv(input.test_argv || ['sh', 'test.sh']);
+  async progress({ id, sync = false }) {
+    const state = await this.state(id);
+    if (['initializing', 'verified', 'waiting', 'configuring'].includes(state.phase) && !state.last_error) return this.resume(id);
+    return this.detail(id, { localOnly: !sync || state.phase !== 'ready' });
+  }
+  async createAdmin(input, { onSaved } = {}) {
+    const fields = memberFields(input), agentId = fields.agent_id;
+    const caps = fields.capabilities; const argv = input.test_command ? commandArgv(input.test_command) : testArgv(input.test_argv || ['sh', 'test.sh']);
     const { repo, remote } = await ensureRepo(input.repo);
     if (inside(repo, this.home)) throw new SetupError('本机配置目录必须在业务仓库之外。');
     for (const profile of (await this.overview()).profiles) if (profile.repo === repo) throw new SetupError('这个 clone 已接入其他身份，请选择独立 clone。');
@@ -178,10 +234,11 @@ export class SetupManager {
       routes: Object.fromEntries(caps.map((cap) => [cap, [agentId]])) });
     team.schema_version = 3; team.review_rules = defaultReviewRules(team.routes);
     const record = policyVersion(team, null, agentId, (await readPrivateJson(identity.private_key_file)).private_key);
-    const state = { id, role: 'admin', agent_id: agentId, repo, remote, identity_path: identity.private_key_file, bootstrap_team: team,
+    const state = { id, role: 'admin', agent_id: agentId, display_name: fields.display_name, team_name: input.team_name || null, repo, remote, identity_path: identity.private_key_file, bootstrap_team: team,
       root_hash: recordHash(record), genesis: record, test_argv: argv,
       wecom: { bot_id: proof.bot_id, secret: proof.secret, chat_ids: [proof.chatid], commands_enabled: true, allow_admin_commands: true }, phase: 'initializing' };
     await this.save(state);
+    if (onSaved) await onSaved(id);
     return this.resume(id);
   }
   async importExisting({ config_path }) {
@@ -227,8 +284,19 @@ export class SetupManager {
     await savePrivate(resolve(config_path), { ...config, team_registry_root: rootHash });
     await this.save(state); this.runCli('start', resolve(config_path)); return this.detail(id, { localOnly: true });
   }
+  async refreshAttachment(state, configPath) {
+    try {
+      const installed = await installedProjectConfig({ repoPath: state.repo, agentId: state.agent_id });
+      const source = (await readPeerConfig(configPath)).config;
+      const bound = (await readPeerConfig(installed.config_path)).config;
+      if (bound.agent_id !== source.agent_id || bound.private_key !== source.private_key ||
+          await realpath(bound.repo) !== await realpath(source.repo) || resolve(bound.data_dir) !== resolve(source.data_dir)) throw new SetupError('项目 MCP 使用其他身份或数据目录，请手动检查原绑定。');
+      await refreshProject({ configPath: installed.config_path });
+    } catch (error) { throw new SetupError(error.message); }
+  }
   async resume(id) {
     const state = await this.state(id);
+    if (state.phase === 'removed') throw new SetupError('该项目已移除，请从首页恢复接入。');
     try {
       if (state.role === 'admin' && state.phase === 'initializing') {
         const bootstrap = new PeerGitStore({ repo: state.repo, dataDir: join(this.path(id), 'data'), team: state.bootstrap_team, agentId: state.agent_id,
@@ -288,15 +356,18 @@ export class SetupManager {
         await diagnosePeer(configPath, { testPush: true });
         if (!state.attached) {
           const existing = await readFile(join(state.repo, '.codex', 'config.toml'), 'utf8').catch(() => '');
-          const template = await readFile(join(packageRoot, 'packages/codex-kit/templates/.agents/skills/team-collab-desktop/SKILL.md'), 'utf8');
-          const installed = await readFile(join(state.repo, '.agents/skills/team-collab-desktop/SKILL.md'), 'utf8').catch(() => '');
-          if (!existing.includes(JSON.stringify(configPath)) || installed !== template) await attachProject({ configPath, repoPath: state.repo });
+          if (projectMcpConfigured(existing, configPath, await readPrivateJson(configPath))) await this.refreshAttachment(state, configPath);
+          else await attachProject({ configPath, repoPath: state.repo });
           state.attached = true; await this.save(state);
         }
         await savePrivate(join(this.path(id), 'binding.json'), { prompt: bindingPrompt(state.agent_id, state.repo) });
         state.phase = 'ready'; state.last_error = null; await this.save(state);
       }
-      if (state.phase === 'ready') this.runCli('start', state.existing_config || join(this.path(id), 'peer.json'));
+      if (state.phase === 'ready') {
+        await this.refreshAttachment(state, state.existing_config || join(this.path(id), 'peer.json'));
+        await savePrivate(join(this.path(id), 'binding.json'), { prompt: bindingPrompt(state.agent_id, state.repo) });
+        this.runCli('start', state.existing_config || join(this.path(id), 'peer.json'));
+      }
       state.last_error = null; await this.save(state);
       return this.detail(id, { localOnly: true });
     } catch (error) {
@@ -305,11 +376,27 @@ export class SetupManager {
       throw new SetupError(state.last_error);
     }
   }
-  async importBundle({ content, password, repo }) {
+  readBundle({ content, password }) {
     if (typeof content !== 'string' || content.length > 500000) throw new SetupError('请选择管理员提供的接入包。');
     let envelope;
     try { envelope = JSON.parse(content); } catch { throw new SetupError('接入包文件不是有效 JSON，请重新下载管理员提供的文件。'); }
-    return this.importAssignment(decryptBundle(envelope, password), repo);
+    return validateBundle(decryptBundle(envelope, password)).bundle;
+  }
+  async inspectBundle(input) {
+    const bundle = this.readBundle(input), invite = bundle.invitation;
+    return { agent_id: invite.agent_id, display_name: bundle.display_name || invite.agent_id, team_name: bundle.team_name || null,
+      remote: bundle.remote, capabilities: invite.capabilities, bot_id: invite.bot_id, suggested_repo: suggestedRepo(bundle.remote, invite.agent_id) };
+  }
+  async importBundle(input) {
+    const bundle = this.readBundle(input);
+    // An interrupted import resumes its original profile without making another clone.
+    for (const profile of (await this.overview()).profiles) {
+      const state = await this.state(profile.id);
+      if (state.bundle?.invitation.invite_id === bundle.invitation.invite_id) return this.detail(profile.id, { localOnly: true });
+    }
+    const repo = input.repo_mode === 'clone'
+      ? await cloneRepository({ remote: bundle.remote, destination: input.destination || suggestedRepo(bundle.remote, bundle.invitation.agent_id), privateHome: this.home }) : input.repo;
+    return this.importAssignment(bundle, repo);
   }
   async importAssignment(value, repo, ownAdminId) {
     const { bundle, history } = validateBundle(value);
@@ -322,13 +409,13 @@ export class SetupManager {
       if (current.repo === selected.repo) throw new SetupError('这个 clone 已接入其他身份，请选择独立 clone。');
     }
     const id = randomUUID(); const identity = await getOrCreateIdentityFiles(bundle.invitation.agent_id, join(this.home, 'identities'));
-    const state = { id, role: 'member', agent_id: bundle.invitation.agent_id, repo: selected.repo, remote: selected.remote, identity_path: identity.private_key_file,
+    const state = { id, role: 'member', agent_id: bundle.invitation.agent_id, display_name: bundle.display_name || bundle.invitation.agent_id, team_name: bundle.team_name || null, repo: selected.repo, remote: selected.remote, identity_path: identity.private_key_file,
       bootstrap_team: history.latest.team, root_hash: bundle.root_hash, bundle, test_argv: bundle.test_argv, phase: 'imported',
       ...(ownAdminId ? { own_admin_id: ownAdminId } : {}) };
     await this.save(state); return this.detail(id, { localOnly: true });
   }
   async verifyMember({ id, discovery_id }) {
-    const state = await this.state(id); if (state.phase !== 'imported') throw new SetupError('此成员已经完成群验证。');
+    const state = await this.state(id); if (state.phase !== 'imported') return this.detail(id, { localOnly: true });
     const proof = this.discovery.consume(discovery_id); const invite = state.bundle.invitation;
     if (proof.bot_id !== invite.bot_id || !invite.chat_ids.includes(proof.chatid)) throw new SetupError('请使用分配的机器人和指定协作群验证。');
     if (invite.owner_userid !== undefined && proof.userid !== invite.owner_userid) throw new SetupError('请用初始化团队时的同一个企业微信账号验证自己的新机器人。');
@@ -339,7 +426,60 @@ export class SetupManager {
       default_workflow: [invite.capabilities[0]] };
     state.phase = 'verified'; await this.save(state); return this.resume(id);
   }
+  async issueBatch({ id, members }) {
+    const state = await this.state(id);
+    if (state.role !== 'admin' || state.phase !== 'ready') throw new SetupError('请先完成管理员接入。');
+    if (!Array.isArray(members) || !members.length || members.length > 25) throw new SetupError('每次请分配 1 到 25 个机器人。');
+    const store = await this.profileStore(state), identity = await readPrivateJson(state.identity_path);
+    const ids = new Set([state.agent_id]), bots = new Set([state.wecom.bot_id]);
+    const prepared = members.map((input) => {
+      const fields = memberFields(input);
+      if (ids.has(fields.agent_id) || store.team.agents[fields.agent_id]) throw new SetupError(`成员 ${fields.agent_id} 已存在或在本次分配中重复。`);
+      if (typeof input.bot_id !== 'string' || !input.bot_id.trim() || typeof input.secret !== 'string' || !input.secret.trim()) throw new SetupError('请为每位成员填写独立机器人的 Bot ID 和 Secret。');
+      const botId = input.bot_id.trim();
+      if (bots.has(botId)) throw new SetupError('本次分配的机器人重复；每个 Agent 必须使用独立机器人。');
+      ids.add(fields.agent_id); bots.add(botId);
+      const password = input.password || randomBytes(18).toString('base64url');
+      encryptBundle({}, password); // Validate the whole batch before any invitation is published.
+      return { ...fields, bot_id: botId, secret: input.secret, commands_enabled: input.commands_enabled !== false,
+        prefer: input.prefer !== false, password, claim: generateIdentity(), invite_id: randomUUID() };
+    });
+    await store.registryTransaction(async (history) => {
+      for (const item of prepared) if (history.latest.team.agents[item.agent_id]) throw new SetupError(`成员 ${item.agent_id} 已存在，请刷新工作台。`);
+      const existing = await readdir(join(store.checkout, registryPath, 'invitations')).catch((error) => error.code === 'ENOENT' ? [] : Promise.reject(error));
+      for (const file of existing) {
+        const invite = JSON.parse(await readFile(join(store.checkout, registryPath, 'invitations', file), 'utf8'));
+        validateInvitation(invite, history);
+        if (prepared.some((item) => (item.agent_id === invite.agent_id || item.bot_id === invite.bot_id) && item.invite_id !== invite.invite_id) &&
+            (Date.now() < Date.parse(invite.expires_at) || history.records.some((record) => record.enrollment?.invite_id === invite.invite_id))) throw new SetupError('成员或机器人已有有效接入包，请使用已生成的文件。');
+      }
+      const files = [];
+      for (const item of prepared) {
+        const invitation = invitationRecord({ invite_id: item.invite_id, agent_id: item.agent_id, capabilities: item.capabilities,
+          bot_id: item.bot_id, chat_ids: state.wecom.chat_ids, commands_enabled: item.commands_enabled, prefer: item.prefer,
+          claim_public_key: item.claim.public_key, expires_at: new Date(Date.now() + 7 * 86400000).toISOString() }, history.latest, state.agent_id, identity.private_key);
+        const bundle = { schema_version: 1, kind: 'codex-collab-invite', root_hash: state.root_hash, remote: state.remote,
+          history: history.records, invitation, claim_private_key: item.claim.private_key, display_name: item.display_name, team_name: state.team_name || null,
+          wecom: { bot_id: item.bot_id, secret: item.secret }, test_argv: state.test_argv };
+        await savePrivate(join(this.path(id), 'exports', `${item.invite_id}.json`), { invitation, display_name: item.display_name,
+          encrypted: encryptBundle(bundle, item.password), delivery_password: item.password });
+        files.push([invitationFile(item.invite_id), invitation]);
+      }
+      return { files, value: null };
+    });
+    return { assignments: prepared.map((item) => ({ invite_id: item.invite_id, agent_id: item.agent_id,
+      display_name: item.display_name, filename: `${item.agent_id}-collab-invite.json`, password: item.password })) };
+  }
+  async delivery({ id, invite_id }) {
+    const state = await this.state(id);
+    if (state.role !== 'admin' || state.phase !== 'ready' || !uuidPattern.test(invite_id || '')) throw new SetupError('只有管理员可查看已分配的接入说明。');
+    const saved = await this.publishAssignment(id, invite_id);
+    if (!saved.encrypted) throw new SetupError('本人机器人直接在本机接入，无需分发接入包。');
+    return { agent_id: saved.invitation.agent_id, display_name: saved.display_name || saved.invitation.agent_id, password: saved.delivery_password || null,
+      instructions: `已为你分配 ${saved.display_name || saved.invitation.agent_id} 协作机器人。\n1. 安装 Node.js 20 或以上版本及 Git。\n2. 执行 npx xuym-codex-collab@latest setup 打开接入向导。\n3. 导入我提供的加密接入包，使用单独发送的密码，选择已有项目或自动拉取。\n4. 按页面提示在群里确认身份；批准后自动完成配置。\n5. 在目标 Codex 项目对话发送页面提供的启用指令。` };
+  }
   async issueBundle(input, { ownRepo } = {}) {
+    if (!ownRepo) return (await this.issueBatch({ id: input.id, members: [input] })).assignments[0];
     const state = await this.state(input.id); if (state.role !== 'admin' || state.phase !== 'ready') throw new SetupError('请先完成管理员接入。');
     const agentId = input.agent_id?.trim(); if (!idPattern.test(agentId || '') || agentId === state.agent_id) throw new SetupError('请填写要加入的成员名称。');
     const caps = capabilities(input.capabilities); const store = await this.profileStore(state);
@@ -464,7 +604,7 @@ export class SetupManager {
     return this.detail(id);
   }
   async detail(id, { localOnly = false } = {}) {
-    const state = await this.state(id); const result = { id, agent_id: state.agent_id, role: state.role, repo: state.repo, phase: state.phase, own_agent: !!state.own_admin_id, error: state.last_error || null };
+    const state = await this.state(id); const result = { id, agent_id: state.agent_id, display_name: state.display_name || state.agent_id, team_name: state.team_name || null, role: state.role, repo: state.repo, phase: state.phase, own_agent: !!state.own_admin_id, error: state.last_error || null };
     if (state.phase === 'imported') result.assignment = { capabilities: state.bundle.invitation.capabilities, bot_id: state.bundle.invitation.bot_id,
       expires_at: state.bundle.invitation.expires_at };
     if (state.role === 'admin' && state.phase === 'ready' && !localOnly) {
@@ -492,11 +632,11 @@ export class SetupManager {
       for (const file of exported) {
         const value = await readPrivateJson(join(this.path(id), 'exports', file));
         result.exports.push({ invite_id: value.invitation.invite_id, agent_id: value.invitation.agent_id,
-          filename: `${value.invitation.agent_id}-collab-invite.json`, expires_at: value.invitation.expires_at, own_agent: !!value.own_bundle });
+          filename: `${value.invitation.agent_id}-collab-invite.json`, display_name: value.display_name || value.invitation.agent_id, expires_at: value.invitation.expires_at, own_agent: !!value.own_bundle });
       }
     }
     if (state.phase === 'ready') {
-      result.config_path = state.existing_config || join(this.path(id), 'peer.json'); result.binding_prompt = bindingPrompt(state.agent_id, state.repo);
+      result.config_path = state.existing_config || join(this.path(id), 'peer.json'); result.binding_prompt = bindingPrompt(state.agent_id, state.repo); result.detailed_binding_prompt = detailedBindingPrompt(state.agent_id, state.repo);
       const config = (await readPeerConfig(result.config_path)).config;
       const skillName = config.execution_mode === 'desktop_poll' ? 'team-collab-desktop' : 'team-collab';
       const projectConfig = await readFile(join(state.repo, '.codex', 'config.toml'), 'utf8').catch((error) => error.code === 'ENOENT' ? '' : Promise.reject(error));
@@ -520,13 +660,19 @@ export class SetupManager {
   async runner({ id, command }) {
     const state = await this.state(id); if (state.phase !== 'ready' || !['start', 'stop'].includes(command)) throw new SetupError('无效连接操作。');
     try {
+      if (command === 'start' && [...this.discovery.sessions.values()].some((session) => session.bot_id === state.wecom?.bot_id && ['connecting', 'authenticated'].includes(session.status))) throw new SetupError('机器人正在验证，请先取消验证，再启动连接。');
       this.runCli(command, state.existing_config || join(this.path(id), 'peer.json'));
       state.last_error = null; await this.save(state);
-    } catch {
+    } catch (error) {
+      if (error instanceof SetupError) throw error;
       state.last_error = `机器人${command === 'start' ? '启动' : '停止'}未完成，请检查本机 Runner 日志后重试。`;
       await this.save(state); throw new SetupError(state.last_error);
     }
     return this.detail(id, { localOnly: true });
   }
+  resetPreview(input) { return this.resets.preview(input); }
+  resetDiscovery(input) { return this.resets.discover(input); }
+  resetCancel(input) { return this.resets.cancel(input); }
+  reset(input) { return this.resets.apply(input); }
   close() { this.discovery.closeAll(); }
 }