@stalfh233/omc-cli 0.4.74 → 0.4.76

package/dist/lanes/workflow.js

@@ -9,7 +9,8 @@ import { writeSummary } from "../human-summary.js";
 import { defineTool, ToolInputError } from "../tool-types.js";
 import { wireCall, wireRows, WireError } from "../wire.js";
 import { diagnoseInstanceActivity, getInstanceBaseInfo, listInstanceActivities, resolveBizObjectIdByInstance, searchWorkItems, wireString } from "../workflow-support.js";
-import { WORKFLOW_EVENT_HANDLER_FIELDS, WORKFLOW_LANE_CONTRACT, workflowTemplateArg } from "./workflow-contract.js";
+import { readSchemaFormButtons } from "../form-support.js";
+import { WORKFLOW_EVENT_HANDLER_FIELDS, WORKFLOW_NODE_EVENT_HANDLER_FIELDS, WORKFLOW_LANE_CONTRACT, workflowTemplateArg } from "./workflow-contract.js";
 import { PLATFORM_TRIGGER_RULE_CODES } from "./rule-graph.js";
 import { executeRuleEnableWrite } from "./rule-lifecycle.js";
 const WORKFLOW_LANE = WORKFLOW_LANE_CONTRACT.lane;
@@ -157,7 +158,7 @@ function validateWorkflowRouteConditions(template, tool) {
             continue;
         const groups = route.ruleConditionGroup;
         if (!Array.isArray(groups) || groups.length === 0)
-            throw new ToolRefusalError({ status: "refused", blocker: "workflow-route-condition-invalid", message: `${tool}: routes[${index}].ruleConditionGroup must be a non-empty array of AND-groups (each an array of conditions)` });
+            throw new ToolRefusalError({ status: "refused", blocker: "workflow-route-condition-invalid", message: `${tool}: routes[${index}].ruleConditionGroup must be a non-empty array of AND-groups (each an array of conditions)（平台存量里的空数组写法在 rollback 重放时会自动剥离，调用方不要手写 []）` });
         for (const [groupIndex, group] of groups.entries()) {
             if (!Array.isArray(group) || group.length === 0)
                 throw new ToolRefusalError({ status: "refused", blocker: "workflow-route-condition-invalid", message: `${tool}: routes[${index}].ruleConditionGroup[${groupIndex}] must be a non-empty array of RuleConditionItem` });
@@ -193,11 +194,85 @@ function resolveEventHandlerField(handler) {
             status: "refused",
             blocker: "workflow-invalid-handler",
             handler,
-            message: `handler must be one of ${Object.keys(WORKFLOW_EVENT_HANDLER_FIELDS).join("|")} (omit for end)`,
+            message: `handler must be one of ${Object.keys(WORKFLOW_EVENT_HANDLER_FIELDS).join("|")} (omit for end). 节点级事件不用 handler：改传 activityCode + nodeEvent（${Object.keys(WORKFLOW_NODE_EVENT_HANDLER_FIELDS).join("|")}）`,
         });
     }
     return { key: key, field };
 }
