stalemap

安装 · 示例 · 工作原理 · 结果 · 更新日志

编码 Agent 从训练数据中学习库的用法，但这些数据会在某个截止日期停止更新。当项目锁定的版本较新时，Agent 会针对旧 API 编写代码：针对 AI SDK 7 使用 maxSteps，针对 zod 4 使用 required_error，针对 Next 16 使用 middleware.ts。

stalemap 会找出在模型训练截止日期后发生变化的依赖，并通过三种方式告诉 Agent 这些变化：

• 备注： 将简短的变更列表按优先级写入 AGENTS.md 或 CLAUDE.md，让 Agent 在开始工作前先阅读。
• 编辑时防护： 每次编辑后运行项目自身的类型检查。如果代码使用了截止日期后发生变化的 API，Agent 会立即收到编译器错误和对应的备注（或解释该变化的发行说明或升级指南章节）。它还会报告那些仍能通过编译、但使用了已迁移内容的代码。
• search_changes： Agent 可以用自己的措辞调用的 MCP 工具，例如“在 next.config 中解析 alias”，以获取匹配的变更及其来源。

它支持 JavaScript 和 TypeScript 项目，可与 Claude Code、Cursor、Codex、OpenCode 或任何 MCP 客户端配合使用。

在一项盲测、预注册的基准测试中，针对 66 个由 2026 年 6 月之后发布的变更构建的任务，使用 claude-sonnet-5-5 的 Agent 在启用 stalemap 时，89% 的会话通过；没有辅助时为 68%，每次编辑后运行普通 tsc --noEmit 钩子时为 73%。请参阅结果。

状态

• npm： 最新版本为 stalemap 0.4.1：它是在留出测试集 v4（0.4.0）中通过测试的构建版本基础上，给备注区块加上了一行页脚。npx stalemap、Claude Code 插件和 GitHub Action 均会运行该版本。请参阅更新日志。
• 项目尚处于早期阶段，由一人维护。

安装

Claude Code 插件

/plugin marketplace add Umair/stalemap
/plugin install stalemap@stalemap

该插件包含：

• 一个 SessionStart 钩子，会将适用于当前会话所用模型的备注放入 Claude 的上下文中（在启动、/clear 之后以及压缩之后触发；不会写入任何文件）；
• 一个 PostToolUse 钩子，会在每次 Write 或 Edit 后运行编辑时防护；
• stalemap MCP 服务和两个技能（/stalemap:sync 用于写入备注区块；upgrade 会提示 Claude 在使用或升级某个软件包前查询其变更）。

钩子和 MCP 服务会运行 npx -y stalemap@latest，因此使用的是最新 npm 版本。其 MCP 工具包括 search_changes、package_changes、project_changes 和 check_notes。

命令行

npx stalemap            # preview what changed and the block it would write
npx stalemap sync       # write the block into AGENTS.md or CLAUDE.md
npx stalemap check      # for CI: exit 1 when the block is missing or stale
npx stalemap guard src/**/*.ts   # run the guard by hand

代码块位于 和 之间。块外的文本不会被修改。Claude Code 会读取 CLAUDE.md；如果你的备注位于 AGENTS.md 中，请将 @AGENTS.md 添加到 CLAUDE.md，或传入 --target CLAUDE.md。

其他 Agent：setup --agent

stalemap setup --agent cursor             # or codex, opencode, claude
stalemap setup --agent codex --dry-run    # print the changes, write nothing

每个 Agent 只需运行一条命令，即可写入备注、注册 MCP 服务，并将防护程序安装为该 Agent 的编辑后钩子，相关内容会作为项目文件保存，方便你提交。它会合并到现有配置文件中，保留未由它写入的条目，重复运行也不会产生任何更改。

有一点需要注意：目前还没有在真实的 Cursor、Codex 或 OpenCode 安装环境中测试过。Cursor 目前不会将 postToolUse 钩子的上下文传递给模型，因此 setup 会添加一个停止钩子作为后备，将未报告的发现作为后续消息发送。

任意 MCP 客户端

{ "mcpServers": { "stalemap": { "command": "npx", "args": ["-y", "stalemap@latest", "mcp"] } } }

GitHub Action

