@stalfh233/omc-cli 0.6.12 → 0.6.14

package/dist/recipes/workflow.js

@@ -92,6 +92,91 @@ const workflowConditionalBranch = Object.freeze({
     requiresEnvironmentDerivedIds: true,
     prerequisiteData: { source: "workflow.get_draft", fields: ["activities[].activityCode", "org.role code"] },
 });
+/**
+ * r31c F24: two-level / one-level fork-then-join. The single-layer
+ * `workflow-conditional-branch` recipe only shows A2→A3(cond) / A2→END(else).
+ * Agents that extend it to "金额>X 走两级、否则一级" often add a second
+ * conditional edge on the same pre/post pair (401013) or leave A_mgr with no
+ * else outbound (dead-end graph that validate still marks valid:true — F23).
+ *
+ * Shape (amount > 50000 → mgr → gm → END; else mgr → END):
+ *   START → 填写 → 主管审批 ─┬─(GT 50000)→ 总经理审批 → END
+ *                            └─(else)───────────────→ END
+ */
+const workflowConditionalTwoLevel = Object.freeze({
+    id: "workflow-conditional-two-level-approval",
+    title: "金额>阈值走两级审批，否则一级（分叉再汇合）",
+    status: "requires-prior-readback",
+    aliases: ["两级审批", "条件两级", "金额大于", "一级或两级", "分叉再汇合"],
+    tool: "workflow.update",
+    args: {
+        environment,
+        schemaCode: model,
+        code: "purchaseWorkflow",
+        template: {
+            workflowCode: "purchaseWorkflow",
+            activities: [
+                { activityCode: "Activity1", activityType: "START", activityName: "开始", i18nMessage: "开始" },
+                { activityCode: "Activity2", activityType: "PARTICIPANT", activityName: "填写申请单", i18nMessage: "填写申请单", participant: "{Originator}" },
+                {
+                    activityCode: "A_mgr",
+                    activityType: "PARTICIPANT",
+                    activityName: "部门主管审批",
+                    i18nMessage: "部门主管审批",
+                    // Correct object shape (r31c F20): code/corpId/id/name/type — NOT participantType/roleId.
+                    participant: JSON.stringify([{ code: "SYS_1000000", corpId: "other", id: "<roleId-from-org.role.list>", name: "主管", type: 2 }]),
+                },
+                {
+                    activityCode: "A_gm",
+                    activityType: "PARTICIPANT",
+                    activityName: "总经理审批",
+                    i18nMessage: "总经理审批",
+                    participant: JSON.stringify([{ code: "<gm-role-code>", corpId: "other", id: "<gm-roleId>", name: "总经理", type: 2 }]),
+                },
+                { activityCode: "Activity5", activityType: "END", activityName: "结束", i18nMessage: "结束" },
+            ],
+            routes: [
+                { preNode: "Activity1", postNode: "Activity2" },
+                { preNode: "Activity2", postNode: "A_mgr" },
+                // Fork at A_mgr: high amount → second level; else → END. Same pre/post
+                // pair must NOT carry both an unconditional edge and a condition edge
+                // (platform 401013). Else uses utilizeElse:true on a DIFFERENT postNode.
+                { preNode: "A_mgr", postNode: "A_gm", ruleConditionGroup: [[{ currentDataItem: "totalAmount", bizPropertyType: 2, conditionType: "GT", value: "50000" }]] },
+                { preNode: "A_mgr", postNode: "Activity5", utilizeElse: true },
+                { preNode: "A_gm", postNode: "Activity5" },
+            ],
+        },
+    },
+    preconditions: [
+        "workflow.create 已完成；org.role.list 取真实角色 code/id 填 participant",
+        "数值字段已发布；bizPropertyType 用数字索引（NUMERICAL=2）",
+        "**整图替换**：省略 merge，否则旧 PARTICIPANT 节点会留下",
+    ],
+    conditionalRequirements: [
+        "**participant 对象数组只认 `{code,corpId,id,name,type}`**（type 2=角色 3=用户）。`participantType`/`roleId`/`participantName` 会被平台静默丢掉，读回变成 `[{}]`，validate 仍 valid、publish 才 warning——待办派不出去（r31c F20）。",
+        "**同一对 pre/post 不能既有无条件边又有条件边**（平台 401013「节点名A&节点名B」）。条件边与 else 边的 postNode 必须不同。",
+        "**有条件边的节点必须有 else 兜底**，否则条件不满足时流程断头；`workflow.validate` 会以 `reachabilityWarnings` 点名这类节点（warning，不阻断发布）。",
+        "汇合边（A_gm→END）是无条件边；不要再给 A_mgr→A_gm 加一条无条件边。",
+        "线性无分支请用 `omc approval-flow`；本配方只覆盖条件两级/一级。",
+    ],
+    priorToolReferences: [
+        { tool: "workflow.get_draft", args: { environment, workflowCode: "purchaseWorkflow" }, purpose: "取草稿基线；默认面含 activityCode/edges" },
+        { tool: "org.role.list", args: { environment }, purpose: "取角色 code/id 填 participant 对象（不要用自由文本名）" },
+    ],
+    dryRun: { supported: true, command: `omc call workflow.update --env ${environment} --dry-run --args '<recipe.args>'`, notes: "dry-run 校验 activities/routes/条件叶；不写入" },
+    expectedReadback: {
+        readback: { draftUpdated: true, rules: 2 },
+        next: ["workflow.validate", "workflow.publish", "data.submit 两条（>50000 / ≤50000）验 workitem.list"],
+    },
+    refusalRecovery: [
+        { code: "401013", action: "同一 pre/post 对重复连线或「条件边+无条件边」冲突——拆成不同 postNode，else 用 utilizeElse:true" },
+        { code: "workflow-route-condition-invalid", action: "条件叶只留 currentDataItem/bizPropertyType/conditionType/value" },
+        { code: "workflow-not-found", action: "先 workflow.create，再 get_draft 取基线" },
+        ...commonRecovery,
+    ],
+    requiresEnvironmentDerivedIds: true,
+    prerequisiteData: { source: "workflow.get_draft + org.role.list", fields: ["activities[].activityCode", "roles[].code", "roles[].id"] },
+});
 const workflowBinding = Object.freeze({
     id: "workflow-handler-binding",
     title: "将规则合并绑定到 workflow handler 并发布",
@@ -116,7 +201,7 @@ const workflowBinding = Object.freeze({
     prerequisiteData: { source: "workflow.get_draft + rule.list", fields: ["workflow.code", "rule.code"] },
 });
 export const WORKFLOW_METADATA = Object.freeze({
-    "workflow.update": Object.freeze({ recipes: [workflowTemplateUpdate, workflowConditionalBranch], relatedTools: ["workflow.get_draft", "workflow.publish"] }),
+    "workflow.update": Object.freeze({ recipes: [workflowTemplateUpdate, workflowConditionalBranch, workflowConditionalTwoLevel], relatedTools: ["workflow.get_draft", "workflow.publish"] }),
     "workflow.bindRule": Object.freeze({ recipes: [workflowBinding], relatedTools: ["workflow.create", "workflow.get_draft", "workflow.get_published", "rule.list"] }),
 });
 //# sourceMappingURL=workflow.js.map

package/dist/refusal-guidance.js

@@ -15,12 +15,18 @@ const SHAPE_GATES = Object.freeze({
         recipeCommand: { tool: "data.submit", recipe: "plain-data-submit" },
         doNot: "不要传毫秒数（如 1790000000000）——不报错但落库 NULL，读回才发现",
     },
+    "child-rows-missing-id": {
+        whatWentWrong: "更新已有记录时，子表行没带 id",
+        correctShape: "三合一：既有行带 id（改）；追加行 {…, rowStatus:\"Added\"}；删除行 {id, rowStatus:\"Deleted\"}（只给 id）。少传行不会删",
+        recipeCommand: { tool: "data.update", recipe: "child-rows-upsert" },
+        doNot: "不要用同一批无 id 子行重试 update——每次都会再插一遍（r17 实测 2 行变 8 行）；也不要靠少传行删行",
+    },
+    // 旧名兼容（r29b F7 前叫 submit-…，data.update 也会抛）
     "submit-child-rows-missing-id": {
         whatWentWrong: "更新已有记录时，子表行没带 id",
-        correctShape: "更新时子表行必须带平台 id（新增行才省略）；无 id 的行会被当**新增**插入，不判重",
-        command: undefined,
-        recipeCommand: { tool: "data.update", recipe: "plain-data-submit" },
-        doNot: "不要用同一批无 id 子行重试 update——每次都会再插一遍（r17 实测 2 行变 8 行）",
+        correctShape: "三合一：既有行带 id（改）；追加行 {…, rowStatus:\"Added\"}；删除行 {id, rowStatus:\"Deleted\"}（只给 id）。少传行不会删",
+        recipeCommand: { tool: "data.update", recipe: "child-rows-upsert" },
+        doNot: "不要用同一批无 id 子行重试 update——每次都会再插一遍（r17 实测 2 行变 8 行）；也不要靠少传行删行",
     },
     "submit-approval-agree-misplaced": {
         whatWentWrong: "agree 放在了 approval 对象里，平台只读顶层 agree",
@@ -105,7 +111,9 @@ const SHAPE_GATES = Object.freeze({
  * retry command — a command that would fail again is worse than none.
  */
 const FIX_FIRST_GATES = Object.freeze({
-    "workflow-start-permission-denied": "40009 有三个独立同码原因：① 发起人角色没挂该流程的发起权限（ouScope ∩ 发起人部门链，全空会静默回退发起人）；② 流程未启用/未发布；③ 模型未绑定流程。先 omc call workflow.get_published 核对 ②，再查角色 ouScope——不要反复换参数重试 data.submit",
+    "workflow-start-permission-denied": "40009 有三个独立同码原因：① 发起人角色没挂该流程的发起权限（ouScope ∩ 发起人部门链，全空会静默回退发起人）；② 流程未启用/未发布；③ 模型未绑定流程。先 omc call workflow.permissions / workflow.get_published 核对；管理员发起成功带 bypassReason 时不证明白名单生效——换非管理员环境验证。不要反复换参数重试 data.submit",
+    "workflow-bound-to-listview": "303024 列表绑定了流程：直接粘贴回执 nextCommand（listview.configure：actions:[] + replaceActions:true + 现成 fieldCodes）解绑，再 workflow.delete；整体清理用 model-purge",
+    "workflow-start-permission-empty": "发起权限表为空：除平台管理员外无人能发起。用 workflow.addPermission 授给部门/角色/用户；管理员 data.submit 成功不证明白名单生效",
     "environment-write-disabled": "当前环境 profile 不可写：换可写环境，或让维护者在配置里开 writable——CLI 侧没有绕过开关",
     "production-confirmation-required": "生产环境的写需要显式 confirmProduction:true——确认这次写入真的要落生产再加该参数，不要靠重试",
     "app-not-published": "目标应用未发布：先 workflow/form/field 各面发布（或 app 级发布），再重试运行面操作",
@@ -191,7 +199,11 @@ export function refusalRecovery(blocker, payload, options = {}) {
     // message/detail, so both refused and frozen (uncertain) envelopes teach it.
     if (mentionsDashboardChannel(payload))
         return dashboardBoundaryGuidance();
-    const shape = SHAPE_GATES[blocker];
+    // r29b F7: blockerAliases 让旧名也能命中新引导。
+    const aliasBlockers = Array.isArray(payload.blockerAliases)
+        ? payload.blockerAliases.filter((entry) => typeof entry === "string")
+        : [];
+    const shape = SHAPE_GATES[blocker] ?? aliasBlockers.map((alias) => SHAPE_GATES[alias]).find((entry) => entry !== undefined);
     if (shape) {
         const command = resolveCommand(shape, options.registry);
         const { recipeCommand: _drop, ...rest } = shape;

package/dist/rollback-spec.js

@@ -1,7 +1,21 @@
+/** Business-key extractors for array alignment in deepDiff (r30a F14/F15). */
+const ARRAY_ALIGN_KEYS = ["code", "id", "propertyCode", "activityCode", "ruleCode", "nodeCode"];
+function arrayEntryKey(entry) {
+    if (entry === null || typeof entry !== "object")
+        return undefined;
+    const record = entry;
+    for (const key of ARRAY_ALIGN_KEYS) {
+        const value = record[key];
+        if (value !== undefined && value !== null && String(value) !== "")
+            return `${key}:${String(value)}`;
+    }
+    return undefined;
+}
 /**
  * Field-level deep diff for the plan surface. Returns at most `limit`
- * changed paths plus the total count; arrays are compared by index
- * (length change is reported on the array path itself).
+ * changed paths plus the total count. Arrays of objects with a business key
+ * (`code`/`id`/…) are aligned by that key; index-only comparison is the
+ * fallback for scalars / unkeyed rows (r30a F14).
  */
 export function deepDiff(before, current, path = "", limit = 40, acc = []) {
     const walk = (b, c, p) => {
@@ -33,6 +47,31 @@ export function deepDiff(before, current, path = "", limit = 40, acc = []) {
             const cA = c;
             if (bA.length !== cA.length)
                 acc.push({ path: p, before: `<array×${bA.length}>`, current: `<array×${cA.length}>` });
+            const bKeys = bA.map(arrayEntryKey);
+            const cKeys = cA.map(arrayEntryKey);
+            const canAlign = bKeys.every((key) => key !== undefined) && cKeys.every((key) => key !== undefined)
+                && new Set(bKeys).size === bKeys.length && new Set(cKeys).size === cKeys.length;
+            if (canAlign) {
+                const bMap = new Map(bKeys.map((key, index) => [key, bA[index]]));
+                const cMap = new Map(cKeys.map((key, index) => [key, cA[index]]));
+                for (const key of new Set([...bMap.keys(), ...cMap.keys()])) {
+                    if (acc.length >= limit)
+                        return;
+                    const inB = bMap.has(key);
+                    const inC = cMap.has(key);
+                    const short = key.includes(":") ? key.slice(key.indexOf(":") + 1) : key;
+                    if (!inB) {
+                        acc.push({ path: `${p}[+${short}]`, before: "<absent>", current: cMap.get(key) });
+                        continue;
+                    }
+                    if (!inC) {
+                        acc.push({ path: `${p}[-${short}]`, before: bMap.get(key), current: "<absent>" });
+                        continue;
+                    }
+                    walk(bMap.get(key), cMap.get(key), `${p}[${short}]`);
+                }
+                return;
+            }
             const shared = Math.min(bA.length, cA.length);
             for (let i = 0; i < shared && acc.length < limit; i += 1)
                 walk(bA[i], cA[i], `${p}[${i}]`);

package/dist/rollback.js

@@ -43,8 +43,19 @@ export async function listRollback(options, context) {
         entries = entries.filter((entry) => entry.target.includes(options.target));
     if (options.tool)
         entries = entries.filter((entry) => entry.tool === options.tool || entry.tool.startsWith(`${options.tool}.`));
+    // r30a F22: hide documented no-ops from the default timeline.
+    const actionable = entries.filter((entry) => entry.noop !== true);
     const limit = options.limit ? Number(options.limit) : 40;
-    const timeline = [...entries].reverse().slice(0, Number.isSafeInteger(limit) && limit > 0 ? limit : 40);
+    const timeline = [...actionable].reverse().slice(0, Number.isSafeInteger(limit) && limit > 0 ? limit : 40);
+    // r30a F9/F11/F20: surface which writes in this window cannot be undone.
+    const unrollbackable = timeline
+        .filter((entry) => entry.rollbackable === false)
+        .map((entry) => ({
+        seq: entry.seq,
+        tool: entry.tool,
+        target: entry.target,
+        reason: entry.note ?? "rollbackable:false",
+    }));
     return {
         status: "ok",
         environment,
@@ -57,9 +68,11 @@ export async function listRollback(options, context) {
             target: entry.target,
             rollbackable: entry.rollbackable,
             ...(entry.note ? { note: entry.note } : {}),
+            ...(entry.steps !== undefined ? { steps: entry.steps } : {}),
             artifact: basename(entry.artifactFile),
         })),
-        hint: "omc rollback plan <seq> 预览恢复（不写）；omc rollback apply <seq> 执行恢复",
+        ...(unrollbackable.length > 0 ? { unrollbackable } : {}),
+        hint: "omc rollback plan <seq> 预览恢复（不写）；omc rollback apply <seq> 执行恢复；unrollbackable[] 是本窗口内撤不了的写",
     };
 }
 async function buildPlan(ref, environmentOption, context) {
@@ -68,13 +81,20 @@ async function buildPlan(ref, environmentOption, context) {
     const entry = resolveJournalEntry(environment, ref, ctx.artifactsDir);
     if (!entry)
         throw new Error(`journal（${environment}）中找不到 ${ref}：先 omc rollback list 核对 seq`);
+    // r30a F9/F12: compound writes are journaled with rollbackable:false and may
+    // have NO RollbackSpec on the tool (configure_model). Do not call findSpec
+    // for the unrollbackable short-circuit — that used to throw and become exit 15.
     const unrollbackable = (reason) => ({
         entry,
-        spec: findSpec(entry.tool).spec,
+        spec: {
+            target: () => entry.target,
+            read: async () => null,
+            inverse: () => ({ kind: "irreversible", reason }),
+        },
         before: undefined,
         artifactArgs: {},
         context: ctx,
-        plan: { environmentMatch: true, diff: { changes: [], total: 0 }, laterWrites: [], inverse: { kind: "irreversible", reason } },
+        plan: { environmentMatch: true, diff: { changes: [], total: 0 }, laterWrites: laterWritesOnTarget(environment, ctx.artifactsDir, entry.seq, entry.target), inverse: { kind: "irreversible", reason } },
     });
     if (!entry.rollbackable)
         return unrollbackable(entry.note ?? "该写的 before 快照捕获失败，无法回滚");
@@ -122,13 +142,17 @@ export async function planRollback(ref, options, context) {
     };
     const script = plan.inverse.kind === "calls" ? plan.inverse.calls.map((call) => JSON.stringify({ tool: call.tool, args: { ...call.args, environment: entry.environment } })) : [];
     const scriptOmitted = script.join("").length > 6000;
+    const irreversible = plan.inverse.kind === "irreversible";
     return {
         status: "ok",
         rollbackOf: { seq: entry.seq, tool: entry.tool, target: entry.target, ts: entry.ts },
         diff: { changedPaths: plan.diff.changes.map((change) => ({ path: change.path, before: preview(change.before), current: preview(change.current) })), total: plan.diff.total },
-        ...(plan.laterWrites.length > 0
+        // r30a F12: do not claim "will overwrite later writes" when inverse is irreversible.
+        ...(plan.laterWrites.length > 0 && !irreversible
             ? { warning: `该目标在此写之后还有 ${plan.laterWrites.length} 次写（seq ${plan.laterWrites.map((w) => w.seq).join(", ")}）；本次回滚会用 before 参数覆盖这些后续变更`, laterWrites: plan.laterWrites.map((w) => ({ seq: w.seq, tool: w.tool, ts: w.ts })) }
-            : {}),
+            : plan.laterWrites.length > 0
+                ? { laterWrites: plan.laterWrites.map((w) => ({ seq: w.seq, tool: w.tool, ts: w.ts })), laterWritesNote: "本写 irreversible，不会覆盖后续写；若要恢复后续变更请对那些 seq 分别 plan/apply" }
+                : {}),
         inverse: plan.inverse.kind === "calls"
             ? {
                 kind: "calls",
@@ -139,19 +163,33 @@ export async function planRollback(ref, options, context) {
                     : { script }),
             }
             : { kind: "irreversible", reason: plan.inverse.reason, ...(plan.inverse.partial ? { partial: plan.inverse.partial } : {}) },
-        hint: "预览不写入；确认后 omc rollback apply <seq>（恢复走完整写闸门，回滚本身也会记 journal，可再回滚）",
+        hint: irreversible
+            ? `本写不可逆（apply 会 skipped/exit 0）；${plan.laterWrites.length > 0 ? `下一步可试 omc rollback plan ${plan.laterWrites[0].seq} --env ${entry.environment}` : "无后续可恢复写"}`
+            : "预览不写入；确认后 omc rollback apply <seq>（恢复走完整写闸门，回滚本身也会记 journal，可再回滚）",
     };
 }
 export async function applyRollback(ref, options, context) {
     const loaded = await buildPlan(ref, options.environment, context);
     const { entry, plan, spec, artifactArgs, before, context: ctx } = loaded;
-    if (plan.inverse.kind !== "calls" || plan.inverse.calls.length === 0)
+    if (plan.inverse.kind !== "calls" || plan.inverse.calls.length === 0) {
+        // r30a F12: irreversible is an expected answer → status:"skipped" + exit 0
+        // (was unclassified-status / exit 15). Keep reason + next step pasteable.
+        const inverse = plan.inverse;
+        const irreversible = inverse.kind === "irreversible";
+        const reason = irreversible ? inverse.reason : "无可执行恢复调用";
+        const later = plan.laterWrites;
         return {
-            status: plan.inverse.kind === "irreversible" ? "irreversible" : "ok",
+            status: irreversible ? "skipped" : "ok",
+            applied: false,
+            reason,
             rollbackOf: { seq: entry.seq, tool: entry.tool, target: entry.target },
-            inverse: plan.inverse,
-            message: plan.inverse.kind === "irreversible" ? plan.inverse.reason : "无可执行恢复调用",
+            inverse,
+            message: reason,
+            ...(later.length > 0
+                ? { nextCommand: `omc rollback plan ${later[0].seq} --env ${entry.environment}`, hint: `本写不可逆；可对后续写 seq ${later.map((w) => w.seq).join(", ")} 再 plan/apply` }
+                : {}),
         };
+    }
     const results = [];
     for (const [index, call] of plan.inverse.calls.entries()) {
         const { exitCode, result } = await runToolCall(call.tool, {

package/dist/script.js

@@ -5,44 +5,80 @@ import { SessionManager } from "./session-manager.js";
 import { makeToolContext } from "./tools.js";
 import { runToolCall } from "./call.js";
 import { currentUsageId, recordScriptCall } from "./usage-log.js";
+function isCommentOrBlank(line) {
+    return line.length === 0 || line.startsWith("#") || line.startsWith("//");
+}
+/**
+ * Parse NDJSON. Blank / `#` / `//` comment lines are ignored. Other illegal
+ * lines are collected as `skipped` (r31b F16/F17) so a trailing `// total 32`
+ * no longer aborts the whole batch before any call runs.
+ */
 export function parseScript(text) {
     const lines = [];
+    const skipped = [];
     const raw = text.split("\n");
     for (const [index, untrimmed] of raw.entries()) {
         const line = untrimmed.trim();
-        if (line.length === 0 || line.startsWith("#"))
+        if (isCommentOrBlank(line))
             continue;
         let parsed;
         try {
             parsed = JSON.parse(line);
         }
         catch (error) {
-            throw new Error(`第 ${index + 1} 行不是合法 JSON：${error instanceof Error ? error.message : String(error)}`);
+            skipped.push({
+                sourceLine: index + 1,
+                reason: `不是合法 JSON：${error instanceof Error ? error.message : String(error)}`,
+                text: line.slice(0, 120),
+            });
+            continue;
         }
         if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed) || typeof parsed.tool !== "string") {
-            throw new Error(`第 ${index + 1} 行必须是 {"tool":"<名称>","args":{...},"env":"<环境>","dryRun":true} 形状（tool 必填）`);
+            skipped.push({
+                sourceLine: index + 1,
+                reason: `必须是 {"tool":"<名称>","args":{...}} 形状（tool 必填）`,
+                text: line.slice(0, 120),
+            });
+            continue;
         }
         const entry = parsed;
-        if (entry.args !== undefined && (entry.args === null || typeof entry.args !== "object" || Array.isArray(entry.args)))
-            throw new Error(`第 ${index + 1} 行 args 必须是 JSON 对象`);
+        if (entry.args !== undefined && (entry.args === null || typeof entry.args !== "object" || Array.isArray(entry.args))) {
+            skipped.push({
+                sourceLine: index + 1,
+                reason: "args 必须是 JSON 对象",
+                text: line.slice(0, 120),
+            });
+            continue;
+        }
         lines.push({
             tool: entry.tool,
             ...(typeof entry.args === "object" && entry.args !== null ? { args: entry.args } : {}),
             ...(typeof entry.env === "string" ? { env: entry.env } : {}),
             ...(entry.dryRun === true ? { dryRun: true } : {}),
+            sourceLine: index + 1,
         });
     }
-    return lines;
+    return { lines, skipped };
 }
 export async function runScript(lines, options = {}) {
     const print = options.print ?? ((line) => console.log(line));
     const context = options.context ?? makeToolContext({ sessions: new SessionManager(new ConfigStore(defaultPaths())) });
-    // The outer `script` invocation is already recorded by completeUsage; these
-    // inner records are what make a batch measurable at all. Before this, all 23
-    // `script -` calls in round 10 logged stdoutBytes=0 and the actual work was
-    // invisible (the outer record says "script -", the log says nothing else).
     const parentId = currentUsageId();
+    const skipped = options.skipped ?? [];
+    for (const skip of skipped) {
+        print(JSON.stringify({
+            kind: "script-skipped",
+            sourceLine: skip.sourceLine,
+            reason: skip.reason,
+            text: skip.text,
+            note: "非法行已跳过（# 与 // 开头的注释/空行会被忽略；其它非法行计入 summary.skipped）",
+        }));
+    }
     let failed = false;
+    let ok = 0;
+    let failedCount = 0;
+    const failedIndexes = [];
+    let stoppedAt;
     for (const [index, line] of lines.entries()) {
         const startedMs = Date.now();
         const { exitCode, result } = await runToolCall(line.tool, {
@@ -67,12 +103,36 @@ export async function runScript(lines, options = {}) {
         print(rendered);
         if (exitCode !== 0) {
             failed = true;
+            failedCount += 1;
+            failedIndexes.push(index);
             if (options.continueOnError !== true) {
-                print(JSON.stringify({ index, tool: line.tool, stopped: true, note: `第 ${index + 1} 行失败，后续 ${lines.length - index - 1} 行未执行；加 --continue 跑完全部` }));
-                return exitCode;
+                stoppedAt = index;
+                print(JSON.stringify({
+                    kind: "script-stopped",
+                    stoppedAtIndex: index,
+                    tool: line.tool,
+                    remaining: lines.length - index - 1,
+                    note: `第 ${index + 1} 行失败，后续 ${lines.length - index - 1} 行未执行；加 --continue 跑完全部（默认首败即停）`,
+                }));
+                break;
             }
         }
+        else {
+            ok += 1;
+        }
     }
+    print(JSON.stringify({
+        summary: {
+            total: lines.length,
+            ok,
+            failed: failedCount,
+            skipped: skipped.length,
+            ...(failedIndexes.length > 0 ? { failedIndexes } : {}),
+            ...(stoppedAt !== undefined ? { stoppedAt } : {}),
+        },
+    }));
+    if (lines.length === 0 && skipped.length > 0)
+        return 10; // invalid-input: nothing runnable
     return failed ? 1 : 0;
 }
 export function readScriptInput(path) {

package/dist/skills.js

@@ -34,9 +34,78 @@ function skillFiles() {
         return [];
     }
 }
+/** r29a F4：合成 topic——跨 app/folder/model/rule 的应用参数矩阵（不落盘 md，省预算）。 */
+/** r31b F4：合成 topic——并发语义（真机实测结论，不落盘 md）。 */
+const SYNTHETIC_SKILLS = Object.freeze({
+    "app-scope": {
+        name: "app-scope",
+        description: "跨 app/folder/model/rule 的应用范围参数名矩阵（主名/别名）",
+        content: [
+            "# 应用范围参数（app-scope）",
+            "",
+            "同一能力族里应用参数名不完全统一。一次看完，别逐个 `describe --full`。",
+            "",
+            "## 矩阵",
+            "",
+            "| 工具面 | 主参数 | 别名 | 备注 |",
+            "| --- | --- | --- | --- |",
+            "| `app.*` | （多数无；create/delete 用 `code`） | — | 管应用包本身 |",
+            "| `folder.*` | `applicationCode` | `appCode` | 双别名；冲突报 `app-code-conflict` |",
+            "| `model.*` | `applicationCode` | **不认** `appCode` | 传 `appCode` → `unknown-app-scope-arg` |",
+            "| `rule.*` | **无** | — | 按 `schemaCode` 定位；传应用键 → `tool-has-no-app-scope` |",
+            "| `report.*` | `appCode` | — | 报表面主用短名 |",
+            "",
+            "## 怎么查",
+            "",
+            "- 单能力：`omc capability model` / `folder`（回执带 `appScopeArgs`）",
+            "- 单工具：`omc describe <tool> --param applicationCode`",
+            "- 本 topic：`omc help app-scope`",
+            "",
+            "## 易踩坑",
+            "",
+            "1. `folder.tree` 能用 `appCode`，不能据此推断 `model.list` 也认。",
+            "2. `rule.list` 传 `applicationCode` 会被拒——规则面没有应用维度。",
+            "3. 不存在的 `applicationCode` 在 `model.list` 会 `app-not-found`（不是空列表）。",
+            "",
+        ].join("\n"),
+    },
+    concurrency: {
+        name: "concurrency",
+        description: "环境写锁 / 记录级 last-writer-wins / version 非乐观锁（r31 真机）",
+        content: [
+            "# 并发语义（r31 真机）",
+            "",
+            "写锁是**环境级**；记录级**无乐观锁**。CLI 不提供 `ifVersion`。以下全部双进程实测。",
+            "",
+            "| 操作 | 保护 | 结果 |",
+            "| --- | --- | --- |",
+            "| 并行写 | 环境写锁 | 输家 `write-lock-held`（`retryable`/`lockOwner`/`nextCommand`） |",
+            "| 同记录 `data.update` 不同字段 +`--wait` | 写锁串行+patch | 两字段都保住；**同字段**后写覆盖 |",
+            "| 读-改-写（旧值算新值） | **无** | 后写覆盖 |",
+            "| 行 `version` | 只读计数器 | update 成功 +1；`formData.version` 静默忽略（**不是乐观锁**） |",
+            "| 并行同 code 字段/模型 | 写锁+存在性闸 | 一成功；一 `duplicate-field`/`model-create-duplicate` |",
+            "| `data.list` 翻页 vs 写 | 读无快照 | 无 `snapshotAt`；可重复/漏行，`total` 可漂移 |",
+            "| 同 id `data.delete` | 写锁串行 | 第二次 `performed.skipped:\"already-absent\"` |",
+            "",
+            "`data.list` 唯一一致性键是 `filter.draftPolicy`（草稿是否计入）。",
+            "",
+            "读面数组键：`field.list`→`fields`；`model.list`→`models`；`data.list`→`items`（别用错 `--jq`）。",
+            "",
+            "```bash",
+            "(omc call data.save --env local --args '{\"schemaCode\":\"<m>\",\"formData\":{\"code\":\"a\",\"value\":1}}') &",
+            "(omc call data.save --env local --args '{\"schemaCode\":\"<m>\",\"formData\":{\"code\":\"b\",\"value\":2}}') & wait",
+            "```",
+            "",
+            "- 写串行或 `--wait`；**不要** shell 重试循环。",
+            "- 批量用 `omc script`（同进程更快）；**测写锁必须多进程 `omc call`**。",
+            "- 详见 `omc help omc-write-hazards --section \"写调用纪律\"`。",
+            "",
+        ].join("\n"),
+    },
+});
 /** Every methodology topic exposed by `omc help`. */
 export function listSkills() {
-    return skillFiles().map((file) => {
+    const files = skillFiles().map((file) => {
         const name = file.replace(/\.md$/, "");
         let description = `OMC methodology: ${name}`;
         try {
@@ -47,6 +116,8 @@ export function listSkills() {
         }
         return { name, description };
     });
+    const synthetic = Object.values(SYNTHETIC_SKILLS).map(({ name, description }) => ({ name, description }));
+    return [...files, ...synthetic].sort((left, right) => left.name.localeCompare(right.name));
 }
 /**
  * r43 后 backlog：`omc help 编号` 曾零命中（高频中文业务词不是 topic 名）。
@@ -76,6 +147,11 @@ const HELP_TOPIC_SYNONYMS = Object.freeze({
     验收: ["omc-acceptance-criteria"],
     入门: ["omc-start-here"],
     拒绝: ["omc-refusals"],
+    并发: ["concurrency", "omc-write-hazards"],
+    竞争: ["concurrency"],
+    乐观锁: ["concurrency"],
+    写锁: ["concurrency", "omc-write-hazards"],
+    快照: ["concurrency"],
 });
 export function suggestHelpTopics(query) {
     if (query === undefined || query.length === 0)
@@ -99,15 +175,25 @@ export function suggestHelpTopics(query) {
     }
     return [...hits].slice(0, 5);
 }
+/** Appended to every `--all` body so the probe learns the cheap face (r31c F2). */
+const HELP_ALL_SECTION_HINT = '\n\n> hint:"下次可按节读：omc help <topic> --section <标题>"\n';
 /** Read one methodology topic for `omc help <topic>`. */
 export function readSkill(name) {
     if (!/^[a-z0-9-]+$/.test(name))
         return undefined;
+    if (SYNTHETIC_SKILLS[name] !== undefined) {
+        const synthetic = SYNTHETIC_SKILLS[name];
+        return { ...synthetic, content: `${synthetic.content.trimEnd()}${HELP_ALL_SECTION_HINT}` };
+    }
     const entry = listSkills().find((skill) => skill.name === name);
     if (entry === undefined)
         return undefined;
     try {
-        return { ...entry, content: normalizeLineEndings(readFileSync(join(skillsDir, `${name}.md`), "utf8")) };
+        const content = normalizeLineEndings(readFileSync(join(skillsDir, `${name}.md`), "utf8"));
+        // r31c F2: `--all` used to dump 5–14KB with no "use --section next time"
+        // hint (that tip lived only on the index face / cli.ts). Append one line so
+        // the expensive face teaches the cheap face. Index blurbs stay ≤40 chars.
+        return { ...entry, content: `${content.trimEnd()}${HELP_ALL_SECTION_HINT}` };
     }
     catch {
         return undefined;
@@ -210,7 +296,9 @@ export function readSkillSection(name, requested) {
  */
 /** First meaningful body line of a section: skip headings/blank/fence/list markers. */
 function sectionBlurb(body) {
-    const limit = 70;
+    // r31c F2: index blurbs must stay ≤40 chars so a bare `omc help <topic>`
+    // is enough to pick the right section (probe had to open --all / second round).
+    const limit = 40;
     // sliceSectionText includes the section's own heading line — skip it.
     for (const raw of body.split(/\r?\n/).slice(1)) {
         const line = raw.trim();