@yss123/cage-cli 0.3.0 → 0.3.2

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

@@ -0,0 +1,63 @@
+# 业务澄清与共同设计
+
+[返回学习入口](../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` 覆盖的区域。
+
+确定规则后，按[能力选择](recipes.md)映射到聚合、命令、状态、范围、审批或连接器，同时补充能观察结果的验收例子。记录不要求固定文件格式，也不要求每项小改动新增计划文件。
+
+## 示例：文档没有写清金额边界
+
+业务文档写着：“金额低于 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/{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` 查询源码本体，与这里面向登录用户的运行时助理用途不同。
 
@@ -36,7 +36,7 @@ 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)。后端循环、通用工具、会话表和性格管理使用框架；应用侧完成业务策略、授权与界面组合。
 
 ## 启用后端
 
@@ -292,7 +292,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 +345,4 @@ Token 使用优先按模型返回 usage 核算；缺少 usage 时使用文本估
 - AI 审批：覆盖 pass、return、manual，检查退回修改后的新轮次从头开始；模型失败应按节点配置转人工或留在失败状态，不得伪造通过。
 - 管理配置：验证模型连接和一次实际工具交互，性格切换作用于后续消息；需要 Responses 接续或压缩时分别核对实际支持，连接成功不能替代这些验证。
 
-`cage doctor` 可辅助检查注册、迁移和进程证据，但未知项不能当作通过；诊断用法见[能力发现与状态诊断](diagnostics.md)。模型输出质量需要应用使用自己的规则样例评测。框架验证的是权限、状态、预算和事务边界；发布前需使用实际模型服务、实际角色和审批样例联调。
+`cage doctor` 可辅助检查注册、迁移和进程证据，但未知项不能当作通过；诊断用法见[能力发现与状态诊断](../tools/diagnostics.md)。模型输出质量需要应用使用自己的规则样例评测。框架验证的是权限、状态、预算和事务边界；发布前需使用实际模型服务、实际角色和审批样例联调。

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

@@ -1,14 +1,14 @@
-# 业务任务配方
+# 业务设计与能力选择
 
-[返回学习入口](README.md) · [原语示例](primitives.md) · [开发步骤](workflow.md)
+[返回学习入口](../README.md) · [原语示例](../reference/primitives.md) · [开发步骤](../getting-started/workflow.md)
 
-本页用于把用户的业务描述转成 Cage 项目的可执行修改。按需要读对应配方即可，不需要修改框架内部。
+本页用于把用户的业务描述转成 Cage 项目的可执行修改。先通过[框架开发 Skill](../skills/cage-development/SKILL.md)理解执行模型，首次使用可沿[完整入门课](../getting-started/first-feature.md)学习。按需要读对应配方，不要求为每个任务加载所有能力。
 
 需要 AI 审批、业务助理、随页聊天、模型管理或性格配置时，先用 `cage capabilities` 查框架能力，再按[原生智能化指南](intelligence.md)接入。普通业务建模仍按下文声明聚合和命令；接入已有框架服务无需另建一套通用后端。
 
-## 先把需求落到一张业务表
+## 先确定业务边界与执行路径
 
-开始编码前，从用户需求或现有业务中确定以下信息。能从上下文确认的直接使用；真正缺失且影响实现的再询问，不要为技术细节反复让用户确认。
+开始编码前，从用户需求、业务文档和现有实现中确定以下信息。按[业务澄清与共同设计](business-collaboration.md)主动提出歧义、冲突、遗漏及有价值的建议，给出选项、影响与推荐理由，让用户选择业务规则。已明确的条件直接采用，API 和普通技术细节由 agent 查证处理；下表用于发现相关问题，不要求用户逐项填表。
 
 | 业务问题 | 落到什么声明 | 例如 |
 | --- | --- | --- |
@@ -20,11 +20,30 @@
 | 取消/失败要撤销什么？ | 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；若需求要展示实际角色列表，应查找当前允许的读取接口或明确所需接口缺口。多角色能力/范围按框架规则合并，前端切换菜单不会自动切换服务端执行身份。用不同真实主体验证权限，不能用固定姓名或公司名称模拟范围。
+
 ## 新增一个普通管理对象
 
-按[最小便笺业务](primitives.md)新增 `packages/domain/src/modules/<业务>/<对象>.ts`：字段、范围、不变量、create/update/archive 命令。采用唯一的导出名和必要的 `name` 覆盖，避免 index 的 `export *` 丢失重名符号。
+按[最小便笺业务](../reference/primitives.md)新增 `packages/domain/src/modules/<业务>/<对象>.ts`：字段、范围、不变量、create/update/archive 命令。采用唯一的导出名和必要的 `name` 覆盖，避免 index 的 `export *` 丢失重名符号。
 
