@walkhi/code-relax 0.1.0-beta.1 → 0.1.0-beta.100

package/dist/src/managed-endpoint.mjs

@@ -0,0 +1,25 @@
+import path from 'node:path';
+import { readRecord } from './service-lifecycle.mjs';
+
+export const defaultManagedPort = 45839;
+export function managedEndpointUrl(value) {
+  if (typeof value !== 'string' || !/^ws:\/\/127\.0\.0\.1:[1-9][0-9]{0,4}$/.test(value)) return null;
+  const port = Number(value.slice(value.lastIndexOf(':') + 1));
+  return port <= 65535 ? `ws://127.0.0.1:${port}` : null;
+}
+export function managedProcessUrl(record) {
+  if (!record) return null;
+  let value;
+  if (Array.isArray(record.args)) {
+    if (record.args.length !== 4 || record.args[1] !== 'app-server' || record.args[2] !== '--listen') return null;
+    value = record.args[3];
+  } else {
+    const match = /^\s*(?:"[^"]+"|\S+)\s+app-server\s+--listen\s+(?:"(ws:\/\/127\.0\.0\.1:[0-9]+)"|(ws:\/\/127\.0\.0\.1:[0-9]+))\s*$/i.exec(record.command || '');
+    value = match?.[1] || match?.[2];
+  }
+  const url = managedEndpointUrl(value);
+  return url && (!record.url || record.url === url) ? url : null;
+}
+export function readManagedEndpoint(stateRoot) {
+  return managedProcessUrl(readRecord(path.join(stateRoot, 'managed-app-server.json')));
+}

package/dist/src/message-images.mjs

