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

package/dist/src/self-relay/wire.mjs

@@ -1,36 +1,36 @@
-import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
-import { WebSocket } from 'ws';
-
-export const secret = () => randomBytes(32).toString('base64url');
-export const digest = value => createHash('sha256').update(value).digest('hex');
-export const validSecret = value => typeof value === 'string' && /^[\w-]{43}$/.test(value);
-export function matches(value, hash) {
-  return validSecret(value) && typeof hash === 'string' && timingSafeEqual(Buffer.from(digest(value)), Buffer.from(hash));
-}
-export function send(socket, message) {
-  if (socket.readyState !== WebSocket.OPEN) return false;
-  if (socket.bufferedAmount > 64 * 1024 * 1024) { socket.close(1013, 'Receiver too slow'); return false; }
-  socket.send(JSON.stringify(message)); return true;
-}
-export function decode(bytes, binary) {
-  if (binary) throw new Error('Text frames required');
-  const value = JSON.parse(bytes.toString());
-  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Object required');
-  return value;
-}
-export function loopbackUrl(value, pathname) {
-  const url = new URL(value);
-  if (url.protocol !== 'ws:' || url.hostname !== '127.0.0.1' || url.pathname !== pathname || url.search || url.hash || url.username || url.password) {
-    throw new Error('本地原型仅接受指定路径的 ws://127.0.0.1 地址');
-  }
-  return url.href;
-}
-
-export function relayAddress(value) {
-  const url = new URL(value);
-  if (url.protocol === 'ws:') return loopbackUrl(value, '/relay');
-  if (url.protocol !== 'wss:' || url.pathname !== '/relay' || url.search || url.hash || url.username || url.password) {
-    throw new Error('远程中继必须使用无查询凭据的 wss://主机/relay 地址');
-  }
-  return url.href;
-}
+import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
+import { WebSocket } from 'ws';
+
+export const secret = () => randomBytes(32).toString('base64url');
+export const digest = value => createHash('sha256').update(value).digest('hex');
+export const validSecret = value => typeof value === 'string' && /^[\w-]{43}$/.test(value);
+export function matches(value, hash) {
+  return validSecret(value) && typeof hash === 'string' && timingSafeEqual(Buffer.from(digest(value)), Buffer.from(hash));
+}
+export function send(socket, message) {
+  if (socket.readyState !== WebSocket.OPEN) return false;
+  if (socket.bufferedAmount > 64 * 1024 * 1024) { socket.close(1013, 'Receiver too slow'); return false; }
+  socket.send(JSON.stringify(message)); return true;
+}
+export function decode(bytes, binary) {
+  if (binary) throw new Error('Text frames required');
+  const value = JSON.parse(bytes.toString());
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Object required');
+  return value;
+}
+export function loopbackUrl(value, pathname) {
+  const url = new URL(value);
+  if (url.protocol !== 'ws:' || url.hostname !== '127.0.0.1' || url.pathname !== pathname || url.search || url.hash || url.username || url.password) {
+    throw new Error('本地原型仅接受指定路径的 ws://127.0.0.1 地址');
+  }
+  return url.href;
+}
+
+export function relayAddress(value) {
+  const url = new URL(value);
+  if (url.protocol === 'ws:') return loopbackUrl(value, '/relay');
+  if (url.protocol !== 'wss:' || url.pathname !== '/relay' || url.search || url.hash || url.username || url.password) {
+    throw new Error('远程中继必须使用无查询凭据的 wss://主机/relay 地址');
+  }
+  return url.href;
+}

package/dist/src/server.mjs

@@ -1,4 +1,5 @@
 import crypto from 'node:crypto';
+import { RustDeskVideoProbe } from './platform/windows/rustdesk-video-probe.mjs';
 import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
@@ -17,14 +18,14 @@ import { streamSharedThread, threadListNotificationMethods } from './shared-thre
 import appServerEvents from '../shared/app-server-events.cjs';
 import messageDelivery from '../shared/message-delivery.cjs';
 import fileChanges from '../shared/file-changes.cjs';
