modelfunction-cli 0.4.1 → 0.4.3

package/README.md

@@ -5,7 +5,7 @@
 ## 安装
 
 ```bash
-npx -y modelfunction-cli@0.2.0 --version
+npx -y modelfunction-cli@0.4.3 --version
 # 或
 npm i -D modelfunction-cli
 npx mf --version
@@ -69,9 +69,10 @@ INTERNAL_LLM_KEY=... mf eval --suite mf.suite.json \
 | `mf case add` | 写入用例（默认 `source=agent`、`reviewed=false`） |
 | `mf coverage` | 每工具用例数、参数覆盖、负例比例、疑似混淆对；有 `profiles` 时按组统计 |
 | `mf lint` | 静态检查工具描述与参数 schema，以及 skills 的 name/description（不调用模型）；重复规则自动合并成一条；有 `profiles` 时给出「这些组不要合并挂载」 |
+| `mf check` | 安装门禁：一个新能力 × 已装能力（`--manifest` + `--installed`），纯静态、返回 pass/warn、不阻断；也可 `import { check } from "modelfunction-cli"` |
 | `mf compare` | 跨版本比较、干扰归因、混淆矩阵；两份报告都有分组时按组对比 |
 | `mf ablate` | 留一法：去掉某个工具再跑一遍，量化它是否干扰其他工具；`--profile` 限定在某个挂载组内 |
-| `mf cluster` | 聚类工具，建议挂载分组；参数形状拆散的同一族（如 `sessions_*`）列为「同族候选」；`--out` 把分组写成套件的 `profiles` |
+| `mf cluster` | 聚类工具，建议挂载分组；参数形状拆散的同一族（如 `sessions_*`）列为「同族候选」；并输出「族内边界清单」（每族会互抢的对 + 每个工具可用的区分词）；`--out` 把分组写成套件的 `profiles` |
 | `mf exec` | 单工具执行 + 指标（Node / Python），支持 `--allow-read/write/net`、超时、sideEffects 准入 |
 | `mf eval --execute` | 一次跑完选择 + 参数 + 运行断言（`toolInput` / `expect`） |
 | `mf sandbox check` | 探测本机可用隔离引擎与降级建议 |
@@ -101,6 +102,8 @@ mf eval --suite mf.suite.json --models internal-ds \
 
 配套的三个检查：`mf lint` 列出组间高风险对（相似工具分属不同组，合并挂载会互抢）；`mf coverage` 按组看谁还缺用例；两次 `--profile` 报告之间用 `mf compare` 看各组升降（分组定义变了会明确标注不可比）。组内还有干扰时，用 `mf ablate --profile <组> --tool <工具>` 做组内留一法，看拆掉谁最划算。
 
+`mf cluster` 还会输出**族内边界清单**：把会互抢的工具对按连通关系分成「族」，每族列出各工具名称里的独有词（名称没有独有词时退到独有参数）作为区分轴，并标出共享参数（不能当判据）。这是写给作者的动作项——每个工具补一句"何时用我、何时用对方"即可，不需要先跑模型。`--json` 的 `boundaries[]` 是该清单的结构化版本（`axes` / `sharedParams` / `pairs` / `suggestion`），平台方可以直接消费。
+
 ## MCP 配置
 
 ```json
@@ -108,7 +111,7 @@ mf eval --suite mf.suite.json --models internal-ds \
   "mcpServers": {
     "modelfunction": {
       "command": "npx",
-      "args": ["-y", "modelfunction-cli@0.2.0", "mcp"]
+      "args": ["-y", "modelfunction-cli@0.4.3", "mcp"]
     }
   }
 }
@@ -116,6 +119,10 @@ mf eval --suite mf.suite.json --models internal-ds \
 
 暴露：`scan_tools`、`list_suite`、`coverage`、`add_cases`、`run_eval`（`run_eval` 支持 `profile` 与 `repeat` 参数：传 `all` 或组名按挂载组评分，`repeat` 取多数结果）。
 
+## 契约与版本
+
+对外 JSON 字段、`check()` 返回结构、MCP 参数与退出码见 [SCHEMA.md](SCHEMA.md)，自 0.4.3 起冻结为 v1：v1 内只做加法，重命名或删除字段需 major 并提前两个 minor 或 90 天弃用。`check()` 的类型声明随包发布。
+
 ## 数据边界
 
 - 本地运行，无遥测、无服务端地址
