dsh-code-server-app 0.2.13 → 0.3.6

package/lib/bridge-observe.mjs

@@ -0,0 +1,184 @@
+/**
+ * lib/bridge-observe.mjs — 观察 agent 的写操作,并把结果送进编辑器(0.3.0)。
+ *
+ * 两个方向:
+ *
+ * **agent → 编辑器**(`tools/result`):把所有写类工具的落点推成"去看一眼这个文件"的事件。
+ *   - 不限定 agent:`ctx.on('tools/result')` 注册在根上下文,而 `dsh-scope` 的载体过滤是
+ *     `tag === undefined → true`,所以**一个监听器能看到所有 agent 与子 agent 的调用**;
+ *   - 事件里**只带路径**,不带内容 —— 内容由扩展自己算(它才知道缓冲区里那一份),
+ *     这也让 host 侧不持有文件内容(少一处泄密面);
+ *   - 有两条抽取路径,都必要:
+ *       ① `result.meta.diffs`(`dsh-tool-fs` 的 write/edit 会带上 `FsDiffMeta`);
+ *       ② 从 `exec.arguments.file_path` / `.path` 直接取(`str_replace_editor` **不带** meta,
+ *          在别的 profile 里它才是主力工具)。
+ *   - `tools/result` 是 emit 型观察点:抛错不会影响调用结果(`notifyResult` 内部吞掉 listener
+ *     异常),所以这里出问题最坏就是"少一次 diff 提示",绝不会弄坏 agent 的一轮。
+ *
+ * **编辑器 → agent**(`tools/pre-execute`):写之前如果该文件在编辑器里是脏的,附一条提示。
+ *   - 用 `exec.deferContext(...)` 而不是改写入参:`PreToolDecision` **明确排除了入参改写**
+ *     (参数已经进日志与展示了),所以"提醒"是唯一正确的介入方式;
+ *   - **不阻断**:误报的代价是模型看到一句提示,而阻断一个正确的编辑会让 agent 卡住;
+ *   - 桥不可用/状态过期 → 直接放行,零开销。
+ */
+
+import { loadDshExport } from './dsh-resolve.mjs';
+
+/** 会改文件的工具名(各 profile 里的名字不同,所以按"名字 + 参数里有路径"双重判定)。 */
+const WRITE_TOOLS = new Set(['write', 'edit', 'str_replace_editor', 'create_file', 'apply_patch', 'multi_edit']);
+
+/** 提示词的来源标记(会话日志里能看出这条来自编辑器桥)。 */
+const SOURCE_PLUGIN = 'dsh-code-server-app:editor-bridge';
+
+/** 同一个文件在多少毫秒内不重复推事件(agent 连续改同一文件时避免刷屏)。 */
+const DEBOUNCE_MS = 1500;
+
+/**
+ * 从一次工具结果里抽出"被改动的文件路径"。
+ *
+ * @param {string} name 工具名
+ * @param {unknown} args 调用参数(可能含 file_path / path)
+ * @param {{meta?: unknown}} result 结果(maybe 带 FsDiffMeta)
+ * @returns {string[]} 绝对路径列表(去重)
+ */
+export function extractEditedPaths(name, args, result) {
+  const paths = new Set();
+  // ① 结果元数据里的 diff(最准:`dsh-tool-fs` 的 write/edit 每个 hunk 一条)
+  const meta = result !== null && typeof result === 'object' ? result.meta : undefined;
+  if (meta !== null && typeof meta === 'object' && Array.isArray(meta.diffs)) {
+    for (const diff of meta.diffs) {
+      if (diff !== null && typeof diff === 'object' && typeof diff.path === 'string' && diff.path !== '') {
+        paths.add(diff.path);
+      }
+    }
+  }
+  // ② 参数里的路径(str_replace_editor 这类没有 meta 的工具靠这条)
+  if (paths.size === 0 && WRITE_TOOLS.has(name) && args !== null && typeof args === 'object') {
+    for (const key of ['file_path', 'path', 'file']) {
+      const value = args[key];
+      if (typeof value === 'string' && value !== '') {
+        paths.add(value);
+        break;
+      }
+    }
+    // str_replace_editor 的 `view` 不改文件 —— 别把只读调用也报成改动
+    if (name === 'str_replace_editor' && args.command === 'view') paths.clear();
+  }
+  return [...paths];
+}
+
+/**
+ * 注册观察器(返回同步 disposer)。
+ *
+ * @param {object} ctx cordis 上下文(需要能 `on`)
+ * @param {{
+ *   emit: (kind: string, fields?: object) => void,
+ *   context: () => object|null,
+ *   isLive: () => boolean,
+ * }} deps
+ *   `emit(kind, fields)` 把事件推进 host 的环形缓冲;
+ *   `context()` 取编辑器状态缓存(可能为 null);
+ *   `isLive()` 桥是否就绪(用于决定要不要做脏缓冲区检查)。
+ */
+export function registerBridgeObserver(ctx, deps) {
+  if (ctx === undefined || ctx === null || typeof ctx.on !== 'function') return null;
+  const disposers = [];
+  /** path → 上次推送时间(去抖)。 */
+  const lastEmit = new Map();
+
+  const onResult = (exec, result) => {
+    try {
+      if (exec === null || exec === undefined) return;
+      const name = typeof exec.name === 'string' ? exec.name : '';
+      if (name === '') return;
+      const isError = result !== null && typeof result === 'object' && result.isError === true;
+      if (isError) return; // 失败的写没有落点,别把编辑器叫起来
+      const paths = extractEditedPaths(name, exec.arguments, result);
+      if (paths.length === 0) return;
+      const now = Date.now();
+      const sessionId = exec.agent !== undefined && exec.agent !== null && exec.agent.session !== undefined
+        ? (exec.agent.session.id ?? exec.agent.id ?? null)
+        : null;
+      for (const filePath of paths) {
+        const previous = lastEmit.get(filePath);
+        if (previous !== undefined && now - previous < DEBOUNCE_MS) continue;
+        lastEmit.set(filePath, now);
+        deps.emit('agent-edit', { path: filePath, tool: name, sessionId });
+      }
+      // 去抖表也要有界(长时间会话里文件数会涨)。
+      if (lastEmit.size > 512) {
+        for (const [key, at] of lastEmit) {
+          if (now - at > DEBOUNCE_MS * 10) lastEmit.delete(key);
+        }
+      }
+    } catch (err) {
+      // emit 型观察点的异常会被 DSH 吞掉,这里自己记一条更清楚
+      console.warn(`[code-server] 编辑器桥:处理 tool/result 失败 ${err && err.message ? err.message : err}`);
+    }
+  };
+
+  const onPreExecute = async (exec, next) => {
+    const decision = await next();
+    try {
+      if (decision === null || decision === undefined || decision.kind !== 'allow') return decision;
+      if (!deps.isLive()) return decision;
+      const name = typeof exec?.name === 'string' ? exec.name : '';
+      if (!WRITE_TOOLS.has(name)) return decision;
+      const args = exec.arguments;
+      if (args === null || typeof args !== 'object') return decision;
+      const filePath = typeof args.file_path === 'string' ? args.file_path
+        : (typeof args.path === 'string' ? args.path : null);
+      if (filePath === null || filePath === '') return decision;
+      if (name === 'str_replace_editor' && args.command === 'view') return decision;
+      const cached = deps.context();
+      if (cached === null || cached === undefined || cached.context === null) return decision;
+      const dirty = Array.isArray(cached.context.dirtyBuffers) ? cached.context.dirtyBuffers : [];
+      const hit = dirty.find((item) => item !== null && item.path === filePath);
+      if (hit === undefined) return decision;
+      const createUserMessage = await loadDshCreateUserMessage();
+      if (typeof createUserMessage !== 'function') return decision;
+      if (typeof exec.deferContext !== 'function') return decision;
+      exec.deferContext(createUserMessage({
+        content: [{
+          type: 'text',
+          text: `Note from the editor: ${filePath} has UNSAVED changes in the VS Code buffer.`
+            + ' Writing it now will conflict with what the user sees; the editor will keep their buffer and show a diff.'
+            + ' Consider mentioning it, or asking them to save/discard first.',
+        }],
+        source: { kind: 'plugin', plugin: SOURCE_PLUGIN, form: 'notice', summary: '编辑器里有未保存改动' },
+      }));
+    } catch (err) {
+      // 提示失败绝不影响调用
+      console.warn(`[code-server] 编辑器桥:dirty 提示失败 ${err && err.message ? err.message : err}`);
+    }
+    return decision;
+  };
+
+  try {
+    disposers.push(ctx.on('tools/result', onResult));
+  } catch (err) {
+    console.warn(`[code-server] 编辑器桥:注册 tools/result 失败 ${err && err.message ? err.message : err}`);
+  }
+  try {
+    disposers.push(ctx.on('tools/pre-execute', onPreExecute));
+  } catch (err) {
+    console.warn(`[code-server] 编辑器桥:注册 tools/pre-execute 失败 ${err && err.message ? err.message : err}`);
+  }
+
+  return () => {
+    for (const dispose of disposers) {
+      try {
+        if (typeof dispose === 'function') dispose();
+      } catch {
+        // 忽略
+      }
+    }
+  };
+}
+
+/** 懒解析(与 bridge-tools 同一策略):解析不到就静默跳过提示。 */
+let createUserMessagePromise = null;
+function loadDshCreateUserMessage() {
+  createUserMessagePromise ??= loadDshExport('@deepseek-ai/dsh-llm', 'createUserMessage');
+  return createUserMessagePromise;
+}

