fde2e-bu 0.0.0 → 1.3.0

package/README.md

@@ -0,0 +1,65 @@
+# fde2e-bu —— FDE2E Browser Use 命令行（零运行时依赖）
+
+浏览器多控执行端（MV3 扩展 `FDE2E BU Bridge`）的 CLI 伴生工具：技能包管理＋MCP
+server＋扩展一次性配对。
+
+```bash
+# 安装（任选其一；Node ≥ 22）
+npm i -g fde2e-bu
+npx -y fde2e-bu@latest --help
+
+fde2e-bu skills list | add <path|git-url> | remove <name> | validate [<path>]
+fde2e-bu mcp serve [--http [--port 8791] [--token <t>]]   # stdio 缺省；--http 见下
+fde2e-bu mcp add --client claude|codex|gemini [--scope user|project|local]
+fde2e-bu mcp list | remove
+fde2e-bu bind install [--browser chrome|chromium|both] | status | remove
+fde2e-bu status | doctor | update
+```
+
+## bind —— 扩展↔CLI 一次性配对（本机，零网络；macOS/Linux）
+
+`bind install` 写入 Chrome Native Messaging host 清单（`com.fde2e.bu`，stdio 型；
+allowed_origins 锚定扩展固定 ID `meojillndgamkbfjijfehjaefolnfopn`）。之后在扩展
+options 面板点「CLI 配对」，扩展经本机 host 把绑定清单
+（profileId/角色/名称/omni server——非敏感标识，不含 token/凭据；单条 ≤50，
+超出如实回执截断数）写入 `~/.config/fde2e-bu/pairing.json`（0600）。
+**配对后 pairing 即成为 `BU_BRIDGE_PROFILE_ID` 的本机缺省来源**：`mcp serve`
+（stdio 与 --http）在环境变量未设置时自动回退到配对的缺省 profileId（优先
+master），并在 stderr 提示一行。`bind status`/`doctor` 展示配对状态并校验
+host 脚本在位可执行。目录映射：macOS＝`~/Library/Application Support/…`、
+Linux＝`~/.config/google-chrome|chromium/…`；Windows（注册表写入）待后续版本。
+
+## mcp serve --http —— 回环 JSON-RPC（脚本集成用）
+
+- **只绑 127.0.0.1**（缺省端口 8791，`--port 0` 临时端口）。
+- 三重门：Host 头白名单（127.0.0.1/localhost/`[::1]`，防 DNS rebinding）＋
+  Origin 校验（在场必须回环源）＋ Bearer token（scheme 大小写不敏感，token 精确
+  比较；`--token` / `BU_MCP_TOKEN` / `~/.config/fde2e-bu/token` 自动生成 0600）。
+  token 打印策略：仅**首次自动生成**时打完整值；来自参数/env/既有文件只显示
+  尾 4 位与来源。空 `--token ''` 直接用法错误。
+- 端点：`POST /` 与 `POST /mcp`（单条 JSON-RPC，与 stdio 同一处理核；批量数组
+  -32600；通知 204；body >4MB → 413）；`GET /healthz` 免 token 探活。
+- 注意：这是**受 token 保护的单端点 JSON-RPC**，不是 MCP streamable-HTTP 全规范
+  （无 SSE/会话）——面向脚本与内部集成；MCP 客户端请继续用 stdio。
+
+## 其余能力（沿用）
+
+- **零运行时依赖**：`util.parseArgs` + 手写 stdio JSON-RPC；`npx` 直跑免安装。
+- **MCP 工具面**（9 工具）：bu_open/bu_click/bu_fill/bu_read/bu_screenshot 六意图级
+  ＋窗口三件套＋bu_cmd 透传；schema 源＝`plugins/contracts/browser-bridge/commands.json`
+  （构建期快照内嵌＋双对表测试）；bu_cmd 枚举＝云端可执行 21 条（7 条保留命令本地即拒）。
+  服务端按 inputSchema 校验全部输入（MCP 规范 MUST）。
+- **传输**：`POST {BU_BRIDGE_SERVER}/api/cmd`（默认 `http://127.0.0.1:8788`）；
+  `BU_BRIDGE_PROFILE_ID` 必配；`BU_INTERNAL_TOKEN`/`BU_BOUND_PROFILE_ID` 认证头
+  **仅向回环地址发送**。
+- **skills**：agentskills.io 事实标准（`<skill>/SKILL.md`）；默认写 `.agents/skills/`，
+  兼容 `.claude/skills`。
+- **配置写入**：`mcp add/remove` 与 pairing/token 一律原子写（同目录 temp → rename），
+  落盘权限统一 **0600**（含 env 中的 profileId/令牌；既有文件也会被收紧）；
+  例外：`bind install` 生成的 `nm-host.sh` 为可执行脚本（0755）。
+- **flag 面**：各子命令只接受自述范围内的 flag/位置参数，多余项一律用法错误 exit 2
+  （不静默忽略，例如 `mcp list --profile-id x` 会被拒绝）。
+
+设计依据：`docs/research/cli-design.md`（Claude Code/Codex/Gemini/MCP 生态调研）；
+变更轨迹：openspec `bu-cli` / `bu-p2-hardening` / `bu-bind-http-publish`。
+License: 私有（FDE2E / 昭智羽名）。

