@walkhi/code-relax 0.1.0-beta.2 → 0.1.0-beta.20

package/README.md

@@ -1,83 +1,67 @@
-# Code Relax Bridge（Windows 私测包）
-
-Bridge 让 HarmonyOS 客户端控制 Windows 上的 Codex Desktop。当前要求 Windows x64、Node >=22.12 和已登录的 Codex Desktop；npm 包不包含 Node，也不修改官方程序文件。
-
-## 安装
-
+# Code Relax 桌面服务（Windows 私测包）
+
+桌面服务让 HarmonyOS 客户端控制 Windows 上的Codex 内核。当前要求 Windows x64、Node >=22.12，以及已登录的 Codex Desktop 配套内核或独立 Codex CLI；npm 包不包含 Node，也不修改官方程序文件。
+
+## 安装
+
 公开 beta 已发布到 npm，安装或更新使用：
 
 ```powershell
-npm i -g @walkhi/code-relax@beta --allow-scripts=@walkhi/code-relax
+npm i -g @walkhi/code-relax@beta --allow-scripts=@walkhi/code-relax --foreground-scripts
 ```
 
-首次安装前先保存工作，并从 Codex 菜单或 Windows 托盘完全退出 Codex。更新无需先停止正在运行的 Bridge；安装器会短暂停止、替换并恢复服务。npm 全局安装会自动执行 `setup` 和 Skill 安装。`setup` 将完整服务部署到 `%LOCALAPPDATA%\Programs\CodexRemote\service`，记录安装所用 Node 的绝对路径，不复制 Node。配置、日志和二维码以 `installation.json.stateRoot` 为准，通常位于 `%LOCALAPPDATA%\CodexRemote`，MSIX 环境可能解析到包缓存目录；附件位于 `%ProgramData%\CodexRemote\attachments`。
-
-`setup` 立即启动 Bridge 和固定 45839 受管 app-server，并启用当前用户登录自启；自启不打开 Codex。受管实例健康后配置当前用户 `CODEX_APP_SERVER_WS_URL`，之后正常启动的 Desktop 自动接入。若安装时 Desktop 仍在运行，不中断现有任务，允许两个 app-server 暂时共存，并在手机提示立即或稍后重启。
-
-## 基础控制与完整控制
-
-```powershell
-relax shortcuts       # 创建完整控制/基础控制两个桌面快捷方式
-relax shared-start    # 完整控制、Desktop、Bridge
-relax desktop-start   # 基础控制、Desktop、Bridge
-relax start           # 启动/复用常驻 Bridge 和已配置中继
+首次安装前先保存工作，并从 Codex 菜单或 Windows 托盘完全退出 Codex。更新无需先停止正在运行的桌面服务；安装器会短暂停止、替换并恢复服务。npm 全局安装会自动执行 `setup` 和 Skill 安装。`setup` 将完整服务部署到 `%LOCALAPPDATA%\Programs\CodexRemote\service`，记录安装所用 Node 的绝对路径，不复制 Node。配置、日志和二维码以 `installation.json.stateRoot` 为准，通常位于 `%LOCALAPPDATA%\CodexRemote`，MSIX 环境可能解析到包缓存目录；附件位于 `%ProgramData%\CodexRemote\attachments`。
+
+`setup` 立即启动桌面服务和固定 45839 Codex 内核，并启用当前用户登录自启；自启不打开 Codex。Codex 内核健康后配置当前用户 `CODEX_APP_SERVER_WS_URL`，之后正常启动的 Desktop 自动接入。若安装时 Desktop 仍未接入，安装器会关闭并重新打开 Desktop；安装前应保存工作。普通更新无接入或启动链迁移需求时复用现有内核。
+
+## Codex 内核
+
+```powershell
+relax start           # 启动/复用桌面服务、Codex 内核和已配置的 Code Relax 中继
 relax pair            # 启动/复用服务并打开配对二维码
