@stalfh233/omc-cli 0.4.98 → 0.4.100

package/dist/refusal-guidance.js

@@ -0,0 +1,207 @@
+/**
+ * Shape-family refusals: the payload was malformed in a way the CLI can see
+ * offline. Each cites the recipe that carries the correct shape.
+ */
+const SHAPE_GATES = Object.freeze({
+    "relation-single-array-shape": {
+        whatWentWrong: "单选关联字段（propertyType 9）传了数组",
+        correctShape: "单选关联只接受 id 字符串或 {id} 对象：{\"字段\":\"<关联行id>\"} 或 {\"字段\":{\"id\":\"<id>\"}}；多选关联（11）/人员（50）/组织（51）才用数组",
+        recipeCommand: { tool: "data.submit", recipe: "plain-data-submit" },
+        doNot: "不要对单选关联继续传数组重试——平台稳定回 50000，不是偶发",
+    },
+    "submit-date-shape": {
+        whatWentWrong: "日期字段的值形状不对（毫秒时间戳会落库 NULL）",
+        correctShape: "字符串且匹配字段 format：日期字段 \"YYYY-MM-DD\"；日期时间字段 ISO8601 带时区 \"2026-01-01T10:00:00+08:00\"",
+        recipeCommand: { tool: "data.submit", recipe: "plain-data-submit" },
+        doNot: "不要传毫秒数（如 1790000000000）——不报错但落库 NULL，读回才发现",
+    },
+    "submit-child-rows-missing-id": {
+        whatWentWrong: "更新已有记录时，子表行没带 id",
+        correctShape: "更新时子表行必须带平台 id（新增行才省略）；无 id 的行会被当**新增**插入，不判重",
+        command: undefined,
+        recipeCommand: { tool: "data.update", recipe: "plain-data-submit" },
+        doNot: "不要用同一批无 id 子行重试 update——每次都会再插一遍（r17 实测 2 行变 8 行）",
+    },
+    "submit-approval-agree-misplaced": {
+        whatWentWrong: "agree 放在了 approval 对象里，平台只读顶层 agree",
+        correctShape: "通过/驳回用顶层参数：{\"agree\": true|false, \"approvalNote\": \"意见\"}；approval 对象只是评论载体（content/relUsers）",
+        recipeCommand: { tool: "data.submit", recipe: "workflow-backed-data-submit" },
+        doNot: "approval.agree 会被静默忽略且仍按通过处理（r18b 真机：agree:false 照样 APPROVE）——原地重试必然得到同样的错误结果",
+    },
+    "submit-approval-opinion-misplaced": {
+        whatWentWrong: "opinion 放在了 approval 对象里，平台不读它",
+        correctShape: "审批意见用顶层 approvalNote；approval.content 是评论内容，不是审批意见",
+        recipeCommand: { tool: "data.submit", recipe: "workflow-backed-data-submit" },
+        doNot: "改 approval.opinion 重试无意义——字段被静默忽略",
+    },
+    "aggregation-self-schema-cycle": {
+        whatWentWrong: "聚合目标是自己的子表——平台 publishFormula 必然判环（checkCycleOfAggregation:1032），无条件 305003",
+        correctShape: "聚合 schemaCode 指向**另一个模型**的主表标量列；要子表合计先物化到来源主表再聚合",
+        recipeCommand: { tool: "field.create", recipe: "formula-aggregation-cross-model" },
+        doNot: "同模型子表聚合是平台死路（8.6.26 与 1.1.25 逐行相同），改 payload 无用；也不要删平台自动生成的 t100 CALCULATE_RULE 镜像行",
+    },
+    "aggregation-target-is-child-schema": {
+        whatWentWrong: "聚合指向了子表 schema",
+        correctShape: "aggregation.schemaCode 必须是来源模型主表；数据项只能是来源主表的标量列",
+        recipeCommand: { tool: "field.create", recipe: "formula-aggregation-cross-model" },
+        doNot: "聚合指向子表会让目标模型整个不可写（40000 无明细）且匹配恒 0——先删这个字段配置再继续",
+    },
+    "aggregation-data-item-not-scalar": {
+        whatWentWrong: "聚合数据项不是来源主表的标量列",
+        correctShape: "跨模型汇总的数据项只能是来源主表标量列；子表列先在来源模型物化成主表字段",
+        recipeCommand: { tool: "field.create", recipe: "formula-aggregation-cross-model" },
+        doNot: "直接把子表列写进数据项不会报配置错误——回算静默恒 0，先回来源模型物化",
+    },
+    "aggregation-large-missing-k": {
+        whatWentWrong: "LARGE/SMALL 聚合缺 k（前 N 名的 N）",
+        correctShape: "algorithmOptions 里带 k（正整数）；LARGE=前 k 大，SMALL=前 k 小",
+        recipeCommand: { tool: "field.create", recipe: "formula-aggregation-cross-model" },
+        doNot: "缺 k 时平台抛 NumberFormatException 掩码成 50000——重试同参数无用",
+    },
+    "aggregation-union-result-type": {
+        whatWentWrong: "UNION（文本拼接）的 resultType 越界",
+        correctShape: "UNION 的 resultType 只能 0 或 1（拼接分隔行为），不是数值型枚举",
+        recipeCommand: { tool: "field.create", recipe: "formula-aggregation-cross-model" },
+        doNot: "写 2 及以上平台直接 50000——改回 0/1 再发布",
+    },
+    "rule-graph-validation-failed": {
+        whatWentWrong: "规则图形状没过写前校验",
+        correctShape: "nodeGraph：nodes（Start/动作/End，系统节点标 isSystemNode）+ routes（preNode→postNode）；条件分支用 BRANCH 节点",
+        recipeCommand: { tool: "rule.save", recipe: "business-rule-branch-conditional" },
+    },
+    "rule-graph-routes-empty": {
+        whatWentWrong: "规则图缺 routes（节点连线）",
+        correctShape: "每条 route {preNode, postNode, routeCondition:true}；Start→首节点→…→End 必须连通",
+        recipeCommand: { tool: "rule.save", recipe: "business-rule-branch-conditional" },
+    },
+    "rule-graph-bizaction-mapping-field-missing": {
+        whatWentWrong: "BIZ_ACTION 节点的输入映射缺 serviceMethodParameterCode 或 bizCode",
+        correctShape: "inputMappings 每条：serviceMethodParameterCode（服务方法参数）↔ bizCode（模型字段 code），codeType 按类型",
+        recipeCommand: { tool: "rule.save", recipe: "rule-cross-model-create" },
+        missingInputs: [
+            { name: "serviceCode/serviceMethodCode", source: "omc call bizservice.list --args '{}'（已注册的二开服务）" },
+            { name: "bizCode（模型字段）", source: "omc call field.list --args '{\"schemaCode\":\"<模型>\",\"all\":true}'" },
+        ],
+    },
+    "rule-graph-bizmethod-unresolved": {
+        whatWentWrong: "规则图引用的二开服务方法不存在或未注册",
+        correctShape: "methodMapping.schemaCode/serviceCode/serviceMethodCode 必须是已注册服务的真实 code",
+        recipeCommand: { tool: "rule.save", recipe: "rule-cross-model-create" },
+        missingInputs: [
+            { name: "serviceCode/serviceMethodCode", source: "omc call bizservice.list --args '{}'；方法级详情用 bizservice.get" },
+        ],
+        doNot: "不要凭记忆拼写服务 code——静默不匹配时规则保存成功但运行为空",
+    },
+    "field-relation-target-missing": {
+        whatWentWrong: "关联字段的目标模型缺失或不可解析",
+        correctShape: "关联字段 options 里目标模型 schemaCode 必须已存在且已发布",
+        missingInputs: [
+            { name: "目标模型 schemaCode", source: "omc call model.list --args '{}'" },
+        ],
+    },
+});
+/**
+ * Platform/permission/environment families: honest "fix this first" with NO
+ * retry command — a command that would fail again is worse than none.
+ */
+const FIX_FIRST_GATES = Object.freeze({
+    "workflow-start-permission-denied": "40009 有三个独立同码原因：① 发起人角色没挂该流程的发起权限（ouScope ∩ 发起人部门链，全空会静默回退发起人）；② 流程未启用/未发布；③ 模型未绑定流程。先 omc call workflow.get_published 核对 ②，再查角色 ouScope——不要反复换参数重试 data.submit",
+    "environment-write-disabled": "当前环境 profile 不可写：换可写环境，或让维护者在配置里开 writable——CLI 侧没有绕过开关",
+    "production-confirmation-required": "生产环境的写需要显式 confirmProduction:true——确认这次写入真的要落生产再加该参数，不要靠重试",
+    "app-not-published": "目标应用未发布：先 workflow/form/field 各面发布（或 app 级发布），再重试运行面操作",
+    "submit-workitem-not-mine": "该 workItem 不在当前登录人的待办里：用 omc call workitem.list --args '{\"status\":\"PENDING\"}' 拿**自己的** workItemId，不要用别人的 id 提交",
+    "capability-out-of-coverage": "需求不在覆盖面内：这份拒绝就是答案——用 omc capabilities 核对运行时清单，不要换相近工具伪造实现",
+    "version-family-evidence-missing": "平台版本证据缺失，写被关闭：先 omc doctor / discover_environment 取版本证据，非 8.6/1.1.25 家族按边界处理",
+});
+/** `tool-input-invalid` and friends: point at the refused tool's own describe. */
+function inputInvalidGuidance(toolName) {
+    if (!toolName)
+        return undefined;
+    return {
+        whatWentWrong: "入参没过工具的 schema 校验（缺必填或类型不对）",
+        correctShape: "必填参数与类型见 command 指向的 describe（firstCall 自带最小可跑形状）",
+        command: `omc describe ${toolName}`,
+        doNot: "不要盲目重试——同参数必然同拒绝",
+    };
+}
+/**
+ * r19 p14 — the report BI boundary (`/dashboard/v1/*`). A deployment without
+ * the report service answers every BI call with a gateway 502 (live p9
+ * evidence); that is an ENVIRONMENT boundary, not a transient failure, so the
+ * teaching says which faces still work and to stop retrying. Matched from the
+ * message/detail text so both the refused and the frozen (uncertain) envelope
+ * paths can carry it.
+ */
+function dashboardBoundaryGuidance() {
+    return {
+        whatWentWrong: "报表 BI 通道（/dashboard/v1/*）不可达——报表服务未启动（本机有此服务；网关 502，p9 实证）",
+        fixFirst: "报表能力暂不优先支持（维护者裁决，先隐藏）：不要重试同一子面。平台层仍可用：report.tree / report.update / report.get 存在性判定；确需 BI 详情/数据源/图表/配置时，先启动本机报表服务再深进",
+    };
+}
+function mentionsDashboardChannel(payload) {
+    return JSON.stringify({ m: payload.message, d: payload.detail, r: payload.reason }).includes("/dashboard/v1/");
+}
+/**
+ * Resolve the authored recipe command against the registry: the guidance must
+ * never cite a recipe the registry does not ship (that would be a second,
+ * contradictory shape source). Falls back to the tool's describe; if even the
+ * tool is unknown, the command is omitted.
+ */
+function resolveCommand(authored, registry) {
+    if (!authored.recipeCommand || !registry)
+        return undefined;
+    const tool = registry.find((entry) => entry.name === authored.recipeCommand.tool);
+    const recipe = tool?.executionMetadata?.recipes.find((entry) => entry.id === authored.recipeCommand.recipe);
+    if (tool && recipe)
+        return `omc describe ${tool.name} --example ${recipe.id}`;
+    if (tool)
+        return `omc describe ${tool.name}`;
+    return undefined;
+}
+export function refusalRecovery(blocker, payload, options = {}) {
+    // A refusal that already teaches (write-lock-held carries lock recovery) is
+    // not overwritten — single owner per envelope.
+    if (payload.recovery !== undefined)
+        return payload.recovery;
+    // r19 p14: the report BI boundary is matched from the wire path in the
+    // message/detail, so both refused and frozen (uncertain) envelopes teach it.
+    if (mentionsDashboardChannel(payload))
+        return dashboardBoundaryGuidance();
+    const shape = SHAPE_GATES[blocker];
+    if (shape) {
+        const command = resolveCommand(shape, options.registry);
+        const { recipeCommand: _drop, ...rest } = shape;
+        return { ...rest, ...(command !== undefined ? { command } : {}) };
+    }
+    const fixFirst = FIX_FIRST_GATES[blocker];
+    if (fixFirst)
+        return { whatWentWrong: String(payload.message ?? blocker).slice(0, 160), fixFirst };
+    if (blocker === "tool-input-invalid")
+        return inputInvalidGuidance(options.toolName);
+    return undefined;
+}
+/**
+ * Attach guidance to a refused result at the `runToolCall` choke point.
+ * Idempotent, refuses to overwrite, and leaves non-refused results untouched.
+ */
+export function attachRefusalRecovery(result, toolName, registry) {
+    // r19 p14: `/dashboard/v1/*` failures surface as UNCERTAIN (frozen) — the
+    // http-status wire kind is classified "uncertain" by design, and frozen
+    // envelopes carry `reason`/`detail` but NO `blocker` field. The dashboard
+    // boundary is definitive (gateway 502, report service not started), so those
+    // frozen envelopes get the teaching too; every other uncertain result stays
+    // untouched (never relabel network jitter as an environment boundary).
+    const frozenWithBoundary = result.status === "uncertain" && mentionsDashboardChannel(result);
+    if (result.status !== "refused" && !frozenWithBoundary)
+        return result;
+    if (result.recovery !== undefined)
+        return result;
+    const blocker = typeof result.blocker === "string" ? result.blocker : "";
+    if (!blocker && !frozenWithBoundary)
+        return result;
+    const recovery = refusalRecovery(blocker, result, { registry, toolName });
+    if (!recovery)
+        return result;
+    return { ...result, recovery };
+}
+//# sourceMappingURL=refusal-guidance.js.map

