@stalfh233/omc-cli 0.6.6 → 0.6.10

package/README.md

@@ -52,7 +52,8 @@ omc setup && omc doctor && omc commands --json
 `route`、`readiness`、`distributedMirror`）。
 
 ```bash
-omc capabilities                                  # 能力 nickname/id/lane/aliases/tools/commands 一张表
+omc capabilities                                  # 能力 id/lane/aliases/tools/依赖顺序 一张表
+omc capabilities --compact                        # 只要能力索引（~2.5KB，工具名按需 omc capability <id>）
 omc capability <id-or-alias> --executable         # 选中能力的完整执行包（离线，不接触环境）
 omc contract <lane-from-the-capability>           # wire 契约 + 该能力路由
 omc describe <tool-from-the-bundle>               # schema + recipe + 能力路由

package/dist/approval-flow.js

@@ -88,8 +88,10 @@ export async function cmdApprovalFlow(args) {
     catch (error) {
         return invalid(error instanceof Error ? error.message : String(error));
     }
+    // F1（r27）：边界前置——成功回执就标出跨账号审批在单会话 CLI 内不可用。
+    const crossAccountApproval = "unsupported: single-session CLI";
     if (!apply) {
-        writeEnvelope(envelope("ok", { schemaCode: schema, ...compiled, dryRun: true, note: "dry-run 仅编译预览；--apply 执行 workflow.create(无流程时)→update(模板+字段权限)→publish" }, request));
+        writeEnvelope(envelope("ok", { schemaCode: schema, ...compiled, dryRun: true, crossAccountApproval, note: "dry-run 仅编译预览；--apply 执行 workflow.create(无流程时)→update(模板+字段权限)→publish。边界：非发起人身份的审批无法在单会话 CLI 内推进（单 token）；若要验跨账号审批，用第二账号另建环境，或把参与人设为 {Originator}" }, request));
         return 0;
     }
     // 1) 确保流程存在（一个模型只能有一个：已存在则直接 update）
@@ -138,9 +140,9 @@ export async function cmdApprovalFlow(args) {
     // 4) publish
     const publishOutcome = await runToolCall("workflow.publish", { args: { schemaCode: schema, code: compiled.workflowCode, ...(environment ? { environment } : {}) }, requestId: request, environment, print: () => undefined });
     const classified = classifyResult(publishOutcome.result);
-    writeEnvelope(envelope(classified.status, { schemaCode: schema, workflowCode: compiled.workflowCode, steps: steps.length, ...preexistingSection, publish: publishOutcome.result }, request, classified.error));
+    writeEnvelope(envelope(classified.status, { schemaCode: schema, workflowCode: compiled.workflowCode, steps: steps.length, crossAccountApproval, ...preexistingSection, publish: publishOutcome.result }, request, classified.error));
     if (publishOutcome.exitCode === 0)
-        process.stderr.write("[omc] 前台生效验证清单：1) 造一条数据提交走流程；2) 每级审批人在门户有待办（角色用 FindUserByRole 需审批人挂在发起人同部门，否则 PENDING 不来）；3) 审批节点字段只读（不可改单）；4) 驳回退发起人核对；5) 设计器打开流程确认节点链显示正常。\n");
+        process.stderr.write("[omc] 前台生效验证清单：1) 造一条数据提交走流程；2) 每级审批人在门户有待办（角色用 FindUserByRole 需审批人挂在发起人同部门，否则 PENDING 不来）；3) 审批节点字段只读（不可改单）；4) 驳回退发起人核对；5) 设计器打开流程确认节点链显示正常。边界：非发起人身份的审批无法在单会话 CLI 内推进（单 token）；跨账号请另建环境或把参与人设为 {Originator}。\n");
     return publishOutcome.exitCode;
 }
 //# sourceMappingURL=approval-flow.js.map

package/dist/bizservice-config.js

@@ -531,22 +531,38 @@ function resolveExternParameterType(parameter, label, index, collect) {
     return hasChildren ? EXTERN_PARAMETER_NAMES.OBJECT : EXTERN_PARAMETER_NAMES.PROPERTY;
 }
 /**
- * Read-side parameter-face normalization: the platform stores each parameter's
- * `configJson.position` as the WIRE INTEGER index (platform built-ins:
- * `{"position":3}`). Decode it back to the canonical NAME for a readable
- * readback (mirrors `normalizeMethodConfigReadback`). Non-RESTFUL faces pass
- * through untouched.
+ * Read-side parameter-face normalization.
+ *
+ * - `configJson.position` (RESTFUL only): wire INTEGER → canonical NAME
+ *   (mirrors `normalizeMethodConfigReadback`). Non-RESTFUL faces leave position alone.
+ * - `bizPropertyType` (every adapter): wire INTEGER → canonical NAME, with the
+ *   original index kept alongside as `bizPropertyTypeIndex` so callers can
+ *   still match against platform int tables. A name already present passes
+ *   through unchanged (idempotent).
+ *
+ * r28f F4: register readback used to echo bare wire ints while method.get
+ * decoded position-only — one decoder, one face.
  */
 export function normalizeParameterFaceReadback(adapterCode, parameters) {
-    if (adapterCode !== "RESTFUL" || !Array.isArray(parameters))
+    if (!Array.isArray(parameters))
         return parameters;
     return parameters.map((parameter) => {
         if (!isRecord(parameter))
             return parameter;
-        const config = isRecord(parameter.configJson) ? parameter.configJson : typeof parameter.configJson === "string" ? safeParse(parameter.configJson) : undefined;
-        if (!isRecord(config) || !(typeof config.position === "number" && Number.isInteger(config.position) && config.position in RESTFUL_PARAMETER_POSITIONS))
-            return parameter;
-        return { ...parameter, configJson: { ...config, position: RESTFUL_PARAMETER_POSITIONS[config.position] } };
+        let next = parameter;
+        // bizPropertyType is adapter-agnostic (BizPropertyType.java).
+        const rawType = parameter.bizPropertyType;
+        if (typeof rawType === "number" && Number.isInteger(rawType) && rawType in BIZ_PROPERTY_TYPES) {
+            next = { ...next, bizPropertyType: BIZ_PROPERTY_TYPES[rawType], bizPropertyTypeIndex: rawType };
+        }
+        // position decode is RESTFUL-only (BizServiceLocationType).
+        if (adapterCode === "RESTFUL") {
+            const config = isRecord(next.configJson) ? next.configJson : typeof next.configJson === "string" ? safeParse(next.configJson) : undefined;
+            if (isRecord(config) && typeof config.position === "number" && Number.isInteger(config.position) && config.position in RESTFUL_PARAMETER_POSITIONS) {
+                next = { ...next, configJson: { ...config, position: RESTFUL_PARAMETER_POSITIONS[config.position] } };
+            }
+        }
+        return next;
     });
 }
 /**

package/dist/call.js

@@ -55,6 +55,50 @@ export function readArgsFile(path, root = resolve(process.env.OMC_CONFIG_HOME ??
     const fd = openSync(safePath, "r");
     return parseJsonArgs(readBounded(fd, "--args-file"), "--args-file");
 }
+/**
+ * F7（r27）：按工具 description/scope 做意图词检索。前缀/编辑距离在跨族
+ * 猜错时会空手（`app.tree` → 只给 `app.*`），而真实工具 `folder.tree` 的描述
+ * 里写着「应用树」。只补 1–2 个、且排在原候选之后，不改 didYouMean 类型。
+ */
+export function toolsByTextIntent(query, registry, limit = 2) {
+    const rawTokens = query
+        .toLowerCase()
+        .split(/[\s._\-/:]+/u)
+        .map((token) => token.trim())
+        .filter((token) => token.length >= 2);
+    if (rawTokens.length === 0)
+        return [];
+    const intentExpand = {
+        tree: ["tree", "树", "目录", "folder", "应用树"],
+        树: ["tree", "树", "目录", "folder", "应用树"],
+        目录: ["tree", "树", "目录", "folder", "应用树"],
+        folder: ["tree", "树", "目录", "folder", "应用树"],
+    };
+    const tokens = new Set();
+    for (const token of rawTokens) {
+        tokens.add(token);
+        for (const expanded of intentExpand[token] ?? [])
+            tokens.add(expanded);
+    }
+    const scored = [];
+    for (const tool of registry) {
+        const haystack = `${tool.name}\n${tool.description ?? ""}\n${tool.scope ?? ""}`.toLowerCase();
+        let score = 0;
+        for (const token of tokens)
+            if (haystack.includes(token))
+                score += token.length >= 3 ? 2 : 1;
+        // Require at least one query token (not only expanded synonyms) to avoid
+        // ranking every folder.* tool for an unrelated ask that happens to expand.
+        const hitRaw = rawTokens.some((token) => haystack.includes(token));
+        if (!hitRaw || score <= 0)
+            continue;
+        scored.push({ name: tool.name, score });
+    }
+    return scored
+        .sort((left, right) => right.score - left.score || left.name.localeCompare(right.name))
+        .slice(0, limit)
+        .map((entry) => entry.name);
+}
 export async function runToolCall(toolName, options = {}) {
     const print = options.print ?? ((line) => console.log(line));
     const context = options.context ?? makeToolContext({ sessions: new SessionManager(new ConfigStore(defaultPaths())) });
@@ -71,6 +115,8 @@ export async function runToolCall(toolName, options = {}) {
         // closestMatches 按名字相似度补 3 个跨族候选，并把下一条命令直接写出来。
         const nearest = closestMatches(toolName, names, 3).map((entry) => entry.name).filter((name) => !candidates.includes(name));
         const didYouMean = [...candidates.slice(0, 3), ...nearest].slice(0, 5);
+        // F7：description/scope 意图词补位（排在原候选之后，另字段不改 didYouMean 类型）。
+        const byText = toolsByTextIntent(toolName, registry, 2).filter((name) => !didYouMean.includes(name) && !candidates.includes(name));
         // A requested operation the PLATFORM itself does not expose (e.g.
         // dictionary.delete) must not read as an OMC gap: name the real recovery
         // path and the documented absence instead of only the nearest tools.
@@ -80,6 +126,7 @@ export async function runToolCall(toolName, options = {}) {
             tool: toolName,
             ...(candidates.length > 0 ? { candidates } : {}),
             ...(didYouMean.length > 0 ? { didYouMean, nextCommand: `omc describe ${didYouMean[0]}` } : {}),
+            ...(byText.length > 0 ? { didYouMeanByText: byText } : {}),
             ...(absence ? { platformAbsence: absence.replace(/^；/, "") } : {}),
             // 跨族/表意不清时，「猜名字」本身就不该是路径——用目标路由一步到位。
             goalCommand: `omc next "${toolName.replace(/[._]/g, " ")}"`,

package/dist/capability-overview.js

@@ -28,23 +28,23 @@ const SURFACES = [
     },
     {
         id: "app",
-        title: "应用",
+        title: "应用包（app）",
         lane: LANES.app,
-        description: "应用包（app）生命周期：列出、创建、更新（分组移动）、admin 删除。",
+        description: "应用包（app.*）生命周期：列出、创建、更新（分组移动）、admin 删除。不是应用内的目录节点——目录用 folder。",
         operations: ["create", "update", "delete"],
         requires: [],
         intent: { level: "none", note: "未覆盖；用 omc call app.*。" },
-        notes: "环境已带默认 applicationCode，建模不必先建应用。",
+        notes: "环境已带默认 applicationCode，建模不必先建应用。新建应用平台会自动塞一个默认分组（folder.isDefault）；有模型/报表等非目录节点时 app.delete 拒 app-not-empty。",
     },
     {
         id: "folder",
-        title: "应用目录（分组）",
+        title: "应用内目录节点（folder）",
         lane: LANES.folder,
-        description: "应用树目录：读（递归展平带 path/depth）、建、改名/挂载、非递归删除。",
+        description: "应用内目录/分组节点（folder.*，不是应用包 app）：读树（递归展平 path/depth）、建、改名/挂载、非递归删除。",
         operations: ["tree", "create", "update", "delete"],
         requires: ["app"],
         intent: { level: "none", note: "未覆盖；用 omc call folder.*。移动模型用 model.move。" },
-        notes: "省略 parentId 建顶层目录（平台默认挂应用根）；平台不校验重名（工具默认同父同名拒绝）；删除非递归（有子节点回 DIRECTORY_NOT_EMPTY）；应用树是嵌套 children，folder.tree 已展平。",
+        notes: "省略 parentId 建顶层目录（平台默认挂应用根）；平台不校验重名（工具默认同父同名拒绝）；删除非递归（有子节点回 DIRECTORY_NOT_EMPTY）；应用树是嵌套 children，folder.tree 已展平。不存在的应用回 applicationExists:false（仍 ok+空树）。平台默认分组节点带 isDefault:true。",
     },
     {
         id: "dictionary",
@@ -123,11 +123,11 @@ const SURFACES = [
         id: "workflow",
         title: "流程模板",
         lane: LANES.workflow,
-        description: "流程模板生命周期：get_draft/get_published、create、update、publish、bindRule、delete、workitem.list。",
+        description: "流程模板生命周期：get_draft/get_published、create、update、publish、bindRule、delete、workitem.list。**含组织/部门/角色/权限范围（org.* 工具）**：部门树、角色组/角色、用户搜索、成员与管理范围（userScope）——流程参与人/可见性的候选来源。",
         operations: ["create", "update", "publish", "bindRule", "delete"],
         requires: ["model"],
         intent: { level: "partial", note: "声明式支持 workflow.create/update/publish 与 bindRules（事件处理器规则绑定，merge/ensure-present）；runtime workitem（提交/审批）仍走 escape hatch。" },
-        notes: "greenfield 首版；publish/bindRule 不得在 ValidateMessage[] 拒绝时报告成功。",
+        notes: "greenfield 首版；publish/bindRule 不得在 ValidateMessage[] 拒绝时报告成功。组织读写（org.*）挂在本能力下，别名 org/organization/organisation。",
     },
     {
         id: "onlinejs",
@@ -190,7 +190,8 @@ const CAPABILITY_ALIASES = Object.freeze({
     datarule: ["data-rules", "G1-datarule"],
     businessrule: ["business-rules", "B1-businessrule"],
     "rule-lifecycle": ["rule-lifecycles", "S25-rule-lifecycle"],
-    workflow: ["workflows", "W7-S29-greenfield"],
+    // r28h F1/F7: org.* lives under workflow; aliases let "我要管部门/组织" hit it.
+    workflow: ["workflows", "W7-S29-greenfield", "org", "organization", "organisation", "组织", "组织架构"],
     onlinejs: ["online-js"],
     programming: ["backend-online-coding", "programming-online-dev", "在线开发", "在线编码"],
     bizservice: ["bizservices", "B2-registration"],
@@ -238,7 +239,13 @@ export const CAPABILITY_CUES = Object.freeze({
     // rule is named by 业务规则/触发器/规则图, not by "automatic".
     businessrule: ["业务规则", "触发器", "规则图", "校验", "事件", "按钮", "定时任务", "定时触发", "定时器", "每天", "每日", "周期执行", "调度", "SCHEDULER", "TIMING_TASK"],
     "rule-lifecycle": ["启用规则", "停用规则", "删除规则", "规则启停", "触发规则", "执行规则", "跑规则", "按钮规则", "规则验收"],
-    workflow: ["流程", "工作流", "审批", "节点", "待办", "流转", "参与人", "审批人", "角色", "部门负责人", "审批角色"],
+    // r28h F1/F7: narrow org cues so "管理组织：部门/角色/角色组/用户/权限范围"
+    // hits workflow (where org.* lives) instead of field→workflow. Keep them
+    // compound/longer than field's bare "部门"/"人员" so they outscore field.
+    // Also include bare "部门"/"组织" here so an org ask that only says 部门 still
+    // ties/beats field (alias "组织" already scores via CAPABILITY_ALIASES).
+    workflow: ["流程", "工作流", "审批", "节点", "待办", "流转", "参与人", "审批人", "角色", "部门负责人", "审批角色",
+        "组织架构", "组织管理", "管理组织", "角色组", "权限范围", "管理范围", "userScope", "部门树", "员工账号", "组织"],
     onlinejs: ["在线js", "脚本", "联动", "onload", "onvalidate"],
     programming: ["在线开发", "在线编码", "后端源码", "java源码", "编码模式", "handler", "programming", "源码编译"],
     bizservice: ["集成", "接口", "服务", "回调", "对接", "外部系统", "datasql", "restful"],
@@ -522,33 +529,49 @@ export function executableCapabilityBundle(registry, id) {
  * node keeps only `id`. The capability id/lane/tools/order/coverage truth is
  * unchanged; only the repetition is gone.
  */
-export function compactCapabilities(registry) {
+export function compactCapabilities(registry, options = {}) {
     const index = capabilityRouteIndex(registry);
+    // `--compact`（HANDOFF §三.3-7）：默认面 ~8 KB，其中 `tools` 一项就占 ~3 KB。
+    // 冷启动只需要「有哪些能力、在哪个 lane、能不能声明式做」，工具名单用
+    // `omc capability <id>` 按需取。压缩档因此把 tools 换成 toolCount，并**明说**
+    // 省略了工具名，不让读者误以为该能力没有工具。
+    const compact = options.compact === true;
     return {
         status: "ok",
         discovery: DISCOVERY_AUTHORITY,
         // Size hint (dogfood R1): `capabilities` is ~6 KB, not a "safe small" face.
         // Keep it a one-line pointer so it does not perturb the discovery-budget
         // baseline more than a hair.
-        outputHint: "~6KB 非安全小档；next 已给路线时可省，单能力用 omc capability <id>",
+        outputHint: compact
+            ? "紧凑索引（无工具名单）；工具名用 omc capability <id>，完整索引去掉 --compact"
+            : "~6KB 非安全小档；next 已给路线时可省，单能力用 omc capability <id>；只要能力索引可加 --compact",
         commands: {
             detail: "omc capability <id>",
             executable: "omc capability <id> --executable",
             contract: "omc contract <lane>",
             readiness: DISCOVERY_AUTHORITY.readiness,
         },
-        capabilities: index.routes.map((route) => ({
-            id: route.id,
-            title: route.title,
-            lane: route.lane,
-            aliases: route.aliases,
-            tools: route.tools,
-            relatedTopics: route.relatedTopics,
-            requires: index.nodeById.get(route.id)?.requires ?? [],
-            precedes: index.nodeById.get(route.id)?.precedes ?? [],
-            intent: index.nodeById.get(route.id)?.intent.level ?? "none",
-            coverage: index.nodeById.get(route.id)?.coverage ?? "unregistered",
-        })),
+        ...(compact ? { toolsInlined: false, toolsHint: "每个能力的具体工具名见 omc capability <id>；完整索引用 omc capabilities（不带 --compact）" } : {}),
+        capabilities: index.routes.map((route) => compact
+            ? {
+                id: route.id,
+                lane: route.lane,
+                intent: index.nodeById.get(route.id)?.intent.level ?? "none",
+                coverage: index.nodeById.get(route.id)?.coverage ?? "unregistered",
+                toolCount: route.tools.length,
+            }
+            : {
+                id: route.id,
+                title: route.title,
+                lane: route.lane,
+                aliases: route.aliases,
+                tools: route.tools,
+                relatedTopics: route.relatedTopics,
+                requires: index.nodeById.get(route.id)?.requires ?? [],
+                precedes: index.nodeById.get(route.id)?.precedes ?? [],
+                intent: index.nodeById.get(route.id)?.intent.level ?? "none",
+                coverage: index.nodeById.get(route.id)?.coverage ?? "unregistered",
+            }),
     };
 }
 //# sourceMappingURL=capability-overview.js.map

package/dist/cli-contract.js

@@ -234,20 +234,43 @@ export function nextCommandFor(result) {
     }
     return undefined;
 }
+/**
+ * Top-level envelope result statuses. Anything outside this set falls through
+ * to the unclassified-status / auth-config catch-all (exit 15/11). Historical
+ * accidents (0.6.6/0.6.7): `meta.get_status` → `"failed"`, `rollback apply` →
+ * `"stopped"` both used to land in `internal` before they were added here.
+ */
+export const RESULT_STATUSES = ["ok", "dry-run", "partial", "unknown-tool", "uncertain", "refused", "failed", "stopped", "blocked", "error"];
+export const RESULT_STATUS_ROUTES = Object.freeze({
+    ok: { kind: "success", envelopeStatus: "ok", exitCode: CLI_EXIT_CODES.ok },
+    "dry-run": { kind: "success", envelopeStatus: "dry-run", exitCode: CLI_EXIT_CODES.ok },
+    partial: { kind: "partial", envelopeStatus: "partial", code: "partial-batch", exitCode: 1 },
+    "unknown-tool": { kind: "unknown-tool", envelopeStatus: "error", code: "invalid-input", exitCode: CLI_EXIT_CODES.invalidInput },
+    uncertain: { kind: "uncertain", envelopeStatus: "uncertain", code: "uncertain", exitCode: CLI_EXIT_CODES.uncertain },
+    refused: { kind: "refused", envelopeStatus: "refused" },
+    failed: { kind: "step-chain", envelopeStatus: "error", code: "step-chain-failed", exitCode: 1 },
+    stopped: { kind: "step-chain", envelopeStatus: "error", code: "step-chain-failed", exitCode: 1 },
+    blocked: { kind: "step-chain", envelopeStatus: "error", code: "step-chain-failed", exitCode: 1 },
+    // `error` keeps today's self-produced / blocker-bypass path: it is listed so
+    // the producer scan accepts it, but classifyResult does not give it a stable
+    // ordinary-path mapping of its own.
+    error: { kind: "passthrough" },
+});
 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")
-        return { status, error: null, exitCode: CLI_EXIT_CODES.ok };
+    const route = RESULT_STATUSES.includes(status)
+        ? RESULT_STATUS_ROUTES[status]
+        : undefined;
+    if (route?.kind === "success")
+        return { status: route.envelopeStatus, error: null, exitCode: route.exitCode };
     // `--args-list` partial success (some entries landed, some refused). Without
     // this branch it fell through to "internal error", which reads as a CLI bug
     // rather than "2 of 3 fields were created — retry index 2".
-    if (status === "partial") {
+    if (route?.kind === "partial") {
         const succeeded = Number(result.succeeded ?? 0);
         const requested = Number(result.requested ?? 0);
         const failed = Number(result.failed ?? 0);
@@ -262,15 +285,19 @@ export function classifyResult(result) {
                 ? `${succeeded}/${requested} 成功，${failed} 失败；逐条原因见 failures[] / failedSteps[]（--args-list 的 index 指向第几条）`
                 : `部分步骤失败：逐条原因见 steps[] 的 status/detail（已在失败处停下；幂等，修好后重跑同一条命令）`;
         return {
-            status,
-            error: withNext({ code: "partial-batch", message, retryable: false }),
-            exitCode: 1,
+            status: route.envelopeStatus,
+            error: withNext({ code: route.code, message, retryable: false }),
+            exitCode: route.exitCode,
         };
     }
-    if (status === "unknown-tool") {
+    if (route?.kind === "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: withNext({ code: "invalid-input", message: `unknown tool ${String(result.tool ?? "")}${suffix}`, retryable: false }), exitCode: CLI_EXIT_CODES.invalidInput };
+        return {
+            status: route.envelopeStatus,
+            error: withNext({ code: route.code, message: `unknown tool ${String(result.tool ?? "")}${suffix}`, retryable: false }),
+            exitCode: route.exitCode,
+        };
     }
     // r25 探针实证（2026-11-04）：`blocker: "invalid-input"` 有 8 处产出点
     // （workflow/runtime-data/compound-writes），但这里只认 `tool-input-*`——于是
@@ -278,16 +305,30 @@ export function classifyResult(result) {
     // 读成"CLI 内部故障"，而实际是**自己传错了参数**（探针原话：
     // 「rejected ✓, but error.code=internal (should be invalid-input), and no nextCommand」）。
     // 入参形状错误一律 exit 10，并给出下一步。
+    // Priority: must stay ahead of the remaining status routes (uncertain /
+    // refused / step-chain / unclassified) so `status:"refused"|"error"` with an
+    // input-shape blocker still exits 10. Do not move this above ok/dry-run/
+    // partial/unknown-tool — that would change today's semantics.
     const inputShapeBlocker = result.blocker === "tool-input-invalid"
         || result.blocker === "tool-input-unknown-keys"
         || result.blocker === "invalid-input";
     if (inputShapeBlocker) {
         // `invalid-input` 也可能是 CLI 层参数校验（compound-writes 的 --schema 必填），
         // 那时没有 tool 字段——别硬拼一条指向不存在的工具的 describe。
+        // 工具在时进一步收窄到**失败的那个参数**（`--param <顶层键>`）：整份 describe
+        // 是 4–17 KB，而 issues[].path 已经把位置说清楚了（HANDOFF §三.1-1）。
         const toolName = typeof result.tool === "string" && result.tool ? result.tool : undefined;
+        const failedParam = Array.isArray(result.issues)
+            ? result.issues
+                .map((issue) => issue?.path)
+                .map((path) => (Array.isArray(path) ? path[0] : path))
+                .find((segment) => typeof segment === "string" && segment.length > 0)
+            : undefined;
         const nextCommand = typeof result.nextCommand === "string"
             ? result.nextCommand
-            : toolName !== undefined ? `omc describe ${toolName}` : undefined;
+            : toolName !== undefined
+                ? `omc describe ${toolName}${failedParam !== undefined ? ` --param ${String(failedParam).split(".")[0]}` : ""}`
+                : undefined;
         return {
             status: "error",
             error: {
@@ -297,22 +338,54 @@ export function classifyResult(result) {
             exitCode: CLI_EXIT_CODES.invalidInput,
         };
     }
-    if (status === "uncertain")
-        return { status, error: withNext({ code: "uncertain", message: String(result.message ?? result.reason ?? "outcome is uncertain"), retryable: true }), exitCode: CLI_EXIT_CODES.uncertain };
-    if (status === "refused") {
+    if (route?.kind === "uncertain") {
+        return {
+            status: route.envelopeStatus,
+            error: withNext({ code: route.code, message: String(result.message ?? result.reason ?? "outcome is uncertain"), retryable: true }),
+            exitCode: route.exitCode,
+        };
+    }
+    if (route?.kind === "refused") {
         if (result.blocker === "write-lock-held")
-            return { status, error: withNext({ code: "policy-refused", message: String(result.message ?? "write lock held"), retryable: true }), exitCode: CLI_EXIT_CODES.policyRefused };
+            return { status: route.envelopeStatus, 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");
         // 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 };
+        return { status: route.envelopeStatus, error: nextCommand === undefined ? error : { ...error, nextCommand }, exitCode: auth ? CLI_EXIT_CODES.authConfig : CLI_EXIT_CODES.policyRefused };
     }
+    // r25 沙盒（2026-11-04，B1 的同类）：`meta.get_status` 返回 `status:"failed"`、
+    // `rollback apply` 返回 `status:"stopped"`——两个都曾掉进 internal（exit 15）：
+    // 调用方看到「CLI 内部故障」，其实是「配置/凭据读回失败」或「恢复链在 N 步停下」。
+    // 这类状态是**步骤链的中途状态**，语义就是 partial：先跑了一些、然后停在某处。
+    // 归到 exit 1 并保留 steps/结果原文。
+    if (route?.kind === "step-chain") {
+        return {
+            status: route.envelopeStatus,
+            error: withNext({
+                code: route.code,
+                message: String(result.message ?? `${status}：链在中途停止；逐条原因见 steps[] 的 status/error`),
+                retryable: false,
+            }),
+            exitCode: route.exitCode,
+        };
+    }
+    // `error` (passthrough) and any unknown status share the unclassified catch-all.
+    // Keep the actual `result.status` in the message (B10/B11): a brand-new value
+    // must never collapse to a bare "CLI 内部故障".
     const message = String(result.message ?? "internal error");
     const auth = /credential|configuration|environment|login|authentication|auth/i.test(message);
-    return { status: "error", error: withNext({ 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" : "unclassified-status",
+            message: `${message}（result.status=${status}${typeof result.blocker === "string" ? `, blocker=${result.blocker}` : ""}——此状态未在 envelope 分类表内，按失败处理并原样上报）`,
+            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-output.js

@@ -2,6 +2,42 @@ import { writeFileSync } from "node:fs";
 import { asciiStdout, serializeEnvelope } from "./cli-contract.js";
 import { currentUsageCommand, priorRepeatedFailures, recordUsageOutput } from "./usage-log.js";
 let options = { quiet: false, verbose: false };
+/**
+ * F2'（r27）：写面 + 非 TTY 时，stderr 人话末尾补一行「勿 2>&1 合流」提示。
+ * 读面保持安静；stdout 字节不变。状态由 beginWriteFace / noteHumanStderr /
+ * maybeWarnMergedStreams 协作，避免每个调用点手写条件。
+ */
+let writeFaceActive = false;
+let humanStderrEmitted = false;
+let pipeMergeHintEmitted = false;
+/** Mark the current command as a write-face (call/script/composers that mutate). */
+export function beginWriteFace() {
+    writeFaceActive = true;
+    humanStderrEmitted = false;
+    pipeMergeHintEmitted = false;
+}
+/** Clear the write-face marker (call after the command finishes). */
+export function endWriteFace() {
+    writeFaceActive = false;
+    humanStderrEmitted = false;
+}
+const PIPE_MERGE_HINT = "提示：本行在 stderr；stdout 仍是**恰好一个** JSON 信封。脚本解析请勿 2>&1 合流（会得到两段文本）。";
+/**
+ * Append the 2>&1 warning once, only when stdout is piped, a write face ran,
+ * and at least one human stderr line was already emitted.
+ */
+export function maybeWarnMergedStreams() {
+    if (pipeMergeHintEmitted || options.quiet)
+        return;
+    if (!writeFaceActive || !humanStderrEmitted)
+        return;
+    if (process.stdout.isTTY === true)
+        return;
+    pipeMergeHintEmitted = true;
+    process.stderr.write(`${PIPE_MERGE_HINT}\n`);
+}
+/** Test seam: the exact hint line (no trailing newline). */
+export const PIPE_MERGE_HINT_FOR_TEST = PIPE_MERGE_HINT;
 /** Parse `--quiet`, `--verbose` and `--out <file>` from the raw argv once, before dispatch. */
 export function configureOutput(argv) {
     const outIndex = argv.indexOf("--out");
@@ -177,7 +213,10 @@ export function writeEnvelope(value) {
 }
 /** Emit a human diagnostic on stderr, unless `--quiet` asked for none. */
 export function humanSummary(line) {
-    if (!options.quiet)
-        process.stderr.write(`${line}\n`);
+    if (options.quiet)
+        return;
+    process.stderr.write(`${line}\n`);
+    humanStderrEmitted = true;
+    maybeWarnMergedStreams();
 }
 //# sourceMappingURL=cli-output.js.map

package/dist/cli-stdout.js

@@ -0,0 +1,74 @@
+/**
+ * Which CLI roots write their own stdout envelope (HANDOFF §三.2-6).
+ *
+ * 这是**显式声明**，不是散落在 `main()` 里的字符串数组。历史上两次踩同一个坑：
+ *   - r10：composers（`form-default` / `compute` / `rule-when` / `approval-flow`）
+ *     不在名单里 → 真信封后又跟一个 `{"ok":true,"result":{}}`，读成第二个答案。
+ *   - 0.6.7：`setup` 非 TTY 报错不在名单里 → 补了一个谎报 `internal` 的信封（B9）。
+ *   - 2026-11-05：`submit-verify` / `rule-save-enable` / `workflow-update-publish`
+ *     三个复合命令自己 `writeEnvelope`，却仍不在名单里 → 参数 JSON 写坏时
+ *     stdout 出两行信封（实测 2 行），破坏「stdout 恰好一个信封」契约。
+ *
+ * 语义只有三档：
+ *   - `envelope`：自己写**一个**结果信封（主流程不得再补）。
+ *   - `raw`：自己写非信封输出（`env --json` 的 JSON、`--version` 的版本行），
+ *     同样不得再补。
+ *   - `stderr-only`：只往 stderr 写人类诊断，成功/失败都不产生信封（`doctor`、
+ *     `bench`）。主流程也不补，否则会给这类命令安一个假的 `ok`/`internal`。
+ *
+ * 新增一个根命令时必须在这里登记；`test/cli-stdout-contract.test.ts` 会遍历
+ * `cli.ts` 里注册的全部根命令，漏登记直接失败。
+ */
+export const CLI_STDOUT_OWNERS = {
+    // 工具执行与读面
+    call: "envelope",
+    script: "envelope",
+    artifact: "envelope",
+    commands: "envelope",
+    describe: "envelope",
+    contract: "envelope",
+    capabilities: "envelope",
+    capability: "envelope",
+    next: "envelope",
+    usage: "envelope",
+    intent: "envelope",
+    help: "envelope",
+    graph: "envelope",
+    programming: "envelope",
+    rollback: "envelope",
+    setup: "envelope",
+    // composers：自己合成结果信封
+    "form-default": "envelope",
+    compute: "envelope",
+    "rule-when": "envelope",
+    "approval-flow": "envelope",
+    "model-scaffold": "envelope",
+    "field-add": "envelope",
+    "model-purge": "envelope",
+    // 复合写命令（r19 tickets 11–13）：两阶段回执是自己的信封
+    "submit-verify": "envelope",
+    "rule-save-enable": "envelope",
+    "workflow-update-publish": "envelope",
+    // 原始输出
+    env: "raw",
+    // MCP stdio 服务器：stdout 是 JSON-RPC 帧流，补一个信封会直接污染协议。
+    "mcp-graph": "raw",
+    "--version": "raw",
+    "-V": "raw",
+    // 人类体检 + 一个结构化回执（checks / unsupportedCapabilities 在 stdout）
+    doctor: "envelope",
+    // bench 只往 stderr 写报告，不产生信封
+    bench: "stderr-only",
+};
+/** 主流程绝不能在这些命令之后再补写一个信封。 */
+export function ownsStdout(name) {
+    return Object.hasOwn(CLI_STDOUT_OWNERS, name);
+}
+/**
+ * 已登记的命令里，哪些**不**写信封——主流程连空的 `ok` 都不该补。
+ * （`ownsStdout` 已覆盖它们；这个集合只是为了把「为什么没有信封」写成代码。）
+ */
+export function isStderrOnlyCommand(name) {
+    return ownsStdout(name) && CLI_STDOUT_OWNERS[name] === "stderr-only";
+}
+//# sourceMappingURL=cli-stdout.js.map