@yss123/cage-cli 0.1.0 → 0.3.0

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

@@ -0,0 +1,51 @@
+# CAGE-PAIR-002：离开持有资源状态却没有释放
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：图规则。
+
+图规则沿进入状态的 acquires 反应推断资源持有，发现离开该状态的迁移没有 releases 路径，也未进入同样持有的状态。
+
+## 修复步骤
+
+1. 沿报错命令 → emits → reaction → 释放命令检查，新增所需事件与真正释放行为。
+2. 释放反应标注与获取一致的资源名；检查取消、收货、撤回等每条离开路径及 map 的条件分支。
+3. 标签只参与静态分析，不会自动释放资源；重要路径需用业务数据验证。不要删除 acquires 或添加永不执行的 map 来骗过检查。
+
+## 正例
+
+```text
+reaction(OrderCancelled, { command: releaseLock, releases: 'inventory.lock', map: e => e.previousStatus === 'approved' ? { id: e.orderId } : null })
+```
+
+## 反例
+
+```text
+新增 approved → draft 的撤回命令，却没有事件及释放反应
+```
+
+## 修复后验证
+
+重跑 cage check，并用业务用例验证每条关键离开路径确实释放资源。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:63`
+- `packages/cli/src/rules.ts:67`
+- `packages/cli/src/rules.ts:81`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-PAIR-002：进入某状态时获得了资源，从该状态出发的每一条迁移都必须释放它，或进入一个同样持有它的状态 */
+/**
+ * 检查离开持有状态的迁移是否声明释放，或进入同样持有资源的状态。
+ * @param g 当前图。
+```

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

@@ -0,0 +1,47 @@
+# CAGE-QUERY-001：查询必须选择一种实现
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+query 同时提供或同时未提供 sql/build。
+
+## 修复步骤
+
+1. 在参数化手写 SQL 与查询构建器之间选择一种，显式声明 reads 和 input。
+
+## 正例
+
+```text
+query('poByStatus', { reads: [PurchaseOrder], input, sql })
+```
+
+## 反例
+
+```text
+query('poByStatus', { reads: [PurchaseOrder], sql, build })
+```
+
+## 修复后验证
+
+重跑 cage check/gen；用普通用户验证查询参数、read 能力、范围和掩码。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:166`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (!/^[a-z][A-Za-z0-9]*$/.test(name)) throw declError('CAGE-NAME-005', `查询名 ${name} 必须是小驼峰`);
+  if (!def.sql === !def.build) throw declError('CAGE-QUERY-001', `查询 ${name} 必须二选一：sql 或 build`);
+  if (def.sql && /\bcore\.|\bsys\./i.test(def.sql)) {
+    throw declError('CAGE-QUERY-002', `查询 ${name} 引用了基表，只能引用 safe.* 安全视图`);
+  }
+```

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

@@ -0,0 +1,47 @@
+# CAGE-QUERY-002：自定义查询直接访问基表
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+query.sql 引用了 core.* 或 sys.*。
+
+## 修复步骤
+
+1. 改成对应 safe 视图，让只读账号落实范围与掩码。需要系统管理数据时使用框架已有系统接口，不绕过安全层。
+
+## 正例
+
+```text
+'select amount from safe.purchase_order where status = :status'
+```
+
+## 反例
+
+```text
+'select * from core.purchase_order'
+```
+
+## 修复后验证
+
+重跑 cage check/gen；用普通用户验证查询参数、read 能力、范围和掩码。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:168`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (def.sql && /\bcore\.|\bsys\./i.test(def.sql)) {
+    throw declError('CAGE-QUERY-002', `查询 ${name} 引用了基表，只能引用 safe.* 安全视图`);
+  }
+  if (def.audit && !def.audit.purpose.trim()) throw declError('CAGE-QUERY-003', `查询 ${name} 的审计 purpose 不能为空`);
+  return Object.freeze({
+```

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

@@ -0,0 +1,50 @@
+# CAGE-QUERY-003：查询读取范围与声明不一致
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 图规则。
+
+SQL 引用了 reads 未声明聚合的 safe 视图，或引用非 safe 的限定表。
+
+## 修复步骤
+
+1. 在 reads 列出每个实际读取的聚合，并只查询相应安全视图；join 同样要声明。
+
+## 正例
+
+```text
+reads: [PurchaseOrder]；SQL from safe.purchase_order
+```
+
+## 反例
+
+```text
+reads: []；SQL from safe.purchase_order
+```
+
+## 修复后验证
+
+重跑 cage check/gen；用普通用户验证查询参数、read 能力、范围和掩码。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:208`
+- `packages/cli/src/rules.ts:228`
+- `packages/cli/src/rules.ts:246`
+- `packages/kernel/src/primitives/flow.ts:170`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-QUERY-003：手写 SQL 只能引用 reads 里聚合的安全视图 */
+/**
+ * 从 SQL 文本检查 safe 视图与 reads 对应关系及显式基表引用。
+ * @param g 当前图。
+```

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

