@walkhi/code-relax 0.1.0-beta.27 → 0.1.0-beta.29

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

@@ -1,4 +1,4 @@
-import { startWindowsProcess } from './background-process.mjs';
+import { startWindowsProcess } from './background-process.mjs';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
@@ -8,45 +8,51 @@ const exec = promisify(execFile);
 const directory = path.dirname(fileURLToPath(import.meta.url));
 export const powershell = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32/WindowsPowerShell/v1.0/powershell.exe');
 export async function runScript(name, args = []) {
-  const { stdout } = await exec(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', path.join(directory, name), ...args], { windowsHide: true, encoding: 'utf8', timeout: 30000 });
+  const { stdout } = await exec(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', path.join(directory, name), ...args], { windowsHide: true, encoding: 'utf8', timeout: 30000 });
   return stdout.trim();
 }
-export const desktopHost = {
+export const desktopHost = {
   inspect: async () => JSON.parse(await runScript('desktop-info.ps1')),
   process: async pid => JSON.parse(await runScript('desktop-info.ps1', ['-ProcessId', String(pid)])),
   sharedServiceUrl,
-  start: startWindowsProcess,
-  closeDesktop: executable => runScript('stop-desktop.ps1', ['-Executable', executable]),
-  stop: pid => process.kill(pid),
-  async prepareKernelRestart() {
-    const info = await this.inspect();
-    if (!info.running || !await this.sharedServiceUrl()) return null;
-    await this.closeDesktop(info.desktop);
-    return info.desktop;
-  },
-  async resumeAfterKernelRestart(executable, environment) {
-    if (!executable) return;
-    await this.start(executable, [], environment, []);
-    const deadline = Date.now() + 30000;
-    while (!await this.sharedServiceUrl()) {
-      if (Date.now() >= deadline) throw new Error('Codex 内核已就绪，但 Desktop 未完成重新接入。');
-      await new Promise(resolve => setTimeout(resolve, 500));
-    }
-  },
+  start: startWindowsProcess,
+  startDesktop: (executable, environment) => runScript('activate-desktop.ps1', [
+    '-Executable', executable, '-AppServerUrl', environment.CODEX_APP_SERVER_WS_URL,
+  ]),
+  async desktopReady() {
+    return (await this.inspect()).hasWindow === true && Boolean(await this.sharedServiceUrl());
+  },
+  closeDesktop: executable => runScript('stop-desktop.ps1', ['-Executable', executable]),
+  stop: pid => process.kill(pid),
+  async prepareKernelRestart() {
+    const info = await this.inspect();
+    if (!info.running || !await this.sharedServiceUrl()) return null;
+    await this.closeDesktop(info.desktop);
+    return info.desktop;
+  },
+  async resumeAfterKernelRestart(executable, environment) {
+    if (!executable) return;
+    await this.startDesktop(executable, environment);
+    const deadline = Date.now() + 30000;
+    while (!await this.desktopReady()) {
+      if (Date.now() >= deadline) throw new Error('Codex 内核已就绪，但 Desktop 未完成重新接入。');
+      await new Promise(resolve => setTimeout(resolve, 500));
+    }
+  },
   ready: async url => { try { return (await fetch(url, { signal: AbortSignal.timeout(1000) })).ok; } catch { return false; } },
-};
-export const resolveStateRoot = stateRoot => runScript('resolve-state-root.ps1', ['-StateRoot', stateRoot]);
+};
+export const resolveStateRoot = stateRoot => runScript('resolve-state-root.ps1', ['-StateRoot', stateRoot]);
 
-export async function removeDesktopShortcut({ serviceRoot, nodeExecutable }, destination) {
+export async function removeDesktopShortcut({ serviceRoot, nodeExecutable }, destination) {
   const entry = path.join(serviceRoot, 'dist/bin/codex-remote.mjs');
   const args = ['-NodePath', nodeExecutable, '-Entry', entry];
   if (destination) args.push('-Destination', destination);
   return JSON.parse(await runScript('desktop-shortcuts.ps1', args));
-}
-
-export async function residentStartup({ serviceRoot, nodeExecutable }, action = 'status') {
-  const { stdout } = await exec(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File',
-    path.join(serviceRoot, 'dist/src/platform/windows/resident-startup.ps1'), '-NodePath', nodeExecutable,
-    '-Entry', path.join(serviceRoot, 'dist/bin/codex-remote.mjs'), '-Action', action], { windowsHide: true, encoding: 'utf8' });
-  return JSON.parse(stdout.trim());
-}
+}
+
+export async function residentStartup({ serviceRoot, nodeExecutable }, action = 'status') {
+  const { stdout } = await exec(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File',
+    path.join(serviceRoot, 'dist/src/platform/windows/resident-startup.ps1'), '-NodePath', nodeExecutable,
+    '-Entry', path.join(serviceRoot, 'dist/bin/codex-remote.mjs'), '-Action', action], { windowsHide: true, encoding: 'utf8' });
+  return JSON.parse(stdout.trim());
+}