-relax status
-relax stop
-```
-
-基础控制使用普通 Desktop 工具管道。完整控制由官方 `codex app-server --listen ws://127.0.0.1:45839` 提供执行服务，Desktop 和 Bridge 同时连接；它只监听回环地址。Bridge 独立报告 app-server 健康、Desktop 接入和手机可写状态；Desktop 离线时不允许手机发起任务。同一 thread 已被另一个实例持有时，手机只读且可重新检测。
-
-手机工作站详情可确认启用完整控制，独立进程逐步执行并保留 Bridge/中继连接，见[启用流程](../docs/shared-recovery.md)。本地 `shared-start` / `desktop-start` 在控制方式不匹配时要求先自行退出 Desktop，不强制结束任务。Bridge 状态匹配且健康时直接复用；未知进程占用 45831/45839 时拒绝接管。`stop` 只停止 Bridge，不停止 Desktop 或完整控制使用的 app-server。
-
-完整控制使用的 app-server 通过隐藏控制台启动，使后续控制台子进程继承隐藏窗口。完整控制不等待 Desktop 工具管道：项目、任务列表和新建任务使用 app-server；Bridge 在后台发现工具管道并读取桌面排序、置顶信息，后续列表读取应用这些信息，项目和任务 ID 保持不变。工具通道断开后重新发现，不中断手机聊天；Desktop 页面跳转在通道就绪后可用。
-
-基础控制聊天仍依赖 Desktop 工具管道；Bridge 启动不等待管道，后台发现成功后恢复聊天能力。管道缺失或多个候选时保留管理连接并报告执行不可用，不猜测目标。
-
-## Code Relax 中继
-
-私有中继仍需要本机 Bridge：
-
-```powershell
-relax relay-shared-start --json
-relax relay-start --json
-relax relay-status --json
+relax doctor          # 集中查看服务、登录自启和最近恢复结果
+```
+
+Codex 内核由官方 `codex app-server --listen ws://127.0.0.1:45839` 提供执行服务，Desktop 和桌面服务均可连接；它只监听回环地址。桌面服务独立报告内核健康、Desktop 接入和手机可写状态；Desktop 退出后，手机仍可操作内核中的任务。同一 thread 已被另一个实例持有时，手机只读且可重新检测。
+
+手机工作站详情可确认让 Desktop 接入Codex 内核，独立进程逐步执行并保留桌面服务/中继连接，见[启用流程](../docs/shared-recovery.md)。本机恢复命令为 `relax desktop-recover --confirm`，查看恢复结果用 `relax doctor`。桌面服务状态匹配且健康时直接复用；未知进程占用 45831/45839 时拒绝接管。
+
+Codex 内核通过隐藏控制台启动，使后续控制台子进程继承隐藏窗口。手机的项目、任务列表和新建任务均使用Codex 内核，不依赖 Desktop 工具管道；项目和任务 ID 保持原生值。
+
+Codex 内核未就绪时，手机停留在连接界面并显示“Codex 内核未就绪”；桌面服务保留健康和恢复接口，聊天请求返回错误。
+
+## Code Relax 中继
+
+私有中继仍需要本机桌面服务：
+
+```powershell
+relax start --json
 relax pair --json
-relax relay-stop --json
-relax relay-revoke --json
-```
-
-`relay-shared-start` 先准备完整控制和 Bridge，再连接公网私有中继。每台移动设备通过 `pair` 配对一次；新增设备不替换已有设备。连接器把 Windows hostname 和当前 Wi-Fi/有线网络候选经已认证 WebSocket 临时发送给手机，手机本地保存电脑名，只在设备身份验证通过后保存可达地址；服务器不持久化这些 Code Relax 中继 hostname、IP 或网络名。OpenAI 官方认证和设备配对仍直接访问 OpenAI；完成后，手机使用统一配对产生的设备凭据，通过独立元数据 WebSocket 把官方环境 ID、名称和 hostname 写入设备记录，不上传 OpenAI access token、配对码或登录态。停止连接器不撤销授权。
-
-## Bridge 调试页面
-
-```powershell
-relax dev --json
-relax dev-status --json
-relax dev-stop --json
-```
-
-调试页面与 Bridge 共用进程和端口（默认 45831），只额外提供白名单静态资源，用于基础控制和完整控制的局域网页面调试。`dev-stop` 只关闭静态页面，不影响 Bridge WebSocket。Code Relax 中继和 OpenAI 中继均使用 HAP 内置页面。
-
-## 更新与卸载
-
-更新固定服务：
-
+```
+
+`start` 启动内核和桌面服务，并在桌面服务内恢复已配置中继。每台移动设备通过 `pair` 配对一次；新增设备不替换已有设备。桌面服务把 Windows hostname 和当前 Wi-Fi/有线网络候选经已认证 WebSocket 临时发送给手机，手机本地保存电脑名，只在设备身份验证通过后保存可达地址；服务器不持久化这些 Code Relax 中继 hostname、IP 或网络名。OpenAI 官方认证和设备配对仍直接访问 OpenAI；完成后，手机使用统一配对产生的设备凭据，通过独立元数据 WebSocket 把官方环境 ID、名称和 hostname 写入设备记录，不上传 OpenAI access token、配对码或登录态。
+
+桌面服务的局域网端口仅提供鉴权 WebSocket，普通 HTTP 请求返回 404；手机聊天页面随 HAP 安装。
+
+## 更新与卸载
+
+更新固定服务：
+
 ```powershell