package/dist/skills.js

@@ -81,6 +81,22 @@ function scanHeadings(lines) {
     }
     return found;
 }
+/**
+ * Slice one heading's body using the documented rule: a section runs until the
+ * next heading of the same or a higher level. Shared by `--section` and search
+ * so a search hit can announce the exact bytes `--section` would return.
+ */
+function sliceSectionText(lines, start, level) {
+    let end = lines.length;
+    for (let index = start + 1; index < lines.length; index += 1) {
+        const match = /^(#{1,6})\s+(.+?)\s*$/.exec(lines[index]);
+        if (match && match[1].length <= level) {
+            end = index;
+            break;
+        }
+    }
+    return lines.slice(start, end).join("\n").trim() + "\n";
+}
 /** Return one Markdown heading and its nested content without loading the full topic into the envelope. */
 export function readSkillSection(name, requested) {
     const document = readSkill(name);
@@ -121,16 +137,7 @@ export function readSkillSection(name, requested) {
     if (start < 0)
         return { document, section: "", headings };
     const startEntry = scanned.find((entry) => entry.index === start);
-    const level = startEntry.level;
-    let end = lines.length;
-    for (let index = start + 1; index < lines.length; index += 1) {
-        const match = /^(#{1,6})\s+(.+?)\s*$/.exec(lines[index]);
-        if (match && match[1].length <= level) {
-            end = index;
-            break;
-        }
-    }
-    return { document, section: lines.slice(start, end).join("\n").trim() + "\n", headings };
+    return { document, section: sliceSectionText(lines, startEntry.index, startEntry.level), headings };
 }
 /**
  * The "shape" of a topic: every heading with the bytes it would cost to read.
@@ -147,17 +154,7 @@ export function readSkillOutline(name) {
     const lines = document.content.split(/\r?\n/);
     const headings = scanHeadings(lines);
     const sections = headings.map((entry) => {
-        let end = lines.length;
-        // Same slicing rule as readSkillSection: a section runs until the next
-        // heading of the same or a higher level, so reported bytes match the read.
-        for (let index = entry.index + 1; index < lines.length; index += 1) {
-            const match = /^(#{1,6})\s+(.+?)\s*$/.exec(lines[index]);
-            if (match && match[1].length <= entry.level) {
-                end = index;
-                break;
-            }
-        }
-        const body = `${lines.slice(entry.index, end).join("\n").trim()}\n`;
+        const body = sliceSectionText(lines, entry.index, entry.level);
         return { heading: entry.heading, level: entry.level, bytes: Buffer.byteLength(body, "utf8") };
     });
     const bytes = Buffer.byteLength(document.content, "utf8");
@@ -170,4 +167,75 @@ export function readSkillOutline(name) {
     const visible = indexLevel === undefined ? sections : sections.filter((entry) => entry.level === indexLevel);
     return { document, bytes, sections: visible.length > 0 ? visible : sections };
 }
+/**
+ * Cross-topic full-text search (`omc help --search`).
+ *
+ * Why this exists: r18 spent 173.8 KB re-dumping five whole topics twice to grep
+ * for `40000`, because `omc help` is a bookshelf (one heading index per topic)
+ * and there was no way to ask a question. A search that returns only
+ * topic/heading would still cost a second call, so a hit carries its section
+ * body and the exact bytes `--section` would return.
+ *
+ * Matching is deliberately literal: case-insensitive substring, whitespace
+ * splits terms, `all` requires every term in the same section and `any`
+ * requires one. No stemming, no fuzzy matching — an agent searching an exact
+ * error code must never be steered to a similar-looking section.
+ */
+export function searchSkills(query, options) {
+    const terms = query.trim().toLowerCase().split(/\s+/).filter((term) => term.length > 0);
+    if (terms.length === 0)
+        return { matches: [], total: 0 };
+    const found = [];
+    for (const entry of listSkills()) {
+        const document = readSkill(entry.name);
+        if (!document)
+            continue;
+        const lines = document.content.split(/\r?\n/);
+        const scanned = scanHeadings(lines);
+        // Same visible levels as the index: a whole-document H1 must not swallow
+        // every H2 hit into one giant match.
+        const levels = [...new Set(scanned.map((item) => item.level))].sort((left, right) => left - right);
+        const singleRoot = levels.length > 1 && scanned.filter((item) => item.level === levels[0]).length === 1;
+        const indexLevel = singleRoot ? levels[1] : levels[0];
+        const visible = scanned.filter((heading) => heading.level === indexLevel);
+        for (const [ordinal, heading] of visible.entries()) {
+            if (indexLevel === undefined)
+                continue;
+            const section = sliceSectionText(lines, heading.index, heading.level);
+            const lower = section.toLowerCase();
+            const hitTerms = terms.filter((term) => lower.includes(term));
+            if (hitTerms.length === 0)
+                continue;
+            if (options.mode === "all" && hitTerms.length < terms.length)
+                continue;
+            const matchLines = [];
+            for (let index = heading.index; index < lines.length && matchLines.length < 3; index += 1) {
+                const text = lines[index];
+                const lineTerms = hitTerms.filter((term) => text.toLowerCase().includes(term));
+                if (lineTerms.length === 0)
+                    continue;
+                if (matchLines.length > 0 && /^(#{1,6})\s+/.test(text))
+                    continue;
+                matchLines.push({ line: index + 1, text: text.trim(), terms: lineTerms });
+            }
+            const headingHit = hitTerms.some((term) => heading.heading.toLowerCase().includes(term));
+            const bytes = Buffer.byteLength(section, "utf8");
+            found.push({
+                topic: document.name,
+                heading: heading.heading,
+                sectionOrdinal: ordinal + 1,
+                matchLines,
+                sectionBytes: bytes,
+                section,
+                // Heading hits beat body hits; more distinct terms beat fewer; smaller
+                // sections beat larger ones (cheaper to carry, usually more specific).
+                score: (headingHit ? 1000 : 0) + hitTerms.length * 100 + Math.max(0, 100 - Math.round(bytes / 64)),
+            });
+        }
+    }
+    found.sort((left, right) => right.score - left.score
+        || left.topic.localeCompare(right.topic)
+        || left.sectionOrdinal - right.sectionOrdinal);
+    return { matches: found.slice(0, Math.max(1, options.limit)), total: found.length };
+}
 //# sourceMappingURL=skills.js.map

package/dist/tools.js

@@ -21,6 +21,8 @@ import { registerListViewLane } from "./lanes/list-view.js";
 import { registerReportLane } from "./lanes/report.js";
 import { registerApplyChangesLane } from "./lanes/apply-changes.js";
 import { executionMetadataFor } from "./execution-metadata.js";
+import { attachRefusalRecovery } from "./refusal-guidance.js";
+import { ToolRefusalError } from "./tool-types.js";
 export { ToolRefusalError, ToolUncertainError } from "./tool-types.js";
 export { makeToolContext };
 /**
@@ -59,6 +61,39 @@ export function buildToolRegistry() {
         if (metadata)
             tool.executionMetadata = metadata;
     }
+    // r19 ticket 06 — 拒绝即教学，收口在最深的一层：每个 handler 返回/抛出的
+    // refused 结果在这里统一附加 recovery（同源配方命令、正确形状、不要做什么）。
+    // 收口在 registry 而不是 CLI 出口，是因为 runToolCall、测试 harness、MCP
+    // client、组装器全部经过 handler——一处附加、处处生效。已自带 recovery 的
+    // 拒绝（write-lock-held）不会被覆盖（attachRefusalRecovery 幂等）。
+    for (const tool of tools) {
+        const inner = tool.handler;
+        const name = tool.name;
+        tool.handler = async (ctx, args, self) => {
+            try {
+                const result = await inner(ctx, args, self);
+                if (result && typeof result === "object") {
+                    const status = result.status;
+                    // attachRefusalRecovery decides for itself: refused envelopes get
+                    // guidance, uncertain ones only when the dashboard boundary is
+                    // pinned in the frozen detail (r19 p14).
+                    if (status === "refused" || status === "uncertain") {
+                        return attachRefusalRecovery(result, name, tools);
+                    }
+                }
+                return result;
+            }
+            catch (error) {
+                const payload = error.payload;
+                if (payload && typeof payload === "object" && payload.status === "refused") {
+                    const enriched = attachRefusalRecovery(payload, name, tools);
+                    if (enriched !== payload)
+                        throw new ToolRefusalError(enriched);
+                }
+                throw error;
+            }
+        };
+    }
     return tools;
 }
 export { loadCoverageManifest };

package/dist/usage-log.js

@@ -34,6 +34,21 @@ const USAGE_LOG_MAX_BYTES = 8 * 1024 * 1024;
  * Memos still read `logPath()` only — a fallback log is append-only telemetry,
  * never a source of "already did this" answers.
  */
+/**
+ * r19 ticket 02: explicit opt-out for the WRITE side of the ledger.
+ *
+ * A maintainer script or an investigation subprocess that runs read-only
+ * discovery faces inside a sandbox used to append to that round's
+ * `.omc/usage.jsonl` — the r18 probe was read as 469 calls where the agent
+ * made 184 (19 polling reads + 105 investigation reads). "What did this round
+ * cost" must mean "what did the AGENT spend": `OMC_NO_USAGE=1` mutes this
+ * invocation's records (project log, user fallback, explicit OMC_USAGE_LOG —
+ * the switch beats them all). Only the write entry points consult this guard;
+ * reading (`omc usage`, idempotency memos) is untouched.
+ */
+function recordingDisabled() {
+    return process.env.OMC_NO_USAGE === "1";
+}
 function recordLogPath() {
     const explicit = process.env.OMC_USAGE_LOG;
     if (explicit)
@@ -74,6 +89,8 @@ function appendRecord(path, record) {
 }
 /** Append a `script-call` record: one line of `omc script` = one inner tool call. */
 export function recordScriptCall(input) {
+    if (recordingDisabled())
+        return;
     const target = recordLogPath();
     if (!target)
         return;
@@ -209,7 +226,7 @@ function commandOf(argv) {
     for (let index = 2; index < argv.length && values.length < 2; index += 1) {
         const token = argv[index];
         if (token.startsWith("--")) {
-            if (["--out", "--max-output-bytes", "--args", "--args-file", "--env", "--environment", "--request-id", "--timeout-ms", "--wait", "--path", "--top"].includes(token))
+            if (["--out", "--max-output-bytes", "--args", "--args-file", "--env", "--environment", "--request-id", "--timeout-ms", "--wait", "--path", "--top", "--search", "--search-mode", "--limit"].includes(token))
                 index += 1;
             continue;
         }
@@ -227,7 +244,7 @@ function facesOf(argv) {
     // `omc artifact get <id> --jq <path>` showed up as a bare `artifact get` with
     // empty argKeys, so the cost report could not tell a 200 B projection from a
     // 44 KB pull — precisely the read path these flags exist to make cheap.
-    const faces = ["--full", "--compact", "--json", "--schema-only", "--param", "--example", "--section", "--sections", "--out", "--quiet", "--jq", "--summary", "--keys", "--path-only", "--extract", "--extract-keys", "--records"];
+    const faces = ["--full", "--compact", "--json", "--schema-only", "--param", "--example", "--section", "--sections", "--search", "--search-mode", "--out", "--quiet", "--jq", "--summary", "--keys", "--path-only", "--extract", "--extract-keys", "--records"];
     return faces.filter((face) => argv.includes(face));
 }
 const safeArgumentKeys = new Set(["schemaCode", "propertyCode", "code", "workflowCode", "ruleCode", "sheetCode", "id", "dataRuleType", "propertyType", "published", "handler"]);
@@ -270,6 +287,8 @@ function summarizeArgs(argv) {
     return summary;
 }
 export function beginUsage(argv) {
+    if (recordingDisabled())
+        return;
     const target = recordLogPath();
     if (!target)
         return;

package/dist/write.js

@@ -124,7 +124,7 @@ async function governedWrite(ctx, tool, args, execute, dryRunPayload) {
             const artifactRef = writeArtifact(ctx, `${tool.name}-${randomUUID().slice(0, 8)}.json`, artifact);
             return { status: executed.status, steps: executed.steps, failedStep: executed.failedStep, ...executed.envelope, ...(args.requestId ? { requestId: args.requestId } : {}), artifactFingerprint: artifactRef.detailSha256 };
         }
-        const { performed, readback, steps } = executed;
+        const { performed, readback, steps, halfSuccess } = executed;
         // Readback gate (live 2026-10-17): a tool that reports `readback.present:false`
         // has NOT proven its own write — the platform accepted the request but the
         // object is absent from the authoritative face. "Called without error" must
@@ -177,7 +177,7 @@ async function governedWrite(ctx, tool, args, execute, dryRunPayload) {
             });
             rollbackRef = { seq: entry.seq, hint: `omc rollback plan ${entry.seq}（--env ${entry.environment}）` };
         }
-        return { status: "ok", deliveryState, performed, readback, ...(readbackWarning ? { readbackWarning } : {}), ...(steps !== undefined ? { steps } : {}), ...(args.requestId ? { requestId: args.requestId, idempotency: idempotencyDeclaration(tool.name) } : {}), ...(productionConfirmed ? { productionConfirmed: true } : {}), ...(rollbackRef ? { rollback: rollbackRef } : {}), summary: writeSummary(tool.name, args, { performed, readback }, "done"), detailFile: artifactRef.detailFile, detailSha256: artifactRef.detailSha256, artifactFingerprint: artifactRef.detailSha256 };
+        return { status: "ok", deliveryState, performed, readback, ...(readbackWarning ? { readbackWarning } : {}), ...(steps !== undefined ? { steps } : {}), ...(halfSuccess !== undefined ? { halfSuccess } : {}), ...(args.requestId ? { requestId: args.requestId, idempotency: idempotencyDeclaration(tool.name) } : {}), ...(productionConfirmed ? { productionConfirmed: true } : {}), ...(rollbackRef ? { rollback: rollbackRef } : {}), summary: writeSummary(tool.name, args, { performed, readback }, "done"), detailFile: artifactRef.detailFile, detailSha256: artifactRef.detailSha256, artifactFingerprint: artifactRef.detailSha256 };
     });
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stalfh233/omc-cli",
-  "version": "0.4.98",
+  "version": "0.4.100",
   "description": "CloudPivot 8.6 configuration capability CLI — governed, fail-closed, coverage-manifest bounded.",
   "type": "module",
   "bin": {
@@ -50,9 +50,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@stalfh233/omc-fake-platform": "0.4.98",
+    "@stalfh233/omc-fake-platform": "0.4.100",
     "commander": "14.0.3",
-    "omc-core": "0.4.98",
+    "omc-core": "0.4.100",
     "proper-lockfile": "4.1.2",
     "write-file-atomic": "6.0.0",
     "zod": "^3.23.8",

package/skills/omc-business-configuration.md

@@ -156,7 +156,7 @@ rules:
   - **`queryConditions` 不能为空**：它是反向过滤器的唯一输入，空数组时回算日志照打但目标字段恒 0（r17 实测）。
   - **聚合目标必须是来源主表的标量列**（r18 2026-10-26 真机）：`aggregation.schemaCode` 指向**子表 schema** 时能发布，但目标模型从此整个不可写（`data.submit`/`data.update` 全回 40000 无明细），且子表无父单单号列、匹配恒 0；`dataItemCode` 写 `<子表>.<子列>` 则 publish 回 309004。要子表合计：先在来源主模型物化一个数值字段，再聚合该标量。
   - **DYNAMIC 条件的两个 code 分属两侧，写反了静默 0**：`propertyCode` = 来源模型字段，`currentPropertyCode` = 目标模型字段；语义「来源行的 X 等于本目标行的 Y」。
-  - **`propertyType`/`currentPropertyType`（BizPropertyType）与 `operatorType`（OperatorType）必须写整数**——两者都是 `@JsonCreator get(int)`：propertyType 0=SHORT_TEXT 2=NUMERICAL 3=DATE 9=WORK_SHEET…；operatorType 1=EQ 2=NEQ 3=GT 4=IT（小于）5=GTEQ 6=ITEQ（小于等于）9=IS_NULL 10=IS_NOT_NULL…。写名字会被 `ObjectMapperUtils` 抛 json processing exception，再被死循环校验掩码成 305003（工具接受名字并自动转码）。`calculateType` 相反，是**字符串**（SUM/COUNT/COUNTIF/SUMIF/AVG/MAX/MIN/LARGE/SMALL/UNION）。
+  - **`propertyType`/`currentPropertyType`（BizPropertyType）与 `operatorType`（OperatorType）必须写整数**——两者都是 `@JsonCreator get(int)`：propertyType 0=SHORT_TEXT 2=NUMERICAL 3=DATE 9=WORK_SHEET…；operatorType 1=EQ 2=NEQ 3=GT 4=IT（小于）5=GTEQ 6=ITEQ（小于等于）9=IS_NULL 10=IS_NOT_NULL…。写名字会被 `ObjectMapperUtils` 抛 json processing exception，再被死循环校验掩码成 305003（工具接受名字并自动转码）。`calculateType` 相反，是**字符串**（SUM/COUNT/COUNTIF/SUMIF/AVG/MAX/MIN/LARGE/SMALL/UNION）；LARGE/SMALL 必须带 k（`LARGE({来源.列},2)`），UNION 是文本拼接、resultType 必须是 0/1。
   - **回算时机（r17b 2026-10-26 完整行为图谱）**：① 目标行**自己 submit** 时镜像规则一定算（最可靠）；② 来源行 submit/update/**delete** 触发 `RollUpEventListener`→`FormulaPropertySupport` 事件回算（FIXED+DYNAMIC 混用、多组 OR、COUNTIF/MAX、子表行级条件都验过）；③ ⚠️ 事件回算**只在目标模型发布后几分钟内可靠**，之后静默停止（无报错）——`field.publish --force` 目标模型恢复。发布后平台自动生成 t100 `CALCULATE_RULE` 镜像行，别删。r17 真机：目标行 srcNo=C1、来源 C1 行 amt=100 → 读 100；再提交一条 C1/amt=5 → 读 105。
   - **普通数值字段 + 计算规则（type2）不能替代**：REST 路径永不执行（`CalculateHandler.java:50` 的 `forceExecuteCalculateRule` 从不置真），门户里才算。
 - **DYNAMIC 来源不要写点号**：`dataActions` 的 `currentDataItemValue` 写 `items.sealNo` 会被引擎当成**子表列集合**（DatasetImpl），标量目标收到集合 → 运行期 `submit/update` 报 50000（`WorkSheetBizField.fillClientContent: Incorrect value type`）。单跳关联字段直接写字段 code（引擎取 `.id`）；子表列只能用于公式/聚合。`rule.save` 已写前拒绝（`rule-graph-create-dynamic-source-is-child-collection`）。

package/skills/omc-start-here.md

@@ -26,7 +26,7 @@ be treated as a second source. Read this, then follow the topics it names.
    - `build`/`modify` → 按阶梯内联的**写工具 + 必填参数**执行。
    - `scout`（能不能/怎么写/是否支持）→ 先探边界（`omc-capability-scouting`），别直接写。若 `next` 返回 **`boundary`**（`match.kind:"boundary"`，如 `ocr-e-signature`/`release-prod`/`inline-coding`），说明需求**不在覆盖内**（`write:false`）：如实报告、用 `omc capabilities` 核对，**不要**用相近能力伪造实现。
    阶梯步骤已内联工具必填参数（`route.ladder[].tools`/`readTools`）与命中 recipe 的 `describe <tool> --example <id>`；据此直接执行——**不要再逐能力 `commands --lane`**，也不要先扫 `commands --json`/全部 `contract`/全部 `describe --full`。
-   方法论按 `route.readSections` 逐节读：对每条 `{topic, section}` 执行 `omc help <topic> --section "<section>"`（单节 0.4–3.4KB）。`omc help <topic>` 默认只回节索引（约 1KB，含每节字节数）；**不要 `--all` 读整篇**（5–14KB，读一次就留在后续每一轮窗口）。
+   方法论按 `route.readSections` 逐节读：对每条 `{topic, section}` 执行 `omc help <topic> --section "<section>"`（单节 0.4–3.4KB）。`omc help <topic>` 默认只回节索引（约 1KB，含每节字节数）；**不要 `--all` 读整篇**（5–14KB，读一次就留在后续每一轮窗口）。**带着具体问题（错误码/跨能力语义/某个词）直接 `omc help --search "<词>"`**——跨全部 topic 全文检索，命中节的正文随结果内联返回，一次调用就是答案；**严禁自己写 `for t in …; do omc help $t --all | grep …` 循环**（r18 实测 12 调用/176KB，检索一次 8KB 搞定）。
 2. 写前只需读 `omc-config-draft-review`（人审门）与 `omc-five-piece-flow`（发现→草稿→权限→执行→回读）；`omc-business-configuration` 按命中的能力分节读（见 `next` 的 `readSections`），不要整篇预取。
 3. 环境名以 `omc doctor` 的「环境=」或 `.omc-env` 为准；工具不确定先用默认 `describe`/`--example`，只有单个工具缺形状才用 `--full`；`describe` 带 `exampleHint`/`recipeHint` 时优先 `--example`。
 4. 只有工具不在 `next` 命中能力内、或要看 purpose/枚举时，才补一次 `commands --json --compact --lane <lane>`。非显然形状（规则图、流程模板、表单布局、RESTFUL）才单独 `describe --example`。
@@ -50,6 +50,7 @@ omc script - --env <env> <<< '{"tool":"model.list"}'   # 多调链：NDJSON 每
 omc capability <selected-id>               # only the selected capability
 omc describe <tool> --example <recipe-id>   # recipe first; default describe otherwise
 omc help <topic> --section "<heading>"       # one methodology section, not all
+omc help --search "40000"                    # full-text search across all topics (answer in one call)
 ```
 
 Discovery precedes every write. 预算档位见 `omc-tool-selection` 的「Discovery 成本档位」；裸 `omc commands` 是有界索引，全量目录须显式 `commands --json`。

package/skills/omc-write-hazards.md

@@ -97,6 +97,16 @@ omc call field.publish --env local --args '{"schemaCode":"expense"}'
 
 - **同一 `<env>` 的写调用必须串行发起**：`write-lock-held` 不只在"并行重放失败请求"时出现，也会在**并行发起两个无关写**时触发（实测：并行两条 `dictionary.save`、并行 `field.update`+`field.publish` 各失败一次）。读可并行，写不要。
 
+## 审批提交的真实形状（r18b 2026-10-26 真机，1.1.25）
+
+| 参数 | 位置 | 语义 |
+|---|---|---|
+| `agree` | **顶层** | true=通过 / false=驳回；**缺省=true**（驳回后实例仍 PROCESSING，别当成功） |
+| `approval.content` / `relUsers` / `resources` | approval 对象 | 意见 / 下一步审批人 / 附件 |
+| `approval.agree`、`approval.opinion` | — | **静默忽略**（真机：agree:false 仍 APPROVE 且走完流程；opinion 不落库）。OMC 已写前拒绝 |
+
+链：`data.save`(draft→workItemId) → `data.submit`(顶层 agree) → 下一级待办。验收看 `sequenceStatus`。
+
 ## 计算规则（datarule）的取值时机
 
 - **字段计算规则（`datarule.create` `dataRuleType:2`）在 REST 路径上不会执行、也不会回填**（r17 2026-10-25 复核，AI-Platform 1.1.25）：
@@ -112,15 +122,13 @@ omc call field.publish --env local --args '{"schemaCode":"expense"}'
   **回算可靠性（重要）**：① 目标行**自己 submit** 时镜像规则一定算（最可靠）；② 来源行 submit/update/delete 的事件回算**只在目标模型发布后几分钟内可靠**，之后静默停止（无报错，源变了目标不更新）——重新 `field.publish --force` 目标模型恢复。验收：发布后立刻改来源行并读目标字段；长期对账别依赖事件回算。
 - **同模型（含自己的子表）聚合不可用**：`field.publish` 必抛 305003 —— `publishFormula` 把相对码改写成子表父模型（= 本模型），
   `checkCycleOfAggregation:1032` 判成环。与 payload 无关，8.6.26 与 1.1.25 代码相同。OMC 已写前拒绝 `aggregation-self-schema-cycle`。
-- **聚合目标不能是任何子表 schema，数据项必须是来源主表的标量列**（r18 2026-10-26 真机，代价约 40 次调用）：
-  `aggregation.schemaCode` 指向子表时**能发布**，但目标模型从此整个不可写 —— `data.submit`/`data.update` 全部回
-  `40000 调用数据库发生异常`（无明细）；且子表 schema 无父单单号列，按父单匹配恒为 0。
-  `dataItemCode` 写成 `<子表>.<子列>` 则在 publish 回 309004「使用的聚合数据项不存在」。
-  正解：要子表合计，先在来源**主模型**物化一个数值字段（门户计算规则 / 写入方维护），再聚合该标量。
-  OMC 已写前拒绝 `aggregation-target-is-child-schema`（读一次来源字段清单识别 parentId+sortKey）与
-  `aggregation-data-item-not-scalar`（点号）。
-- **`40000` 的无明细掩码怎么查**：先怀疑字段级配置（上面的聚合/公式），用「删/禁一个公式字段再写一次」二分，
-  不要从表单/权限开始查。OMC 现在会把 40000 转成 `runtime-write-db-exception` 并列出该模型的公式字段。
+- **聚合必须指向来源主表的标量列**（r18/r18b 真机）：`schemaCode` 指向**子表 schema** 能发布，但目标模型从此整个不可写
+  （写入一律 `40000`，无明细），且子表无父单单号列、匹配恒 0；`dataItemCode` 写 `<子表>.<子列>` 则 publish 回 309004。
+  要子表合计：先在来源主表物化一个数值字段，再聚合该标量。写前拒绝：`aggregation-target-is-child-schema` / `aggregation-data-item-not-scalar`。
+- **`40000` 无明细时**先怀疑字段级配置（上面的聚合、公式序列化），用「删/禁一个公式字段再写一次」二分，别从表单/权限查。
+  OMC 会转成 `runtime-write-db-exception` 并列出该模型的公式字段。
+- **`LARGE/SMALL` 必须带 k**：`LARGE({来源.列},2)`（缺 k → NumberFormatException → 写入 50000）；
+  **`UNION` 是文本拼接**，顶层 `resultType` 必须 0/1（写 2 会 50000）。拒绝：`aggregation-large-missing-k` / `aggregation-union-result-type`。
 - **区别：`FORMULA`（计算公式，`propertyType:100`）字段的 EXPRESSION 模式仍只在前端算** —— API 写入不回填。
 
 ## 规则与业务集成