modelfunction-cli 0.4.0 → 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/js-tools.js

@@ -115,7 +115,11 @@ function toolFromObject(node, ctx, preset = {}) {
     node.props.has("isEnabled") ||
     node.props.has("searchHint");
   if (!description && Object.keys(schema.properties ?? {}).length === 0 && !toolish) return undefined;
-  return { name, description, parameters: schema };
+  // Claude-style tools build the description in `async description()` or a
+  // prompt template; lint must not call that "missing".
+  const descNode = node.props.get("description");
+  const runtimeDescription = !description && (descNode?.t === "unknown" || node.props.has("prompt"));
+  return { name, description, parameters: schema, ...(runtimeDescription ? { descriptionSource: "runtime" } : {}) };
 }
 
 function isSchema(value) {
@@ -601,7 +605,14 @@ function parseObject(src, start, depth) {
       const skipped = skipToValueEnd(src, i);
       if (skipped === null) {
       return null; }
-      props.set(key, { t: "unknown" });
+      // `async description() {...}` — record the method's real name so lint can
+      // tell "description generated at runtime" apart from "no description".
+      let methodName = key;
+      if ((key === "async" || key === "get" || key === "set") && /[A-Za-z_$]/.test(src[i] ?? "")) {
+        const inner = readIdent(src, i);
+        if (inner && src[skipTrivia(src, inner.end)] === "(") methodName = inner.name;
+      }
+      props.set(methodName, { t: "unknown" });
       i = skipped;
       if (src[i] === ",") {
         i += 1;

package/lib/lint.js

@@ -91,7 +91,11 @@ export function lintSuite(suite) {
     const description = (tool.description ?? "").trim();
     const template = `建议：\`${tool.name}：当用户需要____时使用。输入____，返回____。不适用于____。\``;
 
-    if (!description) {
+    if (tool.descriptionSource === "runtime") {
+      // The description exists at runtime but is assembled in code, so static
+      // review cannot judge its wording. Not a defect.
+      add("info", "desc-runtime", tool.name, "description 由代码在运行时生成，静态不可评；请确认运行时输出包含触发时机与边界");
+    } else if (!description) {
       add("error", "desc-missing", tool.name, "工具没有 description，模型无法判断何时调用", { suggestion: template });
     } else {
       if (description.length < 20) {
@@ -107,8 +111,10 @@ export function lintSuite(suite) {
       }
     }
 
+    // Naming style is an ecosystem convention, not a model-facing defect:
+    // Claude-style PascalCase agents work fine on their own. Info only.
     if (!/^[a-z][a-z0-9_]*$/.test(tool.name)) {
-      add("warn", "name-style", tool.name, "工具名建议用小写 snake_case");
+      add("info", "name-style", tool.name, "工具名不是小写 snake_case；对外分发（MCP/插件市场）时建议统一");
     }
     if (GENERIC_NAMES.has(tool.name)) {
       add("warn", "name-generic", tool.name, "工具名过于通用，容易和其它工具混淆", {

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]);
         }
@@ -348,7 +351,8 @@ export function buildSuiteDraft(report) {
     tools: report.tools.map((tool) => ({
       name: tool.name,
       description: tool.description,
-      parameters: tool.parameters
+      parameters: tool.parameters,
+      ...(tool.descriptionSource ? { descriptionSource: tool.descriptionSource } : {})
     })),
     cases: []
   };

package/lib/suite.js

@@ -54,7 +54,8 @@ async function normalizeTool(entry, baseDir) {
     description: entry.description ?? "",
     parameters: entry.parameters ?? entry.input ?? EMPTY_SCHEMA,
     source: null,
-    sideEffects: normalizeSideEffects(entry.sideEffects ?? entry.side_effects)
+    sideEffects: normalizeSideEffects(entry.sideEffects ?? entry.side_effects),
+    ...(entry.descriptionSource === "runtime" ? { descriptionSource: "runtime" } : {})
   };
 }
 

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.0",
+  "version": "0.4.2",
   "type": "module",
   "license": "MIT",
   "description": "mf — function-calling accuracy scorecard for AI agents",
@@ -25,12 +25,15 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test \"test/**/*.test.js\"",
+    "test": "node --test --test-concurrency=1 \"test/**/*.test.js\"",
     "eval": "node mf.js eval",
     "eval:mock": "node mf.js eval --models mock --show-cases",
     "pack:check": "npm pack --dry-run",
     "prepublishOnly": "npm test"
   },
+  "exports": {
+    ".": "./lib/check.js"
+  },
   "engines": {
     "node": ">=20"
   },