@yss123/cage-cli 0.3.1 → 0.4.0

package/templates/{blank/docs/ai → app/docs/development/examples}/purchase-example.md

@@ -1,6 +1,6 @@
 # 标准采购范例：从声明到业务页面
 
-[返回学习入口](README.md) · [业务任务配方](recipes.md)
+[返回学习入口](../README.md) · [业务任务配方](../guides/recipes.md)
 
 选择 `--template purchase` 创建的是可运行的采购应用，下面的路径相对应用根目录；选择 `--template blank` 时，同一份范例仅作为参考源码保存在 `docs/examples/purchase-admin`，下面路径相对该参考目录，它不参与当前应用的编译、注册或迁移。框架能力来自 npm 依赖。先沿一条真实链路读代码，再把需要的模式应用到自己的业务。
 
@@ -22,7 +22,7 @@
 | `packages/contracts/src/aggregates/purchase-order/index.ts` | 生成的前端协议与类型 | 只读它，不手改；process/external 命令不生成浏览器写方法 |
 | `apps/web/src/main.tsx`、`app` | 挂载、全局 Provider、会话与导航组合 | 入口保持简洁，从模块公开入口组装页面 |
 | `apps/web/src/modules/purchase`、`inventory`、`approval` | 各业务页面与交互 | 调契约、处理错误、刷新列表、展示导出任务；不互相穿透 |
-| `packages/domain/src/modules/purchase/purchase-order.test.ts` | 有业务数据的成功/拒绝用例 | 越权、自审批、额度、库存锁、晚到 ERP 回执 |
+| `packages/domain/src/modules/purchase/purchase-order.test.ts` | 有业务数据的成功/拒绝用例 | 越权、自审批、库存锁、晚到 ERP 回执 |
 
 ## 一次正常采购发生了什么
 
@@ -37,7 +37,7 @@
   → 申请启用专业复核时：所选专业人员全部会签
   → 金额 > 50000 时：财务共享候选任务，由 finance 成员领取后处理
   → 流程完成 → 调用 approve
-      → 职责分离、额度、库存检查
+      → 职责分离、库存检查
       → approved + OrderApproved
       → 同事务 lockOnApprove → InventoryLock.held
   → worker 消费 OrderApproved → fake/真实 ERP 推单
@@ -71,20 +71,20 @@ submit 返回成功只表示单据和事件已提交，不表示待办、ERP 或
 
 ## 首次体验所需业务配置
 
-以下体验需要采购模板；空白模板不会出现采购页面和审批配置。先按[开发步骤](workflow.md)准备已有数据库并启动 API、worker、Web。首次管理员凭证按 API 提示获取，不把凭证写到仓库。以下是业务配置，不是需要写进框架内核的逻辑。
+以下体验需要采购模板；空白模板不会出现采购页面和审批配置。先按[开发步骤](../getting-started/workflow.md)准备已有数据库并启动 API、worker、Web。首次管理员凭证按 API 提示获取，不把凭证写到仓库。以下是业务配置，不是需要写进框架内核的逻辑。
 
 | 对象 | 配置要点 |
 | --- | --- |
 | 采购员 | 创建/查看/提交/取消采购单等所需能力，所属部门，以及采购单数据范围；配置专业复核需 `PurchaseOrder.setReviewers` 和 `ApprovalMember.read` |
 | 智能助理使用人 | 显式授予 `Sys.ai.use`；编辑用途还需 `PurchaseOrder.explainPurpose` |
-| 模型管理者 | `Sys.ai.models.manage`；在 `/admin/#/models` 配置并启用 `main`，部署主密钥见[智能能力指南](intelligence.md) |
+| 模型管理者 | `Sys.ai.models.manage`；在 `/admin/#/models` 配置并启用 `main`，部署主密钥见[智能能力指南](../guides/intelligence.md) |
 | 助理性格管理者 | `Sys.ai.personalities.manage`；在 `/admin/#/personalities` 编辑预设、自定义性格、设置默认并试聊 |
 | AI 预审角色 | 创建 code 为 `purchase_ai_reviewer` 的角色，授予 `PurchaseOrder.read/returnForChanges` 及覆盖申请范围的数据权限；本例 AI 仅预审，不执行最终 approve |
