fde2e-bu 0.0.0 → 1.3.0

package/src/mcp/schema.mjs

@@ -0,0 +1,175 @@
+// MCP 工具面编译（task 3.1）——schema 源＝契约层 commands.json 快照
+// （cli/src/mcp/commands-snapshot.json，只读拷贝自 plugins/contracts/browser-bridge/
+// commands.json；对表测试保证与真源一致，真源再生成命令见该文件 $doc）。
+//
+// 工具面＝调研 C 节裁决的混合粒度：6 个意图级（open/click/fill/read/screenshot/
+// cmd 透传）＋窗口三件套；bu_cmd 透传枚举＝云端可执行 21 条（CLOUD_EXECUTABLE_
+// COMMANDS；7 条保留命令经 omni 云端派发必被拒 E_INVALID_COMMAND——conformance C7，
+// 故不进枚举也不暴露）。inputSchema 的 required/optional 逐字来自快照；字段类型
+// 是 CLI 侧展示提示（快照只给字段名，类型面以 packages/protocol/src/validate.js 为准）。
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** BU 插件保留命令（真源＝packages/protocol/src/constants.js RESERVED_COMMANDS；
+ * 此处内嵌副本供独立分发，对表测试校准）。经云端（omni /api/cmd）派发会被拒。 */
+export const RESERVED_COMMANDS = [
+  'windowFocus',
+  'windowBounds',
+  'windowUpdateMeta',
+  'mailboxSend',
+  'mailboxPoll',
+  'mailboxClear',
+  'mailboxMarkRead',
+];
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** 契约快照（单例缓存）。 */
+export function loadContract() {
+  return JSON.parse(readFileSync(join(here, 'commands-snapshot.json'), 'utf8'));
+}
+
+/** cmd → 工具意图映射（window 三件套直连契约命令；cmd＝自由透传）。 */
+const TOOL_DEFS = [
+  { tool: 'bu_open', cmd: 'open' },
+  { tool: 'bu_click', cmd: 'click' },
+  { tool: 'bu_fill', cmd: 'fill' },
+  { tool: 'bu_read', cmd: 'read' },
+  { tool: 'bu_screenshot', cmd: 'screenshot' },
+  { tool: 'bu_window_list', cmd: 'windowList' },
+  { tool: 'bu_window_create', cmd: 'windowCreate' },
+  { tool: 'bu_window_close', cmd: 'windowClose' },
+];
+
+/** 字段类型提示（契约快照只有字段名；按协议 validate.js 语义标注展示类型）。 */
+const FIELD_TYPES = {
+  url: { type: 'string' }, selector: { type: 'string' }, target: { type: 'string' },
+  waitSelector: { type: 'string' }, text: { type: 'string' }, inputMode: { type: 'string' },
+  timeoutMs: { type: 'number' }, targetTabId: { type: 'number' }, targetWindowId: { type: 'number' },
+  quality: { type: 'number' }, maxWidth: { type: 'number' },
+  name: { type: 'string' }, width: { type: 'number' }, height: { type: 'number' },
+  status: { type: 'string' }, taskId: { type: 'string' }, sessionId: { type: 'string' },
+  friendlyName: { type: 'string' }, windowId: { type: 'string' },
+};
+
+/**
+ * 编译 MCP tools 数组（tools/list 的 tools 字段）。
+ * @param {object} [contract] 缺省载入快照
+ */
+export function buildTools(contract = loadContract()) {
+  const byCmd = new Map(contract.commands.map((c) => [c.cmd, c]));
+  const tools = [];
+  for (const def of TOOL_DEFS) {
+    const c = byCmd.get(def.cmd);
+    if (!c) throw new Error(`契约快照缺命令 ${def.cmd}`);
+    const fields = [...c.required, ...c.optional];
+    const properties = {};
+    for (const f of fields) {
+      properties[f] = FIELD_TYPES[f] ?? { type: 'string' };
+    }
+    tools.push({
+      name: def.tool,
+      description: `（契约命令 ${c.cmd}）${c.summary}`,
+      inputSchema: {
+        type: 'object',
+        properties,
+        ...(c.required.length > 0 ? { required: [...c.required] } : {}),
+        additionalProperties: false,
+      },
+    });
+  }
+  // bu_cmd：任意契约命令透传（枚举＝云端可执行 21＝全集 28 − 保留 7）
+  const cloudExecutable = contract.commands.map((c) => c.cmd).filter((c) => !RESERVED_COMMANDS.includes(c));
+  tools.push({
+    name: 'bu_cmd',
+    description: '（透传）一条完整 om-adapter/0.7 命令直达云端可执行白名单（21 条）；保留命令（窗口聚焦/尺寸/元数据与留言板族）经云端派发会被拒，不在此面。命令语义见契约层 commands.json。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cmd: { type: 'string', enum: cloudExecutable, description: '契约命令名（cloud-executable 白名单）' },
+      },
+      required: ['cmd'],
+      additionalProperties: true, // 其余字段＝命令参数（字段面见契约 required/optional）
+    },
+  });
+  return tools;
+}
+
+/** 工具调用 → 协议命令对象（意图工具参数即命令字段；bu_cmd 参数即命令本体）。 */
+export function commandForCall(toolName, args) {
+  if (toolName === 'bu_cmd') {
+    if (!args || typeof args !== 'object' || typeof args.cmd !== 'string') {
+      throw new Error('bu_cmd 参数须为含 cmd 字段的对象');
+    }
+    return { ...args };
+  }
+  const def = TOOL_DEFS.find((d) => d.tool === toolName);
+  if (!def) return null;
+  const command = { cmd: def.cmd };
+  for (const [k, v] of Object.entries(args ?? {})) {
+    if (v !== undefined && v !== null) command[k] = v;
+  }
+  return command;
+}
+
+// ---------- r1 P1-3：tools/call 前置输入校验（手写零依赖 JSON-Schema 子集） ----------
+// MCP 规范 MUST：server 必须按 inputSchema 校验。此处覆盖 required / 未知属性
+// （additionalProperties:false）/ enum（bu_cmd.cmd ∈ 云端可执行 21 白名单）/
+// 宽松基本类型（FIELD_TYPES 面：string/number/boolean/array）。校验不过 →
+// -32602，不派发（不发 POST）。
+
+/** 基本类型判定（宽松：schema 未标类型或非基本类型名即放行）。 */
+function matchesType(value, type) {
+  switch (type) {
+    case 'string': return typeof value === 'string';
+    case 'number': return typeof value === 'number' && Number.isFinite(value);
+    case 'integer': return typeof value === 'number' && Number.isInteger(value);
+    case 'boolean': return typeof value === 'boolean';
+    case 'array': return Array.isArray(value);
+    case 'object': return typeof value === 'object' && value !== null && !Array.isArray(value);
+    default: return true; // 未知类型名＝宽松放行（契约字段面只标基本类型）
+  }
+}
+
+const typeName = (v) => (Array.isArray(v) ? 'array' : v === null ? 'null' : typeof v);
+
+/**
+ * 校验工具输入参数。
+ * @param {string} toolName
+ * @param {unknown} args tools/call 的 params.arguments
+ * @param {object[]} [tools] 缺省 buildTools()
+ * @returns {{ ok: true } | { ok: false, message: string }} 失败信息可直接入 -32602
+ */
+export function validateToolInput(toolName, args, tools = buildTools()) {
+  const tool = tools.find((t) => t.name === toolName);
+  if (!tool) return { ok: false, message: `未知工具 ${toolName}（可用：${tools.map((t) => t.name).join('、')}）` };
+  const schema = tool.inputSchema;
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return { ok: false, message: 'arguments 须为对象' };
+  }
+  const errors = [];
+  for (const req of schema.required ?? []) {
+    if (!(req in args) || args[req] === undefined || args[req] === null) {
+      errors.push(`缺必填字段 ${req}`);
+    }
+  }
+  const props = schema.properties ?? {};
+  for (const [key, value] of Object.entries(args)) {
+    const prop = props[key];
+    if (!prop) {
+      if (schema.additionalProperties === false) errors.push(`未知属性 ${key}（${toolName} 只接受：${Object.keys(props).join('、')}）`);
+      continue; // bu_cmd（additionalProperties:true）：其余字段＝命令参数，透传
+    }
+    if (value === undefined || value === null) continue; // null 占位＝按缺省剔除（commandForCall 同语义）
+    if (prop.type && !matchesType(value, prop.type)) {
+      errors.push(`字段 ${key} 期望 ${prop.type}，实得 ${typeName(value)}`);
+    }
+    if (prop.enum && !prop.enum.includes(value)) {
+      errors.push(`字段 ${key} 取值 ${JSON.stringify(value)} 不在枚举白名单（${prop.enum.length} 项）`);
+    }
+  }
+  return errors.length > 0 ? { ok: false, message: errors.join('；') } : { ok: true };
+}
+
+export const TOOL_NAMES = [...TOOL_DEFS.map((d) => d.tool), 'bu_cmd'];

