modelfunction-cli 0.5.0 → 0.5.2

package/README.md

@@ -5,7 +5,7 @@
 ## 安装
 
 ```bash
-npx -y modelfunction-cli@0.4.4 --version
+npx -y modelfunction-cli@0.5.1 --version
 # 或
 npm i -D modelfunction-cli
 npx mf --version
@@ -26,6 +26,7 @@ mf scan --root . --probe              # 连 stdio MCP server 拉 tools/list
 mf coverage --suite mf.suite.json     # 看每个工具还缺多少用例
 mf eval --suite mf.suite.json --models deepseek,qwen --show-cases
 mf compare before.json after.json     # 跨版本比较（内容指纹判定可比性）
+mf audit --suite mf.suite.json --out audit.md  # 一次静态体检：lint + 边界 + 覆盖 + 挂载
 ```
 
 被测模型用环境变量提供 Key：
@@ -74,12 +75,13 @@ INTERNAL_LLM_KEY=... mf eval --suite mf.suite.json \
 
 | 命令 | 作用 |
 | --- | --- |
-| `mf scan` | 扫描工具定义（function.json / OpenAPI / MCP 配置 / Python `@tool` / JS·TS 声明与 TypeBox·zod schema）；`--probe` 连 MCP server（运行时结果覆盖静态推断）；`--from` 导入运行时工具数组；草稿按来源分组（`profiles`）并列出未覆盖的 skill |
-| `mf eval` | 跑评分卡；`--repeat` 多次取多数并报不稳定用例；`--fail-under` 阈值；`--baseline` + `--fail-on-regression` 回归门禁；`--profile` 按挂载组分别评分 |
+| `mf scan` | 扫描工具定义（function.json / OpenAPI / MCP 配置 / Python `@tool` / JS·TS 声明与 TypeBox·zod schema）；`--probe` 连 stdio 或 streamable-HTTP MCP server（运行时结果覆盖静态推断；headers/query 不写入报告）；`--from` 导入运行时工具数组；草稿按来源分组（`profiles`）并列出未覆盖的 skill |
+| `mf eval` | 跑评分卡；`--repeat` 多次取多数并报不稳定用例；`--fail-under` 阈值；`--baseline` + `--fail-on-regression` 回归门禁；`--profile` 按挂载组分别评分；`--max-cost` 按累计成本停机（退出 2）；`--progress` 逐用例进度（stderr） |
 | `mf case add` | 写入用例（默认 `source=agent`、`reviewed=false`） |
 | `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` |
@@ -87,7 +89,7 @@ INTERNAL_LLM_KEY=... mf eval --suite mf.suite.json \
 | `mf eval --execute` | 一次跑完选择 + 参数 + 运行断言（`toolInput` / `expect`） |
 | `mf sandbox check` | 探测本机可用隔离引擎与降级建议 |
 | `mf config set-key` | 把模型 Key 写入 `~/.modelfunction/credentials.json`（隐藏输入）；`remove-key` 删除；`list` 只显示掩码，`path` 打印路径 |
-| `mf stats` | 本地使用摘要（命令次数、模型、通过率区间、lint 规则命中）；不联网 |
+| `mf stats` | 本地使用摘要（命令次数、本地/CI 区分、模型、通过率区间、lint 规则命中）；不联网 |
 | `mf feedback` | 导出脱敏反馈包（仅计数与比率），发不发由你决定 |
 | `mf mcp` | stdio MCP server，供 Claude Code / Cursor / Kimi Code 调用 |
 
