@stalfh233/omc-cli 0.6.20 → 0.6.22

package/dist/lanes/online-js.js

@@ -5,7 +5,7 @@ import { assertHtmlRender, executeFormDraftWrite, executeFormPublishWrite, readF
 import { capabilityArg, environmentArg } from "../args.js";
 import { writeTool } from "../write.js";
 import { governedRead } from "../read.js";
-import { defineTool } from "../tool-types.js";
+import { defineTool, ToolRefusalError } from "../tool-types.js";
 import { wireCall } from "../wire.js";
 import { composeCustomScript, lintOnlineJsSource } from "../online-js-source.js";
 import { composeLayoutElements } from "../online-js-layout.js";
@@ -51,7 +51,9 @@ function readCustomScriptSource(rawHtml) {
     // real script when the find falls back to the tag name.
     const element = elements.find((candidate) => candidate.id === "customScript");
     const script = typeof element?.innerHTML === "string" && element.innerHTML.trim() !== "" ? element.innerHTML : null;
-    return { present: script !== null, script, sha256: script !== null ? createHash("sha256").update(script, "utf8").digest("hex") : null, elementCount: elements.length };
+    return script !== null
+        ? { present: true, script, sha256: createHash("sha256").update(script, "utf8").digest("hex"), elementCount: elements.length }
+        : { present: false, script: null, sha256: "", elementCount: elements.length, notCollected: true, notCollectedReason: "customScript 不存在，无法计算脚本哈希" };
 }
 export function registerOnlineJsLane(tools) {
     tools.push(defineTool({
@@ -79,11 +81,12 @@ export function registerOnlineJsLane(tools) {
                 sheetCode,
                 present: draft.present || published.present,
                 sheetPublished: sheet.published === true,
-                draft: { ...draft, ...(draft.script === null ? { note: "草稿无 customScript 脚本（尚未 compose 或被清空）" } : {}) },
-                published: { ...published, ...(published.script === null ? { note: "发布面无 customScript 脚本" } : {}) },
-                ...(draft.sha256 !== null && published.sha256 !== null
+                draft: { ...draft, scriptSha256: draft.sha256 || undefined, ...(draft.script === null ? { note: "草稿无 customScript 脚本（尚未 compose 或被清空）" } : {}) },
+                published: { ...published, scriptSha256: published.sha256 || undefined, ...(published.script === null ? { note: "发布面无 customScript 脚本" } : {}) },
+                ...(draft.sha256 !== "" && published.sha256 !== ""
                     ? { draftPublishedInSync: draft.sha256 === published.sha256 }
                     : {}),
+                scriptSha256: published.sha256 || draft.sha256 || undefined,
                 hint: "脚本是 innerHTML 原文（含平台 (function(form){…}) 生命周期包装——那就是平台存储形态）；改脚本用 onlinejs.compose（默认 INCREMENTAL 并入，replace:true 整段替换）；同文件修订直接 replace:true 传完整脚本",
             };
         }, {
@@ -109,6 +112,7 @@ export function registerOnlineJsLane(tools) {
             sheetCode: z.string().min(1).optional().describe("表单槽位码；省略时默认 = schemaCode（与 form.draft/form.publish 同口径）"),
             source: z.string().optional().describe("在线 JS 代码。默认 INCREMENTAL：并入平台 (function(form){…}) 模板的既有脚本，模板与既有注册全部保留；配 replace:true 才是整段替换。脚本不得使用 export/import；事件名必须是平台事件（onLoad/onRendered/onValidate/onPreAction/onCustomAction/onActionDone/onPrintFormDataHandle/onPrintWorkflowLogDataHandle）。与 remove:true 二选一；source 为空字符串也表示移除 customScript"),
             replace: z.boolean().optional().describe("true = 以 source 整体替换 customScript（含完整 (function(form){…}) 脚本）。默认 false = 增量并入既有脚本，保留平台模板与既有逻辑"),
+            confirmReplaceSha256: z.string().regex(/^[a-f0-9]{64}$/i).optional().describe("replace:true 覆盖既有脚本时必须等于当前脚本 SHA-256，防止静默覆盖线上改动"),
             remove: z.boolean().optional().describe("true = 显式移除 customScript，使 onlinejs.get 返回 present:false；会写入并按 publish 设置发布。与 source 二选一"),
             publish: z.boolean().optional().describe("默认 true：写草稿并推发布面；false = 只写草稿不推发布面"),
             summary: z.boolean().optional().describe("true = 只回同步状态（sha/字节数/是否同步/渲染兼容），不回任何 HTML/JS 原文。确认「改动是否生效」用这个；要看原文用 onlinejs.get"),
@@ -122,10 +126,26 @@ export function registerOnlineJsLane(tools) {
                 throw new Error("remove:true 不能与非空 source 同时传入");
             // r28e F9：和同 lane 其它工具一致——省略 sheetCode 即模型码槽位。
             const targetSheetCode = args.sheetCode ?? args.schemaCode;
+            // Keep the human summary truthful when the caller relies on the documented
+            // default (sheetCode omitted): it is the model's default form slot.
             // 1. Read the existing draftHtmlJson.
             const current = await wireCall(session, { path: ENDPOINTS.sheetGet, query: { schemaCode: args.schemaCode, sheetCode: targetSheetCode } });
             const existingSheet = (current.data ?? null);
             const existingRaw = typeof existingSheet?.draftHtmlJson === "string" ? existingSheet.draftHtmlJson : undefined;
+            const existingPublishedRaw = typeof existingSheet?.publishedHtmlJson === "string" ? existingSheet.publishedHtmlJson : undefined;
+            const existingScriptState = readCustomScriptSource(existingRaw ?? existingPublishedRaw);
+            if (args.replace === true && existingScriptState.present && args.confirmReplaceSha256 !== existingScriptState.sha256) {
+                throw new ToolRefusalError({
+                    status: "refused",
+                    blocker: "onlinejs-replace-confirmation-required",
+                    schemaCode: args.schemaCode,
+                    sheetCode: targetSheetCode,
+                    previousSha256: existingScriptState.sha256,
+                    ...(args.confirmReplaceSha256 !== undefined ? { providedSha256: args.confirmReplaceSha256 } : {}),
+                    message: "replace:true 将覆盖已有线上脚本；必须传 confirmReplaceSha256 且与当前脚本 SHA-256 完全一致。未写入任何内容。",
+                    nextCommand: `omc call onlinejs.get --args '${JSON.stringify({ schemaCode: args.schemaCode, sheetCode: targetSheetCode })}'`,
+                });
+            }
             const existingCompat = validateHtmlRender(existingRaw);
             // A persisted legacy face may contain an object or malformed elements.
             // Do not pass any of it through: discard the unproven face and rebuild
@@ -198,17 +218,23 @@ export function registerOnlineJsLane(tools) {
                 return {
                     performed: { errcode: 0, published },
                     readback: {
+                        ...(args.sheetCode === undefined ? { sheetCodeFromSchema: targetSheetCode } : {}),
                         publishedSha256,
                         draftSha256,
                         draftPublishedInSync,
                         publishedElementCount: publishedElements.length,
                         scriptElementPresent: publishedElements.some((element) => element.id === "customScript"),
-                        customScriptMerged: args.replace !== true,
+                        scriptElementMeaning: "skeleton 空槽不等于存在脚本",
+                        composeMode: args.replace === true ? "replace" : "incremental",
+                        ...(removing ? { removed: true } : {}),
+                        scriptSha256: customScriptSha256,
                         customScriptSha256,
+                        scriptSha256DeprecatedAlias: "customScriptSha256",
                         customScriptBytes: Buffer.byteLength(composedScript, "utf8"),
                         composedDraftBytes: Buffer.byteLength(composedDraftHtml, "utf8"),
                         publishedHtmlBytes: Buffer.byteLength(publishedRaw, "utf8"),
                         htmlRenderCompat,
+                        verifyWith: "onlinejs.get → published.scriptSha256",
                         hint: "summary 模式不回原文；要脚本原文用 onlinejs.get，要完整布局用 artifact 或 form.get --full",
                     },
                 };
@@ -216,6 +242,7 @@ export function registerOnlineJsLane(tools) {
             return {
                 performed: { errcode: 0, published },
                 readback: {
+                    ...(args.sheetCode === undefined ? { sheetCodeFromSchema: targetSheetCode } : {}),
                     // Dedupe: after a successful publish the draft and the published
                     // face are the same bytes, and the script also rides inside them.
                     // Return the composed payload ONCE (composedDraftHtmlJson keeps the
@@ -230,10 +257,13 @@ export function registerOnlineJsLane(tools) {
                     draftPublishedInSync,
                     publishedElementCount: publishedElements.length,
                     scriptElementPresent: publishedElements.some((element) => element.id === "customScript"),
+                    scriptElementMeaning: "skeleton 空槽不等于存在脚本",
                     customScript: composedScript,
                     customScriptMatchesPublished: draftPublishedInSync,
-                    customScriptMerged: args.replace !== true,
+                    composeMode: args.replace === true ? "replace" : "incremental",
+                    ...(removing ? { removed: true } : {}),
                     htmlRenderCompat,
+                    verifyWith: "onlinejs.get → published.scriptSha256",
                     portalVerificationPlan: ["在门户打开该表单", "触发已绑定的在线 JS 事件", "检查事件产生的副作用字段或校验提示"],
                 },
             };

package/dist/lanes/runtime-data-contract.js

@@ -38,7 +38,7 @@ export function dataSubmitDescription() {
     const wire = RUNTIME_DATA_WIRE;
     return describeTool(`M2 runtime data SUBMIT (runtime/form/submit, WorkItemSubmitVO).`, [
         "Distinct from data.save: data.save persists as DRAFT; data.submit advances the record to COMPLETED (no workflow) or drives the workflow instance.",
-        "**审批提交（workItemId+agree）时 `formData` 也必填，且其值会写回业务对象——勿把期望结果（如审批级别）预写进 formData，否则规则回写的真伪无法区分（2026-09-22 实测返工案例）**；只传身份参数会被拒 formData: Required。",
+        "**审批提交（带 workItemId）可省略 `formData`**：平台使用已存业务数据，且不要携带子表数组；新建记录（无 bizObjectId/workItemId）才必须传 formData。此前把两种场景混成 Required 是错误提示（2026-11-07 r40）。",
         `就地语义：${wire.submitInPlace}；无流程 readback 必须确认 objectId 与传入 bizObjectId 相同；无 bizObjectId 的 workflowCode 新建单 → PROCESSING + workflowInstanceId，无流程 → 该行 COMPLETED。`,
         `既有草稿发起流程的唯一支持形状是两段式：先 data.save 带 workflowCode 暂存（${wire.workflowDraftSave}），再以返回的 workItemId 提交（issue#11 P6：带流程模型提交**必须**带 bizObjectId+workflowInstanceId+workItemId 三元——只带 bizObjectId 会答「流程实例无待办」、只缺 workItemId 会 50000；完整形状见 omc describe data.submit --example workflow-backed-data-submit，待办查询用 workitem.list）。`,
         `仅无 workflowCode/workItemId/workflowInstanceId 且无 bizObjectId 时保留 save→submit 便捷链（新建记录）；只要存在 workItemId 或 workflowInstanceId 就 fail-closed 拒绝（blocker submit-biz-object-id-required），零 runtime/form/submit wire。`,

package/dist/lanes/runtime-data.js

@@ -33,8 +33,9 @@ function dataListItemPreview(items) {
     return { ids, itemsPreview };
 }
 /**
- * r29b F8：`data.list` 的大结果被外置后 `items:[]`，调用方连 id 都拿不到
- * （3 行的模型也会这样——于是「没数据」与「被外置」看起来一样）。
+ * r40a B：`data.list` 的大结果被外置后不能回 `items:[]`，否则调用方会把
+ * 「有数据但在 artifact」误读成「空结果」。保留一个明确的 items 外置指针，
+ * 让通用读门不会再补回空数组占位。
  *
  * **只在确实要丢弃 items 时才补 `ids`/`itemsPreview`**：这段只在 governedRead
  * 判定 `large`（>2048B）后才会被调用。早期版本把 ids/preview 无条件塞进 handler
@@ -55,8 +56,14 @@ function dataListCompactProjection(result) {
             compact.itemsPreview = preview.ids.slice(0, 3).map((id) => ({ id }));
             if (value.length > 0)
                 compact.listArtifactHint =
-                    "items 已外置（truncatedKeys 含 items）：完整行见 artifact（detailArtifactId / fetch）。同信封三分法：ids=本页全部 id；itemsPreview=ids 前 3 个的引用（仅 {id}，不是第二份行）；items=[] 表示正文在 artifact。";
-            compact.itemsExternalized = true;
+                    "items 已外置：items 是指针而非空结果；完整行见 artifact（detailArtifactId / fetch）。ids=本页全部 id；itemsPreview=ids 前 3 个的引用（仅 {id}，不是第二份行）。";
+            // The generic read gate adds [] for dropped array keys. Keep an explicit
+            // pointer under the original key so it cannot manufacture that false
+            // empty-result shape. The full rows remain in detailArtifactId.
+            compact.items = { externalized: true, count: value.length };
+            compact.truncatedKeys = ["items"];
+            compact.truncated = true;
+            compact.itemsExternalized = { count: value.length };
             continue;
         }
         // 这两个键由本函数按 items 现算，handler 不再重复内联。
@@ -1867,9 +1874,9 @@ export function registerRuntimeDataLane(tools) {
      * gone, not that the model is clean — a submit can leave a separate draft row
      * behind. After a delete, read the model's residue so "cleaned up" is a
      * model-level fact (`total:0`). Best-effort: a query failure never fails the
-     * delete, but it IS surfaced under `preExistingRows.error`.
+      * delete, but it IS surfaced as an explicit readback error.
      */
-    async function preExistingRows(session, schemaCode, sheetCode) {
+    async function remainingRows(session, schemaCode, sheetCode) {
         try {
             const result = await wireCall(session, {
                 path: ENDPOINTS.runtimeQueryList,
@@ -1877,12 +1884,12 @@ export function registerRuntimeDataLane(tools) {
                 body: { schemaCode, queryCode: schemaCode, filters: [], mobile: false, page: 0, size: 1, queryVersion: 1, showTotal: true },
             });
             const page = extractBizObjectPage(result.data);
-            return { preExistingRows: { total: page.total, clean: page.total === 0, sheetCode, note: "含历史既有数据，非本次创建" } };
+            return { remainingRows: page.total, clean: page.total === 0, sheetCode, cleanNote: "clean 表示删除该行后该表是否已为空" };
         }
         catch (error) {
             if (error instanceof WireError && error.kind === "business" && error.errcode === RUNTIME_DATA_WIRE.emptyModelErrcode)
-                return { preExistingRows: { total: 0, clean: true, sheetCode, note: "含历史既有数据，非本次创建" } };
-            return { preExistingRows: { total: null, clean: null, sheetCode, note: "含历史既有数据，非本次创建", error: error instanceof Error ? error.message : String(error) } };
+                return { remainingRows: 0, clean: true, sheetCode, cleanNote: "clean 表示删除该行后该表是否已为空" };
+            return { remainingRows: null, clean: null, sheetCode, cleanNote: "clean 表示删除该行后该表是否已为空", error: error instanceof Error ? error.message : String(error) };
         }
     }
     writeTool({
@@ -1981,13 +1988,14 @@ export function registerRuntimeDataLane(tools) {
                             noop: true,
                             recoveryHint: "若另一进程刚刚删除，这是正常并发结果（already-absent），不是 id 拿错。否则：真实 id 必须取自 data.list 的 items[].id；工作流中心/门户页面回显的 id 会脱敏。",
                             thisRow: { absent: true, deleted: false },
-                            ...(await preExistingRows(session, args.schemaCode, sheetCode)),
+                            thisRowDeleted: true,
+                            ...(await remainingRows(session, args.schemaCode, sheetCode)),
                         },
                     };
                 }
                 return {
                     performed: { errcode: one.errcode, deleted: one.deleted === true, noop: false, sheetCode, resolvedFrom },
-                    readback: { absent: one.absent, deleted: one.deleted === true, thisRow: { absent: one.absent, deleted: one.deleted === true }, ...(await preExistingRows(session, args.schemaCode, sheetCode)) },
+                    readback: { absent: one.absent, deleted: one.deleted === true, thisRowDeleted: one.deleted === true, thisRow: { absent: one.absent, deleted: one.deleted === true }, ...(await remainingRows(session, args.schemaCode, sheetCode)) },
                 };
             }
             const deleted = [];
@@ -1995,7 +2003,7 @@ export function registerRuntimeDataLane(tools) {
                 deleted.push(await deleteOne(id));
             // `deleted`/`count` ride `readback` — the write envelope surfaces only
             // performed/readback inline (extra top-level keys are artifact-only).
-            return { performed: { sheetCode, resolvedFrom }, readback: { absent: true, count: deleted.length, deleted, ...(await preExistingRows(session, args.schemaCode, sheetCode)) } };
+            return { performed: { sheetCode, resolvedFrom }, readback: { absent: true, count: deleted.length, deleted, ...(await remainingRows(session, args.schemaCode, sheetCode)) } };
         },
     });
     writeTool({
@@ -2007,7 +2015,7 @@ export function registerRuntimeDataLane(tools) {
         inputSchema: {
             schemaCode: z.string().min(1),
             sheetCode: z.string().optional(),
-            formData: runtimeFormDataArg,
+            formData: runtimeFormDataArg.optional().describe("business-object data keyed by field code；新建记录必填，审批提交（带 workItemId）可省略——平台使用已存业务数据"),
             workflowCode: z.string().optional(),
             workflowInstanceId: z.string().optional(),
             workItemId: z.string().optional(),
@@ -2077,7 +2085,16 @@ export function registerRuntimeDataLane(tools) {
                 });
             }
             const { sheetCode, resolvedFrom } = await resolveFormSheetCode(session, { schemaCode: args.schemaCode, sheetCode: args.sheetCode });
-            const stampedSubmit = await prepareRuntimeFormData(session, args.schemaCode, args.formData, { isUpdate: targetObjectId !== null });
+            if (!hasWorkItem && args.formData === undefined) {
+                throw new ToolInputError({
+                    status: "error",
+                    blocker: "tool-input-invalid",
+                    tool: "data.submit",
+                    message: "新建提交缺少 formData；审批提交可省略 formData（子表数组不要带），新建记录才必须传 formData。",
+                    nextCommand: "omc call data.submit --args '{\"schemaCode\":\"<schemaCode>\",\"formData\":{...}}'",
+                });
+            }
+            const stampedSubmit = await prepareRuntimeFormData(session, args.schemaCode, (args.formData ?? {}), { isUpdate: targetObjectId !== null });
             const formData = stampedSubmit.formData;
             // r5-asset 2026-10-20: the platform APPENDS child rows carried in an
             // approval submit's formData (no upsert by row id, no error). Live: an
@@ -2089,7 +2106,7 @@ export function registerRuntimeDataLane(tools) {
                 // {bizObject:{data:{...}}}, and a top-level-only check let those through
                 // (the platform appends whatever it finds). The child codes come from the
                 // model's own field list.
-                const carried = collectChildArrayPaths(args.formData, new Set(stampedSubmit.childCodes));
+                const carried = collectChildArrayPaths((args.formData ?? {}), new Set(stampedSubmit.childCodes));
                 if (carried.length > 0)
                     throw new ToolRefusalError({
                         status: "refused",
@@ -2124,7 +2141,7 @@ export function registerRuntimeDataLane(tools) {
                             `确要在提交携带人员字段（个别平台构建接受），显式带 allowStaffOnSubmit:true 自担。`,
                     });
             }
-            const validation = await portalRequiredViolations(session, args.schemaCode, sheetCode, args.formData).catch(() => ({ requiredFields: [], missingRequired: [] }));
+            const validation = await portalRequiredViolations(session, args.schemaCode, sheetCode, args.formData ?? {}).catch(() => ({ requiredFields: [], missingRequired: [] }));
             // Directive: a workflow-backed model's submit must START the workflow, not
             // merely save a sheet row. When the caller names no workflow params, detect
             // the model's workflow and start it (formType=1 + workflowCode); a model
@@ -2178,7 +2195,7 @@ export function registerRuntimeDataLane(tools) {
                 bizObject: {
                     schemaCode: args.schemaCode,
                     sheetCode,
-                    data: args.formData,
+                    data: args.formData ?? {},
                 },
                 agree: args.agree !== false,
             };

package/dist/lanes/workflow.js

@@ -3314,12 +3314,20 @@ export function registerWorkflowLane(tools) {
             const purposeHint = args.workflowInstanceId === undefined && args.workflowCode === undefined
                 ? "本调用用于发现待办并取 workItemId 做审批；只想看流程走到哪，用 workflow.instanceActivity；提交/审批后优先复用 data.submit 的 readback.nextSubmit，不要重复查询。"
                 : undefined;
+            // r40a-E（2026-11-07，E2E F29）：按实例查且本人口径 total:0 时，与「流程没生成」
+            // 不可区分——探针差点误判「审批没生成」。存在范围外待办时显式说明口径差。
+            const scopedToInstance = args.workflowInstanceId !== undefined && args.participant === undefined;
+            const unfiltered = page.unfilteredTotal;
+            const othersScopeNote = scopedToInstance && page.total === 0 && typeof unfiltered === "number" && unfiltered > 0
+                ? `total:0 是当前登录人口径——查询范围（unfilteredTotal=${unfiltered}）内存在他人的待办。若该实例应有待办：待办按持有人过滤，用 participant:<持有人id> 复查（持有人见 data.submit 回执 flowWarning）；不要据此判定「流程未生成」。`
+                : undefined;
             return {
                 total: page.total,
                 // The JPA-spec path reports no page count; only emit it when known.
                 ...("totalPages" in page && page.totalPages !== undefined ? { totalPages: page.totalPages } : {}),
                 itemsCount: items.length,
                 ...(purposeHint ? { purposeHint } : {}),
+                ...(othersScopeNote ? { scopeNote: othersScopeNote } : {}),
                 ...(args.participant !== undefined ? { participant: args.participant, state: args.state ?? "PENDING", source: "list_workitems" } : {}),
                 ...("unfilteredTotal" in page && page.unfilteredTotal !== undefined ? { unfilteredTotal: page.unfilteredTotal } : {}),
                 items,
@@ -3498,6 +3506,7 @@ export function registerWorkflowLane(tools) {
                 fullName: row.fullName ?? null,
                 corpId: row.corpId ?? null,
                 code: row.code ?? null,
+                ...(row.origin === "system-preset" || row.defaultPermission === true || row.preset === true ? { origin: "system-preset" } : row.origin === "user" ? { origin: "user" } : {}),
             }));
             const actor = await resolvePermissionActor(session);
             const effectiveFor = {
@@ -3512,6 +3521,7 @@ export function registerWorkflowLane(tools) {
                 note: actor.isAdmin
                     ? "当前登录人是平台管理员：发起成功不证明白名单生效。要用非管理员账号另建环境验证。"
                     : "本读面只回配置行；membership 命中需非管理员实发 data.submit 才能证伪。",
+                ...(actor.isAdmin ? { verifiable: false, verifyWith: `以普通账号凭据跑同查询：omc call workflow.permissions --env <env> --args '${JSON.stringify({ workflowCode })}'` } : {}),
             };
             return {
                 workflowCode,

package/dist/mcp-graph.js

@@ -47,7 +47,7 @@ const INSTRUCTIONS_INDEXED = [
     "- 改名/删除/重构一个 字段(field)/模型(model)/服务(service) 前，先用 omc_graph_explore 查引用与影响面；查\"谁引用了 X\"也走它。",
     "- 索引只覆盖：业务规则（methodMapping/targetObjectCode）、数据规则（propertyCodes 与公式 {字段}）、视图（列/排序/条件）。**不含**规则条件叶子与流程绑定。",
     "- search 语义：只匹配规则 code+name 的**词首**（中文子串不命中：搜「预算」匹配不到「增加预算」）。",
-    "答案带 freshness/pulledAtIso——索引是快照，平台侧改动后需 CLI 重建：omc graph pull --env <env>（只读远端，约 1 分钟）。",
+    "答案带 freshness/pulledAtIso——索引是快照，平台侧改动后需 CLI 重建：omc graph pull --env <env>（只读远端，约 1 分钟）。MCP 按注册时的 --path 读库；CLI pull 必须把 --path 指到本目录才能写入本库。",
     "索引绑定单一环境（environmentName）；查别的环境先重新 pull。",
 ].join("\n");
 const INSTRUCTIONS_NO_INDEX = [
@@ -60,7 +60,7 @@ const EXPLORE_TOOL = {
     description: [
         "一次查全一个目标的引用与影响面（本地索引，毫秒级）。",
         "输入 query 可为业务名（实体 name+code 子串）或规则 code+name 词首；也可直接给字段/模型/服务 code。kind 可选 field|model|service，不给则三种都查。",
-        "返回 {index(freshness), references:{kind:[{schemaCode,ruleCode,nodeCode,nodeType,via}]}, impact:{kind:totals}, search:{matches:{model,field,service},rules}}。",
+        "返回 {index(freshness), references:{kind:[{schemaCode,ruleCode,nodeCode,nodeType,via,referrer,isSelf}]}, impact:{kind:totals}, search:{matches:{model,field,service},rules}}。",
         "references/impact 支持 offset+limit 分页；truncated 时按返回的 nextOffset 继续调用。实体分页结果带 nextCall；分页不会改变 resolved。字段同名时请用 schemaCode 消歧。",
         "改/删/重命名任何字段、模型、服务之前必查；找\"关于 X 的规则\"拿 code 也走这里。",
         "索引不含规则条件叶子与流程绑定；freshness=partial 时命中可能不完整（答案里有 gapWarning）。",
@@ -69,8 +69,11 @@ const EXPLORE_TOOL = {
         type: "object",
         properties: {
             query: { type: "string", description: "业务名（实体 name+code 子串）、字段/模型/服务 code，或规则检索词（规则 code+name 词首匹配）" },
+            queries: { type: "array", items: { type: "string" }, description: "实体面多条件检索；与 query 并存时合并，match 默认 any" },
+            match: { type: "string", enum: ["all", "any"], description: "queries[] 的模型∪字段所属模型求交/并" },
             kind: { type: "string", enum: [...KINDS], description: "限定一种引用种类；省略则 field/model/service 全查" },
             schemaCode: { type: "string", description: "限定字段所属模型；也可用于校验模型。" },
+            applicationCode: { type: "string", description: "限定应用；仅返回该应用的实体与引用" },
             env: { type: "string", description: "期望的环境名；与索引所属环境不一致时会拒绝（防跨环境误答）" },
             offset: { type: "integer", minimum: 0, description: "引用/实体结果起始偏移；truncated 时使用 nextOffset" },
             limit: { type: "integer", minimum: 1, maximum: MATCH_CAP, description: "每类结果最多返回多少条（默认 50）" },
@@ -125,8 +128,8 @@ function entityInventory() {
     const db = new DatabaseSync(graphDbPath(), { readOnly: true });
     try {
         return [
-            ...db.prepare("SELECT schema_code, name FROM models").all().map((r) => ({ kind: "model", schemaCode: r.schema_code, code: r.schema_code, name: r.name ?? "" })),
-            ...db.prepare("SELECT schema_code, code, name FROM fields").all().map((r) => ({ kind: "field", schemaCode: r.schema_code, code: r.code, name: r.name ?? "" })),
+            ...db.prepare("SELECT schema_code, name, application_code FROM models").all().map((r) => ({ kind: "model", schemaCode: r.schema_code, code: r.schema_code, name: r.name ?? "", applicationCode: r.application_code ?? undefined })),
+            ...db.prepare("SELECT schema_code, code, name, application_code FROM fields").all().map((r) => ({ kind: "field", schemaCode: r.schema_code, code: r.code, name: r.name ?? "", applicationCode: r.application_code ?? undefined })),
             ...db.prepare("SELECT code, name FROM services").all().map((r) => ({ kind: "service", code: r.code, name: r.name ?? "" })),
         ];
     }
@@ -159,12 +162,16 @@ export async function executeGraphTool(name, rawArgs) {
         }
         if (name === EXPLORE_TOOL.name) {
             const query = typeof args.query === "string" ? args.query.trim() : "";
-            if (!query)
-                return toolError("query 不能为空");
+            const queryList = Array.isArray(args.queries) ? args.queries.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean) : [];
+            const queries = queryList.length > 0 ? queryList : query ? [query] : [];
+            if (queries.length === 0)
+                return toolError("query 或 queries 不能为空");
+            const primaryQuery = queries[0];
             const kind = args.kind === undefined ? undefined : String(args.kind);
             if (kind !== undefined && !KINDS.includes(kind))
                 return toolError(`kind 必须是 ${KINDS.join("|")} 之一`);
             const schemaCode = typeof args.schemaCode === "string" && args.schemaCode.trim() ? args.schemaCode.trim() : undefined;
+            const applicationCode = typeof args.applicationCode === "string" && args.applicationCode.trim() ? args.applicationCode.trim() : undefined;
             if (schemaCode && kind !== "field" && kind !== "model")
                 return toolError("schemaCode 仅适用于 kind=field|model");
             const status = readGraphStatus();
@@ -179,11 +186,34 @@ export async function executeGraphTool(name, rawArgs) {
             const impact = {};
             // Resolve from an unpaged search. The result page is presentation only;
             // otherwise offset=2 can silently change the subject being inspected.
-            const search = searchGraphRules(query, limit, offset);
-            const resolvedSearch = searchGraphRules(query, MATCH_CAP, 0);
-            const loweredQuery = query.toLocaleLowerCase();
+            const search = searchGraphRules(primaryQuery, limit, offset);
+            const scopedSearch = applicationCode ? {
+                ...search,
+                matches: {
+                    ...search.matches,
+                    model: { ...search.matches.model, items: search.matches.model.items.filter((row) => row.applicationCode === applicationCode) },
+                    field: { ...search.matches.field, items: search.matches.field.items.filter((row) => row.applicationCode === applicationCode) },
+                },
+            } : search;
+            const resolvedSearch = searchGraphRules(primaryQuery, MATCH_CAP, 0);
+            const loweredQuery = primaryQuery.toLocaleLowerCase();
             const allCandidates = entityInventory().filter((r) => (r.code.toLocaleLowerCase().includes(loweredQuery) || r.name.toLocaleLowerCase().includes(loweredQuery)) &&
-                (!schemaCode || (r.kind !== "service" && r.schemaCode === schemaCode)));
+                (!schemaCode || (r.kind !== "service" && r.schemaCode === schemaCode)) &&
+                (!applicationCode || r.kind === "service" || r.applicationCode === applicationCode));
+            const candidatesForQuery = (term) => entityInventory().filter((r) => (r.code.toLocaleLowerCase().includes(term.toLocaleLowerCase()) || r.name.toLocaleLowerCase().includes(term.toLocaleLowerCase())) &&
+                (!schemaCode || (r.kind !== "service" && r.schemaCode === schemaCode)) &&
+                (!applicationCode || r.kind === "service" || r.applicationCode === applicationCode));
+            const perQueryModels = queries.map((term) => new Set(candidatesForQuery(term).filter((r) => r.kind === "model").map((r) => r.schemaCode)));
+            const perQueryFieldModels = queries.map((term) => new Set(candidatesForQuery(term).filter((r) => r.kind === "field").map((r) => r.schemaCode)));
+            const combine = (sets) => {
+                if (sets.length === 0)
+                    return new Set();
+                if (args.match === "all")
+                    return new Set([...sets[0]].filter((value) => sets.every((set) => set.has(value))));
+                return new Set(sets.flatMap((set) => [...set]));
+            };
+            const hitModels = combine(perQueryModels);
+            const hitFieldModels = combine(perQueryFieldModels);
             const typedCandidates = kind ? allCandidates.filter((r) => r.kind === kind) : allCandidates;
             const fieldCandidates = kind === "field" ? typedCandidates : allCandidates.filter((r) => r.kind === "field");
             const exactSame = fieldCandidates.filter((r) => r.code === query);
@@ -232,7 +262,7 @@ export async function executeGraphTool(name, rawArgs) {
                 }
             }
             const decorate = (row) => withMatchedOn({ ...row, ...(row.schemaCode && row.code === undefined ? { code: row.schemaCode } : {}) }, query);
-            const decoratedMatches = { ...search.matches, model: { ...search.matches.model, items: search.matches.model.items.map(decorate) }, field: { ...search.matches.field, items: search.matches.field.items.map(decorate) }, service: { ...search.matches.service, items: search.matches.service.items.map(decorate) } };
+            const decoratedMatches = { ...scopedSearch.matches, model: { ...scopedSearch.matches.model, items: scopedSearch.matches.model.items.map(decorate) }, field: { ...scopedSearch.matches.field, items: scopedSearch.matches.field.items.map(decorate) }, service: { ...scopedSearch.matches.service, items: scopedSearch.matches.service.items.map(decorate) } };
             const noEntityHit = search.matches.model.total === 0 && search.matches.field.total === 0 && search.matches.service.total === 0;
             const composite = /\s|\+|,|\b(?:AND|OR)\b/i.test(query);
             const searchNote = "实体检索：业务名/实体 name+code 使用子串匹配。\n规则检索：规则 code+name 使用词首匹配（中文子串不命中）。";
@@ -242,8 +272,12 @@ export async function executeGraphTool(name, rawArgs) {
             return toolResult({
                 status: "ok",
                 query,
+                ...(queries.length > 1 ? { queries, match: args.match === "all" ? "all" : "any" } : {}),
+                hitModels: [...hitModels],
+                hitFields: [...hitFieldModels].flatMap((schema) => entityInventory().filter((r) => r.kind === "field" && r.schemaCode === schema).map((r) => ({ schemaCode: schema, code: r.code, name: r.name }))),
                 found: resolvedEntity !== undefined,
                 ...(resolvedEntity ? { resolved: { kind: resolvedEntity.kind, schemaCode: "schemaCode" in resolvedEntity ? resolvedEntity.schemaCode : "", code: resolvedEntity.code, matchedOn: { on: resolvedEntity.name.includes(query) ? "name" : "code", fragment: query } } } : {}),
+                ...(resolvedEntity ? { otherCandidates: allCandidates.filter((r) => r.code !== resolvedEntity.code).slice(0, 5).map((r) => ({ schemaCode: r.schemaCode ?? r.code, name: r.name })) } : {}),
                 ...(ambiguous ? { ambiguous: true, candidates: exactSame.map((r) => ({ schemaCode: r.schemaCode, code: r.code, name: r.name })) } : {}),
                 ...(kind !== undefined ? { kind } : {}),
                 index,
@@ -253,7 +287,7 @@ export async function executeGraphTool(name, rawArgs) {
                 ...(nextCall ? { nextCall } : {}),
                 ...(noEntityHit && composite ? { unsupportedQuerySyntax: true, hint: "组合检索暂不支持，请拆词单查后求交" } : {}),
                 ...(noEntityHit ? { suggestions: suggestions(query), hint: "可尝试 suggestions 中的实体 code/name；引用明细请使用匹配 code 查 references/impact" } : {}),
-                searchNote: `${searchNote}${paginationNote}`,
+                searchNote: `${searchNote}${paginationNote}${queries.length > 1 ? " 规则面（词首匹配）不参与 queries[] 的实体求交。" : ""}`,
                 ...(search.note ? { searchNote: `${searchNote}\n${search.note}` } : {}),
                 // 旧句「索引不含规则条件叶子与流程绑定」漏了表单与流程权限（r35a-F4 实证
                 // 探针据此差点误删被表单引用的字段）。改为指向结构化 coverage，不再靠散文。

package/dist/model-purge.js

@@ -324,6 +324,7 @@ export async function cmdModelPurge(args) {
     const result = {
         status,
         schemaCode,
+        verdict: plan.modelExists && !failed ? "cascading" : "clean",
         ...(plan.workflowCode !== undefined ? { workflowCode: plan.workflowCode } : {}),
         deletedInstances: steps.filter((step) => step.step.startsWith("workflow.delete_instance:") && step.status === "ok").length,
         ...(unremovableInstances.length > 0 ? { unremovableInstances } : {}),

package/dist/residue.js

@@ -7,6 +7,15 @@ import { SessionManager } from "./session-manager.js";
 import { makeToolContext } from "./context.js";
 import { emitInvalid, emitResult } from "./command-transport.js";
 const MAX_ITEMS = 20;
+const SYSTEM_RULE_NAMES = new Set(["Available", "Cancel", "Create", "Delete", "GetList", "Load", "Update"]);
+function residueOrigin(row, faceName) {
+    if (row.defaultRule === true || row.preset === true || row.system === true || row.systemPreset === true)
+        return "system-preset";
+    if (faceName === "rule" && SYSTEM_RULE_NAMES.has(nameOf(row, codeOf(row))))
+        return "system-preset";
+    // Do not guess for datarules or otherwise unmarked rows.
+    return row.origin === "system-preset" || row.origin === "user" ? row.origin : undefined;
+}
 function face(faceName, rows, extra = {}) {
     return { face: faceName, ...extra, count: rows.length, items: rows.slice(0, MAX_ITEMS) };
 }
@@ -64,8 +73,8 @@ async function deepFaces(session, model) {
         // A missing form is an absent online-js face, not a scan failure.
     }
     return [
-        face("rule", rules.map((row) => ({ code: codeOf(row), name: nameOf(row, codeOf(row)) })), { model: schemaCode }),
-        face("datarule", datarules.map((row) => ({ code: codeOf(row), name: nameOf(row, codeOf(row)) })), { model: schemaCode }),
+        face("rule", rules.map((row) => ({ code: codeOf(row), name: nameOf(row, codeOf(row)), ...(residueOrigin(row, "rule") ? { origin: residueOrigin(row, "rule") } : {}) })), { model: schemaCode }),
+        face("datarule", datarules.map((row) => ({ code: codeOf(row), name: nameOf(row, codeOf(row)), ...(residueOrigin(row, "datarule") ? { origin: residueOrigin(row, "datarule") } : {}) })), { model: schemaCode }),
         face("onlinejs", online, { model: schemaCode }),
     ];
 }
@@ -92,13 +101,21 @@ export async function scanResidues(session, prefix, options = {}) {
         for (const model of models)
             faces.push(...await deepFaces(session, model));
     }
+    const systemPresetCount = faces.reduce((sum, item) => sum + item.items.filter((row) => row.origin === "system-preset").length, 0);
+    const userResidues = faces.reduce((sum, item) => sum + item.items.filter((row) => row.origin !== "system-preset").length, 0);
     const totalResidues = faces.reduce((sum, item) => sum + item.count, 0);
+    const modelFace = faces.filter((item) => item.face === "model");
+    const hasModelResidue = modelFace.some((item) => item.count > 0);
+    const hasOtherResidue = faces.some((item) => item.face !== "model" && item.count > 0);
+    const pendingCascade = !hasModelResidue && hasOtherResidue;
     return {
         prefix,
         faces,
         totalResidues,
-        clean: totalResidues === 0,
-        note: "report 面暂停维护未扫描；workflow 模板跟模型走（模型删即删）",
+        clean: userResidues === 0 && !pendingCascade,
+        ...(systemPresetCount > 0 ? { systemPresetCount } : {}),
+        ...(pendingCascade ? { pendingCascade: true } : {}),
+        note: pendingCascade ? "模型已不存在但仍有级联面命中：级联窗口内，等 40-60s 重跑，幂等" : "report 面暂停维护未扫描；workflow 模板跟模型走（模型删即删）",
     };
 }
 export async function cmdResidue(prefix, options, transport) {

package/dist/rule-when.js

@@ -34,10 +34,65 @@ function parseWhen(raw) {
     const value = /^-?\d+(\.\d+)?$/.test(rawValue.trim()) ? Number(rawValue.trim()) : rawValue.trim();
     return { field, op, value };
 }
+/**
+ * 人读层只投影图中真正存在的节点；它不是另一套编译结果。
+ * `matchBy` 明确区分执行门（dataCondition）与选行（filterCondition），
+ * 避免 dry-run 只给 sha256 时把两者误认为同一种条件。
+ */
+export function compiledRuleSummary(nodeGraph) {
+    const nodes = Array.isArray(nodeGraph.nodes) ? nodeGraph.nodes : [];
+    return nodes
+        .filter((node) => !!node && typeof node === "object" && nodeTypeOf(node) !== undefined && nodeTypeOf(node) !== "START" && nodeTypeOf(node) !== "END")
+        .map((node) => {
+        const dataCondition = node.dataCondition;
+        const filterCondition = node.filterCondition;
+        const rawActions = Array.isArray(node.dataActions) ? node.dataActions : Array.isArray(node.actions) ? node.actions : [];
+        const currentRowFilter = filterCondition !== undefined && conditionText(filterCondition) === "id=id";
+        const matchBy = dataCondition !== undefined
+            ? `dataCondition: ${conditionText(dataCondition)}`
+            : filterCondition !== undefined && !currentRowFilter
+                ? `filterCondition: ${conditionText(filterCondition)}`
+                : "always";
+        const actions = rawActions
+            .filter((action) => !!action && typeof action === "object")
+            .map((action) => {
+            const field = action.targetDataItem ?? action.field ?? action.targetField;
+            const value = action.value ?? action.currentDataItemValue;
+            return {
+                ...(field !== undefined ? { field } : {}),
+                ...(value !== undefined ? { value } : {}),
+                ...(action.ruleValueType !== undefined ? { valueType: action.ruleValueType } : {}),
+                ...(action.ruleActionType !== undefined ? { actionType: action.ruleActionType } : {}),
+            };
+        });
+        return { nodeType: nodeTypeOf(node), matchBy, actions };
+    });
+}
+function nodeTypeOf(node) {
+    return typeof node.nodeType === "string" ? node.nodeType : undefined;
+}
+function conditionText(condition) {
+    if (!condition || typeof condition !== "object")
+        return "always";
+    const value = condition;
+    const groups = Array.isArray(value.conditionGroup) ? value.conditionGroup : Array.isArray(value.mainConditions) ? value.mainConditions : [];
+    const leaves = Array.isArray(groups[0]) ? groups[0] : groups;
+    const text = leaves
+        .filter((leaf) => !!leaf && typeof leaf === "object")
+        .map((leaf) => {
+        const field = leaf.currentSchemaDataItem ?? leaf.targetSchemaDataItem ?? "?";
+        const op = leaf.ruleDataConditionType ?? leaf.ruleConditionType ?? "?";
+        const operators = { EQ: "=", NEQ: "!=", GT: ">", LT: "<", GTEQ: ">=", LTEQ: "<=", CT: "~=", NCT: "!~" };
+        const right = leaf.value
+            ?? (leaf.currentDataItemValue !== undefined ? `{${leaf.currentDataItemValue}}` : undefined)
+            ?? (leaf.targetSchemaDataItem !== undefined ? leaf.currentSchemaDataItem : "?");
+        return `${String(field)}${operators[String(op)] ?? String(op)}${String(right)}`;
+    })
+        .join(" AND ");
+    return text || "always";
+}
 /** 编译 --when/--then DSL 为设计器验证形状的规则图（导出供测试断言）。 */
 export function composeRuleWhenGraph(options) {
-    if (options.when.length === 0)
-        throw new Error("至少给一个 --when 条件；无条件更新整表是 bench23 病灶（空 mainConditions=无条件更新全部行）");
     if (options.then.length === 0)
         throw new Error("至少给一个 --then 动作");
     const leaves = [];
@@ -81,7 +136,7 @@ export function composeRuleWhenGraph(options) {
                     // UPDATE.filterCondition selects rows; it is not an execution gate.
                     // Keep the trigger row as the default target and put --when on the
                     // platform's real execution-gate field (dataCondition).
-                    dataCondition: { conditionGroup: [leaves] },
+                    ...(leaves.length > 0 ? { dataCondition: { conditionGroup: [leaves] } } : {}),
                     filterCondition: { mainConditions: [[{ targetSchemaDataItem: "id", ruleConditionType: "EQ", ruleValueType: "DYNAMIC", currentSchemaDataItem: "id" }]], sheetConditions: [] },
                     dataActions: actions },
                 { nodeCode: "End", nodeType: "END" },
@@ -126,7 +181,7 @@ export async function cmdRuleWhen(args) {
     const name = flag("--name");
     const environment = flag("--env") ?? flag("--environment");
     const apply = args.includes("--apply");
-    const usage = '用法：omc rule-when --schema <模型> --on create|update --when "字段=值" [--when ...可多个,AND] --then "set:字段=值|{来源字段}|{公式}" [--then ...] [--apply]\n触发时机只有 create|update（**没有 submit**；“提交时”用 create 或 update）。条件操作符：= != > < >= <= ~=（包含） !~（不包含）。默认 dry-run；--apply 保存并发布（rule.enable 仍需显式执行）。';
+    const usage = '用法：omc rule-when --schema <模型> --on create|update [--when "字段=值" ...] --then "set:字段=值|{来源字段}|{公式}" [--then ...] [--apply]\n触发时机只有 create|update（**没有 submit**；“提交时”用 create 或 update）。条件操作符：= != > < >= <= ~=（包含） !~（不包含）。省略 --when 表示 always（仍按当前 _input.id 定位，不更新整表）。默认 dry-run；--apply 保存并发布（rule.enable 仍需显式执行）。';
     const invalid = (message) => {
         writeEnvelope(envelope("error", {}, request, { code: "invalid-input", message: `${message}\n${usage}`, retryable: false }));
         return CLI_EXIT_CODES.invalidInput;
@@ -160,8 +215,21 @@ export async function cmdRuleWhen(args) {
     const scopedResult = {
         ...result,
         rowScope,
+        compiled: compiledRuleSummary(result && typeof result.nodeGraph === "object" && result.nodeGraph !== null
+            ? result.nodeGraph
+            : createArgs.nodeGraph),
+        detailReadHint: {
+            detailFile: "cat <detailFile>",
+            detailArtifactId: "omc artifact get <detailArtifactId>",
+        },
     };
     const classified = classifyResult(result);
+    if (apply && classified.status === "ok") {
+        scopedResult.effectiveAfter = {
+            note: "规则保存后生效存在延迟；改数据后以读回的 changedFields 为准，不要以第一次读回判未生效",
+            verifyHint: "同一条 data.update 后 data.load 复核",
+        };
+    }
     writeEnvelope(envelope(classified.status, scopedResult, request, classified.error));
     if (apply && classified.status === "ok")
         process.stderr.write("[omc] 前台生效验证清单（后端通过≠门户生效）：1) omc call rule.enable 启用；2) 造一条命中 --when 的测试数据提交；3) 门户打开该记录核对 --then 字段已变更；4) 再造一条不命中的数据确认不误改；5) 设计器打开本规则确认节点/条件显示正常。\n");