package/dist/src/platform/windows/desktop-info.ps1

@@ -8,7 +8,7 @@ if ($ProcessId -gt 0) {
     exit
 }
 $package = Get-AppxPackage OpenAI.Codex | Select-Object -First 1
-if (-not $package) { @{ desktop=$null; running=$false } | ConvertTo-Json -Compress; exit }
+if (-not $package) { @{ desktop=$null; running=$false } | ConvertTo-Json -Compress; exit }
 $desktop = Join-Path $package.InstallLocation 'app/ChatGPT.exe'
 $running = @(Get-Process ChatGPT -ErrorAction SilentlyContinue | Where-Object { $_.Path -eq $desktop })
-@{ desktop=$desktop; running=($running.Count -gt 0) } | ConvertTo-Json -Compress
+@{ desktop=$desktop; running=($running.Count -gt 0); hasWindow=(@($running | Where-Object { $_.MainWindowHandle -ne 0 }).Count -gt 0) } | ConvertTo-Json -Compress

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

@@ -0,0 +1,153 @@
+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 { desktopHost } from './desktop-host.mjs';
+import { processAlive } from '../../background-process.mjs';
+
+// This is a version-specific Desktop state adapter, not a second project store.
+// Desktop reads this file once and flushes its complete in-memory snapshot.
+const desktopVersion = '26.1002.7124.0';
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const key = value => path.win32.normalize(value).replace(/[\\/]+$/, '').toLowerCase();
+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 内核保持运行。';
+
+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 result = { ...state, 'local-projects': { ...projects, [project.id]: previous || {
+    id: project.id, name: project.name, rootPaths,
+    createdAt: project.createdAt * 1000, updatedAt: project.updatedAt * 1000,
+  } } };
+  result['project-order'] = state['project-order'].includes(project.id)
+    ? state['project-order'] : [project.id, ...state['project-order']];
+  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 = desktopHost, wait = delay, readyTimeoutMs = 30000 } = options;
+  const stateFile = path.join(codexDataRoot, '.codex-global-state.json');
+  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();
+    if (!info.desktop?.includes(`OpenAI.Codex_${desktopVersion}_`)) {
+      fail(`当前 Codex Desktop 版本尚未核对项目登记结构；已支持版本为 ${desktopVersion}。`);
+    }
+    parseState(await fs.readFile(stateFile));
+    if (info.running && confirmed !== true) fail(desktopProjectRestartWarning, { desktopRestartRequired: true });
+    if (info.running && await host.sharedServiceUrl() !== serverUrl) {
+      fail('Codex Desktop 尚未接入当前工作站内核，请先完成 Desktop 接入后创建项目。');
+    }
+    return await action({
+      async register(project, operation, saveOperation) {
+        let restartNeeded = operation.desktopWasRunning === true;
+        let registrationError;
+        const current = await host.inspect();
+        if (current.desktop !== info.desktop) fail('Codex Desktop 安装版本发生变化，项目保留，未修改桌面文件。');
+        if (current.running) {
+          if (confirmed !== true) fail(desktopProjectRestartWarning, { 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 = registerProjectInState(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 }); }
+          }
+          operation.desktopRegistered = true;
+          await saveOperation();
+        } 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 });
+            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, `项目已保留，重新打开 Codex Desktop 未完成：${error.message}`].filter(Boolean).join(' '));
+          }
+        }
+        if (registrationError) throw registrationError;
+        const finalState = parseState(await fs.readFile(stateFile));
+        const verified = registerProjectInState(finalState, project, codexDataRoot);
+        if (JSON.stringify(verified) !== JSON.stringify(finalState)) throw new Error('项目已创建，但 Desktop 登记未能在最终文件中核对。');
+        return { status: 'registered', restarted: restartNeeded };
+      },
+    });
+  } finally { await release(); }
+}

package/dist/src/platform/windows/dots-profile.mjs

