@stalfh233/omc-cli 0.6.6 → 0.6.10

package/dist/cli.js

@@ -10,7 +10,7 @@ import { Command, CommanderError, Option } from "commander";
 import { ConfigStore, defaultPaths, removedProfileKeys } from "./config-store.js";
 import { loadCoverageManifest, versionFamilyNotice } from "./coverage.js";
 import { redactText } from "./redact.js";
-import { readArgsFile, readStdinArgs, runToolCall, validateAgentPaths } from "./call.js";
+import { readArgsFile, readStdinArgs, runToolCall, toolsByTextIntent, validateAgentPaths } from "./call.js";
 import { BATCH_MAX_ENTRIES, runBatchCall } from "./batch-call.js";
 import { cmdModelScaffold } from "./model-scaffold.js";
 import { cmdFieldAdd } from "./field-add.js";
@@ -18,11 +18,13 @@ import { cmdModelPurge } from "./model-purge.js";
 import { cmdProgrammingAdopt, cmdProgrammingApply, cmdProgrammingPull, cmdProgrammingStatus, cmdProgrammingTest } from "./programming-workflow.js";
 import { environmentWritable, requiresProductionConfirmation } from "./environment-policy.js";
 import { CLI_EXIT_CODES, classifyResult, envelope, errorEnvelope, humanUtf8, installCodePageSafeStderr, refusalText, requestId } from "./cli-contract.js";
-import { configureOutput, humanSummary, stripOutputFlags, writeEnvelope } from "./cli-output.js";
+import { ownsStdout } from "./cli-stdout.js";
+import { formatDoctorHumanSummary, unsupportedCapabilities } from "./version-family-gaps.js";
+import { beginWriteFace, configureOutput, endWriteFace, humanSummary, maybeWarnMergedStreams, stripOutputFlags, writeEnvelope } from "./cli-output.js";
 import { beginUsage, completeUsage, currentUsageArgsDigest, ensureProjectIgnore, priorIdenticalSuccess, recordUsageOutput, usageReport } from "./usage-log.js";
 import { artifactFetchHint, artifactRoot, boundResult, emitInvalid, emitResult, emitThrown, emitTransportResult, outputBudget, readArtifact, withTransport, } from "./command-transport.js";
 import { CLI_DEFAULT_OUTPUT_BYTES, assertSafeOutputPath, pruneArtifacts } from "./artifacts.js";
