@yss123/cage-cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,51 @@
+# CAGE-STRUCT-001：业务源码目录不符合模块约定
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：check / analyze / verify（structure: modular）。
+
+启用 structure: modular 后，domain/web 的 src 根目录出现业务文件，或使用约定之外的顶层源码目录。
+
+## 修复步骤
+
+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。
+
+## 正例
+
+```text
+apps/web/src/modules/expense/pages/expense-list-page.tsx
+packages/domain/src/modules/expense/expense.ts
+```
+
+## 反例
+
+```text
+apps/web/src/expense-list.tsx
+packages/domain/src/expense.ts
+```
+
+## 修复后验证
+
+按 docs/ai/project-structure.md 整理归属和导入后重跑 cage check 与 verify；不关闭目录规则，也不改业务表或能力标识。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/project-structure.ts:58`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+        findings.push({
+          code: 'CAGE-STRUCT-001',
+          at,
+          reason: `${kind} 源码没有放入约定模块：${from.path}`,
+          fix: `src 根目录只保留${kind === 'domain' ? '领域 index.ts' : '浏览器 main.tsx'}；业务按归属放入 ${layers.join(' / ')}，见 docs/ai/project-structure.md`,
+```

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

@@ -0,0 +1,51 @@
+# CAGE-STRUCT-002：源码依赖越过模块边界
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：check / analyze / verify（structure: modular）。
+
+共享代码反向依赖业务，前端业务互相穿透，领域模块依赖组合层，或跨模块导入了内部文件。
+
+## 修复步骤
+
+1. app 组合前端模块；各模块只用自己的实现和 shared，通过 props/回调协作。shared 不放具体业务请求、文案和状态。
+2. 领域模块间确有 reads 等依赖时从目标 index.ts 导入；跨模块事件反应写到 workflows，外部协议写到 integrations。
+3. 不要用领域总入口反向导入模块内部。公开入口仅转导出，依赖必须保持单向，禁止通过路径别名或转导出绕开规则。
+
+## 正例
+
+```text
+// 领域采购模块读取库存公开声明
+import { Inventory } from '../inventory/index.js';
+```
+
+## 反例
+
+```text
+// shared 反向依赖某项业务页面
+import { ExpensePage } from '../../modules/expense/pages/expense-page';
+```
+
+## 修复后验证
+
+按 docs/ai/project-structure.md 整理归属和导入后重跑 cage check 与 verify；不关闭目录规则，也不改业务表或能力标识。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/project-structure.ts:108`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+          findings.push({
+            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',
+```

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

@@ -0,0 +1,48 @@
+# CAGE-SYNC-001：AGENTS 托管区过期或标记损坏
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：sync / verify。
+
+sync --check 发现框架规则需更新，或 begin/end 标记缺失一边、重复、顺序错误。
+
+## 修复步骤
+
+1. 保留唯一且有序的 begin/end，项目业务约定移到标记外，再运行 pnpm exec cage sync。同步只替换托管区，不升级业务和文档。
+
+## 正例
+
+```text
+一个完整托管区，前后保留自己的业务规则
+```
+
+## 反例
+
+```text
+复制两段 begin/end，或只删除 end 标记
+```
+
+## 修复后验证
+
+运行 cage sync 后再 sync --check，确认标记外业务约定保持不变。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/sync.ts:97`
+- `packages/cli/src/sync.ts:110`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (starts.length !== 1 || ends.length !== 1 || ends[0].index! < starts[0].index!) {
+    throw new Error('[CAGE-SYNC-001] 托管区标记不完整或重复，请修复 AGENTS.md 的 begin/end 标记');
+  }
+  return current.slice(0, starts[0].index) + latest + current.slice(ends[0].index! + ends[0][0].length);
+}
+```

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