@@ -1,8 +1,3 @@
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import crypto from 'node:crypto';
-import sharp from 'sharp';
-
 export function validateInlineImage(value) {
   const data = typeof value === 'string' ? value.slice(value.indexOf(',') + 1) : '';
   if (typeof value !== 'string' || value.length > Math.ceil(8 * 1024 * 1024 / 3) * 4 + 64 ||
@@ -12,16 +7,3 @@ export function validateInlineImage(value) {
   }
   return value;
 }
-
-// Only the Desktop tool compatibility path needs a file visible to the host.
-export async function persistLegacyImage(value, directory) {
-  validateInlineImage(value);
-  const input = Buffer.from(value.slice(value.indexOf(',') + 1), 'base64');
-  const buffer = await sharp(input, { limitInputPixels: 40_000_000 }).rotate()
-    .resize({ width: 2560, height: 2560, fit: 'inside', withoutEnlargement: true }).webp({ quality: 88 }).toBuffer();
-  const id = crypto.createHash('sha256').update(buffer).digest('hex');
-  await fs.mkdir(directory, { recursive: true });
-  const file = path.join(directory, `${id}.webp`);
-  await fs.writeFile(file, buffer);
-  return file;
-}

package/dist/src/message-upload-files.mjs

@@ -0,0 +1,111 @@
+import fs from 'node:fs/promises';
+import { openAsBlob } from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+import media from '../shared/code-browser.cjs';
+import { validateInlineImage } from './message-images.mjs';
+import { createFileUploadSession, FILE_CHUNK_BYTES, MAX_FILE_COUNT } from './file-upload-session.mjs';
+import { fileRevision } from './file-transfer-range.mjs';
+
+const mimeTypes = { pdf: 'application/pdf', txt: 'text/plain', md: 'text/markdown', csv: 'text/csv',
+  json: 'application/json', zip: 'application/zip', doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel', xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint', pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation' };
+
+// Reuse the incoming-file contract without sending workstation bytes to the phone.
+export async function stageWorkstationMessageFile(file, uploadsRoot) {
+  const handle = await fs.open(file.path, 'r');
+  const session = createFileUploadSession(uploadsRoot);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size < 1) throw new Error('附件为空。');
+    const validate = async () => {
+      if (fileRevision(await handle.stat()) !== file.revision || fileRevision(await fs.stat(file.path)) !== file.revision) {
+        throw new Error('电脑文件已变化，请重新添加。');
+      }
+    };
+    await validate();
+    const bytes = Buffer.alloc(FILE_CHUNK_BYTES);
+    const readPart = async offset => {
+      const length = Math.min(bytes.length, stat.size - offset);
+      let count = 0;
+      while (count < length) {
+        const { bytesRead } = await handle.read(bytes, count, length - count, offset + count);
+        if (!bytesRead) throw new Error('电脑文件读取不完整，请重新添加。');
+        count += bytesRead;
+      }
+      return bytes.subarray(0, length);
+    };
+    await validate();
+    const started = await session.receive({ type: 'start', fileKey: '0', name: file.name, size: stat.size });
+    for (let offset = 0; offset < stat.size; offset += FILE_CHUNK_BYTES) {
+      await session.receive({ type: 'chunk', id: started.id, offset, data: await readPart(offset) });
+    }
+    await validate();
+    const result = await session.receive({ type: 'finish', id: started.id });
+    await session.receive({ type: 'commit' });
+    return { ...result, mediaKind: media.mediaKind(file),
+      mimeType: media.mediaMime(file) || mimeTypes[path.extname(file.name).slice(1).toLowerCase()] || 'application/octet-stream' };
+  } finally { await handle.close(); await session.close(); }
+}
+
+async function localFile(file, directory) {
+  if (typeof file?.path !== 'string' || typeof file.name !== 'string' || !file.name || /[\r\n\0]/.test(file.name)) {
+    throw new Error('附件信息无效，请重新选择。');
+  }
+  const root = await fs.realpath(directory), resolved = await fs.realpath(file.path);
+  if (path.relative(root, path.dirname(resolved)) !== '') throw new Error('附件必须来自本次工作站上传目录。');
+  const handle = await fs.open(resolved, 'r');
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size < 1) throw new Error('附件为空。');
+    const bytes = await openAsBlob(resolved);
+    if (bytes.size !== stat.size) throw new Error('附件在读取时发生变化，请重新上传。');
+    const mimeType = media.mediaMime(file) || mimeTypes[path.extname(file.name).slice(1).toLowerCase()] || 'application/octet-stream';
+    if (!/^[a-z0-9.+-]+\/[a-z0-9.+-]+$/i.test(mimeType)) throw new Error('附件类型无效。');
+    return { name: file.name, mimeType, bytes, path: resolved };
+  } finally { await handle.close(); }
+}
+
+export async function readMessageUploads(body, uploadsRoot) {
+  const images = body.images ?? [], originals = body.originalImages ?? [], files = body.files ?? [];
+  if (![images, originals, files].every(Array.isArray) || images.length + originals.length > 4 || files.length + originals.length > MAX_FILE_COUNT) {
+    throw new Error('每条消息最多 4 张图片、4 个文件。');
+  }
+  const uploads = [];
+  let imageBytes = 0;
+  for (const image of images) {
+    let file;
+    if (typeof image === 'string' && image.startsWith('data:')) {
+      validateInlineImage(image);
+      const mimeType = image.slice(5, image.indexOf(';'));
+      file = { name: `image.${mimeType.split('/')[1]}`, mimeType, bytes: Buffer.from(image.slice(image.indexOf(',') + 1), 'base64') };
+    } else {
+      if (typeof image !== 'string' || !/^[a-f0-9]{64}$/.test(image)) throw new Error('图片标识无效。');
+      let extension = 'webp';
+      try { await fs.access(path.join(uploadsRoot, `${image}.webp`)); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; extension = 'png'; }
+      file = await localFile({ path: path.join(uploadsRoot, `${image}.${extension}`), name: `image.${extension}` }, uploadsRoot);
+    }
+    imageBytes += file.bytes.size ?? file.bytes.length;
+    if (imageBytes > 8 * 1024 * 1024) throw new Error('压缩图片合计不能超过 8 MiB。');
+    uploads.push(file);
+  }
+  for (const original of originals) {
+    if (typeof original !== 'string' || !/\.(png|jpe?g|webp|gif)$/i.test(original)) throw new Error('原图路径无效。');
+  }
+  for (const file of [...originals.map(value => ({ path: value, name: path.basename(value) })), ...files]) {
+    const uploaded = await localFile(file, path.join(uploadsRoot, 'incoming'));
+    uploads.push(uploaded);
+  }
+  for (const file of uploads) {
+    if (/^image\/(?:png|jpeg|webp|gif)$/.test(file.mimeType)) {
+      const metadata = await sharp(file.path || file.bytes).metadata();
+      file.width = metadata.width; file.height = metadata.height;
+      if (!file.width || !file.height) throw new Error('无法读取 图片尺寸。');
+    }
+  }
+  if (uploads.filter(file => file.width).length > 4) throw new Error('每条消息最多 4 张图片。');
+  return uploads;
+}

package/dist/src/onboarding.mjs

