@yss123/cage-cli 0.2.0 → 0.3.1

package/templates/app/docs/ai/ontology-context.md

@@ -4,6 +4,62 @@
 
 本页命令在**应用根目录**运行，使用项目安装的 CLI。工具直接分析当前注册的 domain，无需启动 API、worker 或数据库。不要把 Web 截图作为 AI 理解业务的唯一材料：优先取得结构化上下文，再按源码位置阅读实现。
 
+## 在浏览器按业务阅读
+
+运行 `pnpm exec cage graph` 打开业务地图，默认从业务板块进入，再选择完整流程，点击阶段查看规则与实现代码。声明了 `businessProcess` 的板块优先展示完整业务流程；其他板块按真实状态迁移展示对象生命周期。具体操作与查询收在折叠区中。模块目录下的业务对象归入同一板块，未分模块的项目按业务对象组织；查询、任务和外部通知按已声明的读取或调用关系出现在相关板块。系统组织模型默认隐藏，可单独开启。
+
+板块默认使用所属对象的中文名称。可在 `cage.config.json` 的 `graph.labels` 设置 `"module:purchase": "采购管理"` 这样的板块标题；未分模块的对象沿用 `aggregate:对象名`。板块标题属于显示配置，不改变节点身份、本体哈希或业务逻辑。
+
+完整流程以矩形展示业务阶段、菱形展示决定分支、圆角终点展示结束结果。绿色箭头标记业务走向，并注明参与人、自动或等待；棕色箭头标记展开的次要分支；虚线标记涉及的业务对象。取消等次要路径可以展开，审批通过/驳回等主要分支保持可见。主线保持同一轴线，侧面分支使用独立出口和通道，汇合复用已有阶段。长线在源节点附近也显示方向箭头，分支文字注明动作与去向，回路入口注明来源；文字放在线旁，悬停或点选连线可突出显示对应的起点与终点。
+
+主要实现绑定了代码审批路由的阶段默认展开为审批子流程：按声明顺序展示每一步的标题、审批人、任一或全部同意规则；条件用菱形展示，“是”进入该组审批，“否”从侧边跳过整组，再继续后续步骤。所需步骤全部通过才继续业务，任一步骤驳回则结束本轮审批。审批字段和角色使用 `graph.labels` 中的中文名称，点击容器仍可查看原审批及路由源码。未抽取到绑定路由时明确提示缺少步骤；取消审批只作为终止动作展示。这是声明的静态阅读图，不表示某张单据当前走到了哪一步。
+
+普通滚轮以光标为中心缩放，空白处拖动平移；选择模式下可拖动节点，箭头随之更新，抓手模式、空格或中键可从任意位置平移。工具栏支持横向/纵向布局、100% 缩放、适应画布、回到起点、重置节点布局及展开画布（Esc 退出）；触屏支持单指平移与双指缩放。长流程首次按可读字号展示起点，点击“适应”查看全图。点击节点或箭头打开步骤详情与代码面板，查看详情和切换页签保留当前视野与手动布局；这些调整只影响本次页面中的展示，不改写业务声明。
+
+展开具体操作时，触发图只沿事件触发、反应调用、审批结论与外部成功回写展开，异步连线使用虚线。任务的 calls 只表示可调用，反应的 map 仍可能返回 null；读取依赖、同对象归属、状态相接不表示操作必然依次执行。旧项目的生命周期只展示允许的状态迁移，不把人工的下一步当作自动执行。
+
+“实现代码”预览本次抽取保存的完整声明调用，包括 handler、map 或审批路由，提供文件和行号；依赖中的帮助函数仍需按源码阅读。字段、状态和能力点只有聚合位置时，明确显示所属聚合的声明；依赖包没有本地源码位置时不伪造预览。服务只按已注册节点提供快照中的代码，不接受任意文件路径。改代码后点击“重新抽取”，图谱、代码和复制的 AI 上下文才一起更新。
+
+板块、流程、步骤和代码页签保存在 URL 中，支持复制地址、刷新及前进后退。需要查看字段或全部技术关系时，切换“对象与字段”或“完整本体”；步骤详情也可直接进入完整本体及复制 AI 上下文。
+
+## 声明完整业务流程
+
+`businessProcess` 把已有执行声明组织成业务阅读规格，适合把申请、审批、履约、结算串成一条完整主线。它不调度命令、不生成写接口，也不改变数据表或授权。跨模块流程放在 domain 的 `workflows`，单个模块内的流程可放在对应模块，所有引用及流程本身都从 domain 入口导出。
+
+采购范例的完整声明位于 `packages/domain/src/workflows/purchase-process.ts`（空白项目在采购参考源码目录中查找）。以下片段说明主要选项，变量引用该范例已有的聚合、命令和审批：
+
+```ts
+export const purchaseOverview = businessProcess('purchase-overview', {
+  title: '采购申请到批准', description: '看清申请人提交与审批结论。',
+  area: { id: 'purchase', title: '采购管理', description: '采购申请、审批、收货与库存协作。' },
+  subject: PurchaseOrder, entry: 'create',
+  stages: {
+    create: { title: '填写采购申请', description: '保存采购草稿。', actor: '申请人', action: create },
+    submit: { title: '提交申请', description: '校验后提交审批。', actor: '申请人', action: submit },
+    review: { title: '采购审批', description: '按现有审批规则选人。', kind: 'decision', action: poApproval },
+    approved: { title: '批准并锁定库存', description: '审批通过后同事务占用库存。', kind: 'end', action: approve,
+      related: [{ object: InventoryLock, label: '锁定采购所需库存', via: acquireLock }] },
+    rejected: { title: '审批驳回', description: '本轮采购申请结束。', kind: 'end', action: reject },
+  },
+  transitions: [
+    { from: 'create', to: 'submit', mode: 'manual', label: '申请人提交' },
+    { from: 'submit', to: 'review', mode: 'automatic', label: '启动审批' },
+    { from: 'review', to: 'approved', mode: 'automatic', label: '审批通过' },
+    { from: 'review', to: 'rejected', mode: 'automatic', label: '审批驳回' },
+  ],
+});
+```
+
+- `action` 引用该阶段的主要实现；`details` 可补充命令、反应等实现依据，点击后能分别查看代码。
+- `manual` 的目标必须允许用户调用；`automatic` 必须能沿真实触发链到达；`wait` 用于外部通知或定时处理。仅有状态相接不能证明自动执行。
+- `related` 的 `object` 引用实际聚合，`via` 引用本阶段实际可触发且涉及该对象的声明。对象关联显示为虚线，不参与流程先后排序。
+- `branch: true` 将次要路径收起；每个阶段都需要从入口可达，并能到达至少一个 `kind: 'end'` 的结果。回路直接指向原阶段 ID。
+- 同一板块 ID 的名称和说明保持一致；流程按源码声明顺序展示，可把全流程放在专题流程之前。
+
+`cage check` 用 [CAGE-BIZ-001](../errors/CAGE-BIZ-001.md) 和 [CAGE-BIZ-002](../errors/CAGE-BIZ-002.md) 检查声明与实现关系。它不执行 handler、map 或审批，所以仍需业务回归证明运行行为。
+
+阶段直接使用 `title`、`description`、`actor` 的中文文案；操作和字段等继续用 `graph.labels`，审批角色可用 `"role:finance": "财务"`。状态也可在 `states(..., { labels: { draft: '草稿' } })` 中维护中文名；这些名称不更改原有状态标识。
+
 ## 开发一项需求的入口
 
 以采购模板为例：
