fde2e-bu 0.0.0 → 1.2.0

package/src/nm/bind.mjs

@@ -0,0 +1,229 @@
+// bind install/status/remove（change bu-bind-http-publish A3）——Native Messaging
+// host 落盘物管理。设计要点（design §1.2）：
+//   - NM 的 manifest path 必须是单个可执行文件（不能内嵌参数）→ 生成包装脚本
+//     <configDir>/nm-host.sh（0755）：exec env BU_CONFIG_DIR='<configDir>' '<node>'
+//     '<cli/bin.js 绝对路径>' __nm-host（路径 POSIX 单引号转义——P2-2；env 注入使
+//     配置根对真实 host 生效——P2-3）
+//   - manifest com.fde2e.bu.json 写浏览器 NM 目录（macOS：Chrome/Chromium），字段：
+//     {name, description, path:<nm-host.sh 绝对路径>, type:'stdio',
+//      allowed_origins:['chrome-extension://<扩展稳定 ID>/']}
+//     扩展稳定 ID＝meojillndgamkbfjijfehjaefolnfopn（manifest 固定 key 派生——
+//     B1 落地；本 CLI 只锚定该常量）。
+//   - --manifests-dir 显式重定向 manifest 落点（测试沙箱）；--config-dir 重定向配置根
+//     （等价 BU_CONFIG_DIR）。幂等：install 覆盖写，remove 未装跳过。
+import { existsSync, readFileSync, statSync, unlinkSync, chmodSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { atomicWrite } from '../mcp/config.mjs';
+import { UsageError } from '../args.mjs';
+import { NM_HOST_NAME, readPairing, defaultProfileId, pairingPath } from './host.mjs';
+
+/** 扩展稳定 ID（manifest 固定 key 派生）——allowed_origins 锚定点。 */
+export const EXTENSION_ID = 'meojillndgamkbfjijfehjaefolnfopn';
+export const ALLOWED_ORIGIN = `chrome-extension://${EXTENSION_ID}/`;
+
+/** P1-5（CI 实证修正）：bind 支持 macOS 与 Linux（两者 NM 清单都是文件落盘，
+ *  仅目录不同）；Windows 需要 HKCU 注册表写入，暂如实拒绝——不静默错装。 */
+export function assertBindPlatform(platform = process.platform) {
+  if (platform !== 'darwin' && platform !== 'linux') {
+    throw new UsageError('bind 目前支持 macOS 与 Linux（Windows 的 Native Messaging 需注册表写入，待后续版本）');
+  }
+}
+
+const MANIFEST_FILE = `${NM_HOST_NAME}.json`;
+const binPath = join(dirname(dirname(dirname(fileURLToPath(import.meta.url)))), 'bin.js'); // src/nm → cli/bin.js
+
+/** 浏览器 NM 目录（按 Chrome 规范路径；platform 可注入供测试）：
+ *  macOS：~/Library/Application Support/{Google Chrome,Chromium}/NativeMessagingHosts
+ *  Linux：~/.config/{google-chrome,chromium}/NativeMessagingHosts */
+export function browserManifestDirs(home = homedir(), platform = process.platform) {
+  if (platform === 'linux') {
+    const cfg = join(home, '.config');
+    return {
+      chrome: join(cfg, 'google-chrome', 'NativeMessagingHosts'),
+      chromium: join(cfg, 'chromium', 'NativeMessagingHosts'),
+    };
+  }
+  const appSupport = join(home, 'Library', 'Application Support');
+  return {
+    chrome: join(appSupport, 'Google', 'Chrome', 'NativeMessagingHosts'),
+    chromium: join(appSupport, 'Chromium', 'NativeMessagingHosts'),
+  };
+}
+
+/**
+ * manifest 落点集合：--browser 收窄（缺省 chrome；both=两处；重定向时两浏览器同文件
+ * 自动去重）；--manifests-dir 显式重定向（测试/沙箱——目录直接当 NM 目录用）。
+ * @returns {{ label:string, path:string }[]}
+ */
+export function manifestTargets({ browser = 'chrome', manifestsDir, home = homedir() }) {
+  const browsers = browser === 'both' ? ['chrome', 'chromium'] : [browser];
+  const dirs = browserManifestDirs(home);
+  const targets = browsers.map((b) => ({
+    // 重定向落点的 label 如实标注（浏览器目录合一，不再区分 chrome/chromium）
+    label: manifestsDir ? 'manifests-dir' : b,
+    path: manifestsDir ? join(resolve(String(manifestsDir)), MANIFEST_FILE) : join(dirs[b], MANIFEST_FILE),
+  }));
+  const seen = new Set();
+  return targets.filter((t) => (seen.has(t.path) ? false : (seen.add(t.path), true)));
+}
+
+/** nm-host.sh 路径（配置根下）。 */
+export function nmHostScriptPath(configDir) {
+  return join(configDir, 'nm-host.sh');
+}
+
+/**
+ * 原子写可执行文件：atomicWrite（0600 temp+rename）→ chmod 0755。
+ * （atomicWrite 固定收紧 0600，对脚本必须再放开执行位——NM 只认可执行文件。）
+ */
+function writeExecutable(path, text) {
+  atomicWrite(path, text);
+  chmodSync(path, 0o755);
+}
+
+/**
+ * POSIX 单引号字面量（P2-2）：把任意字面量安全包进 sh 单引号——单引号内除单引号
+ * 本身外全部字面（空格/`$`/反引号/通配符一律不展开）；嵌单引号用 `'\''` 断开重开。
+ */
+export function shQuote(s) {
+  return `'${String(s).replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * 生成 nm-host.sh 内容（单可执行文件约束：exec 换进程，不带内嵌参数）。
+ * P2-2/P2-3：路径一律 shQuote 单引号转义（configDir/execPath/binPath 含空格、
+ * `$`、单引号均字面传递）；BU_CONFIG_DIR 经 `exec env` 注入——真实 host 进程的
+ * 落盘点由此与 manifest 的配置根一致（--config-dir 语义对真实 host 生效）。
+ */
+export function buildNmHostScript(configDir) {
+  return `#!/bin/sh\n# fde2e-bu Native Messaging host 包装（bind install 生成；可重复生成覆盖）\nexec env BU_CONFIG_DIR=${shQuote(resolve(String(configDir)))} ${shQuote(process.execPath)} ${shQuote(resolve(binPath))} __nm-host\n`;
+}
+
+/**
+ * host 脚本在位校验（P2-9）：路径存在、是普通文件、带任一执行位。
+ * manifest.path 空挂（脚本被删/移动/失执行位）时由 status/doctor warn。
+ */
+export function hostScriptExecutable(path) {
+  try {
+    return typeof path === 'string' && path !== '' && existsSync(path)
+      && statSync(path).isFile() && (statSync(path).mode & 0o111) !== 0;
+  } catch {
+    return false;
+  }
+}
+
+/** 生成 host manifest 对象（字段逐一对表 Chrome NM 规范）。 */
+export function buildManifest({ scriptPath }) {
+  return {
+    name: NM_HOST_NAME,
+    description: 'FDE2E Browser Use CLI 配对 host（扩展↔CLI 一次性配对；https://fde2e.com）',
+    path: resolve(String(scriptPath)),
+    type: 'stdio',
+    allowed_origins: [ALLOWED_ORIGIN],
+  };
+}
+
+/** 读 manifest：不存在/坏 JSON → null。 */
+export function readManifest(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const data = JSON.parse(readFileSync(path, 'utf8'));
+    return data && typeof data === 'object' ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------- 子命令实现（打印面 + 落盘面；返回 exit code） ----------
+
+/**
+ * bind install：写 nm-host.sh（0755）+ 各浏览器 manifest；幂等覆盖；打印下一步指引。
+ * @returns {number} exit code（恒 0——IO 失败抛异常由 bin.js 兜底 exit 1）
+ */
+export function cmdBindInstall({ browser = 'chrome', manifestsDir, configDir, home = homedir() } = {}) {
+  mkdirSync(configDir, { recursive: true });
+  const scriptPath = nmHostScriptPath(configDir);
+  writeExecutable(scriptPath, buildNmHostScript(configDir));
+  console.log(`已写入 host 包装脚本（0755）：${scriptPath}`);
+  for (const t of manifestTargets({ browser, manifestsDir, home })) {
+    atomicWrite(t.path, `${JSON.stringify(buildManifest({ scriptPath }), null, 2)}\n`);
+    console.log(`已写入 manifest（${t.label}）：${t.path}`);
+  }
+  console.log('下一步：打开 FDE2E 扩展 options → 绑定管理 → 点「CLI 配对」按钮完成配对。');
+  return 0;
+}
+
+/**
+ * bind status：manifest 各落点在否/内容摘要 + nm-host.sh 状态 + pairing 摘要。
+ * @returns {number} 0＝至少一处 manifest 在；1＝全缺（脚本可判）
+ */
+export function cmdBindStatus({ browser = 'both', manifestsDir, configDir, home = homedir() } = {}) {
+  let any = false;
+  for (const t of manifestTargets({ browser, manifestsDir, home })) {
+    const m = readManifest(t.path);
+    if (!m) {
+      console.log(`✗ manifest（${t.label}）：${t.path}（未安装）`);
+      continue;
+    }
+    any = true;
+    console.log(`✓ manifest（${t.label}）：${t.path}`);
+    console.log(`    name=${m.name} type=${m.type} path=${m.path}`);
+    console.log(`    allowed_origins=${(Array.isArray(m.allowed_origins) ? m.allowed_origins : []).join(',')}`);
+    // P2-9：manifest.path 的 host 脚本必须在位且可执行——空挂 manifest 点配对必断开
+    if (hostScriptExecutable(m.path)) {
+      console.log(`    ✓ host 脚本（可执行）：${m.path}`);
+    } else {
+      console.log(`    ⚠ host 脚本缺失/不可执行（重装：fde2e-bu bind install）：${m.path}`);
+    }
+  }
+  const scriptPath = nmHostScriptPath(configDir);
+  const scriptOk = hostScriptExecutable(scriptPath);
+  console.log(`${scriptOk ? '✓' : '✗'} host 包装脚本${scriptOk ? '（可执行）' : '（缺或不可执行）'}：${scriptPath}`);
+
+  const pairing = readPairing(configDir);
+  if (pairing) {
+    const def = defaultProfileId(pairing);
+    console.log(`配对：${pairing.bindings.length} 条（缺省 profileId=${def}，优先 master）`);
+    for (const b of pairing.bindings) {
+      console.log(`  - ${b.profileId}（${b.role}${b.name ? `，${b.name}` : ''}）`);
+    }
+  } else {
+    console.log('配对：未配对（扩展 options 点「CLI 配对」后生成 pairing.json）');
+  }
+  if (!any) {
+    console.error('未发现任何 manifest——先执行 fde2e-bu bind install');
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * bind remove：删 manifest（幂等）；--purge 连 pairing.json 一起删。
+ * nm-host.sh 保留在配置根（重装即用；彻底清理手动删配置根）。
+ * @returns {number} 恒 0（未装＝幂等跳过，不是错误）
+ */
+export function cmdBindRemove({ manifestsDir, configDir, purge = false, home = homedir() } = {}) {
+  let removed = 0;
+  for (const t of manifestTargets({ browser: 'both', manifestsDir, home })) {
+    if (existsSync(t.path)) {
+      unlinkSync(t.path);
+      removed++;
+      console.log(`已删除 manifest（${t.label}）：${t.path}`);
+    } else {
+      console.log(`未安装（幂等跳过）manifest（${t.label}）：${t.path}`);
+    }
+  }
+  if (purge) {
+    const p = pairingPath(configDir);
+    if (existsSync(p)) {
+      unlinkSync(p);
+      console.log(`已删除配对：${p}`);
+    } else {
+      console.log(`无配对（幂等跳过）：${p}`);
+    }
+  }
+  if (removed === 0) console.error('未发现任何 manifest（均未安装）');
+  return 0;
+}

package/src/nm/host.mjs

@@ -0,0 +1,294 @@
+// Native Messaging host（change bu-bind-http-publish A1/A2）——Chrome NM 帧协议
+// 与 bu:pair 配对消息处理。隐蔽子命令 `fde2e-bu __nm-host` 直通本模块 runNmHost。
+//
+// 帧协议（Chrome Native Messaging 规范）：
+//   4 字节小端长度前缀 + UTF-8 JSON 载荷；单帧上限 1MB（超限回错误帧，不崩不退出
+//   ——长度前缀流无法重同步，按「4+声明长度」流式丢弃该帧字节后继续解后续帧）。
+// 消息（扩展 → CLI，唯一受支持类型）：
+//   {type:'bu:pair', version:'<manifest version>',
+//    bindings:[{profileId, role:'master'|'cluster', name?, server?}]}
+//   （bindings 来自扩展绑定表快照；空数组合法——照常落盘并如实显示 0 条。）
+// 应答（CLI → 扩展）：
+//   成功 {type:'bu:pair:ok', cli:'fde2e-bu', version:<pkg>, saved:N}
+//   失败 {type:'bu:pair:error', message:<原因>}（未知类型/校验不过/落盘失败）
+// 落盘：pairing.json（{version, savedAt, bindings}，atomicWrite 0600——复用
+// src/mcp/config.mjs 的原子写底座）。pairing 只含 profileId/role/name/server 等
+// 非敏感标识，绝不含 token/credential。
+// 生命周期：stdin EOF → 退出 0；一切日志只走 stderr（stdout 只有协议帧）。
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWrite } from '../mcp/config.mjs';
+import { resolveConfigDir } from '../configdir.mjs';
+import pkg from '../../package.json' with { type: 'json' };
+
+export const NM_HOST_NAME = 'com.fde2e.bu';
+/** 单帧载荷上限（字节）——对齐 Chrome NM「消息 ≤1MB」口径。 */
+export const MAX_FRAME_BYTES = 1024 * 1024;
+/** bindings 上限（与扩展侧 buildPairMessage 同口径，防滥用）。 */
+export const MAX_BINDINGS = 50;
+/** 绑定 id（＝profileId）安全字符集——与 packages/protocol/src/redeem.js 的
+ * SAFE_PROFILE_ID_RE 同一字符集（字母数字下划线连字符，1~128 位）。 */
+export const SAFE_PROFILE_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+
+// ---------- 帧编解码（纯函数，可测） ----------
+
+/** JSON 文本 → NM 帧（4B 小端长度 + UTF-8 载荷）。超限抛错（调用方只编码应答帧，恒小）。 */
+export function encodeFrame(text) {
+  const payload = Buffer.from(String(text), 'utf8');
+  if (payload.length > MAX_FRAME_BYTES) {
+    throw new Error(`帧超限：${payload.length}B > ${MAX_FRAME_BYTES}B`);
+  }
+  const head = Buffer.alloc(4);
+  head.writeUInt32LE(payload.length, 0);
+  return Buffer.concat([head, payload]);
+}
+
+/**
+ * 从缓冲头部解一帧（纯函数，不修改入参）。
+ * @param {Buffer} buf 已积累的原始字节
+ * @returns {{ complete:false }                                   // 字节不足，继续积累
+ *          | { complete:true, payload:string, rest:Buffer }       // 成功解出一帧
+ *          | { error:'too-large', declared:number }}              // 声明长度超限——
+ *                                                                 // 调用方应丢弃整个缓冲
+ */
+export function decodeFrame(buf) {
+  if (!(buf instanceof Buffer)) buf = Buffer.from(buf);
+  if (buf.length < 4) return { complete: false };
+  const declared = buf.readUInt32LE(0);
+  if (declared > MAX_FRAME_BYTES) return { error: 'too-large', declared };
+  if (buf.length < 4 + declared) return { complete: false };
+  return {
+    complete: true,
+    payload: buf.subarray(4, 4 + declared).toString('utf8'),
+    rest: buf.subarray(4 + declared),
+  };
+}
+
+// ---------- pairing 存储 ----------
+
+/** pairing.json 路径（configDir＝resolveConfigDir 的产物）。 */
+export function pairingPath(configDir) {
+  return join(configDir, 'pairing.json');
+}
+
+/**
+ * 读取 pairing：不存在/坏 JSON/坏形状 → null（读侧宽容——status/doctor 只是展示面）。
+ * P2-8：条目逐条过滤——非对象/profileId 非字符串的条目直接丢弃（手工编辑/历史脏
+ * 数据防 status/doctor 的 TypeError；过滤后可能得空数组，仍如实返回）。
+ */
+export function readPairing(configDir) {
+  const p = pairingPath(configDir);
+  if (!existsSync(p)) return null;
+  try {
+    const data = JSON.parse(readFileSync(p, 'utf8'));
+    if (!data || typeof data !== 'object' || !Array.isArray(data.bindings)) return null;
+    return { ...data, bindings: data.bindings.filter((b) => b !== null && typeof b === 'object' && !Array.isArray(b) && typeof b.profileId === 'string') };
+  } catch {
+    return null;
+  }
+}
+
+/** pairing 落盘（atomicWrite：temp+rename+chmod 0600）。 */
+export function savePairing(configDir, pairing) {
+  atomicWrite(pairingPath(configDir), `${JSON.stringify(pairing, null, 2)}\n`);
+}
+
+/** 缺省 profileId：优先 master，无 master 取第一条；空/无 pairing → null。 */
+export function defaultProfileId(pairing) {
+  if (!pairing || !Array.isArray(pairing.bindings) || pairing.bindings.length === 0) return null;
+  const master = pairing.bindings.find((b) => b?.role === 'master');
+  return (master ?? pairing.bindings[0]).profileId ?? null;
+}
+
+/**
+ * P1-1：pairing 作为 profileId 缺省来源——readPairing → defaultProfileId 的组合
+ * （serve 层在 BU_BRIDGE_PROFILE_ID 未设置时的回退；README/UI 的承诺由此成真）。
+ * 任何读取异常 → null（回退缺位不构成启动失败）。
+ */
+export function pairingDefaultProfileId(configDir) {
+  try {
+    return defaultProfileId(readPairing(configDir));
+  } catch {
+    return null;
+  }
+}
+
+// ---------- bu:pair 校验（纯函数） ----------
+
+const ROLES = new Set(['master', 'cluster']);
+
+/**
+ * 校验 bu:pair 消息并产出规范化 bindings（裁剪到四字段、按 profileId 去重保首条、
+ * role 缺省 cluster——与扩展侧 buildPairMessage 同语义）。
+ * @returns {{ ok:true, bindings:Array<{profileId:string, role:string, name?:string, server?:string}> }
+ *          | { ok:false, message:string }}
+ */
+export function validatePairMessage(msg) {
+  if (msg === null || typeof msg !== 'object' || Array.isArray(msg)) {
+    return { ok: false, message: '消息须为 JSON 对象' };
+  }
+  if (msg.type !== 'bu:pair') {
+    return { ok: false, message: `未知消息类型：${JSON.stringify(msg.type ?? null)}` };
+  }
+  if (!Array.isArray(msg.bindings)) {
+    return { ok: false, message: 'bindings 须为数组' };
+  }
+  if (msg.bindings.length > MAX_BINDINGS) {
+    return { ok: false, message: `bindings 超 ${MAX_BINDINGS} 条上限（收到 ${msg.bindings.length}）` };
+  }
+  const seen = new Set();
+  const bindings = [];
+  for (const [i, raw] of msg.bindings.entries()) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+      return { ok: false, message: `bindings[${i}] 须为对象` };
+    }
+    const { profileId, role, name, server } = raw;
+    if (typeof profileId !== 'string' || !SAFE_PROFILE_ID_RE.test(profileId)) {
+      return { ok: false, message: `bindings[${i}].profileId 非法（须匹配 ${SAFE_PROFILE_ID_RE.source}）` };
+    }
+    if (role !== undefined && !ROLES.has(role)) {
+      return { ok: false, message: `bindings[${i}].role 须为 master|cluster（收到 ${JSON.stringify(role)}）` };
+    }
+    for (const k of ['name', 'server']) {
+      const v = raw[k];
+      if (v !== undefined && (typeof v !== 'string' || v.length > 256)) {
+        return { ok: false, message: `bindings[${i}].${k} 须为 ≤256 字符的字符串` };
+      }
+    }
+    if (seen.has(profileId)) continue; // 同 profileId 去重：保留首条（顺序稳定）
+    seen.add(profileId);
+    const entry = { profileId, role: role ?? 'cluster' };
+    if (name !== undefined) entry.name = name;
+    if (server !== undefined) entry.server = server;
+    bindings.push(entry);
+  }
+  return { ok: true, bindings };
+}
+
+// ---------- 消息处理（依赖注入，可测） ----------
+
+function errorReply(message) {
+  return { type: 'bu:pair:error', message };
+}
+
+/**
+ * 单条 NM 消息 → 应答对象（不碰流；落盘经 deps 注入，纯逻辑可测）。
+ * @param {unknown} msg 解析后的 JSON 值
+ * @param {{ version?: string, now?: () => string, save?: (pairing:object) => void }} [deps]
+ *   save 注入落盘动作；缺省＝写 resolveConfigDir() 下 pairing.json（调用时才解析
+ *   env/家目录——测试可用 BU_CONFIG_DIR 重定向）。
+ * @returns {{type:'bu:pair:ok', cli:string, version:string, saved:number,
+ *            received:number, truncated:boolean}
+ *          |{type:'bu:pair:error', message:string}}
+ *   P1-2：received＝收到的原始条数、truncated＝扩展侧是否声明截断——截断要如实
+ *   回执给 UI 显示「K 条未同步」，不再只报 saved 装作全量。
+ */
+export function handleNmMessage(msg, deps = {}) {
+  const version = deps.version ?? pkg.version;
+  const check = validatePairMessage(msg);
+  if (!check.ok) return errorReply(check.message);
+  const truncated = msg.truncated === true;
+  const pairing = {
+    version,
+    savedAt: (deps.now ?? (() => new Date().toISOString()))(),
+    bindings: check.bindings,
+    // 仅真截断时落盘（扩展侧 buildPairMessage 超出 50 条时置 true）
+    ...(truncated ? { truncated: true } : {}),
+  };
+  try {
+    if (deps.save) deps.save(pairing);
+    else savePairing(resolveConfigDir(), pairing);
+  } catch (err) {
+    return errorReply(`配对落盘失败：${err?.message ?? err}`);
+  }
+  return {
+    type: 'bu:pair:ok',
+    cli: 'fde2e-bu',
+    version,
+    saved: pairing.bindings.length,
+    received: msg.bindings.length,
+    truncated,
+  };
+}
+
+// ---------- host 主循环（stdin 帧流 → stdout 帧流） ----------
+
+/**
+ * NM host 运行体：读到 stdin EOF 退出 0；畸形/未知消息一律回错误帧，不崩不退出。
+ * @param {{ stdin?: object, stdout?: object, stderr?: object, configDir?: string,
+ *           version?: string, now?: () => string }} [opts]
+ * @returns {Promise<number>} exit code（恒 0——协议层错误不退出码化，Chrome 只看断开）
+ */
+export function runNmHost({ stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, configDir, version, now } = {}) {
+  return new Promise((resolve) => {
+    const deps = {
+      ...(version !== undefined ? { version } : {}),
+      ...(now !== undefined ? { now } : {}),
+      // configDir 显式注入时固定落盘点；缺省让 handleNmMessage 走 resolveConfigDir()
+      ...(configDir !== undefined ? { save: (pairing) => savePairing(configDir, pairing) } : {}),
+    };
+    const writeFrame = (obj) => {
+      try {
+        stdout.write(encodeFrame(JSON.stringify(obj)));
+      } catch (err) {
+        stderr.write(`nm-host: 应答帧写出失败：${err?.message ?? err}\n`);
+      }
+    };
+    let buf = Buffer.alloc(0);
+    // P2-1：超限帧流式丢弃——不清空整个缓冲（那会把同批到达的后续合法帧一起杀
+    // 掉），改为按「4+声明长度」记账，随到达字节扣减；扣完即恢复常规解帧。
+    let discard = 0;
+    let settled = false;
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      resolve(code);
+    };
+    stdin.on('data', (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      // 丢弃期内不尝试解帧：新到字节先还超限帧的账
+      if (discard > 0) {
+        const take = Math.min(buf.length, discard);
+        discard -= take;
+        buf = buf.subarray(take);
+        if (discard > 0) return;
+      }
+      for (;;) {
+        const r = decodeFrame(buf);
+        if (r.error === 'too-large') {
+          stderr.write(`nm-host: 帧超限（声明 ${r.declared}B > ${MAX_FRAME_BYTES}B）——流式丢弃 ${4 + r.declared}B\n`);
+          writeFrame(errorReply(`帧超限：声明 ${r.declared}B > 上限 ${MAX_FRAME_BYTES}B`));
+          const total = 4 + r.declared;
+          const take = Math.min(buf.length, total);
+          discard = total - take;
+          buf = buf.subarray(take);
+          if (discard > 0) break; // 余量等后续字节到达（超限帧载荷尚未送完）
+          continue; // 本批字节已覆盖超限帧全长——紧随其后的合法帧继续解
+        }
+        if (!r.complete) break;
+        buf = r.rest;
+        let msg;
+        try {
+          msg = JSON.parse(r.payload);
+        } catch {
+          stderr.write('nm-host: 帧载荷不是合法 JSON\n');
+          writeFrame(errorReply('帧载荷不是合法 JSON'));
+          continue;
+        }
+        try {
+          writeFrame(handleNmMessage(msg, deps));
+        } catch (err) {
+          stderr.write(`nm-host: 消息处理异常：${err?.message ?? err}\n`);
+          writeFrame(errorReply(`处理异常：${err?.message ?? err}`));
+        }
+      }
+    });
+    stdin.on('end', () => finish(0)); // 客户端断开（Chrome 端 port.disconnect）→ 干净退出 0
+    stdin.on('close', () => finish(0));
+    stdin.on('error', (err) => {
+      stderr.write(`nm-host: stdin 错误：${err?.message ?? err}\n`);
+      finish(0);
+    });
+  });
+}

