给 Claude Code 写第一个 Mod：从 Blast Radius 到你自己的 Agent 护栏

先想清楚：你的第一个 Mod 应该是什么

Mod 系统刚发布，社区已经有人在里面跑 Doom、做花哨的仪表盘。但听我一句劝：你的第一个 Mod 不应该是玩具，而应该是护栏。

理由很简单。Mod 的能力越大，你越需要先建立「控制它的手感」。一个拦截危险命令的 Mod 会在接下来几个月里替你挡下无数次手滑，而一个 Doom 复刻版除了发朋友圈没有任何复利。官方示例 Blast Radius 之所以是三个示例里最重要的一个，就是因为它回答了一个真实问题：Agent 越来越自主，谁来替它踩刹车？

所以这篇指南的目标很具体：写一个「Blast Radius 精简版」——拦截 rm -rf、git reset --hard、git push --force，执行前先告诉你它会波及哪些文件。做完这一个，你就掌握了 Mod 开发的完整手感。

第一步：理解事件模型（5 分钟）

Mod 的核心是一个事件钩子模型。一个 Mod 可以挂在三类时机上：事件之前（before）、事件之后（after）、代替事件本身（instead）。能挂的事件包括：工具调用、权限请求、提示词提交、UI 渲染。

我们的护栏 Mod 只需要一种挂法：在「工具调用」事件之前拦截。具体逻辑是：当 Claude Code 准备执行一条 shell 命令时，Mod 先拿到命令文本做模式匹配——命中危险模式就暂停执行，弹出一个侧边面板展示这条命令会 touch 哪些文件，等你确认后再放行。

多个 Mod 挂在同一个事件上时会按加载顺序形成链条，先加载的先看到事件。所以记住一条铁律：安全类的 Mod 永远要最先加载。企业版的 sec-default 内置 Mod 就是这么干的——它永远排第一，专门防止后面的 Mod 覆盖「拒绝」规则。

第二步：让 Claude Code 替你写（10 分钟）

这是整个流程里最有意思的部分：Anthropic 官方说了，你可以直接让 Claude Code 替你写 Mod，写完热重载立刻生效。实测下来，给它的提示词要具体到这三件事：

第一，说清楚拦截什么：「写一个 Mod，在工具调用事件之前拦截 shell 命令。如果命令匹配 rm -rf、git reset --hard、git push --force 这三种模式，就阻止执行并弹出确认面板。」第二，说清楚面板里展示什么：「面板里用 git ls-files 和简单的路径展开，列出这条命令可能影响的文件，标出是否在版本控制之外。」第三，说清楚边界：「只做拦截和展示，不要替我自动放行；代码里不要联网、不要读我 home 目录之外的文件。」

Claude 生成之后，别急着装。先让它用自己的话解释一遍这段代码每一部分在干什么——这是检验它有没有写出你没要求的东西的最快方法。

第三步：安装、热重载、验证（5 分钟）

Mods 随插件分发，安装命令是 /plugin，在 CLI 和桌面版通用。装好之后不需要重启——Mod 支持热重载，改完代码立刻生效。验证时故意让 Claude 执行一条无害的危险命令，比如在一个临时目录里 rm -rf ./tmp-test，确认拦截面板弹出来了、展示的文件列表是对的、点确认后命令才真正执行。

验证清单只有三条：拦截是否触发、面板信息是否准确、放行后行为是否正常。都通过，这个 Mod 就可以长期服役了。

第四步：安全自查（装任何 Mod 之前都做一遍）

因为 Mod 和 Claude Code 拥有同等机器权限，安装第三方 Mod 之前必须做这四件事：读代码——Mod 就是几十行 TypeScript，读不懂就别装；查网络行为——搜一下代码里有没有 fetch、axios、child_process 里拼 URL，护栏类 Mod 没有任何理由联网；看权限面——它申请拦截哪些事件？一个只做 UI 美化的 Mod 不应该碰权限请求事件；锁版本——从插件市场安装时记下版本号，作者更新后先看 diff 再升级。

最后一条是给团队用的：把团队共用的护栏 Mod 放进内部插件市场，管理员侧统一分发，个人就别各装各的了。信任边界这个东西，越集中越好管。

写完第一个之后：三个值得做的下一个

手感建立起来后，按这个顺序继续：密钥脱敏 Mod——在工具输出事件之后，把形如 API key、token 的字符串自动打码再展示；提交信息规范 Mod——在 git commit 之前检查信息格式，不符合团队规范的直接打回；上下文预算 Mod——照着 Token Weather 的思路，在上下文超过 70% 时主动提醒你开新会话。三个都是「每天默默保护你」的类型。

一句话总结：Mod 系统的真正价值不是让 Agent 更花哨，而是让你第一次能把「我不希望它干的事」写成代码、钉进 Agent 的主循环。先写护栏，再玩花样——顺序别反了。