orbit-codex-bridge 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# Orbit · 会话随行
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+从手机连接自己的电脑，查看和继续 Codex 桌面里的原会话。
+
+Orbit 将电脑连接到 [Orbit 工作台](https://orbit.cubesugar.tech)。在网页中选择电脑和会话，即可查看历史、接收实时回复、发送指令、停止任务和处理审批。桌面已加载的会话会自动热接管，沿用原会话 ID 和执行上下文。
+
+## 安装与连接
+
+需要 Node.js 24+，并在电脑上安装、运行 Codex 桌面应用。
+
+Windows PowerShell：
+
+```powershell
+npx.cmd --yes --package=orbit-codex-bridge@latest orbit login
+```
+
+macOS / Linux：
+
+```sh
+npx --yes --package=orbit-codex-bridge@latest orbit login
+```
+
+也可以全局安装，之后直接使用 `orbit` 命令：
+
+```sh
+npm install --global orbit-codex-bridge@latest
+orbit login
+```
+
+1. 命令会打开电脑授权页面，登录或注册 Orbit 账号，确认添加这台电脑。
+2. 手机打开 [orbit.cubesugar.tech](https://orbit.cubesugar.tech)，登录同一账号。
+3. 扫描终端显示的配对二维码，选择这台电脑，完成首次连接。
+4. 选择原有会话，开始使用。尚未加载的会话可先在 Codex 桌面打开，再点“重新连接”。
+
+授权信息保存在电脑本地，下次启动会自动复用。连接器默认在当前用户的后台运行，可以关闭安装终端；断网后自动重连，工作进程异常退出后自动恢复。电脑需要保持开机、联网，Codex 桌面需要保持运行。电脑重启后运行 `orbit start` 恢复连接。
+
+## 常用命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `orbit login` | 首次授权，或复用已有授权启动后台连接器 |
+| `orbit start` | 启动后台连接器 |
+| `orbit status` | 查看后台运行状态、云端连接状态及日志路径 |
+| `orbit stop` | 停止后台连接器，保留授权 |
+| `orbit restart` | 重启后台连接器 |
+| `orbit logout` | 停止连接并撤销这台电脑的授权 |
+| `orbit rebind` | 清理旧绑定，重新打开网页授权这台电脑 |
+| `orbit login --foreground` | 在当前终端运行，显示实时诊断信息 |
+
+自建服务可在首次授权时指定地址：
+
+```sh
+orbit login --server https://your-orbit-domain.com
+```
+
+## 更新
+
+使用 npx 的用户重新执行安装命令即可获取最新版。全局安装的用户运行：
+
+```sh
+npm install --global orbit-codex-bridge@latest
+orbit login
+```
+
+连接器会更新后台运行时，复用已有电脑授权。
+
+从早期需要保持终端打开的版本升级时，先在旧终端按 `Ctrl+C` 停止旧连接器，再运行新版命令。
+
+## 移除与重新绑定
+
+在工作台的电脑列表点击“移除电脑”，确认后立即撤销连接凭证，释放设备名额。需要再次绑定时，在原电脑执行：
+
+```powershell
+npx.cmd --yes --package=orbit-codex-bridge@latest orbit rebind
+```
+
+重新登录并确认电脑授权即可。移除或重绑不会删除电脑上的 Codex 项目和原有会话。
+
+## 常见问题
+
+**Windows 提示禁止运行 `npx.ps1`**
+
+在 PowerShell 中使用 `npx.cmd`。全局安装时也可使用 `npm.cmd`，无需修改系统脚本执行策略。
+
+**电脑显示离线**
+
+先确认电脑开机并联网，运行 `orbit status` 查看状态。短暂断网会自动恢复；电脑重启后运行 `orbit start`。仍有问题时，按状态命令显示的路径查看 `connector.log`，或使用 `orbit login --foreground` 诊断。
+
+**能看历史，但会话尚未连接**
+
+在 Codex 桌面打开同一条会话，再点击网页中的“重新连接”。桌面热接管依赖 Codex 内部接口，桌面版本更新后可能需要更新 Orbit。
+
+**配对二维码与密钥**
+
+只在自己的设备上使用。每台电脑使用独立连接凭证，可在工作台移除电脑，或运行 `orbit logout` 撤销授权。连接中断时，Orbit 不会自动重发已提交的消息和审批。

package/cli.mjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import QRCode from 'qrcode';
+import { createOrbitServer } from './server.mjs';
+import { createRelayAgent } from './relay-agent.mjs';
+import {connectorStatus,installConnectorRuntime,startConnector,stopConnector,superviseConnector} from './lib/connector-service.mjs';
+
+const defaultServerUrl = 'https://orbit.cubesugar.tech';
+const packageDirectory = path.dirname(fileURLToPath(import.meta.url));
+
+function configDirectory() {
+  if (process.env.ORBIT_HOME) return path.resolve(process.env.ORBIT_HOME);
+  if (process.platform === 'win32') return path.join(process.env.LOCALAPPDATA || os.homedir(), 'Orbit');
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'orbit');
+}
+
+function configPath() {
+  return path.join(configDirectory(), 'device.json');
+}
+
+function normalizedServer(value) {
+  const parsed = new URL(value || defaultServerUrl);
+  if (parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.pathname !== '/'
+    || parsed.search || parsed.hash) throw new Error('Orbit 服务器地址必须为 HTTPS 域名。');
+  return parsed.origin;
+}
+
+async function saveConfig(config) {
+  const directory = configDirectory();
+  await fs.mkdir(directory, {recursive:true, mode:0o700});
+  const filename = configPath();
+  const temporary = `${filename}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  try {
+    await fs.writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, {encoding:'utf8', mode:0o600, flag:'wx'});
+    await fs.rename(temporary, filename);
+    try { await fs.chmod(filename, 0o600); } catch {}
+  } catch (error) {
+    try { await fs.unlink(temporary); } catch {}
+    throw error;
+  }
+}
+
+async function loadConfig() {
+  const filename = configPath();
+  try {
+    const config = JSON.parse(await fs.readFile(filename, 'utf8'));
+    if (config.version !== 1 || !config.deviceId || !config.agentToken || !config.relayUrl || !config.publicUrl) {
+      throw new Error(`Orbit 配置无效，请先删除 ${filename} 后运行 orbit login。`);
+    }
+    return config;
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function openBrowser(url) {
+  const command = process.platform === 'win32' ? 'rundll32.exe'
+    : process.platform === 'darwin' ? 'open' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+  try {
+    const child = spawn(command, args, {detached:true, stdio:'ignore', windowsHide:true});
+    child.on('error', () => {});
+    child.unref();
+  } catch {}
+}
+
+async function requestDeviceAuthorization(serverUrl, name) {
+  const response = await fetch(`${serverUrl}/api/cloud/device-auth/start`, {
+    method:'POST',
+    headers:{'Content-Type':'application/json'},
+    body:JSON.stringify({name})
+  });
+  const result = await response.json();
+  if (!response.ok) throw new Error(result.error || `无法发起设备连接 (${response.status})`);
+  return result;
+}
+
+async function waitForDeviceAuthorization(serverUrl, deviceCode, interval) {
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+  console.log('等待你在 Orbit 网页确认这台电脑。按 Ctrl+C 取消。');
+  try {
+    while (!controller.signal.aborted) {
+      const response = await fetch(`${serverUrl}/api/cloud/device-auth/poll`, {
+        method:'POST',
+        headers:{'Content-Type':'application/json'},
+        body:JSON.stringify({deviceCode}),
+        signal:controller.signal
+      });
+      const result = await response.json();
+      if (response.status === 200) return result;
+      if (!response.ok) throw new Error(result.error || `设备授权失败 (${response.status})`);
+      await new Promise((resolve, reject) => {
+        const finish = error => {
+          clearTimeout(timer);
+          controller.signal.removeEventListener('abort', onAbort);
+          error ? reject(error) : resolve();
+        };
+        const onAbort = () => finish(new DOMException('The operation was aborted.', 'AbortError'));
+        const timer = setTimeout(() => finish(), interval * 1000);
+        controller.signal.addEventListener('abort', onAbort, {once:true});
+      });
+    }
+  } finally {
+    process.off('SIGINT', stop);
+    process.off('SIGTERM', stop);
+  }
+  throw new DOMException('The operation was aborted.', 'AbortError');
+}
+
+async function authorizeComputer(serverUrl, name) {
+  const authorization = await requestDeviceAuthorization(serverUrl, name);
+  console.log(`\n在手机或浏览器打开：${authorization.verificationUri}`);
+  console.log(`登录 Orbit 后输入连接码：${authorization.userCode}`);
+  console.log(`连接码 ${Math.ceil(authorization.expiresIn / 60)} 分钟后失效。\n`);
+  openBrowser(authorization.verificationUri);
+  const issued = await waitForDeviceAuthorization(serverUrl, authorization.deviceCode, authorization.interval);
+  const config = {
+    version:1,
+    deviceId:issued.device.id,
+    deviceName:issued.device.name,
+    agentToken:issued.agentToken,
+    relayUrl:`${serverUrl.replace(/^https:/, 'wss:')}/agent`,
+    publicUrl:serverUrl,
+    port:4318
+  };
+  await saveConfig(config);
+  return config;
+}
+
+export async function existingOrbitUrl(port) {
+  const url=`http://127.0.0.1:${port}`;
+  try {
+    const response=await fetch(`${url}/healthz`,{signal:AbortSignal.timeout(1500),cache:'no-store'});
+    if(!response.ok)return null;
+    const health=await response.json();
+    return health.ok===true?url:null;
+  } catch { return null; }
+}
+
+async function printPairing(pairingKey, publicUrl) {
+  const pairingUrl = `${publicUrl}/#pair=${encodeURIComponent(pairingKey)}`;
+  console.log('本机配对二维码和密钥仅供自己的手机使用，请勿公开。');
+  console.log(await QRCode.toString(pairingUrl,{type:'terminal',errorCorrectionLevel:'L',small:true}));
+  console.log(`本机配对密钥：${pairingKey}`);
+}
+
+async function runComputer(config, background = false) {
+  process.env.ORBIT_HOST = '127.0.0.1';
+  process.env.ORBIT_PORT = String(config.port || 4318);
+  process.env.ORBIT_PUBLIC_URL = config.publicUrl;
+  let app=null;
+  let agent;
+  let localUrl=await existingOrbitUrl(config.port || 4318);
+  if(localUrl)console.log(`检测到本机 Orbit 已运行，将复用 ${localUrl} 并连接云端。`);
+  try {
+    if(!localUrl){
+      app=createOrbitServer({dataDir:configDirectory(),publicUrl:config.publicUrl});
+      const info=await app.listen();
+      localUrl=info.url;
+      console.log(`Orbit 电脑端运行中：${localUrl}`);
+      if (!background) await printPairing(app.pairingKey,config.publicUrl);
+    }
+    agent = createRelayAgent({
+      relayUrl:config.relayUrl,
+      localUrl,
+      deviceId:config.deviceId,
+      agentToken:config.agentToken,
+      onReady:() => console.log(`电脑“${config.deviceName}”已安全连接 Orbit。`),
+      onState:state => {
+        if (background && process.connected) process.send({type:'connector-state',state:{...state,workerReady:true}},() => {});
+      },
+      onError:error => console.error(`Orbit 连接暂时中断：${error.message}`)
+    });
+    agent.start();
+    if(!app)console.log(`复用本机 Orbit：${localUrl}`);
+    console.log(`手机工作台：${config.publicUrl}`);
+    if (!background) console.log('前台诊断模式；保持此窗口运行，按 Ctrl+C 停止。');
+    await new Promise(resolve => {
+      const stop = () => {
+        process.off('SIGINT',stop);process.off('SIGTERM',stop);process.off('message',message);process.off('disconnect',stop);
+        resolve();
+      };
+      const message = packet => { if (packet?.type === 'stop') stop(); };
+      process.once('SIGINT',stop);
+      process.once('SIGTERM',stop);
+      if (background) {process.on('message',message);process.once('disconnect',stop);}
+    });
+  } finally {
+    agent?.stop();
+    if (app) await app.close();
+  }
+}
+
+async function runBackground(config) {
+  console.log('正在启动 Orbit 后台连接器…');
+  const runtime = await installConnectorRuntime(packageDirectory,configDirectory());
+  const service = await startConnector({home:configDirectory(),...runtime});
+  const label = service.status === 'online' ? '已连接云端' : service.status === 'blocked' ? service.reason : '正在自动连接云端';
+  console.log(`电脑“${config.deviceName}”后台运行中 · ${label}`);
+  console.log(`手机工作台：${config.publicUrl}`);
+  console.log('可以关闭此终端。断网自动重连，异常退出自动恢复；电脑休眠期间无法远程使用。');
+  console.log('停止：orbit stop；状态：orbit status；前台诊断：orbit login --foreground');
+  console.log(`诊断日志：${path.join(configDirectory(),'connector.log')}`);
+  try {
+    const key = (await fs.readFile(path.join(configDirectory(),'pairing-key'),'utf8')).trim();
+    if (key) await printPairing(key,config.publicUrl);
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+}
+
+async function revokeComputer(config) {
+  const response = await fetch(`${config.publicUrl}/api/cloud/device-auth/revoke`, {
+    method:'POST',
+    headers:{'Authorization':`Bearer ${config.agentToken}`,'Content-Type':'application/json'},
+    body:JSON.stringify({deviceId:config.deviceId}),
+    signal:AbortSignal.timeout(15000)
+  });
+  if (!response.ok && response.status !== 404) {
+    const result = await response.json().catch(() => ({}));
+    throw new Error(result.error || `无法撤销电脑凭证 (${response.status})。请检查网络后重试。`);
+  }
+  await stopConnector(configDirectory());
+  await fs.unlink(configPath());
+}
+
+async function main() {
+  const [command = 'login', ...args] = process.argv.slice(2);
+  if (command === '--version' || command === '-v') {
+    console.log(JSON.parse(await fs.readFile(path.join(packageDirectory, 'package.json'), 'utf8')).version);
+    return;
+  }
+  if (command === '--help' || command === '-h' || command === 'help') {
+    console.log('Orbit computer connector\n\nUsage:\n  orbit login [--name "My computer"] [--server https://orbit.example.com] [--foreground]\n  orbit start\n  orbit stop\n  orbit restart\n  orbit status\n  orbit logout\n  orbit rebind');
+    return;
+  }
+  const namedIndex = args.indexOf('--name');
+  let name = namedIndex >= 0 ? args[namedIndex + 1] : os.hostname();
+  const serverIndex = args.indexOf('--server');
+  let serverUrl = normalizedServer(serverIndex >= 0 ? args[serverIndex + 1] : process.env.ORBIT_SERVER_URL);
+  let existing = await loadConfig();
+  if (command === '__service' || command === '__worker') {
+    if (!existing) throw new Error('电脑凭证不存在，请运行 orbit login。');
+    if (command === '__worker') {
+      if (!process.connected) throw new Error('工作进程只能由后台连接器启动。');
+      await runComputer(existing,true);
+    } else {
+      const version = JSON.parse(await fs.readFile(path.join(packageDirectory,'package.json'),'utf8')).version;
+      await superviseConnector({home:configDirectory(),config:existing,cliPath:fileURLToPath(import.meta.url),version});
+    }
+    return;
+  }
+
+  if (command === 'status') {
+    const service = await connectorStatus(configDirectory());
+    const labels = {online:'在线',connecting:'连接中',reconnecting:'断线重连中',blocked:'连接被拒绝',starting:'启动中',restarting:'异常恢复中'};
+    console.log(existing
+      ? `电脑：${existing.deviceName}\n工作台：${existing.publicUrl}\n后台服务：${service ? labels[service.status] || service.status : '未运行'}${service?.reason ? ` · ${service.reason}` : ''}\n配置文件：${configPath()}\n日志文件：${path.join(configDirectory(),'connector.log')}`
+      : '此电脑尚未连接 Orbit。运行 orbit login 完成连接。');
+    return;
+  }
+  if (command === 'stop') {
+    console.log(await stopConnector(configDirectory()) ? 'Orbit 后台连接器已停止，授权已保留。' : 'Orbit 后台连接器未运行。');
+    return;
+  }
+  if (command === 'logout') {
+    if (!existing) {
+      console.log('此电脑尚未连接 Orbit。');
+      return;
+    }
+    await revokeComputer(existing);
+    console.log('电脑凭证已从服务器撤销，并从本机删除。');
+    return;
+  }
+  if (!['login','start','restart','rebind'].includes(command)) throw new Error(`未知命令：${command}。运行 orbit --help 查看用法。`);
+  if (command === 'rebind' && existing) {
+    if (namedIndex < 0) name = existing.deviceName;
+    if (serverIndex < 0) serverUrl = normalizedServer(existing.publicUrl);
+    await revokeComputer(existing);
+    existing = null;
+    console.log('旧电脑授权已移除，正在重新绑定。');
+  }
+  if (command === 'restart') await stopConnector(configDirectory());
+  if (existing) {
+    if (args.includes('--foreground')) {
+      await stopConnector(configDirectory());
+      await runComputer(existing);
+    } else await runBackground(existing);
+    return;
+  }
+  console.log('正在为这台电脑申请 Orbit 连接授权…');
+  const config = await authorizeComputer(serverUrl, name);
+  console.log(`已保存电脑“${config.deviceName}”的专属凭证到 ${configPath()}。`);
+  if (args.includes('--foreground')) await runComputer(config);
+  else await runBackground(config);
+}
+
+export async function runCli() {
+  try {
+    await main();
+  } catch(error) {
+    if (error.name === 'AbortError') {
+      console.log('\n已取消 Orbit 连接。');
+      process.exitCode=130;
+    } else {
+      console.error(`Orbit：${error.message}`);
+      process.exitCode=1;
+    }
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await runCli();
+}
+
+export {configDirectory, normalizedServer};

package/lib/connector-service.mjs

@@ -0,0 +1,259 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import http from 'node:http';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+import {createRequire} from 'node:module';
+
+const stateFile = home => path.join(home,'service.json');
+const pause = milliseconds => new Promise(resolve => setTimeout(resolve,milliseconds));
+
+async function serviceRequest(home, action = 'status') {
+  let saved;
+  try { saved = JSON.parse(await fs.readFile(stateFile(home),'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  if (!Number.isInteger(saved.port) || saved.port < 1 || saved.port > 65535 || !/^[a-f0-9]{64}$/.test(saved.token)) return null;
+  try {
+    const response = await fetch(`http://127.0.0.1:${saved.port}/${action}`,{
+      method:action === 'stop' ? 'POST' : 'GET',
+      headers:{Authorization:`Bearer ${saved.token}`},
+      signal:AbortSignal.timeout(1500)
+    });
+    if (!response.ok) return null;
+    const result = await response.json();
+    return result.product === 'Orbit connector' ? result : null;
+  } catch { return null; }
+}
+
+export const connectorStatus = home => serviceRequest(home);
+
+export async function stopConnector(home) {
+  if (!await serviceRequest(home,'stop')) return false;
+  for (let attempt = 0; attempt < 50; attempt++) {
+    const locked = await fs.access(path.join(home,'connector.lock')).then(() => true,() => false);
+    if (!await connectorStatus(home) && !locked) return true;
+    await pause(100);
+  }
+  throw new Error('后台连接器尚未停止，请稍后重试。');
+}
+
+async function packageRoot(resolver, name) {
+  let directory = path.dirname(resolver.resolve(name));
+  while (true) {
+    try {
+      const manifest = JSON.parse(await fs.readFile(path.join(directory,'package.json'),'utf8'));
+      if (manifest.name === name) return directory;
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const parent = path.dirname(directory);
+    if (parent === directory) throw new Error(`找不到依赖：${name}`);
+    directory = parent;
+  }
+}
+
+export async function installConnectorRuntime(source, home) {
+  const manifest = JSON.parse(await fs.readFile(path.join(source,'package.json'),'utf8'));
+  const target = path.join(home,'runtime',manifest.version);
+  try { await fs.access(path.join(target,'ready')); return {cliPath:path.join(target,'cli.mjs'),version:manifest.version}; }
+  catch {}
+  const temporary = `${target}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  await fs.mkdir(temporary,{recursive:true,mode:0o700});
+  const copied = new Map();
+  async function copyDependency(name, resolver) {
+    const original = await packageRoot(resolver,name);
+    if (copied.has(name)) {
+      if (copied.get(name) !== original) throw new Error(`依赖 ${name} 存在多个版本，无法安装后台运行时。`);
+      return;
+    }
+    copied.set(name,original);
+    const destination = path.join(temporary,'node_modules',name);
+    await fs.cp(original,destination,{recursive:true,filter:entry => path.basename(entry) !== 'node_modules'});
+    const dependency = JSON.parse(await fs.readFile(path.join(original,'package.json'),'utf8'));
+    for (const child of Object.keys(dependency.dependencies || {})) {
+      await copyDependency(child,createRequire(path.join(original,'package.json')));
+    }
+  }
+  try {
+    for (const filename of ['package.json',...manifest.files]) {
+      await fs.cp(path.join(source,filename),path.join(temporary,filename),{recursive:true});
+    }
+    for (const name of Object.keys(manifest.dependencies || {})) await copyDependency(name,createRequire(path.join(source,'package.json')));
+    await fs.writeFile(path.join(temporary,'ready'),manifest.version,{mode:0o600});
+    try { await fs.rename(temporary,target); }
+    catch (error) {
+      if (!['EEXIST','ENOTEMPTY','EPERM'].includes(error.code)) throw error;
+      await fs.access(path.join(target,'ready'));
+    }
+  } finally {
+    const resolved = path.resolve(temporary);
+    if (path.dirname(resolved) !== path.join(path.resolve(home),'runtime') || !path.basename(resolved).endsWith('.tmp')) throw new Error('无效的临时运行时路径。');
+    await fs.rm(resolved,{recursive:true,force:true});
+  }
+  return {cliPath:path.join(target,'cli.mjs'),version:manifest.version};
+}
+
+export async function startConnector({home,cliPath,version}) {
+  const running = await connectorStatus(home);
+  if (running?.version === version && running.workerReady) return running;
+  if (running) await stopConnector(home);
+  await fs.mkdir(home,{recursive:true,mode:0o700});
+  const startupLog = path.join(home,'service-startup.log');
+  const diagnostic = await fs.open(startupLog,'w',0o600);
+  let child;
+  try {
+    child = spawn(process.execPath,[cliPath,'__service'],{
+      detached:true,windowsHide:true,stdio:['ignore',diagnostic.fd,diagnostic.fd],env:{...process.env,ORBIT_HOME:home}
+    });
+    await new Promise((resolve,reject) => {
+      child.once('spawn',resolve);
+      child.once('error',reject);
+    });
+  } finally {await diagnostic.close();}
+  let exited = false;
+  child.once('exit',() => {exited = true;});
+  child.unref();
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const current = await connectorStatus(home);
+    if (current?.version === version && current.workerReady) return current;
+    if (exited) {
+      const diagnostic = (await fs.readFile(startupLog,'utf8').catch(() => '')).slice(-1500);
+      throw new Error(`后台连接器启动失败。${diagnostic}\n诊断日志：${startupLog}`);
+    }
+    await pause(150);
+  }
+  throw new Error(`后台连接器未就绪。诊断日志：${path.join(home,'connector.log')}`);
+}
+
+export async function superviseConnector(options) {
+  const {home} = options;
+  await fs.mkdir(home,{recursive:true,mode:0o700});
+  const lockfile = path.join(home,'connector.lock');
+  async function acquire() {
+    try {
+      const handle = await fs.open(lockfile,'wx',0o600);
+      try {await handle.writeFile(String(process.pid));}
+      finally {await handle.close();}
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const owner = Number(await fs.readFile(lockfile,'utf8'));
+      if (!Number.isInteger(owner) || owner < 1) throw new Error('另一个后台连接器正在启动，请稍后重试。');
+      try {process.kill(owner,0);}
+      catch (check) {
+        if (check.code !== 'ESRCH') throw check;
+        await fs.unlink(lockfile);
+        await acquire();
+        return;
+      }
+      throw new Error('Orbit 后台连接器已经运行。');
+    }
+  }
+  await acquire();
+  try {await runSupervisor(options);}
+  finally {
+    if ((await fs.readFile(lockfile,'utf8').catch(() => '')) === String(process.pid)) await fs.unlink(lockfile);
+  }
+}
+
+async function runSupervisor({home,cliPath,version,restartDelay = 1000}) {
+  await fs.mkdir(home,{recursive:true,mode:0o700});
+  const token = crypto.randomBytes(32).toString('hex');
+  const logfile = path.join(home,'connector.log');
+  let logBytes = (await fs.stat(logfile).catch(() => ({size:0}))).size;
+  let writes = Promise.resolve();
+  function log(text) {
+    writes = writes.then(async () => {
+      const line = `${new Date().toISOString()} ${text.toString().trimEnd()}\n`;
+      if (logBytes > 2 * 1024 * 1024) {
+        await fs.rename(logfile,`${logfile}.1`);
+        logBytes = 0;
+      }
+      await fs.appendFile(logfile,line,{mode:0o600});
+      logBytes += Buffer.byteLength(line);
+    }).catch(() => {});
+  }
+  let worker = null;
+  let stopped = false;
+  let restartTimer;
+  let failures = 0;
+  let state = {product:'Orbit connector',version,pid:process.pid,workerReady:false,status:'starting',startedAt:Date.now()};
+  const finished = Promise.withResolvers();
+  async function stop() {
+    if (stopped) return;
+    stopped = true;
+    clearTimeout(restartTimer);
+    if (worker) {
+      const previous = worker;
+      const exited = new Promise(resolve => previous.once('exit',resolve));
+      const force = setTimeout(() => previous.kill(),3000);
+      if (previous.connected) previous.send({type:'stop'},() => {});
+      else previous.kill();
+      await exited;
+      clearTimeout(force);
+    }
+    await new Promise(resolve => control.close(resolve));
+    try {
+      const saved = JSON.parse(await fs.readFile(stateFile(home),'utf8'));
+      if (saved.token === token) await fs.unlink(stateFile(home));
+    } catch {}
+    log('连接器已停止。');
+    await writes;
+    finished.resolve();
+  }
+  const control = http.createServer((request,response) => {
+    response.setHeader('Content-Type','application/json');
+    response.setHeader('Cache-Control','no-store');
+    if (request.headers.origin || request.headers.authorization !== `Bearer ${token}`) {
+      response.writeHead(403);response.end('{}');return;
+    }
+    if (request.method === 'GET' && request.url === '/status') return response.end(JSON.stringify(state));
+    if (request.method === 'POST' && request.url === '/stop') {
+      response.end(JSON.stringify({...state,stopping:true}));
+      void stop();return;
+    }
+    response.writeHead(404);response.end('{}');
+  });
+  control.requestTimeout = 5000;
+  control.headersTimeout = 5000;
+  control.keepAliveTimeout = 1000;
+  await new Promise((resolve,reject) => {
+    control.once('error',reject);
+    control.listen(0,'127.0.0.1',resolve);
+  });
+  try {
+    const temporary = `${stateFile(home)}.${token}.tmp`;
+    await fs.writeFile(temporary,JSON.stringify({port:control.address().port,token}),{mode:0o600});
+    await fs.rename(temporary,stateFile(home));
+  } catch (error) {
+    await new Promise(resolve => control.close(resolve));throw error;
+  }
+  function launchWorker() {
+    if (stopped) return;
+    const started = Date.now();
+    state = {...state,workerReady:false,status:'starting'};
+    worker = spawn(process.execPath,[cliPath,'__worker'],{
+      windowsHide:true,stdio:['ignore','pipe','pipe','ipc'],env:{...process.env,ORBIT_HOME:home}
+    });
+    state.workerPid = worker.pid;
+    worker.stdout.on('data',log);
+    worker.stderr.on('data',log);
+    worker.on('error',error => log(error.message));
+    worker.on('message',message => {
+      if (message?.type === 'connector-state') state = {...state,...message.state};
+    });
+    worker.once('exit',(code,signal) => {
+      worker = null;
+      state = {...state,workerReady:false,status:'restarting'};
+      if (stopped) return;
+      failures = Date.now() - started > 60000 ? 0 : failures + 1;
+      const delay = Math.min(30000,restartDelay * 2 ** Math.min(failures - 1,5));
+      log(`工作进程退出 (${code ?? signal})，${delay}ms 后自动恢复。`);
+      restartTimer = setTimeout(launchWorker,delay);
+    });
+  }
+  process.once('SIGINT',stop);
+  process.once('SIGTERM',stop);
+  log(`Orbit ${version} 后台连接器启动。`);
+  launchWorker();
+  await finished.promise;
+  process.off('SIGINT',stop);
+  process.off('SIGTERM',stop);
+}