-import { projectJsonPath, projectJsonPathFanout, projectResultExtract } from "./path-projection.js";
+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";
@@ -177,6 +179,9 @@ async function cmdDoctor(store, environment, serviceCode) {
     const manifest = loadCoverageManifest();
     const steps = [];
     let ok = true;
+    // 版本族缺口（§三.3-9）：没有版本证据时也要照实说「无证据 → 写 fail closed」，
+    // 所以用 undefined 而不是拼一个默认值。
+    let detectedVersion;
     // r45 Windows 实测：PowerShell 管道按 GBK(936) 解码 CLI 的 UTF-8 输出 → 全屏乱码，
     // 且用户常误判为「OMC 输出坏了」。doctor 是入口体检，顺手检测活动代码页。
     if (process.platform === "win32") {
@@ -222,6 +227,7 @@ async function cmdDoctor(store, environment, serviceCode) {
         for (const note of session.loginNotes())
             steps.push(`OAuth 配置  WARN ${note}`);
         const version = session.detectedVersion();
+        detectedVersion = version;
         if (!version) {
             steps.push(`版本      WARN 无版本证据；写入将保守拒绝（fail closed）`);
         }
@@ -306,16 +312,56 @@ async function cmdDoctor(store, environment, serviceCode) {
             ? `环境      ${kind}  已配置环境：${configured || "(none)"}；用 omc env list 查看，再以 --env <name> 指定或 omc setup 绑定；对象不存在（modelPresent:false）不是环境错误`
             : `环境      ${kind}  环境已配置但平台不可达；先查网络/服务，不要改环境名试错（已配置：${configured || "(none)"}）`);
     }
-    for (const line of steps)
-        console.error(line);
-    // Cold-start anchor (round 2, module D): `doctor` runs every session, so it
-    // carries the minimal-read path, the artifact convention, and the readiness
-    // command — the facts a first-time agent otherwise assembles from ~52 KB of
-    // prose. Kept terse so the anchor stays ~1 KB.
-    console.error(doctorAnchor());
-    console.error(ok ? "doctor：通过" : "doctor：失败");
+    // r26b 读回体积审计（2026-11-05）：人类体检行 + 结构化信封曾把同一批 check
+    // **各写一份**（3073 B 里约 1450 B 是重复）。管道/agent 场景（非 TTY）只留一行
+    // 汇总 + 指针；真人在终端里看到的仍是完整逐项明细。
+    const interactive = process.stderr.isTTY === true;
+    if (interactive) {
+        for (const line of steps)
+            console.error(line);
+        console.error(doctorAnchor());
+        console.error(ok ? "doctor：通过" : "doctor：失败");
+    }
+    else {
+        const warns = steps.filter((line) => /(^|\s)(⚠|WARN|FAIL)(\s|$)/.test(line)).length;
+        // r28i F1: name version + unavailable capability ids in the human line
+        // (formatDoctorHumanSummary lives in version-family-gaps.ts).
+        const gaps = unsupportedCapabilities(manifest, detectedVersion);
+        console.error(formatDoctorHumanSummary({
+            ok,
+            warnCount: warns,
+            detectedVersion,
+            unsupported: gaps,
+        }));
+    }
+    // 结构化回执（HANDOFF §三.2-6 / §三.3-9）：doctor 此前只写 stderr，主流程于是
+    // 补一个空 `ok` 信封（失败路径还补过谎报 `internal` 的）。现在它自己写**一个**
+    // 信封：体检行 + 冷启动锚点 + 已知能力缺口。冷启动锚点从 stderr 移到这里
+    // （r26b：stderr 给了 agent 也读不到结构化字段，而锚点是每会话都要用的指引）。
+    writeEnvelope(envelope(ok ? "ok" : "failed", {
+        checks: steps.map(parseDoctorStep),
+        anchor: doctorAnchor(),
+        unsupportedCapabilities: unsupportedCapabilities(manifest, detectedVersion),
+    }, requestId()));
     return ok ? 0 : 1;
 }
+/**
+ * `配置      ok  环境=x` → `{area:"配置", level:"ok", message:"环境=x"}`。
+ * 解析失败的行（极少数自由文本）退化成 `{area:"doctor", level:"info"}`，
+ * 保证结构化回执不缺行——宁可字段糙一点，也不要静默丢一条体检结论。
+ */
+function parseDoctorStep(line) {
+    const match = /^(\S+)\s+(ok|⚠|WARN|FAIL|--)\s+(.*)$/.exec(line);
+    if (!match) {
+        // `环境      env-not-pinned  …` 这类第二档：区域 + 机器码 + 说明。
+        const typed = /^(\S+)\s+([a-z][a-z0-9-]+)\s+(.*)$/.exec(line);
+        if (typed)
+            return { area: typed[1], level: "info", message: `${typed[2]}：${typed[3]}` };
+        return { area: "doctor", level: "info", message: line };
+    }
+    const level = match[2] === "⚠" ? "warn" : match[2] === "--" ? "skip" : match[2].toLowerCase();
+    return { area: match[1], level, message: match[3] };
+}
 /** The cold-start anchor `doctor` appends: minimal path, artifact convention, readiness. */
 function doctorAnchor() {
     const topics = listSkills().map((entry) => entry.name).join("、");
@@ -456,6 +502,7 @@ async function cmdCall(store, args) {
             result = { ...result, nextAction: "read back the requestId before retrying; retry only after the outcome is established" };
         const classified = classifyResult(result);
         writeEnvelope(envelope(status, boundResult(result, maxOutputBytes), request, classified.error));
+        maybeWarnMergedStreams();
         return exitCode;
     };
     const flag = (name) => argvValue(args, name);
@@ -574,16 +621,38 @@ async function cmdCall(store, args) {
     // 「无声」——`{"limt":5}` / `{"filterr":{…}}` 被 zod 剥掉后返回全量，调用方
     // 会读成「过滤没生效 / 数据就是这么多」。读面在**不阻断**的前提下把被忽略的
     // 键回显出来（写面仍是 fail-closed，见 parseToolInput）。
+    //
+    // F6（r27）：应用级键（appCode/applicationCode/application）静默回落会把写
+    // 操作打到错误应用——这些键被忽略时直接拒绝，不进 ignoredArgs。
     const ignoredReadKeys = [];
-    if (tool && tool.kind !== "write") {
+    if (tool) {
         const schemaKeys = new Set(Object.keys(tool.inputSchema));
         const recognized = new Set(["environment", "capability", "requestId", "dryRun"]);
-        for (const key of Object.keys(parsedArgs)) {
-            if (schemaKeys.has(key) || recognized.has(key))
-                continue;
-            // r25 真机：`limt:5` 被就近指到 `filter`（共享 "fi" 就够过阈值），照提示改
-            // 会把「取 5 条」变成「按条件过滤」。短键走显式缩写表，语义才不跑偏。
-            ignoredReadKeys.push({ key, ...suggestArgumentKey(key, [...schemaKeys]) });
+        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 wrong = appScopeUnknown.join("、");
+            const result = {
+                status: "refused",
+                blocker: "unknown-app-scope-arg",
+                tool: toolName,
+                ignored: appScopeUnknown,
+                acceptedAppScopeArg: canonical,
+                message: `本工具的应用范围参数叫 ${canonical}，你传的 ${wrong} 不会生效——为避免写到错误应用，本次调用已拒绝。请改用 ${canonical} 后重试（\`omc describe ${toolName}\` 可确认参数表）。`,
+            };
+            return emit("refused", result, CLI_EXIT_CODES.policyRefused);
+        }
+        if (tool.kind !== "write") {
+            for (const key of unknownKeys) {
+                // r25 真机：`limt:5` 被就近指到 `filter`（共享 "fi" 就够过阈值），照提示改
+                // 会把「取 5 条」变成「按条件过滤」。短键走显式缩写表，语义才不跑偏。
+                ignoredReadKeys.push({ key, ...suggestArgumentKey(key, [...schemaKeys]) });
+            }
         }
     }
     if (tool) {
@@ -601,6 +670,9 @@ async function cmdCall(store, args) {
         }
     }
     const toolKind = tool?.kind;
+    // F2'：只对写面（含 dry-run 预览）标记；读面人话不追加 2>&1 提示。
+    if (toolKind === "write")
+        beginWriteFace();
     let lock;
     // A `--dry-run` never mutates the environment: the governed pipeline settles it
     // before write admission, so it must not contend for the cross-process lock.
@@ -673,7 +745,13 @@ async function cmdCall(store, args) {
         };
     }
     const classified = classifyResult(result);
-    return emit(classified.status, result, classified.exitCode);
+    try {
+        return emit(classified.status, result, classified.exitCode);
+    }
+    finally {
+        if (toolKind === "write")
+            endWriteFace();
+    }
 }
 /** Collect every value of a repeatable flag (`--extract a --extract b`). */
 function argvValues(args, name) {
@@ -687,6 +765,8 @@ function argvValues(args, name) {
     }
     return values;
 }
+/** F6：应用级范围键。被工具 schema 忽略时必须拒绝，不能静默回落到默认应用。 */
+const APP_SCOPE_ARG_KEYS = new Set(["appCode", "applicationCode", "application"]);
 /**
  * 读面「拼错键」建议（r25 真机实证，2026-11-04）：`limt:5` 曾按编辑距离被指到
  * `filter`——两者共享 "fi" 片段就过阈值，但语义完全不同（取 5 条 vs 按条件过滤）。
@@ -750,15 +830,12 @@ function projectArtifactPath(value, path) {
 }
 /**
  * T6（GitLab #17）：`mapped`/`nullEntries` 的读法要跟数据一起走，否则 `mapped:5`
- * 会被读成"取到 5 个值"。仅在确实出现 null 时加一行，正常读取零噪音。
+ * 会被读成"取到 5 个值"。文案的单一真相源在 path-projection（与 `--extract`
+ * 面共用），这里只负责从产物内容算 total。
  */
-function nullProjectionHint(content, nullEntries) {
-    if (nullEntries === undefined || nullEntries === 0)
-        return undefined;
+function artifactNullHint(content, nullEntries) {
     const total = Array.isArray(content) ? content.length : 0;
-    if (total === 0 || nullEntries !== total)
-        return `其中 ${nullEntries} 个命中值为 null（不区分"字段为空"与"列表未投影"）。`;
-    return `路径全部命中但值都是 null——mapped=${total} 只表示命中条目数。常见成因：列表视图未配置该列（data.list 只投影视图列）→ 用 data.load 读单条权威值，或先 listview.configure 配列。`;
+    return nullProjectionHint(nullEntries, total);
 }
 function formatBytes(bytes) {
     if (bytes < 1024)
@@ -788,6 +865,15 @@ async function cmdArtifactGet(id, transport, options = {}) {
         if (options.summary) {
             const record = content && typeof content === "object" && !Array.isArray(content) ? content : undefined;
             const keys = record ? Object.entries(record).map(([key, value]) => ({ key, bytes: Buffer.byteLength(JSON.stringify(value) ?? "null", "utf8"), kind: Array.isArray(value) ? `array[${value.length}]` : value === null ? "null" : typeof value })).sort((left, right) => right.bytes - left.bytes) : [];
+            // r25 真机（2026-11-04）：`--summary` 与裸 `--keys` 曾输出逐字相同（各 878 B），
+            // 但 fetch 提示写「--summary（再 --keys/--jq）」暗示递进——探针白跑一次。
+            // 现在 `--summary` 多给一眼"要花多少/会不会被截断"，`--keys` 保持纯 key 表。
+            const shapeFacts = {
+                bytes: artifact.content.length,
+                ...(record ? { topLevelKeys: keys.length } : {}),
+                overInlineCeiling: artifact.content.length > ARTIFACT_INLINE_CEILING_BYTES,
+                ...(record ? {} : { kind: Array.isArray(content) ? `array[${content.length}]` : typeof content }),
+            };
             // `--summary --jq <path>`: shape AND the one value, in a single call. Without
             // 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.
@@ -797,7 +883,7 @@ async function cmdArtifactGet(id, transport, options = {}) {
                 // 一层 `projection:{path,content}`——`artifact get --jq` 与 `--summary --jq`
                 // 因此同形（顶层 path/content），换读面不用重新探根键。
                 return emitTransportResult(projected.missed
-                    ? { status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, keys, path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, unanswered: true, hint: "路径未命中（这一层没有该段）。可用写法：点式 a.b、下标 a[0]、数组映射 items[].fields.x、按键选择 rules[code=Create]。available 是该层真实存在的键。" }
+                    ? { status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, keys, path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, unanswered: true, hint: artifactPathMissHint(projected.at) }
                     : {
                         status: "ok",
                         artifactId: id,
@@ -809,10 +895,12 @@ async function cmdArtifactGet(id, transport, options = {}) {
                         ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}),
                         ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}),
                         ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}),
-                        ...(nullProjectionHint(projected.content, projected.nullEntries) !== undefined ? { hint: nullProjectionHint(projected.content, projected.nullEntries) } : {}),
+                        ...(artifactNullHint(projected.content, projected.nullEntries) !== undefined ? { hint: artifactNullHint(projected.content, projected.nullEntries) } : {}),
                     }, transport);
             }
-            return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, keys, fetch: artifactFetchHint(id) }, transport);
+            // 裸 `--keys` / 裸 `--jq` 只要键表（`pureKeys`），不带 summary 的形状事实——
+            // 两者要有可见差异，否则 fetch 提示里的「--summary（再 --keys）」就是误导。
+            return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, ...(options.pureKeys === true ? {} : { summary: shapeFacts }), keys, fetch: artifactFetchHint(id) }, transport);
         }
         if (options.keys !== undefined) {
             // Round 15: tolerate a `result.`/`data.` prefix and report missing keys.
@@ -847,14 +935,14 @@ async function cmdArtifactGet(id, transport, options = {}) {
                     const projected = projectArtifactPath(artifactContent, path);
                     return projected.missed
                         ? { path, content: null, pathMiss: true, missedAt: projected.at, available: projected.available }
-                        : { path, content: projected.content ?? null, ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}), ...(nullProjectionHint(projected.content, projected.nullEntries) !== undefined ? { hint: nullProjectionHint(projected.content, projected.nullEntries) } : {}) };
+                        : { path, content: projected.content ?? null, ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}), ...(artifactNullHint(projected.content, projected.nullEntries) !== undefined ? { hint: artifactNullHint(projected.content, projected.nullEntries) } : {}) };
                 });
