@stalfh233/omc-cli 0.4.75 → 0.4.77

package/coverage/m1-coverage-manifest-v1.json

@@ -815,6 +815,7 @@
       "tools": [
         "model.create",
         "model.update",
+        "model.move",
         "model.delete",
         "model.deleteMany",
         "model.setSummary",
@@ -823,7 +824,8 @@
         "model.inspect"
       ],
       "scopes": [
-        "create publish physical delete absence read list inspect"
+        "create publish physical delete absence read list inspect",
+        "move a model's app-tree node to another folder (bizmodels/update parentId)"
       ]
     },
     {
@@ -1328,6 +1330,38 @@
       "scopes": [
         "report tree read page metadata BI config chart data create update delete configure"
       ]
+    },
+    {
+      "capability": "App-tree folders (目录/分组): read flattened tree, create, rename/move, non-recursive delete",
+      "status": "executable",
+      "scope": "App application-tree folders: flattened tree read with path/depth, folder create (omitted parentId = root), rename/reparent, non-recursive delete, and model reparenting.",
+      "version_family": "8.6",
+      "anchor_version": "8.6.26",
+      "evidence": [
+        {
+          "path": "cp-sources/backend/decompiled-full/launcher-8.6.26/cloudpivot-engine-8.6.26/com/authine/cloudpivot/web/api/controller/app/AppFunctionController.java"
+        },
+        {
+          "path": "cp-sources/backend/decompiled-full/launcher-8.6.26/cloudpivot-metadata-8.6.26/com/authine/cloudpivot/metadata/history/apppackage/service/ApplicationFacadeImpl.java"
+        },
+        {
+          "path": "packages/omc-cli/src/lanes/folder.ts"
+        }
+      ],
+      "lane": "app-tree-folders",
+      "notes": "Live 2026-10-23 customer HAR: POST /api/app/folders/create answered errcode 0 成功创建目录; trees are nested (children[]) and must be flattened.",
+      "tools": [
+        "folder.tree",
+        "folder.create",
+        "folder.update",
+        "folder.delete"
+      ],
+      "scopes": [
+        "app-tree folder/model tree (flattened with path/depth)",
+        "app-tree folder create (folders/create)",
+        "app-tree folder rename/move (folders/update)",
+        "app-tree folder delete (folders/delete, non-recursive)"
+      ]
     }
   ]
 }

package/dist/artifacts.js