-从模块 index 到 domain 入口导出后运行 check/gen，审查迁移，再在 `apps/web/src/modules/<业务>` 使用生成 contracts 做列表、详情、表单和操作按钮，经模块公开入口注册到 app 路由。列表和详情都有独立 URL，筛选/分页进入 query，按[浏览器配方](routing.md)检查导航。最后给角色授权并补图谱中文名。完整归属规则见[目录规范](project-structure.md)。不要手写后端增删改查路由、ORM 实体与 repository，也不要复制框架鉴权代码。
+从模块 index 到 domain 入口导出后运行 check/gen，审查迁移，再在 `apps/web/src/modules/<业务>` 使用生成 contracts 做列表、详情、表单和操作按钮，经模块公开入口注册到 app 路由。列表和详情都有独立 URL，筛选/分页进入 query，按[浏览器配方](routing.md)检查导航。最后给角色授权并补图谱中文名。完整归属规则见[目录规范](../reference/project-structure.md)。不要手写后端增删改查路由、ORM 实体与 repository，也不要复制框架鉴权代码。
 
 完成标准：授权用户能创建和修改，范围外数据不可见，归档后的允许行为符合业务要求，生成契约和迁移一致。没有审批需求时不必添加审批；没有外部系统时不必添加连接器。
 
@@ -42,7 +61,7 @@
 4. 配置实际部门负责人、角色或指定用户；给审批人配置能力、范围和额度。
 5. 页面通过待办接口操作。通过后需占用资源时用反应调用资源命令，按业务一致性选择同事务。
 
-完成标准：提交生成待办、正确的人审批、越权和自审批拒绝、取消能结束待办、资源配对完整。任意流程设计器、动态 JS 选人、转签/加签不属于当前现成能力，需要明确扩展范围。
+完成标准：提交生成待办、正确的人审批、越权和自审批拒绝、取消能结束待办、资源配对完整。转办、委派归还及当前节点前签、后签和并行必签见[审批任务流转](approvals.md)，须显式启用政策并传任务版本，旧实例是否开放签序以其快照为准。任意流程设计器、动态 JS 选人和指定节点退回仍需明确扩展范围。
 
 ## 加入 AI 审批或随页助理
 
