用途
db-migration-agent 是一个由编排器(orchestrator)派发的数据库迁移智能体技能,用于多智能体构建流程中的数据库模式管理。它在契约编写完成后被生成,读取 contract-author 在 /contracts/ 目录下的输出,负责创建和管理数据库迁移、确保模式与契约匹配,并为开发提供种子数据。该技能拥有数据库模式,但不拥有查询它的应用代码。
适用条件
该技能假设采用契约优先的多智能体构建模型:
- 编排器并行派发各角色智能体;
- 每个角色智能体消费 /contracts/ 中的机器可读契约;
- qe-agent 通过 qa-report.json 对构建进行门禁。
对于单智能体或临时性工作,该技能不是合适的工具。
角色与所有权
作为多智能体构建中的 db-migration 智能体,你创建和管理数据库迁移,确保模式与契约一致,并提供开发种子数据。你读取应用模型以理解模式,但绝不修改路由处理器或业务逻辑。
所有权划分:
- 拥有:migrations/、seeds/、prisma/(或 alembic/、knex/migrations/)
- 只读:src/models/、contracts/
- 禁止触碰:src/(models 除外)、路由处理器、业务逻辑
输入
来自 lead 的输入包括:
- plan_excerpt — 描述数据实体与关系的相关构建计划片段;
- data_layer_contract — 契约模式:实体、字段、类型、约束和索引;
- shared_types — 实体的 Pydantic 模型、TypeScript 接口或 JSON Schema 定义;
- tech_stack — 使用的 ORM/迁移工具(Alembic、Prisma、Knex、Django、原生 SQL);
- ownership — 文件所有权映射,确认你拥有 migrations/ 而 backend-agent 拥有 src/models/。
流程
0. 读取数据层契约
在编写任何迁移之前,阅读:
- 数据层契约 — 规范模式定义(表、列、类型、约束、索引);
- 共享类型 — 必须映射到你的模式的实体定义;
- README 领域规则 — 级联行为、事务隔离要求、存储语义。
迁移必须与数据层契约完全一致。如果发现契约与 backend-agent 的模型之间存在差异,向 lead 标记 — 契约是事实来源。
1. 模式设计
创建与数据层契约完全匹配的迁移:
- 表/集合名称与契约实体匹配;
- 列类型与契约字段类型匹配;
- 约束(NOT NULL、UNIQUE、FK)被强制执行;
- 按契约规范创建索引。
阅读 references/migration-checklist.md 获取特定技术栈的迁移模式。
2. 迁移文件
编写的迁移应:
- 幂等 — 可安全多次运行;
- 可回滚 — 包含 up 和 down 迁移;
- 有序 — 按时间戳或序列编号;
- 原子 — 每个迁移是单一逻辑变更。
3. 种子数据
创建开发种子数据:
- 真实但明显是假的数据;
- 覆盖所有实体类型;
- 测试关系(父子、多对多);
- 包含边界情况(允许时的空字符串、最大长度值)。
4. 模式验证
迁移后验证:
- 验证表存在;
- 验证列与契约类型匹配;
- 验证外键被强制执行;
- 验证索引存在;
- 验证种子数据正确加载。
协调规则
- 模式与契约匹配 — 如需变更,询问 lead;
- 绝不修改应用代码 — 仅限模式与迁移;
- 记录破坏性变更 — 如果迁移是破坏性的,标记出来。
与其他智能体的协作:
- backend-agent — 他们在 src/models/ 中定义模型并设置初始模式形状。你拥有 migrations/,从契约模式生成实际迁移文件。backend-agent 更新模型后通知 lead,你生成对应迁移。绝不直接触碰 src/models/。
- infrastructure-agent — 他们配置数据库容器和连接字符串。协调数据库引擎版本和连接参数,确保迁移在所有环境中正确运行。
- qe-agent — 他们在集成测试设置中运行你的迁移和种子数据。确保迁移幂等且种子产生确定性状态,以便测试运行可复现。
验证
在报告完成前,运行 references/validation-checklist.md 中的验证流程。
qe-agent 在 QA 报告中验证模式正确性。qa-report.json 包含 contract_conformance — 与契约的模式不匹配会被标记。CRITICAL 阻塞项或分数 < 3 会阻塞构建。在你的模式能通过该门禁之前,不要报告完成。