@stalfh233/omc-cli 0.4.99 → 0.4.100

package/dist/goal-routes.js

@@ -146,7 +146,13 @@ function bestRecipe(registry, capabilityId, lane, goal, minScore = 3) {
         if (tool.lane !== lane)
             continue;
         for (const recipe of tool.executionMetadata?.recipes ?? []) {
-            const score = overlap(goal, `${recipe.title} ${recipe.id} ${(recipe.aliases ?? []).join(" ")}`);
+            // r19 ticket 04: an authored ALIAS phrase present in the goal is a much
+            // stronger signal than bigram overlap — "…汇总另一个模型的…" must route to
+            // formula-aggregation-cross-model, not the title-overlapping dropdown
+            // recipe. +20 per exact alias hit keeps authored intent decisive while
+            // overlap still ranks within equally aliased candidates.
+            const aliasBonus = (recipe.aliases ?? []).reduce((sum, alias) => (goal.includes(alias) ? sum + 20 : sum), 0);
+            const score = overlap(goal, `${recipe.title} ${recipe.id} ${(recipe.aliases ?? []).join(" ")}`) + aliasBonus;
             if (score >= minScore && (best === undefined || score > best.score))
                 best = { tool: tool.name, recipe: recipe.id, title: recipe.title, score };
         }
@@ -265,50 +271,39 @@ function sectionPointersFor(ids) {
     return pointers;
 }
 /**
- * Ready-to-run methodology reads.
+ * Ready-to-run methodology reads — r19 ticket 04: ONE pointer, not a shelf.
  *
- * Round 15 (bench60-62) collapsed ~18 per-section reads into one per topic to
- * save turns. r10 F7 found the other edge: following that hint fetched
- * EVERYTHING at once (~15 KB) when most tasks need only the first section.
- * So the primary command per topic fetches the FIRST required section, and the
- * remaining sections are offered as separate incremental commands (each keeps
- * its byte count in `readSections`) — cheap by default, still one command away.
+ * Round 15 collapsed per-section reads; r10 F7 made the first section cheap.
+ * r18 then showed the residual cost is ATTENTION, not bytes: seven pointers
+ * made the agent crawl methodology before acting, and the generic draft
+ * template ("3. Draft template") was read and produced nothing on
+ * recipe-matched routes. So: a recipe-matched route carries NO pointer (the
+ * recipe command is the answer); otherwise exactly one — the first authored
+ * pointer that is not the omc-config-draft-review human-gate template (that
+ * gate is conversational, not a section to prefetch), falling back to the
+ * first pointer when every authored pointer is draft-review.
  */
-function splitReadCommands(pointers) {
-    const byTopic = new Map();
-    for (const pointer of pointers)
-        byTopic.set(pointer.topic, [...(byTopic.get(pointer.topic) ?? []), pointer.section]);
-    const readCommands = [];
-    const readMore = [];
-    for (const [topic, sections] of byTopic.entries()) {
-        readCommands.push(`omc help ${topic} --section "${sections[0]}"`);
-        for (const section of sections.slice(1))
-            readMore.push(`omc help ${topic} --section "${section}"`);
-    }
-    return { readCommands, readMore };
+function pickSectionPointer(pointers, recipeMatched) {
+    if (recipeMatched || pointers.length === 0)
+        return [];
+    const specific = pointers.find((pointer) => pointer.topic !== "omc-config-draft-review");
+    return [specific ?? pointers[0]];
 }
+const FIRST_SECTION_INLINE_BUDGET_BYTES = 2048;
 /**
- * The route's methodology-read surface: pointers (+ per-section bytes) +
- * ready-to-run batched commands + hint.
- *
- * F9 (r10-friction): the most common task flow was `next` followed
- * IMMEDIATELY by fetching the first readSection — one extra process +
- * round-trip every task. The first section now rides inline when it fits the
- * inline budget (~2 KB); larger sections stay pointer-only so `next` never
- * balloons.
+ * r19 ticket 04: a multi-capability ladder already carries tool maps and
+ * recipes, so its inline section budget is tighter — the 4096B `next` ceiling
+ * must survive a ladder + a 2.5KB section (r18: "工作流审批流程" would have
+ * been 4729B). Single-capability routes keep the fuller budget (F9).
  */
-const FIRST_SECTION_INLINE_BUDGET_BYTES = 2560;
-function routeReads(readSections) {
-    // Per-section UTF-8 bytes ride each pointer (one field, not a parallel array)
-    // so a caller can budget which sections to fetch — dogfood R1 found the
-    // batched readCommands could exceed a window with no way to see sizes.
-    const budgeted = readSections.map((pointer) => ({ ...pointer, bytes: sectionBytes(pointer) }));
-    // Inline the FIRST pointer that fits the budget (order = relevance); an
-    // oversized head section falls through to the next fitting one rather than
-    // dropping the inline content entirely.
+const LADDER_INLINE_BUDGET_BYTES = 1200;
+function routeReads(readSections, recipeMatched = false, inlineBudget = FIRST_SECTION_INLINE_BUDGET_BYTES) {
+    const budgeted = pickSectionPointer(readSections, recipeMatched).map((pointer) => ({ ...pointer, bytes: sectionBytes(pointer) }));
+    // Inline the ONE pointer's content when it fits the budget: the agent then
+    // needs zero extra calls for methodology (F9, r10-friction).
     let firstSection;
-    for (const pointer of budgeted.slice(0, 3)) {
-        if (pointer.bytes > 0 && pointer.bytes <= FIRST_SECTION_INLINE_BUDGET_BYTES) {
+    for (const pointer of budgeted) {
+        if (pointer.bytes > 0 && pointer.bytes <= inlineBudget) {
             const resolved = readSkillSection(pointer.topic, pointer.section);
             if (resolved) {
                 firstSection = { topic: pointer.topic, section: pointer.section, bytes: pointer.bytes, content: resolved.section };
@@ -316,15 +311,19 @@ function routeReads(readSections) {
             }
         }
     }
-    const commands = splitReadCommands(readSections);
-    return { readSections: budgeted, readCommands: commands.readCommands, ...(commands.readMore.length > 0 ? { readMore: commands.readMore } : {}), readHint: READ_HINT, ...(firstSection !== undefined ? { firstSection } : {}) };
+    return {
+        readSections: budgeted,
+        readCommands: budgeted.map((pointer) => `omc help ${pointer.topic} --section "${pointer.section}"`),
+        readHint: READ_HINT,
+        ...(firstSection !== undefined ? { firstSection } : {}),
+    };
 }
 /** UTF-8 byte length of one methodology section (best-effort; 0 when unreadable). */
 function sectionBytes(pointer) {
     const resolved = readSkillSection(pointer.topic, pointer.section);
     return resolved ? Buffer.byteLength(resolved.section, "utf8") : 0;
 }
-const READ_HINT = '先跑 readCommands（每个 topic 只取第一节，形状 `omc help <topic> --section "<section>"`，字节数见 readSections）；不够再按需补 readMore，不要一次全读。`omc help <topic>` 默认只回节索引（每节带字节数，约 1KB），不要再用 `--all` 读整篇（5–14KB，读一次就留在后续每一轮）。';
+const READ_HINT = '方法论只挂最相关的一节（readSections[0] 带字节数，`omc help <topic> --section "<节>"` 可回放，firstSection 已内联时就不用再取）；其他具体问题（错误码/跨能力语义/某个词）用 `omc help --search "<词>"` 一步全文检索；不要 `--all` 读整篇。';
 function orderedCapabilities(ids, index) {
     const selected = new Set(ids);
     const nodes = [...index.nodeById.values()];
@@ -434,6 +433,21 @@ const COMPOSER_ROUTES = Object.freeze([
 ]);
 /** Test seam: the composer registry, so a template typo can be caught offline. */
 export const COMPOSER_ROUTES_FOR_TEST = COMPOSER_ROUTES;
+/**
+ * r19 ticket 04 — the ONE question that unlocks each composer. A composer
+ * skeleton always carries placeholders, so a composer match is a `needs-input`
+ * first answer by definition; the question names exactly what to fill in.
+ */
+const COMPOSER_QUESTIONS = Object.freeze({
+    "model-purge": "要清理哪个模型？给我 schemaCode（不确定就先跑下面的只读判别动作拿清单）",
+    "model-scaffold": "给我模型 code、显示名和字段清单（每字段 code/名称/类型；子表放 subFields），我一条命令建完",
+    "approval-flow": "目标模型 schemaCode 和每级审批节点（节点名@角色code，多级用重复 --steps）是什么？",
+    compute: "目标模型 schemaCode、结果字段 code、公式是什么？（子表条件聚合再加 --where \"子列 = 值\"）",
+    "rule-when": "目标模型 schemaCode、触发时机（Create/Update…）、条件（--when）和动作（--then）各是什么？",
+    "form-default": "目标模型 schemaCode、字段 code 和默认值是什么？",
+});
+/** The read-only discriminator that supplies a missing schema code. */
+const LIST_MODELS_ACTION = "omc call model.list --args '{}'";
 function matchComposer(goal, mode) {
     // A composer is a WRITE path: reads and scouting asks must keep their ladder.
     if (mode !== "build" && mode !== "modify")
@@ -471,11 +485,19 @@ function wholePackageRoute(registry, goal, index) {
             primary: "intent",
             atomicSupplement: { note: "intent 已覆盖下列能力的创建；这些原子工具只用于 intent 未覆盖面（删除/生命周期/运行数据/精确 patch）：", ladder },
             ...routeReads(sectionPointersFor(ordered)),
-            firstCommands: [DISCOVERY_AUTHORITY.readiness],
+            // r19 ticket 04: readiness (discover_environment) left firstCommands —
+            // the probe executed it 0 times in 184 calls; it rides its own field now.
+            readiness: DISCOVERY_AUTHORITY.readiness,
+            firstCommands: ["omc intent schema"],
             write: true,
         },
         write: true,
         intent: intentGuidance(),
+        firstAnswer: {
+            state: "ready",
+            action: "omc intent schema",
+            why: "整包需求走声明式意图：先看 intent YAML 的键位与可运行示例，再按 starter 写文件（validate → plan → apply）",
+        },
     };
 }
 /** A configuration read-back ask that names no capability ("给我一份现状说明"). */
@@ -490,8 +512,13 @@ function readOverviewRoute(registry, goal, index) {
         confident: true,
         mode: "read",
         match: { kind: "read-overview", ref: ordered.join("→"), capabilities: ordered },
-        route: { ladder, ...routeReads(sectionPointersFor(["environment"])), firstCommands: [DISCOVERY_AUTHORITY.readiness], write: false, readback: true },
+        route: { ladder, ...routeReads(sectionPointersFor(["environment"])), readiness: DISCOVERY_AUTHORITY.readiness, firstCommands: [LIST_MODELS_ACTION], write: false, readback: true },
         write: false,
+        firstAnswer: {
+            state: "ready",
+            action: LIST_MODELS_ACTION,
+            why: "盘点从模型清单开始：一次调用拿到全部 schemaCode，后续读面（inspect/field.list）据此展开",
+        },
     };
 }
 export function goalRoute(registry, goal) {
@@ -522,7 +549,8 @@ export function goalRoute(registry, goal) {
                 verify: "omc capabilities / omc capability <id>（运行时清单才是权威边界；能力表只是阅读辅助）",
                 topics: ["omc-requirement-analysis", "omc-capability-scouting"].filter((topic) => availableTopics.has(topic)),
             },
-            route: { write: false, readback: false, firstCommands: ["omc capabilities", "omc capability <id>", "omc help omc-capability-scouting"] },
+            route: { write: false, readback: false, readiness: DISCOVERY_AUTHORITY.readiness, firstCommands: ["omc capabilities", "omc capability <id>", "omc help omc-capability-scouting"] },
+            firstAnswer: { state: "blocked", why: boundary.note },
         };
     }
     // Composer before the capability solver: a recurring write SHAPE has a single
@@ -542,14 +570,22 @@ export function goalRoute(registry, goal) {
                 composer: composer.id,
                 command: composer.command,
                 summary: composer.summary,
-                // The composer IS the first step; readiness still comes first because
-                // the command needs a bound environment to run.
-                firstCommands: [DISCOVERY_AUTHORITY.readiness, composer.command, composer.usage],
+                readiness: DISCOVERY_AUTHORITY.readiness,
+                // The composer IS the first step (its skeleton waits on the ONE
+                // question in firstAnswer; discover_environment no longer occupies
+                // the head slot — r18 executed it 0 times in 184 calls).
+                firstCommands: [composer.command, composer.usage],
                 write: true,
                 readback: true,
-                ...(topics.length > 0 ? { readCommands: topics.map((topic) => `omc help ${topic} --section "<节>"`), readHint: "只在 composer 的 --help 不够用时再读这些 topic 的对应节" } : {}),
             },
             ...(topics.length > 0 ? { topics } : {}),
+            firstAnswer: {
+                state: "needs-input",
+                question: COMPOSER_QUESTIONS[composer.id] ?? "补齐命令里的尖括号占位符后运行（形状见 pendingCommand）",
+                pendingCommand: composer.command,
+                ...(composer.id === "model-purge" || composer.id === "compute" ? { action: LIST_MODELS_ACTION } : {}),
+                why: composer.summary,
+            },
         };
     }
     const scores = [...capabilityScores(registry, goal).entries()].sort((left, right) => right[1] - left[1]);
@@ -562,6 +598,13 @@ export function goalRoute(registry, goal) {
         topics: [...availableTopics],
         write: false,
         mode,
+        // Not confident → say so and hand ONE next move instead of a topic shelf.
+        firstAnswer: {
+            state: "needs-input",
+            question: "把目标说成一个具体动作短语（对象 + 动作，如「给 X 模型加一个汇总字段」），我就能给出一步可跑的命令",
+            action: "omc help omc-requirement-analysis",
+            why: "没命中任何能力线索；不猜路径（precision over recall）",
+        },
     };
     const best = scores[0];
     if (best === undefined) {
@@ -601,6 +644,12 @@ export function goalRoute(registry, goal) {
         const readSections = sectionPointersFor(ordered);
         const write = readish ? false : ordered.some((id) => routeById.get(id)?.tools.some((name) => registryTools.get(name)?.kind === "write"));
         const whole = isWholePackageWrite(mode, goal, ordered.length);
+        // r19 ticket 04: the ladder's first RECIPE command is the first answer
+        // when one exists (its describe carries the copyable firstCall shape);
+        // otherwise the only missing input is the target object code.
+        const recipeCommands = ladder.flatMap((step) => step.recipe?.command ? [step.recipe.command] : []);
+        const firstAction = recipeCommands[0];
+        const firstRecipeId = ladder.find((step) => step.recipe) && (ladder.find((step) => step.recipe).recipe.id);
         // When intent is the primary path, the atomic ladder is only a POINTER to the
         // capabilities (dogfood R1: repeating every tool map was ~60% unused bytes).
         const atomicSupplement = { note: "intent 已覆盖这些能力的创建；原子工具只用于 intent 未覆盖面：", ladder: ladder.map((step) => ({ capability: step.capability, lane: step.lane, firstCommand: step.firstCommand ?? `omc commands --json --compact --lane ${step.lane}` })) };
@@ -612,13 +661,14 @@ export function goalRoute(registry, goal) {
             match: { kind: readish ? "read-ladder" : "ladder", ref: ordered.join("→"), capabilities: ordered },
             route: {
                 ...(whole ? { primary: "intent", atomicSupplement } : { ladder }),
-                ...routeReads(readSections),
+                ...routeReads(readSections, recipeCommands.length > 0, LADDER_INLINE_BUDGET_BYTES),
+                readiness: DISCOVERY_AUTHORITY.readiness,
                 // r18: when a step already carries a goal-matched recipe, the generic
                 // first section ("3. Draft template") is noise — the probe read it and
                 // got nothing. Say that the recipe command is the answer and the
                 // sections are only a fallback.
-                ...(ladder.some((step) => step.recipe)
-                    ? { readHint: "已命中配方：先跑 firstCommands 里的 `omc describe … --example …` 取形状；下面的 readSections 只是补充，不必先读（确实需要时用 `omc help <topic> --section \"<节>\"`，按 readMore 逐节补）。" }
+                ...(recipeCommands.length > 0
+                    ? { readHint: "已命中配方：先跑 firstCommands 里的 `omc describe … --example …` 取形状（首答自带 firstCall 可照抄）；方法论节已按需收缩，确实需要时用 `omc help <topic> --section \"<节>\"`。" }
                     : {}),
                 // Each ladder step already carried a runnable recipe command, but it sat
                 // buried at `ladder[i].recipe.command` behind a readiness line — r14's
@@ -626,8 +676,7 @@ export function goalRoute(registry, goal) {
                 // graph instead. Surface them at the top level where `firstCommands` is
                 // the thing an agent actually reads.
                 firstCommands: [
-                    DISCOVERY_AUTHORITY.readiness,
-                    ...ladder.flatMap((step) => step.recipe?.command ? [step.recipe.command] : []),
+                    ...recipeCommands,
                     // r13 #3: `capability workflow --executable` is 23 KB and still did not
                     // answer "how do I submit an approval" — the answer is a data.submit
                     // recipe, which lives in a DIFFERENT capability. When the goal is about
@@ -640,7 +689,17 @@ export function goalRoute(registry, goal) {
                 ...(readish ? { readback: true } : {}),
             },
             write,
-            ...(whole ? { intent: intentGuidance() } : {}),
+            ...(whole
+                ? { intent: intentGuidance(), firstAnswer: { state: "ready", action: "omc intent schema", why: "整包需求走声明式意图：先看 intent 的键位与示例，再按 starter 写文件" } }
+                : readish
+                    // A read ask about the model inventory itself is answered BY the
+                    // inventory call; any other read needs the target object code first.
+                    ? ordered.every((id) => id === "environment" || id === "model")
+                        ? { firstAnswer: { state: "ready", action: LIST_MODELS_ACTION, why: "问的就是模型清单本身：model.list 一次调用直接回答" } }
+                        : { firstAnswer: { state: "needs-input", question: "要查看哪个对象？给我 schemaCode（或业务名，我列清单核对）", action: LIST_MODELS_ACTION, why: "读路径命中多个能力：readTools 已内联，只差目标对象 code" } }
+                    : firstAction !== undefined
+                        ? { firstAnswer: { state: "ready", action: firstAction, why: `命中配方 ${firstRecipeId}：describe 首答自带 firstCall 形状，代入你的 schemaCode/字段 code 即可执行` } }
+                        : { firstAnswer: { state: "needs-input", question: "第一步要操作哪个对象？给我 schemaCode（或模型业务名，我列清单核对）", action: LIST_MODELS_ACTION, why: "未命中配方：需要目标对象 code 才能给出一步可跑的写命令" } }),
         };
     }
     // Single-capability mode: when several capabilities tie, a matching recipe
@@ -651,7 +710,7 @@ export function goalRoute(registry, goal) {
         return fallback;
     const write = readish ? false : route.tools.some((name) => registryTools.get(name)?.kind === "write");
     const recipe = readish ? undefined : bestRecipe(registry, capabilityId, route.lane, goal);
-    const firstCommands = [DISCOVERY_AUTHORITY.readiness];
+    const firstCommands = [];
     if (recipe)
         firstCommands.push(`omc describe ${recipe.tool} --example ${recipe.recipe}`);
     if (readish)
@@ -666,6 +725,7 @@ export function goalRoute(registry, goal) {
     if (!readish && /审批|通过|驳回|提交|签收/.test(goal) && (capabilityId === "workflow" || capabilityId === "runtimeData"))
         firstCommands.push("omc describe data.submit --example workflow-backed-data-submit");
     const whole = isWholePackageWrite(mode, goal, 1);
+    const recipeCommand = recipe ? `omc describe ${recipe.tool} --example ${recipe.recipe}` : undefined;
     return {
         status: "ok",
         goal,
@@ -683,13 +743,23 @@ export function goalRoute(registry, goal) {
             lane: route.lane,
             ...(whole ? { primary: "intent" } : {}),
             ...(readish ? { readTools: readToolsInLane(registry, route.lane) } : { tools: route.tools }),
-            ...routeReads(sectionPointersFor([capabilityId])),
+            ...routeReads(sectionPointersFor([capabilityId]), recipe !== undefined),
+            readiness: DISCOVERY_AUTHORITY.readiness,
             firstCommands,
             write,
             ...(readish ? { readback: true } : {}),
         },
         write,
         ...(whole ? { intent: intentGuidance() } : {}),
+        ...(whole
+            ? { firstAnswer: { state: "ready", action: "omc intent schema", why: "整包需求走声明式意图：先看 intent 的键位与示例，再按 starter 写文件" } }
+            : readish
+                ? capabilityId === "model"
+                    ? { firstAnswer: { state: "ready", action: LIST_MODELS_ACTION, why: "问的就是模型清单本身：model.list 一次调用直接回答" } }
+                    : { firstAnswer: { state: "needs-input", question: "要查看哪个对象？给我 schemaCode（或业务名，我列清单核对）", action: LIST_MODELS_ACTION, why: `读路径命中能力 ${capabilityId}：readTools 已内联，只差目标对象 code` } }
+                : recipeCommand !== undefined
+                    ? { firstAnswer: { state: "ready", action: recipeCommand, why: `命中配方 ${recipe.recipe}：describe 首答自带 firstCall 形状，代入你的 schemaCode/字段 code 即可执行` } }
+                    : { firstAnswer: { state: "needs-input", question: "要操作哪个对象？给我 schemaCode（或模型业务名，我列清单核对）", action: LIST_MODELS_ACTION, why: "未命中配方：需要目标对象 code 才能给出一步可跑的写命令" } }),
     };
 }
 //# sourceMappingURL=goal-routes.js.map

package/dist/lanes/report.js

@@ -387,11 +387,27 @@ export function registerReportLane(tools) {
         const page = (await wireCall(session, { path: ENDPOINTS.reportGet, query: { code } })).data;
         const objectId = String(page.id ?? page.reportObjectId ?? "");
         if (objectId) {
-            await biCall(session, {
-                path: ENDPOINTS.biReportPageSave,
-                body: { report: { objectId, title: args.name, attributes: "{}", global: JSON.stringify(DEFAULT_REPORT_GLOBAL) } },
-                auth: authOf(args.corpId, code, args.appCode),
-            });
+            try {
+                await biCall(session, {
+                    path: ENDPOINTS.biReportPageSave,
+                    body: { report: { objectId, title: args.name, attributes: "{}", global: JSON.stringify(DEFAULT_REPORT_GLOBAL) } },
+                    auth: authOf(args.corpId, code, args.appCode),
+                });
+            }
+            catch (error) {
+                // r19 p14（p9 实证）：报表服务未启动时 BI 初始化统一 502，但平台层的
+                // 报表页行**已经建了**。裸抛 uncertain 会掩盖这个残留——半成功必须
+                // 显式：回执带 halfSuccess 警示 + 清理命令，让 agent 下一调用就能收拾。
+                return {
+                    performed: { errcode: 0, code, appCode: args.appCode, objectId, biInit: "failed" },
+                    readback: { present: page.code === code, report: reportPageView(page), biInitialized: false },
+                    halfSuccess: {
+                        message: `平台层报表页已建（code=${code}，objectId=${objectId}），但 BI 初始化失败（${error instanceof Error ? error.message : String(error)}）——元数据已残留`,
+                        cleanup: `omc call report.delete --args '{"code":"${code}"}'（或保留，待报表服务启动后重试 BI 配置）`,
+                        boundary: "报表服务未启动时 BI 层（/dashboard/v1/*）统一 502——这是环境边界，不要原样重试",
+                    },
+                };
+            }
         }
         void created;
         return {

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