-import { runtimePaths } from './platform/windows/runtime-paths.mjs';
+import { runtimePaths } from './platform/runtime-paths.mjs';
 import { openControl } from './service-control.mjs';
 import { writeRecord, readRecord } from './service-lifecycle.mjs';
 import { ExecutionHealth } from './execution-health.mjs';
 import { authorizeLanDevice, onLanAuthorizationsChanged } from './self-relay/lan-authorizations.mjs';
 import { createRelayManager } from './self-relay/lifecycle.mjs';
 import { generateAndSetThreadTitle } from './thread-title-generation.mjs';
-import { desktopHost } from './platform/windows/desktop-host.mjs';
+import { desktopHost } from './platform/desktop-host.mjs';
 import { SharedCatalog } from './shared-catalog.mjs';
 import { DotsAppServer } from './dots-task-catalog.mjs';
 import { DotsChatServer } from './dots-chat-server.mjs';
@@ -33,19 +34,22 @@ import { readDotsSummaryTasks } from './dots-summary-tasks.mjs';
 import { readDotsSchedules } from './dots-schedules.mjs';
 import { DotsMessageImages } from './dots-message-images.mjs';
 import { desktopDotsProfiles } from './platform/windows/dots-profile.mjs';
+import { readPlanPricing } from './plan-pricing.mjs';
 import { requestRecovery, recoveryStatus } from './shared-recovery.mjs';
 import { requestServiceRestart } from './service-restart.mjs';
 import { TurnModelHistory } from './turn-model-history.mjs';
 import { browseCode } from './code-browser.mjs';
 import { fileRange, fileRevision, FileRangeError } from './file-transfer-range.mjs';
 import { browseProjectFolders, createProjectFolder, saveProject } from './project-management.mjs';
-import { projectLocations } from './platform/windows/project-locations.mjs';
+import { projectLocations } from './platform/project-locations.mjs';
 import { createWorkstationProject } from './project-create.mjs';
 import { WorkstationDownloads } from './workstation-downloads.mjs';
 import { consumeUsageReset } from './usage-reset.mjs';
+import { DesktopHelper } from './platform/windows/desktop-helper.mjs';
 
 const turnModelHistory = new TurnModelHistory();
 const messageReceipts = new messageDelivery.Store();
+const desktopHelper = process.platform === 'win32' ? new DesktopHelper() : null;
 
 const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
 const MAX_FILE_DOWNLOAD_BYTES = 20 * 1024 * 1024;
@@ -84,6 +88,8 @@ const runtimeVersion = readRuntimeVersion();
 const webRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'web');
 const projectRoot = os.homedir();
 const { codexDataRoot, stateRoot, sessionsRoot, uploadsRoot } = runtimePaths();
+const desktopVideoProbe = process.platform === 'win32' ? new RustDeskVideoProbe({ stateRoot }) : null;
+process.once('exit', () => desktopVideoProbe?.stop());
 const workstationDownloads = new WorkstationDownloads(stateRoot);
 const markdownItScript = fs.readFileSync(path.join(webRoot, 'vendor', 'markdown-it.umd.min.js'));
 const markdownSandbox = { atob };
@@ -101,7 +107,7 @@ const liveActivityCache = new Map();
 let sharedServer = null;
 const managedAppServer = new ManagedAppServer({ stateRoot, host: desktopHost });
 const hostedHistoryCache = new HostedHistoryCache(stateRoot);
-const dotsServer = new DotsAppServer(managedAppServer.client, desktopDotsProfiles(codexDataRoot, stateRoot), hostedHistoryCache);
+const dotsServer = new DotsAppServer(managedAppServer.client, desktopDotsProfiles(codexDataRoot, stateRoot), hostedHistoryCache, { uploadsRoot });
 const dotsImages = new DotsMessageImages({ localServer: managedAppServer.client, identity: () => dotsServer.profileIdentity,
   cache: attachmentCache, capabilityKey: imageCapabilityKey, maxEntries: MAX_CACHED_ATTACHMENTS, maxBytes: MAX_ATTACHMENT_BYTES });
 const dotsChat = new DotsChatServer(dotsServer, undefined, { uploadsRoot });
@@ -156,6 +162,79 @@ async function handleRequest(request, response) {
       return;
     }
 
