ruflo-migrations 迁移创建实战用 migrate-create 技能生成可回滚的 up/down SQL 迁移对【免费下载链接】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一个部署多智能体系统、协调自主工作流与对话式 AI 的 agent meta-harness 项目中ruflo-migrations插件负责数据库 schema 迁移的全生命周期管理。本文围绕migrate-create技能plugins/ruflo-migrations/skills/migrate-create/SKILL.md展开讲解如何通过顺序编号生成NNN_name.up.sql与NNN_name.down.sql迁移文件对、如何按命名自动选择 SQL 模板、如何在 AgentDB 中记录迁移元数据并结合migrate命令的六大子命令与源码级实现细节让你掌握一套可直接落地的生成 — 校验 — 预演 — 应用 — 回滚的迁移工作流。一、migrate-create 技能定位与适用场景migrate-create是ruflo-migrations插件对外暴露的两个技能之一另一个是migrate-validate其职责非常聚焦为数据库 schema 变更生成一条带顺序编号的新迁移并产出成对的 up/down SQL 文件。它的 frontmatter 定义如下--- name: migrate-create description: Create a new sequentially numbered database migration with up/down SQL files argument-hint: name allowed-tools: Read Write Glob Bash mcp__plugin_ruflo-core_ruflo__memory_store mcp__plugin_ruflo-core_ruflo__memory_search mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search ---从argument-hint: name可以看出调用方式是/migrate-create name其中name是用 snake_case 书写的、能简洁描述这次变更意图的名称例如create_users或add_email_index。何时使用它当你需要对 schema 做出如下改动时创建表creating tables添加列adding columns创建索引creating indexes修改约束modifying constraints任何会改变数据库结构、且需要留下可审计、可回滚痕迹的变更都应当走迁移而不是直接手写 DDL。插件 README 给出的完整迁移文件布局印证了这一约定plugins/ruflo-migrations/README.mdmigrations/ 001_create_users.up.sql 001_create_users.down.sql 002_add_email_index.up.sql 002_add_email_index.down.sql二、migrate-create 七步工作流详解技能正文定义了一条完整的 7 步执行链路。下面逐步展开并补入仓库中可验证的细节。步骤 1确定下一个编号Determine next number使用Glob扫描 migrations 目录下已有的迁移文件找出当前最大编号然后加 1并用3 位零填充zero-pad to 3 digits作为新编号。例如目录中最大编号为002则新迁移编号为003这保证了迁移在文件系统层面的字典序即执行顺序。配套的migrate命令plugins/ruflo-migrations/commands/migrate.md对migrate create name子命令定义了同样的流程扫描目录找到最高迁移号 → 计算下一个编号零填充 3 位→ 生成两个文件 → 填充模板 → 记录元数据 → 汇报结果。步骤 2按名称选择 SQL 模板Select template技能根据name的前缀/关键字路由到不同的 SQL 模板名称模式选用模板以create_开头CREATE TABLE 模板以add_开头ALTER TABLE ADD COLUMN 模板以drop_开头DROP 安全检查模板包含indexCREATE INDEX 模板其他带占位注释的通用迁移模板migration-engineeragentplugins/ruflo-migrations/agents/migration-engineer.md中给出了这些模板的完整 SQL 形态我们把它展开成可直接复制的实现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;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;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;注意两个贯穿始终的幂等约定up 文件使用IF NOT EXISTSdown 文件使用IF EXISTS这样无论迁移被重复执行还是回滚都不会因对象已存在/已不存在而报错。这正是插件验证检查表中Idempotency幂等性检查项要求的行为。步骤 3 与 4生成 up / down 迁移文件写NNN_name.up.sql包含正向变更 SQL使用IF NOT EXISTS保证幂等。写NNN_name.down.sql包含反向操作 SQL使用IF EXISTS保证可安全回滚。up/down 成对是回滚安全rollback safety的根基每条 UP 语句都应有对应的 DOWN 语句migrate-validate 技能会专门检查rollback completeness回滚完整性。步骤 5搜索历史模式Search past patterns调用mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search由 ReasoningBank 路由查找仓库中历史积累的相似迁移模式。技能正文特别强调了一个容易踩的坑不要给它传namespace参数 ——pattern-*工具族会忽略 namespace。这一点来自 ruflo-agentdb ADR-0001 的 namespace 约定详见第五节。步骤 6存储迁移元数据Store metadata调用mcp__plugin_ruflo-core_ruflo__memory_store --namespace migrations记录迁移的编号number、名称name、状态status初始为pending以及文件路径file paths。技能给出的 CLI 等价写法npx claude-flow/clilatest memory store --namespace migrations --key migration-NNN_NAME --value {number: NNN, name: NAME, status: pending}步骤 7汇报结果Report向用户展示迁移编号、创建出的文件路径、使用的模板类型以及步骤 5 中检索到的任何相似历史迁移。三、命名规范与编号约定migration-engineeragent 明确了迁移文件的硬性规范格式NNN_descriptive_name.sql示例001_create_users.sql每条迁移两个文件NNN_name.up.sql与NNN_name.down.sql编号零填充至 3 位名称使用 snake_case简洁描述变更内容。也就是说一条完整的迁移由两个文件构成任何时刻都成对存在migrate-validate 技能在检查命名时还要求表名用复数tables plural、列名用 snake_case、索引名遵循idx_table_column约定。四、配套命令创建之后的完整生命周期migrate-create只是入口创建出来的迁移要真正产生价值还需要与migrate命令plugins/ruflo-migrations/commands/migrate.md的其他子命令配合。插件共提供 6 个子命令migrate create name # Create NNN_name.up.sql and NNN_name.down.sql migrate up [--dry-run] # Apply pending migrations (or preview SQL) migrate down [--steps N] # Rollback last N migrations (default: 1) migrate status # Show applied/pending migration status migrate validate # Validate pending migrations for safety migrate history # Show full migration execution historymigrate up [--dry-run]的执行逻辑从迁移历史中确认哪些迁移已应用按顺序找出所有未应用pending的迁移若带--dry-run仅展示每条待执行迁移的 SQL不实际执行—— 这是预演preview能力用于应用前人工审查若不带--dry-run则按顺序执行每个.up.sql文件并记录结果将执行结果成功/失败、耗时存入migrationsnamespace汇报已应用的迁移、总耗时、错误。migrate down [--steps N]默认回滚最近 1 条迁移从历史中找到最近应用的迁移按逆序执行对应的.down.sql并记录回滚结果。migrate status列出目录中全部迁移文件与已应用历史交叉比对展示每条迁移的编号、名称、状态applied/pending、应用日期与耗时。migrate history回放migrationsnamespace 中的全部执行记录展示方向up/down、时间戳、耗时与状态并高亮需要关注的失败迁移。五、AgentDB 命名空间路由memory_* 与 agentdb_hierarchical-* 的本质区别migrate-create 技能反复强调一个关键事实这也是插件 ADR-0001plugins/ruflo-migrations/docs/adrs/0001-migrations-contract.md修复的核心 bug 类别memory_*工具族按 namespace 路由而agentdb_hierarchical-*工具族按 tierworking|episodic|semantic路由agentdb_pattern-*工具族按 ReasoningBank 路由—— 它们都会忽略传入的 namespace 字符串。历史上migrate-create / migrate-validate 两个技能曾用agentdb_hierarchical-*和agentdb_pattern-store携带 namespace 参数结果写入/读取被静默忽略silent ignored-namespace属于真实 bug。ADR-0001 的修复方案就是namespaced 读写一律改用memory_*工具族同时保留 pattern 的 ReasoningBank 路径pattern 工具不传 namespace。这条约定源自ruflo-agentdb的 namespace 契约plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md命名约定plugin-stem-intentkebab-case例如browser-sessions、claude-memories、pattern三个保留 namespacepattern、claude-memories、default不得被遮蔽migrations是ruflo-migrations插件声明的专属 namespace插件名即意图时 kebab-case 隐含与federation同一例外。在技能层面migrate-create 使用memory_storememory_searchagentdb_pattern-search的组合migrate-validate 则额外暴露了双路径dual-path源自 ruflo-cost-tracker ADR-0001 模式Pattern store类型化推荐agentdb_pattern-store传type: migration-validation不传 namespace由 ReasoningBank 路由Plain store可路由 namespacememory_store --namespace migrations记录绑定到具体迁移号的校验结果。六、质量门禁验证检查矩阵与 smoke 契约创建迁移后应当运行/migrate-validate在应用前把问题拦截下来plugins/ruflo-migrations/skills/migrate-validate/SKILL.md。其检查项按严重级别分级检查项级别说明外键目标存在Error被引用表/列必须存在当前 schema 或先前迁移中索引覆盖WarningWHERE/JOIN 用到的列应有索引数据类型兼容ErrorALTER COLUMN 的目标类型必须兼容NOT NULL 无默认值Error添加 NOT NULL 列必须带 DEFAULTDown 迁移完整性Warning每条 UP 语句都要有对应 DOWN破坏性操作WarningDROP TABLE / DROP COLUMN / TRUNCATE 需显式确认命名约定Info表名复数、列名 snake_case、索引idx_table_column幂等性Warning使用 IF EXISTS / IF NOT EXISTSmigrate-validate 的完整步骤是Glob列出全部迁移文件并交叉memory_search历史找出 pending →Read解析每个.up.sql/.down.sql→ 检查外键 → 检查 NOT NULL 默认值 → 检查回滚完整性 → 标记破坏性操作 → 检查幂等性 → 检查命名 → 双路径存储校验模式 → 报告每个问题带文件路径与行号。除此之外插件还通过 smoke 脚本把质量要求固化为可执行契约plugins/ruflo-migrations/scripts/smoke.sh期望输出10 passed, 0 failed。10 项结构性检查包括plugin.json版本 0.2.1 且含mcp/dry-run/up-down-pairs关键字两个技能 agent command 齐备且 frontmatter 合法/migrate覆盖 6 个子命令migrate-create 使用memory_store且不再使用agentdb_hierarchical-storemigrate-validate 使用memory_search/memory_list且不再使用agentdb_hierarchical-recall双路径已文档化README 固定claude-flow/cliv3.6README 遵循 ruflo-agentdb namespace 约定ADR-0001 存在且状态为 Accepted技能无通配符工具授权无allowed-tools: *。插件元数据plugins/ruflo-migrations/.claude-plugin/plugin.json同样以migrations、schema、rollback、mcp、dry-run、up-down-pairs关键字描述了这些能力边界。七、安装、验证与协作生态安装插件claude --plugin-dir plugins/ruflo-migrations验证契约bash plugins/ruflo-migrations/scripts/smoke.sh # Expected: 10 passed, 0 failed兼容性前提插件固定使用claude-flow/cliv3.6 的 majorminorpinning 策略见 plugins/ruflo-migrations/docs/adrs/0001-migrations-contract.md。该插件为文档型插件不通过 package.json 固定依赖smoke 脚本即验证机制。在协作生态中的位置ruflo-agentdbnamespace 约定所有者定义了本文第五节所述路由规则memory_*按 namespace 路由;ruflo-adr为 schema 变更决策补 ADR 文档ruflo-ddd让迁移边界对齐聚合根与限界上下文ruflo-observability跟踪迁移执行耗时与失败率ruflo-security-audit检查迁移中的 SQL 注入风险与权限提升见 plugins/ruflo-migrations/agents/migration-engineer.md 的相关插件说明。此外migration-engineeragent 还提供了迁移完成后的记忆与学习闭环通过memory store --namespace migrations沉淀迁移元数据、memory store --namespace migration-patterns沉淀可复用模式以及用hooks post-task/neural train --pattern-type migrations对迁移模式做神经训练使后续的迁移生成能够借鉴历史成功经验。八、把整个工作流串起来综合以上内容一个完整、可复现的迁移实践流程是创建/migrate-create name或migrate create name—— 自动编号、按名称选模板、生成 up/down 文件对、以memory_store --namespace migrations记录 pending 元数据校验/migrate-validate或migrate validate—— 检查外键一致性、回滚完整性、幂等性、命名约定把 Error/Warning/Info 分级报告出来预演migrate up --dry-run—— 预览待执行 SQL不落库应用migrate up—— 按序执行 up 文件并记录结果回滚migrate down --steps N—— 逆序执行 down 文件审计migrate status/migrate history—— 随时掌握 applied/pending 状态与完整执行历史。这套链路以migrate-create为起点以顺序编号 up/down 成对 namespace 元数据 smoke 契约为四条主线构成了 ruflo 生态中一套可靠、可审计、可回滚的数据库 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考