ruflo-migrations 迁移工程师 Agent 实战指南：从编号规范到可回滚 SQL 的全链路 schema 管理-编程实验室

ruflo-migrations 迁移工程师 Agent 实战指南：从编号规范到可回滚 SQL 的全链路 schema 管理

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo

本指南围绕 ruflo 仓库中 ruflo-migrations 插件的核心 Agent ——migration-engineer（迁移工程师）展开，系统讲解其在数据库 schema 变更场景下的完整职责：顺序编号迁移生成、up/down 成对 SQL 的可回滚设计、dry-run 预演、迁移校验以及基于 AgentDB 的迁移历史追踪。读完本文，你将掌握如何在 ruflo 的 Claude Code 插件体系中创建、校验、应用与回滚数据库迁移，并理解其背后的命名空间路由与验证契约。

一、migration-engineer Agent 的定位与职责

migration-engineer是 ruflo-migrations 插件内置的 Agent，定义于 agents/migration-engineer.md，frontmatter 指定使用sonnet模型，其五项核心职责构成了整个迁移工作流的主干：

生成迁移——按顺序编号生成迁移文件（001_create_users、002_add_email_index……）；
成对编写 up/down SQL——每个迁移都必须配套回滚脚本，保证可回滚安全；
Dry-run 模式——仅展示将要执行的 SQL，不实际执行；
校验迁移——检查外键一致性、索引覆盖、数据类型兼容性；
追踪迁移历史——记录哪些迁移已应用及其状态。

该 Agent 与插件提供的两个 Skill（migrate-create、migrate-validate）及一个命令 migrate 协同，覆盖从"创建迁移"到"应用/回滚/状态查询/校验/历史"的完整闭环。

二、迁移编号规范：可预测、可排序、可追溯

migration-engineer强制迁移文件遵循严格的顺序编号规则，这也是任何迁移系统可用的前提：

文件格式：NNN_descriptive_name.sql（例如001_create_users.sql）；
成对文件：每个迁移包含两个文件——NNN_name.up.sql与NNN_name.down.sql；
编号规则：数字零填充至 3 位（001、002……099）；
命名规则：名称使用 snake_case，简洁描述本次变更意图。

该规范在 migrate create 流程中被进一步落实：创建迁移时首先扫描迁移目录找到当前最高编号，计算下一个编号（零填充 3 位），再生成NNN_<name>.up.sql与NNN_<name>.down.sql两个文件。而在 migrate-create Skill 中，模板选择依据名称前缀智能路由：

以create_开头 → CREATE TABLE 模板；
以add_开头 → ALTER TABLE ADD COLUMN 模板；
以drop_开头 → 带安全检查的 DROP 模板；
名称含index→ CREATE INDEX 模板；
其他 → 带占位注释的通用迁移模板。

标准迁移目录布局（见 README 的 Migration File Format 章节）：

migrations/ 001_create_users.up.sql 001_create_users.down.sql 002_add_email_index.up.sql 002_add_email_index.down.sql

三、迁移模板：三种高频变更的标准 up/down 写法

migration-engineer提供了三种最常用迁移的即用模板，全部遵循幂等原则（IF EXISTS/IF NOT EXISTS），确保重复执行不会产生副作用。

创建表（Create table）：

-- UP CREATE TABLE IF NOT EXISTS table_name ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now() ); -- DOWN DROP TABLE IF EXISTS table_name;

模板默认携带id UUID主键、created_at/updated_at时间戳三件套，符合多数业务表的基础结构。

添加列（Add column）：

-- UP ALTER TABLE table_name ADD COLUMN column_name TYPE NOT NULL DEFAULT value; -- DOWN ALTER TABLE table_name DROP COLUMN IF EXISTS column_name;

注意 UP 中新增NOT NULL列时必须提供DEFAULT值，这不仅是模板惯例，更是下方校验规则表中的硬性 Error 级检查项。

添加索引（Add index）：

-- UP CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_table_column ON table_name (column_name); -- DOWN DROP INDEX CONCURRENTLY IF EXISTS idx_table_column;

索引命名遵循idx_table_column惯例；CONCURRENTLY用于避免长时间锁表（在高流量生产库上尤为重要）。

四、校验规则矩阵：八项检查、三级严重度

migration-engineer对每个迁移执行结构化校验，migrate-validate Skill 将校验落为九个可执行步骤，其完整校验矩阵如下：