+    if (process.platform !== 'win32' && url.pathname.startsWith('/api/desktop/'))
+      throw new RequestError(501, 'Mac 版不提供远程桌面控制。', { code: 'desktop_control_unsupported' });
+
+    if (url.pathname === '/api/desktop/video-probe') {
+      if (request.method === 'POST') {
+        try { sendJson(response, 200, await desktopVideoProbe.begin()); }
+        catch (error) { throw new RequestError(error.statusCode || 502, error.message, { code: error.code || 'desktop_video_failed' }); }
+      }
+      else if (request.method === 'PUT' || request.method === 'DELETE') {
+        const body = await readJsonBody(request);
+        if (typeof body.leaseId !== 'string' || !/^[a-f0-9]{32}$/.test(body.leaseId)) throw new RequestError(400, '无效的视频会话');
+        sendJson(response, 200, request.method === 'PUT' ? desktopVideoProbe.renew(body.leaseId) : desktopVideoProbe.release(body.leaseId));
+      } else throw new RequestError(405, '不支持的操作');
+      return;
+    }
+    if (request.method === 'GET' && url.pathname === '/api/desktop/frame') {
+      const started = Date.now();
+      try {
+        const preview = url.searchParams.get('preview') === '1';
+        const frame = await desktopHelper.frame({ preview });
+        if (!preview) console.info(JSON.stringify({ time: new Date().toISOString(), event: 'desktop-frame', state: frame.state,
+          kind: frame.kind, width: frame.width, height: frame.height, bytes: frame.size, ms: Date.now() - started }));
+        if (response.writableEnded) { desktopHelper.release(frame.frameId); return; }
+        sendJson(response, 200, frame);
+      } catch (error) {
+        console.error(JSON.stringify({ time: new Date().toISOString(), event: 'desktop-frame', state: 'failed',
+          error: error.message.slice(0, 160), ms: Date.now() - started }));
+        throw error;
+      }
+      return;
+    }
+    const desktopImage = /^\/api\/desktop\/frames\/([a-f0-9]{32})$/.exec(url.pathname);
+    if (request.method === 'GET' && desktopImage) {
+      if (!request.fileTransfer) throw new RequestError(400, '请通过文件通道读取桌面画面。');
+      const image = desktopHelper.image(desktopImage[1]);
+      const { offset, length } = fileRange(url.searchParams, image.length, desktopImage[1]);
+      const mimeType = desktopHelper.active.frame.mimeType;
+      response.filePart({ name: mimeType === 'image/jpeg' ? 'desktop.jpg' : 'desktop.png', size: image.length, offset, revision: desktopImage[1], mimeType },
+        image.subarray(offset, offset + length));
+      return;
+    }
+    if (request.method === 'POST' && url.pathname === '/api/desktop/move') {
+      try { sendJson(response, 200, await desktopHelper.move(await readJsonBody(request))); }
+      catch (error) {
+        console.error(JSON.stringify({ time: new Date().toISOString(), event: 'desktop-move', state: 'failed',
+          code: error.code, error: error.message.slice(0, 160) }));
+        throw error;
+      }
+      return;
+    }
+    if (request.method === 'POST' && url.pathname === '/api/desktop/click') {
+      const started = Date.now();
+      console.info(JSON.stringify({ time: new Date().toISOString(), event: 'desktop-click', state: 'received' }));
+      try {
+        const result = await desktopHelper.click(await readJsonBody(request));
+        console.info(JSON.stringify({ time: new Date().toISOString(), event: 'desktop-click', state: result.state,
+          inputCount: result.inputCount, ms: Date.now() - started }));
+        sendJson(response, 200, result);
+      } catch (error) {
+        console.error(JSON.stringify({ time: new Date().toISOString(), event: 'desktop-click', state: 'failed',
+          code: error.code, error: error.message.slice(0, 160), ms: Date.now() - started }));
+        throw error;
+      }
+      return;
+    }
+    if (request.method === 'DELETE' && url.pathname === '/api/desktop/frame') {
+      const body = await readJsonBody(request);
+      if (typeof body.sessionId !== 'string' || !/^[a-f0-9]{32}$/.test(body.sessionId)) throw new RequestError(400, '无效的桌面会话');
+      desktopHelper.release(undefined, body.sessionId);
+      sendJson(response, 200, { released: true });
+      return;
+    }
+
     // These routes never wait on Desktop tools or a stuck thread. They remain
     // available to authenticated paired controllers during an app-server stall.
     if (request.method === 'GET' && url.pathname === '/api/shared-recovery/events') {
@@ -278,18 +357,21 @@ async function handleRequest(request, response) {
       return;
     }
 
+    const localFileRequest = url.pathname === '/api/files/local';
     const fileMatch = /^\/api\/files\/([a-f0-9]{64})$/.exec(url.pathname);
-    if (request.method === 'GET' && fileMatch) {
+    if (request.method === 'GET' && (fileMatch || localFileRequest)) {
       if (!request.fileTransfer) throw new RequestError(400, '请通过文件通道下载附件。');
-      const hosted = attachmentCache.get(fileMatch[1])
-        || dotsImages.restore(fileMatch[1], url.searchParams.get('recovery') || '');
+      const hosted = !localFileRequest && (attachmentCache.get(fileMatch[1])
+        || dotsImages.restore(fileMatch[1], url.searchParams.get('recovery') || ''));
       if (hosted?.dotsFile) {
         const { bytes, ...metadata } = await dotsImages.readPart(hosted, url.searchParams);
         response.filePart(metadata, bytes);
         return;
       }
-      const file = fileCache.get(fileMatch[1]);
-      if (!file) throw new RequestError(404, '文件授权已失效，请重新读取对话。');
+      const localPath = url.searchParams.get('path') || '';
+      if (localFileRequest && !/^[a-z]:[\\/]/i.test(localPath)) throw new RequestError(400, '无效的工作站文件路径。');
+      const file = localFileRequest ? describeLocalFile(localPath) : fileCache.get(fileMatch[1]);
+      if (!file) throw new RequestError(404, '电脑上的文件不存在或无法读取。');
       if (file.externalIdentity) await dotsImages.authorization(file.externalIdentity);
       const { offset, length } = fileRange(url.searchParams, file.size, file.revision);
       let handle;
@@ -302,7 +384,7 @@ async function handleRequest(request, response) {
         const validate = () => {
           const stat = fs.fstatSync(handle);
           if (!stat.isFile() || fileRevision(stat) !== file.revision || fileRevision(fs.statSync(file.path)) !== file.revision) {
-            fileCache.delete(fileMatch[1]);
+            if (fileMatch) fileCache.delete(fileMatch[1]);
             throw new RequestError(409, '电脑上的文件已发生变化，请重新读取对话。');
           }
           if (stat.size > MAX_FILE_DOWNLOAD_BYTES) throw new RequestError(413, '文件超过下载上限（20 MiB），无法下载。');
@@ -468,6 +550,11 @@ async function handleRequest(request, response) {
       return;
     }
 
+    if (request.method === 'GET' && url.pathname === '/api/plan-pricing') {
+      sendJson(response, 200, await readPlanPricing(sharedServer));
+      return;
+    }
+
     if (request.method === 'GET' && url.pathname === '/api/usage-limits') {
       sendJson(response, 200, await sharedServer.usage());
       return;
@@ -629,6 +716,12 @@ async function handleRequest(request, response) {
     }
 
     const approvalMatch = /^\/api\/threads\/([^/]+)\/approvals$/.exec(url.pathname);
+    if (request.method === 'GET' && approvalMatch && rootChat) {
+      const threadId = decodeURIComponent(approvalMatch[1]);
+      sendJson(response, 200, await execution.inspectApproval(threadId, {
+        id: url.searchParams.get('requestId'), roomMessageId: url.searchParams.get('roomMessageId'),
+      })); return;
+    }
     if (request.method === 'POST' && approvalMatch) {
       const threadId = decodeURIComponent(approvalMatch[1]);
       await requireExecutionWritable(threadId, execution);
@@ -764,7 +857,7 @@ async function handleRequest(request, response) {
       if (body.hostId && body.hostId !== hostId) throw new RequestError(400, '请求中的对话主机不一致。');
       const result = await messageReceipts.submit([hostId, threadId], body.clientUserMessageId, async () => {
         let args;
-        try { await requireExecutionWritable(threadId, execution); args = execution === dotsChat ? { ...body, threadId } : appServerTurnArguments(threadId, body); }
+        try { await requireExecutionWritable(threadId, execution); args = execution === dotsChat ? { ...body, threadId } : appServerTurnArguments(threadId, { ...body, hostId }); }
         catch (error) { error.deliveryUnknown = false; throw error; }
         messageSubmissionStarted = true;
         const submitted = await execution.send(args);
@@ -845,6 +938,7 @@ let shuttingDown = false;
 async function shutDown() {
   if (shuttingDown) return;
   shuttingDown = true;
+  desktopHelper?.release();
   lanSocket.close();
   server.close();
   executionHealth?.stop();
@@ -1025,10 +1119,20 @@ function messagePayload(body) {
 
 function appServerTurnArguments(threadId, body) {
   const payload = messagePayload(body);
+  const mentioned = payload.hostId === 'durable' ? fileMentions.parse(payload.prompt) : null;
+  if (mentioned?.files.length) payload.prompt = mentioned.text;
   const input = [];
   if (payload.prompt) input.push({ type: 'text', text: payload.prompt });
-  for (const image of payload.images) input.push(image.startsWith('data:') ? { type: 'image', url: image } : { type: 'localImage', path: image });
+  for (const image of payload.images) {
+    if (image.startsWith('data:')) input.push({ type: 'image', url: image });
+    else if (payload.hostId === 'durable') {
+      const mimeType = imageMimeType(image);
+      if (!mimeType) throw new RequestError(400, '云端图片格式无效。');
+      input.push({ type: 'image', url: `data:${mimeType};base64,${fs.readFileSync(image).toString('base64')}` });
+    } else input.push({ type: 'localImage', path: image });
+  }
   const value = { threadId, input, ...appServerEvents.mobileTurnSource(body.clientUserMessageId, body.containsVoiceInput) };
+  if (mentioned?.files.length) value.uploadFiles = mentioned.files;
   if (typeof body.clientUserMessageId === 'string' && /^[a-f0-9]{32}$/.test(body.clientUserMessageId)) value.clientUserMessageId = body.clientUserMessageId;
   if (payload.model) value.model = payload.model;
   if (payload.thinking) value.effort = payload.thinking;
@@ -1148,10 +1252,10 @@ function normalizeItem(item) {
 
   if (item.type === 'userMessage') {
     const { text, files, delegation } = extractUserText(item.content);
-    const attachments = [...normalizeAttachments(item.content), ...files.map(file => ({
+    const attachments = [...normalizeAttachments(item.content), ...files.map(file => file.fileId ? normalizeAttachment(file) : ({
       ...file,
-      remotePath: rememberLocalFile(file.path)?.id || '',
-      previewRemotePath: file.previewPath ? rememberLocalFile(file.previewPath)?.id || '' : '',
+      remotePath: file.path,
+      previewRemotePath: file.previewPath || '',
     }))];
     if (!text && !attachments.length) return null;
     return {
@@ -1397,8 +1501,8 @@ function markdownFileAssets(text) {
         if (value && !Object.hasOwn(assets, value)) {
           const localPath = fileCitations.localReference(value)?.path;
           if (localPath && /^[a-z]:[\\/]/i.test(localPath)) {
-            const asset = rememberLocalFile(localPath);
-            if (asset) assets[value] = { remotePath: asset.id, name: asset.name, size: asset.size };
+            assets[value] = { remotePath: localPath, name: path.basename(localPath) };
+            // Link rendering must not depend on file existence or transient backend state.
           }
         }
       }
@@ -1409,21 +1513,17 @@ function markdownFileAssets(text) {
   return assets;
 }
 
-function rememberLocalFile(filePath) {
-  try {
-    const resolved = path.resolve(filePath);
-    const stat = fs.statSync(resolved);
-    if (!stat.isFile()) return null;
-    const id = crypto.createHmac('sha256', fileCapabilitySecret)
-      .update(resolved).update('\0').update(String(stat.size)).update('\0').update(String(stat.mtimeMs)).digest('hex');
-    if (!fileCache.has(id)) {
-      while (fileCache.size >= MAX_CACHED_FILES) fileCache.delete(fileCache.keys().next().value);
-      fileCache.set(id, { id, path: resolved, name: path.basename(resolved), size: stat.size, revision: fileRevision(stat) });
-    }
-    return fileCache.get(id);
-  } catch {
-    return null;
+function describeLocalFile(filePath) {
+  const resolved = path.resolve(filePath);
+  let stat;
+  try { stat = fs.statSync(resolved); }
+  catch (error) {
+    if (error.code === 'ENOENT') throw new RequestError(404, '电脑上的文件已不存在。');
+    if (error.code === 'EACCES' || error.code === 'EPERM') throw new RequestError(403, '电脑系统无法读取此文件：' + error.code);
+    throw error;
   }
+  if (!stat.isFile()) throw new RequestError(400, '此路径不是文件。');
+  return { path: resolved, name: path.basename(resolved), size: stat.size, revision: fileRevision(stat) };
 }
 
 function splitUploadedImages(text) {
@@ -1612,7 +1712,7 @@ function extractUserText(content) {
   ].map(value => path.resolve(value).toLowerCase()));
   text = mentioned.text;
   text = text.replace(/<image\b[^>]*\bpath="[^"]+"[^>]*>/g, '').replace(/<\/image>/g, '').trim();
-  return { text, files: mentioned.files.filter(file => !imagePaths.has(path.resolve(file.path).toLowerCase())), delegation };
+  return { text, files: mentioned.files.filter(file => file.fileId || !imagePaths.has(path.resolve(file.path).toLowerCase())), delegation };
 }
 
 function delegationSource(delegation) {

package/dist/src/service-control.mjs

@@ -1,82 +1,82 @@
-import http from 'node:http';
-import { timingSafeEqual } from 'node:crypto';
-
-function matches(left, right) {
-  const a = Buffer.from(left || '');
-  const b = Buffer.from(right || '');
-  return a.length === b.length && timingSafeEqual(a, b);
-}
-
-// Separate from the LAN listener: mobile credentials never authorize lifecycle operations.
-export async function openControl({ instanceId, secret, shutdown, status = () => ({}), actions = {} }) {
-  const server = http.createServer((request, response) => {
-    if (!matches(request.headers.authorization, `Bearer ${secret}`)) {
-      response.writeHead(403).end();
-      return;
-    }
-    const action = Object.keys(actions).find(name => request.url === `/${instanceId}/${name}`);
-    if ((!action && request.url !== `/${instanceId}`) || !['GET', 'POST'].includes(request.method) || (action && request.method !== 'POST')) {
-      response.writeHead(404).end();
-      return;
-    }
-    response.setHeader('Content-Type', 'application/json');
-    response.setHeader('Connection', 'close');
-    if (action) {
-      Promise.resolve().then(async () => {
-        let body = '';
-        request.setEncoding('utf8');
-        for await (const chunk of request) {
-          body += chunk;
-          if (Buffer.byteLength(body) > 4096) throw new Error('管理请求过大');
-        }
-        const details = body ? JSON.parse(body) : {};
-        if (!details || typeof details !== 'object' || Array.isArray(details)) throw new Error('无效管理请求');
-        return actions[action](details);
-      }).then(result => {
-        response.end(JSON.stringify({ ...result, instanceId, pid: process.pid }));
-      }).catch(error => { response.writeHead(409).end(JSON.stringify({ error: error.message })); });
-      return;
-    }
-    if (request.method === 'POST') response.once('finish', () => {
-      Promise.resolve(shutdown()).catch(error => {
-        console.error('桌面服务关闭失败：', error.message);
-        process.exitCode = 1;
-      });
-    });
-    response.end(JSON.stringify({ ...status(), instanceId, pid: process.pid }));
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  return { port: server.address().port, close: () => new Promise((resolve, reject) => {
-    server.close(error => error ? reject(error) : resolve());
-  }) };
-}
-
-export function controlRequest(session, method = 'GET', action = '', details) {
-  return new Promise((resolve, reject) => {
-    const request = http.request({ hostname: '127.0.0.1', port: session.controlPort,
-      path: `/${session.instanceId}${action ? '/' + action : ''}`, method, agent: false,
-      headers: { Authorization: `Bearer ${session.controlSecret}` }, timeout: action ? 25000 : 2000 }, response => {
-      let body = '';
-      response.setEncoding('utf8');
-      response.on('data', chunk => { body += chunk; });
-      response.on('error', reject);
-      response.on('end', () => {
-        try {
-          if (response.statusCode === 409) throw new Error(JSON.parse(body).error);
-          if (response.statusCode !== 200) throw new Error('桌面服务管理通道身份验证失败。');
-          const identity = JSON.parse(body);
-          if (identity.instanceId !== session.instanceId || identity.pid !== session.pid) {
-            throw new Error('桌面服务实例身份不匹配。');
-          }
-          resolve(identity);
-        } catch (error) { reject(error); }
-      });
-    });
-    request.on('timeout', () => request.destroy(new Error('桌面服务管理通道响应超时。')));
-    request.on('error', reject);
-    request.end(details === undefined ? undefined : JSON.stringify(details));
-  });
-}
+import http from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+
+function matches(left, right) {
+  const a = Buffer.from(left || '');
+  const b = Buffer.from(right || '');
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+// Separate from the LAN listener: mobile credentials never authorize lifecycle operations.
+export async function openControl({ instanceId, secret, shutdown, status = () => ({}), actions = {} }) {
+  const server = http.createServer((request, response) => {
+    if (!matches(request.headers.authorization, `Bearer ${secret}`)) {
+      response.writeHead(403).end();
+      return;
+    }
+    const action = Object.keys(actions).find(name => request.url === `/${instanceId}/${name}`);
+    if ((!action && request.url !== `/${instanceId}`) || !['GET', 'POST'].includes(request.method) || (action && request.method !== 'POST')) {
+      response.writeHead(404).end();
+      return;
+    }
+    response.setHeader('Content-Type', 'application/json');
+    response.setHeader('Connection', 'close');
+    if (action) {
+      Promise.resolve().then(async () => {
+        let body = '';
+        request.setEncoding('utf8');
+        for await (const chunk of request) {
+          body += chunk;
+          if (Buffer.byteLength(body) > 4096) throw new Error('管理请求过大');
+        }
+        const details = body ? JSON.parse(body) : {};
+        if (!details || typeof details !== 'object' || Array.isArray(details)) throw new Error('无效管理请求');
+        return actions[action](details);
+      }).then(result => {
+        response.end(JSON.stringify({ ...result, instanceId, pid: process.pid }));
+      }).catch(error => { response.writeHead(409).end(JSON.stringify({ error: error.message })); });
+      return;
+    }
+    if (request.method === 'POST') response.once('finish', () => {
+      Promise.resolve(shutdown()).catch(error => {
+        console.error('桌面服务关闭失败：', error.message);
+        process.exitCode = 1;
+      });
+    });
+    response.end(JSON.stringify({ ...status(), instanceId, pid: process.pid }));
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  return { port: server.address().port, close: () => new Promise((resolve, reject) => {
+    server.close(error => error ? reject(error) : resolve());
+  }) };
+}
+
+export function controlRequest(session, method = 'GET', action = '', details) {
+  return new Promise((resolve, reject) => {
+    const request = http.request({ hostname: '127.0.0.1', port: session.controlPort,
+      path: `/${session.instanceId}${action ? '/' + action : ''}`, method, agent: false,
+      headers: { Authorization: `Bearer ${session.controlSecret}` }, timeout: action ? 25000 : 2000 }, response => {
+      let body = '';
+      response.setEncoding('utf8');
+      response.on('data', chunk => { body += chunk; });
+      response.on('error', reject);
+      response.on('end', () => {
+        try {
+          if (response.statusCode === 409) throw new Error(JSON.parse(body).error);
+          if (response.statusCode !== 200) throw new Error('桌面服务管理通道身份验证失败。');
+          const identity = JSON.parse(body);
+          if (identity.instanceId !== session.instanceId || identity.pid !== session.pid) {
+            throw new Error('桌面服务实例身份不匹配。');
+          }
+          resolve(identity);
+        } catch (error) { reject(error); }
+      });
+    });
+    request.on('timeout', () => request.destroy(new Error('桌面服务管理通道响应超时。')));
+    request.on('error', reject);
+    request.end(details === undefined ? undefined : JSON.stringify(details));
+  });
+}