@stalfh233/omc-cli 0.4.98 → 0.4.100

package/dist/compound-writes.js

@@ -0,0 +1,310 @@
+/**
+ * r19 tickets 11–13 — 复合写命令。
+ *
+ * 16 轮账本里三对相邻调用（提交→读回 157 次 / 保存规则→启用 120 次 / 更新流
+ * 程模板→发布 93 次）：第二步是忘得最快、忘了就静默不生效的地方。三条命令把
+ * 各自的两步压成一次调用，两阶段各自回报。
+ *
+ * 共同纪律（与 omc call 的边界：这里封装的是**业务意图与顺序**，不是批量处理
+ * ——批处理仍走 call --args-list / omc script）：
+ *  - 默认 dry-run，显式 --apply 才写；
+ *  - 第一步失败立即停：提交绝不自动重试（写不可重放）、保存失败绝不启用半成
+ *    品、更新失败绝不发布；
+ *  - 阶段性结果如实回报：启用失败报「已保存但未启用」，发布失败保留草稿。
+ *
+ * 测试注入：invoke（默认走 runToolCall）与 emit（默认写 CLI 信封），进程内测
+ * 试用 harness.call 直连，不需要起服务器。
+ */
+import { runToolCall } from "./call.js";
+function defaultInvoke(environment) {
+    return async (tool, args) => {
+        const { result } = await runToolCall(tool, {
+            args: { ...args, ...(environment !== undefined && args.environment === undefined ? { environment } : {}) },
+            ...(environment !== undefined ? { environment } : {}),
+            print: () => undefined,
+        });
+        return result;
+    };
+}
+function isFailure(result) {
+    const status = String(result.status ?? "ok");
+    return status !== "ok" && status !== "dry-run";
+}
+/**
+ * 提交差异归一：平台读回可能把 {id} 展开成对象、数字存成字符串。比较双方先
+ * 解包到可比形式，只有真正不同才进 diff（假阴性比噪音 diff 危险，假阳性
+ * diff 只是浪费注意力）。
+ */
+function normalizeForDiff(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (Array.isArray(value))
+        return value.map((entry) => normalizeForDiff(entry));
+    if (typeof value === "object") {
+        const record = value;
+        if (typeof record.id === "string" && Object.keys(record).length <= 3)
+            return record.id;
+        return Object.fromEntries(Object.entries(record).map(([key, entry]) => [key, normalizeForDiff(entry)]));
+    }
+    return typeof value === "string" ? value.trim() : value;
+}
+function equalAfterNormalize(sent, got) {
+    const left = normalizeForDiff(sent);
+    const right = normalizeForDiff(got);
+    if (left === right)
+        return true;
+    try {
+        return JSON.stringify(left) === JSON.stringify(right);
+    }
+    catch {
+        return false;
+    }
+}
+function diffSubmittedAgainstLoaded(sent, loaded) {
+    const diff = {};
+    if (!loaded || typeof loaded !== "object")
+        return diff;
+    for (const [key, value] of Object.entries(sent)) {
+        const got = loaded[key];
+        if (!equalAfterNormalize(value, got))
+            diff[key] = { sent: value, got: got ?? null };
+    }
+    return diff;
+}
+function bizObjectIdOf(submitResult) {
+    const readback = (submitResult.readback ?? {});
+    const submittedData = (readback.submittedData ?? {});
+    const performed = (submitResult.performed ?? {});
+    for (const candidate of [readback.objectId, readback.bizObjectId, submittedData.bizObjectId, submittedData.id, performed.bizObjectId]) {
+        if (typeof candidate === "string" && candidate.length > 0)
+            return candidate;
+    }
+    return undefined;
+}
+export async function runSubmitVerify(options) {
+    const invoke = options.invoke ?? defaultInvoke(options.environment);
+    const emit = options.emit ?? (() => undefined);
+    if (!options.schema) {
+        emit({ status: "error", blocker: "invalid-input", message: "--schema 必填" }, "error");
+        return 1;
+    }
+    if (options.rows.length === 0) {
+        emit({ status: "error", blocker: "invalid-input", message: "--rows 至少一条（JSON 数组或单对象）" }, "error");
+        return 1;
+    }
+    if (!options.apply) {
+        emit({
+            status: "ok",
+            dryRun: true,
+            schemaCode: options.schema,
+            plannedRows: options.rows.length,
+            rowKeys: options.rows.map((row) => Object.keys(row)),
+            note: "dry-run 仅预览；--apply 逐条 data.submit → 用真实 id data.load → 回报差异。提交失败立即停（不重试、不降级）；差异是发现不是失败。批处理（不需要读回）用 omc call data.submit --args-list。",
+        }, "ok");
+        return 0;
+    }
+    const rows = [];
+    let verified = 0;
+    let mismatched = 0;
+    for (let index = 0; index < options.rows.length; index += 1) {
+        const formData = options.rows[index];
+        // 提交不可重放：一次失败立即停——重试同参数在写路径上是危险的乐观。
+        const submit = await invoke("data.submit", { schemaCode: options.schema, formData });
+        if (isFailure(submit)) {
+            emit({
+                status: submit.status,
+                schemaCode: options.schema,
+                stoppedAtIndex: index,
+                rows,
+                retried: false,
+                failure: { index, tool: "data.submit", result: submit },
+                message: `第 ${index + 1} 条提交被拒/失败——立即停止，未重试、未降级；前面 ${index} 条已提交的各自见 rows`,
+            }, String(submit.status));
+            return 1;
+        }
+        const bizObjectId = bizObjectIdOf(submit);
+        if (bizObjectId === undefined) {
+            emit({
+                status: "error",
+                schemaCode: options.schema,
+                stoppedAtIndex: index,
+                rows,
+                retried: false,
+                failure: { index, tool: "data.submit", result: submit, reason: "提交成功但读回没给 bizObjectId——无法读回验证" },
+                message: "提交成功但回执缺少 bizObjectId，无法读回（不猜 id）",
+            }, "error");
+            return 1;
+        }
+        const loaded = await invoke("data.load", { schemaCode: options.schema, bizObjectId });
+        const loadData = (loaded.data ?? loaded.content ?? null);
+        const diff = diffSubmittedAgainstLoaded(formData, loadData);
+        if (Object.keys(diff).length === 0)
+            verified += 1;
+        else
+            mismatched += 1;
+        rows.push({
+            index,
+            status: "ok",
+            bizObjectId,
+            verified: Object.keys(diff).length === 0,
+            diff,
+        });
+    }
+    emit({
+        status: "ok",
+        schemaCode: options.schema,
+        rows,
+        summary: { submitted: rows.length, verified, mismatched },
+        note: mismatched > 0 ? "有字段读回与提交不一致（见各行 diff）——差异是发现不是失败；常见原因：日期/关联字段平台侧归一化，先核对是否实质差异" : undefined,
+    }, "ok");
+    return 0;
+}
+export async function runRuleSaveEnable(options) {
+    const invoke = options.invoke ?? defaultInvoke(options.environment);
+    const emit = options.emit ?? (() => undefined);
+    if (!options.schema || !options.ruleCode || !options.name || !options.nodeGraph) {
+        emit({ status: "error", blocker: "invalid-input", message: "--schema/--rule-code/--name/--node-graph 全部必填" }, "error");
+        return 1;
+    }
+    if (!options.apply) {
+        emit({
+            status: "ok",
+            dryRun: true,
+            schemaCode: options.schema,
+            ruleCode: options.ruleCode,
+            phases: ["rule.save（upsert）", "rule.enable"],
+            note: "dry-run 仅预览；--apply 先保存、保存成功才启用。规则保存后默认禁用——不启用就不会运行（16 轮账本里这步相邻遗漏 120 次）。",
+        }, "ok");
+        return 0;
+    }
+    const save = await invoke("rule.save", {
+        schemaCode: options.schema,
+        ruleCode: options.ruleCode,
+        name: options.name,
+        nodeGraph: options.nodeGraph,
+        ...(options.publish === true ? { publish: true } : {}),
+    });
+    if (isFailure(save)) {
+        emit({
+            status: save.status,
+            phase: "save",
+            willRun: false,
+            saved: save,
+            message: "保存失败——规则未落库，绝不启用半成品；修正 nodeGraph 后重跑",
+        }, String(save.status));
+        return 1;
+    }
+    const enable = await invoke("rule.enable", { schemaCode: options.schema, ruleCode: options.ruleCode });
+    if (isFailure(enable)) {
+        emit({
+            status: enable.status,
+            phase: "enable",
+            willRun: false,
+            saved: save,
+            enabled: enable,
+            message: "已保存但未启用——规则现在不会运行；排查启用失败原因后单跑 omc call rule.enable（草稿已保留，不需要重保存）",
+        }, String(enable.status));
+        return 1;
+    }
+    emit({
+        status: "ok",
+        schemaCode: options.schema,
+        ruleCode: options.ruleCode,
+        saved: save,
+        enabled: enable,
+        willRun: true,
+        answer: "会运行：规则已保存且已启用",
+    }, "ok");
+    return 0;
+}
+/**
+ * 合并语义显式化：先读当前草稿，算出新模板没覆盖的旧节点。
+ *  - 默认（无 --confirm-replace）：旧节点**保留**——追加进最终模板（插在 END
+ *    节点之前），回执 preservedNodes 列明；
+ *  - --confirm-replace：按调用者模板原样发送，旧节点被丢弃，回执
+ *    droppedNodes 列明。
+ * 两种路径都不依赖平台的合并/整替行为：最终模板由本命令显式合成。
+ */
+function composeFinalTemplate(draftActivities, template, confirmReplace) {
+    const newCodes = new Set((template.activities ?? []).map((activity) => String(activity.activityCode ?? "")));
+    const oldNodes = draftActivities.filter((activity) => {
+        const code = String(activity.activityCode ?? "");
+        return code !== "" && !newCodes.has(code);
+    });
+    const oldCodes = oldNodes.map((activity) => String(activity.activityCode ?? ""));
+    if (confirmReplace || oldCodes.length === 0) {
+        return { finalTemplate: template, preservedNodes: [], droppedNodes: confirmReplace ? oldCodes : [] };
+    }
+    const activities = template.activities ?? [];
+    const endIndex = activities.findIndex((activity) => String(activity.activityType ?? "").toUpperCase() === "END");
+    const merged = endIndex >= 0
+        ? [...activities.slice(0, endIndex), ...oldNodes, ...activities.slice(endIndex)]
+        : [...activities, ...oldNodes];
+    return { finalTemplate: { ...template, activities: merged }, preservedNodes: oldCodes, droppedNodes: [] };
+}
+export async function runWorkflowUpdatePublish(options) {
+    const invoke = options.invoke ?? defaultInvoke(options.environment);
+    const emit = options.emit ?? (() => undefined);
+    if (!options.schema || !options.code || !options.template) {
+        emit({ status: "error", blocker: "invalid-input", message: "--schema/--code/--template 必填" }, "error");
+        return 1;
+    }
+    const draft = options.apply ? await invoke("workflow.get_draft", { schemaCode: options.schema, ...(options.code ? { code: options.code } : {}) }) : { status: "ok", data: null };
+    const draftData = (draft.data ?? null);
+    const draftActivities = (draftData?.activities ?? draftData?.template?.activities ?? []);
+    const { finalTemplate, preservedNodes, droppedNodes } = composeFinalTemplate(draftActivities, options.template, options.confirmReplace === true);
+    if (!options.apply) {
+        emit({
+            status: "ok",
+            dryRun: true,
+            schemaCode: options.schema,
+            workflowCode: options.code,
+            preservedNodes,
+            droppedNodes: options.confirmReplace === true ? droppedNodes : [],
+            finalTemplate,
+            note: "dry-run 仅合成预览；--apply 走 workflow.update（上面的 finalTemplate）→ workflow.publish。默认保留旧节点（preservedNodes）；--confirm-replace 才允许丢弃（droppedNodes）。",
+        }, "ok");
+        return 0;
+    }
+    const update = await invoke("workflow.update", { schemaCode: options.schema, code: options.code, template: finalTemplate });
+    if (isFailure(update)) {
+        emit({
+            status: update.status,
+            phase: "update",
+            update,
+            message: "更新失败——立即停止，未发布；草稿保持原样",
+        }, String(update.status));
+        return 1;
+    }
+    const publish = await invoke("workflow.publish", { schemaCode: options.schema, code: options.code });
+    if (isFailure(publish)) {
+        emit({
+            status: publish.status,
+            phase: "publish",
+            update,
+            published: publish,
+            preservedNodes,
+            droppedNodes,
+            message: "已更新未发布——模板改动保留在草稿；发布失败原因见 published，处理后单跑 omc call workflow.publish",
+        }, String(publish.status));
+        return 1;
+    }
+    emit({
+        status: "ok",
+        schemaCode: options.schema,
+        workflowCode: options.code,
+        update,
+        published: publish,
+        finalTemplate,
+        preservedNodes,
+        droppedNodes,
+        ...(preservedNodes.length > 0
+            ? { mergeWarning: `合并语义：旧节点 ${preservedNodes.join("、")} 不在新模板里、默认保留（已追加进 finalTemplate）。要丢弃请用 --confirm-replace 重跑。` }
+            : {}),
+        ...(options.confirmReplace === true && droppedNodes.length > 0
+            ? { replaceWarning: `确认替换：旧节点 ${droppedNodes.join("、")} 已被丢弃（不在 finalTemplate 里）。` }
+            : {}),
+    }, "ok");
+    return 0;
+}
+//# sourceMappingURL=compound-writes.js.map

