@stalfh233/omc-cli 0.4.81 → 0.4.82

package/README.md

@@ -130,10 +130,11 @@ omc call discover_environment --env <env> --args '{}'   # 环境就绪（真实
 - **intent**：`partial` 表示该能力可声明式（`omc intent`）覆盖一部分——通常 create/update；
   `none` 表示只走 `omc call`。删除类、方法面、分类/连接池等仍走 `omc call` 逃生舱。
 
-## 近期能力（0.4.74 → 0.4.81）
+## 近期能力（0.4.74 → 0.4.82）
 
 | 版本 | 新增 / 修复 |
 |---|---|
+| 0.4.82 | **流程发起权限（40009）**：新增 `workflow.permissions` / `workflow.addPermission` / `workflow.removePermission`（`/workflow/list_permission`、`create_permission`、`delete_permission`，unitType 线上为枚举序号 1=部门 2=角色 3=用户）。`data.submit`/`data.save+workflowCode` 的 40009 现在直接回 `workflow-start-permission-denied`：带上该流程的权限行现状、两种成因（无权限行 / 发起人部门记录已失效）与可粘贴的修复命令，不再是「流程发起权限不足」五个字 |
 | 0.4.81 | **r11 真机探针修复**：`rule.save` 对 `AGGREGATION` 规则节点**写前 fail-closed**（平台会存进去、运行时 50000，真实路径是 `omc compute`/datarule type2）；`omc next "统计子表行数"` 路由补 `datarule` 阶梯与 `field-compute-subtable-sum` 配方；`org.user.search` 省略关键字时**按部门树列全员**（平台 `wd` 不支持空串，此前只能枚举 0–9）；`omc artifact get --jq` 无值回键清单（不再 commander 报错）；`usage` 的 `faces` 纳入 `--jq/--summary/--keys/--path-only/--extract`（此前读面投影完全不记账） |
 | 0.4.80 | **省 token 与用量账本**：`omc help <topic>` 默认只回节索引（约 1KB，含每节字节数），`--all` 才读整篇；`omc artifact get` 正文 >8KB 默认只回形状（`--full` 才整包）；`omc usage` 默认只回汇总（`byTool`/`redundancy`/`estimatedTokens`），`--records` 才展开；`omc script` 的**每行工具调用单独记账**（`script-call` + `parentId`）；未绑定环境的目录回落 `$OMC_CONFIG_HOME/usage/<cwd-hash>.jsonl` |
 | 0.4.79 | README 对齐 0.4.79 实际工具面（142 工具 / 16 能力） |

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

@@ -339,6 +339,9 @@
         "workflow.bindRule",
         "workflow.setButtons",
         "workflow.delete",
+        "workflow.permissions",
+        "workflow.addPermission",
+        "workflow.removePermission",
         "configure_workflow",
         "workflow.validate",
         "org.role.users",
