@yss123/cage-cli 0.2.0 → 0.3.1

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

@@ -1,4 +1,4 @@
-# CAGE-APPR-001：可路由字段不存在
+# CAGE-APPR-001：审批字段声明无效
 
 [返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
 
@@ -8,11 +8,12 @@
 
 阶段：声明、图规则或 worker。
 
-approval.routable 引用了所属聚合没有声明的字段。
+approval.routable 引用了不存在字段，或 approver.field 指向未声明、隐藏、未进入 routable 的字段。
 
 ## 修复步骤
 
-1. 先在聚合声明实际字段，再将需要给审批路由的字段放入 routable；不要把任意输入直接交给流程。
+1. 先在聚合声明实际字段，再将需要给审批路由的非隐藏字段放入 routable；不要把任意输入直接交给流程。
+2. 字段选人值应为 UUID 或非空 UUID 数组，见 docs/ai/approvals.md；字段公开并不自动授予审批能力。
 
 ## 正例
 
@@ -34,14 +35,17 @@ routable: ['managerName'] // 聚合没有该字段
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/flow.ts:134`
+- `packages/approval/src/route.ts:215`
+- `packages/approval/src/route.ts:220`
+- `packages/approval/src/route.ts:229`
+- `packages/kernel/src/primitives/flow.ts:245`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-  for (const f of def.routable) {
-    if (!(f in agg.fields)) throw declError('CAGE-APPR-001', `可路由字段 ${agg.name}.${f} 不存在`);
-  }
-  for (const c of [def.onApproved, def.onRejected]) {
-    if (c.agg !== agg) throw declError('CAGE-APPR-002', `审批结论命令必须属于 ${agg.name}`);
+      if (reminders && (!routeBinding?.routable.includes(reminders.requesterField) || !routeBinding.agg.fields[reminders.requesterField] || routeBinding.agg.fields[reminders.requesterField].isHidden))
+        throw declError('CAGE-APPR-001', `申请人字段 ${reminders.requesterField} 必须存在、可公开且进入 routable`);
+      for (const node of declaredSteps) {
+        const selector = node.kind === 'ai' ? node.handoff : node.approver;
+        // 新字段选择器必须能从 routable 快照取值；不追溯改变历史部门选人的声明校验行为。
 ```

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

@@ -34,12 +34,12 @@ PurchaseOrder 的审批绑定使用 approvePurchaseOrder 命令
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/kernel/src/primitives/flow.ts:137`
+- `packages/kernel/src/primitives/flow.ts:248`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-  for (const c of [def.onApproved, def.onRejected]) {
+  for (const c of [def.onApproved, def.onRejected, ...(def.onReturned ? [def.onReturned] : [])]) {
     if (c.agg !== agg) throw declError('CAGE-APPR-002', `审批结论命令必须属于 ${agg.name}`);
     if (!c.invokedBy.includes('process')) {
       throw declError('CAGE-APPR-003', `审批结论命令必须声明 invokedBy: 'process'`);

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

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

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

@@ -34,14 +34,14 @@ approval(..., { process: 'po-approval', ... }) 与 route('po-approval', ...)
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/approval/src/bridge.ts:8`
+- `packages/approval/src/bridge.ts:14`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
   const binding = k.registry.approvalByProcess(r.process);
   if (!binding) throw new Error(`[CAGE-APPR-004] 没有流程 ${r.process} 的审批绑定`);
-  const cmd = r.outcome === 'approved' ? binding.a.onApproved : binding.a.onRejected;
-  const ctx = k.processCtx({
-    process: r.process,
+  const cmd = r.outcome === 'approved' ? binding.a.onApproved : r.outcome === 'returned' ? binding.a.onReturned : binding.a.onRejected;
+  if (!cmd) throw new Error('[CAGE-APPR-006] 审批未绑定退回修改命令');
+  let ctx: Ctx;
 ```

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

@@ -34,14 +34,14 @@ route('采购审批', nodes)
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/approval/src/route.ts:96`
+- `packages/approval/src/route.ts:176`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-export function route(process: string, nodes: RouteNode[]): Route {
+export function route(process: string, nodes: RouteNode[], options: { reminders?: ApprovalReminderPolicy } = {}): Route {
   if (!/^[a-z][a-z0-9-]*$/.test(process)) throw declError('CAGE-APPR-005', `流程名 ${process} 必须是小写短横线`);
   if (nodes.length === 0) throw declError('CAGE-APPR-006', `流程 ${process} 至少需要一个步骤`);
-  const fields = new Set<string>();
-  for (const n of nodes) {
+  const inspection = inspectRoute(nodes);
+  const fields = new Set<string>(inspection.fields);
 ```

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

@@ -1,4 +1,4 @@
-# CAGE-APPR-006：流程没有步骤
+# CAGE-APPR-006：审批步骤配置无效
 
 [返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
 
@@ -8,11 +8,13 @@
 
 阶段：声明、图规则或 worker。
 
-route 接收了空步骤数组。
+route 没有步骤、展开后为空，或人工 actions/assignment、候选池与 all 组合、AI 步骤必填配置或预算不合法。
 
 ## 修复步骤
 
 1. 声明至少一个实际审批步骤，并检查条件后能否形成预期流程。
+2. candidate 只支持 any；逐人会签用默认 direct。actions 只接受 transfer/delegate/addSign 布尔值。
+3. AI 步骤需模型、要求、上下文字段、接管规则及正整数预算，并绑定 AI 运行时、退回命令和自动角色。
 
 ## 正例
 
@@ -34,14 +36,33 @@ route('po-approval', [])
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/approval/src/route.ts:97`
+- `packages/approval/src/bridge.ts:16`
+- `packages/approval/src/deadlines.ts:34`
+- `packages/approval/src/deadlines.ts:41`
+- `packages/approval/src/engine.ts:75`
+- `packages/approval/src/execution.ts:40`
+- `packages/approval/src/execution.ts:42`
+- `packages/approval/src/execution.ts:47`
+- `packages/approval/src/execution.ts:49`
+- `packages/approval/src/execution.ts:54`
+- `packages/approval/src/execution.ts:55`
+- `packages/approval/src/execution.ts:88`
+- `packages/approval/src/operations.ts:375`
+- `packages/approval/src/route.ts:109`
+- `packages/approval/src/route.ts:111`
+- `packages/approval/src/route.ts:115`
+- `packages/approval/src/route.ts:117`
+- `packages/approval/src/route.ts:177`
+- `packages/approval/src/route.ts:213`
+- `packages/approval/src/route.ts:224`
+- `packages/approval/src/route.ts:226`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
-  if (!/^[a-z][a-z0-9-]*$/.test(process)) throw declError('CAGE-APPR-005', `流程名 ${process} 必须是小写短横线`);
-  if (nodes.length === 0) throw declError('CAGE-APPR-006', `流程 ${process} 至少需要一个步骤`);
-  const fields = new Set<string>();
-  for (const n of nodes) {
-    const steps = n.kind === 'step' ? [n] : n.steps;
+  const cmd = r.outcome === 'approved' ? binding.a.onApproved : r.outcome === 'returned' ? binding.a.onReturned : binding.a.onRejected;
+  if (!cmd) throw new Error('[CAGE-APPR-006] 审批未绑定退回修改命令');
+  let ctx: Ctx;
+  if (r.lastApprover) {
+    // 待办决定已持有事务连接时复用它；同实例并发排队不能耗尽池后让锁持有者再等新连接。
 ```

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

@@ -8,14 +8,15 @@
 
 阶段：声明、图规则或 worker。
 
-worker 启动或推进审批步骤时，选人器没有找到人。
+worker 启动或推进审批步骤时选人器没有找到人，或字段选人/候选节点中存在非当前租户启用账号。
 
 ## 修复步骤
 
 1. 先看本项目 approvals.ts：deptLeader 读取单据部门的负责人；role 使用角色 code；user 使用实际用户 UUID。
 2. 在 /admin 设置单据所属部门的负责人，或创建对应 code 的角色并分配实际用户。给用户经理角色，并不等于设置了部门负责人。
-3. 再核对审批人的结论能力、数据范围、ceiling 额度和职责分离。选中审批人不等于允许完成审批。
-4. 若 OrderSubmitted 已入死信，修复后在 /admin 按 outboxId 重放，确认待办生成；原提交已成功时不重复提交或 SQL 改回草稿。
+3. field 使用提交时保存的 routable 人员字段；检查 UUID 对应账号是否全部在当前租户且 active。不能删掉不合格人员后默认为审批通过；字段快照错误需按业务撤回/重提修正。
+4. 再核对审批人的结论能力、数据范围、ceiling 额度和职责分离。选中审批人不等于允许完成审批。
+5. 若 OrderSubmitted 已入死信，修复后在 /admin 按 outboxId 重放，确认待办生成；原提交已成功时不重复提交或 SQL 改回草稿。
 
 ## 正例
 
@@ -37,14 +38,15 @@ deptLeader('deptId')：给该部门设置负责人；role('finance')：给实际
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/approval/src/engine.ts:64`
+- `packages/approval/src/engine.ts:87`
+- `packages/approval/src/engine.ts:94`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
     if (who.length === 0) {
-      throw new Error(`[CAGE-APPR-007] 流程 ${this.route.process} 第 ${index + 1} 步「${s.title}」找不到审批人，请在 /admin 配置部门负责人或角色`);
+      throw new Error(`[CAGE-APPR-007] 流程 ${this.route.process} 第 ${index + 1} 步「${title}」找不到审批人，请在 /admin 配置部门负责人或角色`);
     }
-    for (const assignee of new Set(who)) {
-      await tx.insertInto('flow.approval_task').values({ instance_id: instanceId, tenant_id: tenantId, step: index, title: s.title, assignee }).execute();
+    if (selector.kind === 'field' || assignment === 'candidate') {
+      // 新字段/候选声明不允许创建指向停用或其他租户账号的票；整批拒绝，不静默减少会签人数。
 ```

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

@@ -34,15 +34,15 @@ approve 被 poApproval.onApproved 引用，或 acquireLock 被 lockOnApprove 引
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/cli/src/rules.ts:140`
-- `packages/cli/src/rules.ts:149`
+- `packages/cli/src/rules.ts:175`
+- `packages/cli/src/rules.ts:189`
 
 实现片段（位置随框架版本更新）：
 
 ```ts
 
 /** CAGE-APPR-010：invokedBy 为 process 的命令必须有审批绑定或反应调用它，否则没有人能调用 */
-export function checkProcessCommands(g: Ontology): Finding[] {
-  const { into } = index(g);
-  const findings: Finding[] = [];
+/**
+ * 检查仅流程/外部可调用的命令是否有声明调用入口。
+ * @param g 当前图。
 ```

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

@@ -0,0 +1,53 @@
+# CAGE-AUDIT-001：可靠读取审计失败
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：安全读侧 / 查询。
+
+敏感明文读取，或声明 audit.purpose 的查询，无法完成交付前的审计写入。请求拒绝交付结果。
+
+## 修复步骤
+
+1. 凭 requestId 检查审计存储、写账号权限和数据库可用性；修复后重新读取。
+2. 不要吞掉审计异常、去除敏感声明或改用基表绕过审计。查询只声明目的，不把敏感输入放进目的文本。
+
+## 正例
+
+```text
+query('report', { reads: [Order], audit: { purpose: '月度核对' }, /* input/sql */ })
+```
+
+## 反例
+
+```text
+审计写入失败后继续返回敏感明文
+```
+
+## 修复后验证
+
+修复审计存储后重新读取，确认有权交付的数据与相应审计均完成。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/read.ts:136`
+- `packages/kernel/src/read.ts:137`
+- `packages/kernel/src/read.ts:284`
+- `packages/kernel/src/read.ts:285`
+- `packages/kernel/src/transfer/index.ts:176`
+- `packages/kernel/src/transfer/index.ts:177`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    }); } catch {
+      this.k.log.error({ code: 'CAGE-AUDIT-001', aggregate: agg.name, kind, requestId: ctx.requestId }, '读取审计失败，未交付数据');
+      throw cageError('INTERNAL', { diagnostic: 'CAGE-AUDIT-001', phase: 'audit', operation: kind, retryable: true });
+    }
+  }
+```

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

@@ -34,7 +34,7 @@ HTTP 无法取得 OIDC issuer 的发现文档，或远端返回非成功状态
 
 以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
 
-- `packages/http/src/oidc.ts:20`
+- `packages/http/src/oidc.ts:25`
 
 实现片段（位置随框架版本更新）：
 

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

@@ -0,0 +1,51 @@
+# CAGE-BIZ-001：业务流程声明无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 图规则。
+
+流程或板块标识重复、名称说明缺失、入口/连线/结束阶段无效，或引用的真实声明未从 domain 导出。
+
+## 修复步骤
+
+1. 使用 businessProcess 声明阅读规格，填写流程、板块、阶段及连线说明；阶段引用已导出的真实业务声明。
+2. 主对象使用聚合引用；相同板块 ID 的名称和说明保持一致。流程不调度命令，也不授予权限。
+
+## 正例
+
+```text
+export const orderFlow = businessProcess('order-flow', { /* 完整阶段和转移，均引用真实声明 */ });
+```
+
+## 反例
+
+```text
+transitions: [{ from: 'draft', to: 'missing', mode: 'automatic', label: '继续' }] // missing 阶段不存在
+```
+
+## 修复后验证
+
+重跑 cage check，再在 cage graph 中检查主线、分支、关联和实现代码；运行行为仍需相应业务回归。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/business-process.ts:132`
+- `packages/kernel/src/registry.ts:253`
+- `packages/kernel/src/registry.ts:256`
+- `packages/kernel/src/registry.ts:259`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+): BusinessProcess {
+  const invalid = (reason: string): never => { throw declError('CAGE-BIZ-001', `${name}：${reason}`); };
+  const identifier = (value: string) => /^[a-z][a-z0-9-]*$/.test(value);
+  const text = (value: string) => typeof value === 'string' && value.trim().length > 0;
+  if (!identifier(name) || !identifier(def.area.id)) invalid('流程与板块标识须使用小写短横线格式');
+```

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

@@ -0,0 +1,49 @@
+# CAGE-BIZ-002：业务流程与真实声明不一致
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载 / 图规则。
+
+阶段不可达或无法结束，自动连线缺少真实触发链，人工/等待方式与目标入口不符，同对象状态不相接，或关联对象缺少实现依据。
+
+## 修复步骤
+
+1. 自动连线必须有 emits、事件触发、反应目标、审批结论或外部成功回写支持；reads、字段关联和状态相接不能证明自动调用。
+2. 人工下一步使用用户可调用的命令，独立通知或调度使用 wait；核对前后命令的状态约束。
+3. 关联的 via 引用本阶段实际可触发的声明，且该声明确实读取、写入或引用目标对象。补齐入口到所有阶段，以及各阶段到结束结果的路径。
+
+## 正例
+
+```text
+{ from: 'draft', to: 'submit', mode: 'manual', label: '申请人提交' } // submit 允许 user 且状态相接
+```
+
+## 反例
+
+```text
+{ from: 'create', to: 'submit', mode: 'automatic', label: '自动提交' } // 只有状态相接，没有实际触发
+```
+
+## 修复后验证
+
+重跑 cage check，再在 cage graph 中检查主线、分支、关联和实现代码；运行行为仍需相应业务回归。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/process-rules.ts:50`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const fail = (node: ViewNode, reason: string, fix: string) => findings.push({
+    code: 'CAGE-BIZ-002', at: node.file ? `${node.file}:${node.line}` : node.id, reason, fix,
+  });
+  const actual = (start: string) => reachable(start, key => causalSuccessors(model, key));
+  const involving = (start: string, target: string) => {
+```

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`
 
 实现片段（位置随框架版本更新）：