@@ -0,0 +1,49 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { dotsProfile } from '../../dots-profile.mjs';
+
+// Desktop 26.928.2636.0 persists its current TBO sidebar profiles here.
+// Read display names, appearance colors and snapshot references; identity comes from the authenticated kernel.
+export function desktopDotsProfiles(codexDataRoot, stateRoot) {
+  const snapshotPath = ({ accountId, userId }) => stateRoot && path.join(stateRoot, 'dots-profiles',
+    createHash('sha256').update(JSON.stringify([accountId, userId])).digest('hex') + '.json');
+  const read = async ({ accountId, userId }) => {
+    let state;
+    try {
+      state = JSON.parse(await fs.readFile(path.join(codexDataRoot, '.codex-global-state.json'), 'utf8'));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    const cache = state?.['electron-persisted-atom-state']?.['cloud-aeon-sidebar-cache-v1'];
+    const names = new Map();
+    if (!accountId || !userId) return names;
+    const matching = cache?.hostId === 'durable' && cache.accountId === accountId && cache.userId === userId;
+    for (const [threadId, profile] of Object.entries(matching ? cache.profilesByThreadId || {} : {})) {
+      const value = dotsProfile(profile);
+      for (const id of [threadId, profile.active_root_thread_id, profile.root_thread_id]) {
+        if (typeof id === 'string' && id) names.set(id, value);
+      }
+    }
+    const file = snapshotPath({ accountId, userId });
+    if (file) {
+      try {
+        const saved = JSON.parse(await fs.readFile(file, 'utf8'));
+        if (saved.accountId !== accountId || saved.userId !== userId || !Array.isArray(saved.profiles)) throw new Error('点点资料缓存身份无效。');
+        const profiles = new Map(saved.profiles);
+        const byId = new Map([...profiles.values()].map(profile => [profile.profileId, profile]));
+        for (const [id, profile] of names) if (byId.has(profile.profileId)) names.set(id, byId.get(profile.profileId));
+        for (const [id, profile] of profiles) names.set(id, profile);
+      } catch (error) { if (error.code !== 'ENOENT') console.error('读取点点资料缓存失败：', error.message); }
+    }
+    return names;
+  };
+  read.save = async (identity, profiles) => {
+    const file = snapshotPath(identity);
+    if (!file) return;
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file + '.tmp', JSON.stringify({ ...identity, profiles: [...profiles] }), 'utf8');
+    await fs.rename(file + '.tmp', file);
+  };
+  return read;
+}

package/dist/src/platform/windows/launch-worker.mjs

@@ -1,42 +1,41 @@
-import fs from 'node:fs';
-import { spawn } from 'node:child_process';
-
-const [requestPath, readyPath, instance, diagnosticPath] = process.argv.slice(2);
-let result = { instance, brokerPid: process.pid };
-
-function diagnostic(message) {
-  if (!diagnosticPath) return;
-  fs.appendFileSync(diagnosticPath, `${new Date().toISOString()} ${message}\n`, 'utf8');
-}
-
-try {
-  const spec = JSON.parse(fs.readFileSync(requestPath, 'utf8').replace(/^\uFEFF/u, ''));
-  diagnostic('request loaded');
-  if (spec.instance !== instance) throw new Error('Windows process broker request identity mismatch.');
-  fs.rmSync(requestPath, { force: true });
-  const descriptors = (spec.logs || []).map(file => fs.openSync(file, 'a'));
-  try {
-    const child = spawn(spec.executable, spec.args || [], {
-      windowsHide: true,
-      env: spec.environment,
-      stdio: ['ignore', descriptors[0] ?? 'ignore', descriptors[1] ?? 'ignore'],
-    });
-    await new Promise((resolve, reject) => {
-      child.once('spawn', resolve);
-      child.once('error', reject);
-    });
-    // Keep this WMI-owned broker alive with the target so Codex tools inherit
-    // its hidden console instead of creating a visible console per command.
-    result.pid = child.pid;
-    diagnostic(`target started (PID ${child.pid})`);
-  } finally {
-    descriptors.forEach(descriptor => fs.closeSync(descriptor));
-  }
-} catch (error) {
-  result.error = error?.stack || error?.message || String(error);
-  try { diagnostic(`failed: ${result.error}`); } catch {}
-}
-
-const temporary = `${readyPath}.tmp`;
-fs.writeFileSync(temporary, JSON.stringify(result), 'utf8');
-fs.renameSync(temporary, readyPath);
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+import { attachProcessLog } from '../../bounded-process-log.mjs';
+
+const [requestPath, readyPath, instance, diagnosticPath] = process.argv.slice(2);
+let result = { instance, brokerPid: process.pid };
+
+function diagnostic(message) {
+  if (!diagnosticPath) return;
+  fs.appendFileSync(diagnosticPath, `${new Date().toISOString()} ${message}\n`, 'utf8');
+}
+
+try {
+  const spec = JSON.parse(fs.readFileSync(requestPath, 'utf8').replace(/^\uFEFF/u, ''));
+  diagnostic('request loaded');
+  if (spec.instance !== instance) throw new Error('Windows process broker request identity mismatch.');
+  fs.rmSync(requestPath, { force: true });
+  const logs = spec.logs || [];
+  const child = spawn(spec.executable, spec.args || [], {
+    windowsHide: true,
+    env: spec.environment,
+    stdio: ['ignore', logs[0] ? 'pipe' : 'ignore', logs[1] ? 'pipe' : 'ignore'],
+  });
+  if (child.stdout) attachProcessLog(child.stdout, logs[0]);
+  if (child.stderr) attachProcessLog(child.stderr, logs[1]);
+  await new Promise((resolve, reject) => {
+    child.once('spawn', resolve);
+    child.once('error', reject);
+  });
+  // Keep this WMI-owned broker alive with the target so Codex tools inherit
+  // its hidden console instead of creating a visible console per command.
+  result.pid = child.pid;
+  diagnostic(`target started (PID ${child.pid})`);
+} catch (error) {
+  result.error = error?.stack || error?.message || String(error);
+  try { diagnostic(`failed: ${result.error}`); } catch {}
+}
+
+const temporary = `${readyPath}.tmp`;
+fs.writeFileSync(temporary, JSON.stringify(result), 'utf8');
+fs.renameSync(temporary, readyPath);

