@stalfh233/omc-cli 0.4.73 → 0.4.74

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

@@ -339,10 +339,50 @@
         "workflow.bindRule",
         "workflow.delete",
         "configure_workflow",
-        "workflow.validate"
+        "workflow.validate",
+        "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.role.delete",
+        "org.roleGroup.delete",
+        "org.user.transferDepartment",
+        "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"
       ],
       "scopes": [
-        "greenfield workflow authoring"
+        "greenfield workflow authoring",
+        "organization role member read (role/users)",
+        "organization role member management scope read (role/get_ouscope)",
+        "organization role group create (role/add_role_group)",
+        "organization role create (role/add_role)",
+        "organization role update (role/modify_role)",
+        "organization role member add (role/add_role_user)",
+        "organization role member remove (role/strike_out_role_user)",
+        "organization role member scope update (role/update_ouscope)",
+        "organization role delete (role/strike_out_role)",
+        "organization role group delete (role/strike_out_role_group)",
+        "organization user department transfer (user/dept_transfer)",
+        "organization department create (department/add)",
+        "organization department update (department/modefied)",
+        "organization department delete (department/strike_out)",
+        "organization department member read (department/list_user)",
+        "organization user create (user/add)",
+        "organization user update (user/modify)",
+        "organization user delete (user/strike_out)",
+        "organization user read (user/info)",
+        "organization user department read (user/departments)"
       ]
     },
     {

package/dist/cli.js

@@ -28,6 +28,7 @@ import { cmdFormDefault } from "./form-default.js";
 if (process.argv.includes("--utf8"))
     process.env.OMC_ASCII_STDOUT = "0";
 import { commandIndex, commandInventory, describeContract, describeContractFull, describeContractTool, describeExample, describeParam, describeSchemaOnly, describeTool, describeToolFull } from "./discovery.js";
+import { repeatFullDescribe } from "./describe-cache.js";
 import { buildCapabilityOverview, capabilityDetail, compactCapabilities, executableCapabilityBundle, resolveCapabilityId, DISCOVERY_AUTHORITY } from "./capability-overview.js";
 import { goalRoute } from "./goal-routes.js";
 import { absencePointer } from "./capability-absences.js";
@@ -630,8 +631,13 @@ function cmdDiscovery(kind, transport, value, options = {}) {
         result = describeParam(registry, value ?? "", options.param);
     else if (options.example !== undefined)
         result = describeExample(registry, value ?? "", typeof options.example === "string" ? options.example : undefined);
-    else if (options.full)
-        result = describeToolFull(registry, value ?? "");
+    else if (options.full) {
+        const full = describeToolFull(registry, value ?? "");
+        // r9: the same `--full` contract was re-shipped 8 times (134 KB) while the
+        // caller only wanted to re-check a shape. Within a project session the
+        // second identical read returns an artifact reference instead of the body.
+        result = full ? (repeatFullDescribe(value ?? "", full) ?? full) : full;
+    }
     else
         result = describeTool(registry, value ?? "");
     if (!result) {

package/dist/describe-cache.js

@@ -0,0 +1,91 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { artifactRoot, joinConfigRoot } from "./command-transport.js";
+import { createArtifact, readArtifact } from "./artifacts.js";
+import { projectSessionActive } from "./usage-log.js";
+/**
+ * Repeat-read suppression for `describe <tool> --full`.
+ *
+ * r9 (2026-10-22) spent 134 KB on EIGHT `describe rule.save --full` calls: the
+ * same contract, unchanged, re-shipped every time the caller re-checked a shape.
+ * The hint at the bottom of the response ("先试 --example/--param") did not help
+ * because a caller editing a graph wants the authoritative schema again, and
+ * `--full` had no memory.
+ *
+ * The first `--full` in a project still returns the whole contract and spills a
+ * copy to an artifact. A later identical read returns `{artifactId, sha256,
+ * bytes, fetch}` instead: the caller can project the one key it needs with
+ * `omc artifact get <id> --jq <path>` instead of paying for the whole body
+ * again. Identity is the CONTENT hash, so a changed contract (new version, new
+ * field) always returns the full body again.
+ *
+ * Scoped to a project session by construction: the cache only exists where the
+ * usage log does (`.omc-env` in the working directory, or OMC_USAGE_LOG). Repo
+ * tests and the golden master run without it, so their bytes stay stable.
+ */
+const CACHE_FILE = "describe-full-cache.json";
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+function cachePath() {
+    return resolve(joinConfigRoot(), ".omc", CACHE_FILE);
+}
+function readCache() {
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath(), "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeCache(cache) {
+    try {
+        const path = cachePath();
+        mkdirSync(join(path, ".."), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(cache)}\n`, { mode: 0o600 });
+    }
+    catch {
+        // Best-effort: a cache write must never fail the command.
+    }
+}
+/**
+ * Return the compact repeat-read face for `tool`, or `undefined` when this is
+ * the first read (or the contract changed). Records the new entry as a side
+ * effect so the NEXT read is compact.
+ */
+export function repeatFullDescribe(tool, result) {
+    // No project session (repo tests, golden master, one-off runs) ⇒ no cache:
+    // those callers need byte-stable output, and a cache write would be litter.
+    if (!projectSessionActive())
+        return undefined;
+    const body = `${JSON.stringify(result, null, 2)}\n`;
+    const bytes = Buffer.byteLength(body, "utf8");
+    const digest = createHash("sha256").update(body).digest("hex");
+    const cache = readCache();
+    const previous = cache[tool];
+    if (previous && previous.sha256 === digest && Date.now() - previous.at < CACHE_TTL_MS) {
+        // A pruned artifact would turn the summary into a dead end; re-ship instead.
+        if (existsSync(join(artifactRoot(), `${previous.artifactId}.artifact`))) {
+            try {
+                readArtifact(artifactRoot(), previous.artifactId);
+                return {
+                    name: tool,
+                    repeated: true,
+                    artifactId: previous.artifactId,
+                    sha256: digest,
+                    bytes,
+                    fetch: `omc artifact get ${previous.artifactId} --summary（再 --keys/--jq 取需要的键）`,
+                    note: `本项目的会话里已读过同一个契约（${bytes}B，内容 sha256 未变），本次不再重发全文；用 fetch 里的命令按需投影`,
+                };
+            }
+            catch {
+                // fall through to a full re-ship
+            }
+        }
+    }
+    const artifact = createArtifact(artifactRoot(), body);
+    cache[tool] = { tool, sha256: digest, bytes, artifactId: artifact.artifactId, at: Date.now() };
+    writeCache(cache);
+    return undefined;
+}
+//# sourceMappingURL=describe-cache.js.map

package/dist/endpoints.js

@@ -120,6 +120,28 @@ export const ENDPOINTS = {
     organizationRoleList: "/api/api/organization/role/list",
     organizationDepartmentTree: "/api/api/organization/department/tree",
     organizationUserSearch: "/api/api/organization/user/search",
+    organizationRoleUsers: "/api/api/organization/role/users",
+    organizationRoleGetOuScope: "/api/api/organization/role/get_ouscope",
+    organizationRoleUpdateOuScope: "/api/api/organization/role/update_ouscope",
+    organizationRoleAddGroup: "/api/api/organization/role/add_role_group",
+    organizationRoleAdd: "/api/api/organization/role/add_role",
+    organizationRoleModify: "/api/api/organization/role/modify_role",
+    organizationRoleGet: "/api/api/organization/role/get",
+    organizationDepartmentAdd: "/api/api/organization/department/add",
+    organizationDepartmentModify: "/api/api/organization/department/modefied",
+    organizationDepartmentDelete: "/api/api/organization/department/strike_out",
+    organizationDepartmentGet: "/api/api/organization/department/get_dept_info",
+    organizationDepartmentUsers: "/api/api/organization/department/list_user",
+    organizationUserAdd: "/api/api/organization/user/add",
+    organizationUserModify: "/api/api/organization/user/modify",
+    organizationUserDelete: "/api/api/organization/user/strike_out",
+    organizationUserInfo: "/api/api/organization/user/info",
+    organizationUserDepartments: "/api/api/organization/user/departments",
+    organizationRoleAddUser: "/api/api/organization/role/add_role_user",
+    organizationRoleRemoveUser: "/api/api/organization/role/strike_out_role_user",
+    organizationRoleDelete: "/api/api/organization/role/strike_out_role",
+    organizationRoleGroupDelete: "/api/api/organization/role/strike_out_role_group",
+    organizationUserDeptTransfer: "/api/api/organization/user/dept_transfer",
     listQueryCreate: "/api/api/app/query/create",
     listQueryGet: "/api/api/app/query/get",
     listQueryUpdate: "/api/api/app/query/update",

package/dist/lanes/organization-coverage.js

@@ -0,0 +1,27 @@
+import { claim, declareLaneCoverage } from "./coverage-declaration.js";
+import { LANES } from "./lane-ids.js";
+/**
+ * Organization writes (role group / role / members / management scope) sit on
+ * the same live-proven template lane; the scopes below are claimed here so the
+ * runtime gate can resolve them without a second manifest item.
+ */
+export const ORGANIZATION_COVERAGE = declareLaneCoverage(LANES.workflow, [
+    {
+        capability: "W7 S29 greenfield workflow authoring",
+        evidence: [
+            "packages/omc-cli/src/lanes/organization.ts",
+            "OpenAPI /api/v3/api-docs (1.1.25): organization/role/add_role, add_role_user, update_ouscope",
+        ],
+        tools: [
+            claim("org.role.users", "organization role member read (role/users)"),
+            claim("org.role.userScope", "organization role member management scope read (role/get_ouscope)"),
+            claim("org.roleGroup.create", "organization role group create (role/add_role_group)"),
+            claim("org.role.create", "organization role create (role/add_role)"),
+            claim("org.role.update", "organization role update (role/modify_role)"),
+            claim("org.role.addUsers", "organization role member add (role/add_role_user)"),
+            claim("org.role.removeUsers", "organization role member remove (role/strike_out_role_user)"),
+            claim("org.role.setUserScope", "organization role member scope update (role/update_ouscope)"),
+        ],
+    },
+]);
+//# sourceMappingURL=organization-coverage.js.map

package/dist/lanes/organization.js

@@ -0,0 +1,628 @@
+import { z } from "zod";
+import { ToolInputError, ToolRefusalError } from "../tool-types.js";
+import { defineTool } from "../tool-types.js";
+import { governedRead } from "../read.js";
+import { writeTool } from "../write.js";
+import { wireCall, wireRows, WireError } from "../wire.js";
+import { ENDPOINTS } from "../endpoints.js";
+import { environmentArg, capabilityArg } from "../args.js";
+import { LANES } from "./lane-ids.js";
+/**
+ * Organization WRITE faces (8.6.41 customer transcript, 2026-10-21).
+ *
+ * The read faces already existed (org.role.list / org.department.list /
+ * org.user.search); the customer's manual work was entirely writes: create a
+ * role group ("分组" in the UI is a role), create roles under it, add members,
+ * and set each member's management scope. Those are now first-class tools.
+ *
+ * Three wire quirks are encoded here because every one of them cost the
+ * customer a failed round:
+ *  - `corpId` must ride the QUERY (a self-maintained org uses the literal
+ *    "other" in the body), not only the header;
+ *  - `add_role_user` wants `unitType` as a STRING "3", `update_ouscope` wants
+ *    the INT 3;
+ *  - `update_ouscope` is REPLACE semantics with no rollback, so the tool reads
+ *    the current scope and merges by default (`replace:true` is explicit).
+ */
+const LANE = LANES.workflow;
+const SCOPE = "organization role/member/scope lifecycle via /api/api/organization/role/*";
+const SCOPES = {
+    roleUsers: "organization role member read (role/users)",
+    userScope: "organization role member management scope read (role/get_ouscope)",
+    groupCreate: "organization role group create (role/add_role_group)",
+    roleCreate: "organization role create (role/add_role)",
+    roleUpdate: "organization role update (role/modify_role)",
+    addUsers: "organization role member add (role/add_role_user)",
+    removeUsers: "organization role member remove (role/strike_out_role_user)",
+    setScope: "organization role member scope update (role/update_ouscope)",
+    roleDelete: "organization role delete (role/strike_out_role)",
+    roleGroupDelete: "organization role group delete (role/strike_out_role_group)",
+    userTransfer: "organization user department transfer (user/dept_transfer)",
+    deptCreate: "organization department create (department/add)",
+    deptUpdate: "organization department update (department/modefied)",
+    deptDelete: "organization department delete (department/strike_out)",
+    deptUsers: "organization department member read (department/list_user)",
+    userCreate: "organization user create (user/add)",
+    userUpdate: "organization user update (user/modify)",
+    userDelete: "organization user delete (user/strike_out)",
+    userInfo: "organization user read (user/info)",
+    userDepartments: "organization user department read (user/departments)",
+};
+/**
+ * `DeptType` is a Jackson enum over INT indices: writing the readable
+ * "dept"/"DEPT" answers 10009 「类型转换异常: not one of [0,1,2,3]」 (live
+ * 2026-10-22, 1.1.25). Accept the names and map them.
+ */
+const DEPT_TYPE_CODES = Object.freeze({
+    DEPT: 0, DEPARTMENT: 0, 部门: 0,
+    EDU_DEPT: 1, 家校部门: 1,
+    YUNS_DEPT: 2, 云枢部门: 2,
+    VIRTUAL_EDU_DEPT: 3, 虚拟家校部门: 3,
+});
+function deptTypeCode(value) {
+    if (value === undefined)
+        return 0;
+    if (typeof value === "number") {
+        if (!Number.isInteger(value) || value < 0 || value > 3)
+            throw new ToolInputError({ status: "error", blocker: "tool-input-invalid", tool: "org.department.create", message: `deptType ${String(value)} 不在 0..3（0=部门 1=家校部门 2=云枢部门 3=虚拟家校部门）` });
+        return value;
+    }
+    const code = DEPT_TYPE_CODES[String(value).trim().toUpperCase()] ?? DEPT_TYPE_CODES[String(value).trim()];
+    if (code === undefined)
+        throw new ToolInputError({ status: "error", blocker: "tool-input-invalid", tool: "org.department.create", message: `deptType "${String(value)}" 不认识；可用 ${Object.keys(DEPT_TYPE_CODES).join("、")} 或整数 0..3` });
+    return code;
+}
+const orgQuery = (session) => ({ corpId: session.enterpriseId() });
+const roleUserId = (row) => String(row.id ?? row.userId ?? row.recId ?? "");
+async function memberRows(session, roleId) {
+    const data = (await wireCall(session, {
+        path: ENDPOINTS.organizationRoleUsers,
+        query: { ...orgQuery(session), roleId, page: "0", size: "500" },
+    })).data;
+    return Array.isArray(data?.content) ? data.content : wireRows(data);
+}
+async function removeMembers(session, roleId, userIds) {
+    if (userIds.length === 0)
+        return;
+    await wireCall(session, {
+        path: ENDPOINTS.organizationRoleRemoveUser, method: "POST", query: orgQuery(session),
+        body: { roleId, userIds },
+    });
+}
+async function rolesInGroup(session, roleGroupId) {
+    // `expandAll=true` is mandatory: without it /role/list only fills the FIRST
+    // group's children, so roles under any other group read back as absent.
+    const data = (await wireCall(session, { path: ENDPOINTS.organizationRoleList, query: { expandAll: "true" } })).data;
+    const roles = [];
+    const walk = (rows, inside) => {
+        for (const row of rows) {
+            const isGroup = row.group === true || (row.group === undefined && Array.isArray(row.children) && row.children.length > 0);
+            const id = String(row.id ?? "");
+            if (inside || (isGroup && id === roleGroupId)) {
+                if (!isGroup && id !== "")
+                    roles.push({ id, name: String(row.name ?? "") });
+            }
+            if (Array.isArray(row.children))
+                walk(row.children, inside || (isGroup && id === roleGroupId));
+        }
+    };
+    walk(wireRows(data), false);
+    return roles;
+}
+export function registerOrganizationLane(tools) {
+    tools.push(defineTool({
+        name: "org.role.users",
+        layer: "low",
+        kind: "read",
+        lane: LANE,
+        scope: SCOPES.roleUsers,
+        description: "列出角色成员（`GET organization/role/users`）。返回 members[{id(recId),name,...}]；**id 是 recId，不是账号**（addUsers/setUserScope 都传它）。",
+        inputSchema: {
+            environment: environmentArg,
+            roleId: z.string().min(1).describe("角色 id（不是角色 code）"),
+            page: z.number().int().min(0).optional(),
+            size: z.number().int().min(1).max(500).optional(),
+            capability: capabilityArg,
+        },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const data = (await wireCall(session, {
+                path: ENDPOINTS.organizationRoleUsers,
+                query: { ...orgQuery(session), roleId: String(args.roleId), page: String(args.page ?? 0), size: String(args.size ?? 500) },
+            })).data;
+            const rows = Array.isArray(data?.content) ? data.content : wireRows(data);
+            const members = rows.map((row) => ({
+                id: roleUserId(row),
+                name: row.name ?? null,
+                username: row.username ?? null,
+                departmentId: row.departmentId ?? null,
+                unitType: row.unitType ?? null,
+            }));
+            return { roleId: String(args.roleId), count: members.length, total: data?.totalElements ?? members.length, members };
+        }),
+    }));
+    tools.push(defineTool({
+        name: "org.role.userScope",
+        layer: "low",
+        kind: "read",
+        lane: LANE,
+        scope: SCOPES.userScope,
+        description: "读成员的管理范围（`GET organization/role/get_ouscope`）。`type:\"1\"`=部门节点；update_ouscope 是覆盖语义，改前先读。",
+        inputSchema: {
+            environment: environmentArg,
+            roleId: z.string().min(1),
+            userId: z.string().min(1).describe("成员的用户记录 id（recId）"),
+            capability: capabilityArg,
+        },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const data = (await wireCall(session, {
+                path: ENDPOINTS.organizationRoleGetOuScope,
+                query: { ...orgQuery(session), roleId: String(args.roleId), userId: String(args.userId) },
+            })).data;
+            const scopes = wireRows(data).map((row) => ({ id: row.id ?? null, name: row.name ?? null, type: row.type ?? null, deptPath: row.deptPath ?? null }));
+            return { roleId: String(args.roleId), userId: String(args.userId), count: scopes.length, scopes };
+        }),
+    }));
+    writeTool(tools, "org.roleGroup.create", LANE, SCOPES.groupCreate, "创建角色组（`POST organization/role/add_role_group`）。返回 roleGroupId，角色挂在它下面。**corpId 默认写当前企业**（`session.enterpriseId()`）：平台的 `corpId` 只从 body 取，body 缺省时才按 parentId 反查企业设置，查不到就 NPE（被吞成 errcode 0）；`corpId=\"other\"` 是平台合法的「非组织分组」语义，只有明确要建非组织分组时才传。", {
+        roleGroupName: z.string().min(1).describe("角色组名称（界面显示的分组名）"),
+        parentId: z.string().min(1).describe("上级角色组 id。**必填**：1.1.25 的 add_role_group 会先 getByParentId(parentId)，空值直接 Preconditions 异常（50000 parentIds cannot be empty）；顶层组请传现有组 id（如「默认」组），平台允许嵌套"),
+        code: z.string().optional(),
+        corpId: z.string().min(1).optional().describe("组织 corpId，默认当前登录企业；传 \"other\" 表示非组织分组（该组在组织管理里不归属任何企业）"),
+    }, async (session, args) => {
+        const corpId = args.corpId ?? session.enterpriseId();
+        const data = (await wireCall(session, {
+            path: ENDPOINTS.organizationRoleAddGroup, method: "POST",
+            query: orgQuery(session),
+            body: { roleGroupName: args.roleGroupName, corpId, ...(args.parentId ? { parentId: args.parentId } : {}), ...(args.code ? { code: args.code } : {}) },
+        })).data;
+        const roleGroupId = String(data?.roleGroupId ?? data?.id ?? "");
+        if (!roleGroupId)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回 roleGroupId；不要假设创建成功，先 org.role.list 回读" });
+        const readbackCorpId = data?.corpId ?? null;
+        // The platform takes corpId from the body verbatim (RoleGroupHelper
+        // .createRoleGroupModel, 1.1.25): a silent rewrite means the value we sent
+        // did not land, and participants built from this group would not resolve
+        // in the org tree.
+        const corpIdHonoured = readbackCorpId === null || String(readbackCorpId) === corpId;
+        return {
+            performed: { errcode: 0 },
+            readback: {
+                roleGroupId,
+                roleGroupName: data?.roleGroupName ?? args.roleGroupName,
+                code: data?.code ?? null,
+                corpId: readbackCorpId,
+                ...(corpIdHonoured ? {} : { warning: `平台回读 corpId=${String(readbackCorpId)}，与请求的 ${corpId} 不一致；该组可能不归属当前企业，先 org.role.list 核对` }),
+            },
+        };
+    });
+    writeTool(tools, "org.role.create", LANE, SCOPES.roleCreate, "创建角色（界面「分组」；`POST organization/role/add_role`）。返回 roleId；code 创建时 null、随后补 SYS<时间戳>，要稳定编码就传 code。", {
+        roleName: z.string().min(1),
+        roleGroupId: z.string().min(1).describe("所属角色组 id（org.role.list 的 groups[].id）"),
+        roleGroupName: z.string().optional(),
+        roleType: z.enum(["SYS", "CUSTOMIZE", "OTHER"]).optional().describe("默认 SYS（平台会把角色统一落成 SYS，见 RoleHelper.createRoleModel）"),
+        code: z.string().optional(),
+        remarks: z.string().optional(),
+        corpId: z.string().min(1).optional().describe("组织 corpId，默认当前登录企业；传 \"other\" 表示非组织分组角色"),
+    }, async (session, args) => {
+        const corpId = args.corpId ?? session.enterpriseId();
+        const data = (await wireCall(session, {
+            path: ENDPOINTS.organizationRoleAdd, method: "POST",
+            query: orgQuery(session),
+            body: {
+                roleName: args.roleName,
+                roleGroupId: args.roleGroupId,
+                ...(args.roleGroupName ? { roleGroupName: args.roleGroupName } : {}),
+                roleType: args.roleType ?? "SYS",
+                corpId,
+                ...(args.code ? { code: args.code } : {}),
+                ...(args.remarks ? { remarks: args.remarks } : {}),
+            },
+        })).data;
+        const roleId = String(data?.roleId ?? data?.id ?? "");
+        if (!roleId)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回 roleId；先 org.role.list 回读确认" });
+        const readbackCorpId = data?.corpId ?? null;
+        return {
+            performed: { errcode: 0 },
+            readback: {
+                roleId,
+                roleName: data?.roleName ?? args.roleName,
+                code: data?.code ?? null,
+                corpId: readbackCorpId,
+                ...(readbackCorpId === null || String(readbackCorpId) === corpId ? {} : { warning: `平台回读 corpId=${String(readbackCorpId)}，与请求的 ${corpId} 不一致` }),
+            },
+        };
+    });
+    // ── department ────────────────────────────────────────────────────────────
+    writeTool(tools, "org.department.create", LANE, SCOPES.deptCreate, "新建部门（`POST organization/department/add`）。parentId 传上级部门 id（根部门可省）；deptType 传名字或 0..3（平台按 int 枚举反序列化，写 \"dept\" 会 10009）。返回 deptId。", {
+        name: z.string().min(1).describe("部门名称"),
+        parentId: z.string().min(1).optional().describe("上级部门 id（省略=建在根下）"),
+        deptType: z.union([z.string(), z.number().int()]).optional().describe("默认 0=部门；1=家校部门 2=云枢部门 3=虚拟家校部门"),
+        code: z.string().optional(),
+        managerId: z.string().optional().describe("部门主管的用户 id"),
+        sortKey: z.number().int().optional(),
+        remarks: z.string().optional(),
+    }, async (session, args) => {
+        const data = (await wireCall(session, {
+            path: ENDPOINTS.organizationDepartmentAdd, method: "POST", query: orgQuery(session),
+            body: {
+                name: args.name, corpId: session.enterpriseId(), unitType: "1", enabled: true, deptType: deptTypeCode(args.deptType),
+                ...(args.parentId ? { parentId: args.parentId } : {}),
+                ...(args.code ? { code: args.code } : {}),
+                ...(args.managerId ? { managerId: args.managerId } : {}),
+                ...(args.sortKey !== undefined ? { sortKey: args.sortKey } : {}),
+                ...(args.remarks ? { remarks: args.remarks } : {}),
+            },
+        })).data;
+        const deptId = String(data?.id ?? "");
+        if (!deptId)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回部门 id；先 org.department.list 回读确认" });
+        return { performed: { errcode: 0 }, readback: { deptId, name: data?.name ?? args.name, parentId: data?.parentId ?? args.parentId ?? null, code: data?.code ?? null } };
+    });
+    writeTool(tools, "org.department.update", LANE, SCOPES.deptUpdate, "改部门（`POST organization/department/modefied`）。先 get_dept_info 读现状再合并提交，只传要改的字段（名称/上级/主管/排序/备注/启用）。", {
+        deptId: z.string().min(1),
+        name: z.string().optional(),
+        parentId: z.string().optional(),
+        managerId: z.string().optional(),
+        sortKey: z.number().int().optional(),
+        remarks: z.string().optional(),
+        enabled: z.boolean().optional(),
+    }, async (session, args) => {
+        const current = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentGet, query: { ...orgQuery(session), deptId: args.deptId } })).data;
+        if (!current)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `get_dept_info 未返回部门 ${args.deptId}` });
+        const body = {
+            ...current,
+            ...(args.name !== undefined ? { name: args.name } : {}),
+            ...(args.parentId !== undefined ? { parentId: args.parentId } : {}),
+            ...(args.managerId !== undefined ? { managerId: args.managerId } : {}),
+            ...(args.sortKey !== undefined ? { sortKey: args.sortKey } : {}),
+            ...(args.remarks !== undefined ? { remarks: args.remarks } : {}),
+            ...(args.enabled !== undefined ? { enabled: args.enabled } : {}),
+        };
+        await wireCall(session, { path: ENDPOINTS.organizationDepartmentModify, method: "POST", query: orgQuery(session), body });
+        const after = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentGet, query: { ...orgQuery(session), deptId: args.deptId } })).data;
+        return { performed: { errcode: 0 }, readback: { deptId: args.deptId, name: after?.name ?? null, parentId: after?.parentId ?? null, managerId: after?.managerId ?? null, enabled: after?.enabled ?? null } };
+    });
+    writeTool(tools, "org.department.delete", LANE, SCOPES.deptDelete, "删除部门（`GET organization/department/strike_out?id=`）。平台会拒绝：有子部门 → 200009「部门下面存在子部门，不能删除！」；有用户 → 200002「部门下面存在用户，不能删除！」。工具先计数并在回读里给出，仍由平台裁决。", { deptId: z.string().min(1) }, async (session, args) => {
+        const users = wireRows((await wireCall(session, { path: ENDPOINTS.organizationDepartmentUsers, query: { ...orgQuery(session), deptId: args.deptId } })).data);
+        await wireCall(session, { path: ENDPOINTS.organizationDepartmentDelete, query: { ...orgQuery(session), id: args.deptId } });
+        return { performed: { errcode: 0 }, readback: { deptId: args.deptId, deleted: true, usersBeforeDelete: users.length } };
+    });
+    tools.push(defineTool({
+        name: "org.department.users",
+        layer: "low", kind: "read", lane: LANE, scope: SCOPES.deptUsers,
+        description: "列出部门下的员工（`GET organization/department/list_user?deptId=`）。返回 members[{id(recId),name,username,mobile}]。",
+        inputSchema: { environment: environmentArg, deptId: z.string().min(1), capability: capabilityArg },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const data = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentUsers, query: { ...orgQuery(session), deptId: String(args.deptId) } })).data;
+            const members = wireRows(data).map((row) => ({ id: row.id ?? row.userId ?? null, name: row.name ?? null, username: row.username ?? null, mobile: row.mobile ?? null }));
+            return { deptId: String(args.deptId), count: members.length, members };
+        }),
+    }));
+    // ── employee ──────────────────────────────────────────────────────────────
+    writeTool(tools, "org.user.create", LANE, SCOPES.userCreate, "新建员工账号（`POST organization/user/add`）。必填 name/username/departmentId；工具自动补 `userLabelIds:[]`、`userManagerConfigList:[]`、`roleIds:[]` —— 平台 dealUserLabel 对 null 直接 NPE（50000，真机 1.1.25）。返回 userId(recId)；初始密码由平台默认策略生成。", {
+        name: z.string().min(1),
+        username: z.string().min(1).describe("登录账号"),
+        departmentId: z.string().min(1).describe("所属部门 id（必须先存在，否则 201011「用户的部门不存在！」）"),
+        mobile: z.string().optional(),
+        email: z.string().optional(),
+        employeeNo: z.string().optional(),
+        gender: z.enum(["MALE", "FEMALE", "OTHER"]).optional(),
+        roleIds: z.array(z.string()).optional().describe("同时授予的角色 id"),
+        partTimeDeptIds: z.array(z.string()).optional().describe("兼职部门 id（主部门仍是 departmentId）"),
+        deptIds: z.array(z.string()).optional().describe("`partTimeDeptIds` 的别名"),
+        userLabelIds: z.array(z.string()).optional(),
+        active: z.boolean().optional(),
+        status: z.enum(["ENABLE", "DISABLE", "LOCK"]).optional(),
+    }, async (session, args) => {
+        const data = (await wireCall(session, {
+            path: ENDPOINTS.organizationUserAdd, method: "POST", query: orgQuery(session),
+            body: {
+                name: args.name, username: args.username, departmentId: args.departmentId, currentDeptId: args.departmentId,
+                corpId: session.enterpriseId(), unitType: "3", enabled: true, active: args.active ?? true,
+                status: args.status ?? "ENABLE",
+                userLabelIds: args.userLabelIds ?? [], userManagerConfigList: [], roleIds: args.roleIds ?? [], deptIds: args.partTimeDeptIds ?? args.deptIds ?? [],
+                ...(args.mobile ? { mobile: args.mobile } : {}),
+                ...(args.email ? { email: args.email } : {}),
+                ...(args.employeeNo ? { employeeNo: args.employeeNo } : {}),
+                ...(args.gender ? { gender: args.gender } : {}),
+            },
+        })).data;
+        const userId = String(data?.id ?? "");
+        if (!userId)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回用户 id；先 org.user.search 回读确认" });
+        return { performed: { errcode: 0 }, readback: { userId, name: data?.name ?? args.name, username: data?.username ?? args.username, departmentId: data?.departmentId ?? args.departmentId } };
+    });
+    writeTool(tools, "org.user.update", LANE, SCOPES.userUpdate, "改员工（`POST organization/user/modify`）。先 user/info 读现状再合并；工具强制补 `deptIds:[]` 等四个数组——平台 modified 对 null 的 deptIds 直接 NPE（50000，真机 1.1.25）。可改姓名/部门/手机/邮箱/角色/启停。", {
+        userId: z.string().min(1),
+        name: z.string().optional(),
+        departmentId: z.string().optional(),
+        mobile: z.string().optional(),
+        email: z.string().optional(),
+        employeeNo: z.string().optional(),
+        gender: z.enum(["MALE", "FEMALE", "OTHER"]).optional(),
+        roleIds: z.array(z.string()).optional(),
+        partTimeDeptIds: z.array(z.string()).optional().describe("兼职部门 id；**覆盖语义**（传 [] 清空兼职，主部门不变）"),
+        active: z.boolean().optional(),
+        status: z.enum(["ENABLE", "DISABLE", "LOCK"]).optional(),
+    }, async (session, args) => {
+        const current = (await wireCall(session, { path: ENDPOINTS.organizationUserInfo, query: { ...orgQuery(session), id: args.userId } })).data;
+        if (!current)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `user/info 未返回用户 ${args.userId}` });
+        const body = {
+            ...current,
+            id: args.userId,
+            ...(args.name !== undefined ? { name: args.name } : {}),
+            ...(args.departmentId !== undefined ? { departmentId: args.departmentId, currentDeptId: args.departmentId } : {}),
+            ...(args.mobile !== undefined ? { mobile: args.mobile } : {}),
+            ...(args.email !== undefined ? { email: args.email } : {}),
+            ...(args.employeeNo !== undefined ? { employeeNo: args.employeeNo } : {}),
+            ...(args.gender !== undefined ? { gender: args.gender } : {}),
+            ...(args.active !== undefined ? { active: args.active } : {}),
+            ...(args.status !== undefined ? { status: args.status } : {}),
+            deptIds: args.partTimeDeptIds ?? (Array.isArray(current.deptIds) ? current.deptIds : []),
+            userLabelIds: Array.isArray(current.userLabelIds) ? current.userLabelIds : [],
+            userManagerConfigList: Array.isArray(current.userManagerConfigList) ? current.userManagerConfigList : [],
+            roleIds: args.roleIds ?? (Array.isArray(current.roleIds) ? current.roleIds : []),
+        };
+        await wireCall(session, { path: ENDPOINTS.organizationUserModify, method: "POST", query: orgQuery(session), body });
+        const after = (await wireCall(session, { path: ENDPOINTS.organizationUserInfo, query: { ...orgQuery(session), id: args.userId } })).data;
+        const departments = wireRows((await wireCall(session, {
+            path: ENDPOINTS.organizationUserDepartments, query: { ...orgQuery(session), id: String(args.userId) },
+        })).data).map((row) => ({ deptId: row.deptId ?? null, deptName: row.deptName ?? null, isMain: row.isMain ?? null }));
+        return { performed: { errcode: 0 }, readback: { userId: args.userId, name: after?.name ?? null, departmentId: after?.departmentId ?? null, mobile: after?.mobile ?? null, email: after?.email ?? null, active: after?.active ?? null, userStatus: after?.status ?? null, departments } };
+    });
+    writeTool(tools, "org.user.delete", LANE, SCOPES.userDelete, "删除员工（`GET organization/user/strike_out?id=`）。只传用户 id；返回 deleted。", { userId: z.string().min(1) }, async (session, args) => {
+        await wireCall(session, { path: ENDPOINTS.organizationUserDelete, query: { ...orgQuery(session), id: args.userId } });
+        return { performed: { errcode: 0 }, readback: { userId: args.userId, deleted: true } };
+    });
+    tools.push(defineTool({
+        name: "org.user.info",
+        layer: "low", kind: "read", lane: LANE, scope: SCOPES.userInfo,
+        description: "读员工详情（`GET organization/user/info?id=`）。返回姓名/账号/部门/手机/邮箱/状态/角色 id 等。",
+        inputSchema: { environment: environmentArg, userId: z.string().min(1), capability: capabilityArg },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            let data = null;
+            try {
+                data = (await wireCall(session, { path: ENDPOINTS.organizationUserInfo, query: { ...orgQuery(session), id: String(args.userId) } })).data;
+            }
+            catch (error) {
+                // A deleted/unknown user answers 10011 (业务模型不存在-style business
+                // error) rather than an empty body; "read a user" should not turn an
+                // absence into a refusal.
+                if (!(error instanceof WireError) || error.errcode !== 10011)
+                    throw error;
+            }
+            if (!data)
+                return { userId: String(args.userId), exists: false };
+            return {
+                userId: String(args.userId), exists: true,
+                name: data.name ?? null, username: data.username ?? null, departmentId: data.departmentId ?? null,
+                mobile: data.mobile ?? null, email: data.email ?? null, active: data.active ?? null,
+                // `status` is reserved by the tool envelope (ok/refused/…): a user's
+                // ENABLE/DISABLE value under that key made the read look like a failed
+                // tool call (live 2026-10-22).
+                userStatus: data.status ?? null,
+                roleIds: Array.isArray(data.roleIds) ? data.roleIds : [],
+            };
+        }),
+    }));
+    tools.push(defineTool({
+        name: "org.user.departments",
+        layer: "low", kind: "read", lane: LANE, scope: SCOPES.userDepartments,
+        description: "读员工所属部门（含兼职，`GET organization/user/departments?id=`）。返回 departments[{deptId,deptName,isMain}]。",
+        inputSchema: { environment: environmentArg, userId: z.string().min(1), capability: capabilityArg },
+        handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
+            const data = (await wireCall(session, { path: ENDPOINTS.organizationUserDepartments, query: { ...orgQuery(session), id: String(args.userId) } })).data;
+            const departments = wireRows(data).map((row) => ({ deptId: row.deptId ?? null, deptName: row.deptName ?? null, isMain: row.isMain ?? null }));
+            return { userId: String(args.userId), count: departments.length, departments };
+        }),
+    }));
+    writeTool(tools, "org.role.delete", LANE, SCOPES.roleDelete, "删除角色（`GET organization/role/strike_out_role?ids=`）。平台**拒绝删除仍有成员的角色**（`-1 角色下已经包含用户数据！`，实测 1.1.25）：默认先读成员数、非空即拒绝并给出人数；`force:true` 才会先逐人移出再删。", {
+        roleId: z.string().min(1),
+        force: z.boolean().optional().describe("true = 先移出全部成员再删角色"),
+    }, async (session, args) => {
+        const rows = await memberRows(session, String(args.roleId));
+        if (rows.length > 0 && args.force !== true)
+            throw new ToolRefusalError({
+                status: "refused", blocker: "role-has-members", roleId: String(args.roleId), members: rows.length,
+                message: `角色下还有 ${rows.length} 名成员，平台拒绝删除（errmsg：角色下已经包含用户数据）。先 org.role.removeUsers，或传 force:true 让工具移出后再删。`,
+            });
+        if (rows.length > 0)
+            await removeMembers(session, String(args.roleId), rows.map(roleUserId));
+        await wireCall(session, { path: ENDPOINTS.organizationRoleDelete, query: { ...orgQuery(session), ids: String(args.roleId) } });
+        return { performed: { errcode: 0 }, readback: { roleId: String(args.roleId), deleted: true, removedMembers: rows.length } };
+    });
+    writeTool(tools, "org.roleGroup.delete", LANE, SCOPES.roleGroupDelete, "删除角色组（`GET organization/role/strike_out_role_group?ids=`）。平台**拒绝删除仍含角色的组**（`-1 角色组下已经包含角色数据！`）：默认先数角色、非空即拒绝；`force:true` 会逐个删角色（含其成员）再删组。", {
+        roleGroupId: z.string().min(1),
+        force: z.boolean().optional(),
+    }, async (session, args) => {
+        const roles = await rolesInGroup(session, String(args.roleGroupId));
+        if (roles.length > 0 && args.force !== true)
+            throw new ToolRefusalError({
+                status: "refused", blocker: "role-group-has-roles", roleGroupId: String(args.roleGroupId), roles: roles.length,
+                message: `角色组下还有 ${roles.length} 个角色，平台拒绝删除（errmsg：角色组下已经包含角色数据）。先删角色，或传 force:true。`,
+            });
+        for (const role of roles) {
+            const members = await memberRows(session, role.id);
+            if (members.length > 0)
+                await removeMembers(session, role.id, members.map(roleUserId));
+            await wireCall(session, { path: ENDPOINTS.organizationRoleDelete, query: { ...orgQuery(session), ids: role.id } });
+        }
+        await wireCall(session, { path: ENDPOINTS.organizationRoleGroupDelete, query: { ...orgQuery(session), ids: String(args.roleGroupId) } });
+        return { performed: { errcode: 0 }, readback: { roleGroupId: String(args.roleGroupId), deleted: true, removedRoles: roles.map((role) => role.id) } };
+    });
+    writeTool(tools, "org.user.transferDepartment", LANE, SCOPES.userTransfer, "把员工从一个部门移到另一个部门（`POST organization/user/dept_transfer`，body `{userIds,sourceDept,targetDept}`）。sourceDept 必填（缺它 50000）；移动后原部门不再包含该员工，主部门保持。", {
+        userId: z.string().min(1),
+        fromDeptId: z.string().min(1).describe("原部门 id（必填）"),
+        toDeptId: z.string().min(1).describe("目标部门 id"),
+    }, async (session, args) => {
+        await wireCall(session, {
+            path: ENDPOINTS.organizationUserDeptTransfer, method: "POST", query: orgQuery(session),
+            body: { userIds: [String(args.userId)], sourceDept: String(args.fromDeptId), targetDept: String(args.toDeptId) },
+        });
+        const departments = wireRows((await wireCall(session, {
+            path: ENDPOINTS.organizationUserDepartments, query: { ...orgQuery(session), id: String(args.userId) },
+        })).data).map((row) => ({ deptId: row.deptId ?? null, deptName: row.deptName ?? null, isMain: row.isMain ?? null }));
+        return { performed: { errcode: 0 }, readback: { userId: String(args.userId), fromDeptId: String(args.fromDeptId), toDeptId: String(args.toDeptId), departments } };
+    });
+    writeTool(tools, "org.role.update", LANE, SCOPES.roleUpdate, "改角色名称/编码/备注/所属角色组（`POST organization/role/modify_role`）。先读现状再提交，只传要改的字段。**平台要求 roleGroupId 必填**（缺则 202012「角色组主键Id不能为空」），工具默认回填当前组；**corpId 不可改**（RoleHelper.update 不读该字段），要换企业只能在目标企业下重建角色。", {
+        roleId: z.string().min(1),
+        roleName: z.string().optional(),
+        roleGroupId: z.string().min(1).optional().describe("移到别的角色组（默认保持当前组）。平台 update 必填该字段，且目标组必须存在、roleType=SYS"),
+        code: z.string().optional(),
+        remarks: z.string().optional(),
+    }, async (session, args) => {
+        const current = (await wireCall(session, { path: ENDPOINTS.organizationRoleGet, query: { ...orgQuery(session), roleId: String(args.roleId) } })).data;
+        if (!current)
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `role/get 未返回角色 ${String(args.roleId)}；不要盲目 modify` });
+        // RoleHelper.update (1.1.25) validates roleName AND roleGroupId as
+        // REQUIRED before touching the row (validateRoleParam): a delta that omits
+        // either answers 202001 「角色名称不能为空」 / 202012 「角色组主键Id不能为空」.
+        // Both are backfilled from role/get, so a remarks-only edit works.
+        const roleName = String(args.roleName ?? current.roleName ?? current.name ?? "");
+        if (roleName === "")
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `角色 ${String(args.roleId)} 读不到 roleName；平台 modify_role 要求该字段，请显式传 roleName` });
+        const roleGroupId = String(args.roleGroupId ?? current.roleGroupId ?? current.groupId ?? "");
+        if (roleGroupId === "")
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: `角色 ${String(args.roleId)} 读不到 roleGroupId；平台 modify_role 要求该字段，请显式传 roleGroupId` });
+        const body = {
+            ...current,
+            roleId: String(args.roleId),
+            roleName,
+            roleGroupId,
+            ...(args.code !== undefined ? { code: args.code } : {}),
+            ...(args.remarks !== undefined ? { remarks: args.remarks } : {}),
+            corpId: current.corpId ?? "other",
+            roleType: current.roleType ?? "SYS",
+        };
+        await wireCall(session, { path: ENDPOINTS.organizationRoleModify, method: "POST", query: orgQuery(session), body });
+        const after = (await wireCall(session, { path: ENDPOINTS.organizationRoleGet, query: { ...orgQuery(session), roleId: String(args.roleId) } })).data;
+        // role/get answers RoleModel (name/groupId), not RoleVO (roleName/
+        // roleGroupId) — read both spellings so the readback is never null.
+        return {
+            performed: { errcode: 0 },
+            readback: {
+                roleId: String(args.roleId),
+                roleName: after?.roleName ?? after?.name ?? null,
+                roleGroupId: after?.roleGroupId ?? after?.groupId ?? null,
+                code: after?.code ?? null,
+                remarks: after?.remarks ?? null,
+            },
+        };
+    });
+    writeTool(tools, "org.role.addUsers", LANE, SCOPES.addUsers, "加成员并（可选）一次设好管理范围（`add_role_user` + 逐人 `update_ouscope`，一个工具调用）。users[].id 必须是 recId（org.user.search 的 id）；传 `scopes` 会应用到本次新增的每个人。**平台的 add_role_user 虽然收 `ouScope` 但会忽略它**（实测 1.1.25，回读仍为空），所以范围必须单独写——工具内部已按顺序完成。加完回读成员与范围。", {
+        roleId: z.string().min(1),
+        users: z.array(z.object({ id: z.string().min(1).describe("用户记录 id（recId）"), name: z.string().min(1) })).min(1),
+        scopes: z.array(z.object({
+            id: z.string().min(1).describe("部门 id"),
+            name: z.string().min(1),
+            deptPath: z.string().optional(),
+            type: z.string().optional().describe("默认 \"1\"（部门节点）"),
+        })).optional().describe("应用到本次新增的每个成员的管​理范围；省略则不设（成员 ouScope 为空）"),
+        sortKey: z.number().int().optional(),
+        userIds: z.array(z.object({ id: z.string().min(1), name: z.string().min(1) })).optional().describe("`users` 的别名"),
+    }, async (session, args) => {
+        const users = args.users ?? args.userIds ?? [];
+        if (users.length === 0)
+            throw new ToolInputError({ status: "error", blocker: "tool-input-invalid", tool: "org.role.addUsers", message: "需要 users（或 userIds）至少一人" });
+        await wireCall(session, {
+            path: ENDPOINTS.organizationRoleAddUser, method: "POST",
+            query: orgQuery(session),
+            body: { roleId: args.roleId, sortKey: args.sortKey ?? 999, userIds: users.map((user) => ({ id: user.id, name: user.name, type: 3, unitType: "3" })) },
+        });
+        const readback = async () => {
+            const data = (await wireCall(session, {
+                path: ENDPOINTS.organizationRoleUsers,
+                query: { ...orgQuery(session), roleId: String(args.roleId), page: "0", size: "500" },
+            })).data;
+            return Array.isArray(data?.content) ? data.content : wireRows(data);
+        };
+        const rows = await readback();
+        const present = new Set(rows.map(roleUserId));
+        const added = users.filter((user) => present.has(user.id)).map((user) => user.id);
+        const missing = users.filter((user) => !present.has(user.id)).map((user) => user.id);
+        const scopeResults = [];
+        if (args.scopes !== undefined && args.scopes.length > 0) {
+            const ouScopeList = args.scopes.map((scope) => ({ id: scope.id, name: scope.name, type: scope.type ?? "1", ...(scope.deptPath ? { deptPath: scope.deptPath } : {}) }));
+            for (const id of added) {
+                await wireCall(session, {
+                    path: ENDPOINTS.organizationRoleUpdateOuScope, method: "POST", query: orgQuery(session),
+                    body: { roleId: String(args.roleId), userId: id, unitType: 3, sortKey: args.sortKey ?? 999, ouScopeList },
+                });
+                const scope = wireRows((await wireCall(session, {
+                    path: ENDPOINTS.organizationRoleGetOuScope,
+                    query: { ...orgQuery(session), roleId: String(args.roleId), userId: id },
+                })).data);
+                scopeResults.push({ userId: id, scopes: scope.length });
+            }
+        }
+        return {
+            performed: { errcode: 0 },
+            readback: {
+                roleId: String(args.roleId), added,
+                ...(missing.length > 0 ? { missing, hint: "这些 recId 未出现在成员列表：确认 id 是 recId、用户未离职/禁用" } : {}),
+                ...(scopeResults.length > 0 ? { scopeResults } : {}),
+                total: rows.length,
+            },
+        };
+    });
+    writeTool(tools, "org.role.removeUsers", LANE, SCOPES.removeUsers, "把成员移出角色（`POST organization/role/strike_out_role_user`）。**平台要求 JSON body `{roleId,userIds:[...]}`**——用 query 或 `ids` 会报 10009 `Required request body is missing`（实测 1.1.25）。只移出角色，不删用户。", {
+        roleId: z.string().min(1),
+        ids: z.array(z.string().min(1)).min(1).describe("要移出的成员 recId 列表"),
+    }, async (session, args) => {
+        await wireCall(session, {
+            path: ENDPOINTS.organizationRoleRemoveUser, method: "POST", query: orgQuery(session),
+            body: { roleId: String(args.roleId), userIds: args.ids },
+        });
+        const data = (await wireCall(session, {
+            path: ENDPOINTS.organizationRoleUsers,
+            query: { ...orgQuery(session), roleId: String(args.roleId), page: "0", size: "500" },
+        })).data;
+        const rows = Array.isArray(data?.content) ? data.content : wireRows(data);
+        const present = new Set(rows.map(roleUserId));
+        return { performed: { errcode: 0 }, readback: { roleId: String(args.roleId), removed: args.ids.filter((id) => !present.has(id)), stillPresent: args.ids.filter((id) => present.has(id)), total: data?.totalElements ?? rows.length } };
+    });
+    writeTool(tools, "org.role.setUserScope", LANE, SCOPES.setScope, "设置成员管理范围（`POST organization/role/update_ouscope`）。平台覆盖语义、无回滚：默认读旧值合并（mode:\"merge\"），mode:\"replace\" 才整体替换。unitType 传数字 3（addUsers 里是字符串 \"3\"）。节点 {id,name,type:\"1\",deptPath}。", {
+        roleId: z.string().min(1),
+        userId: z.string().min(1).describe("成员 recId"),
+        scopes: z.array(z.object({
+            id: z.string().min(1).describe("部门 id"),
+            name: z.string().min(1),
+            deptPath: z.string().optional().describe("完整路径，如 根组织/广州总所"),
+            type: z.string().optional().describe("默认 \"1\"（部门节点）"),
+        })).describe("要设置的管理范围节点"),
+        mode: z.enum(["merge", "replace"]).optional().describe("默认 merge（读旧值合并）；replace = 覆盖整个范围"),
+        dryRun: z.boolean().optional(),
+    }, async (session, args) => {
+        const before = wireRows((await wireCall(session, {
+            path: ENDPOINTS.organizationRoleGetOuScope,
+            query: { ...orgQuery(session), roleId: args.roleId, userId: args.userId },
+        })).data);
+        const wanted = args.scopes.map((scope) => ({ id: scope.id, name: scope.name, type: scope.type ?? "1", ...(scope.deptPath ? { deptPath: scope.deptPath } : {}) }));
+        const merged = args.mode === "replace"
+            ? wanted
+            : [...before.map((row) => ({ id: String(row.id ?? ""), name: String(row.name ?? ""), type: String(row.type ?? "1"), ...(row.deptPath ? { deptPath: String(row.deptPath) } : {}) })).filter((row) => row.id !== ""), ...wanted]
+                .filter((row, index, all) => all.findIndex((candidate) => candidate.id === row.id) === index);
+        const removed = before.map((row) => String(row.id ?? "")).filter((id) => id !== "" && !merged.some((row) => row.id === id));
+        if (args.mode === "replace" && removed.length > 0)
+            // A data-loss write without an explicit acknowledgement is exactly the
+            // failure mode the customer hit manually; refuse unless replace was
+            // chosen deliberately (mode): the caller already opted in.
+            void removed;
+        await wireCall(session, {
+            path: ENDPOINTS.organizationRoleUpdateOuScope, method: "POST",
+            query: orgQuery(session),
+            body: { roleId: args.roleId, userId: args.userId, unitType: 3, sortKey: 999, ouScopeList: merged },
+        });
+        const after = wireRows((await wireCall(session, {
+            path: ENDPOINTS.organizationRoleGetOuScope,
+            query: { ...orgQuery(session), roleId: args.roleId, userId: args.userId },
+        })).data).map((row) => ({ id: row.id ?? null, name: row.name ?? null, type: row.type ?? null, deptPath: row.deptPath ?? null }));
+        return {
+            performed: { errcode: 0 },
+            readback: { roleId: args.roleId, userId: args.userId, mode: args.mode ?? "merge", before: before.length, after: after.length, scopes: after, ...(removed.length > 0 ? { removedScopeIds: removed } : {}) },
+        };
+    });
+}
+//# sourceMappingURL=organization.js.map

