@stalfh233/omc-cli 0.6.0 → 0.6.2

package/dist/cli.js

@@ -749,8 +749,34 @@ async function cmdArtifactGet(id, transport, options = {}) {
             }, transport);
         }
         const result = { status: "ok", artifactId: id, sha256: artifact.sha256, content };
-        if (Buffer.byteLength(JSON.stringify(result), "utf8") > transport.maxOutputBytes)
-            return emitTransportResult({ status: "ok", artifactId: id, sha256: artifact.sha256, bytes: artifact.content.length, fetch: artifactFetchHint(id) }, transport);
+        if (Buffer.byteLength(JSON.stringify(result), "utf8") > transport.maxOutputBytes) {
+            // 2026-11-04 r70: `--full` used to fall back to the same bare `fetch`
+            // pointer it had just been asked to bypass — re-running `--full` re-hits
+            // the same ceiling, so a caller that genuinely needs the body loops
+            // forever (observed live: three consecutive `--full` calls returned the
+            // same id with bytes 90K→151K→227K of pointer metadata). Say what
+            // actually happened and give the two projections that DO work.
+            const record = content && typeof content === "object" && !Array.isArray(content) ? content : undefined;
+            const keys = record
+                ? Object.entries(record)
+                    .map(([key, value]) => ({ key, bytes: Buffer.byteLength(JSON.stringify(value) ?? "null", "utf8") }))
+                    .sort((left, right) => right.bytes - left.bytes)
+                    .slice(0, 3)
+                    .map((entry) => entry.key)
+                : [];
+            return emitTransportResult({
+                status: "ok",
+                artifactId: id,
+                sha256: artifact.sha256,
+                bytes: artifact.content.length,
+                fullRejected: true,
+                reason: `整包 ${Math.round(artifact.content.length / 1024)}KB 超过本通道输出上限 ${transport.maxOutputBytes}B；--full 无法一次返回，再跑一次结果相同`,
+                ...(keys.length > 0 ? { keysCommand: `omc artifact get ${id} --keys ${keys.join(",")}`, sampledKeys: keys } : {}),
+                jqCommand: `omc artifact get ${id} --jq '<path>'`,
+                raiseCeilingCommand: `omc artifact get ${id} --full --max-output-bytes ${Math.max(artifact.content.length + 1024, transport.maxOutputBytes * 2)}`,
+                hint: "二选一：用 --jq/--keys 取你真正需要的那部分（推荐），或显式抬高 --max-output-bytes",
+            }, transport);
+        }
         return emitTransportResult(result, transport);
     }
     catch (error) {

package/dist/lanes/organization.js

@@ -74,6 +74,83 @@ function deptTypeCode(value) {
     return code;
 }
 const orgQuery = (session) => ({ corpId: session.enterpriseId() });
+/**
+ * Read the role tree (`/role/list?expandAll=true`) and flatten it, keeping the
+ * **id** alongside code/name.
+ *
+ * Why this exists (r70, live 1.1.25): `org.role.list`'s compact projection emits
+ * `code｜name` pairs and drops the id, while `add_role` / `add_role_user` /
+ * `update_ouscope` all want the id. Worse, the platform stores a wrong
+ * `roleGroupId` verbatim (`h_org_role.groupId` is not an FK): passing the group
+ * *code* that the read face shows yields errcode 0 and an orphan role — the row
+ * exists, `role/users` finds it, `role/list` never returns it, `role/get`
+ * answers 50000. Resolving code→id here removes the trap for every caller.
+ */
+async function readRoleTree(session) {
+    const data = (await wireCall(session, {
+        path: ENDPOINTS.organizationRoleList,
+        query: { corpId: session.enterpriseId(), expandAll: "true" },
+    })).data;
+    const groups = [];
+    const roles = [];
+    const childKeys = ["children", "roles", "childRoles", "childList", "list"];
+    const childrenOf = (row) => {
+        for (const key of childKeys) {
+            const value = row[key];
+            if (Array.isArray(value))
+                return value;
+        }
+        return [];
+    };
+    const walk = (rows) => {
+        for (const row of rows) {
+            const kids = childrenOf(row);
+            // A container carries group===true, or has children and no groupId; a leaf
+            // role always carries groupId (mirrors flattenRoleTree's rule).
+            const hasGroupId = row.groupId !== undefined && row.groupId !== null;
+            const isGroup = row.group === true || (!hasGroupId && kids.length > 0);
+            if (!isGroup) {
+                const id = String(row.id ?? "");
+                if (id !== "")
+                    roles.push({ id, code: String(row.code ?? ""), name: String(row.name ?? "") });
+                continue;
+            }
+            groups.push({ id: String(row.id ?? ""), code: String(row.code ?? ""), name: String(row.name ?? "") });
+            if (kids.length > 0)
+                walk(kids);
+        }
+    };
+    walk(wireRows(data));
+    return { groups, roles };
+}
+/**
+ * Resolve a caller-supplied role reference (32-hex id, or the `code` / `name`
+ * that `org.role.list` actually shows) to the platform role id. A reference that
+ * matches nothing is refused with the list of real roles — never written blind.
+ */
+async function resolveRoleRef(session, args, tool) {
+    const requested = args.roleId ?? args.roleCode;
+    if (!requested)
+        throw new ToolInputError({ status: "error", blocker: "tool-input-invalid", tool, message: "需要 roleId 或 roleCode（org.role.list 的 roles 码表给的是 code）" });
+    // An explicit roleCode must resolve — never forward it as an id.
+    if (args.roleId !== undefined && args.roleCode === undefined && /^[0-9a-f]{32}$/i.test(requested))
+        return requested;
+    const { roles } = await readRoleTree(session);
+    const match = roles.find((role) => role.code === requested) ?? roles.find((role) => role.name === requested);
+    if (match)
+        return match.id;
+    // Not a known code/name. `roleId` may still be a valid id the tree does not
+    // surface (e.g. a role in another corp); forward it and let the platform
+    // judge, rather than breaking callers that hold an id we cannot see.
+    if (args.roleId !== undefined)
+        return requested;
+    throw new ToolInputError({
+        status: "error",
+        blocker: "tool-input-invalid",
+        tool,
+        message: `角色 ${requested} 不存在。可用角色：${roles.slice(0, 30).map((role) => `${role.code}（${role.name}）`).join("；")}`,
+    });
+}
 const roleUserId = (row) => String(row.id ?? row.userId ?? row.recId ?? "");
 async function memberRows(session, roleId) {
     const data = (await wireCall(session, {
@@ -226,22 +303,43 @@ export function registerOrganizationLane(tools) {
             },
         };
     });
-    writeTool(tools, "org.role.create", LANE, SCOPES.roleCreate, "创建角色（界面「分组」；`POST organization/role/add_role`）。返回 roleId；code 创建时 null、随后补 SYS<时间戳>，要稳定编码就传 code。", {
+    writeTool(tools, "org.role.create", LANE, SCOPES.roleCreate, "创建角色（界面「分组」；`POST organization/role/add_role`）。返回 roleId；code 创建时 null、随后补 SYS<时间戳>，要稳定编码就传 code。**所属角色组推荐用 `roleGroupCode`（如 SYS_1000000）**：`org.role.list` 的紧凑码表只给 `code｜name`、不显示组 id，而平台对错的 roleGroupId **静默接受**——存进去的值不是真实组 id 时角色会变成看不见的孤儿（r70 实测：在库里、role/users 查得到，role/list 永不返回、role/get 50000）。工具会把 code 归一成真实 id，并在创建后回读可见性。", {
         roleName: z.string().min(1),
-        roleGroupId: z.string().min(1).describe("所属角色组 id（org.role.list 的 groups[].id）"),
+        roleGroupCode: z.string().min(1).optional().describe("所属角色组的 code（org.role.list 的 groups 码表，如 SYS_1000000）或名称。**推荐**；与 roleGroupId 二选一"),
+        roleGroupId: z.string().min(1).optional().describe("所属角色组 id（32 位 hex，只能从 artifact get <role.list 的 detailArtifactId> --jq groups 取到）。误传组 code 时工具会归一成真实 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) => {
+        if (!args.roleGroupCode && !args.roleGroupId) {
+            throw new ToolInputError({ message: "必须给 roleGroupCode（推荐）或 roleGroupId；先 org.role.list 取 groups 码表" });
+        }
+        const { groups } = await readRoleTree(session);
+        if (groups.length === 0) {
+            throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "org.role.list 未解析出任何角色组；先确认组织树可读，不要盲建角色" });
+        }
+        const requested = args.roleGroupId ?? args.roleGroupCode;
+        const match = groups.find((group) => group.id === requested) ??
+            groups.find((group) => group.code === requested) ??
+            groups.find((group) => group.name === requested);
+        // A code/name that resolves to nothing is a definite typo → refuse.
+        // A 32-hex id absent from the tree may be a group created moments ago in
+        // this same session; let it through and rely on the visibility backstop.
+        if (!match && args.roleGroupCode) {
+            throw new ToolInputError({
+                message: `角色组 ${requested} 不存在。可用组：${groups.map((group) => `${group.code}（id=${group.id}，${group.name}）`).join("；")}`,
+            });
+        }
+        const roleGroupId = match?.id ?? String(requested);
         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,
+                roleGroupId,
                 ...(args.roleGroupName ? { roleGroupName: args.roleGroupName } : {}),
                 roleType: args.roleType ?? "SYS",
                 corpId,
@@ -252,15 +350,29 @@ export function registerOrganizationLane(tools) {
         const roleId = String(data?.roleId ?? data?.id ?? "");
         if (!roleId)
             throw new ToolRefusalError({ status: "refused", blocker: "wire-shape", message: "平台未返回 roleId；先 org.role.list 回读确认" });
+        // Backstop against the silent-orphan trap: re-read the tree and report the
+        // truth instead of reporting success for a role nobody can see.
+        const visible = (await readRoleTree(session)).roles.some((role) => role.id === roleId);
         const readbackCorpId = data?.corpId ?? null;
+        const warnings = [];
+        if (!visible) {
+            warnings.push(`角色 ${roleId} 创建后不在 org.role.list 任何组下（孤儿角色）：groupId 很可能没落到真实组 id。请 org.role.delete 后按 roleGroupCode 重建`);
+        }
+        if (readbackCorpId !== null && String(readbackCorpId) !== corpId) {
+            warnings.push(`平台回读 corpId=${String(readbackCorpId)}，与请求的 ${corpId} 不一致`);
+        }
         return {
             performed: { errcode: 0 },
             readback: {
                 roleId,
                 roleName: data?.roleName ?? args.roleName,
                 code: data?.code ?? null,
+                roleGroupId,
+                roleGroupCode: match?.code ?? null,
+                roleGroupName: match?.name ?? null,
+                visibleInRoleList: visible,
                 corpId: readbackCorpId,
-                ...(readbackCorpId === null || String(readbackCorpId) === corpId ? {} : { warning: `平台回读 corpId=${String(readbackCorpId)}，与请求的 ${corpId} 不一致` }),
+                ...(warnings.length > 0 ? { warning: warnings.join("；") } : {}),
             },
         };
     });
@@ -634,21 +746,23 @@ export function registerOrganizationLane(tools) {
             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),
+    writeTool(tools, "org.role.delete", LANE, SCOPES.roleDelete, "删除角色（`GET organization/role/strike_out_role?ids=`）。平台**拒绝删除仍有成员的角色**（`-1 角色下已经包含用户数据！`，实测 1.1.25）：默认先读成员数、非空即拒绝并给出人数；`force:true` 才会先逐人移出再删。**可用 roleCode 代替 roleId**（org.role.list 的码表只有 code）。", {
+        roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
+        roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表，如 qc_manager）或名称"),
         force: z.boolean().optional().describe("true = 先移出全部成员再删角色"),
     }, async (session, args) => {
-        const rows = await memberRows(session, String(args.roleId));
+        const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.delete");
+        const rows = await memberRows(session, roleId);
         if (rows.length > 0 && args.force !== true)
             throw new ToolRefusalError({
-                status: "refused", blocker: "role-has-members", roleId: String(args.roleId), members: rows.length,
-                nextCommand: `omc call org.role.delete --args '${JSON.stringify({ roleId: String(args.roleId), force: true })}'`,
+                status: "refused", blocker: "role-has-members", roleId, members: rows.length,
+                nextCommand: `omc call org.role.delete --args '${JSON.stringify({ roleId, force: true })}'`,
                 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 } };
+            await removeMembers(session, roleId, rows.map(roleUserId));
+        await wireCall(session, { path: ENDPOINTS.organizationRoleDelete, query: { ...orgQuery(session), ids: roleId } });
+        return { performed: { errcode: 0 }, readback: { 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),
@@ -730,7 +844,8 @@ export function registerOrganizationLane(tools) {
         };
     });
     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),
+        roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
+        roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表）或名称——省掉取 artifact 找 id"),
         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"),
@@ -744,15 +859,16 @@ export function registerOrganizationLane(tools) {
         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）至少一人" });
+        const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.addUsers");
         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" })) },
+            body: { 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" },
+                query: { ...orgQuery(session), roleId: roleId, page: "0", size: "500" },
             })).data;
             return Array.isArray(data?.content) ? data.content : wireRows(data);
         };
@@ -766,11 +882,11 @@ export function registerOrganizationLane(tools) {
             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 },
+                    body: { roleId: 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 },
+                    query: { ...orgQuery(session), roleId: roleId, userId: id },
                 })).data);
                 scopeResults.push({ userId: id, scopes: scope.length });
             }