package/dist/src/platform/windows/project-locations.mjs

@@ -0,0 +1,16 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import path from 'node:path';
+import { powershell } from './desktop-host.mjs';
+
+const exec = promisify(execFile);
+
+export async function projectLocations() {
+  const command = "[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false); $projectDocuments = [Environment]::GetFolderPath('MyDocuments'); $projectUserDirectory = [Environment]::GetFolderPath('UserProfile'); $projectDownloads = [Environment]::ExpandEnvironmentVariables((Get-ItemPropertyValue -LiteralPath 'HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders' -Name '{374DE290-123F-4565-9164-39C4925E467B}' -ErrorAction Stop)); $projectDriveRoots = @(Get-PSDrive -PSProvider FileSystem | ForEach-Object { $_.Root }); @{ documents = $projectDocuments; home = $projectUserDirectory; downloads = $projectDownloads; roots = $projectDriveRoots } | ConvertTo-Json -Compress";
+  const { stdout } = await exec(powershell, ['-NoProfile', '-NonInteractive', '-Command', command],
+    { windowsHide: true, encoding: 'utf8', timeout: 10000 });
+  const locations = JSON.parse(stdout);
+  if (!path.isAbsolute(locations.documents)) throw new Error('无法取得电脑的文档目录。');
+  if (!path.isAbsolute(locations.downloads)) throw new Error('无法取得电脑的下载目录。');
+  return { defaultParent: path.join(locations.documents, 'ChatGPT'), home: locations.home, downloads: locations.downloads, roots: locations.roots };
+}

package/dist/src/project-create.mjs