@@ -0,0 +1,47 @@
+# CAGE-TEST-001：测试进程没有生成结果报告
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：test / verify。
+
+测试未输出当前运行的 JSON 结果，CLI 无法认定测试通过。
+
+## 修复步骤
+
+1. 查看 Vitest 的启动/配置错误并重跑，确认当前 .cage/test-results.json；不复用旧报告，不将 skipped 当作 passed。
+
+## 正例
+
+```text
+测试正常退出并生成当前结果，分别报告 passed/failed/skipped
+```
+
+## 反例
+
+```text
+测试没启动，却读取上次 success:true 当作本次成功
+```
+
+## 修复后验证
+
+确认当前运行退出码与 JSON 报告，分别报告通过、失败和跳过。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/verify.ts:36`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (code !== 0) return code;
+  if (!existsSync(report)) throw new Error('[CAGE-TEST-001] 测试进程未输出结果报告，不能判定通过');
+  const result = JSON.parse(readFileSync(report, 'utf8'));
+  if (result.numPendingTests) console.log(`覆盖提示：${result.numPendingTests} 个用例跳过，请结合业务测试验收。`);
+  return result.success ? 0 : 1;
+```

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

@@ -0,0 +1,48 @@
+# CAGE-UNSAFE-001：逃生口缺少原因或负责人
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明 / lint / budget。
+
+unsafe 的 reason/owner 缺失或为空，运行时或 lint 拒绝。
+
+## 修复步骤
+
+1. 先尝试正常声明；确需逃生口写清业务必要性、负责人和评审依据，并通过预算检查。它不会自动授予额外权限。
+
+## 正例
+
+```text
+unsafe({ reason: '已评审的历史数据修复', owner: '数据负责人' }, action)
+```
+
+## 反例
+
+```text
+unsafe({ reason: '', owner: '' }, action)
+```
+
+## 修复后验证
+
+运行相关 lint、budget 和真正业务用例，保留原因与负责人。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/flow.ts:219`
+- `packages/lint/src/rules/unsafe-needs-reason.ts:8`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+export function unsafe<T>(tag: UnsafeTag, fn: () => T): T {
+  if (!tag?.reason || !tag?.owner) throw declError('CAGE-UNSAFE-001', 'unsafe 必须写明 reason 和 owner');
+  return fn();
+}
+(unsafe as any)[UNSAFE] = true;
+```

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

@@ -0,0 +1,48 @@
+# CAGE-UPGRADE-001：升级版本或 codemod 有歧义
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：upgrade。
+
+当前 CLI 不含目标版本迁移，或 command 同时存在旧 caller 与新 invokedBy。
+
+## 修复步骤
+
+1. 先安装目标版本 CLI；dry-run 审查迁移。新旧属性同时存在时人工确定语义并保留一种，不让工具猜测。
+
+## 正例
+
+```text
+安装目标 CLI → upgrade --dry-run → 审查后 upgrade
+```
+
+## 反例
+
+```text
+command(A, { caller: 'user', invokedBy: 'process', ... })
+```
+
+## 修复后验证
+
+审查 dry-run 后升级，再按新版本运行 gen/verify，报告尚未完成的数据库/外部联调。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/upgrade.ts:45`
+- `packages/cli/src/upgrade.ts:58`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (old && obj?.getProperty('invokedBy'))
+      throw new Error('[CAGE-UPGRADE-001] command 同时包含 caller 与 invokedBy，请手工消除歧义');
+    old?.rename('invokedBy');
+  }
+  return file.getFullText();
+```

package/templates/app/docs/errors/README.md

