Mods 概览

​

Mod 可以做什么

• 绘制可以使用的界面：在文本记录旁边的窗格或提示上方的带状区域，带有选项卡、按钮和文本字段。请参阅在界面中绘制。
• 重新绘制 Claude Code 自己的界面：替换或重新设置 Claude Code 自己绘制的部分，例如工具调用的行、微调器或 Claude 提出问题的对话框。请参阅更改 Claude Code 已经绘制的内容。
• 进入工具调用或请求：例如，在向用户提出问题时保持工具调用，在不运行工具的情况下回答问题，或将一个请求发送到不同的模型。请参阅保护或更改工具调用和跟随一个转折。
• 在命令上运行自己的代码：一个 /command，立即运行你的函数，没有 Claude 转折，即使 Claude 正在工作。请参阅添加命令或工具。
• 在 hooks 之间共享数据：mod 的 hooks 共享其文件中的变量，所以一个 hook 记录的内容，另一个可以显示。例如，一个 hook 可以计算工具调用，而另一个在微调器旁边显示计数，或者一个可以读取每个请求的令牌使用情况，而另一个在窗格中绘制它。请参阅对事件做出反应。

​

获取 mod

• 使用你已经拥有的：Claude Code 的一些自己的功能是 mods，例如 /diff。请参阅内置于 Claude Code 的 Mods。
• 创建一个：在 Claude Code 会话中描述你想要的内容，Claude 会编写 mod。请参阅向 Claude 请求 mod。要了解 mod 代码如何工作，自己编写一个。
• 安装一个：请参阅安装或更新 mod

​

安装或更新 mod

• 在 Claude Code 会话中，运行 /plugin install token-chart@your-org。
• 在你的 shell 中，运行 claude plugin install token-chart@your-org。

​

决定是否信任 mod

​

Mod 可以访问什么

• 在你的机器上以你的身份行动：读写你的用户账户可以访问的任何地方的文件、启动程序和发出网络请求
• 读取你的秘密：环境变量和设置文件，包括你保存在其中任何一个的 API 密钥
• 查看你的会话：你发送的每个提示和 Claude 进行的每个工具调用
• 更改你的会话：重写提示或工具调用、提交提示就像你输入的一样，或向你的另一个会话发送消息
• 在不询问你的情况下行动：在被询问之前批准工具调用
• 花费你的使用量：在你的计划或 API 密钥上调用模型

​

在安装 mod 之前列出它做什么

claude plugin validate ./some-mod

​

打开或关闭 mods

• 一个 mod：从/plugin 中的已安装选项卡禁用或卸载其插件
• 每个已安装的 mod，对于一个会话：使用 --safe-mode 启动 Claude Code，这也会排除你的其他自定义
• 你安装的每个 mod，在每个会话中：在 ~/.claude/settings.json 中设置 "disableAllHooks": true。你的设置 hooks 和自定义状态行也会停止。你的组织管理的内容继续运行。

​

查看会话加载了哪些 mods

​

Mod 如何工作

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

• plugin.json：插件的清单
• hooks.json：指向你的代码文件
• register.js：你的代码，称为 hooks 模块。它告诉 Claude Code 在哪些事件上运行你的函数。

// The count, shared by the two hooks below
let calls = 0

// Claude Code calls this once when the mod loads
export function register(on) {
  // Runs each time Claude is about to use a tool
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Ask Claude Code to draw the interface again, so the new count shows
    $.ui.invalidate('ui.render')
    // Let the tool run as usual
    return next(e)
  })

  // Runs each time Claude Code draws the spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Keep Claude Code's spinner, with the count added after its word
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

• tool.call hook 在 Claude 即将使用工具时运行。它将一个添加到 calls，要求 Claude Code 再次绘制界面，并让工具照常运行。
• ui.render hook 在 Claude Code 绘制微调器时运行。它保持 Claude Code 自己的微调器，并在单词后添加计数。

​

Hook 可以对事件做什么

• 观察：注意正在发生的事情并让它继续不变，就像示例中的 tool.call hook 一样
• 重写：在事件继续之前更改事件，就像 ui.render hook 在向微调器添加计数时所做的那样
• 回答：自己处理事件，所以通常的行为不会运行，例如拒绝命令

​

Mods 在哪里运行

​

为你的组织控制 mods

​

比较 mods、设置 hooks、skills 和 MCP 服务器

​

内置于 Claude Code 的 Mods

​

阅读内置 mods 的源代码

• diff：/diff 窗格，带有绑定到键盘操作的按钮和 mod 自己处理的滚动
• agents-md：将 AGENTS.md 加载为项目指令，带有 userConfig 选项
• sec-default：了解默认情况下发生的事情中描述的保护，一个强制执行策略的 mod 的模型
• telemetry：添加其他 mods 可以调用的方法，并发货其类型

​

后续步骤

• 创建 mod：构建一个计算工具调用、在微调器旁边显示计数并添加命令的 mod，并学习编辑和重新加载循环
• 在界面中绘制：窗格、提示上方的带状区域、按钮、文本字段和状态
• 对事件做出反应：工具调用、提示、转折和 mods 运行的顺序
• 使用 mods API：命令、工具、模型调用、计时器和文件
• 测试 mod：在没有会话的情况下运行的自动化测试
• 对 mod 进行故障排除：mod 什么都不做的原因和调试日志
• 为你的组织管理 mods：默认值、托管设置、查看 mod 和策略 mods
• Mods 参考：每个事件、方法、元素和限制