Check	Severity	Description
Foreign key targets exist	Error	被引用的表/列必须存在
Index coverage	Warning	WHERE/JOIN 中使用的列应有索引覆盖
Data type compatibility	Error	ALTER COLUMN 的目标类型必须兼容
NOT NULL without default	Error	新增 NOT NULL 列必须带 DEFAULT
Down migration completeness	Warning	每条 UP 语句都需要对应的 DOWN
Destructive operations	Warning	DROP TABLE、DROP COLUMN 需标记人工复核
Naming conventions	Info	表名复数、列名 snake_case
Idempotency	Warning	应使用 IF EXISTS / IF NOT EXISTS

在 migrate-validate Skill 的逐步流程中，这些检查对应为：外键校验（确认REFERENCES目标存在于当前 schema 或先前迁移中）、NOT NULL 默认值校验、回滚完整性校验（UP 中的每个 CREATE/ALTER 在 DOWN 中都有对应 DROP/ALTER）、破坏性操作告警（DROP TABLE、DROP COLUMN、TRUNCATE 需显式确认）、幂等性校验、命名规范校验（表名复数、列名 snake_case、索引遵循idx_table_column）。最终报告按 Error（必须修复）、Warning（应当修复）、Info（建议）三级输出，并附上问题所在的文件路径与行号，便于定位。

五、六大迁移命令：从创建到回滚的完整闭环

命令定义于 commands/migrate.md，共 6 个子命令（smoke.sh 第 3 项检查即验证这 6 个子命令齐全）：

migrate create <name> # 创建 NNN_name.up.sql 和 NNN_name.down.sql migrate up [--dry-run] # 应用待执行迁移（或仅预览 SQL） migrate down [--steps N] # 回滚最近 N 个迁移（默认 1） migrate status # 显示已应用/待执行迁移状态 migrate validate # 校验待执行迁移的安全性 migrate history # 显示完整迁移执行历史

各命令的执行逻辑要点：

migrate create <name>：扫描最高编号 → 计算下一编号（3 位零填充）→ 生成 up/down 文件 → 按名称选择模板填充 → 记录元数据 → 报告文件路径、迁移编号、所用模板。
migrate up [--dry-run]：先查询迁移历史确定已应用集合，再按顺序找出未应用迁移；--dry-run模式下仅打印每条待执行 SQL 而不执行；正常模式按序执行每个.up.sql，并把执行结果（成功/失败、耗时）写入migrations命名空间；最终报告已应用迁移、总耗时与错误。
migrate down [--steps N]：查询最近应用的迁移，按逆序执行对应.down.sql，记录回滚结果，默认回滚 1 步。
migrate status：列出迁移目录全部文件，与应用历史交叉比对，展示编号、名称、状态（applied/pending）、应用日期与耗时。
migrate validate：解析所有待执行 up/down 文件，执行第四节的八项检查，输出三级报告。
migrate history：读取migrations命名空间全部条目，展示编号、名称、方向（up/down）、时间戳、耗时、状态，并高亮需要关注的失败迁移。

六、AgentDB 命名空间：迁移历史与模式的存储契约

migration-engineer 文档列出了五类 MCP 工具，分别负责迁移元数据存储、状态召回、模式存储与语义路由。这里必须注意一个关键细节——工具族的路由机制差异，这是本插件 ADR-0001 专门修复的坑：

agentdb_hierarchical-*（hierarchical-store / hierarchical-recall）按 tier 路由（working | episodic | semantic），会忽略传入的 namespace 字符串；
agentdb_pattern-*（pattern-store / pattern-search）按 ReasoningBank 路由，同样忽略 namespace；
只有memory_*工具族（memory_store/memory_search/memory_list）才真正按 namespace 路由。

因此 ADR-0001（ruflo-migrations plugin contract）将 Skill 中带 namespace 参数的agentdb_hierarchical-*调用修正为memory_*家族（migrate-create Skill 使用mcp__plugin_ruflo-core_ruflo__memory_store --namespace migrations，migrate-validate Skill 使用memory_search/memory_list做命名空间读取）。同一错误的先例见 ruflo-cost-tracker 与 ruflo-market-data 的 ADR-0001，其命名空间约定以 ruflo-agentdb ADR-0001 "Namespace convention" 为权威依据。

在验证场景中还存在一条双路径存储约定（源自 ruflo-cost-tracker ADR-0001 的 dual-path 模式）：

