@yss123/cage-cli 0.1.0 → 0.3.0

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

@@ -0,0 +1,47 @@
+# CAGE-DEP-005：domain 反向依赖生成物
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：静态检查 / verify。
+
+domain 引用 generated 或 packages/contracts，形成生成循环。
+
+## 修复步骤
+
+1. 领域源码是生成源头；前端/适配层使用 contracts，domain 使用本地领域类型和公开声明 API。
+
+## 正例
+
+```text
+domain 从 './purchase-order.js' 读领域符号
+```
+
+## 反例
+
+```text
+domain 从 '@app/contracts' 导入自己生成的快照
+```
+
+## 修复后验证
+
+重跑 cage check 和 verify，确认边界修复而不是禁用规则。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/lint/dependency-cruiser.cjs:36`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      severity: 'error',
+      comment: '[CAGE-DEP-005] domain 不能依赖生成物',
+      from: { path: '^packages/domain' },
+      to: { path: '^(generated|packages/contracts)/' },
+    },
+```

package/templates/blank/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/blank/docs/errors/CAGE-DLQ-001.md

@@ -0,0 +1,48 @@
+# CAGE-DLQ-001：死信不存在或已经处理
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：系统管理接口。
+
+重放/丢弃时目标死信已被处理或不在待处理集合。
+
+## 修复步骤
+
+1. 刷新死信列表，核对 outboxId 和审计记录；确认是否已由其他人处理，不直接重建/修改系统行。
+
+## 正例
+
+```text
+查看当前状态后只处理待处理的死信
+```
+
+## 反例
+
+```text
+反复提交旧页面上的重放请求或手改 sys.outbox
+```
+
+## 修复后验证
+
+刷新死信列表并查看审计及当前处理结果；核对原始 outboxId。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/worker/outbox.ts:169`
+- `packages/kernel/src/worker/outbox.ts:181`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    const d = await tx.selectFrom('sys.dead_letter').selectAll().where('id', '=', deadLetterId).where('handled_at', 'is', null).forUpdate().executeTakeFirst();
+    if (!d) throw new Error('[CAGE-DLQ-001] 死信不存在或已处理');
+    await tx.updateTable('sys.outbox').set({ status: 'pending', attempts: 0, next_at: sql`now()`, last_error: null }).where('id', '=', d.outbox_id).execute();
+    await tx.updateTable('sys.dead_letter').set({ handled_by: handledBy, handled_at: sql`now()`, resolution: 'replayed' }).where('id', '=', deadLetterId).execute();
+    await sql`select pg_notify('cage_outbox', '')`.execute(tx);
+```

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

