Claude Code 插件校验漏过加载崩溃
作者在 Windows 上对 Claude Code mod 人为制造五类故障,发现插件校验能识别其中四类,却放过一个加载即崩溃的案例。文章同时介绍通过钩子扩展工具调用、命令和界面的基本方式。
AI 深度解读
claude plugin validate 显示通过,mod 却在加载时崩溃;更隐蔽的是,原本应该由 mod 接管的 /tally 随后被当成普通提示词发给模型,模型还给出了一份看起来合理的回答。这是作者在 Windows、Claude Code 2.1.302 上实际撞到的问题。
这篇最有价值的地方,是把 mods 的扩展能力和检查边界放在了一起:它能进入 Claude Code 进程、改写事件,也需要承担普通进程内代码的信任成本。对准备写扩展或用 claude -p 接自动化的程序员,这比装上一个演示插件更值得先弄清楚。
mod 为什么能做普通 hook 做不到的事
按原文介绍,Claude Mods 在 2026 年 10 月 1 日随 Claude Code 2.1.287 推出。作者于 11 月 17 日复核文档及截至 2.1.326 的更新记录,但亲自运行实验的版本是 2.1.302,不能把两个范围混在一起。
mod 是带有 hooks 模块的插件,JavaScript 或 TypeScript 直接运行在 Claude Code 自身进程中。settings hooks 则通过配置触发 shell 命令、HTTP 请求或提示词;MCP server 提供工具,skill 提供指令。它们的接入位置不同,能控制的行为也不同。
mod 可以绘制侧边面板、修改 spinner、注册无需模型回合的命令,还能拦住或改写工具调用。每个处理函数接收三个参数:$ 是 mods API,e 是事件,next 用来把事件继续传下去。
理解它只需要区分三种操作:next(e) 观察后放行,next({...e}) 修改后放行,直接返回结果且不调用 next,则由 mod 接管这次事件。

