@stalfh233/omc-cli 0.6.6 → 0.6.10

package/dist/model-scaffold.js

@@ -128,7 +128,15 @@ export async function cmdModelScaffold(args) {
             });
             const status = String(probe.result.status ?? "ok");
             if (probe.exitCode !== 0 || (status !== "dry-run" && status !== "ok")) {
-                preflightProblems.push({ code: field.code, message: refusalText(probe.result) });
+                const result = probe.result;
+                // r28g F4：field.create 回执带 validation[]，脚手架以前只压成一句
+                // 「按 validation 修正」却把数组丢掉——调用方不得不再逐字段 dry-run。
+                const validation = Array.isArray(result.validation) ? result.validation : undefined;
+                preflightProblems.push({
+                    code: field.code,
+                    message: refusalText(result),
+                    ...(validation ? { validation } : {}),
+                });
             }
         }
         if (preflightProblems.length > 0) {
@@ -140,7 +148,7 @@ export async function cmdModelScaffold(args) {
                 failed: preflightProblems.length,
                 preflightProblems,
                 message: `有 ${preflightProblems.length} 个字段的预检没过，**尚未写入任何东西**。` +
-                    `按 message 改 --fields 后重跑（常见：NUMERICAL 缺 options.scale、文本/数值字段用了自定义键名）。` +
+                    `按 preflightProblems[].validation / message 改 --fields 后重跑（常见：NUMERICAL 缺 options.scale、code 风格不合法、文本/数值字段用了自定义键名）。` +
                     `--fields 的每一项就是 field.create 的参数（形状见 omc describe field.create），子表列用 subFields（childFields 是别名）。`,
             }, request, { code: "policy-refused", message: "字段形状预检未通过（未写入）", retryable: false }));
             return CLI_EXIT_CODES.policyRefused;
@@ -290,15 +298,28 @@ export async function cmdModelScaffold(args) {
     }
     const failedSteps = steps.filter((step) => step.status === "failed");
     const status = failedSteps.length > 0 ? "partial" : "ok";
