@stalfh233/omc-cli 0.6.17 → 0.6.19

package/dist/batch-call.js

@@ -46,7 +46,12 @@ function failureDetails(entry, args) {
     }
     return { hint: "平台回了无明细 50000，常见成因见 help omc-refusals；请用该行输入与已发布字段逐项核对" };
 }
-export function batchWarnings(argsList) {
+export function batchWarnings(argsList, tool) {
+    // Runtime data validation belongs to the runtime-data lane, which has the
+    // published field metadata.  The old generic `code` requirement fabricated
+    // ghost warnings for data.save (models commonly have no code field).
+    if (tool === "data.save")
+        return [];
     const warnings = [];
     const seenCodes = new Map();
     argsList.forEach((args, index) => {
@@ -143,6 +148,11 @@ export async function runBatchCall(options) {
                 ? String(readback.authoritative.id)
                 : undefined;
         const skippedMarker = performed?.skipped;
+        const applicationCode = typeof performed?.applicationCode === "string"
+            ? String(performed.applicationCode)
+            : typeof entry.result.readback?.applicationCode === "string"
+                ? String(entry.result.readback.applicationCode)
+                : undefined;
         return {
             index: entry.index,
             row: entry.index + 1,
@@ -150,12 +160,20 @@ export async function runBatchCall(options) {
             ok: entry.status === "ok",
             ...inputBusinessKey(options.argsList[entry.index] ?? {}),
             ...(bizObjectId !== undefined ? { bizObjectId } : {}),
+            ...(applicationCode !== undefined ? { applicationCode } : {}),
             ...(entry.status === "ok" ? {} : { status: String(entry.result.status ?? "failed"), blocker: entry.result.blocker ?? null }),
             ...(skippedMarker !== undefined ? { skipped: String(skippedMarker) } : {}),
         };
     });
     const entriesInline = entriesSummary.slice(0, ENTRIES_INLINE_LIMIT);
-    const warnings = batchWarnings(options.argsList);
+    const laneWarnings = entries.flatMap((entry) => {
+        const warnings = entry.result.readback?.warnings;
+        return Array.isArray(warnings)
+            ? warnings.map((warning) => ({ ...warning, row: entry.index + 1 }))
+            : [];
+    });
+    const warnings = options.tool === "data.save" ? laneWarnings : batchWarnings(options.argsList, options.tool);
+    const applicationCode = entries.map((entry) => entry.result.performed?.applicationCode).find((value) => typeof value === "string");
     const warningsInline = warnings.slice(0, ENTRIES_INLINE_LIMIT);
     const detailOmitted = entriesSummary.length > entriesInline.length || warnings.length > warningsInline.length;
     const detailArtifact = detailOmitted
@@ -170,6 +188,7 @@ export async function runBatchCall(options) {
             executed,
             succeeded,
             failed,
+            ...(applicationCode !== undefined ? { applicationCode } : {}),
             ...(skipped > 0 ? { notExecuted: skipped } : {}),
             // 每条一行摘要（index/ok/bizObjectId）——不是完整信封，但足以回答
             // 「第 3 条建成了吗、它的 id 是什么」。失败项另有 failures 带完整原因。

package/dist/cli-stdout.js

@@ -34,6 +34,7 @@ export const CLI_STDOUT_OWNERS = {
     intent: "envelope",
     help: "envelope",
     graph: "envelope",
+    residue: "envelope",
     programming: "envelope",
     rollback: "envelope",
     setup: "envelope",

package/dist/cli.js

@@ -57,6 +57,7 @@ import { listSkills, readSkill, readSkillOutline, readSkillSection, searchSkills
 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 { cmdResidue } from "./residue.js";
 import { ENDPOINTS } from "./endpoints.js";
 import { makeToolContext } from "./context.js";
 import { cmdRollbackList, cmdRollbackPlan, cmdRollbackApply } from "./rollback.js";
@@ -368,7 +369,7 @@ function parseDoctorStep(line) {
 function doctorAnchor() {
     const topics = listSkills().map((entry) => entry.name).join("、");
     return [
-        "最小路径  omc next \"<目标>\"（目标→工具一步定位，不确定会明说）→ omc help omc-start-here → omc call discover_environment --env <env> --args '{}'（<env> 名以 doctor 的「环境=」或项目 .omc-env 为准，勿猜）→ omc capabilities / omc describe <tool>",
+        "最小路径  omc next \"<目标>\"（目标→工具一步定位，不确定会明说）→ omc help omc-start-here → omc call discover_environment --env <env> --args '{}'（<env> 名以 doctor 的「环境=」或项目 .omc-env 为准，勿猜；项目环境白名单按 cwd 解析，须在含 .omc-env 的目录内运行）→ omc capabilities / omc describe <tool>",
         `方法论    omc help <topic>（或 --topic <name>）--sections / --section "<标题>"（按节读，随包 skills/）；topic：${topics}`,
         "大输出    超预算结果只回 artifactId/sha256/fetch；用 fetch 里的 omc artifact get <id>（可加 --jq <path>）取回，勿全量读入",
         // r29f F9：只读面不碰远端，但仍会本地落盘——写清，避免「零写入」核对误判。
@@ -534,7 +535,7 @@ async function cmdCall(store, args) {
                 return emitTransportResult({ status: "ok", ...described, helpNote: "来自 omc describe；完整面用 omc describe <tool> [--full|--param|--example]" }, { request, maxOutputBytes });
             }
         }
-        console.error("用法：omc call <tool> [--env <环境>] [--args '<json>' | --args - (stdin) | --args-file <配置根内路径（必须位于配置根内；跨目录临时文件用 --args -（stdin））>] [--extract <path>]... [--jq [path]] [--extract-keys] [--args-list <json数组> [--preflight]]");
+        console.error("用法：omc call <tool> [--env <环境>] [--args '<json>' | --args - (stdin) | --args-file <配置根内路径（必须位于配置根内；数组批量请改用 --args-list；跨目录临时文件用 --args -（stdin））>] [--extract <path>]... [--jq [path]] [--extract-keys] [--args-list <json数组>（最多 200 条；超出请分批或用 omc script 读文件） [--preflight]]");
         console.error("输出预算：--max-output-bytes 默认 65536（只约束最终 stdout 信封；读面 diet ~2048 独立外置 detailArtifactId）；artifact get 内联上限 8192");
         console.error("写入：由环境 writable 决定（只读环境拒写）；生产环境的写必须在 args 里带 confirmProduction:true。");
         return emit(toolName && toolName !== "help" ? "error" : "ok", {}, toolName && toolName !== "help" ? CLI_EXIT_CODES.invalidInput : 0);
@@ -632,18 +633,20 @@ async function cmdCall(store, args) {
         // 原来只在末尾附一句「若问题在引号转义…」，容易被当成补充说明；这里把它
         // 提成主建议，并给出 PS 可粘贴的两条命令。
         const looksLikeShellSplitting = /Unexpected (token|end of JSON)|Expected property name|position \d+/i.test(detail);
-        const message = outOfRoot
-            ? `--args-file 越界：${detail}。可执行做法：把参数文件放到 ${configRoot} 之下（如 ${join(configRoot, "args.json")}），再用 --args-file 引用；不要把参数文件放在系统临时目录（配置根之外一律拒绝）`
-            : looksLikeShellSplitting
-                ? `--args 不像合法 JSON（${detail}）——这个形态通常是 shell 把内联 JSON 拆坏了（Windows PowerShell 的引号/转义规则），不是你写错了字段。改法二选一：① 把 JSON 写进 ${join(configRoot, "args.json")} 再用 --args-file；② \`omc call <tool> --args - \` 从 stdin 读（PS: \`'{"k":"v"}' | omc call <tool> --args -\`）。POSIX 文档里的单引号写法不能照抄到 PS`
-                : `--args 必须是合法 JSON：${detail}。若问题在引号转义（Windows PowerShell），改用 --args-file <配置根内的路径> 或 --args -（stdin）`;
+        const message = argsFile !== undefined && /must be a JSON object/.test(detail)
+            ? `${detail}；--args-file 只收单个 JSON 对象，批量数组请改用 --args-list（最多 200 条，可分批执行）`
+            : outOfRoot
+                ? `--args-file 越界：${detail}。可执行做法：把参数文件放到 ${configRoot} 之下（如 ${join(configRoot, "args.json")}），再用 --args-file 引用；不要把参数文件放在系统临时目录（配置根之外一律拒绝）`
+                : looksLikeShellSplitting
+                    ? `--args 不像合法 JSON（${detail}）——这个形态通常是 shell 把内联 JSON 拆坏了（Windows PowerShell 的引号/转义规则），不是你写错了字段。改法二选一：① 把 JSON 写进 ${join(configRoot, "args.json")} 再用 --args-file；② \`omc call <tool> --args - \` 从 stdin 读（PS: \`'{"k":"v"}' | omc call <tool> --args -\`）。POSIX 文档里的单引号写法不能照抄到 PS`
+                    : `--args 必须是合法 JSON：${detail}。若问题在引号转义（Windows PowerShell），改用 --args-file <配置根内的路径> 或 --args -（stdin）`;
         console.error(message);
         // The MACHINE envelope must carry the same actionable text: agents read
         // stdout, and the old envelope only repeated the English detail.
         // Keep the REJECTED path on stderr only: the machine envelope must not leak
         // host layout (ticket 103), so it carries the root plus the bare file name.
         const rejectedName = typeof argsFile === "string" ? basename(resolve(configRoot, argsFile)) : "";
-        writeEnvelope(envelope("error", {}, request, { code: "invalid-input", message: outOfRoot ? `--args-file 必须位于配置根内（配置根 ${configRoot}${rejectedName ? `；本次文件 ${rejectedName}` : ""}）。免落盘替代：--args - 从 stdin 读 JSON（echo '<json>' | omc call <tool> --args -），或把文件放进配置根后再引用；限制是为了防参数文件携带凭据被收进会话产物` : detail, retryable: false, ...(outOfRoot ? { configurationRoot: configRoot } : {}) }));
+        writeEnvelope(envelope("error", {}, request, { code: "invalid-input", message: outOfRoot ? `--args-file 必须位于配置根内（配置根 ${configRoot}${rejectedName ? `；本次文件 ${rejectedName}` : ""}）。免落盘替代：--args - 从 stdin 读 JSON（echo '<json>' | omc call <tool> --args -），或把文件放进配置根后再引用；限制是为了防参数文件携带凭据被收进会话产物` : argsFile !== undefined && /must be a JSON object/.test(detail) ? `${detail}；批量数组请改用 --args-list（最多 200 条，可分批执行）` : detail, retryable: false, ...(outOfRoot ? { configurationRoot: configRoot } : {}) }));
         return CLI_EXIT_CODES.invalidInput;
     }
     const registry = buildToolRegistry();
@@ -984,7 +987,6 @@ async function cmdArtifactGet(id, transport, options = {}) {
                         ...artifactProjectionMetadata(content),
                         keys,
                         path: options.jq,
-                        content: projected.content ?? null,
                         projections: [{ path: options.jq, content: projected.content ?? null, ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}) }],
                         ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}),
                         ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}),
@@ -1036,7 +1038,7 @@ async function cmdArtifactGet(id, transport, options = {}) {
             const projected = projectArtifactPath(artifactContent, options.jq);
             return emitTransportResult(projected.missed
                 ? { status: "ok", artifactId: id, sha256: artifact.sha256, ...artifactProjectionMetadata(content), path: options.jq, content: null, pathMiss: true, missedAt: projected.at, available: projected.available, unanswered: true, hint: artifactPathMissHint(projected.at) }
-                : { status: "ok", artifactId: id, sha256: artifact.sha256, ...artifactProjectionMetadata(content), path: options.jq, content: projected.content ?? null, projections: [{ path: options.jq, content: projected.content ?? null, ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}) }], ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}), ...(artifactNullHint(projected.content, projected.nullEntries) !== undefined ? { hint: artifactNullHint(projected.content, projected.nullEntries) } : {}) }, transport);
+                : { status: "ok", artifactId: id, sha256: artifact.sha256, ...artifactProjectionMetadata(content), path: options.jq, projections: [{ path: options.jq, content: projected.content ?? null, ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}) }], ...(projected.mapped !== undefined ? { mapped: projected.mapped } : {}), ...(projected.missedEntries !== undefined ? { missedEntries: projected.missedEntries } : {}), ...(projected.nullEntries !== undefined && projected.nullEntries > 0 ? { nullEntries: projected.nullEntries } : {}), ...(artifactNullHint(projected.content, projected.nullEntries) !== undefined ? { hint: artifactNullHint(projected.content, projected.nullEntries) } : {}) }, transport);
         }
         // r6-onboarding 2026-10-21: 47 artifact fetches, 0 used a projection; the 10
         // large ones (up to 55 KB) pulled whole workflow templates just to read one
