Claude Mods 调研摘要
By 陈成 · Published October 26, 2026
Claude Mods 是什么、怎么演进的、Claude 写 mod 的链路如何实现,社区反应如何,值得做哪些 mod?
整理时间:2026-10-26 来源:X 书签(搜 "Claude Mods",10 条)及其评论、X 搜索、Reddit(r/ClaudeCode、r/ClaudeAI)、官方指南、GitHub issue #91870;§3 来自对 Claude Code 2.1.310 解包代码的剖析(
claude-code-versions/docs/impls/claude-mods-implementation.md)
TL;DR
- 是什么:Claude Mods 是 Claude Code 的「进程内插件」。一个 mod 就是一个普通 plugin,里面放一个 JS/TS 模块,用
on(event, matcher, ($, e, next) => …)挂钩子。钩子按 Express/Koa 中间件的方式串成链,可以观察事件、改写事件,或者直接返回结果把事件拦下,还能往界面上画 UI(React 树)。 - 跟原来的 hooks 有什么不同:settings hooks 是每个事件起一个 shell 进程,用 stdin/stdout 传 JSON。mod 加载一次后常驻会话,可以保存状态、画实时刷新的 UI、开侧边 pane、注册 slash command,也能注册给模型调用的 tool。
- 时间线:9/3 在 issue 里以「Function Hooks」提案发出 → 9/9 定名 Claude Mods,可用环境变量开启试用 → 9/15 Boris 宣布开始灰度 → 10/1 官方指南发布(2.1.287+ 默认开启)→ 10/2 @ClaudeDevs 正式发布。
- Claude 写 mod 的链路(dev mods):
/plugin-authoring把 mod 写进会话专属目录~/.claude/dev-mods/<sessionId>/,CC 轮询这个目录,发现新 mod 时用一张只有真人能回答的卡片问「Turn on the mods Claude writes in this session?」。同意后该目录作为--plugin-dir加入会话并热重载,同意记录写进 transcript,--resume时不再询问。这条链路在 2.1.288 – 2.1.310 之间加入,详见 §3。 - 社区反应:发布推 450 万浏览、2 万赞,Reddit 首发帖 1.1k 分。社区一个月内做出 5000+ 个 mod(awesome 列表收录)。主要质疑有三类:安全,因为 mod 不跑在沙箱里;「先去修模型」;「不如直接开源 harness,或者允许订阅额度用在第三方 harness」。
- 我的判断:Claude Code 以后会越来越像一个可编程平台,内置的
/diff和 AGENTS.md 支持本身就是用 mod 写的。最值得做的是解决自己反复遇到的问题,比如 context/额度仪表、危险命令护栏、cache 保温、prompt 改写、diff 回放。纯娱乐的 mod(Tetris、吉祥物)传播效果好,但长期价值有限。
1. 演进时间线
timeline
title Claude Mods 从提案到生态
9月3日 : GitHub issue 91870 发出 Function Hooks 提案
: 中间件式 next() 加 $ 能力对象,附架构 PDF 和 9 个演示视频
9月9日 : 产品名定为 Claude Mods
: CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 可提前试用
: 公开首批 3 个内置 mod 源码
9月15日 : Boris Cherny 宣布 Mods 开始上线
: 社区第一个爆款是 Tetris mod
10月1日 : Addy Osmani 发布官方 Getting started 指南
: 2.1.287+ 默认开启
10月2日 : ClaudeDevs 正式发布
: 示例 Token Weather / Blast Radius / Replay Theater
10月上中旬 : 社区 mod 爆发,awesome 列表收录 5000+
: 2.1.300 到 305 持续补 API
: 2.1.288 到 310 之间加入 dev mods,Claude 在会话里写的 mod 经用户同意后热加载
2. 机制:一个 mod 长什么样
目录结构(就是一个标准 plugin):
token-weather/
├── .claude-plugin/
│ ├── plugin.json # 普通插件清单,可加 "types": "./types/index.d.ts"
│ └── types/ # Claude Code 加载时自动写入当前版本的类型声明
├── hooks/
│ ├── hooks.json # { "modules": ["./token-weather.mjs"] },一个 mod 只有一个模块
│ └── token-weather.mjs # export function register(on, options) { ... }
├── types/index.d.ts # 声明 $.state 用到的状态(validate 会校验)
└── tests/*.test.ts # claude plugin test 跑在真实 runtime 上
每个钩子形状相同:
on("tool.call", { tool: "Bash" }, async ($, e, next) => {
// $:mod API(ui / session / state / store / fs / process / clock / http / tool / command / model …)
// e:本次事件的纯数据
// next(e):交给链上其他插件,最后由 Claude Code 执行默认行为
return next(e);
});
flowchart LR
E["事件<br/>tool.call / prompt.submit / turn.* / session.* / command.run / ui.render"] --> A["你的 hook<br/>($, e, next)"]
A -->|"next(e) 或 next({...e, 改写})"| B["其他插件<br/>(同样形状)"]
B -->|"next(e)"| C["Claude Code 核心<br/>默认行为"]
C -->|结果| B -->|结果| A
A -.->|"不调 next,直接 return {deny}"| X["拦截 / 自己作答"]
A -.->|"$.ui / $.process / $.fs / $.http …"| S["所有副作用走 $<br/>(便于审计、白名单、日志)"]
三种动作(来自官方指南):
| 动作 | 写法 | 例子 |
|---|---|---|
| 观察 Observe | const r = await next(e); /* 看 */ return r |
记录每次文件编辑;每轮结束读一次用量 |
| 改写 Rewrite | return next({ ...e, command: safer }) |
改 prompt、改命令参数 |
| 作答 Answer | return { deny: "…" },不调 next |
拒绝某个工具调用;自己实现 slash command / tool |
关键设计点:
- 注册顺序就是嵌套顺序:
on(X,A); on(X,B); on(X,C)折叠成A(B(C(⊥)))。先注册的包在外层,权限更大,企业管理员的策略就是靠「最先注册」生效的。 $是唯一出口:模块跑在独立环境里,没有 DOM 和 Node,没有隐式的文件或网络访问。所有副作用都要经过$,所以 mod 做了什么,就是它调用了哪些$,审计日志天然可信。作者 poteat 在 issue 里说明$.fs、$.http、$.process都会提供,要不要限制由组织管理员决定。- UI 是 React 树:通过
ui.render钩住某个组件(比如AbovePrompt、Pane、Spinner),用$.ui.resolve(e)拿到Box/Text/Button构造器,终端、桌面、VS Code 共用一套契约。 - 热重载:用
claude --plugin-dir ./xxx启动后保存即生效。模块变量会在重载时清空,状态要放进$.state;在 render 中调用$.state.get会自动订阅,之后set时自动重绘。 - 时间预算:每次 dispatch,hook 自身有 10 秒;在
$调用里等待的时间不计入,所以 Blast Radius 可以挂起命令等用户点按钮。 - 工具链:
claude plugin validate(静态列出 hook 了哪些事件、调用了哪些$、读写了哪些 state)、claude plugin test、claude --debug(看 render 树校验错误),以及内置的/plugin-authoringskill,可以直接让 Claude 写 mod。
3. 内部实现:Claude 写的 mod 怎么被加载(dev mods)
基于 2.1.310 解包代码,核心实现在
chunk-35y6zhv3.js(695 行)。2.1.287 里还没有这部分。
「让 Claude 写一个 mod」不是直接把文件丢进插件目录就生效,中间有一套目录隔离、拒绝闸门、真人同意、持久化的流程。
3.1 组成
| 层 | 是什么 |
|---|---|
| Dev mods 目录 | <configHome>/dev-mods/<sessionId>/,每个子目录是一个 mod(含 .claude-plugin/plugin.json)。configHome 是 CLAUDE_CONFIG_DIR ?? ~/.claude |
| 作者 skill | 内置插件 cc-plugin-plugin-authoring 的 /plugin-authoring。SKILL.md 里的 ${CLAUDE_DEV_MODS_DIR} 在调用时替换成上面的目录,替换的同时创建目录并开始监听 |
| 监听 | chokidar 轮询(400 ms),空闲时防抖 2 s |
| 同意 | confirmWithUser 选择卡片,personOnly: true,模型不能代答 |
| 热重载 | 同意后目录加入会话的 plugin-dir 列表,之后由插件系统通用的 plugin-dir watch 负责(与 --plugin-dir 和 /reload-plugins 同一套) |
| 持久化 | transcript 追加 {type:"dev-mods", folder, sessionId},last-wins |
| 清理 | 定期删掉其他旧会话的 dev-mods 目录;活跃目录每个 turn 结束时 utimes 一下,避免被当成过期目录 |
3.2 端到端时序
sequenceDiagram
actor U as 用户
participant M as 模型
participant S as /plugin-authoring
participant W as dev mods 监听
participant P as 插件系统
U->>M: /plugin-authoring 做个状态行
M->>S: 展开 skill 提示词
S->>W: 替换 CLAUDE_DEV_MODS_DIR,mkdir 并开始监听
M->>W: Write dev-mods/sid/statusline/...
W->>W: 文件事件,检查拒绝闸门
alt 命中拒绝原因
W-->>M: 通知 off 和原因
else 可以询问
W->>U: 卡片:Turn on the mods Claude writes in this session?
alt Turn them on
Note over W: turn 进行中则等 turn 结束
W->>P: joinPluginDir,重建沙箱
W->>P: transcript 写入 dev-mods 条目
W->>P: reloadPlugins
P-->>W: reloaded / held / unbound / failed
W-->>M: 通知 enabled,空闲时唤醒模型
else Not now
W-->>M: 通知 declined,written but NOT loaded
end
end
M->>P: 之后再改 mod 文件
P->>P: plugin-dir watch 热重载
P-->>U: ui.log:This mod reloaded after a change to its files.
3.3 状态机
stateDiagram-v2
[*] --> present: 普通启动
[*] --> consented: resume 时 transcript 里有本会话的同意记录
present --> wanted: 目录里已有 mod,直接加载(不再询问)
present --> wanted: 目录为空但能问人
[*] --> wanted: 调用 /plugin-authoring 分发目录
wanted --> watching: startWatch
watching --> enabled: 用户选 Turn them on
watching --> watching: Not now,只屏蔽已存在的子目录
watching --> off: 命中拒绝闸门 / 没人可问 / 连续 3 次无选择
consented --> enabled: catchUp,不再询问
enabled --> wanted: joinPluginDir 失败时回滚
3.4 关键规则
- 拒绝闸门(按顺序取第一个命中的):diskless(无磁盘的云会话)→ hooks 模块总开关关闭 → 组织禁用全部 hooks → 组织禁止 side-load 插件 → 禁止本地目录插件 →
allowManagedHooksOnly→ 设置里disableAllHooks→ safe mode → bare mode → 工作区未信任。命中后停止监听,并把原因原样告诉模型(如「the organization forbids side-loaded plugins」)。 - 只问真人:
personOnly: true。mod 以用户权限运行,所以必须由人同意。「How does this work?」会换成长文案重问,最多 3 次。 - 一个 turn 最多问一次。turn 运行中只有第一次文件变化会立刻弹卡片,其余等 turn 结束;turn 运行中同意的话,会先显示「This session's mods will load once this turn ends.」。
- 「Not now」的范围:只把当时已存在的子目录记进
declined,Claude 之后再写一个新 mod 目录会重新询问。declined不持久化。 - 会话目录校验:sessionId 必须匹配
^[A-Za-z0-9_-]+$,目录要用realpath比对等于dev-mods/<sid>。resume 时 transcript 里不属于本会话的 dev-mods 条目直接丢弃,防止被塞进别的路径。 held:如果这次加载会改写 prompt cache,reloadPlugins()返回held,挂起等用户手动/reload-plugins。- 给模型的通知措辞很严格:declined 时写「Do not say the change is running」;还没回答时写「Do not say it was declined, and do not suggest --plugin-dir or a restart」。目的是防止模型谎称 mod 已经生效。
- 热重载期间给用户看的
$.ui.log行:重载成功、变化太频繁暂停重载、被 ConfigChange hook 否决、需要重启,这几种情况各有一行。 - 组织策略:除了上面的闸门,还有
allowManagedModsOnly、allowModsToOverrideDenyRules和远端 rollout 开关。
4. 官方三个示例
| Mod | 做什么 | 展示的能力 |
|---|---|---|
| Token Weather(约 80 行) | prompt 上方一行显示 context 用量「天气」:☀ <25% / ☁ / ☂ / ☇ / ↯ ≥90%,带最近 12 轮 sparkline 和单轮增量 | session.start、turn.complete 观察;$.session.usage();$.state;ui.render{AbovePrompt} |
| Blast Radius | 拦截 rm -rf、git reset --hard、force push、DB migration 等命令,dry-run 算出影响面,在 pane 里显示 Proceed / Cancel |
Answer 模式;$.process.run(argv 数组,不经 shell);带热键的 Button;宽度不够时退回到 band 显示。官方原话是「安全网,不是权限系统」,$(…)、别名、脚本都能绕过 |
| Replay Theater | 记录本轮每次 Edit/Write,按 r 或 /replay 逐条回放 diff |
turn.start/turn.complete 配对;e.agentId 排除子 agent;$.command.register;$.fs.read 取写入前内容 |
代码在 anthropics/claude-code-playground;内置 mod(/diff、AGENTS.md)源码和测试在 anthropics/claude-code 仓库的 mods/ 目录。
5. 社区 mod 盘点(按用途分类)
mindmap
root((社区 Mods))
用量与成本
Token Weather 变体
ccOverhead
cache-warmer
Cache Tax
每 prompt 成本追踪
effortless 自动选模型
护栏与安全
Blast Radius
push-guard 测试不过不让 push
隐私替换插件
árbol guard
阅读与导航
prompt-rail 跳回历史 prompt
chat-toc 会话目录
cc-stretch 伸缩文本
tldr 面板
chat-clean
工作流与集成
next-steps
Inbox 待办收集
loose-ends
CI 面板
Sourcegraph Deep Search
Mattermost 镜像
调用 Codex 做二审
视图增强
图片缩略图
Mermaid 渲染
filetree
SwiftUI Preview
diffr 结构化 diff
翻译视图
娱乐与陪伴
Tetris 和 Doom
卡通 spinner
Clawd 吉祥物
Verbs 像素动画
呼吸训练
Goku 打 bug
值得关注的几个:
- cc-stretch(Reddit 1.5k 分,本次看到分数最高的帖子):实现了 Ted Nelson 1967 年提出的 stretchtext,回复默认压缩 83%,点开哪段展开哪段,还会告诉 Claude 你看过哪些部分。
- translate-view(@yrzhe_top,中文用户):发送前把中文翻译成英文交给 agent,回复在右侧 pane 显示中文,左侧保留英文原文对照。
- effortless(Reddit 267 分):用 Haiku 5.5 判断每条 prompt 该用哪个模型、哪个 effort。评论区争议在于:Haiku 当裁判不可靠,而且换模型会让 cache 失效,可能反而更贵。
- mod-scout / Vox 的 prompt:让 Opus 5.5 读官方指南,再翻你最近 20 个会话的 jsonl,统计你反复问的问题,排出最该做的 3 个 mod。
- ESP32 实体屏(Reddit 369 分):用 mod 把订阅用量和 context 数据推到 USB/蓝牙小屏,固件和 CAD 外壳都是 Claude 做的。
- Thariq 提到的方向:mod 可以 fork 出子 agent 做额外工作,比如每轮跑一个分类器、命中了就写 memory。他还在把 plan mode 改造成 mod。
6. 争议与风险
| 观点 | 代表声音 |
|---|---|
| 安全:mod 不在沙箱里 | 官方:「Mods run with the same access to your machine as Claude Code itself」。@samseclabs:mod 就是别人的代码,住进了一个已经有你文件和终端权限的东西里。@Pashoke1:mod 能读 API key,还能在你看到之前批准命令。Reddit:一个函数就能改写 prompt、拦截或改写工具调用、批准权限请求、在输出里删掉密钥,「很适合做恶意 mod」 |
| 中间件顺序的权限问题 | @jatingargiitk:管理员靠「先注册」控制一切,那如果第三方 mod 抢先注册呢?issue 里还问到:hook 抛异常时 fail-open 还是 fail-closed,Promise 永远不 resolve 时怎么超时,怎么测试 |
| 「先修模型」 | Boris 推下的高赞回复里,不少在抱怨 Opus 5 / Fable 变笨、额度消耗太快,认为 Tetris 是玩具不是功能 |
| 「为什么不开源 / 不放开第三方 harness」 | 「/mod open source the harness」(258 赞);多人要求把订阅额度开放给 OpenCode、pi、Cursor 使用。也有人指出 pi、Letta 早就有类似扩展机制 |
| 用例不清 | Reddit「mods is insane」帖下最高赞是「And not a single example was given」(389),其次是「想不出我需要它干嘛」(154)。Hamel Husain 直言官方演示视频「看不懂,visual slop」,后来 Lydia 补了讲解视频 |
| 迁移成本 | DareDev256 统计了自己的 42 个 shell hook,一半以上要访问 workspace 外的文件、起子进程、读 SQLite 或密钥,很难迁移成 mod。他判断两者会长期共存,不是替代关系 |
| 官方对「Claude 自己写 mod」的防护 | 从代码看(§3),Claude 写的 mod 隔离在会话专属目录,必须由真人在卡片上同意才加载,模型不能代答;组织策略、safe mode、未信任工作区都会直接关掉这条链路。但同意是「本会话以后写的 mod 全部生效」,一次同意之后的修改不会再逐个确认 |
| 兼容性 | API 会随版本变化,以每次加载时生成的 .claude-plugin/types/ 为准。早期桌面端渲染和 Remote Control 支持滞后,Agent View 目前还不能 mod |
7. 上手路径
claude --version确认 ≥ 2.1.287(让 Claude 在会话里写并热加载 mod 需要更新的版本,2.1.310 已有)。- 最省事的办法:直接描述你想看到什么,例如「做一个 mod,在 prompt 上方显示 xxx,每轮更新」,或者调用
/plugin-authoring。弹出「Turn on the mods Claude writes in this session?」时选 Turn them on,本轮结束 mod 就会出现。选 Not now 的话,已写的 mod 下次启动这个会话时才加载。mod 文件在~/.claude/dev-mods/<sessionId>/下,想长期保留要自己拷出来,因为旧会话的目录会被清理。 - 自己写:
claude --plugin-dir ./my-mod,保存即热重载;状态放$.state;props 从e.props读(如bodyColumns、hasSurvey);没东西可画时return next(e)把位置让出来;用单宽字符,不要用 emoji。 - 发布:
claude plugin validate(加--profile directory会检查 README 和 license)→claude plugin test→ 放到带marketplace.json的 GitHub 仓库 → 别人用/plugin marketplace add org/repo加/plugin install x@repo安装。也可以提交到 claude.ai/directory。团队场景可以写进项目.claude/settings.json的extraKnownMarketplaces和enabledPlugins。 - 装别人的 mod 前先读代码,可以先在 awesome-claude-code-mods 上看它会访问哪些能力。
参考链接
官方
- @ClaudeDevs 发布推:https://x.com/ClaudeDevs/status/2105721434807083061
- 官方指南 Getting started with Claude Code mods(Addy Osmani):https://claude.dev/blog/getting-started-with-claude-code-mods/
- 提案与社区讨论 issue #91870(Function Hooks → Claude Mods):https://github.com/anthropics/claude-code/issues/91870
- Boris Cherny「Mods are landing now」:https://x.com/bcherny/status/2099551291601248485
- Thariq「all software is becoming malleable」:https://x.com/trq212/status/2105734197801562264
- Lydia Hallie「have you built any claude code mods yet?」(285 条回复,社区作品集中展示):https://x.com/lydiahallie/status/2106066888501645655
- Addy Osmani 介绍推:https://x.com/addyosmani/status/2105908136154673323
- Claude 插件目录:https://claude.ai/directory
源码剖析
- dev mods 热加载实现剖析(2.1.310):
/Users/chencheng/Projects/claude-code-versions/docs/impls/claude-mods-implementation.md
书签中的其他帖子
- Vox:用官方指南加历史会话找出最该做的 mod:https://x.com/Voxyz_ai/status/2105778540251644176
- Oikon:Claude Mods 速查表 / prompt-rail:https://x.com/oikon48/status/2100330383141405013 、https://github.com/oikon48/prompt-rail
- yrzhe:translate-view 中英翻译 mod:https://x.com/yrzhe_top/status/2106375032335184017 、https://github.com/Yrzhe/claude-skills/tree/main/plugins/translate-view
- Anshu:Claude 生成卡通的 spinner:https://x.com/anshuc/status/2105773281936650247 、https://github.com/achimala/claude-toons
- Dave Kiss:/shot 截图 mod:https://x.com/davekiss/status/2105824036928282898
- Kirill Serditov:计划进度条 mod:https://x.com/kirillvserditov/status/2105790255144063241
X 搜索
- Lydia 的讲解视频(回应 Hamel 的批评):https://x.com/addyosmani/status/2106228548537352405
- Hamel Husain 批评演示视频:https://x.com/HamelHusain/status/2106216683585294741
- Charlie Hills 的 12 个免费 mod:https://x.com/charliejhills/status/2106761392883744888
- nogu「Claude Mods 全貌」页面:https://x.com/_nogu66/status/2110668756028633574
- 有人 fork 了 Codex 并加上 mods 支持:https://x.com/_theonly1me/status/2108848713729011865
- 安全提醒(mod 能读 key、能批准命令):https://x.com/Pashoke1/status/2109972738605539573
- 向阳乔木:隐私替换 mod 的思路:https://x.com/vista8/status/2107420985041551671
- 每 prompt 成本追踪:https://x.com/kvncnls/status/2110828891711619160
- Inbox mod:https://x.com/petekp/status/2107878774297727477
- cache-warmer:https://x.com/Samyak0606/status/2106987472668545400
- 图片缩略图 mod:https://github.com/jarrodwatts/claude-image-view
- awesome-claude-code-mods(5000+,标注每个 mod 的访问能力):https://github.com/karanb192/awesome-claude-code-mods
- Introducing Claude Mods(1125 分 / 212 评论):https://www.reddit.com/r/ClaudeCode/comments/1wvc7vc/introducing_claude_mods/
- cc-stretch:伸缩文本,少读 83%(1514 分):https://www.reddit.com/r/ClaudeCode/comments/1x688sx/turning_a_crazy_idea_from_1967_into_a_claude_code/ 、https://github.com/pro-vi/cc-stretch
- mods is insane(316 分,评论质疑缺少用例):https://www.reddit.com/r/ClaudeCode/comments/1x04oq4/mods_is_insane_i_love_it/
- 用 mod 做出 ESP32 实体用量屏:https://www.reddit.com/r/ClaudeCode/comments/1wye4ix/i_just_wanted_to_try_the_new_claude_code_mods_i/
- effortless:Haiku 自动选模型和 effort:https://www.reddit.com/r/ClaudeAI/comments/1x1nnkn/i_made_a_claude_code_mod_that_uses_haiku_55_or/
- push-guard:测试失败时禁止 push:https://www.reddit.com/r/ClaudeCode/comments/1xfpxmm/i_built_a_claude_code_mod_that_blocks_git_push/
- Clawd 吉祥物加用量条(桌面端):https://www.reddit.com/r/ClaudeCode/comments/1xef8gp/made_a_mod_for_the_claude_code_desktop_app_a/