@@ -778,7 +894,7 @@ export function registerOrganizationLane(tools) {
         return {
             performed: { errcode: 0 },
             readback: {
-                roleId: String(args.roleId), added,
+                roleId: roleId, added,
                 ...(missing.length > 0 ? { missing, hint: "这些 recId 未出现在成员列表：确认 id 是 recId、用户未离职/禁用" } : {}),
                 ...(scopeResults.length > 0 ? { scopeResults } : {}),
                 // ouScope 是流程角色参与人解析的过滤维度：平台
@@ -802,12 +918,14 @@ export function registerOrganizationLane(tools) {
         };
     });
     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),
+        roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
+        roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表）或名称"),
         ids: z.array(z.string().min(1)).min(1).describe("要移出的成员 recId 列表"),
     }, async (session, args) => {
+        const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.removeUsers");
         await wireCall(session, {
             path: ENDPOINTS.organizationRoleRemoveUser, method: "POST", query: orgQuery(session),
-            body: { roleId: String(args.roleId), userIds: args.ids },
+            body: { roleId, userIds: args.ids },
         });
         const data = (await wireCall(session, {
             path: ENDPOINTS.organizationRoleUsers,
@@ -818,7 +936,8 @@ export function registerOrganizationLane(tools) {
         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),
+        roleId: z.string().min(1).optional().describe("角色 id（32 位 hex）；与 roleCode 二选一"),
+        roleCode: z.string().min(1).optional().describe("角色 code（org.role.list 的 roles 码表）或名称"),
         userId: z.string().min(1).describe("成员 recId"),
         scopes: z.array(z.object({
             id: z.string().min(1).describe("部门 id"),
@@ -832,9 +951,10 @@ export function registerOrganizationLane(tools) {
         mode: z.enum(["merge", "replace"]).optional().describe("默认 merge（读旧值合并）；replace = 覆盖整个范围"),
         dryRun: z.boolean().optional(),
     }, async (session, args) => {
+        const roleId = await resolveRoleRef(session, { roleId: args.roleId, roleCode: args.roleCode }, "org.role.setUserScope");
         const before = wireRows((await wireCall(session, {
             path: ENDPOINTS.organizationRoleGetOuScope,
-            query: { ...orgQuery(session), roleId: args.roleId, userId: args.userId },
+            query: { ...orgQuery(session), roleId, userId: args.userId },
         })).data);
         const wanted = args.scopes.map((scope) => ({ id: scope.id, name: scope.name, type: scope.type === undefined ? "1" : String(scope.type), ...(scope.deptPath ? { deptPath: scope.deptPath } : {}) }));
         const merged = args.mode === "replace"
@@ -850,15 +970,15 @@ export function registerOrganizationLane(tools) {
         await wireCall(session, {
             path: ENDPOINTS.organizationRoleUpdateOuScope, method: "POST",
             query: orgQuery(session),
-            body: { roleId: args.roleId, userId: args.userId, unitType: 3, sortKey: 999, ouScopeList: merged },
+            body: { 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 },
+            query: { ...orgQuery(session), 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 } : {}) },
+            readback: { roleId, userId: args.userId, mode: args.mode ?? "merge", before: before.length, after: after.length, scopes: after, ...(removed.length > 0 ? { removedScopeIds: removed } : {}) },
         };
     });
 }

package/package.json

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

package/skills/omc-backend-online-coding.md

@@ -35,6 +35,81 @@ AI-Platform 1.1.25（8.7 时代）已实测（2026-11-03）。
 
 先按 cpdocs 的落点判据定「配置 / 二开」；判到二开时，再用上表在两种 Java 落点间选。
 
+## 0.1 在线编码的能力边界（实测，1.1.25）
+
+在线编码**不是一个工程，是单文件 Handler**。平台契约就是「一条规则 = 一个 `content`
+字符串 = 一个 `.java` 文件」，没有多文件、没有模块、看不见你的工程代码。这个边界
+决定了很多事能不能做。
+
+### 源码形态
+
+| 能做 | 不能做 |
+|---|---|
+| **1 个 public 类**（必须 `schemaCode+ruleCode+Handler`） | 第 2 个 public 类（`should be declared in a file named X.java`） |
+| 多个 package-private 顶层类（实测 5 个无问题） | — |
+| 内部类 / 静态嵌套 / 匿名类 / lambda / stream | 顶层 `static class` |
+| 同文件 `enum` / `interface` / `@interface`（非 public） | — |
+| `import a.b.*` 通配符、`import static` | — |
+
+### 语言级别：Java 8
+
+| 语法 | 结果 |
+|---|---|
+| lambda / stream / 匿名类 | ✅ |
+| `var` | ❌ `cannot find symbol` |
+| `record` | ❌ `class, interface, or enum expected` |
+| 文本块 `"""` | ❌ `';' expected` |
+| switch 表达式 `case 1 ->` | ❌ |
+
+**坑**：平台上挂着 Lombok 注解处理器但**它初始化失败**
+（`NoClassDefFoundError: com/sun/tools/javac/processing/JavacProcessingEnvironment`），
+所以用 Java 8 之后的语法时，错误里会先出现一坨 Lombok 异常，真正的
+`cannot find symbol` 排在后面。**看错误先看最后一条**，别被 Lombok 噪音带偏。
+Lombok 的代码生成也**不可用**（`@Data` 生成的方法找不到），老老实实手写 getter/setter
+和 `LoggerFactory.getLogger(...)`。
+
+### 可用依赖
+
+| 可用 | 不可用 |
+|---|---|
+| `java.lang/math/util/io` + wildcard / static import | Jakarta EE（`jakarta.*`） |
+| `engine.open.*`（OpenEngine / BizObject / BizObjectQuery / FilterExpression） | **大部分 `engine.api.facade/model.*`**（包不存在） |
+| `engine.ErrorCode`、`engine.api.historical.*` | **`engine.service.*`**（平台内部 Service 不可见） |
+| commons-lang3 / fastjson / guava / hutool / slf4j | **工程自有包**（`app.modules.*` 编不过） |
+| `javax.annotation` / `javax.servlet` | 额外第三方 jar（不在 launcher 类路径上） |
+| Spring 注解（能编译） | **Spring 运行时**（规则每次重新实例化，无容器上下文；不要注册 Bean） |
+
+**别按平台的「补全白名单」写代码**：白名单列了 `engine.api.*` / `engine.domain.*` /
+`engine.service.*`，但**白名单 ≠ javac 类路径**——白名单里很多类实际编不过。以
+`engine.open.*` 为准，拿不准就先 `programming.compile` 试一次（只读，不落库）。
+
+### 运行时约束
+
+| 项 | 值 | 说明 |
+|---|---|---|
+| 执行超时 | **600s**（默认） | `cloudpivot.online-develop.thread-overtime` |
+| 最大栈深 | 50 | 递归要小心 |
+| 字符串常量 | ≤ 64KB | 超过报 `constant string too long`；文件本身几十 KB 没问题 |
+| 编译产物目录 | `<launcher>/inject_code_dir` | 无写权限 → publish 成功但执行 50000 |
+| 生命周期 | 每次执行重新实例化 | 无状态、不能常驻、不能注册 Bean |
+| 并发/事务 | 跑在平台保存调用内 | 别在里面起线程或长事务 |
+
+### 必须退回本地扩展包的场景
+
+出现任一条就**不是**在线编码能解决的，别硬塞：
+
+1. 要对外开 **REST 接口**
+2. 要接 **SPI / 平台扩展点**（单据号、消息、流程监听、适配器、模型校验…）
+3. 要 **Spring 托管 / 拦截器 / 全局异常 / 多 Bean 协作**
+4. 要**复用工程内自己的类或工具库**（在线编码看不见它们）
+5. 要<strong>引额外第三方 jar</strong>（launcher 类路径上没有）
+6. 要 **Java > 8 语法 / Lombok 代码生成**
+7. 要**多条规则共享同一套工具方法**——在线编码没有跨规则复用，只能各文件复制；
+   一旦出现「三处以上重复」，转本地扩展包
+
+反过来，**留在在线编码**：某个模型 Create/Update/Delete/Load/GetList/自定义规则时，
+用 OpenEngine 做字段改写、补数、简单联动——publish 即生效。
+
 ## 1. 两种用法：单条 vs 工作区
 
 ### 单条（快速改一条规则）
@@ -136,9 +211,8 @@ cpdocs 提供**平台知识与规范**，本 CLI 提供**执行面**。已安装
 推荐循环：**需求 → cpdocs 定落点与 API → `programming.get` 取模板 → 按 cpdocs 规范写 →
 `compile` → `apply --publish` → `programming test` 断言 → （跨模型/对外接口才升到二开扩展包）**。
 
-在线编码里能用什么：`java.lang/math/util/io` + `com.authine.cloudpivot.engine.open.*`
-（OpenEngine）+ `engine.api.*`；web-api 类路径上的二开依赖也能用。**不要用 Spring**
-（规则每次执行重新实例化，无 Spring 上下文），也别把规则类注册成 Bean（内存泄漏）。
+在线编码里能用什么依赖、什么语法、什么必须退回扩展包——见 [§0.1 能力边界](#01-在线编码的能力边界实测-1125)。
+拿不准某个类能不能用，先 `programming.compile` 试一次（只读不落库），比猜快。
 
 ## 5. 典型 handler 骨架（已验证可编译可运行）