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


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

关键设计点:

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 关键规则

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

值得关注的几个:

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. 上手路径

  1. claude --version 确认 ≥ 2.1.287(让 Claude 在会话里写并热加载 mod 需要更新的版本,2.1.310 已有)。
  2. 最省事的办法:直接描述你想看到什么,例如「做一个 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>/ 下,想长期保留要自己拷出来,因为旧会话的目录会被清理。
  3. 自己写:claude --plugin-dir ./my-mod,保存即热重载;状态放 $.state;props 从 e.props 读(如 bodyColumns、hasSurvey);没东西可画时 return next(e) 把位置让出来;用单宽字符,不要用 emoji。
  4. 发布: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。
  5. 装别人的 mod 前先读代码,可以先在 awesome-claude-code-mods 上看它会访问哪些能力。

参考链接

官方

源码剖析

书签中的其他帖子

X 搜索

Reddit

Read this report as Markdown · Cite it (BibTeX)