实测三款编程智能体常装错依赖版本
作者用 20 个发生版本或 API 变更的库测试 Claude Code、Codex 和 Gemini,覆盖 34 项检查和 433 次评分运行。明确要求使用当前版本时,66 次运行中只有 32 次选对,旧版代码有时仍能正常运行。
AI 深度解读
你让 Claude Code、Codex 或 Gemini 给项目装「当前版本」的 SDK,它可能装上旧包,跑通代码,再告诉你用的是最新版。作者拿 2026 年发生变更的 20 个库做了两周实验。在允许选错版本的 66 次运行中,只有 32 次用上当前版。
问题往往在第一条 npm 命令就出现了。包注册表怎么标版本、旧包有没有指明去向、报错里有没有写替代 API,都会影响 Agent 接下来写什么。对维护 npm 包和升级项目依赖的人,这些细节比单纯加一页迁移文档更容易检查。
为什么 Agent 能跑通代码,却还在用旧版?
作者设计了 34 项检查,共评分 433 次运行。任务是给小项目加「当前」SDK、升级大版本,或调用已经变更的 API。提示不写版本号,也不指向文档。三个 Agent 各拿到干净项目、网页访问权限、完整的 shell 和 25 分钟,多数任务每个 Agent 跑两次。脚本核对包名、版本、构建和运行结果,以及 Agent 是否向用户交代了自己的操作。作者还翻日志看它实际读过什么。34 项检查里,31 项出现了库维护者可以改善的问题。
32/66 只统计 11 个存在选错空间的库,比如旧包仍然可装,或用户在提示里沿用了旧名字。其余 9 个库通过 npm 或 PyPI 默认就能装到新版,考的是装好后会不会用对 API。