@@ -0,0 +1,52 @@
+# CAGE-ENV-001：缺少数据库连接配置
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init / migrate / 启动。
+
+API、worker、迁移或初始化没有取得所需的数据库连接。
+
+## 修复步骤
+
+1. 在应用根目录 .env 配置 CAGE_ADMIN_DATABASE_URL，指向已存在的数据库，运行 pnpm exec cage init 自动生成三种账号连接。
+2. 已有账号则直接提供 APP/READ/MIGRATE URL；主机、端口、库名一致，账号各司其职。migrate 需要迁移连接。
+3. 确认运行目录、部署环境覆盖值及服务已重启；不要输出凭证，也不要给日常服务改用管理员连接。
+
+## 正例
+
+```text
+配置已有库 → cage init → gen → 审查后 migrate → dev
+```
+
+## 反例
+
+```text
+未配置连接就启动，或新增自动临时数据库兜底掩盖错误
+```
+
+## 修复后验证
+
+重跑原先失败的命令，确认使用预期库与账号；输出脱敏信息。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `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`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  if (!configured(adminUrl)) {
+    if (!hasSaved) throw new Error('[CAGE-ENV-001] 首次初始化请在项目 .env 填写 CAGE_ADMIN_DATABASE_URL，连接已有数据库后运行 pnpm exec cage init');
+    await verifyConnections(saved);
+    return { status: 'reused', envFile };
+  }
+```

package/templates/blank/docs/errors/CAGE-ENV-002.md

@@ -0,0 +1,51 @@
+# CAGE-ENV-002：运行配置不满足安全边界
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init / migrate / 启动。
+
+生产启动缺少足够强的 Cookie 密钥，或服务配置中的认证并发、超时等参数无效。
+
+## 修复步骤
+
+1. 按诊断的配置项设置合法值；生产提供独立生成的随机 Cookie 密钥并重启服务。
+2. 只报告配置项名称和错误码，不输出密钥或整个环境文件。
+
+## 正例
+
+```text
+由受控环境变量提供随机 CAGE_COOKIE_SECRET，并设置有界认证并发及队列
+```
+
+## 反例
+
+```text
+生产继续使用固定开发 Cookie 密钥，或给并发上限填入无穷值
+```
+
+## 修复后验证
+
+重跑原先失败的命令，确认使用预期库与账号；输出脱敏信息。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/http/src/auth.ts:69`
+- `packages/http/src/auth.ts:72`
+- `packages/http/src/server.ts:111`
+- `packages/http/src/server.ts:115`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+  /** concurrency 是同时派生个数，queueLimit 是额外等待个数；非法配置在启动期抛 CAGE-ENV-002。 */
+  constructor(private readonly concurrency = 4, private readonly queueLimit = 32) {
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1 || !Number.isSafeInteger(queueLimit) || queueLimit < 0) {
+      throw new Error('[CAGE-ENV-002] passwordConcurrency 必须为正整数，passwordQueueLimit 必须为非负整数');
+```

package/templates/blank/docs/errors/CAGE-ENV-003.md

@@ -0,0 +1,48 @@
+# CAGE-ENV-003：服务启动不能隐式初始化组织
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：init / migrate / 启动。
+
+createServer 显式传入 bootstrap: true。初始化不能混入日常服务启动并输出密码。
+
+## 修复步骤
+
+1. 移除启动参数中的 bootstrap: true；先审查执行迁移，再显式执行 cage bootstrap。
+2. 使用 --credentials-file 指定新的受限凭据文件；组织已有用户时不重置凭据。
+
+## 正例
+
+```text
+pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json
+```
+
+## 反例
+
+```text
+createServer({ domain, bootstrap: true })
+```
+
+## 修复后验证
+
+重跑原先失败的命令，确认使用预期库与账号；输出脱敏信息。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/http/src/server.ts:113`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  }
+  if (opts.bootstrap) throw new Error('[CAGE-ENV-003] 服务启动不再隐式初始化组织；请在受控初始化入口显式调用 bootstrapOrg 并安全交付初始凭据');
+  const readinessTimeoutMs = opts.readinessTimeoutMs ?? 2000;
+  if (!Number.isSafeInteger(readinessTimeoutMs) || readinessTimeoutMs < 1) throw new Error('[CAGE-ENV-002] readinessTimeoutMs 必须为正整数');
+  // 开发会话密钥也是随机值，重启会使旧 CSRF/OIDC cookie 失效；多实例必须显式共享配置。
+```

package/templates/blank/docs/errors/CAGE-EVENT-001.md

@@ -0,0 +1,47 @@
+# CAGE-EVENT-001：事件载荷不满足声明
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：写事务 / 基线比较。
+
+命令要写入 outbox 的载荷没有通过事件字段 schema。
+
+## 修复步骤
+
+1. 核对默认载荷映射及字段类型；需要旧状态、改名字段或复杂数据时使用 emit 显式映射。事务失败应回滚，不单独补写消息。
+
+## 正例
+
+```text
+emit(OrderCancelled, (o, _i, prev) => ({ orderId: o.id, previousStatus: prev.status }))
+```
+
+## 反例
+
+```text
+事件要求 orderId，却从错误字段映射成 undefined
+```
+
+## 修复后验证
+
+运行相关命令与消费者测试；兼容性使用修改前基线检查，考虑尚未消费的旧事件。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/kernel.ts:456`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+      if (!p.success) {
+        throw new Error(`[CAGE-EVENT-001] 事件 ${ev.name} 的载荷不符合声明：${JSON.stringify(zodIssues(p.error))}`);
+      }
+      const payload = maskEventPayload(ev, p.data as Record<string, unknown>);
+      const row = await tx
+```

package/templates/blank/docs/errors/CAGE-EVENT-002.md

@@ -0,0 +1,50 @@
+# CAGE-EVENT-002：事件变更不向后兼容
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：写事务 / 基线比较。
+
+与基线相比，删除旧载荷字段、改变字段 kind，或新增必填字段。
+
+## 修复步骤
+
+1. 保留旧字段和类型，新字段 optional；不兼容含义新建事件，并考虑旧 outbox 消息和消费者升级顺序。
+
+## 正例
+
+```text
+note: text().optional() // 新增字段
+```
+
+## 反例
+
+```text
+给线上已有事件新增必填 note，旧消息没有该值
+```
+
+## 修复后验证
+
+运行相关命令与消费者测试；兼容性使用修改前基线检查，考虑尚未消费的旧事件。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/cli/src/rules.ts:275`
+- `packages/cli/src/rules.ts:293`
+- `packages/cli/src/rules.ts:300`
+- `packages/cli/src/rules.ts:310`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+
+/** CAGE-EVENT-002：事件载荷只允许向后兼容的变更（只能新增可选字段） */
+/**
+ * 比较同名事件字段的删除、类型改变及新增必填项。
+ * @param base 旧本体，代表可能仍有在途事件的声明。
+```

package/templates/blank/docs/errors/CAGE-FIELD-001.md

@@ -0,0 +1,47 @@
+# CAGE-FIELD-001：敏感字段种类不存在
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+sensitive 使用了 SENSITIVE_KINDS 之外的值。
+
+## 修复步骤
+
+1. 选用当前包导出的敏感种类；确需新掩码规则时评估框架扩展，不以 any 绕过声明。
+
+## 正例
+
+```text
+supplierPhone: text(32).sensitive('phone')
+```
+
+## 反例
+
+```text
+text().sensitive('自定义随意字符串')
+```
+
+## 修复后验证
+
+重跑 cage check/gen，审查契约与迁移；敏感字段还要验证普通用户读结果。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/fields.ts:197`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if (isRelation(this)) throw declError('CAGE-REL-001', '关系字段不支持 sensitive；目标字段按目标聚合权限掩码');
+    if (!SENSITIVE_KINDS.includes(kind)) throw declError('CAGE-FIELD-001', `未知的敏感种类 ${kind}`);
+    return this.with({ sensitiveKind: kind });
+  }
+  /** 返回要求租户内唯一的新字段；实际约束由 DDL/迁移落实，不是仅一次应用查询。文件和集合已有专用归属/配对语义，拒绝该修饰。 */
+```

package/templates/blank/docs/errors/CAGE-FIELD-002.md

@@ -0,0 +1,47 @@
+# CAGE-FIELD-002：引用目标为空
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+ref 收到空目标，常见原因是循环导入。
+
+## 修复步骤
+
+1. 使用 ref("聚合名") 避免循环求值，确保对应聚合从入口导出且名称正确。
+
+## 正例
+
+```text
+deptId: ref('Dept')
+```
+
+## 反例
+
+```text
+deptId: ref(undefined)
+```
+
+## 修复后验证
+
+重跑 cage check/gen，审查契约与迁移；敏感字段还要验证普通用户读结果。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/fields.ts:270`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+  const target = typeof to === 'string' ? to : to?.name;
+  if (!target) throw declError('CAGE-FIELD-002', 'ref() 的目标为空，可能是循环导入；可改为 ref("聚合名")');
+  return mk(z.string().uuid(), { kind: 'ref', sql: 'uuid', ref: target });
+}
+
+```

package/templates/blank/docs/errors/CAGE-FIELD-003.md

@@ -0,0 +1,47 @@
+# CAGE-FIELD-003：字段不是字段原语
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+aggregate.fields 中存在不是 field/states 描述对象的值。
+
+## 修复步骤
+
+1. 使用 text/int/money/ref/list 等公开字段工厂；Zod 用在命令输入或 json schema，不能直接代替 fields 的字段描述。
+
+## 正例
+
+```text
+fields: { amount: money() }
+```
+
+## 反例
+
+```text
+fields: { amount: z.string() }
+```
+
+## 修复后验证
+
+重跑 cage check/gen，审查契约与迁移；敏感字段还要验证普通用户读结果。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:174`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    }
+    if (!isField(v)) throw declError('CAGE-FIELD-003', `${name}.${k} 不是字段原语`);
+    if ((RESERVED_FIELDS as readonly string[]).includes(k)) {
+      throw declError('CAGE-FIELD-004', `${name}.${k} 是保留字段名，由内核维护`);
+    }
+```

package/templates/blank/docs/errors/CAGE-FIELD-004.md

@@ -0,0 +1,47 @@
+# CAGE-FIELD-004：覆盖系统保留列
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：声明加载。
+
+业务 fields 定义了 id/version/status/createdAt/updatedAt/tenantId 等保留字段。
+
+## 修复步骤
+
+1. 移除重复系统字段；状态使用 aggregate.states 或唯一 fields.status 状态声明；业务另取有意义名称。
+
+## 正例
+
+```text
+fields: { externalId: text() }, states: POStatus
+```
+
+## 反例
+
+```text
+fields: { version: text() }
+```
+
+## 修复后验证
+
+重跑 cage check/gen，审查契约与迁移；敏感字段还要验证普通用户读结果。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/kernel/src/primitives/aggregate.ts:176`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    if ((RESERVED_FIELDS as readonly string[]).includes(k)) {
+      throw declError('CAGE-FIELD-004', `${name}.${k} 是保留字段名，由内核维护`);
+    }
+    if (!/^[a-z][A-Za-z0-9]*$/.test(k)) throw declError('CAGE-NAME-002', `字段名 ${name}.${k} 必须是小驼峰`);
+    fields[k] = v;
+```

package/templates/blank/docs/errors/CAGE-FILE-001.md

@@ -0,0 +1,56 @@
+# CAGE-FILE-001：文件字段或上传配置无效
+
+[返回错误码册](README.md) · [业务排错](../ai/troubleshooting.md)
+
+> 本页由框架生成。正反例为局部声明或操作说明，完整写法见业务开发指南及本项目 domain。
+
+## 何时出现
+
+阶段：字段声明 / 私有文件服务配置。
+
+文件缺少明确的大小/MIME 限制，多文件数量无效，文件嵌入 JSON/事件/范围字段，或存储分片配置超出适配器限制。
+
+## 修复步骤
+
+1. 文件直接声明在聚合 fields 中，设置正整数 maxBytes、明确 MIME accept；files 还需 1–100 的 maxCount。
+2. 不使用 sensitive/hidden/unique 修饰文件；事件只传 id/list(id())。上传 partBytes/maxFileBytes 必须符合存储适配器分片限制。
+
+## 正例
+
+```text
+attachments: files({ maxBytes: 20971520, maxCount: 10, accept: ['application/pdf'] })
+```
+
+## 反例
+
+```text
+list({ contract: file({ maxBytes: 0, accept: ['*/*'] }) })
+```
+
+## 修复后验证
+
+重跑 cage check、gen 和文件回归；实际验证暂停、续传、命令绑定及当前权限下载，云存储联调单独报告。
+
+## 框架内的检查位置
+
+以下路径相对框架源码仓库，不是要求业务项目创建这些文件。当前项目先修业务声明、配置或授权；明确属于框架缺口时反馈错误码和脱敏上下文。
+
+- `packages/files/src/service.ts:95`
+- `packages/files/src/service.ts:98`
+- `packages/kernel/src/primitives/aggregate.ts:189`
+- `packages/kernel/src/primitives/event.ts:51`
+- `packages/kernel/src/primitives/fields.ts:195`
+- `packages/kernel/src/primitives/fields.ts:202`
+- `packages/kernel/src/primitives/fields.ts:208`
+- `packages/kernel/src/primitives/fields.ts:305`
+- `packages/kernel/src/primitives/fields.ts:336`
+
+实现片段（位置随框架版本更新）：
+
+```ts
+    };
+    for (const [name, value] of Object.entries(this.options)) if (!Number.isSafeInteger(value) || value < 1) throw new Error(`[CAGE-FILE-001] ${name} 必须为正安全整数`);
+    const limits = this.storage.limits;
+    if (this.options.partBytes < limits.minPartBytes || this.options.partBytes > limits.maxPartBytes || Math.ceil(this.options.maxFileBytes / this.options.partBytes) > limits.maxParts)
+      throw new Error('[CAGE-FILE-001] 分片配置超出存储适配器限制');
+```