package/bin.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// fde2e-bu CLI 入口（openspec change bu-cli task 1.1）。
+// 零运行时依赖：参数解析用 Node 原生 util.parseArgs（调研 D 节裁量记录见
+// src/cli.mjs 头注），MCP 走手写最小 stdio JSON-RPC 2.0（src/mcp/serve.mjs）。
+import { mainSafe } from './src/cli.mjs';
+
+mainSafe(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    console.error(`fde2e-bu: ${err?.message ?? err}`);
+    process.exit(1);
+  },
+);

package/package.json

@@ -1,9 +1,33 @@
 {
   "name": "fde2e-bu",
-  "version": "0.0.0",
-  "description": "Generated placeholder package reserved by pnpm-pub.",
-  "main": "index.js",
+  "version": "1.3.0",
+  "description": "FDE2E Browser Use CLI —— skills 管理＋MCP server＋扩展配对（零运行时依赖）",
+  "type": "module",
+  "bin": {
+    "fde2e-bu": "bin.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jixoai/fde2e-bu.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/jixoai/fde2e-bu/issues"
+  },
+  "homepage": "https://www.fde2e.com/downloads/",
   "files": [
-    "index.js"
-  ]
-}
+    "bin.js",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "license": "UNLICENSED"
+}

package/src/args.mjs