@@ -0,0 +1,307 @@
+# 错误码册
+
+这是本业务项目自带的离线诊断手册。先使用错误码、声明位置、reason/fix 定位；不需要克隆框架仓库。
+
+- [HTTP 运行时错误与业务码](runtime.md)：401/403/404、状态冲突、约束拒绝、DOMAIN_ERROR 等。
+- [业务排错顺序](../ai/troubleshooting.md)：启动、权限、审批人、worker、死信与导入导出。
+- CAGE-* 是声明、工具链或内部运行诊断；HTTP code 与业务 domainCode 是另一层，不要混为一谈。
+
+每页包含触发阶段、具体原因、修复步骤、正反例、验证方法与当前版实现位置。例子为局部说明，不能替代完整业务输入。
+
+## 审批
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-APPR-001](CAGE-APPR-001.md) | 可路由字段不存在 |
+| [CAGE-APPR-002](CAGE-APPR-002.md) | 审批结论落到其他聚合 |
+| [CAGE-APPR-003](CAGE-APPR-003.md) | 审批结论未允许流程调用 |
+| [CAGE-APPR-004](CAGE-APPR-004.md) | 路由没有对应审批绑定 |
+| [CAGE-APPR-005](CAGE-APPR-005.md) | 流程名称格式错误 |
+| [CAGE-APPR-006](CAGE-APPR-006.md) | 流程没有步骤 |
+| [CAGE-APPR-007](CAGE-APPR-007.md) | 找不到审批人 |
+| [CAGE-APPR-010](CAGE-APPR-010.md) | 流程专用命令没有调用者 |
+
+## 登录认证
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-AUTH-001](CAGE-AUTH-001.md) | OIDC 发现文档获取失败 |
+
+## 体积与逃生口预算
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-BUDGET-001](CAGE-BUDGET-001.md) | 内核超出体积预算 |
+| [CAGE-BUDGET-002](CAGE-BUDGET-002.md) | 公共原语超过词汇预算 |
+| [CAGE-BUDGET-003](CAGE-BUDGET-003.md) | 新增未经基线认可的 unsafe |
+
+## 命令
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-CMD-002](CAGE-CMD-002.md) | 已有记录命令缺少 id |
+| [CAGE-CMD-003](CAGE-CMD-003.md) | 新建命令没有目标状态 |
+
+## 第三方连接器
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-CONN-001](CAGE-CONN-001.md) | 连接器名称格式错误 |
+| [CAGE-CONN-002](CAGE-CONN-002.md) | 外部操作路径格式错误 |
+| [CAGE-CONN-003](CAGE-CONN-003.md) | 地址白名单包含协议或路径 |
+| [CAGE-CONN-004](CAGE-CONN-004.md) | 只读操作被用作出站写映射 |
+| [CAGE-CONN-005](CAGE-CONN-005.md) | 入站事件名称格式错误 |
+| [CAGE-CONN-006](CAGE-CONN-006.md) | 回调命令未允许 external |
+| [CAGE-CONN-007](CAGE-CONN-007.md) | 当前环境没有连接器地址 |
+| [CAGE-CONN-008](CAGE-CONN-008.md) | 外部请求发生网络错误或超时 |
+| [CAGE-CONN-009](CAGE-CONN-009.md) | 外部服务返回非成功状态 |
+| [CAGE-CONN-010](CAGE-CONN-010.md) | 外部响应不符合 schema |
+| [CAGE-CONN-011](CAGE-CONN-011.md) | 出站永久失败进入死信 |
+| [CAGE-CONN-012](CAGE-CONN-012.md) | 外部专用命令没有声明调用者 |
+
+## 创建应用
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-CREATE-001](CAGE-CREATE-001.md) | 项目创建参数或模板资源有误 |
+
+## 可抽取声明
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-DECL-001](CAGE-DECL-001.md) | 声明不在可抽取的顶层常量 |
+| [CAGE-DECL-002](CAGE-DECL-002.md) | 声明没有从 domain 入口导出 |
+| [CAGE-DECL-003](CAGE-DECL-003.md) | 声明不是 export const |
+| [CAGE-DECL-004](CAGE-DECL-004.md) | 跨文件导出名冲突 |
+
+## 依赖边界
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-DEP-001](CAGE-DEP-001.md) | 领域声明直接依赖 IO |
+| [CAGE-DEP-002](CAGE-DEP-002.md) | 适配器绕过命令写库 |
+| [CAGE-DEP-003](CAGE-DEP-003.md) | 前端依赖服务端实现 |
+| [CAGE-DEP-004](CAGE-DEP-004.md) | 声明或 handler 直接发请求/动态导入 |
+| [CAGE-DEP-005](CAGE-DEP-005.md) | domain 反向依赖生成物 |
+
+## 工程目录与模块依赖
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-STRUCT-001](CAGE-STRUCT-001.md) | 业务源码目录不符合模块约定 |
+| [CAGE-STRUCT-002](CAGE-STRUCT-002.md) | 源码依赖越过模块边界 |
+
+## 死信操作
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-DLQ-001](CAGE-DLQ-001.md) | 死信不存在或已经处理 |
+
+## 运行配置
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-ENV-001](CAGE-ENV-001.md) | 缺少数据库连接配置 |
+
+## 事件载荷与兼容性
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-EVENT-001](CAGE-EVENT-001.md) | 事件载荷不满足声明 |
+| [CAGE-EVENT-002](CAGE-EVENT-002.md) | 事件变更不向后兼容 |
+
+## 字段
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-FIELD-001](CAGE-FIELD-001.md) | 敏感字段种类不存在 |
+| [CAGE-FIELD-002](CAGE-FIELD-002.md) | 引用目标为空 |
+| [CAGE-FIELD-003](CAGE-FIELD-003.md) | 字段不是字段原语 |
+| [CAGE-FIELD-004](CAGE-FIELD-004.md) | 覆盖系统保留列 |
+
+## 关系字段
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-REL-001](CAGE-REL-001.md) | 关系字段声明无效 |
+
+## 生成一致性
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-GEN-001](CAGE-GEN-001.md) | 契约等生成结果过期 |
+| [CAGE-GEN-002](CAGE-GEN-002.md) | 声明结构没有对应迁移 |
+
+## 角色授权与防提权
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-GRANT-001](CAGE-GRANT-001.md) | 授予超出自己的能力或额度 |
+| [CAGE-GRANT-002](CAGE-GRANT-002.md) | 授予超出自己的数据范围 |
+| [CAGE-GRANT-003](CAGE-GRANT-003.md) | 能力不在代码目录中 |
+
+## 影响分析
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-IMPACT-001](CAGE-IMPACT-001.md) | 影响分析没有可用基线 |
+
+## 账号初始化
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-INIT-001](CAGE-INIT-001.md) | 管理员 URL 没有数据库名 |
+| [CAGE-INIT-002](CAGE-INIT-002.md) | 集群已有账号但缺少原凭证 |
+| [CAGE-INIT-003](CAGE-INIT-003.md) | 三种连接身份或目标不一致 |
+| [CAGE-INIT-004](CAGE-INIT-004.md) | 账号已创建但 .env 替换失败 |
+
+## 定时任务
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-JOB-001](CAGE-JOB-001.md) | 定时表达式不合法 |
+| [CAGE-JOB-002](CAGE-JOB-002.md) | 任务调用了未声明的命令 |
+| [CAGE-JOB-003](CAGE-JOB-003.md) | 任务读取了未声明的聚合 |
+
+## 通用 lint
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-LINT-001](CAGE-LINT-001.md) | lint 语法或规则错误 |
+
+## 结构迁移与安全层
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-MIG-001](CAGE-MIG-001.md) | 迁移事务执行失败 |
+| [CAGE-MIG-002](CAGE-MIG-002.md) | 安全层重建失败 |
+| [CAGE-MIG-005](CAGE-MIG-005.md) | 已执行迁移内容被修改 |
+
+## 名称
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-NAME-001](CAGE-NAME-001.md) | 聚合名必须大驼峰 |
+| [CAGE-NAME-002](CAGE-NAME-002.md) | 字段名必须小驼峰 |
+| [CAGE-NAME-003](CAGE-NAME-003.md) | 事件名必须大驼峰 |
+| [CAGE-NAME-004](CAGE-NAME-004.md) | 命令名必须小驼峰 |
+| [CAGE-NAME-005](CAGE-NAME-005.md) | 查询名必须小驼峰 |
+| [CAGE-NAME-006](CAGE-NAME-006.md) | 任务名必须小驼峰 |
+
+## 组织模型
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-ORG-001](CAGE-ORG-001.md) | 业务入口遗漏组织模型 |
+
+## 资源配对
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-PAIR-002](CAGE-PAIR-002.md) | 离开持有资源状态却没有释放 |
+
+## 安全查询
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-QUERY-001](CAGE-QUERY-001.md) | 查询必须选择一种实现 |
+| [CAGE-QUERY-002](CAGE-QUERY-002.md) | 自定义查询直接访问基表 |
+| [CAGE-QUERY-003](CAGE-QUERY-003.md) | 查询读取范围与声明不一致 |
+
+## 跨聚合反应
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-REACT-001](CAGE-REACT-001.md) | 反应目标与命令聚合不一致 |
+| [CAGE-REACT-002](CAGE-REACT-002.md) | 同事务反应链嵌套过深 |
+
+## 显式读依赖
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-READS-001](CAGE-READS-001.md) | handler 使用了未声明读依赖 |
+
+## 运行时注册表
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-REG-001](CAGE-REG-001.md) | 注册表缺少被引用声明 |
+| [CAGE-REG-002](CAGE-REG-002.md) | 聚合或查询注册重名 |
+| [CAGE-REG-003](CAGE-REG-003.md) | 命令能力点重复 |
+
+## 自动路由
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-ROUTE-001](CAGE-ROUTE-001.md) | 业务项目手写 HTTP 路由 |
+
+## 数据范围
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SCOPE-001](CAGE-SCOPE-001.md) | 范围组合子未知 |
+| [CAGE-SCOPE-002](CAGE-SCOPE-002.md) | 范围字段没有声明 |
+
+## 密钥边界
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SECRET-001](CAGE-SECRET-001.md) | 运行环境缺少密钥 |
+| [CAGE-SECRET-002](CAGE-SECRET-002.md) | 源码疑似包含密钥字面量 |
+
+## 敏感字段
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SENS-001](CAGE-SENS-001.md) | 敏感字段未标注就进入事件 |
+
+## SQL 参数化
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SQL-001](CAGE-SQL-001.md) | SQL 拼接用户值 |
+| [CAGE-SQL-002](CAGE-SQL-002.md) | sql.raw 接收动态表达式 |
+
+## 状态与可达性
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-STATE-001](CAGE-STATE-001.md) | 引用了未声明状态 |
+| [CAGE-STATE-002](CAGE-STATE-002.md) | 状态集合为空 |
+| [CAGE-STATE-003](CAGE-STATE-003.md) | 状态名称格式错误 |
+| [CAGE-STATE-004](CAGE-STATE-004.md) | 状态名称重复 |
+| [CAGE-STATE-005](CAGE-STATE-005.md) | 状态声明位置冲突 |
+| [CAGE-STATE-010](CAGE-STATE-010.md) | 状态不可达 |
+| [CAGE-STATE-011](CAGE-STATE-011.md) | 非终态没有后续操作 |
+
+## AI 托管区
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-SYNC-001](CAGE-SYNC-001.md) | AGENTS 托管区过期或标记损坏 |
+
+## 测试报告
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-TEST-001](CAGE-TEST-001.md) | 测试进程没有生成结果报告 |
+
+## 逃生口
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-UNSAFE-001](CAGE-UNSAFE-001.md) | 逃生口缺少原因或负责人 |
+
+## 升级
+
+| 诊断码 | 含义 |
+| --- | --- |
+| [CAGE-UPGRADE-001](CAGE-UPGRADE-001.md) | 升级版本或 codemod 有歧义 |
+
+## 历史流程
+
+[CAGE-MIG-003](CAGE-MIG-003.md)、[CAGE-MIG-004](CAGE-MIG-004.md) 属于旧版初始化流程，当前使用 init + migrate；保留页面供历史诊断。
+
+手册随创建项目时的 CLI 版本分发。cage sync 仅更新 AGENTS 托管区；升级后需要按该版本的资料核对差异。
+
+框架维护者：修改 scripts/error-catalog.ts 后运行 pnpm docs:errors；不要只手改生成的逐码页面。