@@ -0,0 +1,47 @@
+# CAGE-REACT-001：反应目标与命令聚合不一致
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 写流水线。
+
+reaction 显式 target 与 command.agg 不同。
+
+## 修复步骤
+
+1. 省略 target 由框架从命令推导；确需写出时必须是命令所属聚合。
+
+## 正例
+
+```text
+reaction(OrderApproved, { command: acquireLock, map })
+```
+
+## 反例
+
+```text
+target: PurchaseOrder，command 却属于 InventoryLock
+```
+
+## 修复后验证
+
+重跑 cage check；同事务链验证共同提交/回滚，异步链检查 worker 和死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:87`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (def.target && def.target !== def.command.agg) {
+    throw declError('CAGE-REACT-001', `反应的 target 与 command 所属聚合不一致`);
+  }
+  if (def.order !== undefined && (!Number.isSafeInteger(def.order) || def.order < 0)) {
+    throw declError('CAGE-REACT-003', '反应 order 必须为非负安全整数');
+```

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

@@ -0,0 +1,47 @@
+# CAGE-REACT-002：同事务反应链嵌套过深
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 写流水线。
+
+同事务执行深度超出内核上限，常见原因是命令与事件互相触发形成循环。
+
+## 修复步骤
+
+1. 沿事件/反应图定位循环，减少同事务级联；仅在业务允许最终一致时改成 outbox，并避免异步循环。
+
+## 正例
+
+```text
+单向批准 → 建锁，释放不会再次触发批准
+```
+
+## 反例
+
+```text
+批准触发建锁，建锁又触发批准，或随意调高深度上限
+```
+
+## 修复后验证
+
+重跑 cage check；同事务链验证共同提交/回滚，异步链检查 worker 和死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/kernel.ts:263`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    const agg = cmd.agg;
+    if (depth > this.maxDepth) throw new Error(`[CAGE-REACT-002] 同事务反应嵌套超过 ${this.maxDepth} 层`);
+
+    // 第 1 关：认证
+    if (!ctx.actor || (ctx.actor.kind === 'anonymous' && !cmd.public)) throw cageError('UNAUTHENTICATED');
+```

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

@@ -0,0 +1,50 @@
+# CAGE-REACT-003：集合或步骤顺序声明无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / 写流水线。
+
+reactionEach 没有正整数上限或排序字段，order 非法，或同事件同事务分组混用有序/无序步骤、顺序重复。
+
+## 修复步骤
+
+1. 为集合声明 maxItems、orderBy、items 和 map；排序键必须稳定、非空且唯一。
+2. 同事件同 tx 分组需要显式顺序时，为全部步骤声明不同的非负整数 order；锁资源按稳定键串行处理。
+
+## 正例
+
+```text
+reactionEach(Allocated, { command: acquire, items: e => e.assets, maxItems: 20, orderBy: 'assetId', order: 20, tx: 'same', map: item => ({ id: item.assetId }) })
+```
+
+## 反例
+
+```text
+同事件同事务一条 order: 10、另一条没有 order，或两个步骤都 order: 10
+```
+
+## 修复后验证
+
+重跑 cage check；同事务链验证共同提交/回滚，异步链检查 worker 和死信。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/collection.ts:68`
+- `packages/kernel/src/primitives/flow.ts:90`
+- `packages/kernel/src/registry.ts:230`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (!Number.isSafeInteger(def.maxItems) || def.maxItems < 1 || !def.orderBy) {
+    throw declError('CAGE-REACT-003', '集合反应必须声明正整数 maxItems 和非空 orderBy 字段');
+  }
+  const base = reaction(event, { ...def, map: () => null });
+  const expand = (payload: PayloadOf<E>): ReactionEntry<z.input<C['input']>>[] => {
+```

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