package/dist/discovery.js

@@ -88,17 +88,57 @@ export function commandInventory(registry, options = {}) {
     };
 }
 /**
- * Bare `omc commands` (no `--json`, no `--compact`, no scope): a bounded INDEX,
- * not the 54 KB catalogue.
+ * r19 ticket 05 — semantic `commands --filter`.
  *
- * Round 9 heavy-task measurement (sandbox 38): an agent exploring cold ran bare
- * `commands` 4× at ~54 KB each — ~216 KB, 28% of the whole task — even though
- * the full rows are the fallback face and `next`/`--compact --lane` exist. The
- * bytes were paid before any hint could be read. So the DEFAULT face is now the
- * lean index (name/lane/kind + lane counts + how to expand); the full rows
- * require the documented machine entry `commands --json`, and one capability is
- * `commands --json --compact --lane <lane>`.
+ * The old filter matched only `name + lane + capability id` substrings, so an
+ * agent asking in capability language（「聚合」「字典」「业务集成」）got an
+ * empty list plus the full governance prose and had to re-read the 20 KB
+ * catalogue. The semantic face matches, in authority order: tool name →
+ * capability aliases/title/id → recipe id/title/aliases → tool description,
+ * with case and separator (`.`/`-`/`_`/space) normalization on both sides.
+ * Deterministic: hits sort by matched-field authority, then name.
  */
