用 Drizzle 为 JSONB 字段补全 TypeScript 类型

是什么 这是一条面向 TypeScript 与 Drizzle ORM 使用者的代码型教程，核心问题是：数据库中的 JSONB 虽然灵活，但如果不额外声明类型，应用层很容易失去静态检查。示例围绕 agent_runs 表展开，把 Agent 计划、执行轨迹、待处理动作和工作文档分别映射到 JSONB 列。

核心设计 关键 API 是 Drizzle 的 jsonb().$type<T>()。它不会改变 PostgreSQL 的存储格式，而是把 TypeScript 类型信息附加到 schema 定义上，例如将 trace 标注为 AgentTraceEntry[]，将 pendingAction 和 workDoc 明确为可空类型，同时为 trace 设置空数组默认值。再结合 $inferSelect 与 $inferInsert，可以让查询结果和插入数据从同一份表定义中推断出来，减少重复接口声明。

关键洞察 这种做法适合结构相对稳定、需要保存嵌套业务对象的 Agent 系统，价值在于缩小数据库 schema、领域类型和调用代码之间的偏差。它也提醒工程师区分“运行时校验”和“编译期类型”：$type 主要提供后者。

边界与风险 截图没有展示运行时验证、迁移策略或 JSONB 查询索引，因此不能据此认为数据一定安全。外部输入仍需使用 Zod 等校验方案，类型变更也需要配套迁移和兼容性检查。