@walkhi/code-relax 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/bin/codex-remote.mjs

@@ -1,49 +1,69 @@
 #!/usr/bin/env node
 import { phonePairingSteps, desktopSetupSteps, pairingDisplayText } from '../src/onboarding.mjs';
-import { lifecycle, readRecord } from '../src/service-lifecycle.mjs';
-import { runtimePaths } from '../src/platform/windows/runtime-paths.mjs';
-import * as host from '../src/platform/windows/service-host.mjs';
+import { lifecycle, readRecord, writeRecord } from '../src/service-lifecycle.mjs';
+import { runtimePaths } from '../src/platform/runtime-paths.mjs';
+import { openFile } from '../src/platform/file-opener.mjs';
+import * as host from '../src/platform/service-host.mjs';
 import { installService, uninstallService, packageRoot } from '../src/service-install.mjs';
 import { installSkill, removeSkill, inspectSkill } from '../src/skill-install.mjs';
-import { doctor } from '../src/service-doctor.mjs';
+import { doctor, formatDoctorOutput } from '../src/service-doctor.mjs';
 import { launchDesktop } from '../src/desktop-launcher.mjs';
-import { desktopHost, desktopShortcuts, residentStartup, resolveStateRoot } from '../src/platform/windows/desktop-host.mjs';
-import { debugUi } from '../src/debug-ui.mjs';
+import { desktopHost, removeDesktopShortcut, residentStartup, resolveStateRoot } from '../src/platform/desktop-host.mjs';
 import { selfRelay } from '../src/self-relay/lifecycle.mjs';
+import { importRelayConfig } from '../src/relay-config-import.mjs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
+import { executableKey } from '../src/platform/path-identity.mjs';
 import fs from 'node:fs';
-import { spawn } from 'node:child_process';
-import { setTimeout as delay } from 'node:timers/promises';
-import { requestRecovery, recoveryStatus, recoveryWarning } from '../src/shared-recovery.mjs';
-import { configureManagedEnvironment, clearManagedEnvironment } from '../src/platform/windows/user-environment.mjs';
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { requestRecovery, recoveryWarning } from '../src/shared-recovery.mjs';
+import { configureManagedEnvironment, clearManagedEnvironment } from '../src/platform/user-environment.mjs';
+import { resolveCodexRuntime } from '../src/platform/codex-runtime.mjs';
+import { controlRequest } from '../src/service-control.mjs';
+import { processAlive } from '../src/background-process.mjs';
+import { prepareNativePackage } from '../src/platform/native-package.mjs';
+import { readManagedEndpoint } from '../src/managed-endpoint.mjs';
+import { powerConfigPath, powerEnabled } from '../src/service-power.mjs';
+import { readDotsTasks } from '../src/dots-task-catalog.mjs';
+import { installDesktopHelper, desktopHelperStatus, removeDesktopHelper } from '../src/platform/windows/desktop-helper.mjs';
 