@@ -1,31 +1,12 @@
-export const connectionModesText = [
-  '可选连接模式：',
-  '• 局域网：启动时会把当前 Wi-Fi/有线网络候选临时发给已配对设备；App 验证后保存，也可手动输入 IP。',
-  '• 私有中继：同一设备授权可跨网络长期重连；基础控制/完整控制能力由电脑当前 Bridge 状态决定。',
-  '• OpenAI 官方中继：在已配对电脑内使用官方账号和设备授权；认证仍直连 OpenAI。',
-].join('\n');
-
-export function phonePairingSteps(transportMode, paired = false) {
-  const mode = transportMode === 'lan-shared' ? '局域网 · 完整控制' : transportMode === 'lan-legacy' ? '局域网 · 基础控制' : '局域网（按电脑实际控制方式选择）';
-  return paired ? [
-    `已有移动设备授权。手机可继续使用私有中继；${mode} 会显示验证成功的当前网络和历史记录。`,
-    '添加另一台设备时执行 relax pair；每台设备只需扫码配对一次。',
-  ] : [
-    '手机先安装 Code Relax。当前为鸿蒙 HarmonyOS 7 私测版，调试 HAP 需通过 DevEco/调试设备安装，尚无商店下载入口。',
-    '使用 App 扫描配对二维码；每台移动设备只需配对一次。',
-    `配对后可直接使用私有中继；${mode} 会接收并验证当前网络候选，也可手动输入 IP。`,
-  ];
-}
-export const desktopSetupSteps = [
-  'Code Relax Skill 已随 npm 包自动安装。',
-  '安装完成后 Bridge 和受管 app-server 已启动，并默认在当前用户登录时启动。',
-  '如果安装时 Codex 仍在运行，手机完整控制仍可使用；可选择立即或稍后重启，让 Desktop 也接入同一受管服务。',
-  '基础控制首次聊天需要在 Codex 对话启动一次 Code Relax 绑定上下文；完整控制不需要。',
-  '尚无设备授权时执行 relax pair，打开并扫描配对二维码。',
-  '若工作站提示 Desktop 尚未接入受管服务，可在手机确认重新打开 Desktop，无需电脑脚本或快捷方式。',
-  '统一配对先建立电脑记录；进入该电脑后可另行完成 OpenAI 官方 Remote 配对。',
+export function phonePairingSteps(_transportMode, paired = false) {
+  return paired ? ['已配对设备可直接连接。添加设备：relax pair']
+    : ['生成配对二维码：relax pair', '用 Code Relax App 扫码添加工作站。'];
+}
+export const desktopSetupSteps = [
+  '工作站服务和 Codex 内核已就绪，已启用登录自启。',
+  '生成配对二维码：relax pair',
 ];
 
-export function pairingDisplayText(nextSteps, notice) {
-  return ['Bridge 已就绪，请在手机上完成连接。', connectionModesText, ...nextSteps.map((step, index) => `${index + 1}. ${step}`), notice].join('\n\n');
+export function pairingDisplayText(nextSteps) {
+  return ['Code Relax 工作站已启动。', ...nextSteps].join('\n');
 }

package/dist/src/plan-pricing.mjs

@@ -0,0 +1,47 @@
+import http2 from 'node:http2';
+import pricing from '../shared/plan-pricing.cjs';
+
+export async function readPlanPricing(client) {
+  await client.connect();
+  const token = async () => (await client.request('getAuthStatus', { includeToken: true, refreshToken: false })).authToken;
+  const authToken = await token();
+  if (!authToken) return null;
+  const identity = value => {
+    const auth = JSON.parse(Buffer.from(value.split('.')[1], 'base64url'))['https://api.openai.com/auth'];
+    return JSON.stringify([auth?.chatgpt_account_id, auth?.chatgpt_user_id]);
+  };
+  const initialIdentity = identity(authToken), accountId = JSON.parse(initialIdentity)[0];
+  if (!accountId) return null;
+  const session = http2.connect('https://chatgpt.com');
+  session.on('error', () => {}); // Each stream reports its own request error.
+  try {
+    const get = route => new Promise((resolve, reject) => {
+      const request = session.request({ ':method': 'GET', ':path': '/backend-api' + route,
+        authorization: `Bearer ${authToken}`, 'chatgpt-account-id': accountId,
+        'user-agent': 'Code-Relax/0.1.0', accept: 'application/json' });
+      let body = '', status, size = 0, ended = false;
+      const timer = setTimeout(() => request.destroy(new Error('套餐费用查询超时。')), 15000);
+      request.setEncoding('utf8');
+      request.on('response', headers => { status = headers[':status']; });
+      request.on('data', chunk => {
+        size += Buffer.byteLength(chunk);
+        if (size > 1024 * 1024) request.destroy(new Error('套餐费用响应过大。'));
+        else body += chunk;
+      });
+      request.on('error', reject);
+      request.on('close', () => { clearTimeout(timer); if (!ended) reject(new Error('套餐费用连接已断开。')); });
+      request.on('end', () => {
+        ended = true;
+        try {
+          if (status !== 200) throw new Error(`套餐费用查询失败（HTTP ${status}）。`);
+          resolve(JSON.parse(body));
+        } catch (error) { reject(error); }
+      });
+      request.end();
+    });
+    const value = await pricing.read(accountId, get);
+    const current = await token();
+    if (!current || identity(current) !== initialIdentity) throw new Error('套餐查询期间账号已变化。');
+    return value;
+  } finally { session.destroy(); }
+}

package/dist/src/platform/README.md

@@ -1,12 +1,7 @@
-# 被控主机平台适配
-
-当前只实现 Windows Codex：
-
-- `windows/runtime-paths.mjs`：固定服务、用户状态、Codex 数据、附件和长期凭据路径。
-- `windows/service-host.mjs`、`desktop-tools.mjs`：网卡、Desktop 工具管道、共享连接检测和旧状态迁移。
-- `windows/desktop-host.mjs`、PowerShell 脚本：普通/共享 Desktop、快捷方式和隐藏控制台启动。
-- `windows/credential-store.mjs/.ps1`：私有中继电脑凭据的 DPAPI 与 ACL。
-
-Windows 专有脚本兼容系统自带 PowerShell 5.1。通用生命周期使用 Node 接口；系统检测和凭据保护不扩散到业务代码。
-
-macOS、Linux 目录仅保留规划说明，尚无路径、IPC、进程或安装实现。接入排在控制端扩展之后，并需分别验证 Codex Desktop/app-server 的可用连接方式；只有独立 app-server 时不能宣称接管 Desktop 当前任务。
+# 被控主机平台适配
+
+Windows/macOS/Linux 通过公共入口选择系统路径、进程、Desktop 和后台启动适配。通用生命周期使用 Node 接口，Windows 专有脚本兼容系统自带 PowerShell 5.1。
+
+`credential-store.mjs` 已统一为当前用户状态目录内的普通 JSON 身份配置，不再选择 DPAPI、Keychain 或 Secret Service 适配器。一次性旧身份转存只由安装前的 `relay-config-import.mjs` 执行，失败不停止旧服务。
+
+范围、平台验收及账号登录保护边界见[工作站跨平台](../../../docs/workstation-platforms.md)和[配置存储](../../../docs/relay-config-storage.md)。

package/dist/src/platform/codex-protocol.mjs

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+const requiredMethods = ['thread/start', 'thread/resume', 'thread/list', 'thread/turns/list',
+  'thread/items/list', 'turn/start', 'turn/steer', 'turn/interrupt', 'model/list', 'project/list',
+  'project/create', 'project/update', 'project/move',
+  'fs/getMetadata', 'fs/readDirectory', 'fs/createDirectory', 'command/exec',
+  'thread/settings/update', 'configRequirements/read', 'thread/queue/list', 'thread/queue/add',
+  'thread/queue/delete', 'thread/queue/start', 'thread/read', 'thread/unsubscribe', 'config/read', 'account/rateLimits/read'];
+
+export function compareVersions(a, b) {
+  const parse = v => v.split(/[.-]/).map(part => /^\d+$/.test(part) ? Number(part) : part);
+  const aa = parse(a), bb = parse(b);
+  for (let i = 0; i < Math.max(aa.length, bb.length); i++) {
+    if (aa[i] === bb[i]) continue;
+    if (aa[i] === undefined) return 1;
+    if (bb[i] === undefined) return -1;
+    return typeof aa[i] === 'number' && typeof bb[i] === 'number' ? aa[i] - bb[i] : String(aa[i]).localeCompare(String(bb[i]));
+  }
+  return 0;
+}
+
+export function newestRuntime(candidates) {
+  return [...candidates].sort((a, b) => compareVersions(b.version, a.version)
+    || Number(b.source === 'desktop') - Number(a.source === 'desktop'))[0];
+}
+
+export async function verifyProtocol(executable, stateRoot) {
+  const directory = fs.mkdtempSync(path.join(stateRoot, 'cli-schema-'));
+  try {
+    await exec(executable, ['app-server', 'generate-json-schema', '--experimental', '--out', directory],
+      { windowsHide: true, timeout: 30000, maxBuffer: 4 * 1024 * 1024 });
+    const request = fs.readFileSync(path.join(directory, 'ClientRequest.json'), 'utf8');
+    const missing = requiredMethods.filter(method => !request.includes(`"${method}"`));
+    const turns = fs.readFileSync(path.join(directory, 'v2/ThreadTurnsListParams.json'), 'utf8');
+    if (!turns.includes('"itemsView"') || !turns.includes('"summary"')) missing.push('turn summary pagination');
+    if (missing.length) throw new Error(`缺少协议能力：${missing.join(', ')}`);
+  } finally {
+    const remove = dir => {
+      for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
+        const file = path.join(dir, item.name);
+        if (item.isDirectory()) remove(file); else fs.unlinkSync(file);
+      }
+      fs.rmdirSync(dir);
+    };
+    remove(directory);
+  }
+}

package/dist/src/platform/codex-runtime.mjs

@@ -0,0 +1,4 @@
+import { platformModule } from './select.mjs';
+const adapter = await import(platformModule('codex-runtime'));
+export const { discoverCodex, resolveCodexRuntime, runtimeFilesAvailable, codeModeHostPath, runtimeFingerprint, pruneRetainedDesktopRuntimes } = adapter;
+export const runtimeInstallationFingerprint = adapter.runtimeInstallationFingerprint || (() => null);

package/dist/src/platform/credential-store.mjs

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { runtimePaths } from './runtime-paths.mjs';
+import { readRecord, writeRecord } from '../service-lifecycle.mjs';
+import { assertPlainPath } from '../skill-install.mjs';
+
+// Workstation identity is ordinary per-user configuration, outside the service
+// installation. No platform vault or interactive permission is needed on load.
+export function credentialStore(action, record, root = runtimePaths().stateRoot) {
+  if (!['load', 'save'].includes(action)) throw new Error('无效的工作站配置操作。');
+  const file = path.join(root, 'self-relay-identity.json');
+  assertPlainPath(file);
+  if (action === 'save') {
+    if (!record || typeof record !== 'object' || Array.isArray(record)) throw new Error('无效的工作站身份配置。');
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    writeRecord(file, record);
+  }
+  return { path: file, record: readRecord(file) };
+}

package/dist/src/platform/desktop-host.mjs

@@ -0,0 +1,3 @@
+import { platformModule } from './select.mjs';
+const adapter = await import(platformModule('desktop-host'));
+export const { desktopHost, resolveStateRoot, removeDesktopShortcut, residentStartup } = adapter;

package/dist/src/platform/desktop-permission-mode.mjs

@@ -0,0 +1,17 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { runtimePaths } from './runtime-paths.mjs';
+
+// Desktop 26.1013.4894.0: LCo / agent-mode-by-host-id, local execution host.
+// Read the preference only; Desktop remains the owner of its state file.
+export async function desktopPermissionMode(codexDataRoot = runtimePaths().codexDataRoot) {
+  let state;
+  try {
+    state = JSON.parse(await fs.readFile(path.join(codexDataRoot, '.codex-global-state.json'), 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  const mode = state?.['electron-persisted-atom-state']?.['agent-mode-by-host-id']?.local;
+  return ({ auto: 'ask', 'guardian-approvals': 'auto', 'full-access': 'full' })[mode] ?? null;
+}

package/dist/src/platform/desktop-project-registration.mjs

@@ -0,0 +1,3 @@
+import { platformModule } from './select.mjs';
+const adapter = await import(platformModule('desktop-project-registration'));
+export const { withDesktopProjectRegistration } = adapter;

package/dist/src/platform/desktop-project-store.mjs

@@ -0,0 +1,219 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { processAlive } from '../background-process.mjs';
+
+// Desktop state is validated by structure, not by application version.
+// Desktop reads this file once and flushes its complete in-memory snapshot.
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const key = value => process.platform === 'win32'
+  ? path.win32.normalize(value).replace(/[\\/]+$/, '').toLowerCase() : path.posix.normalize(value).replace(/\/+$/, '');
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const fail = (message, details) => { throw Object.assign(new Error(message), { statusCode: 409, details }); };
+
+export const desktopProjectRestartWarning = '创建项目需要短暂关闭并重新打开 Codex Desktop，以完成桌面登记。请先保存桌面上未发送的内容；仅由旧桌面实例承接的任务可能中断。手机连接、工作站服务和 Codex 内核保持运行。';
+export const desktopProjectRemovalWarning = '移除项目需要短暂关闭并重新打开 Codex Desktop，以同步项目列表。请先保存桌面上未发送的内容；仅由旧桌面实例承接的任务可能中断。不会删除文件或对话，工作站服务和 Codex 内核保持运行。';
+
+function parseState(bytes) {
+  const state = JSON.parse(bytes.toString('utf8').replace(/^\uFEFF/, ''));
+  if (!object(state) || !object(state['local-projects']) || !Array.isArray(state['project-order'])
+    || state['project-order'].some(id => typeof id !== 'string')) {
+    fail('Codex Desktop 项目文件结构无效，未修改桌面文件。');
+  }
+  return state;
+}
+
+export function registerProjectInState(state, project, codexDataRoot) {
+  if (!Number.isFinite(project.createdAt) || !Number.isFinite(project.updatedAt)) {
+    fail('内核项目时间字段无效，未修改桌面文件。');
+  }
+  const projects = state['local-projects'];
+  const scope = state['app-server-project-id-by-legacy-project-id-by-host']?.[`local:${codexDataRoot}`];
+  if (scope !== undefined && !object(scope)) fail('Codex Desktop 项目映射结构无效，未修改桌面文件。');
+  for (const [legacyId, nativeId] of Object.entries(scope || {})) {
+    if ((legacyId === project.id || nativeId === project.id) && legacyId !== nativeId) {
+      fail('该项目已有不同的桌面身份映射，未覆盖已有登记。');
+    }
+  }
+  const previous = projects[project.id];
+  const rootPaths = project.roots.map(root => root.path);
+  if (previous && (previous.id !== project.id || previous.name !== project.name || !Array.isArray(previous.rootPaths)
+    || previous.rootPaths.length !== rootPaths.length || previous.rootPaths.some((root, index) => key(root) !== key(rootPaths[index])))) {
+    fail('该项目的桌面登记内容已变化，未覆盖已有登记。');
+  }
+  // With identical native/desktop IDs, Desktop storeProject adopts the native
+  // project at startup. No legacy mapping, thread reassignment or import is needed.
+  const entry = previous || {
+    id: project.id, name: project.name, rootPaths,
+    createdAt: project.createdAt * 1000, updatedAt: project.updatedAt * 1000,
+  };
+  // Put the new project first in both the registry and
+  // its explicit display order, including a partial registration resumed later.
+  const result = { ...state, 'local-projects': { [project.id]: entry,
+    ...Object.fromEntries(Object.entries(projects).filter(([id]) => id !== project.id)) } };
+  result['project-order'] = [project.id, ...state['project-order'].filter(id => id !== project.id)];
+  return result;
+}
+
+export function updateProjectInState(state, project, codexDataRoot, previous) {
+  const scope = state['app-server-project-id-by-legacy-project-id-by-host']?.[`local:${codexDataRoot}`];
+  if (scope !== undefined && !object(scope)) fail('Codex Desktop 项目映射结构无效。');
+  const ids = new Set([project.id, ...Object.entries(scope || {}).filter(([, id]) => id === project.id).map(([id]) => id)]);
+  const projects = { ...state['local-projects'] };
+  const matches = (entry, value) => entry.name === value.name && Array.isArray(entry.rootPaths)
+    && entry.rootPaths.length === value.roots.length && entry.rootPaths.every((root, i) => key(root) === key(value.roots[i].path));
+  let found = false;
+  for (const id of ids) {
+    const entry = projects[id]; if (!entry) continue;
+    if (!matches(entry, previous) && !matches(entry, project)) fail('桌面项目已被其他操作修改，请刷新后重新编辑。');
+    projects[id] = { ...entry, name: project.name, rootPaths: project.roots.map(root => root.path), updatedAt: project.updatedAt * 1000 };
+    found = true;
+  }
+  return found ? { ...state, 'local-projects': projects } : registerProjectInState(state, project, codexDataRoot);
+}
+
+export function removeProjectFromState(state, project, codexDataRoot) {
+  const scopeKey = `local:${codexDataRoot}`;
+  const mappings = state['app-server-project-id-by-legacy-project-id-by-host'];
+  const scope = mappings?.[scopeKey];
+  if (scope !== undefined && !object(scope)) fail('Codex Desktop 项目映射结构无效，未修改桌面文件。');
+  const ids = new Set([project.id, ...Object.entries(scope || {}).filter(([, id]) => id === project.id).map(([id]) => id)]);
+  const result = { ...state, 'local-projects': { ...state['local-projects'] },
+    'project-order': state['project-order'].filter(id => !ids.has(id)) };
+  for (const id of ids) delete result['local-projects'][id];
+  if (state['pinned-project-ids'] !== undefined) {
+    if (!Array.isArray(state['pinned-project-ids'])) fail('Codex Desktop 项目置顶结构无效。');
+    result['pinned-project-ids'] = state['pinned-project-ids'].filter(id => !ids.has(id));
+  }
+  if (scope) result['app-server-project-id-by-legacy-project-id-by-host'] = { ...mappings,
+    [scopeKey]: Object.fromEntries(Object.entries(scope).filter(([id]) => !ids.has(id))) };
+  const assignments = state['thread-project-assignments'];
+  if (assignments !== undefined) {
+    if (!object(assignments) || state['projectless-thread-ids'] !== undefined && !Array.isArray(state['projectless-thread-ids'])) {
+      fail('Codex Desktop 对话项目归属结构无效。');
+    }
+    const remaining = { ...assignments }, projectless = new Set(state['projectless-thread-ids'] || []);
+    for (const [id, assignment] of Object.entries(assignments)) {
+      if (assignment?.projectKind !== 'local' || !ids.has(assignment.projectId)) continue;
+      delete remaining[id]; projectless.add(id);
+    }
+    result['thread-project-assignments'] = remaining;
+    result['projectless-thread-ids'] = [...projectless];
+  }
+  return result;
+}
+
+async function acquireLock(stateRoot, operationId) {
+  const file = path.join(stateRoot, 'desktop-launch.lock');
+  try {
+    const previous = JSON.parse(await fs.readFile(file, 'utf8') || 'null');
+    if (previous?.owner === 'project-registration' && Number.isInteger(previous.pid) && !processAlive(previous.pid)) {
+      await fs.unlink(file);
+    }
+  } catch (error) { if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error; }
+  let handle;
+  try { handle = await fs.open(file, 'wx'); }
+  catch (error) { if (error.code === 'EEXIST') fail('Codex Desktop 正在启动或登记项目，请稍后再试。'); throw error; }
+  try { await handle.writeFile(JSON.stringify({ owner: 'project-registration', pid: process.pid, operationId })); }
+  catch (error) { await handle.close(); await fs.unlink(file); throw error; }
+  return async () => { await handle.close(); await fs.unlink(file); };
+}
+
+export async function withDesktopProjectRegistration(options, action) {
+  const { stateRoot, codexDataRoot, operationId, confirmed, serverUrl,
+    host, wait = delay, readyTimeoutMs = 30000 } = options;
+  const stateFile = path.join(codexDataRoot, '.codex-global-state.json');
+  const removing = options.operation === 'remove';
+  const updating = options.operation === 'update';
+  const warning = removing ? desktopProjectRemovalWarning : updating ? desktopProjectRestartWarning.replace('创建项目', '编辑项目') : desktopProjectRestartWarning;
+  const release = await acquireLock(stateRoot, operationId);
+  try {
+    try { await fs.access(path.join(stateRoot, 'shared-recovery.lock')); fail('Codex Desktop 正在恢复连接，请稍后操作项目。'); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const info = await host.inspect();
+    parseState(await fs.readFile(stateFile));
+    if (info.running && confirmed !== true) fail(warning, { desktopRestartRequired: true });
+    if (info.running && await host.sharedServiceUrl() !== serverUrl) {
+      fail('Codex Desktop 尚未接入当前工作站内核，请先完成 Desktop 接入后操作项目。');
+    }
+    const mutate = async (project, operation, saveOperation, removeNative) => {
+        const transform = updating ? (state, value, root) => updateProjectInState(state, value, root, operation.previousProject)
+          : removing ? removeProjectFromState : registerProjectInState;
+        const verify = async () => {
+          const finalState = parseState(await fs.readFile(stateFile));
+          const verified = transform(finalState, project, codexDataRoot);
+          if (JSON.stringify(verified) !== JSON.stringify(finalState)) throw new Error('Desktop 项目状态未能在最终文件中核对，请检查后继续完成操作。');
+        };
+        let restartNeeded = operation.desktopWasRunning === true;
+        let registrationError;
+        const current = await host.inspect();
+        if (current.desktop !== info.desktop || current.desktopIdentity !== info.desktopIdentity) fail('Codex Desktop 安装版本发生变化，项目保留，未修改桌面文件。');
+        if (current.running) {
+          if (confirmed !== true) fail(warning, { desktopRestartRequired: true });
+          if (await host.sharedServiceUrl() !== serverUrl) fail('Codex Desktop 内核连接已变化，未关闭桌面。');
+          restartNeeded = true;
+          operation.desktopWasRunning = true;
+          await saveOperation();
+        }
+        try {
+          if (current.running) await host.closeDesktop(info.desktop);
+          if ((await host.inspect()).running) fail('Codex Desktop 尚未退出，未修改桌面文件。');
+          const original = await fs.readFile(stateFile);
+          const state = parseState(original);
+          const updated = transform(state, project, codexDataRoot);
+          if (JSON.stringify(updated) !== JSON.stringify(state)) {
+            const backupDirectory = path.join(stateRoot, 'desktop-project-backups');
+            await fs.mkdir(backupDirectory, { recursive: true });
+            const backup = path.join(backupDirectory, `${operationId}-${randomUUID()}.json`);
+            await fs.writeFile(backup, original, { flag: 'wx', mode: 0o600 });
+            operation.desktopBackup = backup;
+            await saveOperation();
+            const temporary = `${stateFile}.${operationId}.tmp`;
+            try {
+              const source = original.toString('utf8');
+              const replacement = Buffer.from(`${source.startsWith('\uFEFF') ? '\uFEFF' : ''}${JSON.stringify(updated)}${source.endsWith('\n') ? '\n' : ''}`);
+              await fs.writeFile(temporary, replacement, { flag: 'wx', mode: 0o600 });
+              if ((await host.inspect()).running || digest(await fs.readFile(stateFile)) !== digest(original)) {
+                fail('Codex Desktop 状态在登记期间发生变化，未覆盖原文件，请核对后重试。');
+              }
+              await fs.rename(temporary, stateFile);
+              if (digest(await fs.readFile(stateFile)) !== digest(replacement)) throw new Error('Codex Desktop 登记文件未能核对，原状态备份已保留。');
+            } finally { await fs.rm(temporary, { force: true }); }
+          }
+          // Remove only after the desktop registry has been saved and while
+          // Desktop is closed. project/delete detaches members, never their files.
+          if (removing) await removeNative();
+          operation[removing ? 'desktopRemoved' : 'desktopRegistered'] = true;
+          await saveOperation();
+          // Verify the committed registry while Desktop is still closed. New
+          // projects are usable in the kernel without waiting for its UI.
+          if (!removing && !updating) await verify();
+        } catch (error) { registrationError = error; }
+        // Restore the UI even if the registry write failed. This never starts or
+        // restarts a kernel and never changes the service's active connections.
+        if (restartNeeded) {
+          try {
+            if (!(await host.inspect()).running) await host.startDesktop(info.desktop, { CODEX_APP_SERVER_WS_URL: serverUrl, CODEX_HOME: codexDataRoot });
+            // Creation completes once registration is verified and the OS has
+            // accepted launch. Keep update/removal's existing readiness contract.
+            if (removing || updating) {
+              const deadline = Date.now() + readyTimeoutMs;
+              while (!await host.desktopReady()) {
+                if (Date.now() >= deadline) throw new Error('Codex Desktop 尚未重新就绪。');
+                await wait(500);
+              }
+              if (await host.sharedServiceUrl() !== serverUrl) throw new Error('Desktop 未接入原工作站内核。');
+            }
+          } catch (error) {
+            throw new Error([registrationError?.message, `${removing ? '项目移除状态已记录' : '项目已保留'}，重新打开 Codex Desktop 未完成：${error.message}`].filter(Boolean).join(' '));
+          }
+        }
+        if (registrationError) throw registrationError;
+        if (removing || updating) await verify();
+        return { status: removing ? 'removed' : updating ? 'updated' : 'registered',
+          ...(removing || updating ? { restarted: restartNeeded } : { restartRequested: restartNeeded }) };
+    };
+    return await action({ register: mutate, remove: mutate });
+  } finally { await release(); }
+}

package/dist/src/platform/file-opener.mjs

@@ -0,0 +1,9 @@
+import { spawn } from 'node:child_process';
+
+export function openFile(file) {
+  const executable = { win32: 'explorer.exe', darwin: '/usr/bin/open', linux: 'xdg-open' }[process.platform];
+  if (!executable) throw new Error(`不支持此平台的文件打开操作：${process.platform}`);
+  const viewer = spawn(executable, [file], { detached: true, stdio: 'ignore', windowsHide: true });
+  viewer.once('error', error => console.error(`无法打开二维码：${error.message}`));
+  viewer.unref();
+}