1. 从插件只能加功能到插件能改行为的认知转变Claude Code 2.1.287 这个版本号看起来只是常规迭代但 Mods 这个机制的引入实际上把整个 CLI 的扩展模型从外挂式增强推向了内核级改写。我第一时间升级之后花了大半天时间把手上几个常用的插件全部过了一遍发现之前很多绕路实现的方案现在可以直接用 Mods 干净地解决。这篇文章就把我对这套机制的理解、实测过程、以及踩到的坑完整记录下来。先说清楚这篇文章适合谁看。如果你只是把 Claude Code 当成一个命令行里的对话工具平时用用/compact、/model、/resume这些内置命令就够了那 Mods 对你来说暂时不是刚需。但如果你已经在写插件、或者有想法把 Claude Code 嵌进自己的工作流比如接本地模型、接第三方 API、做团队内部的定制化 CLI那 Mods 这个能力你必须搞清楚因为它直接决定了你的插件能管多宽。在 2.1.287 之前Claude Code 的插件体系本质上是一个能力叠加模型。插件能做的事情是注册新命令、往上下文里塞内容、在特定生命周期钩子上挂回调。但插件改不了核心行为——比如你想让某条内置命令在特定条件下走不同的分支或者想在工具调用真正执行前做一次拦截改写之前的做法要么是包一层 wrapper 脚本要么是 fork 一份配置做覆盖都很脏。Mods 的出现改变了这个局面。它给插件开了一个行为改写的口子让插件不再只是往系统里加东西而是能对已有的执行链路做干预。这个变化听起来抽象但落到实操上影响非常具体。我下面会从机制、实操、坑点三个层面拆开讲。提示Mods 是 2.1.287 引入的新机制如果你用的是更早的版本本文的操作无法复现。升级前建议先备份你的插件目录和配置文件。2. Mods 到底改了什么执行链路里的干预点2.1 旧插件模型的能力边界要理解 Mods 的价值得先看清楚旧模型卡在哪里。之前的插件能力大致分三类命令注册往 CLI 里加新命令比如myplugin:deploy这种。上下文注入在对话开始或特定节点往上下文里塞系统提示、项目信息、文件内容。生命周期钩子在会话启动、工具调用前后等节点挂回调做日志、通知、校验。这三类能力有个共同点都是旁路的。插件在主干流程旁边做事但改不了主干本身。举个具体例子你希望当 Claude 准备执行某个终端命令时先自动做一次危险命令检测如果命中就替换成安全版本。旧模型下你能做的只是在工具调用前挂一个回调打印一条警告但没法真正阻止或改写这次调用。你只能事后提醒不能事前干预。再比如你想让/model这个内置命令在切换模型时自动带上某个团队约定的参数。旧模型下你只能自己注册一个新命令myplugin:model来替代但用户习惯用/model你的替代命令没人用。2.2 Mods 引入的行为改写能力Mods 的核心思路是在核心执行链路上开放一组可被插件覆盖的行为点。插件通过声明自己实现了哪些 Mod就能在这些点上接管或改写默认行为。我用一个生活化的类比来解释。旧插件模型像是给一栋房子加装家具——你能往里搬东西但改不了房子的承重墙。Mods 则是给了你一套可替换的墙板——某些非承重墙你可以拆掉换成自己的房子的整体结构还在但局部行为变了。具体到实现层面一个 Mod 通常包含这几个要素要素作用是否必需Mod 标识声明这个 Mod 接管哪个行为点必需匹配条件决定什么情况下这个 Mod 生效可选改写逻辑实际执行的行为替换必需优先级多个 Mod 命中同一行为点时的顺序可选回退策略Mod 执行失败时是否走默认行为可选这个结构设计的关键在于匹配条件和回退策略。匹配条件让 Mod 可以只在特定场景生效避免全局改写带来的副作用回退策略则保证了即使你的 Mod 写挂了核心功能也不会整个崩掉。这两点是我实测下来觉得设计得最务实的地方。2.3 哪些行为点可以被 Mod 接管这是大家最关心的问题。根据我实测和翻文档的结论2.1.287 开放的 Mod 行为点主要集中在几个区域命令解析与分发内置命令在被解析后、执行前可以被 Mod 拦截改写。工具调用链路工具调用的参数构造、执行前校验、结果后处理都有对应的 Mod 点。上下文组装系统提示、项目上下文、历史消息的组装过程可以被干预。模型请求构造请求发出前的参数、头部、模型选择可以被改写。注意不是所有行为点都开放了。核心的会话管理、认证流程这些目前还是封闭的。这个边界设计是合理的——开放太多会导致插件能做的事情超出安全预期开放太少又没意义。2.1.287 这个版本选的这几个点基本覆盖了定制化工作流最需要的区域。注意Mod 的接管是替换而非叠加。如果你的 Mod 接管了某个行为点默认行为就不会执行除非你在 Mod 逻辑里显式调用默认实现。这一点和钩子的叠加语义完全不同写的时候要特别小心。3. 写第一个 Mod从声明到生效的完整流程3.1 插件目录结构与 Mod 声明我先假设你已经有一个能跑的 Claude Code 插件。如果你还没写过插件建议先看官方插件入门把基础结构搭起来再回来看 Mods 部分。一个带 Mod 的插件目录结构大致是这样my-plugin/ ├── plugin.json # 插件元信息 ├── mods/ │ ├── command-guard.js # 一个 Mod 实现 │ └── context-trim.js # 另一个 Mod 实现 └── index.js # 插件入口plugin.json里需要新增一个mods字段来声明这个插件提供了哪些 Mod{ name: my-plugin, version: 1.0.0, mods: [ { id: command-guard, target: command.dispatch, priority: 100, entry: mods/command-guard.js }, { id: context-trim, target: context.assemble, priority: 50, entry: mods/context-trim.js } ] }这里几个字段的含义需要说清楚idMod 的唯一标识同一个插件内不能重复。target接管的行为点必须是系统支持的值。priority优先级数值越大越先执行。多个 Mod 命中同一行为点时按优先级排序。entryMod 实现的入口文件。priority这个字段容易被忽略但在多插件共存时非常关键。我踩过一个坑两个插件都接管了command.dispatch但都没设优先级结果执行顺序不确定行为时好时坏。后来给关键 Mod 显式设了优先级才稳定下来。3.2 Mod 实现的基本骨架一个 Mod 实现文件导出的通常是一个对象包含匹配和改写两部分逻辑。下面是一个拦截危险命令的示例// mods/command-guard.js module.exports { // 匹配条件只对终端执行类命令生效 match(ctx) { return ctx.command.type shell.execute; }, // 改写逻辑 async apply(ctx, next) { const raw ctx.command.args.command; const dangerous [rm -rf /, mkfs, dd if]; if (dangerous.some(p raw.includes(p))) { // 命中危险命令替换为安全提示 ctx.command.args.command echo [blocked] 危险命令已被拦截: ${raw}; ctx.meta.blocked true; } // 调用 next 继续后续链路 return next(ctx); } };这段代码有几个点值得展开讲。match函数决定了这个 Mod 在什么情况下生效。它接收一个上下文对象ctx返回布尔值。返回false时这个 Mod 会被跳过走默认行为。这个设计让 Mod 可以很精细地控制生效范围避免全局改写。apply函数是实际的改写逻辑。它接收ctx和next两个参数。next是链路上的下一个处理者——可能是另一个 Mod也可能是默认实现。调用next(ctx)是必须的否则链路会断掉。这一点和很多中间件框架的语义一致但新手容易忘。ctx.meta是一个可以自由读写的元数据对象用来在 Mod 之间传递信息。我在上面例子里往ctx.meta.blocked写了个标记后续的 Mod 或者日志钩子可以读这个标记做进一步处理。3.3 让 Mod 真正生效的验证步骤写完 Mod 不代表它就会生效。我实测下来需要走完这几步才能确认插件被正确加载运行claude plugin list确认你的插件在列表里且状态是 enabled。Mod 被识别运行claude plugin info my-plugin看输出的 mods 列表里有没有你声明的 Mod。行为点被接管这一步没有直接命令需要实际触发一次对应行为看你的 Mod 逻辑有没有执行。我通常会在 Mod 里加一行console.error([mod] hit)来确认。回退正常故意让 Mod 抛异常确认核心功能还能用。这一步很多人跳过但非常重要。第 4 步我特别想强调。Mods 的回退策略默认是Mod 失败则走默认行为但这个默认行为需要你在plugin.json里显式配置fallback: true。如果不配Mod 抛异常时整个行为点会直接失败用户体验就是命令卡住或者报错。我第一次写 Mod 就栽在这上面一个空指针把整个/model命令搞挂了排查了半天才发现是回退没配。提示开发阶段建议在 Mod 入口加详细的日志输出生产环境再关掉。Mods 的执行链路目前调试信息不算丰富靠自己打日志是最快的定位方式。4. 三个真实场景Mods 怎么解决以前很别扭的问题4.1 场景一给内置命令加前置校验团队里有个约定切换模型前必须先确认当前会话没有未保存的上下文。以前这个约定只能靠文档和自觉现在可以用 Mod 强制。我写了一个接管command.dispatch的 Mod匹配/model命令在执行前检查会话状态module.exports { match(ctx) { return ctx.command.name model; }, async apply(ctx, next) { const hasUnsaved await checkUnsavedContext(ctx.session); if (hasUnsaved) { ctx.output.warn(当前会话有未保存上下文请先 /compact 或 /save); return; // 不调用 next直接中断 } return next(ctx); } };这里的关键是不调用next就实现了中断。这是 Mods 相比钩子的一个明显优势——钩子只能观察Mod 能阻断。这个能力在需要强制约束的场景下非常有用。4.2 场景二改写模型请求接入本地模型热词里claude code 调用 lmstudio 的本地模型是个高频需求。以前的做法通常是改配置文件或者用环境变量比较僵硬。用 Mod 接管model.request行为点可以做到按条件动态切换module.exports { match(ctx) { // 只在特定项目目录下切换到本地模型 return ctx.cwd.startsWith(/home/me/local-projects); }, async apply(ctx, next) { ctx.request.baseUrl http://localhost:1234/v1; ctx.request.model local-model-name; return next(ctx); } };这个方案的好处是切换逻辑和项目绑定不用每次手动改配置。我在几个本地项目上试了一周稳定性没问题。需要注意的是本地模型的接口兼容性要自己确认Mod 只负责改写请求参数不负责协议适配。4.3 场景三上下文组装的动态裁剪长会话下上下文膨胀是个老问题。内置的/compact是手动触发的但有些场景下希望自动裁剪。用 Mod 接管context.assemble可以在组装阶段做动态裁剪module.exports { match(ctx) { return ctx.messages.length 50; }, async apply(ctx, next) { // 保留最近 30 条 最早 5 条中间做摘要 const head ctx.messages.slice(0, 5); const tail ctx.messages.slice(-30); const middle ctx.messages.slice(5, -30); const summary await summarize(middle); ctx.messages [...head, { role: system, content: summary }, ...tail]; return next(ctx); } };这个 Mod 我用了两周效果比预期好。关键是裁剪策略可以按项目定制——代码项目保留更多代码相关消息文档项目保留更多讨论消息。这种细粒度控制是内置/compact给不了的。不过这里有个坑要提醒context.assemble这个行为点触发频率很高你的 Mod 逻辑如果太重比如每次都调一次模型做摘要会明显拖慢响应。我的做法是加缓存同一批消息只摘要一次。5. 多 Mod 共存时的优先级与冲突处理5.1 优先级数值怎么定当多个 Mod 命中同一个行为点时执行顺序由priority决定数值大的先执行。这个规则本身简单但实际定优先级时容易乱。我总结了一个经验法则拦截类 Mod 优先级最高100比如危险命令拦截、权限校验这些必须最先跑。改写类 Mod 中等50-99比如请求参数改写、上下文裁剪。观察类 Mod 最低1-49比如日志、统计跑在最后。这个分层的好处是拦截类 Mod 可以在改写类 Mod 之前就把不该执行的行为挡掉避免做无用功。5.2 冲突的两种典型表现多 Mod 冲突我遇到过两种第一种是覆盖冲突。两个 Mod 都改写了同一个字段后执行的覆盖了先执行的。这种冲突不会报错但行为不符合预期。排查方法是给每个 Mod 的改写加日志看最终值是谁写的。第二种是链路断裂。某个 Mod 忘了调next导致后面的 Mod 和默认行为都没执行。这种冲突表现是功能莫名失效排查起来更麻烦。我的做法是在开发阶段给每个 Mod 的apply入口和出口都打日志一眼就能看出链路断在哪。5.3 用命名空间隔离 Mod 的副作用如果多个插件都要往ctx.meta里写东西容易互相覆盖。我的做法是给每个插件用独立的命名空间ctx.meta[my-plugin] ctx.meta[my-plugin] || {}; ctx.meta[my-plugin].blocked true;这样即使多个插件共存各自的元数据也不会打架。这个习惯看起来啰嗦但在插件数量上去之后能省很多排查时间。6. 实测中踩到的坑与排查链路6.1 Mod 声明了但完全不生效这是我最开始遇到的问题。plugin.json里写了 mods 字段插件也加载了但 Mod 逻辑就是不执行。排查链路是这样的先确认插件版本——claude plugin info看版本号确认是 2.1.287 及以上。再确认target值拼写——我一开始把command.dispatch写成了command.dispatch末尾多了空格系统不报错但也不匹配。然后确认entry路径——相对路径是相对于插件根目录不是相对于plugin.json。我一开始理解错了路径全错。最后确认match函数——如果match一直返回falseMod 就永远不生效。加日志确认ctx的实际结构。这四步走下来基本能定位 90% 的不生效问题。其中第 2 步和第 3 步是最容易犯的因为系统对这两类错误都不报错只是静默跳过。6.2 Mod 执行了但结果不对这种情况通常是改写逻辑本身有问题。我遇到过一次Mod 改写了ctx.command.args但实际执行时用的还是旧值。排查后发现是改写时机不对——command.dispatch这个行为点触发时参数已经被复制到另一个对象里了改ctx.command.args没用得改ctx.resolvedArgs。这个坑的教训是每个行为点的上下文结构不一样改写前一定要先打印ctx看清楚有哪些字段。我现在的习惯是写新 Mod 之前先写一个只打印ctx的探针 Mod跑一次看清楚结构再动手。6.3 回退没配导致核心功能挂掉前面提过一次这里展开说。Mod 抛异常时如果fallback没配true整个行为点会失败。表现是命令卡住、报错、或者直接退出。我第一次遇到时以为是 Claude Code 本身的问题重装了一遍才发现是自己的 Mod 搞的。修复很简单在plugin.json的 Mod 声明里加fallback: true。但更重要的是养成写防御性代码的习惯——Mod 逻辑里所有可能抛异常的地方都包 try-catch异常时主动走默认行为async apply(ctx, next) { try { // 改写逻辑 } catch (e) { console.error([mod] error, fallback to default, e); } return next(ctx); }这样即使逻辑有问题也不会影响核心功能。6.4 性能问题Mod 拖慢了响应context.assemble和model.request这两个行为点触发频率很高Mod 逻辑稍微重一点就能感觉到卡顿。我实测下来单个 Mod 的执行时间最好控制在 50ms 以内超过 200ms 用户就能明显感觉到。优化手段有几个加缓存同一输入不重复计算、异步化不阻塞主链路的操作放后台、条件短路match函数尽量早返回false。其中条件短路最容易被忽略——如果match函数写得复杂每次都要跑一遍累积起来也是开销。7. 关于 Mods 机制的一些个人判断用了一个多月我对 Mods 这套机制的整体评价是方向对但还在早期。方向对的地方在于它把插件从外挂提升到了可干预内核的层次这解决了很多定制化工作流的真实痛点。尤其是阻断能力是钩子模型给不了的对需要强制约束的场景价值很大。早期的地方在于开放的 behavior point 还不够多调试工具也比较原始。我期待后续版本能开放更多行为点同时提供更完善的 Mod 调试和追踪能力。目前排查问题基本靠打日志效率不高。另外提醒一句Mods 的 API 目前还在演进2.1.287 的写法在后续版本可能会变。如果你要基于 Mods 做生产级的插件建议把 Mod 逻辑和插件其他部分解耦方便后续适配 API 变化。最后分享一个我自己的小习惯每写一个新 Mod我都会先在隔离环境里跑一遍完整的正常路径 异常路径 回退路径三组测试确认没问题再上到日常环境。这个习惯帮我避免了好几次把工作环境搞挂的尴尬。Mods 这个能力很强但强能力意味着大责任写的时候多留个心眼总没错。