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

package/README.md

@@ -1,82 +1,105 @@
-# Code Relax Bridge（Windows 私测包）
+# Code Relax 工作站服务
 
-Bridge 让 HarmonyOS 客户端控制 Windows 上的 Codex Desktop。当前要求 Windows x64、Node >=22.12 和已登录的 Codex Desktop；npm 包不包含 Node，也不修改官方程序文件。
+Windows 与 Mac 的统一 npm 平台分发已随 beta.30 发布，普通用户无需编译原生组件。Linux x64/arm64 平台适配已加入源码，尚未随新版本发布；Ubuntu x64 的官方内核启动、依赖加载和构建已验证，真实桌面账号、钥匙环与手机收发待验收。详见 [跨平台工作站](../docs/workstation-platforms.md) 与 [npm 分发](../docs/npm-distribution.md)。
+
+工作站服务让 Android/HarmonyOS 客户端使用同一个 Codex 内核。要求 Node >=22.12；Linux 使用官方 ChatGPT 桌面版内置内核，不以独立 CLI 代替点点能力。npm 包不包含 Node 或官方桌面版，也不修改官方程序文件。
 
 ## 安装
 
-公开 beta 已发布到 npm，安装或更新使用：
-
-```powershell
-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`。
+公开 beta 已发布到 npm，安装或更新使用：
+
+```powershell
+npm i -g @walkhi/code-relax@latest --allow-scripts=@walkhi/code-relax --foreground-scripts
+```
+
+以下目录与环境变量配置说明适用于 Windows；Mac/Linux 见下方跨平台入口。首次安装前先保存工作，并从 Codex 菜单或 Windows 托盘完全退出 Codex。更新无需先停止正在运行的桌面服务；安装器会短暂停止、替换并恢复服务。npm 全局安装会自动执行 `setup` 和 Skill 安装。`setup` 将完整服务部署到 `%LOCALAPPDATA%\Programs\CodexRemote\service`，记录安装所用 Node 的绝对路径，不复制 Node。配置、日志和二维码以 `installation.json.stateRoot` 为准，通常位于 `%LOCALAPPDATA%\CodexRemote`，MSIX 环境可能解析到包缓存目录；附件位于 `%ProgramData%\CodexRemote\attachments`。
+
+`setup` 立即启动桌面服务和自动选用可用回环端口的 Codex 内核，并启用当前用户登录自启；自启不打开 Codex。Codex 内核健康后配置当前用户 `CODEX_APP_SERVER_WS_URL`，之后正常启动的 Desktop 自动接入。若安装时 Desktop 仍未接入，安装器会关闭并重新打开 Desktop；安装前应保存工作。普通更新无接入或启动链迁移需求时复用现有内核。
 
-`setup` 立即启动 Bridge 和固定 45839 受管 app-server，并启用当前用户登录自启；自启不打开 Codex。受管实例健康后配置当前用户 `CODEX_APP_SERVER_WS_URL`，之后正常启动的 Desktop 自动接入。若安装时 Desktop 仍在运行，不中断现有任务，允许两个 app-server 暂时共存，并在手机提示立即或稍后重启。
+## Linux 源码测试
 