-npm i -g @walkhi/code-relax@beta --allow-scripts=@walkhi/code-relax
+npm i -g @walkhi/code-relax@beta --allow-scripts=@walkhi/code-relax --foreground-scripts
 ```
 
-`setup` 先暂存并校验新版本，再短暂停止 Bridge/中继完成切换；原服务此前正在运行时会自动恢复，新版本启动失败则回滚并启动旧版本。无需提前执行 `stop`。Node 路径变化或原 Node 被删除后需重新 setup。升级可能因 Node 可执行文件路径变化而再次触发 Windows 防火墙授权。
-
-卸载：
-
-```powershell
+`setup` 先暂存并校验新版本，再短暂停止桌面服务/中继完成切换；原服务此前正在运行时会自动恢复，新版本启动失败则回滚并启动旧版本。无需提前停止服务。Node 路径变化或原 Node 被删除后需重新 setup。升级可能因 Node 可执行文件路径变化而再次触发 Windows 防火墙授权。
+
+卸载：
+
+```powershell
 relax uninstall
 npm uninstall -g @walkhi/code-relax
-```
-
-`uninstall` 停止 Bridge 后先核对并清理 Code Relax 所有的当前用户 `CODEX_APP_SERVER_WS_URL`；用户后来修改或不归属 Code Relax 的值会保留。随后删除固定程序和本包管理且未修改的 Skill；保留其他配置、Token、日志、长期设备凭据、附件和自定义 Skill。它不卸载 Node、Codex Desktop，也不强制结束完整控制的执行进程。
-
-## 发布边界
-
-当前包名为 `@walkhi/code-relax@0.1.0-beta.2`，主 CLI 为 `relax`，并保留 `code-relax` 兼容入口。当前已完成 npm scope 发布和本机 registry 在线安装；本版修复了另一台电脑首次安装时的 Windows broker 交接超时，仍需在原电脑复核。详细规则见 [npm 分发](../docs/npm-distribution.md)。
+```
+
+`uninstall` 停止桌面服务后先核对并清理 Code Relax 所有的当前用户 `CODEX_APP_SERVER_WS_URL`；用户后来修改或不归属 Code Relax 的值会保留。随后删除固定程序和本包管理且未修改的 Skill；保留其他配置、Token、日志、长期设备凭据、附件和自定义 Skill。它不卸载 Node、Codex Desktop，也不强制结束完整控制的执行进程。
+
+## 发布边界
+
+registry 测试包使用 `@walkhi/code-relax@beta`，主 CLI 为 `relax`，并保留 `code-relax` 兼容入口。安装摘要通过 `--foreground-scripts` 显示，首次安装或启动链迁移时干净重启 Desktop，分别报告已安装与实际运行版本；登录启动使用当前用户任务计划。通信协议仍为 7。详细规则见 [npm 分发](../docs/npm-distribution.md)。

package/dist/bin/codex-remote.mjs

@@ -1,113 +1,99 @@
 #!/usr/bin/env node
 import { phonePairingSteps, desktopSetupSteps, pairingDisplayText } from '../src/onboarding.mjs';
-import { lifecycle, readRecord } from '../src/service-lifecycle.mjs';
+import { lifecycle, readRecord, writeRecord } 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 { installService, uninstallService, packageRoot } from '../src/service-install.mjs';
-import { installSkill, removeSkill, inspectSkill } from '../src/skill-install.mjs';
+import { installSkill, removeSkill, inspectSkill } from '../src/skill-install.mjs';
 import { doctor } 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/windows/desktop-host.mjs';
 import { selfRelay } from '../src/self-relay/lifecycle.mjs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 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 { requestRecovery, recoveryWarning } from '../src/shared-recovery.mjs';
 import { configureManagedEnvironment, clearManagedEnvironment } from '../src/platform/windows/user-environment.mjs';
+import { resolveCodexRuntime } from '../src/platform/windows/codex-runtime.mjs';
+import { controlRequest } from '../src/service-control.mjs';
+import { processAlive } from '../src/background-process.mjs';
 
 const help = `Code Relax（Windows）