@@ -0,0 +1,92 @@
+// 参数解析底座（task 1.1）：统一 util.parseArgs 包装＋用法错误通道。
+// 选型记录（调研 D 节裁量）：零运行时依赖原则下选 Node 原生 util.parseArgs——
+// 子命令树浅（6 组 × ≤4 子命令），原生能力足够；commander/yargs 各带传递依赖，
+// 对「npx 首跑零安装」的分发目标是纯负担。strict:true 未知 flag 直接报用法错。
+import { parseArgs } from 'node:util';
+
+/** 用法/参数错误：exit code 固定 2，可携带对应 help 文本一起打印。 */
+export class UsageError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ help?: string, code?: number }} [meta]
+   */
+  constructor(message, meta = {}) {
+    super(message);
+    this.name = 'UsageError';
+    this.exitCode = meta.code ?? 2;
+    this.help = meta.help;
+  }
+}
+
+/**
+ * 解析子命令参数（strict；allowPositionals）。
+ * @param {string[]} args 位置参数之后的原始 argv 片段
+ * @param {{ options?: object, help?: string }} [meta]
+ * @returns {{ positionals: string[], values: Record<string, unknown> }}
+ */
+export function parse(args, meta = {}) {
+  try {
+    return parseArgs({
+      args,
+      options: meta.options ?? {},
+      allowPositionals: true,
+      strict: true,
+    });
+  } catch (err) {
+    throw new UsageError(err.message, { help: meta.help });
+  }
+}
+
+/** 逗号分隔列表 → 去空数组（"--client claude,codex" → ['claude','codex']）。 */
+export function csvList(value) {
+  if (typeof value !== 'string' || value.trim() === '') return [];
+  return value.split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+// ---------- C1 flag 面收窄（P2-6）：不适用 flag 一律用法错误，不静默忽略 ----------
+
+/**
+ * 取 argv 片段里出现的 flag 名（长名去 `--`，短名去 `-`；`--k=v` 取 k）。
+ * `--` 之后全部视为位置参数（不当作 flag）。
+ * @param {string[]} args
+ * @returns {string[]}
+ */
+export function flagNames(args) {
+  const names = [];
+  let positionalOnly = false;
+  for (const tok of args) {
+    if (positionalOnly) continue;
+    if (tok === '--') { positionalOnly = true; continue; }
+    if (tok === '-' || !tok.startsWith('-')) continue;
+    names.push(tok.replace(/^--?/, '').split('=')[0]);
+  }
+  return names;
+}
+
+/**
+ * flag 面校验：本子命令不接受的 flag → UsageError exit 2。
+ * parseArgs 的 strict 只拒「全局未知」，这里拒「对子命令无意义」（如
+ * `mcp list --profile-id`）——静默忽略是最难排查的一类 CLI 缺陷（P2-6）。
+ * @param {string[]} args 位置参数之后的 argv 片段
+ * @param {string[]} allowed 允许的 flag 名（长名不含 `--`；'help' 自动兼容 -h）
+ * @param {string} label 子命令标签（如 `mcp list`）
+ * @param {{ help?: string }} [meta]
+ */
+export function assertFlags(args, allowed, label, meta = {}) {
+  const allow = new Set(allowed);
+  const list = allowed.length > 0 ? allowed.map((n) => (n === 'help' ? '--help/-h' : `--${n}`)).join(' ') : '（无 flag）';
+  for (const name of flagNames(args)) {
+    // -h 是 --help 的唯一短旗标（与各组 options 的 short:'h' 对应）
+    const key = name === 'h' && allow.has('help') ? 'help' : name;
+    if (!allow.has(key)) {
+      throw new UsageError(`${label} 不支持 flag：${name.length > 1 ? `--${name}` : `-${name}`}（支持：${list}）`, { help: meta.help });
+    }
+  }
+}
+
+/** 不接受位置参数的子命令：多余位置参数 → UsageError exit 2。 */
+export function assertNoPositionals(positionals, label, meta = {}) {
+  if (positionals.length > 0) {
+    throw new UsageError(`${label} 不接受位置参数（收到：${positionals.join(' ')}）`, { help: meta.help });
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,445 @@
+// fde2e-bu 子命令分发（task 1.1）。
+//
+// 设计决策（零依赖，记录于 change bu-cli）：
+// - 参数解析＝Node 原生 util.parseArgs（理由见 src/args.mjs 头注：npx 首跑零安装，
+//   子命令树浅不需要 commander 的能力面）。
+// - MCP SDK（@modelcontextprotocol/sdk）不引：本 CLI 只做 server 侧最小面
+//   （initialize / tools/list / tools/call / ping，stdio JSON-RPC 2.0，MCP 规范
+//   2025-06-18），手写实现约一百余行且行为完全可审计；SDK 带整棵传输/协议类树。
+// - 子命令＝两级（group → sub）；每组自带 help；未知组/子命令报用法错 exit 2。
+import { UsageError, parse, assertFlags, assertNoPositionals } from './args.mjs';
+import { cmdSkills } from './skills/skills.mjs';
+import { cmdMcp } from './mcp/config-cli.mjs';
+import { runServe } from './mcp/serve.mjs';
+import { runHttpServe, DEFAULT_HTTP_PORT } from './mcp/http.mjs';
+import { runNmHost } from './nm/host.mjs';
+import { cmdBindInstall, cmdBindStatus, cmdBindRemove, assertBindPlatform } from './nm/bind.mjs';
+import { cmdSelfUpdate, DEFAULT_FEED_URL } from './nm/update.mjs';
+import { resolveConfigDir } from './configdir.mjs';
+import { cmdStatus, cmdDoctor } from './misc.mjs';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+const VERSION_HELP = `fde2e-bu ${pkgVersion()} —— FDE2E Browser Use CLI（skills 管理＋MCP server）`;
+
+const MAIN_HELP = `fde2e-bu —— FDE2E Browser Use 命令行（零运行时依赖）
+
+用法：fde2e-bu <group> [sub] [options]
+
+组：
+  skills    管理技能包（agentskills.io 事实标准；默认写 .agents/skills，兼容 .claude/skills）
+              list | add | remove | validate
+  mcp       MCP server 与三家客户端配置
+              serve（stdio JSON-RPC 2.0；--http＝仅回环 token 端点）| add | list | remove
+  status    桥服务（omni /healthz）健康探测，离线降级提示；顶部显示已配对执行器
+  doctor    自检：node 版本 / 配置路径 / 环境变量 / 扩展 zip / NM manifest / pairing
+  update    扩展自更新：发现 unpacked 安装 → feed 检查 → 下载校验原子替换
+              [--ext-dir <dir>] [--feed <url>] [--dry-run]
+  bind      扩展↔CLI 一次性配对（Chrome Native Messaging）
+              install | status | remove
+
+通用：
+  --version     打印版本
+  --help, -h    本帮助；各组/子命令同 flag 打对应帮助
+
+环境变量（mcp serve / status / doctor 读取）：
+  BU_BRIDGE_SERVER        桥服务地址（缺省 http://127.0.0.1:8788）
+  BU_BRIDGE_PROFILE_ID    执行器 profileId（tools/call 必需）
+  BU_INTERNAL_TOKEN       内部令牌（回环来源下映射请求头 x-omni-internal）
+  BU_BOUND_PROFILE_ID     会话绑定 profileId（映射请求头 x-omni-bound-profile）
+  BU_CONFIG_DIR           配置根重定向（缺省 ~/.config/fde2e-bu；pairing/token/nm-host.sh）
+  BU_MCP_TOKEN            mcp serve --http 的 token（优先级 --token > 此变量 > 配置根 token 文件）
+
+文档：openspec/changes/bu-bind-http-publish（本能力）、docs/research/cli-design.md（设计调研）`;
+
+const SKILLS_HELP = `fde2e-bu skills —— 技能包管理（agentskills.io 事实标准）
+
+用法：
+  fde2e-bu skills list [--json] [--root <dir>]
+      扫描 <dir>（缺省 cwd）向上找最近的 .agents/skills 与 .claude/skills，
+      渐进披露（只读 SKILL.md frontmatter 的 name/description/version）表格输出。
+  fde2e-bu skills add <src> [--skill <subdir>] [--dest agents|claude] [--force]
+      源＝本地技能包目录或 git URL（--depth 1 浅拷贝；--skill 指定仓库内子目录，
+      不得越出克隆根）。装前先过 validate；同名已装默认提示退出（--force 覆盖重装，
+      先拷后换不丢既有安装；源即目标的自装请求拒绝）。
+  fde2e-bu skills remove <name> [--dest agents|claude] [--all]
+      删除已装技能；未装时幂等提示（--all 同时清两处目录）。
+      技能名须为小写字母数字连字符——含 ../分隔符/绝对路径一律拒绝（exit 1）。
+  fde2e-bu skills validate [<path>]
+      校验技能包（缺省＝扫描到的全部技能）：name ≤64 小写连字符且＝目录名、
+      description ≤1024、SKILL.md frontmatter 可解析。`;
+
+const MCP_HELP = `fde2e-bu mcp —— MCP server 与客户端配置
+
+用法：
+  fde2e-bu mcp serve [--schema-only]
+      stdio JSON-RPC 2.0 MCP server（MCP 规范 2025-06-18）：
+      initialize / tools/list / tools/call / ping。
+      工具面＝bu_open/bu_click/bu_fill/bu_read/bu_screenshot/bu_cmd（透传）＋
+      bu_window_list/bu_window_create/bu_window_close（schema 源＝契约层
+      commands.json 快照，见 src/mcp/schema.mjs）。
+      execute 经 POST {BU_BRIDGE_SERVER|http://127.0.0.1:8788}/api/cmd。
+      --schema-only 只打印工具清单 JSON（不自起服务）。
+  fde2e-bu mcp serve --http [--port N] [--token <t>]
+      HTTP 端点（面向脚本/内部集成；非 MCP streamable-HTTP 全规范，stdio 仍是
+      MCP 客户端主通道）：
+        只 listen 127.0.0.1（缺省端口 ${DEFAULT_HTTP_PORT}；--port 0=临时端口）；
+        POST / 与 /mcp 单条 JSON-RPC（与 stdio 同一处理核；通知 204；
+        数组 -32600；解析失败 -32700）；GET /healthz 免 token 探活。
+      安全三重门：Host 头白名单（127.0.0.1/localhost/[::1]，防 DNS rebinding）＋
+      Origin 校验（在场必须 http://127.0.0.1[:port]/http://localhost[:port]，无 Origin
+      放行）＋Bearer token（401）。token 解析顺序：--token > BU_MCP_TOKEN >
+      ~/.config/fde2e-bu/token（无则生成 32B hex 落盘 0600；BU_CONFIG_DIR
+      可重定向）。启动打印监听地址与 token 到 stderr。SIGINT/SIGTERM 优雅关闭。
+      --http 与 --schema-only 互斥（exit 2）。
+  fde2e-bu mcp add [--client claude,codex,gemini] [--scope user|project|local]
+                    [--home <dir>] [--dir <dir>] [--server <url>]
+                    [--profile-id <id>] [--cmd <bin>]
+      写三家 MCP 客户端配置（缺省全三家）。scope 语义（r1 如实化）：
+        claude  user→~/.claude.json（顶层 mcpServers）；project→.mcp.json；
+                local→~/.claude.json 的 projects[<cwd>].mcpServers（cwd＝--dir 或当前目录）
+        codex   仅 user（~/.codex/config.toml）；--scope project 降级写 user（打印提示）；
+                local 不支持（跳过并提示）
+        gemini  user→~/.gemini/settings.json；project→.gemini/settings.json；
+                local 不支持（跳过并提示）
+  fde2e-bu mcp list [--client claude,codex,gemini] [--home <dir>] [--dir <dir>]
+      打印六落点配置状态与注册形状（env 值脱敏：***尾4／已配置，不回显完整令牌）。
+  fde2e-bu mcp remove [--client ...] [--scope user|project|local] [--home <dir>] [--dir <dir>]
+      移除注册（--scope 收窄层级，缺省全清）；未注册时幂等提示。
+
+flag 面按子命令收窄（C1）：不适用 flag 与多余位置参数一律用法错误 exit 2
+（如 mcp list --profile-id x 不再被静默忽略）；--port/--token 仅 --http 模式可用。
+--home/--dir 显式重定向配置根与工作区根（测试用，不碰真实家目录）。`;
+
+const UPDATE_HELP = `fde2e-bu update —— 扩展自更新（unpacked 独立安装）
+
+用法：
+  fde2e-bu update [--ext-dir <dir>] [--feed <url>] [--dry-run]
+      发现本机 unpacked 安装（Chrome 系浏览器 Preferences/Secure Preferences 的
+      extensions.settings[meojillndgamkbfjijfehjaefolnfopn].path，多浏览器多
+      profile 全扫）→ fetch feed（缺省 ${DEFAULT_FEED_URL}）→ semver 只认 > →
+      下载（https 强制）→ sha256/字节数双校验 → staging 解压（zip-slip/条目数/
+      根 manifest/总量四重防护）→ rm+rename 原子替换（Windows 瞬态占用退避）。
+      多处安装全部应用；任一失败不回滚其它。受 FDE2E Omni 桌面版管理的安装
+      （~/fde2e/bu/ 内或目录旁 .browser-extension-state.json）自动跳过——随 App 更新。
+      --ext-dir <dir>    显式指定安装目录（复核 manifest.json 在场即可，免扫描）
+      --feed <url>       覆写 feed 地址（测试/私有部署；仍强制 https）
+      --dry-run          只报发现与目标版本，不写盘
+      0 命中 → exit 1＋指引（浏览器未开过本插件/装在非常规处时用 --ext-dir）。
+      CLI 本体的更新仍走 npm：npm i -g fde2e-bu@latest。
+
+环境变量（NM host 路径也生效）：
+  BU_UPDATE_BASE      下载基址/白名单重定向（测试假 feed server/私有部署；
+                      信任重定向到指定基址，不是放宽为任意域）
+
+设计：openspec/changes/bu-online-selfupdate（proposal/design C）。`;
+
+const BIND_HELP = `fde2e-bu bind —— 扩展↔CLI 一次性配对（Chrome Native Messaging）
+
+平台：支持 macOS 与 Linux（NM 清单按 Chrome 规范路径文件落盘）；Windows 需注册表
+写入，待后续——非受支持平台执行 install/status/remove 一律用法错误 exit 2。
+
+用法：
+  fde2e-bu bind install [--browser chrome|chromium|both] [--manifests-dir <dir>]
+                         [--config-dir <dir>]
+      写 Native Messaging host 落盘物（幂等覆盖）：
+        <configDir>/nm-host.sh（0755）——exec env BU_CONFIG_DIR='<configDir>'
+          <node> <cli/bin.js> __nm-host 的包装（路径单引号转义）
+          （NM 要求 path 是单个可执行文件，不能内嵌参数）；
+        浏览器 NM 目录 com.fde2e.bu.json——type:stdio，
+          allowed_origins＝chrome-extension://meojillndgamkbfjijfehjaefolnfopn/
+          （扩展固定 key 派生的稳定 ID）。
+        目录（macOS）：Chrome＝~/Library/Application Support/Google/Chrome/
+        NativeMessagingHosts；Chromium＝.../Chromium/NativeMessagingHosts。
+        --browser 缺省 chrome；both 写两处。
+        --manifests-dir 重定向 manifest 落点、--config-dir 重定向配置根
+        （等价 BU_CONFIG_DIR；测试/沙箱用）。装完打印下一步指引。
+  fde2e-bu bind status [--manifests-dir <dir>] [--config-dir <dir>]
+      manifest 各落点在否/内容摘要＋nm-host.sh 可执行位＋pairing 摘要
+      （profileId/role；缺省 profileId 优先 master）。无任何 manifest 时 exit 1。
+  fde2e-bu bind remove [--purge] [--manifests-dir <dir>] [--config-dir <dir>]
+      删 manifest（Chrome/Chromium/重定向落点全查，幂等）；--purge 连 pairing.json
+      一起删。nm-host.sh 保留（重装即用；彻底清理手动删配置根）。
+
+隐蔽子命令：fde2e-bu __nm-host（由 nm-host.sh/Chrome 启动，不在主 help）
+  ——NM 帧协议 host：4 字节小端长度＋UTF-8 JSON（单帧 ≤1MB），处理
+  {type:'bu:pair', bindings:[{profileId,role,name?,server?}]} → 原子写
+  <configDir>/pairing.json（0600）→ 应答 {type:'bu:pair:ok', saved:N,
+  received:M, truncated:bool}（截断如实回执）；未知/畸形回 bu:pair:error
+  不崩；stdin EOF 退出 0；日志仅 stderr。
+
+设计：openspec/changes/bu-bind-http-publish（proposal/design §1）。`;
+
+function pkgVersion() {
+  return JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')).version;
+}
+
+/** 顶层 --version / --help / -h。只在首参是 flag（或空 argv）时生效——组级
+ *  --help（如 `skills --help`）必须落到组分支打组帮助，不得被这里抢走。 */
+function handleGlobalFlags(argv) {
+  if (argv.length === 0) {
+    console.log(MAIN_HELP);
+    return 2; // 裸调用算用法错
+  }
+  if (!argv[0].startsWith('-')) return null; // 有组名 → 组分发
+  if (argv.includes('--version')) {
+    console.log(VERSION_HELP);
+    return 0;
+  }
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log(MAIN_HELP);
+    return 0;
+  }
+  return null; // 未知 flag 落组分发报未知组（argv[0] 当组名）
+}
+
+/** 组级 help 探测：组名后紧跟 --help/-h（或组后无参）。 */
+function wantsHelp(rest, hasRest) {
+  return rest.includes('--help') || rest.includes('-h') || !hasRest;
+}
+
+/**
+ * CLI 主入口。
+ * @param {string[]} argv process.argv.slice(2)
+ * @returns {Promise<number>} exit code
+ */
+export async function main(argv) {
+  const globalExit = handleGlobalFlags(argv);
+  if (globalExit !== null) return globalExit;
+
+  const [group, ...rest] = argv;
+
+  // A2：隐蔽子命令 __nm-host——Chrome NM host（nm-host.sh exec 启动），不在主 help。
+  // 不接受任何参数（参数只能来自 NM stdio 流，命令行多参即误用）。
+  if (group === '__nm-host') {
+    if (rest.length > 0) {
+      throw new UsageError('__nm-host 不接受命令行参数（由 Chrome Native Messaging 经 nm-host.sh 启动）', { help: BIND_HELP });
+    }
+    return runNmHost();
+  }
+
+  switch (group) {
+    case 'skills': {
+      if (wantsHelp(rest, rest.length > 0)) {
+        console.log(SKILLS_HELP);
+        return rest.length > 0 ? 0 : 2;
+      }
+      return cmdSkills(rest);
+    }
+    case 'mcp': {
+      if (wantsHelp(rest, rest.length > 0)) {
+        console.log(MCP_HELP);
+        return rest.length > 0 ? 0 : 2;
+      }
+      const [sub, ...subRest] = rest;
+      if (sub === 'serve') {
+        // C1＋A4：--schema-only/--http/--port/--token；--port/--token 仅 --http 模式可用
+        assertFlags(subRest, ['schema-only', 'http', 'port', 'token', 'help'], 'mcp serve', { help: MCP_HELP });
+        const { positionals, values } = parse(subRest, {
+          options: {
+            'schema-only': { type: 'boolean' },
+            http: { type: 'boolean' },
+            port: { type: 'string' }, // 手动校验（0~65535 整数；parseArgs 的 number 不拒 NaN）
+            token: { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+          },
+          help: MCP_HELP,
+        });
+        if (values.help) {
+          console.log(MCP_HELP);
+          return 0;
+        }
+        assertNoPositionals(positionals, 'mcp serve', { help: MCP_HELP });
+        if (values.http && values['schema-only']) {
+          // 互斥（A4）：--schema-only 打印即退、--http 常驻服务，语义不可同给
+          throw new UsageError('--http 与 --schema-only 互斥（前者常驻 HTTP 服务，后者打印工具清单即退）', { help: MCP_HELP });
+        }
+        if (!values.http && (values.port !== undefined || values.token !== undefined)) {
+          throw new UsageError('--port/--token 仅在 mcp serve --http 模式下可用', { help: MCP_HELP });
+        }
+        let port = DEFAULT_HTTP_PORT;
+        if (values.port !== undefined) {
+          port = Number(values.port);
+          if (!Number.isInteger(port) || port < 0 || port > 65535) {
+            throw new UsageError(`--port 须为 0~65535 整数（0=临时端口；收到 ${values.port}）`, { help: MCP_HELP });
+          }
+        }
+        // P2-12：显式空 --token 一律拒绝（'' 会被 resolveHttpToken 静默降级到下一来源，
+        // 用户以为设了 token 实则没有——最危险的静默失败面）
+        if (values.token !== undefined && values.token === '') {
+          throw new UsageError('--token 不能为空（显式置空会被静默降级到 env/文件来源——要随机 token 请省略该 flag）', { help: MCP_HELP });
+        }
+        if (values.http) {
+          return runHttpServe({ port, token: values.token ? String(values.token) : undefined });
+        }
+        return runServe({ schemaOnly: Boolean(values['schema-only']) });
+      }
+      return cmdMcp(sub, subRest, MCP_HELP);
+    }
+    case 'status': {
+      // C1 + C2 + A5：flags＝server/home/dir/json/config-dir/help；多余位置参数 exit 2
+      assertFlags(rest, ['server', 'home', 'dir', 'json', 'config-dir', 'help'], 'status', { help: MAIN_HELP });
+      const { positionals, values } = parse(rest, {
+        options: {
+          server: { type: 'string' },
+          home: { type: 'string' },
+          dir: { type: 'string' },
+          json: { type: 'boolean' },
+          'config-dir': { type: 'string' },
+          help: { type: 'boolean', short: 'h' },
+        },
+        help: MAIN_HELP,
+      });
+      if (values.help) {
+        console.log(MAIN_HELP);
+        return 0;
+      }
+      assertNoPositionals(positionals, 'status', { help: MAIN_HELP });
+      return cmdStatus({ server: values.server, home: values.home, dir: values.dir, json: values.json, configDir: values['config-dir'] });
+    }
+    case 'doctor': {
+      assertFlags(rest, ['home', 'dir', 'json', 'config-dir', 'manifests-dir', 'help'], 'doctor', { help: MAIN_HELP });
+      const { positionals, values } = parse(rest, {
+        options: {
+          home: { type: 'string' },
+          dir: { type: 'string' },
+          json: { type: 'boolean' },
+          'config-dir': { type: 'string' },
+          'manifests-dir': { type: 'string' },
+          help: { type: 'boolean', short: 'h' },
+        },
+        help: MAIN_HELP,
+      });
+      if (values.help) {
+        console.log(MAIN_HELP);
+        return 0;
+      }
+      assertNoPositionals(positionals, 'doctor', { help: MAIN_HELP });
+      return cmdDoctor({ home: values.home, dir: values.dir, json: values.json, configDir: values['config-dir'], manifestsDir: values['manifests-dir'] });
+    }
+    case 'update': {
+      // A3（bu-online-selfupdate）：--ext-dir/--feed/--dry-run；不适用 flag 与多余
+      // 位置参数一律 exit 2（cli-tooling 规格）；--feed 在参数面即强制 https。
+      assertFlags(rest, ['ext-dir', 'feed', 'dry-run', 'help'], 'update', { help: UPDATE_HELP });
+      const { positionals, values } = parse(rest, {
+        options: {
+          'ext-dir': { type: 'string' },
+          feed: { type: 'string' },
+          'dry-run': { type: 'boolean' },
+          help: { type: 'boolean', short: 'h' },
+        },
+        help: UPDATE_HELP,
+      });
+      if (values.help) {
+        console.log(UPDATE_HELP);
+        return 0;
+      }
+      assertNoPositionals(positionals, 'update', { help: UPDATE_HELP });
+      if (values['ext-dir'] !== undefined && values['ext-dir'] === '') {
+        throw new UsageError('--ext-dir 不能为空', { help: UPDATE_HELP });
+      }
+      if (values.feed !== undefined) {
+        let u;
+        try {
+          u = new URL(values.feed);
+        } catch {
+          throw new UsageError(`--feed url 无法解析：${values.feed}`, { help: UPDATE_HELP });
+        }
+        if (u.protocol !== 'https:') {
+          throw new UsageError(`--feed 必须 https（收到 ${u.protocol}//${u.host}）`, { help: UPDATE_HELP });
+        }
+      }
+      return cmdSelfUpdate({
+        ...(values['ext-dir'] !== undefined ? { extDir: values['ext-dir'] } : {}),
+        ...(values.feed !== undefined ? { feed: values.feed } : {}),
+        dryRun: Boolean(values['dry-run']),
+      });
+    }
+    case 'bind': {
+      // A3：bind install/status/remove；--help/-h → BIND_HELP exit 0；裸 bind → 帮助 exit 2
+      if (wantsHelp(rest, rest.length > 0)) {
+        console.log(BIND_HELP);
+        return rest.length > 0 ? 0 : 2;
+      }
+      // P1-5：平台守卫（macOS/Linux）——help 可看，install/status/remove 在
+      // 未支持平台（Windows 注册表面待实装）一律 UsageError exit 2
+      assertBindPlatform(process.platform);
+      const [sub, ...subRest] = rest;
+      const BIND_SUBS = {
+        install: {
+          flags: ['browser', 'manifests-dir', 'config-dir', 'help'],
+          options: {
+            browser: { type: 'string' },
+            'manifests-dir': { type: 'string' },
+            'config-dir': { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+          },
+        },
+        status: {
+          flags: ['manifests-dir', 'config-dir', 'help'],
+          options: {
+            'manifests-dir': { type: 'string' },
+            'config-dir': { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+          },
+        },
+        remove: {
+          flags: ['purge', 'manifests-dir', 'config-dir', 'help'],
+          options: {
+            purge: { type: 'boolean' },
+            'manifests-dir': { type: 'string' },
+            'config-dir': { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+          },
+        },
+      };
+      const spec = BIND_SUBS[sub];
+      if (!spec) {
+        throw new UsageError(`未知子命令：bind ${sub ?? ''}（可用：install/status/remove）`, { help: BIND_HELP });
+      }
+      assertFlags(subRest, spec.flags, `bind ${sub}`, { help: BIND_HELP });
+      const { positionals, values } = parse(subRest, { options: spec.options, help: BIND_HELP });
+      if (values.help) {
+        console.log(BIND_HELP);
+        return 0;
+      }
+      assertNoPositionals(positionals, `bind ${sub}`, { help: BIND_HELP });
+      const configDir = resolveConfigDir({
+        ...(values['config-dir'] ? { configDirFlag: values['config-dir'] } : {}),
+      });
+      const browser = values.browser ? String(values.browser) : 'chrome';
+      if (values.browser !== undefined && !['chrome', 'chromium', 'both'].includes(browser)) {
+        throw new UsageError(`--browser 取值 chrome|chromium|both（收到 ${browser}）`, { help: BIND_HELP });
+      }
+      switch (sub) {
+        case 'install':
+          return cmdBindInstall({ browser, manifestsDir: values['manifests-dir'], configDir });
+        case 'status':
+          return cmdBindStatus({ manifestsDir: values['manifests-dir'], configDir });
+        case 'remove':
+          return cmdBindRemove({ manifestsDir: values['manifests-dir'], configDir, purge: Boolean(values.purge) });
+        default:
+          throw new UsageError(`未知子命令：bind ${sub}`, { help: BIND_HELP });
+      }
+    }
+    default:
+      throw new UsageError(`未知命令组：${group}（可用：skills/mcp/status/doctor/update/bind）`, { help: MAIN_HELP });
+  }
+}
+
+/** 包一层 UsageError→stderr+help（bin.js 只兜底未预期异常）。 */
+export async function mainSafe(argv) {
+  try {
+    return await main(argv);
+  } catch (err) {
+    if (err instanceof UsageError) {
+      console.error(`用法错误：${err.message}`);
+      if (err.help) console.error(`\n${err.help}`);
+      return err.exitCode;
+    }
+    throw err;
+  }
+}