@yss123/cage-cli 0.3.0 → 0.3.2

package/graph-ui/approval-parallel.js

@@ -0,0 +1,110 @@
+import { wrapApprovalText } from './approval-flow.js';
+/** 创建空容器；空条件分支仍有一条可连接直线，不假造审批节点或已经运行的票。 */
+function fragment(width = 348, height = 0) {
+    return { width, height, axis: width / 2, boxes: [], paths: [], merges: [] };
+}
+/**
+ * 把已测量子图复制平移到父图，路径坐标只由本模块产生的 M/L/H/V 绝对指令转换。
+ * 不改源片段，递归兄弟分支共享文本对象也不会互相污染；标题与输入不拼入 SVG path。
+ */
+function append(parent, child, dx, dy) {
+    parent.boxes.push(...child.boxes.map(box => ({ ...box, x: box.x + dx, y: box.y + dy })));
+    for (const path of child.paths)
+        parent.paths.push({ ...path,
+            d: path.d.replace(/([ML])(-?[\d.]+),(-?[\d.]+)|([HV])(-?[\d.]+)/g, (_match, point, x, y, axis, value) => point ? `${point}${Number(x) + dx},${Number(y) + dy}` : `${axis}${Number(value) + (axis === 'H' ? dx : dy)}`),
+            ...(path.x === undefined ? {} : { x: path.x + dx }), ...(path.y === undefined ? {} : { y: path.y + dy }) });
+    parent.merges.push(...child.merges.map(point => ({ x: point.x + dx, y: point.y + dy })));
+}
+/** 把一个审批叶节点测量成普通任务框；编号只是声明定位，不决定并行分支的实际运行顺序。 */
+function taskFragment(task) {
+    const title = wrapApprovalText(task.title, 14), actor = wrapApprovalText(`审批人：${task.actor}`, 19), rule = wrapApprovalText(task.rule, 18);
+    const height = 18 + title.length * 18 + actor.length * 16 + rule.length * 16, result = fragment(348, height);
+    result.boxes.push({ kind: 'task', x: 50, y: 0, width: 248, height, title, actor, rule, task });
+    return result;
+}
+/** 各顺序子片段在最大宽度中心对齐，连接只经过相邻片段之间的空隙。 */
+function sequence(parts) {
+    // 条件旁路使子图左右不对称，按中心轴两侧的最大占用测量，不能只取原始 width 后居中导致右侧越界。
+    const result = fragment(Math.max(348, ...parts.map(part => 2 * Math.max(part.axis, part.width - part.axis))));
+    if (!parts.length) {
+        result.height = 20;
+        result.paths.push({ d: `M${result.axis},0 V20` });
+        return result;
+    }
+    for (const [index, part] of parts.entries()) {
+        if (index) {
+            result.paths.push({ d: `M${result.axis},${result.height} V${result.height + 28}` });
+            result.height += 28;
+        }
+        append(result, part, result.axis - part.axis, result.height);
+        result.height += part.height;
+    }
+    return result;
+}
+/**
+ * 条件未满足的路径在整个子树外侧绕行并汇合，包含并行网关时也不能跳过一半后进入内部支路。
+ * 中心轴保持子树入口，额外宽度只用于右侧旁路；祖先会按 axis 平移，避免嵌套时斜穿节点。
+ */
+function conditional(body, condition) {
+    const result = fragment(body.width + 76), title = wrapApprovalText(`${condition}？`, 13), height = Math.max(64, title.length * 36);
+    result.axis = body.axis;
+    result.boxes.push({ kind: 'condition', x: result.axis - 124, y: 0, width: 248, height, title, actor: [], rule: [] });
+    const top = height + 30, merge = top + body.height + 26;
+    append(result, body, 0, top);
+    result.paths.push({ d: `M${result.axis},${height} V${top}`, label: '是', x: result.axis + 16, y: height + 18 }, { d: `M${result.axis},${top + body.height} V${merge}` }, { d: `M${result.axis + 124},${height / 2} H${body.width + 38} V${merge} H${result.axis}`,
+        label: '否 · 跳过', x: body.width + 38, y: (height / 2 + merge) / 2, skip: true });
+    result.merges.push({ x: result.axis, y: merge });
+    result.height = merge;
+    return result;
+}
+/**
+ * 并行分支分别测量，入口共享同一 fork，出口统一接 join；短分支等待线停留在自己通道内。
+ * 分支内部可以有条件或嵌套并行，所有子树完成后才绘制后续出口，不把任一分支画成可独自通过。
+ */
+function parallelFragment(parallel) {
+    const branches = parallel.branches.map(branch => ({ title: wrapApprovalText(branch.title, 14), body: groupsFragment(branch.groups) }));
+    const gap = 30, width = branches.reduce((sum, branch) => sum + branch.body.width, 0) + gap * (branches.length - 1);
+    const result = fragment(Math.max(348, width)), title = wrapApprovalText(`${parallel.title} · AND 分叉`, 24), forkHeight = 20 + title.length * 17;
+    result.boxes.push({ kind: 'fork', x: result.axis - 150, y: 0, width: 300, height: forkHeight, title, actor: [], rule: [] });
+    const splitY = forkHeight + 20, branchTop = splitY + 20;
+    let dx = 0, bottom = branchTop;
+    const ends = [];
+    for (const branch of branches) {
+        const axis = dx + branch.body.axis, labelHeight = 16 + branch.title.length * 17;
+        result.boxes.push({ kind: 'branch', x: axis - 124, y: branchTop, width: 248, height: labelHeight,
+            title: branch.title, actor: [], rule: [] });
+        const bodyTop = branchTop + labelHeight + 24;
+        result.paths.push({ d: `M${result.axis},${forkHeight} V${splitY} H${axis} V${branchTop}` }, { d: `M${axis},${branchTop + labelHeight} V${bodyTop}` });
+        append(result, branch.body, dx, bodyTop);
+        const end = bodyTop + branch.body.height;
+        ends.push({ x: axis, y: end });
+        bottom = Math.max(bottom, end);
+        dx += branch.body.width + gap;
+    }
+    const mergeY = bottom + 24, joinY = mergeY + 20, joinHeight = 40;
+    for (const end of ends)
+        result.paths.push({ d: `M${end.x},${end.y} V${mergeY} H${result.axis} V${joinY}` });
+    result.boxes.push({ kind: 'join', x: result.axis - 150, y: joinY, width: 300, height: joinHeight,
+        title: ['AND 汇合 · 等待全部活动分支'], actor: [], rule: [] });
+    result.height = joinY + joinHeight;
+    return result;
+}
+/** 将保留的声明组递归转换为几何，条件包裹整个子树，parallel 和普通 tasks 不混为串行。 */
+function groupsFragment(groups) {
+    return sequence(groups.map(group => {
+        const body = group.parallel ? parallelFragment(group.parallel) : group.groups ? groupsFragment(group.groups) : sequence(group.tasks.map(taskFragment));
+        return group.condition ? conditional(body, group.condition) : body;
+    }));
+}
+/**
+ * 为带嵌套容器的审批投影生成完整布局；外层主流程使用返回宽高避免与邻接业务节点重叠。
+ * 结构输入由已校验声明派生；此处不重新执行条件，也不猜测当前实例哪些分支已跳过。
+ */
+export function layoutStructuredApproval(flow, name) {
+    const title = wrapApprovalText(name, 18), body = groupsFragment(flow.groups), top = 64 + title.length * 20;
+    const framed = fragment(body.width + 52);
+    append(framed, body, 26, top);
+    const footer = top + body.height + 42;
+    framed.paths.push({ d: `M${26 + body.axis},${top + body.height} V${footer - 16}` });
+    return { flow, title, width: framed.width, height: footer + 60, boxes: framed.boxes, paths: framed.paths, merges: framed.merges, footer };
+}

