modelfunction-cli 0.5.1 → 0.5.3

package/README.md

@@ -5,7 +5,7 @@
 ## 安装
 
 ```bash
-npx -y modelfunction-cli@0.5.0 --version
+npx -y modelfunction-cli@0.5.1 --version
 # 或
 npm i -D modelfunction-cli
 npx mf --version
@@ -81,7 +81,7 @@ INTERNAL_LLM_KEY=... mf eval --suite mf.suite.json \
 | `mf coverage` | 每工具用例数、参数覆盖、负例比例、疑似混淆对；有 `profiles` 时按组统计 |
 | `mf audit` | 一次静态审计：lint + 混淆族边界 + 用例覆盖 + 挂载检查，输出可转发的 Markdown/JSON；不调用模型 |
 | `mf lint` | 静态检查工具描述与参数 schema，以及 skills 的 name/description（不调用模型）；重复规则自动合并成一条；有 `profiles` 时给出「这些组不要合并挂载」 |
-| `mf check` | 安装门禁：一个新能力 × 已装能力（`--manifest` + `--installed`），纯静态、返回 pass/warn、不阻断；也可 `import { check } from "modelfunction-cli"` |
+| `mf check` | 安装门禁：一个或一包新能力 × 已装能力（`--manifest` / `--manifests` + `--installed`），纯静态、返回 pass/warn、不阻断；门禁语境只对混淆对/必填来源/结构性错误报 warn，其余降 info；也可 `import { check, checkMany } from "modelfunction-cli"` |
 | `mf compare` | 跨版本比较、干扰归因、混淆矩阵；两份报告都有分组时按组对比 |
 | `mf ablate` | 留一法：去掉某个工具再跑一遍，量化它是否干扰其他工具；`--profile` 限定在某个挂载组内 |
 | `mf cluster` | 聚类工具，建议挂载分组；参数形状拆散的同一族（如 `sessions_*`）列为「同族候选」；并输出「族内边界清单」（每族会互抢的对 + 每个工具可用的区分词）；`--out` 把分组写成套件的 `profiles` |
@@ -126,19 +126,19 @@ mf eval --suite mf.suite.json --models internal-ds \
   "mcpServers": {
     "modelfunction": {
       "command": "npx",
-      "args": ["-y", "modelfunction-cli@0.5.0", "mcp"]
+      "args": ["-y", "modelfunction-cli@0.5.1", "mcp"]
     }
   }
 }
 ```
 
-暴露：`scan_tools`、`list_suite`、`coverage`、`add_cases`、`run_eval`（`run_eval` 支持 `profile` 与 `repeat` 参数：传 `all` 或组名按挂载组评分，`repeat` 取多数结果）。
+暴露：`scan_tools`、`list_suite`、`coverage`、`audit`、`lint`、`check`、`cluster`、`compare`、`add_cases`、`run_eval`（`run_eval` 支持 `profile`、`repeat`、`maxCost`、`progress`）。`lint`/`check`/`cluster`/`compare` 都是静态操作，不调用模型；`check` 就是安装门禁，Agent 可直接传入 manifest 与 installed。
 
 ## 契约与版本
 
 对外 JSON 字段、`check()` 返回结构、MCP 参数与退出码见 [SCHEMA.md](SCHEMA.md)，自 0.4.3 起冻结为 v1：v1 内只做加法，重命名或删除字段需 major 并提前两个 minor 或 90 天弃用。`check()` 的类型声明随包发布。
 
-npm 已发布 `0.5.0`（凭证与本地反馈渠道）；`0.5.1` 待发布，合并开发改动：usage `ci` 标记与 local/ci 统计、eval `--progress`/`--max-cost`、`mf audit` 组合审计、`scan --probe` 支持 streamable HTTP。示例固定 `@0.5.0`，发布后统一升级。
+`0.5.2` 已发布到 npm：含凭证与本地反馈、usage `ci` 标记、eval `--progress`/`--max-cost`、`mf audit`、`scan --probe` streamable HTTP、MCP 静态工具 `lint`/`check`/`cluster`/`compare`、`checkMany` 一包批量检查，门禁 warn 只保留混淆对/必填来源/结构性错误。本仓库 `0.5.3` 待发布：静态规则性能（真实 100 能力清单 `checkMany` 471ms→40ms，550 能力 9.6s→2.1s，输出与 golden 一致），以及 `installed` 形状校验（接受 `mf scan --json` 输出，无法识别时报错而不是静默返回假 pass）和 `profiles` 兼容平台形态（对象或 `[{agentType, tools, skills}]` 数组）。示例统一使用 `@0.5.2`。
 
 ## 数据边界
 
