@stalfh233/omc-cli 0.6.4 → 0.6.6

package/dist/cli-contract.js

@@ -272,15 +272,31 @@ export function classifyResult(result) {
         const suffix = candidates.length > 0 ? `；did you mean: ${candidates.join("、")}` : "；用 `omc commands --json --compact --lane <lane>` 或 `omc next` 定位工具";
         return { status: "error", error: withNext({ code: "invalid-input", message: `unknown tool ${String(result.tool ?? "")}${suffix}`, retryable: false }), exitCode: CLI_EXIT_CODES.invalidInput };
     }
-    if (result.blocker === "tool-input-invalid" || result.blocker === "tool-input-unknown-keys")
+    // r25 探针实证（2026-11-04）：`blocker: "invalid-input"` 有 8 处产出点
+    // （workflow/runtime-data/compound-writes），但这里只认 `tool-input-*`——于是
+    // 它们全落到函数末尾的 internal 分支：`error.code=internal` + exit 15，被调用方
+    // 读成"CLI 内部故障"，而实际是**自己传错了参数**（探针原话：
+    // 「rejected ✓, but error.code=internal (should be invalid-input), and no nextCommand」）。
+    // 入参形状错误一律 exit 10，并给出下一步。
+    const inputShapeBlocker = result.blocker === "tool-input-invalid"
+        || result.blocker === "tool-input-unknown-keys"
+        || result.blocker === "invalid-input";
+    if (inputShapeBlocker) {
+        // `invalid-input` 也可能是 CLI 层参数校验（compound-writes 的 --schema 必填），
+        // 那时没有 tool 字段——别硬拼一条指向不存在的工具的 describe。
+        const toolName = typeof result.tool === "string" && result.tool ? result.tool : undefined;
+        const nextCommand = typeof result.nextCommand === "string"
+            ? result.nextCommand
+            : toolName !== undefined ? `omc describe ${toolName}` : undefined;
         return {
             status: "error",
             error: {
                 ...withNext({ code: "invalid-input", message: String(result.message ?? "tool input is invalid"), retryable: false }),
-                nextCommand: typeof result.nextCommand === "string" ? result.nextCommand : `omc describe ${String(result.tool ?? "<tool>")}`,
+                ...(nextCommand !== undefined ? { nextCommand } : {}),
             },
             exitCode: CLI_EXIT_CODES.invalidInput,
         };
+    }
     if (status === "uncertain")
         return { status, error: withNext({ code: "uncertain", message: String(result.message ?? result.reason ?? "outcome is uncertain"), retryable: true }), exitCode: CLI_EXIT_CODES.uncertain };
     if (status === "refused") {

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/support.js

@@ -126,8 +126,8 @@ export function applicationScopeHint(scope, noun) {
 export function applicationScopeNotice(scope) {
     const count = scope.applicationCount ?? 1;
     const where = scope.source === "first-tenant-application" && count > 1
-        ? `租户首个应用 ${scope.code}（租户共 ${count} 个应用）`
-        : `应用 ${scope.code}`;
+        ? `租户首个应用「${scope.code}」（租户共 ${count} 个应用）`
+        : `应用「${scope.code}」`;
     return `本次只在${where}内扫描（source=${scope.source}）——结果被应用边界裁剪，不代表租户全集；跨应用先 app.list 取 applicationCode 再传 applicationCode。`;
 }
 export function flattenTreeRows(rows) {

package/dist/tool-types.js

@@ -50,6 +50,23 @@ const KEY_SYNONYMS = Object.freeze({
     code: ["schemaCode", "sheetCode", "workflowCode"],
     ruleCode: ["code"],
 });
+/**
+ * r25 沙盒实证（2026-11-04）：探针给 `configure_form` 传了 `publish:true`，
+ * 得到「未知键 publish。最接近的合法键：publish→（无相近键）」——写面 fail-closed
+ * 是对的，但**意图没被接住**：配置与发布本来就是两步，用户真正要的是
+ * `form.publish`。同类还有「配完字段就发布」（`field.publish`）与
+ * 「配完列表视图」（无需发布）。这里按工具给出可执行的两步指引，
+ * 比「无相近键」有用得多；代价是探针少花一轮（21→22 实测）。
+ */
+const TWO_STEP_GUIDANCE = Object.freeze({
+    configure_form: Object.freeze({
+        publish: "表单的配置与发布是两步：本工具只写草稿，发布用 `omc call form.publish --args '{\"schemaCode\":\"<模型>\",\"sheetCode\":\"<槽位>\"}'`（也可在本工具的成功回执后紧接着跑）。",
+        publishNow: "同上：本工具不负责发布，用 `omc call form.publish`。",
+    }),
+    configure_model: Object.freeze({
+        publish: "模型/字段的配置与发布是两步：字段建好后用 `omc call field.publish --args '{\"schemaCode\":\"<模型>\"}'` 发布；模型本身不需要单独发布。",
+    }),
+});
 /**
  * Per-tool input aliases: a synonym the caller may send INSTEAD of the canonical
  * key. Applied in `parseToolInput` BEFORE validation (fill canonical from an
@@ -115,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;
@@ -152,12 +199,29 @@ export function parseToolInput(tool, input) {
         const unknown = Object.keys(normalized).filter((key) => !schemaKeys.has(key));
         if (unknown.length > 0) {
             const suggestions = unknown.map((key) => `${key}→${closestSchemaKey(key, schemaKeys) ?? "（无相近键，omc describe <tool> 看参数表）"}`);
+            // r25 实证：`publish→（无相近键）` 等于没说——配置与发布是两步，用户要的是
+            // 另一个工具。有语义指引时优先给可执行的下一步。
+            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("、")}。最接近的合法键：${suggestions.join("；")}。参数表：omc describe ${tool.name}`,
-                issues: unknown.map((key) => ({ path: [key], code: "unrecognized_key", message: `unknown key; closest: ${closestSchemaKey(key, schemaKeys) ?? "none"}` })),
+                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: issueHintFor(key) })),
             });
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stalfh233/omc-cli",
-  "version": "0.6.4",
+  "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.4",
+    "@stalfh233/omc-fake-platform": "0.6.6",
     "commander": "14.0.3",
-    "omc-core": "0.6.4",
+    "omc-core": "0.6.6",
     "proper-lockfile": "4.1.2",
     "write-file-atomic": "6.0.0",
     "zod": "^3.23.8",