package/graph-ui/approval-tree.js

@@ -0,0 +1,17 @@
+/**
+ * 审批声明 JSON 的只读结构与遍历工具，供本体抽取、字段关系说明和静态流程图共同消费。
+ * 仅遍历 when、parallel 和 branch 保留的声明树，不执行条件、选人、审批引擎或实际实例状态。
+ * 浏览器可引用这些类型和纯函数，不引入 approval 运行时；标题和依赖始终来自抽取快照。
+ */
+/**
+ * 按声明的深度优先次序遍历全部节点，保留容器供条件解释使用，分支本身不是可执行步骤。
+ * 本函数不排序或改写源树；声明深度/数量由注册器限制，序号只能作为静态定位，不能当执行先后。
+ */
+export function approvalRouteNodes(nodes) {
+    return nodes.flatMap(node => [node, ...(node.kind === 'when' ? approvalRouteNodes(node.steps) :
+            node.kind === 'parallel' ? node.branches.flatMap(branch => approvalRouteNodes(branch.nodes)) : [])]);
+}
+/** 收集全部人工/AI 叶节点，用于取证与选人依赖；并行结构仍需由调用方从原树单独保留。 */
+export function approvalRouteSteps(nodes) {
+    return approvalRouteNodes(nodes).filter((node) => node.kind === 'step' || node.kind === 'ai');
+}

package/graph-ui/business.css

@@ -553,6 +553,22 @@
   font-size: 12px;
   font-weight: 500;
 }
+/* AND 网关与分支标题使用独立形状，不能被误认成一个需要审批的任务；坐标由递归测量布局提供。 */
+.approval-gateway-shape {
+  fill: #e9f0e4;
+  stroke: #72916f;
+  stroke-width: 1.5;
+}
+.approval-gateway-title {
+  fill: #35573b;
+  font-size: 12px;
+  font-weight: 600;
+}
+.approval-branch-shape {
+  fill: #f2f5ed;
+  stroke: #b5c5ab;
+  stroke-dasharray: 4 3;
+}
 .approval-flow-merge {
   fill: #8ba28e;
 }
@@ -781,6 +797,16 @@
 .business-approval-steps p {
   font-size: 10px;
 }