@@ -167,7 +167,7 @@ mf feedback --out out.json  # 导出脱敏反馈包（聚合值，不含原始
 
 ```bash
 # 1. 把 mf 挂成 MCP server
-claude mcp add modelfunction -- npx -y modelfunction-cli@0.5.0 mcp
+claude mcp add modelfunction -- npx -y modelfunction-cli@0.5.1 mcp
 ```
 
 ```text

package/SCHEMA.md

@@ -73,7 +73,7 @@ skills 只做静态检查，不参与模型评测。
 
 ### profiles
 
-组名 → 工具名数组。所有工具名必须存在；组可重叠。`mf eval --profile` 与 `mf ablate --profile` 依赖它。
+组名 → 工具名数组（`{ "group": ["tool", ...] }`）。也接受平台常见的两种形态：对象 `{ "0": { agentType, tools, skills } }` 与数组 `[{ agentType, tools, skills }]`，组名依次取 `name` → `agentType` → 键/下标；`skills` 字段目前被忽略（profiles 只用于工具挂载与 eval 分组）。所有工具名必须存在；组可重叠，组名不可重复。`mf eval --profile` 与 `mf ablate --profile` 依赖它。
 
 ### execution
 
@@ -112,7 +112,7 @@ skills 只做静态检查，不参与模型评测。
 
 report：`root`、`tools[]`（`name` / `description` / `parameters` / `origin` / `confidence` / `source` / `note?` / `descriptionSource?`）、`skills[]`、`mcpServers[]`（env 只保留 `envKeys`，headers 只保留 `headerKeys`；URL 去掉 userinfo / query / hash）、`probes[]`（`server` / `ok` / `toolCount?` / `tools?` / `error?`）、`sources[]`、`warnings[]`。`--probe` 支持 stdio 与 streamable HTTP 两种传输。
 
-`scan --json` 在未找到任何工具时退出码为 3。
+`scan --json` 在工具与 skill 都未找到时退出码为 3（只有 skill 也算有结果，退出 0）。
 
 ## 4. lint JSON
 
@@ -159,7 +159,7 @@ report：`root`、`tools[]`（`name` / `description` / `parameters` / `origin` /
 import { check } from "modelfunction-cli";
 ```
 
-输入 `{ manifest, installed }`：`manifest` 是一个能力（`name` 必填，`description` 可选，`parameters` / `inputSchema` / `input` 任一为 JSON Schema；无 schema 视为 skill）。`installed` 可以是能力数组，或 `{ tools: [], skills: [] }`。
+输入 `{ manifest, installed }`：`manifest` 是一个能力（`name` 必填，`description` 可选，`parameters` / `inputSchema` / `input` 任一为 JSON Schema；无 schema 视为 skill）。`installed` 可以是能力数组、`{ tools: [], skills: [] }`，或直接传 `mf scan --json` 的输出（能力在 `report` 下）。空对象视为没有已装能力；其他无法识别的形状会抛错，避免静默返回假的 `pass`。
 
 返回：
 
