modelfunction-cli 0.1.1 → 0.1.3

package/README.md

@@ -5,12 +5,19 @@
 ## 安装
 
 ```bash
-npx -y modelfunction-cli@0.1.1 --version
+npx -y modelfunction-cli@0.1.3 --version
 # 或
 npm i -D modelfunction-cli
 npx mf --version
 ```
 
+全局安装（可选）后命令为 `mf`，也可以用 `modelfunction`——避开装了 TeX 的机器上 `mf` 与 Metafont 同名：
+
+```bash
+npm i -g modelfunction-cli
+modelfunction --version
+```
+
 ## 五步上手
 
 ```bash
@@ -76,7 +83,7 @@ INTERNAL_LLM_KEY=... mf eval --suite mf.suite.json \
   "mcpServers": {
     "modelfunction": {
       "command": "npx",
-      "args": ["-y", "modelfunction-cli@0.1.1", "mcp"]
+      "args": ["-y", "modelfunction-cli@0.1.3", "mcp"]
     }
   }
 }
@@ -98,7 +105,7 @@ INTERNAL_LLM_KEY=... mf eval --suite mf.suite.json \
 
 ```bash
 # 1. 把 mf 挂成 MCP server
-claude mcp add modelfunction -- npx -y modelfunction-cli@0.1.1 mcp
+claude mcp add modelfunction -- npx -y modelfunction-cli@0.1.3 mcp
 ```
 
 ```text

package/lib/cases.js

@@ -167,15 +167,63 @@ export function suspectedPairs(tools) {
       if (union.size === 0) continue;
       let shared = 0;
       for (const token of union) if (a.has(token) && b.has(token)) shared += 1;
-      const similarity = shared / union.size;
+      const lexical = shared / union.size;
+      const structural = structuralScore(tools[i], tools[j]);
+      const similarity = Math.max(lexical, structural);
       if (similarity >= PAIR_SIMILARITY) {
-        pairs.push({ a: tools[i].name, b: tools[j].name, similarity });
+        pairs.push({
+          a: tools[i].name,
+          b: tools[j].name,
+          similarity,
+          basis: structural > lexical ? "structural" : "lexical"
+        });
       }
     }
   }
   return pairs.sort((x, y) => y.similarity - x.similarity);
 }
 