@@ -0,0 +1,50 @@
+# CAGE-READS-001：handler 使用了未声明读依赖
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：handler 执行。
+
+handler 访问 deps 中不存在的别名。
+
+## 修复步骤
+
+1. 在命令 reads 添加真实聚合与正确别名，核对入口导出。不要通过 any 或自建仓储绕过依赖声明。
+
+## 正例
+
+```text
+reads: { stock: Inventory }；使用 deps.stock.findOne({ sku })
+```
+
+## 反例
+
+```text
+reads: {}；使用 deps.stock
+```
+
+## 修复后验证
+
+检查本体图 reads 边并运行该命令的业务用例。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/pipeline/load.ts:74`
+- `packages/kernel/src/pipeline/load.ts:99`
+- `packages/kernel/src/primitives/command.ts:54`
+- `packages/kernel/src/primitives/command.ts:183`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+ * 仓储绑定当前事务与身份，handler 的读操作因此看到同一事务状态且不能写入。
+ * Proxy 将未声明别名转成明确 CAGE-READS-001；then/toJSON 保留为普通对象协议属性。
+ */
+export function bindReads<R extends Reads>(tx: Db, reads: R, ctx: Ctx): Record<string, ReadRepo<any>> {
+  const deps: Record<string, ReadRepo<any>> = {};
+```

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

@@ -0,0 +1,54 @@
+# CAGE-REG-001：注册表缺少被引用声明
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 执行。
+
+命令、读依赖、反应、审批或任务引用了没有从 domain 入口导出的聚合/命令，或执行时找不到命令。
+
+## 修复步骤
+
+1. 从统一入口导出依赖双方，确认引用是同一个声明对象且名字正确；修复后重新 check/gen。
+
+## 正例
+
+```text
+export * from './inventory.js'; export * from './purchase-order.js';
+```
+
+## 反例
+
+```text
+只导出反应，却没有导出它的目标命令
+```
+
+## 修复后验证
+
+重跑 cage check/analyze/gen，确认统一入口包含引用双方。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/approval/src/route.ts:161`
+- `packages/kernel/src/kernel.ts:161`
+- `packages/kernel/src/registry.ts:209`
+- `packages/kernel/src/registry.ts:215`
+- `packages/kernel/src/registry.ts:220`
+- `packages/kernel/src/registry.ts:234`
+- `packages/kernel/src/registry.ts:238`
+- `packages/kernel/src/registry.ts:268`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+        for (const query of s.context.queries ?? []) if (!registry.queries.some(q => q.name === query))
+          throw declError('CAGE-REG-001', `AI 步骤引用的查询 ${query} 未导出`);
+      }
+    },
+  });
+```

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

@@ -0,0 +1,49 @@
+# CAGE-REG-002：聚合或查询注册重名
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 执行。
+
+同类聚合/查询拥有相同逻辑名称。
+
+## 修复步骤
+
+1. 保留一个规范声明，或为真正不同对象选不同逻辑名；不能通过对象复制创建同名注册。
+
+## 正例
+
+```text
+aggregate('PurchaseOrder', ...)、aggregate('Inventory', ...)
+```
+
+## 反例
+
+```text
+不同文件都 aggregate('Order', ...) 并导出
+```
+
+## 修复后验证
+
+重跑 cage check/analyze/gen，确认统一入口包含引用双方。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/registry.ts:134`
+- `packages/kernel/src/registry.ts:176`
+- `packages/kernel/src/registry.ts:242`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+          if (aggregates.some((a) => a.name === (v as AnyAggregate).name)) {
+            throw declError('CAGE-REG-002', `聚合名重复：${(v as AnyAggregate).name}`);
+          }
+          aggregates.push(v as AnyAggregate);
+          break;
+```

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

@@ -0,0 +1,47 @@
+# CAGE-REG-003：命令能力点重复
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 执行。
+
+同一聚合的多个命令解析成同一个 Aggregate.command 能力点。
+
+## 修复步骤
+
+1. 为不同操作指定不同 name，跨文件导出名也保持唯一；相同操作复用同一命令对象。
+
+## 正例
+
+```text
+name: 'submit' 与 name: 'cancel'
+```
+
+## 反例
+
+```text
+同一聚合两个命令都 name: 'update'
+```
+
+## 修复后验证
+
+重跑 cage check/analyze/gen，确认统一入口包含引用双方。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/registry.ts:212`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      throw declError('CAGE-REL-001', `${c.cmd.agg.name}.related 是生成客户端的关联读取入口；请为业务命令使用其他 name`);
+    if (caps.has(c.capability)) throw declError('CAGE-REG-003', `能力点重复：${c.capability}，可用 command({ name }) 区分`);
+    caps.add(c.capability);
+    for (const [alias, a] of Object.entries(c.cmd.reads)) {
+      if (!aggSet.has(a)) throw declError('CAGE-REG-001', `命令 ${c.capability} 的 reads.${alias} 引用的聚合没有导出`);
+```

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

