@walkhi/code-relax 0.1.0-beta.5 → 0.1.0-beta.50

package/dist/src/service-lifecycle.mjs

@@ -1,130 +1,139 @@
-import fs from 'node:fs';
-import path from 'node:path';
+import fs from 'node:fs';
+import path from 'node:path';
 import { startBackground, processAlive } from './background-process.mjs';
-import { randomBytes, randomUUID } from 'node:crypto';
-import { setTimeout as delay } from 'node:timers/promises';
-import { fileURLToPath } from 'node:url';
-import { controlRequest } from './service-control.mjs';
-import { serviceHealth as health } from './service-health.mjs';
-
-export function readRecord(file) {
-  try { return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '')); }
-  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
-}
-export function writeRecord(file, value) {
-  const temp = `${file}.${randomUUID()}.tmp`;
-  try {
-    fs.writeFileSync(temp, JSON.stringify(value, null, 2), { mode: 0o600 });
-    fs.renameSync(temp, file);
-  } finally { fs.rmSync(temp, { force: true }); }
-}
-
-export function lifecycle({ stateRoot, host }) {
-  fs.mkdirSync(stateRoot, { recursive: true });
-  const sessionPath = path.join(stateRoot, 'bridge-session.json');
-  const configPath = path.join(stateRoot, 'bridge-config.json');
-  const contextPath = path.join(stateRoot, 'bridge-startup-context.json');
-  const scriptPath = fileURLToPath(new URL('./server.mjs', import.meta.url));
-
-  async function alive(session) {
-    if (!session?.controlPort || !session.instanceId || !session.controlSecret) {
-      if (await health(session)) throw new Error('当前为旧版 Bridge，请先使用旧版停止入口结束服务，再启动新版。');
-      return false;
-    }
-    try { await controlRequest(session); return true; }
-    catch (error) { if (error.code === 'ECONNREFUSED') return false; throw error; }
-  }
-  async function stop() {
-    const session = readRecord(sessionPath);
-    if (!await alive(session)) return { stopped: true, message: 'Bridge 已停止。' };
-    await controlRequest(session, 'POST');
-    const deadline = Date.now() + 10000;
-    while (true) {
-      try { if (!await alive(session)) break; }
-      catch (error) {
-        // A connection accepted just before the listener closes may be reset.
-        // Verify refusal on the next connection; never resend the shutdown request.
-        if (error.code !== 'ECONNRESET') throw error;
-      }
-      if (Date.now() > deadline) throw new Error('Bridge 未在 10 秒内退出；未强杀进程。');
-      await delay(100);
-    }
-    return { stopped: true, message: 'Bridge 已正常关闭。' };
-  }
-  async function status() {
-    const session = readRecord(sessionPath);
-    const running = await alive(session);
+import { randomBytes, randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { controlRequest } from './service-control.mjs';
+import { serviceHealth as health } from './service-health.mjs';
+
+export function readRecord(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+export function writeRecord(file, value) {
+  const temp = `${file}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temp, JSON.stringify(value, null, 2), { mode: 0o600 });
+    fs.renameSync(temp, file);
+  } finally { fs.rmSync(temp, { force: true }); }
+}
+
+export function lifecycle({ stateRoot, host }) {
+  fs.mkdirSync(stateRoot, { recursive: true });
+  const sessionPath = path.join(stateRoot, 'bridge-session.json');
+  const configPath = path.join(stateRoot, 'bridge-config.json');
+  const scriptPath = fileURLToPath(new URL('./server.mjs', import.meta.url));
+
+  async function alive(session) {
+    if (!session?.controlPort || !session.instanceId || !session.controlSecret) {
+      if (await health(session)) throw new Error('当前为旧版桌面服务，请先使用旧版停止入口结束服务，再启动新版。');
+      return false;
+    }
+    try { await controlRequest(session); return true; }
+    catch (error) { if (error.code === 'ECONNREFUSED') return false; throw error; }
+  }
+  async function stop() {
+    const session = readRecord(sessionPath);
+    if (!await alive(session)) return { stopped: true, message: '桌面服务已停止。' };
+    await controlRequest(session, 'POST');
+    const deadline = Date.now() + 10000;
+    while (true) {
+      try { if (!await alive(session)) break; }
+      catch (error) {
+        // A connection accepted just before the listener closes may be reset.
+        // Verify refusal on the next connection; never resend the shutdown request.
+        if (error.code !== 'ECONNRESET') throw error;
+      }
+      if (Date.now() > deadline) throw new Error('桌面服务未在 10 秒内退出；未强杀进程。');
+      await delay(100);
+    }
+    return { stopped: true, message: '桌面服务已正常关闭。' };
+  }
+  async function status() {
+    const session = readRecord(sessionPath);
+    const running = await alive(session);
     const result = running ? await health(session) : null;
     return { running: running && result?.status === 'ok', processRunning: running, pid: session?.pid,
-      port: session?.port, mode: result?.transportMode, execution: result?.execution,
+      port: session?.port, mode: result?.transportMode, version: result?.version, execution: result?.execution,
       managedAppServer: result?.managedAppServer, desktop: result?.desktop,
+      keepAwake: result?.keepAwake,
       desktopRestartRecommended: result?.desktopRestartRecommended === true,
       resident: result?.resident === true };
-  }
-  async function pair() {
-    const session = readRecord(sessionPath);
-    const connection = await alive(session) ? await health(session) : null;
-    if (connection?.status !== 'ok' || !session.lan) {
+  }
+  async function pair() {
+    const session = readRecord(sessionPath);
+    const connection = await alive(session) ? await health(session) : null;
+    if (connection?.status !== 'ok' || !session.lan) {
       throw new Error('没有健康的局域网服务，请先执行 relax start。');
-    }
-    const address = await host.lanAddress();
-    const url = new URL(session.accessUrl);
+    }
+    const address = await host.lanAddress();
+    const url = new URL(session.accessUrl);
     url.hostname = address || '127.0.0.1';
-    session.accessUrl = url.href;
-    writeRecord(sessionPath, session);
-    return { pid: session.pid, port: session.port, transportMode: connection.transportMode,
+    session.accessUrl = url.href;
+    writeRecord(sessionPath, session);
+    return { pid: session.pid, port: session.port, version: connection.version, transportMode: connection.transportMode,
       execution: connection.execution, managedAppServer: connection.managedAppServer, desktop: connection.desktop,
       desktopRestartRecommended: connection.desktopRestartRecommended === true, accessUrl: session.accessUrl,
       qrPath: path.join(stateRoot, 'connection-qr.png') };
-  }
-  async function start() {
+  }
+  async function restartManagedAppServer(confirmed = false) {
+    const session = readRecord(sessionPath);
+    if (!await alive(session)) throw new Error('桌面服务尚未运行，无法迁移 Codex 内核。');
+    const action = confirmed ? 'restart-managed-app-server-confirmed' : 'restart-managed-app-server';
+    return controlRequest(session, 'POST', action);
+  }
+  async function startBridge() {
     let session = readRecord(sessionPath);
     if (await alive(session)) {
-      const result = await health(session);
+      const result = await health(session);
       if (session.scriptPath === scriptPath && session.lan && result?.status === 'ok' && result.resident) {
-        const context = readRecord(contextPath) || {};
-        const sourceThreadId = process.env.CODEX_THREAD_ID || process.env.CODEX_SESSION_ID || context.sourceThreadId;
-        writeRecord(contextPath, { sourceThreadId });
         await controlRequest(session, 'POST', 'refresh-execution');
         return pair();
       }
-      await stop();
-    }
-    let config = readRecord(configPath);
-    if (!config && session?.lan) config = { port: session.port, token: new URL(session.accessUrl).searchParams.get('token') };
-    config ||= { port: 45831, token: randomBytes(32).toString('base64url') };
-    if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535 || !/^[A-Za-z0-9_-]{20,}$/.test(config.token)) {
-      throw new Error('bridge-config.json 中端口或 Token 无效；不会自动重置凭据。');
-    }
+      await stop();
+    }
+    let config = readRecord(configPath);
+    if (!config && session?.lan) config = { port: session.port, token: new URL(session.accessUrl).searchParams.get('token') };
+    config ||= { port: 45831, token: randomBytes(32).toString('base64url') };
+    if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535 || !/^[A-Za-z0-9_-]{20,}$/.test(config.token)) {
+      throw new Error('bridge-config.json 中端口或 Token 无效；不会自动重置凭据。');
+    }
     const address = await host.lanAddress() || '127.0.0.1';
-    const { executable, environment } = await host.desktopEnvironment(readRecord(contextPath), '');
-    writeRecord(configPath, config);
-    writeRecord(contextPath, { sourceThreadId: environment.CODEX_THREAD_ID || environment.CODEX_SESSION_ID });
-    const instanceId = randomUUID();
-    const controlSecret = randomBytes(32).toString('base64url');
-    const readyPath = path.join(stateRoot, `bridge-ready-${instanceId}.json`);
+    const { executable, environment } = await host.bridgeEnvironment();
+    writeRecord(configPath, config);
+    const instanceId = randomUUID();
+    const controlSecret = randomBytes(32).toString('base64url');
+    const readyPath = path.join(stateRoot, `bridge-ready-${instanceId}.json`);
     const pid = await startBackground(executable, [scriptPath, '--lan', '--port', String(config.port), '--token', config.token],
       { ...environment, CODEX_REMOTE_INSTANCE: instanceId, CODEX_REMOTE_CONTROL_SECRET: controlSecret,
         CODEX_REMOTE_READY_PATH: readyPath }, [path.join(stateRoot, 'bridge.stdout.log'), path.join(stateRoot, 'bridge.stderr.log')]);
-    try {
-      const deadline = Date.now() + 10000;
-      let ready;
-      while (!(ready = readRecord(readyPath))) {
-        if (!processAlive(pid)) throw new Error('Bridge 启动失败，请查看 bridge.stderr.log。');
-        if (Date.now() > deadline) throw new Error('Bridge 未在 10 秒内就绪。');
-        await delay(100);
-      }
-      if (ready.instanceId !== instanceId || ready.pid !== pid) throw new Error('Bridge 启动实例不匹配。');
-      session = { ...ready, controlSecret, executablePath: executable, scriptPath, port: config.port,
-        lan: true, appServer: false, accessUrl: `http://${address}:${config.port}/?token=${config.token}`,
-        startedAt: new Date().toISOString() };
-      await controlRequest(session);
-      writeRecord(sessionPath, session);
-      return await pair();
-    } catch (error) {
+    try {
+      const deadline = Date.now() + 10000;
+      let ready;
+      while (!(ready = readRecord(readyPath))) {
+        if (!processAlive(pid)) throw new Error('桌面服务启动失败，请查看 bridge.stderr.log。');
+        if (Date.now() > deadline) throw new Error('桌面服务未在 10 秒内就绪。');
+        await delay(100);
+      }
+      if (ready.instanceId !== instanceId || ready.pid !== pid) throw new Error('桌面服务启动实例不匹配。');
+      session = { ...ready, controlSecret, executablePath: executable, scriptPath, port: config.port,
+        lan: true, appServer: false, accessUrl: `http://${address}:${config.port}/?token=${config.token}`,
+        startedAt: new Date().toISOString() };
+      await controlRequest(session);
+      writeRecord(sessionPath, session);
+      return await pair();
+    } catch (error) {
       if (processAlive(pid)) process.kill(pid);
-      throw error;
-    } finally { fs.rmSync(readyPath, { force: true }); }
-  }
-  return { start, pair, status, stop };
-}
+      throw error;
+    } finally { fs.rmSync(readyPath, { force: true }); }
+  }
+  async function start() {
+    const result = await startBridge();
+    if (fs.existsSync(path.join(stateRoot, 'self-relay-config.json'))) {
+      await controlRequest(readRecord(sessionPath), 'POST', 'relay-start');
+    }
+    return result;
+  }
+  return { start, pair, status, stop, restartManagedAppServer };
+}

