xuym-codex-collab 0.4.3 → 0.5.0

package/README.md

@@ -8,10 +8,10 @@
 
 ```sh
 npm install --global xuym-codex-collab
-codex-collab setup
+codex-collab
 ```
 
-`setup` 打开本机网页工作台，所有接入操作集中在一个页面。管理员选择“初始化团队”，成员选择“加入团队”；群身份验证、等待审批和本机配置会自动衔接，页面显示当前进度。已在使用旧配置的成员选择“导入已有配置”。终端保持运行即可继续使用工作台，关闭工作台后已启动的机器人连接仍运行。
+`setup` 打开本机网页工作台，所有接入操作集中在一个页面。管理员选择“连接我的机器人”，成员选择“接受同事邀请”；群身份验证、等待审批和本机配置会自动衔接，页面显示当前进度。已在使用旧配置的成员选择“导入已有配置”。命令启动后台工作台后退出，可以关闭终端和浏览器。macOS 默认设置登录自启；Linux 尝试配置 systemd 用户服务，失败时明确提示。工作台每 15 秒检查一次已开启的机器人进程，意外退出时恢复并在失败后退避重试；手动停止的连接保持停止。
 
 | 谁 | 在工作台做什么 | 接入后需要保留什么 |
 | --- | --- | --- |
