modelfunction-cli 0.4.1 → 0.4.2

package/README.md

@@ -69,6 +69,7 @@ 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` |

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/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.2",
   "type": "module",
   "license": "MIT",
   "description": "mf — function-calling accuracy scorecard for AI agents",
@@ -31,6 +31,9 @@
     "pack:check": "npm pack --dry-run",
     "prepublishOnly": "npm test"
   },
+  "exports": {
+    ".": "./lib/check.js"
+  },
   "engines": {
     "node": ">=20"
   },