Cline 迁移 Skill 实战：Schema、数据、配置与 API 迁移的可回滚方法论与工程落地

迁移是软件演进中最容易出错、最难回头的操作之一——无论改的是数据库 Schema、存量业务数据、配置文件格式还是对外 API 契约。本篇文章以 Cline 开源仓库中 agents-squad 插件自带的 migration Skill（sdk/examples/plugins/agents-squad/skills/migration.md）为主体骨架，结合该 Skill 的加载机制与仓库源码，完整讲解从「评估范围、选择迁移策略、编写四类迁移、测试、上线执行到事后报告」的端到端流程。读完你将掌握一套可直接交给 Cline Agent 与子代理执行的迁移操作手册，并能自行撰写、注册一份属于自己的迁移 Skill。

先认清你面对的是什么：一个 Skill 文件及其加载机制

migration.md 不是一个独立运行的脚本，而是一份 Skill 定义：通过 Markdown + YAML Frontmatter 把一段可复用的「专家级操作指令」打包起来，供 Agent 按需加载。

文件头部的 Frontmatter 是这个 Skill 的元数据与触发依据：

---
name: migration
description: Plan and execute data or schema migrations — database, config, and API migrations with rollback strategies.
---

• name：Skill 的唯一标识，也是 get_skill 工具按名查找时的键；
• description：告知 Agent「何时该启用这份 Skill」——当任务涉及数据库 Schema、数据转换、配置格式或 API 版本演进时，这段描述就是触发信号。

在 agents-squad 插件中，Skill 与 Agent 定义一样都以 Markdown 文件放在约定目录里。从插件入口 sdk/examples/plugins/agents-squad/index.ts 可以看到它们的解析与加载链路：

• 内置 Skill 目录 BUNDLED_SKILLS_DIR 指向插件同级目录 skills/（index.ts）；
• parseFrontmatter 先剥离 UTF-8 BOM 再解析 --- 包裹的 YAML 元数据，正文部分即 content（index.ts）；
• readSkillDefinitions 会按 内置（bundled）→ 全局（~/.cline/data/settings/skills/，见 index.ts）→ 项目（<cwd>/.cline/skills/） 的顺序加载并覆盖同名 Skill（index.ts）——因此你也可以放一份自定义的 migration Skill 去覆盖内置版本；
• 运行时通过 list_skills 枚举可用 Skill，通过 get_skill 把某份 Skill 的完整指令注入给子代理（index.ts）。

这与 Cline 的 Skill 通用机制一致：docs/customization/skills.mdx 中说明 Skill 采用渐进式加载——只有 name 与 description 元数据常驻上下文，SKILL.md 正文在被触发时才加载，因此 migration 这类 Skill 平时不占用任何 token，只有真正要动手迁移时才被激活。本文后半部分的六步流程，正是这份 migration.md 被激活后要求 Agent 严格执行的正文内容。

第 1 步：评估迁移范围（Assess Scope）

动手写任何迁移代码之前，先把边界摸清楚。migration.md 要求围绕四个问题做侦查式提问：

问题	关键决策点
What is being migrated?（迁移对象）	Schema / 数据 / 配置 / API 契约，四者的工具链与风险完全不同
How much data is affected?（影响数据量）	行数、文件数、消费者数量，决定批处理与验证策略
What is the downtime tolerance?（停机容忍度）	零停机（zero-downtime）/ 维护窗口（maintenance window）/ 可离线（offline）
What systems depend on the current state?（依赖方）	谁读老字段、谁调老接口、谁消费老格式

这一步在仓库里天然有执行者：agents-squad 内置的 phantom 子代理定位正是「快速代码库侦察、映射结构、梳理约定，绝不实施修改」，适合承担依赖方与影响面盘点；而 oracle 子代理的职责是「挑战前提、识别隐藏假设、估算复杂度」sdk/examples/plugins/agents-squad/agents/oracle.md，可以对「迁移目标是否真的是正确的目标」这一前提发起反问——这正是评估阶段需要的批判视角。

