---
title: "Claude Code Mods 是什么：10 月 1 日上线，插件能改界面和行为，附启用与验证步骤"
description: "Claude Code 2.1.287（2026 年 10 月 1 日）加入 Claude Mods，插件可以改更深层的行为。本文讲清 mod、hook、plugin 的关系，给出启用、安装与验证的步骤。"
url: https://cdnping.org/blog/claude-code-mods
language: zh-CN
published: 2026-10-19
category: "开发工具"
tags: ["Claude Code","Claude Mods","插件","Hook","开发工具"]
source: cdnping.org
license: Free to quote and summarize with a link to the url above.
---
# Claude Code Mods 是什么：10 月 1 日上线，插件能改界面和行为，附启用与验证步骤

Claude Code mods 是 2026 年 10 月 1 日随 2.1.287 版本推出的一类插件能力：官方更新日志的原话是“Added Claude Mods: plugins may now modify deeper behavior”，也就是插件可以改动比以前更深的行为，例如画界面、拦截提示词、在工具调用前后插手。同一版本还内置了第一个 mod，叫 “You should know”。以下内容截至 2026 年 10 月，以 [Claude Code 官方更新日志](https://code.claude.com/docs/en/changelog)为准。

## Mod、hook、plugin 是什么关系？

三者是包含关系，不是并列关系。

| 名称 | 含义 |
|---|---|
| plugin（插件） | 分发和安装的单位，可以带命令、技能、hook 等内容 |
| hook（钩子） | 在固定时机运行的代码，例如 `prompt.change`、`agent.spawn`、`turn.start` |
| mod | 使用 mod API（日志中以 `$.` 开头，如 `$.ui`、`$.model`）的插件，能画界面、调用模型、改写提示词 |

更新日志里反复出现的说法是“a mod's hook”“a mod's `Input`”“a mod's `Text`”，可见 mod 本质上是一个会注册 hook、并能渲染界面元素的插件。这是根据日志措辞做的归纳，细节以官方文档为准。

## 内置的 “You should know” 做什么？

2.1.287 的日志说明：它是一个内置 mod，由一个旁路 agent 盯着会话，提示你或 Claude 可能漏掉的事。日志给出的启用命令是：

```
/plugin enable cc-plugin-you-should-know@builtin
```

日志同时注明适用于“first-party sessions with telemetry on”，即开启遥测的第一方会话。后续两次小改动：2.1.288（10 月 2 日）让提示根据决策者使用“we”“the main agent”或“you”；2.1.290（10 月 5 日）修复了它不按 `language` 设置输出语言的问题。

## 这两周 mod API 加了什么？

日志里与 mod 相关的条目，按版本整理如下（日期为日志所标）：

| 版本 | 日期 | 变化 |
|---|---|---|
| 2.1.288 | 10 月 2 日 | `$.ui.selection()`：返回全屏模式下最近选中的文字 |
| 2.1.292 | 10 月 6 日 | `$.model.complete` 支持提示缓存，文本块上设 `cache: true`；`claude plugin install` 新增 `--marketplace <source>` |
| 2.1.295 | 10 月 8 日 | `$.ui.notify`：通过你自己的通知设置发出原生通知 |
| 2.1.299 | 10 月 14 日 | `$.prompt.media`、`$.session.identity()`，二者面向由托管设置安装的 mod |
| 2.1.300 | 10 月 14 日 | prompt 装饰新增 `virtualText`；新增 `prompt.change` 钩子；`agent.spawn` 钩子可改写工作流 agent 的 `prompt` 和 `model` |
| 2.1.301 | 10 月 15 日 | `Input` 新增 `rows`，可做多行输入，Enter 提交，Shift+Enter 换行 |

其中提示缓存对成本有直接意义，原理见 [Claude prompt caching 怎么用才省钱](/blog/claude-prompt-caching-save-cost)。

## 怎么装一个 mod 并确认它能用？

1. 升级到 2.1.287 或更高。想用 `--marketplace` 需要 2.1.292 以上。
2. 一步装好并添加来源：`claude plugin install <插件名> --marketplace <source>`。日志说明它会在需要时先添加 marketplace，并执行与 `claude plugin marketplace add` 相同的策略检查。
3. 校验：`claude plugin validate`。2.1.290 起，它会列出 mod 在“可拦截”位置注册的每个 hook，以及有没有 `.catch`（加 `--json` 时字段为 `gatingHooks`）。
4. 需要自动化测试时可以用 `claude plugin test`，具体写法以官方文档为准。
5. 在 `/plugin` 里查看状态。组织用托管设置管理 Claude Code 时，可能影响 mod 的安装与运行，以官方文档为准。

校验的已知点：2.1.292 起，用重复声明或重新赋值的顶层 `var` 读取 `$.state` 的模块会被 `validate` 拒绝。

## 想自己写一个 mod，怎么起步？

最小思路：挑一个钩子，只做一件小事。例如在 `prompt.change` 里读取提示框文字，用 `virtualText` 在输入框里显示一句不会进入草稿的提示。具体的文件结构和 API 签名我没有在公开日志里核实到，请以官方文档为准。2.1.300 的日志提到内置的 `plugin-authoring` 技能负责 mod 的制作和分享，可以让 Claude 带着你搭骨架。

写完先跑 `claude plugin validate`，再装进一个临时项目试，不要一开始就装到日常工作的环境。

## 升级前要看什么？

mod API 在三周内改了很多次，有些是行为变化而不是新增。例如 2.1.301 把 `$.env.set` 改为设置成功后返回 `{}`，被拒绝时返回带原因的 `{ deny }`。已经写了 mod 的人，升级前应逐条看日志。cdnping 的 [官网动态](/changes) 会逐行记录官方更新日志的增删，可以订阅 RSS。

## 和插件目录有什么关系？

Anthropic 的[发布说明](https://support.claude.com/en/articles/12138966-release-notes)在 2026 年 9 月 25 日写明，现在可以通过新的开发者门户把插件提交到 Claude 目录，上线后可看到使用分析。这条说的是面向 Claude 的插件，是否同样适用于 Claude Code 的 mod，请以官方说明为准。

## 相关阅读

- 把 Claude Code 指向自定义接口：[Claude Code 自定义 API 与 Codex、OpenCode 接口地址配置](/blog/configure-custom-api-endpoint-claude-code-codex)
- 升级后连不上：[Claude Code 连接超时和报错怎么排查](/blog/claude-code-connection-troubleshooting)
- 响应变慢：[Claude Code 慢怎么办](/blog/claude-code-slow-response-fix)
- 额度与限制：[Claude Max 5x 和 20x 有什么区别](/blog/claude-max-plan-5x-20x-claude-code)

遇到服务异常，可以先看 [Claude Code 是否在故障中](/down/claude-code) 和 [Anthropic API 状态](/status/anthropic)。

## 参考来源

- [Claude Code 更新日志（2.1.287 至 2.1.302）](https://code.claude.com/docs/en/changelog)
- [Claude 发布说明：Build plugins for Claude（2026 年 9 月 25 日）](https://support.claude.com/en/articles/12138966-release-notes)