@@ -130,7 +137,7 @@ mf eval --suite mf.suite.json --models internal-ds \
 
 ```bash
 # 1. 把 mf 挂成 MCP server
-claude mcp add modelfunction -- npx -y modelfunction-cli@0.2.0 mcp
+claude mcp add modelfunction -- npx -y modelfunction-cli@0.4.3 mcp
 ```
 
 ```text

package/SCHEMA.md

@@ -0,0 +1,200 @@
+# Schemas v1
+
+Frozen at `modelfunction-cli@0.4.3`。这里描述 CLI 与库对外的稳定契约。人类可读文本（表格、提示语）不属于契约；**JSON 字段**属于。
+
+## 兼容政策
+
+- v1 内只做**加法**：新增字段、新增命令、新增可选参数。消费方必须忽略未知字段。
+- 重命名、删除、单位/语义变化 → major 版本；至少提前 **2 个 minor 或 90 天**标记弃用。
+- `mf --version` 与包版本是唯一版本锚点；报告里不重复写 schema 版本。
+- 未复核用例（`reviewed: false`）永远不计入正式分数，这条不受版本影响。
+
+## 1. suite.json v1
+
+```json
+{
+  "name": "my-agent",
+  "description": "可选",
+  "tools": [ ... ],
+  "cases": [ ... ],
+  "skills": [ ... ],
+  "profiles": { "group-a": ["tool_x", "tool_y"] },
+  "execution": { "runtime": "node", "entry": "tools/index.mjs" }
+}
+```
+
+### tools[]
+
+两种写法：
+
+```json
+{ "name": "search_docs", "description": "…", "parameters": { "type": "object", "properties": {} } }
+{ "ref": "fixtures/tools/search_docs.json" }
+```
+
+- `name` 必填、非空、同套件内唯一。
+- `parameters` 可用 `input` 代替（function.json 兼容）。缺省为空对象 schema。
+- `descriptionSource: "runtime"`：描述由代码运行时生成，静态检查只报 info。
+- `sideEffects`: `"none" | "read" | "write" | "external"`，执行准入用。
+- `ref` 指向 function.json；读取 `name` / `description` / `input` 或 `parameters`。
+
+### cases[]
+
+```json
+{
+  "id": "c1",
+  "input": "帮我把这份文档转成 PDF",
+  "expectedTool": "convert_pdf",
+  "expectedArgs": { "path": "a.docx" },
+  "toolInput": { "path": "a.docx" },
+  "expect": { "ok": true, "contains": "pdf", "maxDurationMs": 2000 },
+  "note": "",
+  "source": "manual",
+  "reviewed": true,
+  "tags": []
+}
+```
+
+- `input` 必填；`expectedTool: null` 表示负例（不该调用任何工具）。
+- `expectedArgs` 仅在有 `expectedTool` 时可用；值为断言，支持字面量、`$contains`、`$oneOf`、`$exists`。
+- `toolInput` + `expect` 用于 `--execute`：`expect` 支持 `ok`、`contains`、`equals`、`errorType`、`maxDurationMs`、`maxPeakRssMB`。
+- `reviewed` 缺省为 `true`（手写用例）；`mf case add` 缺省写入 `source=agent`、`reviewed=false`。
+
+### skills[]
+
+字符串或对象：
+
+```json
+"pdf-report"
+{ "name": "pdf-report", "description": "生成 PDF 报告" }
+```
+
+skills 只做静态检查，不参与模型评测。
+
+### profiles
+
+组名 → 工具名数组。所有工具名必须存在；组可重叠。`mf eval --profile` 与 `mf ablate --profile` 依赖它。
+
+### execution
+
+`runtime`（`node` | `python`）、`entry`、`python`、`export`、`timeoutMs`、`allowRead`、`allowWrite`、`allowNet`。命令行参数优先于文件。
+
+## 2. 评分卡 JSON（`mf eval --json` / `--out report.json`）
+
+```json
+{
+  "suite": {
+    "name": "...", "path": "...",
+    "tools": ["..."], "cases": 12,
+    "fingerprint": "sha256:...",
+    "execution": { "runtime": "node", "engine": "node-permission", "entry": "index.mjs", "hash": "..." }
+  },
+  "models": [ { "model": "dsv4-flash", "total": 12, "reviewedTotal": 12, "selectionAccuracy": 0.83,
+               "argAccuracy": 0.9, "passRate": 0.75, "errors": 0, "p50LatencyMs": 900,
+               "p95LatencyMs": 1800, "avgCostCny": 0.001, "totalCostCny": 0.012,
+               "inputTokens": 1000, "cachedTokens": 0, "outputTokens": 200,
+               "rows": [ { "id": "c1", "expectedTool": "...", "actualTool": "...",
+                           "selectionCorrect": true, "args": { "total": 1, "matched": 1, "failures": [] },
+                           "passed": true, "reviewed": true, "source": "manual",
+                           "latencyMs": 900, "usage": { "input": 80, "output": 20 }, "error": null } ] } ],
+  "profiles": { "groups": [ ... ] }
+}
+```
+
+- 正式指标只统计 `reviewed` 行；未复核结果单独给出。
+- `--repeat` 时模型对象带 `stability`（翻转用例与多次结果分布）。
+- `--profile` 时每个组含 `profile`、`mounted`、`allInOne`、`delta`、`lifted`、`jammed`。
+- `fingerprint` 由工具与用例内容计算；`mf compare` 用它判断两份报告是否可比。
+
+## 3. 扫描输出（`mf scan`）
+
+`--json` 输出 `{ "report": {...}, "draft": {...} }`；默认写 `mf.suite.json`（draft）与 `mf.scan.json`（report）。
+
+report：`root`、`tools[]`（`name` / `description` / `parameters` / `origin` / `confidence` / `source` / `note?` / `descriptionSource?`）、`skills[]`、`mcpServers[]`（env 只保留 `envKeys`）、`probes[]`、`sources[]`、`warnings[]`。
+
+`scan --json` 在未找到任何工具时退出码为 3。
+
+## 4. lint JSON
+
+```json
+{
+  "tools": 47, "skills": 53,
+  "counts": { "error": 0, "warn": 5, "info": 12 },
+  "findings": [
+    { "severity": "warn", "code": "pair-no-boundary", "kind": "tool",
+      "tool": "tavily_search", "pair": ["tavily_search", "google_search"],
+      "message": "...", "suggestion": "..." }
+  ],
+  "profilePairs": [ { "a": "group-a", "b": "group-b", "pairs": [ ... ] } ]
+}
+```
+
+- `kind: "skill"` 时用 `skill` 字段代替 `tool`。
+- `param` 出现在参数级发现上；`pair` 出现在工具对/技能对发现上。
+- `profilePairs` 只在套件含 `profiles` 时出现。
+
+## 5. cluster JSON（`mf cluster --json`）
+
+```json
+{
+  "threshold": 0.5, "total": 47,
+  "clusters": [ { "label": "session", "tools": ["..."] } ],
+  "riskyPairs": [ { "a": "...", "b": "...", "similarity": 0.85, "basis": "structural" } ],
+  "familyHints": [ { "token": "session", "size": 6, "merged": ["..."], "loose": ["..."] } ],
+  "boundaries": [
+    { "label": "task", "size": 6, "tools": ["..."],
+      "axes": [ { "tool": "task_get", "distinct": ["get"], "paramsOnly": [] } ],
+      "sharedParams": ["taskId"],
+      "pairs": [ { "a": "task_get", "b": "task_output", "similarity": 0.65, "basis": "structural" } ],
+      "suggestion": "..." }
+  ]
+}
+```
+
+`boundaries[]` 是族内边界清单的结构化版本；`basis` 为 `lexical` / `structural` / `family`。
+
+## 6. `check()`（安装门禁）
+
+```js
+import { check } from "modelfunction-cli";
+```
+
+输入 `{ manifest, installed }`：`manifest` 是一个能力（`name` 必填，`description` 可选，`parameters` / `inputSchema` / `input` 任一为 JSON Schema；无 schema 视为 skill）。`installed` 可以是能力数组，或 `{ tools: [], skills: [] }`。
+
+返回：
+
+```json
+{
+  "verdict": "pass",
+  "summary": { "error": 0, "warn": 0, "info": 1 },
+  "findings": [ { "severity": "info", "code": "skill-pair-sibling", "subject": "feishu-wiki",
+                  "with": "feishu-doc", "message": "...", "suggestion": "..." } ],
+  "family": ["feishu-doc", "feishu-wiki"]
+}
+```
+
+- `verdict` 只有 `pass` / `warn`，**没有 fail**；质量判定不阻断安装。
+- 唯一抛错场景：`manifest.name` 缺失或为空。
+- 同步、无网络、无文件系统、无状态。类型声明见 `lib/check.d.ts`。
+
+## 7. MCP 工具
+
+| 工具 | 参数 |
+| --- | --- |
+| `scan_tools` | `root?`、`probe?`、`timeoutMs?`、`writeSuite?` |
+| `list_suite` | `suite?` |
+| `coverage` | `suite?` |
+| `add_cases` | `suite?`、`cases[]`、`source?`、`reviewed?`、`dryRun?` |
+| `run_eval` | `suite?`、`models?`、`cases?`、`profile?`、`repeat?`、`failUnder?` |
+
+返回值均为 JSON 文本。
+
+## 8. 退出码
+
+| 码 | 含义 |
+| --- | --- |
+| 0 | 成功（`mf check` 的 warn 也是 0） |
+| 1 | 输入/用法错误；`mf compare` 判定不可直接比较 |
+| 2 | `mf eval --fail-under` 未达标，或 `--fail-on-regression` 发现回退 |
+| 3 | `mf exec` 被权限策略拒绝；`mf scan --json` 未找到工具 |
+| 4 | `mf exec` 超时 |

package/lib/cases.js

@@ -241,6 +241,44 @@ export function familyScore(x, y) {
   return paramNames(x).size === 0 && paramNames(y).size === 0 ? 0.6 : 0.2;
 }
 
+// Turn a confusable pair into an authoring instruction. We do not invent the
+// semantic rule (which one wins when); we point at the dimensions the author
+// controls — the words unique to each name and the parameters only one side
+// takes — so the boundary sentence can be written without guessing.
+export function boundaryHint(x, y) {
+  const left = [...new Set(nameTokens(x.name))].filter((token) => !GENERIC_NAME_TOKENS.has(token));
+  const right = [...new Set(nameTokens(y.name))].filter((token) => !GENERIC_NAME_TOKENS.has(token));
+  const sharedName = left.filter((token) => right.includes(token)).sort();
+  const distinctName = {
+    a: left.filter((token) => !right.includes(token)).sort(),
+    b: right.filter((token) => !left.includes(token)).sort()
+  };
+  const aParams = Object.keys(x.parameters?.properties ?? {}).sort();
+  const bParams = Object.keys(y.parameters?.properties ?? {}).sort();
+  const sharedParams = aParams.filter((param) => bParams.includes(param));
+  const paramsOnly = {
+    a: aParams.filter((param) => !bParams.includes(param)),
+    b: bParams.filter((param) => !aParams.includes(param))
+  };
+
+  let axis;
+  if (distinctName.a.length > 0 || distinctName.b.length > 0) {
+    axis = `${x.name} 独有 ${distinctName.a.join("/") || "无"}，${y.name} 独有 ${distinctName.b.join("/") || "无"}`;
+  } else if (paramsOnly.a.length > 0 || paramsOnly.b.length > 0) {
+    axis = `${x.name} 要传 ${paramsOnly.a.join("/") || "无"}，${y.name} 要传 ${paramsOnly.b.join("/") || "无"}`;
+  } else {
+    axis = "各自的触发场景";
+  }
+  const shared = sharedParams.length > 0 ? `；共享参数 ${sharedParams.join("、")} 不能当判据` : "";
+  return {
+    sharedName,
+    distinctName,
+    sharedParams,
+    paramsOnly,
+    suggestion: `在 ${x.name} 和 ${y.name} 的 description 里各补一句选择条件（区分维度：${axis}${shared}），再补一条歧义用例`
+  };
+}
+
 export function suspectedPairs(tools, { threshold = PAIR_SIMILARITY, extraStop } = {}) {
   const pairs = [];
   for (let i = 0; i < tools.length; i += 1) {

package/lib/check.d.ts

@@ -0,0 +1,51 @@
+export type Severity = "error" | "warn" | "info";
+export type Verdict = "pass" | "warn";
+
+export interface Capability {
+  name: string;
+  description?: string;
+  /** JSON Schema. A capability without one is treated as a prompt-injected skill. */
+  parameters?: Record<string, unknown>;
+  /** Accepted alias for parameters, matching MCP tool shape. */
+  inputSchema?: Record<string, unknown>;
+  /** Accepted alias for parameters, matching function.json shape. */
+  input?: Record<string, unknown>;
+}
+
+export interface InstalledCapabilities {
+  tools?: Capability[];
+  skills?: Capability[];
+}
+
+export interface CheckInput {
+  manifest: Capability;
+  installed?: Capability[] | InstalledCapabilities;
+}
+
+export interface CheckFinding {
+  severity: Severity;
+  code: string;
+  subject: string;
+  param?: string;
+  /** The installed capability this pair finding is about. */
+  with?: string;
+  message: string;
+  suggestion?: string;
+}
+
+export interface CheckResult {
+  verdict: Verdict;
+  summary: { error: number; warn: number; info: number };
+  findings: CheckFinding[];
+  /** Connected family of competing installed capabilities, sorted. */
+  family?: string[];
+}
+
+/**
+ * Static install gate: judge one new capability against installed ones.
+ * No model call, no network, no file system, no state.
+ * @throws only when `manifest.name` is missing or empty.
+ */
+export declare function check(input: CheckInput): CheckResult;
+
+export declare function formatCheck(result: CheckResult): string;

package/lib/check.js

@@ -0,0 +1,118 @@
+// Install-gate entry point: judge one new capability against what is already
+// installed. Static only — no model call, no network, no file system, no state.
+// Quality findings are advisory: the verdict is pass/warn, never "block".
+import { lintSuite } from "./lint.js";
+
+export function check({ manifest, installed = [] } = {}) {
+  const target = normalizeEntry(manifest);
+  if (!target) throw new Error('check: manifest 需要非空 "name"');
+  const pool = [];
+  if (Array.isArray(installed)) pool.push(...installed);
+  else if (installed && typeof installed === "object") {
+    pool.push(...(installed.tools ?? []), ...(installed.skills ?? []));
+  }
+  const entries = pool.map(normalizeEntry).filter(Boolean);
+
+  const tools = [];
+  const skills = [];
+  for (const entry of entries) (isToolLike(entry) ? tools : skills).push(entry);
+  (isToolLike(target) ? tools : skills).push(target);
+
+  const report = lintSuite({ tools, skills });
+  const findings = report.findings
+    .filter((finding) => touches(finding, target.name))
+    .map((finding) => shape(finding, target.name));
+  const summary = { error: 0, warn: 0, info: 0 };
+  for (const finding of findings) summary[finding.severity] += 1;
+  const family = familyOf(report.findings.filter((finding) => finding.pair), target.name);
+
+  return {
+    verdict: summary.error + summary.warn > 0 ? "warn" : "pass",
+    summary,
+    findings,
+    ...(family.length > 1 ? { family } : {})
+  };
+}
+
+function normalizeEntry(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  const name = typeof entry.name === "string" ? entry.name.trim() : "";
+  if (!name) return null;
+  const parameters = entry.parameters ?? entry.inputSchema ?? entry.input ?? null;
+  return {
+    name,
+    description: typeof entry.description === "string" ? entry.description : "",
+    parameters: parameters && typeof parameters === "object" ? parameters : null
+  };
+}
+
+// A capability with a parameter schema is a tool; name + description alone is
+// a prompt-injected skill (SKILL.md form).
+function isToolLike(entry) {
+  return entry.parameters !== null;
+}
+
+function touches(finding, name) {
+  if (finding.kind === "skill") {
+    if (finding.skill === name) return true;
+    return Array.isArray(finding.pair) && finding.pair.includes(name);
+  }
+  if (finding.tool === name) return true;
+  return Array.isArray(finding.pair) && finding.pair.includes(name);
+}
+
+function shape(finding, name) {
+  const other = (finding.pair ?? []).find((item) => item !== name);
+  return {
+    severity: finding.severity,
+    code: finding.code,
+    subject: name,
+    ...(finding.param ? { param: finding.param } : {}),
+    ...(other ? { with: other } : {}),
+    message: finding.message,
+    ...(finding.suggestion ? { suggestion: finding.suggestion } : {})
+  };
+}
+
+// The connected family around the manifest — what an installer shows as
+// "these installed capabilities compete with the new one".
+function familyOf(pairs, name) {
+  const edges = new Map();
+  const link = (a, b) => {
+    if (!edges.has(a)) edges.set(a, new Set());
+    edges.get(a).add(b);
+  };
+  for (const finding of pairs) {
+    const [a, b] = finding.pair;
+    link(a, b);
+    link(b, a);
+  }
+  if (!edges.has(name)) return [name];
+  const seen = new Set([name]);
+  const queue = [name];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    for (const next of edges.get(current) ?? []) {
+      if (seen.has(next)) continue;
+      seen.add(next);
+      queue.push(next);
+    }
+  }
+  return [...seen].sort();
+}
+
+export function formatCheck(result) {
+  const lines = [
+    `verdict: ${result.verdict}（error ${result.summary.error} / warn ${result.summary.warn} / info ${result.summary.info}）`
+  ];
+  if (result.findings.length === 0) lines.push("没有发现问题");
+  for (const finding of result.findings) {
+    const param = finding.param ? `.${finding.param}` : "";
+    const withWhat = finding.with ? ` × ${finding.with}` : "";
+    lines.push(`[${finding.severity}] ${finding.code}  ${finding.subject}${param}${withWhat}`);
+    lines.push(`        ${finding.message}`);
+    if (finding.suggestion) lines.push(`        ${finding.suggestion}`);
+  }
+  if (result.family) lines.push("", `族：${result.family.join(", ")}`);
+  return lines.join("\n");
+}

package/lib/cluster.js

@@ -12,9 +12,17 @@ const FAMILY_HINT_STOP = new Set([
   "save", "load", "merge", "sync", "scan", "check", "compare", "exec", "probe"
 ]);
 
+// A pair below the clustering link but above these marks is still confusable
+// enough to need a boundary sentence: same lint threshold for wording/shape,
+// plus the stronger family scores (shared distinctive token with parameter
+// overlap, two shared tokens, or two zero-parameter tools).
+const BOUNDARY_SIMILARITY = 0.35;
+const BOUNDARY_FAMILY = 0.6;
+
 export function clusterTools(tools, { threshold = 0.5, maxSize = 10 } = {}) {
   const scores = tools.map(() => new Array(tools.length).fill(0));
   const pairs = [];
+  const edges = [];
   for (let i = 0; i < tools.length; i += 1) {
     for (let j = i + 1; j < tools.length; j += 1) {
       const { similarity, basis } = pairSimilarity(tools[i], tools[j]);
@@ -25,6 +33,9 @@ export function clusterTools(tools, { threshold = 0.5, maxSize = 10 } = {}) {
       if (link >= threshold) {
         pairs.push({ i, j, similarity, basis: family > similarity ? "family" : basis });
       }
+      if (similarity >= BOUNDARY_SIMILARITY || family >= BOUNDARY_FAMILY) {
+        edges.push({ i, j, similarity, basis, family });
+      }
     }
   }
 
@@ -70,7 +81,119 @@ export function clusterTools(tools, { threshold = 0.5, maxSize = 10 } = {}) {
     }))
     .sort((x, y) => y.similarity - x.similarity);
 
-  return { threshold, total: tools.length, clusters, riskyPairs, familyHints };
+  const boundaries = buildBoundaries(tools, edges);
+
+  return { threshold, total: tools.length, clusters, riskyPairs, familyHints, boundaries };
+}
+
+// Confusable pairs form connected components: that is the unit a platform can
+// hand to an author ("these N tools compete; here is what each must say").
+// Overlap with clusters is intentional — one asks where tools mount, the other
+// asks what still needs a sentence.
+function buildBoundaries(tools, edges) {
+  const parent = tools.map((_, index) => index);
+  const find = (index) => {
+    let root = index;
+    while (parent[root] !== root) root = parent[root];
+    while (parent[index] !== root) {
+      const next = parent[index];
+      parent[index] = root;
+      index = next;
+    }
+    return root;
+  };
+  const union = (a, b) => {
+    const rootA = find(a);
+    const rootB = find(b);
+    if (rootA !== rootB) parent[rootB] = rootA;
+  };
+  for (const edge of edges) union(edge.i, edge.j);
+
+  const groups = new Map();
+  for (const edge of edges) {
+    const root = find(edge.i);
+    const list = groups.get(root) ?? [];
+    list.push(edge);
+    groups.set(root, list);
+  }
+
+  const usedLabels = new Set();
+  const boundaries = [];
+  let position = 0;
+  for (const list of groups.values()) {
+    const memberSet = new Set();
+    for (const edge of list) {
+      memberSet.add(edge.i);
+      memberSet.add(edge.j);
+    }
+    const members = [...memberSet].sort((a, b) => tools[a].name.localeCompare(tools[b].name));
+    const label = uniqueLabel(labelFor(members.map((index) => tools[index].name)), usedLabels, position, "family");
+    position += 1;
+    const pairs = list
+      .map((edge) => ({
+        a: tools[edge.i].name,
+        b: tools[edge.j].name,
+        similarity: Number(edge.similarity.toFixed(2)),
+        basis: edge.similarity >= BOUNDARY_SIMILARITY ? (edge.basis === "structural" ? "structural" : "lexical") : "family"
+      }))
+      .sort((x, y) => y.similarity - x.similarity || x.a.localeCompare(y.a));
+    const { axes, sharedParams } = familyAxes(tools, members);
+    boundaries.push({
+      label,
+      size: members.length,
+      tools: members.map((index) => tools[index].name),
+      axes,
+      sharedParams,
+      pairs,
+      suggestion: familySuggestion(axes, sharedParams)
+    });
+  }
+
+  return boundaries.sort(
+    (x, y) => y.pairs.length - x.pairs.length || y.size - x.size || x.label.localeCompare(y.label)
+  );
+}
+
+// The dimension each tool can claim inside its family: a name word no sibling
+// uses, or failing that a parameter only it takes. A tool with neither has to
+// describe its trigger scenario — no static signal can write that sentence.
+function familyAxes(tools, members) {
+  const tokenSets = new Map();
+  const paramSets = new Map();
+  const tokenCounts = new Map();
+  const paramCounts = new Map();
+  for (const index of members) {
+    const tokens = new Set(nameTokens(tools[index].name));
+    tokenSets.set(index, tokens);
+    for (const token of tokens) tokenCounts.set(token, (tokenCounts.get(token) ?? 0) + 1);
+    const params = new Set(Object.keys(tools[index].parameters?.properties ?? {}));
+    paramSets.set(index, params);
+    for (const param of params) paramCounts.set(param, (paramCounts.get(param) ?? 0) + 1);
+  }
+  const axes = members.map((index) => ({
+    tool: tools[index].name,
+    distinct: [...tokenSets.get(index)].filter((token) => tokenCounts.get(token) === 1).sort(),
+    paramsOnly: [...paramSets.get(index)].filter((param) => paramCounts.get(param) === 1).sort()
+  }));
+  const sharedParams = [...paramCounts.entries()]
+    .filter(([, count]) => count >= 2)
+    .map(([param]) => param)
+    .sort();
+  return { axes, sharedParams };
+}
+
+function familySuggestion(axes, sharedParams) {
+  const named = axes.filter((axis) => axis.distinct.length > 0);
+  const unnamed = axes.filter((axis) => axis.distinct.length === 0);
+  const parts = [];
+  if (named.length > 0) {
+    parts.push(`用名称里的独有词作判据：${named.map((axis) => `${axis.tool}=${axis.distinct.join("/")}`).join("；")}`);
+  }
+  if (unnamed.length > 0) {
+    parts.push(`${unnamed.map((axis) => axis.tool).join("、")} 名称里没有独有词，需写明各自的触发场景`);
+  }
+  const shared = sharedParams.length > 0 ? `；共享参数 ${sharedParams.slice(0, 8).join("、")} 不能当判据` : "";
+  return `${parts.join("；")}${shared}。在每个工具的 description 里各补一句“何时用我、何时用对方”，再补一条歧义用例`;
 }
 
 function buildFamilyHints(tools, clusterOf, clusterSize) {
@@ -108,7 +231,7 @@ function buildFamilyHints(tools, clusterOf, clusterSize) {
 function labelFor(names) {
   const counts = new Map();
   for (const name of names) {
-    for (const token of String(name).toLowerCase().split(/[^a-z0-9]+/)) {
+    for (const token of nameTokens(name)) {
       if (!token || GENERIC_NAME_TOKENS.has(token)) continue;
       counts.set(token, (counts.get(token) ?? 0) + 1);
     }
@@ -120,11 +243,11 @@ function labelFor(names) {
   return best && best.count > 1 ? best.token : "";
 }
 
-function uniqueLabel(base, used, position) {
-  let label = base || `cluster-${position + 1}`;
+function uniqueLabel(base, used, position, prefix = "cluster") {
+  let label = base || `${prefix}-${position + 1}`;
   let suffix = 2;
   while (used.has(label)) {
-    label = `${base || `cluster-${position + 1}`}-${suffix}`;
+    label = `${base || `${prefix}-${position + 1}`}-${suffix}`;
     suffix += 1;
   }
   used.add(label);
@@ -154,5 +277,28 @@ export function formatClusters(result) {
       lines.push(`  [${hint.token}] ${hint.size} 个：${parts.join(" | ")}`);
     }
   }
+  if ((result.boundaries ?? []).length > 0) {
+    lines.push("", "族内边界清单（同族互抢的对，以及每个工具要补的区分词）:");
+    for (const family of result.boundaries) {
+      lines.push(`  [${family.label}] ${family.size} 个工具，${family.pairs.length} 对`);
+      const axes = family.axes.map((axis) => {
+        const label = axis.distinct.length > 0 ? axis.distinct.join("/") : axis.paramsOnly.length > 0 ? `参数 ${axis.paramsOnly.join("/")}` : "（无独有词）";
+        return `${axis.tool}=${label}`;
+      });
+      lines.push(`    区分轴：${axes.join("；")}`);
+      if (family.sharedParams.length > 0) {
+        const shown = family.sharedParams.slice(0, 8).join("、");
+        const more = family.sharedParams.length > 8 ? ` 等 ${family.sharedParams.length} 个` : "";
+        lines.push(`    共享参数：${shown}${more}（不能当判据）`);
+      }
+      const top = family.pairs.slice(0, 5);
+      const pairText = top
+        .map((pair) => `${pair.a} × ${pair.b} ${pair.similarity.toFixed(2)}${pair.basis === "family" ? "（同族）" : ""}`)
+        .join("；");
+      const rest = family.pairs.length > top.length ? `；…共 ${family.pairs.length} 对（--json 看全部）` : "";
+      lines.push(`    互抢对：${pairText}${rest}`);
+      lines.push("    → 在各自 description 里补一句“何时用我、何时用对方”（判据见区分轴），再补一条歧义用例");
+    }
+  }
   return lines.join("\n");
 }

package/lib/exec.js

@@ -3,6 +3,7 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { permissionFlag } from "./node-permission.js";
 
 const HARNESS = fileURLToPath(new URL("./runtime/harness.mjs", import.meta.url));
 const HARNESS_PY = fileURLToPath(new URL("./runtime/harness.py", import.meta.url));
@@ -57,7 +58,7 @@ export async function executeTool(options) {
         process.cwd(),
         ...(options.allowRead ?? [])
       ].map((path) => resolve(path));
-      args = ["--permission"];
+      args = [permissionFlag()];
       for (const path of dedupe(readPaths)) args.push(`--allow-fs-read=${path}`);
       if (options.allowWrite?.length) {
         for (const path of dedupe(options.allowWrite.map((item) => resolve(item)))) {

package/lib/lint.js

@@ -1,4 +1,4 @@
-import { suspectedPairs, nameTokens } from "./cases.js";
+import { suspectedPairs, nameTokens, boundaryHint } from "./cases.js";
 import { normalizeProfiles } from "./profile.js";
 
 const GENERIC_NAMES = new Set([
@@ -223,9 +223,11 @@ export function lintSuite(suite) {
         }
       }
       const reason = pair.basis === "structural" ? "名字与参数形状接近" : "描述相近";
+      const toolA = suite.tools.find((tool) => tool.name === pair.a);
+      const toolB = suite.tools.find((tool) => tool.name === pair.b);
       add("warn", "pair-no-boundary", pair.a, `与 ${pair.b} ${reason}（相似度 ${similarity}），且两边都没写“不适用于”边界，模型只能靠相似度硬猜`, {
         pair: [pair.a, pair.b],
-        suggestion: `在 ${pair.a} 和 ${pair.b} 的 description 里各写一句“不适用于什么”，并补一条歧义用例`
+        suggestion: boundaryHint(toolA, toolB).suggestion
       });
     }
   }

package/lib/node-permission.js

@@ -0,0 +1,7 @@
+// Permission Model flag renamed across Node versions: --experimental-permission
+// in 20–23.4, --permission from 23.5. Using the wrong one makes exec fail with
+// "bad option" on Node 20/22 even though the model itself is available.
+export function permissionFlag(version = process.versions.node) {
+  const [major, minor] = String(version).split(".").map(Number);
+  return major > 23 || (major === 23 && minor >= 5) ? "--permission" : "--experimental-permission";
+}

package/lib/sandbox-check.js

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { permissionFlag } from "./node-permission.js";
 
 function run(command, args, timeout = 4000) {
   const result = spawnSync(command, args, { encoding: "utf8", timeout, windowsHide: true });
@@ -20,7 +21,7 @@ export function checkSandbox() {
   const platform = process.platform;
   const nodeVersion = process.versions.node;
   const nodeMajor = Number(nodeVersion.split(".")[0]);
-  const permission = run(process.execPath, ["--permission", "-e", "0"]);
+  const permission = run(process.execPath, [permissionFlag(), "-e", "0"]);
 
   const pythonProbe = platform === "win32" ? run("python", ["--version"]) : run("python3", ["--version"]);
   const pythonFallback = pythonProbe.ok ? pythonProbe : run("python", ["--version"]);

package/lib/scan.js

@@ -50,6 +50,9 @@ const CODE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".mjs", ".cjs", ".py"]);
 // Test fixtures and mocks use the same APIs as real tool definitions, so any
 // match there is noise for a tool inventory.
 const TEST_PATH = /(^|[\\/])(__tests__|tests?)([\\/])|\.(test|spec)\.[cm]?[jt]sx?$|(^|[\\/])test_[^\\/]+\.py$|_test\.py$/i;
+// Dev harnesses shape objects like tools (`{ name: "ping", inputSchema }`) but
+// are not part of the agent's tool surface.
+const DEV_PATH = /(^|[\\/])(scripts?|bench|benchmarks?|dev|examples?|fixtures?|mocks?)([\\/])|[-_.](runner|scan|bench|fixture|mock)\.[cm]?[jt]sx?$/i;
 
 const CODE_PATTERNS = [
   { label: "registerTool", confidence: "medium", re: /registerTool\s*\(\s*["'`]([\w.-]+)["'`]/ },
@@ -238,7 +241,7 @@ export async function scanProject(root = ".") {
           });
         }
       }
