@yss123/cage-cli 0.3.1 → 0.4.0

package/templates/blank/docs/errors/CAGE-GRANT-003.md

@@ -1,6 +1,6 @@
 # CAGE-GRANT-003：能力不在代码目录中
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 
@@ -8,11 +8,11 @@
 
 阶段：组织命令。
 
-授权请求引用了注册表没有声明的能力点。
+授权请求引用了注册表没有声明的能力点，或普通授权操作使用了初始化专用的全部能力标记。
 
 ## 修复步骤
 
-1. 先在 domain 声明并导出相应命令/聚合，再查看能力目录；不要在管理页面凭空发明能力名称。
+1. 先在 domain 声明并导出相应命令/聚合，再查看能力目录；不要在管理页面凭空发明能力名称。全部能力标记仅由首次初始化写入。
 
 ## 正例
 
@@ -35,7 +35,7 @@ PurchaseOrder.anything // 没有对应声明
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
 - `packages/admin/src/domain/constraints.ts:21`
-- `packages/admin/src/domain/constraints.ts:26`
+- `packages/admin/src/domain/constraints.ts:27`
 
 实现片段（位置随框架版本更新）：
 

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

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

package/templates/blank/docs/errors/CAGE-IMPACT-002.md

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

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

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

package/templates/blank/docs/errors/CAGE-INIT-002.md

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

package/templates/blank/docs/errors/CAGE-INIT-003.md

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

package/templates/blank/docs/errors/CAGE-INIT-004.md

@@ -1,6 +1,6 @@
 # CAGE-INIT-004：账号已创建但 .env 替换失败
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/blank/docs/errors/CAGE-INIT-005.md

@@ -1,6 +1,6 @@
 # CAGE-INIT-005：显式组织初始化或凭据交付失败
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

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

package/templates/blank/docs/errors/CAGE-JOB-002.md

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

package/templates/blank/docs/errors/CAGE-JOB-003.md

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

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

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

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

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

package/templates/blank/docs/errors/CAGE-MIG-002.md

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

package/templates/blank/docs/errors/CAGE-MIG-005.md

@@ -1,6 +1,6 @@
 # CAGE-MIG-005：已执行迁移内容被修改
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

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

package/templates/blank/docs/errors/CAGE-NAME-002.md

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

package/templates/blank/docs/errors/CAGE-NAME-003.md

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

package/templates/blank/docs/errors/CAGE-NAME-004.md

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

package/templates/blank/docs/errors/CAGE-NAME-005.md

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

package/templates/blank/docs/errors/CAGE-NAME-006.md

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

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

@@ -0,0 +1,52 @@
+# CAGE-ONTOLOGY-001：本体节点缺少结构化业务名称
+
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：check / gen / verify / 图谱与上下文诊断。
+
+当前项目可定位的聚合、字段、状态、命令、事件、查询或任务没有非空业务名称，图谱只能回退机器标识。默认警告，graph.naming 为 required 时作为门禁错误。
+
+## 修复步骤
+
+1. 按 reason 的完整节点 key 定位声明。字段和状态的位置指向所属聚合，继续在其中查找成员；无本地源码位置的依赖节点不在本检查范围。
+2. 对象、命令、查询和任务填写 description；事件在第三个参数填写 description；字段用 .describe(...) 或关系选项 description；每个状态都在 states 的 labels 中命名。旧声明可用 graph.labels 的完整 key 覆盖显示。
+3. 普通注释与前端 statusLabel 不会自动进入本体。名称用用户的业务用语，不为翻译改表名、状态值或能力点；详见 docs/development/guides/ontology-modeling.md。
+4. 补齐后重跑 check 并查看 graph/context；完整性不验证语言、名称质量或任意业务关系，仍按已明确规则验证外键方向、基数、状态迁移及真实触发链。
+
+## 正例
+
+```text
+states('active', 'archived', { terminal: ['archived'], labels: { active: '使用中', archived: '已归档' } })
+```
+
+## 反例
+
+```text
+states('active', 'archived', { terminal: ['archived'] }) // 只在页面或注释中翻译状态，没有结构化名称
+```
+
+## 修复后验证
+
+重跑 cage check，再在 graph/context 中按业务用语核对名称；对象关系与运行行为仍需独立业务用例验证。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/ontology-names.ts:27`
+- `packages/cli/src/ontology-names.ts:42`
+- `packages/cli/src/sync.ts:42`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+ * @param presentation 与图谱同一次抽取产生的名称，配置短标题优先于声明文案。
+ * @returns 每个缺名节点一条 CAGE-ONTOLOGY-001；不推断语言、不从注释或前端反推业务名称。
+ */
+export function checkOntologyNames(cfg: CageConfig, graph: Ontology, presentation: GraphPresentation): Finding[] {
+  const aggregates = new Map(graph.nodes.filter(node => node.kind === 'aggregate').map(node => [node.id, node]));
+```

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

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

package/templates/blank/docs/errors/CAGE-PAIR-002.md

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

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

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

package/templates/blank/docs/errors/CAGE-QUERY-002.md

@@ -1,6 +1,6 @@
 # CAGE-QUERY-002：自定义查询直接访问基表
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

package/templates/blank/docs/errors/CAGE-QUERY-003.md

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

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

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

package/templates/blank/docs/errors/CAGE-REACT-002.md

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

package/templates/blank/docs/errors/CAGE-REACT-003.md

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

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

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

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

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

package/templates/blank/docs/errors/CAGE-REG-002.md

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