-const help = `Code Relax（Windows）
-用法：relax <setup|doctor|skill-install|skill-remove|uninstall|start|shared-start|shortcuts|pair|status|stop> [--json]
-  setup   部署并启动固定目录服务、受管 app-server 和登录自启动；安全配置 Desktop 后续接入
-  start   启动或复用 Bridge，并恢复已配置的私有中继
-  shared-start 启动或复用 Codex 内核，再启动 Desktop、Bridge 和已配置的私有中继
-  shared-recover --confirm 重新打开 Desktop 并接入 Codex 内核；不强制重启已有内核
-  shared-recovery-status 查看最近一次恢复的实际阶段和结果
-  autostart-enable / autostart-disable / autostart-status 管理当前用户登录时启动 Bridge
-  shortcuts 创建 Codex 内核桌面快捷方式
-  pair    启动或复用工作站服务，并打开一次性配对二维码
-  status  查看服务健康状态
-  stop    停止服务
-  dev     在 Bridge 端口开启调试页面（实时读取当前源码/包资源）
-  dev-status 查看 Bridge 调试页面状态
-  dev-stop 关闭调试页面，不停止 Bridge
-  relay-start 启动或复用私有中继，已有授权直接恢复，首次授权生成二维码
-  relay-shared-start 启动 Codex 内核和 Bridge 后连接私有中继（需先退出当前 Codex）
-  relay-status 查看私有中继连接器及手机连接状态
-  relay-stop 停止私有中继连接器，不停止 Bridge 或 Codex
-  relay-revoke 撤销这台电脑的全部移动设备授权（停止连接器不会撤销授权）
-  doctor  检查安装、Node、Desktop、网络和 Skill，提示防火墙处理方式
-  skill-install 安装/更新当前用户的 Codex Skill，不覆盖自定义文件
-  skill-remove  移除本包安装且未修改的 Skill
-  uninstall 停止并移除固定目录服务和本包 Skill，清理自有 Desktop 环境变量，保留其他配置与附件
-默认监听 0.0.0.0，手机与电脑需在同一受信任局域网。
---json 输出机器可读结果；统一二维码不含 LAN 地址、Bridge Token 或中继地址。`;
+const help = `Code Relax（Windows / macOS / Linux）
+用法：relax <命令>
+常用指令：
+  start   启动或复用桌面服务和 Codex 内核，并恢复已配置的 Code Relax 中继
+  pair    启动或复用桌面服务，并打开一次性配对二维码
+  pair --expires <带时区的截止时间> 创建本工作站可重复使用的长期二维码
+  pair-list 查看本工作站长期邀请的 ID 和截止时间
+  pair-revoke <邀请ID> 废止本工作站指定长期邀请
+  devices 查看本工作站配对授权及最后连接时间
+  device-revoke <授权ID> --confirm 撤销指定配对授权
+  dots-tasks 读取当前 ChatGPT 账号的 Dots 委派任务与最近轮次状态
+维护指令：
+  setup   部署并启动桌面服务、Codex 内核和登录自启动；安全配置 Desktop 后续接入
+  setup --desktop-helper （Windows）同时安装受保护的桌面操作辅助服务，首次需要工作站 UAC 授权
+  desktop-helper-install （Windows）单独安装桌面操作辅助服务，保持现有桌面服务和 Codex 内核
+  desktop-helper-status （Windows）查看桌面操作辅助服务状态
+  desktop-helper-remove （Windows）移除桌面操作辅助服务，需要工作站 UAC 授权
+  doctor  简单检查工作站是否正常
+  diag 输出详细诊断报告，供客服或技术人员排查
+  keep-awake 默认保持电脑唤醒；查看状态
+  keep-awake on|off 开启或关闭保持唤醒，立即生效并记住选择；允许屏幕熄灭
+  kernel-restart --confirm 重启 Codex 内核并启用已选更新；等待新内核就绪
+  desktop-recover --confirm 重新打开 Desktop 并接入 Codex 内核；不强制重启已有内核
+  uninstall 停止并移除固定目录服务和本包 Skill，清理自有 Desktop 环境变量，保留其他配置与附件
+默认监听 0.0.0.0，移动端与电脑需在同一受信任局域网。
+--json 仅供安装脚本等程序调用。`;
+
+function currentNodeExecutable() {
+  const link = process.env.NVM_SYMLINK && path.join(process.env.NVM_SYMLINK, 'node.exe');
+  if (link && fs.existsSync(link)) {
+    try {
+      if (fs.realpathSync(link).toLowerCase() === fs.realpathSync(process.execPath).toLowerCase()) return link;
+    } catch {}
+  }
+  return process.execPath;
+}
 
 async function main() {
   const [command, ...flags] = process.argv.slice(2);
@@ -51,264 +71,365 @@ async function main() {
     console.log(help);
     return;
   }
-  if (!['autostart-enable', 'autostart-disable', 'autostart-status', 'shared-recover', 'shared-recovery-status', 'relay-shared-start', 'relay-revoke', 'relay-start', 'relay-status', 'relay-stop', 'dev', 'dev-status', 'dev-stop', 'setup', 'doctor', 'skill-install', 'skill-remove', 'uninstall', 'shared-start', 'shortcuts', 'start', 'pair', 'status', 'stop'].includes(command)
-    || flags.some(flag => flag !== '--json' && !(command === 'shared-recover' && flag === '--confirm'))) {
+  const options = flags.filter(flag => flag !== '--json');
+  const longPair = command === 'pair' && options.length === 2 && options[0] === '--expires';
+  const revokeInvite = command === 'pair-revoke' && options.length === 1 && /^[\w-]{16,128}$/.test(options[0]);
+  const revokeDevice = command === 'device-revoke' && options.length === 2 && /^[\w-]{16,128}$/.test(options[0]) && options[1] === '--confirm';
+  const powerCommand = command === 'keep-awake';
+  if (powerCommand && !(options.length === 0 || options.length === 1 && ['on', 'off'].includes(options[0]))) throw new Error('用法：relax keep-awake [on|off]');
+  if (!['keep-awake', 'kernel-restart', 'desktop-recover', 'setup', 'doctor', 'diag', 'uninstall', 'start', 'pair', 'pair-list', 'pair-revoke', 'devices', 'device-revoke', 'dots-tasks', 'desktop-helper-install', 'desktop-helper-status', 'desktop-helper-remove'].includes(command)
+    || (!powerCommand && !longPair && !revokeInvite && !revokeDevice && (['pair-revoke', 'device-revoke'].includes(command) || options.some(flag => !((['kernel-restart', 'desktop-recover'].includes(command) && flag === '--confirm') || (command === 'setup' && ['--desktop-helper', '--preserve-codex'].includes(flag))))))) {
     throw new Error('无效命令或参数。使用 --help 查看用法。');
   }
-  if (process.platform !== 'win32') throw new Error('当前被控端仅支持 Windows。');
+  const inviteExpires = longPair ? Date.parse(options[1]) : undefined;
+  if (longPair && (!/(Z|[+-]\d{2}:\d{2})$/.test(options[1]) || !Number.isSafeInteger(inviteExpires) || inviteExpires <= Date.now())) {
+    throw new Error('截止时间必须在未来且含时区，例如 2026-11-01T00:00:00+08:00。');
+  }
+  if (!['win32', 'darwin', 'linux'].includes(process.platform)) throw new Error('工作站目前支持 Windows、macOS 和 Linux。');
+  if (process.platform !== 'win32' && (command.startsWith('desktop-helper-') || options.includes('--desktop-helper')))
+    throw new Error('此平台不提供远程桌面画面、鼠标和键盘控制。');
+  if (command === 'desktop-recover' && desktopHost.desktopIntegration === false)
+    throw new Error('此平台的 Codex Desktop 自动接入尚未支持。');
   const json = flags.includes('--json');
+  if (['desktop-helper-install', 'desktop-helper-status', 'desktop-helper-remove'].includes(command)) {
+    const result = command === 'desktop-helper-install' ? await installDesktopHelper() : command === 'desktop-helper-remove' ? await removeDesktopHelper() : await desktopHelperStatus();
+    console.log(json ? JSON.stringify(result) : result.removed ? '桌面操作辅助服务已移除。' : result.running ? '桌面操作辅助服务已就绪，手机可按需获取画面并确认点击。' : '桌面操作辅助服务尚未就绪，请运行 relax desktop-helper-install。');
+    return;
+  }
+  if (command === 'dots-tasks') {
+    const url = readManagedEndpoint(runtimePaths().stateRoot);
+    if (!url) throw new Error('Codex 内核尚未就绪，请先运行 relax start。');
+    const result = await readDotsTasks(url);
+    const statuses = { completed: '完成', inProgress: '进行中', failed: '失败', interrupted: '已中断' };
+    console.log(json ? JSON.stringify(result) : result.tasks.length
+      ? result.tasks.map(task => `${task.title || task.id} — ${statuses[task.latestTurn?.status] || task.status || '暂无轮次'}\n${task.cwd || ''}`).join('\n\n')
+      : '当前账号没有未归档的 Dots 委派任务。');
+    return;
+  }
   const paths = runtimePaths();
   const { stateRoot, serviceRoot } = paths;
-  if (['relay-shared-start', 'relay-revoke', 'relay-start', 'relay-status', 'relay-stop'].includes(command)) {
-    if (command === 'relay-shared-start') {
-      const existing = await selfRelay('relay-status', stateRoot);
-      if (existing.running && existing.transportMode !== 'lan-shared') throw new Error('旧连接器仍在运行，请先执行 relay-stop；不会自动中断手机连接。');
-      const result = await new Promise((resolve, reject) => {
-        const child = spawn(process.execPath, [fileURLToPath(import.meta.url), 'shared-start', '--json'], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
-        let output = '', errors = '';
-        child.stdout.on('data', chunk => { output += chunk; }); child.stderr.on('data', chunk => { errors += chunk; });
-        child.once('error', reject);
-        child.once('exit', code => { if (code) reject(new Error(errors.trim().replace(/^(?:Code Relax：)+/u, '') || 'Codex 内核启动失败')); else { try { resolve(JSON.parse(output)); } catch { reject(new Error('Codex 内核启动结果无法确认，未启动中继')); } } });
-      });
-      if (!result.bridgeReady) { console.log(json ? JSON.stringify(result) : result.displayText); return; }
+  if (powerCommand) {
+    const session = readRecord(path.join(stateRoot, 'bridge-session.json'));
+    let live = false;
+    if (session?.controlPort) {
+      try { await controlRequest(session); live = true; }
+      catch (error) { if (error.code !== 'ECONNREFUSED') throw error; }
     }
-    const result = await selfRelay(command === 'relay-shared-start' ? 'relay-start' : command, stateRoot, command === 'relay-shared-start' ? 'lan-shared' : '');
-    console.log(json ? JSON.stringify(result) : `${result.displayText}${result.qrPath ? '\n二维码：' + result.qrPath : ''}`);
-    return;
-  }
-  if (['dev', 'dev-status', 'dev-stop'].includes(command)) {
-    const result = await debugUi(command, stateRoot);
-    console.log(json ? JSON.stringify(result) : result.message || JSON.stringify(result));
+    let result;
+    if (live) {
+      const action = options[0] === 'on' ? 'enable' : options[0] === 'off' ? 'disable' : 'status';
+      result = await controlRequest(session, 'POST', `keep-awake-${action}`);
+    } else {
+      if (options.length) { fs.mkdirSync(stateRoot, { recursive: true }); writeRecord(powerConfigPath(stateRoot), { enabled: options[0] === 'on' }); }
+      result = { enabled: powerEnabled(stateRoot), active: false, error: '', serviceStopped: true };
+    }
+    console.log(json ? JSON.stringify(result) : `保持唤醒：${result.enabled ? '已开启' : '已关闭'}；${result.active ? '正在生效，允许屏幕熄灭' : result.serviceStopped ? '服务未运行，下次启动应用此设置' : result.error || '未生效'}`);
+    if (result.error) process.exitCode = 1;
     return;
   }
   const installedEntry = path.join(serviceRoot, 'dist/bin/codex-remote.mjs');
-  if (['autostart-enable', 'autostart-disable', 'autostart-status', 'shared-recover', 'shared-recovery-status', 'shared-start', 'shortcuts', 'start', 'pair', 'status', 'stop'].includes(command) && path.resolve(fileURLToPath(import.meta.url)).toLowerCase() !== installedEntry.toLowerCase()) {
-    if (!fs.existsSync(installedEntry)) throw new Error('尚未部署服务，请先执行 relax setup。');
-    const executable = readRecord(path.join(serviceRoot, 'installation.json'))?.nodeExecutable;
-    if (!executable || !fs.existsSync(executable)) throw new Error('安装时选用的 Node 不存在，请重新执行 relax setup。');
+  const installationPath = path.join(serviceRoot, 'installation.json');
+  const [nodeMajor, nodeMinor] = process.versions.node.split('.').map(Number);
+  const currentNodeSupported = nodeMajor > 22 || (nodeMajor === 22 && nodeMinor >= 12);
+  const installed = executableKey(fileURLToPath(import.meta.url)) === executableKey(installedEntry);
+  const installation = readRecord(installationPath);
+  if (installation?.nodeExecutable && !fs.existsSync(installation.nodeExecutable) && currentNodeSupported
+    && ['start', 'pair', 'doctor'].includes(command)) {
+    writeRecord(installationPath, { ...installation, nodeExecutable: currentNodeExecutable() });
+  }
+  if (['kernel-restart', 'desktop-recover', 'start', 'pair', 'pair-list', 'pair-revoke', 'devices', 'device-revoke'].includes(command) && !installed) {
+    if (!fs.existsSync(installedEntry)) throw new Error('尚未部署服务，请先执行 relax setup。');
+    const executable = readRecord(installationPath)?.nodeExecutable;
+    if (!executable || !fs.existsSync(executable)) throw new Error('安装时选用的 Node 不存在，请重新执行 relax setup。');
     const child = spawn(executable, [installedEntry, command, ...flags], { stdio: 'inherit', windowsHide: true });
     const code = await new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', resolve); });
     process.exitCode = code ?? 1;
     return;
   }
-  host.migrateState(stateRoot);
-  const service = lifecycle({ stateRoot, host });
-  if (command.startsWith('autostart-')) {
-    const installation = readRecord(path.join(serviceRoot, 'installation.json'));
-    if (!installation?.nodeExecutable) throw new Error('请先执行 setup。');
-    const result = await residentStartup({ serviceRoot, nodeExecutable: installation.nodeExecutable }, command.slice('autostart-'.length));
-    console.log(json ? JSON.stringify(result) : `登录启动：${result.enabled ? '已启用' : '已关闭'}`); return;
-  }
-  if (command === 'shared-recover' || command === 'shared-recovery-status') {
-    if (command === 'shared-recover' && !flags.includes('--confirm')) throw new Error(recoveryWarning + ' 使用 --confirm 确认。');
-    const result = command === 'shared-recover'
-      ? await requestRecovery(stateRoot, { confirmed: true }) : await recoveryStatus(stateRoot);
-    console.log(json ? JSON.stringify(result) : `${result.message || result.status}${result.error ? '\n' + result.error : ''}\n${result.operationId || ''}`.trim());
-    return;
-  }
-  if (command === 'pair') {
-    let bridge = await service.status();
-    if (!bridge.running) {
-      await service.start();
-      bridge = await service.status();
-    }
-    if (!bridge.running) throw new Error('Code Relax 工作站服务未能启动。');
-    const result = await selfRelay('relay-pair', stateRoot);
-    if (!json && result.qrPath) {
-      const viewer = spawn('explorer.exe', [result.qrPath], { detached: true, stdio: 'ignore', windowsHide: true });
-      viewer.unref();
-    }
-    console.log(json ? JSON.stringify(result) : `${result.displayText}\n二维码：${result.qrPath}`);
-    return;
-  }
-  if (command === 'shortcuts') {
-    const installation = readRecord(path.join(serviceRoot, 'installation.json'));
-    if (!installation?.nodeExecutable) throw new Error('请先执行 relax setup。');
-    const shortcuts = await desktopShortcuts({ serviceRoot, nodeExecutable: installation.nodeExecutable });
-    console.log(json ? JSON.stringify({ shortcuts }) : `桌面快捷方式已创建：\n${shortcuts.join('\n')}`);
+  const service = lifecycle({ stateRoot, host });
+  const ensureAutostart = async () => {
+    const currentInstallation = readRecord(installationPath);
+    if (!currentInstallation?.nodeExecutable) throw new Error('请先执行 setup。');
+    const startup = { serviceRoot, nodeExecutable: currentInstallation.nodeExecutable };
+    const current = await residentStartup(startup, 'status');
+    if (current.enabled) return { ...current, repaired: false };
+    const result = await residentStartup(startup, 'enable');
+    return { ...result, repaired: true };
+  };
+  if (command === 'kernel-restart') {
+    if (!flags.includes('--confirm')) {
+      throw new Error('重启会立即结束当前 Codex 内核，正在运行的任务、待审批和未确认结果可能中断；恢复后不会自动重发。使用 --confirm 确认。');
+    }
+    const previous = await service.status();
+    if (!previous.running) throw new Error('桌面服务尚未运行，请先执行 relax start。');
+    await service.restartManagedAppServer(true);
+    const deadline = Date.now() + 60_000;
+    let current = await service.status();
+    while (current.managedAppServer?.restart?.status === 'running' && Date.now() < deadline) {
+      await delay(250);
+      current = await service.status();
+    }
+    if (current.managedAppServer?.restart?.status === 'failed') {
+      throw new Error(current.managedAppServer.restart.error || 'Codex 内核重启失败。');
+    }
+    if (!current.running || current.managedAppServer?.state !== 'ready'
+      || current.managedAppServer?.restart?.status !== 'completed') {
+      throw new Error('Codex 内核未在 60 秒内完成重启，请运行 relax doctor 查看状态。');
+    }
+    if (previous.managedAppServer?.updatePending && current.managedAppServer.updatePending) {
+      throw new Error('Codex 内核已重启，但更新仍未应用；请运行 relax doctor 查看状态。');
+    }
+    const result = { status: 'completed', message: previous.managedAppServer?.updatePending
+      ? 'Codex 内核已重启并应用更新。' : 'Codex 内核已重启。',
+      previousVersion: previous.managedAppServer?.version || null,
+      version: current.managedAppServer.version || null,
+      selectedVersion: current.managedAppServer.selectedVersion || null,
+      updateApplied: previous.managedAppServer?.updatePending === true,
+      updatePending: current.managedAppServer.updatePending === true,
+      pid: current.managedAppServer.pid || null,
+      executionReady: current.execution?.ready === true };
+    console.log(json ? JSON.stringify(result) : `${result.message}\n版本：${result.version || '未知'}\n执行状态：${result.executionReady ? '已就绪' : '正在恢复'}`);
     return;
   }
-  if (command === 'doctor') {
-    const result = await doctor({ paths, host, service });
-    console.log(json ? JSON.stringify(result) : result.checks.map(item => `[${item.status}] ${item.message}`).join('\n'));
-    if (!result.ready) process.exitCode = 1;
+  if (command === 'desktop-recover') {
+    if (!flags.includes('--confirm')) throw new Error(recoveryWarning + ' 使用 --confirm 确认。');
+    const result = await requestRecovery(stateRoot, { confirmed: true });
+    console.log(json ? JSON.stringify(result) : `${result.message || result.status}${result.error ? '\n' + result.error : ''}\n${result.operationId || ''}`.trim());
     return;
   }
-  if (command === 'skill-install' || command === 'skill-remove') {
-    const result = command === 'skill-install'
-      ? installSkill(path.join(packageRoot(path.dirname(fileURLToPath(import.meta.url))), 'dist/skills/code-relax/SKILL.md'))
-      : removeSkill();
-    console.log(json ? JSON.stringify(result) : `${result.message}\n${result.target}`);
-    return;
+  if (command === 'devices' || command === 'device-revoke') {
+    const result = await selfRelay(command === 'devices' ? 'devices-list' : 'device-revoke', stateRoot,
+      command === 'device-revoke' ? { id: options[0], confirmed: true } : undefined);
+    console.log(json ? JSON.stringify(result) : result.displayText); return;
   }
-  if (command === 'uninstall') {
-    const skill = inspectSkill();
-    let environment;
-    const result = await uninstallService(paths, service, async () => {
-      environment = await clearManagedEnvironment(stateRoot);
-      const installation = readRecord(path.join(serviceRoot, 'installation.json'));
-      if (installation?.nodeExecutable) await desktopShortcuts({ serviceRoot, nodeExecutable: installation.nodeExecutable }, true);
-      if (installation?.nodeExecutable) await residentStartup({ serviceRoot, nodeExecutable: installation.nodeExecutable }, 'disable');
-    });
-    result.environment = environment;
-    result.skill = skill.managed ? removeSkill() : { removed: false, message: '未移除自定义或未安装的 Skill。' };
-    result.message = environment?.preserved
-      ? '固定目录服务已卸载；检测到用户自定义的 CODEX_APP_SERVER_WS_URL，已保留。配置、附件和可能仍在执行任务的 app-server 也已保留；重启 Windows可结束该进程。npm 命令入口可再用 npm uninstall -g @walkhi/code-relax 移除。'
-      : '固定目录服务已卸载；Code Relax 设置的 app-server 环境变量已清理，其他配置、附件和可能仍在执行任务的 app-server 已保留；重启 Windows可结束该进程。npm 命令入口可再用 npm uninstall -g @walkhi/code-relax 移除。';
-    console.log(json ? JSON.stringify(result) : `${result.message}\n${result.skill.message}`);
+  if (command === 'pair-list' || command === 'pair-revoke') {
+    const result = await selfRelay(command === 'pair-list' ? 'invite-list' : 'invite-revoke', stateRoot,
+      command === 'pair-revoke' ? { id: options[0] } : undefined);
+    console.log(json ? JSON.stringify(result) : result.displayText);
     return;
   }
-  if (command === 'setup') {
-    const [major, minor] = process.versions.node.split('.').map(Number);
-    if (major < 22 || (major === 22 && minor < 12)) throw new Error('需要 Node >=22.12。');
-    const physicalStateRoot = await resolveStateRoot(stateRoot);
-    // Preserve the effective package view; never replace a newer file already in it.
-    for (const name of ['bridge-config.json', 'bridge-session.json', 'bridge-startup-context.json', 'execution-mode.json',
-      'self-relay-config.json', 'self-relay-session.json', 'lan-device-authorizations.json', 'shared-desktop.json',
-      'managed-app-server.json', 'managed-environment.json', 'shared-recovery.json', 'shared-recovery.lock', 'debug-ui-session.json']) {
-      const source = path.join(stateRoot, name), target = path.join(physicalStateRoot, name);
-      if (fs.existsSync(source) && !fs.existsSync(target)) fs.copyFileSync(source, target, fs.constants.COPYFILE_EXCL);
-    }
-    const hadInstalledService = fs.existsSync(path.join(serviceRoot, 'installation.json'));
-    const desktopBeforeSetup = await desktopHost.inspect();
-    const previous = hadInstalledService ? await service.status() : { processRunning: false };
-    const previousRelay = await selfRelay('relay-status', stateRoot);
-    const resumeAfterUpdate = previous.processRunning || previousRelay.running;
-    const executable = fs.realpathSync(process.execPath);
-    const startInstalled = async () => {
-      const entry = path.join(serviceRoot, 'dist/bin/codex-remote.mjs');
-      const child = spawn(executable, [entry, 'start', '--json'], { windowsHide: true, stdio: ['ignore', 'ignore', 'pipe'] });
-      let errors = '';
-      child.stderr.on('data', chunk => { errors += chunk; });
-      const code = await new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', resolve); });
-      if (code) {
-        try { await selfRelay('relay-stop', stateRoot); } catch {}
-        try { await service.stop(); } catch {}
-        throw new Error(errors.trim().replace(/^(?:Code Relax：)+/u, '') || 'Bridge 启动失败');
-      }
-    };
-    let stoppedForUpdate = false;
-    const installed = await installService(packageRoot(path.dirname(fileURLToPath(import.meta.url))), serviceRoot, executable, physicalStateRoot, {
-      beforeActivate: async () => {
-        stoppedForUpdate = resumeAfterUpdate;
-        if (previousRelay.running) await selfRelay('relay-stop', stateRoot);
-        if (previous.processRunning) await service.stop();
-      },
-      verifyActivation: async () => { await startInstalled(); },
-      restoreActivation: async () => { if (stoppedForUpdate) await startInstalled(); },
-    });
-    const deadline = Date.now() + 35_000;
-    let bridge = await service.status();
-    while (bridge.running && !['ready', 'failed'].includes(bridge.managedAppServer?.state) && Date.now() < deadline) {
-      await delay(250);
-      bridge = await service.status();
-    }
-    if (!bridge.running || bridge.managedAppServer?.state !== 'ready') {
-      throw new Error(bridge.managedAppServer?.error || 'Bridge 已安装，但受管 app-server 未就绪；未写入 Desktop 环境变量。');
-    }
-    let managedAppServerMigrated = false;
-    const managedAppServerMigration = {
-      required: bridge.managedAppServer.launcherRestartRequired === true,
-      restarted: false,
-      previousPid: bridge.managedAppServer.pid || null,
-    };
-    let desktopRestarted = false;
-    let desktopRestartReason = null;
-    if (managedAppServerMigration.required) {
-      const desktopInfo = await desktopHost.inspect();
-      const desktopAttached = desktopInfo.running
-        && (bridge.desktop?.attachedToManagedServer === true || Boolean(await host.sharedServiceUrl()));
-      if (desktopAttached) await desktopHost.closeDesktop(desktopInfo.desktop);
-      await service.restartManagedAppServer();
-      const migrationDeadline = Date.now() + 40_000;
-      do {
-        await delay(250);
-        bridge = await service.status();
-        if (bridge.managedAppServer?.restart?.status === 'failed') {
-          throw new Error(bridge.managedAppServer.restart.error || '受管 app-server 启动链迁移失败。');
-        }
-      } while (Date.now() < migrationDeadline && (!bridge.running || bridge.managedAppServer?.state !== 'ready' || bridge.managedAppServer.launcherRestartRequired));
-      if (!bridge.running || bridge.managedAppServer?.state !== 'ready' || bridge.managedAppServer.launcherRestartRequired) {
-        throw new Error('受管 app-server 未在 40 秒内完成启动链迁移。');
-      }
-      managedAppServerMigrated = true;
-      managedAppServerMigration.restarted = true;
-      if (desktopAttached) {
-        await launchDesktop('shared', { stateRoot: physicalStateRoot, host: desktopHost });
-        desktopRestarted = true;
-        desktopRestartReason = 'app-server-migration';
-        bridge = await service.status();
-      }
-    }
-    const autostart = await residentStartup(installed, 'enable');
-    const environment = await configureManagedEnvironment(physicalStateRoot);
-    if (!hadInstalledService && desktopBeforeSetup.running && !desktopRestarted) {
-      const currentDesktop = await desktopHost.inspect();
-      if (currentDesktop.running) await desktopHost.closeDesktop(currentDesktop.desktop);
-      await launchDesktop('shared', { stateRoot: physicalStateRoot, host: desktopHost });
-      desktopRestarted = true;
-      desktopRestartReason = 'first-install';
-      bridge = await service.status();
-    }
-    installed.autostart = autostart;
-    installed.restarted = resumeAfterUpdate;
-    installed.environment = environment;
-    installed.managedAppServer = bridge.managedAppServer;
-    installed.managedAppServerMigrated = managedAppServerMigrated;
-    installed.managedAppServerMigration = { ...managedAppServerMigration,
-      currentPid: bridge.managedAppServer.pid || null,
-      launcherRevision: bridge.managedAppServer.launcherRevision ?? null };
-    installed.desktopRestarted = desktopRestarted;
-    installed.desktopRestartReason = desktopRestartReason;
-    installed.desktop = bridge.desktop;
-    installed.desktopRestartRecommended = !desktopRestarted && bridge.desktop?.state === 'ordinary';
-    const migrationText = managedAppServerMigrated ? '已自动重建旧启动链的 app-server；安装前尚未完成的任务可能已中断。\n' : '';
-    const restartText = desktopRestarted
-      ? 'Codex Desktop 已干净重启并重新接入受管 app-server。'
-      : installed.desktopRestartRecommended
-      ? 'Codex 当前仍在使用原连接。可以在手机端选择“立即重启（推荐）”，或稍后自行完全退出再启动。'
-      : '下次正常启动 Codex 时会连接受管 app-server。';
-    console.log(json ? JSON.stringify({ ...installed, nextSteps: desktopSetupSteps, displayText: `${migrationText}${desktopSetupSteps.join('\n')}\n${restartText}` }) : `服务已安装：${installed.serviceRoot}\n使用已安装的 Node：${installed.nodeExecutable}\n受管 app-server 已就绪；首次联网可能需要 Windows 防火墙授权。\n${migrationText}${desktopSetupSteps.join('\n')}\n${restartText}`);
+  if (command === 'pair') {
+    await ensureAutostart();
+    let bridge = await service.status();
+    if (!bridge.running) {
+      await service.start();
+      bridge = await service.status();
+    }
+    if (!bridge.running) throw new Error('Code Relax 工作站服务未能启动。');
+    if (longPair) await selfRelay('relay-start', stateRoot);
+    const result = await selfRelay(longPair ? 'invite-create' : 'relay-pair', stateRoot, longPair ? { expires: inviteExpires } : undefined);
+    if (!json && result.qrPath) {
+      openFile(result.qrPath);
+    }
+    console.log(json ? JSON.stringify(result) : `配对二维码已生成。\n${result.displayText}\n二维码文件：${result.qrPath}`);
     return;
   }
-  if (command === 'stop') {
-    const result = await service.stop();
-    console.log(json ? JSON.stringify(result) : result.message);
+  if (command === 'doctor' || command === 'diag') {
+    const cliVersion = readRecord(path.join(packageRoot(path.dirname(fileURLToPath(import.meta.url))), 'package.json'))?.version;
+    const result = await doctor({ paths, host, service, ensureAutostart, cliVersion, diagnostics: command === 'diag' });
+    console.log(json ? JSON.stringify(result) : formatDoctorOutput(result, command === 'diag'));
+    if (!result.ready) process.exitCode = 1;
     return;
   }
-  let desktop;
-  if (command === 'shared-start') {
-    if (!json) console.log('正在检查 Codex 的启动模式…');
-    desktop = await launchDesktop('shared', { stateRoot, host: desktopHost });
-    delete process.env.CODEX_APP_TOOLS_PIPE_PATH;
+  if (command === 'uninstall') {
+    const desktopHelper = process.platform === 'win32' ? await removeDesktopHelper() : { removed: false, supported: false };
+    const skill = inspectSkill();
+    let environment;
+    const result = await uninstallService(paths, service, async () => {
+      environment = await clearManagedEnvironment(stateRoot);
+      const installation = readRecord(path.join(serviceRoot, 'installation.json'));
+      if (installation?.nodeExecutable) await removeDesktopShortcut({ serviceRoot, nodeExecutable: installation.nodeExecutable });
+      if (installation?.nodeExecutable) await residentStartup({ serviceRoot, nodeExecutable: installation.nodeExecutable }, 'disable');
+    });
+    result.environment = environment;
+    result.desktopHelper = desktopHelper;
+    result.skill = skill.managed ? removeSkill() : { removed: false, message: '未移除自定义或未安装的 Skill。' };
+    result.message = process.platform !== 'win32'
+      ? '固定目录服务已卸载；配置、附件、钥匙串凭据和可能仍在执行任务的 Codex 内核已保留。'
+      : environment?.preserved
+      ? '固定目录服务已卸载；检测到用户自定义的 CODEX_APP_SERVER_WS_URL，已保留。配置、附件和可能仍在执行任务的 app-server 也已保留；重启电脑可结束该进程。npm 命令入口可再用 npm uninstall -g @walkhi/code-relax 移除。'
+      : '固定目录服务已卸载；Code Relax 设置的 app-server 环境变量已清理，其他配置、附件和可能仍在执行任务的 app-server 已保留；重启电脑可结束该进程。npm 命令入口可再用 npm uninstall -g @walkhi/code-relax 移除。';
+    console.log(json ? JSON.stringify(result) : `${result.message}\n${result.skill.message}`);
+    return;
   }
-  if (!json && (desktop || command === 'start')) console.log('正在检查电脑连接并准备 Bridge…');
-  const result = await service[desktop ? 'start' : command]();
-  if (command === 'status') {
-    console.log(json ? JSON.stringify(result) : result.running
-      ? `服务正常：${result.mode}，版本 ${result.version || '未知'}，端口 ${result.port}，PID ${result.pid}` : '服务未就绪。');
+  if (command === 'setup') {
+    prepareNativePackage(packageRoot(path.dirname(fileURLToPath(import.meta.url))));
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    if (major < 22 || (major === 22 && minor < 12)) throw new Error('需要 Node >=22.12。');
+    const physicalStateRoot = await resolveStateRoot(stateRoot);
+    // Preserve the effective package view; never replace a newer file already in it.
+    for (const name of ['bridge-config.json', 'bridge-session.json', 'bridge-startup-context.json',
+      'self-relay-config.json', 'self-relay-session.json', 'lan-device-authorizations.json',
+      'managed-app-server.json', 'managed-environment.json', 'shared-recovery.json', 'shared-recovery.lock']) {
+      const source = path.join(stateRoot, name), target = path.join(physicalStateRoot, name);
+      if (fs.existsSync(source) && !fs.existsSync(target)) fs.copyFileSync(source, target, fs.constants.COPYFILE_EXCL);
+    }
+    const hadInstalledService = fs.existsSync(path.join(serviceRoot, 'installation.json'));
+    const previousInstallation = readRecord(path.join(serviceRoot, 'installation.json'));
+    await importRelayConfig(serviceRoot, physicalStateRoot, previousInstallation?.nodeExecutable);
+    if (previousInstallation?.nodeExecutable) await removeDesktopShortcut({ serviceRoot, nodeExecutable: previousInstallation.nodeExecutable });
+    const desktopBeforeSetup = desktopHost.desktopIntegration === false ? { running: false, desktop: null } : await desktopHost.inspect();
+    const runtime = await resolveCodexRuntime(physicalStateRoot, { refresh: true });
+    const preserveCodex = options.includes('--preserve-codex');
+    const desktopNeedsRestart = !hadInstalledService && desktopBeforeSetup.running && !preserveCodex;
+    const previous = hadInstalledService ? await service.status() : { processRunning: false };
+    const legacyRelaySession = readRecord(path.join(stateRoot, 'self-relay-session.json'));
+    const previousRelay = legacyRelaySession ? await controlRequest(legacyRelaySession) : await selfRelay('relay-status', stateRoot);
+    const resumeAfterUpdate = previous.processRunning || previousRelay.running;
+    const executable = currentNodeExecutable();
+    const startInstalled = async () => {
+      const entry = path.join(serviceRoot, 'dist/bin/codex-remote.mjs');
+      const child = spawn(executable, [entry, 'start', '--json'], { windowsHide: true, stdio: ['ignore', 'ignore', 'pipe'] });
+      let errors = '';
+      child.stderr.on('data', chunk => { errors += chunk; });
+      const code = await new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', resolve); });
+      try {
+        if (code !== 0) throw new Error(errors.trim().replace(/^(?:Code Relax：)+/u, '') || '桌面服务启动失败');
+        if (previousRelay.deviceId) {
+          const restoredRelay = await selfRelay('relay-status', stateRoot);
+          if (restoredRelay.deviceId !== previousRelay.deviceId ||
+              (previousRelay.relayConnected && !restoredRelay.relayConnected) ||
+              (previousRelay.paired && !restoredRelay.paired)) {
+            throw new Error('更新后未确认原工作站身份和中继授权恢复，安装未完成。');
+          }
+        }
+      } catch (error) {
+        try { await selfRelay('relay-stop', stateRoot); } catch {}
+        try { await service.stop(); } catch {}
+        throw error;
+      }
+    };
+    let stoppedForUpdate = false;
+    const installed = await installService(packageRoot(path.dirname(fileURLToPath(import.meta.url))), serviceRoot, executable, physicalStateRoot, {
+      beforeActivate: async () => {
+        stoppedForUpdate = resumeAfterUpdate;
+        if (previousRelay.running && legacyRelaySession) {
+          await controlRequest(legacyRelaySession, 'POST');
+          const deadline = Date.now() + 10000;
+          while (processAlive(legacyRelaySession.pid)) {
+            if (Date.now() >= deadline) throw new Error('旧中继进程未在 10 秒内退出。');
+            await delay(100);
+          }
+        } else if (previousRelay.running) await selfRelay('relay-stop', stateRoot);
+        if (previous.processRunning) await service.stop();
+      },
+      verifyActivation: async () => { await startInstalled(); },
+      restoreActivation: async () => { if (stoppedForUpdate) await startInstalled(); },
+    });
+    const autostart = await residentStartup(installed, 'enable');
+    const deadline = Date.now() + 35_000;
+    let bridge = await service.status();
+    while (bridge.running && !['ready', 'failed'].includes(bridge.managedAppServer?.state) && Date.now() < deadline) {
+      await delay(250);
+      bridge = await service.status();
+    }
+    if (!bridge.running || bridge.managedAppServer?.state !== 'ready') {
+      throw new Error(bridge.managedAppServer?.error || '桌面服务已安装，但 Codex 内核未就绪；未写入 Desktop 环境变量。');
+    }
+    const environment = desktopBeforeSetup.desktop
+      ? await configureManagedEnvironment(physicalStateRoot, bridge.managedAppServer.url) : { configured: false, reason: desktopHost.desktopIntegration === false ? 'desktop-integration-unsupported' : 'desktop-not-installed' };
+    let managedAppServerMigrated = false;
+    const managedAppServerMigration = {
+      required: bridge.managedAppServer.launcherRestartRequired === true || bridge.managedAppServer.updatePending === true,
+      reason: bridge.managedAppServer.updatePending ? 'runtime-update' : bridge.managedAppServer.launcherRestartRequired ? 'launcher-migration' : null,
+      restarted: false,
+      previousPid: bridge.managedAppServer.pid || null,
+      previousVersion: bridge.managedAppServer.version || null,
+    };
+    let desktopRestarted = false;
+    if (managedAppServerMigration.required && !preserveCodex) {
+      const requested = await service.restartManagedAppServer(true);
+      const operationId = requested.restart?.operationId;
+      if (!operationId) throw new Error('安装更新未取得 Codex 内核重启操作编号。');
+      const complete = () => bridge.running && bridge.managedAppServer?.state === 'ready'
+        && bridge.managedAppServer.restart?.operationId === operationId
+        && bridge.managedAppServer.restart.status === 'completed'
+        && !bridge.managedAppServer.launcherRestartRequired && !bridge.managedAppServer.updatePending;
+      const migrationDeadline = Date.now() + 60_000;
+      do {
+        await delay(250);
+        bridge = await service.status();
+        if (bridge.managedAppServer?.restart?.operationId === operationId && bridge.managedAppServer.restart.status === 'failed') {
+          throw new Error(bridge.managedAppServer.restart.error || '安装期间 Codex 内核更新失败。');
+        }
+      } while (Date.now() < migrationDeadline && !complete());
+      if (!complete()) throw new Error('安装期间 Codex 内核未在 60 秒内完成更新；未确认新内核就绪。');
+      managedAppServerMigrated = true;
+      managedAppServerMigration.restarted = true;
+    }
+    const skill = installSkill(path.join(serviceRoot, 'dist/skills/code-relax/SKILL.md'));
+    // Kernel migration already reconnects Desktop. Ordinary service updates retain it.
+    if (desktopNeedsRestart && !managedAppServerMigrated) {
+      const currentDesktop = await desktopHost.inspect();
+      if (currentDesktop.running) await desktopHost.closeDesktop(currentDesktop.desktop);
+      await launchDesktop({ stateRoot: physicalStateRoot, host: desktopHost });
+      if (!await desktopHost.desktopReady()) throw new Error('安装期间 Codex 窗口已启动，但未确认连接到工作站内核。');
+      desktopRestarted = true;
+    }
+    // Kernel restart completion can precede the next execution-health sample.
+    // Observe readiness only: never repeat installation or restart the kernel here.
+    const readinessDeadline = Date.now() + 35_000;
+    const installationReady = () => bridge.running && bridge.managedAppServer?.state === 'ready'
+      && bridge.execution?.ready === true
+      && (preserveCodex || (!bridge.managedAppServer.updatePending && !bridge.managedAppServer.launcherRestartRequired));
+    do {
+      bridge = await service.status();
+      if (installationReady()) break;
+      if (Date.now() >= readinessDeadline) {
+        const diagnostic = {
+          observedAt: new Date().toISOString(), running: bridge.running,
+          kernelState: bridge.managedAppServer?.state, kernelError: bridge.managedAppServer?.error,
+          kernelVersion: bridge.managedAppServer?.version, kernelPid: bridge.managedAppServer?.pid,
+          updatePending: bridge.managedAppServer?.updatePending,
+          launcherRestartRequired: bridge.managedAppServer?.launcherRestartRequired,
+          execution: bridge.execution, restart: bridge.managedAppServer?.restart,
+          migration: managedAppServerMigration, preserveCodex,
+        };
+        throw new Error(`安装文件已更新，但等待 35 秒后 Codex 内核更新或完整控制仍未就绪，安装未完成。状态：${JSON.stringify(diagnostic)}`);
+      }
+      await delay(250);
+    } while (true);
+    installed.autostart = autostart;
+    installed.skill = skill;
+    installed.restarted = resumeAfterUpdate;
+    installed.environment = environment;
+    installed.managedAppServer = bridge.managedAppServer;
+    installed.codexRuntime = runtime;
+    installed.managedAppServerMigrated = managedAppServerMigrated;
+    installed.managedAppServerMigration = { ...managedAppServerMigration,
+      currentPid: bridge.managedAppServer.pid || null,
+      launcherRevision: bridge.managedAppServer.launcherRevision ?? null };
+    installed.preserveCodex = preserveCodex;
+    installed.desktopRestarted = desktopRestarted;
+    installed.desktopWasRunning = desktopBeforeSetup.running;
+    installed.desktopRestartReason = desktopRestarted ? 'setup-reconnect' : null;
+    installed.desktopConnected = desktopRestarted ? true : null;
+    installed.executionReady = bridge.execution.ready;
+    if (options.includes('--desktop-helper')) installed.desktopHelper = await installDesktopHelper();
+    const migrationText = managedAppServerMigrated ? 'Codex 内核已更新并重启；请检查安装前正在进行的任务。\n' : '';
+    const displayText = `Code Relax ${installed.version} 安装成功。\n${migrationText}${desktopSetupSteps.join('\n')}`;
+    console.log(json ? JSON.stringify({ ...installed, nextSteps: desktopSetupSteps, displayText }) : displayText);
     return;
   }
-  const { accessUrl, qrPath: _legacyQrPath, ...metadata } = result;
-  const notice = '本机服务检查通过，手机连通性尚未验证。若电脑弹出 Node 网络访问提示，请先处理 Windows 防火墙授权，再用手机连接。';
-  let relay;
-  if (fs.existsSync(path.join(stateRoot, 'self-relay-config.json'))) relay = await selfRelay('relay-start', stateRoot);
-  const nextSteps = phonePairingSteps(metadata.transportMode, relay?.paired === true);
-  const displayText = pairingDisplayText(nextSteps, notice);
-  const output = { ...metadata, ...(desktop ? { desktop, bridgeReady: true } : {}), ...(relay ? { relayConnected: relay.relayConnected,
-    paired: relay.paired, clientCount: relay.clientCount, ...(relay.qrPath ? { qrPath: relay.qrPath, expiresAt: relay.expiresAt } : {}) } : {}),
-    nextSteps, displayText, mode: 'lan', listenAddress: '0.0.0.0', address: new URL(accessUrl).host,
-    lanAccess: 'unverified', notice };
+  if (!json && command === 'start') console.log('正在检查电脑连接并准备桌面服务…');
+  await ensureAutostart();
+  const result = await service[command]();
+  const { accessUrl, qrPath: _legacyQrPath, ...metadata } = result;
+  let relay;
+  if (fs.existsSync(path.join(stateRoot, 'self-relay-config.json'))) relay = await selfRelay('relay-status', stateRoot);
+  const nextSteps = phonePairingSteps(metadata.transportMode, relay?.paired === true);
+  const displayText = pairingDisplayText(nextSteps);
+  const output = { ...metadata, ...(relay ? { relayConnected: relay.relayConnected,
+    paired: relay.paired, clientCount: relay.clientCount, ...(relay.qrPath ? { qrPath: relay.qrPath, expiresAt: relay.expiresAt } : {}) } : {}),
+    nextSteps, displayText, mode: 'lan', listenAddress: '0.0.0.0', address: new URL(accessUrl).host };
   if (json) console.log(JSON.stringify(output));
   else {
-    console.log('电脑连接检查通过 · Bridge 已就绪');
-    console.log(`局域网模式：监听 0.0.0.0:${result.port}，连接地址 ${output.address}，PID ${result.pid}`);
-    if (relay?.qrPath) console.log(`配对二维码：${relay.qrPath}`);
-    console.log(displayText);
+    if (relay?.qrPath) console.log(`配对二维码：${relay.qrPath}`);
+    console.log(displayText);
   }
 }
 
 main().catch(error => {
-  console.error(`Code Relax：${error.message}`);
+  console.error(`Code Relax：${error.message}`);
   process.exitCode = 1;
 });