@@ -174,8 +174,37 @@ import { check } from "modelfunction-cli";
 ```
 
 - `verdict` 只有 `pass` / `warn`，**没有 fail**；质量判定不阻断安装。
-- 唯一抛错场景：`manifest.name` 缺失或为空。
+- **严重度策略（门禁语境）**：只有会改变模型行为的规则保持原等级——`desc-missing`、`param-type-missing`（error），`required-unsourced`、`pair-no-boundary`、`skill-pair-no-boundary`（warn）；描述、命名、必填数量等质量规则降为 `info`，避免成熟工具集每次安装都告警。`mf lint` 不受影响，仍输出原始严重度。
+- 抛错场景：`manifest.name` 缺失或为空；`installed` 不是上述三种形状之一（空对象仍视为无已装能力）。
 - 同步、无网络、无文件系统、无状态。类型声明见 `lib/check.d.ts`。
+- 性能（0.5.3）：每个能力只分词一次，且只比较涉及新能力的对。真实 100 能力清单（53 新 + 47 已装）约 40–50ms，47 工具对 53 skill 约 25ms；550 个高度同质的合成最坏情况约 2s。
+
+批量（一次安装一包）：
+
+```js
+import { checkMany } from "modelfunction-cli";
+const result = checkMany({ manifests: [/* ... */], installed: [/* ... */] });
+```
+
+返回 `{ verdict, summary, items, results[] }`：
+
+```json
+{
+  "verdict": "warn",
+  "summary": { "error": 0, "warn": 1, "info": 0 },
+  "items": 2,
+  "results": [
+    { "name": "gitcrawl", "verdict": "warn", "summary": { "error": 0, "warn": 1, "info": 0 },
+      "findings": [ { "severity": "warn", "code": "skill-pair-no-boundary", "subject": "gitcrawl",
+                      "with": "tag-duplicate-prs-issues", "message": "...", "suggestion": "..." } ],
+      "family": ["gitcrawl", "tag-duplicate-prs-issues"] },
+    { "name": "tag-duplicate-prs-issues", "verdict": "warn", "summary": { "error": 0, "warn": 1, "info": 0 },
+      "findings": [ /* 同一对，subject 为自身 */ ], "family": ["gitcrawl", "tag-duplicate-prs-issues"] }
+  ]
+}
+```
+
+`summary` 按 subject/with 去重（同一对只计一次）；`results[]` 保留与该能力相关的全部发现（pair 会出现在双方）。`manifests` 为空、某项缺 name、名称重复时抛错。CLI：`mf check --manifests pack.json [--installed installed.json] [--json]`。
 
 ## 7. MCP 工具
 
@@ -185,6 +214,10 @@ import { check } from "modelfunction-cli";
 | `list_suite` | `suite?` |
 | `coverage` | `suite?` |
 | `audit` | `suite?` |
+| `lint` | `suite?` |
+| `check` | `manifest`（对象）、`installed?`（数组或 `{tools,skills}`） |
+| `cluster` | `suite?`、`threshold?`、`maxSize?` |
+| `compare` | `before`、`after`（评分卡 JSON 路径） |
 | `add_cases` | `suite?`、`cases[]`、`source?`、`reviewed?`、`dryRun?` |
 | `run_eval` | `suite?`、`models?`、`cases?`、`profile?`、`repeat?`、`failUnder?`、`maxCost?`、`progress?` |
 
@@ -197,7 +230,7 @@ import { check } from "modelfunction-cli";
 | 0 | 成功（`mf check` 的 warn 也是 0） |
 | 1 | 输入/用法错误；`mf compare` 判定不可直接比较 |
 | 2 | `mf eval --fail-under` 未达标、`--fail-on-regression` 发现回退，或 `--max-cost` 超限 |
-| 3 | `mf exec` 被权限策略拒绝；`mf scan --json` 未找到工具 |
+| 3 | `mf exec` 被权限策略拒绝；`mf scan --json` 未找到工具或 skill |
 | 4 | `mf exec` 超时 |
 
 ## 9. 本地文件（0.5.0 起）

package/lib/cases.js

@@ -207,38 +207,52 @@ export function formatCoverage(report) {
   return lines.join("\n");
 }
 
-export function pairSimilarity(x, y, { extraStop } = {}) {
-  const a = tokens(`${x.name} ${x.description}`, extraStop);
-  const b = tokens(`${y.name} ${y.description}`, extraStop);
-  const union = new Set([...a, ...b]);
-  let lexical = 0;
-  if (union.size > 0) {
-    let shared = 0;
-    for (const token of union) if (a.has(token) && b.has(token)) shared += 1;
-    lexical = shared / union.size;
-  }
-  const structural = structuralScore(x, y);
+// O(n²) callers prepare each capability once; the pair loop then only compares
+// sets. Tokenizing inside the loop made a 550-capability gate take ~14s.
+export function prepareItem(item, { extraStop } = {}) {
+  const names = nameTokens(item.name).filter((token) => !GENERIC_NAME_TOKENS.has(token));
+  return {
+    name: item.name,
+    tokens: tokens(`${item.name} ${item.description}`, extraStop),
+    nameTokens: names,
+    nameTokenSet: new Set(names),
+    params: paramNames(item),
+    required: new Set(item.parameters?.required ?? [])
+  };
+}
+
+export function pairSimilarityPrepared(a, b) {
+  const shared = intersectionSize(a.tokens, b.tokens);
+  const union = a.tokens.size + b.tokens.size - shared;
+  const lexical = union > 0 ? shared / union : 0;
+  const structural = intersects(a.nameTokenSet, b.nameTokenSet) ? structuralScorePrepared(a, b) : 0;
   return {
     similarity: Math.max(lexical, structural),
     basis: structural > lexical ? "structural" : "lexical"
   };
 }
 
+export function pairSimilarity(x, y, { extraStop } = {}) {
+  return pairSimilarityPrepared(prepareItem(x, { extraStop }), prepareItem(y, { extraStop }));
+}
+
 // Clustering wants "same family" (alarm_query / alarm_ack belong to one agent),
 // which is looser than "confusable" (lint's question). Shared name token plus
 // any parameter overlap is enough to belong together; two shared tokens are
 // enough on their own (fault_alarm_query / fault_alarm_ack take different ids).
 // One shared token with disjoint params is not: cross-domain tools often share
 // a bare verb (query / list) and nothing else.
-export function familyScore(x, y) {
-  const left = nameTokens(x.name).filter((token) => !GENERIC_NAME_TOKENS.has(token));
-  const right = nameTokens(y.name).filter((token) => !GENERIC_NAME_TOKENS.has(token));
-  const shared = left.filter((token) => right.includes(token));
-  if (shared.length === 0) return 0;
-  const paramOverlap = jaccard(paramNames(x), paramNames(y));
+export function familyScorePrepared(x, y) {
+  const shared = intersectionSize(x.nameTokenSet, y.nameTokenSet);
+  if (shared === 0) return 0;
+  const paramOverlap = jaccard(x.params, y.params);
   if (paramOverlap > 0) return 0.8;
-  if (shared.length >= 2) return 0.7;
-  return paramNames(x).size === 0 && paramNames(y).size === 0 ? 0.6 : 0.2;
+  if (shared >= 2) return 0.7;
+  return x.params.size === 0 && y.params.size === 0 ? 0.6 : 0.2;
+}
+
+export function familyScore(x, y) {
+  return familyScorePrepared(prepareItem(x), prepareItem(y));
 }
 
 // Turn a confusable pair into an authoring instruction. We do not invent the
@@ -280,12 +294,13 @@ export function boundaryHint(x, y) {
 }
 
 export function suspectedPairs(tools, { threshold = PAIR_SIMILARITY, extraStop } = {}) {
+  const prepared = tools.map((tool) => prepareItem(tool, { extraStop }));
   const pairs = [];
-  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], { extraStop });
+  for (let i = 0; i < prepared.length; i += 1) {
+    for (let j = i + 1; j < prepared.length; j += 1) {
+      const { similarity, basis } = pairSimilarityPrepared(prepared[i], prepared[j]);
       if (similarity >= threshold) {
-        pairs.push({ a: tools[i].name, b: tools[j].name, similarity, basis });
+        pairs.push({ a: prepared[i].name, b: prepared[j].name, similarity, basis });
       }
     }
   }
@@ -296,20 +311,13 @@ export function suspectedPairs(tools, { threshold = PAIR_SIMILARITY, extraStop }
 // parameter shape confuse the model even when the wording differs, which the
 // lexical score alone misses. Name order is unreliable: `tavily_search` leads
 // with the vendor, `search_docs` with the action.
-function structuralScore(x, y) {
-  const left = nameTokens(x.name).filter((token) => !GENERIC_NAME_TOKENS.has(token));
-  const right = nameTokens(y.name).filter((token) => !GENERIC_NAME_TOKENS.has(token));
-  const sharedName = left.some((token) => right.includes(token));
+function structuralScorePrepared(x, y) {
+  const sharedName = x.nameTokens.some((token) => y.nameTokens.includes(token));
   if (!sharedName) return 0;
-  const params = paramNames(x);
-  const otherParams = paramNames(y);
-  if (params.size === 0 && otherParams.size === 0) return 0;
-  const paramOverlap = jaccard(params, otherParams);
+  if (x.params.size === 0 && y.params.size === 0) return 0;
+  const paramOverlap = jaccard(x.params, y.params);
   if (paramOverlap < 0.34) return 0;
-  const requiredOverlap = jaccard(
-    new Set(x.parameters?.required ?? []),
-    new Set(y.parameters?.required ?? [])
-  );
+  const requiredOverlap = jaccard(x.required, y.required);
   return 0.5 + 0.5 * (0.6 * paramOverlap + 0.4 * requiredOverlap);
 }
 
@@ -340,10 +348,26 @@ function paramNames(tool) {
 
 function jaccard(a, b) {
   if (a.size === 0 && b.size === 0) return 1;
-  const union = new Set([...a, ...b]);
+  const shared = intersectionSize(a, b);
+  return shared / (a.size + b.size - shared);
+}
+
+// Iterate the smaller set; avoids allocating a union Set for every pair in the
+// O(n²) loops.
+function intersectionSize(a, b) {
+  const small = a.size <= b.size ? a : b;
+  const large = small === a ? b : a;
   let shared = 0;
-  for (const item of union) if (a.has(item) && b.has(item)) shared += 1;
-  return shared / union.size;
+  for (const item of small) if (large.has(item)) shared += 1;
+  return shared;
+}
+
+function intersects(a, b) {
+  if (a.size === 0 || b.size === 0) return false;
+  const small = a.size <= b.size ? a : b;
+  const large = small === a ? b : a;
+  for (const item of small) if (large.has(item)) return true;
+  return false;
 }
 
 function tokens(text, extraStop) {

package/lib/check.d.ts

@@ -17,12 +17,22 @@ export interface InstalledCapabilities {
   skills?: Capability[];
 }
 
+/** `mf scan --json` output; its capabilities live under `report`. */
+export interface ScanReport {
+  report: InstalledCapabilities;
+}
+
 export interface CheckInput {
   manifest: Capability;
-  installed?: Capability[] | InstalledCapabilities;
+  installed?: Capability[] | InstalledCapabilities | ScanReport;
 }
 
 export interface CheckFinding {
+  /**
+   * Install-gate view: only behavior-changing findings keep warn/error
+   * (selection conflicts, unsourced required params, schema errors).
+   * Description and naming rules are reported as info so mature tools pass.
+   */
   severity: Severity;
   code: string;
   subject: string;
@@ -41,11 +51,39 @@ export interface CheckResult {
   family?: string[];
 }
 
+export interface CheckManyInput {
+  manifests: Capability[];
+  installed?: Capability[] | InstalledCapabilities | ScanReport;
+}
+
+export interface CheckItemResult extends CheckResult {
+  name: string;
+}
+
+export interface CheckManyResult {
+  verdict: Verdict;
+  /** Deduplicated by subject/with; per-item summaries are in results[]. */
+  summary: { error: number; warn: number; info: number };
+  items: number;
+  results: CheckItemResult[];
+}
+
 /**
  * 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.
+ * @throws when `manifest.name` is missing or empty, or `installed` is neither
+ * an array, `{ tools, skills }`, nor an `mf scan --json` report.
  */
 export declare function check(input: CheckInput): CheckResult;
 
+/**
+ * Batch install gate: judge a pack of new capabilities against installed ones
+ * and against each other.
+ * @throws when manifests is empty, an item lacks a name, names are duplicated,
+ * or `installed` is not an accepted shape.
+ */
+export declare function checkMany(input: CheckManyInput): CheckManyResult;
+
 export declare function formatCheck(result: CheckResult): string;
+
+export declare function formatCheckMany(result: CheckManyResult): string;

package/lib/check.js

@@ -1,4 +1,4 @@
-// Install-gate entry point: judge one new capability against what is already
+// Install-gate entry point: judge new capabilities 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";
@@ -6,32 +6,115 @@ 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 { results } = evaluateTargets([target], installed);
+  const [result] = results;
+  return {
+    verdict: result.verdict,
+    summary: result.summary,
+    findings: result.findings,
+    ...(result.family ? { family: result.family } : {})
+  };
+}
+
+// Installers usually apply a pack at once: new skills must be checked against
+// installed ones AND against each other.
+export function checkMany({ manifests, installed = [] } = {}) {
+  if (!Array.isArray(manifests) || manifests.length === 0) {
+    throw new Error("checkMany: manifests 需要非空数组");
+  }
+  const targets = manifests.map((entry) => normalizeEntry(entry));
+  if (targets.some((target) => target === null)) {
+    throw new Error('checkMany: 每个 manifest 都需要非空 "name"');
   }
+  const names = new Set();
+  for (const target of targets) {
+    if (names.has(target.name)) throw new Error(`checkMany: duplicate name "${target.name}"`);
+    names.add(target.name);
+  }
+  const { results } = evaluateTargets(targets, installed);
+  return {
+    verdict: results.some((item) => item.verdict === "warn") ? "warn" : "pass",
+    summary: uniqueSummary(results),
+    items: results.length,
+    results
+  };
+}
+
+// A gate that silently ignores a mis-shaped `installed` returns a false pass —
+// the worst failure mode for an install check. Accept the array and
+// {tools,skills} forms, plus `mf scan --json` output (wrapped in `report`);
+// anything else non-empty is an input error.
+function installedPool(installed) {
+  if (installed == null) return [];
+  if (Array.isArray(installed)) return installed;
+  if (typeof installed !== "object") {
+    throw new Error("installed 需要能力数组、{ tools, skills } 或 mf scan --json 的 report");
+  }
+  if (Object.keys(installed).length === 0) return [];
+  const source =
+    installed.report && typeof installed.report === "object" ? installed.report : installed;
+  const tools = source.tools ?? [];
+  const skills = source.skills ?? [];
+  if (!Array.isArray(tools) || !Array.isArray(skills)) {
+    throw new Error("installed.tools / installed.skills 必须是数组");
+  }
+  if (!Array.isArray(source.tools) && !Array.isArray(source.skills)) {
+    throw new Error("installed 需要能力数组、{ tools, skills } 或 mf scan --json 的 report");
+  }
+  return [...tools, ...skills];
+}
+
+function evaluateTargets(targets, installed) {
+  const pool = installedPool(installed);
   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);
+  for (const target of targets) (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);
+  // The gate only reports findings touching the new capabilities; skipping
+  // installed × installed pairs keeps a 500-capability pool linear-ish.
+  const pairScope = new Set(targets.map((target) => target.name));
+  const report = lintSuite({ tools, skills }, { pairScope });
+  const pairFindings = report.findings.filter((finding) => finding.pair);
+  const results = targets.map((target) => {
+    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(pairFindings, target.name);
+    return {
+      name: target.name,
+      verdict: summary.error + summary.warn > 0 ? "warn" : "pass",
+      summary,
+      findings,
+      ...(family.length > 1 ? { family } : {})
+    };
+  });
+  return { results };
+}
 
-  return {
-    verdict: summary.error + summary.warn > 0 ? "warn" : "pass",
-    summary,
-    findings,
-    ...(family.length > 1 ? { family } : {})
-  };
+// A pair finding touches both items, so the batch summary is deduped by
+// subject/with; per-item summaries keep the same finding under each item.
+function uniqueSummary(results) {
+  const seen = new Map();
+  for (const result of results) {
+    for (const finding of result.findings) {
+      const key = [
+        finding.code,
+        finding.severity,
+        finding.subject,
+        finding.with ?? "",
+        finding.param ?? ""
+      ].join("|");
+      if (!seen.has(key)) seen.set(key, finding);
+    }
+  }
+  const summary = { error: 0, warn: 0, info: 0 };
+  for (const finding of seen.values()) summary[finding.severity] += 1;
+  return summary;
 }
 
 function normalizeEntry(entry) {
@@ -42,6 +125,11 @@ function normalizeEntry(entry) {
   return {
     name,
     description: typeof entry.description === "string" ? entry.description : "",
+    // Scan marks descriptions assembled at runtime; without this the gate
+    // treats every Claude-Code-style tool as "description missing".
+    ...(typeof entry.descriptionSource === "string"
+      ? { descriptionSource: entry.descriptionSource }
+      : {}),
     parameters: parameters && typeof parameters === "object" ? parameters : null
   };
 }
@@ -61,10 +149,22 @@ function touches(finding, name) {
   return Array.isArray(finding.pair) && finding.pair.includes(name);
 }
 
+// An install gate should only warn about things that change model behavior:
+// selection conflicts, unsourceable required params, and hard schema errors.
+// Description and naming rules stay informative — otherwise every mature
+// gateway tool warns on install and the signal becomes noise.
+const GATE_CRITICAL_CODES = new Set([
+  "desc-missing",
+  "param-type-missing",
+  "required-unsourced",
+  "pair-no-boundary",
+  "skill-pair-no-boundary"
+]);
+
 function shape(finding, name) {
   const other = (finding.pair ?? []).find((item) => item !== name);
   return {
-    severity: finding.severity,
+    severity: GATE_CRITICAL_CODES.has(finding.code) ? finding.severity : "info",
     code: finding.code,
     subject: name,
     ...(finding.param ? { param: finding.param } : {}),
@@ -101,18 +201,41 @@ function familyOf(pairs, name) {
   return [...seen].sort();
 }
 
+function findingLines(finding) {
+  const param = finding.param ? `.${finding.param}` : "";
+  const withWhat = finding.with ? ` × ${finding.with}` : "";
+  const lines = [
+    `[${finding.severity}] ${finding.code}  ${finding.subject}${param}${withWhat}`,
+    `        ${finding.message}`
+  ];
+  if (finding.suggestion) lines.push(`        ${finding.suggestion}`);
+  return lines;
+}
+
 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}`);