-用法：relax <setup|doctor|skill-install|skill-remove|uninstall|start|shared-start|desktop-start|shortcuts|pair|status|stop> [--json]
-  setup   部署并启动固定目录服务、受管 app-server 和登录自启动；安全配置 Desktop 后续接入
-  start   启动或复用 Bridge，并恢复已配置的私有中继
-  shared-start 启动或复用完整控制，再启动 Bridge 和已配置的私有中继
-  shared-recover --confirm 启用或重新启动完整控制，保留 Bridge 和中继，可能中断当前任务
-  shared-recovery-status 查看最近一次恢复的实际阶段和结果
-  autostart-enable / autostart-disable / autostart-status 管理当前用户登录时启动 Bridge
-  desktop-start 恢复基础控制，再启动 Bridge（切换前须自行退出 Desktop）
-  shortcuts 创建完整控制/基础控制桌面快捷方式
-  pair    启动或复用工作站服务，并打开一次性配对二维码
-  status  查看服务健康状态
-  stop    停止服务
-  dev     在 Bridge 端口开启调试页面（实时读取当前源码/包资源）
-  dev-status 查看 Bridge 调试页面状态
-  dev-stop 关闭调试页面，不停止 Bridge
-  relay-start 启动或复用私有中继，已有授权直接恢复，首次授权生成二维码
-  relay-shared-start 启动完整控制和 Bridge 后连接私有中继（需先退出当前 Codex）
-  relay-status 查看私有中继连接器及手机连接状态
-  relay-stop 停止私有中继连接器，不停止 Bridge 或 Codex
-  relay-revoke 撤销这台电脑的全部移动设备授权（停止连接器不会撤销授权）
-  doctor  检查安装、Node、Desktop、网络和 Skill，提示防火墙处理方式
-  skill-install 安装/更新当前用户的 Codex Skill，不覆盖自定义文件
-  skill-remove  移除本包安装且未修改的 Skill
+用法：relax <命令> [--json]；下列命令均可用
+常用指令：
+  start   启动或复用桌面服务和 Codex 内核，并恢复已配置的 Code Relax 中继
+  pair    启动或复用桌面服务，并打开一次性配对二维码
+维护指令：
+  setup   部署并启动桌面服务、Codex 内核和登录自启动；安全配置 Desktop 后续接入
+  doctor  检查服务、登录自启、最近恢复结果、网络和 Skill
+  desktop-recover --confirm 重新打开 Desktop 并接入 Codex 内核；不强制重启已有内核
   uninstall 停止并移除固定目录服务和本包 Skill，清理自有 Desktop 环境变量，保留其他配置与附件