package/src/skills/frontmatter.mjs

@@ -0,0 +1,150 @@
+// SKILL.md frontmatter 解析器（task 2.1/2.2）——手写最小 YAML 子集，不引 yaml 依赖
+// （零依赖原则；agentskills.io frontmatter 实际用到的语法面极小：
+//   顶层标量键值 + 一~两层嵌套 map + 行内 flow 数组，足够覆盖 name/description/
+//   version/metadata.version 的渐进披露读取）。
+//
+// 支持的子集：
+//   key: value            标量（裸值 / 单引号 / 双引号字符串；行尾 " #" 注释）
+//   key:                  空值或嵌套块（下一行更深缩进 → 子 map）
+//   key: [a, b, c]        行内 flow 数组（字符串元素；引号内逗号不切分——r1 状态机）
+//   键字符＝\w＋CJK＋.-（r1：允许非 ASCII 键，如 `名称:`）
+//   '#' 开头整行注释、空行跳过
+// 其余（多行字符串|、锚点、复杂 flow 等）报 PARSE_ERROR——渐进披露不需要。
+
+/** @returns {{ ok: true, data: Record<string, unknown> } | { ok: false, reason: string }} */
+export function parseFrontmatter(text) {
+  if (typeof text !== 'string') return { ok: false, reason: '输入不是字符串' };
+  const lines = text.split('\n').map((l) => l.replace(/\r$/, ''));
+  if (lines[0] === undefined || lines[0].trim() !== '---') {
+    return { ok: false, reason: '首行不是 --- 分隔符（无 frontmatter）' };
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    const t = lines[i].trim();
+    if (t === '---' || t === '...') { end = i; break; }
+    if (t === '') continue; // 分隔符前允许空行
+  }
+  if (end === -1) return { ok: false, reason: 'frontmatter 未闭合（缺第二个 --- 行）' };
+  try {
+    return { ok: true, data: parseYamlSubset(lines.slice(1, end)) };
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+}
+
+const indentOf = (s) => { const m = /^ */.exec(s); return m ? m[0].length : 0; };
+const isSignificant = (l) => l.trim() !== '' && !l.trim().startsWith('#');
+
+/** 标量解析：剥引号（支持双/单引号与 \" 转义）、剥行尾注释；一律返回字符串。 */
+function parseScalar(raw) {
+  let s = raw.trim();
+  if (s.startsWith('"')) {
+    const m = /^"((?:[^"\\]|\\.)*)"/.exec(s);
+    if (!m) throw new Error(`双引号字符串未闭合：${raw}`);
+    return m[1].replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+  }
+  if (s.startsWith("'")) {
+    const m = /^'([^']*)'/.exec(s);
+    if (!m) throw new Error(`单引号字符串未闭合：${raw}`);
+    return m[1];
+  }
+  const hash = s.indexOf(' #');
+  if (hash !== -1) s = s.slice(0, hash).trim(); // 行尾注释（裸值才会出现 " #"）
+  return s;
+}
+
+/** 行内 flow 数组：[a, "b", 'c'] → string[]。
+ *  r1：逗号切分走引号状态机——引号内的逗号（如 tags: ["a,b", c]）不得切开。 */
+function parseFlowArray(raw) {
+  const s = raw.trim();
+  if (!s.endsWith(']')) throw new Error(`flow 数组未闭合：${raw}`);
+  const inner = s.slice(1, -1).trim();
+  if (inner === '') return [];
+  return splitFlowElements(inner).map((el) => parseScalar(el));
+}
+
+/** 引号保护切分：单/双引号内的分隔符与转义（\"）原样保留，引号外逗号才分段。 */
+function splitFlowElements(inner) {
+  const parts = [];
+  let cur = '';
+  let quote = null; // null | '"' | "'"
+  for (let i = 0; i < inner.length; i++) {
+    const ch = inner[i];
+    if (quote !== null) {
+      cur += ch;
+      if (ch === '\\' && quote === '"' && i + 1 < inner.length) { cur += inner[++i]; continue; }
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; cur += ch; continue; }
+    if (ch === ',') { parts.push(cur); cur = ''; continue; }
+    cur += ch;
+  }
+  parts.push(cur);
+  return parts.map((p) => p.trim()).filter((p) => p !== '');
+}
+
+/**
+ * 缩进递归下降解析（行数组 → 普通对象）。
+ * @param {string[]} lines
+ * @param {number} [baseIndent] 当前块基准缩进
+ */
+function parseYamlSubset(lines, baseIndent = 0) {
+  const map = {};
+  let i = 0;
+  const nextSignificant = (from) => {
+    for (let j = from; j < lines.length; j++) if (isSignificant(lines[j])) return j;
+    return -1;
+  };
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!isSignificant(line)) { i++; continue; }
+    const ind = indentOf(line);
+    if (ind < baseIndent) break;
+    if (ind > baseIndent) throw new Error(`意外缩进（无宿主键）：${line.trim()}`);
+    // r1：键允许非 ASCII（技能作者用中文键，如 `名称: …`）；\w＝[A-Za-z0-9_]，另放行 CJK 与 .-
+    const m = /^([\w\u4e00-\u9fff.-]+):\s*(.*)$/.exec(line.trim());
+    if (!m) throw new Error(`无法解析的 frontmatter 行：${line.trim()}`);
+    const key = m[1];
+    const rest = m[2];
+    if (rest === '') {
+      const nxt = nextSignificant(i + 1);
+      if (nxt !== -1 && indentOf(lines[nxt]) > baseIndent) {
+        map[key] = parseYamlSubset(lines.slice(nxt), indentOf(lines[nxt]));
+        // 块值消费到「下一行首」——continue 免得多跳一行（nxt+count 已指向未消费行）
+        i = nxt + countConsumed(lines, nxt, indentOf(lines[nxt]));
+        continue;
+      }
+      map[key] = null;
+    } else if (rest.trim().startsWith('[')) {
+      map[key] = parseFlowArray(rest);
+    } else {
+      map[key] = parseScalar(rest);
+    }
+    i++;
+  }
+  return map;
+}
+
+/** 子块被递归解析后，计算其在原数组中占用的行数（到下一个不缩进行或末尾）。 */
+function countConsumed(lines, start, childIndent) {
+  let n = 0;
+  for (let j = start; j < lines.length; j++) {
+    if (isSignificant(lines[j]) && indentOf(lines[j]) < childIndent) break;
+    n++;
+  }
+  return n;
+}
+
+/** 渐进披露取值：version 取顶层，缺失回落 metadata.version（agentskills 规范位置）。 */
+export function disclosedFields(data) {
+  const metadata = data && typeof data.metadata === 'object' && data.metadata !== null ? data.metadata : {};
+  return {
+    name: typeof data?.name === 'string' ? data.name : '',
+    description: typeof data?.description === 'string' ? data.description : '',
+    version:
+      typeof data?.version === 'string' && data.version !== '' ? data.version
+        : typeof metadata.version === 'string' && metadata.version !== '' ? metadata.version
+          : '',
+  };
+}