package/dist/src/service-power.mjs

@@ -0,0 +1,58 @@
+import path from 'node:path';
+import { readRecord, writeRecord } from './service-lifecycle.mjs';
+import { launchPowerInhibitor } from './platform/power-inhibitor.mjs';
+
+export const powerConfigPath = stateRoot => path.join(stateRoot, 'keep-awake.json');
+export const powerEnabled = stateRoot => readRecord(powerConfigPath(stateRoot))?.enabled !== false;
+
+export function createPowerManager(stateRoot, { launch = launchPowerInhibitor, report = console.error } = {}) {
+  let enabled = powerEnabled(stateRoot), active = false, error = '', child = null, closed, stopping = false;
+  let queue = Promise.resolve();
+  const snapshot = () => ({ enabled, active, error });
+  async function release() {
+    if (!child) return;
+    stopping = true;
+    child.stdin.end();
+    await closed;
+  }
+  async function acquire() {
+    if (child || !enabled) return;
+    error = '';
+    try {
+      const process = launch();
+      stopping = false;
+      child = process;
+      let stderr = '', output = '';
+      process.stderr.on('data', data => { stderr = (stderr + data).slice(-2048); });
+      process.stdin.on('error', cause => { if (cause.code !== 'EPIPE') report(`保持唤醒通道异常：${cause.message}`); });
+      closed = new Promise(resolve => process.once('close', code => {
+        if (active && !stopping) { error = stderr.trim() || `保持唤醒进程意外退出（${code}）`; report(error); }
+        child = null; active = false; resolve();
+      }));
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { process.kill(); reject(new Error('保持唤醒申请超时')); }, 8000);
+        const finish = cause => { clearTimeout(timer); cause ? reject(cause) : resolve(); };
+        process.once('error', finish);
+        process.once('close', code => {
+          finish(new Error(stderr.trim() || `保持唤醒进程已退出（${code}）`));
+        });
+        process.stdout.on('data', data => {
+          output += data;
+          if (output.includes('ready\n') || output.includes('ready\r\n')) { active = true; finish(); }
+        });
+      });
+    } catch (cause) { error = cause.message; report(`保持唤醒未生效：${error}`); }
+  }
+  const serial = task => { const result = queue.then(task); queue = result.catch(() => {}); return result; };
+  return {
+    snapshot,
+    start: () => serial(async () => { await acquire(); return snapshot(); }),
+    setEnabled: value => serial(async () => {
+      writeRecord(powerConfigPath(stateRoot), { enabled: value });
+      enabled = value;
+      if (enabled) await acquire(); else { await release(); error = ''; }
+      return snapshot();
+    }),
+    close: () => serial(async () => { enabled = false; await release(); }),
+  };
+}

