@stalfh233/omc-cli 0.4.88 → 0.4.91

package/dist/cli-contract.js

@@ -75,8 +75,83 @@ export function serializeEnvelope(value) {
 export function requestId() {
     return randomUUID();
 }
+/**
+ * Derive a runnable next command from a refusal payload. Tools that already
+ * carry a structured recovery (an explicit `nextCommand`, an artifact `fetch`
+ * hint, `recovery[].command`, command-shaped `checks`, or a prepared
+ * `nextSubmit`) do not need their prose parsed; everything else stays null
+ * rather than inventing a command that does not apply.
+ */
+export function nextCommandFor(result) {
+    const commandFrom = (text) => {
+        if (typeof text !== "string")
+            return undefined;
+        const trimmed = text.trim();
+        if (/^omc\s/.test(trimmed))
+            return trimmed;
+        // Recovery entries are often "① 按流程收窄（最可靠）：omc call …" — the
+        // command is there, just after a human marker.
+        const index = trimmed.indexOf("omc ");
+        return index > 0 ? trimmed.slice(index).trim() : undefined;
+    };
+    const explicit = result.nextCommand;
+    if (typeof explicit === "string" && explicit.trim().length > 0)
+        return explicit.trim();
+    const fromFetch = commandFrom(result.fetch);
+    if (fromFetch !== undefined)
+        return fromFetch;
+    const recovery = result.recovery;
+    if (Array.isArray(recovery)) {
+        for (const entry of recovery) {
+            if (entry === null || typeof entry !== "object")
+                continue;
+            const command = commandFrom(entry.command);
+            if (command !== undefined)
+                return command;
+        }
+    }
+    for (const list of [result.checks, result.workaround]) {
+        if (!Array.isArray(list))
+            continue;
+        for (const entry of list) {
+            const command = commandFrom(entry);
+            if (command !== undefined)
+                return command;
+        }
+    }
+    // A submit that advanced the flow already prepared the NEXT approval args —
+    // expose the command instead of making the caller reassemble JSON by hand.
+    const nextSubmit = result.nextSubmit;
+    if (nextSubmit !== null && typeof nextSubmit === "object" && !Array.isArray(nextSubmit)) {
+        const record = nextSubmit;
+        if (typeof record.schemaCode === "string" && typeof record.workItemId === "string") {
+            const args = {
+                schemaCode: record.schemaCode,
+                bizObjectId: record.bizObjectId ?? null,
+                workflowInstanceId: record.workflowInstanceId ?? null,
+                workItemId: record.workItemId,
+                agree: true,
+            };
+            return `omc call data.submit --args '${JSON.stringify(args)}'`;
+        }
+    }
+    const nextWorkItems = result.nextWorkItems;
+    if (Array.isArray(nextWorkItems) && nextWorkItems.length > 0 && typeof result.schemaCode === "string") {
+        const item = nextWorkItems[0];
+        if (item !== null && typeof item === "object") {
+            const workItemId = item.workItemId;
+            if (typeof workItemId === "string")
+                return `omc call data.submit --args '${JSON.stringify({ schemaCode: result.schemaCode, workItemId, agree: true })}'`;
+        }
+    }
+    return undefined;
+}
 export function classifyResult(result) {
     const status = String(result.status ?? "ok");
+    const withNext = (error) => {
+        const nextCommand = nextCommandFor(result);
+        return nextCommand === undefined ? error : { ...error, nextCommand };
+    };
     if (status === "ok")
         return { status, error: null, exitCode: CLI_EXIT_CODES.ok };
     if (status === "dry-run")
@@ -88,30 +163,45 @@ export function classifyResult(result) {
         const succeeded = Number(result.succeeded ?? 0);
         const requested = Number(result.requested ?? 0);
         const failed = Number(result.failed ?? 0);
+        // A `--preflight` batch shape-checks entries instead of executing them; the
+        // message must not claim "N 成功/失败" for calls that never ran.
+        // A step-chain command (model-purge) also answers `partial`, and the batch
+        // wording read "6/7 成功，0 失败" — meaningless for steps (r15).
+        const isBatch = typeof result.tool === "string";
+        const message = result.mode === "preflight"
+            ? `${failed}/${requested} 条未过写前校验（preflight：零 wire、零写入）；逐条原因见 failures[]`
+            : isBatch
+                ? `${succeeded}/${requested} 成功，${failed} 失败；逐条原因见 failures[] / failedSteps[]（--args-list 的 index 指向第几条）`
+                : `部分步骤失败：逐条原因见 steps[] 的 status/detail（已在失败处停下；幂等，修好后重跑同一条命令）`;
         return {
             status,
-            error: { code: "partial-batch", message: `${succeeded}/${requested} 成功，${failed} 失败；逐条原因见 failures[] / failedSteps[]（--args-list 的 index 指向第几条）`, retryable: false },
+            error: withNext({ code: "partial-batch", message, retryable: false }),
             exitCode: 1,
         };
     }
     if (status === "unknown-tool") {
         const candidates = Array.isArray(result.candidates) ? result.candidates : [];
         const suffix = candidates.length > 0 ? `；did you mean: ${candidates.join("、")}` : "；用 `omc commands --json --compact --lane <lane>` 或 `omc next` 定位工具";
-        return { status: "error", error: { code: "invalid-input", message: `unknown tool ${String(result.tool ?? "")}${suffix}`, retryable: false }, exitCode: CLI_EXIT_CODES.invalidInput };
+        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")
-        return { status: "error", error: { code: "invalid-input", message: String(result.message ?? "tool input is invalid"), retryable: false }, exitCode: CLI_EXIT_CODES.invalidInput };
+        return { status: "error", error: withNext({ code: "invalid-input", message: String(result.message ?? "tool input is invalid"), retryable: false }), exitCode: CLI_EXIT_CODES.invalidInput };
     if (status === "uncertain")
-        return { status, error: { code: "uncertain", message: String(result.message ?? result.reason ?? "outcome is uncertain"), retryable: true }, exitCode: CLI_EXIT_CODES.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") {
         if (result.blocker === "write-lock-held")
-            return { status, error: { code: "policy-refused", message: String(result.message ?? "write lock held"), retryable: true }, exitCode: CLI_EXIT_CODES.policyRefused };
+            return { status, error: withNext({ code: "policy-refused", message: String(result.message ?? "write lock held"), retryable: true }), exitCode: CLI_EXIT_CODES.policyRefused };
         const auth = String(result.blocker ?? "").startsWith("auth") || String(result.blocker ?? "").includes("credential");
-        return { status, error: { code: auth ? "auth-config" : "policy-refused", message: String(result.message ?? result.blocker ?? "operation refused"), retryable: false }, exitCode: auth ? CLI_EXIT_CODES.authConfig : CLI_EXIT_CODES.policyRefused };
+        // Every refusal gets a next step: a specific command when the tool knows
+        // one, otherwise the refusal router (`omc-refusals` explains which gate
+        // produced it — the documented path in omc-start-here).
+        const error = { code: auth ? "auth-config" : "policy-refused", message: String(result.message ?? result.blocker ?? "operation refused"), retryable: false };
+        const nextCommand = nextCommandFor(result) ?? (auth ? undefined : "omc help omc-refusals");
+        return { status, error: nextCommand === undefined ? error : { ...error, nextCommand }, exitCode: auth ? CLI_EXIT_CODES.authConfig : CLI_EXIT_CODES.policyRefused };
     }
     const message = String(result.message ?? "internal error");
     const auth = /credential|configuration|environment|login|authentication|auth/i.test(message);
-    return { status: "error", error: { code: auth ? "auth-config" : "internal", message, retryable: false }, exitCode: auth ? CLI_EXIT_CODES.authConfig : CLI_EXIT_CODES.internal };
+    return { status: "error", error: withNext({ code: auth ? "auth-config" : "internal", message, retryable: false }), exitCode: auth ? CLI_EXIT_CODES.authConfig : CLI_EXIT_CODES.internal };
 }
 export function errorEnvelope(error, code, exitCode, request) {
     const message = error instanceof Error ? error.message : String(error);

package/dist/cli.js

@@ -15,12 +15,12 @@ import { BATCH_MAX_ENTRIES, runBatchCall } from "./batch-call.js";
 import { cmdModelScaffold } from "./model-scaffold.js";
 import { cmdModelPurge } from "./model-purge.js";
 import { environmentWritable, requiresProductionConfirmation } from "./environment-policy.js";
-import { CLI_EXIT_CODES, classifyResult, envelope, errorEnvelope, requestId } from "./cli-contract.js";
+import { CLI_EXIT_CODES, classifyResult, envelope, errorEnvelope, refusalText, requestId } from "./cli-contract.js";
 import { configureOutput, humanSummary, stripOutputFlags, writeEnvelope } from "./cli-output.js";
 import { beginUsage, completeUsage, ensureProjectIgnore, recordUsageOutput, usageReport } from "./usage-log.js";
 import { artifactFetchHint, artifactRoot, boundResult, emitInvalid, emitResult, emitTransportResult, outputBudget, readArtifact, withTransport, } from "./command-transport.js";
 import { CLI_DEFAULT_OUTPUT_BYTES, assertSafeOutputPath, pruneArtifacts } from "./artifacts.js";
-import { projectJsonPath, projectResultExtract } from "./path-projection.js";
+import { 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";
@@ -319,6 +319,52 @@ async function cmdBatchCall(store, toolName, rawList, options) {
         }));
         return CLI_EXIT_CODES.invalidInput;
     }
+    // Whole-batch shape precheck (issue 2026-10-25 §6): `--args-list --dry-run`
+    // runs every entry through the full tool (reads included) to report N
+    // previews. When the caller only wants "will this batch be accepted", the
+    // per-tool semantic gate is the thing that refuses mis-shapes, and it is
+    // pure — no wire, no writes. Run it for every entry and report ALL failures
+    // in one envelope instead of N round-trips.
+    if (options.preflight === true) {
+        const registry = buildToolRegistry();
+        const tool = registry.find((definition) => definition.name === toolName);
+        if (!tool) {
+            writeEnvelope(envelope("error", {}, request, { code: "invalid-input", message: `unknown tool ${toolName}；用 omc next 或 omc commands --json --compact --lane <lane> 定位`, retryable: false }));
+            return CLI_EXIT_CODES.invalidInput;
+        }
+        const failures = [];
+        entries.forEach((entry, index) => {
+            try {
+                const parsedEntry = parseToolInput(tool, {
+                    ...entry,
+                    ...(options.environment !== undefined && entry.environment === undefined ? { environment: options.environment } : {}),
+                });
+                tool.writePreflight?.(parsedEntry);
+            }
+            catch (error) {
+                // ToolRefusalError carries the real payload (blocker/citation/validation);
+                // rebuild it only when the failure is a plain Error.
+                const carried = error.payload;
+                const payload = error instanceof ToolInputError ? error.payload : carried ?? { status: "refused", blocker: "tool-input-invalid", message: error instanceof Error ? error.message : String(error) };
+                failures.push({ index, blocker: payload.blocker ?? null, message: refusalText(payload), ...(Array.isArray(payload.validation) ? { validation: payload.validation } : {}), ...(payload.citation !== undefined ? { citation: payload.citation } : {}) });
+            }
+        });
+        const result = {
+            status: failures.length > 0 ? "partial" : "ok",
+            mode: "preflight",
+            tool: toolName,
+            requested: entries.length,
+            shapeChecked: entries.length,
+            failed: failures.length,
+            writes: 0,
+            // On failure the caller has to change the JSON first, so there is no
+            // runnable command yet; on success, hand over the exact execution command.
+            ...(failures.length > 0 ? { failures } : { nextCommand: `omc call ${toolName} --args-list ${JSON.stringify(JSON.stringify(entries))}` }),
+        };
+        const classified = classifyResult(result);
+        writeEnvelope(envelope(classified.status, result, request, classified.error));
+        return failures.length > 0 ? 1 : 0;
+    }
     const batched = await runBatchCall({
         tool: toolName,
         argsList: entries,
@@ -352,7 +398,7 @@ 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")) {
-        console.error("用法：omc call <tool> [--env <环境>] [--args '<json>' | --args - (stdin) | --args-file <配置根内路径>] [--extract <path>]... [--extract-keys]");
+        console.error("用法：omc call <tool> [--env <环境>] [--args '<json>' | --args - (stdin) | --args-file <配置根内路径>] [--extract <path>]... [--jq [path]] [--extract-keys] [--args-list <json数组> [--preflight]]");
         console.error("写入：由环境 writable 决定（只读环境拒写）；生产环境的写必须在 args 里带 confirmProduction:true。");
         return emit(toolName && toolName !== "help" ? "error" : "ok", {}, toolName && toolName !== "help" ? CLI_EXIT_CODES.invalidInput : 0);
     }
@@ -361,14 +407,19 @@ async function cmdCall(store, args) {
     // Batch mode: the SAME tool N times, one process (r12: 36 field.create calls).
     const argsList = flag("--args-list");
     if (argsList !== undefined)
-        return cmdBatchCall(store, toolName, argsList, { environment, requestValue, args });
+        return cmdBatchCall(store, toolName, argsList, { environment, requestValue, args, preflight: args.includes("--preflight") });
     // 1.2 of issue 2026-10-23: read faces answer {detailArtifactId, sha256} and the
     // caller then needs a SECOND call to see one value (16 two-step chains in one
     // session; 15 more were pure --keys probes). `--extract <path>` (repeatable)
     // resolves the path inside the artifact of THIS result and returns only the
     // value; `--extract-keys` lists the artifact's top-level keys with sizes.
-    const extractPaths = argvValues(args, "--extract");
-    const extractKeys = args.includes("--extract-keys");
+    //
+    // issue 2026-10-25 §8: `artifact get` had `--jq` while `omc call` did not, so
+    // every list read that only wanted one column paid a second artifact round.
+    // `--jq` is the same path projection plus `[]` fan-out; a bare `--jq` is the
+    // key inventory (the same muscle memory as `artifact get <id> --jq`).
+    const extractPaths = [...argvValues(args, "--extract"), ...argvValues(args, "--jq")];
+    const extractKeys = args.includes("--extract-keys") || args.some((token, index) => token === "--jq" && (args[index + 1] === undefined || args[index + 1].startsWith("--")));
     const dryRun = args.includes("--dry-run");
     const waitValue = flag("--wait");
     let waitMs = 0;
@@ -547,6 +598,23 @@ function parseDurationMs(text) {
  * template re-read three times is 81 KB of the session.
  */
 const ARTIFACT_INLINE_CEILING_BYTES = 8192;
+/**
+ * `artifact get --jq`: one path walk, with `[]` fan-out (same syntax as
+ * `omc call --jq`). Returns the envelope fields so both the `--summary` and the
+ * plain branch stay identical.
+ */
+function projectArtifactPath(value, path) {
+    if (!path.includes("[]")) {
+        const projected = projectJsonPath(value, path);
+        return projected.missed
+            ? { missed: true, ...(projected.at !== undefined ? { at: projected.at } : {}), ...(projected.available !== undefined ? { available: projected.available } : {}) }
+            : { missed: false, content: projected.value ?? null };
+    }
+    const fanout = projectJsonPathFanout(value, path);
+    return fanout.missed
+        ? { missed: true, ...(fanout.at !== undefined ? { at: fanout.at } : {}), ...(fanout.available !== undefined ? { available: fanout.available } : {}) }
+        : { missed: false, content: fanout.values, mapped: fanout.values.length, ...(fanout.missedEntries > 0 ? { missedEntries: fanout.missedEntries } : {}) };
+}
 function formatBytes(bytes) {
     if (bytes < 1024)
         return `${bytes}B`;
@@ -579,10 +647,10 @@ async function cmdArtifactGet(id, transport, options = {}) {
             // this the caller had to spend one round on the shape and another on the
             // path (or pull the whole body); r5 hit that on 67 KB workflow templates.
             if (options.jq !== undefined) {
-                const projected = projectJsonPath(artifact.content.toString("utf8") === "" ? undefined : content, options.jq);
+                const projected = projectArtifactPath(artifact.content.toString("utf8") === "" ? undefined : content, options.jq);
                 return emitTransportResult(projected.missed
                     ? { status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, keys, projection: { path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available }, fetch: artifactFetchHint(id) }
-                    : { status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, keys, projection: { path: options.jq, content: projected.value ?? null } }, transport);
+                    : { status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, keys, projection: { path: options.jq, content: projected.content ?? null, ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}) } }, transport);
             }
             return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, keys, fetch: artifactFetchHint(id) }, transport);
         }