@@ -124,19 +126,19 @@ mf eval --suite mf.suite.json --models internal-ds \
   "mcpServers": {
     "modelfunction": {
       "command": "npx",
-      "args": ["-y", "modelfunction-cli@0.4.4", "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()` 的类型声明随包发布。
 
-本仓库当前版本 `0.5.0`（凭证与本地反馈渠道，待发布）；上文的 `@0.4.4` 是 npm 上已发布的版本，保证示例可复制。发布后把示例里的版本号统一升级即可。
+`0.5.1` 已发布到 npm：含凭证与本地反馈、usage `ci` 标记、eval `--progress`/`--max-cost`、`mf audit`、`scan --probe` streamable HTTP。本仓库 `0.5.2` 待发布：MCP 补齐 `lint`/`check`/`cluster`/`compare`，安装门禁支持 `--manifests` 一包批量检查，门禁 warn 只保留混淆对/必填来源/结构性错误（描述类降 info）。示例统一使用 `@0.5.1`。
 
 ## 数据边界
 
@@ -146,7 +148,7 @@ mf eval --suite mf.suite.json --models internal-ds \
 
 ## 本地使用记录与反馈（默认不上传）
 
-每条命令会在 `~/.modelfunction/usage/YYYY-MM.jsonl` 追加一行**计数记录**：命令名、退出码、耗时、mf/Node/OS 版本、模型 id、用例/工具数量、通过率区间、lint 规则命中数。**不记录**用例原文、工具描述、源码、文件路径或密钥。
+每条命令会在 `~/.modelfunction/usage/YYYY-MM.jsonl` 追加一行**计数记录**：命令名、退出码、耗时、mf/Node/OS 版本、模型 id、用例/工具数量、通过率区间、lint 规则命中数、是否 CI。**不记录**用例原文、工具描述、源码、文件路径或密钥。`mf stats` 会把本地运行与 CI 运行分开统计。
 
 ```bash
 mf stats                    # 看本机记录；--json 给脚本
@@ -165,7 +167,7 @@ mf feedback --out out.json  # 导出脱敏反馈包（聚合值，不含原始
 
 ```bash
 # 1. 把 mf 挂成 MCP server
-claude mcp add modelfunction -- npx -y modelfunction-cli@0.4.4 mcp
+claude mcp add modelfunction -- npx -y modelfunction-cli@0.5.1 mcp
 ```
 
 ```text

package/SCHEMA.md

@@ -1,6 +1,6 @@
 # Schemas v1
 
-自 `modelfunction-cli@0.4.3` 起冻结为 v1；`0.4.4` 是同一 v1 的补丁；`0.5.0` 增加 §9 本地文件，仍属 v1。这里描述 CLI 与库对外的稳定契约。人类可读文本（表格、提示语）不属于契约；**JSON 字段**属于。
+自 `modelfunction-cli@0.4.3` 起冻结为 v1；`0.4.4` 是同一 v1 的补丁；`0.5.0` 增加 §9 本地文件、`0.5.1` 增加 §10 审计 JSON，仍属 v1。这里描述 CLI 与库对外的稳定契约。人类可读文本（表格、提示语）不属于契约；**JSON 字段**属于。
 
 ## 兼容政策
 
@@ -110,7 +110,7 @@ skills 只做静态检查，不参与模型评测。
 
 `--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[]`。
+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。
 
@@ -174,9 +174,37 @@ import { check } from "modelfunction-cli";
 ```
 
 - `verdict` 只有 `pass` / `warn`，**没有 fail**；质量判定不阻断安装。
+- **严重度策略（门禁语境）**：只有会改变模型行为的规则保持原等级——`desc-missing`、`param-type-missing`（error），`required-unsourced`、`pair-no-boundary`、`skill-pair-no-boundary`（warn）；描述、命名、必填数量等质量规则降为 `info`，避免成熟工具集每次安装都告警。`mf lint` 不受影响，仍输出原始严重度。
 - 唯一抛错场景：`manifest.name` 缺失或为空。
 - 同步、无网络、无文件系统、无状态。类型声明见 `lib/check.d.ts`。
 
+批量（一次安装一包）：
+
+```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 工具
 
 | 工具 | 参数 |
@@ -184,8 +212,13 @@ import { check } from "modelfunction-cli";
 | `scan_tools` | `root?`、`probe?`、`timeoutMs?`、`writeSuite?` |
 | `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?` |
+| `run_eval` | `suite?`、`models?`、`cases?`、`profile?`、`repeat?`、`failUnder?`、`maxCost?`、`progress?` |
 
 返回值均为 JSON 文本。
 
@@ -195,7 +228,7 @@ import { check } from "modelfunction-cli";
 | --- | --- |
 | 0 | 成功（`mf check` 的 warn 也是 0） |
 | 1 | 输入/用法错误；`mf compare` 判定不可直接比较 |
-| 2 | `mf eval --fail-under` 未达标，或 `--fail-on-regression` 发现回退 |
+| 2 | `mf eval --fail-under` 未达标、`--fail-on-regression` 发现回退，或 `--max-cost` 超限 |
 | 3 | `mf exec` 被权限策略拒绝；`mf scan --json` 未找到工具 |
 | 4 | `mf exec` 超时 |
 
@@ -226,6 +259,7 @@ import { check } from "modelfunction-cli";
   "platform": "win32",
   "arch": "x64",
   "node": "24.6.0",
+  "ci": false,
   "models": ["mock"],
   "caseCount": 13,
   "toolCount": 4,
@@ -241,7 +275,7 @@ import { check } from "modelfunction-cli";
 }
 ```
 
-字段为白名单，只含计数、比率与 id；**不含**用例原文、工具描述、源码、文件路径或密钥。新增字段属于 v1 加法，消费方可忽略未知字段。`MF_NO_USAGE=1` 关闭写入；删除 `usage/` 即清空。
+字段为白名单，只含计数、比率与 id；**不含**用例原文、工具描述、源码、文件路径或密钥。`ci` 表示检测到 CI 环境（`CI=true/1` 或 `GITHUB_ACTIONS` / `GITLAB_CI` / `CIRCLECI` / `TRAVIS` / `BUILDKITE` / `TF_BUILD` / `JENKINS_URL` / `CNB_BUILD_ID`），用于把机器运行与本地运行分开；`mf stats` 分别统计。新增字段属于 v1 加法，消费方可忽略未知字段。`MF_NO_USAGE=1` 关闭写入；删除 `usage/` 即清空。
 
 ### `mf feedback` 包
 
@@ -260,3 +294,47 @@ import { check } from "modelfunction-cli";
 ```
 
 `usage` 是 `mf stats` 的聚合结果，不含原始事件、路径或密钥。是否发送由用户决定。
+
+## 10. 工具集审计（`mf audit --json`，0.5.1 起）
+
+```json
+{
+  "suite": { "name": "…", "path": "…", "tools": 4, "skills": 0, "cases": 13, "reviewed": 13 },
+  "lint": {
+    "tools": 4,
+    "skills": 0,
+    "counts": { "error": 0, "warn": 6, "info": 0 },
+    "findings": [],
+    "profilePairs": []
+  },
+  "clusters": {
+    "threshold": 0.5,
+    "total": 4,
+    "clusters": [],
+    "riskyPairs": [],
+    "familyHints": [],
+    "boundaries": []
+  },
+  "coverage": {
+    "total": 13,
+    "negative": 1,
+    "negativeRatio": 0.08,
+    "unreviewed": 0,
+    "tools": [],
+    "pairs": [],
+    "profiles": [],
+    "warnings": []
+  },
+  "profiles": { "groups": [], "warnings": [], "unmounted": [] },
+  "actions": [
+    {
+      "kind": "boundary|param-source|cases|args|review|mount",
+      "subject": "…",
+      "message": "…",
+      "detail": "…"
+    }
+  ]
+}
+```
+
+`profiles` 为 `null` 表示套件未定义分组。`clusters`/`coverage` 的明细与 §5/§4 同源；`actions` 是给人看的优先级列表。`mf audit` 恒退出 0（advisory），不阻断流程。

package/lib/audit.js

@@ -0,0 +1,149 @@
+// One static pass over a whole tool set: lint + cluster boundaries + case
+// coverage + mount checks. No model calls, no execution, no network.
+// The markdown output is meant to be forwarded as a trial deliverable.
+import { lintSuite, formatLint } from "./lint.js";
+import { clusterTools, formatClusters } from "./cluster.js";
+import { computeCoverage, formatCoverage } from "./cases.js";
+import { normalizeProfiles, profileWarnings, profileCaseCoverage } from "./profile.js";
+
+export function auditSuite(suite) {
+  const lint = lintSuite(suite);
+  const clusters = clusterTools(suite.tools);
+  const coverage = computeCoverage(suite);
+  const profiles = normalizeProfiles(suite.profiles, suite.tools.map((tool) => tool.name));
+  const mounted = profiles ? new Set(profiles.flatMap((profile) => profile.tools)) : null;
+  const profile = profiles
+    ? {
+        groups: profileCaseCoverage(profiles, suite.cases),
+        warnings: profileWarnings(profiles, suite),
+        unmounted: suite.tools.map((tool) => tool.name).filter((name) => !mounted.has(name))
+      }
+    : null;
+
+  return {
+    suite: {
+      name: suite.name,
+      path: suite.path ?? null,
+      tools: suite.tools.length,
+      skills: suite.skills?.length ?? 0,
+      cases: suite.cases.length,
+      reviewed: suite.cases.filter((testCase) => testCase.reviewed !== false).length
+    },
+    lint: {
+      tools: lint.tools,
+      skills: lint.skills,
+      counts: lint.counts,
+      findings: lint.findings,
+      profilePairs: lint.profilePairs ?? []
+    },
+    clusters,
+    coverage,
+    profiles: profile,
+    actions: buildActions({ lint, clusters, coverage, profile })
+  };
+}
+
+function buildActions({ lint, clusters, coverage, profile }) {
+  const actions = [];
+
+  const families = (clusters.boundaries ?? [])
+    .filter((family) => family.size > 1)
+    .sort((a, b) => b.pairs.length - a.pairs.length)
+    .slice(0, 3);
+  for (const family of families) {
+    actions.push({
+      kind: "boundary",
+      subject: family.label,
+      message: `为「${family.label}」补选择边界（${family.pairs.length} 对互抢）`,
+      detail: family.suggestion
+    });
+  }
+
+  const unsourced = lint.findings.filter((finding) => finding.code === "required-unsourced");
+  for (const finding of unsourced.slice(0, 5)) {
+    actions.push({
+      kind: "param-source",
+      subject: `${finding.tool}.${finding.param}`,
+      message: `补参数来源：${finding.tool}.${finding.param}`,
+      detail: finding.message
+    });
+  }
+
+  const empty = coverage.tools.filter((tool) => tool.total === 0);
+  if (empty.length > 0) {
+    actions.push({
+      kind: "cases",
+      subject: `${empty.length} tools`,
+      message: `为 ${empty.length} 个工具补用例`,
+      detail: empty.map((tool) => tool.name).join(", ")
+    });
+  }
+  const noArgs = coverage.tools.filter((tool) => tool.total > 0 && tool.withArgs === 0);
+  if (noArgs.length > 0) {
+    actions.push({
+      kind: "args",
+      subject: `${noArgs.length} tools`,
+      message: `为 ${noArgs.length} 个工具补带参数的用例`,
+      detail: noArgs.map((tool) => tool.name).join(", ")
+    });
+  }
+  if (coverage.unreviewed > 0) {
+    actions.push({
+      kind: "review",
+      subject: `${coverage.unreviewed} cases`,
+      message: `复核 ${coverage.unreviewed} 条未复核用例（复核后才计入正式分数）`,
+      detail: "把认可的用例 reviewed 改为 true"
+    });
+  }
+  if (profile && profile.unmounted.length > 0) {
+    actions.push({
+      kind: "mount",
+      subject: `${profile.unmounted.length} tools`,
+      message: `${profile.unmounted.length} 个工具不在任何挂载组`,
+      detail: profile.unmounted.join(", ")
+    });
+  }
+
+  return actions;
+}
+
+export function formatAudit(report) {
+  const { suite, lint, clusters, coverage, profiles, actions } = report;
+  const lines = [
+    `# ${suite.name} — 工具集审计`,
+    "",
+    `- 工具 ${suite.tools} · skills ${suite.skills} · 用例 ${suite.cases}（已复核 ${suite.reviewed}）`,
+    `- 文件：${suite.path ?? "(内存)"}`,
+    `- 纯静态：不调用模型、不执行工具、无网络`,
+    "",
+    "## 建议动作"
+  ];
+  if (actions.length === 0) {
+    lines.push("暂无必须处理项。");
+  } else {
+    actions.forEach((action, index) => {
+      lines.push(`${index + 1}. ${action.message}`);
+      if (action.detail) lines.push(`   ${action.detail}`);
+    });
+  }
+
+  lines.push("", "## 描述与参数（lint）", "", formatLint(lint));
+  lines.push("", "## 混淆与分组（cluster）", "", formatClusters(clusters));
+  lines.push("", "## 用例覆盖（coverage）", "", formatCoverage(coverage));
+  lines.push("", "## 挂载分组（profiles）", "");
+  if (!profiles) {
+    lines.push("未定义 profiles（平台可先用 `mf cluster --out <suite>` 生成候选分组）。");
+  } else {
+    lines.push("group                   tools  cases  negatives  tools-without-cases");
+    lines.push("----------------------  -----  -----  ---------  -------------------");
+    for (const row of profiles.groups) {
+      lines.push(
+        `${row.name.padEnd(22)}  ${String(row.tools).padStart(5)}  ${String(row.cases).padStart(5)}  ${String(row.negatives).padStart(9)}  ${row.missing.length ? row.missing.join(", ") : "-"}`
+      );
+    }
+    if (profiles.unmounted.length > 0) lines.push("", `未挂载工具：${profiles.unmounted.join(", ")}`);
+    for (const warning of profiles.warnings) lines.push(`- ${warning}`);
+  }
+
+  return lines.join("\n");
+}

package/lib/budget.js

@@ -0,0 +1,30 @@
+// Running cost guard for evaluations. Pricing is known per model, but token
+// usage is only known after a call returns, so the limit is enforced after
+// each call: the run stops as soon as the budget is crossed.
+export class CostLimitError extends Error {
+  constructor({ limit, spent, calls }) {
+    super(`cost limit reached: spent ¥${spent.toFixed(4)} of ¥${limit} after ${calls} call(s)`);
+    this.name = "CostLimitError";
+    this.limit = limit;
+    this.spent = spent;
+    this.calls = calls;
+  }
+}
+
+export function createBudget(limit = null) {
+  let spent = 0;
+  let calls = 0;
+  return {
+    get spent() {
+      return spent;
+    },
+    get calls() {
+      return calls;
+    },
+    spend(cost) {
+      calls += 1;
+      if (Number.isFinite(cost) && cost > 0) spent += cost;
+      if (limit !== null && spent > limit) throw new CostLimitError({ limit, spent, calls });
+    }
+  };
+}

package/lib/check.d.ts

@@ -23,6 +23,11 @@ export interface CheckInput {
 }
 
 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,6 +46,23 @@ export interface CheckResult {
   family?: string[];
 }
 
+export interface CheckManyInput {
+  manifests: Capability[];
+  installed?: Capability[] | InstalledCapabilities;
+}
+
+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.
@@ -48,4 +70,13 @@ export interface CheckResult {
  */
 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, or names are duplicated.
+ */
+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,6 +6,41 @@ import { lintSuite } from "./lint.js";
 export function check({ manifest, installed = [] } = {}) {
   const target = normalizeEntry(manifest);
   if (!target) throw new Error('check: manifest 需要非空 "name"');
+  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
+  };
+}
+
+function evaluateTargets(targets, installed) {
   const pool = [];
   if (Array.isArray(installed)) pool.push(...installed);
   else if (installed && typeof installed === "object") {
@@ -16,22 +51,47 @@ export function check({ manifest, installed = [] } = {}) {
   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);
+  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) {
@@ -61,10 +121,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 +173,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");
+}