package/src/mcp/serve.mjs

@@ -0,0 +1,203 @@
+// fde2e-bu mcp serve —— stdio MCP server（task 3.1/3.4）。
+// 手写最小 JSON-RPC 2.0 实现（MCP 规范 2025-06-18，不引 MCP SDK——零依赖原则，
+// server 侧必要面只有四个方法）：
+//   请求：initialize / tools/list / tools/call / ping
+//   通知：notifications/initialized / notifications/cancelled（静默忽略）
+//   错误码（JSON-RPC 2.0 标准 + MCP 约定）：
+//     -32700 parse error（id:null）；-32600 invalid request（含批量数组——
+//       2025-06-18 已移除 JSON-RPC batching，收到数组即本码）；
+//     -32601 method not found（请求未知方法；未知通知静默）；
+//     -32602 invalid params（未知工具名/输入不过 inputSchema——r1 P1-3 前置校验，零派发）；
+//     -32002 server not initialized（initialize 之前收到其他请求；ping 除外——r1 P2）。
+// 纪律：stdout 只写 MCP 消息（每行一个 JSON 对象，UTF-8，\n 结尾）；一切日志走
+// stderr——stdio transport 下 stdout 被客户端解析，混入非协议文本即破坏通道。
+// stdin 关闭（客户端退出）→ 进程正常退出 0。
+
+import { createInterface } from 'node:readline';
+import { buildTools, commandForCall, validateToolInput } from './schema.mjs';
+import { bridgeEnv, dispatchCommand } from './bridge.mjs';
+import { pairingDefaultProfileId } from '../nm/host.mjs';
+import { resolveConfigDir } from '../configdir.mjs';
+import pkg from '../../package.json' with { type: 'json' }; // r1 P2：serverInfo 版本真值（package.json 单源）
+
+const PROTOCOL_VERSION = '2025-06-18';
+const SERVER_NAME = 'fde2e-bu';
+
+function rpcResult(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+export function rpcError(id, code, message, data) {
+  const err = { code, message };
+  if (data !== undefined) err.data = data;
+  return { jsonrpc: '2.0', id, result: undefined, error: err };
+}
+
+/**
+ * 单条入站消息处理（纯函数核心，便于测试）。
+ * @param {unknown} msg 解析后的 JSON 值
+ * @param {{ initialized: boolean, version: string, env: object }} state
+ * @returns {{ responses: object[] }} 待写回的响应（通知＝空数组）
+ */
+export function handleMessage(msg, state) {
+  if (Array.isArray(msg)) {
+    return { responses: [rpcError(null, -32600, 'Invalid Request: JSON-RPC batching 已在 MCP 2025-06-18 移除')] };
+  }
+  if (typeof msg !== 'object' || msg === null || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+    return { responses: [rpcError(null, -32600, 'Invalid Request: 缺 jsonrpc:"2.0" 或 method 字段')] };
+  }
+  const isRequest = 'id' in msg && msg.id !== undefined; // 通知无 id
+  const { method } = msg;
+  const params = msg.params ?? {};
+
+  // r1 P2：ping 无状态、initialize 前即可应答（{} result）——MCP 规范 ping 不依赖会话
+  if (method === 'ping') {
+    return isRequest ? { responses: [rpcResult(msg.id, {})] } : { responses: [] };
+  }
+
+  if (method === 'initialize') {
+    // r1 P2：initialize 必须是 request（规范）；通知形态不置位 initialized——通知不产生副作用
+    if (!isRequest) return { responses: [] };
+    state.initialized = true;
+    return {
+      responses: [
+        rpcResult(msg.id, {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: SERVER_NAME, version: state.version, title: 'FDE2E Browser Use' },
+          instructions: 'FDE2E Browser Use 桥：意图级工具（bu_open/bu_click/bu_fill/bu_read/bu_screenshot）+ 窗口三件套 + bu_cmd 透传；命令经客户本机浏览器插件执行，登录态不出本机。',
+        }),
+      ],
+    };
+  }
+
+  if (!state.initialized) {
+    return isRequest
+      ? { responses: [rpcError(msg.id, -32002, 'Server not initialized: 先发 initialize 请求')] }
+      : { responses: [] };
+  }
+
+  switch (method) {
+    case 'notifications/initialized':
+    case 'notifications/cancelled':
+      return { responses: [] };
+    case 'tools/list':
+      if (!isRequest) return { responses: [] };
+      return { responses: [rpcResult(msg.id, { tools: buildTools() })] };
+    case 'tools/call': {
+      if (!isRequest) return { responses: [] };
+      const name = params.name;
+      const args = params.arguments ?? {};
+      // r1 P1-3：inputSchema 前置校验（required/未知属性/enum/基本类型）——
+      // 不合法即 -32602 且不派发（零 POST），失败不外溢到桥服务
+      const check = validateToolInput(name, args);
+      if (!check.ok) {
+        return { responses: [rpcError(msg.id, -32602, `Invalid params: ${check.message}`)] };
+      }
+      let command;
+      try {
+        command = commandForCall(name, args);
+      } catch (err) {
+        return { responses: [rpcError(msg.id, -32602, `Invalid params: ${err.message}`)] };
+      }
+      if (command === null) {
+        return { responses: [rpcError(msg.id, -32602, `Invalid params: 未知工具 ${name}`)] };
+      }
+      // 派发（异步由 caller await；此处返回 promise 形状由 handleAsyncMessage 承接）
+      return { responses: [], deferred: { id: msg.id, command } };
+    }
+    default:
+      return isRequest
+        ? { responses: [rpcError(msg.id, -32601, `Method not found: ${method}`)] }
+        : { responses: [] }; // 未知通知按 JSON-RPC 惯例静默
+  }
+}
+
+/** tools/call 的异步执行（HTTP 派发 + MCP content 包装）。 */
+async function executeToolCall(id, command, env, write) {
+  if (!env.profileId) {
+    write(rpcResult(id, {
+      content: [{ type: 'text', text: JSON.stringify({ ok: false, code: 'E_AUTH', message: '未配置 BU_BRIDGE_PROFILE_ID——tools/call 需要 profileId（fde2e-bu mcp add --profile-id <id> 可写入客户端配置 env）', retryable: false }) }],
+      isError: true,
+    }));
+    return;
+  }
+  const envelope = await dispatchCommand(env, command);
+  write(rpcResult(id, {
+    content: [{ type: 'text', text: JSON.stringify(envelope) }],
+    isError: envelope.ok !== true,
+  }));
+}
+
+/**
+ * 单条消息的完整异步处理（A4：stdio 与 http 两传输共用）——同步应答 + tools/call
+ * 延迟执行合并为最终应答数组（单条消息至多产出一条应答；通知/未知通知＝空数组）。
+ * @param {unknown} msg
+ * @param {{ initialized: boolean, version: string, env: object }} state
+ * @param {object} env bridgeEnv 产物（execute 派发用）
+ * @returns {Promise<object[]>} 待写回的响应
+ */
+export async function handleAsyncMessage(msg, state, env) {
+  const out = handleMessage(msg, state);
+  if (out.deferred) {
+    const { id, command } = out.deferred;
+    try {
+      await executeToolCall(id, command, env, (r) => { out.responses.push(r); });
+    } catch (err) {
+      out.responses.push(rpcError(id, -32603, `Internal error: ${err?.message ?? err}`));
+    }
+  }
+  return out.responses;
+}
+
+/** serve 主入口（stdio）。r1 P2：version 缺省＝package.json 真值（import 断言单源）。 */
+export async function runServe({ schemaOnly = false, version = pkg.version, env = bridgeEnv(), stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (schemaOnly) {
+    stdout.write(`${JSON.stringify({ server: SERVER_NAME, protocolVersion: PROTOCOL_VERSION, tools: buildTools() }, null, 2)}\n`);
+    return 0;
+  }
+  // P1-1：BU_BRIDGE_PROFILE_ID 未设置时回退本机配对（readPairing→defaultProfileId），
+  // stderr 一行说明来源。回退发生在 run* 层——bridgeEnv 纯函数语义不变（缺省空串）。
+  let effectiveEnv = env;
+  if (!env.profileId) {
+    const fallback = pairingDefaultProfileId(resolveConfigDir());
+    if (fallback) {
+      effectiveEnv = { ...env, profileId: fallback };
+      stderr.write(`fde2e-bu: BU_BRIDGE_PROFILE_ID 未设置——profileId 取自本机配对（fde2e-bu bind）：${fallback}\n`);
+    }
+  }
+  const state = { initialized: false, version, env: effectiveEnv };
+  const write = (msg) => stdout.write(`${JSON.stringify(msg)}\n`);
+
+  await new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    let settled = false;
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      rl.close();
+      resolve(code);
+    };
+    rl.on('line', async (line) => {
+      const text = line.trim();
+      if (text === '') return;
+      let msg;
+      try {
+        msg = JSON.parse(text);
+      } catch {
+        write(rpcError(null, -32700, 'Parse error: 行不是合法 JSON'));
+        return;
+      }
+      try {
+        // A4：与 http 传输共用 handleAsyncMessage（同步应答＋tools/call 延迟执行）；
+        // 派发用 state.env（含 P1-1 的 pairing 回退结果——不得用外层原始 env）
+        for (const r of await handleAsyncMessage(msg, state, state.env)) write(r);
+      } catch (err) {
+        write(rpcError(msg && !Array.isArray(msg) && 'id' in msg ? msg.id : null, -32603, `Internal error: ${err?.message ?? err}`));
+      }
+    });
+    rl.on('close', () => finish(0)); // 客户端断开 → 干净退出
+    process.on('SIGTERM', () => finish(0));
+    process.on('SIGINT', () => finish(0));
+  });
+  return 0;
+}

