@walkhi/code-relax 0.1.0-beta.1

package/README.md

@@ -0,0 +1,83 @@
+# Code Relax Bridge（Windows 私测包）
+
+Bridge 让 HarmonyOS 客户端控制 Windows 上的 Codex Desktop。当前要求 Windows x64、Node >=22.12 和已登录的 Codex Desktop；npm 包不包含 Node，也不修改官方程序文件。
+
+## 安装
+
+计划发布到 npm 后在线安装；当前命令为发布占位，尚不能从 registry 执行：
+
+```powershell
+npm.cmd install -g @walkhi/code-relax@beta
+```
+
+首次安装或更新前先保存工作，并从 Codex 菜单或 Windows 托盘完全退出 Codex。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 和已配置中继
+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 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 内置页面。
+
+## 更新与卸载
+
+更新固定服务：
+
+```powershell
+npm.cmd install -g @walkhi/code-relax@beta
+```
+
+`setup` 先暂存并校验新版本，再短暂停止 Bridge/中继完成切换；原服务此前正在运行时会自动恢复，新版本启动失败则回滚并启动旧版本。无需提前执行 `stop`。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.1`，主 CLI 为 `relax`，并保留 `code-relax` 兼容入口。首次公开 beta 发布前仍需确认 npm scope 所有权、第三方许可、新电脑首次安装、防火墙、升级/卸载和移动端到端验收。详细规则见 [npm 分发](../docs/npm-distribution.md)。

package/dist/bin/codex-remote.mjs

@@ -0,0 +1,262 @@
+#!/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 { 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 { 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 { 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 { configureManagedEnvironment, clearManagedEnvironment } from '../src/platform/windows/user-environment.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
+  uninstall 停止并移除固定目录服务和本包 Skill，清理自有 Desktop 环境变量，保留其他配置与附件
+默认监听 0.0.0.0，手机与电脑需在同一受信任局域网。
+--json 输出机器可读结果；统一二维码不含 LAN 地址、Bridge Token 或中继地址。`;
+
+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'))) {
+    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()) {
+    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 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')}`);
+    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;
+    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 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 移除。';
+    console.log(json ? JSON.stringify(result) : `${result.message}\n${result.skill.message}`);
+    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 previous = fs.existsSync(serviceRoot) ? 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 环境变量。');
+    }
+    const autostart = await residentStartup(installed, 'enable');
+    const environment = await configureManagedEnvironment(physicalStateRoot);
+    installed.autostart = autostart;
+    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}` : '服务未就绪。');
+    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) 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);
+  }
+}
+
+main().catch(error => {
+  console.error(`Code Relax：${error.message}`);
+  process.exitCode = 1;
+});

package/dist/bin/self-relay-demo.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { startRelayDemo } from '../src/self-relay/demo.mjs';
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+const mode = process.argv.includes('--legacy') ? 'lan-legacy' : 'lan-shared';
+let remoteRelay;
+if (process.env.RELAY_URL) {
+  let hostKey;
+  const sshIndex = process.argv.indexOf('--ssh-host');
+  if (sshIndex !== -1) {
+    const host = process.argv[sshIndex + 1];
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(host || '')) throw new Error('Invalid SSH alias');
+    const result = spawnSync('ssh', ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', host,
+      'sudo -n cat /etc/codex-relay/host.key'], { encoding: 'utf8', timeout: 15000, windowsHide: true });
+    if (result.error || result.status !== 0) throw new Error('Cannot read relay credential through SSH');
+    hostKey = result.stdout.trim();
+  } else hostKey = fs.readFileSync(process.env.RELAY_HOST_KEY_FILE, 'utf8').trim();
+  remoteRelay = { url: process.env.RELAY_URL, hostKey };
+}
+const demo = await startRelayDemo({ mode, remoteRelay });
+let client;
+try {
+  client = demo.connect(); await client.ready;
+  const health = await client.request('/api/health');
+  if (health.status !== 200 || health.body.transportMode !== mode) throw new Error('Relay validation failed');
+  console.log(JSON.stringify({ ok: true, simulated: true, mode, relay: demo.relay.url,
+    bridge: demo.bridgeUrl, message: '中继 → 连接器 → 模拟 Bridge 已连通；未连接 Codex，未执行任务。' }, null, 2));
+  if (!process.argv.includes('--check')) {
+    console.log('验证连接保持运行。Ctrl+C 停止全部模拟进程内服务。');
+    await new Promise(resolve => { process.once('SIGINT', resolve); process.once('SIGTERM', resolve); });
+  }
+} finally { client?.close(); await demo.close(); }

package/dist/bin/self-relay-server.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { deviceStore, validId } from '../src/self-relay/device-store.mjs';
+import { startSelfRelay } from '../src/self-relay/server.mjs';
+import { updateDebugAllowlist } from '../src/self-relay/debug-allowlist.mjs';
+
+const keyFile = process.env.RELAY_HOST_KEY_FILE;
+if (!keyFile) throw new Error('RELAY_HOST_KEY_FILE is required');
+const hostKey = fs.readFileSync(keyFile, 'utf8').trim();
+const port = Number(process.env.RELAY_PORT || 45850);
+if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('Invalid RELAY_PORT');
+const stateFile = process.env.RELAY_STATE_FILE;
+if (!stateFile) throw new Error('RELAY_STATE_FILE is required');
+const debugAllowlistFile = process.env.RELAY_DEBUG_ALLOWLIST_FILE || '/etc/codex-relay/debug-allowlist.json';
+const debugCommand = process.argv.find(value => ['--debug-list', '--debug-allow', '--debug-deny'].includes(value));
+if (debugCommand) {
+  const records = deviceStore(stateFile).entries();
+  if (debugCommand === '--debug-list') {
+    console.log(JSON.stringify(records.map(record => ({
+      deviceId: record.id, status: record.status, clientCount: record.clients.length,
+    })), null, 2));
+  } else {
+    const index = process.argv.indexOf(debugCommand), deviceId = process.argv[index + 1];
+    if (!validId(deviceId)) throw new Error('Invalid device ID');
+    const record = records.find(record => record.id === deviceId && record.status === 'active');
+    if (!record && debugCommand === '--debug-allow') throw new Error('Active paired device not found');
+    updateDebugAllowlist(debugAllowlistFile, deviceId, debugCommand === '--debug-allow');
+    console.log('Debug allowlist updated; restart relay to apply.');
+  }
+  process.exit(0);
+}
+if (process.argv.includes('--init-state')) { deviceStore(stateFile, { initialize: true }); console.log('Device store initialized'); process.exit(0); }
+const revokeIndex = process.argv.indexOf('--revoke-host');
+if (revokeIndex >= 0) {
+  // Run only with the service stopped: this is an offline administrator operation.
+  if (!process.argv.includes('--offline')) throw new Error('Stop the relay service and supply --offline');
+  const id = process.argv[revokeIndex + 1];
+  if (!validId(id)) throw new Error('Invalid device ID');
+  const store = deviceStore(stateFile), record = store.entries().find(item => item.id === id);
+  if (!record) throw new Error('Device not found');
+  store.save({ ...record, status: 'revoked', clientHash: undefined, clientId: undefined, revision: record.revision + 1, updatedAt: new Date().toISOString() });
+  console.log('Computer and phone authorization revoked'); process.exit(0);
+}
+const relay = await startSelfRelay({ port, hostKey, stateFile, debugAllowlistFile,
+  publicRelayUrl: process.env.RELAY_PUBLIC_URL || '', appDownloadUrl: process.env.RELAY_APP_DOWNLOAD_URL || '',
+  log: entry => console.log(JSON.stringify({ time: new Date().toISOString(), ...entry })) });
+console.log(JSON.stringify({ service: 'codex-self-relay', listen: relay.url, maxConnections: 32,
+  maxFrameMiB: 8, encryption: 'TLS must be supplied by reverse proxy; no end-to-end encryption' }));
+await new Promise(resolve => { process.once('SIGTERM', resolve); process.once('SIGINT', resolve); });
+await relay.close();

package/dist/get-lan-networks.ps1

@@ -0,0 +1,40 @@
+[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+
+$profiles = @{}
+Get-NetConnectionProfile -ErrorAction SilentlyContinue | ForEach-Object {
+    $profiles[[int]$_.InterfaceIndex] = [string]$_.Name
+}
+
+$networks = [System.Net.NetworkInformation.NetworkInterface]::GetAllNetworkInterfaces() |
+    Where-Object {
+        $_.OperationalStatus -eq 'Up' -and
+        $_.NetworkInterfaceType -in @('Wireless80211', 'Ethernet') -and
+        $_.GetIPProperties().GatewayAddresses.Count -gt 0
+    } | ForEach-Object {
+        $adapter = $_
+        $properties = $adapter.GetIPProperties()
+        $interfaceIndex = $properties.GetIPv4Properties().Index
+        $networkType = if ($adapter.NetworkInterfaceType -eq 'Wireless80211') { 'wifi' } else { 'ethernet' }
+        $networkName = $profiles[$interfaceIndex]
+        if ($networkType -eq 'wifi') {
+            $wlan = (& netsh wlan show interfaces interface="$($adapter.Name)" 2>$null) -join "`n"
+            $ssid = [regex]::Match($wlan, '(?m)^\s*SSID\s*:\s*(.*?)\s*$')
+            if ($ssid.Success -and -not [string]::IsNullOrWhiteSpace($ssid.Groups[1].Value)) {
+                $networkName = $ssid.Groups[1].Value.Trim()
+            }
+        }
+        if ([string]::IsNullOrWhiteSpace($networkName)) { $networkName = $adapter.Name }
+        $properties.UnicastAddresses | Where-Object {
+            $_.Address.AddressFamily -eq 'InterNetwork' -and
+            $_.Address.IPAddressToString -match '^(192\.168\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|100\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])\.)'
+        } | ForEach-Object {
+            [PSCustomObject]@{
+                address = $_.Address.IPAddressToString
+                networkType = $networkType
+                networkName = $networkName
+                interfaceName = [string]$adapter.Name
+            }
+        }
+    }
+
+ConvertTo-Json -InputObject @($networks) -Compress

package/dist/get-shared-service-url.ps1

@@ -0,0 +1,6 @@
+# Detect the Desktop connection, not merely a listening standalone server.
+$connections = @(Get-NetTCPConnection -RemotePort 45839 -State Established -ErrorAction SilentlyContinue | Where-Object {
+    $_.RemoteAddress -eq '127.0.0.1' -and
+    (Get-Process -Id $_.OwningProcess -ErrorAction SilentlyContinue).ProcessName -eq 'ChatGPT'
+})
+if ($connections.Count) { 'ws://127.0.0.1:45839' }