+    const fieldCount = fields.reduce((sum, field) => sum + 1 + scaffoldChildrenOf(field).length, 0);
+    // NOTE: renamed locally to unblock tsx (parallel agent redeclared `created`
+    // in this same scope). Keep semantics identical.
+    const fieldsCreated = steps.filter((step) => step.step.endsWith("field.create") && step.status === "ok").length;
+    const publishActions = publishFieldSteps.filter((step) => step.status === "ok").length;
+    // r28g F5：旧键 publishedFields 实际是「发布动作次数/目标 schema 数」（常=1），
+    // 与 fieldCount 量级不符。保留旧键作兼容别名，同时给 publishActions + 字段计数。
+    const fieldsPublishedEstimate = publishingBlocked || fieldPublishFailed ? 0 : fieldsCreated;
     const result = {
         status,
         model: code,
         name,
-        fieldCount: fields.reduce((sum, field) => sum + 1 + scaffoldChildrenOf(field).length, 0),
-        created: steps.filter((step) => step.step.endsWith("field.create") && step.status === "ok").length,
+        fieldCount,
+        created: fieldsCreated,
         skipped: steps.filter((step) => step.step.endsWith("field.create") && step.status === "skipped").length,
         failed: failedFields.length,
-        publishedFields: publishTargets.size,
+        publishActions,
+        publishedFields: publishActions,
+        fieldsPublishedEstimate,
+        publishNote: publishActions > 0
+            ? `已执行 ${publishActions} 次模型级 field.publish（覆盖本次创建的约 ${fieldsPublishedEstimate}/${fieldCount} 个字段；精确清单用 field.list --published）`
+            : "未发布字段（有失败或被跳过）；精确状态用 field.list",
         ...(failedFields.length > 0 ? { failedFields } : {}),
         ...(failedSteps.length > 0 ? { failedSteps } : {}),
         ...(lastSummaries.length > 0 ? { summaries: lastSummaries } : {}),

package/dist/path-projection.js

@@ -1,6 +1,27 @@
 import { readFileSync } from "node:fs";
 import { readArtifact } from "./artifacts.js";
 import { artifactRoot } from "./command-transport.js";
+import { closestMatch } from "./closest-match.js";
+/**
+ * r28f F2：投影 DSL 不是 jq。对象构造 `{a,b}` / 函数调用 `map(...)` 被逗号
+ * 拆路径后会伪装成两条 pathMiss（available=键列表），误导下一轮。先识别再
+ * 报「不支持」——别让调用方以为键不存在。
+ */
+export const UNSUPPORTED_JQ_OBJECT_HINT = "投影 DSL 不支持对象构造 `{a,b}`；单列请写 `.x[].a`，多列用逗号分隔（--jq \".x[].a,.x[].b\"）或重复传 --jq";
+export function detectUnsupportedJqSyntax(path) {
+    if (/[{}]/.test(path))
+        return UNSUPPORTED_JQ_OBJECT_HINT;
+    // r28g F20（真机 2026-11-05）：jq 过滤表达式 `[?(@...)]` 会被当成路径段，
+    // 在 `rules[?(@` 处**截断**后报 pathMiss——读起来像"键不存在"，实际是
+    // "这个 DSL 不支持过滤"。直接说清，并给出本 DSL 的等价写法。
+    if (/\[\s*\?/.test(path)) {
+        return "投影 DSL 不支持 jq 过滤表达式 `[?(@...)]`；等价写法是按字段选择 `rules[code=Create]`（返回第一个匹配项），或先 `--jq rules[]` 全取再由脚本筛";
+    }
+    // 函数调用：`map(` / `select(` 等（选择器 `[code=X]` 不含 `(`）。
+    if (/\w+\s*\(/.test(path))
+        return "投影 DSL 不支持函数调用；只做路径选择（点式 / [] 映射 / [key=value]），详见 omc help omc-refusals --section 10";
+    return undefined;
+}
 export function projectJsonPath(value, path) {
     // r40 F9：`$.x`（jq 标准根写法）此前 pathMiss——agent/人都习惯带根前缀。
     // 归一剥掉前导 `$.`/`$`，语义等价（本 DSL 根就是整份结果）。
@@ -8,6 +29,11 @@ export function projectJsonPath(value, path) {
         path = path.slice(2);
     else if (path === "$")
         path = "";
+    // r28f F2：不支持语法优先于路径行走——避免 `{code` 被当成 miss 段。
+    const unsupported = detectUnsupportedJqSyntax(path);
+    if (unsupported !== undefined) {
+        return { missed: true, at: path, available: unsupported, unsupportedSyntax: true };
+    }
     // 2026-11-01（r36 维护者实测）：jq 切片 `a[0:6]`/`a[:n]`/`a[n:]` 此前
     // pathMiss 且 hint 的 available 还把数组列成"可用键"，误导下一步。数组
     // 切片与 jq 语义一致（含头不含尾）。
@@ -145,8 +171,77 @@ function argvValues(args, name) {
     }
     return values;
 }
-/** Shared wording for every projection miss, so all three faces teach the same syntax. */
-const PATH_MISS_HINT = "路径未命中（这一层没有该段）。可用写法：点式 a.b、下标 a[0]、切片 a[0:6]、数组映射 items[].fields.x、按键选择 rules[code=Create] 或 data.activities[code=A1]（数组与 index→条目对象都支持；键名可省 activityCode/nodeCode 等别名；返回第一个匹配项）。available 是该层真实存在的键。注意：本参数是路径选择器、不是 jq 语言（不支持 | 管道与对象构造）；一次取多列用逗号分隔（--jq \"a.b,c.d\"）或重复传 --jq。";
+/**
+ * 路径选择器语法**唯一**真相源（HANDOFF §三.1-3）。此前同一套语法在五处各写一份
+ * （`projectResultExtract` 的 miss、`artifact get --summary --jq`、artifact 裸
+ * `--jq`、逗号多路径部分 miss、以及 `artifact get` 的 fetch 提示），改一处忘一处
+ * 就会出现"同一个错误两种说法"。现在语法句子只在这里定义，其余地方拼装。
+ */
+export const JQ_PATH_SYNTAX = "可用写法：点式 a.b、下标 a[0]、切片 a[0:6]、数组映射 items[].fields.x、按键选择 rules[code=Create] 或 data.activities[code=A1]（数组与 index→条目对象都支持；键名可省 activityCode/nodeCode 等别名；返回第一个匹配项）。";
+/** 非 jq 语言 + 一次取多列的写法。每一处 miss 提示都以它收尾。 */
+export const JQ_PATH_RULES = "注意：本参数是路径选择器、不是 jq 语言（不支持 | 管道与对象构造）；一次取多列用逗号分隔（--jq \"a.b,c.d\"）或重复传 --jq。";
+/**
+ * `call --extract/--jq` 专有的位置语义：路径相对 **result**，不是整个信封。
+ * r26b 读回体积审计实测：调用方写 `--jq result.total` → `pathMiss`（missedAt:"result"），
+ * 白付一整份大回执 + 一轮；改成 `--jq total` 立即只有 356 B。这条只属于 call 面
+ * （`artifact get --jq` 相对的是产物正文，不能套用）。
+ */
+export const RESULT_RELATIVE_PATH_NOTE = "路径相对 **result**（不要写 result. 前缀，如 --jq total 而不是 --jq result.total）。";
+/** 语法不再只靠报错学：`omc help omc-refusals --section "10. 投影路径"` 是权威教程。 */
+export const JQ_PATH_TOPIC = "omc-refusals";
+export const JQ_PATH_SECTION = "10. 投影路径（--jq / --extract）";
+export const JQ_PATH_HELP_POINTER = `语法详解：omc help ${JQ_PATH_TOPIC} --section 10（投影路径）。`;
+/** Shared wording for every projection miss, so every face teaches the same syntax. */
+export const PATH_MISS_HINT = `路径未命中（这一层没有该段）。${RESULT_RELATIVE_PATH_NOTE}${JQ_PATH_SYNTAX}available 是该层真实存在的键。${JQ_PATH_RULES}${JQ_PATH_HELP_POINTER}`;
+/**
+ * `artifact get` 面：产物内容的投影。区别只在开头——它已经把 miss 落在哪一段
+ * （`missedAt`）和可用的键/范围一并返回，所以不必重复「这一层没有该段」。
+ */
+export function artifactPathMissHint(at) {
+    return `路径未命中${at !== undefined ? `段 "${at}"` : "（这一层没有该段）"}——available 是该层真实存在的键/范围；方括号下标（a[0]）与点式（a.0）等价。${JQ_PATH_SYNTAX}${JQ_PATH_RULES}${JQ_PATH_HELP_POINTER}`;
+}
+/** 逗号多路径里只有部分 miss：给出定位方式 + 同一套语法。 */
+export function partialPathMissHint() {
+    return `逗号多路径中部分路径未命中（见各 projection.pathMiss/missedAt/available）。${JQ_PATH_SYNTAX}${JQ_PATH_HELP_POINTER}`;
+}
+/**
+ * 逐条 miss 的**短**提示。r27 真机（2026-11-05）实证：一段 695 B 的完整语法在
+ * 3 条路径 miss 时被复制 3 遍 ≈ 2 KB，而三条说的是同一件事。所以多路径时单条
+ * 只指出「在哪断的、这一层有什么」，语法全集由结果顶层的 `hint` 给一次。
+ */
+export function pathMissEntryHint(at, available) {
+    const keys = Array.isArray(available) ? available.slice(0, 12).map((k) => String(k)) : [];
+    const atPart = at !== undefined ? `在 "${at}" 断开` : "这一层没有该段";
+    const more = Array.isArray(available) && available.length > 12 ? " 等" : "";
+    return keys.length > 0 ? `${atPart}；这一层有：${keys.join("、")}${more}` : atPart;
+}
+/**
+ * pathMiss 的 did-you-mean：对 miss 的最后一段在 available 键列表里做近似匹配。
+ * available 不是字符串数组（范围说明 / 空对象文案）或匹配不到时不加字段——
+ * 误导建议比没有更糟；过短输入由 closestMatch 自己静默。
+ */
+export function pathMissDidYouMean(at, available) {
+    if (at === undefined || at.length === 0)
+        return undefined;
+    if (!Array.isArray(available) || available.length === 0)
+        return undefined;
+    const keys = available.map((entry) => String(entry)).filter((entry) => entry.length > 0);
+    if (keys.length === 0)
+        return undefined;
+    // Missed segment may be `items[].workItemId` / `fields.repairNo` — match the
+    // last path piece against the keys at that layer.
+    const leaf = at.includes(".") || at.includes("/") || at.includes("[")
+        ? at.replace(/^[.\/]+/, "").split(/[./\[]/).filter(Boolean).pop() ?? at
+        : at;
+    return closestMatch(leaf, keys);
+}
+/**
+ * 多路径一次投影时的**唯一一份**语法说明（放结果顶层，不再逐条复制）。
+ * 只给最要紧的三条：位置语义、映射写法、help 指针。
+ */
+export function multiPathMissHint() {
+    return `${RESULT_RELATIVE_PATH_NOTE}${JQ_PATH_SYNTAX}${JQ_PATH_HELP_POINTER}`;
+}
 /**
  * T6（GitLab #17）：`mapped` 只是"路径命中的条目数"，值为 null 也算命中。
  * 全 null + ok:true 曾被读成"取到了 N 个值/台账只有 1 行"（真实 42 行）。
@@ -154,12 +249,38 @@ const PATH_MISS_HINT = "路径未命中（这一层没有该段）。可用写
  * 与字段本身为空。
  */
 const ALL_NULL_HINT = `路径全部命中但值都是 null——注意 mapped 只是命中条目数，不代表有值。常见成因是列表投影没配置该列（data.list 只投影视图列，null 或整键省略；看同一次 data.list 的 projectionHint，或用 data.load 读单条权威值）。若 projectionHint 也指向该列，就不是"字段为空"。`;
+/**
+ * `mapped`/`nullEntries` 的读法跟数据一起走（T6 / A6）。仅在确实出现 null 时加
+ * 提示，正常读取零噪音；全 null 用同一段文案，避免"同一事实三种说法"。
+ */
+export function nullProjectionHint(nullEntries, total) {
+    if (nullEntries === undefined || nullEntries === 0)
+        return undefined;
+    if (total === 0 || nullEntries !== total)
+        return `其中 ${nullEntries} 个命中值为 null（不区分"字段为空"与"列表未投影"）。`;
+    return ALL_NULL_HINT;
+}
 /**
  * `call --extract/--extract-keys`: resolve paths inside the result's own
  * artifact (or inside the result object when the tool returned no artifact).
  * Returns undefined when there is nothing to project so the caller's result is
  * emitted unchanged.
  */
+/**
+ * r28g F29（真机 2026-11-05）：读面回执的**顶层**常带 `modelsCount` / `count`
+ * 这类只在 result 层有的键；`--jq modelsCount` 却去 artifact 副本里找，
+ * 于是 pathMiss，且 `available` 列的是 artifact 的键——调用方看到"键明明打印过
+ * 却说没有"。这里把事实补回去：该路径在 result 层存在时明确指路。
+ */
+function resultLayerNote(result, path) {
+    const head = path.replace(/^\$\.?/, "").split(/[.\[]/)[0];
+    if (head === "" || !(head in result))
+        return undefined;
+    return {
+        existsOnResult: head,
+        resultLayerHint: `「${head}」在 result 顶层（只是不在 artifact 副本里）。取它请不带 --jq 直接读回执，或改取 artifact 内的键（见 available）`,
+    };
+}
 export function projectResultExtract(result, paths, keysOnly) {
     const artifactId = typeof result.detailArtifactId === "string" ? result.detailArtifactId : typeof result.artifactId === "string" ? result.artifactId : undefined;
     // Tools hand an in-process artifact as `detailFile` (a local path);
@@ -212,35 +333,96 @@ export function projectResultExtract(result, paths, keysOnly) {
             : [];
     }
     if (paths.length > 0) {
+        // r27 真机：多路径时每条 miss 都带 695 B 完整语法 → 3 条 2 KB 说同一件事。
+        // 单路径照旧带完整提示（只出现一次，最有用）；多路径逐条只给定位，语法放顶层一次。
+        const multiPath = paths.length > 1;
+        const missHintFor = (at, available) => multiPath ? pathMissEntryHint(at, available) : PATH_MISS_HINT;
         out.extract = paths.map((path) => {
+            // r28f F2：对象构造 / 函数调用不是 pathMiss——先识别，别伪装成键缺失。
+            const unsupported = detectUnsupportedJqSyntax(path);
+            if (unsupported !== undefined) {
+                return {
+                    path,
+                    content: null,
+                    pathMiss: false,
+                    unsupportedSyntax: true,
+                    unanswered: true,
+                    available: unsupported,
+                    hint: unsupported,
+                };
+            }
             // `items[].fields.planNo` maps over every row; a plain path stays a single
             // value (issue 2026-10-25 §8). Both faces share one shape so a caller can
             // switch between `--extract`/`--jq` without relearning the envelope.
             if (path.includes("[]")) {
                 const fanout = projectJsonPathFanout(source, path);
-                return fanout.missed
-                    ? { path, content: null, pathMiss: true, missedAt: fanout.at, available: fanout.available, missedEntries: fanout.missedEntries, hint: PATH_MISS_HINT }
-                    : {
+                if (fanout.missed) {
+                    const didYouMean = pathMissDidYouMean(fanout.at, fanout.available);
+                    return {
                         path,
-                        content: fanout.values,
-                        mapped: fanout.values.length,
-                        ...(fanout.nullEntries > 0 ? { nullEntries: fanout.nullEntries } : {}),
-                        ...(fanout.nullEntries > 0 && fanout.nullEntries === fanout.values.length ? { hint: ALL_NULL_HINT } : {}),
-                        ...(fanout.missedEntries > 0 ? { missedEntries: fanout.missedEntries, hint: `有 ${fanout.missedEntries} 条记录在该路径下缺失，values 只含命中项` } : {}),
+                        content: null,
+                        pathMiss: true,
+                        missedAt: fanout.at,
+                        available: fanout.available,
+                        missedEntries: fanout.missedEntries,
+                        ...(didYouMean !== undefined ? { didYouMean } : {}),
+                        ...(readFromArtifact ? resultLayerNote(result, path) ?? {} : {}),
+                        hint: missHintFor(fanout.at, fanout.available),
                     };
+                }
+                return {
+                    path,
+                    content: fanout.values,
+                    mapped: fanout.values.length,
+                    ...(fanout.nullEntries > 0 ? { nullEntries: fanout.nullEntries } : {}),
+                    ...(fanout.nullEntries > 0 && fanout.nullEntries === fanout.values.length ? { hint: ALL_NULL_HINT } : {}),
+                    ...(fanout.missedEntries > 0 ? { missedEntries: fanout.missedEntries, hint: `有 ${fanout.missedEntries} 条记录在该路径下缺失，values 只含命中项` } : {}),
+                };
             }
             const projected = projectJsonPath(source, path);
-            return projected.missed
-                ? { path, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, hint: PATH_MISS_HINT }
-                : { path, content: projected.value ?? null };
+            if (projected.missed) {
+                // projectJsonPath 也会拦 unsupportedSyntax；双保险统一出口。
+                if (projected.unsupportedSyntax === true) {
+                    return {
+                        path,
+                        content: null,
+                        pathMiss: false,
+                        unsupportedSyntax: true,
+                        unanswered: true,
+                        available: projected.available,
+                        hint: typeof projected.available === "string" ? projected.available : UNSUPPORTED_JQ_OBJECT_HINT,
+                    };
+                }
+                const didYouMean = pathMissDidYouMean(projected.at, projected.available);
+                return {
+                    path,
+                    content: null,
+                    pathMiss: true,
+                    missedAt: projected.at,
+                    available: projected.available,
+                    ...(didYouMean !== undefined ? { didYouMean } : {}),
+                    ...(readFromArtifact ? resultLayerNote(result, path) ?? {} : {}),
+                    hint: missHintFor(projected.at, projected.available),
+                };
+            }
+            return { path, content: projected.value ?? null };
         });
         if (paths.length === 1)
             out.content = out.extract[0]?.content ?? null;
         // A projection that missed is not an answer. `status` stays `ok` (adding a
         // new status value would fall through classifyResult to error/exit 15 and
         // change the exit contract), but the envelope now says so out loud.
-        if (out.extract.some((entry) => entry.pathMiss === true))
+        const extracts = out.extract;
+        if (extracts.some((entry) => entry.pathMiss === true || entry.unsupportedSyntax === true)) {
             out.unanswered = true;
+            // 多路径：语法说明给一次，不再逐条复制。不支持语法优先于 pathMiss 语法课。
+            if (extracts.some((entry) => entry.unsupportedSyntax === true)) {
+                out.hint = UNSUPPORTED_JQ_OBJECT_HINT;
+            }
+            else if (multiPath) {
+                out.hint = `${RESULT_RELATIVE_PATH_NOTE}${JQ_PATH_SYNTAX}${JQ_PATH_HELP_POINTER}`;
+            }
+        }
     }
     return out;
 }

package/dist/plan.js

@@ -24,6 +24,28 @@ export function planFingerprint(plan) {
     }))
         .digest("hex");
 }
+/**
+ * r28g F8（真机 2026-11-05）：dry-run 的 `*Summary` 只给键名 + sha256，把**最该
+ * 自查的那段**（三层转义后的条件串）整个遮住——校验通过的结论看得见，被校验的
+ * 内容看不见。这里补一个 `*Preview`：把**小**的字符串叶子原样列出（总长 ≤400B），
+ * 超了就不给（还是回到摘要）。目的是"可自查形状"，不是把正文搬回来。
+ */
+function smallStringPreview(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const out = {};
+    let budget = 400;
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry !== "string")
+            continue;
+        const bytes = Buffer.byteLength(entry, "utf8");
+        if (bytes > budget)
+            continue;
+        budget -= bytes;
+        out[key] = entry;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 function summarizedArgs(tool, args) {
     if (typeof args.summary === "string" && typeof args.fingerprint === "string")
         return { ...args };
@@ -36,6 +58,9 @@ function summarizedArgs(tool, args) {
         }
         else if (Array.isArray(value) || (value && typeof value === "object") || typeof value === "string") {
             summary[`${key}Summary`] = summarizeValue(value);
+            const preview = smallStringPreview(value);
+            if (preview !== undefined)
+                summary[`${key}Preview`] = preview;
         }
         else {
             summary[key] = value;

package/dist/programming-workflow.js

@@ -50,6 +50,58 @@ export function readManifest(paths) {
         return null;
     return JSON.parse(readFileSync(paths.manifestFile, "utf8"));
 }
+/**
+ * r28j F13: existence used to mean "manifest.json present" only, so a user who
+ * hand-wrote `.omc-programming/tests/...` was told the whole workspace was
+ * absent. Distinguish "nothing here" / "tests-only" / "sources without
+ * manifest" so the refusal names the paths it checked.
+ */
+export function describeWorkspacePresence(paths) {
+    const hasRoot = existsSync(paths.root);
+    const hasManifest = existsSync(paths.manifestFile);
+    const hasSources = existsSync(paths.sourcesDir);
+    const hasTests = existsSync(paths.testsDir);
+    return {
+        present: hasManifest,
+        hasRoot,
+        hasManifest,
+        hasSources,
+        hasTests,
+        checked: [paths.manifestFile, paths.sourcesDir, paths.testsDir],
+    };
+}
+export function workspaceAbsentRefusal(paths) {
+    const presence = describeWorkspacePresence(paths);
+    if (!presence.hasRoot) {
+        return {
+            status: "refused",
+            blocker: "programming-workspace-absent",
+            message: `本地没有 .omc-programming/。先 omc programming pull --env <env> --app <appCode>。已检查：${presence.checked.join(" · ")}`,
+            checked: presence.checked,
+        };
+    }
+    if (presence.hasTests && !presence.hasManifest) {
+        return {
+            status: "refused",
+            blocker: "programming-workspace-manifest-absent",
+            message: `已有 .omc-programming/tests/，但缺 manifest.json（以及通常还有 sources/）。tests 单独存在不算完整工作区——先 omc programming pull --env <env> --app <appCode> 生成 manifest+sources，再保留你的 tests。已检查：${presence.checked.join(" · ")}`,
+            checked: presence.checked,
+            hasTests: true,
+            hasManifest: false,
+            hasSources: presence.hasSources,
+        };
+    }
+    return {
+        status: "refused",
+        blocker: "programming-workspace-absent",
+        message: `本地 .omc-programming/ 不完整（缺 manifest.json）。先 omc programming pull --env <env> --app <appCode>。已检查：${presence.checked.join(" · ")}`,
+        checked: presence.checked,
+        hasRoot: true,
+        hasManifest: false,
+        hasSources: presence.hasSources,
+        hasTests: presence.hasTests,
+    };
+}
 function writeManifest(paths, manifest) {
     mkdirSync(paths.root, { recursive: true });
     const ordered = {
@@ -198,7 +250,7 @@ export async function cmdProgrammingStatus(options) {
     const session = await context.sessions.session(options.environment);
     const manifest = readManifest(paths);
     if (!manifest)
-        return { status: "refused", blocker: "programming-workspace-absent", message: "本地没有 .omc-programming/。先 omc programming pull --env <env> --app <appCode>。" };
+        return workspaceAbsentRefusal(paths);
     try {
         assertManifestEnvironment(manifest, session.environmentName, session.profile.baseUrl);
     }
@@ -429,7 +481,7 @@ export async function cmdProgrammingApply(options) {
     const paths = workspacePaths(options.cwd);
     const manifest = readManifest(paths);
     if (!manifest)
-        return { status: "refused", blocker: "programming-workspace-absent", message: "本地没有 .omc-programming/。先 omc programming pull --env <env> --app <appCode>。" };
+        return workspaceAbsentRefusal(paths);
     const context = options.ctx ?? makeToolContext({ sessions: new SessionManager(new ConfigStore(defaultPaths())) });
     const session = await context.sessions.session(options.environment);
     try {
@@ -616,7 +668,7 @@ export async function cmdProgrammingTest(options) {
     const paths = workspacePaths(options.cwd);
     const manifest = readManifest(paths);
     if (!manifest)
-        return { status: "refused", blocker: "programming-workspace-absent", message: "本地没有 .omc-programming/。先 omc programming pull --env <env> --app <appCode>。" };
+        return workspaceAbsentRefusal(paths);
     const context = options.ctx ?? makeToolContext({ sessions: new SessionManager(new ConfigStore(defaultPaths())) });
     const session = await context.sessions.session(options.environment);
     try {

package/dist/read-shapes.js

@@ -0,0 +1,146 @@
+/**
+ * Explicit return-shape table for high-frequency read tools.
+ *
+ * Agents guess jq paths from input arg names (`controls`, `ruleCode`, `id`,
+ * bare business columns) and miss the real result keys. `describe` only listed
+ * inputs, so the only recovery was a pathMiss `available` list. This table is
+ * the cheap pre-call face: one tool's keys (+ one short trap note) on describe.
+ *
+ * Deliberately incomplete — undeclared tools omit `returns` entirely. Do not
+ * invent shapes from intuition.
+ */
+const READ_SHAPES = {
+    // r28k 治理面形状钉：截断≠空表；指纹有用途；doctor/get_status 分流。
+    "discover_environment": {
+        keys: ["applications:array<{code,name,groupId?,portalHidden?}>", "applicationsCount", "groups", "groupsCount", "foldersAndModels?", "foldersAndModelsCount?", "foldersAndModelsOmitted?", "models?", "modelsCount?", "modelsOmitted?", "tablesHint?", "applicationCode", "applicationResolution", "readiness", "environmentFingerprint", "fingerprintHint?", "detailArtifactId?"],
+        notes: [
+            "applications/groups 内联；foldersAndModels/models 外置时是 null + *Omitted:true（不是 []）",
+            "environmentFingerprint 用途见 fingerprintHint（写前漂移/计划绑定/读缓存键，非审批令牌）",
+        ],
+    },
+    "environment.fingerprint": {
+        keys: ["environment", "fingerprint", "fingerprintHint"],
+        notes: ["fingerprint 随 env/origin/application/enterprise 变；写前漂移检测 + 计划/审计绑定"],
+    },
+    "get_status": {
+        keys: ["environment", "session", "coverage", "environmentScope", "unsupportedCapabilities?", "writeLease"],
+        notes: ["覆盖率/环境边界/租约用本工具；逐项中文 checks 用 doctor"],
+    },
+    "doctor": {
+        keys: ["checks", "anchor", "unsupportedCapabilities"],
+        notes: ["unsupportedCapabilities.coverageClaimMeaning：只列已知缺口；未列 ≠ 已验证可用"],
+    },
+    "coverage.manifest": {
+        keys: ["manifest:{version_family,anchor_version,items[],counts?,filter?,hint?}"],
+        notes: ["按 lane 索引（同 lane 可多行）；答能力能不能用 → omc capability <id>"],
+    },
+    "apply_changes": {
+        keys: ["status", "steps?", "failedStep?", "progressFile?", "deliveryState?"],
+        notes: ["一次审批 N 变更、首败即停；单条调试用 omc call"],
+    },
+    "data.list": {
+        // items are {id, fields:{<code>: value}} — business columns live under fields.
+        keys: ["items:array<{id,fields:{<code>:value}}>", "total", "totalPages", "page", "size"],
+        // r28i F4: agents try rows[] / items[].sku first; pin the real shape here too.
+        notes: ["业务列在 items[].fields.<code>，不在 item 顶层，也不是 rows[]（--jq items[].sku / rows[].sku 会 miss；正确：items[].fields.sku）"],
+    },
+    "folder.tree": {
+        keys: ["applicationCode", "applicationExists", "nodeCount", "folderCount", "modelCount", "nodes[]", "note"],
+        notes: ["计数是全应用聚合；共享环境请按 code 前缀过滤 nodes[]，不要只比 nodeCount"],
+    },
+    "custompage.get": {
+        keys: ["code", "present", "page", "parentIdNote?", "contentHint?"],
+        notes: ["page.parentId 常为 null（/custom/get 不回 AppFunction 父节点）；看 parentIdNote，落点用 folder.tree 按 code 核对"],
+    },
+    "data.load": {
+        keys: ["bizObjectId", "exists", "data:{...}"],
+    },
+    "model.list": {
+        // Compact diet may rewrite models to "code｜name" pairs and add modelsCount.
+        keys: ["models:array<code｜name>", "count", "modelsCount", "scopeHint"],
+        notes: [
+            "下游工具的 schemaCode = 本面 models 的 code（内联 diet 后是「code｜name」里的 code）",
+            "modelsCount 是内联 result 键；若 --jq 走 artifact 副本可能 pathMiss——用 --jq count 或先看内联 result",
+        ],
+    },
+    "model.inspect": {
+        // Slim/compact face (window diet): field inventory is `fieldCodes`, not fields[].
+        keys: ["schemaCode", "fieldCodes", "form", "listview", "ruleCodes", "datarules", "workflow", "hint"],
+        notes: ["slim 面键是 fieldCodes（不是 fields[].code）"],
+    },
+    "field.list": {
+        keys: ["fields:array<{code,name,type,...}>", "modelPresent?"],
+        notes: ["模型不存在时平台可能 refused(300004)；存在性判据优先 model.inspect.modelPresent / rule.list.modelPresent"],
+    },
+    "workitem.list": {
+        // Flat rows — no fields bag. Wire id is projected as workItemId.
+        keys: ["items:array<{workItemId,activityCode,...}>", "total", "count"],
+        notes: ["待办 id 键是 workItemId，不是 id（平铺，不套 fields）"],
+    },
+    "rule.list": {
+        keys: ["rules:array<{code,name,enabled,status}>", "modelPresent", "source", "executableHint"],
+        notes: [
+            "入参/他面叫 ruleCode，本面返回 rules[].code",
+            "source=published-list：enabled/status 来自 PUBLISH 投影；可执行性看 rule.get / rule.enable.verified",
+            "modelPresent:false 时未发 list（避免幻影 schema 补建 7 条预置）",
+        ],
+    },
+    "datarule.list": {
+        keys: ["rules:array<{id,propertyCode,dataRuleType,checkType,optionsKeys?}>", "rulesCount", "modelPresent", "rulesOmitted?"],
+        notes: [
+            "超阈值时内联 rules 是库存摘要（rulesOmitted:true），完整 options 在 detailArtifactId",
+            "模型不存在 → ok + modelPresent:false + rules:[]（与 rule.list 同口径）",
+        ],
+    },
+    "form.get": {
+        keys: ["present", "published", "publishedControlCodes", "draftControlCodes"],
+        notes: ["控件清单键是 publishedControlCodes/draftControlCodes，不是 controls"],
+    },
+    "listview.get": {
+        keys: ["present", "published", "lifecycle", "columns[]"],
+    },
+    "service.list": {
+        // r28f F1：行内带 adapterCode；顶栏 adapterDistribution 是选型聚合。
+        keys: ["services:array<{code,name,adapterCode}>", "codes", "adapterDistribution", "servicesCount"],
+        notes: ["选型看 adapterDistribution / services[].adapterCode；完整白名单（含 id/category）在 detailArtifactId"],
+    },
+    "method.get": {
+        // r28f F3：单条读面——参数面内联，不是集合读的 omitted 占位。
+        keys: ["serviceCode", "methodCode", "present", "method:{code,name,configJson,inputParameters,outputParameters}"],
+        notes: ["单条读：method.inputParameters/outputParameters/configJson 内联；其余大字段在 detailArtifactId"],
+    },
+    "service.adapter_config": {
+        // r28f F5：顶栏 adapterCodes 摘要；compact:true 只回 code/name/description。
+        keys: ["adapterCodes", "adapters:array<{code,name,config?...}>", "rawPresent"],
+        notes: ["选型先看 adapterCodes；完整 config 默认内联，compact:true 只回 code/name/description"],
+    },
+    "dictionary.list": {
+        keys: ["dictionaries:{totalElements,totalPages,content[]}"],
+    },
+    // r28h：组织读面——层级键/成员 id 是本面的全部价值，别猜成 code｜name。
+    "org.department.list": {
+        keys: ["count", "departments:array<{id,name,code,parentId,corpId?}>"],
+        notes: ["层级看 departments[].parentId（compact 也保形，不会压成 id｜name）"],
+    },
+    "org.role.list": {
+        keys: ["count", "roleCount", "groupCount", "roles:array<{id,name,code,group,groupId,groupCode}>", "groups:array<{id,name,code,parentId?,path,childCount}>"],
+        notes: ["roles[].group 是组名；写角色请用 roles[].groupId / groupCode（或 groups[].id/code）"],
+    },
+    "org.user.search": {
+        keys: ["keyword", "count", "total", "users:array<{id,name,username,departmentId}>", "departmentsScanned?"],
+        notes: ["≤50 人内联 {id,name,username,departmentId}；更大才外置 artifact"],
+    },
+    "org.role.users": {
+        keys: ["roleId", "count", "total", "members:array<{id,name,username,departmentId,scopeCount}>"],
+        notes: ["roleId 与 roleCode 二者其一；members[].id 是用户 recId"],
+    },
+    "org.role.userScope": {
+        keys: ["roleId", "userId", "count", "scopes:array<{id,name,type,deptPath}>"],
+        notes: ["不是枚举档位：scopes 是部门节点列表；roleId 与 roleCode 二者其一"],
+    },
+};
+/** Lookup the authored return shape for a tool, if any. */
+export function readShapeFor(toolName) {
+    return READ_SHAPES[toolName];
+}
+//# sourceMappingURL=read-shapes.js.map