第 2 步：规划迁移策略与回滚计划

策略选择（Strategy Selection）

migration.md 给出了三种经典迁移策略及各自的适用前提：

• Expand-Contract（扩展-收缩，零停机首选）

  1. Expand（扩展）：在不删除旧结构的前提下，新增列 / 字段 / 端点，新旧并存；
  2. Migrate（迁移）：回填（backfill）数据，并把所有消费者切换到新格式；
  3. Contract（收缩）：确认无读方后，移除旧的列 / 字段 / 端点。

  它的核心价值在于：任何时刻系统都处于可用状态，单个步骤可独立回滚，因此是零停机迁移的默认答案。

• Blue-Green（蓝绿）：新旧两套版本并行运行，通过切换流量完成上线。适合「无法原地渐变」的场景，但通常需要双份资源与流量入口支持。

• Big Bang（一次性爆炸迁移）：将系统整体下线 → 迁移 → 再上线。仅在数据量小或停机可接受时使用——它在执行窗口内最简单直接，但风险面与停机时间也是最大的。

回滚计划（Rollback Plan）

migration.md 明确要求：任何迁移在开始执行之前都必须先有回滚计划。需要回答四个问题：

• Can the migration be reversed with a down migration?（是否可用 down migration 逆向？）
• Is there a backup of the current state?（当前状态是否有备份？）
• What is the point of no return, if any?（是否存在不可逆点？）
• How long does rollback take?（回滚需要多久？）

值得强调的是，把「回滚条件显式写进计划」这一要求，与仓库里 oracle 子代理的系统提示不谋而合——它被要求产出「编号的、按依赖排序的、可直接执行的步骤列表，并包含显式检查点与回滚条件」（见 sdk/examples/plugins/agents-squad/agents/oracle.md）。也就是说：当这套插件运行迁移类任务时，规划环节天然会输出一份带检查点与回滚条件的执行方案。

第 3 步：按类型编写迁移（Write the Migration）

migration.md 将迁移拆成数据库、数据、配置三类，各自有不同的纪律。API 版本迁移虽未单列成小节，但其约束（只增不删、先废弃后移除）与「API 契约演进」紧密相关，同样值得在编写时套用下述原则。

数据库迁移（Database Migrations）

• 每个逻辑变更对应一个独立迁移文件（one migration file per logical change）；
• 每个文件必须同时包含 up 与 down 两个函数——down 是回滚计划的代码实现；
• 数据库支持事务时必须使用事务包裹，保证原子性；
• 绝不把数据变更和 Schema 变更混在同一个迁移里——两者回滚与验证的节奏完全不同；
• 必须用接近生产规模的数据量做测试，而不是只在空表上验证，否则索引、锁与超时问题会在上线后爆发。

数据迁移（Data Migrations）

数据迁移面对的是存量行，纪律集中在「可中断、可续跑、可核对」：

• 分批处理（process in batches），避免内存耗尽与锁竞争（lock contention）；
• 记录进度：输出「已处理 X / Y 条记录」这类日志，便于监控与断点恢复；
• 处理部分失败：让迁移具备幂等性（idempotent），保证可以安全地重复执行；
• 迁移后校验：行数对比（row counts）、校验和（checksums）、抽样检查（spot checks），证明数据真的搬对了。

幂等设计可以进一步落地为：以主键或业务键判断记录是否已处理；写入采用「先查后写」或 UPSERT 语义；每批之间设置检查点，失败时从上一检查点续跑。

配置迁移（Config Migrations）

配置往往伴随注释、顺序与人类可读性，因此规则是：

• 读旧格式 → 写新格式 → 往返校验（round-trip validation），确保新格式能无损表达旧配置的全部语义；
• 尽量保留注释与字段顺序，减少 diff 噪音与评审成本；
• 必须提供一个用户可直接运行的 CLI 命令或脚本，而不是把迁移逻辑散落在应用启动代码里。

