xuym-codex-collab 0.4.4 → 0.6.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 秒检查一次已开启的机器人进程，意外退出时恢复并在失败后退避重试；手动停止的连接保持停止。
 
 | 谁 | 在工作台做什么 | 接入后需要保留什么 |
 | --- | --- | --- |
@@ -20,6 +20,8 @@ codex-collab setup
 
 管理员先在企业微信创建**独立智能机器人**并加入协作群，再填写 Bot ID/Secret。工具通过群验证码发现群 `chatid` 和真人 `userid`，不需要成员手工寻找这些 ID、生成密钥或编辑 JSON。机器人 Secret 通过加密接入包交给指定成员；批量分配自动生成密码，可在“已分配的机器人”查看并单独复制。接入说明不含密码和 Secret。显示名称支持中文，职责可从前端、后端、全栈、测试等预设中选择；内部 ID 和自定义标签放在高级选项中。
 
+协作远程与业务基准分支自动识别；不要求 `origin/main`。有多个不同远程或默认分支不明确时，管理员选择一次。成员与新增机器人继承签名团队基准，各自可使用不同远程别名。每个新任务固定创建时的 commit，排队和重试期间不会漂移；管理员可在团队设置里为后续任务修改基准分支。
+
 同一个真人可以拥有多个 Agent，每个 Agent 使用独立机器人、签名身份、业务 clone 和 Codex 对话。管理员在项目页点击“给自己增加机器人”，验证同一个企业微信账号后自动接入，无需下载包或填写包密码；给同事分配时仍使用加密接入包，同事可以领取多份。相同 userid 不会合并 Agent 权限，审核通知会指明应使用的机器人。
 
 机器人在企业微信后台设为多人可用并加入协作群后，已批准入队的成员可以 `@` 任意团队机器人的自然语言需求；未入队的群成员仍会被工具拒绝。普通成员可提交需求、创建任务和查询状态，审核与取消、完成等控制操作继续受原有身份权限限制。接入完成后，团队成员可直接互相派发，不必再改机器人配置。
@@ -36,6 +38,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.6.0 增加任务 v3 规格：团队全员须先升级并重启工作台、Runner 与 MCP，再创建新任务；历史任务保持原规则。0.5.0 迁移时只接管仍在运行的旧连接，已停止的旧连接需要你主动启动。
+
+`codex-collab autostart off` 关闭登录自启，`autostart on` 重新设置。`setup --no-startup` 仅跳过本次自启配置，`setup --foreground` 以前台模式运行，便于排查。Windows 支持独立后台工作台，暂未自动配置登录启动。电脑休眠、关机或退出系统期间不会执行群任务；Codex 对话的自动化仍需保持启用。
+
 ## 一次任务如何接力
 
 ```mermaid

package/apps/onboarding/bundle.mjs

@@ -17,9 +17,4 @@ export function decryptBundle(value, password) {
     return JSON.parse(Buffer.concat([decipher.update(Buffer.from(value.ciphertext, 'base64')), decipher.final()]).toString('utf8'));
   } catch { throw new SetupError('接入包或密码无效，请确认文件完整且密码正确。'); }
 }
-export function remoteIdentity(remote) {
-  const scp = remote.match(/^(?:[^@/]+@)?([^:/]+):(.+)$/);
-  try { const url = new URL(remote); if (['https:', 'http:', 'ssh:'].includes(url.protocol)) return `${url.hostname.toLowerCase()}/${url.pathname.replace(/^\/+|\/+$/g, '').replace(/\.git$/, '')}`; } catch {}
-  if (scp && !remote.startsWith('/')) return `${scp[1].toLowerCase()}/${scp[2].replace(/\/+$/g, '').replace(/\.git$/, '')}`;
-  return remote;
-}
+export { remoteIdentity } from '../../packages/peer/repository.mjs';

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

@@ -1,9 +1,9 @@
+import { resolveRemote } from '../../packages/peer/repository.mjs';
 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 = {
@@ -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}`);
 }
@@ -79,7 +80,7 @@ export async function cloneRepository({ remote, destination, privateHome }) {
     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;
+      if (await git(actual, 'rev-parse', '--show-toplevel') === actual && !!await resolveRemote(actual, { expectedRemote: remote })) return actual;
     } catch { /* Reject existing unrelated folders instead of overwriting them. */ }
     throw new SetupError('目标目录已存在，请选择新的目录，或切换到使用已有项目。');
   }

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; });
+}