@@ -83,7 +83,7 @@ export function isWithinRoot(root, candidate) {
 export function assertSafeOutputPath(root, candidate, label) {
     const normalized = resolve(root, candidate);
     if (!isWithinRoot(root, normalized))
-        throw new Error(`${label} must be inside the configuration root`);
+        throw new Error(`${label} must be inside the configuration root（配置根 ${resolve(root)}；本次解析为 ${normalized}）`);
     const parent = resolve(normalized, "..");
     if (!existsSync(parent))
         throw new Error(`${label} parent directory does not exist`);
@@ -101,7 +101,7 @@ export function assertSafeInputPath(root, candidate, label) {
     const resolvedRoot = resolve(root);
     const normalized = resolve(root, candidate);
     if (!isWithinRoot(root, normalized))
-        throw new Error(`${label} must be inside the configuration root`);
+        throw new Error(`${label} must be inside the configuration root（配置根 ${resolvedRoot}；本次解析为 ${normalized}）`);
     let current = normalized;
     while (current !== resolvedRoot) {
         try {

package/dist/capability-overview.js

@@ -36,6 +36,16 @@ const SURFACES = [
         intent: { level: "none", note: "未覆盖；用 omc call app.*。" },
         notes: "环境已带默认 applicationCode，建模不必先建应用。",
     },
+    {
+        id: "folder",
+        title: "应用目录（分组）",
+        lane: LANES.folder,
+        description: "应用树目录：读（递归展平带 path/depth）、建、改名/挂载、非递归删除。",
+        operations: ["tree", "create", "update", "delete"],
+        requires: ["app"],
+        intent: { level: "none", note: "未覆盖；用 omc call folder.*。移动模型用 model.move。" },
+        notes: "省略 parentId 建顶层目录（平台默认挂应用根）；平台不校验重名（工具默认同父同名拒绝）；删除非递归（有子节点回 DIRECTORY_NOT_EMPTY）；应用树是嵌套 children，folder.tree 已展平。",
+    },
     {
         id: "dictionary",
         title: "数据字典",
@@ -51,7 +61,7 @@ const SURFACES = [
         title: "业务模型",
         lane: LANES.model,
         description: "模型生命周期：创建、改名、物理删除、存在性。",
-        operations: ["create", "update", "delete", "deleteMany", "setSummary"],
+        operations: ["create", "update", "move", "delete", "deleteMany", "setSummary"],
         intent: { level: "partial", note: "create/update 与 delete（absent:true）已声明式；deleteMany/setSummary 未覆盖。" },
     },
     {

package/dist/cli.js

@@ -17,7 +17,8 @@ import { configureOutput, humanSummary, stripOutputFlags, writeEnvelope } from "
 import { beginUsage, completeUsage, recordUsageOutput, usageReport } from "./usage-log.js";
 import { artifactFetchHint, artifactRoot, boundResult, emitInvalid, emitResult, emitTransportResult, outputBudget, readArtifact, withTransport, } from "./command-transport.js";
 import { CLI_DEFAULT_OUTPUT_BYTES, assertSafeOutputPath, pruneArtifacts } from "./artifacts.js";
-import { resolve } from "node:path";
+import { projectJsonPath, projectResultExtract } from "./path-projection.js";
+import { basename, join, resolve } from "node:path";
 import { buildToolRegistry } from "./tools.js";
 import { acquireWriteLock } from "./write-lock.js";
 import { cmdCompute } from "./compute.js";
@@ -274,12 +275,19 @@ async function cmdCall(store, args) {
     const positional = args.filter((token, index) => !token.startsWith("--") && (index === 0 || !args[index - 1]?.startsWith("--env") && !args[index - 1]?.startsWith("--environment") && !args[index - 1]?.startsWith("--args")));
     const toolName = positional[0];
     if (!toolName || toolName === "help" || args.includes("--help")) {
-        console.error("用法：omc call <tool> [--env <环境>] [--args '<json>' | --args - (stdin) | --args-file <path>]");
+        console.error("用法：omc call <tool> [--env <环境>] [--args '<json>' | --args - (stdin) | --args-file <配置根内路径>] [--extract <path>]... [--extract-keys]");
         console.error("写入：由环境 writable 决定（只读环境拒写）；生产环境的写必须在 args 里带 confirmProduction:true。");
         return emit(toolName && toolName !== "help" ? "error" : "ok", {}, toolName && toolName !== "help" ? CLI_EXIT_CODES.invalidInput : 0);
     }
     const environment = flag("--env") ?? flag("--environment");
     const requestValue = flag("--request-id");
+    // 1.2 of issue 2026-10-23: read faces answer {detailArtifactId, sha256} and the
+    // caller then needs a SECOND call to see one value (16 two-step chains in one
+    // session; 15 more were pure --keys probes). `--extract <path>` (repeatable)
+    // resolves the path inside the artifact of THIS result and returns only the
+    // value; `--extract-keys` lists the artifact's top-level keys with sizes.
+    const extractPaths = argvValues(args, "--extract");
+    const extractKeys = args.includes("--extract-keys");
     const dryRun = args.includes("--dry-run");
     const waitValue = flag("--wait");
     let waitMs = 0;
@@ -331,11 +339,22 @@ async function cmdCall(store, args) {
         // r10 F9: an out-of-root `--args-file` was reported under "--args 必须是
         // 合法 JSON", which points the reader at the wrong flag. Name the real
         // cause (and the configuration root) when the failure came from the file.
-        const message = /must be inside the configuration root/.test(detail)
-            ? `--args-file 越界：${detail}（只接受配置根 ${resolve(process.env.OMC_CONFIG_HOME ?? process.cwd())} 内的路径；把参数文件放进项目目录后重试）`
-            : `--args 必须是合法 JSON：${detail}（Windows PowerShell 下内联 JSON 引号转义不可靠，请改用 --args-file <path> 写入临时文件后引用）`;
+        const configRoot = resolve(process.env.OMC_CONFIG_HOME ?? process.cwd());
+        // 1.1 of issue 2026-10-23: the old hint told the caller to write a TEMP file
+        // while the validator only accepts paths under the config root — the two
+        // instructions contradicted each other and neither named the root. Offer a
+        // single executable recipe: an absolute path inside the root.
+        const outOfRoot = /must be inside the configuration root/.test(detail);
+        const message = outOfRoot
+            ? `--args-file 越界：${detail}。可执行做法：把参数文件放到 ${configRoot} 之下（如 ${join(configRoot, "args.json")}），再用 --args-file 引用；不要把参数文件放在系统临时目录（配置根之外一律拒绝）`
+            : `--args 必须是合法 JSON：${detail}。若问题在引号转义（Windows PowerShell），改用 --args-file <配置根内的路径>`;
         console.error(message);
-        writeEnvelope(envelope("error", {}, request, { code: "invalid-input", message: detail, retryable: false }));
+        // The MACHINE envelope must carry the same actionable text: agents read
+        // stdout, and the old envelope only repeated the English detail.
+        // Keep the REJECTED path on stderr only: the machine envelope must not leak
+        // host layout (ticket 103), so it carries the root plus the bare file name.
+        const rejectedName = typeof argsFile === "string" ? basename(resolve(configRoot, argsFile)) : "";
+        writeEnvelope(envelope("error", {}, request, { code: "invalid-input", message: outOfRoot ? `--args-file 必须位于配置根内（配置根 ${configRoot}${rejectedName ? `；本次文件 ${rejectedName}` : ""}）` : detail, retryable: false, ...(outOfRoot ? { configurationRoot: configRoot } : {}) }));
         return CLI_EXIT_CODES.invalidInput;
     }
     const registry = buildToolRegistry();
@@ -404,9 +423,26 @@ async function cmdCall(store, args) {
                 await lock.release();
         }
     }
+    if (extractPaths.length > 0 || extractKeys) {
+        const projected = projectResultExtract(result, extractPaths, extractKeys);
+        if (projected !== undefined)
+            result = projected;
+    }
     const classified = classifyResult(result);
     return emit(classified.status, result, classified.exitCode);
 }
+/** Collect every value of a repeatable flag (`--extract a --extract b`). */
+function argvValues(args, name) {
+    const values = [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] !== name)
+            continue;
+        const value = args[index + 1];
+        if (value !== undefined && !value.startsWith("--"))
+            values.push(value);
+    }
+    return values;
+}
 function resolvedDefaultEnvironment(store) {
     try {
         return store.resolveEnvironment(undefined).name;
@@ -415,36 +451,6 @@ function resolvedDefaultEnvironment(store) {
         return "default";
     }
 }
-function projectJsonPath(value, path) {
-    const normalized = path
-        .trim()
-        .replace(/^[.\/]+/, "")
-        .replace(/\[(\d+)\]/g, ".$1")
-        .replace(/\[(?:"([^"]+)"|'([^']+)')\]/g, (_all, dq, sq) => `.${dq || sq}`)
-        .replace(/\.{2,}/g, ".");
-    const segments = normalized.split(/[./]/).filter((segment) => segment.length > 0);
-    let current = value;
-    for (const segment of segments) {
-        if (Array.isArray(current)) {
-            const index = Number(segment);
-            if (!Number.isInteger(index) || index < 0 || index >= current.length)
-                return { missed: true, at: segment, available: `数组长度 ${current.length}（下标 0-${Math.max(current.length - 1, 0)}）` };
-            current = current[index];
-        }
-        else if (current && typeof current === "object") {
-            const record = current;
-            if (!Object.prototype.hasOwnProperty.call(record, segment)) {
-                const keys = Object.keys(record);
-                return { missed: true, at: segment, available: keys.length > 0 ? keys.slice(0, 12) : "（该层是空对象）" };
-            }
-            current = record[segment];
-        }
-        else {
-            return { missed: true, at: segment, available: `路径在第 ${segments.indexOf(segment) + 1} 段之前已到标量/undefined（前段类型 ${current === null ? "null" : typeof current}）` };
-        }
-    }
-    return { missed: false, value: current };
-}
 function parseDurationMs(text) {
     const match = /^\s*(\d+)\s*(ms|s|m|h|d|w)?\s*$/u.exec(text);
     if (!match)
@@ -950,11 +956,47 @@ function onboardingHelp() {
     return [
         "首次使用、或不确定从哪开始：omc help omc-start-here（随包权威 topic 路线）；被拒或状态异常：omc help omc-refusals。",
         "目标→工具一步定位：omc next \"<你要做什么>\"（离线、只读，给能力/说明/首批命令；不确定会明说并回退到 omc-requirement-analysis）。",
+        "大结果取值一步到位：读面回 detailArtifactId 时，用 omc call <tool> … --extract <path>（可重复）或 --extract-keys，省掉再跑一次 omc artifact get。",
         "工具发现：omc commands --json（含 capability id/lane/recipes；加 --compact 只回工具行、无目录散文）· omc capabilities（能力 id/lane/aliases/tools/依赖顺序）· omc capability <id> --executable（单能力完整执行包）。",
         "单工具/契约：omc describe <tool>（schema+recipe+能力路由）· omc contract <lane>（wire 契约+能力路由）；环境就绪：omc call discover_environment --env <env> --args '{}'。",
         "写入两道门：对话层草稿确认（omc help omc-config-draft-review）+ 环境 writable 开关；生产环境每笔写需在 args 里带 confirmProduction:true。",
     ].join("\n");
 }
+/** Last command-level failure, so the no-envelope fallback can name the cause. */
+let lastFailureDetail;
+function failureDetail() {
+    return process.env.OMC_LAST_FAILURE ?? lastFailureDetail;
+}
+/**
+ * 1.5 of issue 2026-10-23: a `--jq` expression containing spaces/pipes arrives as
+ * multiple argv entries when the caller's shell splits it. Commander then
+ * answers "too many arguments for 'get'" — an arity complaint, not a quoting
+ * hint. Re-join the value before parsing.
+ */
+function joinSplitFlagValues(raw, flags) {
+    const out = [];
+    for (let index = 0; index < raw.length; index += 1) {
+        const token = raw[index];
+        if (!flags.includes(token)) {
+            out.push(token);
+            continue;
+        }
+        const value = raw[index + 1];
+        if (value === undefined) {
+            out.push(token);
+            continue;
+        }
+        const parts = [value];
+        let cursor = index + 2;
+        while (cursor < raw.length && !raw[cursor].startsWith("--")) {
+            parts.push(raw[cursor]);
+            cursor += 1;
+        }
+        out.push(token, parts.join(" "));
+        index = cursor - 1;
+    }
+    return out;
+}
 async function main() {
     let commandExitCode = 0;
     beginUsage(argv);
@@ -1038,8 +1080,8 @@ async function main() {
         commandExitCode = CLI_EXIT_CODES.ok;
     });
     command.command("doctor").option("--environment <environment>").option("--env <environment>").option("--service <serviceCode>", "可选：体检单个业务集成服务的鉴权参数形状（掩码/占位/全 0 检出，WARN 非致命）").action(async (options) => { commandExitCode = await cmdDoctor(new ConfigStore(defaultPaths()), options.environment ?? options.env, options.service); });
-    command.command("call <tool>").option("--env <environment>").option("--environment <environment>").option("--args <json>").option("--args-file <path>").option("--max-output-bytes <bytes>").option("--request-id <requestId>").option("--timeout-ms <milliseconds>").option("--wait <milliseconds>").option("--dry-run").addHelpText("after", `\n${onboardingHelp()}\n`).action(async (tool, options) => {
-        const rest = [tool, ...(options.env ? ["--env", options.env] : []), ...(options.environment ? ["--environment", options.environment] : []), ...(options.args !== undefined ? ["--args", options.args] : []), ...(options.argsFile !== undefined ? ["--args-file", options.argsFile] : []), ...(options.maxOutputBytes !== undefined ? ["--max-output-bytes", options.maxOutputBytes] : []), ...(options.requestId ? ["--request-id", options.requestId] : []), ...(options.timeoutMs !== undefined ? ["--timeout-ms", options.timeoutMs] : []), ...(options.wait !== undefined ? ["--wait", options.wait] : []), ...(options.dryRun ? ["--dry-run"] : [])];
+    command.command("call <tool>").option("--env <environment>").option("--environment <environment>").option("--args <json>").option("--args-file <path>").addOption(new Option("--extract <path>", "在本次结果的 artifact 内取一个路径的值（可重复；省掉一次 artifact get）").argParser((value, previous = []) => [...previous, value]).default([])).option("--extract-keys", "列出本次结果 artifact 的顶层键与体积（省掉一次 artifact get --keys）").option("--max-output-bytes <bytes>").option("--request-id <requestId>").option("--timeout-ms <milliseconds>").option("--wait <milliseconds>").option("--dry-run").addHelpText("after", `\n${onboardingHelp()}\n`).action(async (tool, options) => {
+        const rest = [tool, ...(options.env ? ["--env", options.env] : []), ...(options.environment ? ["--environment", options.environment] : []), ...(options.args !== undefined ? ["--args", options.args] : []), ...(options.argsFile !== undefined ? ["--args-file", options.argsFile] : []), ...(Array.isArray(options.extract) ? options.extract.flatMap((path) => ["--extract", path]) : []), ...(options.extractKeys ? ["--extract-keys"] : []), ...(options.maxOutputBytes !== undefined ? ["--max-output-bytes", options.maxOutputBytes] : []), ...(options.requestId ? ["--request-id", options.requestId] : []), ...(options.timeoutMs !== undefined ? ["--timeout-ms", options.timeoutMs] : []), ...(options.wait !== undefined ? ["--wait", options.wait] : []), ...(options.dryRun ? ["--dry-run"] : [])];
         commandExitCode = await cmdCall(new ConfigStore(defaultPaths()), rest);
     });
     command.command("compute").option("--schema <schemaCode>").option("--schema-code <schemaCode>").option("--target <propertyCode>").option("--property <propertyCode>").option("--formula <formula>").option("--name <name>").option("--env <environment>").option("--environment <environment>").option("--apply").addHelpText("after", "\n字段计算规则拼装器：公式 {字段} 引用 → datarule type2 完整形状（editorText/editorMark 自动生成）。默认 dry-run，--apply 写入。复杂场景（条件分支/跨模型）走 omc next 的 recipe 路径。\n").action(async (options) => {
@@ -1161,7 +1203,8 @@ async function main() {
     intentCommand.command("readback <file>").option("--env <environment>").option("--max-output-bytes <bytes>").action(async (file, options) => {
         commandExitCode = await withTransport(options, request, (transport) => cmdIntentReadback(file, options.env, transport));
     });
-    await command.parseAsync(stripOutputFlags(argv));
+    // `--jq` expressions the shell split arrive as several tokens; re-join them.
+    await command.parseAsync(joinSplitFlagValues(stripOutputFlags(argv), ["--jq"]));
     return commandExitCode;
 }
 /**
@@ -1194,7 +1237,15 @@ main().then((code) => {
         finish(code);
         return;
     }
-    writeEnvelope(envelope(code === 0 ? "ok" : "error", {}, request, code === 0 ? null : { code: "internal", message: "command failed", retryable: false }));
+    // 1.6 of issue 2026-10-23: a bare "command failed" gives no stage and no cause.
+    writeEnvelope(envelope(code === 0 ? "ok" : "error", {}, request, code === 0
+        ? null
+        : {
+            code: "internal",
+            message: `${argv[2] ?? "omc"} 以退出码 ${code} 结束但没有写出结果信封${failureDetail() ? `：${failureDetail()}` : "（没有捕获到具体异常；加 --verbose 复现，或用相同参数再跑一次看 stderr）"}`,
+            retryable: false,
+            ...(failureDetail() ? { stage: "post-command" } : {}),
+        }));
     completeUsage(code);
     finish(code);
 }, (error) => {

package/dist/command-transport.js

@@ -82,7 +82,7 @@ export function artifactFetchHint(artifactId) {
     // raw. `--summary` shows the key/size map so they fetch only what they need.
     // Kept terse on purpose: this line rides EVERY write and every spilled read
     // (2026-09-25 cost pass — the parenthetical prose was 80 B of the 133 B).
-    return `omc artifact get ${artifactId} --summary（再 --keys/--jq）`;
+    return `omc artifact get ${artifactId} --summary（再 --keys/--jq）；或原调用加 --extract <path> / --extract-keys 一次拿到`;
 }
 /** Replace local paths with a redaction marker (never leak the host layout). */
 function sanitizePaths(value) {

package/dist/compute.js

@@ -74,9 +74,10 @@ export async function cmdCompute(args) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
+        process.env.OMC_LAST_FAILURE = `compute → datarule.create: ${message}`;
         writeEnvelope(envelope("error", {}, request, {
             code: "compute-write-failed",
-            message: `compute 调用 datarule.create 失败：${message}\n` +
+            message: `compute 调用 datarule.create 失败（stage=datarule.create）：${message}\n` +
                 "若 --schema 是**子表 code**（子表列计算），改用可跑样例直接发：omc describe datarule.create --example field-compute-child-column，" +
                 "或 omc call datarule.create --args '<该样例 args>'（含 resultType/formulaType/expression 的嵌套 JSON）。",
             retryable: false,

package/dist/contract-resources.js

@@ -5,6 +5,7 @@ import { DATARULE_LANE_CONTRACT } from "./lanes/datarule-contract.js";
 import { DICTIONARY_LANE_CONTRACT } from "./lanes/dictionary-contract.js";
 import { ENVIRONMENT_LANE_CONTRACT } from "./lanes/environment-contract.js";
 import { FIELD_LANE_CONTRACT } from "./lanes/field-contract.js";
+import { FOLDER_LANE_CONTRACT } from "./lanes/folder-contract.js";
 import { FORM_LANE_CONTRACT } from "./lanes/form-contract.js";
 import { LIST_VIEW_LANE_CONTRACT } from "./lanes/list-view-contract.js";
 import { META_LANE_CONTRACT } from "./lanes/meta-contract.js";
@@ -22,6 +23,7 @@ export const LANE_CONTRACTS = Object.freeze([
     DICTIONARY_LANE_CONTRACT,
     ENVIRONMENT_LANE_CONTRACT,
     FIELD_LANE_CONTRACT,
+    FOLDER_LANE_CONTRACT,
     FORM_LANE_CONTRACT,
     LIST_VIEW_LANE_CONTRACT,
     META_LANE_CONTRACT,

package/dist/coverage-registry.js

@@ -7,6 +7,7 @@ import { DATARULE_COVERAGE } from "./lanes/datarule-coverage.js";
 import { FIELD_COVERAGE } from "./lanes/field-coverage.js";
 import { FORM_COVERAGE } from "./lanes/form-coverage.js";
 import { LIST_VIEW_COVERAGE } from "./lanes/list-view-coverage.js";
+import { FOLDER_COVERAGE } from "./lanes/folder-coverage.js";
 import { MODEL_COVERAGE } from "./lanes/model-coverage.js";
 import { ONLINE_JS_COVERAGE } from "./lanes/online-js-coverage.js";
 import { RULE_LIFECYCLE_COVERAGE } from "./lanes/rule-lifecycle-coverage.js";
@@ -23,6 +24,7 @@ const DECLARATIONS = Object.freeze([
     ...APP_COVERAGE,
     ...DICTIONARY_COVERAGE,
     ...MODEL_COVERAGE,
+    ...FOLDER_COVERAGE,
     ...FIELD_COVERAGE,
     ...DATARULE_COVERAGE,
     ...FORM_COVERAGE,

package/dist/discovery.js

@@ -200,11 +200,29 @@ export function describeTool(registry, name) {
         // of a 133 KB task even though a matching recipe existed.
         ...(hasRecipe ? { exampleHint: `可运行参数用 --example <id>（~1–2KB）；单参数用 --param <name>；仅当二者都缺形状才 --full` } : {}),
         ...(!hasRecipe ? { exampleHint: `无静态 recipe：required + params 已够常规调用；单参数说明用 --param <name>；仅当需要全部参数注释/拒绝形状才 --full（5–20KB）` } : {}),
+        // 1.7 of issue 2026-10-23: the parameter DOC for `subFields` was only
+        // reachable through --param/--full, i.e. discovering a param needed its
+        // name first. Name the documented params inline (cheap: names only) so one
+        // `describe` answers "does this tool take X, and what is X called".
+        ...(documentedParamNames(tool).length > 0
+            ? { paramDocs: { available: documentedParamNames(tool), read: `omc describe ${tool.name} --param <name>（单个参数注释，几百字节）` } }
+            : {}),
         // 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）`,
     };
 }
+/** Param names whose schema entry carries a `.describe()` (documented params). */
+function documentedParamNames(tool) {
+    const shape = (tool.inputSchema ?? {});
+    const names = [];
+    for (const [key, value] of Object.entries(shape)) {
+        const description = value?.description;
+        if (typeof description === "string" && description.trim() !== "")
+            names.push(key);
+    }
+    return names.sort();
+}
 /** `omc describe <tool> --example <id>`: one recipe in full, by id. */
 export function describeExample(registry, name, exampleId) {
     const tool = registry.find((entry) => entry.name === name);

package/dist/endpoints.js

@@ -17,6 +17,22 @@ export const ENDPOINTS = {
     modelGetSummary: "/api/api/app/bizmodels/get_summary",
     modelUpdateSummary: "/api/api/app/bizmodels/update_summary",
     modelUpdate: "/api/api/app/bizmodels/update",
+    /**
+     * App-tree FOLDERS (目录/分组). AppFunctionController (/api/app/folders,
+     * 8.6.26 :90-260):
+     *   POST create  body AppFunctionVO {appCode, name, name_i18n?, parentId?, code?, icon?}
+     *   GET  get     ?folderId=
+     *   POST update  body AppFunctionVO {id, name, name_i18n?, parentId?}
+     *   POST delete  ?folderId=   (refuses a non-empty folder: DIRECTORY_NOT_EMPTY)
+     * createFolder defaults parentId to the app package id (root) and forces
+     * type=Folder; updateFolder refuses parentId === id. Live 2026-10-23 customer
+     * evidence: /api/app/folders/create answers 0 "成功创建目录"; tree readback is
+     * NESTED (children[]), so a caller must flatten recursively.
+     */
+    folderCreate: "/api/api/app/folders/create",
+    folderGet: "/api/api/app/folders/get",
+    folderUpdate: "/api/api/app/folders/update",
+    folderDelete: "/api/api/app/folders/delete",
     appPackagePhysicallyDelete: "/api/api/app/apppackage/physically_delete",
     fieldList: "/api/api/app/bizproperty/list",
     fieldGet: "/api/api/app/bizproperty/get",

package/dist/form-layout.js

@@ -14,6 +14,23 @@
  */
 export const ALLOWED_SPANS = new Set([6, 8, 12, 16, 18, 24]);
 export const FULL_SPAN = 24;
+/**
+ * 1.3 of issue 2026-10-23: these three classifications describe shapes the
+ * PLATFORM ITSELF stores — its default scaffold puts creater/createdTime/
+ * sequenceNo on one row (each defaulting to span 24 → "overflow"), and some
+ * published layouts list child columns as rows. Refusing them makes a
+ * read→write round-trip impossible, so they are warnings, not blockers.
+ * Coverage/span/options/type violations stay hard.
+ */
+export const SOFT_LAYOUT_CLASSIFICATIONS = new Set();
+// No classification is unconditionally soft: a caller-authored bad layout must
+// still refuse with ZERO wire. The platform's own readback is tolerated by
+// `form.draft`'s `fromReadback` path instead (issue 2026-10-23 §1.3), where the
+// supplied faces can be compared against the stored sheet. The default-width
+// row rule below still keeps the platform's scaffold rows from tripping.
+export function hardLayoutViolations(violations) {
+    return violations.filter((violation) => !SOFT_LAYOUT_CLASSIFICATIONS.has(violation.classification));
+}
 /** Child-table (Sheet 201) column keys, which must live on `columns`, never in rows. */
 function childColumnKeys(attrs) {
     const keys = new Set();
@@ -99,10 +116,16 @@ export function validateFormLayout(rows, attributes) {
         const codes = row.map((code) => String(code));
         const widths = codes.map((code) => spanOf(attrs, code, violations));
         const total = widths.reduce((sum, width) => sum + width, 0);
-        if (total > FULL_SPAN) {
+        // The platform's OWN scaffold writes rows like creater+createdTime+
+        // sequenceNo with NO explicit span (each defaults to 24) — rows made only of
+        // default-width system controls are the platform's shape, not a caller
+        // error (issue 2026-10-23 §1.3). Only a row that sets a span explicitly is
+        // judged by the width rules.
+        const hasExplicitSpan = codes.some((code) => attrs[code]?.options !== undefined && (attrs[code]?.options).span !== undefined);
+        if (hasExplicitSpan && total > FULL_SPAN) {
             violations.push({ classification: "layout_row_overflow", row: index + 1, message: `第 ${index + 1} 行 span 合计 ${total}，超过 ${FULL_SPAN}（${codes.join(" + ")}）` });
         }
-        if (codes.length !== 1 && widths.some((width) => width === FULL_SPAN)) {
+        if (hasExplicitSpan && codes.length !== 1 && widths.some((width) => width === FULL_SPAN)) {
             violations.push({ classification: "full_row_control_conflict", row: index + 1, message: `第 ${index + 1} 行含整行控件（span=24），不能与其他控件同行（${codes.join(" + ")}）` });
         }
     });

package/dist/form-support.js

@@ -4,7 +4,7 @@ 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 { deriveControlOptions } from "./capability-shape.js";
-import { validateFormLayoutShape } from "./form-layout.js";
+import { hardLayoutViolations, validateFormLayoutShape } from "./form-layout.js";
 /**
  * Propagate each relation field's `options.mappings` into its form control so
  * the form-fill carry is configured where the form renderer reads it. The
@@ -602,9 +602,7 @@ export function isEmptyLayoutJson(value) {
  * face (one-sided included), covering configure_form/apply_changes paths that
  * do not pass through the `form.draft` write permission gate.
  */
-export function assertCallerFormLayout(args) {
-    if (args.draftViewJson === undefined && args.draftAttributesJson === undefined)
-        return;
+export function formLayoutViolations(args) {
     const parse = (value) => {
         if (typeof value !== "string")
             return undefined;
@@ -615,7 +613,12 @@ export function assertCallerFormLayout(args) {
             return undefined;
         }
     };
-    const violations = validateFormLayoutShape(parse(args.draftViewJson), parse(args.draftAttributesJson));
+    return validateFormLayoutShape(parse(args.draftViewJson), parse(args.draftAttributesJson));
+}
+export function assertCallerFormLayout(args) {
+    if (args.draftViewJson === undefined && args.draftAttributesJson === undefined)
+        return;
+    const violations = hardLayoutViolations(formLayoutViolations(args));
     if (violations.length > 0) {
         throw new ToolRefusalError({
             status: "refused",
@@ -836,8 +839,6 @@ export async function executeFormDraftWrite(session, args) {
     }
     // Caller-provided layouts get the distribution-grade shape gate (options
     // objects, string viewJson cells, no child keys as rows) before any wire.
-    if (args.draftViewJson !== undefined || args.draftAttributesJson !== undefined)
-        assertCallerFormLayout(args);
     // Ticket 74 — refuse CALLER-PROVIDED empty layouts before any wire call.
     // The platform designer's Save clears draft faces to "[]"/"{}" (non-lossless);
     // re-writing that shape explicitly is how the 13-control loss happened.
@@ -888,6 +889,42 @@ export async function executeFormDraftWrite(session, args) {
         if (pre === null)
             throw new WireError("business", `form ${args.sheetCode} was created but is not readable`, 302024);
     }
+    //
+    // 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
+    // columns as rows; `layout_row_overflow` on the auto system row). Refusing a
+    // byte-identical round-trip makes "read → write back" impossible, so a face
+    // that matches the sheet's own published/draft face is allowed through with
+    // the violations reported as warnings. Caller-authored layouts stay strict.
+    const roundTripFaces = new Set();
+    let layoutWarnings = [];
+    if (args.draftViewJson !== undefined || args.draftAttributesJson !== undefined) {
+        const pre2 = pre;
+        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);
+        if (!allProvidedAreRoundTrip && args.fromReadback === true) {
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "form-layout-invalid",
+                schemaCode: args.schemaCode,
+                sheetCode: args.sheetCode,
+                message: "fromReadback:true 但本次布局与已存草稿/发布面不一致——读过之后又改过就必须按普通写面校验（去掉 fromReadback，或按 validation 修正）",
+                validation: formLayoutViolations(args),
+            });
+        }
+        if (allProvidedAreRoundTrip) {
+            layoutWarnings = formLayoutViolations(args);
+            if (args.draftViewJson !== undefined)
+                roundTripFaces.add("draftViewJson");
+            if (args.draftAttributesJson !== undefined)
+                roundTripFaces.add("draftAttributesJson");
+        }
+        else {
+            assertCallerFormLayout(args);
+        }
+    }
     // Field-level relation mappings are the source of truth; read the published
     // fields so the scaffold (or an existing draft) can carry them into the
     // matching form control, where the form renderer reads them at fill time.
@@ -1056,6 +1093,14 @@ export async function executeFormDraftWrite(session, args) {
             hasDraft: sheet.existDraft === true || typeof sheet.draftViewJson === "string",
             ...(formButtons !== null ? { formButtons, formButtonCodes: formButtons.map((button) => String(button.code ?? "")) } : {}),
             ...(mergedOptions !== undefined ? { customButtonJsonWritten: true } : {}),
+            ...(roundTripFaces.size > 0
+                ? {
+                    layoutGate: "platform-roundtrip",
+                    layoutRoundTripFaces: [...roundTripFaces],
+                    layoutNote: "本次布局与平台读回的原样布局一致，形状告警只提示不拒绝（平台自身产出可能含子表列行/系统行超宽）",
+                    ...(layoutWarnings.length > 0 ? { layoutWarnings } : {}),
+                }
+                : {}),
             ...(args.rebuild === true && previousAttributes ? { rebuildPreservedControls } : {}),
         },
     };