+// Tools that share part of the name (search / file / read...) and the same
+// 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);
+  const right = nameTokens(y.name);
+  const sharedName = left.some((token) => right.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 (paramOverlap < 0.34) return 0;
+  const requiredOverlap = jaccard(
+    new Set(x.parameters?.required ?? []),
+    new Set(y.parameters?.required ?? [])
+  );
+  return 0.5 + 0.5 * (0.6 * paramOverlap + 0.4 * requiredOverlap);
+}
+
+function nameTokens(name) {
+  return String(name ?? "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+}
+
+function paramNames(tool) {
+  return new Set(Object.keys(tool.parameters?.properties ?? {}));
+}
+
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 1;
+  const union = new Set([...a, ...b]);
+  let shared = 0;
+  for (const item of union) if (a.has(item) && b.has(item)) shared += 1;
+  return shared / union.size;
+}
+
 function tokens(text) {
   const set = new Set();
   const lowered = String(text ?? "").toLowerCase();

package/lib/lint.js

@@ -15,6 +15,42 @@ const GENERIC_NAMES = new Set([
 
 const WHEN_HINT = /(用于|用来|当|如果|适用|适合|use when|use this|helps? )/i;
 
+// Identifier tokens, matched on token boundaries only: `request_text` is text,
+// `request_id` is an identifier. Strong = platform-injected (session/tenant/trace
+// class); weak = business id the user may or may not supply.
+const STRONG_ID_TOKENS = new Set([
+  "uuid", "guid", "sid", "nonce", "token", "signature",
+  "sessionid", "tenantid", "traceid", "threadid", "conversationid", "correlationid", "requestid",
+  "session", "tenant", "trace", "thread", "conversation", "correlation"
+]);
+const WEAK_ID_TOKENS = new Set(["id", "ids"]);
+const OPAQUE_ID_SCHEMA = /uuid|[0-9a-f]{8}-[0-9a-f]{4}/i;
+const DESCRIPTION_ID_HINT = /(会话\s*id|session\s*id|租户|tenant|trace|请求\s*id|request\s*id|签名|signature|\btoken\b|nonce|uuid|标识|编号)/i;
+const ID_SOURCE_HINT = /(来源|取自|来自|传入|注入|平台|系统|上下文|请求头|header|无需|自动|会提供|由调用方|上一步)/i;
+const FIXED_ID_LENGTHS = new Set([8, 16, 24, 32, 36, 40, 64]);
+
+function nameTokens(name) {
+  return String(name)
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .split(/[^A-Za-z0-9]+/)
+    .map((token) => token.toLowerCase())
+    .filter(Boolean);
+}
+
+function idStrength(name) {
+  const tokens = nameTokens(name);
+  if (tokens.length === 0) return null;
+  const last = tokens[tokens.length - 1];
+  const joinedTail = tokens.slice(-2).join("");
+  if (STRONG_ID_TOKENS.has(last) || STRONG_ID_TOKENS.has(joinedTail)) return "strong";
+  if (WEAK_ID_TOKENS.has(last)) return "weak";
+  return null;
+}
+
+const BOUNDARY_HINT = /(不适用|不要用于|不用于|不能用于|而非|区别于|not for|do not use)/i;
+// Chinese descriptions are compared as bigrams, so mid-0.3s similarity is noise.
+const NO_BOUNDARY_SIMILARITY = 0.5;
+
 export function lintSuite(suite) {
   const findings = [];
   const add = (severity, code, tool, message, extra = {}) =>
@@ -63,6 +99,55 @@ export function lintSuite(suite) {
       });
     }
 
+    for (const name of required) {
+      const schema = properties[name];
+      if (!schema) continue;
+      const description = String(schema.description ?? "");
+      const fixedLength =
+        typeof schema.minLength === "number" &&
+        schema.minLength === schema.maxLength &&
+        FIXED_ID_LENGTHS.has(schema.minLength);
+      const schemaOpaque =
+        (typeof schema.format === "string" && OPAQUE_ID_SCHEMA.test(schema.format)) ||
+        (typeof schema.pattern === "string" && OPAQUE_ID_SCHEMA.test(schema.pattern)) ||
+        fixedLength;
+      const nameStrength = idStrength(name);
+      // Name tokens alone are a weak signal: the author picks the names. Schema
+      // shape and the description are what the model actually reasons from.
+      const strong = schemaOpaque || DESCRIPTION_ID_HINT.test(description) || nameStrength === "strong";
+      const weak = nameStrength === "weak";
+      const scalar = schema.type === undefined || schema.type === "string";
+      if ((strong || weak) && scalar && !ID_SOURCE_HINT.test(description)) {
+        add(
+          strong ? "warn" : "info",
+          "required-unsourced",
+          tool.name,
+          strong
+            ? `必填参数 ${name} 像是外部注入的标识，但没说明从哪里获取；模型拿不到它时可能干脆不调用任何工具`
+            : `必填参数 ${name} 是业务 ID；如果用户不会在对话里给出，模型可能编造或干脆不调用`,
+          {
+            param: name,
+            suggestion: `改为平台注入（移出 schema），或在 description 写明来源，例如「由平台在会话开始时注入，模型无需生成」`
+          }
+        );
+      }
+    }
+
+    const toolCases = (suite.cases ?? []).filter((testCase) => testCase.expectedTool === tool.name);
+    if (toolCases.length > 0) {
+      for (const name of required) {
+        const covered = toolCases.some(
+          (testCase) => testCase.expectedArgs && Object.prototype.hasOwnProperty.call(testCase.expectedArgs, name)
+        );
+        if (!covered) {
+          add("info", "required-uncovered", tool.name, `必填参数 ${name} 没有任何用例校验过，模型是否真能填对它还没有证据`, {
+            param: name,
+            suggestion: `补一条用例在 expectedArgs 里断言 ${name}，或把它降为可选 / 改为平台注入`
+          });
+        }
+      }
+    }
+
     for (const [name, schema] of Object.entries(properties)) {
       if (!schema?.description) {
         add("warn", "param-desc-missing", tool.name, `参数 ${name} 没有说明`, {
@@ -83,9 +168,22 @@ export function lintSuite(suite) {
   }
 
   for (const pair of suspectedPairs(suite.tools)) {
-    add("warn", "pair-overlap", pair.a, `与 ${pair.b} 的描述相似度 ${pair.similarity.toFixed(2)}，容易被混淆`, {
-      suggestion: `在 ${pair.a} 和 ${pair.b} 的 description 里各写一句“不适用于什么”，并补一条歧义用例`
+    const similarity = pair.similarity.toFixed(2);
+    const declaresBoundary = [pair.a, pair.b].some((name) => {
+      const tool = suite.tools.find((item) => item.name === name);
+      return BOUNDARY_HINT.test(tool?.description ?? "");
     });
+    if (declaresBoundary) {
+      add("info", "pair-overlap", pair.a, `与 ${pair.b} 的描述相似度 ${similarity}，已写互斥边界`, {
+        pair: [pair.a, pair.b]
+      });
+    } else if (pair.similarity >= NO_BOUNDARY_SIMILARITY) {
+      const reason = pair.basis === "structural" ? "名字与参数形状接近" : "描述相近";
+      add("warn", "pair-no-boundary", pair.a, `与 ${pair.b} ${reason}（相似度 ${similarity}），且两边都没写“不适用于”边界，模型只能靠相似度硬猜`, {
+        pair: [pair.a, pair.b],
+        suggestion: `在 ${pair.a} 和 ${pair.b} 的 description 里各写一句“不适用于什么”，并补一条歧义用例`
+      });
+    }
   }
 
   const counts = { error: 0, warn: 0, info: 0 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelfunction-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "license": "MIT",
   "description": "mf — function-calling accuracy scorecard for AI agents",
@@ -13,7 +13,8 @@
     "agent"
   ],
   "bin": {
-    "mf": "mf.js"
+    "mf": "mf.js",
+    "modelfunction": "mf.js"
   },
   "files": [
     "mf.js",