package/dist/src/service-restart.mjs

@@ -4,36 +4,69 @@ import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
 import { startBackground } from './background-process.mjs';
-import { lifecycle, readRecord } from './service-lifecycle.mjs';
-import * as host from './platform/windows/service-host.mjs';
+import { lifecycle, readRecord, writeRecord } from './service-lifecycle.mjs';
+import * as host from './platform/service-host.mjs';
+import { desktopHost } from './platform/desktop-host.mjs';
 
 const script = fileURLToPath(import.meta.url);
+const sameProcess = (expected, actual) => expected && actual && expected.pid === actual.pid &&
+  expected.created === actual.created && expected.executable === actual.executable;
+async function processIdentity(pid) {
+  const current = await desktopHost.process(pid);
+  return current ? { pid: current.pid, created: current.created, executable: current.executable } : null;
+}
 
 export async function requestServiceRestart(stateRoot) {
   const lock = path.join(stateRoot, 'service-restart.lock');
   const operationId = randomUUID();
-  let handle;
+  const owner = await processIdentity(process.pid);
+  if (!owner) throw new Error('无法确认桌面服务重启请求进程。');
+  const previous = readRecord(lock);
+  if (previous) {
+    const actual = previous.owner?.pid ? await processIdentity(previous.owner.pid) : null;
+    if (sameProcess(previous.owner, actual) || readRecord(lock)?.operationId !== previous.operationId) {
+      throw new Error('桌面服务已在重启中。');
+    }
+    fs.rmSync(lock);
+  }
+  const temporary = `${lock}.${operationId}.tmp`;
   try {
-    handle = fs.openSync(lock, 'wx', 0o600);
-    fs.writeFileSync(handle, JSON.stringify({ operationId, requestedAt: new Date().toISOString() }));
+    fs.writeFileSync(temporary, JSON.stringify({ operationId, owner, requestedAt: new Date().toISOString() }),
+      { flag: 'wx', mode: 0o600 });
+    // Publish a complete record exclusively; a crash cannot leave a half-written lock.
+    fs.linkSync(temporary, lock);
   } catch (error) {
-    if (error.code === 'EEXIST') throw new Error('工作站服务已在重启中。');
+    if (error.code === 'EEXIST') throw new Error('桌面服务已在重启中。');
     throw error;
-  } finally { if (handle !== undefined) fs.closeSync(handle); }
+  } finally { fs.rmSync(temporary, { force: true }); }
   try {
     const log = path.join(stateRoot, 'service-restart.log');
-    await startBackground(process.execPath, [script, '--worker', stateRoot, operationId], process.env, [log, log]);
-    return { operationId, status: 'scheduled', message: '工作站服务重启已安排。' };
+    const pid = await startBackground(process.execPath, [script, '--worker', stateRoot, operationId], process.env, [log, log]);
+    const worker = await processIdentity(pid);
+    if (!worker) throw new Error('桌面服务重启进程未启动。');
+    const current = readRecord(lock);
+    if (current?.operationId !== operationId) throw new Error('桌面服务重启实例已失效。');
+    writeRecord(lock, { ...current, owner: worker });
+    return { operationId, status: 'scheduled', message: '桌面服务重启已安排。' };
   } catch (error) {
-    fs.rmSync(lock, { force: true }); throw error;
+    const current = readRecord(lock);
+    if (current?.operationId === operationId && sameProcess(current.owner, owner)) fs.rmSync(lock, { force: true });
+    throw error;
   }
 }
 
 async function run(stateRoot, operationId) {
   const lock = path.join(stateRoot, 'service-restart.lock');
-  if (readRecord(lock)?.operationId !== operationId) throw new Error('服务重启实例已失效。');
-  const service = lifecycle({ stateRoot, host });
   try {
+    const deadline = Date.now() + 30000;
+    while (true) {
+      const record = readRecord(lock);
+      if (record?.operationId !== operationId) throw new Error('桌面服务重启实例已失效。');
+      if (record.owner?.pid === process.pid) break;
+      if (Date.now() >= deadline) throw new Error('桌面服务重启进程交接超时。');
+      await delay(100);
+    }
+    const service = lifecycle({ stateRoot, host });
     await delay(1000);
     await service.stop();
     await service.start();

package/dist/src/service-update-worker.mjs

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+
+// Copied outside both npm and service directories before launch. Builtins only.
+const jobFile = process.argv[2];
+const job = JSON.parse(fs.readFileSync(jobFile, 'utf8'));
+process.chdir(path.dirname(jobFile));
+const read = () => JSON.parse(fs.readFileSync(job.statusFile, 'utf8'));
+function update(values) {
+  const current = read();
+  if (current.operationId !== job.operationId) throw new Error('更新操作已被替换');
+  const temporary = `${job.statusFile}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, JSON.stringify({ ...current, ...values }), { mode: 0o600 });
+  fs.renameSync(temporary, job.statusFile);
+}
+try {
+  const deadline = Date.now() + 30000;
+  while (read().owner?.pid !== process.pid) {
+    if (Date.now() >= deadline) throw new Error('独立更新进程交接超时');
+    await delay(100);
+  }
+  await delay(1500);
+  update({ status: 'running', startedAt: new Date().toISOString() });
+  const args = [job.npmCliPath, 'install', '--global', `@walkhi/code-relax@${job.targetVersion}`,
+    '--foreground-scripts', '--allow-scripts=@walkhi/code-relax,node-datachannel,sharp', '--registry=https://registry.npmjs.org'];
+  if (job.npmPrefix) args.push('--prefix', job.npmPrefix);
+  const child = spawn(job.nodeExecutable, args, { cwd: path.dirname(jobFile), windowsHide: true,
+    stdio: ['ignore', 'inherit', 'inherit'] });
+  const code = await new Promise((resolve, reject) => {
+    child.once('error', reject); child.once('exit', (code, signal) => resolve(code ?? `signal ${signal}`));
+  });
+  if (code !== 0) throw new Error(`npm 安装失败（${code}），请查看桌面服务更新日志。`);
+  const installed = JSON.parse(fs.readFileSync(path.join(job.serviceRoot, 'installation.json'), 'utf8'));
+  if (installed.version !== job.targetVersion) throw new Error('安装结束，但桌面服务版本与目标版本不一致。');
+  update({ status: 'completed', finishedAt: new Date().toISOString(), installedVersion: installed.version });
+} catch (error) {
+  console.error(error.stack || error.message);
+  update({ status: 'failed', finishedAt: new Date().toISOString(), error: error.message });
+  process.exitCode = 1;
+}

package/dist/src/service-update.mjs

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { startBackground } from './background-process.mjs';
+import { readRecord, writeRecord } from './service-lifecycle.mjs';
+import { runtimePaths } from './platform/runtime-paths.mjs';
+import { desktopHost } from './platform/desktop-host.mjs';
+
+const versionPattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const statusPath = root => path.join(root, 'service-update.json');
+const installation = () => readRecord(path.join(runtimePaths().serviceRoot, 'installation.json'));
+export function publicUpdateOperation(record, installedVersion) {
+  if (!record) return null;
+  return { operationId: record.operationId, targetVersion: record.targetVersion,
+    status: record.status, targetInstalled: Boolean(installedVersion && installedVersion === record.targetVersion),
+    error: record.status === 'failed' ? '上次更新未完整完成，请查看桌面服务更新日志。' : null,
+    installedVersion: record.installedVersion || null };
+}
+export function serviceUpdateStatus(root) {
+  const record = readRecord(statusPath(root));
+  const installed = installation();
+  return { supported: Boolean(installed?.npmCliPath && fs.existsSync(installed.npmCliPath)),
+    currentVersion: installed?.version || null,
+    operation: publicUpdateOperation(record, installed?.version) };
+}
+export async function checkServiceUpdate(root) {
+  const result = await fetch('https://registry.npmjs.org/@walkhi%2fcode-relax/latest', { signal: AbortSignal.timeout(12000) });
+  if (!result.ok) throw new Error(`查询桌面服务版本失败：HTTP ${result.status}`);
+  const latest = await result.json();
+  if (!versionPattern.test(latest.version || '')) throw new Error('npm 返回的版本号无效');
+  return { ...serviceUpdateStatus(root), latestVersion: latest.version };
+}
+let scheduling = false;
+export async function requestServiceUpdate(root, body) {
+  if (body.confirmed !== true || !/^[0-9a-f-]{36}$/i.test(body.operationId || '') || !versionPattern.test(body.targetVersion || '')) {
+    throw new Error('请确认桌面服务更新及目标版本后再继续。');
+  }
+  if (scheduling) throw new Error('桌面服务更新正在安排。');
+  scheduling = true;
+  try {
+    const previous = readRecord(statusPath(root));
+    if (previous?.operationId === body.operationId) return serviceUpdateStatus(root);
+    if (previous && ['scheduled', 'running'].includes(previous.status)) {
+      const actual = previous.owner?.pid ? await desktopHost.process(previous.owner.pid) : null;
+      if (actual && actual.created === previous.owner.created && actual.executable === previous.owner.executable) {
+        throw new Error('桌面服务已有更新正在执行。');
+      }
+      writeRecord(statusPath(root), { ...previous, status: 'failed', error: '更新进程已退出，未确认安装完成。' });
+    }
+    const latest = await checkServiceUpdate(root);
+    if (!latest.supported) throw new Error('当前安装缺少 npm 路径，请先安装支持手机更新的过渡版。');
+    if (latest.latestVersion !== body.targetVersion) throw new Error('最新版本已变化，请重新检查后确认。');
+    if (latest.currentVersion === body.targetVersion) throw new Error('桌面服务已是此版本。');
+    const installed = installation();
+    const directory = path.join(root, 'service-updates', body.operationId);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const worker = path.join(directory, 'worker.mjs');
+    fs.copyFileSync(fileURLToPath(new URL('./service-update-worker.mjs', import.meta.url)), worker);
+    const jobFile = path.join(directory, 'job.json');
+    writeRecord(jobFile, { ...body, statusFile: statusPath(root), npmCliPath: installed.npmCliPath,
+      npmPrefix: installed.npmPrefix, nodeExecutable: installed.nodeExecutable, serviceRoot: runtimePaths().serviceRoot });
+    writeRecord(statusPath(root), { operationId: body.operationId, targetVersion: body.targetVersion,
+      status: 'scheduled', requestedAt: new Date().toISOString() });
+    try {
+      const log = path.join(directory, 'update.log');
+      const pid = await startBackground(installed.nodeExecutable, [worker, jobFile], process.env, [log, log]);
+      const owner = await desktopHost.process(pid);
+      if (!owner) throw new Error('独立更新进程未启动。');
+      writeRecord(statusPath(root), { ...readRecord(statusPath(root)), owner: {
+        pid: owner.pid, created: owner.created, executable: owner.executable } });
+    } catch (error) {
+      writeRecord(statusPath(root), { ...readRecord(statusPath(root)), status: 'failed', error: error.message });
+      throw new Error('桌面服务更新启动未完成，请查看桌面服务更新日志；结果确认前不要重复提交。');
+    }
+    return serviceUpdateStatus(root);
+  } finally { scheduling = false; }
+}