@walkhi/code-relax 0.1.0-beta.10 → 0.1.0-beta.11

package/README.md

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

package/dist/bin/codex-remote.mjs

@@ -7,8 +7,7 @@ import { installService, uninstallService, packageRoot } from '../src/service-in
 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';
@@ -20,30 +19,24 @@ import { configureManagedEnvironment, clearManagedEnvironment } from '../src/pla
 import { resolveCodexRuntime } from '../src/platform/windows/codex-runtime.mjs';
 
 const help = `Code Relax（Windows）
-用法：relax <setup|doctor|skill-install|skill-remove|uninstall|start|shared-start|shortcuts|pair|status|stop> [--json]
+用法：relax <setup|doctor|skill-install|skill-remove|uninstall|start|pair|status|stop> [--json]
   setup   部署并启动固定目录服务、受管 app-server 和登录自启动；安全配置 Desktop 后续接入
-  start   启动或复用 Bridge，并恢复已配置的私有中继
-  shared-start 启动或复用 Codex 内核，再启动 Desktop、Bridge 和已配置的私有中继
+  start   启动或复用 Bridge 和 Codex 内核，并恢复已配置的私有中继
   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-status 查看私有中继连接器及移动端连接状态
   relay-stop 停止私有中继连接器，不停止 Bridge 或 Codex
   relay-revoke 撤销这台电脑的全部移动设备授权（停止连接器不会撤销授权）
   doctor  检查安装、Node、Codex 内核、网络和 Skill，提示防火墙处理方式
   skill-install 安装/更新当前用户的 Codex Skill，不覆盖自定义文件
   skill-remove  移除本包安装且未修改的 Skill
   uninstall 停止并移除固定目录服务和本包 Skill，清理自有 Desktop 环境变量，保留其他配置与附件
-默认监听 0.0.0.0，手机与电脑需在同一受信任局域网。
+默认监听 0.0.0.0，移动端与电脑需在同一受信任局域网。
 --json 输出机器可读结果；统一二维码不含 LAN 地址、Bridge Token 或中继地址。`;
 
 async function main() {
@@ -52,7 +45,7 @@ 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)
+  if (!['autostart-enable', 'autostart-disable', 'autostart-status', 'shared-recover', 'shared-recovery-status', 'relay-revoke', 'relay-start', 'relay-status', 'relay-stop', 'setup', 'doctor', 'skill-install', 'skill-remove', 'uninstall', 'start', 'pair', 'status', 'stop'].includes(command)
     || flags.some(flag => flag !== '--json' && !(command === 'shared-recover' && flag === '--confirm'))) {
     throw new Error('无效命令或参数。使用 --help 查看用法。');
   }
@@ -60,30 +53,13 @@ async function main() {
   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, '') || 'Codex 内核启动失败')); else { try { resolve(JSON.parse(output)); } catch { reject(new Error('Codex 内核启动结果无法确认，未启动中继')); } } });