- uses: Umair/stalemap@main
  with:
    model: claude-opus-5-5          # fail CI when the notes are missing or stale
    # mode: comment                 # or comment on PRs that change dependencies

评论模式需要 permissions: pull-requests: write。它会列出每个已更改的依赖项（模型已知的版本 → 锁定的版本）及其备注，并在后续推送时更新评论。

备注的样式

对于使用 claude-sonnet-4-5 的 Next.js + AI SDK 应用（截止日期为 2025-07-31），摘录如下：

**ai** 4.3.16 → 7.0.142 (major)
- `CoreMessage` was removed; use `ModelMessage`. [types]
- `convertToCoreMessages` was removed; use `convertToModelMessages`. [types]
- `streamText()` options no longer accept `maxTokens`, `maxSteps`, `toolCallStreaming`, … [types]

**next** 15.4.0 → 16.4.2 (major)
- `revalidateTag()` now requires `profile` (in `next/cache`) [types]
- `NextMiddleware` is deprecated: Use `NextProxy` instead. Middleware has been renamed to Proxy. (in `next/server`) [types]

完整输出：examples/next-ai-app.claude-sonnet-4-5.md。

工作原理

1. 使用哪个模型？ 通过 --model 指定，或使用为 Claude Code、Codex、OpenCode 或 Gemini CLI 配置的模型，或 $ANTHROPIC_MODEL。训练截止日期来自 models.dev（内置备用表），也可以传入 --cutoff YYYY-MM-DD。
2. 模型知道什么？ 对每个依赖项，查找在截止日期至少 30 天前发布的最新稳定版本（--margin）。
3. 检查哪些依赖项？ 你的代码导入的直接依赖项（在本地扫描），以及配置文件配置的依赖项（tsconfig.json、next.config.*、Prisma schema、Vitest 和 ESLint 配置等）。--all 会检查所有直接依赖项。固定版本来自 node_modules 或锁文件（npm、pnpm、yarn、bun）。
4. 发生了哪些变化？
   • 类型： 下载两个版本的 .d.ts 文件，并通过 TypeScript 编译器 API 进行比较：已移除、重命名和移动的导出、新增的必需参数、已移除或新增的必需选项，以及新增的 @deprecated 标签及其提示。
   • 发行说明： 软件包的变更日志或 GitHub Releases，并根据破坏性变更信号和你使用的 API 进行评分。若变更日志宣布了重命名，移除项会标出其替代项。
   • 升级指南（--guides）：针对从未体现在类型签名中的变化，例如新的默认值或重命名的文件约定。Claude 会将每篇指南整理成简短说明，且只有引用了指南内容的说明才会保留。
   • 已验证示例（--examples）：在顶部说明下方提供一行 Before → After，由 Claude 编写，且只有能通过你固定版本编译的示例才会保留。
5. 控制预算。 优先展示与你的项目实际用法相关的说明：导入的 API、成员和属性、项目设置的配置项、文件名。默认预算为 1,800 个 token（--budget）。

守护程序会在每次编辑后运行。它会运行项目自己的 tsc 并按以下顺序报告发现的问题：

1. 截止日期后发生变化的依赖项所导致的编译错误，并附上相应说明作为修复建议。如果没有说明能解释该错误，它会根据错误和错误附近的代码进行搜索，展示软件包类型变更、发行说明或升级指南中的相关部分。
2. 类型检查仍能通过但已发生变化的内容：
   • 已移动的配置项（Next 16 中的 experimental.ppr）；
   • 已移动的成员（axios 1.20 中的 HttpStatusCode.PayloadTooLarge → ContentTooLarge）；
   • 已重命名的文件约定（middleware.ts → proxy.ts）；
   • 项目的 TypeScript 不接受的 tsconfig.json 选项。
3. 编译器报告的其他错误：已编辑文件中的错误、导入该文件的文件中的新增错误，以及其他少量错误。这些错误并不表示依赖项发生了变化。

因此，纯类型检查钩子只是守护程序的一个子集。STALEMAP_GUARD_TSC=0 会将守护程序限制为检查依赖项变更。只有设置 STALEMAP_GUARD_DEPRECATIONS=1 才会报告弃用项。