作者照教程制作的计数器只有三个文件:.claude-plugin/plugin.json 声明插件,hooks/hooks.json 用 "modules": ["./register.js"] 指向代码,hooks/register.js 注册处理函数。让普通插件成为 mod 的关键,是 modules 配置;加载 .js、.ts 不需要另装 Node.js、打包器或构建步骤。
下面这段原始代码解决了三个问题:累计工具调用、提供 /tally 查询,以及把计数显示在 spinner 旁边。
let calls = 0
export function register(on) {
on('session.start', async ($, e, next) => {
await $.command.register({
name: 'tally',
description: 'Show how many tool calls Claude has made',
})
return next(e)
})
on('tool.call', async ($, e, next) => {
calls += 1
$.ui.invalidate('ui.render')
return next(e)
})
on('command.run', { command: 'tally' }, async () => {
return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }
})
on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
})
}
重点看 command.run:它直接返回文本,没有调用 next,所以 /tally 无需模型回答。最后一个处理函数则保留原有属性,只改写 suffix。作者没有实测交互界面;spinner 展示和保存后热重载的行为来自教程描述,重载会让 calls 回到 0。
validate 通过,究竟证明了什么
claude plugin validate ./first-mod 读取代码,但不执行代码。它会列出 hooks:、calls:,也会提示 gating hook without .catch: tool.call。这条提示不是验证失败,而是在提醒:能阻止工具调用的处理函数,需要考虑自身出错时怎么办。
作者称自己破坏了 mod 五次,validate 抓住四次,却放过了加载时抛异常的一次。输入原文没有呈现完整的五项对照表,因此无法逐项复核;能明确看到的关键结果,是下面这个由 claude plugin test 捕获的错误:
(fail) /tally reports the tool calls the mod has seen [97.34ms]
HooksError: first-mod: hooks module did not load: Error: boom at load
要注意 hooks module did not load:故障发生在模块加载阶段,还没走到正常命令处理。静态读取没有发现它,真正加载模块的测试发现了它。
正常版本的测试通过两次模拟工具调用,再执行 /tally,结果为 1 pass、0 fail。这类测试不需要会话、登录或网络。作者还运行了 claude -p "/tally" --plugin-dir ./first-mod,得到 first-mod: Claude has made 0 tool calls since this mod loaded,验证命令能够被 mod 接管。
validate 通过,只能说明它检查的静态条件通过,不能证明模块能成功加载。
更危险的是失败后的行为。损坏版本向 stderr 输出加载错误,但 /tally 因未注册成功,被交给模型当普通提示词处理。模型查看目录,自己算了一份 tally,还消耗了作者的订阅用量。
自动化脚本如果只读取回答文本,就可能把这份临场生成的内容当成扩展命令的执行结果。原文没有给出退出码行为,因此不能自行假定靠退出码就能识别这种失败。
Windows 还有一个独立问题:Git Bash 会把以 / 开头的参数改写成 Windows 路径。作者建议使用 PowerShell 或 cmd,也可以用 MSYS_NO_PATHCONV=1 禁用该转换。
能改工具调用,也就需要信任它的代码
mod 的权限与当前用户一致,而且没有沙箱隔离。按原文列举,它能读写文件、启动进程、访问网络、读取环境或设置中的 API key,也能看到提示词与工具调用,甚至提交提示词、调用模型消耗额度。
Claude Code 对 Bash 命令的沙箱,不会自动覆盖 mod 启动的进程。
因此,validate 输出中的 calls: 更适合当阅读代码的入口。出现 $.process.spawn、$.process.run、$.http.fetch 或 $.fs 时,应继续检查具体操作。API 名称可以提示它会接触什么资源,但不能替你判断这些操作是否可信。
权限限制仍有边界:mod 不能重绘权限提示;在内置 sec-default 生效时,用户 mod 不能批准被 deny 或 ask 规则挡住的调用。auto mode 下,审核后再修改工具输入,也会触发 hook changed this call's input after the model wrote it 拒绝信息。
试用可以先用 claude --plugin-dir ./the-mod。正式安装使用 /plugin install name@marketplace 或 shell 中的 claude plugin install name@marketplace,已打开的会话需要 /reload-plugins。运行 /plugin 可查看是否出现 mod 激活状态。
遇到异常,可用 claude --debug-file ./mod-debug.log --plugin-dir ./your-mod 定位。临时停用已安装 mods 使用 claude --safe-mode;在 ~/.claude/settings.json 设置 "disableAllHooks": true 会同时停掉 settings hooks 和自定义状态栏。这些方式都不会停用内置 mods。
我的判断
作者最有说服力的发现,是加载失败会改变命令的执行路径。对人来说,它可能只是一次回答异常;对自动化来说,却是「程序结果」悄悄变成「模型生成文本」。这需要放在接入设计里处理。
但实验范围有限:单个教程 mod、Windows、2.1.302,没有完整五项破坏记录,也没有交互 UI 实测。它证明了该环境存在这条失败路径,没有证明所有版本、所有 mod 都会如此。原文也没有给出不同扩展方案的性能或可靠性对照,不能据此断言 mods 比 settings hooks 或 MCP 更好。
选择应从需求出发。只想记录或拦截事件,settings hooks 可能更省事;只想给模型增加工具,MCP server 更合适。确实需要改界面、共享进程内状态,或提供即时命令时,mod 的额外能力才值得引入。
能拿来做什么
- 写第一个 mod 时,可以从调用计数器入手,依次运行
claude plugin validate、claude plugin test,再通过claude -p检查命令是否真正被接管,把静态检查与执行检查分开。 - 用 Node 脚本包装
claude -p时,应读取 stderr,并给扩展命令设计可识别的输出标记;遇到加载错误时停止解析,避免把模型回答当成执行成功。 - 评估第三方 mod 时,先检查
hooks:和calls:,再阅读进程、网络与文件相关代码。官方示例也注明不提供支持,示例身份不能替代代码审查。 - 排查 API 不匹配时,优先查看当前 Claude Code 为 mod 生成的
.claude-plugin/types/类型文件。原文明确提醒事件和方法仍会变化,旧教程中的接口未必适用于本机版本。