dsh-code-server-app 0.2.13 → 0.3.6

package/lib/index.js

@@ -17,6 +17,7 @@
  */
 
 import { spawn, execFile, execFileSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
@@ -37,6 +38,21 @@ import {
 import { aliasNodePathDirs, ensureRuntimeLayout, resolveRuntime, runtimePackageName, verifyNatives } from './native.js';
 import { MOUNT_PATH, mountOnWebServer } from './serve-dsh.mjs';
 import { DEFAULT_CLAIM_EXTENSIONS, describeClaimPolicy, normalizeClaimExtensions } from './claim-types.js';
+import {
+  BRIDGE_DIRNAME,
+  bodyWithinLimit,
+  bridgeGuard,
+  bridgeUrl,
+  createContextCache,
+  createEventRing,
+  mintBridgeToken,
+  readBridgeConfig,
+  removeBridgeConfig,
+  writeBridgeConfig,
+} from './bridge.mjs';
+import { registerEditorPrompt, registerEditorTools, setPromptLiveProbe } from './bridge-tools.mjs';
+import { deliverEditorPrompt } from './bridge-session.mjs';
+import { registerBridgeObserver } from './bridge-observe.mjs';
 
 // schemastery 由 DSH 部署自带(官方核心依赖),仿 auto-open-web 的解析策略:
 // 常规 import 优先,不可用时回退到全局 npm 布局的 DSH 部署副本。
@@ -87,22 +103,33 @@ export const Config = z.object({
    *  客户端把右侧栏切到全屏(铺满窗口);false 则保持 DSH 默认的 push(与对话并排)。
    *  只影响"打开那一刻":之后用户点「退出全屏」不会被抢回去。 */
   fullscreenOnOpen: z.boolean().default(true),
+  /** editorBridge=true(默认):启用「编辑器桥」(0.3.0)—— 树内扩展 dshcs-editor-bridge 与
+   *  host 之间建立**只读**通道,给 agent 提供 only-the-editor-knows 的上下文(未保存缓冲区、
+   *  诊断、活动选区),并让编辑器里的动作能驱动 DSH。关闭后不写 bridge.json、不注册编辑器工具,
+   *  扩展会休眠(它读不到配置就不做任何事)。安全模型见 lib/bridge.mjs 顶部。 */
+  editorBridge: z.boolean().default(true),
 });
 
 const DEFAULT_CONFIG = {
   bin: '',
   host: '127.0.0.1',
-  port: 8090,
+  /** 0(默认)= 每次启动由系统分配空闲端口(launcher 把实际端口写进 endpoint 文件,host 读回);
+   *  显式给端口则照用(用于需要固定地址的场景)。 */
+  port: 0,
   auth: 'none',
   serve: 'loopback',
   userDataDir: '',
   extensionsDir: '',
   locale: '',
   readyTimeoutMs: 60000,
+  /** 编辑器桥(0.3.0):见 Config.editorBridge。行配置与设置文档都可关;设置卡片暂不提供行。 */
+  editorBridge: true,
 };
 
 const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
 const LOG_TAIL_MAX = 6000;
+/** 路径令牌格式(与 launcher 的一致;字符集同时满足 VS Code 自己的 token 校验)。 */
+const TOKEN_RE = /^[0-9A-Za-z_-]{16,128}$/;
 
 function dshHome() {
   return process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
@@ -116,6 +143,16 @@ function pidFile(config) {
   return path.join(dataRoot(config), 'pid.json');
 }
 
+/** 路径令牌文件(0600 语义:位于用户 profile 下,默认 ACL 仅本人可读)。 */
+function tokenFile(config) {
+  return path.join(dataRoot(config), 'path-token');
+}
+
+/** launcher 回写实际监听地址的文件(端口 0 时 host 只能从这里知道端口)。 */
+function endpointFile(config) {
+  return path.join(dataRoot(config), 'endpoint.json');
+}
+
 function isAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
@@ -144,56 +181,72 @@ function launcherPath() {
   return path.join(path.dirname(fileURLToPath(import.meta.url)), 'launcher.mjs');
 }
 
-/** 扩展安装目标:VS Code「内置扩展」目录 = <树>/lib/vscode/extensions。
- *  (位于程序内置目录的扩展被 VS Code 视为内置——用户视图显示为"内置",不可卸载;
- *   --extensions-dir 的是用户级扩展,可被用户禁用/卸载。)
- *  返回 { dst, builtin }——builtin=true 时为核心路径;找不到树则回退用户级。 */
-function extensionTarget(extensionsDir) {
-  try {
-    const root = vsRoot();
-    if (root !== null) {
-      const vscodeExt = path.join(root, 'lib', 'vscode', 'extensions');
-      if (fs.existsSync(vscodeExt)) {
-        return { dst: path.join(vscodeExt, 'dshcs-open-file'), builtin: true };
+/** 扩展安装目标:`placement: 'builtin'` 时优先 VS Code「内置扩展」目录 = <树>/lib/vscode/extensions
+ *  (位于程序内置目录的扩展被 VS Code 视为内置——用户视图显示为"内置",**不能卸载**);
+ *  `placement: 'user'` 时只用 --extensions-dir(用户级扩展,可被用户禁用/卸载)。
+ *  返回 { dst, builtin }——builtin=true 时是核心路径;找不到树时回退用户级。 */
+function extensionTarget(extensionsDir, name, placement = 'builtin') {
+  if (placement === 'builtin') {
+    try {
+      const root = vsRoot();
+      if (root !== null) {
+        const vscodeExt = path.join(root, 'lib', 'vscode', 'extensions');
+        if (fs.existsSync(vscodeExt)) {
+          return { dst: path.join(vscodeExt, name), builtin: true };
+        }
       }
-    }
-  } catch { /* fall through */ }
-  return { dst: path.join(extensionsDir, 'dshcs-open-file'), builtin: false };
+    } catch { /* fall through */ }
+  }
+  return { dst: path.join(extensionsDir, name), builtin: false };
 }
 
-/** 内置扩展安装:dshcs-open-file(host 信号文件 → VS Code 打开文件,可带行号)。
- *  优先装进 code-server 内置扩展目录(不可卸载);同时清理用户级旧副本。
- *  每次启动调用:缺失**或内容有变化**即同步(自愈,且插件升级后能更新已装的旧副本)。 */
-function installBundledExtension(extensionsDir, userDataDir) {
-  try {
-    const here = path.dirname(fileURLToPath(import.meta.url));
-    const src = path.join(here, '..', 'assets', 'extensions', 'dshcs-open-file');
-    if (!fs.existsSync(path.join(src, 'package.json'))) return;
-    const target = extensionTarget(extensionsDir);
-    const dst = target.dst;
-    const files = ['package.json', 'extension.js'];
-    const stale = files.filter((name) => {
-      const to = path.join(dst, name);
-      if (!fs.existsSync(to)) return true;
-      try {
-        return fs.readFileSync(path.join(src, name), 'utf8') !== fs.readFileSync(to, 'utf8');
-      } catch {
-        return true;
+/** 树内自带扩展清单。
+ *  - dshcs-open-file:host 信号文件 → VS Code 打开文件(可带行号)。**内置**(用户不需要看到它)。
+ *  - dshcs-editor-bridge(0.3.0):编辑器桥的扩展侧。**必须用户级** —— 它是可选能力,
+ *    用户得有办法一键禁用;内置扩展按 VS Code 语义不能禁用。代价是用户可能卸载它,
+ *    这没关系:host 侧本来就按"桥不可用"降级。 */
+const BUNDLED_EXTENSIONS = [
+  { name: 'dshcs-open-file', placement: 'builtin' },
+  { name: 'dshcs-editor-bridge', placement: 'user' },
+];
+
+/** 内置扩展安装:每次启动调用 —— 缺失**或内容有变化**即同步(自愈,且插件升级后能更新已装的旧副本)。
+ *  同时清理"放错位置"的旧副本(用户级/内置两份同时存在会让 VS Code 打架)。 */
+function installBundledExtensions(extensionsDir, userDataDir) {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  for (const ext of BUNDLED_EXTENSIONS) {
+    try {
+      const src = path.join(here, '..', 'assets', 'extensions', ext.name);
+      const manifest = path.join(src, 'package.json');
+      if (!fs.existsSync(manifest)) continue;
+      const files = ['package.json', 'extension.js'];
+      const target = extensionTarget(extensionsDir, ext.name, ext.placement);
+      const dst = target.dst;
+      const stale = files.filter((name) => {
+        const to = path.join(dst, name);
+        if (!fs.existsSync(to)) return true;
+        try {
+          return fs.readFileSync(path.join(src, name), 'utf8') !== fs.readFileSync(to, 'utf8');
+        } catch {
+          return true;
+        }
+      });
+      if (stale.length > 0) {
+        fs.mkdirSync(dst, { recursive: true });
+        for (const name of stale) fs.copyFileSync(path.join(src, name), path.join(dst, name));
       }
-    });
-    if (stale.length > 0) {
-      fs.mkdirSync(dst, { recursive: true });
-      for (const name of stale) fs.copyFileSync(path.join(src, name), path.join(dst, name));
-    }
-    // 清理用户级旧副本(避免重复/可卸载副本)
-    const legacy = path.join(extensionsDir, 'dshcs-open-file');
-    if (legacy !== dst && fs.existsSync(legacy)) {
-      fs.rmSync(legacy, { recursive: true, force: true });
+      // 清理放错位置的副本:dshcs-open-file 的旧用户级副本 / 编辑器桥的错误内置副本。
+      const wrong = extensionTarget(extensionsDir, ext.name, ext.placement === 'builtin' ? 'user' : 'builtin');
+      if (wrong.dst !== dst && fs.existsSync(wrong.dst)) {
+        fs.rmSync(wrong.dst, { recursive: true, force: true });
+        console.log(`[code-server] 清理放错位置的扩展副本 ${wrong.dst}(${ext.name} 应装在${target.builtin ? '内置' : '用户级'}目录)`);
+      }
+      console.log(`[code-server] bundled extension ${ext.name} -> ${dst}${target.builtin ? ' (内置,不可卸载)' : ' (用户级,可禁用)'}${stale.length > 0 ? ` [更新 ${stale.join(',')}]` : ''}`);
+    } catch (err) {
+      console.warn(`[code-server] bundled extension ${ext.name} install failed:`, err && err.message ? err.message : String(err));
     }
-    console.log(`[code-server] bundled extension dshcs-open-file -> ${dst}${target.builtin ? ' (内置,不可卸载)' : ' (用户级回退)'}${stale.length > 0 ? ` [更新 ${stale.join(',')}]` : ''}`);
-  } catch (err) {
-    console.warn('[code-server] bundled extension install failed:', err && err.message ? err.message : String(err));
   }
+  void userDataDir;
 }
 
 /** 打开文件信号文件:<user-data>/User/dshcs-open.json(扩展轮询此文件)。 */
@@ -315,9 +368,10 @@ function pipeName() {
   return win32() ? `\\\\.\\pipe\\dshcs-vscode-${key}` : path.join(os.tmpdir(), `dshcs-vscode-${key}.sock`);
 }
 
-function healthCheck(host, port, timeoutMs = 1500) {
+function healthCheck(host, port, token, timeoutMs = 1500) {
+  const requestPath = token === null || token === undefined ? '/healthz' : `/${token}/healthz`;
   return new Promise((resolve) => {
-    const req = http.get({ host, port, path: '/healthz', timeout: timeoutMs, method: 'GET' }, (res) => {
+    const req = http.get({ host, port, path: requestPath, timeout: timeoutMs, method: 'GET' }, (res) => {
       res.resume();
       resolve({ ok: res.statusCode >= 200 && res.statusCode < 500, statusCode: res.statusCode });
     });
@@ -367,6 +421,37 @@ function removePidFile(config) {
   }
 }
 
+/** 读路径令牌;文件缺失或格式不对返回 null(不抛:调用方据此判定"没有可接管的实例")。 */
+function readToken(config) {
+  try {
+    const raw = fs.readFileSync(tokenFile(config), 'utf8').trim();
+    return TOKEN_RE.test(raw) ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 生成并写入新的路径令牌(每次**新启动**都换;原子写,0600)。 */
+function rotateToken(config) {
+  const token = randomBytes(24).toString('base64url'); // [A-Za-z0-9_-] 共 32 位
+  const file = tokenFile(config);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, token, { encoding: 'utf8', mode: 0o600 });
+  fs.renameSync(tmp, file);
+  return token;
+}
+
+/** 读 launcher 回写的监听端点(端口 0 时唯一可信来源);缺失/不可用返回 null。 */
+function readEndpoint(config) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(endpointFile(config), 'utf8'));
+    return raw && Number.isInteger(raw.pid) && Number.isInteger(raw.port) && raw.port > 0 ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
 export async function apply(ctx, config) {
   const cfg = { ...DEFAULT_CONFIG, ...(config ?? {}) };
 
@@ -382,6 +467,8 @@ export async function apply(ctx, config) {
   let keepResident = true; // 客户端常驻预热(0.2.2)
   let claimExtensions = DEFAULT_CLAIM_EXTENSIONS; // 认领类型清单(0.2.11,取代 fileOpenScope)
   let fullscreenOnOpen = true; // 客户端"打开标签即全屏右侧栏"(0.2.9)
+  /** 编辑器桥开关(0.3.0):行配置 cfg.editorBridge 是种子,设置文档里可改并实时生效。 */
+  let bridgeSetting = cfg.editorBridge !== false;
   if (settingsSvc !== undefined && typeof settingsSvc.register === 'function') {
     try {
       const scope = settingsSvc.register(SETTINGS_NS, Config);
@@ -394,6 +481,7 @@ export async function apply(ctx, config) {
           ? normalizeClaimExtensions(resolved.claimExtensions)
           : DEFAULT_CLAIM_EXTENSIONS;
         fullscreenOnOpen = resolved && typeof resolved.fullscreenOnOpen === 'boolean' ? resolved.fullscreenOnOpen : true;
+        bridgeSetting = resolved && typeof resolved.editorBridge === 'boolean' ? resolved.editorBridge : bridgeSetting;
       }
       scope.watch((next) => {
         if (next != null && (next.serve === 'dsh' || next.serve === 'loopback')) {
@@ -402,6 +490,19 @@ export async function apply(ctx, config) {
             console.log(`[code-server] serve updated: ${serveSetting}(下次启动生效)`);
           }
         }
+        if (next != null && typeof next.editorBridge === 'boolean') {
+          if (next.editorBridge !== bridgeSetting) {
+            bridgeSetting = next.editorBridge;
+            console.log(`[code-server] editorBridge updated: ${bridgeSetting}`);
+            // 关掉 → 立刻下线(删配置 + 注销工具);开启 → 若 IDE 在跑就补一份配置。
+            if (bridgeSetting === false) {
+              clearBridgeRuntime();
+            } else if (state.status === 'running' && state.serve === 'loopback' && Number.isSafeInteger(state.port) && state.port > 0) {
+              bridgeToken ??= mintBridgeToken();
+              syncBridgeRuntime({ host: cfg.host, port: state.port, pid: state.pid, startedAt: state.startedAt });
+            }
+          }
+        }
         if (next != null && typeof next.keepResident === 'boolean') {
           keepResident = next.keepResident;
           console.log(`[code-server] keepResident updated: ${keepResident}`);
@@ -448,6 +549,8 @@ export async function apply(ctx, config) {
     status: 'stopped', // stopped | starting | running | stopping | error
     pid: null,
     port: cfg.port,
+    /** 本实例的路径令牌(回环模式;不写日志、不进 argv)。 */
+    token: null,
     cwd: null,
     /** 进程**启动时**的工作目录(诊断用):运行时切工作区只改 cwd,进程 cwd 保持这里不变。 */
     launchCwd: null,
@@ -470,6 +573,134 @@ export async function apply(ctx, config) {
   let pollTimer = null;
   let disposeKilled = false;
 
+  // ---- 编辑器桥(0.3.0):配置/凭据写在 <extensionsDir>/.dshcs-bridge/bridge.json ----
+  // 这里只算路径;是否启用还要看 cfg.editorBridge 与 setting 值。详见 lib/bridge.mjs 顶部。
+  const bridgeRoot = dataRoot(cfg);
+  const bridgeUserDataDir = cfg.userDataDir || path.join(bridgeRoot, 'user-data');
+  const bridgeExtensionsDir = cfg.extensionsDir || path.join(bridgeRoot, 'extensions');
+  const bridgeMetaDir = path.join(bridgeExtensionsDir, BRIDGE_DIRNAME);
+  /** 已写入的桥配置(供桥路由与 /status 读回);null = 未启用/未就绪。 */
+  let bridgeMeta = null;
+  /** 桥工具(editor_context / editor_diagnostics)的 disposer;null = 未注册。 */
+  let bridgeToolDispose = null;
+  /** 提示词段落的 disposer(只注册一次;文本按桥是否存活渲染)。 */
+  let bridgePromptDispose = null;
+  /** agent 写操作观察器的 disposer。 */
+  let bridgeObserveDispose = null;
+  /** 推给编辑器的事件环形缓冲(tools/result → 扩展轮询)。 */
+  const bridgeEvents = createEventRing();
+  /** 编辑器状态缓存:扩展在每次 /sync 里推上来,agent 的工具调用来读它。 */
+  const bridgeContext = createContextCache();
+
+  /** 本次启动生成的新桥令牌;null = 本实例没有令牌(adopt 旧实例时会回读 bridge.json)。 */
+  let bridgeToken = null;
+
+  /** 桥是否启用(行配置为种子,设置文档里可实时改)。 */
+  function bridgeEnabled() {
+    return bridgeSetting !== false;
+  }
+
+  /** 提示词段落在插件激活时注册一次:文本按"桥是否存活"渲染(桥停时为空串 → DSH 丢弃该段),
+   *  所以在 IDE 从未启动的部署里它也只是一段空注册,不产生任何提示词开销。 */
+  setPromptLiveProbe(() => bridgeMeta !== null);
+  bridgePromptDispose = registerEditorPrompt(ctx);
+  if (bridgePromptDispose === null && bridgeEnabled()) {
+    console.warn('[code-server] 编辑器桥:systemPrompt 服务不可用,提示词段落未注册(工具仍可用)');
+  }
+
+  // 观察 agent 的写操作(→ 编辑器 diff 提示)并在写脏文件前附一条提醒。
+  // 与 IDE 是否在跑无关:桥没起来时 isLive() 为 false,dirty 检查直接跳过。
+  bridgeObserveDispose = registerBridgeObserver(ctx, {
+    emit: (kind, fields) => bridgeEvents.push(kind, fields),
+    context: () => bridgeContext.get(),
+    isLive: () => bridgeMeta !== null && !bridgeContext.isStale(),
+  });
+
+  /** 同步桥运行时:写入/更新 bridge.json,并(就绪时)注册编辑器工具。
+   *  端口、令牌、pid 三者任一变化都重写 —— 扩展每 5s 重读,故不需要任何推送。 */
+  function syncBridgeRuntime({ host, port, pid, startedAt }) {
+    if (!bridgeEnabled()) return;
+    if (typeof host !== 'string' || !Number.isSafeInteger(port) || port <= 0) return;
+    bridgeToken ??= mintBridgeToken();
+    const base = bridgeUrl(host, port);
+    const changed = bridgeMeta === null || bridgeMeta.url !== base || bridgeMeta.token !== bridgeToken || bridgeMeta.pid !== pid;
+    bridgeMeta = { url: base, token: bridgeToken, pid, startedAt: startedAt ?? null, host, port };
+    try {
+      writeBridgeConfig(bridgeExtensionsDir, { url: base, token: bridgeToken, pid, startedAt: startedAt ?? null });
+    } catch (err) {
+      console.warn(`[code-server] 编辑器桥配置写入失败(${bridgeExtensionsDir}):${err && err.message ? err.message : err}`);
+      return;
+    }
+    if (changed) {
+      // 只打印"已启用",不打印令牌本身(与 path-token 同一决策)。
+      console.log(`[code-server] 编辑器桥:已启用(${base},令牌文件 ${path.join(bridgeMetaDir, 'bridge.json')})`);
+    }
+    ensureBridgeTools();
+  }
+
+  /**
+   * 接管实例时对齐桥令牌:磁盘上已有配置且基址一致 → 沿用(避免无谓轮换打乱正在运行的扩展);
+   * 否则 mint 新的(扩展下次轮询就会读到新的 bridge.json,一次请求的失败无所谓)。
+   */
+  function adoptBridgeRuntime(host, port, pid, startedAt) {
+    if (!bridgeEnabled() || typeof host !== 'string' || !Number.isSafeInteger(port) || port <= 0) return;
+    const existing = readBridgeConfig(bridgeExtensionsDir);
+    const base = bridgeUrl(host, port);
+    bridgeToken = existing !== null && existing.url === base && TOKEN_RE.test(String(existing.token))
+      ? String(existing.token)
+      : mintBridgeToken();
+    syncBridgeRuntime({ host, port, pid, startedAt });
+  }
+
+  /** 注销桥运行时(停止 IDE / 插件卸载):删配置 + 注销工具 + 清缓存,扩展随即休眠。 */
+  function clearBridgeRuntime() {
+    bridgeToolDispose = disposeSafely(bridgeToolDispose);
+    bridgeContext.clear();
+    bridgeEvents.reset();
+    if (bridgeMeta === null) return;
+    bridgeMeta = null;
+    try {
+      removeBridgeConfig(bridgeExtensionsDir);
+    } catch {
+      // 配置删不掉不影响正确性(扩展会因 IDE 不可达而休眠)
+    }
+  }
+
+  function disposeSafely(dispose) {
+    if (typeof dispose !== 'function') return null;
+    try {
+      dispose();
+    } catch (err) {
+      console.warn(`[code-server] 桥工具注销失败:${err && err.message ? err.message : err}`);
+    }
+    return null;
+  }
+
+  /** 桥就绪时注册编辑器工具;`tools` / `defineTool` 缺失时静默退化为"只有 HTTP 面"。 */
+  function ensureBridgeTools() {
+    if (bridgeMeta === null || bridgeToolDispose !== null) return;
+    Promise.resolve(registerEditorTools(ctx, {
+      target: () => bridgeMeta,
+      cache: () => bridgeContext,
+    }))
+      .then((dispose) => {
+        if (dispose === null) {
+          console.log('[code-server] 编辑器桥:工具服务不可用,仅提供 HTTP 面(editor_context/editor_diagnostics 未注册)');
+          return;
+        }
+        // 期间桥可能已经被停掉(IDE 退出):立刻回滚,避免留下永远不可用的工具。
+        if (bridgeMeta === null) {
+          disposeSafely(dispose);
+          return;
+        }
+        bridgeToolDispose = dispose;
+        console.log('[code-server] 编辑器桥:已注册 editor_context / editor_diagnostics');
+      })
+      .catch((err) => {
+        console.warn(`[code-server] 编辑器桥工具注册失败:${err && err.message ? err.message : err}`);
+      });
+  }
+
   // ---- DSH 同源挂载(serve=dsh):把 /code-server 注册到 DSH 自己的 webServer ----
   // webServer 只在 web profile 存在(desktop 显式禁用该行)→ 用 ctx.inject 特性检测,
   // 缺失时 requestedServe() 自动回退 loopback。
@@ -497,6 +728,13 @@ export async function apply(ctx, config) {
     }
   }, 'code-server: dsh mount');
 
+  /** 回环模式的客户端 URL:随机端口 + 路径令牌(令牌是 URL 路径的一段,浏览器会把子请求与 WS
+   *  一并带过去 —— 这正是不走 VS Code 自带 cookie 令牌的原因,见 launcher 文件头"安全模型")。 */
+  function loopbackUrl() {
+    const token = typeof state.token === 'string' && state.token !== '' ? `${state.token}/` : '';
+    return `http://${cfg.host}:${state.port}/${token}`;
+  }
+
   function snapshot() {
     const running = state.status === 'running' && state.pid !== null;
     const dshMode = state.serve === 'dsh';
@@ -510,8 +748,9 @@ export async function apply(ctx, config) {
       pid: state.pid,
       cwd: state.cwd,
       launchCwd: state.launchCwd,
-      // dsh 模式:同源相对地址(由 DSH webServer 的 prefix 路由提供服务)
-      url: running ? (dshMode ? '/code-server/' : `http://${cfg.host}:${state.port}/`) : null,
+      // dsh 模式:同源相对地址(由 DSH webServer 的 prefix 路由提供服务);
+      // loopback:随机端口 + 路径令牌(令牌只出现在这个 URL 里,客户端据此加载 iframe)
+      url: running ? (dshMode ? '/code-server/' : loopbackUrl()) : null,
       productPath: state.env?.productPath ?? null,
       version: state.version,
       error: state.error,
@@ -521,6 +760,15 @@ export async function apply(ctx, config) {
       claimExtensions, // 客户端据此按扩展名决定认领哪些文件(0.2.11,取代 fileOpenScope)
       fullscreenOnOpen, // 客户端据此决定"打开标签即全屏右侧栏"(0.2.9)
       sidebarUi: state.sidebarUi,
+      /** 编辑器桥状态(0.3.0,只读诊断面;**不含令牌** —— 令牌只在 bridge.json 里)。 */
+      bridge: {
+        enabled: bridgeEnabled(),
+        live: bridgeMeta !== null,
+        toolsRegistered: bridgeToolDispose !== null,
+        supported: state.serve === 'loopback',
+        url: bridgeMeta === null ? null : bridgeMeta.url,
+        file: path.join(bridgeMetaDir, 'bridge.json'),
+      },
       env: state.env,
       setup: {
         running: state.setup.running,
@@ -617,19 +865,22 @@ export async function apply(ctx, config) {
       await killTree(pid);
     }
     removePidFile(cfg);
+    clearBridgeRuntime(); // 桥在 IDE 停止时同步下线:配置删除,扩展随即休眠
     state.status = 'stopped';
     state.pid = null;
     state.cwd = null;
     state.launchCwd = null;
+    state.token = null;
+    state.port = cfg.port;
     state.startedAt = null;
     state.adopted = false;
     if (reason) state.error = null;
   }
 
-  /** 就绪探针:loopback 走 TCP,dsh 模式走命名管道。 */
+  /** 就绪探针:loopback 走 TCP(带路径令牌),dsh 模式走命名管道。 */
   function probeReady(timeoutMs = 1500) {
     if (state.pipe !== null) return healthCheckPipe(state.pipe, timeoutMs);
-    return healthCheck(cfg.host, state.port, timeoutMs);
+    return healthCheck(cfg.host, state.port, state.token, timeoutMs);
   }
 
   function beginPollingReady() {
@@ -720,23 +971,29 @@ export async function apply(ctx, config) {
       console.warn('[code-server] 0.2.0 起不再支持口令认证(argon2 已移除),按 auth=none 运行');
     }
 
-    // 端口占用则尝试 adopt(仅 loopback 模式;pid.json 有效 + /healthz 响应),否则报错
-    if (serve === 'loopback') {
-      const probe = await healthCheck(cfg.host, cfg.port, 800);
+    // 端口占用则尝试 adopt(仅"显式指定端口"时;默认 port=0 由系统分配,不存在占用问题)。
+    // 探针必须带路径令牌(被接管的实例是我们自己拉的,令牌在令牌文件里)——
+    // 没有令牌文件说明那个实例不是本插件当前这代拉起来的,不接管。
+    if (serve === 'loopback' && cfg.port !== 0) {
+      const existingToken = readToken(cfg);
+      const probe = await healthCheck(cfg.host, cfg.port, existingToken, 800);
       if (probe.ok) {
         const record = readPidFile(cfg);
         if (record && isAlive(record.pid)) {
           state.serve = 'loopback';
           state.status = 'running';
           state.pid = record.pid;
+          state.port = cfg.port;
+          state.token = existingToken;
           state.cwd = cwd ?? record.cwd ?? null;
           state.launchCwd = record.launchCwd ?? record.cwd ?? null;
           state.startedAt = record.startedAt ?? null;
           state.adopted = true;
+          adoptBridgeRuntime(cfg.host, cfg.port, record.pid, state.startedAt);
           return snapshot();
         }
         state.status = 'error';
-        state.error = `端口 ${cfg.port} 已被占用且没有有效的 pid.json 记录(拒绝误杀);请释放端口或修改 port 配置`;
+        state.error = `端口 ${cfg.port} 已被占用且没有有效的 pid.json 记录(拒绝误杀);请释放端口或把 port 改回 0(随机端口)`;
         return snapshot();
       }
     }
@@ -748,8 +1005,9 @@ export async function apply(ctx, config) {
     fs.mkdirSync(userDataDir, { recursive: true });
     fs.mkdirSync(extensionsDir, { recursive: true });
 
-    // 安装内置扩展(dshcs-open-file:host 信号文件 → VS Code 打开文件)
-    installBundledExtension(extensionsDir, userDataDir);
+    // 安装树内自带扩展(dshcs-open-file:host 信号文件 → VS Code 打开文件;
+    // dshcs-editor-bridge:编辑器桥的扩展侧,0.3.0)
+    installBundledExtensions(extensionsDir, userDataDir);
 
     const args = launch.kind === 'launcher'
       ? [
@@ -773,7 +1031,12 @@ export async function apply(ctx, config) {
         args.push('--pipe', state.pipe);
       } else {
         state.pipe = null;
-        args.push('--port', String(cfg.port), '--host', cfg.host);
+        // 随机端口(port=0)+ 路径令牌:令牌**不进程 argv**(本机任意进程都能读命令行),
+        // 走文件传递;实际端口由 launcher 写 endpoint 文件回报。
+        fs.rmSync(endpointFile(cfg), { force: true }); // 清掉上一实例的记录,避免读到旧端口
+        state.token = rotateToken(cfg);
+        args.push('--port', String(cfg.port), '--host', cfg.host,
+          '--token-file', tokenFile(cfg), '--endpoint-file', endpointFile(cfg));
       }
       if (typeof cfg.locale === 'string' && cfg.locale !== '') args.push('--locale', cfg.locale);
     }
@@ -783,6 +1046,7 @@ export async function apply(ctx, config) {
     state.error = null;
     state.logTail = '';
     state.status = 'starting';
+    state.port = serve === 'dsh' ? null : cfg.port;
     state.cwd = cwd ?? null;
     state.launchCwd = cwd ?? null;
     state.startedAt = Date.now();
@@ -827,26 +1091,61 @@ export async function apply(ctx, config) {
     }
     child = proc;
     state.pid = proc.pid ?? null;
-    writePidFile(cfg, {
+    /** 实例记录:pid 一到手就先写(崩溃/回收要靠它);端口 0 时在拿到实际端口后再补写一次。 */
+    const writeInstanceRecord = () => writePidFile(cfg, {
       pid: proc.pid,
       startedAt: state.startedAt,
       cwd: cwd ?? null,
       launchCwd: cwd ?? null,
       host: serve === 'dsh' ? null : cfg.host,
-      port: serve === 'dsh' ? null : cfg.port,
+      port: serve === 'dsh' ? null : state.port,
       serve,
       pipe: state.pipe,
       launchKind: launch.kind,
       launchCommand: launch.kind === 'bin' ? launch.command : launch.script,
+      tokenized: state.token !== null,
     });
+    writeInstanceRecord();
 
     proc.stdout?.on?.('data', appendLog);
     proc.stderr?.on?.('data', appendLog);
 
+    // 端口 0(默认)时 host 只能从 endpoint 文件知道实际端口:等 launcher 写完再开始就绪轮询。
+    if (launch.kind === 'launcher' && serve === 'loopback' && cfg.port === 0) {
+      const deadline = Date.now() + 10000;
+      let endpoint = null;
+      while (endpoint === null && Date.now() < deadline) {
+        endpoint = readEndpoint(cfg);
+        if (endpoint !== null && endpoint.pid !== (proc.pid ?? -1)) endpoint = null; // 旧进程的残留记录
+        if (endpoint === null) await new Promise((r) => setTimeout(r, 100));
+      }
+      if (endpoint === null) {
+        state.status = 'error';
+        state.error = 'launcher 未回报监听端口(endpoint 文件缺失);请查看启动日志';
+        return snapshot();
+      }
+      state.port = endpoint.port;
+      writeInstanceRecord();
+      console.log(`[code-server] 随机端口: ${state.port}(host=${endpoint.host}, pid=${endpoint.pid})`);
+    }
+    // 编辑器桥:端口已定(loopback + 已知端口)时写入配置,扩展随即能连上来。
+    // 新启动会轮换桥令牌 —— 与路径令牌同一时机(每次新启动都换)。
+    // dsh 模式(无独立端口)不启用:桥的 Host 白名单假设是 127.0.0.1:<实际端口>,管道模式没有端口。
+    if (serve === 'loopback' && (cfg.port !== 0 || state.port !== null)) {
+      bridgeToken = mintBridgeToken();
+      syncBridgeRuntime({
+        host: cfg.host,
+        port: state.port,
+        pid: proc.pid ?? null,
+        startedAt: state.startedAt,
+      });
+    }
+
     proc.on('error', (err) => {
       if (child !== proc) return;
       child = null;
       removePidFile(cfg);
+      clearBridgeRuntime();
       state.status = 'error';
       state.error = `code-server 启动失败: ${err && err.message ? err.message : String(err)}\n${state.logTail.slice(-1000)}`;
     });
@@ -855,6 +1154,7 @@ export async function apply(ctx, config) {
       if (child !== proc) return; // 已被 stop/dispose 接管
       child = null;
       removePidFile(cfg);
+      clearBridgeRuntime();
       if (disposeKilled) return;
       state.status = 'error';
       state.error = `code-server 意外退出${code !== null ? `(exit ${code})` : signal ? `(signal ${signal})` : ''}:\n${state.logTail.slice(-1500)}`;
@@ -1017,6 +1317,95 @@ export async function apply(ctx, config) {
     }
   }
 
+  // ---- 编辑器桥路由(0.3.0)----
+  // 这些路由**不依赖** DSH 的 cookie 认证:扩展宿主是 Node 进程,拿不到浏览器 cookie,
+  // 所以自带独立令牌(见 lib/bridge.mjs 顶部的安全不变量)。命名空间永久只读。
+
+  /** 每个桥路由都先过 guard;返回 Response 表示拒绝,调用方直接返回它。 */
+  function bridgeRejection(request) {
+    return bridgeGuard(request, bridgeMeta === null ? null : bridgeMeta.token);
+  }
+
+  /** 桥不可达时的统一 503(扩展侧没跑 / IDE 刚起还没加载扩展)。 */
+  function bridgeDown(reason) {
+    return jsonResponse({ ok: false, error: reason }, 503);
+  }
+
+  async function handleBridgeHealth() {
+    // 无鉴权:只回一句"桥活着吗",不含任何编辑器数据(便于重启后一眼确认)。
+    return jsonResponse({
+      ok: true,
+      bridge: bridgeMeta !== null,
+      pid: state.pid,
+      url: bridgeMeta === null ? null : bridgeMeta.url,
+    });
+  }
+
+  async function handleBridgeSync(request) {
+    const denied = bridgeRejection(request);
+    if (denied !== null) return denied;
+    let body;
+    try {
+      body = await readJsonBody(request);
+    } catch {
+      return jsonResponse({ ok: false, error: '请求体不是合法 JSON' }, 400);
+    }
+    if (!bodyWithinLimit(body)) return jsonResponse({ ok: false, error: '上报内容过大' }, 413);
+    bridgeContext.update(body);
+    // 取事件 + 推进游标:与上报同一趟来回,扩展不需要第二个定时器。
+    let since = 0;
+    try {
+      const raw = new URL(request.url).searchParams.get('since');
+      const parsed = raw === null ? 0 : Number.parseInt(raw, 10);
+      if (Number.isSafeInteger(parsed) && parsed > 0) since = parsed;
+    } catch {
+      since = 0;
+    }
+    const events = bridgeEvents.since(since);
+    bridgeEvents.reset();
+    return jsonResponse({ ok: true, events });
+  }
+
+  async function handleBridgeAsk(request) {
+    const denied = bridgeRejection(request);
+    if (denied !== null) return denied;
+    let body;
+    try {
+      body = await readJsonBody(request);
+    } catch {
+      return jsonResponse({ ok: false, error: '请求体不是合法 JSON' }, 400);
+    }
+    const text = typeof body.text === 'string' ? body.text : '';
+    if (text === '') return jsonResponse({ ok: false, error: '需要 text 字段(要问 DSH 的话)' }, 400);
+    const file = typeof body.file === 'string' && body.file !== '' ? body.file : null;
+    const lineStart = Number.isSafeInteger(body.lineStart) ? body.lineStart : null;
+    const lineEnd = Number.isSafeInteger(body.lineEnd) ? body.lineEnd : null;
+    const selection = typeof body.selection === 'string' && body.selection !== '' ? body.selection : null;
+    // 交给 bridge-session.mjs(agent 投递);它内部特性探测 agents,缺失时返回
+    // {ok:false, code:'NO_AGENT'} —— 这里原样透传,并把 NO_AGENT 映射成 409。
+    const result = await deliverEditorPrompt(ctx, {
+      text,
+      file,
+      lineStart,
+      lineEnd,
+      selection,
+      languageId: typeof body.languageId === 'string' ? body.languageId : null,
+    });
+    return jsonResponse(result, result.ok === true ? 200 : (result.code === 'NO_AGENT' ? 409 : 200));
+  }
+
+  async function handleBridgeEvent(request) {
+    const denied = bridgeRejection(request);
+    if (denied !== null) return denied;
+    const body = await readJsonBody(request);
+    const kind = typeof body.kind === 'string' ? body.kind : '';
+    if (kind === '') return jsonResponse({ ok: false, error: '需要 kind 字段' }, 400);
+    // 扩展上报的编辑器侧事件(打开/关闭文件等):目前只进日志尾,供诊断时回看。
+    appendLog(`[bridge] ${kind}${typeof body.path === 'string' ? ` ${body.path}` : ''}\n`);
+    return jsonResponse({ ok: true });
+  }
+
+
   // 每条操作一条 exact Fetch 路由。desktop 的 assetHandler 只把 /api/* 交给
   // createSharedFetchHandler('/api'),所以路径必须落在 /api 下。
   const disposers = [    { path: `${API_BASE}/status`, methods: ['GET'], fetch: handleStatus },
@@ -1025,6 +1414,13 @@ export async function apply(ctx, config) {
     { path: `${API_BASE}/setup`, methods: ['POST'], fetch: handleSetup },
     { path: `${API_BASE}/open-file`, methods: ['POST'], fetch: handleOpenFile },
     { path: `${API_BASE}/ui-mode`, methods: ['POST'], fetch: handleUiMode },
+    // ---- 编辑器桥(0.3.0):扩展侧的 HTTP 面。全部自带令牌鉴权,**命名空间永久只读**。----
+    // 只有 4 条:扩展宿主没有 HTTP 服务器,所以"拿编辑器状态"由扩展在 /sync 里推上来,
+    // host 缓存后供 agent 工具读取(见 lib/bridge.mjs 顶部的通道说明)。
+    { path: `${API_BASE}/bridge/health`, methods: ['GET'], fetch: handleBridgeHealth },
+    { path: `${API_BASE}/bridge/sync`, methods: ['POST'], fetch: handleBridgeSync },
+    { path: `${API_BASE}/bridge/ask`, methods: ['POST'], fetch: handleBridgeAsk },
+    { path: `${API_BASE}/bridge/event`, methods: ['POST'], fetch: handleBridgeEvent },
   ].map(route => connection.fetch.register({
     path: route.path,
     methods: route.methods,
@@ -1036,6 +1432,9 @@ export async function apply(ctx, config) {
     return () => {
       disposeKilled = true;
       stopPolling();
+      bridgeObserveDispose = disposeSafely(bridgeObserveDispose);
+      bridgePromptDispose = disposeSafely(bridgePromptDispose);
+      clearBridgeRuntime();
       for (const d of disposers) {
         try {
           // connection.fetch.register 的 disposer 是异步的(返回 Promise);
@@ -1094,19 +1493,28 @@ export async function apply(ctx, config) {
     console.log(`[code-server] 检测到旧版安装根 ${legacyRoot}(0.1.35 及更早遗留,已不再使用,可安全删除)`);
   }
 
-  // DSH host 重启后 adopt(仅 loopback 模式):pid.json 有效且进程存活且 /healthz 响应 → 接管。
+  // DSH host 重启后 adopt(仅 loopback 模式):pid.json 有效、进程存活、令牌文件在、endpoint 记录的端口
+  // 上 /healthz(带令牌)响应 → 接管。端口 0 时不能拿 cfg.port 去探(那是个占位值),必须用 endpoint 文件。
   // dsh 模式的 launcher 带 --parent-pid 看门狗:host 一退出它就自行退出,不存在可接管的孤儿。
   if (liveInstance && (record.serve !== 'dsh')) {
-    const probe = await healthCheck(cfg.host, cfg.port, 800);
+    const adoptedToken = readToken(cfg);
+    const endpoint = readEndpoint(cfg);
+    const adoptPort = endpoint !== null && endpoint.pid === record.pid ? endpoint.port : (cfg.port !== 0 ? cfg.port : null);
+    const probe = adoptPort === null || adoptedToken === null
+      ? { ok: false }
+      : await healthCheck(cfg.host, adoptPort, adoptedToken, 800);
     if (probe.ok) {
       state.serve = 'loopback';
       state.status = 'running';
       state.pid = record.pid;
+      state.port = adoptPort;
+      state.token = adoptedToken;
       state.cwd = record.cwd ?? null;
       state.launchCwd = record.launchCwd ?? record.cwd ?? null;
       state.startedAt = record.startedAt ?? null;
       state.adopted = true;
-      console.log(`[code-server] adopted running instance pid=${record.pid} port=${cfg.port}`);
+      console.log(`[code-server] adopted running instance pid=${record.pid} port=${adoptPort}(令牌已启用)`);
+      adoptBridgeRuntime(cfg.host, adoptPort, record.pid, state.startedAt);
     } else {
       removePidFile(cfg);
     }
@@ -1116,5 +1524,5 @@ export async function apply(ctx, config) {
 
   maybePrestart();
 
-  console.log(`[code-server] static plugin loaded (serve=${requestedServe()} host=${cfg.host} port=${cfg.port})`);
+  console.log(`[code-server] static plugin loaded (serve=${requestedServe()} host=${cfg.host} port=${cfg.port === 0 ? '0=随机' : cfg.port})`);
 }