@stalfh233/omc-cli 0.6.12 → 0.6.14

package/dist/describe-cache.js

@@ -51,9 +51,13 @@ function writeCache(cache) {
 /**
  * Return the compact repeat-read face for `tool`, or `undefined` when this is
  * the first read (or the contract changed). Records the new entry as a side
- * effect so the NEXT read is compact.
+ * effect so the NEXT `--cache-ok` read can be compact.
+ *
+ * r31b F3: `--full` alone always wants the body. Pass `{ recordOnly:true }` to
+ * refresh the cache without short-circuiting; pass nothing / `{cacheOk:true}`
+ * (via CLI `--full --cache-ok`) to allow the compact face.
  */
-export function repeatFullDescribe(tool, result) {
+export function repeatFullDescribe(tool, result, options = {}) {
     // No project session (repo tests, golden master, one-off runs) ⇒ no cache:
     // those callers need byte-stable output, and a cache write would be litter.
     if (!projectSessionActive())
@@ -63,7 +67,7 @@ export function repeatFullDescribe(tool, result) {
     const digest = createHash("sha256").update(body).digest("hex");
     const cache = readCache();
     const previous = cache[tool];
-    if (previous && previous.sha256 === digest && Date.now() - previous.at < CACHE_TTL_MS) {
+    if (!options.recordOnly && previous && previous.sha256 === digest && Date.now() - previous.at < CACHE_TTL_MS) {
         // A pruned artifact would turn the summary into a dead end; re-ship instead.
         if (existsSync(join(artifactRoot(), `${previous.artifactId}.artifact`))) {
             try {
@@ -75,7 +79,7 @@ export function repeatFullDescribe(tool, result) {
                     sha256: digest,
                     bytes,
                     fetch: `omc artifact get ${previous.artifactId} --summary（再 --keys/--jq 取需要的键）`,
-                    note: `本项目的会话里已读过同一个契约（${bytes}B，内容 sha256 未变），本次不再重发全文；用 fetch 里的命令按需投影`,
+                    note: `本项目的会话里已读过同一个契约（${bytes}B，内容 sha256 未变），本次因 --cache-ok 不再重发全文；要全文请去掉 --cache-ok 再 --full`,
                 };
             }
             catch {

package/dist/discovery.js

@@ -485,6 +485,10 @@ export function describeTool(registry, name) {
         // High-frequency read faces: declare the RESULT keys so `--jq` does not
         // have to learn them from a pathMiss. Zero bytes when undeclared.
         ...(returnsFace(tool.name) ?? {}),
+        // r32 F1（真机）：探针并发发两条 app.create，第二条回 write-lock-held。
+        // 撞上之前没有任何发现面说过"写是环境级串行"——describe 的 params 里没有 wait
+        // （它是 omc call 的 CLI 开关，不在工具 schema），capability notes 是空的。
+        ...(tool.kind === "write" ? { writeLock: "写锁=环境级：同一环境的并发写，后到的直接回 write-lock-held（不排队）。可带 --wait <ms> 让 CLI 内部排队（CLI 开关，不是本工具参数）；不要写 shell 重试循环" } : {}),
         // Keep the cost salient at the decision point: agents reached for --full even
         // when --example/--param existed (sandbox22: 8 --full calls, one 19 KB).
         full: `omc describe ${tool.name} --full（5–20KB；先试 --example/--param）`,

package/dist/environment-policy.js

@@ -23,4 +23,24 @@ export function environmentNotice(profile) {
         ? "当前是测试环境；已允许写入，仅应使用测试数据。"
         : "当前是测试环境；当前设置为只读，写入会被拒绝。";
 }
+export function versionEvidenceOf(input) {
+    const detected = input.detectedVersion;
+    if (detected === undefined || detected.length === 0) {
+        return {
+            detectedVersion: null,
+            inAnchorFamily: null,
+            versionSource: null,
+            anchorVersion: input.anchorVersion,
+            versionFamily: input.versionFamily,
+        };
+    }
+    return {
+        detectedVersion: detected,
+        inAnchorFamily: detected.startsWith(`${input.versionFamily}.`),
+        versionSource: "system-config",
+        anchorVersion: input.anchorVersion,
+        versionFamily: input.versionFamily,
+        ...(input.versionNotice ? { versionNotice: input.versionNotice } : {}),
+    };
+}
 //# sourceMappingURL=environment-policy.js.map

package/dist/field-families.js

@@ -11,8 +11,11 @@ export { FIELD_FAMILY_LIST, FIELD_CONTROL_CODES };
 export const propertyTypeArg = z
     .string()
     .min(1)
-    .describe(`field family. Accepted: ${FIELD_FAMILY_LIST}, CHILD_TABLE (子表, requires \`subFields\`). **NUMERICAL 必填 options.scale**（0=整数 … 8=8 位小数；金额两位小数用 scale:2，不要照搬列格式枚举）。Out of coverage (refused with a citation): OCR, ELECTRONIC_SIGN, and nested CHILD_TABLE. Selection families take \`choices\`; relation families take \`relativeCode\` + \`options\`.`);
-export const relativeCodeArg = z.string().optional().describe("relation target model code (required for WORK_SHEET / MULT_WORK_SHEET)");
+    .describe(`field family. Accepted: ${FIELD_FAMILY_LIST}, CHILD_TABLE (requires \`subFields\`). **NUMERICAL 必填 options.scale**（0..8）。WORK_SHEET=关联单选；RELEVANCE_DATA=引用关联列；MULT_WORK_SHEET=关联多选。Out of coverage: OCR/ELECTRONIC_SIGN/nested CHILD_TABLE. Selection→\`choices\`（dictionary 用 optionsSet）；relation→\`relativeCode\`+\`options\`。`);
+export const relativeCodeArg = z
+    .string()
+    .optional()
+    .describe("relation target model code；WORK_SHEET/MULT_WORK_SHEET 必填，且与 options.schemaCode 相同");
 /**
  * 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
@@ -164,10 +167,13 @@ export const subFieldArg = z
  */
 export const fieldOptionsArg = z
     .object({
-    schemaCode: z.string().optional().describe("relation target model code (WORK_SHEET / MULT_WORK_SHEET)"),
+    schemaCode: z.string().optional().describe("relation target model code（WORK_SHEET/MULT_WORK_SHEET；与 relativeCode 都填且必须相同）"),
     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.union([z.string(), z.array(z.object({ source: z.string(), target: z.string() }))]).optional().describe('relation carry mappings——数组 [{"source":"<target field code>","target":"<this-model field code>"}] 或等价 JSON 字符串均可，CLI 就地归一（空数组/"[]" → 无映射）'),
+    mappings: z
+        .union([z.string(), z.array(z.object({ source: z.string(), target: z.string() }))])
+        .optional()
+        .describe('relation mappings：[{"source":"<目标字段>","target":"<本模型字段>"}] 或 JSON 串（[]/""=无映射）。仅门户选取时回填；data.save/update 不触发；data.load 是快照，上游改名不跟随'),
     searchFormula: jsonString().optional().describe("WORK_SHEET / MULT_WORK_SHEET data restriction range JSON"),
     conditions: jsonString().optional().describe("WORK_SHEET / MULT_WORK_SHEET query conditions JSON"),
     optionsSet: optionsSetArg.optional().describe("selection source: custom, dictionary, or businessModel"),
@@ -1205,4 +1211,56 @@ export function assertFieldOptionsAllowed(type, options, schemaCode) {
             refuseFieldOptions("RELEVANCE_DATA referenceFieldControlType is not an integer control code", "rejected: RELEVANCE_DATA(16) referenceFieldControlType must be an integer BizFormPropertyType code");
     }
 }
+/**
+ * CHILD_TABLE(8) columns as a compact list (issue 2026-10-25 §7).
+ *
+ * The stored `subSchema` is the full designer payload — system columns included,
+ * ~37.6 KB for a 10-column child table when asked for one field by code. A caller
+ * almost always wants the column codes (to build formData / verify the attach);
+ * the raw payload stays available behind `full:true`. Accepts both the object and
+ * the JSON-string wire form.
+ *
+ * Lives here (not in the field lane) because the form lane needs the same
+ * child-column inventory to answer "which subtable columns is this layout
+ * missing?" (GitLab issue #24).
+ */
+export function childColumnsOf(subSchema) {
+    let parsed = subSchema;
+    if (typeof subSchema === "string") {
+        try {
+            parsed = JSON.parse(subSchema);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return [];
+    const properties = parsed.properties;
+    if (!Array.isArray(properties))
+        return [];
+    return properties
+        .filter((child) => child !== null && typeof child === "object")
+        .map((child) => {
+        const rawType = child.propertyType ?? child.type;
+        const type = rawType === undefined || rawType === null || Number.isNaN(Number(rawType)) ? null : Number(rawType);
+        const typeLabel = type === null ? undefined : fieldTypeLabel(type);
+        const code = String(child.code ?? child.propertyCode ?? "");
+        return {
+            code,
+            name: String(child.name ?? child.code ?? child.propertyCode ?? ""),
+            type,
+            ...(typeLabel !== undefined ? { typeName: typeLabel } : {}),
+            ...(typeof child.relativeCode === "string" && child.relativeCode ? { relativeCode: child.relativeCode } : {}),
+            // r15 feedback: the projection mixed the platform's system columns with
+            // the authored ones, so "which child columns did I declare?" still needed
+            // a filter. Keep every column but mark the system ones.
+            // `parentId` / `sortKey` are injected by the platform into every child
+            // schema (they are the child row's link + order), so they are system
+            // columns here even though a MAIN model never carries them.
+            ...(SYSTEM_FIELD_CODES.has(code) || code === "parentId" || code === "sortKey" ? { system: true } : {}),
+        };
+    })
+        .filter((child) => child.code.length > 0);
+}
 //# sourceMappingURL=field-families.js.map

package/dist/form-support.js

@@ -2,7 +2,7 @@ import { wireCall, wireRows, WireError } from "./wire.js";
 import { ENDPOINTS } from "./endpoints.js";
 import { decodeJsonObjectColumn } from "./json-column.js";
 import { ToolRefusalError } from "./tool-types.js";
-import { FIELD_CONTROL_TYPES, SYSTEM_FIELD_CODES, fieldControlOptions, relationDisplayField, relationMappings, } from "./field-families.js";
+import { FIELD_CONTROL_TYPES, childColumnsOf, SYSTEM_FIELD_CODES, fieldControlOptions, relationDisplayField, relationMappings, } from "./field-families.js";
 import { deriveControlOptions } from "./capability-shape.js";
 import { hardLayoutViolations, validateFormLayoutShape } from "./form-layout.js";
 /**
@@ -39,6 +39,31 @@ export function propagateRelationOptions(attributesJson, fields) {
     return JSON.stringify(attributes);
 }
 export const propagateRelationMappings = propagateRelationOptions;
+/**
+ * Parse-only JavaScript check for a `<script>` element body.
+ *
+ * `new Function(source)` compiles without running it, so a SyntaxError here means
+ * the browser would fail the same way — except the browser fails at RENDER time,
+ * with the whole form script dead and no signal in any read face.
+ *
+ * Only `SyntaxError` is reported. Anything else (runtime `ReferenceError`, a
+ * `form` that is undefined at parse time) is not a shape problem and must not
+ * block a legitimate compose.
+ */
+function scriptSyntaxProblem(source) {
+    try {
+        // Function body context: the platform wraps customScript in
+        // `(function(form){ … })`, so top-level `return`/`await` semantics differ.
+        // Compiling as a *function body* matches how it actually runs.
+        new Function(source);
+        return undefined;
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return error.message;
+        return undefined;
+    }
+}
 /** Validate the JSON shape consumed by the Online JS HTML renderer. */
 export function validateHtmlRender(value, requirePlatformSkeleton = false) {
     if (value === undefined || value === null)
@@ -70,6 +95,16 @@ export function validateHtmlRender(value, requirePlatformSkeleton = false) {
             violations.push({ index, problem: "tagName missing or attrs not an array" });
         if (typeof record.id === "string")
             ids.add(record.id);
+        // 2026-11-05（r30b F14）：`<script>` 元素的正文**从来没被检查过**，于是
+        // `onlinejs.compose` 写进一段 `var x = ;` 也三连绿（写入 ok / 发布 ok /
+        // htmlRenderCompat ok）——门户一渲染就 SyntaxError，整个表单脚本全死。
+        // 这里只做**最便宜的语法检查**（`new Function` 只解析、不执行），
+        // 不引入依赖、不请求网络；运行期错误（如 form 未定义）不归它管。
+        if (record.tagName === "script" && typeof record.innerHTML === "string" && record.innerHTML.trim() !== "") {
+            const syntaxProblem = scriptSyntaxProblem(record.innerHTML);
+            if (syntaxProblem !== undefined)
+                violations.push({ index, problem: `${String(record.id ?? "script")} JavaScript 语法错误：${syntaxProblem}` });
+        }
     });
     if (requirePlatformSkeleton) {
         for (const id of ["toolbar", "template", "beforeCustomScript", "customScript", "afterCustomScript"]) {
@@ -335,6 +370,135 @@ function childTableColumns(parentCode, children) {
         options: fieldControlOptions(child.type, child.name, child.relativeCode, child.mappings, child.displayField ?? "name", child.fieldOptions),
     }));
 }
+/**
+ * GitLab issue #24（2026-11-05，Windows 8.6.44 实测）：给**已有手工布局**的模型
+ * 加子表列后，`field.publish` 成功、模型里也有这一列，但表单的 Sheet201 控件
+ * `columns` 里没有它 → 业务页面看不到。旧路径只有两条路：手工读
+ * `publishedAttributesJson`（26KB+）改 JSON 再写回，或整表 `rebuild`（丢掉所有
+ * 手工布局与控件表达式）。这里补第三条：**只往已有的 Sheet201 控件里追加缺失列**，
+ * 其余控件与顺序一律不动。
+ *
+ * 列的形状与 scaffold 共用 `childTableColumns`（`{type,width,key,parentKey,options}`），
+ * 因为平台渲染与 `bizsheet/publish` 的校验只认这一种形状（field-contract 的
+ * `childTableFormControl` 就是按它钉的）。
+ */
+export async function insertChildColumnsIntoLayout(session, schemaCode, attributesJson, requests) {
+    let attributes;
+    try {
+        attributes = JSON.parse(attributesJson);
+    }
+    catch {
+        throw new ToolRefusalError({
+            status: "refused",
+            blocker: "form-layout-invalid",
+            schemaCode,
+            message: "已有表单布局的 draftAttributesJson 不是合法 JSON 对象，无法增量插入子表列；先按 `omc call form.get` 的原文修复布局",
+        });
+    }
+    const added = [];
+    const alreadyBound = [];
+    const unknownParents = [];
+    const unknownColumns = [];
+    for (const request of requests) {
+        const control = attributes[request.parent];
+        const columns = control && Array.isArray(control.columns) ? control.columns : undefined;
+        if (!control || columns === undefined) {
+            unknownParents.push(request.parent);
+            continue;
+        }
+        const bound = new Set(columns.map((column) => String(column.key ?? "")).filter((key) => key.length > 0));
+        // 列的字段元数据在**父模型下的子表 schema**（子表 schemaCode = 父字段 code）。
+        const rows = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: request.parent, isPublish: "true" } })).data);
+        for (const code of request.fieldCodes) {
+            if (bound.has(code)) {
+                alreadyBound.push({ parent: request.parent, code });
+                continue;
+            }
+            const row = rows.find((candidate) => String(candidate.code ?? candidate.propertyCode ?? "") === code);
+            if (!row) {
+                unknownColumns.push({ parent: request.parent, code });
+                continue;
+            }
+            const type = Number(row.type ?? row.propertyType);
+            const relativeCode = row.relativeCode ? String(row.relativeCode) : undefined;
+            let displayField;
+            if (relativeCode && (type === 9 || type === 11)) {
+                displayField = relationDisplayField(row.options);
+                if (!displayField) {
+                    const targetRows = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: relativeCode, isPublish: "true" } })).data);
+                    const title = targetRows.find((target) => String(target.code ?? target.propertyCode) === "name" || target.name === "数据标题");
+                    displayField = title ? String(title.code ?? title.propertyCode) : "name";
+                }
+            }
+            columns.push(...childTableColumns(request.parent, [{
+                    code,
+                    name: String(row.name ?? code),
+                    type: Number.isFinite(type) ? type : 1,
+                    ...(relativeCode !== undefined ? { relativeCode } : {}),
+                    ...(row.mappings !== undefined ? { mappings: String(row.mappings) } : {}),
+                    ...(displayField !== undefined ? { displayField } : {}),
+                    fieldOptions: decodeJsonObjectColumn(row.options, { invalid: "throw", array: "accept", object: "accept" }),
+                }]));
+            bound.add(code);
+            added.push({ parent: request.parent, code });
+        }
+        control.columns = columns;
+    }
+    return { attributesJson: JSON.stringify(attributes), added, alreadyBound, unknownParents, unknownColumns };
+}
+/**
+ * True when `provided` differs from `stored` ONLY by appended child-table
+ * columns inside existing Sheet201 controls. This is the one edit that arrives
+ * from the platform's own layout (issue #24): everything else is byte-identical,
+ * so the caller-shape gate would otherwise force a full rebuild (losing manual
+ * layout + control expressions) or hand-editing 26KB of JSON.
+ */
+export function attributesOnlyAddedChildColumns(provided, stored) {
+    let next;
+    let prev;
+    try {
+        next = JSON.parse(provided);
+        prev = JSON.parse(stored);
+    }
+    catch {
+        return false;
+    }
+    if (next === null || prev === null || typeof next !== "object" || typeof prev !== "object")
+        return false;
+    if (Array.isArray(next) || Array.isArray(prev))
+        return false;
+    const nextKeys = Object.keys(next).sort();
+    const prevKeys = Object.keys(prev).sort();
+    if (nextKeys.length !== prevKeys.length || nextKeys.some((key, index) => key !== prevKeys[index]))
+        return false;
+    for (const key of prevKeys) {
+        const nextControl = next[key];
+        const prevControl = prev[key];
+        if (nextControl === null || prevControl === null || typeof nextControl !== "object" || typeof prevControl !== "object") {
+            if (JSON.stringify(nextControl) !== JSON.stringify(prevControl))
+                return false;
+            continue;
+        }
+        const { columns: nextColumns, ...nextRest } = nextControl;
+        const { columns: prevColumns, ...prevRest } = prevControl;
+        if (JSON.stringify(nextRest) !== JSON.stringify(prevRest))
+            return false;
+        if (prevColumns === undefined) {
+            if (nextColumns !== undefined)
+                return false;
+            continue;
+        }
+        if (!Array.isArray(nextColumns) || !Array.isArray(prevColumns))
+            return false;
+        if (nextColumns.length < prevColumns.length)
+            return false;
+        for (let index = 0; index < prevColumns.length; index += 1) {
+            if (JSON.stringify(nextColumns[index]) !== JSON.stringify(prevColumns[index]))
+                return false;
+        }
+    }
+    return true;
+}
 /**
  * Keep the designer's non-structural control edits across a rebuild. The
  * freshly scaffolded control owns its label and relation target keys (they must
@@ -879,6 +1043,30 @@ export function readFormButtons(options) {
     }
 }
 export async function executeFormDraftWrite(session, args) {
+    // 兼容别名：`fieldCodes:["items.category"]` 等价于
+    // `childColumns:[{parent:"items",fieldCodes:["category"]}]`（issue #24）。
+    // 点号形式是使用者最自然的写法——子表列在父模型里本来就该这样指代。
+    if (args.childColumns === undefined) {
+        const dotted = (args.fieldCodes ?? []).filter((code) => code.includes("."));
+        if (dotted.length > 0) {
+            const grouped = new Map();
+            for (const entry of dotted) {
+                const [parent, ...rest] = entry.split(".");
+                const child = rest.join(".");
+                if (!parent || !child)
+                    continue;
+                grouped.set(parent, [...(grouped.get(parent) ?? []), child]);
+            }
+            if (grouped.size > 0) {
+                args = {
+                    ...args,
+                    fieldCodes: (args.fieldCodes ?? []).filter((code) => !code.includes(".")),
+                    childColumns: [...grouped.entries()].map(([parent, fieldCodes]) => ({ parent, fieldCodes })),
+                };
+            }
+        }
+    }
+    const requestedChildColumns = args.childColumns && args.childColumns.length > 0 ? args.childColumns : undefined;
     if (args.draftHtmlJson !== undefined) {
         assertHtmlRender(args.draftHtmlJson, { schemaCode: args.schemaCode, sheetCode: args.sheetCode, face: "draftHtmlJson" });
     }
@@ -909,18 +1097,47 @@ export async function executeFormDraftWrite(session, args) {
     // BEFORE creating anything so an unknown code never writes a form row.
     const wanted = args.fieldCodes;
     let selectionUnknown;
+    let childColumnOwners;
     if (wanted && args.draftAttributesJson === undefined) {
         const rows = wireRows((await wireCall(session, { path: ENDPOINTS.fieldList, query: { schemaCode: args.schemaCode, isPublish: "true" } })).data);
         const publishedCodes = new Set(rows.map((row) => String(row.code ?? row.propertyCode ?? "")));
         selectionUnknown = wanted.filter((code) => !publishedCodes.has(code));
+        // issue #24：子表列不在父模型发布面上，但它是真实存在的已发布字段——
+        // 旧文案只会说「先 field.create + field.publish」，而用户明明已经做了。
+        if (selectionUnknown.length > 0) {
+            childColumnOwners = new Map();
+            for (const row of rows) {
+                if (Number(row.type ?? row.propertyType) !== 8)
+                    continue;
+                const parent = String(row.code ?? row.propertyCode ?? "");
+                for (const column of childColumnsOf(row.subSchema)) {
+                    if (column.system === true)
+                        continue;
+                    childColumnOwners.set(column.code, [...(childColumnOwners.get(column.code) ?? []), parent]);
+                }
+            }
+        }
     }
     if (selectionUnknown && selectionUnknown.length > 0) {
+        const asChildColumns = selectionUnknown
+            .map((code) => ({ code, parents: childColumnOwners?.get(code) ?? [] }))
+            .filter((entry) => entry.parents.length > 0);
         throw new ToolRefusalError({
             status: "refused",
             blocker: "form-fieldcodes-unknown",
             schemaCode: args.schemaCode,
             fieldCodes: selectionUnknown,
-            message: `fieldCodes 引用了模型 ${args.schemaCode} 发布面上不存在的字段：${selectionUnknown.join("、")}；先 field.create + field.publish 这些字段，或修正 fieldCodes`,
+            ...(asChildColumns.length > 0
+                ? {
+                    childColumns: asChildColumns.map((entry) => ({ code: entry.code, parent: entry.parents[0] })),
+                    nextCommand: `omc call configure_form --args '${JSON.stringify({ schemaCode: args.schemaCode, childColumns: asChildColumns.map((entry) => ({ parent: entry.parents[0], fieldCodes: [entry.code] })) })}'`,
+                }
+                : {}),
+            message: asChildColumns.length === selectionUnknown.length
+                ? `${selectionUnknown.join("、")} 是**子表列**，不在模型 ${args.schemaCode} 的顶层发布面——子表列用 childColumns（或 fieldCodes 写「父字段.子列」，如 ${asChildColumns[0].parents[0]}.${asChildColumns[0].code}）绑进对应 Sheet201 控件的 columns；纯 fieldCodes 只描述顶层控件`
+                : asChildColumns.length > 0
+                    ? `${selectionUnknown.join("、")} 里有子表列（${asChildColumns.map((entry) => `${entry.parents[0]}.${entry.code}`).join("、")}），子表列用 childColumns / 「父字段.子列」；其余未知 code 先 field.create + field.publish`
+                    : `fieldCodes 引用了模型 ${args.schemaCode} 发布面上不存在的字段：${selectionUnknown.join("、")}；先 field.create + field.publish 这些字段，或修正 fieldCodes`,
         });
     }
     // The default form may not exist yet on a freshly created model
@@ -934,6 +1151,46 @@ export async function executeFormDraftWrite(session, args) {
         if (pre === null)
             throw new WireError("business", `form ${args.sheetCode} was created but is not readable`, 302024);
     }
+    // issue #24：把子表列追加进**已有**布局（Sheet201 控件的 columns），不重建整表。
+    // 没有已存布局时退回 scaffold（rebuild 会按 subSchema 生成全部子表列，等价）。
+    let childColumnInsert;
+    if (requestedChildColumns !== undefined && args.draftAttributesJson === undefined && args.rebuild !== true) {
+        const storedAttributes = typeof pre.draftAttributesJson === "string" && pre.draftAttributesJson.trim() !== "" && pre.draftAttributesJson.trim() !== "{}"
+            ? pre.draftAttributesJson
+            : typeof pre.publishedAttributesJson === "string" && pre.publishedAttributesJson.trim() !== "" && pre.publishedAttributesJson.trim() !== "{}"
+                ? pre.publishedAttributesJson
+                : undefined;
+        if (storedAttributes === undefined) {
+            args = { ...args, rebuild: true };
+        }
+        else {
+            childColumnInsert = await insertChildColumnsIntoLayout(session, args.schemaCode, storedAttributes, requestedChildColumns);
+            if (childColumnInsert.unknownParents.length > 0 || childColumnInsert.unknownColumns.length > 0) {
+                throw new ToolRefusalError({
+                    status: "refused",
+                    blocker: "form-child-columns-unknown",
+                    schemaCode: args.schemaCode,
+                    ...(childColumnInsert.unknownParents.length > 0 ? { unknownParents: childColumnInsert.unknownParents } : {}),
+                    ...(childColumnInsert.unknownColumns.length > 0 ? { unknownColumns: childColumnInsert.unknownColumns } : {}),
+                    message: (childColumnInsert.unknownParents.length > 0
+                        ? `父控件 ${childColumnInsert.unknownParents.join("、")} 不在表单布局里（不是子表控件）：先用 fieldCodes 绑定父字段，或核对控件 code。`
+                        : "")
+                        + (childColumnInsert.unknownColumns.length > 0
+                            ? `子表发布面没有这些列：${childColumnInsert.unknownColumns.map((entry) => `${entry.parent}.${entry.code}`).join("、")}；先在子表上 field.create 再 field.publish 父模型。`
+                            : ""),
+                });
+            }
+            const storedView = typeof pre.draftViewJson === "string" ? pre.draftViewJson : typeof pre.publishedViewJson === "string" ? pre.publishedViewJson : undefined;
+            const storedHtml = typeof pre.draftHtmlJson === "string" ? pre.draftHtmlJson : undefined;
+            args = {
+                ...args,
+                ...(storedView !== undefined ? { draftViewJson: storedView } : {}),
+                draftAttributesJson: childColumnInsert.attributesJson,
+                ...(storedHtml !== undefined ? { draftHtmlJson: storedHtml } : {}),
+                amendChildColumns: true,
+            };
+        }
+    }
     //
     // 1.3 of issue 2026-10-23: the platform's OWN readback can carry shapes this
     // gate rejects (`child_column_in_rows` when a published layout lists child
@@ -948,14 +1205,38 @@ export async function executeFormDraftWrite(session, args) {
         const same = (provided, stored) => typeof provided === "string" && typeof stored === "string" && provided.trim() === stored.trim();
         const viewRoundTrip = same(args.draftViewJson, pre2?.publishedViewJson) || same(args.draftViewJson, pre2?.draftViewJson);
         const attributesRoundTrip = same(args.draftAttributesJson, pre2?.publishedAttributesJson) || same(args.draftAttributesJson, pre2?.draftAttributesJson);
-        const allProvidedAreRoundTrip = (args.draftViewJson === undefined || viewRoundTrip) && (args.draftAttributesJson === undefined || attributesRoundTrip);
+        // issue #24：本次 attributes 由工具自己从已存布局**只追加了子表列**得来。
+        // 它既不是逐字回写（所以要过形状门），也不该按调用方手写布局严判（平台
+        // 自己的布局本来就可能带门不接受的形态）。唯一允许的差异 = 既有 Sheet201
+        // 控件 columns 尾部追加。
+        const amendedChildColumns = childColumnInsert !== undefined &&
+            typeof args.draftAttributesJson === "string" &&
+            (typeof pre2?.publishedAttributesJson === "string" && attributesOnlyAddedChildColumns(args.draftAttributesJson, pre2.publishedAttributesJson)
+                || typeof pre2?.draftAttributesJson === "string" && attributesOnlyAddedChildColumns(args.draftAttributesJson, pre2.draftAttributesJson));
+        const allProvidedAreRoundTrip = (args.draftViewJson === undefined || viewRoundTrip) && (args.draftAttributesJson === undefined || attributesRoundTrip || amendedChildColumns);
         if (!allProvidedAreRoundTrip && args.fromReadback === true) {
+            // GitLab issue #24 附带坑 2：`fromReadback` 的语义是「**逐字**回写未改动的
+            // 原文」，不是「我读过原文」。所有「读 → 改一列 → 写回」都会撞在这里，
+            // 而旧文案只说「去掉 fromReadback」，没给可直接执行的下一条命令。
+            const onlyChildColumnsDiffers = typeof args.draftAttributesJson === "string" &&
+                typeof pre2?.publishedAttributesJson === "string" &&
+                attributesOnlyAddedChildColumns(args.draftAttributesJson, pre2.publishedAttributesJson);
             throw new ToolRefusalError({
                 status: "refused",
                 blocker: "form-layout-invalid",
                 schemaCode: args.schemaCode,
                 sheetCode: args.sheetCode,
-                message: "fromReadback:true 但本次布局与已存草稿/发布面不一致——读过之后又改过就必须按普通写面校验（去掉 fromReadback，或按 validation 修正）",
+                reason: "fromReadback 只接受**逐字**未改动的原文回写；读过之后改过一个字符就不再是回读",
+                ...(onlyChildColumnsDiffers
+                    ? {
+                        detectedChange: "child-columns-appended",
+                        message: "fromReadback 只接受逐字未改动的原文（它是「回写」不是「我读过」）。本次比已存布局多出的内容**只是子表列**——加子表列不必手动改 26KB 的属性 JSON，用 configure_form 的 childColumns 增量绑定即可（不动其它控件与布局）。",
+                        nextCommand: `omc call configure_form --args '${JSON.stringify({ schemaCode: args.schemaCode, childColumns: [{ parent: "<父字段>", fieldCodes: ["<子列>"] }] })}'`,
+                    }
+                    : {
+                        message: "fromReadback 只接受逐字未改动的原文（它是「回写」不是「我读过」）。你改过布局 → 按普通写面校验：同一条命令去掉 fromReadback 即可；若仍被拒，按 validation 修正后再写。",
+                        nextCommand: `omc call form.draft --args '<同一份参数，去掉 \"fromReadback\">'`,
+                    }),
                 validation: formLayoutViolations(args),
             });
         }
@@ -1300,8 +1581,14 @@ export async function executeFormPublishWrite(session, args) {
         (Array.isArray(args.removeButtonCodes) && args.removeButtonCodes.length > 0) ||
         (Array.isArray(args.buttonScripts) && args.buttonScripts.length > 0);
     const forcePromote = args.force === true || args.rebuild === true || hasButtonDelta;
-    if (pre.published === true && !forcePromote)
-        return { performed: { skipped: "already-published" }, readback: { published: true } };
+    // issue #24：旧短路只看「已发布」标记，于是「改了草稿 → form.publish」被静默跳过，
+    // 回执还是 `skipped:"already-published" + published:true`（读起来像成功），实际
+    // 发布面一字未变——页面继续看不到新控件。只有当**草稿与发布面逐字相同**时才跳过。
+    const draftEqualsPublished = typeof pre.draftViewJson === "string" && pre.draftViewJson === pre.publishedViewJson &&
+        typeof pre.draftAttributesJson === "string" && pre.draftAttributesJson === pre.publishedAttributesJson &&
+        (pre.draftHtmlJson === undefined || pre.draftHtmlJson === pre.publishedHtmlJson);
+    if (pre.published === true && draftEqualsPublished && !forcePromote)
+        return { performed: { skipped: "already-published" }, readback: { published: true, draftMatchesPublished: true } };
     if (!hasDraft(pre))
         throw new WireError("business", "form publish requires a saved draft (draftViewJson/draftAttributesJson)", 302020);
     if (pre.draftHtmlJson !== "[]")