Prisma 解释了 Agent 为什么会主动选旧版。实验时,Prisma 8 的 CLI 候选版已经挂在 latest,但 @prisma/client@latest 仍指向 7.10.1。6 次里有 3 次按「CLI 和 client 的大版本要一致」这条原本正确的规则主动回到 Prisma 7,最终只有 2 次用上 Prisma 8。OpenCode 的问题更隐蔽,旧 @opencode-ai/sdk 仍挂着 latest,6 次有 3 次先选了它,调用 v2 服务时还收到了状态码为 200 的 HTML。Effect v4 沿用原包名并更新 latest,Agent 按惯例安装就能拿到新版及其随包文档。
旧包还在,迁移提示要放在哪里?
Agent 通常先执行 npm view 或 npm install,然后查 node_modules 里的类型、README 和报错,官网排在后面。没有入口指向 llms.txt 时,59 次运行里一次也没打开它。
Hedera 把 JavaScript SDK 迁到了 @hiero-ledger/sdk,但旧 @hashgraph/sdk 仍是 latest,README 也没提搬家。6 次都用旧包写出了正确的签名转账代码,没人打开 Hedera 为此发布的 skill。作者用本地 registry 模拟 npm deprecate 后,有 3 次换到了新包。日志里能看出剩下的提示怎么漏掉的。npm view old-pkg 会在顶部显示弃用信息,npm view old-pkg version 只打印版本号,npm install 则要等选包之后才提示。还有一次输出被 | tail -5 截掉了。
Moss 改包名后,6 次有 3 次选中 @moss-js/moss。模拟弃用后是 4 次,再给旧包发一个补丁版,把迁移说明放到 README 首行,6 次全选对。Video.js 10 也把迁移入口放进了旧 video.js 包,6 次都找到了新的 @videojs/* 包。

用户怎么称呼库也会改变结果。提示写 Brand.dev 时,6 次有 4 次装了冻结的 brand.dev,写 Context.dev 时,6 次都用了新 SDK。LadybugDB 给 skill 补了 Kùzu 已归档的说明,6 次有 5 次把这件事告诉了用户,但仍有 5 次安装了 kuzu。知道该提醒用户,和实际换包,是两个可以分别验证的结果。
Agent 写错 API 时,哪条提示能让它改对?
Kestra 2.0 把 ForEach 换成 Loop,把 json() 换成 fromJson()。没有额外提示的 15 次运行里,6 次写进了旧用法。错误只说类型无效或函数不存在,Agent 只好通过服务端插件列表找答案,其中一次耗尽了 25 分钟,还解压了服务端的 JAR。Claude Code 和 Gemini 都没打开 Kestra 2.0 的文档。对这些运行,报错直接写出 io.kestra.plugin.core.flow.Loop,就能把替代名称送到出错的位置。
作者建议把替代 API 写进类型文件的 @deprecated 标记,并考虑保留一个版本的旧入口,让编译或运行时的诊断能指向新写法。文档里的命令也要能直接跑。Prisma 有一次执行 init 时漏了 --yes,等交互输入等到超时。E2B 有 4 次照抄了自定义 MCP 服务示例里的 install_cmd 和 run_cmd,但网关会忽略这两个字段。作者建议在 CI 里运行文档示例,并把升级说明随包发布。Video.js 把文档放进 @videojs/html,Effect 则随包提供 AGENTS.md 和可运行示例。
项目里的几行迁移说明,和文档 MCP 差在哪?
作者在三个库上各做了 45 次运行,共 135 次。每个库每种条件跑 9 次,分别是无提示、给 llms.txt 入口、提供官方 skill、接入文档 MCP,以及在项目根目录的 AGENTS.md 放入官方迁移指南里的 5 到 13 行。
Camunda 8.10 选当前 Node 客户端的任务,短说明把正确数从 4/9 提到 9/9(p = 0.03)。Video.js 10 的 v8 项目升级任务中,作者报告短说明让 token 用量和工具调用次数都减少了约三分之一(p ≤ 0.001)。Kestra 2.0 的各渠道差异没有达到统计显著。文档 MCP 在 27 次里只被调用 16 次,Codex 的 9 次全走了其他路径。skill 在 27 次里都被读了,但没有测出收益。llms.txt 有明确入口后,27 次里有 23 次跟了过去。

模型已经知道的迁移也会影响结果。Expo 的替代模块在 2025 年就已发布,尽管旧模块仍挂着 latest 且未弃用,12 次全选了替代品。作者用下面的命令探测 Claude 对某个版本的记忆。
claude -p "From memory, no tools: do you know <package> version <N>? Install command and a 10-line example, or say UNKNOWN." --tools ""
末尾的 --tools "" 关闭工具,结果反映的是模型在该提示下能答出什么。真正的升级还要核对依赖和代码。
我的判断
我认同先修默认安装入口,再把简短迁移说明放进项目。latest 和旧包 README 会在选包时出现,项目里的 AGENTS.md 可以提前写清目标包名、版本和替代 API。文档 MCP 适合提供更广的查询范围,不过这组实验里,工具是否真的被调用已经影响了它能发挥多少作用。
这里的 32/66 是这组特定任务的结果。每项检查只有一种任务表述,每个 Agent 通常只跑两三次,Hedera 和 Moss 的改动也只在本地 registry 模拟过。把 latest、弃用提示和随包文档作为排查顺序有根据。为旧 API 保留一版 stub 则是作者的经验建议,原文没给单独的对照数据。Video.js 正文说最终都完成了升级,配图的无提示组记为 8/9,原文没交代两处统计口径的差别。
能拿来做什么
- 用 AI 升级前端或 Node 依赖时,把目标大版本、准确包名和必须迁走的 API 写进任务。完成后核对 lockfile、实际 import 和构建结果。
- 维护改名的 npm 包时,用用户还会搜索的旧名字试一次
npm view和安装。弃用消息写上新包名,旧包最后一个补丁版的 README 首行也写明去向。 - 给团队维护一段 5 到 15 行的
AGENTS.md迁移说明,列清要装的包、移除的 API 和对应的新名字。把无交互安装命令和最短可运行示例放进 CI 验证。