rollbackplan

rollbackplan

在压力之下回滚一个版本时，最容易出错的就是顺序：先撤销了迁移，之后才关闭依赖它的功能标记；或者发现被删除的列是唯一没人能重建的列。rollbackplan 会将你已有的版本差异转换成有序计划，确保在任何人动手之前做好准备——先处理功能标记，然后是环境变量，最后按逆序处理迁移。

你需要提供差异中的三个部分：该版本涉及的功能标记、它做出的环境变量变更，以及按应用顺序排列的迁移。计划会按唯一安全的顺序逐项回滚版本：

• 功能标记，按输入顺序排列。 该版本启用的标记会被禁用，禁用的标记会被重新启用，新增的标记会被移除。该版本移除的标记无法简单地切换回去，因此这一步会标记为手动：必须有人将它恢复到发布前的状态。
• 环境变更，按输入顺序排列。 该版本新增的变量会被取消设置。对于已更改或已移除的变量，如果记录了发布前的值，这一步会恢复该值；当 previous_value_known 为 false 时，这一步会标记为手动，因为必须由人工查找旧值。
• 迁移，按输入顺序的逆序排列——最后应用的迁移会最先回滚。具有补偿性 down_id 的迁移会运行对应迁移（down_id 优先，即使 reversible: false 也一样）；可逆迁移会运行自身的向下迁移。没有补偿迁移的不可逆迁移会标记为已阻止：这需要手动恢复数据；只要存在任何已阻止的步骤，计划的 safe 字段就会是 false。

每个步骤都包含其位置（order，从 1 开始）、种类、要执行的操作、目标、具体指令（detail）和风险——normal、manual 或 blocked。结果还会统计步骤总数和各类步骤数，并按风险统计手动步骤和已阻止步骤，以便调用方在人工开始逐项处理前根据 safe 决定是否允许继续。

该计划仅提供建议，不会执行操作：rollbackplan 不会执行任何内容。它不会运行迁移、切换功能标记或修改环境。计算是纯粹的本地操作——不会联网、不会读取配置，也不会读取你提供的输入以外的文件。

格式错误的输入——缺少、为空或不是字符串的 release，不是数组的列表，不是对象的条目，缺少、为空或重复的迁移 id 或变量／功能标记 name，超出枚举范围的 action 或 change，类型错误的 reversible 或 previous_value_known，或为空的 down_id——都会产生验证错误，并指出有问题的路径（例如 migrations[2].id duplicates migrations[0].id "add_orders"），且不会生成部分计划。

CLI

npx @reneturcios/rollbackplan plan --input args.json
npx @reneturcios/rollbackplan --version

args.json 包含完整的参数对象：

{
  "release": "v2.4.0",
  "feature_flags": [
    { "name": "checkout-v2", "change": "enabled" },
    { "name": "old-banner", "change": "removed" }
  ],
  "env_changes": [
    { "name": "TIMEOUT_MS", "action": "changed", "previous_value_known": true },
    { "name": "LEGACY_TOKEN", "action": "removed" }
  ],
  "migrations": [
    { "id": "add_orders_table" },
    { "id": "backfill_orders", "down_id": "clear_backfill" },
    { "id": "drop_legacy_table", "reversible": false }
  ]
}

migrations、env_changes 和 feature_flags 均为可选项，默认值为 []；每个迁移的 reversible 默认值为 true，每个环境变更的 previous_value_known 默认值为 false。这三个列表都可以为空：此时计划不包含任何步骤，且 safe 为 true。计划会以 JSON 格式输出：

{
  "release": "v2.4.0",
  "steps": [
    { "order": 1, "kind": "feature_flag", "action": "disable", "target": "checkout-v2", "detail": "Disable feature flag checkout-v2 (enabled by this release)", "risk": "normal" },
    { "order": 2, "kind": "feature_flag", "action": "restore", "target": "old-banner", "detail": "Feature flag old-banner was removed by this release; recreate it in its pre-release state", "risk": "manual" },
    { "order": 3, "kind": "env", "action": "set", "target": "TIMEOUT_MS", "detail": "Restore environment variable TIMEOUT_MS to its recorded pre-release value", "risk": "normal" },
    { "order": 4, "kind": "env", "action": "restore", "target": "LEGACY_TOKEN", "detail": "Environment variable LEGACY_TOKEN was removed by this release and its pre-release value is not recorded; restore it manually", "risk": "manual" },
    { "order": 5, "kind": "migration", "action": "manual", "target": "drop_legacy_table", "detail": "Migration drop_legacy_table is irreversible and has no compensating migration; manual data recovery is required", "risk": "blocked" },
    { "order": 6, "kind": "migration", "action": "run_down_migration", "target": "clear_backfill", "detail": "Run compensating migration clear_backfill to undo backfill_orders", "risk": "normal" },
    { "order": 7, "kind": "migration", "action": "run_down_migration", "target": "add_orders_table", "detail": "Run the down migration for add_orders_table", "risk": "normal" }
  ],
  "counts": { "steps": 7, "feature_flags": 2, "env_changes": 2, "migrations": 3, "manual": 2, "blocked": 1 },
  "safe": false
}

退出代码：成功时为 0，运行时错误时为 1（包括输入文件无法读取或无效，以及输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/rollbackplan mcp

MCP 客户端配置：

{
  "mcpServers": {
    "rollbackplan": {
      "command": "npx",
      "args": ["-y", "@reneturcios/rollbackplan", "mcp"]
    }
  }
}

工具

• plan_rollback — 根据差异规划版本回滚。

  • release（字符串，必填，非空）— 正在回滚的版本标识符或版本号
  • migrations（数组，可选，默认 []）— 按应用顺序排列的迁移，格式为 {id, reversible?, down_id?} 对象；id 在集合中唯一， reversible 默认为 true
  • env_changes（数组，可选，默认 []）— 格式为 {name, action, previous_value_known?} 对象的变更；action 的值为 added、changed、 removed 之一，previous_value_known 默认为 false
  • feature_flags（数组，可选，默认 []）— 格式为 {name, change} 对象的变更；change 的值为 enabled、disabled、added、removed 之一

  返回 {release, steps, counts, safe}。

Docker

docker run -i ghcr.io/cloudcorprecords/rollbackplan
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/rollbackplan plan --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios