@yss123/cage-cli 0.2.0 → 0.3.0

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

@@ -34,7 +34,7 @@
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/budget.ts:45`
+- `packages/cli/src/budget.ts:85`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,7 +34,7 @@
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/budget.ts:51`
+- `packages/cli/src/budget.ts:91`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,7 +34,7 @@ unsafe({ reason: '受审的历史修复', owner: '负责人' }, action) 并使
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/budget.ts:58`
+- `packages/cli/src/budget.ts:98`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,7 +34,7 @@ input: z.object({ title: z.string() }) // from 不是 new
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/command.ts:142`
+- `packages/kernel/src/primitives/command.ts:240`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,7 +34,7 @@ from: 'new', to: null
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/command.ts:135`
+- `packages/kernel/src/primitives/command.ts:233`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,14 +34,14 @@ connector('FinanceERP', definition)
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/connectors/src/primitives.ts:56`
+- `packages/connectors/src/primitives.ts:63`
 
 实现片段（位置随框架版本更新）：
 
 ```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}`);
+  if (def.timeoutMs !== undefined && (!Number.isSafeInteger(def.timeoutMs) || def.timeoutMs <= 0 || def.timeoutMs > 300_000)) {
+    throw declError('CAGE-CONN-015', '连接器 timeoutMs 必须是 1～300000 毫秒的整数');
   }
 ```

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

@@ -34,7 +34,7 @@ path: 'https://erp.example.com/api/orders'
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/connectors/src/primitives.ts:29`
+- `packages/connectors/src/primitives.ts:31`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,7 +34,7 @@ hosts: { prod: 'https://erp.example.com/api' }
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/connectors/src/primitives.ts:58`
+- `packages/connectors/src/primitives.ts:71`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,7 +34,7 @@ effect: 'read' // 却在业务事件后创建远端订单
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/connectors/src/primitives.ts:99`
+- `packages/connectors/src/primitives.ts:116`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,7 +34,7 @@ inbound(erp, 'GoodsReceived', definition)
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/connectors/src/primitives.ts:153`
+- `packages/connectors/src/primitives.ts:176`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,7 +34,7 @@ invokedBy: 'user' // 作为 inbound.command
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/connectors/src/primitives.ts:155`
+- `packages/connectors/src/primitives.ts:178`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,14 +34,14 @@ CAGE_STAGE=test，hosts.test 指向沙箱主机
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/connectors/src/runtime.ts:131`
+- `packages/connectors/src/runtime.ts:168`
 
 实现片段（位置随框架版本更新）：
 
 ```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}`);
+      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, signal);
+      const url = new URL(o.path, `https://${host}`);
 ```

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

@@ -34,14 +34,14 @@ fetch 在收到有效 HTTP 响应前失败，例如 DNS、网络、TLS 或 timeo
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/connectors/src/runtime.ts:151`
+- `packages/connectors/src/runtime.ts:192`
 
 实现片段（位置随框架版本更新）：
 
 ```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);
+  } catch (e) {
+    const err = e instanceof ConnectorError ? e : new ConnectorError(`[CAGE-CONN-008] 调用 ${o.connector.name}.${o.name} 失败：${(e as Error)?.name ?? 'Error'}`, httpStatus, o.effect !== 'write', 'unknown');
+    await recordCall(opts.kernel, o, key, opts.tenantId ?? null, 'failed', httpStatus, body, undefined, err.message);
+    throw err;
   }
-  const text = await res.text();
-  let json: unknown = null;
 ```

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

