@yss123/cage-cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,47 @@
+# CAGE-BUDGET-003：新增未经基线认可的 unsafe
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：budget / verify。
+
+本次图中的 unsafe 数超过给定基线；没有基线时允许值为零。
+
+## 修复步骤
+
+1. 优先移除逃生口；确需使用时写明 reason/owner，评审后更新受审基线。不要用刚改后的图冒充旧基线。
+
+## 正例
+
+```text
+unsafe({ reason: '受审的历史修复', owner: '负责人' }, action) 并使用受审基线
+```
+
+## 反例
+
+```text
+随手调用 unsafe，再覆盖基线隐藏增长
+```
+
+## 修复后验证
+
+重跑 cage budget；有 unsafe 基线时使用真实受审基线。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/budget.ts:58`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    findings.push({
+      code: 'CAGE-BUDGET-003',
+      reason: `unsafe 从 ${allowance} 增加到 ${graph.unsafeCount}`,
+      fix: '移除新增逃生口，或在评审完成后更新受审基线',
+    });
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CMD-002：已有记录命令缺少 id
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+非新建命令的对象输入 schema 没有 id，无法确定要加载哪条记录。
+
+## 修复步骤
+
+1. 在 input 添加 UUID id；没有其他输入时可省略 input 使用默认 idOnly。
+
+## 正例
+
+```text
+input: z.object({ id: z.string().uuid(), title: z.string() })
+```
+
+## 反例
+
+```text
+input: z.object({ title: z.string() }) // from 不是 new
+```
+
+## 修复后验证
+
+重跑 cage check、gen 和相关命令测试，检查生成输入/方法签名。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/command.ts:142`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (from !== 'new' && input instanceof z.ZodObject && !('id' in input.shape)) {
+    throw declError('CAGE-CMD-002', `${agg.name} 的非新建命令输入必须包含 id`);
+  }
+  if (def.name !== undefined && !/^[a-z][A-Za-z0-9]*$/.test(def.name)) {
+    throw declError('CAGE-NAME-004', `命令名 ${def.name} 必须是小驼峰`);
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CMD-003：新建命令没有目标状态
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+from 为 new 时使用 to: null，新记录没有可保留的当前状态。
+
+## 修复步骤
+
+1. 新建必须指向已声明状态；to: null 只用于已有记录的字段更新，仍检查 from、身份、版本并写审计。
+
+## 正例
+
+```text
+from: 'new', to: 'draft' // 或已有记录 from: 'approved', to: null
+```
+
+## 反例
+
+```text
+from: 'new', to: null
+```
+
+## 修复后验证
+
+重跑 cage check、gen 和相关命令测试，检查生成输入/方法签名。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/command.ts:135`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (from === 'new' && def.to === null) {
+    throw declError('CAGE-CMD-003', `${agg.name} 的新建命令必须指定目标状态，不能使用 to: null`);
+  }
+  if (def.to !== null && !hasStates(agg, def.to as string)) {
+    throw declError('CAGE-STATE-001', `${agg.name} 的命令 to 是未声明的状态：${String(def.to)}`);
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-001：连接器名称格式错误
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+connector 的名称不是小写字母开头的小写短横线格式。
+
+## 修复步骤
+
+1. 采用稳定的英文连接器标识，中文名称写 description 或图谱 label。
+
+## 正例
+
+```text
+connector('finance-erp', definition)
+```
+
+## 反例
+
+```text
+connector('FinanceERP', definition)
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/primitives.ts:56`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+export function connector<Ops extends Record<string, OpDef<any, any>>>(name: string, def: ConnectorDef<Ops>): Connector<Ops> {
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) throw declError('CAGE-CONN-001', `连接器名 ${name} 必须是小写短横线`);
+  for (const h of Object.values(def.hosts)) {
+    if (h && /[/:\s]/.test(h.replace(/:\d+$/, ''))) throw declError('CAGE-CONN-003', `地址白名单只能写主机名（可带端口）：${h}`);
+  }
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-002：外部操作路径格式错误
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+op.path 没有以斜线开头。
+
+## 修复步骤
+
+1. host 在连接器白名单中配置，操作 path 只写从 / 开始的相对接口路径。
+
+## 正例
+
+```text
+path: '/api/purchase-orders'
+```
+
+## 反例
+
+```text
+path: 'https://erp.example.com/api/orders'
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/primitives.ts:29`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+export function op<Req extends z.ZodObject<any>, Res extends z.ZodType>(def: OpDef<Req, Res>): OpDef<Req, Res> {
+  if (!def.path.startsWith('/')) throw declError('CAGE-CONN-002', `操作路径 ${def.path} 必须以 / 开头`);
+  return def;
+}
+
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-003：地址白名单包含协议或路径
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+connector.hosts 中包含协议、路径或空白，而不是主机名（可带端口）。
+
+## 修复步骤
+
+1. 将协议和路径从 host 移除；实际路径写 op.path，环境 host 按声明配置。
+
+## 正例
+
+```text
+hosts: { test: 'erp-sandbox.example.com:8443', prod: 'erp.example.com' }
+```
+
+## 反例
+
+```text
+hosts: { prod: 'https://erp.example.com/api' }
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/primitives.ts:58`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  for (const h of Object.values(def.hosts)) {
+    if (h && /[/:\s]/.test(h.replace(/:\d+$/, ''))) throw declError('CAGE-CONN-003', `地址白名单只能写主机名（可带端口）：${h}`);
+  }
+  const c: any = {
+    [CONNECTOR]: true,
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-004：只读操作被用作出站写映射
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+outbound 绑定了 effect 为 read 的操作。
+
+## 修复步骤
+
+1. 按真实副作用给操作声明 write/retryableWrite；有可重试写入时设计远端幂等协议，不能只改标签。
+
+## 正例
+
+```text
+effect: 'retryableWrite' // 第三方实际支持幂等写入
+```
+
+## 反例
+
+```text
+effect: 'read' // 却在业务事件后创建远端订单
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/primitives.ts:99`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+): Outbound<E, O> {
+  if (operation.effect === 'read') throw declError('CAGE-CONN-004', '只读操作不能用于出站映射');
+  const o: any = {
+    [OUTBOUND]: true,
+    event: ev,
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-005：入站事件名称格式错误
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+inbound 的事件名不是小驼峰格式。
+
+## 修复步骤
+
+1. 使用小驼峰稳定标识，展示文案另设中文。
+
+## 正例
+
+```text
+inbound(erp, 'goodsReceived', definition)
+```
+
+## 反例
+
+```text
+inbound(erp, 'GoodsReceived', definition)
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/primitives.ts:153`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+): Inbound<P> {
+  if (!/^[a-z][A-Za-z0-9]*$/.test(eventName)) throw declError('CAGE-CONN-005', `入站事件名 ${eventName} 必须是小驼峰`);
+  if (!def.command.invokedBy.includes('external') && !def.command.invokedBy.includes('user')) {
+    throw declError('CAGE-CONN-006', `入站回调调用的命令必须声明 invokedBy: 'external'`);
+  }
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-006：回调命令未允许 external
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+入站回调指向的命令没有声明 external 调用身份。
+
+## 修复步骤
+
+1. 为专用回调命令声明 external；验签和输入校验之后才能调用，不把内部命令暴露为普通用户接口。
+
+## 正例
+
+```text
+invokedBy: 'external'
+```
+
+## 反例
+
+```text
+invokedBy: 'user' // 作为 inbound.command
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/primitives.ts:155`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (!def.command.invokedBy.includes('external') && !def.command.invokedBy.includes('user')) {
+    throw declError('CAGE-CONN-006', `入站回调调用的命令必须声明 invokedBy: 'external'`);
+  }
+  return Object.freeze({ [INBOUND]: true as const, connector: conn, event: eventName, ...def });
+}
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-007：当前环境没有连接器地址
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+非 fake 环境中，连接器 hosts 找不到当前 stage 对应的主机。
+
+## 修复步骤
+
+1. 检查 CAGE_STAGE 与 hosts.test/prod。fake 不需要真实主机；真实联调必须配置正确环境及密钥。
+
+## 正例
+
+```text
+CAGE_STAGE=test，hosts.test 指向沙箱主机
+```
+
+## 反例
+
+```text
+只配置 prod 却用 test 环境启动，或把 fake 成功称作真实联调通过
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:131`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const host = o.connector.hosts[st];
+  if (!host) throw new ConnectorError(`[CAGE-CONN-007] 连接器 ${o.connector.name} 没有 ${st} 环境的地址`, null, false);
+  const token = o.connector.secret ? await secrets.get(o.connector.secret) : undefined;
+  await take(o.connector);
+  const url = new URL(o.path, `https://${host}`);
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-008：外部请求发生网络错误或超时
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+fetch 在收到有效 HTTP 响应前失败，例如 DNS、网络、TLS 或 timeout。
+
+## 修复步骤
+
+1. 核对脱敏后的主机、网络、代理和 timeoutMs；排除临时故障后由 worker 重试，不能在 handler 内加网络重试。
+
+## 正例
+
+```text
+使用同步记录定位失败阶段；保持同一业务幂等键重试
+```
+
+## 反例
+
+```text
+每次重试换远端幂等键，导致重复写入
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:151`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    await recordCall(opts.kernel, o, key, opts.tenantId ?? null, 'failed', null, body, undefined, String(e));
+    throw new ConnectorError(`[CAGE-CONN-008] 调用 ${o.connector.name}.${o.name} 失败：${String(e)}`, null, true);
+  }
+  const text = await res.text();
+  let json: unknown = null;
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-009：外部服务返回非成功状态
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+连接器取得 HTTP 响应，但状态码不是成功码。
+
+## 修复步骤
+
+1. 看同步记录的状态与脱敏响应；核对鉴权、字段及限流。可重试性还受 effect 和状态码控制，不是所有 4xx 都会重试。
+
+## 正例
+
+```text
+修正 401 的运行环境密钥，确认后重放失败事件
+```
+
+## 反例
+
+```text
+把所有 4xx 改成成功，或无限重试无效请求
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:163`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    const retryable = o.effect === 'retryableWrite' || o.effect === 'read' ? res.status >= 500 || res.status === 429 : false;
+    throw new ConnectorError(`[CAGE-CONN-009] ${o.connector.name}.${o.name} 返回 ${res.status}`, res.status, retryable);
+  }
+  const parsed = o.response.safeParse(json);
+  if (!parsed.success) {
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-010：外部响应不符合 schema
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+外部返回成功 HTTP 状态，但内容不满足声明的 response schema。
+
+## 修复步骤
+
+1. 对照真实协议、响应样例和声明，修正一方；不要用 any 或空对象吞掉未知格式。该错误按永久失败处理。
+
+## 正例
+
+```text
+response: z.object({ erpNo: z.string() }) 与真实成功协议一致
+```
+
+## 反例
+
+```text
+后端返回 { orderNo: 123 }，却继续读取 res.erpNo
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:168`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    await recordCall(opts.kernel, o, key, opts.tenantId ?? null, 'failed', res.status, body, json, '响应格式不符合声明');
+    throw new ConnectorError(`[CAGE-CONN-010] ${o.connector.name}.${o.name} 的响应格式与声明不符`, res.status, false);
+  }
+  await recordCall(opts.kernel, o, key, opts.tenantId ?? null, 'ok', res.status, body, parsed.data);
+  return parsed.data;
+```

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

@@ -0,0 +1,47 @@
+# CAGE-CONN-011：出站永久失败进入死信
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+出站消费者将不可重试的 ConnectorError 包装为永久错误；真正原因是内层错误码。
+
+## 修复步骤
+
+1. 先按内层 CAGE-CONN-007/009/010 等修正配置/协议，再重放死信；检查远端是否已完成写入并复用业务幂等键。
+
+## 正例
+
+```text
+修复响应 schema，核对远端幂等结果，再重放指定 outboxId
+```
+
+## 反例
+
+```text
+只重启 worker，希望永久错误自动恢复或直接删 outbox
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:190`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+          // 不可重试：标成永久错误，直接进死信
+          throw Object.assign(new Error(`[CAGE-CONN-011] ${e.message}`), { permanent: true });
+        }
+        throw e;
+      }
+```