@stalfh233/omc-cli 0.6.12 → 0.6.13

package/dist/cli.js

@@ -27,7 +27,7 @@ import { CLI_DEFAULT_OUTPUT_BYTES, assertSafeOutputPath, pruneArtifacts } from "
 import { artifactPathMissHint, nullProjectionHint, partialPathMissHint, projectJsonPath, projectJsonPathFanout, projectResultExtract } from "./path-projection.js";
 import { basename, join, resolve } from "node:path";
 import { buildToolRegistry } from "./tools.js";
-import { acquireWriteLock } from "./write-lock.js";
+import { acquireWriteLock, writeLockHeldFace } from "./write-lock.js";
 import { cmdCompute } from "./compute.js";
 import { cmdRuleWhen } from "./rule-when.js";
 import { cmdApprovalFlow } from "./approval-flow.js";
@@ -209,7 +209,9 @@ async function cmdDoctor(store, environment, serviceCode) {
     try {
         const resolved = store.resolveEnvironment(environment);
         steps.push(`配置      ok  环境=${resolved.name}（来源 ${resolved.source}）`);
-        steps.push(`写入      ok  写入=${environmentWritable(resolved.profile) ? "允许" : "只读"}${requiresProductionConfirmation(resolved.profile) ? "；生产环境：每笔写入需 confirmProduction" : ""}`);
+        steps.push(`远端写    ok  远端写=${environmentWritable(resolved.profile) ? "允许" : "只读"}${requiresProductionConfirmation(resolved.profile) ? "；生产环境：每笔写入需 confirmProduction" : ""}（平台侧变更）`);
+        // r29f F9：读面也会本地落盘（artifacts/usage/describe 缓存）；与远端写分开说。
+        steps.push(`本地落盘  ok  .omc/（artifacts·usage·describe 缓存；读面也会写）。重定位：OMC_CONFIG_HOME=<根>（其下 .omc/）或 OMC_ARTIFACTS_HOME=<产物目录>`);
         const removed = removedProfileKeys(resolved.profile);
         if (removed.length > 0)
             steps.push(`配置      ⚠  含已移除键（请删除）：${removed.join("、")}`);
@@ -367,8 +369,10 @@ function doctorAnchor() {
     const topics = listSkills().map((entry) => entry.name).join("、");
     return [
         "最小路径  omc next \"<目标>\"（目标→工具一步定位，不确定会明说）→ omc help omc-start-here → omc call discover_environment --env <env> --args '{}'（<env> 名以 doctor 的「环境=」或项目 .omc-env 为准，勿猜）→ omc capabilities / omc describe <tool>",
-        `方法论    omc help <topic> --sections / --section "<标题>"（按节读，随包 skills/）；topic：${topics}`,
+        `方法论    omc help <topic>（或 --topic <name>）--sections / --section "<标题>"（按节读，随包 skills/）；topic：${topics}`,
         "大输出    超预算结果只回 artifactId/sha256/fetch；用 fetch 里的 omc artifact get <id>（可加 --jq <path>）取回，勿全量读入",
+        // r29f F9：只读面不碰远端，但仍会本地落盘——写清，避免「零写入」核对误判。
+        "落盘      远端写=环境 writable 决定的平台变更；本地落盘=.omc/（artifacts/usage/describe 缓存，读面也会写）。可用 OMC_CONFIG_HOME 重定位配置根（其下 .omc/），或 OMC_ARTIFACTS_HOME 单独重定位产物目录",
     ].join("\n");
 }
 function flag0(args, name) {
@@ -509,7 +513,20 @@ async function cmdCall(store, args) {
     const positional = args.filter((token, index) => !token.startsWith("--") && (index === 0 || !args[index - 1]?.startsWith("--env") && !args[index - 1]?.startsWith("--environment") && !args[index - 1]?.startsWith("--args")));
     const toolName = positional[0];
     if (!toolName || toolName === "help" || args.includes("--help")) {
+        // r29f F3：`omc call <tool> --help` 识别具名工具时转发 describe 摘要，
+        // 并写死输出预算默认值（别只回通用 call 选项）。
+        if (toolName && toolName !== "help") {
+            const registry = buildToolRegistry();
+            const described = describeTool(registry, toolName);
+            if (described) {
+                console.error(`工具：${toolName}`);
+                console.error(`输出预算：--max-output-bytes 默认 65536（只约束最终 stdout 信封；读面 diet ~2048 独立外置 detailArtifactId）；artifact get 内联上限 8192`);
+                console.error(`投影：--jq/--extract 相对 result（不要写 result. 前缀；误写会自动剥并标 autoStripped）；先投影再判预算`);
+                return emitTransportResult({ status: "ok", ...described, helpNote: "来自 omc describe；完整面用 omc describe <tool> [--full|--param|--example]" }, { request, maxOutputBytes });
+            }
+        }
         console.error("用法：omc call <tool> [--env <环境>] [--args '<json>' | --args - (stdin) | --args-file <配置根内路径>] [--extract <path>]... [--jq [path]] [--extract-keys] [--args-list <json数组> [--preflight]]");
+        console.error("输出预算：--max-output-bytes 默认 65536（只约束最终 stdout 信封；读面 diet ~2048 独立外置 detailArtifactId）；artifact get 内联上限 8192");
         console.error("写入：由环境 writable 决定（只读环境拒写）；生产环境的写必须在 args 里带 confirmProduction:true。");
         return emit(toolName && toolName !== "help" ? "error" : "ok", {}, toolName && toolName !== "help" ? CLI_EXIT_CODES.invalidInput : 0);
     }
@@ -617,26 +634,44 @@ async function cmdCall(store, args) {
     }
     const registry = buildToolRegistry();
     const tool = registry.find((definition) => definition.name === toolName);
-    // 调用流畅性（2026-11-04，#18 的「查不到数据」同源）：读面「宽松」不等于
-    // 「无声」——`{"limt":5}` / `{"filterr":{…}}` 被 zod 剥掉后返回全量，调用方
-    // 会读成「过滤没生效 / 数据就是这么多」。读面在**不阻断**的前提下把被忽略的
-    // 键回显出来（写面仍是 fail-closed，见 parseToolInput）。
+    // r29f F7：读面未知参数默认硬拒（与写面 tool-input-unknown-keys 对齐）；
+    // 显式 `lenientArgs:true` 才回退到旧的 ignoredArgs 回显。
     //
     // F6（r27）：应用级键（appCode/applicationCode/application）静默回落会把写
     // 操作打到错误应用——这些键被忽略时直接拒绝，不进 ignoredArgs。
     const ignoredReadKeys = [];
     if (tool) {
         const schemaKeys = new Set(Object.keys(tool.inputSchema));
-        const recognized = new Set(["environment", "capability", "requestId", "dryRun"]);
+        const recognized = new Set(["environment", "capability", "requestId", "dryRun", "lenientArgs"]);
+        const lenientArgs = parsedArgs.lenientArgs === true;
         const unknownKeys = Object.keys(parsedArgs).filter((key) => !schemaKeys.has(key) && !recognized.has(key));
         const appScopeUnknown = unknownKeys.filter((key) => APP_SCOPE_ARG_KEYS.has(key));
         if (appScopeUnknown.length > 0) {
-            const canonical = schemaKeys.has("applicationCode")
-                ? "applicationCode"
-                : schemaKeys.has("appCode")
-                    ? "appCode"
-                    : "applicationCode（或 appCode，以 omc describe 为准）";
+            const hasApplicationCode = schemaKeys.has("applicationCode");
+            const hasAppCode = schemaKeys.has("appCode");
             const wrong = appScopeUnknown.join("、");
+            // r29a F7：schema 两个应用范围键都没有时，旧文案回退成
+            // 「请改用 applicationCode（或 appCode…）」——调用方传的正是它，形成死循环。
+            // 这种工具根本没有应用范围参数（如 rule.* 按 schemaCode 定位），走专用 blocker。
+            if (!hasApplicationCode && !hasAppCode) {
+                const locateBy = schemaKeys.has("schemaCode")
+                    ? "schemaCode（模型 code）"
+                    : schemaKeys.has("code")
+                        ? "code"
+                        : "本工具自己的定位键（见 omc describe）";
+                const result = {
+                    status: "refused",
+                    blocker: "tool-has-no-app-scope",
+                    tool: toolName,
+                    ignored: appScopeUnknown,
+                    locateBy,
+                    message: `本工具没有应用范围参数（不接受 applicationCode/appCode）；你传的 ${wrong} 不会生效。` +
+                        `它按 ${locateBy} 定位——应用边界请在 model.*/folder.*/app.* 面使用。` +
+                        `（\`omc describe ${toolName}\` 可确认参数表）`,
+                };
+                return emit("refused", result, CLI_EXIT_CODES.policyRefused);
+            }
+            const canonical = hasApplicationCode ? "applicationCode" : "appCode";
             const result = {
                 status: "refused",
                 blocker: "unknown-app-scope-arg",
@@ -647,10 +682,29 @@ async function cmdCall(store, args) {
             };
             return emit("refused", result, CLI_EXIT_CODES.policyRefused);
         }
-        if (tool.kind !== "write") {
-            for (const key of unknownKeys) {
-                // r25 真机：`limt:5` 被就近指到 `filter`（共享 "fi" 就够过阈值），照提示改
-                // 会把「取 5 条」变成「按条件过滤」。短键走显式缩写表，语义才不跑偏。
+        const otherUnknown = unknownKeys.filter((key) => !APP_SCOPE_ARG_KEYS.has(key));
+        if (tool.kind !== "write" && otherUnknown.length > 0) {
+            if (!lenientArgs) {
+                const suggestions = otherUnknown.map((key) => ({ key, ...suggestArgumentKey(key, [...schemaKeys]) }));
+                const pairs = suggestions.map((entry) => {
+                    if (entry.closest)
+                        return `${entry.key}→${entry.closest}`;
+                    if (entry.absentInTool)
+                        return `${entry.key}（本工具没有 ${entry.absentInTool}）`;
+                    return entry.key;
+                });
+                const result = {
+                    status: "error",
+                    blocker: "tool-input-unknown-keys",
+                    tool: toolName,
+                    unknownKeys: otherUnknown,
+                    suggestions,
+                    message: `读面不接受未知键（与写面对齐）：${pairs.join("、")}。` +
+                        `改用合法键后重试；确需宽松忽略传 lenientArgs:true。参数表：omc describe ${toolName}`,
+                };
+                return emit("error", result, CLI_EXIT_CODES.invalidInput);
+            }
+            for (const key of otherUnknown) {
                 ignoredReadKeys.push({ key, ...suggestArgumentKey(key, [...schemaKeys]) });
             }
         }
@@ -684,15 +738,16 @@ async function cmdCall(store, args) {
             if (lock.held)
                 break;
             if (Date.now() >= deadline) {
-                const conflict = {
-                    status: "refused",
-                    blocker: "write-lock-held",
+                // r31b F2: structured retryable/lockOwner/nextCommand so scripts do not
+                // invent a shell retry loop (help says use --wait; the refusal must too).
+                const conflict = writeLockHeldFace({
                     environment: lockTarget,
                     owner: lock.owner,
                     recovery: lock.recovery,
-                    message: lock.recovery[0],
-                };
-                console.error(`write lock conflict: ${JSON.stringify(lock.owner)}`);
+                    refusedTool: toolName,
+                    waitMs: waitMs > 0 ? waitMs : 30_000,
+                });
+                console.error(`write lock conflict: ${JSON.stringify({ pid: lock.owner?.pid, tool: lock.owner?.tool ?? lock.owner?.command, startedAt: lock.owner?.startedAt })}`);
                 writeEnvelope(envelope("refused", conflict, request, classifyResult(conflict).error));
                 return CLI_EXIT_CODES.policyRefused;
             }
@@ -1053,6 +1108,76 @@ async function cmdBench(args) {
     const dims = report.dimensions;
     return failedSteps === 0 && dims.intent.passed === dims.intent.cases ? 0 : 1;
 }
+/** r29f F8：discovery 面复用同一投影层（相对本命令 result，不是 call 信封）。 */
+function emitProjectedResult(result, transport, jq) {
+    const raw = Array.isArray(jq) ? jq : jq === undefined ? [] : [jq];
+    const keysOnly = raw.some((entry) => entry === true) || (raw.length === 0 && jq === true);
+    const paths = raw
+        .filter((entry) => typeof entry === "string")
+        .flatMap((path) => path.split(","))
+        .map((path) => path.trim())
+        .filter(Boolean);
+    if (paths.length === 0 && !keysOnly)
+        return emitTransportResult(result, transport);
+    const projected = projectResultExtract(result, paths, keysOnly);
+    return emitTransportResult(projected ?? result, transport);
+}
+function enrichDescribeParamMiss(registry, toolName, param, miss) {
+    // r31b F1: a miss must teach the next move — closest name, or "that param
+    // lives on another tool" — instead of dumping the whole available table.
+    const available = Array.isArray(miss.available) ? miss.available.map((entry) => String(entry)) : [];
+    const didYouMean = typeof miss.didYouMean === "string" ? miss.didYouMean : undefined;
+    const family = toolName.includes(".") ? toolName.split(".")[0] : toolName;
+    // Known cross-tool identity pairs first (新建 vs 更新), then same-family,
+    // then any other tool that declares the param.
+    const preferredPair = toolName === "data.save" && param === "bizObjectId"
+        ? "data.update"
+        : toolName === "data.update" && param === "formData"
+            ? "data.save"
+            : undefined;
+    const otherTools = registry
+        .filter((tool) => tool.name !== toolName && tool.inputSchema && Object.prototype.hasOwnProperty.call(tool.inputSchema, param))
+        .map((tool) => tool.name)
+        .sort((left, right) => {
+        const rank = (name) => {
+            if (preferredPair !== undefined && name === preferredPair)
+                return 0;
+            if (name.startsWith(`${family}.`))
+                return 1;
+            return 2;
+        };
+        return rank(left) - rank(right) || left.localeCompare(right);
+    });
+    const otherTool = preferredPair && otherTools.includes(preferredPair) ? preferredPair : otherTools[0];
+    // Known cross-tool identity guidance for the data lane (新建 vs 更新).
+    const dataIdentityHint = toolName === "data.save" && param === "bizObjectId"
+        ? "新建用 data.save（schemaCode+formData）；更新用 data.update + bizObjectId"
+        : undefined;
+    const cappedAvailable = available.slice(0, 8);
+    const hintParts = [
+        didYouMean !== undefined ? `本工具最接近的参数是 ${didYouMean}` : undefined,
+        otherTool !== undefined ? `参数 "${param}" 属于 ${otherTool}${otherTools.length > 1 ? `（同名还在 ${otherTools.slice(1, 3).join("、")}）` : ""}` : undefined,
+        dataIdentityHint,
+    ].filter((part) => typeof part === "string" && part.length > 0);
+    return {
+        ...miss,
+        ...(didYouMean !== undefined ? { didYouMean, nextCommand: `omc describe ${toolName} --param ${didYouMean}` } : {}),
+        ...(otherTool !== undefined
+            ? {
+                otherTool,
+                otherTools: otherTools.slice(0, 5),
+                nextCommand: `omc describe ${otherTool} --param ${param}`,
+            }
+            : {}),
+        ...(hintParts.length > 0 ? { hint: hintParts.join("；") } : {}),
+        ...(dataIdentityHint !== undefined ? { guidance: dataIdentityHint } : {}),
+        available: cappedAvailable,
+        ...(available.length > cappedAvailable.length ? { availableTruncated: available.length - cappedAvailable.length } : {}),
+        message: hintParts.length > 0
+            ? `本工具没有参数 "${param}"——${hintParts.join("；")}`
+            : `本工具没有参数 "${param}"——available 是本工具的合法参数（已截断）`,
+    };
+}
 function cmdDiscovery(kind, transport, value, options = {}) {
     const registry = buildToolRegistry();
     let result;
@@ -1079,7 +1204,7 @@ function cmdDiscovery(kind, transport, value, options = {}) {
         // agent paid 4×54 KB on the default face before any hint could land).
         if (options.json !== true && options.compact !== true && !scoped) {
             result = commandIndex(registry);
-            return emitTransportResult({ status: "ok", ...result }, transport);
+            return emitProjectedResult({ status: "ok", ...result }, transport, options.jq);
         }
         const inventory = commandInventory(registry, { compact: options.compact === true });
         // r19 ticket 05: above this many hits a filter word is "broad" — the filtered
@@ -1170,16 +1295,28 @@ function cmdDiscovery(kind, transport, value, options = {}) {
     }
     else if (options.schemaOnly)
         result = describeSchemaOnly(registry, value ?? "");
-    else if (options.param)
-        result = describeParam(registry, value ?? "", options.param);
+    else if (options.param) {
+        const missOrHit = describeParam(registry, value ?? "", options.param);
+        // r31b F1: enrich a param miss with otherTool / capped available / guidance.
+        result =
+            missOrHit && missOrHit.found === false
+                ? enrichDescribeParamMiss(registry, value ?? "", options.param, missOrHit)
+                : missOrHit;
+    }
     else if (options.example !== undefined)
         result = describeExample(registry, value ?? "", typeof options.example === "string" ? options.example : undefined);
     else if (options.full) {
         const full = describeToolFull(registry, value ?? "");
-        // r9: the same `--full` contract was re-shipped 8 times (134 KB) while the
-        // caller only wanted to re-check a shape. Within a project session the
-        // second identical read returns an artifact reference instead of the body.
-        result = full ? (repeatFullDescribe(value ?? "", full) ?? full) : full;
+        // r31b F3: `--full` means "give me the body". Short-circuit only when the
+        // caller opts in with `--cache-ok` (legacy r9 repeat-read suppression).
+        if (!full)
+            result = full;
+        else if (options.cacheOk)
+            result = repeatFullDescribe(value ?? "", full) ?? full;
+        else {
+            repeatFullDescribe(value ?? "", full, { recordOnly: true });
+            result = full;
+        }
     }
     else {
         result = describeTool(registry, value ?? "");
@@ -1236,7 +1373,7 @@ function cmdDiscovery(kind, transport, value, options = {}) {
         const textNote = byText.length > 0 ? `；didYouMeanByText: ${byText.join("、")}` : "";
         return emitInvalid(transport, { message: `${kind} target not found: "${requested}"${shown.length > 0 ? `; did you mean: ${shown.join("、")}` : ""}${textNote}${absence}${approvalPointer}${intentPointer}${formPointer}${pointer}` });
     }
-    return emitTransportResult({ status: "ok", ...result }, transport);
+    return emitProjectedResult({ status: "ok", ...result }, transport, options.jq);
 }
 function cmdUsage(transport, options = {}) {
     return emitTransportResult(usageReport(undefined, { records: options.records === true, top: options.top, resolveLikeWriter: true }), transport);
@@ -1254,11 +1391,11 @@ function cmdNext(goal, transport) {
  * capability overview. Read-only, zero environment contact; a projection of
  * the tool registry, the coverage manifest, and the intent capability registry.
  */
-function cmdCapabilities(transport, compact = false) {
+function cmdCapabilities(transport, compact = false, jq) {
     const result = compactCapabilities(buildToolRegistry(), { compact });
-    return emitTransportResult({ status: "ok", ...result }, transport);
+    return emitProjectedResult({ status: "ok", ...result }, transport, jq);
 }
-function cmdCapability(id, transport, executable = false) {
+function cmdCapability(id, transport, executable = false, jq) {
     const registry = buildToolRegistry();
     const resolved = resolveCapabilityId(id);
     if (!resolved) {
@@ -1269,9 +1406,64 @@ function cmdCapability(id, transport, executable = false) {
         const bundle = executableCapabilityBundle(registry, resolved);
         if (!bundle)
             return emitInvalid(transport, { message: `capability "${id}" 没有可执行 bundle` });
-        return emitResult({ status: "ok", capability: bundle }, transport);
-    }
-    return emitResult({ status: "ok", capability: capabilityDetail(registry, resolved) }, transport);
+        return emitProjectedResult({ status: "ok", capability: bundle }, transport, jq);
+    }
+    const detail = capabilityDetail(registry, resolved);
+    if (!detail)
+        return emitInvalid(transport, { message: `capability "${id}" 无详情` });
+    // r29a F4：app/folder/model/rule 面附应用参数名矩阵（主/别名），一次看完。
+    const appScopeMatrix = buildAppScopeMatrix(registry, resolved);
+    return emitProjectedResult({
+        status: "ok",
+        capability: {
+            ...detail,
+            ...(appScopeMatrix !== undefined ? { appScopeArgs: appScopeMatrix } : {}),
+        },
+    }, transport, jq);
+}
+/**
+ * r29a F4：跨 app/folder/model/rule 的「工具 → 应用参数名(主/别名)」小表。
+ * 只在这四个能力面上挂，避免每条 capability 都膨胀。
+ */
+function buildAppScopeMatrix(registry, capabilityId) {
+    const faces = new Set(["app", "folder", "model", "businessrule", "rule"]);
+    if (!faces.has(capabilityId))
+        return undefined;
+    const laneByCapability = {
+        app: "app-management",
+        folder: "app-tree-folders",
+        model: "model-management",
+        businessrule: "B1-businessrule",
+        rule: "B1-businessrule",
+    };
+    const lane = laneByCapability[capabilityId];
+    const rows = registry
+        .filter((tool) => tool.lane === lane || ((capabilityId === "rule" || capabilityId === "businessrule") && tool.name.startsWith("rule.")))
+        .map((tool) => {
+        const keys = Object.keys(tool.inputSchema);
+        const primary = keys.includes("applicationCode") ? "applicationCode" : keys.includes("appCode") ? "appCode" : null;
+        const aliases = keys.includes("applicationCode") && keys.includes("appCode")
+            ? ["applicationCode", "appCode"]
+            : primary === "applicationCode"
+                ? ["applicationCode"]
+                : primary === "appCode"
+                    ? ["appCode"]
+                    : [];
+        return {
+            tool: tool.name,
+            primary,
+            aliases,
+            note: primary === null ? "无应用范围参数（按 schemaCode/自身键定位）" : aliases.length > 1 ? "双别名；冲突报 app-code-conflict" : undefined,
+        };
+    });
+    if (rows.length === 0)
+        return undefined;
+    return {
+        face: capabilityId,
+        rows,
+        relatedTopics: ["app-scope"],
+        hint: "完整矩阵也见 `omc help app-scope`",
+    };
 }
 /**
  * Read + validate an intent file, or emit the shared invalid-input envelope.
@@ -1621,14 +1813,14 @@ function cmdHelpSearch(topic, query, transport, searchMode, limit) {
                 : "")
         : "";
     if (topic === undefined) {
-        console.error("用法：omc help <topic>  |  omc help --search \"<词>\"（跨 topic 检索，命中节正文随结果返回）");
+        console.error("用法：omc help <topic>  |  omc help --topic <name>  |  omc help --search \"<词>\"（跨 topic 检索，命中节正文随结果返回）");
         console.error("权威路线：omc help omc-start-here（随包 skills/，不是分发镜像）");
         console.error("环境就绪：omc call discover_environment --env <env> --args '{}'");
         console.error(`命令：${commands.join("、")}`);
         console.error(`方法论 topic：${topics.map((entry) => entry.name).join("、")}`);
         return emitTransportResult({
             status: "ok",
-            usage: "omc help <topic>",
+            usage: "omc help <topic> | omc help --topic <name>",
             discovery: DISCOVERY_AUTHORITY,
             commands,
             topics,
@@ -1738,14 +1930,16 @@ function onboardingHelp() {
     return [
         "首次使用、或不确定从哪开始：omc help omc-start-here（随包权威 topic 路线）；被拒或状态异常：omc help omc-refusals。",
         "中文可读输出：任何命令加 --utf8——它让人类可读诊断（stderr/散文）按 UTF-8 原文输出。stdout 的 JSON 信封在非 UTF-8 代码页下仍保持 \\uXXXX 转义（保证 JSON.parse/ConvertFrom-Json 一定可解析，这是有意为之）。要连信封也是中文明文，必须先让管道按 UTF-8 解码（chcp 65001）——只设 OMC_ASCII_STDOUT=0 关写出端转义，在 cp936 管道下会把信封解码坏。",
-        "方法论按需读：omc help <topic> 默认只回节索引（每节字节数）；用 --section \"<标题>\" 取正文（可重复），确需整篇才 --all。找具体事实（错误码/字段名/命令名）不要整篇 dump：omc help --search \"<词>\"（跨 topic，命中节正文随结果返回）。",
+        "方法论按需读：omc help <topic>（或 omc help --topic <name>）默认只回节索引（每节字节数）；用 --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、零写入，一次报全）。",
+        // r30f F20：写清两道门——读面 diet(~2048) 与 stdout 预算(--max-output-bytes，默认 64KiB) 不是一回事。
+        "输出预算：`--max-output-bytes` 默认 65536（64KiB；超则回 artifact 指针 + sha256），只约束最终 stdout 信封（投影/--jq 之后）；`artifact get` 内联上限 8192。读面另有独立 diet 门（~2048）会先外置 detailArtifactId——抬高 --max-output-bytes 不会把已 diet 的大表重新内联。",
+        "大结果取值一步到位：读面回 detailArtifactId 时，用 omc call <tool> … --jq <path>（可重复；`[]` 映射数组，如 items[].fields.planNo）或 --extract/--extract-keys，省掉再跑一次 omc artifact get。commands/capabilities/describe 也支持 --jq。批量形状预检用 --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 commands --json（含 capability id/lane/recipes；加 --compact 只回工具行、无目录散文）· omc capabilities（能力 id/lane/aliases/tools/依赖顺序）· omc capability <id> --executable（单能力完整执行包）。应用参数矩阵：omc help app-scope。",
         "单工具/契约：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。",
     ].join("\n");
@@ -1819,6 +2013,22 @@ async function main() {
         process.stdout.write(`${ownPackageVersion()}\n`);
         return 0;
     }
+    // r29f F3：commander 在 action 前就吞掉 `--help`。`omc call <tool> --help`
+    // 必须在这里短路转发 describe，否则永远只见通用 call 选项。
+    if (bare[0] === "call" && bare[1] && bare[1] !== "help" && !bare[1].startsWith("-") && (bare.includes("--help") || bare.includes("-h"))) {
+        const toolName = bare[1];
+        const registry = buildToolRegistry();
+        const described = describeTool(registry, toolName);
+        console.error(`工具：${toolName}`);
+        console.error(`输出预算：--max-output-bytes 默认 2048（超则回 artifact 指针 + sha256）；artifact get 内联上限 8192`);
+        console.error(`投影：--jq/--extract 相对 result（不要写 result. 前缀；误写会自动剥并标 autoStripped）`);
+        if (described) {
+            writeEnvelope(envelope("ok", { ...described, helpNote: "来自 omc describe；完整面用 omc describe <tool> [--full|--param|--example]" }, request));
+            return CLI_EXIT_CODES.ok;
+        }
+        writeEnvelope(envelope("error", { tool: toolName }, request, { code: "invalid-input", message: `未知工具 ${toolName}；用 omc commands --json --compact 查名单`, retryable: false }));
+        return CLI_EXIT_CODES.invalidInput;
+    }
     command.addHelpText("after", `\n${onboardingHelp()}\n`);
     // No command at all: guide the agent (help text + onboarding), exit 0. This
     // is a benign "show me the surface" invocation, not a failure.
@@ -1826,7 +2036,11 @@ async function main() {
         command.outputHelp();
         return CLI_EXIT_CODES.ok;
     }
-    command.command("help [topic]").option("--section [heading]", "按标题取该节内容；可重复或用逗号一次取多节：--section a --section b / --section a,b（不带值则列出该 topic 的节标题）").option("--sections").option("--all", "回整篇正文（默认只回节索引：标题 + 各节字节）").option("--search <query>", "跨 topic 全文检索（错误码/字段名/命令名）；命中节正文随结果返回，不需要再取一次").option("--search-mode <mode>", "all（默认，同一节包含全部词）或 any（包含任一）").option("--limit <n>", "检索最多返回几节（默认 5，1–50）").option("--max-output-bytes <bytes>").action(async (topic, options) => { commandExitCode = await withTransport(options, request, (transport) => cmdHelp(topic, command.commands.map((entry) => entry.name()), transport, options.section, options.sections === true, options.all === true, typeof options.search === "string" ? options.search : undefined, typeof options.searchMode === "string" ? options.searchMode : undefined, typeof options.limit === "string" ? options.limit : undefined)); });
+    // r30f F15：topic 既是位置参数也接受 `--topic <name>` 别名（肌肉记忆对齐 capability/contract）。
+    command.command("help [topic]").option("--topic <name>", "topic 别名（与位置参数等价：`omc help omc-refusals` = `omc help --topic omc-refusals`）").option("--section [heading]", "按标题取该节内容；可重复或用逗号一次取多节：--section a --section b / --section a,b（不带值则列出该 topic 的节标题）").option("--sections").option("--all", "回整篇正文（默认只回节索引：标题 + 各节字节）").option("--search <query>", "跨 topic 全文检索（错误码/字段名/命令名）；命中节正文随结果返回，不需要再取一次").option("--search-mode <mode>", "all（默认，同一节包含全部词）或 any（包含任一）").option("--limit <n>", "检索最多返回几节（默认 5，1–50）").option("--max-output-bytes <bytes>").action(async (topic, options) => {
+        const resolvedTopic = typeof options.topic === "string" && options.topic.trim() !== "" ? options.topic.trim() : topic;
+        commandExitCode = await withTransport(options, request, (transport) => cmdHelp(resolvedTopic, command.commands.map((entry) => entry.name()), transport, options.section, options.sections === true, options.all === true, typeof options.search === "string" ? options.search : undefined, typeof options.searchMode === "string" ? options.searchMode : undefined, typeof options.limit === "string" ? options.limit : undefined));
+    });
     command.command("setup").option("--list").option("--edit <environment>").option("--remove <environment>").action(async (options) => {
         // r25 真机（2026-11-04）：setup 不在 ownsStdout 里，于是非 TTY 拒绝时主流程会补一个
         // `error.code=internal` 的信封——明明是可预期的用法错误（stdin 不是终端），却被包成
@@ -1886,7 +2100,7 @@ async function main() {
         commandExitCode = CLI_EXIT_CODES.ok;
     });
     command.command("doctor").option("--environment <environment>").option("--env <environment>").option("--service <serviceCode>", "可选：体检单个业务集成服务的鉴权参数形状（掩码/占位/全 0 检出，WARN 非致命）").action(async (options) => { commandExitCode = await cmdDoctor(new ConfigStore(defaultPaths()), options.environment ?? options.env, options.service); });
-    command.command("call <tool>").option("--env <environment>").option("--environment <environment>").option("--args <json>").option("--args-file <path>").option("--args-list <json-array>", '同一工具跑 N 次（JSON 数组，每条一个 args 对象）；逐条执行、默认不中断，最后回 succeeded/failed 汇总。适合批量建字段等').option("--preflight", "与 --args-list 一起用：只跑参数校验 + 写前语义闸（零 wire、零写入），一次报全所有形状问题").option("--keys", "与 artifact get 的 --keys 同义（= --extract-keys）：列出本次结果 artifact 的顶层键与体积").addOption(new Option("--extract <path>", "在本次结果的 artifact 内取一个路径的值（可重复；省掉一次 artifact get）").argParser((value, previous = []) => [...previous, value]).default([])).addOption(new Option("--jq [path]", "同 --extract，并支持 [] 映射（如 items[].fields.planNo）；裸 --jq 列出结果的顶层键").argParser((value, previous = []) => [...previous, value]).default([])).option("--extract-keys", "列出本次结果 artifact 的顶层键与体积（省掉一次 artifact get --keys）").option("--max-output-bytes <bytes>").option("--request-id <requestId>").option("--timeout-ms <milliseconds>").option("--wait <milliseconds>").option("--dry-run").addHelpText("after", `\n${onboardingHelp()}\n`).action(async (tool, options) => {
+    command.command("call <tool>").option("--env <environment>").option("--environment <environment>").option("--args <json>").option("--args-file <path>").option("--args-list <json-array>", '同一工具跑 N 次（JSON 数组，每条一个 args 对象）；逐条执行、默认不中断，最后回 succeeded/failed 汇总。适合批量建字段等').option("--preflight", "与 --args-list 一起用：只跑参数校验 + 写前语义闸（零 wire、零写入），一次报全所有形状问题").option("--keys", "与 artifact get 的 --keys 同义（= --extract-keys）：列出本次结果 artifact 的顶层键与体积").addOption(new Option("--extract <path>", "在本次结果的 artifact 内取一个路径的值（可重复；省掉一次 artifact get）").argParser((value, previous = []) => [...previous, value]).default([])).addOption(new Option("--jq [path]", "同 --extract，并支持 [] 映射（如 items[].fields.planNo）；裸 --jq 列出结果的顶层键").argParser((value, previous = []) => [...previous, value]).default([])).option("--extract-keys", "列出本次结果 artifact 的顶层键与体积（省掉一次 artifact get --keys）").option("--max-output-bytes <bytes>", "最终 stdout 信封预算；默认 65536（投影/--jq 之后再判）；读面 diet(~2048) 独立外置 detailArtifactId，抬高本参数不会把已 diet 的大表重新内联；artifact get 内联上限 8192").option("--request-id <requestId>").option("--timeout-ms <milliseconds>").option("--wait <milliseconds>").option("--dry-run").addHelpText("after", `\n${onboardingHelp()}\n`).action(async (tool, options) => {
         const rest = [tool, ...(options.env ? ["--env", options.env] : []), ...(options.environment ? ["--environment", options.environment] : []), ...(options.args !== undefined ? ["--args", options.args] : []), ...(options.argsFile !== undefined ? ["--args-file", options.argsFile] : []), ...(options.argsList !== undefined ? ["--args-list", options.argsList] : []), ...(options.preflight ? ["--preflight"] : []), ...(Array.isArray(options.extract) ? options.extract.flatMap((path) => ["--extract", path]) : []), ...(Array.isArray(options.jq) ? options.jq.flatMap((path) => path === true ? ["--jq"] : ["--jq", path]) : []), ...(options.extractKeys ? ["--extract-keys"] : []),
             ...(options.keys ? ["--keys"] : []), ...(options.maxOutputBytes !== undefined ? ["--max-output-bytes", options.maxOutputBytes] : []), ...(options.requestId ? ["--request-id", options.requestId] : []), ...(options.timeoutMs !== undefined ? ["--timeout-ms", options.timeoutMs] : []), ...(options.wait !== undefined ? ["--wait", options.wait] : []), ...(options.dryRun ? ["--dry-run"] : [])];
         commandExitCode = await cmdCall(new ConfigStore(defaultPaths()), rest);
@@ -2030,7 +2244,7 @@ async function main() {
         .option("--code <schemaCode>", "模型 code")
         .option("--schema <schemaCode>")
         .option("--name <name>", "模型名")
-        .option("--fields <json>", "JSON 数组，每条是一个 field.create 参数；子表加 childFields")
+        .option("--fields <json>", "JSON 数组，每条是一个 field.create 参数；子表加 subFields")
         .option("--fields-json <json>")
         .option("--folder <folderId>", "建在哪个应用目录（省略=默认目录）")
         .option("--app <applicationCode>")
@@ -2049,7 +2263,7 @@ async function main() {
         `  常见错写：DEPARTMENT_MULTI→DEPARTMENT_MULTI_SELECTOR、STAFF_SINGLE→STAFF_SELECTOR、DROP_DOWN_BOX→DROPDOWN_BOX\n\n` +
         `choices（RADIO/CHECKBOX/DROPDOWN 系列）：**字符串数组**，如 [\"待处理\",\"已完成\"]——不是 [{key,value}]\n` +
         `关联字段（WORK_SHEET/MULT_WORK_SHEET）：options:{\"schemaCode\":\"<目标模型>\"} + relativeCode:\"<目标模型>\"\n` +
-        `子表：childFields:[…]（每条同字段形状）\n`)
+        `子表：subFields:[…]（每条同字段形状；childFields 仍作别名接受）\n`)
         .action(async (options) => {
         const rest = ["model-scaffold",
             ...(options.code ? ["--code", options.code] : []),
@@ -2107,23 +2321,20 @@ async function main() {
             ...(options.apply ? ["--apply"] : [])];
         commandExitCode = await cmdFieldAdd(rest);
     });
-    command.command("script [file]").option("--env <environment>", "行内无 env 时的默认环境").option("--continue", "某行失败后继续执行剩余行（默认停在首个失败）").description("NDJSON 多调脚本：每行 {\"tool\":\"<名称>\",\"args\":{...},\"env\":\"<环境>\",\"dryRun\":true}（# 注释/空行忽略；file 为 - 读 stdin）；一个进程一次会话跑完全部，逐行输出 {index,tool,exitCode,result}").action(async (file, options) => {
+    command.command("script [file]").option("--env <environment>", "行内无 env 时的默认环境").option("--continue", "某行失败后继续执行剩余行（默认首败即停）").description("NDJSON 多调脚本：每行 {\"tool\":\"<名称>\",\"args\":{...},\"env\":\"<环境>\",\"dryRun\":true}（# 与 // 注释/空行忽略；其它非法行跳过计入 summary.skipped；file 为 - 读 stdin）。一个进程一次会话串行跑完全部（共用登录，比逐条 omc call 快；测写锁竞争请用多个独立 omc call 进程）。逐行输出 {index,tool,exitCode,result}，末行 {summary:{total,ok,failed,skipped,stoppedAt?}}。").action(async (file, options) => {
         const { runScript, parseScript, readScriptInput } = await import("./script.js");
-        let lines;
-        try {
-            lines = parseScript(readScriptInput(file ?? "-"));
-        }
-        catch (error) {
-            console.error(String(error instanceof Error ? error.message : error));
-            commandExitCode = CLI_EXIT_CODES.invalidInput;
-            return;
-        }
-        if (lines.length === 0) {
-            console.error("脚本为空：每行一个 {\"tool\":\"<名称>\",\"args\":{...}} 调用");
+        const parsed = parseScript(readScriptInput(file ?? "-"));
+        const lines = parsed.lines;
+        if (lines.length === 0 && parsed.skipped.length === 0) {
+            console.error("脚本为空：每行一个 {\"tool\":\"<名称>\",\"args\":{...}} 调用（# 与 // 开头为注释）");
             commandExitCode = CLI_EXIT_CODES.invalidInput;
             return;
         }
-        commandExitCode = await runScript(lines, { defaultEnv: options.env, continueOnError: options.continue === true });
+        commandExitCode = await runScript(lines, {
+            defaultEnv: options.env,
+            continueOnError: options.continue === true,
+            skipped: parsed.skipped,
+        });
         // `script` emits NDJSON (one envelope per line), so the single-envelope
         // recorder never ran and usage.jsonl left every batch at its initial
         // "no-envelope" status — a successful 4-call batch looked like 4 failures
@@ -2132,7 +2343,7 @@ async function main() {
         recordUsageOutput({
             status: commandExitCode === 0 ? "ok" : "refused",
             ...(commandExitCode === 0 ? {} : { error: { code: "script-batch-failed" } }),
-            script: { lines: lines.length },
+            script: { lines: lines.length, skipped: parsed.skipped.length },
         }, 0);
     });
     const rollbackCommand = command.command("rollback").description("配置回滚（git-revert 语义）：list 列写时间线 / plan 预览恢复（diff+后续写覆盖警告）/ apply 执行恢复——恢复走完整写闸门并记 journal（回滚可再回滚）。接入全部配置写面（workflow/规则/数据规则/视图/表单草稿/在线JS/字典/字段/模型/应用/报表）；publish 类生命周期推进不可逆（plan 会说明）；journal 与 before 快照为本机边界（不跨机器）");
@@ -2187,14 +2398,15 @@ async function main() {
             pureKeys: (options.keys === true || bareJq) && options.summary !== true, ...(typeof options.keys === "string" ? { keys: options.keys } : {}), full: options.full === true }));
     });
     command.command("bench").option("--live-sample").option("--env <environment>").action(async (options) => { commandExitCode = await cmdBench([...(options.liveSample ? ["--live-sample"] : []), ...(options.env ? ["--env", options.env] : [])]); });
-    command.command("commands").option("--json").option("--compact").option("--filter <keyword>").option("--lane <id>").option("--max-output-bytes <bytes>").action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("commands", transport, undefined, { json: options.json === true, compact: options.compact === true, ...(options.filter ? { filter: options.filter } : {}), ...(options.lane ? { lane: options.lane } : {}) })); });
-    command.command("describe <tool>").option("--full").option("--schema-only").option("--param <name>").option("--example [id]").option("--max-output-bytes <bytes>").action(async (tool, options) => {
-        commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("describe", transport, tool, { full: options.full === true, schemaOnly: options.schemaOnly === true, ...(options.param ? { param: options.param } : {}), ...(options.example ? { example: options.example } : {}) }));
+    const jqOption = () => new Option("--jq [path]", "路径投影（与 call --jq 同 DSL；可逗号多路径；裸 --jq 列顶层键）").argParser((value, previous = []) => [...previous, value]).default([]);
+    command.command("commands").option("--json").option("--compact").option("--filter <keyword>").option("--lane <id>").option("--max-output-bytes <bytes>").addOption(jqOption()).action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("commands", transport, undefined, { json: options.json === true, compact: options.compact === true, ...(options.filter ? { filter: options.filter } : {}), ...(options.lane ? { lane: options.lane } : {}), ...(options.jq !== undefined ? { jq: options.jq } : {}) })); });
+    command.command("describe <tool>").option("--full").option("--cache-ok", "允许 --full 在同会话重复读时短路为 artifact 指针（默认每次回全文）").option("--schema-only").option("--param <name>").option("--example [id]").option("--max-output-bytes <bytes>").addOption(jqOption()).action(async (tool, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("describe", transport, tool, { full: options.full === true, cacheOk: options.cacheOk === true, schemaOnly: options.schemaOnly === true, ...(options.param ? { param: options.param } : {}), ...(options.example ? { example: options.example } : {}), ...(options.jq !== undefined ? { jq: options.jq } : {}) }));
     });
-    command.command("contract <lane>").option("--full").option("--tool <name>").option("--max-output-bytes <bytes>").action(async (lane, options) => { commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("contract", transport, lane, { full: options.full === true, ...(options.tool ? { tool: options.tool } : {}) })); });
+    command.command("contract <lane>").option("--full").option("--tool <name>").option("--max-output-bytes <bytes>").addOption(jqOption()).action(async (lane, options) => { commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("contract", transport, lane, { full: options.full === true, ...(options.tool ? { tool: options.tool } : {}), ...(options.jq !== undefined ? { jq: options.jq } : {}) })); });
     // 2026-11-05 用户实测：`commands --json` 存在，于是大家自然写 `capabilities --json`
     // ——旧实现报 `unknown option`（退出码 10）。输出本来就是 JSON 信封，接受它做兼容别名。
-    command.command("capabilities").option("--compact").option("--json", "兼容别名：输出本就是 JSON 信封（与 commands --json 对齐）").option("--max-output-bytes <bytes>").action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdCapabilities(transport, options.compact === true)); });
+    command.command("capabilities").option("--compact").option("--json", "兼容别名：输出本就是 JSON 信封（与 commands --json 对齐）").option("--max-output-bytes <bytes>").addOption(jqOption()).action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdCapabilities(transport, options.compact === true, options.jq)); });
     // `--env` is accepted but ignored: `next` is a zero-environment-contact route
     // solver, and a caller who reflexively passes `--env` should not be refused
     // (round 15 dogfood: `next "<goal>" --env local` → unknown option, one round).
@@ -2208,8 +2420,8 @@ async function main() {
             ...(Number.isFinite(parsedTop) && parsedTop > 0 ? { top: parsedTop } : {}),
         }));
     });
-    command.command("capability <id>").option("--executable").option("--max-output-bytes <bytes>").action(async (id, options) => {
-        commandExitCode = await withTransport(options, request, (transport) => cmdCapability(id, transport, options.executable === true));
+    command.command("capability <id>").option("--executable").option("--max-output-bytes <bytes>").addOption(jqOption()).action(async (id, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdCapability(id, transport, options.executable === true, options.jq));
     });
     const intentCommand = command.command("intent");
     intentCommand.command("schema").option("--example [id]").action((options) => { commandExitCode = cmdIntentSchema({ request, maxOutputBytes: CLI_DEFAULT_OUTPUT_BYTES }, typeof options.example === "string" ? options.example : undefined, options.example !== undefined); });

package/dist/describe-cache.js

@@ -51,9 +51,13 @@ function writeCache(cache) {
 /**
  * Return the compact repeat-read face for `tool`, or `undefined` when this is
  * the first read (or the contract changed). Records the new entry as a side
- * effect so the NEXT read is compact.
+ * effect so the NEXT `--cache-ok` read can be compact.
+ *
+ * r31b F3: `--full` alone always wants the body. Pass `{ recordOnly:true }` to
+ * refresh the cache without short-circuiting; pass nothing / `{cacheOk:true}`
+ * (via CLI `--full --cache-ok`) to allow the compact face.
  */
-export function repeatFullDescribe(tool, result) {
+export function repeatFullDescribe(tool, result, options = {}) {
     // No project session (repo tests, golden master, one-off runs) ⇒ no cache:
     // those callers need byte-stable output, and a cache write would be litter.
     if (!projectSessionActive())
@@ -63,7 +67,7 @@ export function repeatFullDescribe(tool, result) {
     const digest = createHash("sha256").update(body).digest("hex");
     const cache = readCache();
     const previous = cache[tool];
-    if (previous && previous.sha256 === digest && Date.now() - previous.at < CACHE_TTL_MS) {
+    if (!options.recordOnly && previous && previous.sha256 === digest && Date.now() - previous.at < CACHE_TTL_MS) {
         // A pruned artifact would turn the summary into a dead end; re-ship instead.
         if (existsSync(join(artifactRoot(), `${previous.artifactId}.artifact`))) {
             try {
@@ -75,7 +79,7 @@ export function repeatFullDescribe(tool, result) {
                     sha256: digest,
                     bytes,
                     fetch: `omc artifact get ${previous.artifactId} --summary（再 --keys/--jq 取需要的键）`,
-                    note: `本项目的会话里已读过同一个契约（${bytes}B，内容 sha256 未变），本次不再重发全文；用 fetch 里的命令按需投影`,
+                    note: `本项目的会话里已读过同一个契约（${bytes}B，内容 sha256 未变），本次因 --cache-ok 不再重发全文；要全文请去掉 --cache-ok 再 --full`,
                 };
             }
             catch {