-  }
+  for (const finding of result.findings) lines.push(...findingLines(finding));
   if (result.family) lines.push("", `族：${result.family.join(", ")}`);
   return lines.join("\n");
 }
+
+export function formatCheckMany(result) {
+  const lines = [
+    `verdict: ${result.verdict}（${result.items} 个新能力；去重后 error ${result.summary.error} / warn ${result.summary.warn} / info ${result.summary.info}）`
+  ];
+  result.results.forEach((item, index) => {
+    lines.push(
+      "",
+      `[${index + 1}] ${item.name}  ${item.verdict}（error ${item.summary.error} / warn ${item.summary.warn} / info ${item.summary.info}）`
+    );
+    if (item.findings.length === 0) lines.push("    没有发现问题");
+    for (const finding of item.findings) {
+      for (const line of findingLines(finding)) lines.push(`    ${line}`);
+    }
+    if (item.family) lines.push(`    族：${item.family.join(", ")}`);
+  });
+  return lines.join("\n");
+}

package/lib/cluster.js

@@ -1,4 +1,10 @@
-import { pairSimilarity, familyScore, nameTokens, GENERIC_NAME_TOKENS } from "./cases.js";
+import {
+  prepareItem,
+  pairSimilarityPrepared,
+  familyScorePrepared,
+  nameTokens,
+  GENERIC_NAME_TOKENS
+} from "./cases.js";
 
 // A shared domain noun ("session", "goal", "tool") says these tools serve one
 // purpose even when their verbs and parameter shapes differ — exactly what