-## Codex 内核
+公开 beta.30 尚不含 Linux，不能用上面的 registry 命令取得本轮修改。Linux 源码测试需要官方 ChatGPT 桌面版、Node >=22.12；工作站身份使用当前用户状态目录的普通 JSON，不再依赖 Secret Service。以普通用户在图形桌面会话中安装，不使用 sudo 运行 npm/relax。
+
+数据与服务位于 XDG Data 下的 `CodexRemote`，状态位于 XDG State 下；登录启动使用 `~/.config/autostart/cn.walkhi.code-relax.desktop`（遵循 XDG_CONFIG_HOME）。只为启动的 Desktop 实例设置托管地址；普通应用菜单启动不会自动继承，需使用 `relax desktop-recover --confirm` 接入。目录、自定义 CODEX_HOME、运行时更新与验收边界见 [Linux 实现](../docs/workstation-platforms.md#linux-工作站2026-10-15)。Mac 的普通配置/LaunchAgent 说明也在该文档；旧安装身份转存与失败不停服规则见[配置存储](../docs/relay-config-storage.md)。
+
+## Codex 内核
 
 ```powershell
-relax shortcuts       # 创建 Codex 内核桌面快捷方式
-relax shared-start    # Codex 内核、Desktop、Bridge
-relax start           # 启动/复用常驻 Bridge 和已配置中继
-relax pair            # 启动/复用服务并打开配对二维码
-relax status
-relax stop
+relax start           # 启动/复用桌面服务、Codex 内核和已配置的 Code Relax 中继
+relax pair            # 启动/复用服务并打开配对二维码
+relax doctor          # 查看工作站是否正常及需要处理的问题
+relax diag        # 输出供客服或技术人员使用的详细诊断报告
+relax kernel-restart --confirm # 重启内核并启用已选更新，等待新内核就绪
 ```
 
-Codex 内核由官方 `codex app-server --listen ws://127.0.0.1:45839` 提供执行服务，Desktop 和 Bridge 均可连接；它只监听回环地址。Bridge 独立报告内核健康、Desktop 接入和手机可写状态；Desktop 退出后，手机仍可操作内核中的任务。同一 thread 已被另一个实例持有时，手机只读且可重新检测。
+Codex 内核由官方 `codex app-server --listen ws://127.0.0.1:<实际端口>` 提供执行服务，Desktop 和桌面服务均可连接；它只监听回环地址。桌面服务独立报告内核健康、Desktop 接入和手机可写状态；Desktop 退出后，手机仍可操作内核中的任务。同一 thread 已被另一个实例持有时，手机只读且可重新检测。
 
-手机工作站详情可确认让 Desktop 接入 Codex 内核，独立进程逐步执行并保留 Bridge/中继连接，见[启用流程](../docs/shared-recovery.md)。本地 `shared-start` 在 Desktop 未接入受管服务时要求先自行退出 Desktop，不强制结束任务。Bridge 状态匹配且健康时直接复用；未知进程占用 45831/45839 时拒绝接管。`stop` 只停止 Bridge，不停止 Desktop 或受管 app-server。
+发现待启用内核更新时，手机“重启并更新”和 `relax kernel-restart --confirm` 复用同一受控停启流程：先验证候选，再停止旧内核，确认新内核协议就绪后恢复 Desktop，并按清单清理不再运行的旧版保留目录。手机工作站详情可确认让 Desktop 接入Codex 内核，独立进程逐步执行并保留桌面服务/中继连接，见[启用流程](../docs/shared-recovery.md)。本机恢复命令为 `relax desktop-recover --confirm`，查看恢复记录用 `relax diag`。桌面服务状态匹配且健康时直接复用；未知进程占用 Bridge 端口 45831 时拒绝接管；内核默认尝试 45839，被占用则自动选择其他回环端口，不结束占用者。
 
-受管 app-server 通过隐藏控制台启动，使后续控制台子进程继承隐藏窗口。手机的项目、任务列表和新建任务均使用受管内核，不依赖 Desktop 工具管道；项目和任务 ID 保持原生值。
+Codex 内核通过隐藏控制台启动，使后续控制台子进程继承隐藏窗口。手机的项目、任务列表和新建任务均使用Codex 内核，不依赖 Desktop 工具管道；项目和任务 ID 保持原生值。
 
-受管 app-server 未就绪时，手机停留在连接界面并显示“Codex 内核未就绪”；Bridge 保留健康和恢复接口，聊天请求返回错误。
+Codex 内核未就绪时，手机停留在连接界面并显示“Codex 内核未就绪”；桌面服务保留健康和恢复接口，聊天请求返回错误。
 
-## Code Relax 中继
+## Dots 委派任务
 
-私有中继仍需要本机 Bridge：
+`dots-tasks --json` 只读查询当前 ChatGPT 账号在托管 app-server 中的 Dots 委派任务及最近轮次状态。本机内核须已启动并登录 ChatGPT，凭据只用于工作站到官方主机的连接。任务合入 LAN 和 Code Relax 中继列表，按执行目录归入项目，标题旁显示云朵，委派正文与发送者分开显示。委派任务已接入发送/引导、停止、审批和实时事件；点点主聊天已接官方消息房间，保留独立正文与执行任务边界。当前实现与手机验证范围见 [Dots 接入](../docs/dots-integration.md)和[消息房间修复](../docs/dots-messaging-repair.md)。
+
+源码运行：
 
 ```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
+node bridge/bin/codex-remote.mjs dots-tasks --json
 ```
 
-`relay-shared-start` 先准备 Codex 内核和 Bridge，再连接公网私有中继。每台移动设备通过 `pair` 配对一次；新增设备不替换已有设备。连接器把 Windows hostname 和当前 Wi-Fi/有线网络候选经已认证 WebSocket 临时发送给手机，手机本地保存电脑名，只在设备身份验证通过后保存可达地址；服务器不持久化这些 Code Relax 中继 hostname、IP 或网络名。OpenAI 官方认证和设备配对仍直接访问 OpenAI；完成后，手机使用统一配对产生的设备凭据，通过独立元数据 WebSocket 把官方环境 ID、名称和 hostname 写入设备记录，不上传 OpenAI access token、配对码或登录态。停止连接器不撤销授权。
+构建产物使用 `node bridge/dist/bin/codex-remote.mjs dots-tasks --json`；已更新的本机全局 CLI 使用 `relax dots-tasks --json`，公共 npm 包尚未同步这项功能。任务目录归属与执行环境不同，本次托管任务携带 Windows 工作目录；协议与实读证据见 [Dots 接入](../docs/dots-integration.md)。
+
+## Code Relax 中继
 
-## Bridge 调试页面
+私有中继仍需要本机桌面服务：
 
 ```powershell
-relax dev --json
-relax dev-status --json
-relax dev-stop --json
+relax start --json
+relax pair --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 --foreground-scripts
-```
-
-`setup` 先暂存并校验新版本，再短暂停止 Bridge/中继完成切换；原服务此前正在运行时会自动恢复，新版本启动失败则回滚并启动旧版本。无需提前执行 `stop`。Node 路径变化或原 Node 被删除后需重新 setup。升级可能因 Node 可执行文件路径变化而再次触发 Windows 防火墙授权。
+```powershell
+npm i -g @walkhi/code-relax@latest --allow-scripts=@walkhi/code-relax --foreground-scripts
+```
+
+`setup` 先暂存并校验新版本，再短暂停止桌面服务/中继完成切换；原服务此前正在运行时会自动恢复，新版本启动失败则回滚并启动旧版本。无需提前停止服务。Node 路径变化或原 Node 被删除后需重新 setup。升级可能因 Node 可执行文件路径变化而再次触发 Windows 防火墙授权。
 
 卸载：
 
 ```powershell
-relax uninstall
-npm uninstall -g @walkhi/code-relax
+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，也不强制结束完整控制的执行进程。
+`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)。
+registry 默认安装使用 `@walkhi/code-relax@latest`，主 CLI 为 `relax`，并保留 `code-relax` 兼容入口。安装摘要通过 `--foreground-scripts` 显示，首次安装或启动链迁移时干净重启 Desktop，分别报告已安装与实际运行版本；登录启动使用当前用户任务计划。通信协议仍为 7。详细规则见 [npm 分发](../docs/npm-distribution.md)。
+
+### CLI 输出（2026-10-15）
+
+安装和启动成功后只显示结果与 `relax pair` 入口；配对成功显示二维码文件。`relax doctor` 报告工作站健康及实际问题，独立的 `relax diag` 默认用可读文本输出系统、Node、服务进程、逐项检查和 Desktop 接入排障记录；常规命令不再提供 `--detail`；`--json` 保留给安装器等现有程序调用。服务未运行或内核未就绪判为失败；未连接局域网只提示，不阻断中继使用。手机连通性不作为 CLI 检查项，doctor 不创建配对邀请。
+
+`doctor` 默认逐项说明安装文件、工作站服务和 Codex 内核的当前状态，问题集中给出处理方法。上次 Desktop 接入记录仅由 `diag` 读取，并明确标注排障用途；常规 `doctor` 不读取该记录，不参与当前健康判定，不拼接互相矛盾的阶段消息与最终错误。
+
+### 内核端口自动恢复（beta.43）
+
+无需手工设置端口。先复用记录中身份、监听与协议均验证通过的内核；没有可用内核时尝试上次端口／默认 45839，冲突后选择系统分配的空闲回环端口。端口抢占导致刚启动的进程退出时最多尝试五次；已启动但未就绪的内核保留身份记录，不创建第二个实例。
+
+只有进程身份、监听所有者、HTTP 就绪和 WebSocket 初始化全部通过后，才公布实际地址，并同步 Windows 当前用户的 `CODEX_APP_SERVER_WS_URL`。原值由 Code Relax 管理时自动更新；用户另行设置的值保留并明确报错。Mac/Linux 继续通过启动时环境传递实际地址，不修改 shell 配置。正常登录自启同样自动选端口。
+
+从旧版恢复可运行 `npm install -g @walkhi/code-relax@beta`，其安装流程自动部署并运行 setup；需要重试安装时运行 `relax setup`。不需要重启电脑或结束未知 PID。`relax status --json` 的 `managedAppServer.url` 显示实际地址。已经打开的终端和 Desktop 不能被外部原地修改环境；setup 沿用既有受控 Desktop 接入流程，新启动的进程使用更新后的值。
+
+实现依据与验证范围见 [动态端口审阅](../docs/managed-kernel-dynamic-port.md)。