package/lib/bridge-session.mjs

@@ -0,0 +1,124 @@
+/**
+ * lib/bridge-session.mjs — 把编辑器里的动作投递成 DSH 的一条用户消息(0.3.0)。
+ *
+ * 方向:编辑器 → DSH。用户在编辑器里选中一段代码、说一句"这个函数为什么是错的",
+ * 这句话应当出现在**当前会话**里,并且带上文件:行与选区文本。
+ *
+ * 投递目标的选取顺序(都通过 `ctx.get(...)` 特性探测,DSH 版本差异不会炸主流程):
+ *   1. `ctx.agents.currentInitiator()` —— 正在跑的那次驱动链的 agent(最贴近"当前会话");
+ *   2. `ctx.agents.list()` —— 有 running 的取 running,否则取列表里最后一个(通常是最新的);
+ *   3. 都没有 → `{ok:false, code:'NO_AGENT'}`(编辑器侧据此提示"先在 DSH 里打开一个会话")。
+ *
+ * 投递方式是 `agent.followup(message)`(= `send(msg, 'next-turn', true)`):
+ * agent 空闲则立刻开一轮,正在跑则排在下一轮 —— 两种情况下用户都能看到自己的话进了对话。
+ */
+
+import { loadDshExport } from './dsh-resolve.mjs';
+
+/** 消息来源标记:在会话日志里能一眼看出这条来自编辑器桥。 */
+export const SOURCE_PLUGIN = 'dsh-code-server-app:editor-bridge';
+
+/** 拼进消息的选区文本上限(超长时截断并注明)。 */
+export const MAX_SELECTION_CHARS = 8000;
+
+/** 供模型识别的文件引用文本(1 基行号,与 VS Code 一致)。 */
+function locationText(file, lineStart, lineEnd) {
+  if (typeof file !== 'string' || file === '') return null;
+  if (!Number.isSafeInteger(lineStart)) return file;
+  if (!Number.isSafeInteger(lineEnd) || lineEnd === lineStart) return `${file}:${lineStart}`;
+  return `${file}:${lineStart}-${lineEnd}`;
+}
+
+/**
+ * 组消息文本。
+ *
+ * 结构刻意保持"人类可读 + 机器可抠":第一行是位置,代码块带语言标记,
+ * 最后是用户的原话 —— 这样即使模型没调任何工具,它也知道该看哪个文件。
+ *
+ * @param {{text: string, file: string|null, lineStart: number|null, lineEnd: number|null,
+ *          languageId: string|null, selection: string|null}} input
+ */
+export function composeEditorPrompt(input) {
+  const parts = [];
+  const location = locationText(input.file, input.lineStart, input.lineEnd);
+  if (location !== null) parts.push(`From the editor: ${location}`);
+  if (typeof input.selection === 'string' && input.selection !== '') {
+    const lang = typeof input.languageId === 'string' && input.languageId !== '' ? input.languageId : '';
+    const body = input.selection.length > MAX_SELECTION_CHARS
+      ? `${input.selection.slice(0, MAX_SELECTION_CHARS)}\n…(selection truncated)`
+      : input.selection;
+    parts.push(['```' + lang, body, '```'].join('\n'));
+  }
+  parts.push(input.text);
+  return parts.join('\n\n');
+}
+
+/**
+ * 选一个投递目标 agent。
+ * @param {object} ctx cordis 上下文
+ */
+export function pickAgent(ctx) {
+  const agents = ctx?.agents ?? (typeof ctx?.get === 'function' ? ctx.get('agents') : undefined);
+  if (agents === undefined || agents === null) return null;
+  try {
+    if (typeof agents.currentInitiator === 'function') {
+      const current = agents.currentInitiator();
+      if (current !== undefined && current !== null) return current;
+    }
+  } catch {
+    // 不在 initiator 边界内(正常:路由回调不在驱动链上)
+  }
+  try {
+    if (typeof agents.list === 'function') {
+      const list = agents.list();
+      if (Array.isArray(list) && list.length > 0) {
+        const running = list.filter((agent) => agent !== null && agent !== undefined && agent.status === 'running');
+        return running.length > 0 ? running[running.length - 1] : list[list.length - 1];
+      }
+    }
+  } catch {
+    // 探测失败 = 当作没有可用 agent
+  }
+  return null;
+}
+
+/**
+ * 投递一条编辑器消息。
+ *
+ * **永不抛**:返回结构化结果,由路由决定 HTTP 码。
+ * 所有失败路径都带上 `code`,便于编辑器侧给出可操作的提示。
+ *
+ * @param {object} ctx cordis 上下文
+ * @param {object} input `composeEditorPrompt` 的输入
+ * @returns {Promise<{ok: boolean, code?: string, error?: string, sessionId?: string, text?: string}>}
+ */
+export async function deliverEditorPrompt(ctx, input) {
+  const createUserMessage = await loadDshExport('@deepseek-ai/dsh-llm', 'createUserMessage');
+  if (typeof createUserMessage !== 'function') {
+    return { ok: false, code: 'NO_LLM', error: '解析不到 @deepseek-ai/dsh-llm 的 createUserMessage(DSH 部署不完整?)' };
+  }
+  const agent = pickAgent(ctx);
+  if (agent === null || agent === undefined) {
+    return { ok: false, code: 'NO_AGENT', error: '没有可投递的会话:请先在 DSH 里打开或新建一个会话' };
+  }
+  const text = composeEditorPrompt(input);
+  let message;
+  try {
+    message = createUserMessage({
+      content: [{ type: 'text', text }],
+      source: { kind: 'plugin', plugin: SOURCE_PLUGIN, form: 'notice', summary: '来自编辑器' },
+    });
+  } catch (err) {
+    return { ok: false, code: 'BAD_MESSAGE', error: `构造消息失败:${err && err.message ? err.message : String(err)}` };
+  }
+  try {
+    // followup = 下一轮 + 唤醒:agent 空闲就立刻开一轮,在跑就排队,两种情况用户都能看到。
+    agent.followup(message);
+  } catch (err) {
+    return { ok: false, code: 'DELIVER_FAILED', error: `投递失败:${err && err.message ? err.message : String(err)}` };
+  }
+  const sessionId = agent.session !== undefined && agent.session !== null && typeof agent.session === 'object'
+    ? (agent.session.id ?? agent.id ?? null)
+    : (agent.id ?? null);
+  return { ok: true, sessionId, text };
+}

