@yss123/cage-cli 0.3.1 → 0.4.0

package/templates/app/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/app/docs/development/skills/cage-development/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: cage-development
+description: 使用 Cage 框架开发、修改和排查业务应用。适用于依赖 @yss123/cage-*、具有 cage.config.json 的项目，与用户澄清需求、比较方案，再完成业务建模、框架接入与验收；维护框架内部实现时先遵守框架仓库的 AGENTS.md。
+---
+
+# 使用 Cage 开发业务
+
+本 Skill 是编程 agent 的工作流程：**读项目 → 理解需求并澄清 → 查证框架与现有实现 → 说明实现映射 → 编码 → 按业务验收**。先知道用户要什么、Cage 如何实现，再改代码；不要从一句需求直接套用熟悉的技术方案。
+
+按当前任务使用本流程，保留项目自己的业务规则和用户授权边界。案例中的对象、角色和流程不代表当前应用的需求。这里指导开发阶段的 agent；应用内原生 AI 的接入另见[智能化指南](../../guides/intelligence.md)。
+
+## 先建立正确的运行模型
+
+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 决定时，在委托范围内选择并说明依据。推荐、预选和未回复均不等于用户已选择。
+- 将回答更新为业务规则和验收例子，再映射到框架；实现中发现新疑问仍按此方式处理，用户改主意时同步调整受影响的部分。
+
+## 3. 选择已有能力并核对用法
+
+带着已理解的业务动作，按[业务设计与能力选择](../../guides/recipes.md)判断聚合、一致性和能力边界，再按下表查用法。先看当前应用有没有对应实现，再决定复用、修改还是新增；不要先设计一套通用后端，再尝试套进 Cage。先看最小接入，再查高级选项，不要一次加载所有专题。
+
+| 需求 | 选择方法与学习入口 |
+| --- | --- |
+| 新对象、状态、业务操作 | [原语](../../reference/primitives.md)：先确定命令意图；已有记录只改字段使用 `to: null`，仍检查允许状态 |
+| 对象/状态看不懂、关系和联动不清楚 | [本体建模](../../guides/ontology-modeling.md)：业务含义落实到真实声明，名称完整性与业务正确性分别核对 |
+| 一对多、多对多 | [关系](../../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)与[前端组件](../../guides/frontend-ui.md)：AI 生成真实 React 页面、Ant Design 组合、模块公开入口、独立 URL、会话恢复与用户缓存清理 |
+
+知道任务类别时直接阅读上表的章节；需要定位具体术语时先用本地文本搜索。在应用根目录使用：
+
+```sh
+rg -n "术语或符号" docs/development docs/errors
+pnpm exec cage capabilities "公开符号" --format json
+pnpm exec cage context "当前业务关键词" --format json
+```
+
+三者分别回答“手册怎样教”“当前版本提供什么”“当前应用在哪里实现”。没有 rg 时使用宿主的本地文件搜索。按命中位置阅读完整规则和代码上下文；结果为空时改用目录中的术语或公开符号，不能由一次未命中推断能力缺失。教材直接保存在本地，无需向量模型、索引构建或独立服务。
+
+调用前确认真实签名、参数、返回结果和前提。类型断言不能增加服务端实际未返回的字段。若当前版本确有缺口，说明具体缺口，给出有依据的可行方案及其业务影响，让用户选择涉及目标或范围变化的方案，同时继续处理独立部分；不要编造 API、复制框架运行时或用本地模拟补足正式业务。
+
+## 4. 写代码前说明实现映射
+
+对准备实现的部分，向用户简述以下对应关系；示例见[规则到实现的映射](../../guides/recipes.md#写代码前的实现映射)。这一步应发生在修改业务代码之前，不能写完后再补一份解释。
+
+| 要说明什么 | 必须有的依据 |
+| --- | --- |
+| 本次要实现的业务行为 | 已明确的目标、规则和来源；尚待决定的事项单列 |
+| Cage 如何实现 | 已查证的聚合、命令、状态、范围及必要的后续流程；具体指南、公开签名或现有声明位置 |
+| 具体改哪里 | 复用或修改的模块与导出、需要生成的契约/迁移、页面入口及运行前提；区分框架已提供和应用需完成的部分 |
+| 怎样证明完成 | 用户能观察到的成功结果，以及相关的权限、状态、边界值或失败情形 |
+
+每个业务提交按钮应对应真实契约，每项可见范围应有服务端归属和授权依据，每个自动后续动作应有执行与失败处理路径。对应不上时先查证或补设计；涉及业务取舍则回到第 2 步，不用猜测、类型断言或模拟数据填空。
+
+新建或修改领域时，按[本体建模](../../guides/ontology-modeling.md)说明相关对象的业务含义、关系方向/基数、状态与动作前后结果，再映射到 ref/集合关系、states、命令及必要的触发链。自然语言、文档、表格和原型都是需求证据；不能按页面建表、按字段名猜外键，或把读取箭头当自动联动。聚合/字段/命令等填写结构化描述，每个状态填写 labels；普通注释和页面文案不会自动进入图谱。
+
+清楚的小改动用一两句话即可，不要求新建计划文件，也不要求用户批准普通技术方案。已有明确需求与授权就继续实施；只有尚未确定的业务选择阻塞依赖它的部分。需求或能力证据变化时更新这份映射，避免实现与已选规则脱节。
+
+## 5. 沿一条真实链路实施，再扩展
+
+新业务先完成一个动作的保存与读取；已有业务只贯通受影响的动作。按[开发步骤](../../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)：说明职责、输入输出、调用关系和实际边界。注释中的保证必须能在代码中找到实现。
+
+## 6. 用观察结果决定完成程度
+
+验证与改动匹配，不因小改动运行全部数据库测试。逐项回到编码前的规则与验收例子，检查实现和生成结果是否落实了选择、是否混入未要求的业务行为；待决定事项不能报告为已完成。对新的业务读写链，至少核对所涉及的以下证据：
+
+| 要证明什么 | 应取得的证据 |
+| --- | --- |
+| 声明与接口相符 | check、生成一致性、类型检查以及实际契约调用 |
+| 本体可理解且符合需求 | 处理本次声明的 CAGE-ONTOLOGY-001，按业务用语检查图谱/context；逐项核对关系、状态和触发依据，再用业务例子验证，名称齐全不等于业务正确 |
+| 数据持久保存 | 命令成功后通过安全接口独立读取；页面重新加载使用同一服务端记录 |
+| 权限与范围生效 | 允许主体成功，范围外或缺能力主体的直接请求被拒绝 |
+| 流程真正执行 | 提交、待办、决定、结论命令及最终业务状态对应起来 |
+| 文件真正保存 | 上传原始内容，绑定成功，授权下载内容一致，越权下载拒绝 |
+| 异步工作完成 | 实际任务终态和业务结果；接受请求或 fake 成功只证明对应阶段 |
+| 页面可用 | 按[浏览器验收](../../guides/routing.md)实际操作对应路径，包含错误/无权限及相关导航行为 |
+
+检查通过不能扩大解释为未检查的业务结果。交付分别报告通过、跳过、未执行，附具体行为与证据；缺少运行条件时明确剩余验证，不伪造成功记录。
+
+## 7. 遇到失败，沿边界定位
+
+先保留 `code / at / reason / fix` 和相关操作事实，查[排错方法](../../tools/troubleshooting.md)与[错误码册](../../../errors/README.md)。从页面真实调用开始，定位第一个不符合预期的边界，再做最小修正：
+
+- 页面未发请求：查事件处理器和数据来源。
+- 契约缺方法或图中缺节点：查导出、生成及当前版本。
+- 请求拒绝：查认证、能力、范围、状态、版本和业务约束。
+- 请求成功但后续未完成：查实际事件、worker、待办或任务执行记录。
+- 服务端正确但页面陈旧：查查询失效、URL 和用户缓存。
+
+不要通过放宽授权、删除约束、关闭门禁或改写迁移历史消除错误。找到具体实现缺口再扩展框架；框架内部修改遵守框架仓库的维护规则。

package/templates/{blank/docs/ai → app/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
@@ -8,13 +8,16 @@ pnpm exec cage capabilities reactionEach --format json
 pnpm exec cage capabilities "AI审批" --format json
 pnpm exec cage capabilities "页面上下文" --format json
 pnpm exec cage capabilities "性格" --format json
+pnpm exec cage capabilities "状态名称" --format json
 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()`、执行迁移、配置模型或授予角色权限；接着核对项目启用状态，最后进行实际功能验证。
+“本体建模”“状态名称”“对象关系”分别召回真实的领域声明、状态 labels 和关系 API。按[本体建模指南](../guides/ontology-modeling.md)填写结构化名称；`CAGE-ONTOLOGY-001` 对本地可定位且支持命名的节点检查非空名称，默认警告，`graph.naming: 'required'` 时阻止 check/gen/verify。它不从注释或页面推断含义，也不把名称存在判为业务关系正确。
+
+原生智能化可用“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 入口、注册节点和对应路由，集合反应还包含上限、排序键、顺序和事务。
 
@@ -26,7 +29,7 @@ pnpm exec cage doctor --format json
 pnpm exec cage doctor --runtime-url http://127.0.0.1:3000 --cookie-file .cage/diagnostic-cookie.txt
 ```
 
-此模式只调用受 `Sys.ops.read` 保护的诊断接口。证据缺失、服务未运行、没有权限或没有 worker 心跳时标记 `unknown`；接口显示已加载版本和注册指纹，不能仅凭磁盘源码推断进程已经更新。能力已配置给某个角色也不代表任意用户具备范围、额度或调用身份。完成修改后仍需运行 `verify` 和实际业务验收。
+此模式只调用受 `Sys.ops.read` 保护的诊断接口。证据缺失、服务未运行、没有权限或没有 worker 心跳时标记 `unknown`；接口显示已加载版本和注册指纹，不能仅凭磁盘源码推断进程已经更新。能力已配置给某个角色也不代表任意用户具备范围或调用身份。完成修改后仍需运行 `verify` 和实际业务验收。
 
 运行指纹优先使用项目标准 `src→dist` 的实际编译入口，并逐文件检查源码与对应产物的修改时间。缺少构建或使用非标准输出布局时标记未知；编译后还需要重启 API 和 worker。源码经不同转换器执行时的函数文本可能不同，因此不把源码指纹直接当作生产产物指纹。
 

package/templates/{blank/docs/ai → app/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,9 +56,9 @@ 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: '草稿' } })` 中维护中文名；这些名称不更改原有状态标识。
+阶段直接使用 `title`、`description`、`actor` 的业务文案；对象和操作使用声明的 `description`，字段使用 `.describe(...)`，每个状态都在 `states(..., { labels: { draft: '草稿' } })` 中填写名称。`graph.labels` 用于显示覆盖及无通用描述选项的节点，例如 `"role:finance": "财务"`。普通注释与前端状态映射不会被抽取，`CAGE-ONTOLOGY-001` 会报告缺失的结构化名称；填写位置与业务验收边界见[本体建模指南](../guides/ontology-modeling.md)。这些名称不更改机器标识。
 
 ## 开发一项需求的入口
 
@@ -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/app/docs/{ai → development/tools}/troubleshooting.md

@@ -1,10 +1,16 @@
 # 排错方法
 
-[返回学习入口](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 消除现象。
 
-先执行 `pnpm exec cage doctor` 查看各阶段证据；异步动作按 requestId/outboxId/业务对象用 `cage timeline` 关联实际执行记录。能力、范围、调用身份或额度不清楚时，有权诊断的管理员可使用 `cage explain`，不会执行目标命令。完整参数与权限见[诊断指南](diagnostics.md)。
+先执行 `pnpm exec cage doctor` 查看各阶段证据；异步动作按 requestId/outboxId/业务对象用 `cage timeline` 关联实际执行记录。能力、范围或调用身份不清楚时，有权诊断的管理员可使用 `cage explain`，不会执行目标命令。完整参数与权限见[诊断指南](diagnostics.md)。
 
 ## 按现象定位
 
@@ -13,7 +19,7 @@
 | dev 启不动 | `.env` 是否在项目根目录，数据库服务是否可连接 | 缺连接、密码/端口错误、没执行迁移、端口占用 |
 | init 提示账号已存在 | CAGE-INIT-002；找已有 APP/READ/MIGRATE 连接 | 角色在 PG 集群内共享；不应覆盖原密码 |
 | 新业务不出现在接口/图谱 | 顶层 export const 和 domain/index.ts | 漏导出、重名导出、放进函数/条件声明 |
-| API 403 | code/detail、角色能力、调用身份、硬约束 | 能力不足、CSRF、职责分离、额度缺失/超限 |
+| API 403 | code/detail、角色能力、调用身份、硬约束 | 能力不足、CSRF、职责分离或其他业务约束不满足 |
 | 详情 404 | 记录 id、租户和数据范围 | 不存在或在范围外；不能仅凭 404 断言被删除 |
 | 列表为空 | read 能力、范围与相应字段 | 默认本人范围、无 owner 字段或部门不匹配 |
 | 电话看不到明文 | sensitive 标注、unmask 能力 | 默认掩码是正常安全行为 |
@@ -36,7 +42,7 @@
 | `approver.role('finance')` | 创建 code 为 finance 的角色，并给实际用户分配 | 选人看角色 code，不是中文显示名称 |
 | `approver.user(id)` | 使用存在的用户 UUID，核对业务可用性 | 把用户名或角色名当成 UUID |
 
-选人成功后，再检查此人所需能力、数据范围、额度。示例中提单人不能审批自己，经理的 `PurchaseOrder.approve` 必须有 ceiling 参数。
+选人成功后，再检查此人所需能力、数据范围及结论命令的业务约束。示例中提单人不能审批自己；采购金额决定是否进入财务节点，不需要配置角色额度。
 
 若事件已进入死信，在 `/admin` 查看对应 outboxId 的错误并修正配置，再点击重放。原 submit 通常已提交，单据处于 pending_approval；不要重复提交，更不要直接 SQL 改回 draft。重放后确认待办及后续事件，不把“点击重放成功”当成整条链路已经完成。
 

package/templates/app/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。
 

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

@@ -1,6 +1,6 @@
 # CAGE-APPR-001：审批字段声明无效
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 
@@ -13,7 +13,7 @@ approval.routable 引用了不存在字段，或 approver.field 指向未声明
 ## 修复步骤
 
 1. 先在聚合声明实际字段，再将需要给审批路由的非隐藏字段放入 routable；不要把任意输入直接交给流程。
-2. 字段选人值应为 UUID 或非空 UUID 数组，见 docs/ai/approvals.md；字段公开并不自动授予审批能力。
+2. 字段选人值应为 UUID 或非空 UUID 数组，见 docs/development/guides/approvals.md；字段公开并不自动授予审批能力。
 
 ## 正例
 

package/templates/app/docs/errors/CAGE-APPR-002.md

@@ -1,6 +1,6 @@
 # CAGE-APPR-002：审批结论落到其他聚合
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-APPR-003.md

@@ -1,6 +1,6 @@
 # CAGE-APPR-003：审批结论未允许流程调用
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-APPR-004.md

@@ -1,6 +1,6 @@
 # CAGE-APPR-004：路由没有对应审批绑定
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-APPR-005.md

@@ -1,6 +1,6 @@
 # CAGE-APPR-005：流程名称格式错误
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-APPR-006.md

@@ -1,6 +1,6 @@
 # CAGE-APPR-006：审批步骤配置无效
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-APPR-007.md

@@ -1,6 +1,6 @@
 # CAGE-APPR-007：找不到审批人
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 
@@ -15,7 +15,7 @@ worker 启动或推进审批步骤时选人器没有找到人，或字段选人/
 1. 先看本项目 approvals.ts：deptLeader 读取单据部门的负责人；role 使用角色 code；user 使用实际用户 UUID。
 2. 在 /admin 设置单据所属部门的负责人，或创建对应 code 的角色并分配实际用户。给用户经理角色，并不等于设置了部门负责人。
 3. field 使用提交时保存的 routable 人员字段；检查 UUID 对应账号是否全部在当前租户且 active。不能删掉不合格人员后默认为审批通过；字段快照错误需按业务撤回/重提修正。
-4. 再核对审批人的结论能力、数据范围、ceiling 额度和职责分离。选中审批人不等于允许完成审批。
+4. 再核对审批人的结论能力、数据范围和职责分离。选中审批人不等于允许完成审批。
 5. 若 OrderSubmitted 已入死信，修复后在 /admin 按 outboxId 重放，确认待办生成；原提交已成功时不重复提交或 SQL 改回草稿。
 
 ## 正例

package/templates/app/docs/errors/CAGE-APPR-010.md

@@ -1,6 +1,6 @@
 # CAGE-APPR-010：流程专用命令没有调用者
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -1,6 +1,6 @@
 # CAGE-AUDIT-001：可靠读取审计失败
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -1,6 +1,6 @@
 # CAGE-AUTH-001：OIDC 发现文档获取失败
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -1,6 +1,6 @@
 # CAGE-BIZ-001：业务流程声明无效
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-BIZ-002.md

@@ -1,6 +1,6 @@
 # CAGE-BIZ-002：业务流程与真实声明不一致
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -1,6 +1,6 @@
 # CAGE-BUDGET-001：内核超出体积预算
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-BUDGET-002.md

@@ -1,6 +1,6 @@
 # CAGE-BUDGET-002：公共原语超过词汇预算
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-BUDGET-003.md

@@ -1,6 +1,6 @@
 # CAGE-BUDGET-003：新增未经基线认可的 unsafe
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CMD-002.md

@@ -1,6 +1,6 @@
 # CAGE-CMD-002：已有记录命令缺少 id
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CMD-003.md

@@ -1,6 +1,6 @@
 # CAGE-CMD-003：新建命令没有目标状态
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -1,6 +1,6 @@
 # CAGE-CONN-001：连接器名称格式错误
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-002.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-002：外部操作路径格式错误
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-003.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-003：地址白名单包含协议或路径
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-004.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-004：只读操作被用作出站写映射
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-005.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-005：入站事件名称格式错误
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-006.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-006：回调命令未允许 external
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-007.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-007：当前环境没有连接器地址
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-008.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-008：外部请求发生网络错误或超时
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-009.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-009：外部服务返回非成功状态
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-010.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-010：外部响应不符合 schema
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-011.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-011：出站永久失败进入死信
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-012.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-012：外部专用命令没有声明调用者
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-013.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-013：出站幂等键无效或请求冲突
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-014.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-014：不可重试外部写入结果未知
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/app/docs/errors/CAGE-CONN-015.md

@@ -1,6 +1,6 @@
 # CAGE-CONN-015：连接器超时或限流参数无效
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。