模式存储（类型化，推荐）：mcp__plugin_ruflo-core_ruflo__agentdb_pattern-store携带type: 'migration-validation'，不传 namespace 参数，由 ReasoningBank 路由；
普通存储（可命名空间路由）：mcp__plugin_ruflo-core_ruflo__memory_store --namespace migrations，将校验结果绑定到具体迁移编号。

命名空间协调（见 README Namespace coordination 章节）：本插件拥有migrations命名空间，用于追踪迁移元数据、应用/待执行状态与校验结果；pattern、claude-memories、default三个保留命名空间严禁被遮蔽。

七、神经学习与记忆学习：让迁移经验持续沉淀

migration-engineer在成功创建或校验迁移后，会触发两个学习通道，将经验沉淀进系统：

神经学习（Neural Learning）——训练迁移模式：

npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --train-neural true npx @claude-flow/cli@latest neural train --pattern-type migrations --epochs 10

记忆学习（Memory Learning）——存储迁移模式与校验结果：

npx @claude-flow/cli@latest memory store --namespace migrations --key "migration-NNN_NAME" --value "MIGRATION_METADATA_JSON" npx @claude-flow/cli@latest memory store --namespace migration-patterns --key "pattern-PATTERN_NAME" --value "PATTERN_JSON" npx @claude-flow/cli@latest memory search --query "migrations adding foreign keys" --namespace migrations

migrate-create Skill 提供了等效的 CLI 替代写法：

npx @claude-flow/cli@latest memory store --namespace migrations --key "migration-NNN_NAME" --value '{"number": NNN, "name": "NAME", "status": "pending"}'

这使后续迁移能通过agentdb_pattern-search检索相似历史模式，让"如何为外键建索引""如何安全 DROP 列"等经验可复用，而非每次从零推理。

八、验证契约：smoke.sh 十条检查

ruflo-migrations 以 scripts/smoke.sh 作为契约级验证手段，预期输出10 passed, 0 failed（ADR-0001 的 Verification 章节与 README 均明确此标准）。十条结构性检查覆盖：

plugin.json声明版本0.2.1且包含mcp、dry-run、up-down-pairs关键词（实际插件清单见.claude-plugin/plugin.json）；
两个 Skill + Agent + Command 存在且 frontmatter 合法（name:、description:、allowed-tools:）；
/migrate命令覆盖 6 个子命令（create/up/down/status/validate/history）；
migrate-create 使用memory_store（命名空间路由）且不再残留agentdb_hierarchical-store带 namespace 的调用；
migrate-validate 使用memory_search/memory_list做命名空间读取，不再使用agentdb_hierarchical-recall；
migrate-validate 文档化双路径存储（同时出现 "ReasoningBank" 与memory_store --namespace migrations）；
README 将 CLI 固定到@claude-flow/cliv3.6（major+minor）；
README 遵守 ruflo-agentdb 命名空间约定（引用 "Namespace convention"）；
ADR-0001 存在且状态为 Accepted；
Skill 的allowed-tools中无通配符（*）授权。

安装与验证方式：

claude --plugin-dir plugins/ruflo-migrations bash plugins/ruflo-migrations/scripts/smoke.sh # 预期: "10 passed, 0 failed"

九、与生态插件的协同边界

migration-engineer文档明确了与四个相邻插件的分工，避免职责重叠：

ruflo-security-audit：检查迁移中的 SQL 注入漏洞与权限提升风险——本 Agent 只做结构校验，安全审计交由其完成；
ruflo-adr：将 schema 变更决策记录为架构决策记录（ADR）——解决"为什么这样改"；
ruflo-ddd：将迁移边界与 DDD 聚合根、限界上下文对齐——解决"改动边界划在哪"；
ruflo-observability：追踪迁移执行耗时与失败率——解决"迁移跑得怎么样"。

十、实践建议小结

编号即顺序：坚持 3 位零填充 + snake_case 命名，让migrate up能严格按序执行、migrate down能按逆序精确回滚；
down 不可省：回滚完整性是 Warning 级检查，但生产环境中缺失 down 脚本的迁移会直接堵死回滚通道，建议视作 Error 处理；
dry-run 先行：任何应用到生产库的迁移，先跑migrate up --dry-run预览 SQL；
命名空间纪律：写入migrations命名空间务必使用memory_*工具族；agentdb_pattern-*用于类型化模式存储时不传 namespace；
以 smoke 为门禁：插件改动必须通过 smoke.sh 的 10 项契约检查方可合并。