-| 经理 | `PurchaseOrder.read/approve/reject/returnForChanges`，适当数据范围，`approve` 的 `ceiling` 额度参数 |
-| 专业协作人 | 真实账号及同样的审批能力、范围、额度；由名录管理员通过 `ApprovalMember.create` 登记公开业务姓名、专业说明；需要在任务中选人时授予 `ApprovalMember.read` |
+| 经理 | `PurchaseOrder.read/approve/reject/returnForChanges` 和适当数据范围 |
+| 专业协作人 | 真实账号及所需审批能力和范围；由名录管理员通过 `ApprovalMember.create` 登记公开业务姓名、专业说明；需要在任务中选人时授予 `ApprovalMember.read` |
 | 名录管理员 | 显式授予 `ApprovalMember.create/update/retire/read`；登记、更新资料或退役不修改用户角色，不自动给采购参与者授予 `User.read` |
 | 部门 | 将采购员所属部门的负责人设为经理；不能为空 |
-| 财务 | 角色 **code** 为 `finance`，给至少两位实际用户分配以体验共享候选池；配置审批所需权限、范围及足够额度；领取后才能处理 |
+| 财务 | 角色 **code** 为 `finance`，给至少两位实际用户分配以体验共享候选池；配置审批所需权限和范围；领取后才能处理 |
 | 库存台账 | 预先登记与采购明细相同的 sku，数量满足演示检查 |
 | 连接器环境 | fake 阶段使用 worker 注册的 fake；真实环境另配 host 对应密钥及回调签名密钥 |
 
@@ -110,11 +110,11 @@ submit 返回成功只表示单据和事件已提交，不表示待办、ERP 或
 
 `apps/web` 中对字段和按钮的中文名称属于业务文案。图谱名称来自 `cage.config.json` 的 `graph.labels`，比如 `command:PurchaseOrder.submit` 对应“提交审批”。替换业务时别忘了更新这些名称，不要改英文能力标识来做翻译。
 
-导出按钮是调用通用异步接口的一个例子；框架不规定所有业务都要放相同的按钮。导入、导出、任务列表与错误报告应按客户页面需要接入，参考[开发步骤](workflow.md)中的客户端方法。
+导出按钮是调用通用异步接口的一个例子；框架不规定所有业务都要放相同的按钮。导入、导出、任务列表与错误报告应按客户页面需要接入，参考[开发步骤](../getting-started/workflow.md)中的客户端方法。
 
 ## 把示例改成自己的业务
 
-先按[目录规范](project-structure.md)新增自己的领域模块和前端模块，完成一条完整链路，再逐步移除不需要的采购导出、路由、反应、连接器和页面引用。`@app/domain`、`@app/contracts` 是应用内包名，可以保留；npm 框架包也不需要重命名。
+先按[目录规范](../reference/project-structure.md)新增自己的领域模块和前端模块，完成一条完整链路，再逐步移除不需要的采购导出、路由、反应、连接器和页面引用。`@app/domain`、`@app/contracts` 是应用内包名，可以保留；npm 框架包也不需要重命名。
 
 若数据库尚未投入使用，可为新应用审查和规划初始结构；只要迁移已执行或已发布，就不能通过覆盖 `0001_init.sql` 来假装采购表从未存在。用新迁移表达后续变更，并明确已有数据处理方式。
 

package/templates/{blank/docs/ai → app/docs/development/getting-started}/architecture.md

@@ -1,6 +1,6 @@
 # 架构与执行模型
 
-[返回学习入口](README.md) · [下一篇：原语](primitives.md)
+[返回学习入口](../README.md) · [下一篇：原语](../reference/primitives.md)
 
 ## 业务声明是一份可执行规格
 
@@ -34,7 +34,7 @@ domain/index.ts 导出的声明
 
 一个采购单可以有明细列表，也可以引用库存等其他聚合。跨聚合写入要调用对方的命令，通过反应表达关系，不能拿到对方数据库表直接更新。
 
-对象关联统一写在 fields：ref 为本表外键，hasMany 依据目标外键反查，manyToMany 自动生成中间表。多对多链接属于来源对象的命令事务，但不授权修改目标内容；公开关联通过两侧安全视图分页读取。完整模式见[对象关系](relations.md)。
+对象关联统一写在 fields：ref 为本表外键，hasMany 依据目标外键反查，manyToMany 自动生成中间表。多对多链接属于来源对象的命令事务，但不授权修改目标内容；公开关联通过两侧安全视图分页读取。完整模式见[对象关系](../guides/relations.md)。
 
 ## 一次写入的完整路径
 
@@ -43,7 +43,7 @@ domain/index.ts 导出的声明
   → 校验输入、上下文、调用身份与能力
   → 幂等检查
   → 按范围加载并锁定记录，检查状态与版本
-  → 硬约束（职责分离、额度、二次认证等）
+  → 硬约束（职责分离、二次认证等）
   → 绑定 reads，只运行 handler 的业务计算
   → 合并结果，内核设置目标状态，校验字段及不变量
   → 写记录、版本、审计和 outbox，执行同事务反应