@@ -94,16 +150,15 @@ command:PurchaseOrder.cancel
 ```powershell
 # 开发前：先取得上下文、阅读实际实现，再保存独立基线。
 pnpm exec cage context "采购单取消"
-pnpm exec cage analyze
-Copy-Item .cage/ontology.json .cage/before-change.json
+pnpm exec cage snapshot save before-change
 # 在源码修改业务声明和实现……
 pnpm exec cage check
 pnpm gen
-pnpm exec cage impact --base-file .cage/before-change.json
+pnpm exec cage impact --snapshot before-change
 # 按影响和实际风险选择必要测试，审查迁移与管理员授权。
 ```
 
-查询也会更新 `.cage/ontology.json`。基线必须在改代码前另存，保留到验收结束，不能把每次被覆盖的当前图当作旧图。`context` 用于开发前定位，`impact` 用于修改后比较；二者都不能替代业务验收。
+`context`、`graph search/inspect/path` 不写入当前 `.cage/ontology.json`；`analyze/gen` 才更新当前图。命名快照写到 `.cage/snapshots`，同名拒绝覆盖，`snapshot list` 显示保存时间、版本与指纹。独立本体图文件和真实 Git 基线仍可使用。基线保留到验收结束，不能把修改后的当前图当作旧图。`context` 用于开发前定位，`impact` 用于修改后比较；二者都不能替代业务验收。详见[诊断与快照](diagnostics.md)。
 
 可直接交给编程工具的要求：
 

package/templates/app/docs/ai/primitives.md

@@ -4,6 +4,8 @@
 
 本页代码使用当前公开导出。完整文件示例可直接放入应用；标为“片段”的代码需要结合采购范例已有符号使用。不要把片段中的变量名当成新的框架 API。
 
+文件字段使用 `file({ maxBytes, accept }).optional()` 或 `files({ maxBytes, accept, maxCount })`。字段保存文件 ID，上传/续传先获得临时文件，最终通过业务命令绑定；完整流程、限制和存储配置见[文件指南](files.md)。
+
 ## 最小的增、查、改、归档业务
 
 下面是完整的 `packages/domain/src/modules/note/note.ts`。它演示带部门范围的便笺，不影响采购范例原有业务；需要此业务时才添加文件。