@@ -34,14 +34,14 @@
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/connectors/src/runtime.ts:163`
+- `packages/connectors/src/runtime.ts:183`
 
 实现片段（位置随框架版本更新）：
 
 ```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) {
+      try { json = text ? JSON.parse(text) : null; } catch { /* 无效响应由下方 schema 统一诊断，不记录原文。 */ }
+      if (!res.ok) throw new ConnectorError(`[CAGE-CONN-009] ${o.connector.name}.${o.name} 返回 ${res.status}`, res.status,
+        o.effect !== 'write' && (res.status >= 500 || res.status === 429), res.status >= 500 ? 'unknown' : 'rejected');
+      const result = o.response.safeParse(json);
+      if (!result.success) throw new ConnectorError(`[CAGE-CONN-010] ${o.connector.name}.${o.name} 的响应格式与声明不符`, res.status, false, 'unknown');
 ```

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

@@ -34,14 +34,14 @@ response: z.object({ erpNo: z.string() }) 与真实成功协议一致
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/connectors/src/runtime.ts:168`
+- `packages/connectors/src/runtime.ts:186`
 
 实现片段（位置随框架版本更新）：
 
 ```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;
+      const result = o.response.safeParse(json);
+      if (!result.success) throw new ConnectorError(`[CAGE-CONN-010] ${o.connector.name}.${o.name} 的响应格式与声明不符`, res.status, false, 'unknown');
+      return result.data;
+    });
+    await recordCall(opts.kernel, o, key, opts.tenantId ?? null, 'ok', httpStatus, body, parsed);
 ```

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

@@ -34,7 +34,7 @@
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/connectors/src/runtime.ts:190`
+- `packages/connectors/src/runtime.ts:283`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,7 +34,7 @@ recordErpNo 被 pushToErp.onSuccess.command 引用
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/rules.ts:157`
+- `packages/cli/src/rules.ts:197`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -0,0 +1,49 @@
+# CAGE-CONN-013：出站幂等键无效或请求冲突
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+幂等键不是非空字符串，或同租户、连接器、操作、幂等键已经对应另一份请求。
+
+## 修复步骤
+
+1. 使用同一业务操作的稳定声明键；重试保持键和请求内容不变。
+2. 新业务操作使用新键，不能覆盖已有执行记录。远端收到的键还包含租户隔离前缀。
+
+## 正例
+
+```text
+idempotencyKey: payload => payload.id // 同业务操作的稳定键
+```
+
+## 反例
+
+```text
+复用旧键发送不同金额，或每次重试生成随机键
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:219`
+- `packages/connectors/src/runtime.ts:244`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const key = ob.idempotencyKey(row.payload as any);
+  if (!key || typeof key !== 'string') throw new ConnectorError('[CAGE-CONN-013] 出站幂等键必须为非空字符串', null, false);
+  const requestHash = createHash('sha256').update(canonical(body)).digest('hex');
+  const identity = { tenant_id: row.tenant_id, connector: ob.op.connector.name, operation: ob.op.name, idempotency_key: key };
+  const locate = (db: typeof k.app) => db.selectFrom('sys.connector_execution').selectAll()
+```

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

@@ -0,0 +1,48 @@
+# CAGE-CONN-014：不可重试外部写入结果未知
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+不可安全重试的外部写入超时或中断，无法确认远端是否已经生效。
+
+## 修复步骤
+
+1. 先凭远端幂等键和同步记录人工核对结果，再选择连接器专用的受控恢复或业务补偿。当前没有通用回执确认或解除 unknown 的入口，普通死信重放不会解除。
+2. 需要自动恢复时先让远端提供可靠幂等协议，再使用 retryableWrite；不盲目重放未知结果写入。
+
+## 正例
+
+```text
+核对远端已生成凭证，再通过受控命令落实本地结果
+```
+
+## 反例
+
+```text
+超时等于远端没执行，直接再次扣款
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/runtime.ts:245`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (claim.kind === 'conflict') throw new ConnectorError(`[CAGE-CONN-013] ${consumer} 同一幂等键对应不同请求；禁止覆盖已有执行`, null, false);
+  if (claim.kind === 'unknown') throw new ConnectorError(`[CAGE-CONN-014] ${consumer} 的不可重试调用结果未知；人工核对远端后再恢复`, null, false, 'unknown');
+  if (claim.kind === 'busy') throw new ConnectorError(`${consumer} 的调用仍由其他执行者持有`, null, true);
+  if (claim.kind === 'receipt') return { skipped: false, response: ob.op.response.parse(claim.response) };
+  let response: unknown;
+```

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

@@ -0,0 +1,49 @@
+# CAGE-CONN-015：连接器超时或限流参数无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明、图规则或 worker。
+
+timeoutMs 不是 1 至 300000 的整数，或 rateLimit.perSecond 不是有限正数。
+
+## 修复步骤
+
+1. 按第三方服务的实际边界设置有界超时和每秒限额。
+2. 首阶段额度在单进程内生效；多进程共享限额需要额外设计，不能按本地额度推断全局限流。
+
+## 正例
+
+```text
+timeoutMs: 10000, rateLimit: { perSecond: 5 }
+```
+
+## 反例
+
+```text
+timeoutMs: Infinity 或 rateLimit: { perSecond: 0 }
+```
+
+## 修复后验证
+
+先 cage check；涉及网络时检查同步记录、外部幂等结果与成功回写。fake 与真实联调分别报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/connectors/src/primitives.ts:65`
+- `packages/connectors/src/primitives.ts:68`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (def.timeoutMs !== undefined && (!Number.isSafeInteger(def.timeoutMs) || def.timeoutMs <= 0 || def.timeoutMs > 300_000)) {
+    throw declError('CAGE-CONN-015', '连接器 timeoutMs 必须是 1～300000 毫秒的整数');
+  }
+  if (def.rateLimit && (!Number.isFinite(def.rateLimit.perSecond) || def.rateLimit.perSecond <= 0)) {
+    throw declError('CAGE-CONN-015', '连接器 rateLimit.perSecond 必须为有限正数');
+```

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

@@ -35,18 +35,19 @@ cage create . 覆盖当前已有业务项目
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/create-prompt.ts:12`
 - `packages/cli/src/create-prompt.ts:17`
-- `packages/cli/src/create.ts:20`
-- `packages/cli/src/create.ts:22`
-- `packages/cli/src/create.ts:29`
+- `packages/cli/src/create-prompt.ts:24`
+- `packages/cli/src/create-prompt.ts:29`
+- `packages/cli/src/create.ts:45`
+- `packages/cli/src/create.ts:47`
+- `packages/cli/src/create.ts:54`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-  if (template !== undefined && !isAppTemplate(template))
-    throw new Error('[CAGE-CREATE-001] --template 只能是 blank 或 purchase');
-
-  // 管道和 CI 没有可操作的终端，不隐式选择业务模板，也不让安装任务挂在提示上。
-  if ((!target || !template) && (!process.stdin.isTTY || !process.stdout.isTTY))
+ * @returns 完整创建选择；用户取消返回 null，由入口转换为取消退出码。
+ * @throws 非交互缺项或模板名无效时抛出 CAGE-CREATE-001。
+ */
+export async function chooseApp(
+  target?: string,
 ```

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

@@ -34,8 +34,8 @@ export function build() { return aggregate('Order', definition); }
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/static-check.ts:188`
-- `packages/cli/src/static-check.ts:195`
+- `packages/cli/src/static-check.ts:232`
+- `packages/cli/src/static-check.ts:239`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,14 +34,15 @@ export * from './purchase-order.js'; // index.ts
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/static-check.ts:254`
+- `packages/cli/src/doctor.ts:96`
+- `packages/cli/src/static-check.ts:304`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-    .map((s) => ({
-      code: 'CAGE-DECL-002',
-      at: `${s.file}:${s.line}`,
-      reason: `声明 ${s.exportName} 没有从 domain 入口导出，内核和抽取器都看不到它`,
-      fix: `从所属模块 index.ts 导出 ${s.exportName}，再由 domain 的统一入口转导出；源文件 ${s.file}`,
+    exports: result.registration?.find(entry => entry.name === site.exportName && entry.file === site.file),
+    registered: !result.findings.some(f => f.code === 'CAGE-DECL-002' && f.at === `${site.file}:${site.line}`),
+    nodes: result.graph?.nodes.filter(n => n.file === site.file && n.line === site.line).map(n => ({ key: `${n.kind}:${n.id}`, attrs: n.kind === 'reaction' ? { event: n.attrs.event, command: n.attrs.command, tx: n.attrs.tx, order: n.attrs.order, collection: n.attrs.collection } : undefined })) ?? [] }));
+  const verifyFile = abs(cfg, '.cage/verify.json');
+  return { schemaVersion: 1, cliVersion: VERSION, observedAt, project: cfg.name, registryHash, sourceHash, registryHashSource: compiledExists ? compiledEntry : /\.js$/.test(cfg.domain) ? cfg.domain : null, ok: checks.every(c => c.status !== 'fail'), complete: checks.every(c => c.status !== 'unknown'), checks, findings, registration,
 ```

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

@@ -34,7 +34,7 @@ const OrderSubmitted = event('OrderSubmitted', fields)
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/static-check.ts:207`
+- `packages/cli/src/static-check.ts:251`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,7 +34,7 @@ note.ts 与 order.ts 都 export const create，再 export *
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/static-check.ts:239`
+- `packages/cli/src/static-check.ts:283`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,8 +34,8 @@ import pg from 'pg'; // domain 直接操作数据库
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/static-check.ts:144`
-- `packages/lint/dependency-cruiser.cjs:8`
+- `packages/cli/src/static-check.ts:188`
+- `packages/lint/dependency-cruiser.cjs:13`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,7 +34,7 @@ packages/adapters 依赖数据库访问包并可能直接写业务表。
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/lint/dependency-cruiser.cjs:17`
+- `packages/lint/dependency-cruiser.cjs:22`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,7 +34,7 @@ import { approve } from '@app/domain'
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/lint/dependency-cruiser.cjs:24`
+- `packages/lint/dependency-cruiser.cjs:29`
 
 实现片段（位置随框架版本更新）：
 
@@ -42,6 +42,6 @@ import { approve } from '@app/domain'
       severity: 'error',
       comment: '[CAGE-DEP-003] 前端只能依赖 @app/contracts',
       from: { path: '^apps/web' },
-      to: { path: '^packages/domain|node_modules/@yss123/cage-(kernel|http|admin|connectors|approval|testkit)/' },
+      to: { path: '^packages/domain|node_modules/@yss123/cage-(kernel|http|files|admin|connectors|approval|testkit|ai|ontology)/' },
     },
 ```

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

@@ -34,7 +34,7 @@ handler 里 await fetch(...) 或动态 import 数据库模块
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/static-check.ts:155`
+- `packages/cli/src/static-check.ts:199`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -34,7 +34,7 @@ domain 从 '@app/contracts' 导入自己生成的快照
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/lint/dependency-cruiser.cjs:31`
+- `packages/lint/dependency-cruiser.cjs:36`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -0,0 +1,53 @@
+# CAGE-DIAG-001：运行诊断输入或连接失败
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：doctor / timeline / explain。
+
+诊断 URL、Cookie 文件、输入文件或筛选项无效，或受控诊断请求无法完成。
+
+## 修复步骤
+
+1. 使用不含用户信息、查询参数或片段的 HTTP(S) 地址；通过 --cookie-file 提供受控会话。
+2. 按 reason 检查目标接口、权限、输入和服务状态；unknown 不能视为通过。不要在 URL 中携带令牌。
+
+## 正例
+
+```text
+cage doctor --runtime-url http://127.0.0.1:3000 --cookie-file .cage/diagnostic-cookie.txt
+```
+
+## 反例
+
+```text
+把密码或 Cookie 写进 --runtime-url 的查询参数
+```
+
+## 修复后验证
+
+核对诊断输入、受控会话和目标服务，再重新获取实际运行证据；未知不当作通过。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/main.ts:150`
+- `packages/cli/src/runtime-diagnostics.ts:23`
+- `packages/cli/src/runtime-diagnostics.ts:26`
+- `packages/cli/src/runtime-diagnostics.ts:27`
+- `packages/cli/src/runtime-diagnostics.ts:29`
+- `packages/cli/src/runtime-diagnostics.ts:32`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (command === 'timeline' || command === 'explain') {
+    if (command === 'explain' && (!target || !o['input-file'])) throw new Error('[CAGE-DIAG-001] 使用 cage explain <命令> --input-file <JSON文件> --runtime-url <地址> --cookie-file <文件>');
+    const body = command === 'explain' ? { command: target, input: JSON.parse(readFileSync(abs(cfg, o['input-file']!), 'utf8')), userId: o['user-id'] } : undefined;
+    const result = await (await import('./runtime-diagnostics.js')).runtimeDiagnostic(cfg, { runtimeUrl: o['runtime-url'], cookieFile: o['cookie-file'] }, `/api/sys/diagnostics/${command === 'timeline' ? 'timeline' : 'authorization'}`, {
+      query: command === 'timeline' ? { requestId: o['request-id'], outboxId: o['outbox-id'], aggregate: o.aggregate, aggregateId: o['aggregate-id'] } : undefined, body,
+```

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

@@ -34,8 +34,8 @@
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/worker/outbox.ts:128`
-- `packages/kernel/src/worker/outbox.ts:139`
+- `packages/kernel/src/worker/outbox.ts:169`
+- `packages/kernel/src/worker/outbox.ts:181`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -36,10 +36,10 @@ API、worker、迁移或初始化没有取得所需的数据库连接。
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/init.ts:74`
-- `packages/cli/src/migrate.ts:22`
-- `packages/kernel/src/db/connect.ts:74`
-- `packages/kernel/src/kernel.ts:100`
+- `packages/cli/src/init.ts:94`
+- `packages/cli/src/migrate.ts:39`
+- `packages/kernel/src/db/connect.ts:91`
+- `packages/kernel/src/kernel.ts:146`
 
 实现片段（位置随框架版本更新）：