@stalfh233/omc-cli 0.6.2 → 0.6.4

package/dist/lanes/runtime-data.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
-import { FilterDslError, injectPropertyTypes, toQueryCondition } from "../data-list-filter.js";
+import { FilterDslError, injectPropertyTypes, SIMPLE_OP_MAP, toQueryCondition } from "../data-list-filter.js";
 import { ENDPOINTS } from "../endpoints.js";
 import { capabilityArg, environmentArg } from "../args.js";
 import { governedRead } from "../read.js";
@@ -12,6 +12,40 @@ import { CHILD_TABLE_PROPERTY_TYPE, diagnoseApprovalSubmitIdentity, runtimeWrite
 import { getReplayToken, searchWorkItems, wireString } from "../workflow-support.js";
 import { ENGINE_OWNED_KEYS, RUNTIME_DATA_LANE_CONTRACT, RUNTIME_DATA_WIRE, runtimeFormDataArg, } from "./runtime-data-contract.js";
 import { SYSTEM_FIELD_CODES } from "../field-families.js";
+// A2（GitLab #15，2026-11-04）：单选/字典字段（RADIO/CHECKBOX/DROPDOWN_BOX/
+// DROPDOWN_MULTI_BOX）在运行面查询按**字典 key**匹配，不按显示值——按「已审核」
+// 这类显示值过滤会静默 0 条；加 `_key` 后缀的字段名则不在发布元数据里，直接拒。
+// 两个方向都给写法提示，防"total:0 被读成查不到数据"（实测 313 条被误读）。
+const CHOICE_FILTER_PROPERTY_TYPES = new Set([12, 13, 14, 15]);
+function collectConditionLeafFields(condition) {
+    const codes = [];
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            node.forEach(walk);
+            return;
+        }
+        if (node === null || typeof node !== "object")
+            return;
+        const leaf = node;
+        if (typeof leaf.propertyCode === "string" && leaf.propertyCode)
+            codes.push(leaf.propertyCode);
+        Object.values(leaf).forEach(walk);
+    };
+    walk(condition);
+    return [...new Set(codes)];
+}
+function choiceKeySuffixHint(missing, typeByCode) {
+    const bases = missing
+        .filter((code) => code.endsWith("_key"))
+        .map((code) => code.slice(0, -"_key".length))
+        .filter((base) => CHOICE_FILTER_PROPERTY_TYPES.has(typeByCode.get(base) ?? -1));
+    if (bases.length === 0)
+        return "";
+    return `；${bases.join("、")} 是单选/多选（字典来源）字段：列表虽同时返回 code 与 code_key，但过滤要用原字段名 + 字典 key 值（不是 _key 后缀的字段名、也不是显示值）；key 可用 dictionary.names 查，或改 rawCondition 绕过字段元数据校验`;
+}
+function choiceFilterValueHint(fields) {
+    return `total:0 且过滤字段 ${fields.join("、")} 是单选/多选（字典来源）：平台查询按字典 key 匹配而非显示值——若 value 用的是显示值（如「已审核」），换字典 key（如 YSH，dictionary.names 可查）再试；确认确无数据再下「查不到」结论；也可用 rawCondition 或先无过滤查询复核 total`;
+}
 const RUNTIME_LANE = RUNTIME_DATA_LANE_CONTRACT.lane;
 const RUNTIME_TOOLS = RUNTIME_DATA_LANE_CONTRACT.tools;
 /**
@@ -725,6 +759,9 @@ export function registerRuntimeDataLane(tools) {
         lane: RUNTIME_LANE,
         scope: RUNTIME_TOOLS["data.list"].scope,
         description: RUNTIME_TOOLS["data.list"].description,
+        // T3（GitLab #17）：op 的封闭取值来自 DSL 的 SIMPLE_OP_MAP（不是 zod enum——
+        // 那样会抢先拒绝、丢掉带 acceptedOps 的说明性拒绝）。默认 describe 内联一次。
+        paramEnums: { filter: Object.keys(SIMPLE_OP_MAP).join("|") },
         inputSchema: {
             environment: environmentArg,
             schemaCode: z.string().min(1),
@@ -734,7 +771,7 @@ export function registerRuntimeDataLane(tools) {
             // `Expected object, received array`). An array is the caller's AND-list,
             // so accept it and treat it as `filters` rather than costing a retry
             // (dogfood R1 round17).
-            filter: z.union([z.record(z.string(), z.unknown()), z.array(z.record(z.string(), z.unknown()))]).optional().describe('one clause { op, field, value? } (or an array of clauses = AND); op is one of eq, neq, gt, lt, gte, lte, like, notlike, in, notin, between, notbetween, isnull, isnotnull（camelCase 别名 equally valid: equals/notEquals/contains/isNull/isNotNull）'),
+            filter: z.union([z.record(z.string(), z.unknown()), z.array(z.record(z.string(), z.unknown()))]).optional().describe('one clause { op, field, value? } (or an array of clauses = AND); op 取值见过滤语义：eq/neq/gt/lt/gte/lte/like/notlike/in/notin/between/notbetween/isnull/isnotnull（camelCase 别名 equally valid: equals/notEquals/contains/isNull/isNotNull）。**like/contains 是子串包含（String.includes），不是前缀匹配，`%` / `_` 是字面量而非通配符**；按前缀分片请用 gte/lt 区间或更长的前缀+本地去重，别假设 like:"0%" 只命中 0 开头（GitLab #18 P1-3 实测 4 个"前缀分片"互相重叠 2258 条）'),
             filters: z.array(z.record(z.string(), z.unknown())).optional().describe("clauses combined with AND; a malformed clause is refused with blocker invalid-filter-DSL"),
             filterGroup: z.record(z.string(), z.unknown()).optional().describe('nested group { op:"and"|"or", clauses:[clause|group] }'),
             rawCondition: z.unknown().optional(),
@@ -745,7 +782,7 @@ export function registerRuntimeDataLane(tools) {
             showTotal: z.boolean().default(true),
             page: z.number().int().min(0).default(0),
             size: z.number().int().min(1).max(200).default(10),
-            all: z.boolean().optional().describe("true 时自动翻页聚合全部结果（内部按 size=200 逐页拉取，安全上限 1000 行，超出截断并标记 capped）——存量盘点/数据核对用，替代手动循环翻页"),
+            all: z.boolean().optional().describe("true 时自动翻页聚合全部结果（内部按 size=200 逐页拉取，安全上限 1000 行；超过时回 truncated:true + missingCount，别当全集）——存量盘点/数据核对用，替代手动循环翻页。与 page 互斥（all 固定从第 0 页起）"),
             full: z.boolean().optional().describe("内联完整列表结果；默认大结果只返回计数与 detailFile"),
             // r31 (2026-10-31 real machine): agents pass `query: {field: value}` as a
             // filter — zod would STRIP the unknown key silently and the server
@@ -782,13 +819,15 @@ export function registerRuntimeDataLane(tools) {
                         status: "refused",
                         blocker: "invalid-filter-DSL",
                         reason: error.code,
-                        message: `${error.message}；filter 的最小合法形状：{"filter":{"op":"eq","field":"<字段code>","value":"<值>"}}（op 取 eq/neq/gt/lt/gte/lte/like/notlike/in/notin/between/notbetween/isnull/isnotnull）；多条件用 filters:[clause,…]（AND）或 filterGroup:{op:"and"|"or",clauses:[…]}。可运行示例：describe data.list --example list-filter-equality`,
+                        message: `${error.message}；filter 的最小合法形状：{"filter":{"op":"eq","field":"<字段code>","value":"<值>"}}（op 取 eq/neq/gt/lt/gte/lte/like/notlike/in/notin/between/notbetween/isnull/isnotnull；like/contains 是**子串包含**、% 非通配）。多条件用 filters:[clause,…]（AND）或 filterGroup:{op:"and"|"or",clauses:[…]}。可运行示例：describe data.list --example list-filter-equality`,
                         minimalValidFilter: { filter: { op: "eq", field: "<fieldCode>", value: "<value>" } },
                         acceptedOps: ["eq", "neq", "gt", "lt", "gte", "lte", "like", "notlike", "in", "notin", "between", "notbetween", "isnull", "isnotnull"],
                     };
                 throw error;
             }
             return governedRead(ctx, self, args, async (session) => {
+                // A2：DSL 过滤命中的单选/字典字段（total:0 时给值写法提示）
+                let choiceFilterFields = [];
                 // Published field metadata is the sole source for filter propertyType
                 // injection AND for the projectionHint below. Fetch at most once per
                 // call: the DSL path needs it up front; the hint path asks only after
@@ -813,9 +852,27 @@ export function registerRuntimeDataLane(tools) {
                             status: "refused",
                             blocker: "unknown-filter-field",
                             missing: injected.missing,
-                            message: `filter fields not found in published field metadata: ${injected.missing.join(", ")}; the runtime query requires each leaf's propertyType from field metadata (no guessing); system/foreign fields may use rawCondition`,
+                            message: `filter fields not found in published field metadata: ${injected.missing.join(", ")}; the runtime query requires each leaf's propertyType from field metadata (no guessing); system/foreign fields may use rawCondition` + choiceKeySuffixHint(injected.missing, typeByCode),
                         };
                     condition = injected.condition;
+                    // A2（GitLab #15）：单选/字典字段按显示值过滤会静默 0 条（平台查询按
+                    // 字典 key 匹配）。带出这些字段，total:0 时给写法提示，防"查不到数据"
+                    // 误报（实测 313 条被 total:0 误读成"今天没有已审核单"）。
+                    choiceFilterFields = collectConditionLeafFields(condition).filter((code) => CHOICE_FILTER_PROPERTY_TYPES.has(typeByCode.get(code) ?? -1));
+                    // P1-4（GitLab #18，2026-11-04）：子表字段（CHILD_TABLE=8）的值是行数组，
+                    // 运行面 query/list 只做标量过滤——拿它当 filter 字段会回一个没有明细的
+                    // errcode 50000「服务异常」，被读成"平台挂了"。元数据已证它是子表，就在
+                    // 发查询前拒绝并给替代路径（data.load 读主表后看子表数组）。
+                    const childTableFields = collectConditionLeafFields(condition).filter((code) => typeByCode.get(code) === CHILD_TABLE_PROPERTY_TYPE);
+                    if (childTableFields.length > 0)
+                        return {
+                            status: "refused",
+                            blocker: "unsupported-filter-on-child-table",
+                            schemaCode: args.schemaCode,
+                            fields: childTableFields,
+                            message: `这些字段是子表（propertyType=${CHILD_TABLE_PROPERTY_TYPE}，值是行数组）：运行面 query/list 只支持标量过滤，按子表字段过滤会回 errcode 50000 且无明细。改法：用 data.load 读主表记录（子表行随主记录返回），或在本地按子表字段筛选。`,
+                            nextCommand: `omc call data.load --env <env> --args '{"schemaCode":"${args.schemaCode}","bizObjectId":"<主表 bizObjectId>"}'`,
+                        };
                 }
                 const requestedFields = args.displayFields ?? args.columns;
                 const fields = requestedFields && requestedFields.length > 0 ? requestedFields : undefined;
@@ -835,12 +892,23 @@ export function registerRuntimeDataLane(tools) {
                 if (args.all === true) {
                     const CAP = 1000;
                     const pageSize = 200;
+                    // GitLab #18 P1-2: `all:true` is "aggregate from page 0 up to the cap".
+                    // A caller who ALSO passed page expected server-side paging, got page 0
+                    // silently (page:6 → 0 rows, read as "no data"). Refuse the combo
+                    // instead of guessing which one they meant.
+                    if ((args.page ?? 0) !== 0)
+                        throw new ToolInputError({
+                            status: "error",
+                            blocker: "invalid-input",
+                            tool: "data.list",
+                            message: `all:true 与 page 互斥：all 固定从第 0 页聚合到上限 ${CAP} 行；要指定页请去掉 all（page/size 手动翻页），要全集请用 filters 分片。`,
+                        });
                     const firstBody = { ...body, page: 0, size: pageSize };
                     const first = await wireCall(session, { path: ENDPOINTS.runtimeQueryList, method: "POST", body: firstBody });
                     const firstPage = extractBizObjectPage(first.data);
                     const total = Number(firstPage.total ?? 0);
                     if (total === 0 || firstPage.content.length === 0)
-                        return { schemaCode: args.schemaCode, total: 0, page: "all", size: 0, pagesFetched: 0, items: [] };
+                        return { schemaCode: args.schemaCode, total: 0, page: "all", size: 0, pagesFetched: 0, items: [], ...(choiceFilterFields.length > 0 ? { filterValueHint: choiceFilterValueHint(choiceFilterFields) } : {}) };
                     const rows = [...firstPage.content];
                     const target = Math.min(total, CAP);
                     let pageIndex = 1;
@@ -852,15 +920,57 @@ export function registerRuntimeDataLane(tools) {
                         rows.push(...nextPage.content);
                         pageIndex += 1;
                     }
-                    const capped = rows.length > CAP;
-                    const items = (capped ? rows.slice(0, CAP) : rows).map((row0) => {
+                    // 翻页按 size=200 走，最后一页可能越过 total（total=999 会拉到 1000 行）；
+                    // 先按 total 夹一次，itemsCount/items.length 才与 total 可比。
+                    const collected = rows.length > total ? rows.slice(0, total) : rows;
+                    // GitLab #18 P1-2：`capped = rows.length > CAP` 是死代码——target 已被
+                    // Math.min(total, CAP) 夹住，rows 永远到不了 CAP+1，于是 total>1000 时
+                    // 返回「total:1043 / items:1000 / 无任何标记」，43 条静默消失（实测被
+                    // 读成"数据就这么多"）。真正的截断判据是「拿到的比总量少」。
+                    const truncatedByCap = collected.length < total;
+                    const items = collected.map((row0) => {
                         const row = row0;
                         const rawData = row.data && typeof row.data === "object" ? row.data : {};
                         const data = args.full === true ? rawData : compactRuntimeRecord(rawData);
                         const selected = fields ?? Object.keys(data).filter((field) => !["id", "bizObjectId", "schemaCode", "sequenceStatus", "createdTime", "updatedTime", "creator", "updater"].includes(field));
                         return { id: row.bizObjectId ?? row.id ?? data.id, fields: Object.fromEntries(selected.map((field) => [field, data[field] ?? null])) };
                     });
-                    return { schemaCode: args.schemaCode, total, page: "all", size: rows.length, pagesFetched: pageIndex, ...(capped ? { capped: true, capNotice: `结果超过安全上限 ${CAP}，已截断；请加 filters 分批` } : {}), items };
+                    // A6（GitLab #15）：all:true 路径此前完全没有 projectionHint——未配置列
+                    // 的 null/省略同样要点名，防「全量拉取却被投影坑」（实测 orderChange）。
+                    let allHint;
+                    if (items.length > 0) {
+                        try {
+                            const typeByCode = await publishedTypeByCode();
+                            const returnedKeys = new Set(Object.keys(items[0]?.fields ?? {}));
+                            const hintColumns = [...typeByCode.keys()].filter((field) => !SYSTEM_FIELD_CODES.has(field) && (!returnedKeys.has(field) || items.every((item) => item.fields[field] === null)));
+                            if (hintColumns.length > 0)
+                                allHint = `这些列在默认视图未配置（值可能存在但列表投影为 null 或整列省略）：${hintColumns.join("、")}；先用 listview.configure 配置列，或用 data.load 读单条权威值`;
+                        }
+                        catch {
+                            // 元数据读失败不阻断数据返回
+                        }
+                    }
+                    return {
+                        schemaCode: args.schemaCode,
+                        total,
+                        page: "all",
+                        size: collected.length,
+                        pagesFetched: pageIndex,
+                        // 形状常量：脚本按 result.items 取数（与内联态一致），itemsCount 与
+                        // total 的差就是被截断的条数——不再只靠 size 反推。
+                        itemsCount: collected.length,
+                        ...(truncatedByCap
+                            ? {
+                                truncated: true,
+                                capped: true,
+                                cap: CAP,
+                                missingCount: total - collected.length,
+                                capNotice: `已取前 ${collected.length} 条 / 共 ${total} 条（安全上限 ${CAP}）——还差 ${total - collected.length} 条没返回。不要把它当全集：加 filters 分片（如按日期/业务键）分别拉取，或去掉 all 用 page/size 手动翻页。`,
+                            }
+                            : {}),
+                        ...(allHint ? { projectionHint: allHint } : {}),
+                        items,
+                    };
                 }
                 let result;
                 try {
@@ -868,7 +978,7 @@ export function registerRuntimeDataLane(tools) {
                 }
                 catch (error) {
                     if (error instanceof WireError && error.kind === "business" && error.errcode === RUNTIME_DATA_WIRE.emptyModelErrcode) {
-                        return { schemaCode: args.schemaCode, total: 0, totalPages: 0, page: args.page ?? 0, size: args.size ?? 10, items: [] };
+                        return { schemaCode: args.schemaCode, total: 0, totalPages: 0, page: args.page ?? 0, size: args.size ?? 10, items: [], ...(choiceFilterFields.length > 0 ? { filterValueHint: choiceFilterValueHint(choiceFilterFields) } : {}) };
                     }
                     // r30: a MISSING model answers this face with a generic 50000
                     // 服务异常 — indistinguishable from a real outage. One field-face
@@ -890,6 +1000,13 @@ export function registerRuntimeDataLane(tools) {
                             }
                         }
                     }
+                    // P1-4：其余 50000 保持原样抛出（真服务异常必须照实暴露），但给一条
+                    // 不改判定的排查提示——子表/子表 schema 的过滤与系统字段过滤是这个面
+                    // 最常见的"服务异常"来源（live: 子表 schema 加 parentId 过滤 → 50000，
+                    // 去掉 filter 就正常）。只加 hint，不猜 blocker。
+                    if (error instanceof WireError && error.kind === "business" && error.errcode === 50000) {
+                        throw new WireError(error.kind, error.message, error.errcode, error.diagnostic, `若 filter/filters 里含子表字段或子表自身 schema 的 parentId 等系统字段：运行面 query/list 的标量过滤不适用于子表，去掉 filter 后按主表 id 用 data.load 读子表行。其余情况按真服务异常处理（同一 schemaCode 去掉 filter 可读即说明是过滤形状问题）。`);
+                    }
                     throw error;
                 }
                 const page = extractBizObjectPage(result.data);
@@ -921,6 +1038,7 @@ export function registerRuntimeDataLane(tools) {
                     // (live 2026-10-18: total:0 was read as "no residue" while 9 drafts
                     // existed).
                     filter: { excludedDraft: true, hint: "默认不含 DRAFT（total 亦仅计非草稿）；核对/清理残留请加 all:true" },
+                    ...(choiceFilterFields.length > 0 && Number(page.total ?? 0) === 0 ? { filterValueHint: choiceFilterValueHint(choiceFilterFields) } : {}),
                     totalPages: page.totalPages,
                     page: page.page ?? args.page ?? 0,
                     size: page.size ?? args.size ?? 20,
@@ -942,6 +1060,26 @@ export function registerRuntimeDataLane(tools) {
                     const typeByCode = await publishedTypeByCode();
                     return candidates.filter((field) => typeByCode.has(field));
                 };
+                // A6（GitLab #15，2026-11-04）：未配置列有两种投影形态——值为 null，或
+                // **整键省略**（orderChange 实测：sequenceNo 在 data.list 里根本不出现，
+                // data.load 却有值，被误读成「单号为空」）。省略检测需要发布元数据
+                // （fieldList 有 60s wire 缓存，DSL 过滤路径本就已取）；两种形态合并进 hint。
+                const projectionHintFor = async () => {
+                    if (items.length === 0)
+                        return undefined;
+                    const typeByCode = await publishedTypeByCode();
+                    const returnedKeys = new Set(Object.keys(items[0]?.fields ?? {}));
+                    const nullColumns = fields && fields.length > 0
+                        ? fields.filter((field) => typeByCode.has(field) && items.every((item) => item.fields[field] === null))
+                        : [...returnedKeys].filter((field) => !SYSTEM_FIELD_CODES.has(field) && typeByCode.has(field) && items.every((item) => item.fields[field] === null));
+                    const omittedColumns = !fields
+                        ? [...typeByCode.keys()].filter((field) => !SYSTEM_FIELD_CODES.has(field) && !returnedKeys.has(field))
+                        : [];
+                    const hintColumns = [...new Set([...nullColumns, ...omittedColumns])];
+                    if (hintColumns.length === 0)
+                        return undefined;
+                    return `这些列在默认视图未配置（值可能存在但列表投影为 null 或整列省略）：${hintColumns.join("、")}；先用 listview.configure 配置列，或用 data.load 读单条权威值`;
+                };
                 if (fields &&
                     fields.length > 0 &&
                     items.length > 0 &&
@@ -955,9 +1093,9 @@ export function registerRuntimeDataLane(tools) {
                     // business fields absent from the list view render as null in every
                     // row with no explanation. Name the null'd business columns so the
                     // agent reads data.load instead of misdiagnosing "data lost".
-                    const nullColumns = await businessNullColumns();
-                    if (nullColumns.length > 0)
-                        readback.projectionHint = `这些列在默认视图未配置（值可能存在但列表投影为 null）：${nullColumns.join("、")}；先用 listview.configure 配置列，或用 data.load 读单条权威值`;
+                    const hint = await projectionHintFor();
+                    if (hint)
+                        readback.projectionHint = hint;
                 }
                 return readback;
             }, { full: args.full === true, target: `data.list:${JSON.stringify({ schemaCode: args.schemaCode, queryCode: args.queryCode ?? args.schemaCode, filter: args.filter, filters: args.filters, filterGroup: args.filterGroup, rawCondition: args.rawCondition, displayFields: args.displayFields, columns: args.columns, page: args.page ?? 0, size: args.size ?? 10 })}` });
@@ -974,8 +1112,8 @@ export function registerRuntimeDataLane(tools) {
             environment: environmentArg,
             schemaCode: z.string(),
             bizObjectId: z.string({ required_error: "bizObjectId 必填（参数名就是 bizObjectId——不是 id 也不是 objectId，r44 两个 agent 都猜了 objectId；取值来自 data.submit 读回的 objectId/sequenceNo 或 data.list 的 row.bizObjectId）" }),
-            full: z.boolean().optional().describe("返回未裁剪的完整业务对象（含 owner/creater 等系统字段；默认返回业务字段+身份的精简记录）"),
-            fields: z.array(z.string().min(1)).optional().describe("只保留列出的字段——核验状态时传 [\"sequenceStatus\",\"<业务状态字段>\"]，别整条 data.load（r4-training 2026-10-20：同一对象被读 74 次）；缺失字段回在 missingFields"),
+            full: z.boolean().optional().describe("返回未裁剪的完整业务对象（含 owner/creater 等系统字段；默认返回业务字段+身份的精简记录）。整条大对象（百 KB 级）会被外置成 artifact——只需要几列时改用 fields"),
+            fields: z.array(z.string().min(1)).optional().describe("列投影：只保留列出的字段——核验状态时传 [\"sequenceStatus\",\"<业务状态字段>\"]，别整条 data.load（r4-training 2026-10-20：同一对象被读 74 次）；缺失字段回在 missingFields。这是本地裁剪、在 artifact 外置**之前**生效，所以只取 9 列不会先拉整包（GitLab #17 T5）。平台 form/load 无列参数，投影只能在这一层做"),
             capability: capabilityArg,
         },
         handler: async (ctx, args, self) => {

package/dist/path-projection.js

@@ -105,21 +105,23 @@ export function projectJsonPathFanout(value, path) {
     if (marker < 0) {
         const projected = projectJsonPath(value, path);
         return projected.missed
-            ? { values: [], missed: true, ...(projected.at !== undefined ? { at: projected.at } : {}), ...(projected.available !== undefined ? { available: projected.available } : {}), missedEntries: 0 }
-            : { values: [projected.value], missed: false, missedEntries: 0 };
+            ? { values: [], missed: true, ...(projected.at !== undefined ? { at: projected.at } : {}), ...(projected.available !== undefined ? { available: projected.available } : {}), missedEntries: 0, nullEntries: 0 }
+            : { values: [projected.value], missed: false, missedEntries: 0, nullEntries: projected.value === null ? 1 : 0 };
     }
     const before = path.slice(0, marker);
     const after = path.slice(marker + 2).replace(/^[./]+/, "");
     const base = projectJsonPath(value, before);
     if (base.missed)
-        return { values: [], missed: true, ...(base.at !== undefined ? { at: base.at } : {}), ...(base.available !== undefined ? { available: base.available } : {}), missedEntries: 0 };
+        return { values: [], missed: true, ...(base.at !== undefined ? { at: base.at } : {}), ...(base.available !== undefined ? { available: base.available } : {}), missedEntries: 0, nullEntries: 0 };
     if (!Array.isArray(base.value))
-        return { values: [], missed: true, at: before || "$", available: `该层不是数组（是 ${base.value === null ? "null" : typeof base.value}）；[] 只能映射数组，如 items[].fields.planNo`, missedEntries: 0 };
+        return { values: [], missed: true, at: before || "$", available: `该层不是数组（是 ${base.value === null ? "null" : typeof base.value}）；[] 只能映射数组，如 items[].fields.planNo`, missedEntries: 0, nullEntries: 0 };
     const values = [];
     let missedEntries = 0;
+    let nullEntries = 0;
     for (const entry of base.value) {
         const projected = projectJsonPathFanout(entry, after);
         values.push(...projected.values);
+        nullEntries += projected.nullEntries;
         if (projected.missed)
             missedEntries += 1;
     }
@@ -127,9 +129,9 @@ export function projectJsonPathFanout(value, path) {
     // array) — report the miss so the caller does not read an empty list as data.
     if (values.length === 0 && missedEntries > 0) {
         const first = projectJsonPathFanout(base.value[0], after);
-        return { values: [], missed: true, ...(first.at !== undefined ? { at: `${before}[].${first.at}` } : {}), ...(first.available !== undefined ? { available: first.available } : {}), missedEntries };
+        return { values: [], missed: true, ...(first.at !== undefined ? { at: `${before}[].${first.at}` } : {}), ...(first.available !== undefined ? { available: first.available } : {}), missedEntries, nullEntries: 0 };
     }
-    return { values, missed: false, ...(missedEntries > 0 ? { missedEntries } : { missedEntries: 0 }) };
+    return { values, missed: false, ...(missedEntries > 0 ? { missedEntries } : { missedEntries: 0 }), nullEntries };
 }
 /** Collect every value of a repeatable flag (`--extract a --extract b`). */
 function argvValues(args, name) {
@@ -144,7 +146,14 @@ function argvValues(args, name) {
     return values;
 }
 /** Shared wording for every projection miss, so all three faces teach the same syntax. */
-const PATH_MISS_HINT = "路径未命中（这一层没有该段）。可用写法：点式 a.b、下标 a[0]、切片 a[0:6]、数组映射 items[].fields.x、按键选择 rules[code=Create] 或 data.activities[code=A1]（数组与 index→条目对象都支持；键名可省 activityCode/nodeCode 等别名；返回第一个匹配项）。available 是该层真实存在的键。";
+const PATH_MISS_HINT = "路径未命中（这一层没有该段）。可用写法：点式 a.b、下标 a[0]、切片 a[0:6]、数组映射 items[].fields.x、按键选择 rules[code=Create] 或 data.activities[code=A1]（数组与 index→条目对象都支持；键名可省 activityCode/nodeCode 等别名；返回第一个匹配项）。available 是该层真实存在的键。注意：本参数是路径选择器、不是 jq 语言（不支持 | 管道与对象构造）；一次取多列用逗号分隔（--jq \"a.b,c.d\"）或重复传 --jq。";
+/**
+ * T6（GitLab #17）：`mapped` 只是"路径命中的条目数"，值为 null 也算命中。
+ * 全 null + ok:true 曾被读成"取到了 N 个值/台账只有 1 行"（真实 42 行）。
+ * 提示里把两种成因分开说：未投影（看 data.list 的 projectionHint / data.load）
+ * 与字段本身为空。
+ */
+const ALL_NULL_HINT = `路径全部命中但值都是 null——注意 mapped 只是命中条目数，不代表有值。常见成因是列表投影没配置该列（data.list 只投影视图列，null 或整键省略；看同一次 data.list 的 projectionHint，或用 data.load 读单条权威值）。若 projectionHint 也指向该列，就不是"字段为空"。`;
 /**
  * `call --extract/--extract-keys`: resolve paths inside the result's own
  * artifact (or inside the result object when the tool returned no artifact).
@@ -186,6 +195,14 @@ export function projectResultExtract(result, paths, keysOnly) {
         ...(artifactId !== undefined ? { artifactId, sha256: artifact?.sha256 } : {}),
         from: readFromArtifact ? "artifact" : "result",
     };
+    // T6：列表投影里「未配置的列」也是 null 键——工具自己已经写了 projectionHint
+    // （#15 A6），但投影层此前把它丢了，于是 `--jq items[].fields.x` 全 null 时
+    // 调用方看不到任何线索。把源结果的提示原样透传（有才带，零额外体积）。
+    const sourceProjectionHint = source && typeof source === "object" && !Array.isArray(source) && typeof source.projectionHint === "string"
+        ? source.projectionHint
+        : undefined;
+    if (sourceProjectionHint !== undefined)
+        out.projectionHint = sourceProjectionHint;
     if (keysOnly) {
         const record = source && typeof source === "object" && !Array.isArray(source) ? source : undefined;
         out.keys = record
@@ -203,7 +220,14 @@ export function projectResultExtract(result, paths, keysOnly) {
                 const fanout = projectJsonPathFanout(source, path);
                 return fanout.missed
                     ? { path, content: null, pathMiss: true, missedAt: fanout.at, available: fanout.available, missedEntries: fanout.missedEntries, hint: PATH_MISS_HINT }
-                    : { path, content: fanout.values, mapped: fanout.values.length, ...(fanout.missedEntries > 0 ? { missedEntries: fanout.missedEntries, hint: `有 ${fanout.missedEntries} 条记录在该路径下缺失，values 只含命中项` } : {}) };
+                    : {
+                        path,
+                        content: fanout.values,
+                        mapped: fanout.values.length,
+                        ...(fanout.nullEntries > 0 ? { nullEntries: fanout.nullEntries } : {}),
+                        ...(fanout.nullEntries > 0 && fanout.nullEntries === fanout.values.length ? { hint: ALL_NULL_HINT } : {}),
+                        ...(fanout.missedEntries > 0 ? { missedEntries: fanout.missedEntries, hint: `有 ${fanout.missedEntries} 条记录在该路径下缺失，values 只含命中项` } : {}),
+                    };
             }
             const projected = projectJsonPath(source, path);
             return projected.missed

package/dist/read.js

@@ -54,7 +54,7 @@ export async function governedRead(ctx, tool, args, execute, options = {}) {
         const targetFingerprint = sha256(result);
         const cached = ctx.readbackCache.get(target);
         if (ctx.readbackCacheBypass === 0 && cached && cached.environmentFingerprint === environmentFingerprint && cached.targetFingerprint === targetFingerprint && options.full !== true)
-            return { status: "ok", unchanged: true, detailFile: cached.detailFile, detailSha256: cached.detailSha256, environmentFingerprint };
+            return { status: "ok", unchanged: true, detailFile: cached.detailFile, detailSha256: cached.detailSha256, ...(cached.shapePlaceholders ?? {}), environmentFingerprint };
         const detail = { status: "ok", ...result, environmentFingerprint };
         // 2026-11-01 预算批 v2（r38 usage 实证）：1-4KB 中结果 59 次/135KB≈37% 全内联，
         // model.inspect 17 次全部卡在旧门下。降到 2048；compact 对配置清单保形为码表
@@ -62,19 +62,26 @@ export async function governedRead(ctx, tool, args, execute, options = {}) {
         const large = jsonBytes(result) > 2048;
         const fileName = `${tool.name.replace(/[^a-zA-Z0-9._-]/g, "_")}-${sha256(target).slice(0, 16)}.json`;
         const artifactRef = writeArtifact(ctx, fileName, detail);
-        ctx.readbackCache.set(target, { environmentFingerprint, targetFingerprint, detailFile: artifactRef.detailFile, detailSha256: artifactRef.detailSha256 });
+        const cacheEntry = { environmentFingerprint, targetFingerprint, detailFile: artifactRef.detailFile, detailSha256: artifactRef.detailSha256 };
         if (options.full === true) {
             const rawBytes = jsonBytes(result);
             // Small raw bodies keep the old inline behaviour; large ones are dieted
             // (see FULL_INLINE_CEILING_BYTES). The raw body stays fully reachable via
             // the artifact, so no capability is lost — only the inline copy is skipped.
-            if (rawBytes <= FULL_INLINE_CEILING_BYTES)
+            if (rawBytes <= FULL_INLINE_CEILING_BYTES) {
+                ctx.readbackCache.set(target, cacheEntry);
                 return { ...detail, detailFile: artifactRef.detailFile, detailSha256: artifactRef.detailSha256 };
+            }
             const compact = options.compact ? options.compact(result, session) : compactReadback(result);
+            // A1：外置与内联同形——被折叠的 payload 键补回空占位；缓存同样记占位，
+            // unchanged 二次读回时不丢形状（GitLab #15）。
+            const placeholders = externalizedShapePlaceholders(result, droppedShapeKeys(result, compact));
+            ctx.readbackCache.set(target, { ...cacheEntry, shapePlaceholders: placeholders });
             return {
                 status: "ok",
-                ...passthroughScalars(result),
+                ...passthroughScalars(result, omittedScalarKeys(compact)),
                 ...compact,
+                ...placeholders,
                 full: true,
                 fullOmitted: true,
                 fullBytes: rawBytes,
@@ -84,19 +91,39 @@ export async function governedRead(ctx, tool, args, execute, options = {}) {
                 detailSha256: artifactRef.detailSha256,
             };
         }
-        if (!large)
+        if (!large) {
+            ctx.readbackCache.set(target, cacheEntry);
             return { status: "ok", ...result, environmentFingerprint };
+        }
         const compact = options.compact ? options.compact(result, session) : compactReadback(result);
-        return { status: "ok", ...passthroughScalars(result), ...compact, environmentFingerprint, detailFile: artifactRef.detailFile, detailSha256: artifactRef.detailSha256 };
+        const placeholders = externalizedShapePlaceholders(result, droppedShapeKeys(result, compact));
+        ctx.readbackCache.set(target, { ...cacheEntry, shapePlaceholders: placeholders });
+        return { status: "ok", ...passthroughScalars(result, omittedScalarKeys(compact)), ...compact, ...placeholders, environmentFingerprint, detailFile: artifactRef.detailFile, detailSha256: artifactRef.detailSha256 };
     }
     catch (error) {
         if (isUncertainWireError(error))
             return { status: "uncertain", frozen: true, reason: `wire-transport:${wireErrorKind(error)}`, detail: error.message };
         if (error instanceof WireError)
-            return { status: "refused", blocker: `wire-${error.kind}`, errcode: error.errcode, message: error.message, ...(error.diagnostic ? { diagnostic: error.diagnostic } : {}) };
+            return { status: "refused", blocker: `wire-${error.kind}`, errcode: error.errcode, message: error.message, ...(error.diagnostic ? { diagnostic: error.diagnostic } : {}), ...(error.hint ? { hint: error.hint } : {}) };
         throw error;
     }
 }
+/**
+ * A1（GitLab #15，2026-11-04）：外置结果与内联同形。compact 把 BULKY_READ_KEYS
+ * （items/data/…）折叠成 `*Count` 后，按内联形状取数的脚本读 `result.items` /
+ * `result.data` 直接 TypeError——外置只是把数据搬进 artifact，不应改变返回形状。
+ * 被折叠的键补回为空占位（原值是数组→[]，否则 null）并标记 truncatedKeys；
+ * 真实数据在 detailFile 指向的 artifact 里，根键与内联一致（list=items、load=data）。
+ */
+function externalizedShapePlaceholders(result, dropped) {
+    const placeholders = { truncatedKeys: [...dropped], truncated: true };
+    for (const key of dropped)
+        placeholders[key] = Array.isArray(result[key]) ? [] : null;
+    return placeholders;
+}
+function droppedShapeKeys(result, payload) {
+    return Object.keys(result).filter((key) => BULKY_READ_KEYS.has(key) && !(key in payload));
+}
 function compactReadback(result) {
     const compact = {};
     for (const [key, value] of Object.entries(result)) {
@@ -181,10 +208,10 @@ const BULKY_READ_KEYS = new Set(["data", "nodes", "routes", "items", "rules", "a
  * `result.workflowCode` got `undefined` (round 10: live demo). Pass the scalar
  * (non-bulky) top-level keys through; the compact's own keys still win.
  */
-function passthroughScalars(result) {
+function passthroughScalars(result, omit = []) {
     const carried = {};
     for (const [key, value] of Object.entries(result)) {
-        if (key === "status" || BULKY_READ_KEYS.has(key))
+        if (key === "status" || BULKY_READ_KEYS.has(key) || omit.includes(key))
             continue;
         const type = typeof value;
         if (value === null || type === "string" || type === "number" || type === "boolean")
@@ -192,6 +219,32 @@ function passthroughScalars(result) {
     }
     return carried;
 }
+/**
+ * T1（GitLab #17）：某个工具的自定义 compact 用 `<key>Omitted` 显式声明"这段正文
+ * 已外置"（form.get 的六份布局 JSON 是大**字符串**，不是 BULKY_READ_KEYS 里的
+ * 数组/对象）。passthroughScalars 会把所有字符串原样带回来，正好把外置又抵消掉
+ * （42KB 读回里 41KB 是刚声明省略的布局）。这里把省略声明翻译成跳过名单。
+ *
+ * 白名单化（审查 2026-11-04）：只认 form 的六个布局面。否则任何 compact 恰好
+ * 产出的 `<key>Omitted:true`（如 `fullOmitted` → 派生 omit=`full`）都会误删同名
+ * 标量，靠后续展开掩盖太脆。
+ */
+const EXTERNALIZED_SCALAR_KEYS = new Set([
+    "draftViewJson",
+    "draftAttributesJson",
+    "draftHtmlJson",
+    "draftActionsJson",
+    "publishedViewJson",
+    "publishedAttributesJson",
+    "publishedHtmlJson",
+    "publishedActionsJson",
+]);
+function omittedScalarKeys(compact) {
+    return Object.keys(compact)
+        .filter((key) => key.endsWith("Omitted") && compact[key] === true)
+        .map((key) => key.slice(0, -"Omitted".length))
+        .filter((key) => EXTERNALIZED_SCALAR_KEYS.has(key));
+}
 function safeFingerprint(session) {
     try {
         return session.environmentFingerprint();

package/dist/recipes/businessrule.js

@@ -167,6 +167,88 @@ const ruleTimingTask = Object.freeze({
     ],
     requiresEnvironmentDerivedIds: false,
 });
+const ruleTimingBizService = Object.freeze({
+    id: "rule-timing-bizservice",
+    title: "定时任务：定时调用业务方法（SCHEDULER-only 图 + BIZ_SERVICE，生产 106 条实证形状）",
+    aliases: ["定时调服务", "定时调接口", "定时调用方法", "BIZ_SERVICE", "定时调方法"],
+    status: "requires-prior-readback",
+    tool: "rule.save",
+    args: {
+        environment,
+        schemaCode: model,
+        ruleCode: "<customRuleCode e.g. nightly_ledger_rebuild>",
+        name: "每日台账重建",
+        nodeGraph: {
+            bizRuleType: 2,
+            // 与 rule-timing-task 的关键差异：**无动作节点**——方法挂在 schedulerSetting
+            // 上，不是 SCHEDULER 后面再接 UPDATE/BIZ_ACTION。生产 106 条「定时调服务」
+            // 全部是这个形状（Start → SCHEDULER → End）。
+            nodes: [
+                { nodeCode: "Start", nodeName: "开始", nodeType: "START" },
+                { nodeCode: "SCHEDULER", nodeName: "定时作业", nodeType: "SCHEDULER", isSystemNode: true, nodeCategory: "systemNode" },
+                { nodeCode: "End", nodeName: "结束", nodeType: "END" },
+            ],
+            routes: [
+                { preNode: "Start", postNode: "SCHEDULER", routeCondition: true },
+                { preNode: "SCHEDULER", postNode: "End", routeCondition: true },
+            ],
+            schedulerSetting: {
+                triggerTimeType: "SELECTED_TIME",
+                cycleType: "DAY",
+                executeType: "CYCLE",
+                execCycle: 1,
+                hour: 2,
+                minute: 0,
+                second: 0,
+                startTime: "<yyyy-MM-dd HH:mm:ss，未来时刻>",
+                endType: "NEVER",
+                // 定时调用业务集成方法：以方法为数据源，调度到点直接调用。
+                dataSourceType: "BIZ_SERVICE",
+                // methodCode 是**应用编码（appCode）**，不是方法 code——serviceCode+
+                // serviceMethodCode 定位方法，methodCode 定位应用。缺它：8.6 create 容忍、
+                // 8.1 update 回无明细 50000 且 enable 只翻 status 不翻 enabled
+                // （2026-11-03 issue A7/A8 实证；写前 gate 会直接拒绝缺失形态）。
+                methodMapping: {
+                    schemaCode: model,
+                    serviceCode: "<已注册服务 code>",
+                    serviceMethodCode: "<方法 code>",
+                    methodCode: "<应用编码 appCode>",
+                    inputMappings: [
+                        { serviceMethodParameterCode: "<参数 code，与方法声明逐字一致>", codeType: 0, bizCode: "<常量值>", required: false },
+                    ],
+                },
+                latestVersion: true,
+                consolidation: false,
+            },
+        },
+        publish: true,
+    },
+    preconditions: [
+        "目标业务集成服务与方法**已注册且已发布**（service.list / service.get 核对）",
+        "`methodCode`（应用编码）已知——不确定时先 `rule.get --keys schedulerSetting` 一条同族生产定时规则对照 methodMapping 形状",
+        "本环境需 `cloudpivot.task.enabled=true`（否则平台不建调度任务）",
+    ],
+    conditionalRequirements: [
+        "**不要**套用 `rule-timing-task`（GET_LIST + UPDATE 动作节点）的形状——那是「定时改数据」，本配方是「定时调方法」；两者 schedulerSetting.dataSourceType 与节点图都不同。",
+        "`methodMapping.inputMappings[]` 的 `serviceMethodParameterCode` 必须与方法声明的参数 code 逐字一致（method.get 读参数面核对，readbackCaveat 出现时以 inputParametersFromList 为准）；无参方法传 `[]`。",
+        "`latestVersion` 必须 true（false 走旧 builder → publish/update 50000，与 rule-timing-task 同坑）。",
+        "保存≠生效：`rule.save` 后必须 `rule.enable`；enable 回成功但 DB `enabled` 仍为 0 = 实体残缺（methodCode 缺失/options 空串），回 rule.save 修实体，不是重试 enable。",
+    ],
+    priorToolReferences: [
+        { tool: "service.list", args: { environment }, purpose: "确认服务已注册" },
+        { tool: "method.get", args: { environment, serviceCode: "<svc>", methodCode: "<method>" }, purpose: "读参数面拿 serviceMethodParameterCode（readbackCaveat.parametersUnreadable 出现时以 inputParametersFromList 为准）" },
+        { tool: "rule.get", args: { environment, schemaCode: model, ruleCode: "<同族生产规则>", keys: ["schedulerSetting"] }, purpose: "不确定 methodMapping 形状时对照生产实证形状" },
+    ],
+    dryRun: { supported: true, command: `omc call rule.save --env ${environment} --dry-run --args '<recipe.args>'`, notes: "dry-run 跑图校验 + BIZ_SERVICE 写前 gate（methodMapping 三键非空），不写不发布" },
+    expectedReadback: { readback: { published: true, enabled: false, next: "rule.enable；到点后以平台日志/方法侧效果核验，不认返回值" } },
+    refusalRecovery: [
+        { code: "rule-scheduler-bizservice-mapping", action: "dataSourceType:BIZ_SERVICE 必须带 methodMapping{serviceCode,serviceMethodCode,methodCode}；methodCode 是应用编码（appCode）。对照 rule.get 的生产规则形状补齐" },
+        { code: "rule-name-invalid", action: "规则名仅支持中文/字母/数字、≤50 字符（平台设计器约束）" },
+        { code: "rule-graph-scheduler-setting-shape", action: "schedulerSetting 必须是 nodeGraph.schedulerSetting 上的对象，不是 SCHEDULER 节点字段" },
+        ...commonRecovery,
+    ],
+    requiresEnvironmentDerivedIds: true,
+});
 const dataDuplicateFlag = Object.freeze({
     id: "data-duplicate-flag",
     title: "字段唯一性防重打标（8.6.26 实证唯一可靠路径）：预置 Create 规则挂 BIZ_ACTION 自调二开 markDuplicates（规则图内 QUERY→UPDATE 打标会静默空转）",
@@ -328,6 +410,6 @@ const ruleBizactionInvokeService = Object.freeze({
     requiresEnvironmentDerivedIds: true,
 });
 export const BUSINESSRULE_METADATA = Object.freeze({
-    "rule.save": Object.freeze({ recipes: [ruleGraph, ruleBranchGraph, ruleTimingTask, dataDuplicateFlag, ruleCrossModelCreate, ruleBizactionInvokeService], relatedTools: ["field.list", "rule.get", "rule.enable", "service.get"] }),
+    "rule.save": Object.freeze({ recipes: [ruleGraph, ruleBranchGraph, ruleTimingTask, ruleTimingBizService, dataDuplicateFlag, ruleCrossModelCreate, ruleBizactionInvokeService], relatedTools: ["field.list", "rule.get", "rule.enable", "service.get"] }),
 });
 //# sourceMappingURL=businessrule.js.map