@@ -36,6 +36,25 @@ Skill 完成身份核对、对话绑定和 heartbeat 配置，页面自动观察
 
 若管理员工作台显示接入包密码为空，通常是旧版本未保存原密码：无法从密文恢复，只能在管理员项目的“已分配的机器人”中重新生成包和密码。详情见[密码遗失恢复步骤](docs/onboarding.md#接入包密码遗失)。
 
+## 日常使用与升级
+
+在业务项目目录运行以下命令；只有一个接入时，也可以在任意目录运行。多个接入可通过 `codex-collab projects` 查看，再加 `--profile <项目ID>` 或唯一的 Agent ID 选择。原有显式 `peer.json` 路径参数继续支持。
+
+```sh
+codex-collab status
+codex-collab doctor
+codex-collab repair
+codex-collab stop
+codex-collab start
+codex-collab autostart status
+```
+
+`doctor` 检查项目 MCP/Skill、机器人进程与认证、对话绑定、真实轮询以及 Git 读取和推送权限，并给出下一步。页面也提供“检查整条连接”和“修复本机配置”。修复更新已识别的生成配置，并恢复缺失的 MCP 配置和 Skill；自定义、符号链接或已提交的共享配置需要手动合并。修复后请在 Codex 重新加载项目 MCP，在原对话执行启用指令。
+
+升级执行 `npm install -g xuym-codex-collab@latest`，然后重新打开工作台并修复项目配置。已经运行的 Node 进程需要重启才能加载新代码：停止并重新启动机器人；后台工作台可等下次登录，或终止 `codex-collab service-status` 显示的工作台 PID 后重新执行 `codex-collab`。0.5.0 迁移时只接管仍在运行的旧连接，已停止的旧连接需要你主动启动。
+
+`codex-collab autostart off` 关闭登录自启，`autostart on` 重新设置。`setup --no-startup` 仅跳过本次自启配置，`setup --foreground` 以前台模式运行，便于排查。Windows 支持独立后台工作台，暂未自动配置登录启动。电脑休眠、关机或退出系统期间不会执行群任务；Codex 对话的自动化仍需保持启用。
+
 ## 一次任务如何接力
 
 ```mermaid
@@ -72,13 +91,20 @@ sequenceDiagram
 
 自然语言入口使用 `desktop_poll`，沿用本人身份和群权限。对话从团队路由选择职责，指定的同事不存在或分工不明确时需要追问；机器人显示名不决定调度。旧的 `协作 创建 ...` 命令仍兼容。
 
-Alice 的绑定对话认领后在隔离 worktree 执行前端阶段，提交代码、运行固定验证命令、写入总结；群里收到分支、提交 SHA、测试结果和审核命令。默认由实际执行者本人审核，通过后才开放 Bob 的后端阶段。退回时必须填写修改意见，当前阶段从被退回的提交继续修改，重新提交后再次审核。管理员可在工作台按职责选择审核人、额外通知对象，或关闭中间阶段审核。候补从 Git 签名事件和租约判断，机器人 @ 消息本身不负责调度。群消息中的验收文字不会替换管理员设置的本机测试 argv。
+Alice 的绑定对话认领后在隔离 worktree 执行前端阶段，提交代码、运行固定验证命令、写入总结；群里收到分支、提交 SHA、测试结果和审核提示。默认由实际执行者本人审核，通过后才开放 Bob 的后端阶段。退回时必须填写修改意见，当前阶段从被退回的提交继续修改，重新提交后再次审核。管理员可在工作台按职责选择审核人、额外通知对象，或关闭中间阶段审核。候补从 Git 签名事件和租约判断，机器人 @ 消息本身不负责调度。群消息中的验收文字不会替换管理员设置的本机测试 argv。
 
-自然语言“通过”或“完成”不会批准任务；真人审核仍复制通知中的明确命令。已有安装须同时更新工具、项目 Skill、MCP 和原对话的 heartbeat 提示词，步骤见 [已有项目升级](docs/desktop-poll.md#已有项目启用自然语言入口)。
+审核也支持自然语言：指定审核人 @ 自己的机器人说“通过，继续下一步”，或“先别通过，安装步骤再补一下”。只有一条待审核任务时无需复制任务 ID 和版本号；多条时机器人先请你选任务。只说“收到”、带条件的“如果测试通过就批准”不会触发通过；退回缺少具体意见时先追问。已有安装须由所有参与者一起更新工具、重启 Runner/MCP、刷新项目 Skill 和原对话的 heartbeat 提示词，步骤见 [已有项目升级](docs/desktop-poll.md#已有项目启用自然语言入口)。
 
 代码保存在独立 `codex/*` 分支；任务和签名策略保存在 `agent-collab`，两者不自动合并到 `main`。最后阶段始终等待真人审核，审核通过后由管理员完成任务。
 
-审核人在群里 @ 自己绑定的机器人，复制最新通知中的任务 ID 和 `R-版本号`：
+审核人在群里 @ 自己绑定的机器人直接表达决定：
+
+```text
+@Alice 通过，交给 Bob 继续。
+@Bob 先别通过，安装步骤再补一下。
+```
+
+自然语言审核按收到消息时的待审核任务与提交版本处理；任务已经变化时，需要看最新结果后重新确认。审核通过会按已有分工交接，不修改职责或跳过阶段。最终审核通过后仍由管理员明确完成任务。旧的精确命令也可继续使用：
 
 ```text
 协作 审核 T-实际任务ID R-7 通过

package/apps/onboarding/commands.mjs

@@ -0,0 +1,46 @@
+import { isAbsolute, resolve } from 'node:path';
+import { SetupManager } from './manager.mjs';
+import { selectProfile, workspaceHome, profiles } from './workspace.mjs';
+import { configureStartup, startupStatus } from './startup.mjs';
+import { serviceState } from './main.mjs';
+
+// Preserve the original explicit peer.json interface for scripts and advanced users.
+export async function resolveCommand(args, { home = workspaceHome(), cwd = process.cwd() } = {}) {
+  const [command, ...input] = args;
+  let selector; const rest = [];
+  for (let i = 0; i < input.length; i++) {
+    if (input[i] === '--profile') { if (!input[i + 1]) throw new Error('--profile 需要项目 ID 或 Agent ID。'); selector = input[++i]; }
+    else rest.push(input[i]);
+  }
+  if (rest[0] && (isAbsolute(rest[0]) || rest[0].endsWith('.json'))) return { command, configPath: resolve(rest.shift()), args: rest };
+  const profile = await selectProfile({ home, cwd, selector });
+  return { command, configPath: profile.config_path, profile, args: rest };
+}
+export async function workspaceCommand(args, { home = workspaceHome() } = {}) {
+  if (args[0] === 'projects') {
+    console.log(JSON.stringify((await profiles(home)).map(({ id, agent_id, repo, phase }) => ({ id, agent_id, repo, phase })), null, 2)); return true;
+  }
+  if (args[0] === 'autostart') {
+    if (!['on', 'off', 'status'].includes(args[1])) throw new Error('usage: codex-collab autostart on|off|status');
+    console.log(JSON.stringify(args[1] === 'status' ? await startupStatus(home) : await configureStartup({ home, enabled: args[1] === 'on' }), null, 2)); return true;
+  }
+  if (args[0] === 'service-status') {
+    const state = await serviceState(home);
+    console.log(JSON.stringify({ online: !!state, pid: state?.pid || null, startup: await startupStatus(home) }, null, 2)); return true;
+  }
+  return false;
+}
+export async function guidedCommand(resolved, { home = workspaceHome() } = {}) {
+  if (resolved.command === 'repair' && !resolved.profile) {
+    const { refreshProject } = await import('../../scripts/peer/refresh-project.mjs');
+    console.log(JSON.stringify(await refreshProject({ configPath: resolved.configPath }), null, 2)); return true;
+  }
+  if (!['doctor', 'repair'].includes(resolved.command) || !resolved.profile) return false;
+  const manager = new SetupManager({ home });
+  try {
+    const value = resolved.command === 'repair' ? await manager.repair({ id: resolved.profile.id }) : await manager.diagnostics({ id: resolved.profile.id });
+    console.log(JSON.stringify(value, null, 2));
+    if (resolved.command === 'doctor' && value.checks.some((check) => !check.ok)) process.exitCode = 1;
+  } finally { manager.close(); }
+  return true;
+}

package/apps/onboarding/guided.mjs

@@ -55,6 +55,7 @@ export async function recommendTests(repo) {
   return commands.map((argv) => ({ argv, command: displayCommand(argv) }));
 }
 export function suggestedRepo(remote, agentId) {
+  if (typeof remote !== 'string' || !remote.trim()) throw new SetupError('请填写业务仓库地址。');
   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}`);
 }

package/apps/onboarding/main.mjs

@@ -1,32 +1,85 @@
 import { spawn } from 'node:child_process';
-import { mkdir, readFile, rm } from 'node:fs/promises';
+import { chmod, mkdir, open as openFile, readFile, rm } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import { homedir } from 'node:os';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
 import { startSetupServer } from './server.mjs';
-import { SetupManager } from './manager.mjs';
+import { SetupManager, savePrivate } from './manager.mjs';
+import { RunnerSupervisor } from './supervisor.mjs';
+import { workspaceHome } from './workspace.mjs';
+import { configureStartup, startupStatus } from './startup.mjs';
 import { alive } from '../peer/process.mjs';
+const entry = fileURLToPath(import.meta.url);
 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 });
+export async function serviceState(home) {
+  for (let attempt = 0; attempt < 30; attempt++) {
+    try { const state = JSON.parse(await readFile(join(home, 'wizard.json'), 'utf8')); return alive(state.pid) ? state : null; }
+    catch (error) { if (error.code === 'ENOENT') return null; if (!(error instanceof SyntaxError)) throw error; }
+    await delay(50);
+  }
+  throw new Error('本机工作台正在初始化，请稍后重试。');
+}
+export async function runService({ home = workspaceHome() } = {}) {
+  process.umask(0o077); 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 });
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try { lock = await openFile(path, 'wx', 0o600); break; }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      if (await serviceState(home)) return null;
+      await rm(path, { force: true });
+    }
   }
-  let app;
+  if (!lock) throw new Error('无法取得本机工作台锁。');
+  let app, timer, stopping = false;
   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;
+    const manager = new SetupManager({ home });
+    app = await startSetupServer({ manager });
+    await lock.writeFile(JSON.stringify({ pid: process.pid, url: app.url, started_at: new Date().toISOString() }) + '\n'); await lock.close();
+    const supervisor = new RunnerSupervisor(manager);
+    const tick = async () => {
+      try { await manager.exclusive(() => supervisor.tick()); } catch { /* Local diagnostics show missing/invalid profiles without logging secrets. */ }
+      if (!stopping) timer = setTimeout(tick, 15000);
+    };
+    timer = setTimeout(tick, 1000);
+    const stop = async () => {
+      if (stopping) return; stopping = true; clearTimeout(timer);
+      await app.close(); const state = await serviceState(home); if (state?.pid === process.pid) await rm(path, { force: true });
+    };
+    process.once('SIGINT', () => void stop()); process.once('SIGTERM', () => void stop());
+    return { ...app, stop };
   } catch (error) { await lock.close().catch(() => {}); await rm(path, { force: true }); if (app) await app.close(); throw error; }
 }
