用途：为 agents-api/src/domains/**/routes/ 下的路由处理器及其 CRUD 测试提供统一约定，避免字段转发遗漏导致的数据丢失。
主要能力与用法：
- 展开模式（必需）。把校验后的请求体转发给 DAL 函数时必须使用展开语法，先展开完整 body，再覆盖需要转换的字段。示例：const body = c.req.valid('json'); const result = await createEntity(db)({ ...body, id: body.id || generateId() });。禁止逐字段挑选（name: body.name 之类），否则新增 schema 列时不会被转发。
- 字段转换覆盖。转换项放在展开之后以覆盖原始值，常见项包括 ID 生成、空值转换、类型转换、默认值、认证哈希、计算字段（如 createdBy: c.get('userId')）。
- CI 约束。scripts/check-route-handler-patterns.mjs 在 pnpm check 中运行，检测显式字段挑选而无展开的处理器。本地可运行 pnpm check:route-handler-patterns。确需例外的处理器可在对象字面量块内加注释 // allow-field-picking，应尽量少用。
- CRUD 测试要求。每个有路由处理器的实体都必须有覆盖全部 schema 字段的往返持久化测试：用全字段创建后 GET 校验；逐字段更新后 GET 校验；同时带全部可选字段往返；可选字段的 null/undefined 处理；可空字段清空为 null；默认值被正确应用并返回。测试位于 agents-api/src/tests/manage/routes/crud/，使用 testRequest.ts 的 makeRequest()。可参考 contextConfigs.test.ts、credentialReferences.test.ts 及 testHelpers.ts 中的 createTestAgentData()、createTestToolData() 等工厂。
- 路由定义与 HTTP 方法。所有路由必须使用带显式授权的 createProtectedRoute()（如 requireProjectPermission('edit')）。PATCH 是部分/稀疏更新的规范方法，PUT 保留用于完整资源替换；新增更新路由必须用 PATCH。在已有 PUT 旁新增 PATCH 时，把处理器与路由配置抽为共享变量，PATCH 使用规范 operationId，PUT 使用带 -put 后缀的 operationId 并设 'x-speakeasy-ignore': true。
限制：资料未说明适用范围之外的项目配置、依赖版本或失败后果细节，暂未提供。