从仓库实现看，Cline 自身的配置体系同样遵循「配置带版本、可加载校验」的思路——例如用户指令配置以带 version 的 JSON 结构持久化（见 sdk/packages/core/src/extensions/config/user-instruction-config-loader.ts 及其测试中对 { source, version, files } 形状的校验 user-instruction-config-loader.test.ts）。这说明「版本化 + 校验性加载」正是健壮配置迁移的通用实现形态。

第 4 步：测试（Test）

migration.md 要求迁移在真实执行前经历四重验证：

• 在生产数据的拷贝上运行迁移（而不是测试数据的样本）；
• 迁移后验证应用功能正常——Schema 变了不代表业务逻辑还能跑；
• 运行回滚并验证应用在老状态上同样正常——回滚计划若从未演练过，等于没有回滚计划；
• 若目标是零停机，还需在负载下测试迁移，确认迁移过程不会拖垮在线流量。

这一步可以与 agents-squad 的子代理流水线衔接：phantom 负责侦察与影响面梳理，oracle 产出含回滚条件的计划，anvil（外科手术式实现，读写前先看上下文、严格待在范围内）负责落地迁移代码，最后由 inquisitor（对抗性评审，发现缺陷并按严重度排序）做变更审查（见 sdk/examples/plugins/agents-squad/README.md 中的典型编排示例）。

第 5 步：上线执行（Execute）

执行阶段是对前面所有准备的兑现，migration.md 给出的执行纪律是：

• 开始前先做备份（take a backup before starting）——即使有 down migration，备份仍是最后的保险；
• 在监控下运行迁移：持续关注错误率（error rates）、延迟（latency）、磁盘使用（disk usage）等信号；
• 完成后立即验证成功标准（success criteria），不要等事后报告才发现问题；
• 在约定的监控窗口期内让回滚计划随时待命，窗口结束后方可解除。

把这条与仓库的执行机制对应起来：agents-squad 中每个子代理都是独立的 Cline SDK 会话，通过 ClineCore.create(...) 创建、后台非交互式运行，父代理可用 get_subagent 轮询状态或在结束时收到 steer 消息（见 index.ts 与 README.md）。因此你可以让一个专门子代理执行迁移并回报逐阶段状态，父代理持续监控，任何指标异常时立即触发已备好的回滚。

第 6 步：事后报告（Report）

迁移完成并不等于结束。migration.md 要求最终把以下信息写进报告，为团队留下可审计记录：

• 迁移了什么、为什么迁移（what was migrated and why）；
• 耗时与遇到的问题（duration and any issues encountered）；
• 验证结果（verification results）；
• 回滚状态（rollback status）：可用（available）/ 已失效（expired）/ 无需回滚（not needed）。

「回滚状态」这一项尤其容易被忽略：当监控窗口过去、回滚所需的旧数据或备份被清理后，回滚计划实际上已经过期——在报告中如实标注其状态，才能避免未来误判自己仍有退路。

小结：把 migration Skill 变成团队的迁移操作手册

回到本质：migration.md 的价值不在于教某一套数据库工具，而在于把「先评估、再规划（含回滚）、分类型编写、四重测试、监控执行、透明报告」这一组高信噪比的流程约束写死，让任何模型驱动的 Agent 在执行迁移时都有一套可复用的判断框架。你可以直接复用它：

1. 通过 agents-squad 插件按 README.md 的 Quick start 接入（pluginPaths: ["./examples/plugins/agents-squad"]），用 list_skills / get_skill 按需加载这份 Skill；
2. 将其与 phantom（侦察）→ oracle（规划与回滚条件）→ anvil（实施）→ inquisitor（评审）的子代理编排结合，形成完整的迁移执行流水线；
3. 若需团队自定义，可参照 migration.md 的 Frontmatter 结构（name + description）把改造版放进项目 .cline/skills/ 或全局 ~/.cline/data/settings/skills/，按同名覆盖内置版本——它就会在你下一次真实迁移时被正确触发。