upgradepath

upgradepath

升级依赖很少只需一步。从当前版本到目标版本之间的每个发行版都有各自的破坏性变更，而经过这些版本的顺序也很重要。upgradepath 会为单个依赖规划这条路径。你提供相关信息——名称、当前版本、目标版本，以及你记录的已知发行版及其破坏性变更和弃用标记——它会返回中间各步骤的有序列表、每一步会带来的变更，以及整个路径的判定结果。

不会获取任何信息。版本不会被查询，变更也不会被猜测；计划中的所有信息都来自调用方。只有数值上大于当前版本且不超过目标版本的发行版才会成为步骤，并按升序排列。版本格式为 x.y.z，并按数值比较，因此 01.2.3 和 1.2.3 是同一版本——如果这导致提供的两个发行版重复，就会报错。目标版本必须大于当前版本，否则计划会在选择任何步骤之前被拒绝。

除了步骤，结果还会统计从当前版本开始、按顺序经过每个步骤时跨越的主版本边界数量，并报告最后一个步骤是否实际到达目标版本：发行版列表即使未到达目标版本，也仍会生成计划，但 reaches_target 会明确指出计划并未到达目标。

判定结果按固定优先级决定。没有任何步骤时为 no_path。路径中没有破坏性变更时为 clean。破坏性变更总数不超过 3 时为 manageable，超过 3 时为 major_effort——因此，即使无步骤计划的破坏性变更总数为零，判定结果仍为 no_path。

每个步骤都会按原样返回其版本和破坏性变更，统计变更数量，并报告该发行版是否已弃用（调用方未说明时为 false）。格式错误的输入——包括缺少、为空或非字符串的 name，不符合 x.y.z 格式的版本，缺少、非数组或为空的 releases 列表，格式错误的发行版条目，重复的发行版版本，或不大于当前版本的目标版本——都会产生指出出错路径的验证错误，且不会返回部分结果。未知的额外字段会被忽略，包括发行版条目内的字段。

CLI

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

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

{
  "name": "widgetlib",
  "current": "1.2.3",
  "target": "3.0.0",
  "releases": [
    { "version": "1.3.0" },
    {
      "version": "2.0.0",
      "breaking_changes": ["removed the legacy parser entry point"]
    },
    {
      "version": "2.4.1",
      "breaking_changes": ["renamed the configuration keys", "dropped Node 14 support"],
      "deprecated": true
    },
    { "version": "3.0.0" }
  ]
}

结果以 JSON 格式打印：

{
  "name": "widgetlib",
  "current": "1.2.3",
  "target": "3.0.0",
  "steps": [
    {
      "version": "1.3.0",
      "breaking_changes": [],
      "breaking_count": 0,
      "deprecated": false
    },
    {
      "version": "2.0.0",
      "breaking_changes": ["removed the legacy parser entry point"],
      "breaking_count": 1,
      "deprecated": false
    },
    {
      "version": "2.4.1",
      "breaking_changes": ["renamed the configuration keys", "dropped Node 14 support"],
      "breaking_count": 2,
      "deprecated": true
    },
    {
      "version": "3.0.0",
      "breaking_changes": [],
      "breaking_count": 0,
      "deprecated": false
    }
  ],
  "step_count": 4,
  "total_breaking": 3,
  "majors_crossed": 2,
  "reaches_target": true,
  "verdict": "manageable"
}

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

MCP 服务

npx -y @reneturcios/upgradepath mcp

MCP 客户端配置：

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

工具

• plan_upgrade_path — 根据调用方提供的发行版信息，规划安全的依赖升级路径。

  • name（字符串，必填，不能为空）— 依赖名称
  • current（字符串，必填）— 当前安装的版本，格式为 x.y.z
  • target（字符串，必填）— 目标版本，格式为 x.y.z；必须大于 current
  • releases（数组，必填，至少包含 1 项）— 该依赖的已知发行版；每一项包含：
    • version（字符串，必填）— 发行版版本，格式为 x.y.z
    • breaking_changes（字符串数组，可选）— 此发行版引入的破坏性变更；缺省表示没有
    • deprecated（布尔值，可选）— 此发行版是否已弃用；缺省为 false

  返回 {name, current, target, steps, step_count, total_breaking, majors_crossed, reaches_target, verdict}，其中每个步骤的格式为 {version, breaking_changes, breaking_count, deprecated}。

Docker

docker run -i ghcr.io/cloudcorprecords/upgradepath
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/upgradepath 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