package/src/misc.mjs

@@ -0,0 +1,229 @@
+// status / doctor（tasks 1.2 / 1.3；C2 P2-7；A5＝pairing 消费）。
+// （update 组自 bu-online-selfupdate A3 起改走 src/nm/update.mjs 的 cmdSelfUpdate。）
+import { existsSync, readdirSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { bridgeEnv, fetchHealthz, DEFAULT_SERVER } from './mcp/bridge.mjs';
+import { allTargets, readTargetEntry } from './mcp/config.mjs';
+import { findSkillsWorkspace } from './skills/skills.mjs';
+import { resolveConfigDir } from './configdir.mjs';
+import { readPairing, defaultProfileId } from './nm/host.mjs';
+import { manifestTargets, readManifest, hostScriptExecutable } from './nm/bind.mjs';
+
+// ---------- status（task 1.2 + C2）：/healthz 探活＋绑定配置面＋六落点注册清单 ----------
+
+/** profileId 脱敏：与 mcp list 同口径（***尾4；短值全遮）。 */
+function maskProfileId(id) {
+  if (!id) return null;
+  const v = String(id);
+  return v.length > 4 ? `***${v.slice(-4)}` : '***';
+}
+
+/** 从落点条目抽 profileId（JSON 条目取 env；codex TOML 块解析经验行）。 */
+function entryProfileId(entry) {
+  if (!entry) return null;
+  if (typeof entry === 'string') {
+    // codex TOML 块：env 为行内表（env = { BU_BRIDGE_PROFILE_ID = "p1" }），全文匹配
+    const m = /BU_BRIDGE_PROFILE_ID\s*=\s*"([^"]*)"/.exec(entry);
+    return m ? m[1] : null;
+  }
+  return entry?.env?.BU_BRIDGE_PROFILE_ID ?? null;
+}
+
+/** 六落点注册清单（C2：client/scope/路径/是否注册/脱敏 profileId）。 */
+export function registrationRows(home = homedir(), dir = process.cwd()) {
+  return allTargets(home, dir).map((t) => {
+    const entry = readTargetEntry(t);
+    return {
+      client: t.client,
+      scope: t.kind,
+      path: t.path,
+      registered: Boolean(entry),
+      profileId: maskProfileId(entryProfileId(entry)),
+    };
+  });
+}
+
+export async function cmdStatus({ server, home, dir, json, configDir } = {}) {
+  const env = bridgeEnv();
+  const url = server ?? env.server;
+  const health = await fetchHealthz(url);
+  // A5：pairing 消费——配置根可注入（--config-dir > BU_CONFIG_DIR > 缺省）
+  const cfgDir = resolveConfigDir({ ...(configDir ? { configDirFlag: configDir } : {}) });
+  const pairing = readPairing(cfgDir);
+  const config = {
+    server: url,
+    profileId: env.profileId || null,
+    internalToken: env.internalToken ? '(已配置)' : null,
+    boundProfileId: env.boundProfileId ? '(已配置)' : null,
+  };
+  const registrations = registrationRows(home ?? homedir(), dir ?? process.cwd());
+  if (json) {
+    console.log(JSON.stringify({
+      health: { ok: health.ok, status: health.status, body: health.body },
+      pairing: pairing
+        ? { count: pairing.bindings.length, defaultProfileId: defaultProfileId(pairing), bindings: pairing.bindings }
+        : null,
+      config,
+      registrations,
+    }, null, 2));
+  } else if (health.ok) {
+    console.log(`桥服务：健康（${url} → HTTP ${health.status}）`);
+    if (health.body) console.log(`  ${JSON.stringify(health.body)}`);
+  } else if (health.status > 0) {
+    console.error(`桥服务：异常（${url} → HTTP ${health.status}）`);
+  } else {
+    // 离线降级：如实提示，不堆栈不惊吓
+    console.error(`桥服务：不可达（${url}）——离线降级：`);
+    console.error('  1. 确认 omni 服务端已启动（缺省 http://127.0.0.1:8788）');
+    console.error('  2. BU_BRIDGE_SERVER 指向正确派发入口时重试 fde2e-bu status');
+    console.error('  3. skills 管理不受影响（纯本地文件面）；mcp tools/call 需要桥服务在线');
+  }
+  if (!json) {
+    // A5：顶部配对面（health 之后、绑定面之前）——已配对执行器与缺省 profileId
+    if (pairing) {
+      console.log(`已配对执行器：${pairing.bindings.length} 条（缺省 profileId=${defaultProfileId(pairing)}，优先 master）`);
+    } else {
+      console.log('已配对执行器：未配对（fde2e-bu bind install 后在扩展 options 点「CLI 配对」）');
+    }
+    console.log(`绑定面：profileId=${config.profileId ?? '(未配置——tools/call 需要)'} internalToken=${config.internalToken ?? '(未配置)'} boundProfileId=${config.boundProfileId ?? '(未配置)'}`);
+    console.log('注册清单（六落点）：');
+    for (const r of registrations) {
+      console.log(`  ${r.registered ? '✓' : '✗'} ${r.client.padEnd(6)} ${r.scope.padEnd(7)} ${r.path}${r.profileId ? `  profileId=${r.profileId}` : ''}`);
+    }
+  }
+  return health.ok ? 0 : 1;
+}
+
+// ---------- doctor（task 1.3）：node 版本/配置路径/环境变量/zip 存在性自检 ----------
+
+/** 从 dir 逐级向上找 dist-pack/*.zip（扩展安装包）。 */
+function findExtensionZip(dir) {
+  let d = resolve(dir);
+  for (;;) {
+    const packDir = join(d, 'dist-pack');
+    if (existsSync(packDir)) {
+      const zips = readdirSync(packDir).filter((f) => f.endsWith('.zip'));
+      if (zips.length > 0) return join(packDir, zips[0]);
+    }
+    const parent = dirname(d);
+    if (parent === d) return null;
+    d = parent;
+  }
+}
+
+/**
+ * 自检项（C2：/healthz 网络探测；A5：NM manifest/pairing 两检查项）。
+ * @param {{ nodeVersion?: string, home?: string, cwd?: string, env?: object,
+ *           fetchImpl?: Function, healthzTimeoutMs?: number,
+ *           configDir?: string, manifestsDir?: string }} [opts]
+ *   healthzTimeoutMs 仅供测试注入（缺省 4s 预算）；
+ *   configDir/manifestsDir 注入 pairing/NM manifest 落点（缺省 resolveConfigDir()/
+ *   浏览器缺省目录——不碰真实家目录的测试一律显式注入）。
+ * @returns {Promise<{ checks: Array<{name:string, level:'ok'|'warn'|'fail', detail:string}> }>}
+ */
+export async function doctorChecks({
+  nodeVersion = process.version,
+  home = homedir(),
+  cwd = process.cwd(),
+  env = process.env,
+  fetchImpl,
+  healthzTimeoutMs = 4000,
+  configDir,
+  manifestsDir,
+} = {}) {
+  const checks = [];
+  const major = Number(/v(\d+)/.exec(nodeVersion)?.[1] ?? 0);
+  checks.push(major >= 22
+    ? { name: 'node 版本', level: 'ok', detail: `${nodeVersion}（≥22）` }
+    : { name: 'node 版本', level: 'fail', detail: `${nodeVersion} < 22（engines 要求 node>=22）` });
+
+  const buEnv = bridgeEnv(env);
+  checks.push(buEnv.profileId
+    ? { name: 'BU_BRIDGE_PROFILE_ID', level: 'ok', detail: '已配置（tools/call 可用）' }
+    : { name: 'BU_BRIDGE_PROFILE_ID', level: 'warn', detail: '未配置——mcp tools/call 与 status 绑定面需要 profileId' });
+  checks.push({ name: 'BU_BRIDGE_SERVER', level: 'ok', detail: buEnv.server === DEFAULT_SERVER ? `${DEFAULT_SERVER}（缺省）` : buEnv.server });
+
+  // C2：网络探测（4s 预算）——离线只 warn，不参与退出码
+  const startedAt = Date.now();
+  const health = await fetchHealthz(buEnv.server, { timeoutMs: healthzTimeoutMs, fetchImpl });
+  const elapsed = Date.now() - startedAt;
+  checks.push(health.ok
+    ? { name: '桥服务 /healthz', level: 'ok', detail: `可达：${health.url}（HTTP ${health.status}，${elapsed}ms）` }
+    : {
+      name: '桥服务 /healthz',
+      level: 'warn',
+      detail: health.status > 0
+        ? `HTTP ${health.status}（${elapsed}ms）——服务在线但回执异常，tools/call 可能不可用`
+        : `不可达：${health.url}（${elapsed}ms）——离线是合法状态（status 会降级提示，不判失败）`,
+    });
+
+  checks.push(buEnv.internalToken
+    ? { name: 'BU_INTERNAL_TOKEN', level: 'ok', detail: '已配置（x-omni-internal，仅回环来源生效）' }
+    : { name: 'BU_INTERNAL_TOKEN', level: 'warn', detail: '未配置——omni 开启内部令牌面时需要' });
+
+  for (const p of [join(home, '.claude.json'), join(home, '.codex', 'config.toml'), join(cwd, '.mcp.json'), join(cwd, '.gemini', 'settings.json')]) {
+    checks.push({ name: '配置路径', level: existsSync(p) ? 'ok' : 'warn', detail: `${existsSync(p) ? '存在' : '不存在'}：${p}` });
+  }
+  const zip = findExtensionZip(cwd);
+  checks.push(zip
+    ? { name: '扩展 zip', level: 'ok', detail: `存在：${zip}` }
+    : { name: '扩展 zip', level: 'warn', detail: `自 ${cwd} 向上未找到 dist-pack/*.zip（浏览器插件安装包）` });
+  const { workspace } = findSkillsWorkspace(cwd);
+  checks.push(workspace
+    ? { name: '技能工作区', level: 'ok', detail: `找到：${workspace}` }
+    : { name: '技能工作区', level: 'warn', detail: `自 ${cwd} 向上无 .agents/skills / .claude/skills（skills add 会创建）` });
+
+  // A5：NM manifest 与 pairing 两检查项（未装/未配对＝warn 合法状态，不判 fail）。
+  // P2-9：manifest 在场还不够——其 path 指向的 host 脚本必须存在且可执行，
+  // 否则 manifest 是「空挂」（点配对必断开），warn 并给重装指引。
+  const nmTargets = manifestTargets({ browser: 'both', manifestsDir, home });
+  const nmFound = nmTargets.filter((t) => existsSync(t.path));
+  if (nmFound.length === 0) {
+    checks.push({ name: 'NM manifest', level: 'warn', detail: `未安装（fde2e-bu bind install；查找：${nmTargets.map((t) => t.path).join('；')}）` });
+  } else {
+    const missingScripts = nmFound.filter((t) => {
+      const m = readManifest(t.path);
+      return !m || typeof m.path !== 'string' || !hostScriptExecutable(m.path);
+    });
+    checks.push(missingScripts.length === 0
+      ? { name: 'NM manifest', level: 'ok', detail: `已安装：${nmFound.map((t) => t.path).join('；')}` }
+      : {
+        name: 'NM manifest',
+        level: 'warn',
+        detail: `已安装但 host 脚本缺失/不可执行（重装：fde2e-bu bind install）：${missingScripts.map((t) => {
+          const m = readManifest(t.path);
+          return `${t.path} → ${m?.path ?? '(manifest 坏，无 path)'}`;
+        }).join('；')}`,
+      });
+  }
+  const cfgDir = resolveConfigDir({ ...(configDir ? { configDirFlag: configDir } : {}) });
+  const pairing = readPairing(cfgDir);
+  checks.push(pairing
+    ? { name: 'pairing 配对', level: 'ok', detail: `${pairing.bindings.length} 条（缺省 profileId=${defaultProfileId(pairing)}，优先 master）：${cfgDir}` }
+    : { name: 'pairing 配对', level: 'warn', detail: `未配对（${cfgDir}——bind install 后在扩展 options 点「CLI 配对」）` });
+  return { checks };
+}
+
+export async function cmdDoctor({ home, dir, json, fetchImpl, healthzTimeoutMs, configDir, manifestsDir } = {}) {
+  const { checks } = await doctorChecks({
+    home: home ?? homedir(),
+    cwd: dir ?? process.cwd(),
+    ...(fetchImpl ? { fetchImpl } : {}),
+    ...(healthzTimeoutMs ? { healthzTimeoutMs } : {}),
+    ...(configDir ? { configDir } : {}),
+    ...(manifestsDir ? { manifestsDir } : {}),
+  });
+  const counts = { ok: 0, warn: 0, fail: 0 };
+  for (const c of checks) counts[c.level]++;
+  if (json) {
+    console.log(JSON.stringify({ checks, counts }, null, 2));
+  } else {
+    for (const c of checks) {
+      const tag = { ok: '✓', warn: '⚠', fail: '✗' }[c.level];
+      console.log(`${tag} ${c.name}：${c.detail}`);
+    }
+    console.log(`自检：${counts.ok} 通过 / ${counts.warn} 提示 / ${counts.fail} 失败`);
+  }
+  return counts.fail > 0 ? 1 : 0;
+}