-                return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, projections, ...(projections.some((entry) => entry.pathMiss) ? { unanswered: true, hint: "逗号多路径中部分路径未命中（见各 projection.pathMiss/missedAt/available）；路径语法：点式 a.b、下标 a[0]、切片 a[0:6]、数组映射 items[].fields.x、按键选择 rules[code=Create]" } : {}) }, transport);
+                return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, projections, ...(projections.some((entry) => entry.pathMiss) ? { unanswered: true, hint: partialPathMissHint() } : {}) }, transport);
             }
             const projected = projectArtifactPath(artifactContent, 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, unanswered: true, hint: `路径未命中段 "${projected.at}"——available 是该层可用的键/范围；方括号下标（a[0]）与点式（a.0）等价；[] 映射数组（items[].fields.x）；按键选择 rules[code=Create]；一次取多列用逗号分隔路径（--jq "a.b,c.d"），本参数是路径选择器、不是 jq 语言（不支持 | 与对象构造）` }
-                : { 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 } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}), ...(nullProjectionHint(projected.content, projected.nullEntries) !== undefined ? { hint: nullProjectionHint(projected.content, projected.nullEntries) } : {}) }, transport);
+                ? { status: "ok", artifactId: id, sha256: artifact.sha256, path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, unanswered: true, hint: artifactPathMissHint(projected.at) }
+                : { 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 } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}), ...(artifactNullHint(projected.content, projected.nullEntries) !== undefined ? { hint: artifactNullHint(projected.content, projected.nullEntries) } : {}) }, 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
@@ -1118,11 +1206,15 @@ function cmdDiscovery(kind, transport, value, options = {}) {
             .map((tool) => tool.name)
             .filter((name) => name === segment || name.startsWith(`${segment}.`) || name.includes(requested))
             .slice(0, 8);
-        const pointer = candidates.length === 0 && (kind === "describe" || kind === "contract")
+        // F7：前缀候选之外，按 description/scope 意图词补 1–2 个（排在原候选之后）。
+        const byText = toolsByTextIntent(requested, registry, 2).filter((name) => !candidates.includes(name));
+        const shown = [...candidates, ...byText];
+        const pointer = candidates.length === 0 && byText.length === 0 && (kind === "describe" || kind === "contract")
             ? `；describe 的目标是工具名（如 rule.save）；图/模板/节点形状用 describe <tool> --full 或 contract <lane>，工具清单用 omc next "<目标>" / omc commands --json --compact`
             : "";
         const absence = absencePointer(requested);
-        return emitInvalid(transport, { message: `${kind} target not found: "${requested}"${candidates.length > 0 ? `; did you mean: ${candidates.join("、")}` : ""}${absence}${approvalPointer}${intentPointer}${formPointer}${pointer}` });
+        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);
 }