package/dist/bin/cleanup-accounts.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHmac } from 'node:crypto';
+import mysql from 'mysql2/promise';
+import { relayDiagnostics } from '../src/self-relay/diagnostics.mjs';
+import { purgeCancelledAccounts } from '../src/self-relay/account-cleanup.mjs';
+
+const config = JSON.parse(await fs.readFile('/etc/codex-relay/mysql.json', 'utf8'));
+const account = JSON.parse(await fs.readFile('/etc/codex-relay/account.json', 'utf8'));
+if (typeof account.codePepper !== 'string' || account.codePepper.length < 32) throw new Error('Invalid account cleanup configuration');
+const pool = mysql.createPool({ ...config, connectionLimit: 1, dateStrings: true, timezone: 'Z' });
+const startedAt = Date.now();
+let stage = 'accounts';
+const diagnostics = relayDiagnostics(pool, () => console.error('Account cleanup diagnostic write failed'));
+const record = (event, detail) => diagnostics.record('account-cleanup', event, detail);
+let purged = 0;
+try {
+  await record('started', 'scheduled');
+  purged = await purgeCancelledAccounts(pool, value => createHmac('sha256', account.codePepper).update(value).digest('hex'));
+  await record('accounts-cleared', `count=${purged}`);
+  stage = 'backups';
+
+// Only deployment SQL snapshots; never follow symlinks or remove release directories.
+const root = '/opt/codex-relay/releases';
+if (await fs.realpath(root) !== root) throw new Error('Unexpected backup root');
+const files = [];
+for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+  if (entry.isDirectory() && /^deploy-\d{8}T\d{6}Z$/.test(entry.name)) {
+    files.push(path.join(root, entry.name, 'database.sql'));
+  }
+}
+// Pre-deployment snapshots observed on this installation, before the release tool existed.
+for (const directory of ['before-email-20260925', 'before-usage-20260925']) {
+  files.push(path.join(root, directory, 'code_relax.sql'));
+}
+let backups = 0;
+for (const file of files) {
+  let stat;
+  try { stat = await fs.lstat(file); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+  if (!stat.isFile() || stat.isSymbolicLink() || Date.now() - stat.mtimeMs < 86400000) continue;
+  if (await fs.realpath(file) !== file) throw new Error('Unexpected backup path');
+  await fs.unlink(file); backups++;
+}
+await record('backups-cleared', `count=${backups}`);
+stage = 'recovery-logs';
+// Rotate even on a quiet server so expired binlogs are actually purged.
+const maintenance = await mysql.createConnection({ user: 'root', socketPath: '/var/run/mysqld/mysqld.sock' });
+try {
+  const [settings] = await maintenance.query('SELECT @@GLOBAL.binlog_expire_logs_seconds AS seconds, @@GLOBAL.binlog_expire_logs_auto_purge AS autoPurge');
+  if (Number(settings[0].seconds) <= 0 || Number(settings[0].seconds) > 259200 || Number(settings[0].autoPurge) !== 1) {
+    throw new Error('MySQL recovery-log retention exceeds account cleanup policy');
+  }
+  await maintenance.query('FLUSH BINARY LOGS');
+} finally { await maintenance.end(); }
+await record('completed', `users=${purged};backups=${backups};ms=${Date.now() - startedAt}`);
+console.log(JSON.stringify({ event: 'account-cleanup', purged, expiredBackups: backups, recoveryLogsRotated: true }));
+} catch (error) {
+  // Codes and stage only: SQL errors may contain email addresses or credentials.
+  const code = String(error.code || 'operation-failed').toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 32);
+  await record('failed', `stage=${stage};code=${code}`);
+  throw error;
+} finally { await pool.end(); }