search_changes（也可使用 stalemap search <query>）会搜索 stalemap 为项目依赖项找到的所有内容：每项类型变更、每条发行说明、缓存的升级指南说明，以及新主版本对应指南的正文。排序使用基于词语和拆分标识符的 BM25（resolveAlias 可以匹配“resolve alias”），并对项目实际使用的内容加权。首次搜索会根据分析缓存建立索引；之后的搜索无需联网且速度很快。

stalemap probe 用于衡量模型实际需要哪些说明：它会要求模型针对每项变更编写代码，使用固定版本对答案进行类型检查，然后提供说明再运行一次。对于模型本来就能正确处理的说明，会从说明块中移除。探测任务会指出旧 API，因此它测量的是模型在被明确指出变更后是否了解该变更，这比让模型自行察觉更容易。

运行 stalemap --help 查看所有命令和选项，包括 --llm（由 Claude 编写摘要）以及约 200 个快速迭代软件包的预计算报告（目前尚未托管）。

哪些内容会离开你的机器

• 包名和版本会发送到 npm registry、GitHub（更新日志和发布信息；如有可用，会使用 GITHUB_TOKEN 或你的 gh 登录凭据）以及 models.dev。
• 你的源代码绝不会上传。导入扫描在本地进行。
• 使用 --llm、--examples 或 --guides 时：类型差异、发布说明摘录、指南文本以及你导入的 API 名称会发送到 Claude（Anthropic API 或 claude -p）。不会包含你的代码。
• 使用 probe 时：探测提示词会发送到你选择的提供商。
• 设置 $STALEMAP_PRECOMPUTED_URL 时：发送到该主机的是包名，而非版本。

缓存位于 ~/.cache/stalemap（设置 $STALEMAP_CACHE 可更改缓存位置）。

结果

所有结果均来自无头 Claude Code 会话，并由 Agent 看不到的隐藏测试评分。每项任务都以两种模式运行：单次执行（仅文件工具）和检查模式（Agent 还可以运行 npm test 和 tsc）。置信区间通过两级自助抽样（先抽任务，再抽运行）得出。只有当差异的置信区间不包含零时，才算胜出。

留出 v4（协议、claude-sonnet-5-5 的结果、claude-sonnet-4-5 的结果）采用盲测并预先注册：

• 从 2026 年 7 月至 10 月发布的 33 个热门 npm 包的所有重大变更、弃用和行为变更中，按种子抽样选出 66 项任务；
• 每项任务、实验组、模式和模型各运行 3 个会话；
• 在任何 v4 结果出现之前，将构建冻结为 freeze/v4-final。

配置	claude-sonnet-5-5	claude-sonnet-4-5
仅 Agent	68%	46%
每次编辑后添加普通的 tsc --noEmit 钩子	73%	53%
+ stalemap（笔记、编辑时保护、search_changes）	89%	64%
+ 一行手写提示，指出变更内容（上限）	98%	78%

所有四项预先注册的对比均胜出：

对比	模型	差异	置信区间
stalemap 对比仅 Agent（主要对比）	claude-sonnet-5-5	+20.7 个百分点	[13.6, 28.3]（95%）
stalemap 对比 tsc 钩子	claude-sonnet-5-5	+16.4 个百分点	[7.6, 26.0]（98.3%）
stalemap 对比仅 Agent	claude-sonnet-4-5	+17.9 个百分点	[7.6, 28.8]（98.3%）
stalemap 对比 tsc 钩子	claude-sonnet-4-5	+10.6 个百分点	[0.3, 21.7]（98.3%）

• **单次执行模式最能体现效果：**使用 claude-sonnet-5-5 时，stalemap 的通过率为 89%，无帮助时为 60%。使用检查模式时，分别为 89% 和 77%。
• **更少的过时编辑：**使用 stalemap 时，claude-sonnet-5-5 会话中 Agent 首次编辑使用过时 API 的比例为 11%，无帮助时为 27%。
• 成本：
  • claude-sonnet-5-5：每个会话的中位成本为 $0.050，无帮助时为 $0.041，交互轮数大致相同（7 轮对比 8 轮）。
  • claude-sonnet-4-5：成本更高，为 $0.124 对比 $0.085，耗时为 79 秒对比 47 秒。