@@ -1142,8 +1234,8 @@ 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) {
-    const result = compactCapabilities(buildToolRegistry());
+function cmdCapabilities(transport, compact = false) {
+    const result = compactCapabilities(buildToolRegistry(), { compact });
     return emitTransportResult({ status: "ok", ...result }, transport);
 }
 function cmdCapability(id, transport, executable = false) {
@@ -1716,7 +1808,20 @@ async function main() {
     }
     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)); });
     command.command("setup").option("--list").option("--edit <environment>").option("--remove <environment>").action(async (options) => {
-        commandExitCode = await cmdSetup(new ConfigStore(defaultPaths()), [...(options.list ? ["--list"] : []), ...(options.edit ? ["--edit", options.edit] : []), ...(options.remove ? ["--remove", options.remove] : [])]);
+        // r25 真机（2026-11-04）：setup 不在 ownsStdout 里，于是非 TTY 拒绝时主流程会补一个
+        // `error.code=internal` 的信封——明明是可预期的用法错误（stdin 不是终端），却被包成
+        // 「CLI 内部故障」（探针原话：「差点以为是崩溃；看了 stderr 才确认是故意的策略拒绝」）。
+        // 现由 setup 自己写正确档位的信封，并加入 ownsStdout 让主流程不再覆盖。
+        const setupCode = await cmdSetup(new ConfigStore(defaultPaths()), [...(options.list ? ["--list"] : []), ...(options.edit ? ["--edit", options.edit] : []), ...(options.remove ? ["--remove", options.remove] : [])]);
+        commandExitCode = setupCode;
+        writeEnvelope(setupCode === 0
+            ? envelope("ok", {}, request, null)
+            : envelope("error", { blocker: "setup-requires-tty" }, request, {
+                code: "invalid-input",
+                message: "setup 的交互式创建/编辑需要 TTY（stdin 不是终端）。改用 --list / --remove，或在真实终端里运行 --edit；脚本化注册直接改配置文件。",
+                retryable: false,
+                nextCommand: "omc setup --list",
+            }));
     });
     command.command("env [action] [name]").option("--json").action(async (action, name, options) => {
         // Read-only inventory of configured environment names. r18: the sandbox
@@ -1774,11 +1879,11 @@ async function main() {
     // landed in the argParser slot and silently dropped every --steps value
     // (live 2026-10-18: `--steps "审批@role:x"` answered "至少一个 --steps").
     const collectValues = (value, previous = []) => [...previous, value];
-    command.command("rule-when").option("--schema <schemaCode>").option("--schema-code <schemaCode>").option("--on <trigger>").addOption(new Option("--when <condition>", "条件，可重复").argParser(collectValues).default([])).addOption(new Option("--then <action>", "动作，可重复").argParser(collectValues).default([])).option("--name <name>").option("--env <environment>").option("--environment <environment>").option("--apply").addHelpText("after", "\n条件-动作规则拼装器：--when 条件（可多个 AND）→ --then set:字段=值/引用/公式。编译为设计器验证形状（预置触发+UPDATE filter/赋值）。默认 dry-run，--apply 保存并发布；前台生效按输出清单人工验证。\n").action(async (options) => {
+    command.command("rule-when").option("--schema <schemaCode>").option("--schema-code <schemaCode>").option("--on <trigger>", "触发时机：create | update（**没有 submit**——提交后执行请用 create 或 update，按平台触发面语义选）").addOption(new Option("--when <condition>", "条件，可重复").argParser(collectValues).default([])).addOption(new Option("--then <action>", "动作，可重复").argParser(collectValues).default([])).option("--name <name>").option("--env <environment>").option("--environment <environment>").option("--apply").addHelpText("after", "\n条件-动作规则拼装器：--when 条件（可多个 AND）→ --then set:字段=值/引用/公式。编译为设计器验证形状（预置触发+UPDATE filter/赋值）。默认 dry-run，--apply 保存并发布；前台生效按输出清单人工验证。\n触发时机只有 create / update 两个（无 submit）：\"提交后/审批前\"这类需求在平台侧没有独立触发点，用 create（新建即触发）或 update（更新即触发）表达；要按状态过滤，把条件写进 --when。\n").action(async (options) => {
         const rest = ["rule-when", ...(options.schema ? ["--schema", options.schema] : []), ...(options.schemaCode ? ["--schema-code", options.schemaCode] : []), ...(options.on ? ["--on", options.on] : []), ...(Array.isArray(options.when) ? options.when.flatMap((w) => ["--when", w]) : []), ...(Array.isArray(options.then) ? options.then.flatMap((a) => ["--then", a]) : []), ...(options.name ? ["--name", options.name] : []), ...(options.env ? ["--env", options.env] : []), ...(options.environment ? ["--environment", options.environment] : []), ...(options.apply ? ["--apply"] : [])];
         commandExitCode = await cmdRuleWhen(rest);
     });
-    command.command("approval-flow").option("--schema <schemaCode>").option("--schema-code <schemaCode>").addOption(new Option("--steps <step>", "审批步骤，可重复").argParser(collectValues).default([])).option("--env <environment>").option("--environment <environment>").option("--apply").option("--no-originator-node").option("--no-reject-to-start").addHelpText("after", "\n审批流拼装器：--steps 名称@role:<角色code>（多级给多个）。编译为验证模板（START→填写→审批链→END，审批节点字段只读），--apply 建流+权限+发布。\n").action(async (options) => {
+    command.command("approval-flow").option("--schema <schemaCode>").option("--schema-code <schemaCode>").addOption(new Option("--steps <step>", "审批步骤，可重复").argParser(collectValues).default([])).option("--env <environment>").option("--environment <environment>").option("--apply").option("--no-originator-node").option("--no-reject-to-start").addHelpText("after", "\n审批流拼装器：--steps 名称@role:<角色code>（多级给多个）。编译为验证模板（START→填写→审批链→END，审批节点字段只读），--apply 建流+权限+发布。\n边界：非发起人身份的审批无法在单会话 CLI 内推进（单 token）；若要验跨账号审批，用第二账号另建环境，或把参与人设为 {Originator}。\n").action(async (options) => {
         const rest = ["approval-flow", ...(options.schema ? ["--schema", options.schema] : []), ...(options.schemaCode ? ["--schema-code", options.schemaCode] : []), ...(Array.isArray(options.steps) ? options.steps.flatMap((s) => ["--steps", s]) : []), ...(options.env ? ["--env", options.env] : []), ...(options.environment ? ["--environment", options.environment] : []), ...(options.apply ? ["--apply"] : []), ...(options.originatorNode === false ? ["--no-originator-node"] : []), ...(options.rejectToStart === false ? ["--no-reject-to-start"] : [])];
         commandExitCode = await cmdApprovalFlow(rest);
     });
@@ -2047,13 +2152,19 @@ async function main() {
             console.error(`已清理 ${result.removed} 个读回产物，释放 ${formatBytes(result.freedBytes)}；保留 ${result.kept} 个（${formatBytes(result.keptBytes)}）`);
         commandExitCode = CLI_EXIT_CODES.ok;
     });
-    artifactCommand.command("get <id>").option("--jq [path]").option("--path-only").option("--summary").option("--keys [a,b]").option("--full", "整包返回正文（默认：正文超过 8KB 时只回形状 outline + fetch，按需 --jq/--keys 定向取值）").option("--max-output-bytes <bytes>").action(async (id, options) => {
+    // r28h F3（真机 2026-11-05）：`omc call` 用 `--extract`、`artifact get` 用 `--jq`，
+    // 语义完全相同。探针先试 `--extract` 拿到 `unknown option`（白花一次往返），
+    // 才想起两者不同名。别名照收，help 里也标出来。
+    artifactCommand.command("get <id>").option("--jq [path]").option("--extract <path>", "同 --jq（与 omc call 的 --extract 同名，省一次命名切换）").option("--path-only").option("--summary").option("--keys [a,b]").option("--full", "整包返回正文（默认：正文超过 8KB 时只回形状 outline + fetch，按需 --jq/--keys 定向取值）").option("--max-output-bytes <bytes>").action(async (id, options) => {
         // A bare `--jq`/`--keys` is a key-inventory request, not a missing argument:
         // commander's "argument missing" (invalid-input + retry) is a dead end the
         // caller cannot fix without already knowing the flag takes a value (r11
         // burned six rounds on `artifact get <id> --jq` before trying `--summary`).
+        // --extract 是 --jq 的同义别名（r28h F3）。
+        const jqPath = typeof options.jq === "string" ? options.jq : typeof options.extract === "string" ? options.extract : undefined;
         const bareJq = options.jq === true;
-        commandExitCode = await withTransport(options, request, (transport) => cmdArtifactGet(id, transport, { ...(typeof options.jq === "string" ? { jq: options.jq } : {}), pathOnly: options.pathOnly === true, summary: options.summary === true || options.keys === true || bareJq, ...(typeof options.keys === "string" ? { keys: options.keys } : {}), full: options.full === true }));
+        commandExitCode = await withTransport(options, request, (transport) => cmdArtifactGet(id, transport, { ...(jqPath !== undefined ? { jq: jqPath } : {}), pathOnly: options.pathOnly === true, summary: options.summary === true || options.keys === true || bareJq,
+            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 } : {}) })); });
@@ -2061,7 +2172,7 @@ async function main() {
         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 } : {}) }));
     });
     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("capabilities").option("--max-output-bytes <bytes>").action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdCapabilities(transport)); });