-默认监听 0.0.0.0，手机与电脑需在同一受信任局域网。
---json 输出机器可读结果；统一二维码不含 LAN 地址、Bridge Token 或中继地址。`;
+默认监听 0.0.0.0，移动端与电脑需在同一受信任局域网。
+--json 输出机器可读结果；统一二维码不含 LAN 地址、桌面服务凭据或中继地址。`;
+
+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() {
+async function main() {
   const [command, ...flags] = process.argv.slice(2);
   if (!command || command === '--help' || command === '-h') {
     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', 'desktop-start', 'shortcuts', 'start', 'pair', 'status', 'stop'].includes(command)
-    || flags.some(flag => flag !== '--json' && !(command === 'shared-recover' && flag === '--confirm'))) {
+  if (!['desktop-recover', 'setup', 'doctor', 'uninstall', 'start', 'pair'].includes(command)
+    || flags.some(flag => flag !== '--json' && !(command === 'desktop-recover' && flag === '--confirm'))) {
     throw new Error('无效命令或参数。使用 --help 查看用法。');
   }
   if (process.platform !== 'win32') throw new Error('当前被控端仅支持 Windows。');
   const json = flags.includes('--json');
   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, '') || '完整控制启动失败')); else { try { resolve(JSON.parse(output)); } catch { reject(new Error('完整控制启动结果无法确认，未启动中继')); } } });
-      });
-      if (!result.bridgeReady) { console.log(json ? JSON.stringify(result) : result.displayText); return; }
-    }
-    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));
-    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', 'desktop-start', 'shortcuts', 'start', 'pair', 'status', 'stop'].includes(command) && path.resolve(fileURLToPath(import.meta.url)).toLowerCase() !== installedEntry.toLowerCase()) {
+  const { stateRoot, serviceRoot } = paths;
+  const installedEntry = path.join(serviceRoot, 'dist/bin/codex-remote.mjs');
+  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 = path.resolve(fileURLToPath(import.meta.url)).toLowerCase() === installedEntry.toLowerCase();
+  const installation = readRecord(installationPath);
+  if (installation?.nodeExecutable && !fs.existsSync(installation.nodeExecutable) && currentNodeSupported
+    && ['start', 'pair', 'doctor'].includes(command)) {
+    writeRecord(installationPath, { ...installation, nodeExecutable: currentNodeExecutable() });
+  }
+  if (['desktop-recover', 'start', 'pair'].includes(command) && !installed) {
     if (!fs.existsSync(installedEntry)) throw new Error('尚未部署服务，请先执行 relax setup。');
-    const executable = readRecord(path.join(serviceRoot, 'installation.json'))?.nodeExecutable;
+    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);
+  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 === '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 === 'pair') {
+    await ensureAutostart();
     let bridge = await service.status();
     if (!bridge.running) {
       await service.start();
@@ -122,40 +108,26 @@ async function main() {
     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')}`);
-    return;
-  }
   if (command === 'doctor') {
-    const result = await doctor({ paths, host, service });
+    const result = await doctor({ paths, host, service, ensureAutostart });
     console.log(json ? JSON.stringify(result) : result.checks.map(item => `[${item.status}] ${item.message}`).join('\n'));
     if (!result.ready) process.exitCode = 1;
     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 === '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 removeDesktopShortcut({ serviceRoot, nodeExecutable: installation.nodeExecutable });
       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，已保留。配置、附件也已保留。npm 命令入口可再用 npm uninstall -g @walkhi/code-relax 移除。'
-      : '固定目录服务已卸载；Code Relax 设置的 app-server 环境变量已清理，其他配置和附件已保留。npm 命令入口可再用 npm uninstall -g @walkhi/code-relax 移除。';
+      ? '固定目录服务已卸载；检测到用户自定义的 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}`);
     return;
   }
@@ -164,16 +136,23 @@ async function main() {
     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']) {
+    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 previous = fs.existsSync(serviceRoot) ? await service.status() : { processRunning: false };
-    const previousRelay = await selfRelay('relay-status', stateRoot);
+    const hadInstalledService = fs.existsSync(path.join(serviceRoot, 'installation.json'));
+    const previousInstallation = readRecord(path.join(serviceRoot, 'installation.json'));
+    if (previousInstallation?.nodeExecutable) await removeDesktopShortcut({ serviceRoot, nodeExecutable: previousInstallation.nodeExecutable });
+    const desktopBeforeSetup = await desktopHost.inspect();
+    const runtime = await resolveCodexRuntime(physicalStateRoot, { refresh: true });
+    const desktopNeedsAttach = desktopBeforeSetup.running && !await host.sharedServiceUrl();
+    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 = fs.realpathSync(process.execPath);
+    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'] });
@@ -183,19 +162,28 @@ async function main() {
       if (code) {
         try { await selfRelay('relay-stop', stateRoot); } catch {}
         try { await service.stop(); } catch {}
-        throw new Error(errors.trim().replace(/^(?:Code Relax：)+/u, '') || 'Bridge 启动失败');
+        throw new Error(errors.trim().replace(/^(?:Code Relax：)+/u, '') || '桌面服务启动失败');
       }
     };
     let stoppedForUpdate = false;
     const installed = await installService(packageRoot(path.dirname(fileURLToPath(import.meta.url))), serviceRoot, executable, physicalStateRoot, {
       beforeActivate: async () => {
+        if (desktopNeedsAttach) await desktopHost.closeDesktop(desktopBeforeSetup.desktop);
         stoppedForUpdate = resumeAfterUpdate;
-        if (previousRelay.running) await selfRelay('relay-stop', stateRoot);
+        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) {
@@ -203,53 +191,89 @@ async function main() {
       bridge = await service.status();
     }
     if (!bridge.running || bridge.managedAppServer?.state !== 'ready') {
-      throw new Error(bridge.managedAppServer?.error || 'Bridge 已安装，但受管 app-server 未就绪；未写入 Desktop 环境变量。');
+      throw new Error(bridge.managedAppServer?.error || '桌面服务已安装，但 Codex 内核未就绪；未写入 Desktop 环境变量。');
+    }
+    const environment = desktopBeforeSetup.desktop
+      ? await configureManagedEnvironment(physicalStateRoot) : { configured: false, reason: 'desktop-not-installed' };
+    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 || 'Codex 内核启动链迁移失败。');
+        }
+      } 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('Codex 内核未在 40 秒内完成启动链迁移。');
+      }
+      managedAppServerMigrated = true;
+      managedAppServerMigration.restarted = true;
+      if (desktopAttached) {
+        await launchDesktop({ stateRoot: physicalStateRoot, host: desktopHost });
+        desktopRestarted = true;
+        desktopRestartReason = 'app-server-migration';
+        bridge = await service.status();
+      }
+    }
+    const skill = installSkill(path.join(serviceRoot, 'dist/skills/code-relax/SKILL.md'));
+    if (desktopNeedsAttach && !desktopRestarted) {
+      const currentDesktop = await desktopHost.inspect();
+      if (currentDesktop.running) await desktopHost.closeDesktop(currentDesktop.desktop);
+      await launchDesktop({ stateRoot: physicalStateRoot, host: desktopHost });
+      desktopRestarted = true;
+      desktopRestartReason = 'attach-managed-server';
+      bridge = await service.status();
     }
-    const autostart = await residentStartup(installed, 'enable');
-    const environment = await configureManagedEnvironment(physicalStateRoot);
     installed.autostart = autostart;
+    installed.skill = skill;
     installed.restarted = resumeAfterUpdate;
     installed.environment = environment;
     installed.managedAppServer = bridge.managedAppServer;
-    installed.desktop = bridge.desktop;
-    installed.desktopRestartRecommended = bridge.desktop?.state === 'ordinary';
-    const restartText = installed.desktopRestartRecommended
-      ? 'Codex 当前仍在使用原连接。可以在手机端选择“立即重启（推荐）”，或稍后自行完全退出再启动。'
-      : '下次正常启动 Codex 时会连接受管 app-server。';
-    console.log(json ? JSON.stringify({ ...installed, nextSteps: desktopSetupSteps, displayText: `${desktopSetupSteps.join('\n')}\n${restartText}` }) : `服务已安装：${installed.serviceRoot}\n使用已安装的 Node：${installed.nodeExecutable}\n受管 app-server 已就绪；首次联网可能需要 Windows 防火墙授权。\n${desktopSetupSteps.join('\n')}\n${restartText}`);
-    return;
-  }
-  if (command === 'stop') {
-    const result = await service.stop();
-    console.log(json ? JSON.stringify(result) : result.message);
-    return;
-  }
-  let desktop;
-  if (command === 'shared-start' || command === 'desktop-start') {
-    if (!json) console.log('正在检查 Codex 的启动模式…');
-    desktop = await launchDesktop(command === 'shared-start' ? 'shared' : 'ordinary', { stateRoot, host: desktopHost });
-    delete process.env.CODEX_APP_TOOLS_PIPE_PATH;
-  }
-  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.port}，PID ${result.pid}` : '服务未就绪。');
+    installed.codexRuntime = runtime;
+    installed.managedAppServerMigrated = managedAppServerMigrated;
+    installed.managedAppServerMigration = { ...managedAppServerMigration,
+      currentPid: bridge.managedAppServer.pid || null,
+      launcherRevision: bridge.managedAppServer.launcherRevision ?? null };
+    installed.desktopRestarted = desktopRestarted;
+    installed.desktopRestartReason = desktopRestartReason;
+    const migrationText = managedAppServerMigrated ? '已自动重建旧启动链的 app-server；安装前尚未完成的任务可能已中断。\n' : '';
+    const restartText = desktopRestarted
+      ? 'Codex Desktop 已干净重启并重新接入 Codex 内核。'
+      : desktopBeforeSetup.desktop ? 'Codex Desktop 使用同一 Codex 内核；移动端控制不依赖 Desktop 是否打开。'
+      : '使用独立 Codex CLI；无需安装 Codex Desktop。';
+    console.log(json ? JSON.stringify({ ...installed, nextSteps: desktopSetupSteps, displayText: `${migrationText}${desktopSetupSteps.join('\n')}\n${restartText}` }) : `桌面服务已安装：${installed.serviceRoot}\n使用已安装的 Node：${installed.nodeExecutable}\nCodex 内核已就绪；首次联网可能需要 Windows 防火墙授权。\n${migrationText}${desktopSetupSteps.join('\n')}\n${restartText}`);
     return;
   }
+  if (!json && command === 'start') console.log('正在检查电脑连接并准备桌面服务…');
+  await ensureAutostart();
+  const result = await service[command]();
   const { accessUrl, qrPath: _legacyQrPath, ...metadata } = result;
-  const notice = '本机服务检查通过，手机连通性尚未验证。若电脑弹出 Node 网络访问提示，请先处理 Windows 防火墙授权，再用手机连接。';
+  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,
+  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,
     lanAccess: 'unverified', notice };
   if (json) console.log(JSON.stringify(output));
   else {
-    console.log('电脑连接检查通过 · Bridge 已就绪');
+    console.log('电脑连接检查通过 · 桌面服务已就绪');
     console.log(`局域网模式：监听 0.0.0.0:${result.port}，连接地址 ${output.address}，PID ${result.pid}`);
     if (relay?.qrPath) console.log(`配对二维码：${relay.qrPath}`);
     console.log(displayText);

package/dist/bin/manage-relay-admin.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import mysql from 'mysql2/promise';
+
+const path = process.env.RELAY_MYSQL_CONFIG_FILE;
+const action = process.argv[2];
+const email = (process.argv[3] || '').trim().toLowerCase();
+if (!path || !['--grant', '--revoke', '--list'].includes(action) ||
+    (action !== '--list' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))) {
+  throw new Error('Use --grant EMAIL, --revoke EMAIL or --list with RELAY_MYSQL_CONFIG_FILE');
+}
+const db = await mysql.createConnection({ ...JSON.parse(fs.readFileSync(path, 'utf8')),
+  dateStrings: true, timezone: 'Z', multipleStatements: false });
+try {
+  if (action === '--grant') await db.execute(`INSERT INTO relay_admin_emails (email,granted_at)
+    VALUES (?,UTC_TIMESTAMP(3)) ON DUPLICATE KEY UPDATE email=VALUES(email)`, [email]);
+  else if (action === '--revoke') await db.execute('DELETE FROM relay_admin_emails WHERE email=?', [email]);
+  const [rows] = await db.query('SELECT email FROM relay_admin_emails ORDER BY email');
+  console.log(JSON.stringify({ admins: rows.map(row => row.email) }));
+} finally { await db.end(); }