package/dist/lanes/rule-graph.js

@@ -1805,6 +1805,43 @@ export function validateRuleNodeGraph(graph, ruleCode, schemaCode, options = {})
                 walkConditionLeaves(node.targetConditionGroups, (leaf, where) => blockers.push(...validateConditionLeaf(leaf, nodeCode, where, warnings, (relaxEnums || carried?.has(String(node.nodeCode ?? "")) === true))));
                 scanConditionKeyCollisions(node.targetConditionGroups, nodeCode, warnings);
             }
+            // QUERY has THREE silent-empty exits in the engine (1.1.25 source, r9
+            // §14.1): `QueryActivityBehavior:47-50` returns null when the resolved
+            // inputs are empty, `:78-86` returns emptyList when getMainConditions()
+            // is null/empty, and `ActivityBizObjectManagerImpl:172-178` returns
+            // emptyList on a zero-hit page. NONE of them logs anything, so "executed,
+            // matched nothing" is indistinguishable from "executed, worked" — r9 lost
+            // ~1/4 of its call budget to this. The two shapes that reliably land in
+            // the first two exits are visible here before the wire:
+            const groups = node.targetConditionGroups;
+            const targetIsChild = typeof node.targetSchemaCode === "string" && node.targetSchemaCode.includes(".");
+            const mainEmpty = groups === undefined || countConditionLeaves(groups.mainConditions ?? groups) === 0;
+            const sheetEmpty = countConditionLeaves(groups?.sheetConditions ?? []) === 0;
+            // Mirrors QueryActivityBehavior.getPage exactly: an empty MAIN group
+            // returns emptyList unconditionally; the sheet group is only consulted
+            // when the target is a child table.
+            if (mainEmpty || (targetIsChild && sheetEmpty)) {
+                // A QUERY with no conditions at all is the "return emptyList" path, not
+                // "select everything" — the opposite of UPDATE's semantics. Fail closed:
+                // a caller who really wants every row must say so with an always-true
+                // leaf, which is visible in the graph.
+                blockers.push({
+                    code: "rule-graph-query-conditions-empty",
+                    nodeCode,
+                    key: "targetConditionGroups",
+                    message: `QUERY 的 ${mainEmpty ? "mainConditions" : "sheetConditions"} 没有任何条件叶——引擎 getPage 会直接返回空列表且不写日志（QueryActivityBehavior:78-86，1.1.25），运行期表现为「节点执行开始」后静默无输出。要查全表请显式写一条恒真条件叶（如 targetSchemaDataItem:"id" + ruleConditionType:"NOT_EMPTY"），否则补上真正的筛选条件。`,
+                });
+            }
+            if (node.dataCondition !== undefined && node.dataCondition !== null && countConditionLeaves(node.dataCondition) === 0) {
+                blockers.push({
+                    code: "rule-graph-query-datacondition-empty",
+                    nodeCode,
+                    key: "dataCondition",
+                    severity: "warning",
+                    hazard: true,
+                    message: "QUERY 的 dataCondition 是空条件组——输入数据经 DefaultConditionGroupBizObjectCompare 过滤后为空，QueryActivityBehavior:47-50 直接 return null（静默无输出，1.1.25）。要么去掉 dataCondition，要么写至少一条条件叶。",
+                });
+            }
         }
         if (nodeType === "BRANCH") {
             // Source evidence: RuleBranchQuoteImpl.getCurrentBizSchema throws

package/dist/lanes/rule-lifecycle.js

@@ -7,6 +7,7 @@ import { executeRuleSaveWrite, ruleNodeGraphArg, assertRuleSchemaExists, explain
 import { ToolRefusalError } from "../tool-types.js";
 import { prepareRuleGraph, validateRuleNodeGraph, PLATFORM_TRIGGER_RULE_CODES } from "./rule-graph.js";
 import { wireCall, wireRows, WireError } from "../wire.js";
+import { currentUsageArgsDigest, priorIdenticalSuccess } from "../usage-log.js";
 import { RULE_ENABLE_CHAIN, RULE_LIFECYCLE_LANE_CONTRACT } from "./rule-lifecycle-contract.js";
 const RULE_LIFECYCLE_LANE = RULE_LIFECYCLE_LANE_CONTRACT.lane;
 const RULE_LIFECYCLE_TOOLS = RULE_LIFECYCLE_LANE_CONTRACT.tools;
@@ -52,6 +53,25 @@ export async function executeRuleEnableWrite(session, args) {
     const full = (await wireCall(session, { path: ENDPOINTS.businessRuleGet, query: { id: String(row.id) } })).data;
     if (!full)
         throw new WireError("business", `rule ${args.ruleCode} 完整模型读回为空（businessrule/get id ${row.id}），拒绝用列表投影发布`, 302024);
+    // Idempotency (r9 2026-10-22): identical `rule.enable` calls answered
+    // `alreadyEnabled:true` 14 times and each one still minted a new rule version
+    // row. The session log is the only durable memory a CLI has, so the memo is
+    // there: same (schemaCode, ruleCode) already enabled successfully, with no
+    // `rule.save` in between ⇒ nothing to do. Any save invalidates it.
+    const digest = currentUsageArgsDigest();
+    if (digest) {
+        const prior = priorIdenticalSuccess("call rule.enable", digest, { invalidators: ["call rule.save", "call rule.node.update"], keyFields: ["schemaCode", "ruleCode"] });
+        if (prior && prior.count > 0) {
+            return {
+                performed: { errcode: 0, alreadyEnabled: true, noop: true },
+                readback: {
+                    enabled: true,
+                    ...(prior.requestIds.length > 0 ? { priorRequestIds: prior.requestIds } : {}),
+                    nextAction: "本会话已用相同参数成功 enable 过该规则，且此后没有 rule.save；本次未发任何 wire 请求（重复 enable 只会多铸一个规则版本）。改了图就先 rule.save，再按需 rule.enable",
+                },
+            };
+        }
+    }
     let published;
     try {
         published = await wireCall(session, { path: ENDPOINTS.businessRulePublish, method: "POST", body: { ...full, enabled: true, status: "ENABLED" } });

package/dist/lanes/workflow-contract.js

@@ -148,7 +148,7 @@ export const WORKFLOW_LANE_CONTRACT = Object.freeze({
         }),
         "org.department.list": Object.freeze({
             scope: "workflow participant resolution",
-            description: "列出组织结构（`GET /api/api/organization/department/tree`），扁平化为 {id,name,code,corpId,parentId}。用于需要按部门解析审批人（配合 `FindUserByRole({Originator.OU},\"<roleCode>\",\"random\")` 或部门引用）时取得真实 code/id。",
+            description: "列出组织结构（`GET /api/api/organization/department/tree`），扁平化为 {id,name,code,corpId,parentId}。**平台语义：不带 deptIds 只返回根部门；带 deptIds=<id> 返回该部门整棵子树（不是一层）**——工具先取根再逐个取子树，支持多层；可选 parentId 只看子树。用于需要按部门解析审批人（配合 `FindUserByRole({Originator.OU},\"<roleCode>\",\"random\")` 或部门引用）时取得真实 code/id。",
         }),
         "org.user.search": Object.freeze({
             scope: "workflow participant resolution",

package/dist/lanes/workflow-coverage.js

@@ -18,6 +18,27 @@ export const WORKFLOW_COVERAGE = declareLaneCoverage(WORKFLOW_LANE_CONTRACT.lane
             claim("workflow.delete", T["workflow.delete"].scope),
             claim("configure_workflow", T["configure_workflow"].scope),
             claim("workflow.validate", T["workflow.validate"].scope),
+            // Organization writes (role group / role / members / management scope).
+            claim("org.role.users", "organization role member read (role/users)"),
+            claim("org.role.userScope", "organization role member management scope read (role/get_ouscope)"),
+            claim("org.roleGroup.create", "organization role group create (role/add_role_group)"),
+            claim("org.role.create", "organization role create (role/add_role)"),
+            claim("org.role.update", "organization role update (role/modify_role)"),
+            claim("org.role.addUsers", "organization role member add (role/add_role_user)"),
+            claim("org.role.removeUsers", "organization role member remove (role/strike_out_role_user)"),
+            claim("org.role.setUserScope", "organization role member scope update (role/update_ouscope)"),
+            claim("org.role.delete", "organization role delete (role/strike_out_role)"),
+            claim("org.roleGroup.delete", "organization role group delete (role/strike_out_role_group)"),
+            claim("org.user.transferDepartment", "organization user department transfer (user/dept_transfer)"),
+            claim("org.department.create", "organization department create (department/add)"),
+            claim("org.department.update", "organization department update (department/modefied)"),
+            claim("org.department.delete", "organization department delete (department/strike_out)"),
+            claim("org.department.users", "organization department member read (department/list_user)"),
+            claim("org.user.create", "organization user create (user/add)"),
+            claim("org.user.update", "organization user update (user/modify)"),
+            claim("org.user.delete", "organization user delete (user/strike_out)"),
+            claim("org.user.info", "organization user read (user/info)"),
+            claim("org.user.departments", "organization user department read (user/departments)"),
         ],
     },
     {

package/dist/lanes/workflow.js

@@ -2313,9 +2313,18 @@ export function registerWorkflowLane(tools) {
         lane: WORKFLOW_LANE,
         scope: WORKFLOW_TOOLS["org.role.list"].scope,
         description: WORKFLOW_TOOLS["org.role.list"].description,
-        inputSchema: { environment: environmentArg, capability: capabilityArg },
+        inputSchema: { environment: environmentArg, expandAll: z.boolean().optional().describe("默认 true：展开所有角色组并带回角色。平台的 /role/list 只有 expandAll=true 才填 children（RoleController.list，1.1.25）；传 false 只回角色组、roles 恒为空，别据此判断「角色未创建」"), capability: capabilityArg },
         handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
-            const data = (await wireCall(session, { path: ENDPOINTS.organizationRoleList })).data;
+            // `/role/list` without `expandAll=true` only expands the FIRST group's
+            // children (RoleController.list, 1.1.25), so a role created under any
+            // other group is invisible — r9 read that as "role not created" and
+            // burned 8 org.role.list calls. Always expand; expose the flag only so
+            // a caller can ask for the container-only face deliberately.
+            const expandAll = args.expandAll ?? true;
+            const data = (await wireCall(session, {
+                path: ENDPOINTS.organizationRoleList,
+                query: expandAll ? { expandAll: "true" } : {},
+            })).data;
             return flattenRoleTree(wireRows(data));
         }),
     }));
@@ -2326,11 +2335,51 @@ export function registerWorkflowLane(tools) {
         lane: WORKFLOW_LANE,
         scope: WORKFLOW_TOOLS["org.department.list"].scope,
         description: WORKFLOW_TOOLS["org.department.list"].description,
-        inputSchema: { environment: environmentArg, capability: capabilityArg },
+        inputSchema: { environment: environmentArg, parentId: z.string().min(1).optional().describe("只列出该部门下的子树（默认从根递归展开整棵部门树）"), capability: capabilityArg },
         handler: async (ctx, args, self) => governedRead(ctx, self, args, async (session) => {
-            const data = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentTree })).data;
-            const list = Array.isArray(data?.departmentList) ? data.departmentList : wireRows(data);
-            const departments = list.map((dept) => ({
+            // `/department/tree` semantics (live 2026-10-22, 1.1.25): no `deptIds`
+            // → the ROOTS; with `deptIds=<id>` → that department's WHOLE SUBTREE
+            // (not one level). So: roots once, then one subtree call per root.
+            const requested = args.parentId;
+            const fetchLevel = async (deptId) => {
+                const query = deptId === undefined ? {} : { deptIds: deptId };
+                const data = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentTree, query })).data;
+                return Array.isArray(data?.departmentList) ? data.departmentList : wireRows(data);
+            };
+            const levels = [];
+            const seen = new Set();
+            const push = (rows) => {
+                for (const row of rows) {
+                    const id = String(row.id ?? "");
+                    if (id === "" || seen.has(id))
+                        continue;
+                    seen.add(id);
+                    levels.push(row);
+                }
+            };
+            if (requested === undefined) {
+                push(await fetchLevel(undefined));
+            }
+            else {
+                // `deptIds=<id>` returns the subtree BELOW that department, excluding
+                // it (live 2026-10-22). A caller asking for `parentId` expects that
+                // department itself too, so add it from the authoritative record.
+                try {
+                    const self = (await wireCall(session, { path: ENDPOINTS.organizationDepartmentGet, query: { deptId: requested } })).data;
+                    if (self)
+                        push([self]);
+                }
+                catch {
+                    // an unknown id simply yields an empty list
+                }
+                push(await fetchLevel(requested));
+            }
+            for (const root of levels.filter((row) => String(row.parentId ?? "") === "" || requested !== undefined).map((row) => String(row.id ?? ""))) {
+                if (seen.size >= 500)
+                    break;
+                push(await fetchLevel(root));
+            }
+            const departments = levels.map((dept) => ({
                 id: dept.id ?? null,
                 name: dept.name ?? null,
                 code: dept.code ?? null,

package/dist/tools.js

@@ -12,6 +12,7 @@ import { registerBusinessRuleLane } from "./lanes/businessrule.js";
 import { registerRuleLifecycleLane } from "./lanes/rule-lifecycle.js";
 import { registerRuntimeDataLane } from "./lanes/runtime-data.js";
 import { registerWorkflowLane } from "./lanes/workflow.js";
+import { registerOrganizationLane } from "./lanes/organization.js";
 import { registerOnlineJsLane } from "./lanes/online-js.js";
 import { registerB2Lane } from "./lanes/b2-registration.js";
 import { registerListViewLane } from "./lanes/list-view.js";
@@ -41,6 +42,7 @@ export function buildToolRegistry() {
     registerRuleLifecycleLane(tools);
     registerRuntimeDataLane(tools);
     registerWorkflowLane(tools);
+    registerOrganizationLane(tools);
     registerOnlineJsLane(tools);
     registerB2Lane(tools);
     registerListViewLane(tools);

package/dist/usage-log.js

@@ -2,6 +2,14 @@ import { appendFileSync, existsSync, mkdirSync, openSync, readFileSync, readSync
 import { createHash } from "node:crypto";
 import { dirname, resolve } from "node:path";
 let pending;
+/**
+ * The project session marker: a working directory that opted into the usage log
+ * (`.omc-env` present) or an explicit OMC_USAGE_LOG. Session-scoped caches key
+ * off this so repo tests and the golden master (no `.omc-env`) stay stable.
+ */
+export function projectSessionActive() {
+    return logPath() !== undefined;
+}
 function logPath() {
     const explicit = process.env.OMC_USAGE_LOG;
     if (explicit)
@@ -9,6 +17,60 @@ function logPath() {
     const projectEnv = resolve(process.cwd(), ".omc-env");
     return existsSync(projectEnv) ? resolve(process.cwd(), ".omc", "usage.jsonl") : undefined;
 }
+/** The args digest of the in-flight invocation (session-scoped memo key). */
+export function currentUsageArgsDigest() {
+    return pending?.argsDigest;
+}
+/** The summarized args of the in-flight invocation (safe keys only). */
+export function currentUsageArgSummary() {
+    return pending?.argSummary;
+}
+/**
+ * Was this exact invocation (same command + same args) already SUCCESSFUL in the
+ * current project session, with no intervening call from `invalidators` for the
+ * same business key?
+ *
+ * r9 (2026-10-22) called `rule.enable` with identical args 14 times; each call
+ * answered `alreadyEnabled:true` and minted another rule version. The log is the
+ * only durable session memory a CLI has, so the idempotency memo lives there.
+ */
+export function priorIdenticalSuccess(command, argsDigest, options = {}) {
+    const path = logPath();
+    if (!path)
+        return undefined;
+    const limit = options.limit ?? 60;
+    const tail = readUsageTail(path, 131072).slice(-limit);
+    const current = pending?.argSummary ?? {};
+    const keyFields = options.keyFields ?? ["schemaCode", "ruleCode", "code"];
+    const sameKey = (record) => {
+        const summary = record.argSummary && typeof record.argSummary === "object" ? record.argSummary : {};
+        return keyFields.every((field) => {
+            const wanted = current[field];
+            if (wanted === undefined)
+                return true;
+            return String(summary[field] ?? "") === String(wanted);
+        });
+    };
+    let count = 0;
+    const requestIds = [];
+    for (let index = tail.length - 1; index >= 0; index -= 1) {
+        const record = tail[index];
+        const recordCommand = String(record.command ?? "");
+        if (options.invalidators?.includes(recordCommand) && sameKey(record))
+            return count > 0 ? { count, requestIds } : undefined;
+        if (recordCommand !== command)
+            continue;
+        if (String(record.argsDigest ?? "") !== argsDigest)
+            continue;
+        if (String(record.status ?? "") !== "ok")
+            continue;
+        count += 1;
+        const requestId = record.requestId;
+        if (typeof requestId === "string" && requestIds.length < 3)
+            requestIds.push(requestId);
+    }
+    return count > 0 ? { count, requestIds } : undefined;
+}
 /** The command string of the in-flight invocation (for diagnostics). */
 export function currentUsageCommand() {
     return pending?.command;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stalfh233/omc-cli",
-  "version": "0.4.73",
+  "version": "0.4.74",
   "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.73",
+    "@stalfh233/omc-fake-platform": "0.4.74",
     "commander": "14.0.3",
-    "omc-core": "0.4.73",
+    "omc-core": "0.4.74",
     "proper-lockfile": "4.1.2",
     "write-file-atomic": "6.0.0",
     "zod": "^3.23.8",

package/skills/omc-business-configuration.md

@@ -157,7 +157,14 @@ rules:
 - **DYNAMIC 来源不要写点号**：`dataActions` 的 `currentDataItemValue` 写 `items.sealNo` 会被引擎当成**子表列集合**（DatasetImpl），标量目标收到集合 → 运行期 `submit/update` 报 50000（`WorkSheetBizField.fillClientContent: Incorrect value type`）。单跳关联字段直接写字段 code（引擎取 `.id`）；子表列只能用于公式/聚合。`rule.save` 已写前拒绝（`rule-graph-create-dynamic-source-is-child-collection`）。
 - **单选字段的 `dataCondition` 在 1.1.25 不生效**：用 FIXED 值比较 RADIO/CHECKBOX/DROPDOWN 时，运行时日志「解析选框类型数据项的比较值失败」，条件被跳过、节点**无条件执行**（r8：异常归还被当成已归还回写）。`rule.save` 会把它放进 `readback.lintHazards`（`rule-graph-radio-condition-unparseable`）；改用 BRANCH 判断该字段，或拆两条规则。
 - **预置 Update 规则里的跨模型回写只在 `data.update` 触发**：`rule-graph-cross-model-update-trigger-inert` 现在是 hazard（在 `readback.lintHazards`，不混进 `lintWarnings`）；create/submit 不执行它。要提交时生效，把节点放进 Create 规则或流程事件规则。
+- **部门/员工写面**：`org.department.create`（`deptType` 传名字或 0..3，平台按 **int 枚举**反序列化，写 `"dept"` 会 10009）→ `org.department.update`（先读再合并）/`org.department.delete`（`strike_out`）；`org.user.create` 必填 `name/username/departmentId`，**平台对 `userLabelIds`/`userManagerConfigList`/`roleIds` 的 null 直接 NPE**（50000，`UserHelper.dealUserLabel:428`），工具已补空数组；`org.user.update` 同样必须先补 `deptIds` 等数组（`UserHelper.modified` 对 null 的 `deptIds` NPE）。`org.department.list` 递归展开整棵树（`/department/tree` 每次只返回一层）；`org.department.users` / `org.user.info` / `org.user.departments` 用于回读。新建用户的 `active` 平台回读为 false（账号激活另有流程），不要把 active 当作创建成功标志。
+- **组织写面（角色/成员/管理范围）**：界面上的「分组」= 角色（`group:false`），容器是角色组（`group:true`）。链路：`org.roleGroup.create`（**parentId 必填**，1.1.25 传空会 50000 `parentIds cannot be empty`）→ `org.role.create`（roleId 平台生成，code 随后补 `SYS<时间戳>`）→ `org.role.addUsers`（`id` 必须传 **recId**，不是账号；工具补 `type:3`/`unitType:"3"`）→ `org.role.setUserScope`（**平台覆盖语义、无回滚**：默认读旧值合并，`mode:"replace"` 才整体替换；`unitType` 传数字 3）。读回用 `org.role.users` / `org.role.userScope`。
+  - **`corpId` 默认写当前企业，不要写 `"other"`**（r9 2026-10-22 更正）：`RoleGroupHelper.createRoleGroupModel` 只从 body 取 corpId，缺省才按 parentId 反查企业设置、查不到就 NPE（被吞成 errcode 0）；`other` 是平台**合法的「非组织分组」语义**，不是兜底值。工具现在默认 `session.enterpriseId()`，并回读校验（不一致给 warning）；只有明确要建非组织分组时才显式传 `corpId:"other"`。
+  - **`org.role.list` 必须带 `expandAll=true`**：`/role/list` 不带该参数只展开**第一个**角色组的 children（`RoleController.list`，1.1.25），所以建在别的组下的角色读回为「不存在」——r9 因此误判「角色未创建」并重复读了 8 次。工具已默认展开，`expandAll:false` 才拿容器面。
+  - **`org.role.update` 的平台前置条件**：`modify_role` 的 `validateRoleParam` 要求 `roleName` 与 `roleGroupId` **都非空**（否则 202001 / 202012），所以只改备注也要回填这两项——工具已从 `role/get` 自动补齐。`corpId` 在 update 里不生效，换企业只能重建角色。
+  - **角色参与人可用性**：r9 对照实验证明，`corpId=other` 的角色**仍能正常解析参与人**（把非发起人加进该角色后，待办正确落到该人）。所以「审批人变成发起人」要按**解析为空**排查（角色零成员 / 成员没挂部门 / 自由文本 / 角色码不存在），不要归因于 corpId。
 - **系统持久化节点是平台自带的，不要手写**：预置 `Create/Update/Delete` 行本来就带 `SYSTEM_CREATE/SYSTEM_UPDATE/SYSTEM_DELETE`（实测基线 `Start → Create(SYSTEM_CREATE) → End`）。`rule.save` 会丢弃调用方传入的 `SYSTEM_*` 并**从平台基线原样携带**那一个节点（code/name/几何都不由我们猜）。手写的后果：预置规则里类型错配 → `data.submit` 50000；自定义规则/流程事件里带系统节点 → 结束事件无当前对象，`Object <id> is not serialized`，每步仍回 DELIVERED 但什么都没写。只写平台允许配置的业务节点（UPDATE/CREATE/DELETE/BRANCH/ASSIGN/MESSAGE/BIZ_ACTION…）。
+- **QUERY 节点的三个「静默空结果」入口（1.1.25 源码，r9 §14.1）**：`QueryActivityBehavior:47-50`（输入数据为空，或 `dataCondition` 过滤后为空 → `return null`）、`:78-86`（`mainConditions` 为空 → `emptyList`；目标带 `.` 时 `sheetConditions` 为空也 `emptyList`）、`ActivityBizObjectManagerImpl:172-178`（真查询 0 命中 → `emptyList`）。**三条都不写日志**，所以「节点执行开始后什么都没有」既可能是配置错也可能是 0 命中。前两条工具已在写前拦：`rule-graph-query-conditions-empty`（无条件叶，fail closed——QUERY 的空条件**不是**「查全表」，与 UPDATE 语义相反；要全表请写恒真叶）与 `rule-graph-query-datacondition-empty`（hazard）。第三条只能在运行期验证：先 `data.list` 确认目标行存在且状态已提交。
 - **取 artifact 先投影**：`artifact get <id> --summary` 看形状 → `--jq '<path>'` 取那一段；只有确实要整份时才裸取（r6：47 次整包拉取 650KB，0 次用投影）。
 - **读回产物会自动清理，也可手动清**：每次大结果落一个 artifact（机器级目录，跨项目累积；实测一轮沙盒 504 个/3.4MB）。`createArtifact` 每 24h 顺手删 7 天未动的；要立刻回收用 `omc artifact prune --older-than 7d --max-bytes 268435456`（默认预算 256MB，超出按最旧优先删），`--json` 回 removed/freedBytes/kept。
 - **核验状态用投影，别重复整条读**：`data.load --args '{"schemaCode":..,"bizObjectId":..,"fields":["sequenceStatus","<业务状态字段>"]}'` 只回指定字段（缺失项在 `missingFields`）——r4 实测同一对象被整条读 74 次；大结果先 `artifact get <id> --summary` → `--keys/--jq`，别整包内联进推理。

package/skills/omc-capabilities.md

@@ -138,7 +138,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.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`
+- **工具**：`workflow.get_draft`、`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`
 - **recipe**：`omc describe workflow.bindRule --example workflow-handler-binding`
 - **边界 / 陷阱**：greenfield 首版；`publish`/`bindRule` 不得在 `ValidateMessage[]` 拒绝时报告成功。运行时 workitem（提交/审批）走 `data.submit`；想知道实例停在哪/是否错派，用 `workflow.instanceActivity`（无 status=1=真停，参与人全是发起人=解析为空退回）。