@@ -79,10 +98,11 @@
 ## 给编程工具的任务模板
 
 ```text
-阅读当前项目 AGENTS.md，按 docs/ai/README.md 找到本次需求对应的原语和标准范例。
-遵守 docs/ai/project-structure.md：领域和前端按业务建 modules，app 组合页面，shared 只放通用代码，不平铺 src 或堆进 main.tsx。
+阅读当前项目 AGENTS.md，按 docs/development/README.md 找到本次需求对应的原语和标准范例。
+遵守 docs/development/reference/project-structure.md：领域和前端按业务建 modules，app 组合页面，shared 只放通用代码，不平铺 src 或堆进 main.tsx。
 业务：……；角色与数据范围：……；状态与允许动作：……；审批/外部系统/资源占用：……。
-先列出需要修改的 domain、页面、契约、迁移和授权，再直接完成实现。
+阅读后主动指出描述或文档中的疑点，按 docs/development/guides/business-collaboration.md 给出可行选项、影响与推荐，让我选择；已明确条件不重复询问，普通技术细节自行查证处理。
+将已选择的规则映射到 domain、页面、契约、迁移、授权和验收，再完成实现；等待业务决定时继续不依赖该决定的工作，可选建议不阻塞已明确任务。
 使用当前公开 API；对无法表达的需求说明具体缺口，不编造方法。
 生成文件通过 cage gen 更新，数据库使用已有 .env 配置，按改动完成必要验证。
 交付时说明用户如何体验、管理员需配置什么，以及通过/跳过/未执行的检查。

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

@@ -1,6 +1,6 @@
 # 业务对象之间的关系
 
-[返回学习入口](README.md) · [最小业务](primitives.md) · [开发步骤](workflow.md)
+[返回学习入口](../README.md) · [最小业务](../reference/primitives.md) · [开发步骤](../getting-started/workflow.md)
 
 关系和普通属性统一写在 `aggregate(...).fields` 中。业务不需要另写 `relations` 区块，也不用为单纯“便笺与用户的关联”创建 `NoteMember` 聚合。
 
@@ -20,7 +20,7 @@
 
 ## 完整领域例子
 
-下面可作为 `packages/domain/src/modules/note/note.ts`。它是[最小便笺](primitives.md)的关系版本，按需要替换原文件，避免重复声明 Note。
+下面可作为 `packages/domain/src/modules/note/note.ts`。它是[最小便笺](../reference/primitives.md)的关系版本，按需要替换原文件，避免重复声明 Note。
 
 ```ts
 import {

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

@@ -1,6 +1,6 @@
 # 业务前端路由与浏览器验收
 
-[返回学习入口](README.md) · [工程目录](project-structure.md) · [开发步骤](workflow.md)
+[返回学习入口](../README.md) · [工程目录](../reference/project-structure.md) · [开发步骤](../getting-started/workflow.md)
 
 多页面业务默认使用 React Router 的 BrowserRouter。列表、详情、报表等可独立访问的页面必须有 URL；在 app 中统一组合路由和工作台布局，页面从模块 index.ts 导出。useState 用于弹窗、未提交表单和按钮忙碌状态。筛选、分页和需要分享的选项使用 useSearchParams。
 

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

@@ -1,6 +1,6 @@
 # 在客户业务页接入导入和导出
 
-[返回学习入口](README.md) · [开发步骤](workflow.md)
+[返回学习入口](../README.md) · [开发步骤](../getting-started/workflow.md)
 
 框架提供持久化任务、CSV 处理、权限和下载接口。业务项目决定入口、列名、上传表单、任务状态与报告如何展示；不要求用户进入系统管理页，也不要求具备 Sys.ops 能力。路径中的 `/api/sys/transfers` 是通用任务接口。
 

package/templates/{app/docs/ai → blank/docs/development/reference}/commenting.md

@@ -1,6 +1,6 @@
 # 详细中文注释规范
 
-[返回学习入口](README.md) · [工程目录](project-structure.md) · [开发步骤](workflow.md)
+[返回学习入口](../README.md) · [工程目录](project-structure.md) · [开发步骤](../getting-started/workflow.md)
 
 本规范同时适用于 Cage 框架源码、标准范例，以及通过脚手架创建后由 Codex 等 agent 编写和维护的应用源码。**详细中文注释是代码交付的一部分。** 新建或修改代码时，必须让后续开发者仅凭源码及其注释理解职责、输入输出、关键步骤、设计原因、调用关系和行为边界，不能只在聊天回复或外部设计文档中解释。
 

package/templates/blank/docs/{ai → development/reference}/primitives.md

@@ -1,70 +1,16 @@
 # 原语与最小业务
 
-[返回学习入口](README.md) · [开发步骤](workflow.md)
+[返回学习入口](../README.md) · [开发步骤](../getting-started/workflow.md)
 
 本页代码使用当前公开导出。完整文件示例可直接放入应用；标为“片段”的代码需要结合采购范例已有符号使用。不要把片段中的变量名当成新的框架 API。
 
-文件字段使用 `file({ maxBytes, accept }).optional()` 或 `files({ maxBytes, accept, maxCount })`。字段保存文件 ID，上传/续传先获得临时文件，最终通过业务命令绑定；完整流程、限制和存储配置见[文件指南](files.md)。
+文件字段使用 `file({ maxBytes, accept }).optional()` 或 `files({ maxBytes, accept, maxCount })`。字段保存文件 ID，上传/续传先获得临时文件，最终通过业务命令绑定；完整流程、限制和存储配置见[文件指南](../guides/files.md)。
 
 ## 最小的增、查、改、归档业务
 
-下面是完整的 `packages/domain/src/modules/note/note.ts`。它演示带部门范围的便笺，不影响采购范例原有业务；需要此业务时才添加文件。
+完整教学代码统一维护在[便笺声明](../examples/note/note.ts)。[第一条完整业务链](../getting-started/first-feature.md)带你依次完成领域导出、契约生成、权限配置与真实页面接入，包含可编译的列表、新建、详情、修改和归档组件。
 
-```ts
-import { aggregate, command, ref, scope, states, text } from '@yss123/cage-kernel';
-import { z } from 'zod';
-
-export const Note = aggregate('Note', {
-  description: '部门便笺',
-  fields: {
-    title: text(120),
-    deptId: ref('Dept'),
-    createdBy: ref('User'),
-  },
-  states: states('active', 'archived', { terminal: ['archived'] }),
-  // 指明部门字段。最终能看哪个部门，由角色的数据范围决定。
-  scope: scope.deptSubtree('deptId'),
-  invariants: { titleNotBlank: (o) => o.title.trim().length > 0 },
-});
-
-export const createNote = command(Note, {
-  // 使用独立导出名避免多个文件 export * 时 create 重名；能力仍叫 Note.create。
-  name: 'create',
-  from: 'new',
-  to: 'active',
-  input: z.object({ title: z.string().trim().min(1).max(120) }),
-  // 新建草稿已有输入字段；deptId 和 createdBy 由内核按当前主体填入。
-  handler: (draft) => draft,
-});
-
-export const updateNote = command(Note, {
-  name: 'update',
-  from: 'active',
-  to: null,
-  input: z.object({ id: z.string().uuid(), title: z.string().trim().min(1).max(120) }),
-  // 只返回业务变化，状态、版本及审计仍由内核维护。
-  handler: (_draft, input) => ({ title: input.title }),
-});
-
-export const archiveNote = command(Note, {
-  name: 'archive',
-  from: 'active',
-  to: 'archived',
-  // 省略 input 时，已有记录命令默认使用 { id: uuid }。
-  handler: (draft) => draft,
-});
-```
-
-先在 `packages/domain/src/modules/note/index.ts` 写 `export * from './note.js';`，再在 `packages/domain/src/index.ts` 保留组织模型及已有模块，加入新模块：
-
-```ts
-export * from '@yss123/cage-admin/domain';
-export * from './modules/note/index.js';
-```
-
-随后 `pnpm exec cage check`、`pnpm gen`，审查迁移后 `pnpm migrate`。管理员给目标角色配置 `Note.create / Note.update / Note.archive / Note.read` 和 `Note` 数据范围；前端使用生成的 `note.create({ title })`、`note.update(id, { title }, version)`、`note.archive(id, version)`、`note.list()`、`note.get(id)`。
-
-这里的删除选择“归档”这一业务命令，没有硬删表行。读侧列表默认行为以生成契约与实际过滤参数为准，页面要按需求选择是否展示归档记录。系统默认状态并不意味着自动拥有完整 CRUD 命令。
+原语参考从下文查字段与选项；无需重复复制一份入门代码。便笺的删除选择“归档”命令，保留历史；系统默认状态不会自动提供完整 CRUD 命令。
 
 ## 字段速查
 
@@ -85,7 +31,7 @@ export * from './modules/note/index.js';
 
 字段可链式使用 `.optional()`、`.unique()`、`.sensitive('phone')`、`.hidden()` 等。可用敏感种类以包导出的 `SENSITIVE_KINDS` 为准；hidden 字段不会作为普通公开读字段，sensitive 字段按权限掩码。不要通过前端隐藏来替代它们。
 
-集合关系也放在 `fields` 中，但不是普通 SQL 列，不支持上述四种修饰。完整声明、成员命令、分页接口、权限与迁移见[对象关系指南](relations.md)。纯关联不手写 NoteMember 聚合，具有职位、状态等业务属性的关联仍应建业务聚合。
+集合关系也放在 `fields` 中，但不是普通 SQL 列，不支持上述四种修饰。完整声明、成员命令、分页接口、权限与迁移见[对象关系指南](../guides/relations.md)。纯关联不手写 NoteMember 聚合，具有职位、状态等业务属性的关联仍应建业务聚合。
 
 不要定义 `id/version/status/createdAt/updatedAt/tenantId` 同名业务字段。聚合名和事件名用大驼峰，字段、命令、查询和任务名用小驼峰，状态名用小写下划线。
 
@@ -231,7 +177,7 @@ 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#审计保证)。
+有目的级审计要求时，在 query 中声明 `audit: { purpose: '月度结算核对' }`。目的应为固定说明，不包含敏感输入。查询会先可靠写入用途审计再交付结果；潜在敏感明文还按 `reads` 保守审计，不假定任意 SQL 投影能精确推导字段和对象。审计故障返回 `CAGE-AUDIT-001`，不交付查询数据。完整保证见[审计矩阵](../getting-started/architecture.md#审计保证)。
 
 通用列表参数要求正安全整数 page/pageSize；数值筛选必须有限并满足字段 schema，布尔只接受 true/false，日期必须合法，排序字段必须来自公开字段。非法值返回字段级 `INVALID_INPUT`，不会把任意非 true 字符串转成 false。当前仍采用 offset 分页及精确计数，大规模分页成本需按实际数据测量。
 
@@ -261,9 +207,9 @@ 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 与边界见[审批任务流转](../guides/approvals.md)。任意函数选人、前后加签和并行流程分支仍需扩展。
 
-被选中的审批人还要具备结论命令所需能力、范围和额度。部门负责人为空会产生 `CAGE-APPR-007`，详见[排错](troubleshooting.md)。
+被选中的审批人还要具备结论命令所需能力、范围和额度。部门负责人为空会产生 `CAGE-APPR-007`，详见[排错](../tools/troubleshooting.md)。
 
 ## 连接器、定时任务和逃生口
 

package/templates/blank/docs/{ai → development/reference}/project-structure.md

@@ -60,7 +60,7 @@
 │     │  └─ user/index.ts
 │     └─ queries/index.ts
 ├─ db/migrations/
-└─ docs/ai/、docs/errors/
+└─ docs/development/、docs/errors/
 ```
 
 树中的采购文件可在采购模板中运行；空白模板把它们作为离线参考放在 `docs/examples/purchase-admin`，真实源码只有认证、工作台和组织模型。空白项目没有需要用到的目录可以不创建。
@@ -74,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` 引入并注册列表、详情 URL，通过 Outlet 放入工作台布局。导航用 Link/NavLink，筛选和分页用 useSearchParams；弹窗和提交状态留在页面，不把整个页面切换写成 useState。按[路由指南](routing.md)验收深链接、刷新、前进后退和登录回跳。
+6. 从前端模块 `index.ts` 导出页面，应用壳从 `../modules/expense` 引入并注册列表、详情 URL，通过 Outlet 放入工作台布局。导航用 Link/NavLink，筛选和分页用 useSearchParams；弹窗和提交状态留在页面，不把整个页面切换写成 useState。按[路由指南](../guides/routing.md)验收深链接、刷新、前进后退和登录回跳。
 
 前后端可以有相同的业务模块名，但文件不混放：领域定义授权和行为，前端管理交互，通过生成契约连接。API 启动入口维持薄壳，普通业务无需新增 controller/service/repository。
 

package/templates/blank/docs/development/skills/cage-development/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: cage-development
+description: 使用 Cage 框架开发、修改和排查业务应用。适用于依赖 @yss123/cage-*、具有 cage.config.json 的项目，与用户澄清需求、比较方案，再完成业务建模、框架接入与验收；维护框架内部实现时先遵守框架仓库的 AGENTS.md。
+---
+
+# 使用 Cage 开发业务
+
+阅读用户描述、业务文档和现有实现，主动提出疑问与建议，与用户共同确定业务规则，再转换成 Cage 声明，把声明、生成契约、页面和实际执行连接起来。按当前任务使用本指南，保留项目自己的业务规则和用户授权边界。本文由框架维护，适用于不同业务和 agent；案例中的对象、角色和流程不代表当前应用的需求。
+
+## 先建立正确的运行模型
+
+Cage 是由业务声明驱动的框架。应用定义业务含义，框架执行这些声明。
+
+```text
+定义阶段：领域声明 → domain 导出 → 注册表
+                              ├─ 能力、HTTP 接口与运行时
+                              └─ 本体图、前端契约与迁移草稿
+写入阶段：页面 → 生成契约 → HTTP → 内核执行命令 → 数据、审计与事件
+读取阶段：页面 → 生成的 list/get 或 query → 安全读侧 → 当前主体可见的数据
+后续阶段：事件 → 同事务反应，或 outbox → worker → 反应 / 审批 / 连接器
+```
+
+- **聚合**定义一个业务对象的字段、状态、归属和不变量。以生命周期和一致性要求划分边界；关联对象可以有自己的生命周期。
+- **命令**表达业务意图，是业务写入口。`from/to` 声明允许的状态变化，handler 根据草稿、输入与 `reads` 依赖返回变化；内核处理授权、范围、版本、事务、审计与 outbox。handler 不执行数据库、网络或文件 IO。
+- **读取**使用生成的读取接口；复杂汇总声明 query，通过 `safe.*` 查询。页面展示的数据来自这些服务端结果。
+- **事件**表达已发生的事实；reaction 调用后续命令。共同成功的变化用 `tx: 'same'`，允许稍后完成的变化使用异步执行，并处理失败和重试。
+- **权限**分别考虑角色分配、能力点、数据范围、调用身份和业务约束。`user/process/job/external` 是调用身份；`can()` 是界面提示。角色名称、页面门户和审批选人均不能代替授权。
+- **页面**管理表单、弹窗与展示，并通过契约执行业务。声明存在、接口生成、应用启用和实际执行成功是四种不同证据。
+
+首次接触 Cage，先读[架构与执行模型](../../getting-started/architecture.md)，再沿[第一条完整业务链](../../getting-started/first-feature.md)理解声明如何变成真实读写。已经熟悉框架时只读当前缺失的部分；不要把教学案例整体加入用户项目。
+
+## 1. 确认正在修改什么
+
+读取当前项目的 AGENTS.md、package.json、cage.config.json，以及相关模块的入口和现有测试。确认：
+
+- 当前工作目录是框架源码仓库，还是依赖框架的应用。框架仓库的业务范例在 `examples/purchase-admin`；普通应用命令在对应应用根目录执行。
+- 当前安装版本、domain 入口、契约目录和真实前端入口。API 以该版本的公开导出与生成契约为准。
+- 任务属于新建业务、扩展已有业务、排错，还是界面调整。界面文案或样式调整不重新建模；排错先定位现有链路，避免重写一套实现。
+- 参考代码和正在运行的代码分别在哪里。空白项目的 `docs/examples/purchase-admin` 只供阅读。
+
+先复用已存在的声明、客户端与组织基础。区分用户希望实现的规则、文档中的约定与代码当前的行为；现有代码只能证明现在怎样运行，不能替用户决定目标业务。用户已明确的条件直接采用，发现仍未解决的歧义、冲突或遗漏时按下一节共同澄清。
+
+## 2. 提出疑问和建议，与用户共同确定业务
+
+按[业务澄清与共同设计](../../guides/business-collaboration.md)处理不完整的描述和不清楚的文档。主动指出可能影响业务含义、使用体验、实现范围或验收的疑点，不等到实现失败才询问，也不默默补成自定规则。
+
+- 先读相关上下文；API、版本与当前行为由 agent 查文档、公开签名和实现证据。查证后仍涉及业务取舍的，交给用户选择。
+- 提问带上具体疑点及来源、可行选项与影响、推荐方案及理由。用用户能判断的业务语言表达，允许用户提出选项之外的方案；框架缺口和额外实现成本要说明。
+- 按对当前工作的影响分批提出问题，也可提出有价值的改进建议。需要选择的业务规则先取得答案再实现相关部分；等待时推进独立工作。可选建议不阻塞已明确的任务。
+- 沿用用户已给出的选择和授权，不重复确认。普通技术细节自行解决；用户明确委托 agent 决定时，在委托范围内选择并说明依据。推荐、预选和未回复均不等于用户已选择。
+- 将回答更新为业务规则和验收例子，再映射到框架；实现中发现新疑问仍按此方式处理，用户改主意时同步调整受影响的部分。
+
+业务条件明确后，按[业务设计与能力选择](../../guides/recipes.md)形成简短的实现映射：
+
+| 需要确定的事实 | 对应设计 |
+| --- | --- |
+| 管理什么、哪些数据必须共同成立 | 聚合边界、字段、不变量和对象关系 |
+| 谁在什么阶段做什么 | 命令、输入、允许状态、调用身份、硬约束 |
+| 数据归谁、各主体可以看到什么 | 归属字段、角色能力及范围，敏感字段掩码 |
+| 成功后发生什么、失败要恢复什么 | 事件、反应、审批、连接器、资源释放及补偿 |
+| 页面如何展示和操作 | 生成的读取/写入契约、查询、URL、加载与失败状态 |
+| 如何知道实现正确 | 持久结果、另一主体的观察结果和关键拒绝路径 |
+
+仅记录与本次改动有关的设计，不要求每个任务生成额外计划文件。对每个新增业务按钮，能指出它调用的真实契约；对每个范围要求，能指出服务端使用的归属字段与授权。缺少对应关系时，先补设计。
+
+## 3. 选择已有能力并核对用法
+
+按下表阅读相关章节；先看最小接入，再查高级选项。不要一次加载所有专题。
+
+| 需求 | 选择方法与学习入口 |
+| --- | --- |
+| 新对象、状态、业务操作 | [原语](../../reference/primitives.md)：先确定命令意图；已有记录只改字段使用 `to: null`，仍检查允许状态 |
+| 一对多、多对多 | [关系](../../guides/relations.md)：只读反查选 hasMany；纯链接选 manyToMany；关系有独立状态/属性时再建聚合 |
+| 列表、详情、统计 | 普通 list/get 优先；汇总或联表使用[query](../../reference/primitives.md#两种查询写法)，显式 reads 与安全视图 |
+| 角色、本人/部门范围、敏感字段 | [授权模型](../../getting-started/architecture.md#权限是几层判断)：先定归属字段，再配置能力和范围，核对当前会话公开字段 |
+| 审批和人员流转 | [审批](../../guides/approvals.md)：提交事件、approval 绑定、route、结论命令；页面通过待办接口决定，选人和授权分别检查 |
+| 事件联动、资源占用、定时动作 | [原语](../../reference/primitives.md)：显式 emits/reads/calls，按一致性要求选择事务边界；资源标签还需实际命令落实 |
+| 上传、下载、断点续传 | [文件](../../guides/files.md)：上传字节获得文件 ID，业务命令绑定，受控接口下载 |
+| 导入、导出 | [数据传输](../../guides/transfers.md)：导入逐条或原子执行命令，导出异步读取；跟踪任务到终态 |
+| 第三方系统 | [连接器配方](../../guides/recipes.md#接入外部系统)：外呼、验签、幂等、回写命令与失败恢复 |
+| 原生 AI、AI 审批、随页助理 | [智能化](../../guides/intelligence.md)：先检查已有框架能力和 domain 启用状态，再配置策略、授权、模型与界面 |
+| 页面、导航、会话 | [目录](../../reference/project-structure.md)与[路由](../../guides/routing.md)：模块公开入口、独立 URL、会话恢复与用户缓存清理 |
+
+知道任务类别时直接阅读上表的章节；需要定位具体术语时先用本地文本搜索。在应用根目录使用：
+
+```sh
+rg -n "术语或符号" docs/development docs/errors
+pnpm exec cage capabilities "公开符号" --format json
+pnpm exec cage context "当前业务关键词" --format json
+```
+
+三者分别回答“手册怎样教”“当前版本提供什么”“当前应用在哪里实现”。没有 rg 时使用宿主的本地文件搜索。按命中位置阅读完整规则和代码上下文；结果为空时改用目录中的术语或公开符号，不能由一次未命中推断能力缺失。教材直接保存在本地，无需向量模型、索引构建或独立服务。
+
+调用前确认真实签名、参数、返回结果和前提。类型断言不能增加服务端实际未返回的字段。若当前版本确有缺口，说明具体缺口，给出有依据的可行方案及其业务影响，让用户选择涉及目标或范围变化的方案，同时继续处理独立部分；不要编造 API、复制框架运行时或用本地模拟补足正式业务。
+
+## 4. 沿一条真实链路实施，再扩展
+
+新业务先完成一个动作的保存与读取；已有业务只贯通受影响的动作。按[开发步骤](../../getting-started/workflow.md)操作：
+
+1. 涉及已有领域含义变化时先保存本体基线。按[目录规范](../../reference/project-structure.md)修改声明，从模块 index 到 domain 入口导出；handler 的读取与 job 的调用声明依赖。
+2. 运行 check/gen，检查生成契约和迁移草稿。生成内容说明声明被识别；需要结构变化时审查后执行迁移，保留已发布迁移。
+3. 按当前环境准备实际授权与必要配置；应用入口和 worker 加载一致的 domain。新能力不自动授给生产角色，沿用用户已授权的配置范围。
+4. 页面调用实际生成的方法并处理业务失败。底层 `CageResult` 检查 `ok`；hook 的成功/失败语义以当前 API 为准。成功后重新读取或失效对应查询；失败保留输入并给出可操作提示。
+5. 验证一个完整动作后复用该模式扩展。前端临时状态可保存草稿、筛选和弹窗；正式业务记录、审批结果及权限由服务端决定。测试夹具或用户明确要求的原型要标明用途，不作为正式运行结果交付。
+
+编写时同步遵守[中文注释规范](../../reference/commenting.md)：说明职责、输入输出、调用关系和实际边界。注释中的保证必须能在代码中找到实现。
+
+## 5. 用观察结果决定完成程度
+
+验证与改动匹配，不因小改动运行全部数据库测试。以双方确定的业务规则和验收例子为依据，检查选择是否落实；待决定事项不能报告为已完成。对新的业务读写链，至少核对所涉及的以下证据：
+
+| 要证明什么 | 应取得的证据 |
+| --- | --- |
+| 声明与接口相符 | check、生成一致性、类型检查以及实际契约调用 |
+| 数据持久保存 | 命令成功后通过安全接口独立读取；页面重新加载使用同一服务端记录 |
+| 权限与范围生效 | 允许主体成功，范围外或缺能力主体的直接请求被拒绝 |
+| 流程真正执行 | 提交、待办、决定、结论命令及最终业务状态对应起来 |
+| 文件真正保存 | 上传原始内容，绑定成功，授权下载内容一致，越权下载拒绝 |
+| 异步工作完成 | 实际任务终态和业务结果；接受请求或 fake 成功只证明对应阶段 |
+| 页面可用 | 按[浏览器验收](../../guides/routing.md)实际操作对应路径，包含错误/无权限及相关导航行为 |
+
+检查通过不能扩大解释为未检查的业务结果。交付分别报告通过、跳过、未执行，附具体行为与证据；缺少运行条件时明确剩余验证，不伪造成功记录。
+
+## 6. 遇到失败，沿边界定位
+
+先保留 `code / at / reason / fix` 和相关操作事实，查[排错方法](../../tools/troubleshooting.md)与[错误码册](../../../errors/README.md)。从页面真实调用开始，定位第一个不符合预期的边界，再做最小修正：
+
+- 页面未发请求：查事件处理器和数据来源。
+- 契约缺方法或图中缺节点：查导出、生成及当前版本。
+- 请求拒绝：查认证、能力、范围、状态、版本和业务约束。
+- 请求成功但后续未完成：查实际事件、worker、待办或任务执行记录。
+- 服务端正确但页面陈旧：查查询失效、URL 和用户缓存。
+
+不要通过放宽授权、删除约束、关闭门禁或改写迁移历史消除错误。找到具体实现缺口再扩展框架；框架内部修改遵守框架仓库的维护规则。

package/templates/{app/docs/ai → blank/docs/development/tools}/diagnostics.md

@@ -1,6 +1,6 @@
 # 能力发现与状态诊断
 
-业务开发前可以先按问题查框架公开能力，再定位当前项目中的声明。两个查询回答不同问题：`capabilities` 读取当前安装版本的公开类型，`context` 分析当前项目实际注册的业务。
+业务开发方法见[框架开发 Skill](../skills/cage-development/SKILL.md)。按任务目录或本地文本搜索定位手册，再用 `capabilities` 核对当前安装版本的公开类型、`context` 定位当前应用的声明。三者分别提供教学说明、API 签名和应用证据，不需要独立知识服务或向量索引。
 
 ```powershell
 pnpm exec cage capabilities 本人 --format json
@@ -12,9 +12,9 @@ pnpm exec cage context "设备归还" --format json
 pnpm exec cage doctor --format json
 ```
 
-公开能力报告包含包版本、真实签名、公开导出名、声明位置与本地学习指南。未安装的包标为未检查；未命中关键词不能证明能力不存在。完整例子见 [原语](primitives.md) 和 [任务配方](recipes.md)。
+公开能力报告包含包版本、真实签名、公开导出名、声明位置与本地学习指南。未安装的包标为未检查；未命中关键词不能证明能力不存在。完整例子见 [原语](../reference/primitives.md) 和 [任务配方](../guides/recipes.md)。
 
-原生智能化可用“AI审批”“业务助理”“随页助理”“模型管理”“性格”“Responses”“上下文预算”等关键词检索，结果指向[智能化指南](intelligence.md)。例如 AI 审批返回现有 `step` 的重载及 `AiStepOptions`，不是另造 `aiStep` 原语。公开能力可被检索，不代表本应用已经导出 `ai()`、执行迁移、配置模型或授予角色权限；接着核对项目启用状态，最后进行实际功能验证。
+原生智能化可用“AI审批”“业务助理”“随页助理”“模型管理”“性格”“Responses”“上下文预算”等关键词检索，结果指向[智能化指南](../guides/intelligence.md)。例如 AI 审批返回现有 `step` 的重载及 `AiStepOptions`，不是另造 `aiStep` 原语。公开能力可被检索，不代表本应用已经导出 `ai()`、执行迁移、配置模型或授予角色权限；接着核对项目启用状态，最后进行实际功能验证。
 
 `doctor` 复用 `check`、`gen --check`，输出统一的 `schemaVersion / observedAt / checks / findings / registration / routes`。每个检查包含 `status / source / reason / next`。`pass` 表示相应证据通过，`fail` 表示已发现问题，`unknown` 表示未检查；`complete: false` 不能作为完整验收通过。注册报告列出声明位置、domain 入口、注册节点和对应路由，集合反应还包含上限、排序键、顺序和事务。
 

package/templates/{app/docs/ai → blank/docs/development/tools}/ontology-context.md

@@ -1,6 +1,6 @@
 # 用本体图辅助 AI 开发业务
 
-[返回学习入口](README.md) · [开发步骤](workflow.md)
+[返回学习入口](../README.md) · [开发步骤](../getting-started/workflow.md)
 
 本页命令在**应用根目录**运行，使用项目安装的 CLI。工具直接分析当前注册的 domain，无需启动 API、worker 或数据库。不要把 Web 截图作为 AI 理解业务的唯一材料：优先取得结构化上下文，再按源码位置阅读实现。
 
@@ -56,7 +56,7 @@ export const purchaseOverview = businessProcess('purchase-overview', {
 - `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 或审批，所以仍需业务回归证明运行行为。
+`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: '草稿' } })` 中维护中文名；这些名称不更改原有状态标识。
 
@@ -163,7 +163,7 @@ pnpm exec cage impact --snapshot before-change
 可直接交给编程工具的要求：
 
 ```text
-先读 AGENTS.md 和 docs/ai/README.md。
+先读 AGENTS.md 和 docs/development/README.md。
 需求：修改……
 先运行 cage context 查询需求相关业务，再用 graph inspect/path 消除入口和关系歧义。
 按报告的源码位置阅读条件与实现；说明选中的业务入口、影响范围和图的覆盖边界。

package/templates/blank/docs/{ai → development/tools}/troubleshooting.md

@@ -1,6 +1,12 @@
 # 排错方法
 
-[返回学习入口](README.md) · [错误码册](../errors/README.md) · [HTTP 运行时错误](../errors/runtime.md)
+## 先找第一个失败的边界
+
+从真实用户动作开始，检查页面是否调用契约、请求是否发出、接口如何返回、持久记录是否改变，再看异步后续和页面刷新。页面显示成功但没有请求时，先修页面的数据来源；不要先改数据库或重写领域模型。
+
+接口成功与流程完成分开判断。使用[诊断工具](diagnostics.md)按需要收集注册、构建、迁移、授权和执行记录；未取得的运行证据保持 unknown。保留失败输入与错误码，修复最小缺口后复验同一路径，避免同时改变多层而失去原因。
+
+[返回学习入口](../README.md) · [错误码册](../../errors/README.md) · [HTTP 运行时错误](../../errors/runtime.md)
 
 先保留完整诊断的 code、源码位置、reason/fix、requestId 或 outboxId。检查所在阶段，再修复原因；不要通过改业务状态、给全局权限、注释约束或禁用 lint 消除现象。
 

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

@@ -1,6 +1,6 @@
 # CAGE-AI-001：智能运行时声明无效
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 
@@ -47,8 +47,8 @@ ai({ models: {}, assistant: { model: 'missing', limits: { maxSteps: 0 } } })
 - `packages/ai/src/index.ts:94`
 - `packages/ai/src/index.ts:96`
 - `packages/ai/src/index.ts:126`
-- `packages/ai/src/index.ts:130`
-- `packages/ai/src/index.ts:132`
+- `packages/ai/src/index.ts:133`
+- `packages/ai/src/index.ts:135`
 
 实现片段（位置随框架版本更新）：