package/templates/blank/docs/errors/CAGE-REG-003.md

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

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

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

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

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

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

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

package/templates/blank/docs/errors/CAGE-SCOPE-002.md

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

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

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

package/templates/blank/docs/errors/CAGE-SECRET-002.md

@@ -1,6 +1,6 @@
 # CAGE-SECRET-002：源码疑似包含密钥字面量
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

@@ -1,6 +1,6 @@
 # CAGE-SENS-001：敏感字段未标注就进入事件
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 

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

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

package/templates/blank/docs/errors/CAGE-SQL-002.md

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

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

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

package/templates/blank/docs/errors/CAGE-STATE-002.md

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

package/templates/blank/docs/errors/CAGE-STATE-003.md

@@ -1,6 +1,6 @@
 # CAGE-STATE-003：状态名称格式错误
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 
@@ -12,7 +12,7 @@
 
 ## 修复步骤
 
-1. 状态标识使用 pending_approval 等，中文名称通过页面/graph.labels 显示。
+1. 状态标识使用 pending_approval 等，业务名称在 states 的 labels 中填写，graph.labels 可覆盖显示；页面文案和普通注释不会自动进入本体。
 
 ## 正例
 

package/templates/blank/docs/errors/CAGE-STATE-004.md

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

package/templates/blank/docs/errors/CAGE-STATE-005.md

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

package/templates/blank/docs/errors/CAGE-STATE-010.md

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

package/templates/blank/docs/errors/CAGE-STATE-011.md

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

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

@@ -1,6 +1,6 @@
 # CAGE-STRUCT-001：业务源码目录不符合模块约定
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 
@@ -14,7 +14,7 @@
 
 1. 前端使用 app / modules / shared，src 根目录只保留 main.tsx；领域使用 modules / workflows / integrations / shared，根目录只保留 index.ts。
 2. 把页面、表单、hooks 和业务辅助代码放在同一业务模块，需要时再拆文件；不要创建空目录凑层级。测试就近放置，类型声明 .d.ts 不受入口约束。
-3. 目录调整后修正导入并运行 cage check、gen、verify；完整规范见 docs/ai/project-structure.md。
+3. 目录调整后修正导入并运行 cage check、gen、verify；完整规范见 docs/development/reference/project-structure.md。
 
 ## 正例
 
@@ -32,7 +32,7 @@ packages/domain/src/expense.ts
 
 ## 修复后验证
 
-按 docs/ai/project-structure.md 整理归属和导入后重跑 cage check 与 verify；不关闭目录规则，也不改业务表或能力标识。
+按 docs/development/reference/project-structure.md 整理归属和导入后重跑 cage check 与 verify；不关闭目录规则，也不改业务表或能力标识。
 
 ## 框架内的检查位置
 
@@ -47,5 +47,5 @@ packages/domain/src/expense.ts
           code: 'CAGE-STRUCT-001',
           at,
           reason: `${kind} 源码没有放入约定模块：${from.path}`,
-          fix: `src 根目录只保留${kind === 'domain' ? '领域 index.ts' : '浏览器 main.tsx'}；业务按归属放入 ${layers.join(' / ')}，见 docs/ai/project-structure.md`,
+          fix: `src 根目录只保留${kind === 'domain' ? '领域 index.ts' : '浏览器 main.tsx'}；业务按归属放入 ${layers.join(' / ')}，见 docs/development/reference/project-structure.md`,
 ```

package/templates/blank/docs/errors/CAGE-STRUCT-002.md

@@ -1,6 +1,6 @@
 # CAGE-STRUCT-002：源码依赖越过模块边界
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 
@@ -32,7 +32,7 @@ import { ExpensePage } from '../../modules/expense/pages/expense-page';
 
 ## 修复后验证
 
-按 docs/ai/project-structure.md 整理归属和导入后重跑 cage check 与 verify；不关闭目录规则，也不改业务表或能力标识。
+按 docs/development/reference/project-structure.md 整理归属和导入后重跑 cage check 与 verify；不关闭目录规则，也不改业务表或能力标识。
 
 ## 框架内的检查位置
 
@@ -47,5 +47,5 @@ import { ExpensePage } from '../../modules/expense/pages/expense-page';
             code: 'CAGE-STRUCT-002',
             at: `${at}:${source.slice(0, spec.pos).split('\n').length}`,
             reason: `${reason}（${spec.fileName}）`,
-            fix: '调整依赖归属；共用纯逻辑下沉到 shared，页面协作由 app 传参，领域交互通过模块公开声明。见 docs/ai/project-structure.md',
+            fix: '调整依赖归属；共用纯逻辑下沉到 shared，页面协作由 app 传参，领域交互通过模块公开声明。见 docs/development/reference/project-structure.md',
 ```

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

@@ -1,6 +1,6 @@
 # CAGE-SYNC-001：AGENTS 托管区过期或标记损坏
 
-[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+[返回错误码册](README.md) · [业务排错](../development/tools/troubleshooting.md)
 
 > 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
 
@@ -34,9 +34,9 @@ sync --check 发现框架规则需更新，或 begin/end 标记缺失一边、
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/sync.ts:149`
-- `packages/cli/src/sync.ts:156`
-- `packages/cli/src/sync.ts:167`
+- `packages/cli/src/sync.ts:73`
+- `packages/cli/src/sync.ts:80`
+- `packages/cli/src/sync.ts:91`
 
 实现片段（位置随框架版本更新）：