package/templates/app/docs/errors/runtime.md

@@ -0,0 +1,50 @@
+# HTTP 运行时错误与业务码
+
+[返回错误码册](README.md) · [排错方法](../ai/troubleshooting.md)
+
+框架诊断分三层：`CAGE-APPR-007` 等内部/工具码、HTTP 响应的通用 `code`、业务拒绝的 `domainCode`。同一次失败可以同时涉及几层；例如审批人配置问题出现在 worker 死信，前端提交此前可能已成功。
+
+## 接口错误
+
+| code | HTTP | 含义 | 业务前端/AI 应怎么做 |
+| --- | --- | --- | --- |
+| UNAUTHENTICATED | 401 | 会话不存在/失效或认证未通过 | 重新登录；回调先核对验签，不跳过认证 |
+| FORBIDDEN | 403 | 无能力、身份不允许，或 CSRF 拒绝等 | 看 detail 与当前授权；不能只因有按钮就认为有权。客户端会刷新过期 CSRF 令牌重试 |
+| NOT_FOUND | 404 | 记录不存在或超出范围 | 用当前用户检查 id/租户/范围，不泄漏范围外数据 |
+| INVALID_INPUT | 400 | Zod/协议输入错误、外键或检查约束等 | 按输入 schema 修正字段和格式，不直接扩大 schema |
+| INVALID_TRANSITION | 409 | 当前状态不允许该命令 | 刷新记录，按真实生命周期显示允许操作 |
+| CONSTRAINT_VIOLATED | 403 | 职责分离、额度、二次认证、防提权等拒绝 | 看约束原因，调整业务操作或由有权管理员配置；不删除约束 |
+| INVARIANT_VIOLATED | 409 | 命令结果不满足聚合不变量 | 修正输入或 handler，保持合法结果 |
+| CONFLICT | 409 | 版本、唯一性、数据库串行化/死锁等冲突 | 看 detail、重新读取再决定是否重试；不要盲目重复创建 |
+| DOMAIN_ERROR | 422 | handler 返回 fail | 读取 domainCode，展示业务文案和必要 detail |
+| RATE_LIMITED | 429 | 请求超过限流 | 按提示等待，避免页面无限重试 |
+| INTERNAL | 500 | 未分类内部错误 | 用 requestId 查服务端日志，向用户显示通用失败；不返回堆栈/密钥 |
+| NETWORK（仅客户端） | 0 | 请求未取得可用网络响应 | 检查连接与服务状态；保留同次操作幂等键，避免误认为服务端一定未执行 |
+
+网络失败和超时不证明服务端事务未提交。通用重试与人工重试都需考虑幂等与当前状态，不能先写 SQL 回滚业务再重发。
+
+## 业务码用法
+
+领域 handler 返回：
+
+```ts
+return fail('STOCK_SHORT', ['A-01']);
+```
+
+HTTP 响应形状为：
+
+```json
+{ "code": "DOMAIN_ERROR", "domainCode": "STOCK_SHORT", "detail": ["A-01"] }
+```
+
+客户端方法返回可区分结果，先判断 `result.ok`；失败时看 `result.code`，业务错误再看 `result.domainCode`。不要假设 code 直接等于 STOCK_SHORT，也不要把所有 403 当作“请重新登录”。
+
+业务码由项目定义并在页面翻译；字段 schema、不变量、硬约束和业务 fail 各有职责。正常业务拒绝不要伪装成普通异常导致 INTERNAL。
+
+## 异步任务与死信
+
+导入/导出 HTTP 202 只表示任务已接受，任务详情另有 queued/processing/retrying/completed/failed/expired。检查 task.errorCode/result 和导入报告，完成后才提供成功提示或下载。
+
+outbox 消费失败可能重试或进死信；修复内层错误后重放，查看同一聚合后续消息是否继续。使用管理接口处理，不直接更新 sys.outbox 或业务状态。
+
+当前实现定义位于框架源码 `packages/kernel/src/errors.ts` 与客户端包；实际 API 响应为准。生成契约会列出命令可能的通用错误与能抽取到的业务码，但不代表任何错误都已被实际测试覆盖。

package/templates/app/package.json

@@ -5,18 +5,15 @@
   "packageManager": "pnpm@10.14.0",
   "scripts": {
     "dev": "cage dev",
-    "db:setup": "cage db setup",
-    "db:up": "cage db up",
-    "db:down": "cage db down",
-    "db:status": "cage db status",
+    "migrate": "cage migrate",
     "verify": "cage verify",
     "gen": "cage gen",
     "build:app": "pnpm --filter @app/domain build && pnpm --filter @app/api build && pnpm --filter @app/web build"
   },
   "devDependencies": {
-    "@yss123/cage-cli": "0.1.0",
-    "@yss123/cage-testkit": "0.1.0",
-    "@yss123/cage-lint": "0.1.0",
+    "@yss123/cage-cli": "0.2.0",
+    "@yss123/cage-testkit": "0.2.0",
+    "@yss123/cage-lint": "0.2.0",
     "@types/node": "^24.3.0",
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",

package/templates/app/packages/contracts/package.json

@@ -10,7 +10,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@yss123/cage-client": "0.1.0",
+    "@yss123/cage-client": "0.2.0",
     "zod": "^4.1.5"
   }
 }