@@ -0,0 +1,64 @@
+# CAGE-REL-001：关系字段声明无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 生成。
+
+关系目标未导出、hasMany.mappedBy 不是指回当前聚合的公开 ref、关系表重名/过长，或集合关系用于不支持的位置与修饰。带关系聚合的用户命令名 related 也会占用生成客户端入口。
+
+## 修复步骤
+
+1. 把 ref/hasMany/manyToMany 的目标从 domain 入口导出；循环引用使用聚合名字符串。
+2. hasMany 的 mappedBy 写目标上的真实 ref 字段名，该字段不能 hidden 或 sensitive；修改归属调用子对象命令。
+3. 集合关系只写在聚合 fields 中，不放进 list、事件载荷或 scope 字段。不要对关系链式调用 optional/unique/hidden/sensitive；没有关联用空集合表示。
+4. 缩短或调整发生冲突的字段/表名；业务命令避开 related，运行 cage check/gen 后审查迁移。
+
+## 正例
+
+```text
+Note.fields.members = manyToMany('User', { description: '协作成员' }); // User 已导出
+Notebook.fields.notes = hasMany('Note', { mappedBy: 'notebookId' }); // Note.notebookId = ref('Notebook')
+```
+
+## 反例
+
+```text
+hasMany('Note', { mappedBy: 'title' }); // title 不是反向 ref
+list({ members: manyToMany('User') }); // JSON 明细中不能声明关系
+```
+
+## 修复后验证
+
+重跑 cage check/gen；迁移后用真实用户验证关系命令、关联分页读取和双侧范围。不要手写纯中间表聚合。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:188`
+- `packages/kernel/src/primitives/event.ts:50`
+- `packages/kernel/src/primitives/fields.ts:190`
+- `packages/kernel/src/primitives/fields.ts:196`
+- `packages/kernel/src/primitives/fields.ts:203`
+- `packages/kernel/src/primitives/fields.ts:209`
+- `packages/kernel/src/primitives/fields.ts:277`
+- `packages/kernel/src/primitives/fields.ts:284`
+- `packages/kernel/src/primitives/fields.ts:335`
+- `packages/kernel/src/registry.ts:193`
+- `packages/kernel/src/registry.ts:197`
+- `packages/kernel/src/registry.ts:203`
+- `packages/kernel/src/registry.ts:211`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (f && f !== 'id' && !(f in fields)) throw declError('CAGE-SCOPE-002', `${name} 的范围字段 ${f} 不存在`);
+    if (f && f !== 'id' && isRelation(fields[f])) throw declError('CAGE-REL-001', `${name} 的范围字段必须是主表列，不能使用集合关系 ${f}`);
+    if (f && f !== 'id' && isFile(fields[f])) throw declError('CAGE-FILE-001', `${name} 的范围字段不能使用文件 ${f}`);
+  }
+  const scope: ScopeSpec = Object.freeze({ ...sc, ownerField });
+```

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

@@ -0,0 +1,48 @@
+# CAGE-ROUTE-001：业务项目手写 HTTP 路由
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：lint / verify。
+
+业务代码调用 app.get/post 等手动注册接口，绕过声明生成路径。
+
+## 修复步骤
+
+1. 将普通业务写接口声明为 command、读接口声明为 query；API 入口只装配框架。协议扩展另按框架边界评估。
+
+## 正例
+
+```text
+领域 command → gen → 自动路由和前端契约
+```
+
+## 反例
+
+```text
+app.post('/api/order/submit', handler)
+```
+
+## 修复后验证
+
+重新生成，检查 generated/routes.json 和前端契约，再验证自动接口。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/lint/src/rules/no-manual-routes.ts:3`
+- `packages/lint/src/rules/no-manual-routes.ts:23`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+ * 检查业务代码是否绕过声明直接注册 HTTP 路由。
+ * 通过常见接收器名、HTTP 方法和路径形状识别调用，命中返回 CAGE-ROUTE-001。
+ * 这是有界语法检查，不解析任意变量别名或运行时动态路由；框架自己的 HTTP 实现由其维护边界管理。
+ */
+// 业务项目里禁止手写 HTTP 路由：没有声明就没有路由，所有写入都经过内核
+```