@yss123/cage-cli 0.3.1 → 0.4.0

package/templates/blank/docs/{ai → development/guides}/approvals.md

@@ -1,6 +1,18 @@
 # 审批任务流转、并行分支与流程时效
 
-[返回学习入口](README.md) · [审批原语](primitives.md) · [AI 审批](intelligence.md)
+## 第一次接入审批
+
+审批负责谁在什么步骤作出决定，业务状态由领域结论命令落实。先完成下列最小链路，再按需要阅读后面的并行、加签与时效选项。普通自动状态变化直接使用命令和反应，无需套审批。
+
+1. 业务对象有草稿、待审批和相应结论状态。提交命令声明 emits 并成功发出提交事件；通过/拒绝等结论声明为 process 命令。
+2. approval 绑定提交事件、结论命令和取消事件，route 定义步骤与选人；两者都从 domain 入口导出。routable 只包含选路和任务需要的业务快照字段。
+3. 配置实际负责人/角色成员，并分别授予所需能力和范围；声明 role code 不会创建角色或分配人员。检查迁移和运行中的 worker。
+4. 页面先通过业务契约提交，再读取真实待办，通过公开任务接口携带当前 revision 作出决定。业务列表中的“待审批”不等于当前用户拥有待办。
+5. 观察提交事件、待办、决定与领域最终状态；用不合格主体验证拒绝，按需求验证撤回。缺少待办时按[排错方法](../tools/troubleshooting.md)查具体断点，不直接把单据改成通过。
+
+完整跨文件参考见[采购导读](../examples/purchase-example.md)，基础声明见[审批绑定与选人](../reference/primitives.md#审批绑定与选人)。本页后续的客户端操作是接入片段，业务符号与 UI 需来自当前应用。
+
+[返回学习入口](../README.md) · [审批原语](../reference/primitives.md) · [AI 审批](intelligence.md)
 
 本页描述 Cage 原生审批引擎的顺序/条件/结构化 AND 并行、字段选人、候选领取/释放、转办、委派归还、前后/并行必签、操作记录，以及框架通用的自然分钟时限、站内提醒和申请人催办。它参考 Flowable 的任务责任划分和并行汇合语义，不表示支持全部 BPMN 或与 Flowable XML 兼容。
 
@@ -36,7 +48,7 @@ step('专业审核', approver.field('reviewers'), {
 
 字段缺失或为 `null` 时解析为空候选，开启节点报 `CAGE-APPR-007`；空数组、非法 UUID、数组中包含非字符串或超过 200 项报 `INVALID_INPUT`。开启字段选人或候选节点时，所有选中的 ID 必须属于当前租户且账号 active，否则整批失败，不静默去掉无效人员或默认批准。旧的固定用户/部门负责人直派规则保持原有开启行为。
 
-开启节点的账号校验不会替用户授予批准/read 能力或数据范围。领取、转办、委派、加签和实际决定仍按当时的权限核验；配置了有效用户也不代表其最终额度、职责分离等业务硬约束一定满足。
+开启节点的账号校验不会替用户授予批准/read 能力或数据范围。领取、转办、委派、加签和实际决定仍按当时的权限核验；配置了有效用户也不代表职责分离等业务硬约束一定满足。
 
 ## 结构化并行分支与 AND 汇合
 
@@ -73,7 +85,7 @@ export const documentRoute = route('document-review', [
 
 拒绝、退回或取消结束整个审批轮次，关闭其他分支中的活动节点和 pending/waiting 任务；尚未开启的后续节点不再创建。正常推进在实例锁内检查持久前驱状态，节点唯一键防止并发分支重复创建同一汇合后继。若同一次启动或推进中的任一新节点无法开启，整个本次事务回滚，不留下部分成功的分支入口。已经在较早事务中通过的票仍保留。
 
-最终业务结论仍以实际推进完成的办理人身份调用领域命令。并行组后没有明确的最终审批节点时，最后完成分支的人可能承担该身份；额度、职责分离或状态约束不满足会回滚本次决定。需要固定最终责任人时，应像上例一样在 AND 汇合后声明明确的最终节点。
+最终业务结论仍以实际推进完成的办理人身份调用领域命令。并行组后没有明确的最终审批节点时，最后完成分支的人可能承担该身份；职责分离或状态约束不满足会回滚本次决定。需要固定最终责任人时，应像上例一样在 AND 汇合后声明明确的最终节点。
 
 ### 快照、历史和界面定位
 
@@ -128,7 +140,7 @@ waiting 任务只能查看，不能决定或执行任务管理动作。前签完
 
 任一当前可决定的任务拒绝或退回，会调用原有领域结论命令；成功后关闭同轮次剩余 pending 和 waiting。取消或重新提交也会关闭旧轮次两种状态的任务。不能通过释放仍带未完成前/后/并行子票的候选任务来丢弃必签责任。
 
-最终推进流程的实际决定人必须通过领域结论命令的额度、职责分离、状态和版本约束。后签人可能成为最终签署人；若其额度不足，最后决定、版本、阶段变化及本次历史共同回滚，之前已提交的父票保留。引擎不会自动改用更早审批人的身份。
+最终推进流程的实际决定人必须通过领域结论命令的职责分离、状态和版本约束。后签人可能成为最终签署人；若其不满足职责分离，最后决定、版本、阶段变化及本次历史共同回滚，之前已提交的父票保留。引擎不会自动改用更早审批人的身份。
 
 ## 客户端调用
 
@@ -190,13 +202,11 @@ if (candidates.ok && candidates.data.length) {
 
 框架 Admin 用同一收件箱表格展示本人、可领取和等待加签任务及各类数量；采购范例提供“待我处理 / 可领取 / 等待加签”三个视图。两者都有领取、释放、受托任务归还及正常决定入口。waiting 仅展示，不显示决定按钮；候选和受托任务分别显示领取、归还入口。采购 `/approvals` 用 `view=candidates`、`view=waiting` 保存视图，默认本人待办不需要 view 参数。界面可提示操作，未完成子票等动态限制仍由服务端拒绝。
 
-采购范例后续已接入协作名录选人、转办/委派/三种加签及分页人工操作历史，详见 [采购导读](purchase-example.md)。框架 Admin 保留通用任务收件箱，启用审批运营后新增“我的申请”和“流程提醒”，不依赖采购的页面、名录或额外业务字段。框架支持、应用路由启用、浏览器验收仍是不同状态。
-
-本批真实 PostgreSQL/HTTP 定向回归共 144 项通过、最终 0 跳过：新增候选/签序 38 项、既有人员动作 27 项和内核/HTTP/AI/恢复 79 项。先执行六文件 143 项，再补旧实例签序权限用例并复跑两个审批文件 65 项，重复用例不累加。包含 8 人抢领、超过五连接池容量的并发、字段非法/停用/跨租户、动态候选身份、前后签 any/all、取消、领域命令失败回滚和真实旧库升级。首次内嵌测试数据库短暂拒绝连接造成的跳过，已由后续完整执行覆盖；该次跳过不计入通过。
+采购范例包含协作名录选人、转办/委派/三种加签及分页人工操作历史，详见 [采购导读](../examples/purchase-example.md)。框架 Admin 提供通用任务收件箱，启用审批运营后提供“我的申请”和“流程提醒”，不依赖采购的页面、名录或额外业务字段。框架支持、应用路由启用、浏览器验收仍是不同状态。
 
-上述第二批基础页面曾使用真实构建和内存 HTTP 夹具验收；后续采购场景已另做真实隔离 PostgreSQL、API、worker 和账号登录的浏览器验证。各次记录不累加为全部功能验收；本页 API 说明也不能代替部署后的实际验证。
+应用接入需检查真实角色、路由、迁移、worker 与浏览器路径，覆盖相关成功和拒绝场景；框架历史回归结果不能代替当前应用验收。
 
-尚未实现受限岗位规则、代理时间段、嵌套委派、无可用人员的通用恢复、减签/撤销加签、任意串行加签链、指定节点退回、任意流程图/循环/OR 网关、工作日计时、自动升级、抄送、邮件/短信通知和可视化运行时设计器。应用接入仍需检查真实角色、路由、迁移与浏览器路径；上述历史测试数量不作为本次 AND 并行的验证数量。
+尚未实现受限岗位规则、代理时间段、嵌套委派、无可用人员的通用恢复、减签/撤销加签、任意串行加签链、指定节点退回、任意流程图/循环/OR 网关、工作日计时、自动升级、抄送、邮件/短信通知和可视化运行时设计器。
 
 ## 框架通用时限、提醒与催办
 

package/templates/blank/docs/development/guides/business-collaboration.md

@@ -0,0 +1,65 @@
+# 业务澄清与共同设计
+
+[返回学习入口](../README.md) · [框架开发 Skill](../skills/cage-development/SKILL.md) · [业务设计与能力选择](recipes.md)
+
+用户可能只有一个目标，业务文档也可能有遗漏、歧义或相互冲突的规则。agent 阅读后应主动提出疑问和建议，帮助用户比较方案、作出选择，再把选择落实为 Cage 业务声明与验收结果。本页用于开发时的协作，不是应用内 AI 助理的交互协议。
+
+## 先核对事实，找出需要共同决定的事
+
+先读当前对话、项目业务约定和受影响的源码，区分“用户希望怎样”“文档约定怎样”“系统现在怎样”。已经明确的需求沿用；用户明确要求改变旧规则时说明影响并执行，不因为旧文档不同而重复请求同一决定。
+
+主动检查对象和术语、参与人及范围、状态与动作、金额/数量/时间口径、失败与撤回、页面体验和验收标准。只检查本次相关内容，不要求用户先填写一份完整问卷。发现疑点应尽量说明具体位置和影响，不把未说明的内容当作默认允许，也不照搬采购示例中的规则。
+
+| 发现的情况 | agent 如何处理 | 用户需要决定什么 |
+| --- | --- | --- |
+| “大额需审批”“负责人可见”等描述有多种解释 | 指出缺失的阈值、负责人来源或可见范围，列出可行理解及影响 | 业务口径与希望的行为 |
+| 业务文档互相矛盾，或与现有行为不一致 | 引用冲突位置，说明当前实现；已有明确新要求时直接采用，否则给出调整方案 | 哪条规则应作为目标，变更适用范围 |
+| 框架文档写法不清、签名或版本不一致 | 按[能力诊断](../tools/diagnostics.md)核对安装版本、公开导出与实现，说明查证结果和仍不确定的部分 | 仅在影响业务目标或实现范围时选择方案；API 是否存在由证据确定 |
+| 需求无法由当前能力直接表达 | 说明缺口，比较已有能力可实现的方案、应用扩展或框架扩展及成本；只提供有依据的选项 | 保留目标并扩展、接受明确的行为调整，或延后相关部分 |
+| 规则可实现，但存在更清楚的使用方式或遗漏的失败体验 | 提出具体建议，解释收益和额外工作，标明是可选改进 | 是否纳入本次；未采纳不妨碍已明确工作 |
+| 命名、目录归属、普通组件组织等技术选择 | 按项目约定和框架指南自行解决；有实质业务影响时再说明 | 通常无需选择实现细节 |
+
+代码能说明当前行为，框架文档能说明能力边界，都不能单独证明用户希望的业务。查证不能解决的业务疑问要提出；已经查明的技术事实不转交用户猜测。资料确有错误时指出来源，在任务授权范围内修正或记录，不把猜测写成已实现能力。
+
+## 每次提问都帮助用户作选择
+
+一个有用的问题通常包含以下内容，按复杂程度合并表达即可：
+
+1. **疑点与依据**：哪句话、哪段规则或哪个现有行为有问题，以及为什么会影响结果。
+2. **选项与影响**：给出少量可行方案，通常两到三个；说明用户能观察到的区别，以及必要的配置、实现成本或框架限制。允许用户补充其他方案。
+3. **推荐与理由**：结合已知业务、现有实现和框架能力推荐一个方案。缺乏推荐依据时说明还缺什么事实，不为了给建议而编造行业规则。
+4. **本次需要的决定**：明确让用户选择哪个业务规则，以及未决定前哪一部分暂不落实。
+
+例如应问“提交后哪些人可以修改申请”，再由 agent 选择对应命令和状态约束；不要让用户先决定 `from/to` 怎样写。金额阈值、审批人、数据可见范围等也不能从示例或技术便利性推断。
+
+优先提出影响下一步设计的少量问题，相关问题可以合并。其余已发现疑点简短列为后续事项，随工作推进继续澄清；不要为了减少提问而隐去重要疑点，也不要一次倾倒所有可能的问题。用户只回答一部分时，保留这些答案，下一轮只追问剩余的相关事项。
+
+## 在选择中推进实现
+
+- 对需要业务选择的部分，在获得答案前保留为待定；可以继续阅读、核对能力、实现不依赖该决定的部分。不要把待定策略写成生效的权限、金额计算或状态规则。
+- 可选改进单独说明；已明确任务照常推进。不要把每个建议都变成一个必须批准的关卡。
+- 用户已有明确选择、授权或要求“你来定”时，按该范围推进并说明采用的规则。推荐选项、界面预选、等待时间和沉默均不构成新的选择；用户委托决定也不扩大任务或外部操作的授权范围。
+- 实现中发现约定无法落地时，带着实际证据和替代方案回到用户，不默默降低要求。用户改变规则时，先指出受影响的声明、页面、数据和验收，再修改相关部分，无需重新确认无关规则。
+
+简单任务在对话中简短记录即可；需要后续维护的规则写入项目已有业务文档或 AGENTS.md 的托管区外，并从项目入口引用。保留“已确定的规则及依据”“尚待决定的事项”“可选建议”的区别。客户业务事实不写进框架通用教材，也不写进会被 `cage sync` 覆盖的区域。
+
+回答应变成可以核对的业务规则和验收例子，保留来源；不要只记“用户同意方案 A”，丢失选项当时的含义。接着查证现有实现与框架能力，按[编码前的实现映射](recipes.md#写代码前的实现映射)说明如何落到声明、页面、配置和验收，再实施。只有规则已确定而技术做法尚未查清时，继续查证，不把技术猜测混进用户的业务选择。
+
+记录不要求固定文件格式，也不要求每项小改动新增计划文件。已明确的技术方案无需再设一轮批准，普通实现取舍由 agent 负责。
+
+## 示例：文档没有写清金额边界
+
+业务文档写着：“金额低于 5000 元由部门负责人审批；超过 5000 元增加财务审批。”
+
+agent 读后可以提出：
+
+> 这两条规则没有覆盖恰好 5000 元，会影响审批路径。可以选择：
+>
+> - A：满 5000 元就增加财务审批。
+> - B：5000 元仍只由部门负责人审批，超过才增加财务。
+>
+> 我建议 A，让阈值本身也经过财务审核；这是一项待你选择的业务规则。你希望采用哪一种？也可以指定其他边界。
+
+用户选择 A 后，agent 将规则落实为“低于 5000 元仅部门负责人审批；大于等于 5000 元增加财务”，按当前审批能力实现条件，并验证 4999.99、5000、5000.01 元三种输入。金额精度和单位仍沿用项目约定；若尚未约定且影响实现，也应继续提出。
+
+如果文档还没说明财务与部门负责人的先后关系，这仍是独立疑点：说明顺序审批和并行审批的业务区别及当前支持方式，再让用户选择。金额边界已有答案，不再重复询问；选人、授权和真实待办的验收按[审批指南](approvals.md)落实。

package/templates/{app/docs/ai → blank/docs/development/guides}/files.md

@@ -1,6 +1,10 @@
 # 私有文件字段与断点续传
 
-[返回学习入口](README.md) · [原语](primitives.md) · [权限与执行模型](architecture.md)
+先理解三个独立动作：上传原始字节得到文件 ID，业务命令将该 ID 绑定到字段，通过受控下载接口读取内容。只声明 file 字段不会上传文件，只保存文件名也不会保存内容。
+
+第一次接入依次完成本页的声明、客户端上传与授权下载，再增加暂停/续传等交互。验证上传内容与下载内容一致、业务保存失败有明确反馈、范围外主体下载被拒绝；文件目录存在或页面显示附件名都不足以证明链路成功。
+
+[返回学习入口](../README.md) · [原语](../reference/primitives.md) · [权限与执行模型](../getting-started/architecture.md)
 
 文件字节由 `@yss123/cage-files` 管理；业务字段只保存文件 ID。上传完成得到临时文件，业务命令成功后才正式绑定。不要把文件内容、Base64、存储路径或公开 URL 放进业务字段、事件或审计。
 

package/templates/blank/docs/development/guides/frontend-ui.md

@@ -0,0 +1,30 @@
+# React 前端与组件库
+
+本指南约束 Cage 应用中的 AI 生成式 React 开发。AI 在开发阶段根据业务需求编写、修改并验证真实 `.tsx` 页面与组件；运行时仍是普通 React 应用，不引入页面描述语言、schema 渲染器或固定 CRUD 页面模板。
+
+## 组件库选择
+
+Cage Web 默认使用 Ant Design（`antd`）和 `@ant-design/icons`。Ant Design 提供覆盖面完整的 React 控件、中文 locale、表格/表单/反馈组件和成熟文档，适合由 agent 按具体页面组合使用。通用 React 生态中也有 Mantine、MUI 等选择；本仓库采用 Ant Design 是为了统一范例和模板的默认组件接口，不要求业务页面套用某种固定版式。
+
+需要构建对话、消息气泡、提示词或 AI 推理步骤等 AI 原生交互时，可以评估 Ant Design X；普通表单、详情、筛选、数据表格仍使用 `antd`。模板不预装这项可选依赖，只有用户需求确实包含这类交互时才添加。不要把 ProComponents 或整套后台脚手架作为默认页面生成方式；它们的高层 CRUD 约定容易把页面形态固定下来，而真实字段、操作与范围必须由业务需求和 Cage 契约决定。
+
+## 应用入口与调用边界
+
+范例和模板已在 Web 入口安装 `ConfigProvider`、简体中文 locale、共享主题 token 与 Ant Design `App` 上下文。生成组件可从 `antd` 和 `@ant-design/icons` 导入控件；需要消息、通知或确认框时，在 React 子组件中调用 `App.useApp()` 返回的方法，使反馈使用入口提供的上下文。不要在模块中重复创建 Provider，也不要使用无法继承应用上下文的静态反馈 API。
+
+页面仍按 `apps/web/src/modules/<module>` 组织，并从模块公开入口导出，由 `app` 层组合到 React Router。筛选、排序和分页等可分享状态进入 URL 查询参数；列表和详情使用各自稳定 URL。组件状态只保存尚未提交的交互草稿，不代替服务端记录。
+
+业务数据使用生成契约和 Cage Client/现有 hooks：读取经过安全读侧，写操作调用对应命令，并处理 `CageResult`、并发冲突和查询刷新。前端 `can()` 只控制入口或按钮显示，服务端仍执行能力、数据范围和业务状态检查。不得为了让生成页面看起来完整而增加伪造统计、静态仓储或绕开契约的直接数据库访问。
+
+## 生成页面的组合准则
+
+- 先按当前任务选择控件：`Form`/输入组件负责编辑，`Table` 负责需要行列比较的数据，`Descriptions` 负责详情字段，`Tag`/`Badge` 表示已有状态，`Result`/`Empty`/`Skeleton`/`Alert` 分别表达结果、空态、加载和错误。
+- 用 `Layout`、`Flex`、`Grid`、`Space`、`Typography` 和局部 CSS 建立页面层次；页面布局由任务决定，不为每个区块机械套卡片，也不生成与用户目标无关的仪表盘。
+- 优先使用 Ant Design 的 `Button`、`Input` 等组件 props 和主题 token 表达样式与状态。不要把现有业务 CSS 类（如 `.primary`）直接赋给 Ant Design 控件；项目里的旧全局原生按钮规则与其业务类仅服务于原有 DOM 页面。
+- 图标从 `@ant-design/icons` 按需导入；只有图标含义不明确时加 Tooltip，主要操作按清楚的文字命名。
+- 每个页面自行呈现真实加载、空结果、请求失败、无权限和提交中状态；避免通过组件默认值把未知状态渲染成零或成功。
+- 表格给稳定的 `rowKey`，分页与筛选变化同步 URL 和服务端查询；不能只在当前页本地过滤服务端分页结果。
+- 表单校验帮助使用者尽早发现输入问题，不能取代服务端 schema、领域不变量或权限校验；成功后按现有查询键刷新数据，失败时保留输入并显示可处理的原因。
+- 保持布局在窄屏可用，避免固定宽度、横向溢出及把操作只放在 hover 上；可复用的业务组件留在所属模块，只有确实跨模块复用时才进入 `shared`。
+
+实现前阅读相关页面、模块入口和契约类型。组件库提供的是可组合的 UI 原语，AI 应根据实际业务含义选择与组织它们；组件本身不会生成 Cage 领域声明、API、授权或持久化行为。

package/templates/blank/docs/{ai → development/guides}/intelligence.md

@@ -1,6 +1,6 @@
 # 原生智能助理与 AI 审批
 
-[返回学习入口](README.md) · [审批与命令](primitives.md) · [架构与执行模型](architecture.md)
+[返回学习入口](../README.md) · [审批与命令](../reference/primitives.md) · [架构与执行模型](../getting-started/architecture.md)
 
 这是当前框架的可选运行能力，使用自研持久状态机，不依赖 DeepSeek-Harness。框架提供模型适配、工具、任务、记忆、HTTP 和 SDK；应用提供领域声明、审核策略、角色授权及界面。开发阶段的 `cage context` 查询源码本体，与这里面向登录用户的运行时助理用途不同。
 
@@ -10,13 +10,13 @@
 
 | 需求关键词 | 公开入口 | 本页使用说明 |
 | --- | --- | --- |
-| AI审批、智能审批、转人工 | `@yss123/cage-approval` 的 `step`、`AiStepOptions` | “AI 是一个正常审批步骤”；沿用 `approval`，声明三态及真实角色 |
-| 业务助理、本体助理 | `@yss123/cage-ai` 的 `ai` | “启用后端”“助理工具来自注册表”；框架编译工具，应用提供声明 |
-| 页面上下文、随页助理 | `@yss123/cage-client` 的 `useAssistant`、`useAiPageContext`、`AiPageContext` | “SDK 传入页面内容”；应用维护界面与语义快照 |
-| 模型管理、动态配置 | `@yss123/cage-ai` 的 `managedModel` | “启用后端”；Admin 配置连接，部署配置凭据加密密钥 |
-| Responses | `managedModel` 的 Admin 协议选项；代码配置用 `responsesModel` | “Responses 会话与上下文配置”；实际验证网关接续及压缩支持 |
-| 性格、自定义人设 | `useAssistant`、`client.ai`；类型由 `@yss123/cage-ai-protocol` 提供 | “Admin 配置助理性格”；内置预设与自定义表达，不改变审核策略 |
-| 上下文预算、大本体 | `@yss123/cage-ai` 的 `AiContextOptions`，传入 `ai({ context: ... })` | “大本体按需加载”；工具、历史、页面与输出共同受预算约束 |
+| AI审批、智能审批、转人工 | `@yss123/cage-approval` 的 `step`、`AiStepOptions` | [AI 审批步骤](#ai-是一个正常审批步骤)；沿用 `approval`，声明三态及真实角色 |
+| 业务助理、本体助理 | `@yss123/cage-ai` 的 `ai` | [启用后端](#启用后端)、[工具来源](#助理工具来自注册表)；框架编译工具，应用提供声明 |
+| 页面上下文、随页助理 | `@yss123/cage-client` 的 `useAssistant`、`useAiPageContext`、`AiPageContext` | [SDK 与页面内容](#sdk-传入页面内容)；应用维护界面与语义快照 |
+| 模型管理、动态配置 | `@yss123/cage-ai` 的 `managedModel` | [启用后端](#启用后端)；Admin 配置连接，部署配置凭据加密密钥 |
+| Responses | `managedModel` 的 Admin 协议选项；代码配置用 `responsesModel` | [Responses 配置](#responses-会话与上下文配置)；实际验证网关接续及压缩支持 |
+| 性格、自定义人设 | `useAssistant`、`client.ai`；类型由 `@yss123/cage-ai-protocol` 提供 | [Admin 性格配置](#admin-配置助理性格)；内置预设与自定义表达，不改变审核策略 |
+| 上下文预算、大本体 | `@yss123/cage-ai` 的 `AiContextOptions`，传入 `ai({ context: ... })` | [按需加载](#大本体按需加载)；工具、历史、页面与输出共同受预算约束 |
 
 在应用根目录按需查询，例如：
 
@@ -36,7 +36,9 @@ pnpm exec cage capabilities "Responses" --format json
 | 项目已启用 | domain 根入口导出 `ai()`、API/worker 使用相同声明、系统迁移已执行、模型及相关角色权限已配置；有助理需求时包含 `assistant` 并接入 SDK |
 | 实际验证通过 | 真实角色和模型下完成本次需求的读取、交互、审批或写入验收；报告通过、跳过与未执行项 |
 
-先查现有 domain 入口，已有 AI 运行时就扩展该声明；框架只允许一个 `ai()` 运行时。空白模板只注册组织模型，`docs/examples/purchase-admin` 是参考源码，不代表启用了助理。标准范例可沿 `packages/domain/src/integrations/intelligence.ts`、`packages/domain/src/modules/purchase/approvals.ts` 和 `apps/web/src/shared/ui/assistant-panel.tsx` 阅读，路径规则见[学习入口](README.md)。后端循环、通用工具、会话表和性格管理使用框架；应用侧完成业务策略、授权与界面组合。
+先查现有 domain 入口，已有 AI 运行时就扩展该声明；框架只允许一个 `ai()` 运行时。空白模板只注册组织模型，`docs/examples/purchase-admin` 是参考源码，不代表启用了助理。标准范例可沿 `packages/domain/src/integrations/intelligence.ts`、`packages/domain/src/modules/purchase/approvals.ts` 和 `apps/web/src/shared/ui/assistant-panel.tsx` 阅读，路径规则见[学习入口](../README.md)。后端循环、通用工具、会话表和性格管理使用框架；应用侧完成业务策略、授权与界面组合。
+
+按本次实现范围选择阅读顺序：业务助理走[后端启用与迁移授权](#启用后端) → [工具边界](#助理工具来自注册表) → [页面 SDK](#sdk-传入页面内容) → [验收](#接入后的验收)；AI 审批走同一后端前提 → [审批步骤](#ai-是一个正常审批步骤) → [验收](#接入后的验收)。Responses、性格和预算按需求补读。先按 Skill 明确助理应帮助用户完成哪些动作、审批采用哪些规则，再选择接入点。
 
 ## 启用后端
 
@@ -61,6 +63,8 @@ export const intelligence = ai({
 });
 ```
 
+只有 AI 审批时可以省略 `assistant`。审查并执行 `pnpm migrate` 后再启动 API/worker；新增命名系统迁移由框架携带，`cage doctor` 会列出未执行项，不把建表放到服务启动。管理员显式向使用助理的人授予 `Sys.ai.use`，再按需授予领域 `read`、命令与范围；启用服务不自动授予业务权限。AI 审批的执行角色与授权按下文审批步骤配置。
+
 `managedModel` 是框架托管的模型入口。应用引用稳定别名，实际模型名称、HTTP / HTTPS API 基地址、API Key、接口协议、上下文窗口、超时及启停状态在 `/admin/#/models` 配置。可声明多个入口供审批和助理分别使用。不需要在业务项目定义模型配置表、管理路由或环境变量读取逻辑。
 
 部署向 API 和 worker 注入同一份 `CAGE_AI_ENCRYPTION_KEY`（32 字节随机密钥的标准 Base64），也可通过连接器 `SecretProvider` 提供。它是加密模型凭据的部署主密钥，不是模型 API Key；应稳定保存并与数据库分开备份。不要随进程启动重新生成，也不要直接轮换它而不重新加密旧配置。未配置时不能保存 API Key。
@@ -71,6 +75,8 @@ export const intelligence = ai({
 
 需要代码配置或离线测试时，可使用 `chatModel('language-model', { model, hosts, secret, fake })` 或同包导出的 `responsesModel`：`secret` 是 SecretProvider 的密钥名称；默认遵循 `CAGE_STAGE`，fake 阶段必须显式提供模拟函数且禁止外呼；`environment: 'test' | 'prod'` 可独立选择真实模型环境。自定义 `credential` 解析器只在服务端按次调用，不参与声明序列化。两者默认 HTTPS，可显式设置 `protocol: 'http:'` 连接 HTTP 网关。所有标准模型外呼经过框架连接器的地址校验、限流、取消和超时。
 
+`ModelProvider` 是服务端扩展接口，可适配其他协议；适配器必须响应 `AbortSignal`。运行时仍会在超时后放弃等待，迟到结果不会被提交。
+
 ### Responses 会话与上下文配置
 
 Admin 的 `apiFormat` 默认 `chat-completions`，旧模型升级后保持该协议；选择 `responses` 后启用服务端接续。`contextWindowTokens` 默认 32768，可配置 8192 至 2000000，必须按实际模型容量填写；窗口包括输入、输出及推理 Token，和 `assistant.limits.tokenBudget` 的单轮累计消耗分别控制。代码模型使用同名选项。
@@ -83,10 +89,6 @@ Responses 请求使用 `store: true` 和 `previous_response_id`。框架持久
 
 升级执行系统迁移 `cage:ai_context_001` 和 `cage:ai_execution_001`：前者增加模型协议/窗口及接续状态，后者将调用预留、尝试次数、接续兼容性及工具预算单独持久化；不改写已有迁移。旧运行的已有计数保留，不追溯推测其费用。前端调用 `client.ai` 的发送、流式订阅与交互方法不变。
 
-只有 AI 审批时可以省略 `assistant`。`ModelProvider` 是服务端扩展接口，可适配其他协议；适配器必须响应 `AbortSignal`。运行时仍会在超时后放弃等待，迟到结果不会被提交。
-
-审查并执行 `pnpm migrate` 后再启动 API/worker。新增命名系统迁移由框架携带，`cage doctor` 会列出未执行项。不要把建表放到服务启动。管理员显式向使用助理的人授予 `Sys.ai.use`，再按需授予领域 `read`、命令与范围；启用服务不自动授予业务权限。
-
 ## Admin 配置助理性格
 
 性格是框架提供的租户配置，无需应用声明性格聚合或编写工具。启用 `ai({ models, assistant })`、执行系统迁移后即可使用；管理员需显式获得 **`Sys.ai.personalities.manage`**，从 `/admin/#/personalities` 管理。它与 `Sys.ai.models.manage`、普通用户的 `Sys.ai.use` 分开授权。
@@ -173,7 +175,7 @@ export const reviewRoute = route('document-review', [
 
 三个结论命令必须属于该聚合并声明 `invokedBy: 'process'`。`onReturned` 与最终拒绝 `onRejected` 独立。修订后再次触发 start 事件，会创建新轮次，从第一个步骤重新开始；旧步骤和旧任务不能继续生效。通知申请人可以由结论命令发事件，再接已有通知反应/连接器；框架不会猜测通知渠道。
 
-`automatedBy` 是真实组织角色的 code，不是模型可选身份。角色需显式拥有对象读取、所需查询读取、通过/退回命令，以及相应范围与额度。没有隐式全范围，也不冒充提交人。`sod.notSameAs` 要求可核验的真人操作人，自动节点不能绕过该约束；这种命令会转人工。
+`automatedBy` 是真实组织角色的 code，不是模型可选身份。角色需显式拥有对象读取、所需查询读取、通过/退回命令，以及相应范围。没有隐式全范围，也不冒充提交人。`sod.notSameAs` 要求可核验的真人操作人，自动节点不能绕过该约束；这种命令会转人工。
 
 `context.fields` 白名单定义单据上下文；`context.queries` 引用已导出的 query 名称，AI 可按查询 schema 补参数。审核阶段只能调用这些查询、`review_decide` 及读取本次证据的 `context_read`，不能访问其他会话、动态加载其他业务工具或调用助理写工具。证据引用会校验来源是否已提供，但不会把模型判断当作数学证明。
 
@@ -292,7 +294,7 @@ const assistant = useAssistant(client.ai, page);
 // progress.tool / toolName / toolState：当前工具及执行状态。
 ```
 
-以上片段的 hooks 从 `@yss123/cage-client` 导入，record/location 是应用路由与数据。SDK 会在卸载、退出和切换账号时取消订阅并清理 hook 状态；应用其他缓存仍须按[开发步骤](workflow.md)处理。
+以上片段的 hooks 从 `@yss123/cage-client` 导入，record/location 是应用路由与数据。SDK 会在卸载、退出和切换账号时取消订阅并清理 hook 状态；应用其他缓存仍须按[开发步骤](../getting-started/workflow.md)处理。
 
 `send` / `respond` 返回的 Promise 等待本轮完成或需要用户交互；界面应在等待期间渲染 `streamingText` 和 `progress`。`run.status`、步数、工具调用数和待确认操作也随事件更新，不必等 Promise 返回。`model.started` 表示开始一次模型调用，`message.delta` 是增量文本，`tool.started` / `tool.completed` 表示实际工具进度；这些事件不包含模型的私有推理内容。新的模型步骤会重置当前文本，最终以 `message.completed` 校准。
 
@@ -345,4 +347,4 @@ Token 使用优先按模型返回 usage 核算；缺少 usage 时使用文本估
 - AI 审批：覆盖 pass、return、manual，检查退回修改后的新轮次从头开始；模型失败应按节点配置转人工或留在失败状态，不得伪造通过。
 - 管理配置：验证模型连接和一次实际工具交互，性格切换作用于后续消息；需要 Responses 接续或压缩时分别核对实际支持，连接成功不能替代这些验证。
 
-`cage doctor` 可辅助检查注册、迁移和进程证据，但未知项不能当作通过；诊断用法见[能力发现与状态诊断](diagnostics.md)。模型输出质量需要应用使用自己的规则样例评测。框架验证的是权限、状态、预算和事务边界；发布前需使用实际模型服务、实际角色和审批样例联调。
+`cage doctor` 可辅助检查注册、迁移和进程证据，但未知项不能当作通过；诊断用法见[能力发现与状态诊断](../tools/diagnostics.md)。模型输出质量需要应用使用自己的规则样例评测。框架验证的是权限、状态、预算和事务边界；发布前需使用实际模型服务、实际角色和审批样例联调。

package/templates/blank/docs/development/guides/ontology-modeling.md

@@ -0,0 +1,83 @@
+# 把业务含义写进本体声明
+
+[返回学习入口](../README.md) · [业务澄清](business-collaboration.md) · [能力选择](recipes.md) · [本体查询](../tools/ontology-context.md)
+
+Cage 的本体来自实际注册的领域声明。对象是什么、状态表示什么、对象之间如何关联、操作后影响谁，都应落实到这些声明及其实现中。图谱用来检查和解释它们；不另建一份与运行代码分离的本体配置来代替领域设计。
+
+用户可以通过自然语言、业务文档、已有系统、表格或原型表达需求。原型只能提供其中一部分线索：页面上的“所属部门”可能是对象引用，也可能只是历史名称快照，必须结合业务含义判断。模板和参考例子提供框架用法，不能替用户决定对象、关系或流程。
+
+## 编码前，把相关业务说清楚
+
+新建或修改领域时，沿[Skill 的实现映射](../skills/cage-development/SKILL.md#4-写代码前说明实现映射)，说明本次涉及的对象、关系、动作与结果。小改动用几句话即可；已有清楚的业务文档直接引用，不要求每次另建文档或让用户逐项填表。
+
+| 要说清楚什么 | 应落实到哪里 | 如何核对 |
+| --- | --- | --- |
+| 对象代表什么，是否有独立身份和生命周期 | aggregate、fields、states、不变量 | 不按页面数建表，不把独立业务对象藏进任意 JSON |
+| 谁属于谁，双方各能关联几个，关系可否为空 | ref、unique、optional、hasMany、manyToMany 或关系聚合 | 外键方向、基数、目标声明、mappedBy 和实际查询一致 |
+| 状态表示什么，哪些操作允许进入或离开 | states 的 labels、terminal、command 的 from/to | 状态名称和允许操作符合用户规则，保留状态的操作用 to: null |
+| 谁能执行，能作用于哪些记录 | 能力、scope、invokedBy、constraints | 页面隐藏按钮和审批选人不能代替服务端授权 |
+| 操作完成后，其他对象或系统怎样变化 | emits、reaction、approval、job、connector 及执行代码 | 明确触发、输入映射、事务、失败和重试；读取依赖不等于自动联动 |
+| 怎样才算业务完成 | 已确认规则及成功、失败例子 | 独立读取结果，验证关键反例，区分静态声明和实际执行 |
+
+涉及取舍时按[业务澄清](business-collaboration.md)提出疑点及选项。例如“一个员工是否允许同时有两个有效任职”“删除父对象后子记录如何处理”不能由字段名推断。已明确的规则直接采用，普通技术用法由 agent 查证。
+
+## 名称写在真实 API 中
+
+机器标识负责存储、能力点、路由和代码引用，业务名称负责让用户与 agent 理解它们。中文业务用中文名称，其他语言的应用用对应业务用语；不要为翻译而改已有状态值、表名或能力点。
+
+| 内容 | 结构化填写位置 | 边界 |
+| --- | --- | --- |
+| 业务对象 | `aggregate('Note', { description: '部门便笺', ... })` | 说明对象含义；长篇规则仍由代码、JSDoc 和业务文档解释 |
+| 字段及引用 | `text(120).describe('便笺标题')`、`ref('Dept').describe('所属部门')` | 描述不能代替 ref 关系、输入校验或 scope |
+| 集合关系 | `.describe(...)` 或工厂选项 `description` | `hasMany` 仍需真实的 `mappedBy`，`manyToMany` 不会自动生成有业务状态的关系对象 |
+| 每个状态 | `states(..., { labels: { active: '使用中', archived: '已归档' } })` | 每个状态都应有业务名；初态、终态和可达性单独声明/检查 |
+| 业务操作 | `command(对象, { description: '归档便笺', ... })` | 用业务意图命名，实际条件由 from、constraints、handler 等落实 |
+| 事件 | `event('NoteArchived', { ... }, { description: '便笺已归档' })` | 描述已发生的事实；没有下游需求时不必添加事件 |
+| 查询、定时任务 | 各自选项中的 `description` | reads/calls、SQL 或 run 才表达实际依赖和处理 |
+| 完整业务阅读流程 | `businessProcess` 的 `title/description`，阶段的 `title/description/actor` | action 和连接引用真实实现；阅读规格本身不会执行命令或补出缺失联动 |
+| 板块、角色、无通用描述选项的协作节点、短标题覆盖 | `cage.config.json` 的 `graph.labels`，键为完整节点 key | 属于显示覆盖；不会修正错误关系，也不会自动成为其他界面的文案 |
+
+优先把名称与领域声明一起维护。已有项目可用 `graph.labels` 适配：`state:Note.archived`、`field:Note.deptId`、`command:Note.archive`。配置覆盖优先于声明文案；字段也能使用本体属性里的 description。不要为每个节点发明不存在的 `label` 或 `description` 选项，先用 `cage capabilities` 核对公开签名。
+
+普通源码注释和前端的 `statusLabel` 映射不会自动被抽取。仅在注释写“archived 表示已归档”，或者仅在页面翻译 archived，图谱仍缺少该状态的业务名。`graph.labels` 只作用于 CLI 图谱及上下文；页面文案与领域状态含义仍需核对一致，前端不得为读取文案导入 domain。
+
+完整可编译示例见[便笺领域声明](../examples/note/note.ts)。其中 active/archived 保持机器标识，labels 写“使用中/已归档”，字段和命令分别填写自己的业务名称。便笺不需要审批和事件，不为凑齐图谱节点而添加它们。
+
+## 对象关系要落到声明与执行
+
+参考[关系指南](relations.md)选择方向与保存方式。例如“每条评论属于一条便笺”：
+
+- 评论上的 `noteId: ref('Note').describe('所属便笺')` 表达真正引用；普通 `id()`、`text()` 或命名为 noteId 的字段不会自动建立引用。
+- 便笺上的 `hasMany('NoteComment', { mappedBy: 'noteId', description: '便笺评论' })` 只是反查。修改归属仍执行评论命令，不能写父对象的只读集合。
+- 评论是否沿用便笺部门、便笺归档后能否评论，分别由评论命令的 reads、handler 和允许规则落实；ref 不会自动继承权限、状态或删除行为。
+
+跨对象动作也要有真实执行链。“批准后占用资源”应能找到命令发事件、反应接收、调用目标命令的完整声明，以及数据映射与事务选择。`reads` 箭头只证明读取，`from/to` 只证明允许的迁移，`invokedBy: 'process'` 只证明调用身份；它们都不能独自证明审批或自动执行。
+
+业务阅读确实跨多个对象时，可以声明 `businessProcess` 解释完整主线并引用真实实现；简单对象生命周期不必额外包一层流程。图谱看起来有连线不能代替实际业务用例。
+
+## 检查名称，再按业务验收
+
+在应用根目录执行：
+
+```sh
+pnpm exec cage check
+pnpm gen
+pnpm exec cage graph
+pnpm exec cage context "本次业务用语" --format json
+```
+
+`CAGE-ONTOLOGY-001` 报告当前项目有源码位置的聚合、字段、状态、命令、事件、查询和任务缺少非空结构化名称。字段和状态的位置指向所属聚合，不是假装精确的成员行号。来自依赖包且没有本地声明位置的节点不在本检查范围；协作节点没有统一的 description API，也不纳入该完整性规则。
+
+旧配置默认产生警告；新脚手架启用以下门禁，也可在已有应用补齐名称后启用：
+
+```json
+{
+  "graph": {
+    "naming": "required"
+  }
+}
+```
+
+将 naming 合并进原有 graph 配置，保留 title 和 labels。required 让缺名阻止 check/gen/verify；图谱仍会展示可抽取的图及诊断，便于修复。默认警告并不表示业务文案已经完成，应在交付中说明仍缺什么。
+
+静态检查只能验证名称存在和框架可识别的结构，不能判断中文是否准确，也不能判断一条外键是否符合任意用户需求。检查后逐项返回编码前的规则：对象含义、关系方向与基数、状态迁移、触发链及权限是否一致？成功和关键失败例子是否得到预期结果？按这些证据报告完成程度，不把“命名门禁通过”当作“理解了业务”。

package/templates/blank/docs/development/guides/recipes.md

@@ -0,0 +1,123 @@
+# 业务设计与能力选择
+
+[返回学习入口](../README.md) · [原语示例](../reference/primitives.md) · [开发步骤](../getting-started/workflow.md)
+
+本页负责业务规则到 Cage 能力的设计映射；工作顺序由[框架开发 Skill](../skills/cage-development/SKILL.md)统一规定，具体命令见[开发步骤](../getting-started/workflow.md)。按需要读对应配方，不要求为每个任务加载所有能力。
+
+需要 AI 审批、业务助理、随页聊天、模型管理或性格配置时，先用 `cage capabilities` 查框架能力，再按[原生智能化指南](intelligence.md)接入。普通业务建模仍按下文声明聚合和命令；接入已有框架服务无需另建一套通用后端。
+
+## 先确定业务边界与执行路径
+
+开始编码前，从用户需求、业务文档和现有实现中确定以下信息。按[业务澄清与共同设计](business-collaboration.md)主动提出歧义、冲突、遗漏及有价值的建议，给出选项、影响与推荐理由，让用户选择业务规则。已明确的条件直接采用，API 和普通技术细节由 agent 查证处理；下表用于发现相关问题，不要求用户逐项填表。
+
+| 业务问题 | 落到什么声明 | 例如 |
+| --- | --- | --- |
+| 管理什么对象？有哪些字段？ | aggregate、字段与 Zod 输入 | 报销单：金额、事由、部门、提单人、明细 |
+| 有哪些阶段？谁能做什么？ | states、command、invokedBy | 草稿可编辑、提交后审批、完成后不可撤回 |
+| 数据属于谁/哪个部门？ | 范围字段 + 角色数据范围 | 申请人看本人，经理看部门及下级 |
+| 每次操作有什么硬规则？ | constraints、invariants、fail | 提单人不可审批、金额必须为正 |
+| 成功后还要发生什么？ | event、reaction、approval、outbound | 启动审批、登记资源占用、推送财务系统 |
+| 取消/失败要撤销什么？ | cancelOn、释放命令、补偿流程 | 取消待办、释放占用、远端撤销或人工补偿 |
+| 页面需要看什么？ | 生成的 list/get、query、业务页面 | 分页、详情、按状态汇总、导出与导入 |
+
+聚合按业务身份、生命周期和一致性要求划分。一个页面可展示多个聚合，一个聚合也可服务多个页面；不要把页面数量直接当成聚合数量。先识别必须始终成立的不变量，再确定哪些变化需要共同提交。需求没有审批或第三方时，普通命令和生成读取接口就能构成完整功能。
+
+### 在相近能力之间作选择
+
+| 判断依据 | 选择与边界 |
+| --- | --- |
+| 关系只有成员链接，还是有自己的状态与业务属性？ | 纯链接用 manyToMany；需要管理关系生命周期时建独立聚合。hasMany 是对目标 ref 的反查，变更归属走目标命令 |
+| 是改变阶段，还是在当前阶段修改字段？ | 改阶段用 from/to；仅修改已有记录字段用 to: null，仍声明 from，不让 handler 直接改变 status |
+| 是普通对象读取，还是汇总/联表？ | 前者使用生成 list/get；后者声明 query、reads 与安全视图。前端筛选不能承担后端数据范围 |
+| 两项业务变化是否必须一起成功？ | 必须共同提交时使用同事务反应；允许稍后完成时走 outbox，明确失败、重试和结果展示 |
+| 是否涉及事务外系统？ | 网络 IO 放连接器；超时可能已经远端成功，需要幂等与核对/补偿，不能用数据库事务保证远端回滚 |
+| 需要人工决定，还是确定的业务联动？ | 人工/AI 审批使用现有审批流程；确定的自动联动使用事件与反应，不给每个状态变化都加审批 |
+
+### 主体与范围必须能够落实到数据
+
+先确定真实账号及组织关系，再列出各主体需要的能力和记录范围。当前授权模型使用已声明的归属字段；`scope.none()` 仍要求授权，但不能表达部门/创建人范围。声明了一个自定义 applicantId 或 companyName 不会自动获得“本人/本企业”过滤，应核对框架实际支持的范围字段与当前组织映射。
+
+角色是后台分配的数据，能力是被授权的动作，门户是界面组织方式。当前会话公开类型不应通过类型断言凭空添加 roles；若需求要展示实际角色列表，应查找当前允许的读取接口或明确所需接口缺口。多角色能力/范围按框架规则合并，前端切换菜单不会自动切换服务端执行身份。用不同真实主体验证权限，不能用固定姓名或公司名称模拟范围。
+
+## 写代码前的实现映射
+
+理解规则并核对能力后，把“规则 → 框架机制与证据 → 修改位置 → 验收”连接起来。按当前任务写一段说明或小表即可；这里是设计示例，不是要求复制的业务或固定计划文件。
+
+例如，用户已经明确：“已有部门通知增加归档；原有编辑者能归档；归档后保留记录、禁止修改；可见范围不变。”先查现有通知声明、编辑权限、页面及生成契约，再查[命令原语](../reference/primitives.md)。在这些证据一致的前提下，可以形成以下映射：
+
+| 已确认规则 | 已查证的框架做法 | 受影响的位置 | 可观察的验收 |
+| --- | --- | --- | --- |
+| 通知可以归档并保留历史 | 在原聚合增加归档状态与命令，使用 `from/to` 表达转换；复用现有记录 | 原通知领域模块、导出、重新生成的契约与迁移草稿 | 授权主体归档后独立读取仍是同一记录，状态已改变 |
+| 归档后禁止修改 | 核对所有相关修改命令的允许状态，让服务端拒绝归档状态的修改 | 原修改命令及必要的规则用例，页面按状态更新操作入口 | 直接请求修改归档记录被拒绝，刷新后内容仍未改变 |
+| 原有编辑者能归档，可见范围不变 | 沿用原归属字段和读范围，明确新增归档能力由哪些现有角色获得；选人或隐藏按钮不代替授权 | 角色配置、命令能力、页面实际契约调用 | 原编辑者获得对应授权后成功；缺能力主体拒绝；范围外主体仍不能读取 |
+
+实际任务中把“原通知领域模块”等替换为查到的具体文件、声明和签名位置；生成前说明预期契约，生成后核对实际方法。迁移是否新增、需要哪些数据处理，以真实生成差异和已有数据为准。不要从这个例子推断所有项目都需要归档，也不要顺手加入恢复、删除或通知订阅。
+
+如果需求只说“加一个归档”，是否可恢复、谁能归档、归档后能否修改等应按对本次设计的影响提出；用户未要求恢复功能时可作为可选建议，不能擅自纳入实现。业务决定尚未取得时，映射中的相关行为保持待定，继续查证和推进独立部分。
+
+## 新增一个普通管理对象
+
+参考[最小便笺业务](../reference/primitives.md)在 `packages/domain/src/modules/<业务>/<对象>.ts` 声明字段、范围、不变量和本次确需的命令。便笺演示 create/update/archive；当前业务是否需要这些动作由已确认规则决定。采用唯一的导出名和必要的 `name` 覆盖，避免 index 的 `export *` 丢失重名符号。
+
+声明时同步填写对象、字段、操作的业务名称及每个状态的 labels，按[本体建模指南](ontology-modeling.md)核对对象含义、关系和操作结果。从模块 index 到 domain 入口导出后运行 check/gen，处理缺名诊断并审查迁移，再在 `apps/web/src/modules/<业务>` 使用生成 contracts 做列表、详情、表单和操作按钮，经模块公开入口注册到 app 路由。列表和详情都有独立 URL，筛选/分页进入 query，按[浏览器配方](routing.md)检查导航，并为需要的角色授权。完整归属规则见[目录规范](../reference/project-structure.md)。不要手写后端增删改查路由、ORM 实体与 repository，也不要复制框架鉴权代码。
+
+完成标准：已要求的动作由授权主体执行，范围外数据不可见，状态和失败行为符合已确认规则，生成契约和迁移一致。没有审批需求时不必添加审批；没有外部系统时不必添加连接器。
+
+## 增加一对多或多对多
+
+参考[对象关系](relations.md)，在聚合的同一个 fields 中添加 `hasMany/manyToMany`。纯关联交给框架生成中间表；关系本身有职位、状态等业务属性时再建立有意义的聚合。hasMany 反查目标上的 ref，修改归属执行子对象命令；manyToMany 用所属对象的命令返回 ID 数组。
+
+生成后前端通过 `对象.related.字段(id, params)` 或 `use对象Related字段` 分页读取，不从普通 get 响应猜测已加载关联。给角色配置两侧 read 能力与范围；添加成员时也检查目标可见性。修改关系执行版本检查，不能把当前一页当作完整集合替换。不要创建新的业务连接池、ORM 中间实体或手写关系路由。
+
+## 给业务单据加审批
+
+1. 为单据补草稿、待审批、通过、驳回等真实状态及命令；提交时发事件。
+2. 通过/驳回使用 process 命令，根据业务添加职责分离等约束；分支条件写在审批路由中。
+3. 添加 approval 绑定和 route；只将需要的字段放进 routable，取消命令发事件并配置 cancelOn。
+4. 配置实际部门负责人、角色或指定用户；给审批人配置能力和范围。
+5. 页面通过待办接口操作。通过后需占用资源时用反应调用资源命令，按业务一致性选择同事务。
+
+完成标准：提交生成待办、正确的人审批、越权和自审批拒绝、取消能结束待办、资源配对完整。转办、委派归还及当前节点前签、后签和并行必签见[审批任务流转](approvals.md)，须显式启用政策并传任务版本，旧实例是否开放签序以其快照为准。任意流程设计器、动态 JS 选人和指定节点退回仍需明确扩展范围。
+
+## 加入 AI 审批或随页助理
+
+先检查 domain 是否已经导出 `ai()`，再按需求修改已有声明或启用一次。AI 审批配置在业务模块的现有 `step` 内，填写 `kind: 'ai'`、审核策略、取证字段/查询与 `handoff`，由 `approval` 绑定自动执行角色和结论命令。业务助理使用框架生成的工具，前端通过 `useAssistant` 与 `useAiPageContext` 接入当前页面；悬浮窗、Markdown 和确认交互由应用实现。
+
+模型地址、协议和密钥通过 `managedModel` 对应的 Admin 配置管理，性格也使用框架现有管理页。先完成系统迁移和必要授权，按[智能化指南](intelligence.md)的接入顺序、SDK 示例和验收步骤验证。分别说明框架支持、应用已启用和真实联调结果；空白模板中的参考代码不参与运行。
+
+## 增加报表或复杂列表
+
+普通分页和详情先使用生成的 list/get；汇总、联表等需求再添加 query。写清 reads、输入 schema，选择参数化 SQL 或 build；只查对应 safe 视图，不为“报表方便”切到管理员连接。
+
+重新生成后使用 `queries.你的查询()` 或生成 hook。检查真实调用人的 read 能力和数据范围；管理员能看到结果不能证明普通用户的报表正确。
+
+## 接入外部系统
+
+沿 `packages/domain/src/integrations/erp.ts` 的结构声明 host、密钥名、操作 schema、outbound 和 inbound。远端成功后的字段回写也走 external 命令。先用 fake 完成本地链路，再在测试环境做真实联调。
+
+明确重复请求如何识别、哪些错误重试、回执晚到怎么办、取消后如何补偿。不要假设本地事务可以回滚已经提交给第三方的写入。
+
+## 增加导入或导出
+
+在客户实际需要的业务页调用客户端/生成契约，展示任务进行中、完成和失败。导入映射到用户可调用的命令，准备与该命令输入匹配的 CSV；不要生成直接写业务表的上传接口。
+
+明确逐行还是整批原子模式、失败报告如何呈现、任务过期如何处理。任务提交成功不能立即标成导入/导出完成，worker 与下载时授权也是链路的一部分。完整方法、CSV 例子与协议见[业务页导入导出](transfers.md)。
+
+## 由采购演示换成客户业务
+
+空白模板不需要清理采购业务，直接从 `packages/domain/src` 新增自己的声明和页面；参考源码在 `docs/examples/purchase-admin`，不在运行入口中。下面的替换步骤只适用于采购模板。
+
+建议先保留运行薄壳和一条可验证的演示链路，新增真实业务并接通页面，再移除不需要的演示引用。清理时沿领域导出、反应、审批、连接器、查询、任务、页面和 graph.labels 一起检查，避免残留仍在运行的自动任务。
+
+组织模型仍从 `@yss123/cage-admin/domain` 导出。已执行迁移作为历史保留，新表/删表通过新迁移表达；需要保存旧数据时先制定迁移方案，不能只把整个 migrations 文件夹删除。
+
+## 给编程工具的任务模板
+
+```text
+阅读当前项目 AGENTS.md，按 docs/development/skills/cage-development/SKILL.md 完成理解、澄清、能力查证、实现映射、编码和验收。
+业务：……；角色与数据范围：……；状态与允许动作：……；审批/外部系统/资源占用：……。
+先用业务语言说明对本次目标的理解，主动指出疑点，给出可行选项、影响与推荐，让我选择；已明确条件不重复询问，普通技术细节自行查证处理。
+查现有实现和当前版本 API，写代码前简述已确定规则如何落到 Cage、改哪些模块、如何验收；能明确实现的部分直接推进，等待业务决定时继续独立工作。
+遵守项目目录与中文注释规范，生成文件通过 cage gen 更新，按改动完成必要验证。
+交付时说明用户如何体验、管理员需配置什么，以及通过/跳过/未执行的检查。
+```