+function resolveBindTarget(handler, nodeEvent, activityCode) {
+    const hasNode = nodeEvent !== undefined && nodeEvent !== null;
+    const hasActivity = activityCode !== undefined && activityCode !== null && String(activityCode).trim() !== "";
+    if (hasNode !== hasActivity) {
+        throw new ToolRefusalError({
+            status: "refused",
+            blocker: "workflow-invalid-handler",
+            message: hasNode
+                ? `nodeEvent=${String(nodeEvent)} 必须同时给 activityCode（节点级事件写在具体活动上）`
+                : `activityCode=${String(activityCode)} 必须同时给 nodeEvent（${Object.keys(WORKFLOW_NODE_EVENT_HANDLER_FIELDS).join("|")}）；只给 activityCode 不知道要绑该节点的哪个事件`,
+        });
+    }
+    if (hasNode && hasActivity) {
+        if (handler !== undefined && handler !== null)
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "workflow-invalid-handler",
+                message: "handler（流程级）与 activityCode+nodeEvent（节点级）互斥：请只用一种形式",
+            });
+        const key = String(nodeEvent);
+        const field = WORKFLOW_NODE_EVENT_HANDLER_FIELDS[key];
+        if (!field)
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "workflow-invalid-handler",
+                nodeEvent,
+                message: `nodeEvent must be one of ${Object.keys(WORKFLOW_NODE_EVENT_HANDLER_FIELDS).join("|")}`,
+            });
+        return { scope: "activity", key, activityCode: String(activityCode), field };
+    }
+    const resolved = resolveEventHandlerField(handler);
+    return { scope: "workflow", ...resolved };
+}
+/**
+ * Activity rows on a workflow template arrive EITHER as an array OR as an
+ * index-keyed object (the shape `workflow.get_draft` returns on 1.1.25). Node-
+ * level handler edits must preserve whichever shape the draft uses — rebinding a
+ * rule must not restructure the caller's stored template.
+ */
+function findTemplateActivity(template, activityCode) {
+    const raw = template?.activities;
+    if (Array.isArray(raw))
+        return raw.find((row) => String(row?.activityCode ?? "") === activityCode);
+    if (raw && typeof raw === "object")
+        return Object.values(raw).find((row) => String(row?.activityCode ?? "") === activityCode);
+    return undefined;
+}
+function mapTemplateActivity(template, activityCode, update) {
+    const raw = template.activities;
+    if (Array.isArray(raw)) {
+        let found = false;
+        const activities = raw.map((entry) => {
+            const row = (entry ?? {});
+            if (String(row.activityCode ?? "") !== activityCode)
+                return entry;
+            found = true;
+            return update(row);
+        });
+        return { found, template: found ? { ...template, activities } : template };
+    }
+    if (raw && typeof raw === "object") {
+        const rows = raw;
+        const key = Object.keys(rows).find((name) => String((rows[name] ?? {}).activityCode ?? "") === activityCode);
+        if (key === undefined)
+            return { found: false, template };
+        return { found: true, template: { ...template, activities: { ...rows, [key]: update((rows[key] ?? {})) } } };
+    }
+    return { found: false, template };
+}
+function templateActivityCodes(template) {
+    const raw = template?.activities;
+    const rows = Array.isArray(raw) ? raw : raw && typeof raw === "object" ? Object.values(raw) : [];
+    return rows.map((row) => String(row?.activityCode ?? "")).filter((code) => code !== "");
+}
 /**
  * Live 8.6.26 fidelity — a REFUSED workflow write still answers HTTP 200 with
  * `errcode 0`; the refusal rides `data` as a `ValidateMessage[]`
@@ -494,7 +569,13 @@ function mapCallerRules(callerRoutes, draftRules, activities) {
         const record = (entry ?? {});
         const pre = String(record.preActivityCode ?? record.preNode ?? record.pre ?? record.from ?? "");
         const post = String(record.postActivityCode ?? record.postNode ?? record.post ?? record.to ?? "");
-        const points = Array.isArray(record.points) && record.points.length > 0 ? record.points : deriveRulePoints(pre, post, activities);
+        // Derive points only when the caller gave none (absent or empty). A
+        // MALFORMED value must ride through untouched so validateWorkflowRender
+        // refuses it — silently repairing it would hide a shape error.
+        const pointsRaw = record.points;
+        const points = pointsRaw === undefined || pointsRaw === null || (Array.isArray(pointsRaw) && pointsRaw.length === 0)
+            ? deriveRulePoints(pre, post, activities)
+            : pointsRaw;
         const mapped = {
             ...baseRule,
             ...Object.fromEntries(Object.entries(record).filter(([key]) => !["preNode", "postNode", "pre", "post", "from", "to"].includes(key))),
@@ -509,13 +590,19 @@ function mapCallerRules(callerRoutes, draftRules, activities) {
         // silently turn a supplied ruleConditionGroup into a no-op, and both ride in
         // via the draft baseRule. So force them unless the caller set them itself.
         if (record.ruleConditionGroup !== undefined) {
-            if (record.popupType === undefined)
-                mapped.popupType = "EXPRESSION";
-            if (record.utilizeElse === undefined)
-                mapped.utilizeElse = false;
-            // The platform deserializes BizPropertyType from an INT index; normalize a
-            // caller's enum name before the wire (see WORKFLOW_BIZ_PROPERTY_TYPE_INDEX).
-            mapped.ruleConditionGroup = normalizeRuleConditionGroup(record.ruleConditionGroup);
+            // The stored spelling for "no condition" is an empty outer array; drop it
+            // instead of forcing EXPRESSION/else on a plain edge.
+            if (Array.isArray(record.ruleConditionGroup) && record.ruleConditionGroup.length === 0)
+                delete mapped.ruleConditionGroup;
+            else {
+                if (record.popupType === undefined)
+                    mapped.popupType = "EXPRESSION";
+                if (record.utilizeElse === undefined)
+                    mapped.utilizeElse = false;
+                // The platform deserializes BizPropertyType from an INT index; normalize a
+                // caller's enum name before the wire (see WORKFLOW_BIZ_PROPERTY_TYPE_INDEX).
+                mapped.ruleConditionGroup = normalizeRuleConditionGroup(record.ruleConditionGroup);
+            }
         }
         return mapped;
     });
@@ -810,6 +897,18 @@ function validateWorkflowRender(template, tool) {
             throw new ToolRefusalError({ status: "refused", blocker: "workflow-render-rules-invalid", message: `${tool}: rules[${index}].points must be a non-empty string[] of "x, y" coordinates` });
     }
 }
+/** The three accepted spellings of the same edge list; refuse two non-empty ones. */
+function pickRouteSpelling(spellings, tool) {
+    const present = Object.entries(spellings).filter(([, value]) => Array.isArray(value) && value.length > 0);
+    if (present.length > 1)
+        throw new ToolRefusalError({
+            status: "refused",
+            blocker: "workflow-routes-ambiguous",
+            spellings: present.map(([name]) => name),
+            message: `${tool}: routes/edges 与 rules 是同一条连线的三种写法（平台 DTO 字段名是 rules；recipe 写法是 routes/edges），本次同时给了 ${present.map(([name]) => name).join(" 和 ")}——只能给一种`,
+        });
+    return present.length === 1 ? present[0][1] : undefined;
+}
 /**
  * The draft rules remapped by index cannot describe an activity the caller
  * ADDED (an extra approval node): the remapped edges stop at the old chain, an
@@ -856,7 +955,13 @@ export function completeWorkflowChain(rules, activities) {
     // activities without routes erased A3→A5, every low-amount instance stalled
     // in PROCESSING with errcode 0, and the only trace was a missing edge in
     // get_published. Never linearize a graph that already branches.
-    const branched = [...outbound.values()].some((count) => count > 1);
+    //
+    // issue 2026-10-22 §1.2: a graph can also fan IN (several approval paths
+    // converging on one node). Such a graph has no node with out-degree > 1, so
+    // the out-degree-only test missed it and the linear rebuild below compressed
+    // 46 edges into 31 (r10/customer 8.6). A merge/shape check must treat BOTH
+    // directions as "not a chain": anything with a fork or a join is a graph.
+    const branched = [...outbound.values()].some((count) => count > 1) || [...inbound.values()].some((count) => count > 1);
     if (branched)
         return rules;
     const byEdge = new Map(rules.map((rule) => [`${rule.preActivityCode}->${rule.postActivityCode}`, rule]));
@@ -1238,8 +1343,16 @@ async function refuseRequiredOnChildTableFields(session, schemaCode, template, t
  * subset silently REPLACED the whole activity list and dropped nodes.
  */
 function mergeCallerDelta(template, draft, options = {}) {
-    const { routes: routesRaw, activities: _raw, edges: edgesRaw, ...rest } = template;
-    const routes = routesRaw ?? edgesRaw;
+    const { routes: routesRaw, rules: rulesRaw, activities: _raw, edges: edgesRaw, ...rest } = template;
+    // `routes` and `edges` are the recipe spellings; `rules` is the platform DTO
+    // field name that `get_draft` returns and that a round-tripping caller sends
+    // verbatim. Before this alias, `rules` rode `rest` and was then OVERWRITTEN by
+    // `{...rest, activities, rules}` at the end — a caller that sent `rules` had
+    // its edges silently ignored (issue 2026-10-22 §1.3②). Giving two spellings
+    // with both non-empty is ambiguous; refuse instead of guessing. An EMPTY array
+    // is "not given" (spreading a full template then overriding `rules` is the
+    // documented shape).
+    const routes = pickRouteSpelling({ routes: routesRaw, edges: edgesRaw, rules: rulesRaw }, "workflow.update");
     const draftActivities = Array.isArray(draft.activities) ? draft.activities : [];
     const draftRules = Array.isArray(draft.rules) ? draft.rules : [];
     const caller = (callerActivities(template) ?? []).map((raw) => {
@@ -1328,17 +1441,51 @@ function mergeCallerDelta(template, draft, options = {}) {
         for (const key of ["postActivityCode", "postNode", "post", "to"])
             if (rule[key] !== undefined)
                 mapped[key] = remapCode(rule[key]);
+        // Stored drafts on 8.x carry `ruleConditionGroup: []` for a plain edge.
+        // Never echo that empty shape back onto the wire (see the validator note).
+        if (Array.isArray(mapped.ruleConditionGroup) && mapped.ruleConditionGroup.length === 0)
+            delete mapped.ruleConditionGroup;
         return mapped;
     };
     const edgeKey = (rule) => `${rule.preActivityCode ?? rule.preNode ?? rule.pre ?? rule.from}->${rule.postActivityCode ?? rule.postNode ?? rule.post ?? rule.to}`;
     const remappedDraftRules = draftRules.map(remapRuleEndpoints);
-    const mappedCallerRoutes = Array.isArray(routes) ? mapCallerRules(routes.map((entry) => remapRuleEndpoints((entry ?? {}))), remappedDraftRules, mergedActivities) : [];
+    const callerGaveRoutes = Array.isArray(routes);
+    const mappedCallerRoutes = callerGaveRoutes ? mapCallerRules(routes.map((entry) => remapRuleEndpoints((entry ?? {}))), remappedDraftRules, mergedActivities) : [];
     const byEdge = new Map();
     for (const rule of remappedDraftRules)
         byEdge.set(edgeKey(rule), rule);
     for (const rule of mappedCallerRoutes)
         byEdge.set(edgeKey(rule), { ...(byEdge.get(edgeKey(rule)) ?? {}), ...rule });
-    const mergedRules = completeWorkflowChain([...byEdge.values()], mergedActivities);
+    const unionRules = [...byEdge.values()];
+    // A delta that neither sends routes nor adds a node is an edit of EXISTING
+    // rows — the draft's graph is already the platform's own, so it must ride the
+    // wire verbatim. Running the chain rebuild here is what destroyed the 46-edge
+    // graph (issue 2026-10-22 §1.2: a converging graph failed the chain test and
+    // was replaced by a 31-edge linear chain). Chain completion only makes sense
+    // when the caller actually declares new topology.
+    const needsChainCompletion = callerGaveRoutes || newActivities.length > 0;
+    // Verbatim path: no caller topology and no new node. Return the draft edges
+    // themselves — NOT the by-edge map, which keys on `pre->post` and would
+    // collapse two conditional lines drawn between the same pair of nodes.
+    const mergedRules = needsChainCompletion ? completeWorkflowChain(unionRules, mergedActivities) : remappedDraftRules;
+    // Fail closed on topology CONTRACTION. Merge is a union — it can add edges but
+    // never delete one — so fewer edges than the draft means a rebuild went wrong
+    // (the r10/customer 46→31 incident). Refuse BEFORE the wire and name exactly
+    // which draft edges would disappear, so the caller can re-send routes
+    // explicitly instead of losing them silently.
+    if (mergedRules.length < remappedDraftRules.length) {
+        const kept = new Set(mergedRules.map((rule) => edgeKey(rule)));
+        const dropped = remappedDraftRules.map((rule) => edgeKey(rule)).filter((key) => !kept.has(key));
+        throw new ToolRefusalError({
+            status: "refused",
+            blocker: "workflow-merge-would-drop-routes",
+            workflowCode: String(draft.workflowCode ?? ""),
+            routesBefore: remappedDraftRules.length,
+            routesAfter: mergedRules.length,
+            droppedRoutes: dropped.slice(0, 40),
+            message: `workflow.update merge 会把草稿的连线从 ${remappedDraftRules.length} 条压到 ${mergedRules.length} 条（merge 只会并集、不会删边，减少即工具重算失控）。${dropped.length > 0 ? `缺失连线：${dropped.slice(0, 12).join("、")}${dropped.length > 12 ? `…等 ${dropped.length} 条` : ""}。` : "（多落在同一节点对的多条条件线上，被按节点对合并了。）"}已拒绝写入，草稿未变。改法：要么把要保留的连线随 routes 一起显式发（平台 DTO 名 rules），要么用 merge:false 整模板替换`,
+        });
+    }
     // Same layout + points derivation as the replace path: a chain-completion edge
     // synthesized above carries no points, and the designer canvas needs them.
     const laidOut = canonicalizeWorkflowLayout(mergedActivities, mergedRules);
@@ -1354,7 +1501,9 @@ function normalizeWorkflowTemplate(template, draft, options = {}) {
     if (template === undefined || template === null)
         return {};
     const { routes: routesRaw, activities: rawActivities, edges: edgesRaw, ...rest } = template;
-    const routes = routesRaw ?? edgesRaw;
+    const routes = pickRouteSpelling({ routes: routesRaw, edges: edgesRaw, rules: rest.rules }, "workflow.update/publish");
+    if (routes !== undefined)
+        delete rest.rules;
     void rawActivities;
     // Array OR index-keyed object; `rest` must not carry the raw form or an
     // object-shaped activities would ride the wire unmerged.
@@ -1435,6 +1584,27 @@ function normalizeWorkflowTemplate(template, draft, options = {}) {
  * before template as a full-row replace (mergedTemplateBody echoes the draft
  * verbatim when the caller template IS the draft row).
  */
+/**
+ * Restore-shaped snapshots come from the platform (`get_draft`), so they may
+ * carry spellings the WRITE gate refuses as malformed — notably
+ * `ruleConditionGroup: []` (8.x stores an empty outer array for a plain edge).
+ * Drop it before replaying a rollback: it means "no condition", and the strict
+ * input gate (round7) is right to refuse a caller-authored empty group.
+ */
+function sanitizeWorkflowSnapshotForReplay(row) {
+    const rules = row.rules;
+    if (!Array.isArray(rules))
+        return row;
+    return {
+        ...row,
+        rules: rules.map((rule) => {
+            const record = { ...(rule ?? {}) };
+            if (Array.isArray(record.ruleConditionGroup) && record.ruleConditionGroup.length === 0)
+                delete record.ruleConditionGroup;
+            return record;
+        }),
+    };
+}
 function workflowRollbackSpec(toolName) {
     return {
         target: (args) => `workflow:${String(args.schemaCode ?? "")}/${String(args.code ?? args.workflowCode ?? "")}`,
@@ -1460,7 +1630,7 @@ function workflowRollbackSpec(toolName) {
                     kind: "calls",
                     calls: [
                         { tool: "workflow.create", args: { schemaCode, code, name: String(row.workflowName ?? row.name ?? code) } },
-                        { tool: "workflow.update", args: { schemaCode, code, template: row, merge: false } },
+                        { tool: "workflow.update", args: { schemaCode, code, template: sanitizeWorkflowSnapshotForReplay(row), merge: false } },
                     ],
                 };
             }
@@ -1472,7 +1642,7 @@ function workflowRollbackSpec(toolName) {
             // update / bindRule：整模板替换回 before 草稿
             if (before == null)
                 return { kind: "irreversible", reason: "before 快照为空（流程不存在），无内容可恢复" };
-            return { kind: "calls", calls: [{ tool: "workflow.update", args: { schemaCode, code, template: before, merge: false } }] };
+            return { kind: "calls", calls: [{ tool: "workflow.update", args: { schemaCode, code, template: sanitizeWorkflowSnapshotForReplay(before), merge: false } }] };
         },
     };
 }
@@ -1593,6 +1763,18 @@ export function workflowCompactProjection(result) {
         // NON-DEFAULT rows (any of visible/editable/required true) so the summary
         // stays small and names exactly what a readback should confirm.
         ...(activityPermissions(activity) ?? {}),
+        // The designer's 「表单操作」 checkboxes live in buttonPermission.customBtns;
+        // surface the enabled codes so a readback answers "which buttons show on
+        // this node" without the 30–75 KB body.
+        ...(() => {
+            const bp = activity.buttonPermission;
+            const btns = Array.isArray(bp?.customBtns) ? bp.customBtns : [];
+            if (btns.length === 0)
+                return {};
+            const enabled = btns.filter((button) => button.enabled === true).map((button) => String(button.code ?? ""));
+            const disabled = btns.filter((button) => button.enabled !== true).map((button) => String(button.code ?? ""));
+            return { formButtons: { ...(enabled.length ? { enabled } : {}), ...(disabled.length ? { disabled } : {}) } };
+        })(),
     }));
     const rules = data.rules;
     const edges = Array.isArray(rules)
@@ -1613,6 +1795,21 @@ export function workflowCompactProjection(result) {
         if (codes.length > 0 && config?.bizActionType === "BIZ_RULE")
             ruleBindings.push({ handler, field, ruleCodes: codes });
     }
+    // Node-level bindings are invisible in the flow-level list above; surface the
+    // non-empty ones so a `get_draft`/`get_published` readback can confirm a
+    // `workflow.bindRule {activityCode,nodeEvent}` landing without `--full`.
+    const nodeRuleBindings = [];
+    for (const row of Object.values(activities)) {
+        const activityCode = String(row?.activityCode ?? "");
+        if (activityCode === "")
+            continue;
+        for (const nodeEvent of Object.keys(WORKFLOW_NODE_EVENT_HANDLER_FIELDS)) {
+            const config = row[nodeEvent];
+            const codes = Array.isArray(config?.bizActions) ? config.bizActions.filter((value) => typeof value === "string") : [];
+            if (codes.length > 0 && config?.bizActionType === "BIZ_RULE")
+                nodeRuleBindings.push({ activityCode, nodeEvent, ruleCodes: codes });
+        }
+    }
     const originate = data.originateActivity;
     return {
         workflowSummary: {
@@ -1621,6 +1818,7 @@ export function workflowCompactProjection(result) {
             activities: nodes,
             edges,
             ruleBindings,
+            ...(nodeRuleBindings.length > 0 ? { nodeRuleBindings } : {}),
             ruleBindingCount: ruleBindings.reduce((sum, binding) => sum + binding.ruleCodes.length, 0),
             ...(originate ? { originateActivity: { code: originate.activityCode ?? null, type: originate.activityType ?? null, name: effectiveActivityName(originate), participant: originate.participant ?? null } } : {}),
         },
@@ -1868,7 +2066,7 @@ export function registerWorkflowLane(tools) {
             readback: { workflowCode: args.code, headerPresent: true, draftPresent: draft != null, templateId: draft?.id ?? null },
         };
     }, undefined, undefined, workflowRollbackSpec("workflow.create"));
-    writeTool(tools, "workflow.update", WORKFLOW_LANE, WORKFLOW_TOOLS["workflow.update"].scope, WORKFLOW_TOOLS["workflow.update"].description, { schemaCode: z.string().min(1), code: z.string().min(1), template: workflowTemplateArg, merge: z.boolean().optional().describe("增量：只发改动/新增的活动与路由，工具按 activityCode 合并到草稿（草稿为基；新增节点自动接链），不必先读回整模板再重发。默认自动：模板缺 START 或 END 时按增量 merge（部分模板），给了完整 START..END 才整模板替换；显式 true 强制增量、false 强制替换") }, async (session, args) => {
+    writeTool(tools, "workflow.update", WORKFLOW_LANE, WORKFLOW_TOOLS["workflow.update"].scope, WORKFLOW_TOOLS["workflow.update"].description, { schemaCode: z.string().min(1), code: z.string().min(1), template: workflowTemplateArg, merge: z.boolean().optional().describe("增量：只发改动/新增的活动与路由，工具按 activityCode 合并到草稿（草稿为基；新增节点自动接链），不必先读回整模板再重发。默认自动：模板缺 START 或 END 时按增量 merge（部分模板），给了完整 START..END 才整模板替换；显式 true 强制增量、false 强制替换。merge 是并集、绝不删边：结果比草稿少边会被拒（workflow-merge-would-drop-routes）；--dry-run 会返回 routesBefore/routesAfter/routesAdded/routesDropped") }, async (session, args) => {
         const template = args.template ?? {};
         validateCallerActivities(template, "workflow.update");
         validateWorkflowRouteConditions(template, "workflow.update");
@@ -1920,7 +2118,66 @@ export function registerWorkflowLane(tools) {
         // Zero-wire refusal (ticket 77): fires in semanticGate BEFORE the
         // governed pipeline — including the rollback before-capture read.
         assertTemplateNotMinimal(args.template ?? {}, "workflow.update");
-    }, undefined, workflowRollbackSpec("workflow.update"));
+    }, 
+    // Dry-run must actually look at the merge result: shape-only previews said
+    // "wouldChange" while the write silently dropped 15 of 46 edges (issue
+    // 2026-10-22 §1.2). The payload runs the SAME merge as the write (reads
+    // only) and reports the edge delta; the contraction refusal fires here too.
+    async (session, args) => {
+        const template = args.template ?? {};
+        const merge = args.merge === true || (args.merge !== false && activitiesLackBoundaries(template));
+        const draft = await getWorkflowDraftOrNull(session, args.code);
+        if (draft === null)
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "workflow-not-found",
+                workflowCode: args.code,
+                message: `流程 ${args.code} 不存在（get_draft 401001 缺席）——先 workflow.create 再 update/publish`,
+            });
+        const body = await mergedTemplateBody(session, args.schemaCode, args.code, template, merge);
+        validateWorkflowRender(body, "workflow.update");
+        const edgeKeys = (rules) => (Array.isArray(rules) ? rules : []).map((rule) => `${String(rule.preActivityCode ?? "")}->${String(rule.postActivityCode ?? "")}`);
+        const beforeEdges = edgeKeys(draft.rules);
+        const afterEdges = edgeKeys(body.rules);
+        // Multiset difference: two conditional lines can share one node pair, so a
+        // Set would hide a real drop.
+        const remaining = [...afterEdges];
+        const routesDropped = [];
+        for (const edge of beforeEdges) {
+            const index = remaining.indexOf(edge);
+            if (index >= 0)
+                remaining.splice(index, 1);
+            else
+                routesDropped.push(edge);
+        }
+        const beforeLeft = [...beforeEdges];
+        const routesAdded = [];
+        for (const edge of afterEdges) {
+            const index = beforeLeft.indexOf(edge);
+            if (index >= 0)
+                beforeLeft.splice(index, 1);
+            else
+                routesAdded.push(edge);
+        }
+        const activityCodes = (rows) => {
+            const list = Array.isArray(rows) ? rows : rows && typeof rows === "object" ? Object.values(rows) : [];
+            return list.map((row) => String(row?.activityCode ?? "")).filter((code) => code !== "");
+        };
+        const callerSentRoutes = template.routes !== undefined || template.edges !== undefined || template.rules !== undefined;
+        return {
+            merge,
+            callerSentRoutes,
+            activitiesBefore: activityCodes(draft.activities).length,
+            activitiesAfter: activityCodes(body.activities).length,
+            routesBefore: beforeEdges.length,
+            routesAfter: afterEdges.length,
+            routesAdded,
+            routesDropped,
+            hint: callerSentRoutes
+                ? "本次显式给了连线：merge 是并集（草稿边 + 你的边），不会删边"
+                : "本次未给 routes/edges/rules：草稿连线原样沿用（新增节点才会自动接链）",
+        };
+    }, workflowRollbackSpec("workflow.update"));
     writeTool(tools, "workflow.publish", WORKFLOW_LANE, WORKFLOW_TOOLS["workflow.publish"].scope, WORKFLOW_TOOLS["workflow.publish"].description, { schemaCode: z.string().min(1), code: z.string().min(1), template: workflowTemplateArg.optional() }, async (session, args) => {
         // An absent template publishes the stored draft as-is — the platform's own
         // path. The schema is optional so the contract no longer contradicts it.
@@ -1984,10 +2241,19 @@ export function registerWorkflowLane(tools) {
         handler: z
             .string()
             .optional()
-            .describe("event handler to bind: start | cancel | activate | end (default end)"),
+            .describe("FLOW-level event handler to bind: start | cancel | activate | end (default end). 与 activityCode+nodeEvent 互斥"),
+        activityCode: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("NODE-level target activity (草稿里的 activityCode，如 Activity2). 必须与 nodeEvent 同时给；节点不存在时报 workflow-activity-not-found 并列出可用 code"),
+        nodeEvent: z
+            .enum(["beforeActivate", "afterActivate", "endActivity", "cancelActivity", "activityApproved", "activityRejected", "jobSubmitted", "jobRejected"])
+            .optional()
+            .describe("NODE-level event on activityCode: beforeActivate|afterActivate|endActivity|cancelActivity|activityApproved|activityRejected|jobSubmitted|jobRejected（如填写节点 endActivity = 申请人提交离开该节点时）. 与 handler 互斥"),
         publish: z.boolean().optional(),
     }, async (session, args) => {
-        const { key: handlerKey, field: handlerField } = resolveEventHandlerField(args.handler);
+        const target = resolveBindTarget(args.handler, args.nodeEvent, args.activityCode);
         const codes = (args.ruleCodes ?? [args.ruleCode]).map(String);
         // Only CUSTOM rules are bindable to workflow events — the designer's picker
         // does not offer preset trigger rows (bench59 bound `Create` to `end`).
@@ -2005,7 +2271,25 @@ export function registerWorkflowLane(tools) {
                 message: `流程 ${args.workflowCode} 不存在（get_draft 401001 缺席）——先 workflow.create，再 bindRule`,
             });
         }
-        const existing = (draft[handlerField] ?? {});
+        // Node-level: fail closed BEFORE the wire when the activity code is not in
+        // the draft, and name the codes that ARE (the designer's own codes like
+        // Activity2 are the common miss).
+        if (target.scope === "activity" && !findTemplateActivity(draft, target.activityCode)) {
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "workflow-activity-not-found",
+                workflowCode: args.workflowCode,
+                activityCode: target.activityCode,
+                activities: templateActivityCodes(draft),
+                message: `流程 ${args.workflowCode} 的草稿里没有活动 ${target.activityCode}——节点级事件必须指向已存在的活动。可用活动：${templateActivityCodes(draft).join("、") || "（无）"}（先用 workflow.get_draft 看 code，别用节点名）`,
+            });
+        }
+        const handlerOf = (template) => {
+            if (target.scope === "workflow")
+                return (template?.[target.field] ?? {}) ?? {};
+            return (findTemplateActivity(template, target.activityCode)?.[target.field] ?? {}) ?? {};
+        };
+        const existing = handlerOf(draft);
         const priorActions = Array.isArray(existing.bizActions)
             ? existing.bizActions.filter((value) => typeof value === "string")
             : [];
