👁 163 次阅读
Claude Code 从 2026 年 10 月 1 日起悄悄加了一套新的扩展系统叫 Mods。它不是新工具，也不是让你学一套 API 的框架，而是官方把 Claude Code 里一些原本藏得很深的行为开放出来，让你能用一句自然语言描述我想要屏幕上方多出一条这样的提示，Claude Code 自己在 30 秒内写出对应的插件代码装进你的会话里。Anthropic 官方给出的例子有 3 个：Token Weather 显示上下文窗口占用率、Blast Radius 在危险命令执行前弹出影响预览、Replay Theater 逐步回放刚才这一轮改动。本文按实战思路把这 5 步走一遍，最后再补齐几个社区里已经在广泛使用的 Mods，帮你避开一开始容易踩的三个坑。
一、Mods 是什么，和 Slash Command / Skill / MCP 到底有啥区别
先厘清概念，不然你会觉得这跟 /permissions 有什么两样。Slash Command 是你在输入框里敲 /xxx 触发的动作；Skill 是 .claude/skills/ 下的一个文件夹，Claude Code 只在匹配任务时才加载它的完整说明；MCP Server 是把 Claude Code 接到外部系统（数据库、浏览器、Ticket）上的桥；Hooks 是每个事件都执行一次外部命令。
Mods 不一样。它是一个跑在你会话内部的小 JavaScript 模块，一次加载之后常驻，能画 UI、订阅事件、甚至注册新的 slash command 和 tool。Anthropic 官方把 AGENTS.md 支持和 /diff 面板都写成了 Mod，你可以在 anthropics/claude-code 仓库的 mods/ 目录里看到源码。所以严格意义上，你以后装的每一个能改变 Claude Code 界面的功能，都是 Mod；只不过现在官方已经把它默认打开，你甚至不用开关。
来源：Anthropic claude.dev 官方教程《Getting started with Claude Code mods》（2026-10-01）与 MindStudio 官方指南（2026-10-03）。
二、5 步装好 Mods：先更新到 v2.1.287 以上
Mods 依赖 Claude Code v2.1.287 引入的一批 hook，低于这个版本装不上。先用以下命令确认：
$ claude --version
2.1.287 or newer没到就升级：npm install -g @anthropic-ai/claude-code@latest。然后进入一个你自己的项目（不要用主仓库做实验，先拿一个空 git 目录），跑 claude 进入会话。Mods 默认打开，不需要额外开关。
关键的一点：claude plugin validate 会检查你的 Mod 有没有合法地声明状态字段。装完 Mod 一定要跑一次这个命令，别直接相信它跑起来了就算 OK。
三、第一个 Mod：Token Weather，让你看到上下文窗口还剩多少
这是 Anthropic 官方给的第一个教程例子，也最实用。为什么实用？Claude Code 每收到一条消息，都会把文件内容、代码、shell 输出全都塞进上下文窗口。窗口被塞到 90% 以上之后，回答质量会明显下降，而且费用会翻倍。以前你只能用 /context 命令手动查，Token Weather 把这个数变成一个常驻的气象条。
安装方法不需要你手敲任何一行代码。把下面这段提示词整段粘贴给 Claude Code：
Build a Claude Code mod called Token Weather for me.
Show a live band directly above the prompt with:
- A weather icon that changes based on context fill percentage
- The percentage and raw tokens used out of the window
- A small chart of the last 5 turns
- The token delta from the last turn
Use $.session.usage() for the numbers and $.state to keep history across hot reloads.
After building, run claude plugin validate and claude plugin test, then install it as a persistent plugin.Claude 会反问你是否启用 hot reloading，回答 yes。30 秒之内你会在提示框上方看到那条状态条。之后你随时可以再让它改：让 Storm 阈值从 80% 改成 70%、末尾再加一行本次会话的美元成本估算，它会直接改代码并且原地热重载。
来源：claude.dev/blog/getting-started-with-claude-code-mods/。
四、第二个 Mod：Blast Radius，危险命令执行前先看一眼
这是官方给的第二个例子，也是我建议每个用 Claude Code 的人都装的一个。它的逻辑是：当 Claude 要调 Bash 跑 rm -rf、git reset –hard、git clean、force push、数据库迁移这种命令时，Blast Radius 拦下来，先跑一次 dry run，把会被影响的文件、提交、迁移对象列到一个面板上，然后问你 Proceed 还是 Cancel。
它内部只用了 3 个 hook：Bash 的 tool.call、Pane 的 ui.render、AbovePrompt 的 ui.render。核心技巧是把 git status –porcelain、git clean -n、git log HEAD..origin/main 这些命令当 argv 数组传给 $.process.run，路径里的特殊字符不会被 shell 解释。这一步比想象中重要，很多自作聪明的 Hook 都会在这里翻车。
安装提示词：
Install the Blast Radius mod described in the official Anthropic tutorial.
Show what rm -rf, git reset --hard, git clean, force push and DB migrations would touch before they run,
with Proceed / Cancel buttons. Do not modify the mod source unless claude plugin validate reports an error.这个 Mod 特别适合你开了多个 Claude Code 会话并行工作的场景。两个会话同时对同一个项目下手，谁先提交谁覆盖谁，Blast Radius 至少能在关键动作前给你一个刹车。
五、第三个 Mod：Next Steps，每次回答完自动给你下一步建议
Anthropic 自己的一位工程师做的 Next Steps 现在算是社区里最流行的 Mods 之一。它在每轮回答完之后在末尾多一个面板，列 2-3 条具体的下一步建议。比如你让它修了一个登录 bug，它会建议：下一步跑一遍现有的登录测试套件、下一步检查其他调用 authenticate() 的地方是否也要跟着改。
价值在于它把该干什么这件事前置了。你不用再自己想现在是不是该跑测试了、是不是漏了其他调用点，它按当前的代码改动和刚才的对话上下文给出建议，你按不接受或者接受就是。
安装提示词（社区版本，注意是 Anthropic 工程师自己分享的）：
Install the Next Steps mod built by the Claude Code team.
At the end of every turn, show a small panel with 2-3 concrete next actions
based on the just-completed work, with a dismiss button.六、装完之后必做的三件事
第一，跑 claude plugin validate 检查所有已装 Mod 的状态声明是否合法。Anthropic 官方特别提醒：如果你加了 $.state 但忘了在 plugin.json 的 types/index.d.ts 里声明，validate 会报一个非常明确的错误：token-weather.readings is not declared: the manifest types contract must name it in interface PluginState。看到这个错误不要慌，把报错里的字段名加到 .d.ts 文件里就行。
第二，跑 claude plugin test 执行 Mod 的单元测试。Claude Code 现在为每个 Mod 生成 *.test.ts，你可以控制 $.session.usage() 的返回值，验证 UI 是否会按预期重绘。
第三，用 claude plugin list 看看当前会话里挂了哪些 Mod。装了太多会导致 UI 一片花，Anthropic 自己也建议在开始阶段只装 1-2 个真正解决问题的，不要看到什么装什么。
七、三个新手最容易踩的坑
坑一：以为装了 Mod 就永久生效。Mod 默认只在你当前会话里加载，退出后下次开新会话需要重新激活。想永久使用，把它安装为 plugin：claude plugin install ./mods/token-weather。
坑二：想当然地以为 Mod 和 Settings Hooks 是同一个东西。Settings Hook 是每次事件都跑一次外部 shell 命令、通过 stdin/stdout 传 JSON；Mod 是一次加载、常驻会话、能画 UI、能跨事件保存状态。前者适合每次编辑后跑 prettier 这种纯机械动作，后者适合常驻面板 + 跨轮对话的仪表盘。
坑三：把多个 Mod 都开成常驻导致 UI 拥挤。Anthropic 的 FAQ 里明确说，Mod 本身很轻、不会拖慢会话速度，但视觉上的堆叠会让你眼睛找不到重点。社区里比较合理的组合是 Token Weather（成本意识）+ Blast Radius（安全）+ Next Steps（下一步建议），三个各管一件事，不会互相遮挡。
八、Mods 和 Slash Command、Skill、MCP、Hooks 对比表
| 能力 | Slash Command | Skill | MCP Server | Mod | Hooks |
|---|---|---|---|---|---|
| 触发方式 | 用户敲 /xxx | 任务匹配时自动加载 | 外部系统调用 | 会话加载时常驻 | 每个事件触发 |
| 能否画 UI | 否 | 否 | 否 | 是（AbovePrompt / Pane / Status） | 否 |
| 能否跨事件保存状态 | 否 | 否 | 是（在外部系统） | 是（$.state） | 否 |
| 能否注册新 slash command | 是（自己就是） | 是 | 否 | 是 | 否 |
| 能否拦截 tool 调用 | 否 | 否 | 间接 | 是（tool.call hook） | 是 |
| 典型用例 | 固定动作 | 领域知识 | 接外部系统 | 常驻仪表盘 / 拦截面板 | 机械自动化 |
九、常见场景速查表：你该装哪个 Mod
| 你的问题 | 推荐 Mod | 说明 |
|---|---|---|
| 不知道这次会话花了多少 token / 多少钱 | Token Weather + Cache & Cost Tracker | 前者看占用率，后者看美元成本和缓存剩余时间 |
| 怕 Claude 不小心 rm 掉重要文件 | Blast Radius | 拦截危险命令并 dry run |
| 多会话并行工作，怕互相覆盖 | Collision Guard | 检测最近 30 分钟被别的会话改过的文件 |
| 刚装完 Claude Code 不知道该干嘛 | Next Steps | 每轮回答完自动给 2-3 条建议 |
| 跑长 goal 但不知道跑到哪了 | Goal Progress Tracker | 可视化 phase、耗时、勾选状态 |
| 录屏教程时不想泄露邮箱或账号 | Recording Mode Blurring | 视觉上打码，Claude 内部照常处理 |
十、写在最后
Claude Code Mods 的官方教程其实写得挺简，一个 Token Weather 就写了 80 行。真正难的不是写，而是选。Anthropic 官方给的三个例子（Token Weather、Blast Radius、Replay Theater）解决的是看占用率、防误删、回放改动三件事，社区里比较常用的另外三个（Cache & Cost Tracker、Collision Guard、Recording Mode Blurring）解决的是成本意识、并行安全、隐私保护。这六个加起来基本覆盖了日常场景，不用贪多。
如果你只装一个，先装 Blast Radius。它对老手和新手的收益都是明确的：老手可以少一次 git reset 后悔，新手可以在真正误删文件之前被拦下来。装完之后再决定要不要加 Token Weather 和 Next Steps。
数据来源：Anthropic 官方 claude.dev 博客（2026-10-01）、MindStudio 官方博客（2026-10-03）、Claude Code 官方 Changelog（2026-10-01 v2.1.287）。