@@ -69,7 +69,7 @@ worker → 消费 outbox → 异步反应 / 审批 / 连接器
 
 资源标签 `acquires: 'inventory.lock'`、`releases: 'inventory.lock'` 为图规则提供证据。它们不会自动加锁或释放，真正效果来自 `acquireLock/releaseLock` 命令。
 
-有界批量步骤可用 `reactionEach`：声明目标命令、最大项数、唯一排序键和映射，按稳定顺序串行调用。`order` 表达同一事件的步骤依赖，同事务链仍整体回滚。具体声明见[原语指南](primitives.md#有界集合与步骤顺序)。
+有界批量步骤可用 `reactionEach`：声明目标命令、最大项数、唯一排序键和映射，按稳定顺序串行调用。`order` 表达同一事件的步骤依赖，同事务链仍整体回滚。具体声明见[原语指南](../reference/primitives.md#有界集合与步骤顺序)。
 
 出站分成外部执行与短事务回写两个阶段。框架先领取本地执行租约，用 `${tenantId}:${declaredKey}` 作为远端幂等键，可靠保存回执后再在短事务调用成功命令；回写失败可复用已保存回执。远端必须实际支持幂等，框架不能承诺任意外部系统恰好一次。不可安全重试的写入结果未知时隔离并要求核对，不能把超时当作远端未执行。
 
@@ -85,12 +85,12 @@ worker → 消费 outbox → 异步反应 / 审批 / 连接器
 | 调用身份 | `user/process/job/external` | `process` 命令不给浏览器生成直接写接口；这不是角色名 |
 | 能力点 | `PurchaseOrder.submit`、`PurchaseOrder.read` | 代码声明能力目录，管理员在目录范围内授权 |
 | 数据范围 | 本人、本部门、部门及下级、指定部门、全部 | 决定能触及哪些记录，越范围详情通常表现为 404 |
-| 业务硬约束 | 不是提单人、额度不超过 ceiling | 即使被选为审批人也必须通过 |
+| 业务硬约束 | 不是提单人 | 即使被选为审批人也必须通过 |
 | 明文能力 | `PurchaseOrder.unmask.phone` | 没有该能力时，安全读侧对电话掩码 |
 
 `scope.deptSubtree('deptId')` 描述聚合的部门字段和建议范围；**实际范围取决于角色授权数据**。`scope.none()` 表示没有部门/创建人范围字段，仍然需要能力和适当的 `all` 范围授权，不能理解成“任何人能读”。多角色范围合并为并集，缺少显式范围时默认本人范围，不是全部。
 
-`useCan()`、`can()` 只决定按钮呈现；前端隐藏按钮不能代替后端授权。新增命令不会自动授给已有生产角色，角色分配和额度调整也受防提权约束。
+`useCan()`、`can()` 只决定按钮呈现；前端隐藏按钮不能代替后端授权。新增命令不会自动授给普通生产角色，角色分配也受防提权约束。首次初始化的超级管理员拥有当前及以后新增的全部能力和本租户全部范围。
 
 授权通知监听异常时不再复用缓存，每次重新读取授权；重新订阅后清空缓存，并阻止旧请求回填旧上下文。`/readyz` 反映数据库和授权监听健康，`/healthz` 仅表示存活。诊断入口受 `Sys.ops.read` 及相关对象 read/范围控制，`explain` 解释调用身份、能力、范围、状态与硬约束，不能预测 handler 的业务结果；新建对象的最终范围无法提前确定时返回 unknown。
 
@@ -141,8 +141,8 @@ APP、READ、MIGRATE 指向**同一个已经存在的数据库**，用不同账
 
 ## 本体图为什么有这些连线
 
-图谱抽取命令状态迁移与事件、反应调用、审批 start/cancelOn、约束/路由字段、查询读依赖和外部映射；另以虚线标记按标识推导的所属聚合。关系解释区分显式声明、规则推导与文本匹配，箭头要按各自含义阅读。开发前可用[本体上下文工具](ontology-context.md)检索相关业务与源码。
+图谱抽取命令状态迁移与事件、反应调用、审批 start/cancelOn、约束/路由字段、查询读依赖和外部映射；另以虚线标记按标识推导的所属聚合。关系解释区分显式声明、规则推导与文本匹配，箭头要按各自含义阅读。开发前可用[本体上下文工具](../tools/ontology-context.md)检索相关业务与源码。
 
-`cage analyze` 将图写到 `.cage/ontology.json`；`cage graph` 提供浏览器工作台。中文显示名写在 `cage.config.json` 的 `graph.labels`，例如 `"command:PurchaseOrder.submit": "提交审批"`。显示名不更改能力标识、源码符号或表名。
+`cage analyze` 将图写到 `.cage/ontology.json`；`cage graph` 提供浏览器工作台。业务名称优先与领域声明一起维护：对象和操作用 `description`，字段用 `.describe(...)`，状态用 `states` 的 `labels`。`cage.config.json` 的 `graph.labels` 可覆盖显示名，例如 `"command:PurchaseOrder.submit": "提交审批"`。这些名称不更改能力标识、源码符号或表名；普通注释和页面翻译不会自动进入图谱。详见[本体建模指南](../guides/ontology-modeling.md)。
 
-图规则能检查“离开持有状态是否声明了释放”等结构问题，无法证明 `map` 的任意分支或 handler 计算一定正确。因此重要的资源释放条件、权限拒绝、额度边界仍需对应业务回归用例。
+图规则能检查“离开持有状态是否声明了释放”等结构问题，无法证明 `map` 的任意分支或 handler 计算一定正确。因此重要的资源释放条件、权限拒绝、业务条件边界仍需对应业务回归用例。

package/templates/app/docs/development/getting-started/first-feature.md

@@ -0,0 +1,66 @@
+# 第一条完整业务链
+
+[学习入口](../README.md) · [框架开发 Skill](../skills/cage-development/SKILL.md) · [原语参考](../reference/primitives.md)
+
+本课教会你把声明、契约、页面和持久数据连接起来。以“部门便笺”解释方法：创建便笺、查看列表与详情、修改标题、归档。这个对象只用于教学；开发真实业务时替换对象含义和规则，不需要向用户项目添加便笺。
+
+## 先确定业务，再选择声明
+
+一条便笺有标题、所属部门和创建人，状态为 active 或 archived。创建、修改标题、归档都是命令；列表和详情使用生成的读取接口。标题不能为空是不变量，归档后不能修改由 update 的 from 表达。
+
+归属字段使用 `deptId: ref('Dept')` 与 `createdBy: ref('User')`，内核新建时根据当前主体填写；`scope.deptSubtree('deptId')` 描述范围字段。实际授权仍由角色配置决定，普通用户不能通过提交任意部门 ID 把记录放进其他部门。公司、项目组等自定义归属不能仅改一个字段名字就假定沿用同样规则，应核对当前支持的范围模型。
+
+完整领域代码见[便笺声明](../examples/note/note.ts)。依次阅读聚合、createNote、updateNote、archiveNote，注意命令导出名不同于 `name` 指定的能力名称。
+
+## 让声明进入应用
+
+把本课声明放入应用的 `packages/domain/src/modules/note/note.ts`，在模块 index.ts 导出它，再从 domain 总入口导出模块。保留原有组织模型及其他业务；不要让不同模块的 `export *` 带来重名导出。
+
+在应用根目录执行：
+
+```sh
+pnpm exec cage check
+pnpm gen
+```
+
+检查生成的 Note 契约、图节点、路由信息及迁移草稿。应能找到 `note.create`、`note.update`、`note.archive`、`note.list` 和 `note.get`。这里验证的是注册和生成；尚未证明数据库里有表或用户有权执行。
+
+数据库初次准备按[开发步骤](workflow.md#第一次启动应用)进行；已有项目复用现有配置。审查新迁移后执行 `pnpm migrate`，再按当前环境启动/重启 API 与 worker。不要改已执行迁移，也不要为学习案例覆盖业务数据库配置。
+
+## 给真实主体配置权限
+
+在独立验收环境准备有能力的主体、同部门另一主体和范围外主体。为所需角色明确配置 `Note.read`、`Note.create`、`Note.update`、`Note.archive` 及对应数据范围。按业务分别选择本人、部门或部门及下级等范围；创建一个角色名称不会自动获得这些能力。
+
+`scope.none()` 缺少部门/创建人范围表达，不能拿它替代“仅看本部门”。当前框架合并多角色能力与范围；只切换前端门户不会把后端权限自动缩减到所选角色。产品确需切换执行身份时，先确认当前公开协议是否支持该语义，不能通过本地 role 变量伪装授权。
+
+## 页面调用真实契约
+
+[列表与新建页面](../examples/note/notes-page.tsx)演示创建成功后重新读取服务端列表；[详情页面](../examples/note/note-detail-page.tsx)从 URL 读取 ID，直接加载服务端记录，修改和归档带上读取到的版本。它们是可编译的完整教学组件，样式由应用自行设计。
+
+将组件放到 `apps/web/src/modules/note/pages`，从模块 index.ts 公开导出。再在已有 app 路由组合层导入模块入口，在登录后的 Outlet 内加入以下路由片段：
+
+```tsx
+<Route path="notes" element={<RequireCapability capability="Note.read" home="/workspace"><NotesPage /></RequireCapability>} />
+<Route path="notes/:id" element={<RequireCapability capability="Note.read" home="/workspace"><NoteDetailPage /></RequireCapability>} />
+```
+
+片段中的 Route、RequireCapability 和两个页面要从当前应用真实入口导入；保留已有会话恢复、退出清理和 404。新增菜单使用 Link 指向 `/notes`。完整导航要求见[路由与浏览器验收](../guides/routing.md)。
+
+创建按钮检查 `Note.create` 只是界面提示。提交后检查 `result.ok`，成功才清空输入并重新读取；失败展示错误并保留输入。详情请求可能返回范围外的 NOT_FOUND，不能显示“该记录已删除”这种未经证明的结论。编辑冲突后重新读取版本并让用户核对，不静默覆盖他人修改。
+
+## 沿操作观察结果
+
+| 操作 | 预期观察 | 若失败，优先检查 |
+| --- | --- | --- |
+| 有权用户创建便笺 | 真实请求成功，服务端返回 ID，独立 list/get 可读 | 契约调用、迁移、能力与归属字段 |
+| 新标签页打开详情 URL | 重新请求后显示同一条记录 | URL ID、会话恢复、读取范围 |
+| 另一位有同部门范围的用户查看 | 服务端读取同一条记录 | 实际部门、角色范围、接口结果 |
+| 范围外主体直接请求详情 | 请求拒绝或安全地返回不可见 | 服务端范围，不能只看菜单是否隐藏 |
+| 两个页面使用同一旧版本修改 | 后一次得到冲突，不覆盖新值 | expectedVersion 和页面刷新策略 |
+| 归档后再次修改 | 业务状态拒绝；页面重新读取为 archived | from/to 与真实状态 |
+
+运行受影响包的类型检查和构建、生成一致性与必要业务测试，再按浏览器配方操作。未配置测试账号、未连接独立测试库或没有浏览器能力时，写清未执行项；不要用编译通过替代本表结果。
+
+## 从本课迁移到其他业务
+
+先替换对象、字段、归属与动作，保留“声明 → 导出 → 生成 → 运行配置 → 契约 → 观察结果”的方法。只有需求需要时再增加能力：审批学习[审批单元](../guides/approvals.md)，附件学习[文件单元](../guides/files.md)，关联学习[关系单元](../guides/relations.md)，跨对象联动参考[事务选择](architecture.md#同事务与异步的选择)。完整组合范例见[采购导读](../examples/purchase-example.md)，无需一次复制全部采购实现。

package/templates/{blank/docs/ai → app/docs/development/getting-started}/workflow.md

@@ -1,6 +1,8 @@
 # 开发步骤与交付要求
 
-[返回学习入口](README.md) · [范例导读](purchase-example.md) · [详细中文注释](commenting.md)
+[返回学习入口](../README.md) · [框架开发 Skill](../skills/cage-development/SKILL.md) · [完整入门课](first-feature.md) · [详细中文注释](../reference/commenting.md)
+
+本页提供应用启动、修改和验证的操作命令。需求理解、与用户澄清、能力查证和编码前的实现映射统一按[Skill](../skills/cage-development/SKILL.md)执行；下列操作用于落实已经明确的设计。
 
 本页命令在**应用根目录**执行，除非注明“框架根目录”。使用项目安装的 CLI：`pnpm exec cage ...`。项目脚本可简写为 `pnpm gen / pnpm migrate / pnpm dev / pnpm verify`；不要假定机器已全局安装 cage。
 
@@ -25,21 +27,22 @@ pnpm dev
 
 `init` 自动创建独立账号与随机密码，填写 APP/READ/MIGRATE 连接和 Cookie 密钥，成功后删除文件中的管理员连接。三个连接使用同一数据库。已有 Cage 集群账号时复用原连接，不能重置其他应用的账号密码。生产环境可由平台直接提供账号连接，不必执行本地 init。
 
-`bootstrap` 独立初始化组织，不自动授予业务能力。管理员凭据只进入新的受限文件，不进入服务控制台；已有用户时不重置。交付后移除凭据文件。日常 API 启动不初始化组织；生产缺少合格 Cookie 密钥会拒绝启动。具体文件权限与诊断用法见[能力发现与状态诊断](diagnostics.md)。
+`bootstrap` 独立初始化组织，并给初始超级管理员当前及以后新增的全部能力和本租户全部数据范围。超级管理员可以直接为普通角色配置能力和范围；普通角色不会自动获得新增能力。管理员凭据只进入新的受限文件，不进入服务控制台；已有用户时不重置账号，也不会自动升级已有角色。交付后移除凭据文件。日常 API 启动不初始化组织；生产缺少合格 Cookie 密钥会拒绝启动。具体文件权限与诊断用法见[能力发现与状态诊断](../tools/diagnostics.md)。
 
 `.env.example` 是配置说明，`.env` 是本机私密配置，二者不混用。CLI 自动加载应用 `.env`，部署环境同名变量优先。API 和 worker 启动需重启后读取变更；不要输出整个 `.env` 排障。
 
 框架仓库首次先在根目录 `pnpm install`、`pnpm build`，再进入 `examples/purchase-admin` 配置。`dev` 不自动执行迁移；生成新迁移后要审查并显式运行 migrate。
 
-## 做一项业务修改
+## 按已明确的设计修改业务
+
+只执行实现映射涉及的操作；文案或样式调整无需修改 domain、生成迁移或重新授权。实现过程中发现业务规则尚不清楚，回到[业务澄清](../guides/business-collaboration.md)处理相关部分。
 
-1. 读 AGENTS.md、[目录规范](project-structure.md)和[详细中文注释规范](commenting.md)，确认需求落在领域模块、前端模块、组织配置还是框架。先 `pnpm exec cage context "需求关键词"`，按需 `graph search/inspect/path` 定位，确认候选入口后阅读对应源码、范例与测试；证据和边界见[本体上下文指南](ontology-context.md)。发现能力缺口先说明，不编造 API。
-2. 涉及已存在业务含义变化时，**修改前**运行 `pnpm exec cage snapshot save before-change` 保存命名基线；也可使用真实 Git 提交或独立本体图文件。
-3. 在所属领域模块写字段、状态、不变量和命令输入；再实现 handler、事件、查询与审批。跨模块反应放 workflows，第三方协议放 integrations。从模块 index 到 domain 总入口逐层导出，避免跨文件 export 名冲突。同步编写详细中文注释：文件职责与调用链、导出声明及输入字段、权限/状态/reads/事件/事务、关键步骤和失败边界；涉及已有行为时补齐受影响的上下游说明。
-4. `pnpm exec cage check` 检查声明和图规则；`pnpm gen` 更新契约与迁移草稿。聚合和命令填写中文 `description`，需要覆盖时补 `cage.config.json` 的 `graph.labels`（如 `aggregate:Note`、`command:Note.archive`、`capability:Note.export`）。这些名称同时用于图谱和 `/admin` 授权界面；修改后重启 API。不重命名实际能力点来实现翻译。在图谱确认连接与资源生命周期。
-5. 审查数据库变更，特别是非空字段、数据回填、删列和索引。已执行的迁移不可改写。需要落库时显式 `pnpm migrate`。
-6. 页面和表单放 `apps/web/src/modules/<业务>`，从模块公开入口接入 app 的 URL 路由；依赖生成 contracts，处理失败结果。列表、详情等多页面使用 React Router，筛选和分页进入 URL；组件状态只管理页面内临时交互。新增能力由管理员授权，页面按钮可用 `useCan` 控制。按[路由与浏览器验收](routing.md)检查直达、刷新、前进后退和登录回跳。
-7. 补足重要业务反例并运行相关验证；测试解释夹具目的、所保护的规则和覆盖边界。按注释规范审查本次 diff，核对页面、组件/hooks、类型字段、脚本副作用和恢复流程的说明是否完整准确。提交源声明、契约和审查过的迁移，报告跳过及未执行项。
+1. **保存基线。** 涉及已存在业务含义变化时，修改前运行 `pnpm exec cage snapshot save before-change`；也可使用真实 Git 提交或独立本体图文件。
+2. **修改声明与导出。** 按[目录规范](../reference/project-structure.md)在所属领域模块修改字段、状态、不变量、命令及必要的后续流程。按[本体建模指南](../guides/ontology-modeling.md)把对象含义、关系方向与基数、状态和操作结果写进真实声明；名称用 description、字段 .describe 和每个状态的 labels 维护，普通注释与页面翻译不能代替。跨模块反应放 workflows，第三方协议放 integrations；从模块 index 到 domain 总入口逐层导出，避免重名丢失。按[注释规范](../reference/commenting.md)同步解释职责、输入、权限/状态/reads、事件/事务与失败边界。
+3. **检查与生成。** `pnpm exec cage check` 检查声明和图规则，处理 `CAGE-ONTOLOGY-001` 指出的缺名；`pnpm gen` 更新契约与迁移草稿，不手改生成物。名称显示覆盖可写 `cage.config.json` 的 `graph.labels`（如 `aggregate:Note`、`command:Note.archive`、`capability:Note.export`），不重命名能力点来翻译。图谱中核对业务名称、关系、状态迁移与资源生命周期；名称齐全不能证明联动已经实现。
+4. **审查与迁移。** 核对非空字段、回填、删列和索引，保留已执行迁移；有结构变化且需落库时显式 `pnpm migrate`。按需要配置能力、范围和外部服务，API/worker 使用一致声明。
+5. **接入页面。** 在 `apps/web/src/modules/<业务>` 使用真实生成契约，从模块入口接入 app 路由。处理业务失败与版本冲突；多页面使用独立 URL，筛选/分页进入 URL。`useCan` 只控制按钮，服务端仍校验授权；成功后重新读取或失效查询。按[浏览器验收](../guides/routing.md)检查对应操作和导航。
+6. **核对规则与交付。** 对照编码前的规则与验收例子，补足关键反例，执行下文与改动匹配的检查。审查 diff 中的业务变化、生成物和中文注释；交付源声明、契约、审查过的迁移及配置要求，分别报告通过、跳过、未执行。
 
 ### 如何保存和比较基线
 
@@ -62,7 +65,7 @@ pnpm exec cage impact --base main
 | --- | --- | --- |
 | 增加字段 | 修改 aggregate；按命令更新 input/handler；重新生成 | 是否敏感、是否可选、旧数据如何回填、查询/事件/页面受影响吗 |
 | 增加状态或撤回 | 修改 states 和 command；声明事件及资源处理 | 可达性、非终态出边、审批 cancelOn、CAGE-PAIR-002 |
-| 修改审批 | 修改 route/approval；按需要增加 routable | 负责人/role code、步骤 mode、结论命令、额度和职责分离 |
+| 修改审批 | 修改 route/approval；按需要增加 routable | 负责人/role code、步骤 mode、业务分支条件、结论命令和职责分离 |
 | 增加报表 | 声明 query 的 reads、input 和 sql/build | 安全视图、参数化、调用人 read 权限、生成 queries 契约 |
 | 接入第三方 | 声明 connector/op/outbound/inbound；配置运行环境密钥 | 请求响应白名单、幂等、超时、验签、永久/可重试错误和补偿 |
 | 改后台管理配置 | 通过组织模型与系统接口修改 | 防提权、实际授权范围、角色缓存刷新、操作人权限 |
@@ -98,7 +101,7 @@ if (!result.ok) {
 - `atomic: true` 请求整批原子处理，普通逐行导入需展示成功/失败计数及报告。HTTP 202 仅代表接受任务，不能立即提示处理完成。
 - worker 必须运行；任务可能 queued/retrying/failed/expired。下载会再次校验当前权限。导出的系统列和掩码值不能原样回导。
 
-CSV 编码、限制、SDK 与完整接口见本项目自带的[业务页导入导出](transfers.md)。给新业务做入口时按实际生成的签名调用，不硬编码采购单专属逻辑进框架。
+CSV 编码、限制、SDK 与完整接口见本项目自带的[业务页导入导出](../guides/transfers.md)。给新业务做入口时按实际生成的签名调用，不硬编码采购单专属逻辑进框架。
 
 ## 工具做什么，结果在哪里
 
@@ -106,12 +109,12 @@ CSV 编码、限制、SDK 与完整接口见本项目自带的[业务页导入
 | --- | --- | --- |
 | `pnpm exec cage analyze` | 抽取显式声明与源码位置 | `.cage/ontology.json` |
 | `pnpm exec cage capabilities 关键词 --format json` | 查询当前安装版本的公开能力 | 公开签名、声明位置和学习入口 |
-| `pnpm exec cage doctor` | 统一核对注册、生成、构建及可用运行证据 | pass / fail / unknown 与下一步；见[诊断指南](diagnostics.md) |
+| `pnpm exec cage doctor` | 统一核对注册、生成、构建及可用运行证据 | pass / fail / unknown 与下一步；见[诊断指南](../tools/diagnostics.md) |
 | `pnpm exec cage snapshot save 名称` | 保存不可覆盖的命名基线 | `.cage/snapshots`；配合 `impact --snapshot 名称` |
 | `pnpm exec cage check` | 静态检查、注册表与图规则 | 终端 `code/at/reason/fix` |
 | `pnpm exec cage graph` | 启动中文本体图谱 | 默认 `http://127.0.0.1:15418`，按终端地址访问 |
 | `pnpm exec cage context "需求或节点"` | 开发前取得相关子图、原因、源码与候选验证 | 默认终端 Markdown；`--format json --out .cage/context.json` 保存结构化报告 |
-| `pnpm exec cage graph search/inspect/path ...` | 检索候选 / 精确节点 / 关系路径 | 同源中文与证据；每次重新抽取，见[用法](ontology-context.md) |
+| `pnpm exec cage graph search/inspect/path ...` | 检索候选 / 精确节点 / 关系路径 | 同源中文与证据；每次重新抽取，见[用法](../tools/ontology-context.md) |
 | `pnpm gen` | 更新契约、结构说明、迁移草稿 | `packages/contracts/src`、`db/migrations`、`generated`、`.cage/ontology.json` |
 | `pnpm exec cage gen --check` | 只比较需提交的生成物 | 不一致时报 CAGE-GEN；不是实际数据库漂移扫描 |
 | `pnpm exec cage test --only project` | 项目测试 | `.cage/test-results.json` 与终端 |
@@ -127,26 +130,18 @@ CSV 编码、限制、SDK 与完整接口见本项目自带的[业务页导入
 ## 验证要与改动匹配
 
 - 文档、文案、可逆的小改动：检查链接、格式、资料分发；不需要重复运行全套数据库测试。
-- 所有源码变更：按[注释交付清单](commenting.md#交付前逐项核对)人工核对中文职责、接口与关键流程说明；静态检查不能替代注释准确性检查。仅补注释时不新增复述实现的测试、不改写已执行迁移。
-- 命令/约束/反应变化：针对成功路径及真正的风险增加用例，如越权拒绝、额度边界、资源释放、同事务回滚。不要写只复述实现的测试。
+- 所有源码变更：按[注释交付清单](../reference/commenting.md#交付前逐项核对)人工核对中文职责、接口与关键流程说明；静态检查不能替代注释准确性检查。仅补注释时不新增复述实现的测试、不改写已执行迁移。
+- 命令/约束/反应变化：针对成功路径及真正的风险增加用例，如越权拒绝、业务条件边界、资源释放、同事务回滚。不要写只复述实现的测试。
 - 领域结构变化：check、gen、生成一致性、类型检查；有数据库影响时在独立测试库验证迁移和读写。
-- 页面或导航变化：构建后按[浏览器配方](routing.md)实际操作，包含深链接、新标签页、刷新、前进后退、登录回跳、无权限和 404。check/verify 不自动执行浏览器验收；未操作时明确报告未执行，不能写“页面功能完整”。
+- 页面或导航变化：构建后按[浏览器配方](../guides/routing.md)实际操作，包含深链接、新标签页、刷新、前进后退、登录回跳、无权限和 404。check/verify 不自动执行浏览器验收；未操作时明确报告未执行，不能写“页面功能完整”。
 - 发布前：按项目要求执行完整 verify/build/test，核对分发包。没有执行的项目明确写出原因。
 
 测试使用真实 PostgreSQL。`CAGE_TEST_DATABASE_URL` 供独立测试集群使用，测试工具会准备角色和临时数据库；不要指向业务/生产集群。没有设置时 testkit 可使用内嵌的真实 PostgreSQL，这与 dev 的固定已有库流程不同。
 
 派生测试无法凭空推断所有业务合法输入，会报告跳过。它们证明的是通用性质，不能代替采购 happy path、审批配置和第三方真实联调。
 
-## 可以交给 AI 的任务描述
+## 交付说明
 
-```text
-先读 AGENTS.md 和它指定的 docs/ai/README.md，再参考对应标准范例。
-需求：为某业务增加……
-先用 cage context 查询现有业务，必要时 graph inspect/path，确认候选与关系后阅读实现。
-说明字段、状态、能力与范围、事件/资源的影响，再修改 domain、生成契约和迁移草稿、接入业务页面。
-使用真实公开 API；不要手写业务路由、直接写表或新增本地数据库生命周期命令。
-按 docs/ai/commenting.md 给新建和修改代码写详细中文注释，覆盖职责、API/字段、步骤、原因和边界，同步修正相关上下游说明。
-按改动运行必要检查，报告通过/跳过/未执行项和需要的管理员配置。
-```
+可复用的需求输入见[任务模板](../guides/recipes.md#给编程工具的任务模板)，工作流程使用 Skill，不另维护一套提示词。
 
 交付说明至少包含行为变化、源文件、生成物/迁移、角色授权需求、详细中文注释覆盖的主要职责与边界、验证结果，以及尚未做的真实外部联调。注释未覆盖项如实说明，不能用聊天中的解释代替源码注释。遇到错误先修复根因；不把待办未生成、任务已接受或 fake 成功写成业务全部完成。

package/templates/app/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/app/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/{blank/docs/ai → app/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/app/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、授权或持久化行为。