+export async function runLocalSetup({ open = true, home = workspaceHome(), cwd = process.cwd(), foreground = false, startup = true } = {}) {
+  home = resolve(home); await savePrivate(join(home, 'context.json'), { cwd: resolve(cwd) });
+  let state = await serviceState(home);
+  if (foreground) {
+    if (state) { console.log(`本机工作台已运行：${state.url}`); if (open) openBrowser(state.url); return; }
+    const app = await runService({ home }); if (app) { console.log(`Codex Collab 工作台：${app.url}`); if (open) openBrowser(app.url); } return app;
+  }
+  const previous = await startupStatus(home);
+  let registered = startup ? previous : { enabled: false };
+  if (startup && (previous.enabled || previous.kind == null && previous.supported && !previous.error)) registered = await configureStartup({ home, start: !state });
+  if (!state) {
+    state = await serviceState(home);
+    if (!state && !registered.enabled) {
+      const log = await openFile(join(home, 'service.log'), 'a', 0o600); await chmod(join(home, 'service.log'), 0o600);
+      const child = spawn(process.execPath, [entry, '--home', home], { detached: true, stdio: ['ignore', log.fd, log.fd], env: process.env });
+      let error; child.on('error', () => { error = true; }); child.unref(); await log.close();
+      for (let i = 0; i < 100 && !state && !error; i++) { await delay(100); state = await serviceState(home); }
+    } else for (let i = 0; i < 100 && !state; i++) { await delay(100); state = await serviceState(home); }
+  }
+  if (!state) throw new Error(`本机后台工作台未启动，请检查 ${join(home, 'service.log')}，或运行 codex-collab setup --foreground。`);
+  console.log(`Codex Collab 工作台：${state.url}\n后台服务已运行，可以关闭终端和浏览器。${registered.enabled ? '登录时将自动恢复已开启的连接。' : '登录自启未启用。'}`);
+  if (registered.error) console.log(registered.error);
+  if (open) openBrowser(state.url);
+  return state;
+}
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  const args = process.argv.slice(2);
+  if (args.length !== 2 || args[0] !== '--home') throw new Error('Internal service requires --home.');
+  runService({ home: args[1] }).catch(() => { console.error('Codex Collab 后台服务启动失败，请运行 codex-collab setup --foreground 排查。'); process.exitCode = 1; });
+}