@@ -365,6 +368,7 @@
       "scopes": [
         "greenfield workflow authoring",
         "workflow node form-button checkboxes",
+        "workflow start permission (who may originate)",
         "organization role member read (role/users)",
         "organization role member management scope read (role/get_ouscope)",
         "organization role group create (role/add_role_group)",

package/dist/endpoints.js

@@ -152,6 +152,18 @@ export const ENDPOINTS = {
     workflowValidate: "/api/api/workflow/validate",
     workflowPublish: "/api/api/workflow/publish",
     workflowDelete: "/api/api/workflow/delete",
+    // 发起权限 (who may START the flow). Without a row here — or with a role/
+    // department row the caller is not in — `data.submit`/`data.save+workflowCode`
+    // answers 40009 流程发起权限不足 (WorkflowAspect.validateWorkflowPermission →
+    // WorkflowManagementFacadeImpl.getWorkflowTemplateHeadersBySchemaCode). Endpoints
+    // from WorkflowTemplateController (cloudpivot-engine 8.6.26; live 1.1.25):
+    //   GET  /workflow/list_permission?workflowCode=        → [{id,name,unitType,fullName,corpId,code}]
+    //   POST /workflow/create_permission  body {workflowCode,unitId,unitType,corpId?}
+    //        unitType is the ENUM INDEX on the wire: 1=部门 2=角色 3=用户 (UnitType @JsonValue)
+    //   POST/DELETE /workflow/delete_permission?permissionId=
+    workflowListPermission: "/api/api/workflow/list_permission",
+    workflowCreatePermission: "/api/api/workflow/create_permission",
+    workflowDeletePermission: "/api/api/workflow/delete_permission",
     workflowSearchWorkItems: "/api/api/runtime/workflow/search_workitems",
     workflowGetBizObjectByWfInstanceId: "/api/api/runtime/workflow/getBizObjectByWfInstanceId",
     workflowListInstanceActivity: "/api/api/runtime/workflow/list_workflow_instance_activity",

package/dist/lanes/runtime-data.js

@@ -699,7 +699,7 @@ export function registerRuntimeDataLane(tools) {
                     ...(replayToken ? { replayToken } : {}),
                     bizObject: { schemaCode: args.schemaCode, sheetCode, data: { ...formData, id: objectId, sequenceStatus: "DRAFT" } },
                 },
-            }), formData);
+            }), formData, args.workflowCode);
             const vo = (performed.data ?? {});
             const returnedId = typeof vo.objectId === "string" && vo.objectId ? vo.objectId : typeof vo.bizObjectId === "string" && vo.bizObjectId ? vo.bizObjectId : objectId;
             const workflowInstanceId = typeof vo.workflowInstanceId === "string" ? vo.workflowInstanceId : null;
@@ -1087,7 +1087,7 @@ export function registerRuntimeDataLane(tools) {
             path: ENDPOINTS.runtimeFormSubmit,
             method: "POST",
             body: payload,
-        }));
+        }), undefined, hasWorkflowCode ? explicitWorkflowCode : undefined);
         const performedData = (performed.data ?? {});
         let readback = { formType };
         if (formType === "2") {

package/dist/lanes/workflow-contract.js

@@ -174,6 +174,18 @@ export const WORKFLOW_LANE_CONTRACT = Object.freeze({
             scope: WORKFLOW_SCOPE,
             description: "删除工作流模板（`/api/api/workflow/delete`），回读确认缺失。",
         }),
+        "workflow.permissions": Object.freeze({
+            scope: "workflow start permission (who may originate)",
+            description: "列出谁能发起该流程（`GET /api/api/workflow/list_permission?workflowCode=` → {id,name,unitType,fullName,corpId,code}；1=部门 2=角色 3=用户）。**`data.submit` 报 40009 时先看这里**：PART_VISIABLE 且本表无命中行 ⇒ 除平台管理员（`h_perm_admin` 的 ADMIN/SYS_MNG，非登录 isAdmin）外无人能发起；发布流程不会自动建这一行。",
+        }),
+        "workflow.addPermission": Object.freeze({
+            scope: "workflow start permission (who may originate)",
+            description: "授予发起权限（`POST /api/api/workflow/create_permission`，body `{workflowCode,unitId,unitType,corpId}`；unitType 取枚举序号 1=部门 2=角色 3=用户）。unitId 用 org.department.list / org.role.list / org.user.search 取。重复授予按 402003 幂等跳过，写后回读确认。",
+        }),
+        "workflow.removePermission": Object.freeze({
+            scope: "workflow start permission (who may originate)",
+            description: "撤销发起权限（`POST /api/api/workflow/delete_permission?permissionId=`）。首选传 `permissionId`（`workflow.permissions` 的 id）；也可传 `workflowCode`+`unitId`+`unitType`，工具解析该主体的显示名后匹配（`list_permission` 不回 unitId）。缺失即幂等成功。",
+        }),
         "workflow.validate": Object.freeze({
             scope: WORKFLOW_SCOPE,
             description: "只读预检（`POST /api/api/workflow/validate`）：合成草稿模板（或可选 `template` 按 merge 语义）后返回 ValidateMessage[]，拆出 errors/warnings，`valid = 无 ERROR`。用于 publish 前先看平台会不会拒——平台对 publish 常回 errcode:0 但 ValidateMessage[] 里带 ERROR，本工具把它显式暴露，避免「publish 看似成功却没落库」。不写任何状态。",
@@ -223,6 +235,9 @@ export function assertWorkflowContract() {
     assertDescriptionCarries(WORKFLOW_LANE_CONTRACT, "workflow.publish", ["workflow/publish", "template"]);
     assertDescriptionCarries(WORKFLOW_LANE_CONTRACT, "workflow.setButtons", ["buttonPermission", "customBtns", "childTableBtns", "formButtonCodes", "form-button-absent", "publish:false"]);
     assertDescriptionCarries(WORKFLOW_LANE_CONTRACT, "workflow.bindRule", ["startEventHandler", "cancelEventHandler", "activateEventHandler", "endEventHandler", "bizActions", "bizActionType", "BIZ_RULE", "publish:false", "enabledRuleCodes", "workflow-bind-rule-absent", "activityCode", "nodeEvent", "endActivity", "activityApproved"]);
+    assertDescriptionCarries(WORKFLOW_LANE_CONTRACT, "workflow.permissions", ["list_permission", "40009", "PART_VISIABLE"]);
+    assertDescriptionCarries(WORKFLOW_LANE_CONTRACT, "workflow.addPermission", ["create_permission", "unitType", "unitId"]);
+    assertDescriptionCarries(WORKFLOW_LANE_CONTRACT, "workflow.removePermission", ["delete_permission", "permissionId"]);
     assertDescriptionCarries(WORKFLOW_LANE_CONTRACT, "org.role.list", ["organization/role/list", "type", "Originator"]);
     assertDescriptionCarries(WORKFLOW_LANE_CONTRACT, "org.department.list", ["organization/department/tree", "parentId"]);
     assertDescriptionCarries(WORKFLOW_LANE_CONTRACT, "org.user.search", ["organization/user/search", "wd", "type 3"]);

package/dist/lanes/workflow-coverage.js

@@ -18,6 +18,9 @@ export const WORKFLOW_COVERAGE = declareLaneCoverage(WORKFLOW_LANE_CONTRACT.lane
             claim("workflow.bindRule", T["workflow.bindRule"].scope),
             claim("workflow.setButtons", T["workflow.setButtons"].scope),
             claim("workflow.delete", T["workflow.delete"].scope),
+            claim("workflow.permissions", T["workflow.permissions"].scope),
+            claim("workflow.addPermission", T["workflow.addPermission"].scope),
+            claim("workflow.removePermission", T["workflow.removePermission"].scope),
             claim("configure_workflow", T["configure_workflow"].scope),
             claim("workflow.validate", T["workflow.validate"].scope),
             // Organization writes (role group / role / members / management scope).

package/dist/lanes/workflow.js

@@ -2724,6 +2724,194 @@ export function registerWorkflowLane(tools) {
             };
         }),
     }));