+    command.command("capabilities").option("--compact").option("--max-output-bytes <bytes>").action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdCapabilities(transport, options.compact === true)); });
     // `--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).
@@ -2165,17 +2276,14 @@ function finish(code) {
 }
 const request = requestId();
 main().then((code) => {
-    // Commands that own their stdout never grow a trailing envelope. `--version`/
-    // `-V` are here because their short-circuit already wrote the bare version.
-    // Composers (`form-default`, `compute`, `rule-when`, `approval-flow`) own their
-    // stdout exactly like `call` does. Without them in this list every composer
-    // printed its real envelope AND a trailing `{"ok":true,"result":{}}` — r10 read
-    // that as a second, empty answer. `rollback` / `env` emit their own
-    // envelope (or, for `env --json`, their own JSON) and were printing a second
-    // empty envelope after it (live 2026-10-23: `omc rollback apply` answered two
-    // lines, violating the one-envelope stdout contract).
-    const ownsStdout = ["call", "script", "artifact", "commands", "describe", "contract", "capabilities", "capability", "next", "usage", "intent", "help", "form-default", "compute", "rule-when", "approval-flow", "model-scaffold", "field-add", "model-purge", "rollback", "env", "graph", "programming", "--version", "-V"];
-    if (ownsStdout.includes(argv[2] ?? "")) {
+    // Commands that own their stdout never grow a trailing envelope. The list is
+    // an explicit declaration in `cli-stdout.ts` (HANDOFF §三.2-6): an inline array
+    // was maintained by hand and twice lost a command — composers in r10 and
+    // `setup` in 0.6.7 both answered two envelopes, and the compound writes
+    // (`submit-verify` / `rule-save-enable` / `workflow-update-publish`) still did
+    // on a bad JSON flag. `test/cli-stdout-contract.test.ts` walks every registered
+    // root command so a new one cannot be forgotten.
+    if (ownsStdout(argv[2] ?? "")) {
         completeUsage(code);
         finish(code);
         return;

package/dist/command-transport.js

@@ -60,7 +60,14 @@ export function checkedOutputBudget(value) {
     return value;
 }
 export function artifactRoot() {
-    return resolve(process.env.OMC_ARTIFACTS_HOME ?? joinConfigRoot(), "artifacts");
+    // r28k F11（真机 2026-11-05）：旧默认落在项目根 `artifacts/`，`describe --full`
+    // 等 transport spill 与「全程只读」探针预期的「零残留」冲突（账本 createdCodes
+    // 仍为空，但磁盘多了文件）。默认与工具产物目录对齐到 `.omc/artifacts`。
+    // OMC_ARTIFACTS_HOME 若设置，则它本身就是最终 artifact 根（历史契约，不再拼一层）。
+    const home = process.env.OMC_ARTIFACTS_HOME;
+    return home !== undefined && home.trim() !== ""
+        ? resolve(home)
+        : resolve(joinConfigRoot(), ".omc", "artifacts");
 }
 export function joinConfigRoot() {
     return resolve(process.env.OMC_CONFIG_HOME ?? process.cwd());

package/dist/config-store.js

@@ -277,9 +277,24 @@ export class ConfigStore {
             console.error(`cross-env: 环境 "${name}" 不在本项目允许列表（${own.join("、") || "空"}）；已按 OMC_ALLOW_CROSS_ENV=1 放行本次访问。请确认这是用户批准的临时跨环境操作。`);
             return;
         }
+        // r28j F8: cwd decides the project root. Agents often assemble JSON under
+        // /tmp then call --env local, and the refusal used to say only "允许：test"
+        // while `omc env` in another directory showed local — two sources, one
+        // unexplained. Spell both files + the resolved project root in the refusal.
+        const projectRoot = dirname(this.paths.projectEnvPath);
+        const bound = this.readProjectEnvBinding();
+        const allowlist = this.readProjectEnvsFile();
+        const boundText = bound === undefined
+            ? `.omc-env=（无；未绑定）`
+            : `.omc-env=${bound}`;
+        const allowText = allowlist.length === 0
+            ? `.omc-envs=（无或不存在；准入回退到 .omc-env ∪ 全局 default）`
+            : `.omc-envs=${allowlist.join(",")}`;
         throw new ConfigurationError(`跨环境访问被拒绝：环境 "${name}" 不属于本项目（本项目允许：${own.join("、") || "(none)"}）。` +
-            `每个项目目录只能使用自己声明的环境，不允许读取其他环境的信息。` +
-            `如确需跨环境，先向用户报告并取得同意，再由用户执行 \`omc env allow ${name}\`（写入项目 .omc-envs），` +
+            `解析到的项目根=${projectRoot}；${boundText}；${allowText}。` +
+            `准入由「当前工作目录」下的 .omc-envs（白名单）+ .omc-env（默认绑定）共同决定，不是由 --env 参数单独决定；` +
+            `在无声明的目录里 --env local 会落到机器全局 default（常见是 test）。` +
+            `请改到声明了该环境的项目根再跑，或先向用户报告并取得同意后执行 \`omc env allow ${name}\`（写入项目 .omc-envs），` +
             `或临时设置 OMC_ALLOW_CROSS_ENV=1 单次放行。`);
     }
     bindProjectEnvironment(name) {

package/dist/discovery.js

@@ -7,6 +7,7 @@ import { LANE_CONTRACTS } from "./contract-resources.js";
 import { intentCapabilityBlock } from "./intent/cli.js";
 import { listSkills } from "./skills.js";
 import { capabilityRouteForTool, capabilityRouteForLane, capabilityRouteIndex, DISCOVERY_AUTHORITY } from "./capability-overview.js";
+import { readShapeFor } from "./read-shapes.js";
 /**
  * `commands --json` — the tool catalogue.
  *
@@ -169,7 +170,11 @@ function jsonSchemaFor(shape) {
 /** First sentence, whitespace-collapsed and bounded — enough to pick a tool. */
 function summarizeDescription(description) {
     const collapsed = description.replace(/\s+/g, " ").trim();
-    const firstStop = collapsed.search(/[。.;；!！?？]/);
+    // r28k F8（真机 2026-11-05）：此前把**任何**点号都当句末，于是
+    // `setup.commit` 的摘要被切在 "写 omc." ——恰好切掉了「写 omc.config.json 与
+    // 0600 凭据库」这个决定「要不要执行」的核心事实（探针必须再 --full 才拿到）。
+    // 点号只有当后面是空白或结尾时才是句末；`omc.config.json` / `v1.2.3` 里的不属于。
+    const firstStop = collapsed.search(/[。；;！!？?]|\.(?=\s|$)/);
     const sentence = firstStop >= 0 ? collapsed.slice(0, firstStop + 1) : collapsed;
     return sentence.length > 200 ? `${sentence.slice(0, 197)}...` : sentence;
 }
@@ -422,6 +427,23 @@ function firstCallFor(tool) {
     };
     return firstCall;
 }
+/**
+ * Compact `returns` block for the default describe / --param faces.
+ * Only tools with an authored entry in read-shapes.ts emit this field —
+ * undeclared tools stay at zero extra bytes. Keep notes to at most one line.
+ */
+function returnsFace(toolName) {
+    const shape = readShapeFor(toolName);
+    if (!shape)
+        return undefined;
+    const notes = shape.notes?.slice(0, 1);
+    return {
+        returns: {
+            keys: shape.keys,
+            ...(notes && notes.length > 0 ? { notes } : {}),
+        },
+    };
+}
 /** Default `omc describe`: the compact contract projection. */
 export function describeTool(registry, name) {
     const tool = registry.find((entry) => entry.name === name);
@@ -451,12 +473,18 @@ export function describeTool(registry, name) {
         // reachable through --param/--full, i.e. discovering a param needed its
         // name first. Name the documented params inline (cheap: names only) so one
         // `describe` answers "does this tool take X, and what is X called".
+        // r26b 读回体积审计（2026-11-05）：提示原写「单个参数注释，几百字节」，而
+        // `--param nodeGraph` 实测 **8773 B**（object 参数展开≈整份 --full）——照提示
+        // 做反而更贵。现在点名哪些参数是大对象，并改指 --example。
         ...(documentedParamNames(tool).length > 0
-            ? { paramDocs: { available: documentedParamNames(tool), read: `omc describe ${tool.name} --param <name>（单个参数注释，几百字节）` } }
+            ? { paramDocs: { available: documentedParamNames(tool), read: largeParamDocsHint(tool) } }
             : {}),
         // T3（GitLab #17）：封闭取值（schema 里没有 enum 的那些）在默认面内联一次，
         // 省掉「写错 → 报错 → 再写」的循环；报错里的 accepted* 仍是权威兜底。
         ...(tool.paramEnums !== undefined ? { paramEnums: tool.paramEnums } : {}),
+        // High-frequency read faces: declare the RESULT keys so `--jq` does not
+        // have to learn them from a pathMiss. Zero bytes when undeclared.
+        ...(returnsFace(tool.name) ?? {}),
         // Keep the cost salient at the decision point: agents reached for --full even
         // when --example/--param existed (sandbox22: 8 --full calls, one 19 KB).
         full: `omc describe ${tool.name} --full（5–20KB；先试 --example/--param）`,
@@ -473,6 +501,24 @@ function documentedParamNames(tool) {
     }
     return names.sort();
 }
+/**
+ * `--param` 的价码提示（r26b 实测）：标量参数 150–900 B，**object 参数 ≈ 整份
+ * `--full`**（`--param nodeGraph` = 8773 B，`--full` = 16950 B）。原来的提示只写
+ * 「几百字节」，照着做会付 10–50 倍。这里点名当前工具里哪些参数是大对象。
+ */
+function largeParamDocsHint(tool) {
+    const schema = jsonSchemaFor((tool.inputSchema ?? {}));
+    // 只算 **object**（record）参数：字符串数组（displayFields/columns）展开只要几十字节，
+    // 把它们也标成"大"会误导（r26b 实测 data.list --param displayFields 很小）。
+    const heavy = Object.entries(schema.properties ?? {})
+        .filter(([, node]) => node.type === "object")
+        .map(([key]) => key);
+    const base = `omc describe ${tool.name} --param <name>（标量 150–900B`;
+    if (heavy.length === 0)
+        return `${base}）`;
+    const named = heavy.slice(0, 3).join("、") + (heavy.length > 3 ? " 等" : "");
+    return `${base}；对象参数 ${named} ≈ --full，改用 --example）`;
+}
 /** `omc describe <tool> --example <id>`: one recipe in full, by id. */
 export function describeExample(registry, name, exampleId) {
     const tool = registry.find((entry) => entry.name === name);
@@ -535,7 +581,18 @@ export function describeParam(registry, name, param) {
     const schema = jsonSchemaFor(tool.inputSchema);
     const node = schema.properties?.[param];
     if (!node) {
-        return { name: tool.name, param, found: false, available: Object.keys(schema.properties ?? {}) };
+        // r28e 真机（2026-11-05）：调用方看到 `status:"ok"` + 一堆键，误以为"参数存在、
+        // 只是描述为空"。`found:false` 是机器信号，但人读时需要一句话点明——否则
+        // 会照着 `available` 之外的名字继续试。
+        const nearest = closestMatch(param, Object.keys(schema.properties ?? {}));
+        return {
+            name: tool.name,
+            param,
+            found: false,
+            message: `本工具没有参数 "${param}"${nearest !== undefined ? `；最接近的是 "${nearest}"` : ""}——available 是本工具的全部合法参数`,
+            ...(nearest !== undefined ? { didYouMean: nearest, nextCommand: `omc describe ${tool.name} --param ${nearest}` } : {}),
+            available: Object.keys(schema.properties ?? {}),
+        };
     }
     return {
         name: tool.name,
@@ -544,6 +601,8 @@ export function describeParam(registry, name, param) {
         type: terseType(node),
         ...(node.description ? { description: node.description } : {}),
         schema: node,
+        // Same authored return face as the default describe (only when declared).
+        ...(returnsFace(tool.name) ?? {}),
     };
 }
 /**