@@ -611,10 +679,10 @@ async function cmdArtifactGet(id, transport, options = {}) {
             return emitTransportResult(result, transport);
         }
         if (options.jq !== undefined) {
-            const projected = projectJsonPath(artifact.content.toString("utf8") === "" ? undefined : content, options.jq);
+            const projected = projectArtifactPath(artifact.content.toString("utf8") === "" ? undefined : content, options.jq);
             return emitTransportResult(projected.missed
-                ? { status: "ok", artifactId: id, sha256: artifact.sha256, path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, hint: `路径未命中段 "${projected.at}"——available 是该层可用的键/范围；方括号下标（a[0]）与点式（a.0）等价` }
-                : { status: "ok", artifactId: id, sha256: artifact.sha256, path: options.jq, content: projected.value ?? null }, transport);
+                ? { status: "ok", artifactId: id, sha256: artifact.sha256, path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, hint: `路径未命中段 "${projected.at}"——available 是该层可用的键/范围；方括号下标（a[0]）与点式（a.0）等价；[] 映射数组（items[].fields.x）` }
+                : { status: "ok", artifactId: id, sha256: artifact.sha256, path: options.jq, content: projected.content ?? null, ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}) }, transport);
         }
         // r6-onboarding 2026-10-21: 47 artifact fetches, 0 used a projection; the 10
         // large ones (up to 55 KB) pulled whole workflow templates just to read one