@@ -21,12 +27,13 @@ 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 prepared = tools.map((tool) => prepareItem(tool));
   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]);
-      const family = familyScore(tools[i], tools[j]);
+      const { similarity, basis } = pairSimilarityPrepared(prepared[i], prepared[j]);
+      const family = familyScorePrepared(prepared[i], prepared[j]);
       const link = Math.max(similarity, family);
       scores[i][j] = link;
       scores[j][i] = link;

package/lib/lint.js

@@ -57,7 +57,12 @@ const BOUNDARY_HINT = /(不适用|不要用于|不用于|不能用于|而非|区
 // Chinese descriptions are compared as bigrams, so mid-0.3s similarity is noise.
 const NO_BOUNDARY_SIMILARITY = 0.5;
 
-export function lintSuite(suite) {
+// `pairScope` (a Set of names) is for incremental gates: only emit pair
+// findings that touch one of the new capabilities. Installed × installed pairs
+// are computed and then discarded by the caller, which dominates large sets.
+export function lintSuite(suite, { pairScope } = {}) {
+  const inScope = (pair) => !pairScope || pairScope.has(pair.a) || pairScope.has(pair.b);
+  const toolByName = new Map(suite.tools.map((tool) => [tool.name, tool]));
   const findings = [];
   const add = (severity, code, tool, message, extra = {}) =>
     findings.push({ severity, code, kind: "tool", tool, message, ...extra });
@@ -205,9 +210,10 @@ export function lintSuite(suite) {
   }
 
   for (const pair of suspectedPairs(suite.tools)) {
+    if (!inScope(pair)) continue;
     const similarity = pair.similarity.toFixed(2);
     const declaresBoundary = [pair.a, pair.b].some((name) => {
-      const tool = suite.tools.find((item) => item.name === name);
+      const tool = toolByName.get(name);
       return BOUNDARY_HINT.test(tool?.description ?? "");
     });
     if (declaresBoundary) {
@@ -223,8 +229,8 @@ 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);
+      const toolA = toolByName.get(pair.a);
+      const toolB = toolByName.get(pair.b);
       add("warn", "pair-no-boundary", pair.a, `与 ${pair.b} ${reason}（相似度 ${similarity}），且两边都没写“不适用于”边界，模型只能靠相似度硬猜`, {
         pair: [pair.a, pair.b],
         suggestion: boundaryHint(toolA, toolB).suggestion
@@ -236,6 +242,7 @@ export function lintSuite(suite) {
   // question is narrower than for tools: is the description specific enough to
   // be triggered, and does it collide with another installed skill?
   const skills = suite.skills ?? [];
+  const skillByName = new Map(skills.map((skill) => [skill.name, skill]));
   for (const skill of skills) {
     const description = String(skill.description ?? "").trim();
     if (!description) {
@@ -258,9 +265,10 @@ export function lintSuite(suite) {
     threshold: SKILL_PAIR_SIMILARITY,
     extraStop: SKILL_BOILERPLATE
   })) {
+    if (!inScope(pair)) continue;
     const similarity = pair.similarity.toFixed(2);
     const declaresBoundary = [pair.a, pair.b].some((name) => {
-      const skill = skills.find((item) => item.name === name);
+      const skill = skillByName.get(name);
       return BOUNDARY_HINT.test(skill?.description ?? "");
     });
     // Same-vendor siblings ("feishu-doc" / "feishu-wiki") share the vendor token

package/lib/mcp-server.js

@@ -11,6 +11,10 @@ import { writeFileAtomic } from "./fsutil.js";
 import { probeStdioServer, probeHttpServer } from "./mcp-probe.js";
 import { addCases, computeCoverage } from "./cases.js";
 import { auditSuite } from "./audit.js";
+import { check, checkMany } from "./check.js";
+import { lintSuite } from "./lint.js";
+import { clusterTools } from "./cluster.js";
+import { compareScorecards } from "./compare.js";
 
 const MF_PATH = fileURLToPath(new URL("../mf.js", import.meta.url));
 const PACKAGE_JSON = new URL("../package.json", import.meta.url);
@@ -125,6 +129,78 @@ export async function startMcpServer() {
       )
   );
 
+  server.registerTool(
+    "lint",
+    {
+      title: "Lint suite",
+      description:
+        "静态检查 tools 与 skills 的描述、参数与工具对边界（不调用模型）。返回 counts / findings / profilePairs。",
+      inputSchema: { suite: z.string().optional().describe("套件路径，默认 ./mf.suite.json") }
+    },
+    async ({ suite }) =>
+      json(
+        lintSuite(
+          await loadSuite(suitePath(suite), { allowEmptyCases: true, allowEmptyTools: true })
+        )
+      )
+  );
+
+  server.registerTool(
+    "check",
+    {
+      title: "Install gate",
+      description:
+        "安装门禁：把新能力与已装能力做静态比较，返回 pass/warn、findings 与竞争族。传 manifest 检查单个；传 manifests 检查一包（新能力之间也会互比）。不阻断、不调用模型、无网络。",
+      inputSchema: {
+        manifest: z.any().optional().describe("新能力 {name, description, parameters?} 或 tool schema"),
+        manifests: z.array(z.any()).optional().describe("一次安装一包能力时的数组"),
+        installed: z.any().optional().describe("已装能力数组，或 {tools: [], skills: []}")
+      }
+    },
+    async ({ manifest, manifests, installed }) => {
+      if (manifests) return json(checkMany({ manifests, installed }));
+      return json(check({ manifest, installed }));
+    }
+  );
+
+  server.registerTool(
+    "cluster",
+    {
+      title: "Cluster tools",
+      description:
+        "聚类工具，给出挂载分组、跨组高风险与族内边界清单（每族要补哪句选择条件）。不调用模型。",
+      inputSchema: {
+        suite: z.string().optional().describe("套件路径，默认 ./mf.suite.json"),
+        threshold: z.number().min(0).max(1).optional().describe("聚类阈值，默认 0.5"),
+        maxSize: z.number().int().positive().optional().describe("单组最大工具数，默认 10")
+      }
+    },
+    async ({ suite, threshold, maxSize }) => {
+      const loaded = await loadSuite(suitePath(suite), { allowEmptyCases: true });
+      return json(clusterTools(loaded.tools, { threshold, maxSize }));
+    }
+  );
+
+  server.registerTool(
+    "compare",
+    {
+      title: "Compare scorecards",
+      description:
+        "比较两份评分卡 JSON：可比性、升降、干扰归因与混淆矩阵。只读文件，不调用模型。",
+      inputSchema: {
+        before: z.string().describe("旧评分卡 JSON 路径"),
+        after: z.string().describe("新评分卡 JSON 路径")
+      }
+    },
+    async ({ before, after }) => {
+      const [oldText, newText] = await Promise.all([
+        readFile(resolve(before), "utf8"),
+        readFile(resolve(after), "utf8")
+      ]);
+      return json(compareScorecards(JSON.parse(oldText), JSON.parse(newText)));
+    }
+  );
+
   server.registerTool(
     "add_cases",
     {

package/lib/profile.js

@@ -2,17 +2,28 @@ import { pct } from "./score.js";
 
 export function normalizeProfiles(raw, toolNames) {
   if (raw === undefined || raw === null) return null;
-  if (typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error('suite "profiles" must be an object of { "group": ["tool", ...] }');
+  if (typeof raw !== "object") {
+    throw new Error('suite "profiles" must be an object or an array of groups');
   }
   const known = new Set(toolNames);
   const profiles = [];
-  for (const [key, list] of Object.entries(raw)) {
-    const name = String(key).trim();
+  const seen = new Set();
+  // Platform registries often hand us an array of
+  // { agentType, tools, skills } rather than { "group": ["tool"] }.
+  const entries = Array.isArray(raw)
+    ? raw.map((value, index) => [String(index), value])
+    : Object.entries(raw);
+  for (const [key, value] of entries) {
+    // Array form: { "group": ["tool", ...] }. Object form (platform registries
+    // often look like this): { "0": { agentType, tools, skills } }.
+    const list = Array.isArray(value) ? value : value?.tools;
+    const name = String(Array.isArray(value) ? key : value?.name ?? value?.agentType ?? key).trim();
     if (!name) throw new Error('suite "profiles": group name must be non-empty');
     if (!Array.isArray(list) || list.length === 0) {
       throw new Error(`profile "${name}": must be a non-empty array of tool names`);
     }
+    if (seen.has(name)) throw new Error(`profile "${name}": duplicate group name`);
+    seen.add(name);
     const tools = [];
     for (const item of list) {
       if (typeof item !== "string" || item.trim() === "") {

package/mf.js

@@ -11,7 +11,7 @@ import { probeStdioServer, probeHttpServer } 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 { check, checkMany, formatCheck, formatCheckMany } from "./lib/check.js";
 import { auditSuite, formatAudit } from "./lib/audit.js";
 import { suiteFingerprint, hashText, hashOf } from "./lib/fingerprint.js";
 import { runExecutionChecks } from "./lib/eval-exec.js";
@@ -75,7 +75,7 @@ Usage:
   mf coverage [--suite <file>] [--json]
   mf audit [--suite <file>] [--out <file>] [--json]  # 静态审计：lint + 分组边界 + 用例覆盖 + 挂载
   mf lint [--suite <file>] [--json]  # 静态检查 tools 与 skills，不调用模型
-  mf check --manifest <file> [--installed <file>] [--json]  # 安装门禁：新能力 × 已装能力
+  mf check (--manifest <file> | --manifests <file>) [--installed <file>] [--json]  # 安装门禁：新能力 × 已装能力（--manifests 支持一包）
   mf compare <before.json> <after.json> [--json]
   mf ablate --tool <name> [--suite <file>] [--profile <group>] [--models <ids>] [--max-cost <cny>] [--progress] [--json]
   mf cluster [--suite <file>] [--threshold <0.5>] [--max-size <10>] [--out <file>] [--json]  # 建议挂载分组 + 同族候选
@@ -482,7 +482,7 @@ export async function runScan(options, io = console) {
 
   if (options.json) {
     io.log(JSON.stringify({ report: redactReport(report), draft }, null, 2));
-    return report.tools.length > 0 ? 0 : 3;
+    return report.tools.length > 0 || report.skills.length > 0 ? 0 : 3;
   }
 
   io.log(formatScanSummary(report));
@@ -497,7 +497,7 @@ export async function runScan(options, io = console) {
     io.log(`wrote ${reportPath}`);
   }
 
-  return report.tools.length > 0 ? 0 : 3;
+  return report.tools.length > 0 || report.skills.length > 0 ? 0 : 3;
 }
 
 export async function runCaseAdd(options, io = console) {
@@ -584,11 +584,24 @@ export async function runSandboxCheck(options, io = console) {
 // 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"))
     : [];
+
+  if (options.manifests) {
+    const manifests = JSON.parse(await readFile(resolve(options.manifests), "utf8"));
+    const result = checkMany({ manifests, installed });
+    noteUsage({
+      checkVerdict: result.verdict,
+      checkFindings: Object.values(result.summary).reduce((sum, count) => sum + count, 0)
+    });
+    io.log(options.json ? JSON.stringify(result, null, 2) : formatCheckMany(result));
+    return 0;
+  }
+  if (!options.manifest) {
+    throw new Error("--manifest 或 --manifests <file> 必填（[name, description, parameters?]）");
+  }
+  const manifest = JSON.parse(await readFile(resolve(options.manifest), "utf8"));
   const result = check({ manifest, installed });
   noteUsage({ checkVerdict: result.verdict, checkFindings: result.findings.length });
   io.log(options.json ? JSON.stringify(result, null, 2) : formatCheck(result));
@@ -1009,6 +1022,7 @@ function parseArgs(argv) {
     dryRun: false,
     tool: null,
     manifest: null,
+    manifests: null,
     installed: null,
     threshold: 0.5,
     maxSize: 10,
@@ -1077,6 +1091,7 @@ function parseArgs(argv) {
       case "--dry-run": options.dryRun = true; break;
       case "--tool": options.tool = value(); break;
       case "--manifest": options.manifest = resolve(value()); break;
+      case "--manifests": options.manifests = resolve(value()); break;
       case "--installed": options.installed = resolve(value()); break;
       case "--threshold": {
         const raw = Number(value());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelfunction-cli",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "type": "module",
   "license": "MIT",
   "description": "mf — function-calling accuracy scorecard for AI agents",