@stalfh233/omc-cli 0.4.101 → 0.5.0

package/dist/bench/discovery-cost-eval.js

@@ -128,6 +128,8 @@ async function runScenario(scenario) {
     };
 }
 export async function runDiscoveryCostBaseline() {
+    // r29（2026-10-29）：describe 重复提示读项目 ledger，组合测试顺序会改变它——测量面禁用保证字节确定性。
+    process.env.OMC_DESC_REPEAT_HINT = "0";
     const scenarios = [];
     for (const scenario of SCENARIOS)
         scenarios.push(await runScenario(scenario));

package/dist/cli.js

@@ -17,8 +17,8 @@ import { cmdModelPurge } from "./model-purge.js";
 import { environmentWritable, requiresProductionConfirmation } from "./environment-policy.js";
 import { CLI_EXIT_CODES, classifyResult, envelope, errorEnvelope, refusalText, requestId } from "./cli-contract.js";
 import { configureOutput, humanSummary, stripOutputFlags, writeEnvelope } from "./cli-output.js";
-import { beginUsage, completeUsage, ensureProjectIgnore, recordUsageOutput, usageReport } from "./usage-log.js";
-import { artifactFetchHint, artifactRoot, boundResult, emitInvalid, emitResult, emitTransportResult, outputBudget, readArtifact, withTransport, } from "./command-transport.js";
+import { beginUsage, completeUsage, currentUsageArgsDigest, ensureProjectIgnore, priorIdenticalSuccess, recordUsageOutput, usageReport } from "./usage-log.js";
+import { artifactFetchHint, artifactRoot, boundResult, emitInvalid, emitResult, emitThrown, emitTransportResult, outputBudget, readArtifact, withTransport, } from "./command-transport.js";
 import { CLI_DEFAULT_OUTPUT_BYTES, assertSafeOutputPath, pruneArtifacts } from "./artifacts.js";
 import { projectJsonPath, projectJsonPathFanout, projectResultExtract } from "./path-projection.js";
 import { basename, join, resolve } from "node:path";
@@ -44,8 +44,11 @@ import { planIntent, readbackIntent, applyIntent, intentWarnings } from "./inten
 import { listSkills, readSkill, readSkillOutline, readSkillSection, searchSkills } from "./skills.js";
 import { parseToolInput, ToolInputError } from "./tool-types.js";
 import { WireError, wireCall } from "./wire.js";
+import { DEFAULT_PULL_CONCURRENCY, GraphIndexAbsentError, GraphPullLockHeldError, MAX_PULL_CONCURRENCY, impactGraph, publishGraphPull, queryGraphReferences, readGraphStatus, searchGraphRules, } from "./graph.js";
 import { ENDPOINTS } from "./endpoints.js";
+import { makeToolContext } from "./context.js";
 import { cmdRollbackList, cmdRollbackPlan, cmdRollbackApply } from "./rollback.js";
+import { SessionManager } from "./session-manager.js";
 async function ask(question) {
     const rl = createInterface({ input: stdin, output: process.stderr });
     try {
@@ -879,8 +882,20 @@ function cmdDiscovery(kind, transport, value, options = {}) {
         // second identical read returns an artifact reference instead of the body.
         result = full ? (repeatFullDescribe(value ?? "", full) ?? full) : full;
     }
-    else
+    else {
         result = describeTool(registry, value ?? "");
+        // r28b 账本（2026-10-28）：describe rule.save×11 / form.publish×9——firstCall 教学后
+        // 仍反复全量 describe。同参数近期已 ok 时附降载提示，引导 --param/--example 精准取。
+        // 无项目 ledger（golden/repo 测试/一次性运行）时 priorIdenticalSuccess 返回
+        // undefined，输出保持 byte-stable。
+        if (result) {
+            const digest = currentUsageArgsDigest();
+            const prior = digest === undefined ? undefined : priorIdenticalSuccess(`describe ${String(value ?? "")}`, digest);
+            if (prior !== undefined && prior.count >= 1)
+                result.describeRepeatHint =
+                    `同参数 describe 近期已执行过 ${prior.count + 1} 次（含本次）。在找单个参数：omc describe ${String(value ?? "")} --param <参数名>（几百字节）；找可抄的完整例子：--example <配方id>；都不必重读整面`;
+        }
+    }
     if (!result) {
         // Name the closest candidates so a near-miss tool name does not cost a
         // guess-and-retry call (round-4 dogfood: `form.create` / `data.create` /
@@ -1029,6 +1044,106 @@ async function cmdIntentReadback(file, environment, transport) {
         return read.code;
     return emitResult(await readbackIntent(read.intent, environment), transport);
 }
+/**
+ * ADR-0008 — `omc graph` family: the local derived rule-graph index. A CLI
+ * management face like `intent`/`rollback`: NOT a call tool, not in the tool
+ * registry or `commands --json`. Results are candidate pointers only — plan /
+ * apply / readback keep reading the live baseline.
+ */
+async function cmdGraphPull(environment, concurrency, transport) {
+    const workers = concurrency ?? DEFAULT_PULL_CONCURRENCY;
+    if (!Number.isSafeInteger(workers) || workers < 1 || workers > MAX_PULL_CONCURRENCY)
+        return emitInvalid(transport, { message: `--concurrency 必须是 1–${MAX_PULL_CONCURRENCY} 的整数（平台负载有界；默认 ${DEFAULT_PULL_CONCURRENCY}）` });
+    const context = makeToolContext({ sessions: new SessionManager(new ConfigStore(defaultPaths())) });
+    try {
+        const session = await context.sessions.session(environment);
+        const data = await publishGraphPull(session, workers);
+        const edgesByKind = {};
+        for (const edge of data.edges)
+            edgesByKind[edge.kind] = (edgesByKind[edge.kind] ?? 0) + 1;
+        const gapsByKind = {};
+        for (const gap of data.gaps)
+            gapsByKind[gap.kind] = (gapsByKind[gap.kind] ?? 0) + 1;
+        return emitResult({
+            status: "ok",
+            environment: data.meta.environmentName,
+            applicationCode: data.meta.applicationCode,
+            identityFingerprint: data.meta.identityFingerprint,
+            pulledAtIso: data.meta.pulledAtIso,
+            scope: data.meta.scope,
+            freshness: data.gaps.length === 0 ? "complete" : "partial",
+            scanned: { models: data.scanned.models, rules: data.scanned.rules, datarules: data.scanned.datarules, views: data.scanned.views, ...(data.scanned.parseFailures > 0 ? { parseFailures: data.scanned.parseFailures } : {}) },
+            edges: edgesByKind,
+            ...(data.gaps.length > 0 ? { gaps: { count: data.gaps.length, byKind: gapsByKind } } : {}),
+            dbBytes: data.dbBytes,
+            timings: data.timings,
+            nextCommand: "omc graph references <kind> <code>",
+        }, transport);
+    }
+    catch (error) {
+        if (error instanceof GraphPullLockHeldError)
+            return emitResult({ status: "refused", blocker: "graph-pull-lock-held", message: error.message, nextCommand: "omc graph status" }, transport);
+        if (error instanceof WireError)
+            return emitResult({ status: "uncertain", reason: "wire-transport", message: `graph pull 中断（${error.message}）；索引未发布，重跑 omc graph pull --env <env>` }, transport);
+        return emitThrown(error, transport);
+    }
+}
+function cmdGraphReferences(kind, code, transport) {
+    if (!["service", "model", "field"].includes(kind))
+        return emitInvalid(transport, { message: "kind 必须是 service / model / field（同 rule.references 第一版边界）" });
+    try {
+        const result = queryGraphReferences(kind, code);
+        return emitResult({
+            status: "ok",
+            kind: result.kind,
+            code: result.code,
+            matches: result.matches,
+            index: result.index,
+            ...(result.note !== undefined ? { note: result.note } : {}),
+            ...(result.gapWarning !== undefined ? { gapWarning: result.gapWarning } : {}),
+        }, transport);
+    }
+    catch (error) {
+        if (error instanceof GraphIndexAbsentError)
+            return emitResult({ status: "refused", blocker: "graph-index-absent", message: error.message, nextCommand: "omc graph pull --env <env>" }, transport);
+        return emitThrown(error, transport);
+    }
+}
+function cmdGraphStatus(transport) {
+    try {
+        const status = readGraphStatus();
+        return emitResult({ status: "ok", index: status.index, dbBytes: status.dbBytes, gaps: status.gaps }, transport);
+    }
+    catch (error) {
+        if (error instanceof GraphIndexAbsentError)
+            return emitResult({ status: "refused", blocker: "graph-index-absent", message: error.message, nextCommand: "omc graph pull --env <env>" }, transport);
+        return emitThrown(error, transport);
+    }
+}
+function cmdGraphImpact(kind, code, transport) {
+    if (!["service", "model", "field"].includes(kind))
+        return emitInvalid(transport, { message: "kind 必须是 service / model / field（同 rule.references 第一版边界）" });
+    try {
+        const result = impactGraph(kind, code);
+        return emitResult({ status: "ok", ...result }, transport);
+    }
+    catch (error) {
+        if (error instanceof GraphIndexAbsentError)
+            return emitResult({ status: "refused", blocker: "graph-index-absent", message: error.message, nextCommand: "omc graph pull --env <env>" }, transport);
+        return emitThrown(error, transport);
+    }
+}
+function cmdGraphSearch(term, transport) {
+    try {
+        const result = searchGraphRules(term);
+        return emitResult({ status: "ok", ...result }, transport);
+    }
+    catch (error) {
+        if (error instanceof GraphIndexAbsentError)
+            return emitResult({ status: "refused", blocker: "graph-index-absent", message: error.message, nextCommand: "omc graph pull --env <env>" }, transport);
+        return emitThrown(error, transport);
+    }
+}
 /** Ticket 119 — `omc intent apply <plan-file>`: plan integrity + baseline drift gates, then serial execution through the EXISTING apply_changes machinery. */
 async function cmdIntentApply(planPath, options, transport) {
     return applyIntent(planPath, options, {
@@ -1508,7 +1623,7 @@ async function main() {
         .option("--schema <schemaCode>", "模型 code")
         .option("--schema-code <schemaCode>")
         .option("--rule-code <ruleCode>")
-        .option("--name <name>")
+        .option("--name <name>", "规则显示名（rule.save 的 name 位；与既有规则同名则覆盖更新）")
         .option("--node-graph <json>", "规则图 {nodes,routes} JSON")
         .option("--publish", "保存后同时发布规则版本")
         .option("--env <environment>")
@@ -1714,6 +1829,25 @@ async function main() {
     intentCommand.command("readback <file>").option("--env <environment>").option("--max-output-bytes <bytes>").action(async (file, options) => {
         commandExitCode = await withTransport(options, request, (transport) => cmdIntentReadback(file, options.env, transport));
     });
+    // ADR-0008: local derived rule-graph index — CLI management face, not a call
+    // tool (so it stays out of `commands --json`/coverage by construction).
+    const graphCommand = command.command("graph").description("本地派生规则图索引（ADR-0008）：pull 全量重建（有界并发）/ references 离线引用 / impact 影响面 / search 规则全文 / status 完整性与新鲜度。候选定位器——不进 baseline/plan/写门禁");
+    graphCommand.command("pull").option("--env <environment>").option("--environment <environment>").option("--concurrency <n>", "并发 wire 读数（1–32，默认 16）：拉取已流水线化，墙钟 ≈ max(模型面,规则面)/并发 × 延迟；过高可能触发平台限流形成缺口").option("--max-output-bytes <bytes>").addHelpText("after", "\n只读远端（model.list → 每模型 rule.list+datarule.list → 每规则 rule.get，统一任务池流水线并发）+ 本地原子重建；不写环境、不占环境写锁。新鲜度随结果回报（complete|partial），查询走 graph references / impact / search。\n").action(async (options) => {
+        const parsed = options.concurrency === undefined ? undefined : Number.parseInt(String(options.concurrency), 10);
+        commandExitCode = await withTransport(options, request, (transport) => cmdGraphPull(options.environment ?? options.env, parsed, transport));
+    });
+    graphCommand.command("references <kind> <code>").option("--max-output-bytes <bytes>").addHelpText("after", "\n离线查询（零 wire）：kind = service|model|field，语义同 rule.references 第一版边界；结果带索引新鲜度与扫描缺口（有缺口时零命中不构成「无引用」证明）。\n").action(async (kind, code, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdGraphReferences(kind, code, transport));
+    });
+    graphCommand.command("impact <kind> <code>").option("--max-output-bytes <bytes>").addHelpText("after", "\n影响面（离线）：跳1=引用该编码的规则（同 references），跳2=这些规则还读写哪些 service/model/field——改前看爆炸半径。截断上限 50 规则×每类 20 码。\n").action(async (kind, code, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdGraphImpact(kind, code, transport));
+    });
+    graphCommand.command("search <term...>").option("--max-output-bytes <bytes>").addHelpText("after", "\n规则全文检索（code+name，FTS5，末词前缀匹配）：找到\"关于 X 的规则\"拿 code，再走 references/impact。中文需给全词或词首（如 报名*）。\n").action(async (term, options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdGraphSearch(term.join(" "), transport));
+    });
+    graphCommand.command("status").option("--max-output-bytes <bytes>").action(async (options) => {
+        commandExitCode = await withTransport(options, request, (transport) => cmdGraphStatus(transport));
+    });
     // `--jq` expressions the shell split arrive as several tokens; re-join them.
     await command.parseAsync(joinSplitFlagValues(stripOutputFlags(argv), ["--jq"]));
     return commandExitCode;
@@ -1742,7 +1876,7 @@ main().then((code) => {
     // envelope (or, for `env --json`, their own JSON) and were printing a second
     // empty envelope after it (live 2026-10-23: `omc rollback apply` answered two
     // lines, violating the one-envelope stdout contract).
-    const ownsStdout = ["call", "script", "artifact", "commands", "describe", "contract", "capabilities", "capability", "next", "usage", "intent", "help", "form-default", "compute", "rule-when", "approval-flow", "model-scaffold", "model-purge", "rollback", "env", "--version", "-V"];
+    const ownsStdout = ["call", "script", "artifact", "commands", "describe", "contract", "capabilities", "capability", "next", "usage", "intent", "help", "form-default", "compute", "rule-when", "approval-flow", "model-scaffold", "model-purge", "rollback", "env", "graph", "--version", "-V"];
     if (ownsStdout.includes(argv[2] ?? "")) {
         completeUsage(code);
         finish(code);

package/dist/compound-writes.js

@@ -225,18 +225,25 @@ export async function runRuleSaveEnable(options) {
  *    droppedNodes 列明。
  * 两种路径都不依赖平台的合并/整替行为：最终模板由本命令显式合成。
  */
+/**
+ * 节点码/类型的读取兼容真机与 fake 两种投影（r22 2026-10-27 真机实证：
+ * workflow.get_draft 真机节点形如 {"index":0,"code":"Activity1","type":"START"}，
+ * 而本命令原读法 activityCode/activityType 恒空 → preservedNodes 恒空）。
+ */
+const activityCodeOf = (activity) => String(activity.activityCode ?? activity.code ?? "");
+const activityTypeOf = (activity) => String(activity.activityType ?? activity.type ?? "").toUpperCase();
 function composeFinalTemplate(draftActivities, template, confirmReplace) {
-    const newCodes = new Set((template.activities ?? []).map((activity) => String(activity.activityCode ?? "")));
+    const newCodes = new Set((template.activities ?? []).map((activity) => activityCodeOf(activity)));
     const oldNodes = draftActivities.filter((activity) => {
-        const code = String(activity.activityCode ?? "");
+        const code = activityCodeOf(activity);
         return code !== "" && !newCodes.has(code);
     });
-    const oldCodes = oldNodes.map((activity) => String(activity.activityCode ?? ""));
+    const oldCodes = oldNodes.map((activity) => activityCodeOf(activity));
     if (confirmReplace || oldCodes.length === 0) {
         return { finalTemplate: template, preservedNodes: [], droppedNodes: confirmReplace ? oldCodes : [] };
     }
     const activities = template.activities ?? [];
-    const endIndex = activities.findIndex((activity) => String(activity.activityType ?? "").toUpperCase() === "END");
+    const endIndex = activities.findIndex((activity) => activityTypeOf(activity) === "END");
     const merged = endIndex >= 0
         ? [...activities.slice(0, endIndex), ...oldNodes, ...activities.slice(endIndex)]
         : [...activities, ...oldNodes];
@@ -251,7 +258,11 @@ export async function runWorkflowUpdatePublish(options) {
     }
     const draft = options.apply ? await invoke("workflow.get_draft", { schemaCode: options.schema, ...(options.code ? { code: options.code } : {}) }) : { status: "ok", data: null };
     const draftData = (draft.data ?? null);
-    const draftActivities = (draftData?.activities ?? draftData?.template?.activities ?? []);
+    // r22 真机实证：真机投影在 workflowSummary.activities；fake 在 activities/template.activities——三口径全兼容。
+    const draftActivities = (draftData?.workflowSummary?.activities
+        ?? draftData?.activities
+        ?? draftData?.template?.activities
+        ?? []);
     const { finalTemplate, preservedNodes, droppedNodes } = composeFinalTemplate(draftActivities, options.template, options.confirmReplace === true);
     if (!options.apply) {
         emit({

package/dist/field-change.js

@@ -2,6 +2,7 @@ import { FIELD_PROPERTY_TYPES } from "./field-families.js";
 import { assertFormConditions, assertNumericalScale, assertFieldOptionsAllowed, buildChildTableSubSchema, buildFieldOptions, ensureRelationDisplayFieldOptions, normalizeFieldPropertyType, relationDisplayFieldCode, } from "./field-families.js";
 import { nameI18nJson } from "./field-families.js";
 import { decodeJsonObjectColumn } from "./json-column.js";
+import { normalizeFormConditionOptions } from "./lanes/datarule-protocol.js";
 import { ToolRefusalError } from "./tool-types.js";
 /**
  * Fail-closed relation-target gate (round17 dogfood R3). A relation field whose
@@ -75,6 +76,10 @@ export function fieldChangeWireBody(input, prepared) {
     };
 }
 export function prepareFieldUpdate(input) {
+    // r26 快速装载：符号式/裸值条件就地编译为平台中文规范形状（合规式零改写）。
+    const normalizedOptions = input.options === undefined ? undefined : normalizeFormConditionOptions(input.options);
+    const effectiveOptions = normalizedOptions?.options;
+    const conditionCompiled = normalizedOptions?.compiledNotes ?? [];
     const recordType = Number(input.base.type ?? input.base.propertyType);
     const isChildTable = recordType === FIELD_PROPERTY_TYPES.CHILD_TABLE;
     if (isChildTable && (input.options !== undefined || input.choices !== undefined || input.subFields !== undefined))
@@ -86,17 +91,33 @@ export function prepareFieldUpdate(input) {
             message: `子表字段 ${input.schemaCode}.${input.code} 不接受 options/choices/subFields。子表列就是 schemaCode=${input.code} 上的普通字段：增列用 field.create --args '{"schemaCode":"${input.code}","code":"<子列>",...}'，改列/删列用 field.update/field.delete（同 schemaCode），改完对父模型 field.publish 即发布`,
         });
     const currentOptions = decodeJsonObjectColumn(input.base.options, { invalid: "throw", array: "accept", object: "accept" }) ?? {};
-    const nextOptions = isChildTable
+    const rebuiltOptions = isChildTable
         ? currentOptions
         : ensureRelationDisplayFieldOptions(recordType, {
             ...currentOptions,
             ...buildFieldOptions({
                 propertyType: recordType,
                 ...(input.choices ? { choices: input.choices } : {}),
-                ...(input.options ? { options: input.options } : {}),
+                ...(effectiveOptions ? { options: effectiveOptions } : {}),
             }),
         });
-    if (!isChildTable && !input.options && !input.choices)
+    // 2026-10-29 防御（治豪 issue 的 optionsSet 覆盖风险）：带 choices 更新选项族时
+    // optionsSet 走保留式合并——以服务端原文 optionsSet 为基线，只换 custom 条目，
+    // optionStructure/treeSelect/businessModel 等未声明键（含跨版本导入态）一律继承，
+    // 不整体重建。锚定线（8.6/1.1.25）实测无此形状，纯防御。
+    const nextOptions = isChildTable
+        ? currentOptions
+        : input.choices !== undefined
+            && rebuiltOptions.optionsSet !== undefined
+            && currentOptions.optionsSet !== undefined
+            && currentOptions.optionsSet !== null
+            && typeof currentOptions.optionsSet === "object"
+            ? {
+                ...rebuiltOptions,
+                optionsSet: { ...currentOptions.optionsSet, ...rebuiltOptions.optionsSet },
+            }
+            : rebuiltOptions;
+    if (!isChildTable && !effectiveOptions && !input.choices)
         Object.assign(nextOptions, currentOptions);
     if (!isChildTable) {
         // An update that touches a relation's options must keep a resolvable target:
@@ -104,10 +125,10 @@ export function prepareFieldUpdate(input) {
         // field.publish cannot later 300010 on this field.
         assertRelationTargetPresent(recordType, nextOptions, input.relativeCode ?? (typeof input.base.relativeCode === "string" ? input.base.relativeCode : undefined), input.code);
         assertFieldOptionsAllowed(recordType, nextOptions, input.schemaCode);
-        if (input.options !== undefined || input.choices !== undefined)
+        if (effectiveOptions !== undefined || input.choices !== undefined)
             assertNumericalScale(recordType, nextOptions);
-        if (input.options !== undefined)
-            assertFormConditions(input.options);
+        if (effectiveOptions !== undefined)
+            assertFormConditions(effectiveOptions);
     }
     // Ticket 61: an explicit displayField wins; otherwise preserve the stored
     // top-level relativePropertyCode (the runtime reads it, not options).
@@ -119,7 +140,7 @@ export function prepareFieldUpdate(input) {
         : input.name !== undefined
             ? nameI18nJson(input.name)
             : (typeof input.base.name_i18n === "string" ? input.base.name_i18n : undefined);
-    return { propertyType: recordType, isChildTable, options: nextOptions, ...(displayCode !== undefined ? { displayCode } : {}), ...(name !== undefined ? { name } : {}), ...(nameI18n !== undefined ? { nameI18n } : {}) };
+    return { propertyType: recordType, isChildTable, options: nextOptions, ...(conditionCompiled.length > 0 ? { conditionCompiled } : {}), ...(displayCode !== undefined ? { displayCode } : {}), ...(name !== undefined ? { name } : {}), ...(nameI18n !== undefined ? { nameI18n } : {}) };
 }
 /** The single field-update wire body: the stored row spread with changed keys. */
 export function fieldUpdateWireBody(input, prepared) {

package/dist/field-families.js

@@ -167,7 +167,7 @@ export const fieldOptionsArg = z
     schemaCode: z.string().optional().describe("relation target model code (WORK_SHEET / MULT_WORK_SHEET)"),
     queryCode: z.string().optional().describe("relation query code (usually the target model code)"),
     displayField: z.string().optional().describe("relation display field (usually 'name')"),
-    mappings: z.string().optional().describe('relation carry mappings, e.g. [{"source":"<target field code>","target":"<this-model field code>"}]'),
+    mappings: z.union([z.string(), z.array(z.object({ source: z.string(), target: z.string() }))]).optional().describe('relation carry mappings——数组 [{"source":"<target field code>","target":"<this-model field code>"}] 或等价 JSON 字符串均可，CLI 就地归一（空数组/"[]" → 无映射）'),
     searchFormula: jsonString().optional().describe("WORK_SHEET / MULT_WORK_SHEET data restriction range JSON"),
     conditions: jsonString().optional().describe("WORK_SHEET / MULT_WORK_SHEET query conditions JSON"),
     optionsSet: optionsSetArg.optional().describe("selection source: custom, dictionary, or businessModel"),
@@ -495,6 +495,64 @@ function normalizeBusinessModelCondition(businessModel) {
     if (parts.length > 0)
         businessModel.condition = parts.join("&&");
 }
+/**
+ * r26 快速装载（2026-10-28）：关联带出 mappings 的就地归一。agent 最自然的
+ * 写法是数组 `mappings:[{source:"contract_name",target:"contract_name"}]`——
+ * 此前静默失效（wire 成数组形态，平台只认 JSON 字符串），必须照 describe
+ * 拼字符串（r24/r26 各 ~15 轮试错的来源之一）。归一规则：
+ *  - 数组：空数组 → `""`（无映射规范形态，规避 `"[]"` 假"已设置"坑）；
+ *    非空逐项必须是 `{source,target}` 非空字符串 → 紧凑 JSON 字符串
+ *  - 字符串：`"[]"` → `""`；可 JSON.parse 的必须解析为 `[{source,target}]`
+ *    形状（坏结构教学拒绝）；parse 失败按原样拒绝
+ *  - 其它类型拒绝教学
+ */
+export function normalizeMappingsOption(options) {
+    if (!("mappings" in options) || options.mappings === undefined)
+        return { options };
+    const mappings = options.mappings;
+    const mappingsError = (detail) => refuseFieldOptions(`relation mappings fail the reproduced protocol`, `rejected: options.mappings ${detail}；合法形状：JSON 字符串 [{"source":"<来源字段>","target":"<目标字段>"}] 或等价数组；无映射用 ""（不是 "[]"——"[]" 会让设计器显示"已设置"但弹窗无映射行）`);
+    let normalized;
+    if (Array.isArray(mappings)) {
+        if (mappings.length === 0)
+            normalized = "";
+        else {
+            const rows = mappings.map((row) => {
+                if (row === null || typeof row !== "object" || Array.isArray(row))
+                    mappingsError("数组每项必须是 {source,target} 对象");
+                const record = row;
+                const source = record.source;
+                const target = record.target;
+                if (typeof source !== "string" || source.trim() === "" || typeof target !== "string" || target.trim() === "")
+                    mappingsError("每项的 source/target 必须是非空字符串");
+                return { source: source.trim(), target: target.trim() };
+            });
+            normalized = JSON.stringify(rows);
+        }
+    }
+    else if (typeof mappings === "string") {
+        const trimmed = mappings.trim();
+        if (trimmed === "" || trimmed === "[]")
+            normalized = "";
+        else {
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch {
+                mappingsError(`字符串必须可解析为 JSON 数组（收到：${trimmed.slice(0, 40)}…）`);
+            }
+            if (!Array.isArray(parsed) || parsed.some((row) => row === null || typeof row !== "object" || Array.isArray(row) || typeof row.source !== "string" || typeof row.target !== "string" || row.source === "" || row.target === ""))
+                mappingsError("解析结果必须是 [{source,target}] 形状（source/target 非空字符串）");
+            normalized = JSON.stringify(parsed.map(({ source, target }) => ({ source: source.trim(), target: target.trim() })));
+        }
+    }
+    else
+        mappingsError(`必须是 JSON 字符串或数组（收到 ${typeof mappings}）`);
+    const next = { ...options, mappings: normalized };
+    // note 只在「形态」变化（数组→字符串 / "[]"→""）时给；纯 trim 不算。
+    const shapeChanged = Array.isArray(mappings) || (typeof mappings === "string" && mappings.trim() === "[]");
+    return { options: next, ...(shapeChanged ? { note: `options.mappings 已归一为平台字符串形态：${normalized === "" ? "空串（无映射）" : String(normalized)}` } : {}) };
+}
 export function buildFieldOptions(args) {
     const explicit = args.options;
     const raw = args.propertyType;
@@ -513,7 +571,7 @@ export function buildFieldOptions(args) {
                 refuseFieldOptions("selection field options carry no optionsSet source", `rejected: ${choiceError}`);
         }
         normalizeBusinessModelOrderBy(explicit);
-        return explicit;
+        return normalizeMappingsOption(explicit).options;
     }
     const choices = args.choices;
     if (Array.isArray(choices) && choices.length > 0) {

package/dist/goal-routes.js

@@ -561,6 +561,43 @@ export function goalRoute(registry, goal) {
     // 对控件条件必拒；唯一路径是表单 attributes（form.get 读 draftAttributesJson
     // 定位控件 → form.draft 改 → form.publish）。此前该场景路由进 field→form 梯子
     // 且首级无可行工具（firstCommands 为空），agent 只能靠拒收文案自己悟。
+    // r27 探针（2026-10-28）：普通字段的条件必填/显隐/只读——「为字段配置条件必填…规则」
+    // 这类措辞被判成 read-ladder（"要查看哪个对象？"），agent 被迫自行探索并先撞
+    // datarule.create（配方明令禁止的路线）再折回 field.update，单意图浪费约 15 次调用。
+    // 触发词面：条件必填/必填条件/条件显隐/显示条件/隐藏条件/条件只读/只读条件 +
+    // 配置/设置/改成/修改/加上 等写动词，或直接点名 requiredFormula/displayFormula/
+    // readonlyCondition。不提「子表/控件」（那是上一条表单 attributes 的专项路由）。
+    if (!/子表/.test(goal)
+        && !/查看|有哪些|是什么|怎么|列出|看看|查询|检查|确认/.test(goal)
+        && (/条件必填|必填条件|条件显隐|显隐条件|显示条件|条件显示|隐藏条件|条件隐藏|条件只读|只读条件|requiredFormula|displayFormula|readonlyCondition/.test(goal))
+        && /配置|设置|改成|修改|加上|加一个|做个|做一|变必填|控制|当.*时/.test(goal)) {
+        return {
+            status: "ok",
+            goal,
+            confident: true,
+            mode: "modify",
+            write: true,
+            match: { kind: "recipe", ref: "form-conditional-required", title: "字段层条件必填/显隐/只读（field.update options 面）" },
+            route: {
+                capability: "field",
+                lane: "field-families",
+                note: "普通字段的条件必填（requiredFormula）/条件显隐（displayFormula）/条件只读（readonlyCondition）都在字段 options 面：field.update 写入即自动配对 bizdatarule 3/4/5 行（回执 formConditionSync）。表达式可用自然符号式（{字段} = \"值\" / {字段} >= 5000 / {字段} 不为空），CLI 就地编译为平台中文形状。**不要用 datarule.create**——type4 不让门户控件变必填（实测）。",
+                readiness: DISCOVERY_AUTHORITY.readiness,
+                firstCommands: [
+                    "omc describe field.update --example form-conditional-required",
+                    "omc call field.list --args '{\"schemaCode\":\"<schemaCode\",\"full\":true}'",
+                ],
+                write: true,
+            },
+            firstAnswer: {
+                state: "needs-input",
+                question: "目标模型 schemaCode 与字段 code 是什么？（给我 schemaCode 或业务名，我列清单核对）",
+                action: LIST_MODELS_ACTION,
+                pendingCommand: "omc call field.update --args '{\"schemaCode\":\"<schemaCode>\",\"code\":\"<字段code>\",\"options\":{\"requiredFormula\":\"{触发字段} 等于 某值\"}}'",
+                why: "命中字段层条件三件套路由：field.update 的 options.requiredFormula/displayFormula/readonlyCondition（表达式支持符号式就地编译）",
+            },
+        };
+    }
     if (/子表|控件/.test(goal) && /子表.*(显示|隐藏|只读|显隐).*(条件|公式|规则)|displayFormula|readonlyFormula/.test(goal)) {
         return {
             status: "ok",