@stalfh233/omc-cli 0.6.5 → 0.6.6

package/dist/cli.js

@@ -43,6 +43,7 @@ else if (process.env.OMC_ASCII_STDOUT !== "0" && process.argv.some((arg) => arg
 }
 import { commandIndex, commandInventory, describeContract, describeContractFull, describeContractTool, describeExample, describeParam, describeSchemaOnly, describeTool, describeToolFull, filterTools } from "./discovery.js";
 import { closestMatches } from "./closest-match.js";
+import { KEY_ALIAS_HINTS } from "./tool-types.js";
 import { repeatFullDescribe } from "./describe-cache.js";
 import { buildCapabilityOverview, capabilityDetail, capabilityRouteIndex, compactCapabilities, executableCapabilityBundle, resolveCapabilityId, DISCOVERY_AUTHORITY } from "./capability-overview.js";
 import { goalRoute } from "./goal-routes.js";
@@ -580,8 +581,9 @@ async function cmdCall(store, args) {
         for (const key of Object.keys(parsedArgs)) {
             if (schemaKeys.has(key) || recognized.has(key))
                 continue;
-            const closest = closestMatches(key, [...schemaKeys], 1)[0]?.name;
-            ignoredReadKeys.push({ key, ...(closest !== undefined ? { closest } : {}) });
+            // r25 真机：`limt:5` 被就近指到 `filter`（共享 "fi" 就够过阈值），照提示改
+            // 会把「取 5 条」变成「按条件过滤」。短键走显式缩写表，语义才不跑偏。
+            ignoredReadKeys.push({ key, ...suggestArgumentKey(key, [...schemaKeys]) });
         }
     }
     if (tool) {
@@ -655,7 +657,13 @@ async function cmdCall(store, args) {
     }
     // 读面未知键的非阻断回显：放在投影**之后**，否则会被 --jq 的窄投影吞掉。
     if (ignoredReadKeys.length > 0 && typeof result === "object" && result !== null) {
-        const pairs = ignoredReadKeys.map((entry) => (entry.closest ? `${entry.key}→${entry.closest}` : entry.key));
+        const pairs = ignoredReadKeys.map((entry) => {
+            if (entry.closest)
+                return `${entry.key}→${entry.closest}`;
+            if (entry.absentInTool)
+                return `${entry.key}（本工具没有 ${entry.absentInTool} 参数）`;
+            return entry.key;
+        });
         result = {
             ...result,
             ignoredArgs: {
@@ -679,6 +687,27 @@ function argvValues(args, name) {
     }
     return values;
 }
+/**
+ * 读面「拼错键」建议（r25 真机实证，2026-11-04）：`limt:5` 曾按编辑距离被指到
+ * `filter`——两者共享 "fi" 片段就过阈值，但语义完全不同（取 5 条 vs 按条件过滤）。
+ * 短键（≤5 字符）靠距离算不准，这里先查显式缩写表（与 tool-types 的 KEY_ALIAS_HINTS
+ * 同源），命中且参数真实存在才用；否则退回 closestMatches。
+ */
+export function suggestArgumentKey(key, schemaKeys) {
+    const known = new Set(schemaKeys);
+    const aliases = KEY_ALIAS_HINTS[key.toLowerCase()] ?? [];
+    for (const candidate of aliases) {
+        if (known.has(candidate))
+            return { closest: candidate };
+    }
+    // 关键：若这个键明确是某个已知参数的缩写、而**本工具根本没有该参数**（实测
+    // `model.list` 就没有 `size`），不能退回最近匹配硬凑一个（`filter` 语义相反）——
+    // 返回 absentInTool，让回执直说「本工具没有这个参数」。
+    if (aliases.length > 0)
+        return { absentInTool: aliases[0] };
+    const closest = closestMatches(key, schemaKeys, 1)[0]?.name;
+    return closest !== undefined ? { closest } : {};
+}
 function resolvedDefaultEnvironment(store) {
     try {
         return store.resolveEnvironment(undefined).name;
@@ -1600,6 +1629,10 @@ function onboardingHelp() {
         "方法论按需读：omc help <topic> 默认只回节索引（每节字节数）；用 --section \"<标题>\" 取正文（可重复），确需整篇才 --all。找具体事实（错误码/字段名/命令名）不要整篇 dump：omc help --search \"<词>\"（跨 topic，命中节正文随结果返回）。",
         "目标→工具一步定位：omc next \"<你要做什么>\"（离线、只读，给能力/说明/首批命令；不确定会明说并回退到 omc-requirement-analysis）。",
         "大结果取值一步到位：读面回 detailArtifactId 时，用 omc call <tool> … --jq <path>（可重复；`[]` 映射数组，如 items[].fields.planNo）或 --extract/--extract-keys，省掉再跑一次 omc artifact get；artifact get 正文超 8KB 默认也只回形状（--jq/--keys 定向取，--full 才整包）。批量形状预检用 --args-list … --preflight（零 wire、零写入，一次报全）。",
+        // r25 真机（2026-11-04）：探针连跑同一读面 2–3 次想验证「第二次是否 unchanged」，
+        // 结果三次都是全量，还去 describe 找 dedupe 参数（多花 3 轮）。读面确实不做跨调用
+        // 结果去重——**明说**比留白强，省掉一次探索。
+        "读面不做跨调用结果去重：同一读面同参数连跑 N 次就是 N 次真实读（不会回 unchanged，也没有 dedupe 开关）。要省就 --jq 定向取值或把结果落到自己的变量里复用；`unchanged:true` 只出现在写面回读缓存那一条路径。",
         "工具发现：omc commands --json（含 capability id/lane/recipes；加 --compact 只回工具行、无目录散文）· omc capabilities（能力 id/lane/aliases/tools/依赖顺序）· omc capability <id> --executable（单能力完整执行包）。",
         "单工具/契约：omc describe <tool>（schema+recipe+能力路由）· omc contract <lane>（wire 契约+能力路由）；环境就绪：omc call discover_environment --env <env> --args '{}'。",
         "写入两道门：对话层草稿确认（omc help omc-config-draft-review）+ 环境 writable 开关；生产环境每笔写需在 args 里带 confirmProduction:true。",

package/dist/tool-types.js

@@ -132,16 +132,46 @@ function keyRenameHint(issuePath, input, tool) {
     return `（该对象在本工具里的键是 ${key}，你传的是 ${synonyms.join("/")}；键名对照见 omc-tool-selection 的 Key-name table）`;
 }
 /** Cheap closest-key suggestion: exact→prefix→shared-start bigrams, threshold keeps it honest. */
+/**
+ * 常见参数缩写 → 规范键。r25 真机实证（2026-11-04）：`limt:5` 被指到 `filter`
+ * （`limt` 与 `filter` 共享 "fi" 片段就够过阈值），照提示改会从"取 5 条"变成
+ * "按条件过滤"，是**语义陷阱**；`fieldCodes` 被指到单数 `code`（真正要的是
+ * `codes`），照改会变成"只发一个字段"。短键与复数形态靠编辑距离算不准，
+ * 用显式小表兜住高频误拼，比调阈值可靠。
+ */
+export const KEY_ALIAS_HINTS = Object.freeze({
+    limt: ["size", "limit"],
+    limit: ["size"],
+    siz: ["size"],
+    offst: ["page", "offset"],
+    offset: ["page"],
+    fieldcodes: ["codes", "fieldCodes", "fields"],
+    codes: ["code"],
+    fliter: ["filter"],
+    filterr: ["filter"],
+    order: ["orders"],
+    orderby: ["orders"],
+});
 function closestSchemaKey(key, schemaKeys) {
     if (schemaKeys.has(key))
         return key;
+    // 0) 显式缩写表优先：命中且该键真实存在才用，避免"建议一个不存在的参数"。
+    for (const candidate of KEY_ALIAS_HINTS[key.toLowerCase()] ?? []) {
+        if (schemaKeys.has(candidate))
+            return candidate;
+    }
     let best;
     let bestScore = 0;
     for (const candidate of schemaKeys) {
         const lower = key.toLowerCase();
         const candLower = candidate.toLowerCase();
         let score = 0;
-        if (candLower.startsWith(lower) || lower.startsWith(candLower))
+        // 单复数/尾随 s 的差异要压过零散片段匹配：`fieldCodes`→`fieldCodes` 应胜过 →`code`。
+        if (candLower === lower)
+            score = 1;
+        else if (candLower === `${lower}s` || lower === `${candLower}s`)
+            score = 0.85;
+        else if (candLower.startsWith(lower) || lower.startsWith(candLower))
             score = 0.9;
         else if (candLower.includes(lower) || lower.includes(candLower))
             score = 0.7;
@@ -174,13 +204,24 @@ export function parseToolInput(tool, input) {
             const twoStep = unknown
                 .map((key) => TWO_STEP_GUIDANCE[tool.name]?.[key])
                 .filter((hint) => typeof hint === "string" && hint.length > 0);
+            // r25 真机实证：人读 `message` 已指向 `form.publish`，但 `issues[].message`
+            // 仍是 `unknown key; closest: none` —— 程序消费回执时会取 issues[]，于是
+            // 漏掉发布指引（报告原文：「若用程序消费回执，会选 issues[]，就会漏掉」）。
+            // 两条通道必须同源，否则等于修了一半。
+            const issueHintFor = (key) => {
+                const guidance = TWO_STEP_GUIDANCE[tool.name]?.[key];
+                if (guidance !== undefined)
+                    return guidance;
+                const closest = closestSchemaKey(key, schemaKeys);
+                return closest === undefined ? "unknown key; no close match in this tool's params" : `unknown key; closest: ${closest}`;
+            };
             throw new ToolInputError({
                 status: "error",
                 blocker: "tool-input-unknown-keys",
                 tool: tool.name,
                 message: `写面工具不接受未知键（会被静默丢弃）：${unknown.join("、")}。${twoStep.length > 0 ? twoStep.join(" ") : `最接近的合法键：${suggestions.join("；")}。参数表：omc describe ${tool.name}`}`,
                 ...(twoStep.length > 0 ? { nextCommand: `omc describe ${tool.name}` } : {}),
-                issues: unknown.map((key) => ({ path: [key], code: "unrecognized_key", message: `unknown key; closest: ${closestSchemaKey(key, schemaKeys) ?? "none"}` })),
+                issues: unknown.map((key) => ({ path: [key], code: "unrecognized_key", message: issueHintFor(key) })),
             });
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stalfh233/omc-cli",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "CloudPivot 8.6 configuration capability CLI — governed, fail-closed, coverage-manifest bounded.",
   "type": "module",
   "bin": {
@@ -52,9 +52,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@stalfh233/omc-fake-platform": "0.6.5",
+    "@stalfh233/omc-fake-platform": "0.6.6",
     "commander": "14.0.3",
-    "omc-core": "0.6.5",
+    "omc-core": "0.6.6",
     "proper-lockfile": "4.1.2",
     "write-file-atomic": "6.0.0",
     "zod": "^3.23.8",