@@ -1090,7 +1158,7 @@ function onboardingHelp() {
         "首次使用、或不确定从哪开始：omc help omc-start-here（随包权威 topic 路线）；被拒或状态异常：omc help omc-refusals。",
         "方法论按需读：omc help <topic> 默认只回节索引（每节字节数）；用 --section \"<标题>\" 取正文（可重复），确需整篇才 --all。",
         "目标→工具一步定位：omc next \"<你要做什么>\"（离线、只读，给能力/说明/首批命令；不确定会明说并回退到 omc-requirement-analysis）。",
-        "大结果取值一步到位：读面回 detailArtifactId 时，用 omc call <tool> … --extract <path>（可重复）或 --extract-keys，省掉再跑一次 omc artifact get；artifact get 正文超 8KB 默认也只回形状（--jq/--keys 定向取，--full 才整包）。",
+        "大结果取值一步到位：读面回 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、零写入，一次报全）。",
         "工具发现：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。",
@@ -1214,8 +1282,8 @@ 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 汇总。适合批量建字段等').addOption(new Option("--extract <path>", "在本次结果的 artifact 内取一个路径的值（可重复；省掉一次 artifact get）").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) => {
-        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] : []), ...(Array.isArray(options.extract) ? options.extract.flatMap((path) => ["--extract", path]) : []), ...(options.extractKeys ? ["--extract-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"] : [])];
+    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、零写入），一次报全所有形状问题").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) => {
+        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.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);
     });
     command.command("compute").option("--schema <schemaCode>").option("--schema-code <schemaCode>").option("--target <propertyCode>").option("--property <propertyCode>").option("--formula <formula>").option("--where <condition>", "条件聚合：\"<子列code> = <值>\"，与 --formula \"{<子表code>.<子列code>}\" 配合编译为 COUNTIF/SUMIF").option("--aggregate <count|sum>", "条件聚合用哪种：count（默认，→COUNTIF）/ sum（→SUMIF）").option("--allow-unfiltered", "显式接受「对整个子表列无条件聚合」；不给则拒绝（会把不符合条件的行也算进去）").option("--name <name>").option("--env <environment>").option("--environment <environment>").option("--apply").addHelpText("after", "\n字段计算规则拼装器：公式 {字段} 引用 → datarule type2 完整形状（editorText/editorMark 自动生成）。默认 dry-run，--apply 写入。条件聚合用 --formula \"{子表.子列}\" --where \"子列 = 值\"。复杂场景（条件分支/跨模型）走 omc next 的 recipe 路径。\n").action(async (options) => {

package/dist/goal-routes.js

@@ -113,6 +113,29 @@ function capabilityScores(registry, goal) {
     }
     return scores;
 }
+/**
+ * Default ladder examples (r15). A ladder step with no goal-matching recipe only
+ * got `omc commands --lane`, so "创建业务规则" handed the caller nothing runnable
+ * even though `rule.save` ships examples. These are the lane's canonical shapes,
+ * used ONLY when the goal does not match a specific recipe.
+ */
+const DEFAULT_LADDER_RECIPES = {
+    businessrule: { tool: "rule.save", recipe: "business-rule-branch-conditional" },
+    datarule: { tool: "datarule.create", recipe: "field-compute-rule" },
+};
+function defaultRecipeFor(registry, capabilityId, lane) {
+    const wanted = DEFAULT_LADDER_RECIPES[capabilityId];
+    if (!wanted)
+        return undefined;
+    for (const tool of registry) {
+        if (tool.name !== wanted.tool || tool.lane !== lane)
+            continue;
+        const recipe = (tool.executionMetadata?.recipes ?? []).find((entry) => entry.id === wanted.recipe);
+        if (recipe)
+            return { tool: tool.name, recipe: recipe.id, title: recipe.title };
+    }
+    return undefined;
+}
 function bestRecipe(registry, capabilityId, lane, goal, minScore = 3) {
     let best;
     for (const tool of registry) {
@@ -238,17 +261,27 @@ function sectionPointersFor(ids) {
     return pointers;
 }
 /**
- * Ready-to-run methodology reads, one per topic, that fetch ALL of that topic's
- * relevant sections in a single call. Round 15: bench60-62 fetched each
- * `readSections` entry separately (~18 round-trips); `--section` is repeatable
- * and comma-separated, so grouping by topic collapses them to ~3 without adding
- * any bytes (the outputs land in context either way — the saving is turns).
+ * Ready-to-run methodology reads.
+ *
+ * Round 15 (bench60-62) collapsed ~18 per-section reads into one per topic to
+ * save turns. r10 F7 found the other edge: following that hint fetched
+ * EVERYTHING at once (~15 KB) when most tasks need only the first section.
+ * So the primary command per topic fetches the FIRST required section, and the
+ * remaining sections are offered as separate incremental commands (each keeps
+ * its byte count in `readSections`) — cheap by default, still one command away.
  */
-function batchReadCommands(pointers) {
+function splitReadCommands(pointers) {
     const byTopic = new Map();
     for (const pointer of pointers)
         byTopic.set(pointer.topic, [...(byTopic.get(pointer.topic) ?? []), pointer.section]);
-    return [...byTopic.entries()].map(([topic, sections]) => `omc help ${topic} ${sections.map((section) => `--section "${section}"`).join(" ")}`);
+    const readCommands = [];
+    const readMore = [];
+    for (const [topic, sections] of byTopic.entries()) {
+        readCommands.push(`omc help ${topic} --section "${sections[0]}"`);
+        for (const section of sections.slice(1))
+            readMore.push(`omc help ${topic} --section "${section}"`);
+    }
+    return { readCommands, readMore };
 }
 /**
  * The route's methodology-read surface: pointers (+ per-section bytes) +
@@ -279,14 +312,15 @@ function routeReads(readSections) {
             }
         }
     }
-    return { readSections: budgeted, readCommands: batchReadCommands(readSections), readHint: READ_HINT, ...(firstSection !== undefined ? { firstSection } : {}) };
+    const commands = splitReadCommands(readSections);
+    return { readSections: budgeted, readCommands: commands.readCommands, ...(commands.readMore.length > 0 ? { readMore: commands.readMore } : {}), readHint: READ_HINT, ...(firstSection !== undefined ? { firstSection } : {}) };
 }
 /** UTF-8 byte length of one methodology section (best-effort; 0 when unreadable). */
 function sectionBytes(pointer) {
     const resolved = readSkillSection(pointer.topic, pointer.section);
     return resolved ? Buffer.byteLength(resolved.section, "utf8") : 0;
 }
-const READ_HINT = '按 readCommands 一次读完（每条命令用可重复的 `--section` 取该 topic 的所有相关节，等价于逐节 `omc help <topic> --section "<section>"` 但只花一次往返）；单节字节数见 readSectionBudget，按预算自选。`omc help <topic>` 默认只回节索引（每节带字节数，约 1KB），不要再用 `--all` 读整篇（5–14KB，读一次就留在后续每一轮）。';
+const READ_HINT = '先跑 readCommands（每个 topic 只取第一节，形状 `omc help <topic> --section "<section>"`，字节数见 readSections）；不够再按需补 readMore，不要一次全读。`omc help <topic>` 默认只回节索引（每节带字节数，约 1KB），不要再用 `--all` 读整篇（5–14KB，读一次就留在后续每一轮）。';
 function orderedCapabilities(ids, index) {
     const selected = new Set(ids);
     const nodes = [...index.nodeById.values()];
@@ -322,6 +356,18 @@ function orderedCapabilities(ids, index) {
  */
 const WHOLE_PACKAGE_CAPABILITIES = ["model", "field", "form", "listview", "datarule", "businessrule", "workflow", "onlinejs"];
 const COMPOSER_ROUTES = Object.freeze([
+    {
+        id: "model-purge",
+        command: "omc model-purge --code <模型code> --purge-instances --apply",
+        usage: "omc model-purge --help",
+        summary: "清理一个模型：先删流程实例，再 model.delete 级联带走流程模板/视图/字段/表单/规则；默认 dry-run，不可删的停滞实例会跳过并在结尾列出",
+        // r15: "清理本轮创建的模型和流程实例" matched approval-flow (流程 + 创建)
+        // and would have CREATED a workflow instead of removing one. Cleanup intents
+        // are their own composer, and this one comes first.
+        groups: [["清理", "删除", "移除", "回收", "清除", "purge", "teardown", "clean", "remove"], ["模型", "实例", "数据", "model", "instance", "data"]],
+        avoid: ["字段", "角色", "部门", "视图", "按钮", "规则图"],
+        topics: ["omc-write-hazards"],
+    },
     {
         id: "model-scaffold",
         command: "omc model-scaffold --code <模型code> --name <模型名> --fields '<JSON数组>' --apply",
@@ -339,7 +385,7 @@ const COMPOSER_ROUTES = Object.freeze([
         summary: "线性审批流一条命令：建流程 → 模板+字段只读权限 → 发布（多级用重复 --steps）",
         groups: [["审批", "流程"], ["建", "创建", "新建", "配置", "加", "搭"]],
         // Branching / countersign shapes are NOT this composer's business.
-        avoid: ["条件分支", "分支", "会签", "并行", "或签", "网关", "子流程", "动态审批人"],
+        avoid: ["条件分支", "分支", "会签", "并行", "或签", "网关", "子流程", "动态审批人", "清理", "删除", "移除", "purge", "teardown"],
         topics: ["omc-five-piece-flow"],
     },
     {
@@ -531,7 +577,7 @@ export function goalRoute(registry, goal) {
             if (readish) {
                 return { capability: id, lane: capability.lane, readTools: readToolsInLane(registry, capability.lane), firstCommand: `omc capability ${id}` };
             }
-            const recipe = bestRecipe(registry, id, capability.lane, goal);
+            const recipe = bestRecipe(registry, id, capability.lane, goal) ?? defaultRecipeFor(registry, id, capability.lane);
             return {
                 capability: id,
                 lane: capability.lane,

package/dist/lanes/field.js

@@ -45,6 +45,54 @@ function fieldRollbackSpec(toolName) {
 function parseFieldOptionsForReadback(options) {
     return decodeJsonColumn(options, JSON_COLUMN_PASSTHROUGH);
 }
+/**
+ * CHILD_TABLE(8) columns as a compact list (issue 2026-10-25 §7).
+ *
+ * The stored `subSchema` is the full designer payload — system columns included,
+ * ~37.6 KB for a 10-column child table when asked for one field by code. A caller
+ * almost always wants the column codes (to build formData / verify the attach);
+ * the raw payload stays available behind `full:true`. Accepts both the object and
+ * the JSON-string wire form.
+ */
+function childColumnsOf(subSchema) {
+    let parsed = subSchema;
+    if (typeof subSchema === "string") {
+        try {
+            parsed = JSON.parse(subSchema);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return [];
+    const properties = parsed.properties;
+    if (!Array.isArray(properties))
+        return [];
+    return properties
+        .filter((child) => child !== null && typeof child === "object")
+        .map((child) => {
+        const rawType = child.propertyType ?? child.type;
+        const type = rawType === undefined || rawType === null || Number.isNaN(Number(rawType)) ? null : Number(rawType);
+        const typeLabel = type === null ? undefined : fieldTypeLabel(type);
+        const code = String(child.code ?? child.propertyCode ?? "");
+        return {
+            code,
+            name: String(child.name ?? child.code ?? child.propertyCode ?? ""),
+            type,
+            ...(typeLabel !== undefined ? { typeName: typeLabel } : {}),
+            ...(typeof child.relativeCode === "string" && child.relativeCode ? { relativeCode: child.relativeCode } : {}),
+            // r15 feedback: the projection mixed the platform's system columns with
+            // the authored ones, so "which child columns did I declare?" still needed
+            // a filter. Keep every column but mark the system ones.
+            // `parentId` / `sortKey` are injected by the platform into every child
+            // schema (they are the child row's link + order), so they are system
+            // columns here even though a MAIN model never carries them.
+            ...(SYSTEM_FIELD_CODES.has(code) || code === "parentId" || code === "sortKey" ? { system: true } : {}),
+        };
+    })
+        .filter((child) => child.code.length > 0);
+}
 /**
  * `name_i18n` is a JSON locale map. When every locale value equals the display
  * `name` there is no translation to convey, so echoing the map on every field of
@@ -117,7 +165,21 @@ export function registerFieldLane(tools) {
                     ...(redundantNameI18n(row.name_i18n, row.name) ? {} : typeof row.name_i18n === "string" ? { name_i18n: row.name_i18n } : {}),
                     type: row.type ?? row.propertyType,
                     ...(typeLabel !== undefined ? { typeName: typeLabel } : {}),
-                    ...(row.subSchema !== undefined && row.subSchema !== null ? { subSchema: row.subSchema } : {}),
+                    // A CHILD_TABLE row's `subSchema` is the whole designer payload; the
+                    // default face carries the column list + count and keeps the raw
+                    // payload behind `full:true` (issue 2026-10-25 §7: one field read was
+                    // 37.6 KB for a 5-code answer).
+                    ...(row.subSchema !== undefined && row.subSchema !== null
+                        ? args.full === true
+                            ? { subSchema: row.subSchema }
+                            : (() => {
+                                const subColumns = childColumnsOf(row.subSchema);
+                                const businessColumns = subColumns.filter((column) => column.system !== true).length;
+                                return subColumns.length > 0
+                                    ? { subColumnCount: subColumns.length, businessSubColumnCount: businessColumns, subColumns, subSchemaHint: "子表列已投影为 code/name/type（system:true 是平台注入的系统列）；要平台原始 subSchema 加 full:true" }
+                                    : { subSchema: row.subSchema };
+                            })()
+                        : {}),
                     ...(row.relativeCode ? { relativeCode: row.relativeCode } : {}),
                     ...(typeof row.relativePropertyCode === "string" && row.relativePropertyCode ? { relativePropertyCode: row.relativePropertyCode } : {}),
                     ...(options !== undefined ? { options } : {}),
@@ -150,11 +212,20 @@ export function registerFieldLane(tools) {
                         const value = options[key];
                         return key === "readonlyFormula" ? value === true : typeof value === "string" && value.trim() !== "";
                     });
+                    // Inventory reads could not see child columns at all (r13 §7): the
+                    // only face that carried them was the 37.6 KB subSchema. Codes alone
+                    // are ~12 B each and answer "did the child columns land?".
+                    const subColumns = field.subColumns;
+                    const businessCodes = Array.isArray(subColumns) ? subColumns.filter((column) => column.system !== true).map((column) => column.code) : undefined;
                     return {
                         code: field.code,
                         type: field.type,
                         ...(field.typeName !== undefined ? { typeName: field.typeName } : {}),
                         ...(field.name !== undefined ? { name: field.name } : {}),
+                        // Inventory answers "which columns did I author?" — system
+                        // columns are reported as a count, not mixed into the list.
+                        ...(businessCodes !== undefined ? { subColumnCodes: businessCodes } : {}),
+                        ...(Array.isArray(subColumns) && subColumns.length > businessCodes.length ? { systemSubColumnCount: subColumns.length - businessCodes.length } : {}),
                         ...(conditions.length > 0 ? { conditions } : {}),
                         ...(field.shapeWarning !== undefined ? { shapeWarning: field.shapeWarning } : {}),
                     };
@@ -202,6 +273,7 @@ export function registerFieldLane(tools) {
                             type: field.type,
                             ...(field.typeName !== undefined ? { typeName: field.typeName } : {}),
                             ...(field.name !== undefined ? { name: field.name } : {}),
+                            ...(Array.isArray(field.subColumns) ? { subColumns: field.subColumns } : {}),
                             ...(conditions.length > 0 ? { conditions } : {}),
                             ...(field.shapeWarning !== undefined ? { shapeWarning: field.shapeWarning } : {}),
                         };
@@ -225,7 +297,7 @@ export function registerFieldLane(tools) {
         const draft = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "false" } })).data);
         const published = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } })).data);
         if ([...draft, ...published].some((row) => (row.code ?? row.propertyCode) === args.code))
-            throw new ToolRefusalError({ status: "refused", blocker: "duplicate-field", schemaCode: args.schemaCode, propertyCode: args.code, message: `字段 ${args.schemaCode}.${args.code} 已存在于草稿或发布面；拒绝重复 POST` });
+            throw new ToolRefusalError({ status: "refused", blocker: "duplicate-field", schemaCode: args.schemaCode, propertyCode: args.code, message: `字段 ${args.schemaCode}.${args.code} 已存在于草稿或发布面；拒绝重复 POST`, nextCommand: `omc call field.list --args '${JSON.stringify({ schemaCode: args.schemaCode, published: true, code: args.code })}'` });
         // One seam owns field-change normalization, every reproduced gate, and the
         // wire body (src/field-change.ts), so configure_model and intent share it.
         const prepared = prepareFieldChange(args);

package/dist/lanes/list-view.js

@@ -302,6 +302,21 @@ export function registerListViewLane(tools) {
                 conditions,
                 actionCodes: readArray(model, "queryActions").map((action) => action.actionCode).filter((value) => value !== undefined),
                 buttonCount: readArray(model, "customButtons").length,
+                // r14 F5 / r11 #6: the default face exposed only `buttonCount`, so a
+                // caller could not prove WHICH buttons landed (it had to trust the
+                // configure readback or cross-check rule.list). Codes + bindings cost
+                // ~40 B per button and answer "did my buttons land?"; the full
+                // script/actionConfig payload stays behind `buttons:true`.
+                buttonCodes: readArray(model, "customButtons").map((button) => button.code).filter((value) => typeof value === "string"),
+                buttonBindings: readArray(model, "customButtons")
+                    .filter((button) => typeof button.code === "string")
+                    .map((button) => ({
+                    code: button.code,
+                    ...(button.bindAction !== undefined ? { bindAction: button.bindAction } : {}),
+                    ...(button.targetCode !== undefined ? { targetCode: button.targetCode } : {}),
+                    ...(button.targetModel !== undefined ? { targetModel: button.targetModel } : {}),
+                    ...(button.targetForm !== undefined ? { targetForm: button.targetForm } : {}),
+                })),
                 // Button scripts live in h_biz_button.actionConfig (a JSON STRING)
                 // whose `scriptData` holds the source for bindAction=SCRIPT. Surfacing
                 // them here removes the "listview.get → artifact → JSON.parse →
@@ -776,7 +791,27 @@ export function registerListViewLane(tools) {
         const before = await wireCall(session, { path: ENDPOINTS.listQueryGetHeader, query: { schemaCode: args.schemaCode, code: args.code } });
         if (before.data == null)
             return { performed: { skipped: "already-absent" }, readback: { absent: true, header: null } };
-        const performed = await wireCall(session, { path: ENDPOINTS.listQueryDelete, method: "POST", query: { schemaCode: args.schemaCode, code: args.code } });
+        let performed;
+        try {
+            performed = await wireCall(session, { path: ENDPOINTS.listQueryDelete, method: "POST", query: { schemaCode: args.schemaCode, code: args.code } });
+        }
+        catch (error) {
+            // 306103 删除后将无可用视图 — the platform requires at least one visible
+            // list view per model. r15's `nextCommand` fell back to the generic
+            // refusal router; name the constraint and the only real deletion path.
+            if (error instanceof WireError && error.kind === "business" && (error.errcode === 306103 || /无可用视图/.test(error.message)))
+                throw new ToolRefusalError({
+                    status: "refused",
+                    blocker: "listview-last-visible",
+                    schemaCode: args.schemaCode,
+                    code: args.code,
+                    nextCommand: `omc model-purge --code ${args.schemaCode}`,
+                    message: `不能删除视图 ${args.code}：平台要求每个模型至少保留一条可见列表视图（306103）。` +
+                        `单独删最后一条视图没有意义——视图会随模型一起级联删除。要继续用这个模型就**就地改**（listview.configure 省略 code 即改默认视图），` +
+                        `要整体清理就用 model-purge（默认 dry-run，先看计划）。`,
+                });
+            throw error;
+        }
         const readback = await wireCall(session, { path: ENDPOINTS.listQueryGetHeader, query: { schemaCode: args.schemaCode, code: args.code } });
         return { performed: { errcode: performed.errcode }, readback: { absent: readback.data == null, header: readback.data ?? null } };
     }, undefined, undefined, listviewRollbackSpec("listview.delete"));

package/dist/lanes/model.js

@@ -199,7 +199,10 @@ export function registerModelLane(tools) {
             const tree = flattenTreeRows(wireRows((await wireCall(session, { path: ENDPOINTS.applicationTree, query: { appCode: applicationCode } })).data));
             const all = tree
                 .filter((row) => row.type === "BizModel" && typeof row.code === "string" && row.code)
-                .map((row) => ({ code: row.code, name: row.name ?? row.text ?? null }));
+                // `schemaCode` is the parameter name every other tool takes; `code` is
+                // the tree row's key. Echo both so `--jq 'models[].schemaCode'` works
+                // (r15 P6: the alias was missing and the path missed).
+                .map((row) => ({ code: row.code, schemaCode: row.code, name: row.name ?? row.text ?? null }));
             const needle = args.filter?.trim();
             const models = needle ? all.filter((model) => String(model.code).includes(needle) || String(model.name ?? "").includes(needle)) : all;
             // `filterApplied` disambiguates an empty result: it distinguishes "the