+export function filterTools(registry, query) {
+    const rawQuery = query.trim().toLowerCase();
+    if (rawQuery.length === 0)
+        return [];
+    const normalizedQuery = normalizeFaceText(query);
+    const routeByLane = capabilityRouteIndex(registry).routeByLane;
+    const hits = [];
+    for (const tool of registry) {
+        const capability = tool.lane ? routeByLane.get(tool.lane) : undefined;
+        const fields = [
+            { label: "工具名", text: tool.name },
+            ...(capability ? [
+                { label: `能力 ${capability.id} 别名`, text: capability.aliases.join(" ") },
+                { label: `能力 ${capability.id} 标题`, text: capability.title },
+                { label: "能力 id", text: capability.id },
+            ] : []),
+            ...(tool.executionMetadata?.recipes ?? []).flatMap((recipe) => [
+                { label: `配方 ${recipe.id} 标题`, text: recipe.title },
+                { label: "配方 id", text: recipe.id },
+                { label: `配方 ${recipe.id} 别名`, text: (recipe.aliases ?? []).join(" ") },
+            ]),
+            { label: "工具摘要", text: tool.description },
+        ];
+        let via;
+        let rank = 0;
+        for (const field of fields) {
+            const lower = field.text.toLowerCase();
+            if (lower.includes(rawQuery) || normalizeFaceText(field.text).includes(normalizedQuery)) {
+                via = `${field.label}含 "${query.trim()}"`;
+                break;
+            }
+            rank += 1;
+        }
+        if (via !== undefined)
+            hits.push({ name: tool.name, via, rank });
+    }
+    return hits.sort((left, right) => left.rank - right.rank || left.name.localeCompare(right.name)).map(({ name, via }) => ({ name, via }));
+}
+function normalizeFaceText(text) {
+    return text.toLowerCase().replace(/[._\s-]/g, "");
+}
 export function commandIndex(registry) {
     const byLane = new Map();
     for (const tool of registry) {
@@ -177,6 +217,178 @@ function exampleList(tool) {
         requiresPriorReadback: recipe.requiresEnvironmentDerivedIds,
     }));
 }
