SuperAPI AI 工具集

db-migration-agent

编程与开发

查看项目

更新于 11-05 16:19

技能介绍

用途

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 会阻塞构建。在你的模式能通过该门禁之前,不要报告完成。