• **当前模型仍然需要它。**即使是 claude-sonnet-5-5，单独使用也会有三分之一的任务失败，而一行提示几乎能修复所有失败。stalemap 弥补了其中约三分之二的差距。
• 未发布与第三方工具的对比结果。

早期测试套件（均使用 claude-sonnet-4-5）：

• 留出 v1（预先注册，10 项任务）：通过率为 83%，仅 Agent 时为 50%，胜出。
• 留出 v2（盲测，10 项任务）：通过率为 35%，仅 Agent 时为 23%，打平。
• 留出 v3（盲测，59 项任务）：通过率为 53%，仅 Agent 时为 43%，胜出。与普通 tsc 钩子打平。0.3 和 0.4 中的改动源自 v3 记录揭示的问题：保护机制没有运行项目自带的 TypeScript，笔记和搜索丢失了修复文本，搜索也没有得到充分使用。v4 是首次对这些改动进行的盲测。

请注意：

• **作者相同。**stalemap、测试框架和协议均由同一作者编写。v4 的任务由一个独立会话编写，该会话从未见过 stalemap 的代码、笔记或结果。另有一位独立且同样在盲测条件下的审阅者对任务进行了检查并应用了试点规则。任务、隐藏测试、抽样文件、审阅、试点和各会话结果都在 bench/ 中，供你查验。
• **JavaScript 和 TypeScript，两种 Claude 模型。**未测量其他 Agent 和模型。
• **预先注册与事后分析。**只有在运行前协议中确定的对比才算作结论。v3 之后所做的改动属于事后分析，因此需要进行 v4 测试。

限制

• 仅支持 JavaScript 和 TypeScript，且只支持一个 package.json（暂不遍历工作区）。
• 未捆绑类型的包仅提供发布说明（不会比较 @types/*）。
• 用法跟踪仅覆盖导入的名称和 x.member 访问；不会跟踪 client.messages.create({ temperature }) 这样的实例链。
• 未反映在类型签名中的行为变更，只能从发布说明以及（使用 --guides 时）升级指南中获取。如果两者都未提及相关设置，stalemap 也无从得知。
• 发布说明的排序采用启发式方法，对散文较多的变更日志来说结果可能不够准确。
• Agent 有时会忽略正确的说明。守护工具会捕获无法通过编译的问题，以及一些仍能通过编译的问题（键和成员已迁移、文件已重命名）；其他仍能通过编译的过时代码，只有在说明中有所提及时才会被捕获。

运行基准测试

测试框架、任务、协议和结果都位于 bench/。简而言之：

npm install && npm run build
mkdir -p bench/.work/template-heldout-v4-latest && cp bench/heldout-v4/templates/latest/*.json bench/.work/template-heldout-v4-latest/
(cd bench/.work/template-heldout-v4-latest && npm install --ignore-scripts)
npx tsx bench/heldout-v4/validate.ts      # reference solutions pass, stale versions fail
npx tsx bench/run.ts --suite heldout-v4 --model claude-sonnet-5-5 --arms alone,stalemap-full,tsc-hook,oracle --examples --guides --reps 3
npx tsx bench/analyze.ts bench/results/<dir>

会话使用当前登录的 Claude Code 运行；完整的 v4 测试每个模型约需 1,600 个会话，因此建议从 --reps 1 或 --tasks 开始。记录会写入 bench/results/<dir>/runs/，该目录已被 Git 忽略。有关测试组、隔离、分片和成本，请参阅 bench/README.md。

开发

git clone https://github.com/Umair/stalemap && cd stalemap
npm install
npm run build       # → dist/cli.js
npm test            # node:test via tsx
node dist/cli.js scan --cwd test/fixtures/next-ai-app --model claude-sonnet-4-5
npm link            # optional: put your local build on your PATH

库的用法：

import { runStalemap, packageChanges, checkBlock } from "stalemap";

const { rendered } = await runStalemap({ cwd: ".", model: "claude-opus-5-5" });

贡献

欢迎提交 Bug 报告、错误或缺失的说明，以及新的基准测试任务。请参阅 CONTRIBUTING.md。如需报告安全问题，请参阅 SECURITY.md。

许可证

MIT