@@ -2016,16 +2300,21 @@ export function registerWorkflowLane(tools) {
         for (const code of codes)
             if (!nextActions.includes(code))
                 nextActions.push(code);
-        const nextTemplate = {
-            ...draft,
-            [handlerField]: {
-                ...(typeof existing === "object" && existing ? existing : {}),
-                bizActions: nextActions,
-                bizActionType: "BIZ_RULE",
-            },
-            workflowCode: args.workflowCode,
-            schemaCode: args.schemaCode,
+        const mergedHandler = {
+            ...(typeof existing === "object" && existing ? existing : {}),
+            bizActions: nextActions,
+            bizActionType: "BIZ_RULE",
         };
+        let nextTemplate;
+        if (target.scope === "workflow") {
+            nextTemplate = { ...draft, [target.field]: mergedHandler, workflowCode: args.workflowCode, schemaCode: args.schemaCode };
+        }
+        else {
+            // Keep the draft's activities container shape (array or index-keyed
+            // object) — only the selected row's handler field changes.
+            nextTemplate = mapTemplateActivity(draft, target.activityCode, (row) => ({ ...row, [target.field]: mergedHandler })).template;
+            nextTemplate = { ...nextTemplate, workflowCode: args.workflowCode, schemaCode: args.schemaCode };
+        }
         validateWorkflowRender(nextTemplate, "workflow.bindRule");
         const performed = await wireCall(session, {
             path: ENDPOINTS.workflowUpdate,
@@ -2052,18 +2341,21 @@ export function registerWorkflowLane(tools) {
         if (!data)
             throw new ToolRefusalError({ status: "refused", blocker: "workflow-render-readback-invalid", message: "workflow.bindRule returned no draft" });
         validateWorkflowRender(data, "workflow.bindRule readback");
-        const handler = data ? data[handlerField] : undefined;
+        const handler = handlerOf(data);
         const bizActions = Array.isArray(handler?.bizActions) ? handler.bizActions.filter((value) => typeof value === "string") : [];
-        const publishedHandler = publishedReadback ? publishedReadback[handlerField] : undefined;
+        const publishedHandler = publishedReadback ? handlerOf(publishedReadback) : undefined;
         const publishedBizActions = Array.isArray(publishedHandler?.bizActions)
             ? publishedHandler.bizActions.filter((value) => typeof value === "string")
             : [];
+        const targetShape = target.scope === "workflow"
+            ? { handler: target.key, handlerField: target.field }
+            : { activityCode: target.activityCode, nodeEvent: target.key, nodeEventField: target.field };
         return {
-            performed: { errcode: performed.errcode, handler: handlerKey, addedRuleCodes: codes, bizActions, publishRequested: shouldPublish },
+            performed: { errcode: performed.errcode, scope: target.scope, ...targetShape, addedRuleCodes: codes, bizActions, publishRequested: shouldPublish },
             readback: {
                 workflowCode: args.workflowCode,
-                handler: handlerKey,
-                handlerField,
+                scope: target.scope,
+                ...targetShape,
                 semantics: "merge",
                 bound: codes.every((code) => bizActions.includes(code)),
                 bizActions,
@@ -2071,7 +2363,9 @@ export function registerWorkflowLane(tools) {
                 enabledRuleCodes,
                 alreadyEnabledRuleCodes,
                 bizActionType: typeof handler?.bizActionType === "string" ? handler.bizActionType : null,
-                templateFieldsPreserved: Object.keys(draft).every((key) => key === handlerField || data[key] !== undefined),
+                templateFieldsPreserved: target.scope === "workflow"
+                    ? Object.keys(draft).every((key) => key === target.field || data[key] !== undefined)
+                    : Object.keys(draft).every((key) => data[key] !== undefined),
                 // Authoritative published-face marker, NOT the request echo: a
                 // refused publish keeps errcode 0 and the draft marker (live 8.6.26).
                 published: publishMarked,
@@ -2086,7 +2380,7 @@ export function registerWorkflowLane(tools) {
             },
         };
     }, (args) => {
-        resolveEventHandlerField(args.handler);
+        resolveBindTarget(args.handler, args.nodeEvent, args.activityCode);
         const hasSingle = typeof args.ruleCode === "string" && args.ruleCode.length > 0;
         const hasMany = Array.isArray(args.ruleCodes);
         if (hasSingle && hasMany)
@@ -2099,6 +2393,130 @@ export function registerWorkflowLane(tools) {
                 throw new ToolRefusalError({ status: "refused", blocker: "workflow-bindrule-codes-invalid", message: "ruleCodes 必须是非空、去重的规则 code 数组" });
         }
     }, undefined, workflowRollbackSpec("workflow.bindRule"));
+    /**
+     * Friendly writer for the designer's 「表单操作」 checkboxes: each PARTICIPANT
+     * activity carries `buttonPermission.customBtns[]` = the form-toolbar buttons
+     * enabled at that node (ActionPermissionHandler.setProcessButtonPermission
+     * filters `getByTriggerTypeAndCode(FORM, formCode)` by this list; a code that
+     * is absent or enabled:false does not render). Writing the whole
+     * `buttonPermission` object by hand means re-sending containerCode +
+     * childTableBtns, which is exactly how a caller drops the child-table
+     * defaults — this tool merges per node.
+     */
+    writeTool(tools, "workflow.setButtons", WORKFLOW_LANE, WORKFLOW_TOOLS["workflow.setButtons"].scope, WORKFLOW_TOOLS["workflow.setButtons"].description, {
+        schemaCode: z.string().min(1),
+        workflowCode: z.string().min(1),
+        nodes: z
+            .array(z.object({
+            activityCode: z.string().min(1).describe("活动 code（workflow.get_draft 的 activities[].code）"),
+            buttonCodes: z.array(z.string().min(1)).describe("该节点要**启用**的表单按钮 code（按 form.get 的 formButtonCodes）；未列出的置为 enabled:false，不删除子表按钮配置"),
+        }))
+            .min(1),
+        publish: z.boolean().optional().describe("默认 true：写草稿后发布，表单页立即生效；false 只写草稿"),
+    }, async (session, args) => {
+        const draft = (await getWorkflowDraftOrNull(session, args.workflowCode)) ?? {};
+        if (Object.keys(draft).length === 0)
+            throw new ToolRefusalError({
+                status: "refused",
+                blocker: "workflow-not-found",
+                workflowCode: args.workflowCode,
+                message: `流程 ${args.workflowCode} 不存在（get_draft 401001 缺席）`,
+            });
+        const available = await readSchemaFormButtons(session, args.schemaCode);
+        const availableCodes = Object.keys(available);
+        const draftCodes = templateActivityCodes(draft);
+        const patches = [];
+        const names = {};
+        for (const node of args.nodes) {
+            const row = findTemplateActivity(draft, node.activityCode);
+            if (!row) {
+                throw new ToolRefusalError({
+                    status: "refused",
+                    blocker: "workflow-activity-not-found",
+                    workflowCode: args.workflowCode,
+                    activityCode: node.activityCode,
+                    activities: draftCodes,
+                    message: `流程 ${args.workflowCode} 没有活动 ${node.activityCode}；可用：${draftCodes.join("、") || "（无）"}`,
+                });
+            }
+            const unknown = node.buttonCodes.filter((code) => available[code] === undefined);
+            if (unknown.length > 0) {
+                throw new ToolRefusalError({
+                    status: "refused",
+                    blocker: "form-button-absent",
+                    schemaCode: args.schemaCode,
+                    activityCode: node.activityCode,
+                    buttonCodes: unknown,
+                    available: availableCodes,
+                    message: `按钮 ${unknown.join("、")} 不在模型 ${args.schemaCode} 的表单按钮里；先 form.publish {buttons:[…]} 生成。可用：${availableCodes.join("、") || "（无）"}`,
+                });
+            }
+            const existing = (row.buttonPermission ?? {});
+            const existingBtns = Array.isArray(existing.customBtns) ? existing.customBtns : [];
+            const wanted = new Set(node.buttonCodes);
+            const merged = [];
+            for (const button of existingBtns) {
+                const code = String(button.code ?? "");
+                if (code === "")
+                    continue;
+                merged.push({ ...button, enabled: wanted.has(code) });
+                wanted.delete(code);
+            }
+            for (const code of wanted) {
+                const source = available[code];
+                names[code] = String(source.name ?? code);
+                merged.push({ code, name: String(source.name ?? code), name_i18n: source.name_i18n ?? null, enabled: true, type: "form" });
+            }
+            patches.push({
+                activityCode: node.activityCode,
+                buttonPermission: {
+                    ...existing,
+                    containerCode: existing.containerCode ?? args.schemaCode,
+                    customBtns: merged,
+                    childTableBtns: existing.childTableBtns ?? [],
+                },
+            });
+        }
+        const body = await mergedTemplateBody(session, args.schemaCode, args.workflowCode, { activities: patches }, true);
+        validateWorkflowRender(body, "workflow.setButtons");
+        const performed = await wireCall(session, { path: ENDPOINTS.workflowUpdate, method: "POST", body });
+        const shouldPublish = args.publish !== false;
+        let publishMarked = false;
+        if (shouldPublish) {
+            const publishPerformed = await wireCall(session, { path: ENDPOINTS.workflowPublish, method: "POST", body });
+            assertWorkflowWriteAccepted(publishPerformed, "workflow.setButtons", args.workflowCode);
+            const pub = await wireCall(session, { path: ENDPOINTS.workflowGetPublished, query: { workflowCode: args.workflowCode } });
+            const published = (pub.data ?? null);
+            publishMarked = published !== null && (published.templateType === "PUBLISH" || published.published === true);
+        }
+        const readback = (await wireCall(session, { path: ENDPOINTS.workflowGetDraft, query: { workflowCode: args.workflowCode } })).data;
+        const nodeButtons = (readback ? readback.activities : draft.activities);
+        const rows = Array.isArray(nodeButtons)
+            ? nodeButtons
+            : nodeButtons && typeof nodeButtons === "object"
+                ? Object.values(nodeButtons)
+                : [];
+        const state = args.nodes.map((node) => {
+            const row = rows.find((entry) => String(entry.activityCode ?? "") === node.activityCode) ?? {};
+            const bp = (row.buttonPermission ?? {});
+            const btns = Array.isArray(bp.customBtns) ? bp.customBtns : [];
+            return {
+                activityCode: node.activityCode,
+                enabled: btns.filter((button) => button.enabled === true).map((button) => String(button.code ?? "")),
+                disabled: btns.filter((button) => button.enabled !== true).map((button) => String(button.code ?? "")),
+            };
+        });
+        return {
+            performed: { errcode: performed.errcode, publishRequested: shouldPublish, nodes: args.nodes.map((node) => node.activityCode) },
+            readback: {
+                workflowCode: args.workflowCode,
+                nodes: state,
+                published: publishMarked,
+                buttonNames: names,
+                note: "节点未列出的按钮被置为 enabled:false（不删除子表按钮配置）；表单页只在 enabled:true 的节点显示该按钮",
+            },
+        };
+    }, undefined, undefined, workflowRollbackSpec("workflow.update"));
     writeTool(tools, "workflow.delete", WORKFLOW_LANE, WORKFLOW_TOOLS["workflow.delete"].scope, WORKFLOW_TOOLS["workflow.delete"].description, { schemaCode: z.string().min(1), code: z.string().min(1) }, async (session, args) => {
         const performed = await wireCall(session, {
             path: ENDPOINTS.workflowDelete,