package/lib/bridge-tools.mjs

@@ -0,0 +1,330 @@
+/**
+ * lib/bridge-tools.mjs — 编辑器桥的 agent 侧接口(0.3.0)。
+ *
+ * 两个**只读**工具 + 一段系统提示词说明:
+ *   - `editor_context`     :编辑器当前状态(活动文件/选区、未保存缓冲区、诊断计数)
+ *   - `editor_diagnostics` :按严重度排序的诊断(可只问一个文件)
+ *
+ * 为什么是工具而不是"每步注入":
+ *   `agent/pre-step` 每步都会跑,把编辑器状态无条件塞进上下文会让每个请求都变重且多半无关。
+ *   工具化 = 按需、有界、可被模型自己取舍。提示词只在桥可用时渲染(函数式 `text` 返回空串
+ *   会被 DSH 丢弃),所以 IDE 没起来时模型完全看不到这套东西。
+ *
+ * 为什么只在桥存活时注册:
+ *   桥不可用时注册会留下"永远不可用"的工具,模型会反复试。注销掉更干净 —— `tools/change`
+ *   会让客户端刷新工具集。若实测发现客户端对工具集变化处理不佳,把 `registerEditorTools`
+ *   改成"始终注册 + execute 里返回不可用说明"即可(单点开关)。
+ *
+ * 依赖注入:`defineTool` 从 DSH 部署里解析(见 `loadDefineTool`),不引入新的包依赖。
+ */
+
+import { loadDshExport } from './dsh-resolve.mjs';
+
+/** 工具名(模型可见)。 */
+export const EDITOR_CONTEXT_TOOL = 'editor_context';
+export const EDITOR_DIAGNOSTICS_TOOL = 'editor_diagnostics';
+
+/** systemPrompt 段名与排序位置:靠后(在工具说明之后、运行时上下文之前)。 */
+export const PROMPT_SECTION = 'code-server:editor-bridge';
+export const PROMPT_ORDER = 4500;
+
+/** 提示词全文(仅桥可用时渲染)。 */
+export const PROMPT_TEXT = [
+  '## Editor bridge (VS Code / code-server)',
+  '',
+  'A VS Code workbench is running next to this session and can be queried read-only:',
+  '',
+  '- `editor_context` — what the user is looking at right now: active file and selection, which',
+  '  buffers have UNSAVED changes, and how many problems each file has.',
+  '- `editor_diagnostics` — errors/warnings with file:line, produced by the real language servers',
+  '  (TypeScript, ESLint, …). Prefer this over guessing: it is cheaper and more accurate than',
+  '  re-reading whole files.',
+  '',
+  'Use them when the user mentions "this file", "my selection", "the error I see", or when a change',
+  'must not clobber unsaved edits. If a file has unsaved changes in the editor, the on-disk content',
+  'differs from what the user sees — say so instead of silently overwriting it. Both tools are',
+  'read-only: they never edit files or run commands.',
+].join('\n');
+
+/** 工具描述(内联,避免 z.string().default 那种"必须重启才生效"的配置面)。 */
+const CONTEXT_DESCRIPTION = [
+  'Read the current state of the VS Code editor: active file + selection, open buffers with unsaved',
+  'changes, and problem counts per file. Read-only. Returns {"available":false} when no editor is',
+  'attached (then fall back to reading files from disk).',
+].join(' ');
+
+const DIAGNOSTICS_DESCRIPTION = [
+  'Read errors/warnings reported by the editor\'s language servers (the Problems panel), newest',
+  'state, sorted by severity. Optionally narrow to one file. Read-only. Returns',
+  '{"available":false} when no editor is attached.',
+].join(' ');
+
+// ---------------------------------------------------------------- DSH 依赖懒解析
+
+/**
+ * 解析 `defineTool`(解析策略见 lib/dsh-resolve.mjs)。
+ * 解析不到 = 当前 DSH 没有工具服务 → 返回 null,桥退化为"只有 HTTP 面",不影响主流程。
+ */
+async function loadDefineTool() {
+  return loadDshExport('@deepseek-ai/dsh-tools', 'defineTool');
+}
+
+// ---------------------------------------------------------------- 工具值投影
+
+/**
+ * 把 `/context` 的响应压成模型友好的短文本。
+ *
+ * 上限在**扩展侧**也有一份(它才是权威);这里再兜一层是因为模型看到的是这个字符串,
+ * 不能因为扩展版本不一致就把一整棵诊断树塞进上下文。
+ */
+function renderContext(value) {
+  if (value.available !== true) {
+    return `编辑器上下文不可用:${value.reason ?? '未知原因'}(回退到直接读磁盘文件)`;
+  }
+  const lines = [];
+  const active = value.active ?? null;
+  if (active === null) {
+    lines.push('活动编辑器:无(用户没有聚焦任何文件)');
+  } else {
+    const sel = active.selection === null || active.selection === undefined
+      ? ''
+      : ` 选区 ${active.selection.startLine}:${active.selection.startColumn}-${active.selection.endLine}:${active.selection.endColumn}`;
+    lines.push(`活动编辑器:${active.path ?? active.name}${active.language ? ` (${active.language})` : ''}`
+      + `${active.dirty === true ? ' — 有未保存改动' : ''}${sel}`);
+    if (typeof active.selectedText === 'string' && active.selectedText !== '') {
+      lines.push('选中的文本:');
+      lines.push('```');
+      lines.push(active.selectedText.length > 4000 ? `${active.selectedText.slice(0, 4000)}\n…(已截断)` : active.selectedText);
+      lines.push('```');
+    }
+  }
+  const dirty = Array.isArray(value.dirtyBuffers) ? value.dirtyBuffers : [];
+  if (dirty.length === 0) {
+    lines.push('未保存缓冲区:无(磁盘内容 = 用户所见)');
+  } else {
+    lines.push(`未保存缓冲区(${dirty.length} 个,磁盘内容与用户所见不一致;不要直接覆盖):`);
+    for (const item of dirty.slice(0, 20)) {
+      lines.push(`  - ${item.path ?? item.name}${typeof item.unsavedLines === 'number' ? `(+${item.unsavedLines} 行未保存)` : ''}`);
+    }
+    if (dirty.length > 20) lines.push(`  …(还有 ${dirty.length - 20} 个)`);
+  }
+  const problems = Array.isArray(value.problems) ? value.problems : [];
+  if (problems.length === 0) {
+    lines.push('问题面板:无错误/警告');
+  } else {
+    lines.push('问题面板(按文件聚合,用 editor_diagnostics 看细节):');
+    for (const item of problems.slice(0, 30)) {
+      lines.push(`  - ${item.path}:${item.line ?? ''} ${item.severity} ${item.message}`);
+    }
+    if (problems.length > 30) lines.push(`  …(还有 ${problems.length - 30} 个)`);
+  }
+  if (typeof value.truncated === 'string' && value.truncated !== '') lines.push(`(注:${value.truncated})`);
+  return lines.join('\n');
+}
+
+/** 诊断结果 → 模型友好短文本(带 file:line,便于模型直接定位)。 */
+function renderDiagnostics(value) {
+  if (value.available !== true) {
+    return `编辑器诊断不可用:${value.reason ?? '未知原因'}(回退到在你自己的终端里跑 tsc/eslint)`;
+  }
+  const items = Array.isArray(value.diagnostics) ? value.diagnostics : [];
+  if (items.length === 0) return '没有匹配的诊断(编辑器当前没有报错或警告)';
+  const lines = [`诊断 ${items.length} 条${typeof value.total === 'number' && value.total > items.length ? `(共 ${value.total},已截断)` : ''}:`];
+  for (const d of items) {
+    lines.push(`${d.path}:${d.line}:${d.column} [${d.severity}] ${d.message}${d.source ? ` (${d.source}${d.code ? ` ${d.code}` : ''})` : ''}`);
+  }
+  return lines.join('\n');
+}
+
+/** 桥不可用时的统一值(永不抛:工具失败会让模型重试,而"没接编辑器"不是错误)。 */
+function unavailable(reason) {
+  return { available: false, reason, active: null, dirtyBuffers: [], problems: [], diagnostics: [], total: 0 };
+}
+
+/** 严重度排序权重(与扩展侧 lib/context-model.js 的 SEVERITY_RANK 一致)。 */
+const SEVERITY_RANK = { error: 0, warning: 1, info: 2, hint: 3 };
+const MAX_DIAGNOSTICS = 200;
+
+/** 把缓存里的诊断树(`[{path, items:[{line,column,severity,message,source,code}]}]`)按入参过滤。 */
+function projectDiagnostics(tree, args) {
+  const rows = [];
+  for (const group of tree) {
+    if (group === null || typeof group.path !== 'string') continue;
+    if (typeof args.file === 'string' && args.file !== '' && group.path !== args.file) continue;
+    for (const item of Array.isArray(group.items) ? group.items : []) {
+      const severity = typeof item.severity === 'string' ? item.severity : 'info';
+      if (typeof args.severity === 'string' && SEVERITY_RANK[severity] !== undefined && SEVERITY_RANK[severity] > SEVERITY_RANK[args.severity]) continue;
+      rows.push({
+        path: group.path,
+        line: Number.isSafeInteger(item.line) ? item.line : 1,
+        column: Number.isSafeInteger(item.column) ? item.column : 1,
+        severity,
+        message: typeof item.message === 'string' ? item.message : '',
+        ...(typeof item.source === 'string' && item.source !== '' ? { source: item.source } : {}),
+        ...(item.code === undefined || item.code === null || item.code === '' ? {} : { code: String(item.code) }),
+      });
+    }
+  }
+  rows.sort((a, b) => (SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity])
+    || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)
+    || (a.line - b.line));
+  const cap = Number.isSafeInteger(args.limit) && args.limit > 0 ? Math.min(args.limit, MAX_DIAGNOSTICS) : 100;
+  return { diagnostics: rows.slice(0, cap), total: rows.length, truncated: rows.length > cap };
+}
+
+/** 桥是否"活着":启用 + 扩展在最近一个 TTL 内上报过。 */
+function bridgeLive(deps) {
+  const meta = deps.target();
+  if (meta === null || meta === undefined) return { live: false, reason: '编辑器桥未启用(IDE 没在运行,或 serve=dsh 不支持桥)' };
+  const cache = deps.cache();
+  if (cache === null || cache === undefined || cache.get() === null) {
+    return { live: false, reason: '编辑器里的扩展还没有上报状态(IDE 刚起?扩展被禁用了?)' };
+  }
+  if (cache.isStale()) {
+    const age = cache.ageMs();
+    return { live: false, reason: `编辑器状态已过期(${age === null ? '未知' : `${Math.round(age / 1000)}s`} 没更新;IDE 面板关掉了吗?)` };
+  }
+  return { live: true };
+}
+
+// ---------------------------------------------------------------- 注册
+
+/**
+ * 注册编辑器工具,返回**同步** disposer。
+ *
+ * 由 `lib/index.js` 在桥进入 running 时调用、离开 running 时调用 disposer。
+ * `tools` 服务缺失 / `defineTool` 解析不到时返回 null(调用方据此退化为"只有 HTTP 面")。
+ *
+ * @param {object} ctx cordis 上下文(需要有 `tools` 服务)
+ * @param {{target: () => object|null, cache: () => object|null}} deps
+ *        `target()` 取当前桥目标(null = 未启用);`cache()` 取编辑器状态缓存
+ *        (见 lib/bridge.mjs 的 createContextCache —— 扩展在每次 /sync 里刷新它)。
+ */
+export async function registerEditorTools(ctx, deps) {
+  const tools = ctx?.tools ?? (typeof ctx?.get === 'function' ? ctx.get('tools') : undefined);
+  if (tools === undefined || tools === null || typeof tools.register !== 'function') return null;
+  const defineTool = await loadDefineTool();
+  if (defineTool === null) return null;
+
+  const contextTool = defineTool({
+    name: EDITOR_CONTEXT_TOOL,
+    description: CONTEXT_DESCRIPTION,
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          available: { type: 'boolean', required: true },
+          reason: { type: 'string' },
+          active: { type: 'json' },
+          dirtyBuffers: { type: 'array', items: { type: 'json' } },
+          problems: { type: 'array', items: { type: 'json' } },
+          diagnostics: { type: 'array', items: { type: 'json' } },
+          total: { type: 'integer' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: renderContext(value) }],
+    },
+    async execute(_args, _exec) {
+      const status = bridgeLive(deps);
+      if (status.live !== true) return unavailable(status.reason);
+      const context = deps.cache().get().context;
+      return { ...context, available: true };
+    },
+    presentCall: () => ({ card: 'generic', title: '读取编辑器状态', kind: 'read' }),
+  });
+
+  const diagnosticsTool = defineTool({
+    name: EDITOR_DIAGNOSTICS_TOOL,
+    description: DIAGNOSTICS_DESCRIPTION,
+    parameters: {
+      file: { type: 'string', description: '可选:只看这个文件(绝对路径,必须已在编辑器的工作区内)' },
+      severity: {
+        type: 'string',
+        enum: ['error', 'warning', 'info', 'hint'],
+        description: '可选:只保留该严重度及以上(默认全部)',
+      },
+      limit: { type: 'integer', description: '可选:最多返回多少条(默认 100,上限 200)' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          available: { type: 'boolean', required: true },
+          reason: { type: 'string' },
+          diagnostics: { type: 'array', items: { type: 'json' } },
+          total: { type: 'integer' },
+          truncated: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: renderDiagnostics(value) }],
+    },
+    async execute(args, _exec) {
+      const status = bridgeLive(deps);
+      if (status.live !== true) return unavailable(status.reason);
+      const cached = deps.cache().get();
+      const projected = projectDiagnostics(cached.diagnostics, args);
+      return {
+        available: true,
+        diagnostics: projected.diagnostics,
+        total: projected.total,
+        truncated: projected.truncated ? `只返回前 ${projected.diagnostics.length} 条(共 ${projected.total})` : '',
+      };
+    },
+    presentCall: (args) => ({
+      card: 'generic',
+      title: args.file ? `读取诊断:${args.file}` : '读取诊断',
+      kind: 'read',
+      ...(args.file ? { locations: [{ path: args.file }] } : {}),
+    }),
+  });
+
+  const disposers = [tools.register(contextTool), tools.register(diagnosticsTool)];
+  return () => {
+    for (const dispose of disposers) {
+      try {
+        dispose();
+      } catch {
+        // 双保险:注册本身也挂在 fiber 上
+      }
+    }
+  };
+}
+
+/**
+ * 系统提示词段落里"桥是否可用"的同步探针。
+ *
+ * `PromptSection.text` 不支持 async 也不支持 `when` 谓词,所以只能用一个同步可读的开关:
+ * 由 `lib/index.js` 在桥状态变化时维护(`setPromptLiveProbe(() => bridgeLive)`),
+ * 段落文本按它返回整段或空串(空串会被 DSH 整个丢弃 —— 模型看不到"有一个用不了的工具")。
+ */
+let promptLiveProbe = () => false;
+
+/** 注入同步探针(桥 running 时为 true)。 */
+export function setPromptLiveProbe(probe) {
+  promptLiveProbe = typeof probe === 'function' ? probe : () => false;
+}
+
+function bridgeIsLive() {
+  try {
+    return promptLiveProbe() === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 注册系统提示词段落,返回 disposer(或 null = 该 DSH 没有 systemPrompt 服务)。
+ * @param {object} ctx cordis 上下文
+ */
+export function registerEditorPrompt(ctx) {
+  const systemPrompt = ctx?.systemPrompt ?? (typeof ctx?.get === 'function' ? ctx.get('systemPrompt') : undefined);
+  if (systemPrompt === undefined || systemPrompt === null || typeof systemPrompt.section !== 'function') return null;
+  return systemPrompt.section({
+    name: PROMPT_SECTION,
+    order: PROMPT_ORDER,
+    text: () => (bridgeIsLive() ? PROMPT_TEXT : ''),
+  });
+}