-      if (!name.endsWith(".py") && !TEST_PATH.test(rel)) {
+      if (!name.endsWith(".py") && !TEST_PATH.test(rel) && !DEV_PATH.test(rel)) {
         for (const match of text.matchAll(/(?:export\s+)?const\s+([A-Z][A-Z0-9_]{2,})\s*=\s*(['"])([^'"\n]{1,200})\2/g)) {
           if (!constIndex.has(match[1])) constIndex.set(match[1], match[3]);
         }

package/mf.js

@@ -10,6 +10,7 @@ import { probeStdioServer } from "./lib/mcp-probe.js";
 import { loadAdapterTools } from "./lib/adapter-import.js";
 import { addCases, computeCoverage, formatCoverage } from "./lib/cases.js";
 import { lintSuite, formatLint } from "./lib/lint.js";
+import { check, formatCheck } from "./lib/check.js";
 import { suiteFingerprint, hashText, hashOf } from "./lib/fingerprint.js";
 import { runExecutionChecks } from "./lib/eval-exec.js";
 import { checkSandbox, formatSandboxReport } from "./lib/sandbox-check.js";
@@ -51,6 +52,7 @@ Usage:
   mf case add --suite <file> (--input <file> | stdin) [--source agent] [--reviewed] [--dry-run]
   mf coverage [--suite <file>] [--json]
   mf lint [--suite <file>] [--json]  # 静态检查 tools 与 skills，不调用模型
+  mf check --manifest <file> [--installed <file>] [--json]  # 安装门禁：新能力 × 已装能力
   mf compare <before.json> <after.json> [--json]
   mf ablate --tool <name> [--suite <file>] [--profile <group>] [--models <ids>] [--json]
   mf cluster [--suite <file>] [--threshold <0.5>] [--max-size <10>] [--out <file>] [--json]  # 建议挂载分组 + 同族候选
@@ -425,6 +427,19 @@ export async function runSandboxCheck(options, io = console) {
   return 0;
 }
 
+// Advisory install gate: static only, never blocks. Exit code stays 0 for a
+// warn verdict so a platform can log it without failing the install.
+export async function runCheck(options, io = console) {
+  if (!options.manifest) throw new Error("--manifest <file> 必填（新能力的 [name, description, parameters?]）");
+  const manifest = JSON.parse(await readFile(resolve(options.manifest), "utf8"));
+  const installed = options.installed
+    ? JSON.parse(await readFile(resolve(options.installed), "utf8"))
+    : [];
+  const result = check({ manifest, installed });
+  io.log(options.json ? JSON.stringify(result, null, 2) : formatCheck(result));
+  return 0;
+}
+
 export async function runLint(options, io = console) {
   const suite = await loadSuite(resolve(options.suite ?? DEFAULT_SUITE), {
     allowEmptyCases: true,
@@ -669,6 +684,8 @@ function parseArgs(argv) {
     reviewed: false,
     dryRun: false,
     tool: null,
+    manifest: null,
+    installed: null,
     threshold: 0.5,
     maxSize: 10,
     baseline: null,
@@ -728,6 +745,8 @@ function parseArgs(argv) {
       case "--reviewed": options.reviewed = true; break;
       case "--dry-run": options.dryRun = true; break;
       case "--tool": options.tool = value(); break;
+      case "--manifest": options.manifest = resolve(value()); break;
+      case "--installed": options.installed = resolve(value()); break;
       case "--threshold": {
         const raw = Number(value());
         if (!Number.isFinite(raw) || raw <= 0 || raw > 1) throw new Error("--threshold expects a ratio between 0 and 1");
@@ -821,7 +840,7 @@ if (isMain) {
     }
   } else if (argv.length === 0 || argv[0] === "help" || argv[0] === "-h" || argv[0] === "--help") {
     process.stdout.write(USAGE);
-  } else if (!["eval", "scan", "case", "coverage", "lint", "ablate", "cluster", "exec"].includes(argv[0])) {
+  } else if (!["eval", "scan", "case", "coverage", "lint", "check", "ablate", "cluster", "exec"].includes(argv[0])) {
     process.stderr.write(`unknown command "${argv[0]}"\n\n${USAGE}`);
     process.exit(1);
   } else if (argv[0] === "case" && argv[1] !== "add") {
@@ -844,6 +863,8 @@ if (isMain) {
               ? await runCoverage(options)
               : argv[0] === "lint"
                 ? await runLint(options)
+                : argv[0] === "check"
+                ? await runCheck(options)
                 : argv[0] === "ablate"
                   ? await runAblate(options)
                   : argv[0] === "cluster"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelfunction-cli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
   "license": "MIT",
   "description": "mf — function-calling accuracy scorecard for AI agents",
@@ -22,15 +22,26 @@
     "fixtures",
     "skills",
     "README.md",
+    "SCHEMA.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test --test-concurrency=1 \"test/**/*.test.js\"",
+    "test": "node --test --test-concurrency=1",
+    "golden": "node scripts/golden.js",
+    "golden:update": "node scripts/golden.js --update",
+    "verify": "npm test && npm pack --dry-run",
     "eval": "node mf.js eval",
     "eval:mock": "node mf.js eval --models mock --show-cases",
     "pack:check": "npm pack --dry-run",
     "prepublishOnly": "npm test"
   },
+  "types": "./lib/check.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/check.d.ts",
+      "default": "./lib/check.js"
+    }
+  },
   "engines": {
     "node": ">=20"
   },