@@ -0,0 +1,119 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { readRecord, writeRecord } from './service-lifecycle.mjs';
+import { projectRoots, projectSummary } from './project-management.mjs';
+import { projectLocations } from './platform/windows/project-locations.mjs';
+import { withDesktopProjectRegistration } from './platform/windows/desktop-project-registration.mjs';
+
+const pending = new Map();
+const uuid = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+const fail = message => { throw Object.assign(new Error(message), { statusCode: 400 }); };
+const pathKey = value => path.normalize(value).toLowerCase();
+
+function defaultName(name) {
+  let value = path.basename(name).trim().replace(/[<>:"/\\|?*\x00-\x1f]/g, '_').replace(/[ .]+$/g, '') || 'New project';
+  if (/^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(value)) value = `_${value}`;
+  return value;
+}
+
+export async function createWorkstationProject(server, stateRoot, codexDataRoot, body, dependencies = {}) {
+  if (!uuid.test(body.idempotencyKey || '')) fail('项目创建标识无效。');
+  const name = typeof body.name === 'string' ? body.name.trim() : '';
+  if (!name) fail('请输入项目名称。');
+  if (!Array.isArray(body.roots) || body.roots.some(root => typeof root?.path !== 'string' || !path.isAbsolute(root.path.trim()))) {
+    fail('项目文件夹路径无效。');
+  }
+  const roots = body.roots.map(root => ({ path: path.normalize(root.path.trim()) }));
+  const signature = createHash('sha256').update(JSON.stringify({ name, roots })).digest('hex');
+  const directory = path.join(stateRoot, 'project-create-operations');
+  const record = path.join(directory, `${body.idempotencyKey}.json`);
+  const running = pending.get(record);
+  if (running) {
+    if (running.signature !== signature) fail('同一个创建请求不能修改项目名称或目录。');
+    return running.promise;
+  }
+  const promise = perform().finally(() => pending.delete(record));
+  pending.set(record, { signature, promise });
+  return promise;
+
+  async function perform() {
+    await fs.mkdir(directory, { recursive: true });
+    let operation = readRecord(record);
+    if (operation && operation.signature !== signature) fail('项目创建标识已用于其他内容，请重新打开项目编辑器。');
+    if (operation?.result) return operation.result;
+    operation ||= { signature, name, roots };
+    const save = () => writeRecord(record, operation);
+    const rpc = (method, params) => server.request(method, params);
+    const register = dependencies.registration || withDesktopProjectRegistration;
+    try {
+      return await register({ stateRoot, codexDataRoot, operationId: body.idempotencyKey,
+        confirmed: body.confirmDesktopRestart === true, serverUrl: server.url }, async desktop => {
+        // The restart confirmation and version/state checks happen before any
+        // directory or project write. Existing folders are never moved or copied.
+        if (!operation.resolvedRoots) {
+          operation.resolvedRoots = await projectRoots(rpc, roots);
+          if (!operation.resolvedRoots.length) {
+            const locations = await (dependencies.locations || projectLocations)();
+            await rpc('fs/createDirectory', { path: locations.defaultParent, recursive: true });
+            const entries = (await rpc('fs/readDirectory', { path: locations.defaultParent })).entries;
+            const names = new Set(entries.map(entry => entry.fileName.toLowerCase()));
+            const base = defaultName(name);
+            let folder = base;
+            for (let suffix = 2; names.has(folder.toLowerCase()); suffix++) folder = `${base} ${suffix}`;
+            operation.defaultDirectory = path.join(locations.defaultParent, folder);
+            operation.resolvedRoots = [{ path: operation.defaultDirectory }];
+          }
+          save();
+        }
+        if (operation.defaultDirectory && !operation.directoryCreated) {
+          if (operation.directoryAttempted) {
+            // On an explicit retry, keep the originally allocated directory. Never
+            // allocate another name after an interrupted createDirectory response.
+            await projectRoots(rpc, operation.resolvedRoots);
+          } else {
+            operation.directoryAttempted = true; save();
+            await rpc('fs/createDirectory', { path: operation.defaultDirectory, recursive: false });
+          }
+          operation.directoryCreated = true; save();
+          try {
+            const result = await rpc('command/exec', { command: ['git', 'init'], cwd: operation.defaultDirectory, timeoutMs: 10000 });
+            if (result.exitCode !== 0) throw new Error(result.stderr || result.stdout || `退出码 ${result.exitCode}`);
+          } catch (error) { operation.gitWarning = `项目目录已创建，Git 初始化未完成：${error.message}`; save(); }
+        }
+        const resolvedRoots = await projectRoots(rpc, operation.resolvedRoots);
+        if (!operation.projectId) {
+          operation.createAttempted = true; save();
+          // Native project/create owns idempotency; a retry uses this exact key
+          // and original roots on the same server, never a second transport.
+          const created = await rpc('project/create', { name, roots: resolvedRoots, idempotencyKey: body.idempotencyKey });
+          operation.projectId = created.project.id; save();
+        }
+        const { project } = await rpc('project/read', { projectId: operation.projectId });
+        if (project.id !== operation.projectId || project.name !== name || project.roots.length !== resolvedRoots.length
+          || project.roots.some((root, index) => pathKey(root.path) !== pathKey(resolvedRoots[index].path))) {
+          throw new Error('已创建项目的名称或目录发生变化，未覆盖其内容。');
+        }
+        if (!operation.ordered) {
+          const first = (await rpc('project/list', { limit: 1, sortKey: 'position', sortDirection: 'asc' })).data[0];
+          if (first && first.id !== project.id) await rpc('project/move', { projectId: project.id, beforeProjectId: first.id });
+          operation.ordered = true; save();
+        }
+        const desktopRegistration = await desktop.register(project, operation, save);
+        operation.result = { project: projectSummary(project), desktopRegistration,
+          ...(operation.gitWarning ? { warning: operation.gitWarning } : {}) };
+        save();
+        return operation.result;
+      });
+    } catch (error) {
+      if (operation.projectId || operation.createAttempted || operation.directoryAttempted) {
+        error.details = { ...error.details, projectCreationPending: true,
+          ...(operation.projectId ? { createdProjectId: operation.projectId } : {}) };
+        error.message += operation.projectId
+          ? ' 项目已创建，请继续完成桌面登记；会沿用同一项目，不会重复创建。'
+          : ' 请继续核对本次创建；会沿用原请求标识和目录。';
+      } else error.details = { ...error.details, projectCreationPending: false };
+      throw error;
+    }
+  }
+}

package/dist/src/project-management.mjs

@@ -0,0 +1,69 @@
+import path from 'node:path';
+
+const fail = (message, statusCode = 400) => { throw Object.assign(new Error(message), { statusCode }); };
+const pathKey = value => process.platform === 'win32' ? value.toLowerCase() : value;
+
+function absoluteDirectory(value) {
+  if (typeof value !== 'string' || !value.trim() || !path.isAbsolute(value.trim())) fail('请输入电脑上的绝对文件夹路径。');
+  return path.normalize(value.trim());
+}
+
+async function directory(rpc, value) {
+  const target = absoluteDirectory(value);
+  const stat = await rpc('fs/getMetadata', { path: target });
+  if (!stat.isDirectory) fail(`此路径不是文件夹：${target}`);
+  return target;
+}
+
+function folderName(value) {
+  if (typeof value !== 'string' || !value.trim() || /[<>:"/\\|?*\x00-\x1f]/.test(value) || /[ .]$/.test(value)
+    || /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(value) || ['.', '..'].includes(value)) {
+    fail('文件夹名称无效，请勿使用路径分隔符或系统保留名称。');
+  }
+  return value;
+}
+
+export async function projectRoots(rpc, roots) {
+  if (!Array.isArray(roots)) fail('项目文件夹列表无效。');
+  const result = [], seen = new Set();
+  for (const root of roots) {
+    const target = await directory(rpc, root?.path);
+    const key = pathKey(target);
+    if (seen.has(key)) fail(`重复的项目文件夹：${target}`);
+    seen.add(key); result.push({ path: target });
+  }
+  return result;
+}
+
+export function projectSummary(project) {
+  return { projectId: project.id, name: project.name, label: project.name, roots: project.roots,
+    path: project.roots[0]?.path || '', cwd: project.roots[0]?.path || '', hostId: 'local' };
+}
+
+export async function browseProjectFolders(rpc, locations, value) {
+  const target = await directory(rpc, value || locations.home);
+  const entries = (await rpc('fs/readDirectory', { path: target })).entries
+    .filter(entry => entry.isDirectory).map(entry => ({ name: entry.fileName, path: path.join(target, entry.fileName) }))
+    .sort((a, b) => a.name.localeCompare(b.name, 'zh-CN', { numeric: true }));
+  return { path: target, parent: path.dirname(target) === target ? null : path.dirname(target), entries, ...locations };
+}
+
+export async function createProjectFolder(rpc, body) {
+  const parent = await directory(rpc, body.parent);
+  const name = folderName(body.name);
+  const entries = (await rpc('fs/readDirectory', { path: parent })).entries;
+  if (entries.some(entry => pathKey(entry.fileName) === pathKey(name))) fail('同名文件夹已存在，请选择它或使用其他名称。', 409);
+  const target = path.join(parent, name);
+  await rpc('fs/createDirectory', { path: target, recursive: false });
+  return { path: target };
+}
+
+export async function saveProject(rpc, locations, body, projectId = null) {
+  // Native creation and Desktop registration are coordinated by project-create.mjs.
+  if (!projectId) fail('新建项目必须通过工作站项目创建流程。', 503);
+  const name = typeof body.name === 'string' ? body.name.trim() : '';
+  if (!name) fail('请输入项目名称。');
+  const roots = await projectRoots(rpc, body.roots);
+  const result = await rpc('project/update', { name, roots, projectId });
+  return { project: projectSummary(result.project) };
+}