+/* 并行分支在规则详情中保留树层级，独立左边线区分分支，不靠列表编号暗示执行先后。 */
+.business-approval-branches {
+  margin: 8px 0;
+  padding-left: 16px;
+  list-style: none;
+  border-left: 2px solid #b5c5ab;
+}
+.business-approval-branches > li {
+  margin: 10px 0 14px;
+}
 /* 源码预览按行显示并保留原始缩进，横向溢出在代码框内滚动；行号只参与显示。 */
 .source-preview {
   min-width: 0;

package/graph-ui/business.js

@@ -496,20 +496,37 @@ export function renderBusiness(host, model, snapshot, actions) {
         }
         const approvalFlow = approvals.get(selected.id);
         if (approvalFlow) {
-            const rules = section('审批步骤与条件', '按下列顺序执行；条件不满足时跳过该组审批。');
-            const list = h('ol', 'business-approval-steps');
-            for (const group of approvalFlow.groups) {
-                const row = h('li');
-                if (group.condition)
-                    row.append(h('strong', '', `当${group.condition}时`));
-                for (const task of group.tasks) {
-                    row.append(h('strong', '', `${task.number}. ${task.title}`));
-                    row.append(h('p', '', `审批人：${task.actor} · ${task.rule}`));
+            const rules = section('审批步骤与条件', '顺序节点依次执行；并行分支同时开始，全部活动分支完成后汇合。条件在启动时判断。');
+            /** 阅读说明与图保持同一嵌套结构，编号只作定位，不把兄弟分支写成前后执行。 */
+            const describeGroups = (groups) => {
+                const list = h('ol', 'business-approval-steps');
+                for (const group of groups) {
+                    const row = h('li');
+                    if (group.condition)
+                        row.append(h('strong', '', `当${group.condition}时`));
+                    for (const task of group.tasks) {
+                        row.append(h('strong', '', `${task.number}. ${task.title}`));
+                        row.append(h('p', '', `审批人：${task.actor} · ${task.rule}`));
+                    }
+                    if (group.groups)
+                        row.append(describeGroups(group.groups));
+                    if (group.parallel) {
+                        row.append(h('strong', '', `${group.parallel.title} · AND 并行`));
+                        const branches = h('ul', 'business-approval-branches');
+                        for (const branch of group.parallel.branches) {
+                            const branchRow = h('li');
+                            branchRow.append(h('strong', '', branch.title), describeGroups(branch.groups));
+                            branches.append(branchRow);
+                        }
+                        row.append(branches, h('p', 'source-note', '各分支同时开始；全部活动分支完成 → AND 汇合后继续'));
+                    }
+                    if (group.condition)
+                        row.append(h('p', 'source-note', '条件不满足 → 跳过整组，继续后续步骤'));
+                    list.append(row);
                 }
-                if (group.condition)
-                    row.append(h('p', 'source-note', '条件不满足 → 跳过，继续后续步骤'));
-                list.append(row);
-            }
+                return list;
+            };
+            const list = describeGroups(approvalFlow.groups);
             rules.append(list, h('p', '', approvalFlow.route
                 ? '所需步骤全部通过后继续业务；任一步骤驳回则结束本轮审批。'
                 : '未抽取到绑定的审批步骤，请查看审批声明或外部流程配置。'));

package/graph-ui/graph-approvals.js

@@ -50,16 +50,29 @@ export function approvalFlowForStep(model, step, labels = {}) {
             ? `${fieldName(item.approver.field)}的负责人`
             : item.approver.kind === 'role'
                 ? (labels[`role:${item.approver.code}`] ?? '待命名审批角色')
-                : `指定用户 ${item.approver.userId}`,
-        rule: item.mode === 'all' ? '所有审批人同意后继续' : '任一审批人同意即可继续',
+                : item.approver.kind === 'field' ? `${fieldName(item.approver.field)}指定的审批人` : `指定用户 ${item.approver.userId}`,
+        rule: [item.mode === 'all' ? '所有审批人同意后继续' : item.actions?.addSign ? '任一原审批人同意' : '任一审批人同意即可继续',
+            ...(item.assignment === 'candidate' ? ['候选共享一项任务，领取后处理'] : []),
+            ...(item.actions?.addSign ? ['支持前签、后签和并行加签，全部加签人同意后继续'] : []),
+            ...(item.actions?.transfer ? ['允许转办'] : []), ...(item.actions?.delegate ? ['允许委派，归还后由原负责人决定'] : []),
+            ...(item.sla ? [`节点总时限 ${item.sla.durationMinutes} 自然分钟${item.sla.remindBeforeMinutes ? `，提前 ${item.sla.remindBeforeMinutes} 分钟提醒` : ''}；超时仅提醒`] : [])].join('；'),
         mode: item.mode,
     });
+    /** 条件内只有普通叶步骤时保留原协议；含嵌套条件/并行时保留树，避免旧图把分支误连成一条链。 */
+    const groups = (nodes) => nodes.map(item => {
+        if (item.kind === 'parallel')
+            return { tasks: [], parallel: { title: item.title,
+                    branches: item.branches.map(branch => ({ title: branch.title, groups: groups(branch.nodes) })) } };
+        if (item.kind === 'when')
+            return { condition: conditionName(item.cond),
+                ...(item.steps.every(node => node.kind === 'step' || node.kind === 'ai') ?
+                    { tasks: item.steps.map(node => task(node)) } : { tasks: [], groups: groups(item.steps) }) };
+        return { tasks: [task(item)] };
+    });
     return {
         approval,
         route,
-        groups: route.attrs.nodes.map((item) => item.kind !== 'when'
-            ? { tasks: [task(item)] }
-            : { condition: conditionName(item.cond), tasks: item.steps.map(task) }),
+        groups: groups(route.attrs.nodes),
     };
 }
 /** 从真实驳回结论绑定辨认出口，不依赖阶段标题里是否含有“驳回”二字。 */

package/graph-ui/graph-relations.js

@@ -4,6 +4,7 @@
  * 不求值 handler、映射或审批条件；存在连线只代表对应声明关系，不证明某次操作已发生。
  */
 import { kindLabels, nodeLabel } from './graph-model.js';
+import { approvalRouteNodes, approvalRouteSteps } from './approval-tree.js';
 /**
  * 按真实关系种类解释连线，补充声明来源和证据强度。
  * @param edge 已投影且两端有效的边。
@@ -76,13 +77,14 @@ export function explainEdge(edge, model, labels = {}) {
             const as = edge.as ?? '';
             if (as === '可路由字段')
                 return result('允许审批读取', '审批可用字段', `“${a}”把“${b}”列入 routable，允许该字段作为审批流程变量。`, '明确审批可以拿到哪些业务数据。这里只表示允许使用；是否真的参与分支或审批选人，要查看审批路由的字段关系。', [`${from.id}.routable 包含 ${field}`]);
+            if (as === '催办申请人')
+                return result('确定催办申请人', '流程运营依赖', `“${a}”以提交时“${b}”的用户标识确定可催办申请人。`, '字段必须进入 routable；催办仍校验当前对象可见性、运行节点、业务版本及冷却，不赋予审批权限。字段也可能被选人或条件使用，完整用途见路由声明。', [`route.reminders.requesterField = ${JSON.stringify(field)}`]);
             if (as === '路由条件') {
-                // fieldsUsed 同时包含 when 条件和 deptLeader 选人字段，不能一律解释成条件判断。
+                // fieldsUsed 同时包含 when 条件、部门负责人和单据人员字段，必须区分实际选人方式。
                 const nodes = from.attrs.nodes;
-                const conditions = nodes.filter((n) => n.kind === 'when' && n.cond.field === field);
-                const steps = nodes
-                    .flatMap((n) => (n.kind !== 'when' ? [n] : n.steps))
-                    .filter((s) => (s.approver ?? s.handoff)?.kind === 'deptLeader' && (s.approver ?? s.handoff)?.field === field);
+                const conditions = approvalRouteNodes(nodes).filter((n) => n.kind === 'when' && n.cond.field === field);
+                const steps = approvalRouteSteps(nodes).map(step => ({ ...step, selector: step.kind === 'ai' ? step.handoff : step.approver }))
+                    .filter(step => (step.selector.kind === 'deptLeader' || step.selector.kind === 'field') && step.selector.field === field);
                 const operators = {
                     gt: '大于',
                     gte: '大于等于',
@@ -93,11 +95,11 @@ export function explainEdge(edge, model, labels = {}) {
                     in: '属于',
                 };
                 const reasons = [
-                    ...steps.map((s) => `“${s.title}”步骤根据“${b}”找到对应部门的负责人`),
-                    ...conditions.map((n) => `当“${b}”${operators[n.cond.op]} ${JSON.stringify(n.cond.value)} 时，加入${n.steps.map((s) => `“${s.title}”`).join('、')}步骤`),
+                    ...steps.map((s) => s.selector.kind === 'field' ? `“${s.title}”步骤读取“${b}”保存的审批人员` : `“${s.title}”步骤根据“${b}”找到对应部门的负责人`),
+                    ...conditions.map((n) => `当“${b}”${operators[n.cond.op]} ${JSON.stringify(n.cond.value)} 时，加入${approvalRouteSteps(n.steps).map((s) => `“${s.title}”`).join('、')}步骤（内部顺序或并行关系见路由）`),
                 ];
                 return result(steps.length && conditions.length ? '选人和分支依据' : steps.length ? '确定审批人' : '判断审批分支', '审批路由依赖', `${reasons.join('；')}。`, '字段值会影响审批人或需要经过的审批步骤；修改字段含义时，应一起检查这些路由配置。', [
-                    ...steps.map((s) => `${s.title}: approver.deptLeader(${JSON.stringify(field)})`),
+                    ...steps.map((s) => `${s.title}: approver.${s.selector.kind}(${JSON.stringify(field)})`),
                     ...conditions.map((n) => `when(${n.cond.op}(${JSON.stringify(field)}, ${JSON.stringify(n.cond.value)}))`),
                 ]);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yss123/cage-cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "cage 命令行：init、gen、check、graph、context、impact、test、verify、budget、sync、upgrade、dev、migrate",
   "type": "module",
   "bin": {
@@ -31,11 +31,11 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",
     "zod": "^4.1.5",
-    "@yss123/cage-ontology": "0.3.0",
-    "@yss123/cage-admin": "0.3.0",
-    "@yss123/cage-kernel": "0.3.0",
-    "@yss123/cage-lint": "0.3.0",
-    "@yss123/cage-testkit": "0.3.0"
+    "@yss123/cage-admin": "0.3.2",
+    "@yss123/cage-testkit": "0.3.2",
+    "@yss123/cage-ontology": "0.3.2",
+    "@yss123/cage-lint": "0.3.2",
+    "@yss123/cage-kernel": "0.3.2"
   },
   "devDependencies": {
     "@types/pg": "^8.15.5"

package/templates/app/.agents/skills/cage-development/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: cage-development
+description: 使用 Cage 框架开发、修改和排查业务应用。适用于依赖 @yss123/cage-*、具有 cage.config.json 的项目，与用户澄清需求、比较方案，再完成业务建模、框架接入与验收；维护框架内部实现时先遵守框架仓库的 AGENTS.md。
+---
+
+<!-- 由 scripts/sync-agent-skill.ts 生成；教学正文只在 docs/development 维护。 -->
+
+加载本技能后，先阅读[完整框架开发方法](../../../docs/development/skills/cage-development/SKILL.md)，再根据其中的任务选择表读取相关专题。
+正文包含 Cage 运行模型、与用户澄清业务并选择方案的方法、真实接入、排错与验收；不要只凭本入口的摘要开始编写业务。
+当前项目的业务要求与 AGENTS.md 仍适用，框架维护任务遵守仓库的包边界。

package/templates/app/AGENTS.md

@@ -2,7 +2,7 @@
 
 这是 create-cage-app 生成的业务项目，当前包含采购演示，可逐步替换成客户业务。业务源码在本项目，框架通过 @yss123/cage-* 依赖提供。
 
-先读 [业务开发指南](docs/ai/README.md)，按需求查 [任务配方](docs/ai/recipes.md)、[完整采购范例](docs/ai/purchase-example.md) 和 [错误码册](docs/errors/README.md)。这些资料就在项目内，无需克隆框架仓库。
+先读 [业务开发指南](docs/development/README.md)，按需求查 [任务配方](docs/development/guides/recipes.md)、[完整采购范例](docs/development/examples/purchase-example.md) 和 [错误码册](docs/errors/README.md)。这些资料就在项目内，无需克隆框架仓库。
 
 ## 项目自己的业务约定
 
@@ -10,127 +10,44 @@
 
 本节位于托管区之外，cage sync 会保留。下面的托管区提供框架工作方法。
 
-<!-- cage:begin v0.3.0 -->
+<!-- cage:begin v0.3.2 -->
 ## Cage 业务开发约定（框架托管）
 
-### 先读，再按需求改业务
-
-本项目由 create-cage-app 创建。框架来自 `@yss123/cage-*` 依赖，业务写在本项目；不需要克隆框架仓库，也不要复制框架内部实现。
-
-先读项目说明指定的学习资料，默认入口为 `docs/ai/README.md`。第一次读 `architecture.md`、`project-structure.md` 和 `primitives.md`；具体任务读 `recipes.md`，采购全链路读 `purchase-example.md`，错误查 `docs/errors/README.md` 和 `docs/ai/troubleshooting.md`。资料相对该学习目录，项目说明可指定源码仓库中的规范资料位置。
-
-### 详细中文注释（每次开发必须遵守）
-
-所有新增和维护的手写源码都必须写详细中文注释，先读学习目录中的 `commenting.md`（独立项目为 `docs/ai/commenting.md`）。注释是交付内容，不能以“代码自解释”或“保持简洁”为由省略。
-
-- 每个文件开头说明模块职责、谁调用它、主要调用链和责任边界；纯导出入口也说明如何组合模块。
-- 导出函数、类、组件、hooks、接口和业务声明使用 JSDoc，写清用途、参数含义、返回结果、主要步骤、前置条件、失败行为和副作用；复杂内部函数同样说明。参数类型已表达的语法无需重复，业务单位、空值、默认行为与约束必须解释。
-- 领域代码说明字段和状态的业务意义、命令调用身份与权限/范围、reads 依赖、事件用途、事务与异步边界、幂等/重试及资源释放；只写实际声明和实现已有的保证。
-- 页面说明 URL/查询参数、数据来源、临时状态、加载/空态/失败/无权限、提交后的刷新、会话与订阅清理；复杂分支、计算、顺序、并发和缓存规则在附近解释原因与过程。
-- 测试说明场景、前置条件、动作、断言和所防止的回归；脚本说明输入、读写路径、执行顺序、外部副作用与退出条件。注释不含密钥、凭据或个人数据。
-- 注释同时回答“做什么、为什么、如何完成、有哪些边界”，不能只有一句标题，也不能机械逐行翻译、凑字数或批量粘贴空泛模板。代码变更时同步更新注释，交付前逐文件核对。
-- 生成契约的注释由生成器维护，不手改生成物；已执行/已发布迁移不能改写。仅补注释时不得顺便重构或改变逻辑、接口、配置值和运行文案。
-
-### 原生 AI 能力入口
-
-遇到以下需求，先读 `docs/ai/intelligence.md`，用 `pnpm exec cage capabilities "关键词" --format json` 核对当前安装版本的公开 API，再检查本项目 domain 导出和页面接入。关键词可直接使用下表需求名称；未命中时缩短关键词或查公开符号，不能据此断言能力不存在。
-
-| 需求 | 框架入口与应用职责 |
-| --- | --- |
-| AI审批 / 智能审批 | 现有 `step` 使用 `kind: 'ai'`，支持 pass 通过、return 退回修改、manual 转人工；应用声明策略、结论命令、自动执行角色及接管人 |
-| 业务助理 / 本体助理 | 导出 `ai({ models, assistant })`；框架提供执行循环、按领域声明生成的工具、会话、偏好记忆和 HTTP；应用配置授权及界面 |
-| 页面上下文 / 随页助理 | `useAssistant(client.ai, page)` 配合 `useAiPageContext` / `AiPageContext`；应用上报页面、对象、选中项和草稿，服务端重读并校验业务事实 |
-| 模型管理 / Responses | `managedModel` 接入 Admin 动态配置，支持 Chat Completions / Responses；应用配置部署加密密钥并显式授权管理者 |
-| 性格 / 流式输出 | Admin 管理性格，SDK 提供选择、增量文字与执行进度；应用实现悬浮窗、Markdown 和确认卡片 |
-| 上下文预算 | `ai({ context: ... })` 的配置形状见 `AiContextOptions`；框架按预算选择完整工具或发现模式，历史和本体按需读取 |
-
-前端只使用客户端、协议与契约；后端循环、通用工具和记忆使用框架实现。页面快照和性格不授予权限。分别核对**框架支持**（公开导出）、**项目已启用**（domain 导出、迁移、模型、权限、worker、SDK）和**实际验证通过**（真实角色与模型联调）；空白模板的参考代码不表示已启用。具体接入顺序和验收步骤见该指南，不必将整份指南塞入每次任务上下文。
-
-### 业务代码放在哪里
-
-| 位置 | 职责 |
-| --- | --- |
-| `packages/domain/src/modules/<业务>` | 同业务聚合、状态、命令、事件、审批、查询、任务；模块 index.ts 公开导出 |
-| `packages/domain/src/workflows`、`integrations` | 跨模块反应 / 第三方协议与映射；不堆到全局 reactions.ts、queries.ts |
-| `packages/domain/src/index.ts` | 统一导出全部业务及组织模型；没导出的声明不会注册 |
-| `packages/contracts/src/aggregates/<聚合>`、`queries` | 生成协议；根 index.ts 提供 @app/contracts 公共入口，只用 cage gen 更新 |
-| `apps/api/src` | API/worker 薄启动入口，普通业务不手写 HTTP 路由 |
-| `apps/web/src/app` | 会话、URL 路由、布局、模块组合；main.tsx 只挂载和装配 Provider |
-| `apps/web/src/modules/<业务>` | 页面、表单、专用 hooks/API/样式；从模块 index.ts 暴露页面 |
-| `apps/web/src/shared` | 跨模块复用且不绑定业务的 UI、hooks、纯辅助函数 |
-| `db/migrations` | 审查过的结构迁移，作用于已配置的数据库 |
-| `cage.config.json` | 项目路径、检查配置、graph.labels 中文图谱名称 |
-| `.env` | 本机真实连接和密钥；不提交、不输出完整内容 |
-
-新增业务不得继续平铺在 src 根目录。前端模块只依赖自己和 shared，由 app 通过公开入口组合；shared 不反向依赖业务。领域模块间确有读取依赖时走目标模块 index.ts；跨模块反应写 workflows。小模块不创建空层级，已有独立职责再拆文件。完整命名、目录树和示例见 `docs/ai/project-structure.md`。新模板启用 `structure: modular`，check/verify 检查目录和导入边界，遇到 CAGE-STRUCT 错误按职责修正。
-
-### 实现一项需求的顺序
-
-1. 先运行 `pnpm exec cage context "需求关键词"`；按需 `graph search` 查候选、`graph inspect` 查完整节点、`graph path` 看关系路径。确认中文匹配入口后按源码位置阅读实现；候选和子图不是全部依赖，具体条件不能凭连线推断。完整用法见 `docs/ai/ontology-context.md`。从用户需求确定字段、状态/动作、角色/范围、约束与后续动作；能由业务声明表达的不改框架。
-2. 已有业务含义变化时，修改前用 `pnpm exec cage snapshot save before-change` 保存不可覆盖的命名基线；或使用真实 Git 提交/独立本体图文件。
-3. 先声明 aggregate/states/command/constraints/event，再写 handler、reaction/query/approval/connector，最后接业务页面。声明使用模块顶层 `export const`，从 domain 入口导出，跨文件导出名保持唯一。
-4. 运行 `pnpm exec cage check` 和 `pnpm gen`，审查 contracts 和迁移草稿。按需运行 `pnpm exec cage impact --snapshot before-change`，补中文图谱名。
-5. 页面使用生成方法并处理 code/domainCode；列表、详情等多页面注册到 React Router，Link/NavLink 导航，筛选/分页进入 URL。组件状态用于弹窗和表单等临时交互。新增能力由管理员授权。数据库结构变化审查后显式 `pnpm migrate`，dev 不代办迁移。
-6. 按 `commenting.md` 逐文件检查详细中文注释与实现一致，再按改动运行必要验证；交付时说明体验步骤、授权配置、迁移、注释覆盖，以及通过/跳过/未执行项。
-
-### 必守边界
-
-- 聚合定义对象字段、状态、范围字段与不变量；命令是业务写入口。handler 只计算业务变化和读取 reads 中的依赖，不直接操作数据库、网络或文件。
-- 对象关系统一放在 fields：ref 为外键，hasMany 为只读反查，manyToMany 自动生成中间表并随所属对象命令提交。前端用生成的 related 方法分页读取；不手写纯中间表聚合，不把单页结果当完整集合替换。完整例子见 docs/ai/relations.md。
-- command 的 input 使用 Zod；已有记录输入必须含 id。from/to 表达状态迁移；`to: null` 只适用于已有记录并保留状态，不能靠 handler 改 status 绕过状态机。
-- 写入、审计、版本、幂等和事务交给内核；不要在业务项目重建 repository、连接池或权限流水线。
-- 自定义查询声明 reads，二选一使用 sql/build，只读 `safe.*`；值参数化。不得拼接 SQL、查询基表绕过范围或硬编码密钥。
-- scope 描述范围字段，角色数据决定实际范围；`scope.none()` 不代表所有人可访问。`can/useCan` 只控制按钮，后端负责授权。
-- 前端从 `@app/contracts` 导入生成 API/类型，按需使用 `@yss123/cage-client`；不导入 domain、内核或数据库包。
-- 多页面业务必须有独立 URL，不用 useState/tab 模拟整页导航；详情从 URL 取 ID 并独立加载。前端路由集中在 app，页面从模块公开入口接入 Outlet。登录后保留原路径/query/hash，401 回登录，403 展示权限提示；/admin/ 使用普通链接进入独立系统管理。前端路由不替代后端授权。实现、SPA 部署回退和浏览器配方见 docs/ai/routing.md。
-- 跨聚合写入通过 reaction 调用命令。`tx: 'same'` 共同提交/回滚，默认 outbox 异步执行。资源 acquires/releases 是图规则标签，实际占用/释放仍由命令完成；离开持有状态要检查每条释放路径。
-- 批量调用同一命令使用 reactionEach，声明 maxItems、唯一排序字段 orderBy、items 和 map；稳定键排序后串行执行。步骤依赖用 order，同事件同事务分组不得混用有序/无序或重复顺序。保持同事务回滚边界，见 docs/ai/primitives.md。
-- 审批通过 approval + route 配置，结论是 process 命令；选中审批人不等于已具备能力、范围和额度。第三方 IO 通过连接器，回调验签后调用 external 命令。
-- job 的读取与调用必须列入 reads/calls。业务导入/导出放在需要的业务页面调用通用任务接口，202 只代表任务已接受；worker 必须运行。
-- 已部署事件只做兼容扩展；新增字段设为 optional，不兼容含义用新事件。已执行/已发布迁移不能改写，结构更新新增迁移。
-- 不手改生成物，不关闭门禁掩盖错误，不因方便自动授予生产角色新能力。unsafe 必须写明 reason/owner，不能替代普通业务声明。
-- 按前述详细中文注释规范完成文件、API、业务声明和关键流程说明；避免无业务价值的防御分支和静默兜底。维护脚本用 TypeScript，不新增 .mjs。
-
-### 最小命令形状
-
-```ts
-// 片段：Order 为已导出的聚合，OrderSubmitted 为事件，业务校验按需求添加。
-/**
- * 将草稿订单提交审批：只有 draft 可进入 pending_approval。
- * 入口使用 Order.submit 能力，真实授权、范围、状态和版本由内核检查；声明本身不自动授予权限。
- * handler 返回草稿供后续校验和持久化，OrderSubmitted 随命令事务登记，后续由已配置消费者处理。
- * 失败不会提交这次业务变更；事件已登记也不代表后续审批已经完成。
- */
-export const submitOrder = command(Order, {
-  name: 'submit',
-  from: 'draft',
-  to: 'pending_approval',
-  emits: [OrderSubmitted],
-  handler: (draft) => draft,
-});
-```
-
-完整可添加的普通管理对象见 `docs/ai/primitives.md` 的 Note；采购模板的审批、资源、第三方示例在 `packages/domain/src`，空白模板的参考源码在 `docs/examples/purchase-admin`。先读本项目 AGENTS.md 中的模板说明，区分运行代码与参考资料。API 以当前包公开导出和生成契约为准，不发明不存在的配置和方法。
-
-### 启动、验证与排错
-
-在项目根目录执行：首次 `pnpm install`，复制并编辑 .env.example，仅提供已有库管理员连接后 `pnpm exec cage init`；再 `pnpm build:app`、`pnpm gen`，审查后 `pnpm migrate`；用 `pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json` 显式初始化组织，最后 `pnpm dev`。已有配置不能覆盖，凭据文件必须是新受限文件且父目录存在。
-
-init 只准备账号/schema/授权并填写三个连接，不创建数据库；APP/READ/MIGRATE 指向同一个库。已有集群账号复用原密码，日常启动不用管理员。普通项目不新增 Docker 生命周期命令。
-
-API 日常启动不初始化组织、不输出管理员密码；生产缺少合格 Cookie 密钥会拒绝启动。bootstrap 不自动授予业务能力。`/healthz` 只表示存活，`/readyz` 检查必要依赖。首阶段 API 与 worker 同版本部署，查看实际注册指纹和消费者心跳。
-
-- `pnpm exec cage graph`：浏览器图谱，默认端口 15418，以终端为准。
-- `pnpm exec cage context command:对象.命令 --format json --out .cage/context.json`：按完整 key 取精简上下文；默认 Markdown，可用 --depth/--limit 调整范围。CLI 每次重新抽取；Web“复制 AI 上下文”使用当前页面快照，改代码后先刷新图谱。
-- `graph inspect/path` 有歧义时复制候选完整 key；path 默认沿箭头，--direction both 的逆向遍历不表示执行方向。报告中的测试/前端文件是候选，须核对；context 与图谱查询不覆盖当前图或命名快照。
-- `pnpm exec cage capabilities 关键词 --format json`：查当前安装版本公开签名；`cage doctor`：区分注册、生成、构建、迁移、授权与实际进程证据，unknown 不能当作通过。`cage timeline/explain` 关联实际异步证据与解释授权，参数和权限见 docs/ai/diagnostics.md。
-- 生成方法支持 signal/timeoutMs/idempotencyKey 请求选项。底层 CageResult 与 mutation 行为有区别：useCageCommand 失败抛 CageCommandError，成功才返回业务数据。订阅 client.subscribe 在退出、401、切换账号时取消查询并清除应用缓存。
-- `pnpm exec cage gen --check`：生成一致性；`pnpm exec cage sync --check`：本托管区一致性。
-- `pnpm exec cage test --only project`：业务测试；`pnpm verify`：类型、依赖、lint、图规则、生成、托管区、预算和测试。
-- `pnpm exec cage verify --skip-tests` 表示不完整门禁；派生测试跳过不能当作通过。测试连接只用独立测试集群。
-- 重要业务改动验证成功路径及有风险的反例；文档或可逆的小改动不反复跑全量数据库测试。
-- 修改页面/导航后实际验收深链接、刷新、前进后退、登录回跳、无权限和 404；生产再查 SPA 回退。check/verify 不自动完成浏览器验收，未执行要明确报告。见 docs/ai/routing.md。
-- CLI 报错先看 code/at/reason/fix，再查错误码册；HTTP 错误查 runtime.md。异步失败先看 worker、同步记录和死信，修复后重放，不能直接 SQL 改状态。
-
-框架托管区由 cage sync 更新；项目独有的业务规则写在标记之外，避免升级覆盖。
+### 学习与任务入口
+
+本项目使用 `@yss123/cage-*`，业务写在本项目。先读项目说明指定的教材；独立项目默认入口是 `docs/development/README.md`。
+
+开始 Cage 业务开发或排错时，加载 `docs/development/skills/cage-development/SKILL.md`。它讲清运行模型、业务澄清、能力选择、实施与验收方法；首次学习配合 `docs/development/getting-started/first-feature.md`。已熟悉时只读受影响专题，普通样式/文案改动无需重走业务建模。
+
+支持 Agent Skills 的工具可发现 `.agents/skills/cage-development`；其他工具直接读取上述 Markdown，使用相同流程。教材随框架版本分发，均为本地文件，不需要额外服务、模型或索引。框架仓库范例使用项目说明指定的规范教材位置。
+
+### 框架执行什么
+
+- 业务声明从 domain 总入口导出，框架据此构建注册表、能力、HTTP 接口、本体图、契约与迁移草稿；只有文件而未导出不会生效。
+- 命令是业务写入口；handler 描述变化与显式 reads，内核处理授权、状态、范围、版本、事务、审计及 outbox。读侧通过生成契约或 query 的安全视图，外部 IO 通过连接器。
+- 角色、能力、数据范围、调用身份与业务约束分别建模。前端 can() 只影响显示，新增能力不自动授给生产角色；审批选人不授予能力。
+- 页面依赖生成契约及客户端。表单、弹窗等临时状态留在前端；正式业务数据和流程结果通过服务端读写。实际记录不能用模拟仓储或固定统计替代。
+
+### 实现与排错
+
+1. 阅读需求、文档和现有实现后，按 `docs/development/guides/business-collaboration.md` 主动提出疑点、可行选项、影响与推荐理由，让用户选择业务规则；沿用已明确的选择与授权，等待回答时推进独立部分，可选建议不阻塞已明确任务。再把确定的规则映射到聚合、命令、归属/范围、后续行为与验收，沿已有模块修改。具体选择看 `docs/development/guides/recipes.md`，目录归属看 `docs/development/reference/project-structure.md`。
+2. 不熟悉的 API 先按手册任务目录定位，用本地文件搜索查术语，再执行 `pnpm exec cage capabilities 符号 --format json` 核对当前版本签名；`cage context "业务关键词"` 定位当前应用。未命中不代表不支持，不发明方法或返回字段。
+3. 涉及已有领域含义变化，先 `pnpm exec cage snapshot save before-change` 保存本体基线，或使用真实 Git 基线。修改声明与导出，运行 check/gen，审查契约和迁移草稿。生成物不手改，已执行迁移不可改写。
+4. 页面使用真实契约，处理业务失败、版本冲突、会话与缓存；多页面使用独立 URL，列表筛选/分页进入查询参数。按 `docs/development/guides/routing.md` 验收深链接、刷新、登录回跳和无权限行为。
+5. 出错保留 code/at/reason/fix，查 `docs/errors/README.md` 与 `docs/development/tools/troubleshooting.md`；从真实调用逐层定位。不得放宽权限、删约束或关闭门禁来掩盖问题。
+
+遇到原生 AI、AI 审批或随页助理，先读 `docs/development/guides/intelligence.md`，核对已有能力及应用启用状态。审批、文件、关系、数据传输等专题由 Skill 按需引导，不重建框架已有运行时。
+
+### 代码与环境边界
+
+- 所有手写代码遵守 `docs/development/reference/commenting.md`：文件职责与调用链、导出 API/字段、复杂分支的中文说明，写清做什么、为什么、怎样完成及实际边界；随代码更新。生成物注释从生成器维护。
+- domain 按 modules/workflows/integrations/shared 组织，Web 按 app/modules/shared 组织。模块通过 index.ts 公开入口组合，前端不导入 domain、数据库或内核运行时；不关闭 modular 目录门禁。
+- 新项目启动步骤见 `docs/development/getting-started/workflow.md`。使用已有 PostgreSQL 和项目 .env；init 准备账号，migrate 更新结构，bootstrap 显式初始化组织，dev 启动进程。普通业务不新增连接池或管理 Docker。
+- 不输出或提交 .env、数据库密码、Cookie 密钥及初始化凭据。API 与 worker 使用一致的 domain，修改配置后按实际需要重启。
+
+### 完成依据
+
+验证与改动匹配。check/gen/typecheck/build 证明各自检查范围；业务读写还需独立读取结果，权限需直接请求验证，审批需待办与结论，文件需实际内容，异步需任务终态，页面需浏览器操作。
+
+`pnpm verify` 汇总门禁；`verify --skip-tests` 不代表完整通过。诊断用 `cage doctor`、`timeline`、`explain`，具体前提见 `docs/development/tools/diagnostics.md`。交付分别说明通过、跳过、未执行及剩余配置；文档和可逆小改动不反复执行全量数据库回归。
 <!-- cage:end -->

package/templates/app/CLAUDE.md

@@ -0,0 +1,6 @@
+<!-- 由 scripts/sync-agent-skill.ts 生成；共享同一套框架教材。 -->
+# Cage 开发入口
+
+先读本目录 [AGENTS.md](AGENTS.md) 的项目说明和约定。
+进行 Cage 业务开发或排错时，阅读[框架开发 Skill](docs/development/skills/cage-development/SKILL.md)，按任务选择章节并完成对应验证。
+这是框架维护的通用教学流程；具体业务以用户需求和项目约定为准。

package/templates/app/README.md

@@ -4,9 +4,9 @@
 
 ## 让 AI 在本项目开发业务
 
-把本目录交给 Codex 等编程工具时，先让它读 [AGENTS.md](AGENTS.md)，再按[业务开发指南](docs/ai/README.md)和[任务配方](docs/ai/recipes.md)实现需求。普通业务不需要修改框架源码。
+把本目录交给 Codex 等编程工具时，先让它读 [AGENTS.md](AGENTS.md)，再按[业务开发指南](docs/development/README.md)和[任务配方](docs/development/guides/recipes.md)实现需求。普通业务不需要修改框架源码。
 
-[采购全链路导读](docs/ai/purchase-example.md)说明每个文件和异步步骤；[原语与最小业务](docs/ai/primitives.md)提供可添加的普通管理对象；[错误码册](docs/errors/README.md)用于按码修复。脚手架会将这些资料放入生成项目本地的 `docs/ai` 与 `docs/errors`，无需再次克隆框架。
+[采购全链路导读](docs/development/examples/purchase-example.md)说明每个文件和异步步骤；[原语与最小业务](docs/development/reference/primitives.md)提供可添加的普通管理对象；[错误码册](docs/errors/README.md)用于按码修复。脚手架会将这些资料放入生成项目本地的 `docs/development` 与 `docs/errors`，无需再次克隆框架。
 
 ## 启动
 
@@ -54,15 +54,16 @@ pnpm dev
 
 ## 体验完整采购流程
 
-前端使用 React Router：工作台 `/workspace`，采购列表 `/procurement/orders`，单据详情 `/procurement/orders/:id`，审批 `/approvals`，库存 `/inventory`，登录 `/login`。单号和审批待办可直接打开详情；刷新、前进后退和登录回跳保留页面地址。新增页面与部署按[路由和浏览器验收指南](docs/ai/routing.md)执行；Nginx 示例见 [deploy/nginx.conf](deploy/nginx.conf)。
+前端使用 React Router：工作台 `/workspace`，采购列表 `/procurement/orders`，单据详情 `/procurement/orders/:id`，审批 `/approvals`，库存 `/inventory`，登录 `/login`。单号和审批待办可直接打开详情；刷新、前进后退和登录回跳保留页面地址。新增页面与部署按[路由和浏览器验收指南](docs/development/guides/routing.md)执行；Nginx 示例见 [deploy/nginx.conf](deploy/nginx.conf)。
 
 1. 管理员在“库存台账”登记 `A-01` 等物料。
 2. 进入 `/admin/` 创建采购员、经理，分别分配采购命令和审批能力；经理的 `PurchaseOrder.approve` 参数配置 `ceiling`。
 3. 把经理设为采购员所在部门的负责人。提单人与审批人必须不同。
-4. 采购员新建并提交采购单；worker 建立审批待办。
-5. 经理在“审批待办”通过，内核同事务生成库存锁；worker 调用 fake ERP 并回写单号。
-6. 超过 50,000 元的采购走财务第二步，需另建 code 为 `finance` 的角色并分配审批人。
-7. 取消单据或收到 ERP 收货回调后，通过异步反应释放锁。回调需要 `ERP_WEBHOOK_SECRET` 对原始 JSON 的 HMAC-SHA256 签名。
+4. 为需要选人的采购参与者授予 `ApprovalMember.read` 与该聚合 `all` 范围，通过 `ApprovalMember.create` 登记审批协作人的公开业务姓名与专业领域；名录不授予实际审批能力。
+5. 采购员新建采购单，可开启专业复核并选择 1–5 人；草稿使用 `PurchaseOrder.setReviewers` 调整名单，提交时重新校验。worker 先执行 AI 材料预审；未配置模型或模型失败时按声明转人工接管。
+6. AI 预审/人工接管之后进入经理节点；启用专业复核时，经理后由所选人员全部会签。经理、专业和财务节点开放转办、委派归还和前置/后置/并行加签。
+7. 超过 50,000 元的采购继续进入财务共享候选池，需另建 code 为 `finance` 的角色并给实际用户配置权限、范围和额度；财务必须先领取，恰好 50,000 元跳过该步骤。
+8. 全部必签完成后，最终审批命令同事务生成库存锁；worker 调用 fake ERP 并回写单号。取消单据或收到 ERP 收货回调后异步释放锁；回调需要 `ERP_WEBHOOK_SECRET` 对原始 JSON 的 HMAC-SHA256 签名。
 
 `Inventory.available` 是演示台账数量。本例验证库存锁生命周期，尚未实现仓库级的并发扣减、实物库存及退货核算。
 
@@ -86,6 +87,6 @@ pnpm dev
 - `apps/api/src`：API 和 worker 的薄启动入口。
 - `apps/web/src/app`、`modules`、`shared`：应用组合、业务页面、共享基础组件；`main.tsx` 只挂载。
 
-新增业务先读[工程目录与代码组织](docs/ai/project-structure.md)，不要继续在 src 根目录平铺文件。模板已启用模块目录门禁，`cage check` 和 `verify` 会指出目录与依赖越界。
+新增业务先读[工程目录与代码组织](docs/development/reference/project-structure.md)，不要继续在 src 根目录平铺文件。模板已启用模块目录门禁，`cage check` 和 `verify` 会指出目录与依赖越界。
 
 先运行 `pnpm cage gen` 再提交契约和迁移草稿；`pnpm cage verify` 检查完整工具链。派生测试遇到无法推断的业务输入会显示跳过，`purchase-order.test.ts` 另外准备真实业务数据覆盖成功审批和约束反例。

package/templates/app/apps/api/package.json

@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@app/domain": "workspace:*",
-    "@yss123/cage-http": "0.3.0",
-    "@yss123/cage-connectors": "0.3.0"
+    "@yss123/cage-http": "0.3.2",
+    "@yss123/cage-connectors": "0.3.2"
   }
 }

package/templates/app/apps/web/package.json

@@ -10,7 +10,7 @@
   "dependencies": {
     "@app/contracts": "workspace:*",
     "@tanstack/react-query": "^5.87.1",
-    "@yss123/cage-client": "0.3.0",
+    "@yss123/cage-client": "0.3.2",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "react-markdown": "^10.1.0",