@@ -1624,6 +1626,7 @@ async function cmdGraphPull(environment, concurrency, transport) {
             identityFingerprint: data.meta.identityFingerprint,
             pulledAtIso: data.meta.pulledAtIso,
             scope: data.meta.scope,
+            coverage: { applicationCodes: [data.meta.applicationCode] },
             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,
@@ -2162,7 +2165,7 @@ async function main() {
         commandExitCode = CLI_EXIT_CODES.ok;
     });
     command.command("doctor").option("--environment <environment>").option("--env <environment>").option("--service <serviceCode>", "可选：体检单个业务集成服务的鉴权参数形状（掩码/占位/全 0 检出，WARN 非致命）").action(async (options) => { commandExitCode = await cmdDoctor(new ConfigStore(defaultPaths()), options.environment ?? options.env, options.service); });
-    command.command("call <tool>").option("--env <environment>").option("--environment <environment>").option("--args <json>").option("--args-file <path>", "从文件读参数 JSON。**必须位于配置根内**（跨目录/系统临时文件会被拒）；免落盘用 `--args -`（stdin）").option("--args-list <json-array>", '同一工具跑 N 次（JSON 数组，每条一个 args 对象）；逐条执行、默认不中断，最后回 succeeded/failed 汇总。适合批量建字段等').option("--preflight", "与 --args-list 一起用：只跑参数校验 + 写前语义闸（零 wire、零写入），一次报全所有形状问题").option("--keys", "与 artifact get 的 --keys 同义（= --extract-keys）：列出本次结果 artifact 的顶层键与体积").addOption(new Option("--extract <path>", "在本次结果的 artifact 内取一个路径的值（可重复；省掉一次 artifact get）").argParser((value, previous = []) => [...previous, value]).default([])).addOption(new Option("--jq [path]", "同 --extract，并支持 [] 映射（如 items[].fields.planNo）；裸 --jq 列出结果的顶层键").argParser((value, previous = []) => [...previous, value]).default([])).option("--extract-keys", "列出本次结果 artifact 的顶层键与体积（省掉一次 artifact get --keys）").option("--max-output-bytes <bytes>", "最终 stdout 信封预算；默认 65536（投影/--jq 之后再判）；读面 diet(~2048) 独立外置 detailArtifactId，抬高本参数不会把已 diet 的大表重新内联；artifact get 内联上限 8192").option("--request-id <requestId>").option("--timeout-ms <milliseconds>").option("--wait <milliseconds>").option("--dry-run").addHelpText("after", `\n${onboardingHelp()}\n`).action(async (tool, options) => {
+    command.command("call <tool>").option("--env <environment>", "环境名；项目白名单按当前 cwd 解析，须在含 .omc-env 的目录内运行").option("--environment <environment>").option("--args <json>").option("--args-file <path>", "从文件读参数 JSON。**必须位于配置根内**（数组批量请改用 --args-list；跨目录/系统临时文件会被拒）；免落盘用 `--args -`（stdin）").option("--args-list <json-array>", '同一工具跑 N 次（JSON 数组，每条一个 args 对象，最多 200 条）；超过上限请分批，或用 omc script 读文件。逐条执行、默认不中断，最后回 succeeded/failed 汇总。适合批量建字段等').option("--preflight", "与 --args-list 一起用：只跑参数校验 + 写前语义闸（零 wire、零写入），一次报全所有形状问题").option("--keys", "与 artifact get 的 --keys 同义（= --extract-keys）：列出本次结果 artifact 的顶层键与体积").addOption(new Option("--extract <path>", "在本次结果的 artifact 内取一个路径的值（可重复；省掉一次 artifact get）").argParser((value, previous = []) => [...previous, value]).default([])).addOption(new Option("--jq [path]", "同 --extract，并支持 [] 映射（如 items[].fields.planNo）；裸 --jq 列出结果的顶层键").argParser((value, previous = []) => [...previous, value]).default([])).option("--extract-keys", "列出本次结果 artifact 的顶层键与体积（省掉一次 artifact get --keys）").option("--max-output-bytes <bytes>", "最终 stdout 信封预算；默认 65536（投影/--jq 之后再判）；读面 diet(~2048) 独立外置 detailArtifactId，抬高本参数不会把已 diet 的大表重新内联；artifact get 内联上限 8192").option("--request-id <requestId>").option("--timeout-ms <milliseconds>").option("--wait <milliseconds>").option("--dry-run").addHelpText("after", `\n${onboardingHelp()}\n`).action(async (tool, options) => {
         const rest = [tool, ...(options.env ? ["--env", options.env] : []), ...(options.environment ? ["--environment", options.environment] : []), ...(options.args !== undefined ? ["--args", options.args] : []), ...(options.argsFile !== undefined ? ["--args-file", options.argsFile] : []), ...(options.argsList !== undefined ? ["--args-list", options.argsList] : []), ...(options.preflight ? ["--preflight"] : []), ...(Array.isArray(options.extract) ? options.extract.flatMap((path) => ["--extract", path]) : []), ...(Array.isArray(options.jq) ? options.jq.flatMap((path) => path === true ? ["--jq"] : ["--jq", path]) : []), ...(options.extractKeys ? ["--extract-keys"] : []),
             ...(options.keys ? ["--keys"] : []), ...(options.maxOutputBytes !== undefined ? ["--max-output-bytes", options.maxOutputBytes] : []), ...(options.requestId ? ["--request-id", options.requestId] : []), ...(options.timeoutMs !== undefined ? ["--timeout-ms", options.timeoutMs] : []), ...(options.wait !== undefined ? ["--wait", options.wait] : []), ...(options.dryRun ? ["--dry-run"] : [])];
         commandExitCode = await cmdCall(new ConfigStore(defaultPaths()), rest);
@@ -2408,15 +2411,21 @@ async function main() {
             script: { lines: lines.length, skipped: parsed.skipped.length },
         }, 0);
     });
-    const rollbackCommand = command.command("rollback").description("配置回滚（git-revert 语义）：list 列写时间线 / plan 预览恢复（diff+后续写覆盖警告）/ apply 执行恢复——恢复走完整写闸门并记 journal（回滚可再回滚）。接入全部配置写面（workflow/规则/数据规则/视图/表单草稿/在线JS/字典/字段/模型/应用/报表）；publish 类生命周期推进不可逆（plan 会说明）；journal 与 before 快照为本机边界（不跨机器）");
+    const rollbackCommand = command.command("rollback").description("配置回滚（git-revert 语义）：list 列写时间线 / plan 预览恢复（diff+后续写覆盖警告）/ apply 执行恢复——恢复走完整写闸门并记 journal（回滚可再回滚）。apply 支持 --wait <毫秒> 有界排队；list/plan 为只读面不接写锁。接入全部配置写面（workflow/规则/数据规则/视图/表单草稿/在线JS/字典/字段/模型/应用/报表）；publish 类生命周期推进不可逆（plan 会说明）；journal 与 before 快照为本机边界（不跨机器）");
     rollbackCommand.command("list").option("--env <environment>").option("--environment <environment>").option("--target <substr>").option("--tool <name>").option("--limit <n>").action(async (options) => {
         commandExitCode = await withTransport(options, "rollback list", (transport) => cmdRollbackList({ environment: options.env ?? options.environment, target: options.target, tool: options.tool, limit: options.limit }, transport));
     });
     rollbackCommand.command("plan <ref>").option("--env <environment>").option("--environment <environment>").action(async (ref, options) => {
         commandExitCode = await withTransport(options, "rollback plan", (transport) => cmdRollbackPlan(ref, { environment: options.env ?? options.environment }, transport));
     });
-    rollbackCommand.command("apply <ref>").option("--env <environment>").option("--environment <environment>").option("--confirm-production").action(async (ref, options) => {
-        commandExitCode = await withTransport(options, "rollback apply", (transport) => cmdRollbackApply(ref, { environment: options.env ?? options.environment, confirmProduction: options.confirmProduction === true }, transport));
+    rollbackCommand.command("apply <ref>").option("--env <environment>").option("--environment <environment>").option("--confirm-production").option("--wait <milliseconds>", "写锁冲突时的有界排队毫秒数（默认 0=立刻拒绝）").action(async (ref, options) => {
+        const waitMs = options.wait === undefined ? 0 : Number(options.wait);
+        if (!Number.isSafeInteger(waitMs) || waitMs < 0 || waitMs > 600_000) {
+            console.error("--wait must be an integer number of milliseconds from 0 to 600000");
+            commandExitCode = CLI_EXIT_CODES.invalidInput;
+            return;
+        }
+        commandExitCode = await withTransport(options, "rollback apply", (transport) => cmdRollbackApply(ref, { environment: options.env ?? options.environment, confirmProduction: options.confirmProduction === true, waitMs }, transport));
     });
     const artifactCommand = command.command("artifact");
     artifactCommand.command("prune").option("--older-than <duration>", "删除超过该时长的读回产物（如 7d/12h/30m）").option("--max-bytes <bytes>", "产物目录预算；超出时按最旧优先删除").option("--json").action((options) => {
@@ -2461,6 +2470,7 @@ async function main() {
             pureKeys: (options.keys === true || bareJq) && options.summary !== true, ...(typeof options.keys === "string" ? { keys: options.keys } : {}), full: options.full === true }));
     });
     command.command("bench").option("--live-sample").option("--env <environment>").action(async (options) => { commandExitCode = await cmdBench([...(options.liveSample ? ["--live-sample"] : []), ...(options.env ? ["--env", options.env] : [])]); });
+    command.command("residue <prefix>").description("跨面前缀残留扫描（model 全租户/folder/custompage；默认 deep 再查命中模型的 rule/datarule/onlinejs）——收尾「删净」一次证明，clean:true 即零残留。只读零写入；report 面暂停维护未扫描").option("--env <environment>", "环境名（默认按 cwd 的 .omc-env 解析）").option("--apps <codes>", "all（默认，全租户）或逗号分隔应用码").option("--no-deep", "只扫 model/folder/custompage，不深查命中模型").option("--max-output-bytes <bytes>").action(async (prefix, options) => { commandExitCode = await withTransport(options, request, (transport) => cmdResidue(prefix, { env: options.env, apps: options.apps, ...(options.deep === false ? { noDeep: true } : {}) }, transport)); });
     const jqOption = () => new Option("--jq [path]", "路径投影（与 call --jq 同 DSL；可逗号多路径；裸 --jq 列顶层键）").argParser((value, previous = []) => [...previous, value]).default([]);
     command.command("commands").option("--json").option("--compact").option("--filter <keyword>").option("--lane <id>").option("--max-output-bytes <bytes>").addOption(jqOption()).action(async (options) => { commandExitCode = await withTransport(options, request, (transport) => cmdDiscovery("commands", transport, undefined, { json: options.json === true, compact: options.compact === true, ...(options.filter ? { filter: options.filter } : {}), ...(options.lane ? { lane: options.lane } : {}), ...(options.jq !== undefined ? { jq: options.jq } : {}) })); });
     command.command("describe <tool>").option("--full").option("--cache-ok", "允许 --full 在同会话重复读时短路为 artifact 指针（默认每次回全文）").option("--schema-only").option("--param <name>").option("--example [id]").option("--max-output-bytes <bytes>").addOption(jqOption()).action(async (tool, options) => {

package/dist/field-change.js

@@ -59,7 +59,12 @@ export function prepareFieldChange(input) {
     assertFormConditions(raw);
     const options = ensureRelationDisplayFieldOptions(propertyType, raw);
     const displayCode = relationDisplayFieldCode(propertyType, options);
-    return { propertyType, isChildTable, options, ...(displayCode ? { displayCode } : {}) };
+    const optionRelationTarget = typeof options.schemaCode === "string" ? options.schemaCode.trim() : "";
+    const normalizedRelation = (propertyType === FIELD_PROPERTY_TYPES.WORK_SHEET || propertyType === FIELD_PROPERTY_TYPES.MULT_WORK_SHEET) &&
+        optionRelationTarget.length > 0 && !(typeof input.relativeCode === "string" && input.relativeCode.trim().length > 0)
+        ? { relationTarget: "options.schemaCode→relativeCode" }
+        : undefined;
+    return { propertyType, isChildTable, options, ...(displayCode ? { displayCode } : {}), ...(normalizedRelation ? { normalized: normalizedRelation } : {}) };
 }
 /** The single platform wire body for a field create. */
 export function fieldChangeWireBody(input, prepared) {
@@ -74,6 +79,7 @@ export function fieldChangeWireBody(input, prepared) {
             ? { defaultValue: null, subSchema: prepared.subSchema }
             : { defaultValue: "", ...(prepared.displayCode ? { relativePropertyCode: prepared.displayCode } : {}), options: JSON.stringify(prepared.options) }),
         ...(input.relativeCode ? { relativeCode: input.relativeCode } : {}),
+        ...(!input.relativeCode && prepared.normalized ? { relativeCode: String(prepared.options.schemaCode) } : {}),
     };
 }
 /**

package/dist/field-families.js

@@ -15,7 +15,7 @@ export const propertyTypeArg = z
 export const relativeCodeArg = z
     .string()
     .optional()
-    .describe("relation target model code；WORK_SHEET/MULT_WORK_SHEET 必填，且与 options.schemaCode 相同");
+    .describe("关联目标 code；租户唯一、按 code 全局解析，可跨应用");
 /**
  * Ticket 59 (P0): the wire `name_i18n` column must be a *parseable JSON object
  * string*, never a bare display string. The admin designer runs an unguarded
@@ -167,7 +167,7 @@ export const subFieldArg = z
  */
 export const fieldOptionsArg = z
     .object({
-    schemaCode: z.string().optional().describe("relation target model code（WORK_SHEET/MULT_WORK_SHEET；与 relativeCode 都填且必须相同）"),
+    schemaCode: z.string().optional().describe("关联目标 code；租户唯一、按 code 全局解析，可跨应用"),
     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
@@ -270,6 +270,13 @@ export const FIELD_TYPE_SYNONYMS = Object.freeze({
 });
 /** A "did you mean" hint for a family name that is actually a Chinese concept. */
 export function fieldTypeHint(type) {
+    const commonAliases = {
+        SINGLE_TEXT: "SHORT_TEXT",
+        NUMERIC: "NUMERICAL",
+    };
+    const alias = commonAliases[type.toUpperCase()];
+    if (alias)
+        return `「${type}」不是族名；你要找的可能是 ${alias}`;
     for (const [concept, family] of Object.entries(FIELD_TYPE_SYNONYMS))
         if (type.includes(concept) || concept.includes(type))
             return `「${type}」看起来是概念名而非族名；最接近的是 ${family}`;
@@ -281,6 +288,64 @@ export function fieldTypeHint(type) {
         return `「${type}」不是族名；你要找的可能是 ${closest}`;
     return undefined;
 }
+/**
+ * Validate a model-relation target before bizproperty/create.  The platform
+ * accepts the row and only fails at model publish (300010), which leaves the
+ * whole model poisoned.  Callers supply the already-read model list so this
+ * helper remains usable by both field entry points without owning transport.
+ */
+export function assertRelationTargetExists(args, candidates) {
+    const raw = args.propertyType;
+    const type = typeof raw === "number" && Number.isInteger(raw)
+        ? raw
+        : typeof raw === "string" && raw in FIELD_PROPERTY_TYPES ? FIELD_PROPERTY_TYPES[raw] : undefined;
+    if (type !== FIELD_PROPERTY_TYPES.WORK_SHEET && type !== FIELD_PROPERTY_TYPES.MULT_WORK_SHEET)
+        return;
+    const relativeCode = typeof args.relativeCode === "string" ? args.relativeCode.trim() : "";
+    const optionsCode = typeof args.options?.schemaCode === "string" ? args.options.schemaCode.trim() : "";
+    const target = relativeCode || optionsCode;
+    // Some offline/fake transports do not expose a model-list face.  An empty
+    // candidate set is therefore "unknown", not proof of absence; live model
+    // lists are non-empty and get the strict pre-write gate.
+    if (!target || candidates.length === 0 || candidates.includes(target))
+        return;
+    const visibleCandidates = [...candidates].sort().slice(0, 5);
+    throw new ToolRefusalError({
+        status: "refused",
+        blocker: "relation-target-not-found",
+        relationTarget: target,
+        candidates: visibleCandidates,
+        message: `关联字段 ${String(args.code ?? "(未命名)")} 的关联目标 ${target} 不存在；已在写入前拒绝。可选模型：${visibleCandidates.length > 0 ? visibleCandidates.join("、") : "（无）"}`,
+    });
+}
+/** Construct the field-specific explanation when an older platform leaks 300010. */
+export function relationPublishFailureMessage(fields, candidates) {
+    for (const field of fields) {
+        let options;
+        if (field.options && typeof field.options === "object" && !Array.isArray(field.options))
+            options = field.options;
+        else if (typeof field.options === "string") {
+            try {
+                const parsed = JSON.parse(field.options);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                    options = parsed;
+            }
+            catch { /* malformed options will be reported by the platform */ }
+        }
+        const raw = field.propertyType ?? field.type;
+        const type = typeof raw === "number" ? raw : typeof raw === "string" && raw in FIELD_PROPERTY_TYPES ? FIELD_PROPERTY_TYPES[raw] : undefined;
+        if (type !== FIELD_PROPERTY_TYPES.WORK_SHEET && type !== FIELD_PROPERTY_TYPES.MULT_WORK_SHEET)
+            continue;
+        const relativeCode = typeof field.relativeCode === "string" ? field.relativeCode.trim() : "";
+        const target = relativeCode || (typeof options?.schemaCode === "string" ? options.schemaCode.trim() : "");
+        if (typeof options?.schemaCode === "string" && options.schemaCode.trim() && (!field.relativeCode || String(field.relativeCode).trim() === "")) {
+            return `字段 ${String(field.code ?? "(未知)")} 的关联目标 ${options.schemaCode} 仅写在 options.schemaCode；发布面不解析该位置（平台原始 errcode 300010「数据模型编码不能为空！」）。请重建/归一化为顶层 relativeCode=${options.schemaCode}`;
+        }
+        if (target && candidates.length > 0 && !candidates.includes(target))
+            return `字段 ${String(field.code ?? "(未知)")} 的关联目标 ${target} 不存在（平台原始 errcode 300010「数据模型编码不能为空！」）；可选模型：${candidates.slice(0, 5).join("、")}`;
+    }
+    return undefined;
+}
 /** Case/underscore-insensitive closest match over the family list (shared helper, see closest-match.ts). */
 function closestFamilyName(type) {
     return closestMatch(type, Object.keys(FIELD_PROPERTY_TYPES));

package/dist/graph.js

@@ -52,12 +52,19 @@ export const DEFAULT_PULL_CONCURRENCY = 16;
 export const MAX_PULL_CONCURRENCY = 32;
 /** 索引超过这个天数就提示刷新（配置类查询，1 天足够新）。 */
 export const STALE_INDEX_DAYS = 1;
+export const STALE_AFTER_MINUTES = STALE_INDEX_DAYS * 24 * 60;
 export function indexAgeDays(pulledAtIso, now = Date.now()) {
     const pulled = Date.parse(pulledAtIso);
     if (Number.isNaN(pulled))
         return 0;
     return Math.max(0, Math.floor((now - pulled) / 86_400_000));
 }
+export function indexAgeMinutes(pulledAtIso, now = Date.now()) {
+    const pulled = Date.parse(pulledAtIso);
+    if (Number.isNaN(pulled))
+        return 0;
+    return Math.max(0, Math.floor((now - pulled) / 60_000));
+}
 export class GraphIndexAbsentError extends Error {
     constructor(message) {
         super(message);
@@ -404,6 +411,7 @@ export async function pullRuleGraph(session, concurrency = DEFAULT_PULL_CONCURRE
             identityFingerprint: identity,
             environmentName: session.environmentName,
             applicationCode,
+            coverage: { applicationCodes: [applicationCode] },
             ...(scope !== undefined ? { applicationResolution: applicationResolutionOf(scope) } : {}),
             pulledAtIso,
         },
@@ -611,11 +619,14 @@ function openGraphIndex() {
         }
         const pulledAtIso = meta.pulledAtIso ?? "";
         const ageDays = indexAgeDays(pulledAtIso);
+        const ageMinutes = indexAgeMinutes(pulledAtIso);
+        const coverage = { applicationCodes: meta.applicationCode ? [meta.applicationCode] : [] };
         return {
             db,
             summary: {
                 environmentName: meta.environmentName ?? "",
                 applicationCode: meta.applicationCode ?? "",
+                coverage,
                 // Persisted as JSON by the writer; a legacy index (pre-0.5.4) has no
                 // such key, so this stays optional rather than failing the read.
                 ...(meta.applicationResolution ? { applicationResolution: parseApplicationResolution(meta.applicationResolution) } : {}),
@@ -623,6 +634,8 @@ function openGraphIndex() {
                 pulledAtIso,
                 freshness: gapCount === 0 ? "complete" : "partial",
                 ageDays,
+                ageMinutes,
+                staleAfterMinutes: STALE_AFTER_MINUTES,
                 // r31a-F16：旧索引 + complete 标签 = 静默错答。给可直接照抄的刷新命令，
                 // 并明确「complete 只指扫描无缺口」。
                 ...(ageDays >= STALE_INDEX_DAYS
@@ -696,7 +709,7 @@ export function queryGraphReferences(kind, code) {
                 ? {
                     note: (gapped
                         ? "零命中，但索引存在扫描缺口——不可作为「无引用」证明；先 omc graph pull 重建再查"
-                        : "零命中=仅 scanned 面（规则/数据规则/视图）没有引用它；form（表单控件）与 workflow.permissions 未扫描，见 coverage.notScanned——不可据此判定可安全删除") +
+                        : `零命中=仅 scanned 面（规则/数据规则/视图）没有引用它；本索引覆盖应用：${summary.coverage.applicationCodes.join("、") || "（未知）"}，不代表其他应用没有引用；form（表单控件）与 workflow.permissions 未扫描，见 coverage.notScanned——不可据此判定可安全删除`) +
                         (zeroHitKindHint(db, kind, code, "references") ?? ""),
                 }
                 : {}),
@@ -719,6 +732,10 @@ export function readGraphStatus() {
             dbBytes: statSync(dbPath).size,
             dbPath,
             dbId: sha256(dbPath).slice(0, 12),
+            ageMinutes: summary.ageMinutes,
+            staleAfterMinutes: summary.staleAfterMinutes,
+            ...(summary.staleWarning ? { warning: summary.staleWarning } : {}),
+            coverage: summary.coverage,
             gaps,
         };
     }
@@ -733,7 +750,7 @@ export function readGraphStatus() {
  * a prefix match (`引用*`), which is also what makes CJK usable: unicode61
  * stores a CJK run as one token, so a full-run query hits only by prefix.
  */
-export function searchGraphRules(term, limit = 20) {
+export function searchGraphRules(term, limit = 20, offset = 0) {
     const { db, summary } = openGraphIndex();
     try {
         const tokens = term.trim().split(/\s+/).filter((token) => token !== "");
@@ -748,8 +765,8 @@ export function searchGraphRules(term, limit = 20) {
             const rows = db
                 .prepare(`SELECT r.schema_code, r.rule_code, r.name, r.enabled, r.status
            FROM rules_fts JOIN rules r ON r.rowid = rules_fts.rowid
-           WHERE rules_fts MATCH ? ORDER BY bm25(rules_fts), r.schema_code, r.rule_code LIMIT ?`)
-                .all(quoted, limit);
+           WHERE rules_fts MATCH ? ORDER BY bm25(rules_fts), r.schema_code, r.rule_code LIMIT ? OFFSET ?`)
+                .all(quoted, limit, offset);
             const refsFor = db.prepare("SELECT kind, code FROM edges WHERE schema_code = ? AND rule_code = ? ORDER BY kind, code");
             matches = rows.map((row) => {
                 const refs = { service: [], model: [], field: [] };
@@ -767,8 +784,15 @@ export function searchGraphRules(term, limit = 20) {
             });
             const searchEntity = (countSql, rowsSql, params, map) => {
                 const total = Number(db.prepare(countSql).get(...params).n);
-                const rows = db.prepare(rowsSql).all(...params, limit);
-                return { count: rows.length, total, items: rows.map(map), ...(rows.length < total ? { truncated: true } : {}) };
+                const rows = db.prepare(rowsSql.replace("LIMIT ?", "LIMIT ? OFFSET ?")).all(...params, limit, offset);
+                return {
+                    count: rows.length,
+                    total,
+                    items: rows.map(map),
+                    offset,
+                    limit,
+                    ...(offset + rows.length < total ? { truncated: true, nextOffset: offset + rows.length } : {}),
+                };
             };
             entityMatches.model = searchEntity("SELECT COUNT(*) AS n FROM models WHERE instr(name, ?) > 0 OR instr(schema_code, ?) > 0", "SELECT schema_code, name FROM models WHERE instr(name, ?) > 0 OR instr(schema_code, ?) > 0 ORDER BY schema_code LIMIT ?", [term.trim(), term.trim()], (row) => ({ schemaCode: row.schema_code, name: row.name }));
             entityMatches.field = searchEntity("SELECT COUNT(*) AS n FROM fields WHERE instr(name, ?) > 0 OR instr(code, ?) > 0", "SELECT schema_code, code, name FROM fields WHERE instr(name, ?) > 0 OR instr(code, ?) > 0 ORDER BY schema_code, code LIMIT ?", [term.trim(), term.trim()], (row) => ({ schemaCode: row.schema_code, code: row.code, name: row.name }));
@@ -789,7 +813,7 @@ export function searchGraphRules(term, limit = 20) {
                         // 实测摩擦（2026-10-30，zlt测试）：中文子串 0 命中后没有下一步提示，
                         // 调用方在「换个词再试」里打转。把两个出口都写进 note：CJK 词首
                         // 通配 + 找引用走 references/impact。
-                        : "没有命中规则。索引只覆盖规则的 code+name（不含规则体）；且只匹配**词首**——FTS5 把「增加预算」当一个词，「预算」匹配不到它。请给全词（增加预算）、词首（增加 或 增加*），或英文 code 前缀。找\"谁引用了 X\"请走 references/impact <kind> <code>。",
+                        : `实体检索：没有命中模型/字段/服务的 name 或 code；本索引覆盖应用：${summary.coverage.applicationCodes.join("、") || "（未知）"}，不代表其他应用没有该实体。\n规则检索：没有命中规则 code/name；规则搜索只匹配词首（例如「增加预算」是一个词，「预算」匹配不到），请给全词、词首或英文 code 前缀。找"谁引用了 X"请走 references/impact <kind> <code>。`,
                 }
                 : {}),
             ...(gapped ? { gapWarning: `索引有 ${summary.gaps.count} 个扫描缺口；命中列表可能不完整` } : {}),

package/dist/lanes/app.js

@@ -5,10 +5,22 @@ import { governedRead } from "../read.js";
 import { writeTool } from "../write.js";
 import { defineTool, ToolRefusalError } from "../tool-types.js";
 import { wireCall, wireRows, WireError } from "../wire.js";
+import { resolveApplicationScope } from "../support.js";
 import { APP_LANE_CONTRACT } from "./app-contract.js";
 import { readAppTree } from "./folder.js";
 const APP_LANE = APP_LANE_CONTRACT.lane;
 const APP_TOOLS = APP_LANE_CONTRACT.tools;
+export async function resolveValidatedApplicationScope(session, requested) {
+    const scope = await resolveApplicationScope(session, requested);
+    const availableApps = wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data)
+        .map((row) => String(row.appCode ?? row.code ?? "")).filter((code) => code !== "");
+    if (availableApps.length > 0 && !availableApps.includes(scope.code)) {
+        throw new ToolRefusalError({ status: "refused", blocker: "app-not-found", applicationCode: scope.code,
+            applicationResolution: { status: "unresolved", source: scope.source, requested: scope.requested ?? scope.code, available: availableApps.slice(0, 40) },
+            message: `应用「${scope.code}」不在租户 app.list 里（不是「该应用没有模型」）。可用：${availableApps.slice(0, 12).join("、")}${availableApps.length > 12 ? " 等" : ""}；先 app.list 取正确 applicationCode。` });
+    }
+    return scope;
+}
 function appRollbackSpec(toolName) {
     return {
         target: (args) => `app:${String(args.code ?? "")}`,
@@ -48,10 +60,11 @@ export function registerAppLane(tools) {
         description: APP_TOOLS["app.list"].description,
         inputSchema: { environment: environmentArg, capability: capabilityArg },
         handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
-            const applications = wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data).map((row) => ({
-                code: String(row.appCode ?? row.code),
-                name: row.appName ?? row.name,
-                groupId: row.groupId,
+            const applications = await Promise.all(wireRows((await wireCall(session, { path: ENDPOINTS.applicationList, query: {} })).data).map(async (row) => {
+                const code = String(row.appCode ?? row.code);
+                const tree = await readAppTree(session, code);
+                const modelCount = tree.reduce((count, node) => count + (node.type === "BizModel" ? 1 : 0), 0);
+                return { code, name: row.appName ?? row.name, groupId: row.groupId, modelCount };
             }));
             // r29f F2：与 discover_environment 同构——一眼判断「内联是否全集」。
             // 应用通常个位数，默认内联 + omitted:false；大租户由 governedRead 外置时