-      });
-      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' : '');
+  if (['relay-revoke', 'relay-start', 'relay-status', 'relay-stop'].includes(command)) {
+    const result = await selfRelay(command, stateRoot);
     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', 'shortcuts', 'start', 'pair', 'status', 'stop'].includes(command) && path.resolve(fileURLToPath(import.meta.url)).toLowerCase() !== installedEntry.toLowerCase()) {
+  if (['autostart-enable', 'autostart-disable', 'autostart-status', 'shared-recover', 'shared-recovery-status', '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。');
@@ -92,7 +68,6 @@ async function main() {
     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'));
@@ -122,13 +97,6 @@ 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 });
     console.log(json ? JSON.stringify(result) : result.checks.map(item => `[${item.status}] ${item.message}`).join('\n'));
@@ -148,7 +116,7 @@ async function main() {
     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;
@@ -164,13 +132,15 @@ 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 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();
@@ -240,7 +210,7 @@ async function main() {
       managedAppServerMigrated = true;
       managedAppServerMigration.restarted = true;
       if (desktopAttached) {
-        await launchDesktop('shared', { stateRoot: physicalStateRoot, host: desktopHost });
+        await launchDesktop({ stateRoot: physicalStateRoot, host: desktopHost });
         desktopRestarted = true;
         desktopRestartReason = 'app-server-migration';
         bridge = await service.status();
@@ -250,7 +220,7 @@ async function main() {
     if (desktopNeedsAttach && !desktopRestarted) {
       const currentDesktop = await desktopHost.inspect();
       if (currentDesktop.running) await desktopHost.closeDesktop(currentDesktop.desktop);
-      await launchDesktop('shared', { stateRoot: physicalStateRoot, host: desktopHost });
+      await launchDesktop({ stateRoot: physicalStateRoot, host: desktopHost });
       desktopRestarted = true;
       desktopRestartReason = 'attach-managed-server';
       bridge = await service.status();
@@ -269,7 +239,7 @@ async function main() {
     const migrationText = managedAppServerMigrated ? '已自动重建旧启动链的 app-server；安装前尚未完成的任务可能已中断。\n' : '';
     const restartText = desktopRestarted
       ? 'Codex Desktop 已干净重启并重新接入受管 app-server。'
-      : desktopBeforeSetup.desktop ? 'Codex Desktop 使用同一受管 app-server；手机控制不依赖 Desktop 是否打开。'
+      : desktopBeforeSetup.desktop ? 'Codex Desktop 使用同一受管 app-server；移动端控制不依赖 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}\n受管 app-server 已就绪；首次联网可能需要 Windows 防火墙授权。\n${migrationText}${desktopSetupSteps.join('\n')}\n${restartText}`);
     return;
@@ -279,26 +249,20 @@ async function main() {
     console.log(json ? JSON.stringify(result) : result.message);
     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 (!json && (desktop || command === 'start')) console.log('正在检查电脑连接并准备 Bridge…');
-  const result = await service[desktop ? 'start' : command]();
+  if (!json && command === 'start') console.log('正在检查电脑连接并准备 Bridge…');
+  const result = await service[command]();
   if (command === 'status') {
     console.log(json ? JSON.stringify(result) : result.running
       ? `服务正常：${result.mode}，版本 ${result.version || '未知'}，端口 ${result.port}，PID ${result.pid}` : '服务未就绪。');
     return;
   }
   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 };

package/dist/shared/app-server-events.cjs

@@ -1,14 +1,14 @@
 (function (root, factory) {
   if (typeof module === 'object' && module.exports) module.exports = factory();
   else root.CodexAppServerEvents = factory();
-})(globalThis, function () {
+})(globalThis, function () {
   function mergeItems(existing, incoming = []) {
     for (const source of incoming) {
       const item = compactItem(source);
       const index = existing.findIndex(current => current.id === item.id);
       if (index < 0) existing.push(item);
       else existing[index] = { ...existing[index], ...item };
-    }
+    }
     return existing;
   }
 
@@ -137,6 +137,18 @@
     }
     return match;
   }
+  function catalogThreadProjectId(thread, projects) {
+    if (thread.projectId) return thread.projectId;
+    const local = thread.environments?.find(environment => environment.environmentId === 'local');
+    if (local && Array.isArray(local.runtimeWorkspaceRoots)) {
+      for (const root of local.runtimeWorkspaceRoots) {
+        const projectId = threadProjectId({ cwd: root }, projects);
+        if (projectId) return projectId;
+      }
+      return null;
+    }
+    return threadProjectId({ cwd: thread.cwd }, projects);
+  }
   function projectlessThreadTarget(cwd = '') {
     return { projectId: null, runtimeWorkspaceRoots: [], ...(cwd ? { cwd } : {}) };
   }
@@ -289,6 +301,6 @@
     }
     return readQueue(request, threadId);
   }
-  return { createThread, readQueue, addQueue, changeQueue, compactItem, compactTurn, mergeItems, applyNotification, mergeUsage, UsageCache, readProjects, orderDesktopProjects, threadProjectId, projectlessThreadTarget, updateSettings,
+  return { createThread, readQueue, addQueue, changeQueue, compactItem, compactTurn, mergeItems, applyNotification, mergeUsage, UsageCache, readProjects, orderDesktopProjects, threadProjectId, catalogThreadProjectId, projectlessThreadTarget, updateSettings,
     permissionState, availablePermissionModes, PermissionOptionsCache, updatePermissions };
 });

package/dist/shared/file-mentions.cjs

@@ -0,0 +1,35 @@
+(function (root, factory) {
+  const api = factory();
+  if (typeof module === 'object' && module.exports) module.exports = api;
+  else root.CodexFileMentions = api;
+})(globalThis, function () {
+  const heading = '# Files mentioned by the user:';
+  const request = '## My request:';
+
+  function parse(value) {
+    const source = typeof value === 'string' ? value : '';
+    if (!source.startsWith(heading)) return { text: source, files: [] };
+    const marker = source.indexOf(`\n${request}`, heading.length);
+    if (marker < 0) return { text: source, files: [] };
+    const files = [];
+    for (const line of source.slice(heading.length, marker).split(/\r?\n/)) {
+      const match = /^## (.+): ((?:[A-Za-z]:[\\/]|\/)[^\r\n]+)$/.exec(line);
+      if (!match) continue;
+      let name = match[1];
+      if (name.startsWith('"')) {
+        try { name = JSON.parse(name); } catch { continue; }
+      }
+      if (typeof name !== 'string' || !name) continue;
+      files.push({ type: 'file', name, path: match[2] });
+    }
+    if (!files.length) return { text: source, files: [] };
+    return { text: source.slice(marker + request.length + 1).trim(), files };
+  }
+
+  function wrap(prompt, files) {
+    if (!files?.length) return prompt;
+    return `${heading}\n${files.map(file => `\n## ${JSON.stringify(file.name)}: ${file.path}\n`).join('')}\n${request}\n${prompt || '请查看上述文件。'}`;
+  }
+
+  return Object.freeze({ parse, wrap });
+});

package/dist/skills/code-relax/SKILL.md

@@ -5,7 +5,7 @@ description: 启动、检查或停止 Code Relax 工作站服务，生成并展
 
 # Code Relax
 
-- `relax start --json` 启动 Bridge 和受管 Codex 内核，无需打开 Desktop；支持纯 CLI 安装。`shared-start` 仅用于额外打开 Desktop 并接入同一内核。已配置 Code Relax 中继时，启动命令同时恢复中继连接器和已有设备授权。
+- `relax start --json` 启动 Bridge 和受管 Codex 内核，无需打开 Desktop；支持纯 CLI 安装。Desktop 正常打开后接入已配置内核；需要重新接入时使用 App 的“重启 Codex Desktop”或经确认的 `relax shared-recover --confirm`。已配置 Code Relax 中继时，启动命令同时恢复中继连接器和已有设备授权。
 - npm 全局安装会自动执行服务部署和 Skill 安装；只有修复安装时才单独运行 `relax setup --json` 或 `relax skill-install --json`。
 - `setup` 默认启用当前用户登录启动工作站服务，不自动打开 Codex；用 `autostart-status / autostart-disable / autostart-enable` 管理。恢复完整控制会保留 Bridge 和中继，但仍须明确确认可能中断全部完整控制任务。
 - 用户要求启动 Code Relax 时，执行一次 `relax start --json`。用户要求二维码或当前启动结果包含二维码时，展示 CLI 返回的 `qrPath` 和 `displayText`；没有设备授权时可用 `relax pair --json` 生成新的配对二维码。

package/dist/src/desktop-launcher.mjs

@@ -1,11 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
-import { readRecord, writeRecord } from './service-lifecycle.mjs';
+import { readRecord } from './service-lifecycle.mjs';
 import { ManagedAppServer, managedAppServerUrl as sharedUrl, managedPortAvailable as portAvailable } from './managed-app-server.mjs';
 export { portAvailable };
-export async function launchDesktop(mode, { stateRoot, host, environment = process.env, available = portAvailable, wait = delay, timeout = 30000, recoveryId, progress = () => {} }) {
-  if (mode !== 'shared') throw new Error('只支持接入 Code Relax 管理的 Codex 内核。');
+export async function launchDesktop({ stateRoot, host, environment = process.env, available = portAvailable, wait = delay, timeout = 30000, recoveryId, progress = () => {} }) {
   fs.mkdirSync(stateRoot, { recursive: true });
   const recovery = readRecord(path.join(stateRoot, 'shared-recovery.lock'));
   if (recovery && recovery.operationId !== recoveryId) throw new Error('Codex 内核正在启动，请先查看 shared-recovery-status。');
@@ -22,11 +21,8 @@ export async function launchDesktop(mode, { stateRoot, host, environment = proce
     if (!info.desktop) throw new Error('未安装 Codex Desktop，请使用 relax start 启动工作站。');
     const connected = await host.sharedServiceUrl();
     if (info.running) {
-      if ((mode === 'shared') === Boolean(connected)) {
-        writeRecord(path.join(stateRoot, 'execution-mode.json'), { mode });
-        return { reused: true, mode };
-      }
-      throw new Error('请先保存任务并完全退出 Codex Desktop，再切换模式；不会自动结束正在运行的任务。');
+      if (connected) return { reused: true };
+      throw new Error('请先保存任务并完全退出 Codex Desktop，再接入 Codex 内核；不会自动结束正在运行的任务。');
     }
     const childEnv = { ...environment };
     for (const key of ['CODEX_APP_SERVER_WS_URL', 'CODEX_APP_SERVER_FORCE_CLI', 'CODEX_APP_TOOLS_PIPE_PATH']) delete childEnv[key];
@@ -42,10 +38,9 @@ export async function launchDesktop(mode, { stateRoot, host, environment = proce
     while (true) {
       const ready = await host.sharedServiceUrl();
       if (ready) break;
-      if (Date.now() >= deadline) throw new Error('Desktop 尚未按所选模式就绪，未启动 Bridge。请查看 Desktop 窗口后重试。');
+      if (Date.now() >= deadline) throw new Error('Desktop 尚未接入 Codex 内核。请查看 Desktop 窗口后重试。');
       await wait(500);
     }
-    writeRecord(path.join(stateRoot, 'execution-mode.json'), { mode });
-    return { reused: false, mode };
+    return { reused: false };
   } finally { managed?.close(); fs.closeSync(descriptor); fs.rmSync(lock, { force: true }); }
 }

package/dist/src/file-upload-session.mjs

@@ -0,0 +1,124 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const MAX_FILE_BYTES = 20 * 1024 * 1024;
+export const MAX_FILE_COUNT = 4;
+export const MAX_TOTAL_BYTES = 40 * 1024 * 1024;
+export const FILE_CHUNK_BYTES = 256 * 1024;
+
+function validName(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 180 &&
+    value !== '.' && value !== '..' && !/[\\/:*?"<>|\x00-\x1f]/.test(value) && !/[. ]$/.test(value) &&
+    !/^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/i.test(value);
+}
+
+async function uniqueDestination(directory, name, partial) {
+  const dot = name.lastIndexOf('.');
+  const stem = dot > 0 ? name.slice(0, dot) : name;
+  const extension = dot > 0 ? name.slice(dot) : '';
+  for (let index = 0; ; index++) {
+    const suffix = index ? ` (${index})` : '';
+    const candidate = index ? `${stem.slice(0, 180 - extension.length - suffix.length)}${suffix}${extension}` : name;
+    if (!candidate || candidate.length > 180) throw new Error('同名文件过多，文件名无法继续编号');
+    const destination = path.join(directory, candidate);
+    try {
+      await fs.link(partial, destination);
+      await fs.unlink(partial);
+      return { name: candidate, path: destination };
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+    }
+  }
+}
+
+export function createFileUploadSession(root) {
+  let upload;
+  const completed = new Map();
+  let completedBytes = 0;
+  const directory = path.join(root, 'incoming');
+  const clearActive = async () => {
+    const current = upload;
+    upload = undefined;
+    if (!current) return;
+    await current.handle.close().catch(() => {});
+    await fs.unlink(current.partial).catch(() => {});
+  };
+  const clear = async () => {
+    await clearActive();
+    for (const file of completed.values()) await fs.unlink(file.path).catch(() => {});
+    completed.clear(); completedBytes = 0;
+  };
+  return {
+    async receive(message) {
+      if (!message || typeof message !== 'object') throw new Error('无效的文件上传请求');
+      if (message.type === 'cancel') { await clear(); return { type: 'cancelled' }; }
+      if (message.type === 'commit') {
+        if (upload) throw new Error('文件尚未上传完成');
+        completed.clear(); completedBytes = 0;
+        return { type: 'committed' };
+      }
+      if (message.type === 'remove') {
+        if (upload) throw new Error('请等待当前文件上传完成');
+        const file = completed.get(message.id);
+        if (!file) throw new Error('文件上传会话已失效');
+        await fs.unlink(file.path);
+        completed.delete(message.id); completedBytes -= file.size;
+        return { type: 'removed', id: message.id };
+      }
+      if (message.type === 'start') {
+        if (upload) throw new Error('已有文件正在上传');
+        if (!validName(message.name)) throw new Error('文件名无效');
+        if (!Number.isSafeInteger(message.size) || message.size < 1 || message.size > MAX_FILE_BYTES) {
+          throw new Error('单个文件不得超过 20 MiB');
+        }
+        if (completed.size >= MAX_FILE_COUNT || completedBytes + message.size > MAX_TOTAL_BYTES) {
+          throw new Error('每条消息最多 4 个文件，合计不超过 40 MiB');
+        }
+        if (!/^[a-f0-9]{64}$/i.test(message.sha256 || '')) throw new Error('文件校验值无效');
+        const id = crypto.randomUUID();
+        await fs.mkdir(directory, { recursive: true });
+        const partial = path.join(directory, `.upload-${id}`);
+        const handle = await fs.open(partial, 'wx');
+        upload = { id, partial, handle, name: message.name, size: message.size,
+          expected: message.sha256.toLowerCase(), hash: crypto.createHash('sha256'), offset: 0 };
+        return { type: 'started', id, offset: 0, chunkBytes: FILE_CHUNK_BYTES };
+      }
+      const current = upload;
+      if (!current || message.id !== current.id) throw new Error('文件上传会话已失效');
+      if (message.type === 'chunk') {
+        if (!Number.isSafeInteger(message.offset) || message.offset !== current.offset) {
+          return { type: 'offset', id: current.id, offset: current.offset };
+        }
+        if (typeof message.data !== 'string' || message.data.length > Math.ceil(FILE_CHUNK_BYTES / 3) * 4 + 4 ||
+            !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(message.data)) {
+          throw new Error('文件分片格式无效');
+        }
+        const bytes = Buffer.from(message.data, 'base64');
+        if (!bytes.length || bytes.length > FILE_CHUNK_BYTES || current.offset + bytes.length > current.size) {
+          throw new Error('文件分片大小无效');
+        }
+        await current.handle.writeFile(bytes);
+        current.hash.update(bytes);
+        current.offset += bytes.length;
+        return { type: 'offset', id: current.id, offset: current.offset };
+      }
+      if (message.type === 'finish') {
+        if (current.offset !== current.size || current.hash.digest('hex') !== current.expected) {
+          await clear(); throw new Error('文件大小或 SHA-256 校验失败');
+        }
+        await current.handle.sync();
+        await current.handle.close();
+        upload = undefined;
+        let saved;
+        try { saved = await uniqueDestination(directory, current.name, current.partial); }
+        catch (error) { await fs.unlink(current.partial).catch(() => {}); throw error; }
+        const result = { type: 'completed', id: current.id, ...saved, size: current.size };
+        completed.set(current.id, result); completedBytes += current.size;
+        return result;
+      }
+      throw new Error('不支持的文件上传操作');
+    },
+    close: clear,
+  };
+}