@@ -167,6 +169,33 @@ export const releaseOnCancel = reaction(OrderCancelled, {
 
 事件默认载荷映射的具体命名规则见真实 `event.ts` 与范例；映射不明确时使用 `emit` 显式声明。已部署事件只做兼容扩展，新增字段设 optional；不兼容含义用新事件并考虑旧 outbox 消费，不能只改消费者。
 
+### 有界集合与步骤顺序
+
+同一事件需要对 20 台设备调用相同命令时，用 `reactionEach` 声明一次。下面为局部片段，`EquipmentAllocated` 事件含 `assets: [{ assetId }]`，`acquireAsset` 为已导出的目标命令：
+
+```ts
+import { reactionEach } from '@yss123/cage-kernel';
+
+export const acquireAllocatedAssets = reactionEach(EquipmentAllocated, {
+  command: acquireAsset,
+  items: event => event.assets,
+  maxItems: 20,
+  orderBy: 'assetId',
+  order: 20,
+  tx: 'same',
+  acquires: 'asset.use',
+  map: (item, _event, _index) => ({ id: item.assetId }),
+});
+```
+
+`maxItems` 是执行上限，输入 schema 也应表达业务上限。`orderBy` 必须是各项真实存在、非空、同类型且唯一的字符串或有限数值键；按键升序串行执行，以稳定资源锁顺序。`map` 收到排序后的索引，可返回 null 跳过；映射和选择器都是纯函数。
+
+失败诊断中的 `itemIndex` 是跳过 null 后的实际执行输入索引；`sortedIndex` 是排序后原项位置，`originalIndex` 是事件数组原位置，`itemKey` 是稳定排序键，均使用零基索引。诊断不附完整项载荷。
+
+多个跨对象步骤用 `order` 表达预算 → 设备 → 占用明细等依赖。同事件同 `tx` 分组一旦使用 order，所有步骤必须提供互不重复的非负整数。普通 `reaction` 也支持 order；不要靠导出变量的编号表达流程顺序。
+
+`tx: 'same'` 的集合仍走每一条目标命令的授权、约束、审计与版本流水线，任一失败使主命令及整个同事务链回滚。默认 outbox 集合由 worker 串行调用并随该消费者事务提交；重试与死信仍按事件处理。图谱和 context 展示目标、上限、排序键、顺序和事务。框架不替业务决定整单或分批：配发整单可用一个命令及其同事务集合，分批归还则每次提交的一批共同回滚。
+
 ## 两种查询写法
 
 下面两段均为完整声明，可选择需要的写法。它们都走只读连接与安全视图；调用人需要 `PurchaseOrder.read`，并受其范围与掩码限制。
@@ -202,6 +231,10 @@ export const recentOrders = query('recentOrders', {
 
 `sql` 与 `build` 必须二选一。SQL 用数据库的 snake_case 列名和 `:参数名`；不要拼接输入，也不要查询 `core.*`/`sys.*` 基表。`reads` 列出所有涉及的聚合，不能漏掉 join 的对象。业务前端调用生成的 `queries.*`，不复制查询 SQL。
 
+有目的级审计要求时，在 query 中声明 `audit: { purpose: '月度结算核对' }`。目的应为固定说明，不包含敏感输入。查询会先可靠写入用途审计再交付结果；潜在敏感明文还按 `reads` 保守审计，不假定任意 SQL 投影能精确推导字段和对象。审计故障返回 `CAGE-AUDIT-001`，不交付查询数据。完整保证见[审计矩阵](architecture.md#审计保证)。
+
+通用列表参数要求正安全整数 page/pageSize；数值筛选必须有限并满足字段 schema，布尔只接受 true/false，日期必须合法，排序字段必须来自公开字段。非法值返回字段级 `INVALID_INPUT`，不会把任意非 true 字符串转成 false。当前仍采用 offset 分页及精确计数，大规模分页成本需按实际数据测量。
+
 ## 审批绑定与选人
 
 下面是完整的采购路由文件形状，使用同目录现有的采购符号：
@@ -228,7 +261,7 @@ export const poRoute = route('po-approval', [
 
 `approval` 绑定事件与结论命令；`route` 决定步骤与人；`routable` 限制交给路由的数据字段。`onApproved/onRejected` 必须属于同一聚合，且允许 process 调用。
 
-内置选人器是 `approver.deptLeader(字段名)`、`approver.role(角色code)`、`approver.user(用户id)`。条件使用 `gt/gte/lt/lte/eq/ne/isIn` 等封闭表达式。`mode: 'any'/'all'` 描述一步内的人如何完成，不表示任意并行分支。可以在代码组合这些能力；任意函数选人、转签和加签需框架扩展或外部审批适配器，当前不能直接写成现成 API。
+内置选人器是 `approver.deptLeader(字段名)`、`approver.role(角色code)`、`approver.user(用户id)`。条件使用 `gt/gte/lt/lte/eq/ne/isIn` 等封闭表达式。`mode: 'any'/'all'` 描述一步内的人如何完成，不表示任意并行分支。人工节点可通过 `actions: { transfer: true, delegate: true, addSign: true }` 显式开放转办、委派归还和当前节点并行必签，默认关闭；任务版本、权限、SDK 与边界见[审批任务流转](approvals.md)。任意函数选人、前后加签和并行流程分支仍需扩展。
 
 被选中的审批人还要具备结论命令所需能力、范围和额度。部门负责人为空会产生 `CAGE-APPR-007`，详见[排错](troubleshooting.md)。
 

package/templates/app/docs/ai/project-structure.md

@@ -4,6 +4,8 @@
 
 两种模板使用同一规则：采购模板提供完整业务，空白模板保留认证和工作台。不要为小功能创建空目录；文件确实承担独立职责时再拆分。
 
+目录表达代码归属，[详细中文注释规范](commenting.md)说明每个文件及接口如何被理解和使用。框架与脚手架应用的新建、修改源码都必须执行这份规范，职责说明和实现一起交付。
+
 ## 项目分工
 
 ```text
@@ -14,8 +16,9 @@
 │  │  └─ worker.ts                # 启动异步任务，按环境装配连接器 fake
 │  └─ web/src/
 │     ├─ main.tsx                 # 挂载 React、全局 Provider 和样式
-│     ├─ app/                     # 会话恢复、布局、导航、模块组合
+│     ├─ app/                     # 会话恢复、URL 路由、布局、模块组合
 │     │  ├─ app.tsx
+│     │  ├─ use-session.ts        # 会话恢复和 401 回跳，不把网络故障当成未登录
 │     │  ├─ workspace-layout.tsx
 │     │  └─ styles/global.css
 │     ├─ modules/                 # 按业务命名，一个模块内管理它的页面和交互
@@ -71,7 +74,7 @@
 3. 需要驱动其他模块时，把 reaction 放在 `workflows/expense-xxx.ts`，从双方模块公开入口取声明。第三方接口放 `integrations/<系统名>.ts`，声明 hosts、schema、secret 名、outbound/inbound，不直接发网络请求。
 4. 运行 `pnpm gen`，审查 `contracts/src/aggregates/expense/index.ts` 和迁移草稿。根 `@app/contracts` 自动导出 Expense API/类型。不要在 contracts 里手工建“报销 service”。
 5. 在 `apps/web/src/modules/expense/pages/expense-list-page.tsx` 使用生成 hooks。新建表单放该模块 `components/expense-form.tsx`，模块专用 hooks 放自己的 `hooks`，专用接口封装按需放自己的 `api`，专用常量留在模块内。
-6. 从前端模块 `index.ts` 导出页面，应用壳从 `../modules/expense` 引入并接入导航。页面自己拥有筛选、分页、弹窗和提交状态；不要把它们全移到 App 或 Workspace。
+6. 从前端模块 `index.ts` 导出页面，应用壳从 `../modules/expense` 引入并注册列表、详情 URL，通过 Outlet 放入工作台布局。导航用 Link/NavLink，筛选和分页用 useSearchParams；弹窗和提交状态留在页面，不把整个页面切换写成 useState。按[路由指南](routing.md)验收深链接、刷新、前进后退和登录回跳。
 
 前后端可以有相同的业务模块名，但文件不混放：领域定义授权和行为，前端管理交互，通过生成契约连接。API 启动入口维持薄壳，普通业务无需新增 controller/service/repository。
 
@@ -107,7 +110,9 @@
 - 入口只挂载或组合；页面主要描述页面流程。表单、表格或交互已承担独立职责时再抽取，避免一个大组件处理所有业务，也避免每个按钮都新建文件。
 - 全局主题、reset、基础布局放 `app/styles`；业务专用样式与组件就近放置，可用 CSS Modules。不要把所有新增业务样式长期追加进一个全局文件。当前范例保留既有全局主题，结构调整不重新设计界面。
 - 单测与被测代码相邻，使用 `*.test.ts(x)`。需要真实业务链路的集成用例与所属业务模块相邻；框架的测试发现递归查找，不必为它回到 src 根目录。
-- 新代码写清职责、关键流程和设计原因，特别是事务边界、状态迁移、缓存刷新和权限展示。不要给每行语法写翻译，不加无业务价值的防御分支和静默兜底；脚本使用 TypeScript，不新增 `.mjs`。
+- 新建和修改的手写源码文件必须有中文职责、主要调用链与运行边界说明；模块入口也要说明公开职责。导出函数/类/声明、React 组件/hooks、接口及类型字段使用中文 JSDoc，复杂私有函数与关键分支解释具体步骤、原因和边界，详细要求见[注释规范](commenting.md)。
+- 业务字段说明单位、格式、空值与来源；命令说明输入、权限、状态、读依赖、事件、事务与失败行为；页面说明 URL、数据加载、权限和错误交互；测试说明意图与覆盖边界；脚本说明前置条件、写入/覆盖等副作用。修改已有代码时同步补齐受影响的上下游注释，不能只更新当前实现。
+- 注释必须准确、充分，不以“代码自解释”免除必要说明，不用每行语法翻译、注释字数或比例充数。生成注释从声明/生成器维护，已执行或已发布迁移不可因补注释而重写。不加无业务价值的防御分支和静默兜底；脚本使用 TypeScript，不新增 `.mjs`。
 
 ## 自动约束与整理已有项目
 

package/templates/app/docs/ai/purchase-example.md

@@ -11,9 +11,11 @@
 | `packages/domain/src/index.ts` | 哪些声明真正被注册 | 保留组织模型，导出新增业务，避免导出名冲突 |
 | `packages/domain/src/modules/inventory/inventory.ts` | 最简字段、创建命令、资源锁聚合 | scope.none 不等于无需授权；创建与释放都是命令 |
 | `packages/domain/src/modules/purchase/purchase-order.ts` | 单据生命周期、金额、明细、约束、事件 | 哪些字段由输入提供，哪些由内核维护；每个状态的允许操作 |
+| `packages/domain/src/modules/purchase/approval-members.ts` | 采购协作名录与公开业务姓名 | 名录读权限与系统用户资料分离；成员身份不授予审批权限 |
 | `packages/domain/src/workflows/purchase-inventory.ts` | 同事务建锁、异步释放 | acquires/releases 的配对及 map 返回 null 的原因 |
-| `packages/domain/src/modules/purchase/approvals.ts` | 启动/取消审批、条件步骤与选人 | routable、部门负责人、角色 code、结论命令 |
+| `packages/domain/src/modules/purchase/approvals.ts` | 启动/取消审批、专业会签、财务候选与任务动作 | routable、部门负责人、字段选人、候选领取、结论命令 |
 | `packages/domain/src/integrations/erp.ts` | 出站推单、成功回写、入站回调 | 白名单、secret 名、schema、幂等与 HMAC |
+| `packages/domain/src/integrations/intelligence.ts` | 消费框架托管模型和本体助理 | Admin 配置连接，通用工具由框架生成 |
 | `packages/domain/src/modules/purchase/queries.ts` | 按状态汇总 | reads、安全视图、命名参数 |
 | `packages/domain/src/modules/purchase/jobs.ts` | 过期草稿取消 | reads/calls 和 job 调用身份 |
 | `apps/api/src/main.ts`、`apps/api/src/worker.ts` | 如何启动框架与 worker | 保持薄装配，fake 只用于相应环境 |
@@ -27,8 +29,13 @@
 ```text
 采购员新建 → draft
   → submit → pending_approval + OrderSubmitted（同事务提交）
-  → worker 消费事件 → 按 poRoute 创建经理待办
-  → 经理审批；金额 > 50000 时还有财务步骤
+  → worker 消费事件 → AI 材料预审
+      → 材料不足：returnForChanges → draft，补充用途后重新提交、从头审核
+      → 疑难材料：在本节点创建人工接管待办
+      → 材料清楚：通过本节点，创建经理待办
+  → 部门经理审批
+  → 申请启用专业复核时：所选专业人员全部会签
+  → 金额 > 50000 时：财务共享候选任务，由 finance 成员领取后处理
   → 流程完成 → 调用 approve
       → 职责分离、额度、库存检查
       → approved + OrderApproved
@@ -41,11 +48,12 @@
 
 submit 返回成功只表示单据和事件已提交，不表示待办、ERP 或其他异步工作已经完成。worker 未运行时，单据可以已经处于待审批，但没有待办。
 
-### 为什么分三个聚合
+### 为什么分开单据、库存与协作名录
 
 - `PurchaseOrder` 管单据、审批结论和采购状态。
 - `Inventory` 是物料台账，提供库存检查的数据。
 - `InventoryLock` 记录某张订单的资源占用，使用订单 id 作为锁 id，让释放目标明确。
+- `ApprovalMember` 保存采购参与者可读取的公开业务姓名和专业说明。它引用真实用户，但不开放 `User.name` 等系统用户资料，也不代替角色授权。
 
 审批通过和建锁放在同一事务，是为了避免“单据已批准却没拿到资源”。ERP 网络请求放到 outbox，是因为远端调用无法与本地 PostgreSQL 共同回滚。
 
@@ -67,15 +75,35 @@ submit 返回成功只表示单据和事件已提交，不表示待办、ERP 或
 
 | 对象 | 配置要点 |
 | --- | --- |
-| 采购员 | 创建/查看/提交/取消采购单等所需能力，所属部门，以及采购单数据范围 |
-| 经理 | `PurchaseOrder.read/approve/reject`，适当数据范围，`approve` 的 `ceiling` 额度参数 |
+| 采购员 | 创建/查看/提交/取消采购单等所需能力，所属部门，以及采购单数据范围；配置专业复核需 `PurchaseOrder.setReviewers` 和 `ApprovalMember.read` |
+| 智能助理使用人 | 显式授予 `Sys.ai.use`；编辑用途还需 `PurchaseOrder.explainPurpose` |
+| 模型管理者 | `Sys.ai.models.manage`；在 `/admin/#/models` 配置并启用 `main`，部署主密钥见[智能能力指南](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` |
+| 名录管理员 | 显式授予 `ApprovalMember.create/update/retire/read`；登记、更新资料或退役不修改用户角色，不自动给采购参与者授予 `User.read` |
 | 部门 | 将采购员所属部门的负责人设为经理；不能为空 |
-| 财务 | 角色 **code** 为 `finance`，给实际用户分配；配置审批所需权限、范围及额度 |
+| 财务 | 角色 **code** 为 `finance`，给至少两位实际用户分配以体验共享候选池；配置审批所需权限、范围及足够额度；领取后才能处理 |
 | 库存台账 | 预先登记与采购明细相同的 sku，数量满足演示检查 |
 | 连接器环境 | fake 阶段使用 worker 注册的 fake；真实环境另配 host 对应密钥及回调签名密钥 |
 
 经理与提单人必须是不同用户。配置“负责人”决定选谁；配置角色能力与范围决定此人能否完成结论命令，两者都需要。金额 **大于** 50,000 才追加财务步骤，恰好 50,000 不满足 gt 条件。
 
+专业复核默认关闭，兼容旧单据的空字段；开启后需选择 1–5 位不同且非提单人的有效名录成员。`setReviewers` 只允许编辑草稿；创建可暂存未选完整的草稿，但 `submit` 会重新核对名单，拒绝保存后退役的成员。名录退役不修改已经提交的名单快照，也不撤销在途任务；账号停用和实际审批权限继续由审批引擎核验。名录的用户引用不能换绑，已退役记录保留且不支持重新启用。
+
+`ApprovalMember` 使用 `scope.none()`，没有部门或本人字段。名录管理员和需要选人的采购参与者都必须显式获得该聚合的 `all` 数据范围；仅授予 `ApprovalMember.read` 仍看不到成员，草稿的专业名单校验也会因读范围不足拒绝。这里的 `all` 始终受当前租户隔离，不要求也不授予 `User.read`。
+
+经理、专业会签和财务节点均显式启用转办、委派与前置/后置/并行加签，节点政策随每次提交保存。转办交接处理责任；委派处理完成后归还原审批人；加签增加必须完成的签署任务，前置签署完成前原任务等待，后置签署在原任务通过后才开放。任务动作和决定都应携带页面当前 `revision`，冲突后刷新待办，不自动重试旧决定。AI 人工接管继续采用 AI 节点自身政策，不能因为后续经理节点启用动作而越权操作。
+
+逐项体验时用不同采购单分别记录：普通经理审批、专业双人会签、恰好 50,000 元跳过财务、超过 50,000 元财务领取/释放/再领取、转办、委派归还、三种加签，以及退回重提和申请人取消。每一步同时查看采购状态、当前可操作/等待任务及动作历史；专业会签只通过一人或必签尚未完成时采购单应仍待审批，最终通过才产生库存锁。浏览器验收需切换真实账号进行，自动测试通过不能替代页面验证。
+
+可分别准备“采购办公用品”、说明实际使用场景的完整用途、含“紧急采购”的用途，体验退回、通过本节点和转人工。真实模型的判定应按实际样例验收；故障默认转人工，不能当作正常审查通过。详情页显示历史理由、修改建议及审核轮次；用途编辑框的未保存内容会经 SDK 一起传给助理，服务端重新核对当前单据与权限。
+
+拥有 `Sys.ai.use` 的用户在所有业务页面右下角都有助理入口，点击打开悬浮对话窗，收起后继续执行当前任务。工作台、采购列表/详情、库存和待办分别提供页面语义；列表带筛选与可见记录，详情带单据引用和未保存用途。应用壳只挂载一个 `AssistantScope`，业务页面通过 `AssistantPage` 注册上下文，所以站内切页保留对话，但下一条消息使用新页面的快照。不同页面拥有独立的 `AiPageContext` 身份，旧任务要求补充页面时不能提交新页面代替。登录页和独立的 `/admin/` 不挂载业务助理。
+
+悬浮窗的“相处方式”选择器消费框架 `useAssistant` 的性格目录和切换接口。默认跟随 Admin 设置，也可为当前会话选择其他已启用性格；切换不清空对话，旧回复保留生成时的性格名称。采购范例没有单独的性格表或 Prompt 拼接逻辑，AI 审批继续使用原节点策略。
+
 ## 页面如何使用框架
 
 采购页和库存页通过 `@app/contracts` 获取方法、快照类型和查询 hooks。命令成功后刷新相应列表；失败时按 code/domainCode 展示原因。只有允许 user 调用的命令才生成页面方法，因此审批通过应使用待办接口。

package/templates/app/docs/ai/recipes.md

@@ -4,6 +4,8 @@
 
 本页用于把用户的业务描述转成 Cage 项目的可执行修改。按需要读对应配方即可，不需要修改框架内部。
 
+需要 AI 审批、业务助理、随页聊天、模型管理或性格配置时，先用 `cage capabilities` 查框架能力，再按[原生智能化指南](intelligence.md)接入。普通业务建模仍按下文声明聚合和命令；接入已有框架服务无需另建一套通用后端。
+
 ## 先把需求落到一张业务表
 
 开始编码前，从用户需求或现有业务中确定以下信息。能从上下文确认的直接使用；真正缺失且影响实现的再询问，不要为技术细节反复让用户确认。
@@ -22,7 +24,7 @@
 
 按[最小便笺业务](primitives.md)新增 `packages/domain/src/modules/<业务>/<对象>.ts`：字段、范围、不变量、create/update/archive 命令。采用唯一的导出名和必要的 `name` 覆盖，避免 index 的 `export *` 丢失重名符号。
 
-从模块 index 到 domain 入口导出后运行 check/gen，审查迁移，再在 `apps/web/src/modules/<业务>` 使用生成 contracts 做列表、表单和操作按钮，经模块公开入口接入 app。最后给角色授权并补图谱中文名。完整归属规则见[目录规范](project-structure.md)。不要手写增删改查路由、ORM 实体与 repository，也不要复制框架鉴权代码。
+从模块 index 到 domain 入口导出后运行 check/gen，审查迁移，再在 `apps/web/src/modules/<业务>` 使用生成 contracts 做列表、详情、表单和操作按钮，经模块公开入口注册到 app 路由。列表和详情都有独立 URL，筛选/分页进入 query，按[浏览器配方](routing.md)检查导航。最后给角色授权并补图谱中文名。完整归属规则见[目录规范](project-structure.md)。不要手写后端增删改查路由、ORM 实体与 repository，也不要复制框架鉴权代码。
 
 完成标准：授权用户能创建和修改，范围外数据不可见，归档后的允许行为符合业务要求，生成契约和迁移一致。没有审批需求时不必添加审批；没有外部系统时不必添加连接器。
 
@@ -40,7 +42,13 @@
 4. 配置实际部门负责人、角色或指定用户；给审批人配置能力、范围和额度。
 5. 页面通过待办接口操作。通过后需占用资源时用反应调用资源命令，按业务一致性选择同事务。
 
-完成标准：提交生成待办、正确的人审批、越权和自审批拒绝、取消能结束待办、资源配对完整。任意流程设计器、动态 JS 选人、转签/加签不属于当前现成能力，需要明确扩展范围。
+完成标准：提交生成待办、正确的人审批、越权和自审批拒绝、取消能结束待办、资源配对完整。转办、委派归还和当前节点并行必签见[审批任务流转](approvals.md)，须显式启用政策并传任务版本。任意流程设计器、动态 JS 选人、前后加签和指定节点退回仍需明确扩展范围。
+
+## 加入 AI 审批或随页助理
+
+先检查 domain 是否已经导出 `ai()`，再按需求修改已有声明或启用一次。AI 审批配置在业务模块的现有 `step` 内，填写 `kind: 'ai'`、审核策略、取证字段/查询与 `handoff`，由 `approval` 绑定自动执行角色和结论命令。业务助理使用框架生成的工具，前端通过 `useAssistant` 与 `useAiPageContext` 接入当前页面；悬浮窗、Markdown 和确认交互由应用实现。
+
+模型地址、协议和密钥通过 `managedModel` 对应的 Admin 配置管理，性格也使用框架现有管理页。先完成系统迁移和必要授权，按[智能化指南](intelligence.md)的接入顺序、SDK 示例和验收步骤验证。分别说明框架支持、应用已启用和真实联调结果；空白模板中的参考代码不参与运行。
 
 ## 增加报表或复杂列表
 

package/templates/app/docs/ai/routing.md

@@ -0,0 +1,86 @@
+# 业务前端路由与浏览器验收
+
+[返回学习入口](README.md) · [工程目录](project-structure.md) · [开发步骤](workflow.md)
+
+多页面业务默认使用 React Router 的 BrowserRouter。列表、详情、报表等可独立访问的页面必须有 URL；在 app 中统一组合路由和工作台布局，页面从模块 index.ts 导出。useState 用于弹窗、未提交表单和按钮忙碌状态。筛选、分页和需要分享的选项使用 useSearchParams。
+
+本页对应后续开发版本的模板改进；已发布的 0.2.0 项目需要按本页迁入路由实现，不能只升级依赖就认为旧页面已完成改造。框架包无需维护客户的页面地址。
+
+## 模板中的可运行示例
+
+| 页面 | 空白模板 | 采购模板 |
+| --- | --- | --- |
+| 登录 | `/login` | `/login` |
+| 工作台 | `/workspace` | `/workspace` |
+| 列表 | `/directory/users?page=2` | `/procurement/orders?status=draft&page=2` |
+| 详情 | `/directory/users/:id` | `/procurement/orders/:id` |
+| 其他业务 | 按实际需求新增 | `/inventory`、`/approvals` |
+| 404 | 未匹配页面显示“页面不存在” | 同左 |
+
+`:id` 替换成真实记录 ID。空白模板的成员目录读取已有 User 组织模型，不注册额外业务、演示表或虚假数据；列表与详情均需要 User.read，数据范围由安全接口落实。采购待办的 businessKey 由 app 映射成采购详情链接，审批模块不直接导入采购模块。
+
+在应用根目录运行 pnpm dev 后访问终端打印的 Web 地址。先在系统管理配置真实账号与权限，再从列表复制某条记录的详情 URL，用于刷新和新标签页测试。
+
+## 新增一项业务页面
+
+1. 在 `apps/web/src/modules/<业务>/pages` 编写列表、详情和表单，从模块 index.ts 导出。详情用 useParams 读取 ID，再用生成的 use对象(id) 获取记录；不要求先打开列表，也不从组件状态或上一页传来的对象直接认定记录存在。
+2. 在 `apps/web/src/app/app.tsx` 注册列表与详情 Route。放在已有会话守卫和 WorkspaceLayout 之下，使页面通过 Outlet 渲染。新增实际页面时扩展路由表；不要再添加 tab/page useState 来选择整页。
+3. 导航使用 Link / NavLink；完整页面地址可收藏、复制或新标签页打开。列表筛选和分页通过 useSearchParams 更新，刷新和前进后退恢复相应查询。
+4. 需要 read 能力的页面用共享 RequireCapability 提供直接访问时的提示；服务端返回 FORBIDDEN 时显示权限提示，NOT_FOUND 显示“记录不存在，或不在当前可访问范围”。401 由会话回调进入登录。不要把 403 当成登录失效，也不要通过放宽读权限解决页面导航问题。
+5. 用下面的浏览器配方验收，并报告通过、跳过与未执行。构建和 cage verify 通过，只证明其各自检查范围，不能据此宣称路由体验正确。
+
+```tsx
+// app 中的组合片段：页面通过所属模块的 index.ts 导出。
+<Route element={<WorkspaceLayout onLogout={onLogout} />}>
+  <Route path="procurement/orders" element={<PurchaseOrdersPage />} />
+  <Route path="procurement/orders/:id" element={<PurchaseOrderDetailPage />} />
+</Route>
+```
+
+片段只展示路由与布局关系。实际代码参考本模板 app.tsx，保留会话守卫、页面 props 和能力提示。`cage/no-manual-routes` 限制手写后端业务 HTTP 路由，不禁止 React Router；前端导航不会生成能力或授予数据访问权。
+
+## 登录后返回原地址
+
+应用启动先 loadMe 恢复会话。未登录访问详情时，守卫使用 replace 导航到 `/login?returnTo=编码后的原路径`，包含 query 和 hash。登录完成再次 replace 回原页面，避免浏览器后退反复落入登录页。
+
+`shared/lib/navigation.ts` 的 loginReturnTo 只接受应用内页面，排除外站、登录循环及 API/admin 等服务端入口；不要直接把用户提供的任意 returnTo 交给 location.href。网络错误显示重试界面并保留地址，只有 UNAUTHENTICATED 才要求重新登录。运行中会话过期同样保存当前 URL，并清除上一账号的查询缓存。
+
+前端路由守卫只改善导航与提示。请求仍由 Cage HTTP 和内核检查会话、能力、租户、数据范围与掩码；直接请求接口必须得到相同约束。
+
+## 与系统管理及部署共存
+
+| 路径 | 所有者 |
+| --- | --- |
+| `/login`、`/workspace`、客户业务页面 | React Router |
+| `/admin`、`/admin/` 及其脚本/样式 | Cage 系统管理 |
+| `/api/`、`/auth/`、`/hooks/` | Cage HTTP 接口 |
+| `/assets/` | Vite 构建资源 |
+
+进入 `/admin/` 使用普通 `<a href="/admin/">`，让浏览器请求独立管理入口；应用内部页面使用 Link。不要在 React 中注册覆盖 /admin 或 /auth 的页面。Vite 配置已代理 API、认证与管理请求，开发环境支持业务深链接刷新。
+
+生产可选两种部署方式：
+
+- **Cage 托管 Web**：API 启动时提供 webDir，标准入口读取 WEB_DIR；将其设置为 apps/web/dist 的绝对路径。模板 Dockerfile 已复制构建产物并设置 WEB_DIR=/app/web。浏览器 GET/HEAD 页面请求可回退到 index.html，React 决定详情或 404；API、管理和丢失资源返回各自错误，不应变成业务首页。
+- **Nginx 托管 Web**：参考项目 `deploy/nginx.conf`，将 root 指向真实 dist，将 API/admin/auth/hooks 代理到 Cage；业务页面使用 try_files 回退到 index.html，/assets/ 缺失时直接 404。示例按 Nginx 与 API 在同一主机、API 端口 3000 编写；按部署拓扑修改上游。仅复制 dist 到没有 SPA 回退的静态服务器会导致详情刷新 404。
+
+上线前用实际反向代理地址验收深链接。Vite 开发环境成功，不代表 Nginx、CDN 或生产容器已配置正确。
+
+## 浏览器验收配方
+
+准备一条有权读取的真实记录和两个测试账号：有 read 能力及范围的账号、没有该能力的账号。测试账号和记录在独立验收环境准备，不修改生产角色。
+
+| 操作 | 预期结果 |
+| --- | --- |
+| 复制列表中某条详情 URL，在新标签页粘贴 | 直接加载对应记录，无需先访问列表 |
+| 在详情页刷新 | URL 和记录保持一致 |
+| 列表 → 详情 → 另一页面，再点浏览器后退、前进 | 地址、页面内容与导航高亮同步变化 |
+| 改变列表筛选/分页，复制地址或刷新 | 条件与列表恢复，不返回工作台或第一页 |
+| 未登录打开带 query/hash 的详情 URL | 进入登录；成功后回到原 URL，保留 query/hash |
+| 在业务页使测试会话过期，再触发读取 | 进入登录；重新登录后回到原页面，旧账号缓存不残留 |
+| 无 read 能力账号直接访问有效详情地址 | 显示权限提示，直接请求 API 仍为 403 |
+| 有 read 能力但记录位于范围外 | 显示记录不可用，直接请求 API 为 404，不泄露记录是否存在 |
+| 访问不存在的业务路径 | 显示应用 404，并有返回工作台入口 |
+| 访问 /admin/，以及缺失的 API/JS/CSS | 管理入口独立可用；缺失接口或资源不返回业务 index.html |
+| 在实际部署地址重复深链接和刷新步骤 | 正常加载，浏览器控制台无脚本 MIME 错误 |
+
+验收记录写明模板、地址、操作和结果。模拟 API 的浏览器检查可以证明导航行为；真实权限、范围和数据库链路需要相应集成验收，二者分别报告。

package/templates/app/docs/ai/troubleshooting.md

@@ -4,6 +4,8 @@
 
 先保留完整诊断的 code、源码位置、reason/fix、requestId 或 outboxId。检查所在阶段，再修复原因；不要通过改业务状态、给全局权限、注释约束或禁用 lint 消除现象。
 
+先执行 `pnpm exec cage doctor` 查看各阶段证据；异步动作按 requestId/outboxId/业务对象用 `cage timeline` 关联实际执行记录。能力、范围、调用身份或额度不清楚时，有权诊断的管理员可使用 `cage explain`，不会执行目标命令。完整参数与权限见[诊断指南](diagnostics.md)。
+
 ## 按现象定位
 
 | 现象 | 先查什么 | 常见原因 |
@@ -15,6 +17,9 @@
 | 详情 404 | 记录 id、租户和数据范围 | 不存在或在范围外；不能仅凭 404 断言被删除 |
 | 列表为空 | read 能力、范围与相应字段 | 默认本人范围、无 owner 字段或部门不匹配 |
 | 电话看不到明文 | sensitive 标注、unmask 能力 | 默认掩码是正常安全行为 |
+| 有明文能力但读取报 CAGE-AUDIT-001 | requestId、审计库可用性与权限 | 可靠审计未成功，框架拒绝交付结果 |
+| 生产服务拒绝启动 | CAGE-ENV-002/003、Cookie 密钥与 bootstrap 参数 | 关键配置不合格，或试图在日常启动时隐式初始化 |
+| 任务时间线有 CAGE-WORKER-002 | API/worker 版本、注册指纹和消费者清单 | 旧进程或必要消费者缺失，不能把 done 当作已执行 |
 | 提交成功但无待办 | worker、outbox/死信、审批路由 | 未投递、缺审批人、没有匹配的绑定/路由 |
 | 已批准但 ERP 单号未回写 | worker、同步记录、死信、环境/fake | 密钥/白名单/响应错误，或异步还未完成 |
 | 已取消但锁未释放 | 释放事件、反应、死信 | 先前消息阻塞、map 条件不匹配或遗漏释放 |

package/templates/app/docs/ai/workflow.md

@@ -1,6 +1,6 @@
 # 开发步骤与交付要求
 
-[返回学习入口](README.md) · [范例导读](purchase-example.md)
+[返回学习入口](README.md) · [范例导读](purchase-example.md) · [详细中文注释](commenting.md)
 
 本页命令在**应用根目录**执行，除非注明“框架根目录”。使用项目安装的 CLI：`pnpm exec cage ...`。项目脚本可简写为 `pnpm gen / pnpm migrate / pnpm dev / pnpm verify`；不要假定机器已全局安装 cage。
 
@@ -18,39 +18,44 @@ pnpm build:app
 pnpm gen
 # 审查 db/migrations 中的迁移草稿，再执行：
 pnpm migrate
+# 迁移后显式初始化组织，目标是新的受限凭据文件；父目录需存在。
+pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json
 pnpm dev
 ```
 
 `init` 自动创建独立账号与随机密码，填写 APP/READ/MIGRATE 连接和 Cookie 密钥，成功后删除文件中的管理员连接。三个连接使用同一数据库。已有 Cage 集群账号时复用原连接，不能重置其他应用的账号密码。生产环境可由平台直接提供账号连接，不必执行本地 init。
 
+`bootstrap` 独立初始化组织，不自动授予业务能力。管理员凭据只进入新的受限文件，不进入服务控制台；已有用户时不重置。交付后移除凭据文件。日常 API 启动不初始化组织；生产缺少合格 Cookie 密钥会拒绝启动。具体文件权限与诊断用法见[能力发现与状态诊断](diagnostics.md)。
+
 `.env.example` 是配置说明，`.env` 是本机私密配置，二者不混用。CLI 自动加载应用 `.env`，部署环境同名变量优先。API 和 worker 启动需重启后读取变更；不要输出整个 `.env` 排障。
 
 框架仓库首次先在根目录 `pnpm install`、`pnpm build`，再进入 `examples/purchase-admin` 配置。`dev` 不自动执行迁移；生成新迁移后要审查并显式运行 migrate。
 
 ## 做一项业务修改
 
-1. 读 AGENTS.md 和[目录规范](project-structure.md)，确认需求落在领域模块、前端模块、组织配置还是框架。先 `pnpm exec cage context "需求关键词"`，按需 `graph search/inspect/path` 定位，确认候选入口后阅读对应源码、范例与测试；证据和边界见[本体上下文指南](ontology-context.md)。发现能力缺口先说明，不编造 API。
-2. 涉及已存在业务含义变化时，**修改前**保存基线。已有 Git 可用提交，也可保存独立本体图文件。
-3. 在所属领域模块写字段、状态、不变量和命令输入；再实现 handler、事件、查询与审批。跨模块反应放 workflows，第三方协议放 integrations。从模块 index 到 domain 总入口逐层导出，避免跨文件 export 名冲突。
+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 导航；依赖生成 contracts，处理失败结果。新增能力由管理员授权，页面按钮可用 `useCan` 控制。
-7. 补足重要业务反例并运行相关验证。提交源声明、契约和审查过的迁移，报告跳过及未执行项。
+6. 页面和表单放 `apps/web/src/modules/<业务>`，从模块公开入口接入 app 的 URL 路由；依赖生成 contracts，处理失败结果。列表、详情等多页面使用 React Router，筛选和分页进入 URL；组件状态只管理页面内临时交互。新增能力由管理员授权，页面按钮可用 `useCan` 控制。按[路由与浏览器验收](routing.md)检查直达、刷新、前进后退和登录回跳。
+7. 补足重要业务反例并运行相关验证；测试解释夹具目的、所保护的规则和覆盖边界。按注释规范审查本次 diff，核对页面、组件/hooks、类型字段、脚本副作用和恢复流程的说明是否完整准确。提交源声明、契约和审查过的迁移，报告跳过及未执行项。
 
 ### 如何保存和比较基线
 
 ```powershell
-# 修改前执行，避免后续 gen/analyze 覆盖唯一的旧图。
-pnpm exec cage analyze
-Copy-Item .cage/ontology.json .cage/before-change.json
+# 修改前执行；同名快照不会覆盖。
+pnpm exec cage snapshot save before-change
 # 修改 domain 后执行：
-pnpm exec cage impact --base-file .cage/before-change.json
+pnpm exec cage impact --snapshot before-change
 # 或与真实可用的 Git 提交比较；下面的 main 应按仓库实际情况替换。
 pnpm exec cage impact --base main
 ```
 
 基线文件要保留到验收结束。影响分析用于找到相关命令、约束、审批、查询和候选测试，不能当作不需验证的证明。没有 Git 提交时不要为了让命令成功而擅自创建/推送远端。
 
+`context` 和图谱查询只返回查询结果，不更新当前图文件或命名基线；`analyze/gen` 更新当前图。快照来源时间、版本与图指纹随报告保存。
+
 ## 常见需求的具体改法
 
 | 需求 | 做法 | 必查项 |
@@ -82,6 +87,8 @@ if (!result.ok) {
 
 对自定义 HTTP 协议能力使用 `@yss123/cage-client`；它负责会话、CSRF 和类型化结果。需让多个提交共享幂等键时，按当前客户端接口显式传递同一次业务操作的 key，并在页面阻止重复进行中的提交。生成契约的方法签名以 `packages/contracts/src` 为准，不假设每个命令方法都支持自定义 options。
 
+生成方法最后的请求选项支持 `signal/timeoutMs/idempotencyKey`。底层返回 `CageResult`；`useCageCommand` 成功返回业务数据、失败抛出 `CageCommandError`，因此 mutation 的 `isSuccess` 表示业务成功。退出、401、切换账号时订阅 `client.subscribe` 取消用户查询并清除应用缓存，范例 `apps/web/src/app/use-session.ts` 展示了接法。
+
 ### 导入和导出属于业务页面
 
 框架提供通用异步接口与任务查询，页面放在哪里由具体业务决定。
@@ -98,6 +105,9 @@ 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 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` 保存结构化报告 |
@@ -117,8 +127,10 @@ CSV 编码、限制、SDK 与完整接口见本项目自带的[业务页导入
 ## 验证要与改动匹配
 
 - 文档、文案、可逆的小改动：检查链接、格式、资料分发；不需要重复运行全套数据库测试。
+- 所有源码变更：按[注释交付清单](commenting.md#交付前逐项核对)人工核对中文职责、接口与关键流程说明；静态检查不能替代注释准确性检查。仅补注释时不新增复述实现的测试、不改写已执行迁移。
 - 命令/约束/反应变化：针对成功路径及真正的风险增加用例，如越权拒绝、额度边界、资源释放、同事务回滚。不要写只复述实现的测试。
 - 领域结构变化：check、gen、生成一致性、类型检查；有数据库影响时在独立测试库验证迁移和读写。
+- 页面或导航变化：构建后按[浏览器配方](routing.md)实际操作，包含深链接、新标签页、刷新、前进后退、登录回跳、无权限和 404。check/verify 不自动执行浏览器验收；未操作时明确报告未执行，不能写“页面功能完整”。
 - 发布前：按项目要求执行完整 verify/build/test，核对分发包。没有执行的项目明确写出原因。
 
 测试使用真实 PostgreSQL。`CAGE_TEST_DATABASE_URL` 供独立测试集群使用，测试工具会准备角色和临时数据库；不要指向业务/生产集群。没有设置时 testkit 可使用内嵌的真实 PostgreSQL，这与 dev 的固定已有库流程不同。
@@ -133,7 +145,8 @@ CSV 编码、限制、SDK 与完整接口见本项目自带的[业务页导入
 先用 cage context 查询现有业务，必要时 graph inspect/path，确认候选与关系后阅读实现。
 说明字段、状态、能力与范围、事件/资源的影响，再修改 domain、生成契约和迁移草稿、接入业务页面。
 使用真实公开 API；不要手写业务路由、直接写表或新增本地数据库生命周期命令。
+按 docs/ai/commenting.md 给新建和修改代码写详细中文注释，覆盖职责、API/字段、步骤、原因和边界，同步修正相关上下游说明。
 按改动运行必要检查，报告通过/跳过/未执行项和需要的管理员配置。
 ```
 
-交付说明至少包含行为变化、源文件、生成物/迁移、角色授权需求、验证结果，以及尚未做的真实外部联调。遇到错误先修复根因；不把待办未生成、任务已接受或 fake 成功写成业务全部完成。
+交付说明至少包含行为变化、源文件、生成物/迁移、角色授权需求、详细中文注释覆盖的主要职责与边界、验证结果，以及尚未做的真实外部联调。注释未覆盖项如实说明，不能用聊天中的解释代替源码注释。遇到错误先修复根因；不把待办未生成、任务已接受或 fake 成功写成业务全部完成。

package/templates/app/docs/errors/CAGE-AI-001.md

@@ -0,0 +1,61 @@
+# CAGE-AI-001：智能运行时声明无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：领域声明 / 模型与运行预算配置。
+
+模型引用未配置、重复启用 AI 运行时，或上下文预算、重试、并发、超时、队列参数非法。
+
+## 修复步骤
+
+1. 在 domain 顶层导出一个 ai({ models, assistant }) 声明，审批 step 的 model 引用同名模型。
+2. 预算与并发为正整数；maxModelRetries 为 0 至 8，context.maxTools 最多 128（包含通用工具）。并发最多 32，单次运行 timeoutMs 最多 300000。API 与 worker 使用相同声明和模型配置。
+
+## 正例
+
+```text
+ai({ models: { main: provider }, assistant: { model: 'main', limits: { maxSteps: 8 } } })
+```
+
+## 反例
+
+```text
+ai({ models: {}, assistant: { model: 'missing', limits: { maxSteps: 0 } } })
+```
+
+## 修复后验证
+
+重跑 cage check、迁移与相关测试，再以真实角色验证助理和审批；fake 成功不代表真实模型联调完成。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/ai/src/index.ts:54`
+- `packages/ai/src/index.ts:61`
+- `packages/ai/src/index.ts:74`
+- `packages/ai/src/index.ts:82`
+- `packages/ai/src/index.ts:86`
+- `packages/ai/src/index.ts:88`
+- `packages/ai/src/index.ts:89`
+- `packages/ai/src/index.ts:90`
+- `packages/ai/src/index.ts:92`
+- `packages/ai/src/index.ts:94`
+- `packages/ai/src/index.ts:96`
+- `packages/ai/src/index.ts:126`
+- `packages/ai/src/index.ts:133`
+- `packages/ai/src/index.ts:135`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  /**
+   * 校验扩展唯一性与审批模型引用，无效配置以 CAGE-AI-001 拒绝。
+   */
+  validate(registry: Registry): void;
+}
+```