+/**
+ * `firstCall`: one runnable minimal shape, inline.
+ *
+ * r18 measured 71 adjacent `describe <tool>` → `describe <tool> --example <id>`
+ * pairs across 16 rounds: the compact default named the recipes but withheld
+ * the args, so learning the shape cost a second turn. The default now carries
+ * the cheapest *offline-valid* recipe (deterministic: status, then args bytes,
+ * then id) with its args inlined when small enough to stay a cheap face.
+ *
+ * Two honesty rules, because a wrong shape here is worse than no shape:
+ *  - shipped recipes use stand-in ids (`omc_recipe_model`, `<environment>`).
+ *    They are rewritten to explicit `<...>` placeholders and listed in
+ *    `missing`, so nothing pretends to be a legal value.
+ *  - `executable` is true only when `missing` is empty. Today that is never,
+ *    because every authored recipe is a template; the field exists so a future
+ *    concrete recipe becomes executable without a shape change.
+ */
+const RECIPE_INLINE_ARGS_CEILING = 1_000;
+const RECIPE_PLACEHOLDER_MODEL = "omc_recipe_model";
+const RECIPE_PLACEHOLDER_ENV = "<environment>";
+const PLACEHOLDER_SOURCES = {
+    environment: "omc env / 项目 .omc-env",
+    schemaCode: "omc call model.list（models[].schemaCode）",
+    workflowCode: "omc call workflow.get_published（workflow.code）",
+    bizObjectId: "data.save 读回的 performed.bizObjectId",
+    workflowInstanceId: "data.save 读回的 performed.workflowInstanceId",
+    workItemId: "data.save 读回的 performed.workItemId",
+    propertyCode: "omc call field.list（fields[].code）",
+    code: "任务要求；模型/应用内唯一",
+    name: "任务要求",
+    propertyType: "按 inputSchema / 任务要求选枚举值",
+};
+/**
+ * Keys whose value always comes from the caller's own environment, never from
+ * the recipe. A recipe may name a concrete example (`wms_material`), but
+ * presenting that as the first call would send a write at the wrong model —
+ * the exact failure mode this projection exists to avoid. The literal is
+ * rewritten to `<key>` and named in `missing` with its source.
+ */
+const CONTEXT_KEYS = new Set([
+    "environment",
+    "schemaCode",
+    "schemaCodes",
+    "sheetCode",
+    "workflowCode",
+    "bizObjectId",
+    "bizObjectIds",
+    "workflowInstanceId",
+    "workItemId",
+    "propertyCode",
+    "propertyCodes",
+    "appCode",
+    "parentCode",
+    // Service/dictionary/form identifiers are also tenant-specific: a sample
+    // `wms_material_service` pasted into another environment fails at the
+    // platform, not at the CLI gate.
+    "serviceCode",
+    "serviceMethodCode",
+    "serviceMethodParameterCode",
+    "dictionaryCode",
+    "recordCode",
+    "formCode",
+    "formSchemaCode",
+]);
+function contextValue(key) {
+    return key === "environment" ? "<env>" : `<${key}>`;
+}
+function hasPlaceholder(value) {
+    if (typeof value === "string") {
+        return value.includes(RECIPE_PLACEHOLDER_MODEL) || value === RECIPE_PLACEHOLDER_ENV || /<[^<>]+>/.test(value);
+    }
+    if (Array.isArray(value))
+        return value.some(hasPlaceholder);
+    if (value && typeof value === "object")
+        return Object.values(value).some(hasPlaceholder);
+    return false;
+}
+/** Replace stand-in ids with explicit placeholders; never invent a real-looking id. */
+function replacePlaceholders(value, key) {
+    if (key !== undefined && CONTEXT_KEYS.has(key)) {
+        return Array.isArray(value) ? [contextValue(key)] : contextValue(key);
+    }
+    if (typeof value === "string")
+        return value.split(RECIPE_PLACEHOLDER_MODEL).join("<existing-model-schemaCode>");
+    if (Array.isArray(value))
+        return value.map((entry) => replacePlaceholders(entry));
+    if (value && typeof value === "object") {
+        const output = {};
+        for (const [entryKey, entry] of Object.entries(value))
+            output[entryKey] = replacePlaceholders(entry, entryKey);
+        return output;
+    }
+    return value;
+}
+function placeholderKeys(args) {
+    return Object.entries(args)
+        .filter(([key, value]) => CONTEXT_KEYS.has(key) || hasPlaceholder(value))
+        .map(([key]) => key)
+        .sort();
+}
+function trimPreconditions(preconditions) {
+    const kept = [];
+    let bytes = 0;
+    for (const entry of preconditions) {
+        const next = bytes + Buffer.byteLength(entry, "utf8") + 4;
+        if (kept.length >= 3 || next > 420)
+            break;
+        kept.push(entry);
+        bytes = next;
+    }
+    return kept;
+}
+function selectRecipe(recipes) {
+    if (recipes.length === 0)
+        return undefined;
+    const ranked = [...recipes].sort((left, right) => {
+        const leftRank = left.status === "offline-valid" ? 0 : 1;
+        const rightRank = right.status === "offline-valid" ? 0 : 1;
+        if (leftRank !== rightRank)
+            return leftRank - rightRank;
+        const leftBytes = Buffer.byteLength(JSON.stringify(left.args), "utf8");
+        const rightBytes = Buffer.byteLength(JSON.stringify(right.args), "utf8");
+        if (leftBytes !== rightBytes)
+            return leftBytes - rightBytes;
+        return left.id.localeCompare(right.id);
+    });
+    return ranked[0];
+}
+function firstCallFor(tool) {
+    const recipe = selectRecipe(tool.executionMetadata?.recipes ?? []);
+    if (!recipe)
+        return undefined;
+    const rawArgs = recipe.args;
+    const hoistedEnvironment = "environment" in rawArgs;
+    const withoutEnv = {};
+    for (const [key, value] of Object.entries(rawArgs))
+        if (key !== "environment")
+            withoutEnv[key] = value;
+    const inlined = replacePlaceholders(withoutEnv);
+    const inlinedJson = JSON.stringify(inlined);
+    const argsBytes = Buffer.byteLength(inlinedJson, "utf8");
+    const missing = [...(hoistedEnvironment ? ["environment"] : []), ...placeholderKeys(withoutEnv)];
+    // A single quote cannot ride inside `--args '<json>'`; fall back to the file
+    // form rather than emit a command that is subtly wrong when pasted.
+    const inline = argsBytes <= RECIPE_INLINE_ARGS_CEILING;
+    // Above the one-liner size, `args` already carries the shape; repeating it as
+    // a shell-quoted `command` doubles the bytes for no new information.
+    const inlineCommand = inline && argsBytes <= 512 && !inlinedJson.includes("'");
+    const firstCall = {
+        recipeId: recipe.id,
+        ...(inline
+            ? {
+                args: inlined,
+                ...(inlineCommand
+                    ? { command: `omc call ${tool.name}${hoistedEnvironment ? " --env <env>" : ""} --args '${inlinedJson}'` }
+                    : { commandHint: `把上面的 args 原样作为 --args '<json>' 传给 omc call ${tool.name}${hoistedEnvironment ? " --env <env>" : ""}` }),
+                note: "args 里的标识（模型/服务/字段 code）来自示例环境，需换成你自己的",
+            }
+            : { argsBytes, note: `配方参数 ${argsBytes}B，超过默认内联上限；用 readMore 取完整形状（不要凭这一行猜 args）` }),
+        executable: missing.length === 0,
+        ...(missing.length > 0 ? { missing } : {}),
+        ...(missing.length > 0
+            ? {
+                requiredValues: Object.fromEntries(missing.map((key) => [key, { value: key === "environment" ? "<env>" : `<${key}>`, source: PLACEHOLDER_SOURCES[key] ?? "按 inputSchema 或任务要求" }])),
+            }
+            : {}),
+        preconditions: trimPreconditions(recipe.preconditions),
+        requiresPriorReadback: recipe.requiresEnvironmentDerivedIds,
+        readMore: `omc describe ${tool.name} --example ${recipe.id}`,
+    };
+    return firstCall;
+}
 /** Default `omc describe`: the compact contract projection. */
 export function describeTool(registry, name) {
     const tool = registry.find((entry) => entry.name === name);
@@ -186,6 +398,7 @@ export function describeTool(registry, name) {
     const { required, params } = compactParams(schema);
     const examples = exampleList(tool);
     const hasRecipe = (tool.executionMetadata?.recipes.length ?? 0) > 0;
+    const firstCall = firstCallFor(tool);
     return {
         name: tool.name,
         lane: tool.lane ?? null,
@@ -194,6 +407,7 @@ export function describeTool(registry, name) {
         required,
         params,
         examples,
+        ...(firstCall !== undefined ? { firstCall } : {}),
         // Point cold callers at the cheap runnable face BEFORE they reach for
         // --full: a recipe is ~1–2 KB and a single --param is a few hundred bytes,
         // while --full is 5–20 KB. Benchmark (bench13): two --full calls were 34 KB

package/dist/field-families.js

@@ -954,6 +954,33 @@ export function assertFieldOptionsAllowed(type, options, schemaCode) {
                 const agg = parseOptionsObject(config.aggregation);
                 if (!agg || !isNonEmptyString(agg.schemaCode) || !isNonEmptyString(agg.dataItemCode) || !isNonEmptyString(agg.formula))
                     refuseFieldOptions("AGGREGATION aggregation is missing schemaCode/dataItemCode/formula", 'rejected: aggregation 形状 {schemaCode:"<目标模型schemaCode>", dataItemCode:"<目标字段code>", formula:"SUM({<目标模型>.<字段>})", calculateType:"SUM", queryConditions:[[…]]}（FormulaProcessor.executeMainAggregation + AggregationFormula）');
+                // r18b (2026-10-26 live): LARGE/SMALL take a position argument and the
+                // platform evaluates the FORMULA, so `LARGE({col})` (no k) throws
+                // NumberFormatException internally and the target write answers 50000.
+                const calcType = typeof agg.calculateType === "string" ? agg.calculateType.toUpperCase() : "";
+                if (["LARGE", "SMALL"].includes(calcType) && !/(LARGE|SMALL)\s*\(\s*[^,()]+\s*,/.test(String(agg.formula)))
+                    throw new ToolRefusalError({
+                        status: "refused",
+                        blocker: "aggregation-large-missing-k",
+                        schemaCode: schemaCode ?? null,
+                        calculateType: calcType,
+                        formula: String(agg.formula),
+                        message: `${calcType} 必须带位置参数 k：写成 ${calcType}({<来源模型>.<数值列>},<k>)（k=1 是最大/最小）。` +
+                            `缺 k 时平台内部抛 NumberFormatException（日志可见），目标模型写入一律 50000（r18b 真机）。` +
+                            `真机验证：LARGE({src.amt},2) 对 10/30/20 返回 20；SMALL({src.amt},1) 返回 10。`,
+                    });
+                // UNION concatenates DISTINCT text values ("去重后拼接文本"), so a numeric
+                // resultType makes the aggregation parse text as a number and the write
+                // 50000s. Text result types: SHORT_TEXT(0) / LONG_TEXT(1).
+                if (calcType === "UNION" && ![0, 1].includes(Number(agg.resultType ?? 2)))
+                    throw new ToolRefusalError({
+                        status: "refused",
+                        blocker: "aggregation-union-result-type",
+                        schemaCode: schemaCode ?? null,
+                        resultType: Number(agg.resultType ?? 2),
+                        message: `UNION 是「去重后拼接文本」，resultType 必须是文本类型（0=SHORT_TEXT / 1=LONG_TEXT；顶层 formulaConfig.resultType 决定）。` +
+                            `用数值 resultType 时平台把拼接结果按数字解析 → NumberFormatException → 目标写入 50000（r18b 真机：resultType:2 失败，0 成功，读回 "P1"）。`,
+                    });
                 if (String(agg.dataItemCode).includes("."))
                     throw new ToolRefusalError({
                         status: "refused",