package/apps/onboarding/manager.mjs

@@ -2,9 +2,12 @@ import { defaultReviewRules } from '../../packages/peer/review.mjs';
 import { SetupError } from './errors.mjs';
 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';
-import { spawnSync } from 'node:child_process';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readRunnerIntent, writeRunnerIntent } from '../peer/intent.mjs';
+import { localDefaults, workspaceHome } from './workspace.mjs';
+import { startupStatus } from './startup.mjs';
 import { fileURLToPath } from 'node:url';
 import { canonical, digest, generateIdentity, readPrivateJson, validateTeam } from '../../packages/peer/config.mjs';
 import { PeerGitStore, git } from '../../packages/peer/store.mjs';
@@ -111,12 +114,13 @@ function validateBundle(value) {
 }
 
 export class SetupManager {
-  constructor({ home = join(homedir(), '.config', 'codex-collab', 'workspace'), discovery = new BotDiscovery(), runCli } = {}) {
+  constructor({ home = workspaceHome(), discovery = new BotDiscovery(), runCli } = {}) {
     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 日志。`);
-      return result.stdout.trim();
+    this.runCli = runCli || (async (command, config) => {
+      try {
+        const result = await promisify(execFile)(process.execPath, [join(packageRoot, 'scripts/peer/cli.mjs'), command, config], { timeout: 35000, maxBuffer: 200000 });
+        return result.stdout.trim();
+      } catch { throw new Error(`本机 ${command} 操作未完成，请检查项目 Git 权限或 Runner 日志。`); }
     });
   }
   async exclusive(fn) { const action = this.queue.then(fn); this.queue = action.catch(() => {}); return action; }
@@ -143,7 +147,8 @@ export class SetupManager {
       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 };
+    let context = {}; try { context = await readPrivateJson(join(this.home, 'context.json')); } catch {}
+    return { profiles, removed_profiles, drafts, defaults: await localDefaults(context.cwd || this.home), startup: await startupStatus(this.home) };
   }
   async checkBotAvailable(botId) {
     for (const profile of (await this.overview()).profiles) {
@@ -178,7 +183,7 @@ export class SetupManager {
   }
   async prepareProject(input) {
     const path = input.repo_mode === 'clone'
-      ? await cloneRepository({ remote: input.remote, destination: input.destination, privateHome: this.home }) : input.repo;
+      ? await cloneRepository({ remote: input.remote, destination: input.destination || suggestedRepo(input.remote, memberFields({ ...input, display_name: input.display_name || input.agent_id || 'owner' }).agent_id), 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) };
@@ -282,11 +287,12 @@ export class SetupManager {
     await savePrivate(join(this.path(id), 'peer.json'), { ...config, team_registry_root: rootHash });
     // Existing MCP processes keep using this path and the same private desktop state.
     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 });
+    await this.save(state); await 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 installed = await installedProjectConfig({ repoPath: state.repo, agentId: state.agent_id, allowMissing: true });
+      if (installed.missing) { await refreshProject({ configPath }); return; }
       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 ||
@@ -296,6 +302,7 @@ export class SetupManager {
   }
   async resume(id) {
     const state = await this.state(id);
+    const wasReady = state.phase === 'ready';
     if (state.phase === 'removed') throw new SetupError('该项目已移除，请从首页恢复接入。');
     try {
       if (state.role === 'admin' && state.phase === 'initializing') {
@@ -367,7 +374,11 @@ export class SetupManager {
       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'));
+        const configPath = state.existing_config || join(this.path(id), 'peer.json');
+        const { config } = await readPeerConfig(configPath);
+        const intent = await readRunnerIntent(config.data_dir);
+        if (intent?.enabled) await this.runCli('recover', configPath);
+        else if (!intent && !wasReady) { await writeRunnerIntent(config.data_dir, true); await this.runCli('start', configPath); }
       }
       state.last_error = null; await this.save(state);
       return this.detail(id, { localOnly: true });
@@ -618,7 +629,9 @@ export class SetupManager {
   async createOwnAgent(input) {
     const state = await this.state(input.id);
     if (state.role !== 'admin' || state.phase !== 'ready') throw new SetupError('请从已接入的管理员项目添加自己的机器人。');
-    const selected = await ensureRepo(input.repo);
+    if (!idPattern.test(input.agent_id?.trim() || '')) throw new SetupError('请填写新 Agent 名称。');
+    const repo = input.repo_mode === 'clone' ? await cloneRepository({ remote: state.remote, destination: input.destination || suggestedRepo(state.remote, input.agent_id.trim()), privateHome: this.home }) : input.repo;
+    const selected = await ensureRepo(repo);
     if (inside(selected.repo, this.home)) throw new SetupError('本机配置目录必须在业务仓库之外。');
     if (remoteIdentity(selected.remote) !== remoteIdentity(state.remote)) throw new SetupError('新 Agent 必须选择同一业务仓库的另一个 clone。');
     const files = await readdir(join(this.path(input.id), 'exports')).catch((error) => { if (error.code === 'ENOENT') return []; throw error; });
@@ -728,6 +741,7 @@ export class SetupManager {
       }
       const desktop = new DesktopExecutor({ agentId: config.agent_id, store: { clock: Date.now } }, config);
       result.desktop = await desktop.status();
+      result.connection_enabled = (await readRunnerIntent(config.data_dir))?.enabled ?? result.runner.online;
       result.last_poll_at = result.desktop.last_poll_at || null;
       result.poll_observed = !!result.last_poll_at;
       result.poll_recent = !!result.last_poll_at && Date.now() - Date.parse(result.last_poll_at) < 180000;
@@ -740,7 +754,10 @@ export class SetupManager {
     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'));
+      const configPath = state.existing_config || join(this.path(id), 'peer.json');
+      const { config } = await readPeerConfig(configPath);
+      await writeRunnerIntent(config.data_dir, command === 'start');
+      await this.runCli(command, configPath);
       state.last_error = null; await this.save(state);
     } catch (error) {
       if (error instanceof SetupError) throw error;
@@ -749,6 +766,32 @@ export class SetupManager {
     }
     return this.detail(id, { localOnly: true });
   }
+  async diagnostics({ id }) {
+    const value = await this.detail(id, { localOnly: true });
+    const checks = [];
+    const add = (key, label, ok, action) => checks.push({ key, label, ok: !!ok, action: ok ? null : action });
+    add('setup', '本机接入', value.phase === 'ready', '先继续完成群身份验证和管理员确认。');
+    if (value.phase === 'ready') {
+      add('mcp', '项目 MCP', value.project_setup.mcp_configured, '点击修复本机配置，然后在 Codex 中重新加载项目 MCP。');
+      add('skill', '接入 Skill', value.project_setup.skill_installed, '点击修复本机配置，恢复工具生成的 Skill。');
+      add('runner', '后台机器人进程', value.runner.online, value.connection_enabled ? '连接已启用，后台将尝试恢复；也可以点击启动机器人连接。' : '连接已停止。需要接任务时点击启动机器人连接。');
+      add('wecom', '企业微信认证', value.runner.wecom === 'authenticated', '等待认证；若持续失败，请检查网络或通过更新机器人凭据重新验证。');
+      add('binding', '目标 Codex 对话', !!value.desktop.binding, '复制启用指令，发送到你选定的 Codex 对话。');
+      add('poll', '对话实际轮询', value.poll_recent, '在绑定对话中执行启用指令，并确认该对话的协作自动化已启用。');
+      try { await diagnosePeer(value.config_path, { testPush: true }); add('git', 'Git 读取与推送权限', true); }
+      catch { add('git', 'Git 读取与推送权限', false, '请完成本机 Git 登录，确认 origin/main 可读并具有推送权限。'); }
+    }
+    const startup = await startupStatus(this.home);
+    return { id, checks, ready: value.can_receive_tasks === true, startup, heartbeat_confirmed: false,
+      note: '检查使用真实进程、认证和轮询记录，不创建测试任务。未来能否自动唤醒仍需在 Codex 中确认自动化。' };
+  }
+  async repair({ id }) {
+    const state = await this.state(id);
+    if (state.phase !== 'ready') throw new SetupError('请先完成本机接入。');
+    const configPath = state.existing_config || join(this.path(id), 'peer.json');
+    await this.refreshAttachment(state, configPath);
+    return { id, repaired: true, next_step: '本机生成配置已更新。请在 Codex 重新加载项目 MCP，并在原绑定对话中执行启用指令。' };
+  }
   resetPreview(input) { return this.resets.preview(input); }
   resetDiscovery(input) { return this.resets.discover(input); }
   resetCancel(input) { return this.resets.cancel(input); }

package/apps/onboarding/reset.mjs

@@ -6,6 +6,7 @@ import { SetupError } from './errors.mjs';
 import { readPeerConfig, loadRuntime } from '../peer/runtime.mjs';
 import { PrivateDesktopState } from '../peer/private-state.mjs';
 import { alive, readRunnerLock } from '../peer/process.mjs';
+import { writeRunnerIntent } from '../peer/intent.mjs';
 import { installedProjectConfig } from '../../scripts/peer/refresh-project.mjs';
 import { bindingPrompt } from '../../scripts/peer/setup-desktop-project.mjs';
 import { digest, readPrivateJson } from '../../packages/peer/config.mjs';
@@ -152,8 +153,9 @@ export class ResetActions {
     if (!value || value.id !== input.id || value.kind !== input.kind || value.expires < Date.now() || value.fingerprint !== fingerprint) throw new SetupError('项目配置或绑定已改变，或预览已过期，请重新预览。');
   }
   async stop(context, plan) {
+    await writeRunnerIntent(context.dataDir, false);
     if (!plan.lock || !alive(plan.lock.pid)) return;
-    try { this.manager.runCli('stop', plan.lock.config); }
+    try { await this.manager.runCli('stop', plan.lock.config); }
     catch { throw new SetupError('机器人停止失败，未修改配置；请检查 Runner 后重试。'); }
     const lock = await readRunnerLock(join(context.dataDir, 'runner.pid.json'));
     if (lock && alive(lock.pid)) throw new SetupError('机器人仍在停止，请稍后重试；未修改配置。');

package/apps/onboarding/server.mjs

@@ -41,7 +41,7 @@ export async function startSetupServer({ manager = new SetupManager(), port = 0
         const value = await manager.exclusive(() => manager.exportedBundle(url.searchParams.get('id'), url.searchParams.get('invite')));
         res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Disposition': `attachment; filename="${value.filename}"` }); res.end(value.content); return;
       }
-      const actions = { 'project-check': () => manager.prepareProject(body), 'admin-prepare': () => manager.prepareAdmin(body), 'admin-complete': () => manager.completeAdmin(body), 'admin-retry': () => manager.adminDraft({ id: body.id, reconnect: true }), 'inspect-invite': () => manager.inspectBundle(body), progress: () => manager.progress(body), 'issue-batch': () => manager.issueBatch(body), 'reissue-invite': () => manager.reissueBundle(body), delivery: () => manager.delivery(body), 'reset-cancel': () => manager.resetCancel(body), 'reset-preview': () => manager.resetPreview(body), 'reset-discovery': () => manager.resetDiscovery(body), reset: () => manager.reset(body), 'own-agent': () => manager.createOwnAgent(body), 'own-agent-resume': () => manager.resumeOwnAgent(body), discovery: () => manager.beginDiscovery(body), admin: () => manager.createAdmin(body), import: () => manager.importBundle(body), existing: () => manager.importExisting(body), verify: () => manager.verifyMember(body), resume: () => manager.resume(body.id), issue: () => manager.issueBundle(body), approve: () => manager.approve(body), runner: () => manager.runner(body), 'review-rules': () => manager.setReviewRules(body) };
+      const actions = { diagnostics: () => manager.diagnostics(body), repair: () => manager.repair(body), 'project-check': () => manager.prepareProject(body), 'admin-prepare': () => manager.prepareAdmin(body), 'admin-complete': () => manager.completeAdmin(body), 'admin-retry': () => manager.adminDraft({ id: body.id, reconnect: true }), 'inspect-invite': () => manager.inspectBundle(body), progress: () => manager.progress(body), 'issue-batch': () => manager.issueBatch(body), 'reissue-invite': () => manager.reissueBundle(body), delivery: () => manager.delivery(body), 'reset-cancel': () => manager.resetCancel(body), 'reset-preview': () => manager.resetPreview(body), 'reset-discovery': () => manager.resetDiscovery(body), reset: () => manager.reset(body), 'own-agent': () => manager.createOwnAgent(body), 'own-agent-resume': () => manager.resumeOwnAgent(body), discovery: () => manager.beginDiscovery(body), admin: () => manager.createAdmin(body), import: () => manager.importBundle(body), existing: () => manager.importExisting(body), verify: () => manager.verifyMember(body), resume: () => manager.resume(body.id), issue: () => manager.issueBundle(body), approve: () => manager.approve(body), runner: () => manager.runner(body), 'review-rules': () => manager.setReviewRules(body) };
       const key = url.pathname.replace('/api/', ''); const action = Object.hasOwn(actions, key) ? actions[key] : null;
       if (req.method === 'POST' && url.pathname.startsWith('/api/') && action) return json(200, await manager.exclusive(action));
       return json(404, { error: '操作不存在。' });

package/apps/onboarding/startup.mjs

@@ -0,0 +1,61 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, open, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+const exec = promisify(execFile);
+const entry = fileURLToPath(new URL('./main.mjs', import.meta.url));
+const xml = (value) => String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+const unitArg = (value, expand = true) => {
+  let text = String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%');
+  if (expand) text = text.replaceAll('$', () => '$$');
+  return `"${text}"`;
+};
+export function startupDefinition({ home, platform = process.platform, userHome = homedir(), node = process.execPath, path = process.env.PATH || '/usr/bin:/bin' }) {
+  if ([home, userHome, node, path].some((value) => typeof value !== 'string' || /[\x00\r\n]/.test(value))) throw new Error('自启路径不能包含换行或空字符。');
+  const suffix = createHash('sha256').update(home).digest('hex').slice(0, 12);
+  const label = `com.codex-collab.${suffix}`;
+  const log = join(home, 'service.log');
+  if (platform === 'darwin') return { kind: 'launchd', label, path: join(userHome, 'Library/LaunchAgents', `${label}.plist`), content: `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>${label}</string><key>ProgramArguments</key><array>${[node, entry, '--home', home].map((arg) => `<string>${xml(arg)}</string>`).join('')}</array><key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict><key>ThrottleInterval</key><integer>15</integer><key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(path)}</string></dict><key>Umask</key><integer>63</integer><key>StandardOutPath</key><string>${xml(log)}</string><key>StandardErrorPath</key><string>${xml(log)}</string></dict></plist>\n` };
+  if (platform === 'linux') return { kind: 'systemd', label: `${label}.service`, path: join(userHome, '.config/systemd/user', `${label}.service`), content: `[Unit]\nDescription=Codex Collab local workspace\n[Service]\nType=simple\nExecStart=${[node, entry, '--home', home].map((arg) => unitArg(arg)).join(' ')}\nEnvironment=${unitArg(`PATH=${path}`, false)}\nRestart=on-failure\nRestartSec=15\nUMask=0077\n[Install]\nWantedBy=default.target\n` };
+  return null;
+}
+export async function configureStartup({ home, enabled = true, start = false, platform = process.platform, userHome = homedir(), execute = exec } = {}) {
+  const definition = startupDefinition({ home, platform, userHome });
+  const status = { enabled: false, supported: !!definition, kind: definition?.kind || null };
+  await mkdir(home, { recursive: true, mode: 0o700 });
+  const run = (command, args) => execute(command, args, { timeout: 10000, maxBuffer: 10000 });
+  if (definition) {
+    try {
+      if (enabled) {
+        const logPath = join(home, 'service.log');
+        const log = await open(logPath, 'a', 0o600); await log.close(); await chmod(logPath, 0o600);
+        await mkdir(dirname(definition.path), { recursive: true, mode: 0o700 });
+        await writeFile(definition.path, definition.content, { mode: 0o600 });
+        if (definition.kind === 'launchd') {
+          const domain = `gui/${process.getuid()}`;
+          if (start) {
+            try { await run('launchctl', ['bootstrap', domain, definition.path]); }
+            catch { await run('launchctl', ['kickstart', `${domain}/${definition.label}`]); }
+          }
+        } else {
+          await run('systemctl', ['--user', 'daemon-reload']);
+          await run('systemctl', ['--user', 'enable', ...(start ? ['--now'] : []), definition.label]);
+        }
+        status.enabled = true;
+      } else {
+        if (definition.kind === 'launchd') await run('launchctl', ['bootout', `gui/${process.getuid()}/${definition.label}`]).catch(() => {});
+        else await run('systemctl', ['--user', 'disable', definition.label]);
+        await rm(definition.path, { force: true });
+      }
+    } catch { status.error = '登录自启未完成。后台连接仍可使用，可运行 codex-collab autostart on 重试。'; }
+  } else if (enabled) status.error = '此系统暂不支持自动配置登录自启；本次后台服务已独立运行。';
+  await writeFile(join(home, 'startup.json'), JSON.stringify(status) + '\n', { mode: 0o600 });
+  return status;
+}
+export async function startupStatus(home) {
+  try { return JSON.parse(await readFile(join(home, 'startup.json'), 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return { enabled: false, supported: ['darwin', 'linux'].includes(process.platform) }; throw error; }
+}

package/apps/onboarding/supervisor.mjs

@@ -0,0 +1,41 @@
+import { join } from 'node:path';
+import { profiles } from './workspace.mjs';
+import { readPeerConfig } from '../peer/runtime.mjs';
+import { alive, readRunnerLock, acquireRunnerControl } from '../peer/process.mjs';
+import { readRunnerIntent, writeRunnerIntent } from '../peer/intent.mjs';
+import { savePrivate } from './manager.mjs';
+
+export class RunnerSupervisor {
+  constructor(manager, { clock = Date.now } = {}) { this.manager = manager; this.clock = clock; this.failures = new Map(); }
+  async tick() {
+    for (const profile of await profiles(this.manager.home)) {
+      if (profile.phase !== 'ready') continue;
+      const retry = this.failures.get(profile.id);
+      if (retry?.after > this.clock()) continue;
+      try {
+        const { config } = await readPeerConfig(profile.config_path);
+        const lock = await readRunnerLock(join(config.data_dir, 'runner.pid.json'));
+        let intent = await readRunnerIntent(config.data_dir);
+        // Upgrade only adopts a live connection. Previously stopped installations stay stopped.
+        if (!intent) {
+          const release = await acquireRunnerControl(config.data_dir, profile.config_path);
+          try {
+            intent = await readRunnerIntent(config.data_dir);
+            if (!intent) {
+              const current = await readRunnerLock(join(config.data_dir, 'runner.pid.json'));
+              intent = await writeRunnerIntent(config.data_dir, !!current && alive(current.pid));
+            }
+          } finally { await release(); }
+        }
+        if (!intent.enabled || lock && alive(lock.pid)) { this.failures.delete(profile.id); continue; }
+        if ([...this.manager.discovery.sessions.values()].some((session) => session.bot_id === config.wecom?.bot_id && ['connecting', 'authenticated'].includes(session.status))) continue;
+        await this.manager.runCli('recover', profile.config_path);
+        this.failures.delete(profile.id);
+      } catch {
+        const attempts = (retry?.attempts || 0) + 1;
+        this.failures.set(profile.id, { attempts, after: this.clock() + Math.min(300000, 15000 * 2 ** Math.min(attempts - 1, 5)) });
+      }
+    }
+    await savePrivate(join(this.manager.home, 'supervisor.json'), { checked_at: new Date(this.clock()).toISOString(), retrying: [...this.failures].map(([id, retry]) => ({ id, next_retry_at: new Date(retry.after).toISOString() })) });
+  }
+}