+    // ── 发起权限 (who may originate) ────────────────────────────────────────────
+    //
+    // 40009 流程发起权限不足 is the single most opaque refusal on this platform:
+    // `data.submit` (and `data.save` with workflowCode) answers it, the message
+    // names no permission, and there is no CLI face to inspect or grant one. r11
+    // (2026-10-24) burned 7 submit attempts and could not deliver the whole
+    // workflow section; the platform source shows the check is concrete:
+    // `WorkflowAspect.validateWorkflowPermission` → template header must exist and
+    // be published → `getWorkflowTemplateHeadersBySchemaCode(userId, schemaCode)`:
+    //   • the user's root department must resolve (`getAllParentIds` non-empty),
+    //   • `visibleType=ALL_VISIABLE` templates are open to everyone,
+    //   • otherwise a `h_workflow_permission` row must match the user, their
+    //     department (or any ancestor), or one of their roles,
+    //   • platform admins (`h_perm_admin` ADMIN/SYS_MNG) bypass all of it.
+    // Publishing a flow creates NO permission row, so a freshly published flow is
+    // unusable by anyone who is not a platform admin.
+    const permissionRows = async (session, workflowCode) => wireRows((await wireCall(session, { path: ENDPOINTS.workflowListPermission, query: { workflowCode } })).data);
+    // `list_permission` echoes the PERMISSION row id plus the unit's display name
+    // and code — never the unitId (WorkflowTemplateController.getPermissionMap).
+    // So identity for readback/removal is resolved from the unit's own face.
+    const unitIdentity = async (session, unitType, unitId) => {
+        try {
+            if (unitType === 1) {
+                const row = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentGet, query: { deptId: unitId } })).data;
+                return { name: row ? String(row.name ?? "") || null : null, code: row ? (String(row.code ?? "") || null) : null };
+            }
+            if (unitType === 2) {
+                const rows = wireRows((await wireCall(session, { path: ENDPOINTS.organizationRoleList, query: { expandAll: "true" } })).data);
+                const walk = (entries) => {
+                    for (const entry of entries) {
+                        if (String(entry.id ?? "") === unitId)
+                            return entry;
+                        const children = Array.isArray(entry.children) ? entry.children : [];
+                        const hit = walk(children);
+                        if (hit)
+                            return hit;
+                    }
+                    return undefined;
+                };
+                const hit = walk(rows);
+                return { name: hit ? String(hit.name ?? "") || null : null, code: hit ? (String(hit.code ?? "") || null) : null };
+            }
+            const row = (await wireCall(session, { path: ENDPOINTS.organizationUserInfo, query: { id: unitId } })).data;
+            return { name: row ? String(row.name ?? "") || null : null, code: row ? (String(row.username ?? "") || null) : null };
+        }
+        catch {
+            return { name: null, code: null };
+        }
+    };
+    tools.push(defineTool({
+        name: "workflow.permissions",
+        layer: "low",
+        kind: "read",
+        lane: WORKFLOW_LANE,
+        scope: WORKFLOW_TOOLS["workflow.permissions"].scope,
+        description: WORKFLOW_TOOLS["workflow.permissions"].description,
+        inputSchema: {
+            environment: environmentArg,
+            workflowCode: z.string().optional().describe("流程 code；省略则用 schemaCode 解析"),
+            schemaCode: z.string().optional().describe("模型 code：省略 workflowCode 时用它解析该模型的流程"),
+            capability: capabilityArg,
+        },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const workflowCode = await resolveWorkflowArg(session, args);
+            if (!workflowCode)
+                return { schemaCode: args.schemaCode, exists: false, permissions: [], note: "该模型没有流程" };
+            const rows = await permissionRows(session, workflowCode);
+            const permissions = rows.map((row) => ({
+                id: row.id ?? null,
+                name: row.name ?? null,
+                unitType: row.unitType ?? null,
+                unitTypeName: row.unitType === 1 || row.unitType === "1" ? "部门" : row.unitType === 2 || row.unitType === "2" ? "角色" : row.unitType === 3 || row.unitType === "3" ? "用户" : null,
+                fullName: row.fullName ?? null,
+                corpId: row.corpId ?? null,
+                code: row.code ?? null,
+            }));
+            return {
+                workflowCode,
+                count: permissions.length,
+                permissions,
+                ...(permissions.length === 0
+                    ? {
+                        blocker: "workflow-start-permission-empty",
+                        note: "该流程没有任何发起权限行：除平台管理员（h_perm_admin 里 ADMIN/SYS_MNG）外**没有人能发起**，data.submit 会回 40009「流程发起权限不足」。发布流程不会自动建这一行，用 workflow.addPermission 授给部门/角色/用户（或把模板 visibleType 改成 ALL_VISIABLE）。",
+                        nextCommand: `omc call workflow.addPermission --env <env> --args '{"workflowCode":"${workflowCode}","unitId":"<部门|角色|用户 id>","unitType":1}'`,
+                    }
+                    : {}),
+            };
+        }),
+    }));
+    writeTool(tools, "workflow.addPermission", WORKFLOW_LANE, WORKFLOW_TOOLS["workflow.addPermission"].scope, WORKFLOW_TOOLS["workflow.addPermission"].description, {
+        workflowCode: z.string().optional().describe("流程 code；省略则用 schemaCode 解析"),
+        schemaCode: z.string().optional().describe("模型 code：省略 workflowCode 时用它解析该模型的流程"),
+        unitId: z.string().min(1).describe("部门 id / 角色 id / 用户 id（看 unitType）"),
+        unitType: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal("DEPARTMENT"), z.literal("ROLE"), z.literal("USER")]).describe("1=部门 2=角色 3=用户；也接受 DEPARTMENT/ROLE/USER"),
+        corpId: z.string().optional().describe("企业 id；省略则用当前会话企业"),
+    }, async (session, args) => {
+        const workflowCode = await resolveWorkflowArg(session, args);
+        if (!workflowCode)
+            throw new ToolRefusalError({ status: "refused", blocker: "workflow-not-found", message: `模型 ${String(args.schemaCode ?? "")} 没有流程；先 workflow.create` });
+        const unitType = args.unitType === 1 || args.unitType === "DEPARTMENT" ? 1 : args.unitType === 2 || args.unitType === "ROLE" ? 2 : 3;
+        // Idempotent retry: the platform answers 402003 WORKFLOW_PERMISSION_EXIST
+        // for a duplicate unitId, which would read as a failure. `list_permission`
+        // does NOT echo unitId (only id/name/unitType/fullName/code), so identity
+        // is decided by the platform's own refusal rather than a guessed pre-read.
+        const before = await permissionRows(session, workflowCode);
+        try {
+            // Send the unit's own name/code too: `list_permission` reads them back
+            // (it echoes `name`/`code`), which is the only way `workflow.permissions`
+            // can describe a row by more than its opaque permission id.
+            const identity = await unitIdentity(session, unitType, args.unitId);
+            await wireCall(session, {
+                path: ENDPOINTS.workflowCreatePermission,
+                method: "POST",
+                body: {
+                    workflowCode,
+                    unitId: args.unitId,
+                    unitType,
+                    corpId: args.corpId ?? session.enterpriseId(),
+                    ...(identity.name ? { name: identity.name } : {}),
+                    ...(identity.code ? { code: identity.code } : {}),
+                },
+            });
+        }
+        catch (error) {
+            const errcode = error.details?.errcode ?? error.errcode;
+            if (String(errcode ?? "") !== "402003")
+                throw new ToolRefusalError({
+                    status: "refused",
+                    blocker: "workflow-permission-write-failed",
+                    workflowCode,
+                    unitId: args.unitId,
+                    unitType,
+                    message: `create_permission 被平台拒绝（err=${String(errcode ?? "n/a")}）。核对 unitId 是否真实存在（部门用 org.department.list、角色用 org.role.list、用户用 org.user.search），以及发起权限是否被企业策略禁用。原始错误：${error instanceof Error ? error.message : String(error)}`,
+                });
+            return {
+                performed: { skipped: "already-present" },
+                readback: { workflowCode, alreadyPresent: true, unitId: args.unitId, unitType, count: before.length, note: "该主体已有发起权限（平台 402003），未重复写入" },
+            };
+        }
+        const after = await permissionRows(session, workflowCode);
+        const created = after.find((row) => !before.some((old) => String(old.id ?? "") === String(row.id ?? ""))) ?? after[after.length - 1];
+        return {
+            performed: { errcode: 0 },
+            readback: {
+                workflowCode,
+                count: after.length,
+                permissionId: created?.id ?? null,
+                unitType: created?.unitType ?? unitType,
+                name: created?.name ?? null,
+                note: "发起权限已授予。若之前 data.submit 回 40009，现在应可发起；仍失败先 workflow.permissions 确认行存在，并核对发起人所属部门/角色。",
+            },
+        };
+    });
+    writeTool(tools, "workflow.removePermission", WORKFLOW_LANE, WORKFLOW_TOOLS["workflow.removePermission"].scope, WORKFLOW_TOOLS["workflow.removePermission"].description, {
+        permissionId: z.string().min(1).optional().describe("首选：workflow.permissions 返回的 id（唯一确定）"),
+        workflowCode: z.string().optional().describe("配合 unitId+unitType 使用（平台的 list_permission 不回 unitId，需按显示名解析）"),
+        unitId: z.string().min(1).optional().describe("部门/角色/用户 id；按 unitType 解析显示名后匹配权限行"),
+        unitType: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal("DEPARTMENT"), z.literal("ROLE"), z.literal("USER")]).optional().describe("unitId 的类型：1=部门 2=角色 3=用户"),
+        schemaCode: z.string().optional(),
+    }, async (session, args) => {
+        let permissionId = args.permissionId;
+        if (!permissionId) {
+            const workflowCode = await resolveWorkflowArg(session, { workflowCode: args.workflowCode, schemaCode: args.schemaCode });
+            if (!workflowCode || !args.unitId || args.unitType === undefined)
+                throw new ToolInputError({ status: "error", blocker: "tool-input-invalid", tool: "workflow.removePermission", message: "需要 permissionId（推荐），或 workflowCode（/schemaCode）+ unitId + unitType" });
+            const unitType = args.unitType === 1 || args.unitType === "DEPARTMENT" ? 1 : args.unitType === 2 || args.unitType === "ROLE" ? 2 : 3;
+            const identity = await unitIdentity(session, unitType, args.unitId);
+            const rows = await permissionRows(session, workflowCode);
+            const wantedType = String(unitType);
+            const hit = rows.find((row) => String(row.unitType ?? "") === wantedType && (String(row.id ?? "") === args.unitId ||
+                (identity.name !== null && String(row.name ?? "") === identity.name) ||
+                (identity.code !== null && String(row.code ?? "") === identity.code)));
+            if (!hit)
+                return {
+                    performed: { skipped: "absent" },
+                    readback: {
+                        workflowCode,
+                        removed: false,
+                        note: `没有匹配该主体的权限行（幂等）。注意 list_permission 不回 unitId，匹配靠解析出的显示名「${identity.name ?? "?"}」；不确定时用 workflow.permissions 拿 id 再按 permissionId 删。`,
+                        permissions: rows.map((row) => ({ id: row.id ?? null, name: row.name ?? null, unitType: row.unitType ?? null })),
+                    },
+                };
+            permissionId = String(hit.id ?? "");
+        }
+        await wireCall(session, { path: ENDPOINTS.workflowDeletePermission, method: "POST", query: { permissionId } });
+        return { performed: { errcode: 0 }, readback: { permissionId, removed: true } };
+    });
     tools.push(defineTool({
         name: "org.role.list",
         layer: "low",

package/dist/runtime-support.js

@@ -54,11 +54,17 @@ export async function mapUnpublishedAppFailure(session, schemaCode, errcode, roo
  * unpublished-app failure. Used by data.save/data.submit (errcode 50000) and
  * datarule.create type2 (errcode 305003) so the try/catch wiring lives once.
  */
-export async function runtimeWriteWithAppMapping(session, schemaCode, errcode, rootCause, call, formData) {
+export async function runtimeWriteWithAppMapping(session, schemaCode, errcode, rootCause, call, formData, workflowCode) {
     try {
         return await call();
     }
     catch (error) {
+        // 40009 is diagnosed FIRST: it names a cause the app/relation mappings
+        // cannot see, and it is the one refusal whose fix is a concrete next
+        // command (r11: seven blind submit attempts). Guarded by the errcode so
+        // every other failure keeps its existing mapping.
+        if (error instanceof WireError && error.kind === "business" && error.errcode === 40009)
+            await diagnoseWorkflowStartPermission(session, schemaCode, workflowCode, error);
         let mapped;
         try {
             mapped = await mapUnpublishedAppFailure(session, schemaCode, errcode, rootCause, error);
@@ -131,4 +137,89 @@ export async function diagnoseRelationShapeFailure(session, schemaCode, errcode,
         message: `errcode ${errcode}——根因：单选关联字段 ${culprits.join(", ")} 传了数组（WORK_SHEET/propertyType 9 只接受 id 字符串或 {id}；数组会稳定 ${errcode}）。多选关联（11）与人员/组织（50/51）才用数组`,
     });
 }
+/**
+ * 40009 流程发起权限不足 — the most opaque refusal on this platform.
+ *
+ * r11 (2026-10-24, 1.1.25) could not deliver an entire workflow section: seven
+ * `data.submit` attempts all answered the same two words, and neither the
+ * message nor any CLI face said WHY. The platform source
+ * (`WorkflowAspect.validateWorkflowPermission` →
+ * `WorkflowManagementFacadeImpl.getWorkflowTemplateHeadersBySchemaCode`) shows
+ * three independent causes, all of which produce the identical code:
+ *
+ *   1. `h_workflow_template` header missing / not published;
+ *   2. the caller's root department does not resolve (`getAllParentIds` empty →
+ *      the allowed-template list is short-circuited to EMPTY, so a user whose
+ *      department row was deleted/moved can never start anything);
+ *   3. no `h_workflow_permission` row matching the user, their department (or an
+ *      ancestor), or one of their roles — and `visibleType != ALL_VISIABLE`.
+ *      Publishing a flow creates NO permission row, so a freshly published flow
+ *      is unusable by everyone except a `h_perm_admin` ADMIN/SYS_MNG.
+ *
+ * The diagnosis here reads only the cheap, authoritative faces (permission list
+ * + header presence) and names the recovery command instead of leaving the
+ * caller to guess. Anything that fails is swallowed: a diagnosis must never
+ * replace the original refusal.
+ */
+export async function diagnoseWorkflowStartPermission(session, schemaCode, workflowCode, error) {
+    if (!(error instanceof WireError && error.kind === "business" && error.errcode === 40009))
+        throw error;
+    const resolvedCode = workflowCode ?? (await resolvePublishedWorkflowCodeQuiet(session, schemaCode));
+    if (!resolvedCode)
+        throw error;
+    let permissions = [];
+    let headerPresent = true;
+    try {
+        headerPresent = (await wireCall(session, { path: ENDPOINTS.workflowGetHeader, query: { workflowCode: resolvedCode } })).data != null;
+    }
+    catch {
+        headerPresent = true;
+    }
+    try {
+        permissions = wireRows((await wireCall(session, { path: ENDPOINTS.workflowListPermission, query: { workflowCode: resolvedCode } })).data);
+    }
+    catch {
+        permissions = [];
+    }
+    const headerHint = headerPresent ? "" : ` 流程头 ${resolvedCode} 不存在或未发布（先 workflow.publish）。`;
+    const message = permissions.length === 0
+        ? `流程 ${resolvedCode} 没有任何发起权限行。§ 发布流程不会自动建发起权限§：` +
+            `除平台管理员（平台 h_perm_admin 里的 ADMIN/SYS_MNG，注意这与登录接口返回的 isAdmin 不是一回事）外，任何人都无法发起，` +
+            `data.submit / data.save+workflowCode 一律回 40009。${headerHint}` +
+            ` 修复：把发起权限授给一个部门/角色/用户 —— ` +
+            `omc call workflow.addPermission --env <env> --args '{"workflowCode":"${resolvedCode}","unitId":"<org.department.list|org.role.list|org.user.search 的 id>","unitType":1}'` +
+            `（1=部门 2=角色 3=用户；同一行也可用 workflow.permissions 复核）。` +
+            `另一种原因同样报 40009 且无法从权限行看出来：发起人所属部门记录已被删除/移动（平台 getRootDeptId 解析为空时直接短路成"无任何可发起模板"）——` +
+            `用 org.user.search 看自己的 departmentId，再用 org.department.list 确认该部门仍在。`
+        : `流程 ${resolvedCode} 已有 ${permissions.length} 条发起权限行（${permissions.map((row) => `${String(row.name ?? row.code ?? "?")}/unitType=${String(row.unitType ?? "?")}`).join("、")}），` +
+            `但当前调用者不在其中。${headerHint}` +
+            ` 核对顺序：① 发起人的 departmentId（org.user.search）是否等于某条 unitType=1 的部门，或是其祖先链上的一级；` +
+            `② 发起人是否属于某条 unitType=2 的角色（org.role.users）；③ 是否该 unitType=3 的用户本人；` +
+            `④ 若部门记录已被删除/移动，平台会把可发起列表短路成空——同样报 40009，但与权限行无关。` +
+            ` 补授权：omc call workflow.addPermission --env <env> --args '{"workflowCode":"${resolvedCode}","unitId":"<id>","unitType":1}'；查看现状用 omc call workflow.permissions。`;
+    throw new ToolRefusalError({
+        status: "refused",
+        blocker: "workflow-start-permission-denied",
+        schemaCode,
+        workflowCode: resolvedCode,
+        errcode: 40009,
+        permissionCount: permissions.length,
+        permissions,
+        message,
+    });
+}
+/** The published workflow code for a schema, or undefined (never throws). */
+async function resolvePublishedWorkflowCodeQuiet(session, schemaCode) {
+    try {
+        const isWorkflow = (await wireCall(session, { path: ENDPOINTS.workflowIsWorkflow, query: { schemaCode } })).data === true;
+        if (!isWorkflow)
+            return undefined;
+        const template = (await wireCall(session, { path: ENDPOINTS.workflowGetBySchema, query: { schemaCode } })).data;
+        const code = template && typeof template.workflowCode === "string" && template.workflowCode.length > 0 ? template.workflowCode : null;
+        return code ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 //# sourceMappingURL=runtime-support.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stalfh233/omc-cli",
-  "version": "0.4.81",
+  "version": "0.4.82",
   "description": "CloudPivot 8.6 configuration capability CLI — governed, fail-closed, coverage-manifest bounded.",
   "type": "module",
   "bin": {
@@ -50,9 +50,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@stalfh233/omc-fake-platform": "0.4.81",
+    "@stalfh233/omc-fake-platform": "0.4.82",
     "commander": "14.0.3",
-    "omc-core": "0.4.81",
+    "omc-core": "0.4.82",
     "proper-lockfile": "4.1.2",
     "write-file-atomic": "6.0.0",
     "zod": "^3.23.8",

package/skills/omc-capabilities.md

@@ -148,7 +148,7 @@ only the section for the capability you need —
 ## 流程模板 `workflow`
 
 - **能做哪些事**：流程模板 get_draft/get_published、create、update、publish、bindRule（事件处理器规则绑定）、delete、workitem.list、workflow.instanceActivity（实例节点状态诊断）；参与人用组织对象。
-- **工具**：`workflow.get_draft`、`workflow.setButtons`（节点「表单操作」按钮勾选）、`workflow.get_published`、`workflow.validate`、`workflow.create`、`workflow.update`、`workflow.publish`、`workflow.bindRule`、`workflow.delete`、`configure_workflow`、`workitem.list`、`workflow.instanceActivity`、`org.role.list`、`org.department.list`、`org.user.search`、`org.role.users`、`org.role.userScope`、`org.roleGroup.create`、`org.role.create`、`org.role.update`、`org.role.addUsers`、`org.role.removeUsers`、`org.role.setUserScope`、`org.department.create`、`org.department.update`、`org.department.delete`、`org.department.users`、`org.user.create`、`org.user.update`、`org.user.delete`、`org.user.info`、`org.user.departments`、`org.role.delete`、`org.roleGroup.delete`、`org.user.transferDepartment`
+- **工具**：`workflow.get_draft`、`workflow.setButtons`（节点「表单操作」按钮勾选）、`workflow.get_published`、`workflow.validate`、`workflow.create`、`workflow.update`、`workflow.publish`、`workflow.bindRule`、`workflow.delete`、`workflow.permissions`、`workflow.addPermission`、`workflow.removePermission`（发起权限：发布流程不会自动建这一行，缺它一律 40009）、`configure_workflow`、`workitem.list`、`workflow.instanceActivity`、`org.role.list`、`org.department.list`、`org.user.search`、`org.role.users`、`org.role.userScope`、`org.roleGroup.create`、`org.role.create`、`org.role.update`、`org.role.addUsers`、`org.role.removeUsers`、`org.role.setUserScope`、`org.department.create`、`org.department.update`、`org.department.delete`、`org.department.users`、`org.user.create`、`org.user.update`、`org.user.delete`、`org.user.info`、`org.user.departments`、`org.role.delete`、`org.roleGroup.delete`、`org.user.transferDepartment`
 - **recipe**：`omc describe workflow.bindRule --example workflow-handler-binding`
 - **边界 / 陷阱**：greenfield 首版；`publish`/`bindRule` 不得在 `ValidateMessage[]` 拒绝时报告成功。运行时 workitem（提交/审批）走 `data.submit`；想知道实例停在哪/是否错派，用 `workflow.instanceActivity`（无 status=1=真停，参与人全是发起人=解析为空退回）。