插件也能声明版本要求了：plugin.json 新增 engines["claude-code"]

写过 npm 包的人对 engines 字段不会陌生：在 package.json 里写上 "node": ">=18"，告诉使用者这个包需要什么运行环境。Claude Code 2.1.323 把同样的思路带到了插件上——plugin.json 现在可以写 engines["claude-code"]，声明插件兼容的 Claude Code 版本范围。

解决了什么问题

插件常常会用到新版 Claude Code 才有的能力：新的钩子事件、新的 settings 字段、新的命令参数。以前插件作者没办法表达「我至少需要某个版本」，结果就是：

• 团队里有人还在用旧版 CLI，装上插件后某些功能静默失效；
• 报错信息和版本无关，排查半天才发现是客户端太旧；
• 插件作者只能在 README 里写一句「请先升级」，但没人会看。

现在的行为

在 plugin.json 里加上版本范围后，Claude Code 会按这个范围做三件事：

1. 不安装：当前版本不在范围内，插件不会被装上；
2. 不更新、不加载：已经装好的插件，如果新版本要求更高，或当前客户端不满足要求，就不会被更新或加载；
3. 自动挑兼容版本：安装和更新时，会在所有版本里挑满足当前客户端的最新那个，而不是一律拿最新版。

第三点对插件作者尤其友好：你可以放心发布只支持新版 CLI 的大版本，还在旧客户端上的用户会自动停在上一个兼容版本，不会被「升级」到用不了的版本。

写法示例

{
  "name": "my-plugin",
  "version": "2.0.0",
  "engines": {
    "claude-code": ">=2.1.323"
  }
}

范围写法可以参照 npm 常见的 semver 表达式习惯；具体支持哪些语法，以官方插件文档为准。

顺带的几处插件改进

同一版本里，和插件开发相关的还有：

• claude plugin validate 会对插件的 TypeScript 钩子模块做类型检查，发现的问题默认只是警告，加 --strict 时会直接判失败，适合放进 CI；
• 插件自带的语言服务器启动失败时，会给出警告，写明是哪个服务器、该检查什么；
• claude plugin install --json 的结果新增 unsetOptionCount，告诉你还有几个 userConfig 选项没填，自动化脚本可以据此提示用户补配置。

建议

• 插件作者：凡是用到较新能力的插件，都把最低版本写进 engines，并在 CI 里跑一遍 claude plugin validate --strict；
• 团队管理员：如果发现某个插件「装不上」或「没加载」，先看看本机 Claude Code 版本是否落在插件声明的范围之外，claude update 升级后再试。

版本要求写进清单，比写在 README 里可靠得多。