File Deleted
View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Plugins 参考
6
7> Claude Code 插件系统的完整技术参考，包括模式、CLI 命令和组件规范。
8
9<Tip>
10 想要安装插件？请参阅 [发现和安装插件](/docs/zh-CN/discover-plugins)。有关创建插件，请参阅 [Plugins](/docs/zh-CN/plugins)。有关分发插件，请参阅 [Plugin marketplaces](/docs/zh-CN/plugin-marketplaces)。
11</Tip>
12
13**插件**是一个自包含的组件目录，使用自定义功能扩展 Claude Code。插件组件包括 skills、agents、hooks、MCP servers、LSP servers 和 monitors。
14
15<h2 id="plugin-components-reference">
16 插件组件参考
17</h2>
18
19<h3 id="skills">
20 Skills
21</h3>
22
23插件向 Claude Code 添加 skills，创建可由您或 Claude 调用的 `/name` 快捷方式。
24
25**位置**：插件根目录中的 `skills/` 或 `commands/` 目录，或插件根目录中的单个 `SKILL.md` 文件
26
27**文件格式**：Skills 是包含 `SKILL.md` 的目录；commands 是简单的 markdown 文件
28
29**Skill 结构**：
30
31```text theme={null}
32skills/
33├── pdf-processor/
34│ ├── SKILL.md
35│ ├── reference.md (optional)
36│ └── scripts/ (optional)
37└── code-reviewer/
38 └── SKILL.md
39```
40
41安装插件时会自动发现 Skills 和 commands。
42
43如果插件没有 `skills/` 目录且没有 `skills` manifest 字段，则插件根目录中的 `SKILL.md` 会作为单个 skill 加载。设置 frontmatter `name` 字段来控制 skill 的调用名称。如果没有设置，Claude Code 会回退到安装目录名称。对于 [复制到缓存中](#plugin-caching-and-file-resolution) 的插件，该名称是一个在每次更新时都会改变的版本字符串。对于包含多个 skill 的插件，请使用上面所示的 `skills/` 目录布局。
44
45在插件 skills 和 commands 中，Boolean frontmatter 字段（如 `disable-model-invocation`）接受 `yes`、`no`、`on`、`off`、`1` 和 `0`（任何字母大小写），以及 `true` 和 `false`。在 v2.1.218 之前，Claude Code 仅识别 `true` 和 `false`。
46
47有关完整详情，请参阅 [Skills](/docs/zh-CN/skills)。
48
49<h3 id="agents">
50 Agents
51</h3>
52
53插件可以为特定任务提供专门的子代理，Claude 可以在适当时自动调用这些代理。
54
55**位置**：插件根目录中的 `agents/` 目录
56
57**文件格式**：描述代理功能的 markdown 文件
58
59**Agent 结构**：
60
61```markdown theme={null}
62name: agent-name
63description: What this agent specializes in and when Claude should invoke it
64model: sonnet
65effort: medium
66maxTurns: 20
67disallowedTools: Write, Edit
68
69Detailed system prompt for the agent describing its role, expertise, and behavior.
70```
71
72<h4 id="plugin-agent-frontmatter">
73 插件代理 frontmatter
74</h4>
75
76插件代理文件使用与 [子代理文件相同的 frontmatter 字段](/docs/zh-CN/sub-agents#supported-frontmatter-fields)，但当代理来自插件时，Claude Code 仅支持其中的某些字段：
77
78* **支持**：`name`、`description`、`model`、`effort`、`maxTurns`、`tools`、`disallowedTools`、`skills`、`memory`、`background`、`omitClaudeMd`、`isolation`、`color` 和 `experimental`。唯一有效的 `isolation` 值是 `"worktree"`。
79* **出于安全原因不支持**：`hooks`、`mcpServers` 和 `permissionMode`。Claude Code 在从插件加载代理时会忽略这些。要使用它们，请将代理文件复制到 `.claude/agents/` 或 `~/.claude/agents/`。
80* **不支持**：`initialPrompt`。
81
82您可以将插件代理文件放在 `agents/` 的子文件夹中。Claude Code [递归加载它们](/docs/zh-CN/sub-agents#choose-the-subagent-scope)，并使用冒号连接插件名称、每个子文件夹名称和文件名来形成代理的作用域名称。例如，名为 `my-plugin` 的插件中的 `agents/review/security.md` 加载为 `my-plugin:review:security`。两个设置会改变该名称：
83
84* Frontmatter `name`：它仅替换文件名，因此 `agents/review/security.md` 中的 `name: audit` 加载为 `my-plugin:review:audit`
85* Manifest [`agents`](#component-path-fields) 字段：您在其中列出的文件加载时不带子文件夹名称，因此 `"agents": "./custom/review/security.md"` 加载为 `my-plugin:security`
86
87Claude Code 加载插件代理，即使其 frontmatter 没有 `name` 或无法解析：
88
89* 没有 `name`：Claude Code 根据文件名命名代理，因此名为 `my-plugin` 的插件中的 `agents/reviewer.md` 加载为 `my-plugin:reviewer`
90* Frontmatter 无法解析：Claude Code 根据文件名命名代理，使用 `Agent from my-plugin plugin` 作为其描述，并忽略文件中的每个字段
91
92相比之下，Claude Code 会跳过其 frontmatter 没有 `name` 或无法解析的项目、用户或托管代理文件。
93
94要查找插件默认 `agents/` 目录中 frontmatter 无法解析的文件，请运行 `claude plugin validate`。您传递的路径取决于插件是否有 manifest，两个示例都使用 `./my-plugin` 作为插件目录：
95
96* 具有 manifest 的插件：`claude plugin validate ./my-plugin`
97* 没有 manifest 的插件：`claude plugin validate ./my-plugin/agents`。需要 Claude Code v2.1.233 或更高版本。
98
99启用插件后，代理会在 [@-mention 类型提示](/docs/zh-CN/sub-agents#invoke-subagents-explicitly) 中显示其作用域名称，例如 `my-plugin:code-reviewer`。
100
101有关完整详情，请参阅 [Subagents](/docs/zh-CN/sub-agents)。
102
103<h3 id="hooks">
104 Hooks
105</h3>
106
107插件可以提供事件处理程序，自动响应 Claude Code 事件。
108
109**位置**：插件根目录中的 `hooks/hooks.json`，或在 plugin.json 中内联
110
111**格式**：具有事件匹配器和操作的 JSON 配置
112
113`hooks/hooks.json` 可以包含一个顶级 `$schema` 键，该键命名一个 JSON Schema URL 以用于编辑器自动完成和验证。Claude Code 在加载时忽略该键。
114
115**Hook 配置**：
116
117```json theme={null}
118{
119 "hooks": {
120 "PostToolUse": [
121 {
122 "matcher": "Write|Edit",
123 "hooks": [
124 {
125 "type": "command",
126 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
127 }
128 ]
129 }
130 ]
131 }
132}
133```
134
135插件 hooks 响应与 [用户定义的 hooks](/docs/zh-CN/hooks) 相同的生命周期事件：
136
137| 事件 | 触发时机 |
138| :-------------------- | :--------------------------------------------------------------------------------------------------------------------- |
139| `SessionStart` | 当会话开始或恢复时 |
140| `Setup` | 当你使用 `--init-only` 启动 Claude Code，或在 `-p` 模式下使用 `--init` 或 `--maintenance` 时。用于 CI 或脚本中的一次性准备 |
141| `UserPromptSubmit` | 当你提交提示词时，在 Claude 处理之前 |
142| `UserPromptExpansion` | 当用户输入的命令扩展为提示词时，在到达 Claude 之前。可以阻止扩展 |
143| `PreToolUse` | 在工具调用执行之前。可以阻止它 |
144| `PermissionRequest` | 当工具调用需要权限决策时 |
145| `PermissionDenied` | 当自动模式拒绝工具调用时，包括没有分类器判决的拒绝。使用 JSON `hookSpecificOutput.retry: true` 来告诉模型它可以重试被拒绝的工具调用。Claude Code 在分类器未产生判决时忽略 `retry` |
146| `PostToolUse` | 在工具调用成功后 |
147| `PostToolUseFailure` | 在工具调用失败后 |
148| `PostToolBatch` | 在一整批并行工具调用解决后，在下一次模型调用之前 |
149| `Notification` | 当 Claude Code 发送通知时 |
150| `MessageDisplay` | 当助手消息文本正在显示时 |
151| `SubagentStart` | 当子代理被生成时 |
152| `SubagentStop` | 当子代理完成时 |
153| `TaskCreated` | 当通过 `TaskCreate` 创建任务时 |
154| `TaskCompleted` | 当任务被标记为已完成时 |
155| `Stop` | 当 Claude 完成响应时 |
156| `StopFailure` | 当轮次因 API 错误而结束时 |
157| `TeammateIdle` | 当[代理团队](/docs/zh-CN/agent-teams)队友即将空闲时 |
158| `InstructionsLoaded` | 当 CLAUDE.md 或 `.claude/rules/*.md` 文件被加载到上下文中时。在会话开始时和文件在会话期间被延迟加载时触发 |
159| `ConfigChange` | 当配置文件在会话期间更改时 |
160| `CwdChanged` | 当工作目录更改时，例如当 Claude 执行 `cd` 命令时。对于使用 direnv 等工具的反应式环境管理很有用 |
161| `DirectoryAdded` | 当工作目录在会话中期通过 `/add-dir` 或 SDK `register_repo_root` 控制请求添加时 |
162| `FileChanged` | 当监视的文件在磁盘上更改时。`matcher` 字段指定要监视的文件名 |
163| `WorktreeCreate` | 当通过 `--worktree`、`isolation: "worktree"` 创建工作树时，或用于后台会话。替换默认的 git 行为 |
164| `WorktreeRemove` | 当在会话退出时、子代理完成时或删除后台会话时移除工作树 |
165| `PreCompact` | 在上下文压缩之前 |
166| `PostCompact` | 在上下文压缩完成后 |
167| `PreModelSwitch` | 在 Claude Code 应用你或客户端请求的模型切换之前。可以阻止切换 |
168| `PostModelSwitch` | 在会话的模型更改后，包括 Claude Code 自己进行的更改，例如在你恢复会话时恢复模型 |
169| `Elicitation` | 当 MCP 服务器在工具调用期间请求用户输入时 |
170| `ElicitationResult` | 在用户响应 MCP 引出后，在响应发送回服务器之前 |
171| `SessionEnd` | 当会话终止时 |
172
173**Hook 类型**：
174
175* `command`：执行 shell 命令或脚本
176* `http`：将事件 JSON 作为 POST 请求发送到 URL
177* `mcp_tool`：在配置的 [MCP server](/docs/zh-CN/mcp) 上调用工具
178* `prompt`：使用 LLM 评估提示（使用 `$ARGUMENTS` 占位符作为上下文）
179* `agent`：运行具有工具的代理验证器以完成复杂验证任务
180
181针对插件自己的 [捆绑 MCP server](#mcp-servers) 的 hooks 必须使用其作用域名称。工具匹配器和 `if` 字段采用作用域工具名称 `mcp__plugin_<plugin-name>_<server-name>__<tool>`，`mcp_tool` hook 的 `server` 字段采用 `plugin:<plugin-name>:<server-name>`。针对裸服务器密钥编写的匹配器永远不会触发。请参阅 [Match MCP tools](/docs/zh-CN/hooks#match-mcp-tools) 和 [Plugin-provided MCP servers](/docs/zh-CN/mcp#plugin-provided-mcp-servers)。
182
183<h3 id="mcp-servers">
184 MCP servers
185</h3>
186
187插件可以捆绑 Model Context Protocol (MCP) 服务器，以将 Claude Code 与外部工具和服务连接。
188
189**位置**：插件根目录中的 `.mcp.json`，或在 plugin.json 中内联
190
191**格式**：标准 MCP 服务器配置
192
193**MCP 服务器配置**：
194
195```json theme={null}
196{
197 "mcpServers": {
198 "plugin-database": {
199 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
200 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
201 "env": {
202 "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
203 }
204 },
205 "plugin-api-client": {
206 "command": "npx",
207 "args": ["@company/mcp-server", "--plugin-mode"]
208 }
209 }
210}
211```
212
213**集成行为**：
214
215* 启用插件时，插件 MCP 服务器会自动启动
216* 服务器在 Claude 的工具包中显示为标准 MCP 工具
217* 插件服务器可以独立于用户 MCP 服务器进行配置
218* 如果您在会话中途运行 [`/reload-plugins`](/docs/zh-CN/discover-plugins#apply-plugin-changes-without-restarting)，Claude Code 会保持配置未更改的服务器的实时连接
219
220<h3 id="lsp-servers">
221 LSP servers
222</h3>
223
224<Tip>
225 想要使用 LSP 插件？从官方市场安装它们：在 `/plugin` Discover 选项卡中搜索"lsp"。本部分记录如何为官方市场未涵盖的语言创建 LSP 插件。
226</Tip>
227
228插件可以提供 [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) 服务器，以在处理您的代码库时为 Claude 提供 [实时代码智能](/docs/zh-CN/discover-plugins#code-intelligence)。
229
230**位置**：插件根目录中的 `.lsp.json`，或在 `plugin.json` 中内联
231
232**格式**：将语言服务器名称映射到其配置的 JSON 配置
233
234**`.lsp.json` 文件格式**：
235
236```json theme={null}
237{
238 "go": {
239 "command": "gopls",
240 "args": ["serve"],
241 "extensionToLanguage": {
242 ".go": "go"
243 }
244 }
245}
246```
247
248**在 `plugin.json` 中内联**：
249
250```json theme={null}
251{
252 "name": "my-plugin",
253 "lspServers": {
254 "go": {
255 "command": "gopls",
256 "args": ["serve"],
257 "extensionToLanguage": {
258 ".go": "go"
259 }
260 }
261 }
262}
263```
264
265**必需字段：**
266
267| 字段 | 描述 |
268| :-------------------- | :------------------------- |
269| `command` | 要执行的 LSP 二进制文件（必须在 PATH 中） |
270| `extensionToLanguage` | 将文件扩展名映射到语言标识符 |
271
272**可选字段：**
273
274| 字段 | 描述 |
275| :---------------------- | :------------------------------------------------------------------------------------------ |
276| `args` | LSP 服务器的命令行参数 |
277| `transport` | 通信传输：`stdio`（默认）或 `socket`。Claude Code 接受 `socket` 但在 stdio 上运行每个服务器，因此 stdout 协议规则适用于所有服务器 |
278| `env` | 启动服务器时要设置的环境变量 |
279| `initializationOptions` | 在初始化期间传递给服务器的选项 |
280| `settings` | 通过 `workspace/didChangeConfiguration` 传递的设置 |
281| `workspaceFolder` | 服务器的工作区文件夹路径 |
282| `startupTimeout` | 等待服务器启动的最长时间（毫秒） |
283| `shutdownTimeout` | 等待正常关闭的最长时间（毫秒）。当超时时间过去时，Claude Code 会终止服务器进程。未设置时，不适用超时 |
284| `restartOnCrash` | 服务器崩溃后是否重新启动。默认为 `true`。设置为 `false` 以保持崩溃的服务器停止而不是重新启动它 |
285| `maxRestarts` | 放弃前的最大重启尝试次数 |
286| `diagnostics` | 编辑后是否将诊断推送到 Claude 的上下文中（默认 `true`）。设置为 `false` 以保持代码导航但禁止自动诊断注入。 |
287
288`restartOnCrash` 和 `shutdownTimeout` 需要 Claude Code v2.1.205 或更高版本。在 v2.1.205 之前，配置架构接受两个选项，但设置其中任何一个都会导致 Claude Code 在启动时完全跳过该 LSP 服务器，原因仅在 `claude --debug` 输出中可见。
289
290**同一扩展名的多个服务器**：当多个启用的 LSP 服务器在 `extensionToLanguage` 中声明相同的文件扩展名时，无论服务器来自一个插件还是来自不同的插件，第一个注册的服务器处理具有该扩展名的文件，其他服务器永远不会启动。`/plugin` 界面显示一个警告，命名其服务器处于活动状态的插件。
291
292**无法初始化的服务器**：Claude Code 会跳过配置无效的服务器，例如缺少 `command` 或 `extensionToLanguage` 的服务器，其他配置的服务器仍会启动。运行 `claude --debug` 以查看服务器被跳过的原因。
293
294被跳过的服务器不会声明其文件扩展名，因此声明相同扩展名的另一个有效服务器（来自同一插件或不同插件）仍会处理这些文件。
295
296**将日志输出发送到 stderr，而不是 stdout**：Claude Code 仅将服务器的 stdout 读取为协议消息，并接受最大 64 KiB 的消息头和最大 32 MiB 的消息体。Claude Code 会断开超过任一限制或向 stdout 写入非协议输出的服务器，并将断开连接计为 `restartOnCrash` 和 `maxRestarts` 的崩溃。当您使用 `--debug` 运行时，Claude Code 会将命名原因的错误写入调试日志。
297
298<Warning>
299 **您必须单独安装语言服务器二进制文件。** LSP 插件配置 Claude Code 如何连接到语言服务器，但它们不包括服务器本身。如果您在 `/plugin` Errors 选项卡中看到 `Executable not found in $PATH`，请为您的语言安装所需的二进制文件。
300</Warning>
301
302**可用的 LSP 插件：**
303
304| 插件 | 语言服务器 | 安装命令 |
305| :------------------ | :------------------------- | :------------------------------------------------------------------------------ |
306| `pyright-lsp` | Pyright (Python) | `pip install pyright` 或 `npm install -g pyright` |
307| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |
308| `rust-analyzer-lsp` | rust-analyzer | [参见 rust-analyzer 安装](https://rust-analyzer.github.io/manual.html#installation) |
309
310首先安装语言服务器，然后从市场安装插件。
311
312<h3 id="monitors">
313 Monitors
314</h3>
315
316插件可以声明后台监视器，Claude Code 在插件处于活动状态时自动启动。每个监视器在会话的生命周期内运行 shell 命令，并将每个 stdout 行作为通知传递给 Claude，以便 Claude 可以对日志条目、状态更改或轮询事件做出反应，而无需被要求自己启动监视。
317
318插件监视器使用与 [Monitor tool](/docs/zh-CN/tools-reference#monitor-tool) 相同的机制，并共享其可用性约束。它们仅在交互式 CLI 会话中运行，以与 [hooks](#hooks) 相同的信任级别在非沙箱环境中运行，并在 Monitor tool 不可用的主机上被跳过。
319
320**位置**：插件根目录中的 `monitors/monitors.json`，或在 `plugin.json` 中内联
321
322**格式**：监视器条目的 JSON 数组
323
324以下 `monitors/monitors.json` 监视部署状态端点和本地错误日志：
325
326```json theme={null}
327[
328 {
329 "name": "deploy-status",
330 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
331 "description": "Deployment status changes"
332 },
333 {
334 "name": "error-log",
335 "command": "tail -F ./logs/error.log",
336 "description": "Application error log",
337 "when": "on-skill-invoke:debug"
338 }
339]
340```
341
342要内联声明监视器，请在 `plugin.json` 中将 `experimental.monitors` 设置为相同的数组。要从非默认路径加载，请将 `experimental.monitors` 设置为相对路径字符串，例如 `"./config/monitors.json"`。监视器是 [实验性组件](#experimental-components)。
343
344**必需字段：**
345
346| 字段 | 描述 |
347| :------------ | :------------------------------------- |
348| `name` | 在插件中唯一的标识符。防止插件重新加载或再次调用 skill 时出现重复进程 |
349| `command` | 在会话工作目录中作为持久后台进程运行的 shell 命令 |
350| `description` | 正在监视的内容的简短摘要。显示在任务面板和通知摘要中 |
351
352**可选字段：**
353
354| 字段 | 描述 |
355| :----- | :---------------------------------------------------------------------------------------------------- |
356| `when` | 控制监视器何时启动。`"always"` 在会话启动和插件重新加载时启动它，这是默认值。`"on-skill-invoke:<skill-name>"` 在第一次调度此插件中的命名 skill 时启动它 |
357
358`command` 值支持 [路径替换](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_PLUGIN_DATA}` 和 `${CLAUDE_PROJECT_DIR}`，以及环境中的任何 `${ENV_VAR}`。如果脚本需要从插件自己的目录运行，请在命令前加上 `cd "${CLAUDE_PLUGIN_ROOT}" && `。
359
360监视器 `command` 不能引用 [`${user_config.*}`](#user-configuration) 值。命令通过 shell 运行，因此 Claude Code 会拒绝监视器并显示 [错误](/docs/zh-CN/errors#plugin-command-references-user-config)，而不是替换该值。监视器进程不会接收 `CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量，因此让监视器脚本从它拥有的配置文件中读取该值。
361
362如果您在会话中途禁用插件，Claude Code 不会停止已在运行的监视器；它们在会话结束时停止。
363
364<h3 id="themes">
365 Themes
366</h3>
367
368插件可以提供颜色主题，这些主题与内置预设和用户的本地主题一起显示在 `/theme` 中。主题是 `themes/` 中的 JSON 文件，具有 `base` 预设和稀疏的 `overrides` 颜色令牌映射。主题是 [实验性组件](#experimental-components)。
369
370```json theme={null}
371{
372 "name": "Dracula",
373 "base": "dark",
374 "overrides": {
375 "claude": "#bd93f9",
376 "error": "#ff5555",
377 "success": "#50fa7b"
378 }
379}
380```
381
382当用户选择插件主题时，Claude Code 会在其配置中保存 `custom:<plugin-name>:<slug>`。插件主题是只读的：当用户在 `/theme` 中按 `Ctrl+E` 时，Claude Code 会将其复制到 `~/.claude/themes/` 中，以便他们可以编辑副本。
383
384***
385
386<h2 id="plugin-installation-scopes">
387 Plugin 安装作用域
388</h2>
389
390当你安装一个 plugin 时，你选择一个**作用域**来确定 plugin 在哪里可用以及谁可以使用它：
391
392| 作用域 | 设置文件 | 用例 |
393| :-------- | :------------------------------------------ | :----------------------------------------------- |
394| `user` | `~/.claude/settings.json` | 在所有项目中可用的个人 plugins（默认） |
395| `project` | `.claude/settings.json` | 通过版本控制共享的团队 plugins |
396| `local` | `.claude/settings.local.json` | 项目特定的 plugins，当 Claude Code 保存设置到其中时被 gitignored |
397| `managed` | [Managed settings](/docs/zh-CN/managed-settings) | 托管 plugins（只读，仅更新） |
398
399Plugins 使用与其他 Claude Code 配置相同的作用域系统。有关安装说明和作用域标志，请参阅 [Install plugins](/docs/zh-CN/discover-plugins#install-plugins)。有关作用域的完整说明，请参阅 [Configuration scopes](/docs/zh-CN/settings#where-settings-live)。
400
401***
402
403<h2 id="skills-directory-plugins">
404 Skills-directory plugins
405</h2>
406
407任何 skills 目录下包含 `.claude-plugin/plugin.json` 清单的文件夹都会在下一个会话中作为名为 `<name>@skills-dir` 的 plugin 加载，无需 marketplace，也无需安装步骤。使用 [`plugin init`](#plugin-init) 来搭建一个。与复制的 marketplace 安装不同，该 plugin 是在原地发现的，而不是复制到 plugin 缓存中。
408
409A skills directory tree supports three distinct things:
410
411| What you have | What it is |
412| :-------------------------------------------- | :------------------------------------------------------- |
413| `<skills-dir>/foo/SKILL.md` with no manifest | 一个名为 `foo` 的普通 [skill](/docs/zh-CN/skills) |
414| `<skills-dir>/foo/.claude-plugin/plugin.json` | 一个 plugin `foo@skills-dir`，可以捆绑自己的 skills、agents、hooks 等 |
415| `<plugin>/skills/bar/SKILL.md` | 一个 skill `bar`，打包在 plugin 内部 |
416
417<h3 id="choose-where-the-plugin-loads-from">
418 选择 plugin 从哪里加载
419</h3>
420
421| Skills directory | Scope | Loads |
422| :---------------------- | :------- | :--------------------------------------------------------------------------------------- |
423| `~/.claude/skills/` | personal | 在每个项目中加载，因为该位置仅属于你 |
424| `<cwd>/.claude/skills/` | project | 仅在你接受该文件夹的工作区 [trust dialog](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 后加载 |
425
426项目范围的 plugin 被检入到仓库中，并到达克隆它的每个协作者。因为该内容来自仓库而不是来自你，它仅在与 `.claude/settings.json` 中的项目允许规则相同的信任门控后加载，所以信任父文件夹或使用 `-p` 运行是不够的，运行代码的组件受到进一步限制：
427
428* 它声明的 MCP servers 会经过与项目 `.mcp.json` 相同的 [per-server approval](/docs/zh-CN/mcp)
429* LSP servers 仅在你信任工作区后启动
430* [Background monitors](#monitors) 不加载
431
432Personal-scope plugins 没有这些限制。
433
434<Warning>
435 Project-scope `@skills-dir` plugins 仅从会话的 [primary working directory](/docs/zh-CN/permissions#working-directories) 的 `.claude/skills/` 加载。它们不会像普通 skills 和 commands 那样 [walk up to the repository root](/docs/zh-CN/skills#discovery-from-parent-and-nested-directories)，所以从子目录启动会错过位于仓库根目录的 plugin。从仓库根目录启动，或在 v2.1.246 或更高版本上 [使用 `/cd` 将会话移动到那里](/docs/zh-CN/permissions#move-the-session-to-another-directory)。
436</Warning>
437
438<h3 id="edit-reload-and-disable-a-skills-directory-plugin">
439 编辑、重新加载和禁用 skills-directory plugin
440</h3>
441
442你对 skill 的 `SKILL.md` 所做的更改会立即在当前会话中生效。对 plugin 的其他组件（如 `hooks/`、`.mcp.json`、`agents/` 和 `output-styles/`）的更改则不会。运行 `/reload-plugins` 或重启 Claude Code 来获取这些更改。参见 [Live change detection](/docs/zh-CN/skills#live-change-detection)。
443
444要停止加载 skills-directory plugin，删除其文件夹或按名称禁用它。没有 `uninstall` 步骤，因为没有从 marketplace 安装任何东西。
445
446```bash theme={null}
447claude plugin disable my-tool@skills-dir
448```
449
450***
451
452<h2 id="synced-plugins">
453 从 claude.ai 同步的插件
454</h2>
455
456Claude Code 加载为你的 claude.ai 账户启用的插件，包括你的组织为其成员启用的插件，以及你从 marketplace 安装的插件。它将每个插件下载到 `~/.claude/plugins/synced/` 中，并将其加载为 `<name>@synced`，没有 marketplace 和没有安装记录。同步的插件运行时具有与你安装的 marketplace 插件相同的信任级别：其 skills、agents、hooks、MCP servers 和 LSP servers 都会加载。
457
458Claude Code 同步这些插件的位置取决于会话类型：
459
460* 在 [Cowork](https://claude.com/product/cowork) 和[云会话](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)中，Claude Code 在会话启动时将它们下载到会话自身的环境中。在 v2.1.239 之前，Claude Code 将这些插件加载为 `<name>@inline`，这是 `--plugin-dir` 插件使用的身份。
461* 在你使用 claude.ai 账户登录的终端会话中，Claude Code 每次启动时检查你的账户一次，然后在后台下载新的和更新的插件，并删除你或你的组织关闭的插件。在终端会话中同步需要 Claude Code v2.1.273 或更高版本。
462
463启动检查在后台运行，因此可以在你的会话启动后完成。当它在交互式会话中添加、更新或删除同步插件时，Claude Code 会显示 `Plugins changed. Run /reload-plugins to activate.` 运行 [`/reload-plugins`](/docs/zh-CN/discover-plugins#apply-plugin-changes-without-restarting) 以在该会话中加载更改，或者等待下次启动 Claude Code 时加载。如果你在会话运行时在 claude.ai 上启用插件，Claude Code 会在下次启动时下载它。
464
465终端会话中的插件同步在与[从 claude.ai 同步的 skills](/docs/zh-CN/skills#where-synced-skills-load)相同的登录条件下运行。它还需要一个授予 Claude Code 访问你账户插件权限的登录。
466
467来自早期版本 Claude Code 的登录会在 Claude Code 在后台更新该登录时（通常在几小时内）或如果你再次运行 `/login` 时立即获取插件访问权限。在此之后，下次启动 Claude Code 时插件同步就会开始。
468
469`claude plugin list` 在 `Synced from claude.ai` 标题下显示同步的插件，`/plugin` **Installed** 标签页将它们列出，其来源为 `synced`。通过 `claude plugin list` 打印的 `<name>@synced` ID 来管理同步的插件：
470
471* **关闭一个插件**：运行 `claude plugin disable <name>@synced`，或从 `/plugin` **Installed** 标签页禁用它。Claude Code 会将该选择保存为你用户级 [`enabledPlugins`](/docs/zh-CN/settings-reference#enabledplugins) 中的 `"<name>@synced": false`。要重新打开该插件，运行 `claude plugin enable <name>@synced`。
472* **在任何地方都排除一个插件**：[为你的 claude.ai 账户关闭该插件](/docs/zh-CN/desktop#extend-claude-code)。要在每个环境中将其排除在一个项目之外，在该项目的已提交 `.claude/settings.json` 中的 `enabledPlugins` 下设置 `"<name>@synced": false`。
473* **在 claude.ai 上管理插件本身**：`claude plugin install`、`update` 和 `uninstall` 不适用于同步的插件。Claude Code 在下次同步时下载插件的更新。要删除一个，为你的 claude.ai 账户关闭该插件，Claude Code 会在下次同步时删除它。
474* **停止在一台机器上同步**：在你的用户设置中将 [`syncClaudeAiPlugins`](/docs/zh-CN/settings-reference#syncclaudeaiplugins) 设置为 `false`。Claude Code 停止下载，下次启动时会将它已同步的插件移动到 `~/.claude/plugins/.trash/` 并不再加载它们。你的组织可以在[托管设置](/docs/zh-CN/managed-settings)中设置相同的键，或关闭 claude.ai 上的 Skills，这也会停止插件同步。
475
476你无法关闭你的组织在 claude.ai 上标记为必需的插件。Claude Code 会加载它，即使你之前禁用了它，`claude plugin disable` 会拒绝并显示 `Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.` 在 `claude plugin list` 中，这些插件被标记为 `required by your org`。
477
478当来自任何其他来源的启用插件与同步插件的名称匹配时，Claude Code 会加载该插件并报告同步副本未加载。其他来源包括 marketplace 安装、[skills-directory 插件](#skills-directory-plugins)、`--plugin-dir` 插件和 Claude Code 内置的插件。要改用 claude.ai 副本，请禁用你自己的副本。在 v2.1.239 之前，Claude Code 会加载同步副本而不是同名的 marketplace 安装。
479
480***
481
482<h2 id="plugin-manifest-schema">
483 Plugin manifest schema
484</h2>
485
486`.claude-plugin/plugin.json` 文件定义了你的插件的元数据和配置。
487
488manifest 是可选的。如果省略，Claude Code 会在[默认位置](#file-locations-reference)自动发现组件，并从目录名称派生插件名称。当你需要提供元数据或自定义组件路径时，使用 manifest。
489
490<h3 id="complete-schema">
491 Complete schema
492</h3>
493
494```json theme={null}
495{
496 "name": "plugin-name",
497 "displayName": "Plugin Name",
498 "version": "1.2.0",
499 "description": "Brief plugin description",
500 "author": {
501 "name": "Author Name",
502 "email": "author@example.com",
503 "url": "https://github.com/author"
504 },
505 "homepage": "https://docs.example.com/plugin",
506 "repository": "https://github.com/author/plugin",
507 "license": "MIT",
508 "keywords": ["keyword1", "keyword2"],
509 "metadata": { "catalogId": "cat-123", "tier": "pro" },
510 "skills": "./custom/skills/",
511 "commands": ["./custom/commands/special.md"],
512 "agents": ["./custom/agents/reviewer.md"],
513 "hooks": "./config/hooks.json",
514 "mcpServers": "./mcp-config.json",
515 "outputStyles": "./styles/",
516 "lspServers": "./.lsp.json",
517 "experimental": {
518 "themes": "./themes/",
519 "monitors": "./monitors.json",
520 "evals": "quality/evals"
521 },
522 "dependencies": [
523 "helper-lib",
524 { "name": "secrets-vault", "version": "~2.1.0" }
525 ]
526}
527```
528
529<h3 id="required-fields">
530 必需字段
531</h3>
532
533如果你包含 manifest，`name` 是唯一必需的字段。
534
535| 字段 | 类型 | 描述 | 示例 |
536| :----- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |
537| `name` | string | 唯一标识符，采用 kebab-case，不包含空格、控制字符或双向格式化字符。当[marketplace 条目](/docs/zh-CN/plugin-marketplaces#plugin-entries)以不同的名称列出插件时，marketplace 条目名称是 `enabledPlugins` 键和 `/plugin` 使用的名称 | `"deployment-tools"` |
538
539此名称用于命名空间组件。例如，在 UI 中，名称为 `plugin-dev` 的插件的代理 `agent-creator` 将显示为 `plugin-dev:agent-creator`。
540
541<h3 id="unrecognized-fields">
542 无法识别的字段
543</h3>
544
545Claude Code 忽略它不识别的顶级字段。你可以在 `plugin.json` 中保留来自另一个生态系统的元数据，插件仍然会加载。这使得维护一个 manifest 作为 VS Code 或 Cursor 扩展 manifest、npm `package.json` 或 MCPB/DXT bundle manifest 变得实用。
546
547`claude plugin validate` 将无法识别的字段报告为警告，而不是错误。如果一个字段与识别的字段相差一两个字符，警告会建议可能的预期名称。仅具有无法识别字段警告的插件仍然通过验证并在运行时加载。
548
549Claude Code 如何处理值类型错误的识别字段取决于该字段：
550
551* **大多数字段**：插件无法加载。例如，`keywords` 值是字符串而不是数组是加载错误，`claude plugin validate` 会将其报告为错误。
552* **`experimental` 和 `metadata`**：Claude Code 忽略非对象值，`claude plugin validate` 报告警告。
553
554传递 `--strict` 以将警告视为错误。在 CI 中使用它来捕获拼写错误的字段名称或在发布前留下的来自另一个工具的 manifest 的字段，即使插件在运行时会加载。
555
556```bash theme={null}
557claude plugin validate ./my-plugin --strict
558```
559
560<h3 id="metadata-fields">
561 元数据字段
562</h3>
563
564| 字段 | 类型 | 描述 | 示例 |
565| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
566| `$schema` | string | JSON Schema URL，用于编辑器自动完成和验证。Claude Code 在加载时忽略此字段。 | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |
567| `displayName` | string | 在 `/plugin` 选择器和其他 UI 表面中显示的人类可读名称。对于 marketplace 安装的插件，[marketplace 条目](/docs/zh-CN/plugin-marketplaces#optional-plugin-fields)上的 `displayName` 优先于此值。当两个地方都未设置显示名称时，用户会看到 `name`。与 `name` 不同，可以包含空格和任何大小写。不用于命名空间或查找。 | `"Deployment Tools"` |
568| `version` | string | 可选。语义版本。设置此项会将插件固定到该版本字符串，因此用户仅在你提升版本时才会收到更新，除了[`command` 源](/docs/zh-CN/plugin-marketplaces#command-sources)或[加载到位](#plugin-caching-and-file-resolution)的插件；请参阅[版本管理](#version-management)。如果也在 marketplace 条目中设置，`plugin.json` 优先。如果省略，版本来自[版本管理](#version-management)中的下一个源。 | `"2.1.0"` |
569| `description` | string | 插件用途的简要说明 | `"Deployment automation tools"` |
570| `author` | object | 作者信息 | `{"name": "Dev Team", "email": "dev@company.com"}` |
571| `homepage` | string | 文档 URL | `"https://docs.example.com"` |
572| `repository` | string | 源代码 URL | `"https://github.com/user/plugin"` |
573| `license` | string | 许可证标识符 | `"MIT"`、`"Apache-2.0"` |
574| `keywords` | array | 发现标签 | `["deployment", "ci-cd"]` |
575| `metadata` | object | 自由格式对象，用于你自己的数据，例如权利或目录字段。Claude Code 不读取它，因此值永远不会影响插件行为。Claude Code 忽略非对象值，`claude plugin validate` 报告警告。在 v2.1.222 之前，Claude Code 将该键视为[无法识别的字段](#unrecognized-fields)。 | `{"catalogId": "cat-123"}` |
576| `defaultEnabled` | boolean | 当用户未设置插件状态时，插件是否以启用状态启动。默认为 `true`。请参阅[默认启用](#default-enablement)。 | `false` |
577
578<h3 id="default-enablement">
579 默认启用
580</h3>
581
582在 `plugin.json` 中设置 `defaultEnabled: false` 以发布禁用状态下安装的插件。用户使用 `claude plugin enable <plugin>` 或 `/plugin` 界面将其打开。对于添加成本或用户应该选择加入的范围的插件（例如连接到外部服务的插件），使用此选项。
583
584`defaultEnabled` 是当没有其他因素决定插件状态时的后备。用户的设置和依赖项要求优先于它：
585
586* **用户的设置**：任何设置范围内 `enabledPlugins` 中的插件条目。一旦写入，它会在插件更新和重新安装中持续存在，因此在后续版本中更改 `defaultEnabled` 不会翻转现有用户。
587* **依赖项要求**：当插件被活跃的另一个插件所需时，Claude Code 在安装或启用时为其写入 `true`。这给了它一个显式设置，所以它自己的默认值不再适用。请参阅[启用或禁用具有依赖项的插件](/docs/zh-CN/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)。
588
589同一字段也可以出现在插件的 marketplace 条目中，其中它优先于 `plugin.json` 中的值。请参阅[可选插件字段](/docs/zh-CN/plugin-marketplaces#optional-plugin-fields)。
590
591<h3 id="component-path-fields">
592 组件路径字段
593</h3>
594
595| 字段 | 类型 | 描述 | 示例 |
596| :---------------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------- |
597| `skills` | string\|array | 包含 `<name>/SKILL.md` 的自定义 skill 目录。添加到默认 `skills/` 扫描。请参阅[路径行为规则](#path-behavior-rules)了解 marketplace-root 异常 | `"./custom/skills/"` |
598| `commands` | string\|array | 自定义平面 `.md` skill 文件或目录（替换默认 `commands/`） | `"./custom/cmd.md"` 或 `["./cmd1.md"]` |
599| `agents` | string\|array | 自定义代理文件（替换默认 `agents/`） | `"./custom/agents/reviewer.md"` |
600| `workflows` | string\|array | 自定义[工作流](/docs/zh-CN/workflows)脚本文件或目录（替换默认 `workflows/`） | `"./custom/workflows/"` |
601| `hooks` | string\|array\|object | Hook 配置路径或内联配置 | `"./my-extra-hooks.json"` |
602| `mcpServers` | string\|array\|object | MCP 配置路径或内联配置 | `"./my-extra-mcp-config.json"` |
603| `outputStyles` | string\|array | 自定义输出样式文件/目录（替换默认 `output-styles/`） | `"./styles/"` |
604| `lspServers` | string\|array\|object | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) 配置，用于代码智能（转到定义、查找引用等） | `"./.lsp.json"` |
605| `experimental.themes` | string\|array | 颜色主题文件/目录（替换默认 `themes/`）。请参阅[主题](#themes) | `"./themes/"` |
606| `experimental.monitors` | string\|array | 后台[Monitor](/docs/zh-CN/tools-reference#monitor-tool)配置，在插件活跃时自动启动。请参阅[监视器](#monitors) | `"./monitors.json"` |
607| `experimental.evals` | string\|array | 插件根目录下的目录，保存插件的[评估案例](/docs/zh-CN/plugin-evals#use-a-different-eval-directory)，当它不是默认 `evals/` 时。`claude plugin eval --eval-dir` 覆盖它 | `"quality/evals"` |
608| `userConfig` | object | 在启用时提示的用户可配置值。请参阅[用户配置](#user-configuration) | |
609| `channels` | array | 消息注入的频道声明（Telegram、Slack、Discord 风格）。请参阅[频道](#channels) | |
610| `dependencies` | array | 此插件需要的其他插件，可选择带有 semver 版本约束。请参阅[约束插件依赖项版本](/docs/zh-CN/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |
611
612<h3 id="experimental-components">
613 实验性组件
614</h3>
615
616`experimental` 键下的组件、`themes` 和 `monitors` 具有在稳定期间可能在版本之间更改的 manifest schema。你声明它们的位置是一个单独的迁移：顶级仍然有效，`claude plugin validate` 警告，未来版本将需要 `experimental.*`。
617
618<h3 id="user-configuration">
619 用户配置
620</h3>
621
622`userConfig` 字段声明当插件启用时 Claude Code 提示用户的值。使用此选项而不是要求用户手动编辑 `settings.json`。
623
624```json theme={null}
625{
626 "userConfig": {
627 "api_endpoint": {
628 "type": "string",
629 "title": "API endpoint",
630 "description": "Your team's API endpoint"
631 },
632 "api_token": {
633 "type": "string",
634 "title": "API token",
635 "description": "API authentication token",
636 "sensitive": true
637 }
638 }
639}
640```
641
642键必须是有效的标识符。每个选项支持这些字段：
643
644| 字段 | 必需 | 描述 |
645| :------------ | :- | :-------------------------------------------------------------------------------------------------------------------------- |
646| `type` | 是 | `string`、`number`、`boolean`、`directory` 或 `file` 之一 |
647| `title` | 是 | 在配置对话框中显示的标签 |
648| `description` | 是 | 显示在字段下方的帮助文本 |
649| `sensitive` | 否 | 如果为 `true`，掩盖输入并将值存储在安全存储中而不是 `settings.json` |
650| `required` | 否 | 如果为 `true`，当字段为空时验证失败 |
651| `default` | 否 | 当用户未提供任何内容时使用的值 |
652| `options` | 否 | 对于 `string` 类型，字段接受的值，在 `/config` 中显示为它们的选择器。请参阅[将字段限制为固定选项](#limit-a-field-to-fixed-options)。需要 Claude Code v2.1.271 或更高版本 |
653| `multiple` | 否 | 对于 `string` 类型，允许字符串数组 |
654| `min` / `max` | 否 | `number` 类型的边界 |
655
656除了 `sensitive` 字段和 `multiple` 列表，每个启用插件的每个字段也显示为 `/config` 面板中的一行。这些行需要 Claude Code v2.1.269 或更高版本。
657
658每个值都可用于在 MCP 和 LSP 服务器配置以及 hook 命令中作为 `${user_config.KEY}` 进行替换。非敏感值也可以在 skill 和代理内容中替换。所有值都导出到 hook 进程作为 `CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量，其中 `<KEY>` 是选项键的大写形式。
659
660在 shell 中运行的字段拒绝 `${user_config.*}`：将配置的值替换到 shell 命令中会让 shell 运行该值包含的任何内容，因此组件失败并出现[错误](/docs/zh-CN/errors#plugin-command-references-user-config)。每个被拒绝的字段都有一种替代方式来传递值：
661
662| 被拒绝的字段 | 如何传递值 |
663| :------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------- |
664| Shell 形式的 hook 命令 | 使用带有 `args` 的 [exec 形式](/docs/zh-CN/hooks#exec-form-and-shell-form)，或从 hook 的环境中读取 `CLAUDE_PLUGIN_OPTION_<KEY>` |
665| [Monitor](#monitors) 命令 | 从脚本中的配置文件读取值 |
666| MCP [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication) | 从脚本中的配置文件读取值 |
667
668在 v2.1.207 之前，这些字段替换了 `${user_config.KEY}` 值；更新依赖此的插件。
669
670非敏感值存储在用户 `settings.json` 中的 [`pluginConfigs`](/docs/zh-CN/settings-reference#pluginconfigs) 键下，作为 `pluginConfigs[<plugin-id>].options`。
671
672在 macOS 上，Claude Code 将敏感值存储在 macOS Keychain 中，当 Keychain 拒绝写入时回退到 `~/.claude/.credentials.json`。在没有支持的 keychain 的平台上，它将它们存储在 `~/.claude/.credentials.json` 中。Keychain 存储与 OAuth 令牌共享，总限制约为 2 KB，因此保持敏感值较小。
673
674Claude Code 仅从三个设置源读取所有 `pluginConfigs` 值：
675
676* **用户设置**：`~/.claude/settings.json`，启用时提示写入的文件
677* **`--settings`**：CLI 标志或 SDK 内联设置
678* **托管设置**：[组织控制的策略](/docs/zh-CN/permissions#managed-settings)
679
680当多个源设置相同的键时，托管设置优先，然后是 `--settings`，然后是用户设置。你可以从此列表中删除的唯一源是用户设置：传递不带 `user` 的 [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags)，Claude Code 会跳过它们。托管设置和 `--settings` 保持你传递的任何内容。SDK 的 [`settingSources`](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) 选项设置相同的列表。
681
682项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的条目被忽略。两个文件都位于工作区中，因此克隆的存储库可以在那里提供值，这些值会流入插件 hook 命令、MCP 服务器配置、LSP 命令和监视器命令。在 v2.1.207 之前，这些条目被读取。限制特定于 `pluginConfigs`：[`enabledPlugins`](/docs/zh-CN/settings-reference#enabledplugins) 仍然遵守项目和本地设置。
683
684<h4 id="limit-a-field-to-fixed-options">
685 将字段限制为固定选项
686</h4>
687
688在 `userConfig` 字段上设置 `options` 以使用户从固定列表中选择其值。
689
690要将 `tone` 字段限制为三个选项，在 `options` 中列出它们并将 `default` 设置为其中之一：
691
692```json theme={null}
693{
694 "userConfig": {
695 "tone": {
696 "type": "string",
697 "title": "Tone",
698 "description": "Voice for generated replies",
699 "options": ["neutral", "warm", "formal"],
700 "default": "neutral"
701 }
702 }
703}
704```
705
706如果你在任何字段上声明 `options`，Claude Code v2.1.271 之前版本的用户无法加载插件。
707
708当你在字段上设置 `options` 时，遵循这些规则：
709
710* 将 `type` 设置为 `string`
711* 不要将 `multiple` 或 `sensitive` 设置为 `true`
712* 将 `default` 设置为其中一个选项
713* 如果你不设置 `default`，将 `required` 设置为 `true`
714* 列出至少一个选项，每个 1 到 64 个字符长
715* 不要以空格开始或结束选项
716* 不要在选项中使用控制字符、不可见字符、改变文本方向的字符或除常规空格外的空格
717* 不要列出相同的选项两次，即使是不同的字母大小写
718
719如果你违反任何这些规则，插件无法加载。运行 `claude plugin validate` 以查看哪个字段违反了哪个规则。
720
721<h3 id="channels">
722 频道
723</h3>
724
725`channels` 字段让插件声明一个或多个消息频道，将内容注入到对话中。每个频道绑定到插件提供的 MCP 服务器。
726
727```json theme={null}
728{
729 "channels": [
730 {
731 "server": "telegram",
732 "userConfig": {
733 "bot_token": {
734 "type": "string",
735 "title": "Bot token",
736 "description": "Telegram bot token",
737 "sensitive": true
738 },
739 "owner_id": {
740 "type": "string",
741 "title": "Owner ID",
742 "description": "Your Telegram user ID"
743 }
744 }
745 }
746 ]
747}
748```
749
750`server` 字段是必需的，必须与插件的 `mcpServers` 中的键匹配。可选的每个频道 `userConfig` 使用与顶级字段相同的 schema，让插件在启用插件时提示输入机器人令牌或所有者 ID。
751
752<h3 id="path-behavior-rules">
753 路径行为规则
754</h3>
755
756自定义路径是替换还是扩展插件的默认目录取决于该字段：
757
758* **替换默认值**：`commands`、`agents`、`workflows`、`outputStyles`、`experimental.themes`、`experimental.monitors`。例如，当 manifest 指定 `commands` 时，默认 `commands/` 目录不被扫描。要保留默认值并添加更多，明确列出它：`"commands": ["./commands/", "./extras/"]`
759* **添加到默认值**：`skills`。默认 `skills/` 目录始终被扫描，`skills` 中列出的目录与它一起加载。异常：对于[其 `source` 解析为 marketplace 根的 marketplace 条目](/docs/zh-CN/plugin-marketplaces#advanced-plugin-entries)，声明特定子目录替换默认 `skills/` 扫描
760* **自己的合并规则**：[hooks](#hooks)、[MCP 服务器](#mcp-servers) 和 [LSP 服务器](#lsp-servers)。请参阅每个部分了解多个源如何组合
761
762当插件同时具有默认文件夹和匹配的 manifest 键时，Claude Code 在 `claude plugin list` 和 `/plugin` 详细视图中警告被忽略的文件夹。插件仍然使用 manifest 路径加载。当 manifest 键指向默认文件夹时，Claude Code 不会警告，例如 `"commands": ["./commands/deploy.md"]`，因为该路径明确命名了文件夹。
763
764对于所有路径字段：
765
766* 所有路径必须相对于插件根目录并以 `./` 开头，除了 `skills` 字段也接受 `"."`
767 * `"."` 和 `"./"` 都表示插件根目录本身
768 * 在 v2.1.221 之前，`"."` 无法通过 manifest 验证，插件无法加载，因此使用 `"./"` 以支持早期版本
769* 来自自定义路径的组件使用相同的命名和命名空间规则，除了代理文件。请参阅[代理](#agents)了解代理名称如何工作
770* 多个路径可以指定为数组
771* skill 路径可以指向直接包含 `SKILL.md` 的目录，例如 `"skills": ["."]` 用于插件根目录
772 * Claude Code 从 `SKILL.md` 中的 frontmatter `name` 字段获取 skill 的调用名称，因此无论安装目录的名称如何，名称都保持稳定
773 * 如果 frontmatter 中未设置 `name`，Claude Code 回退到目录基名
774
775具有根目录中的 `SKILL.md`、没有 `skills/` 子目录且没有 `skills` manifest 字段的插件会自动作为单一 skill 插件加载。你不需要为此布局在 `plugin.json` 中设置 `"skills": ["./"]`。
776
777**路径示例**：
778
779```json theme={null}
780{
781 "commands": [
782 "./specialized/deploy.md",
783 "./utilities/batch-process.md"
784 ],
785 "agents": [
786 "./custom-agents/reviewer.md",
787 "./custom-agents/tester.md"
788 ]
789}
790```
791
792<h3 id="environment-variables">
793 环境变量
794</h3>
795
796Claude Code 提供三个变量用于引用路径：
797
798| 变量 | 解析为 | 用途 |
799| :---------------------- | :--------------------------------------------------- | :----------------------------------------------- |
800| `${CLAUDE_PLUGIN_ROOT}` | 插件安装目录的绝对路径 | 与插件捆绑的脚本、二进制文件和配置文件 |
801| `${CLAUDE_PLUGIN_DATA}` | [持久目录](#persistent-data-directory)，在首次引用时创建，在插件更新中存活 | 已安装的依赖项，例如 `node_modules` 或 Python 虚拟环境、生成的代码和缓存 |
802| `${CLAUDE_PROJECT_DIR}` | 项目根目录 | 项目本地脚本和配置文件 |
803
804所有三个都导出为环境变量到 hook 进程以及 MCP 和 LSP 服务器子进程。它们不存在于 Claude 通过 Bash 工具运行的命令的环境中，无论是在主会话还是在子代理中。在插件内容中，写入占位符，Claude Code 在加载内容时内联替换路径。哪些字段内联替换它们取决于插件组件：
805
806| 插件组件 | 占位符解析的字段 |
807| :------------------------ | :--------------------------------------- |
808| Skill 和代理内容 | 占位符出现的任何地方 |
809| Hook 和监视器命令 | 占位符出现的任何地方 |
810| MCP `stdio` 服务器 | `command`、`args`、`env` |
811| MCP `http`、`sse`、`ws` 服务器 | `url`、`headers`、`headersHelper` |
812| LSP 服务器 | `command`、`args`、`env`、`workspaceFolder` |
813
814在 hook 命令中，使用带有 `args` 的 [exec 形式](/docs/zh-CN/hooks#exec-form-and-shell-form)，以便每个路径作为一个参数传递，无需引用。在 shell 形式的 hooks 和监视器命令中，用双引号包装变量，如 `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`。此 shell 形式的 hook 运行与插件捆绑的脚本：
815
816```json theme={null}
817{
818 "hooks": {
819 "PostToolUse": [
820 {
821 "hooks": [
822 {
823 "type": "command",
824 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
825 }
826 ]
827 }
828 ]
829 }
830}
831```
832
833对于复制的插件，`${CLAUDE_PLUGIN_ROOT}` 在插件更新时更改。前一个版本的目录在更新后的宽限期内保留在磁盘上，但将其视为临时的，不要在那里写入状态。对于从本地目录 marketplace 加载到位的插件，变量指向稳定的源目录。请参阅[插件缓存](#plugin-caching-and-file-resolution)了解哪些插件被复制以及清理语义。
834
835当复制的插件在会话中期更新时，hook 命令、监视器、MCP 服务器和 LSP 服务器继续使用前一个版本的路径。运行 `/reload-plugins` 以将 hooks、MCP 服务器和 LSP 服务器切换到新路径；监视器需要会话重启。在没有交互式终端的会话中，重新加载会将插件 MCP 服务器保留在旧路径上，直到下一个会话。
836
837对于具有 `command` 源的插件，Claude Code [可以重新加载插件本身](/docs/zh-CN/plugin-marketplaces#when-claude-code-re-runs-the-command)。
838
839MCP 服务器也可以调用 `roots/list` 请求以在运行时读取会话的工作目录。请参阅[`roots/list` 返回的内容以及 Claude Code 何时通知服务器更改](/docs/zh-CN/mcp#option-3-add-a-local-stdio-server)。
840
841<h4 id="persistent-data-directory">
842 持久数据目录
843</h4>
844
845`${CLAUDE_PLUGIN_DATA}` 目录解析为 `~/.claude/plugins/data/{id}/`，其中 `{id}` 是插件标识符，其中 `a-z`、`A-Z`、`0-9`、`_` 和 `-` 之外的字符被替换为 `-`。对于作为 `formatter@my-marketplace` 安装的插件，目录是 `~/.claude/plugins/data/formatter-my-marketplace/`。
846
847常见用途是一次安装语言依赖项并在会话和插件更新中重用它们。将其用于 Python 依赖项、使用 Yarn 或 pnpm 锁定的依赖项以及其生命周期脚本必须运行的包。对于 marketplace 安装的插件，你可能根本不需要它：Claude Code 在缓存插件时自动安装符合条件的 [Node.js 包依赖项](#node-js-package-dependencies)。
848
849因为数据目录比任何单个插件版本更长寿，仅检查目录存在无法检测更新何时更改插件的依赖项 manifest。推荐的模式是将捆绑的 manifest 与数据目录中的副本进行比较，并在它们不同时重新安装。
850
851此 `SessionStart` hook 在第一次运行时安装 `node_modules`，并在插件更新包含更改的 `package.json` 时再次安装：
852
853```json theme={null}
854{
855 "hooks": {
856 "SessionStart": [
857 {
858 "hooks": [
859 {
860 "type": "command",
861 "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
862 }
863 ]
864 }
865 ]
866 }
867}
868```
869
870当存储的副本丢失或与捆绑的副本不同时，`diff` 退出非零，涵盖首次运行和依赖项更改更新。如果 `npm install` 失败，尾部 `rm` 删除复制的 manifest，以便下一个会话重试。
871
872捆绑在 `${CLAUDE_PLUGIN_ROOT}` 中的脚本可以针对持久化的 `node_modules` 运行：
873
874```json theme={null}
875{
876 "mcpServers": {
877 "routines": {
878 "command": "node",
879 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
880 "env": {
881 "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
882 }
883 }
884 }
885}
886```
887
888当你从最后一个安装它的范围卸载插件时，数据目录会自动删除。`/plugin` 界面显示目录大小并在删除前提示。CLI 默认删除；传递 [`--keep-data`](#plugin-uninstall) 以保留它。
889
890***
891
892<h2 id="plugin-caching-and-file-resolution">
893 Plugin 缓存和文件解析
894</h2>
895
896Plugin 可以通过以下三种方式指定：
897
898* 通过 `claude --plugin-dir` 或 `claude --plugin-url`，在会话期间使用。
899* 通过 marketplace，为未来的会话安装。
900* 通过你的 claude.ai 账户，[同步](#synced-plugins)到 `~/.claude/plugins/synced/`。
901
902出于安全和验证目的，Claude Code 将 *marketplace* plugin 复制到用户的本地 **plugin 缓存**（`~/.claude/plugins/cache`），除非 plugin 就地加载。[link 模式下的 `command` 源](/docs/zh-CN/plugin-marketplaces#copy-mode-and-link-mode)通过缓存条目中的链接就地加载。来自本地目录添加的 marketplace 的[相对路径源](/docs/zh-CN/plugin-marketplaces#relative-paths)从 marketplace 文件夹就地加载。
903
904对于从本地目录 marketplace 就地加载的 plugin，你对源目录的编辑在下一个会话启动或 `/reload-plugins` 时生效。你不需要版本号提升。plugin 的 hook 进程和 MCP 和 LSP 服务器接收指向源目录的 `CLAUDE_PLUGIN_ROOT`。Claude Code 不会将 plugin 的 [Node.js 包依赖](#node-js-package-dependencies)安装到源目录中。自己在那里安装它们，或从 hook 安装到[持久数据目录](#persistent-data-directory)。
905
906对于复制的 plugin，每个已安装的版本都是缓存中的一个单独目录，按 marketplace 和 plugin 分组，并以解析的版本命名，包含 plugin 文件和 [Node.js 包依赖](#node-js-package-dependencies)的自己的副本。从[release tag](/docs/zh-CN/plugin-dependencies#tag-plugin-releases-for-version-resolution)解析的依赖会获得一个带有 commit-SHA 后缀的目录名。
907
908当你更新或卸载 plugin 时，Claude Code 会将之前的版本目录标记为孤立，并在大约 14 天后的后台扫描中将其删除。宽限期允许已加载旧版本的并发 Claude Code 会话继续运行而不出错。Claude Code 仅在至少安装了一个 plugin 时才运行扫描；在卸载最后一个 plugin 后，孤立目录会保留在磁盘上，直到你再次安装 plugin。
909
910Claude Code 仅在 plugin 或 marketplace 文件夹不再包含任何目录或符号链接时才将其从缓存中删除。如果你将开发检出符号链接到缓存中作为 plugin 的版本条目，Claude Code 永远不会将该链接标记为孤立，也永远不会删除它或保存它的文件夹。Claude Code 也永远不会在链接的检出中写入其版本跟踪文件。
911
912Claude 的 Glob 和 Grep 工具在搜索期间跳过孤立的版本目录，因此文件结果不包括过时的 plugin 代码。
913
914<h3 id="node-js-package-dependencies">
915 Node.js 包依赖
916</h3>
917
918当 Claude Code 将 plugin 复制到缓存中时，它也会在那里安装 plugin 的 Node.js 包依赖，以便 plugin 的 hooks 和 MCP 服务器可以加载它们。本节涵盖 plugin 在其自己的 `package.json` 中声明的 npm 和 Bun 包。对于依赖其他 plugin 的 plugin，请参阅[plugin 依赖版本](/docs/zh-CN/plugin-dependencies)。
919
920Claude Code 在每次创建复制的版本目录时在其中运行安装：当你安装 plugin 时、当 Claude Code 将 plugin 更新到新版本时，以及在会话启动时当启用的 plugin 尚未缓存时（例如在新机器上）。仅当 plugin 的根目录同时包含 `package.json` 和受支持的 lockfile 时，安装才会运行：
921
922| Lockfile | 命令 |
923| :------------------------------------------ | :----------------------------------------------- |
924| `bun.lock` 或 `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |
925| `npm-shrinkwrap.json` 或 `package-lock.json` | `npm ci --ignore-scripts` |
926
927如果 plugin 包含多个这些 lockfile，Claude Code 使用第一个匹配项，按顺序检查：`bun.lock`、`bun.lockb`、`npm-shrinkwrap.json`、`package-lock.json`。
928
929Claude Code 在两种情况下跳过安装，每种情况都有自己的修复方法：
930
931* 如果你的 plugin 仅提供 `yarn.lock` 或 `pnpm-lock.yaml`，请将其替换为 npm lockfile。
932* 如果 `bunfig.toml` 位于 bun lockfile 旁边，请删除 `bunfig.toml`，或将 bun lockfile 替换为 npm lockfile。
933
934为了获得最广泛的覆盖范围，请提供 npm lockfile。Claude Code 从用户的 PATH 运行匹配的 lockfile 的包管理器，如果缺少其他 lockfile，不会回退到它。对于通过 npm 源分发的 plugin，使用 `npm-shrinkwrap.json`；npm 从已发布的包中排除 `package-lock.json`。
935
936Claude Code 对此依赖安装进行了约束，以便 plugin 或其包中的任何代码在安装期间都不会执行，并限制其运行时间：
937
938* **冻结分辨率：** Bun 和 npm 安装 lockfile 精确指定的内容，当 `package.json` 和 lockfile 不一致时失败而不是重新分辨版本。
939* **无生命周期脚本：** `--ignore-scripts` 防止 `preinstall`、`install` 和 `postinstall` 脚本运行，因此在这些脚本中构建本机模块的依赖会下载但在此安装期间不会编译。
940* **60 秒超时：** Claude Code 停止运行时间较长的安装并将其视为失败。
941
942Claude Code 在此依赖安装之前获取 npm 源 plugin，并且包自己的任何安装脚本在获取期间都不会运行。请参阅 [npm 包](/docs/zh-CN/plugin-marketplaces#npm-packages)。
943
944失败或跳过的安装永远不会阻止 plugin。当安装失败或 Claude Code 跳过它因为 yarn 或 pnpm lockfile 或 `bunfig.toml` 时，它会在[调试输出](#debugging-commands)中将原因记录为警告。具有 `package.json` 但没有 lockfile 的 plugin 会被跳过而不记录日志条目。超时的安装可能会在缓存副本中留下部分 `node_modules` 树。
945
946你无法关闭自动安装；没有设置或环境变量可以禁用它。在受限网络中，请参阅[网络访问要求](/docs/zh-CN/network-config#network-access-requirements)以了解要允许的主机。
947
948对于自动安装无法提供的依赖，例如需要其生命周期脚本来构建的包、Python 依赖或使用 Yarn 或 pnpm 锁定的 plugin，请从 hook 将它们安装到[持久数据目录](#persistent-data-directory)。
949
950<h3 id="path-traversal-limitations">
951 路径遍历限制
952</h3>
953
954Claude Code 不允许 plugin 引用其自己目录之外的文件。它拒绝解析到 plugin 根目录之外的组件路径，无论该路径是在 `plugin.json` 中声明还是在[marketplace 条目](/docs/zh-CN/plugin-marketplaces#plugin-entries)中声明。这涵盖指向 plugin 外部的路径（如 `../shared-utils`）和导向 plugin 外部的符号链接，除了[一个 marketplace 内的链接](#share-files-within-a-marketplace-with-symlinks)。
955
956在 macOS 和 Linux 上，Claude Code 也拒绝包含反斜杠的组件路径，即使该路径保留在 plugin 内。因此，使用反斜杠路径声明的组件仅在 Windows 上加载。使用正斜杠编写组件路径，例如 `./commands/deploy.md`。
957
958当 Claude Code 拒绝路径时，它会报告 [`path escapes plugin directory`](/docs/zh-CN/errors#path-escapes-plugin-directory) 错误，并在没有该组件的情况下加载 plugin。
959
960Claude Code 在安装 plugin 时也不会将 plugin 目录之外的文件复制到缓存中，因此当复制的 plugin 内的脚本读取 plugin 根目录上方的路径时，它也找不到这些文件。
961
962<h3 id="share-files-within-a-marketplace-with-symlinks">
963 使用符号链接在 marketplace 内共享文件
964</h3>
965
966如果你的 plugin 需要与同一 marketplace 的其他部分共享文件，你可以在 plugin 目录内创建符号链接。当 plugin 被复制到缓存中时，符号链接的处理方式取决于其目标的解析位置：
967
968* **在 plugin 自己的目录内：** 符号链接在缓存中被保留为相对符号链接，因此它在运行时继续解析到复制的目标。
969* **在同一 marketplace 内的其他位置：** 符号链接被解引用。目标的内容被复制到缓存中以代替它。这允许元 plugin 的 `skills/` 目录链接到 marketplace 中其他 plugin 定义的技能。
970* **在 marketplace 外：** 符号链接出于安全原因被跳过。这防止 plugin 将任意主机文件（如系统路径）拉入缓存。
971
972对于使用 `--plugin-dir` 安装的 plugin、来自本地路径的 plugin 或 来自 [copy 模式下的 `command` 源](/docs/zh-CN/plugin-marketplaces#copy-mode-and-link-mode)的 plugin，仅保留解析到 plugin 自己目录内的符号链接。所有其他的都被跳过。
973
974以下命令创建从 marketplace plugin 内部到由兄弟 plugin 定义的共享技能的链接。在 Windows 上，从提升的命令提示符使用 `mklink /D` 或启用开发者模式：
975
976```bash theme={null}
977ln -s ../../shared-plugin/skills/foo ./skills/foo
978```
979
980***
981
982<h2 id="plugin-directory-structure">
983 Plugin 目录结构
984</h2>
985
986<h3 id="standard-plugin-layout">
987 标准 plugin 布局
988</h3>
989
990一个完整的 plugin 遵循以下结构：
991
992```text theme={null}
993enterprise-plugin/
994├── .claude-plugin/ # 元数据目录（可选）
995│ └── plugin.json # plugin 清单
996├── skills/ # Skills
997│ ├── code-reviewer/
998│ │ └── SKILL.md
999│ └── pdf-processor/
1000│ ├── SKILL.md
1001│ └── scripts/
1002├── commands/ # Skills 作为平面 .md 文件
1003│ ├── status.md
1004│ └── logs.md
1005├── agents/ # Subagent 定义
1006│ ├── security-reviewer.md
1007│ ├── performance-tester.md
1008│ ├── compliance-checker.md
1009│ └── review/ # 此处的 Agents 加载为 enterprise-plugin:review:<name>
1010│ └── accessibility.md
1011├── workflows/ # Workflow 脚本
1012│ └── release-audit.js
1013├── output-styles/ # 输出样式定义
1014│ └── terse.md
1015├── themes/ # 颜色主题定义
1016│ └── dracula.json
1017├── monitors/ # 后台监视器配置
1018│ └── monitors.json
1019├── hooks/ # Hook 配置
1020│ ├── hooks.json # 主 hook 配置
1021│ └── security-hooks.json # 其他 hooks
1022├── bin/ # 添加到 PATH 的 plugin 可执行文件
1023│ └── my-tool # 在 Bash tool 中可作为裸命令调用
1024├── settings.json # plugin 的默认设置
1025├── .mcp.json # MCP 服务器定义
1026├── .lsp.json # LSP 服务器配置
1027├── scripts/ # Hook 和实用脚本
1028│ ├── security-scan.sh
1029│ ├── format-code.py
1030│ └── deploy.js
1031├── LICENSE # 许可证文件
1032└── CHANGELOG.md # 版本历史
1033```
1034
1035<Warning>
1036 `.claude-plugin/` 目录包含 `plugin.json` 文件。所有其他目录（commands/、agents/、skills/、workflows/、output-styles/、themes/、monitors/、hooks/）必须位于 plugin 根目录，而不是在 `.claude-plugin/` 内部。
1037</Warning>
1038
1039plugin 根目录中的 `CLAUDE.md` 文件不会作为项目上下文加载。Plugins 通过 skills、agents 和 hooks 而不是 CLAUDE.md 来贡献上下文。要提供加载到 Claude 上下文中的说明，请将其放在 [skill](#skills) 中。
1040
1041<h3 id="file-locations-reference">
1042 文件位置参考
1043</h3>
1044
1045| 组件 | 默认位置 | 用途 |
1046| :------------ | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1047| **清单** | `.claude-plugin/plugin.json` | Plugin 元数据和配置（可选） |
1048| **Skills** | `skills/` | 具有 `<name>/SKILL.md` 结构的 Skills |
1049| **Commands** | `commands/` | 作为平面 Markdown 文件的 Skills。新 plugins 请使用 `skills/` |
1050| **Agents** | `agents/` | Subagent Markdown 文件。子文件夹是 [agent 名称](#agents) 的一部分 |
1051| **Workflows** | `workflows/` | [Workflow](/docs/zh-CN/workflows) 脚本文件 |
1052| **输出样式** | `output-styles/` | 输出样式定义 |
1053| **主题** | `themes/` | 颜色主题定义 |
1054| **Hooks** | `hooks/hooks.json` | Hook 配置 |
1055| **MCP 服务器** | `.mcp.json` | MCP 服务器定义 |
1056| **LSP 服务器** | `.lsp.json` | 语言服务器配置 |
1057| **监视器** | `monitors/monitors.json` | 后台监视器配置 |
1058| **可执行文件** | `bin/` | 添加到 Bash tool 的 `PATH` 中的可执行文件，在 plugin 启用时可作为裸命令调用。如果您 [通过 claude.ai 组织设置分发 plugin](/docs/zh-CN/plugin-marketplaces#keep-executables-out-of-the-top-level-bin-directory)，则不能在其中包含此目录 |
1059| **设置** | `settings.json` | 启用 plugin 时应用的默认配置。仅支持 [`agent`](/docs/zh-CN/sub-agents) 和 [`subagentStatusLine`](/docs/zh-CN/statusline#subagent-status-lines) 键 |
1060
1061***
1062
1063<h2 id="cli-commands-reference">
1064 CLI 命令参考
1065</h2>
1066
1067Claude Code 提供 CLI 命令用于非交互式插件管理，适用于脚本和自动化。
1068
1069<h3 id="plugin-init">
1070 plugin init
1071</h3>
1072
1073在 `~/.claude/skills/<name>/` 处搭建一个新插件。在下一个 Claude Code 会话中，它会自动加载为 `<name>@skills-dir`，并在 `/plugin` 和 `claude plugin list` 中显示，无需安装步骤。
1074
1075请参阅 [Skills-directory plugins](#skills-directory-plugins) 了解范围和信任要求。
1076
1077```bash theme={null}
1078claude plugin init <name> [options]
1079```
1080
1081该命令接受这些参数：
1082
1083* `<name>`：插件名称。成为技能命名空间和 `~/.claude/skills/` 下的目录名称，因此不能包含空格或路径分隔符。
1084
1085该命令接受这些选项：
1086
1087| 选项 | 描述 | 默认值 |
1088| :----------------------- | :--------------------------------------------------------------------------- | :---------------------- |
1089| `--description <text>` | 清单描述 | |
1090| `--author <name>` | 作者名称 | `git config user.name` |
1091| `--author-email <email>` | 作者电子邮件 | `git config user.email` |
1092| `--with <components...>` | 同时搭建组件文件夹。有效值：`skills`、`agents`、`hooks`、`mcp`、`lsp`、`output-style`、`channel` | |
1093| `-f, --force` | 覆盖目标处现有的 `.claude-plugin/` | |
1094| `-h, --help` | 显示命令帮助 | |
1095
1096`claude plugin new` 是此命令的别名。
1097
1098每个 `--with` 值都会为该组件添加一个启动文件，准备好编辑：
1099
1100| 组件 | 搭建内容 |
1101| :------------- | :----------------------------------------------------------------------------------------------- |
1102| `skills` | 一个额外的命名空间 `<name>:example` 技能，与默认技能并列 |
1103| `agents` | 一个 `agents/` 子代理定义 |
1104| `hooks` | 一个 `hooks/hooks.json`，包含示例事件处理程序 |
1105| `mcp` | 一个 `.mcp.json`，包含 HTTP 和 stdio 服务器示例 |
1106| `lsp` | 一个 `.lsp.json` 语言服务器示例 |
1107| `output-style` | 一个 `output-styles/<name>.md`，在插件启用时自动应用 |
1108| `channel` | 一个基于 MCP 的 [channel](/docs/zh-CN/channels)：一个 stdio 服务器（`server.ts`）、其 `.mcp.json` 和一个 `package.json` |
1109
1110搭建的插件使用 `@skills-dir` 源而不是市场。管理员可以通过 `strictKnownMarketplaces` 或在 [managed settings](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) 中添加 `{"source": "skills-dir"}` 到 `blockedMarketplaces` 来阻止此源。当被阻止时，`plugin init` 在写入前失败。
1111
1112这些示例显示常见的调用：
1113
1114```bash theme={null}
1115# 搭建最小插件
1116claude plugin init my-helper
1117
1118# 搭建带有技能和钩子文件夹的插件
1119claude plugin init my-helper --with skills hooks
1120
1121# 覆盖现有搭建
1122claude plugin init my-helper --force
1123```
1124
1125<h3 id="plugin-install">
1126 plugin install
1127</h3>
1128
1129从可用市场安装插件。
1130
1131```bash theme={null}
1132claude plugin install <plugin> [options]
1133```
1134
1135该命令接受这些参数：
1136
1137* `<plugin>`：插件名称或 `plugin-name@marketplace-name` 用于特定市场
1138
1139该命令接受这些选项：
1140
1141| 选项 | 描述 | 默认值 |
1142| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
1143| `-s, --scope <scope>` | 安装范围：`user`、`project` 或 `local` | `user` |
1144| `--config <key=value>` | 设置插件清单中声明的 [`userConfig`](#user-configuration) 选项。重复该标志以设置多个选项 | |
1145| `-y, --yes` | 接受插件市场声明的命令，无需确认提示：生成具有 [`command` source](/docs/zh-CN/plugin-marketplaces#command-sources) 的插件的命令，或验证存档下载的 [`headersHelper`](/docs/zh-CN/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更高版本。Claude Code 仍会首先打印命令。当 stdin 或 stdout 不是 TTY 时需要，除非您传递 `--accept-command`。在 Claude Code 会话内无效，因此从您自己的终端运行命令 | |
1146| `--accept-command <sha256>` | 接受市场声明的命令，其 `sha256` 之前的 [`--json` 运行](#plugin-json-result) 在 `shownCommand` 中报告，代替 `-y`。接受计数仅适用于该特定命令、插件和市场目录。如果自命令显示以来其中任何一个已更改，包括通过运行自己的市场刷新，Claude Code 不接受摘要并再次显示命令。不能与 `-y` 组合。在 Claude Code 会话内无效，因此从您自己的终端运行命令。需要 Claude Code v2.1.271 或更高版本 | |
1147| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，用于脚本。请参阅 [JSON result format](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 | |
1148| `-h, --help` | 显示命令帮助 | |
1149
1150范围决定了已安装插件添加到哪个设置文件。例如，`--scope project` 写入 .claude/settings.json 中的 `enabledPlugins`，使插件对克隆项目存储库的每个人都可用。
1151
1152<span id="plugin-json-result" />使用 `--json`，stdout 的最后一行是一个 JSON 对象。仅解析该行，因为 Claude Code 会在其前面打印市场声明的任何命令。三个字段始终存在：
1153
1154* `command`：运行的子命令，例如 `install`
1155* `outcome`：`ok` 或 `failed`
1156* `message`：结果的人类可读描述
1157
1158其他字段，例如 `pluginId`、`scope` 和 `failureCode`，仅在适用时出现。`plugin uninstall`、`plugin update`、`plugin enable` 和 `plugin disable` 上的 `--json` 选项打印具有该子命令自己字段的相同对象。使用错误，例如无效的 `--scope`，不打印结果行并以 stderr 上的原因退出 1。
1159
1160当运行显示市场声明的命令且不运行它时，`failed` 结果也会携带一个 `shownCommand` 对象，其字段包括显示的命令、它所属的插件和命令的 `sha256`。要接受完全相同的命令，使用该 `sha256` 作为 `--accept-command` 重新运行。需要 Claude Code v2.1.271 或更高版本。
1161
1162如果 `shownCommand.acceptCommandMatched` 是 `false`，您传递的摘要与现在显示的命令不匹配。在传递其 `sha256` 之前向某人显示该命令。
1163
1164这些示例显示常见的调用：
1165
1166```bash theme={null}
1167# 安装到用户范围（默认）
1168claude plugin install formatter@my-marketplace
1169
1170# 安装到项目范围（与团队共享）
1171claude plugin install formatter@my-marketplace --scope project
1172
1173# 安装到本地范围（不与团队共享）
1174claude plugin install formatter@my-marketplace --scope local
1175```
1176
1177<h3 id="plugin-uninstall">
1178 plugin uninstall
1179</h3>
1180
1181删除已安装的插件。
1182
1183```bash theme={null}
1184claude plugin uninstall <plugin> [options]
1185```
1186
1187该命令接受这些参数：
1188
1189* `<plugin>`：插件名称或 `plugin-name@marketplace-name`
1190
1191该命令接受这些选项：
1192
1193| 选项 | 描述 | 默认值 |
1194| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :----- |
1195| `-s, --scope <scope>` | 从范围卸载：`user`、`project` 或 `local` | `user` |
1196| `--keep-data` | 保留插件的 [persistent data directory](#persistent-data-directory) | |
1197| `--prune` | 同时删除没有其他插件需要的自动安装依赖项。请参阅 [plugin prune](#plugin-prune) | |
1198| `-y, --yes` | 跳过 `--prune` 确认提示。当 stdin 或 stdout 不是 TTY 时需要 | |
1199| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 [`plugin install --json`](#plugin-json-result) 相同。不能与 `--prune` 组合。需要 Claude Code v2.1.268 或更高版本 | |
1200| `-h, --help` | 显示命令帮助 | |
1201
1202`claude plugin remove` 和 `claude plugin rm` 是此命令的别名。
1203
1204默认情况下，从最后剩余的范围卸载也会删除插件的 `${CLAUDE_PLUGIN_DATA}` 目录。使用 `--keep-data` 保留它，例如在测试新版本后重新安装时。
1205
1206<Note>
1207 当来自不同市场的已安装插件共享一个名称时，`plugin-name@marketplace-name` 形式仅卸载来自命名市场的插件。在 v2.1.212 之前，限定形式可能会匹配并卸载来自不同市场的同名插件。
1208</Note>
1209
1210<h3 id="plugin-prune">
1211 plugin prune
1212</h3>
1213
1214删除不再被任何已安装插件需要的自动安装插件依赖项。Claude Code 为满足另一个插件的 [`dependencies`](/docs/zh-CN/plugin-dependencies) 字段而拉入的依赖项会被删除；您直接安装的插件永远不会被触及。
1215
1216```bash theme={null}
1217claude plugin prune [options]
1218```
1219
1220该命令接受这些选项：
1221
1222| 选项 | 描述 | 默认值 |
1223| :-------------------- | :--------------------------------- | :----- |
1224| `-s, --scope <scope>` | 在范围处修剪：`user`、`project` 或 `local` | `user` |
1225| `--dry-run` | 列出将被删除的内容而不实际删除 | |
1226| `-y, --yes` | 跳过确认提示。当 stdin 或 stdout 不是 TTY 时需要 | |
1227| `-h, --help` | 显示命令帮助 | |
1228
1229`claude plugin autoremove` 是此命令的别名。
1230
1231该命令列出孤立的依赖项并在删除前请求确认。要在一个步骤中删除插件并清理其依赖项，请运行 `claude plugin uninstall <plugin> --prune`。
1232
1233<h3 id="plugin-enable">
1234 plugin enable
1235</h3>
1236
1237启用已禁用的插件。当目标从市场安装并声明 [dependencies](/docs/zh-CN/plugin-dependencies) 时，Claude Code 在同一范围内以传递方式启用它们。该命令在 [Enable or disable a plugin with dependencies](/docs/zh-CN/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) 列出的条件下失败。
1238
1239```bash theme={null}
1240claude plugin enable <plugin> [options]
1241```
1242
1243该命令接受这些参数：
1244
1245* `<plugin>`：插件名称、`plugin-name@marketplace-name` 或 `plugin-name@synced` 用于 [plugin synced from claude.ai](#synced-plugins)
1246
1247该命令接受这些选项：
1248
1249| 选项 | 描述 | 默认值 |
1250| :-------------------- | :----------------------------------------------------------------------------------------------------------------- | :--- |
1251| `-s, --scope <scope>` | 启用范围：`user`、`project` 或 `local`。省略时，Claude Code 检测安装插件的范围 | 自动检测 |
1252| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更高版本 | |
1253| `-h, --help` | 显示命令帮助 | |
1254
1255<h3 id="plugin-disable">
1256 plugin disable
1257</h3>
1258
1259禁用插件而不卸载它。
1260
1261当目标从市场安装时，如果另一个启用的插件[依赖](/docs/zh-CN/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)它，该命令会失败。错误消息包含一个链式命令，首先禁用每个依赖它的插件。
1262
1263对于您的组织需要的[同步插件](#synced-plugins)，该命令会失败并且不保存任何内容。
1264
1265```bash theme={null}
1266claude plugin disable [plugin] [options]
1267```
1268
1269该命令接受这些参数：
1270
1271* `[plugin]`：插件名称、`plugin-name@marketplace-name` 或 `plugin-name@synced` 用于 [plugin synced from claude.ai](#synced-plugins)。使用 `--all` 时可选
1272
1273该命令接受这些选项：
1274
1275| 选项 | 描述 | 默认值 |
1276| :-------------------- | :----------------------------------------------------------------------------------------------------------------- | :--- |
1277| `-a, --all` | 禁用所有启用的插件。不能与 `--scope` 组合 | |
1278| `-s, --scope <scope>` | 禁用范围：`user`、`project` 或 `local`。省略时，Claude Code 检测安装插件的范围 | 自动检测 |
1279| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更高版本 | |
1280| `-h, --help` | 显示命令帮助 | |
1281
1282<h3 id="plugin-update">
1283 plugin update
1284</h3>
1285
1286将插件更新到最新版本。
1287
1288```bash theme={null}
1289claude plugin update <plugin> [options]
1290```
1291
1292该命令接受这些参数：
1293
1294* `<plugin>`：插件名称或 `plugin-name@marketplace-name`
1295
1296该命令接受这些选项：
1297
1298| 选项 | 描述 | 默认值 |
1299| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |
1300| `-s, --scope <scope>` | 更新范围：`user`、`project`、`local` 或 `managed` | `user` |
1301| `-y, --yes` | 接受插件市场声明的命令，无需确认提示：生成具有 [`command` source](/docs/zh-CN/plugin-marketplaces#command-sources) 的插件的命令，或验证存档下载的 [`headersHelper`](/docs/zh-CN/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更高版本。Claude Code 仍会首先打印命令。当 stdin 或 stdout 不是 TTY 时需要，除非您传递 `--accept-command`。在 Claude Code 会话内无效，因此从您自己的终端运行命令 | |
1302| `--accept-command <sha256>` | 接受市场声明的命令，其 `sha256` 之前的 [`--json` 运行](#plugin-json-result) 在 `shownCommand` 中报告，代替 `-y`。接受计数仅适用于该特定命令、插件和市场目录。如果自命令显示以来其中任何一个已更改，包括通过运行自己的市场刷新，Claude Code 不接受摘要并再次显示命令。不能与 `-y` 组合。在 Claude Code 会话内无效，因此从您自己的终端运行命令。需要 Claude Code v2.1.271 或更高版本 | |
1303| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更高版本 | |
1304| `-h, --help` | 显示命令帮助 | |
1305
1306<Note>
1307 Claude Code 根据您已安装的插件解析裸插件名称。当来自不同市场的已安装插件共享该名称时，Claude Code 拒绝更新并列出要运行的限定 `plugin-name@marketplace-name` 命令。在 v2.1.246 之前，Claude Code 仅接受限定形式并拒绝裸名称为未找到。
1308</Note>
1309
1310***
1311
1312<h3 id="plugin-list">
1313 plugin list
1314</h3>
1315
1316列出已安装的插件及其版本、源市场和启用状态。
1317
1318```bash theme={null}
1319claude plugin list [options]
1320```
1321
1322该命令接受这些选项：
1323
1324| 选项 | 描述 | 默认值 |
1325| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-- |
1326| `--json` | 输出为 JSON。具有加载问题或创作警告的插件行携带 `errors` 或 `notes` 字符串数组。在 Claude Code v2.1.268 或更高版本上，并行 `errorDetails` 和 `noteDetails` 数组为每个条目提供诊断 `type` 和它引用的名称，例如插件、市场、服务器或文件 | |
1327| `--available` | 包括市场中的可用插件。需要 `--json` | |
1328| `-h, --help` | 显示命令帮助 | |
1329
1330在交互式会话中，`/plugin list` 打印类似的列表内联，但仅涵盖市场安装的插件：
1331
1332* 从技能目录加载的插件出现在 `/plugin` 界面和 `claude plugin list` 中，但不出现在内联 `/plugin list` 输出中。
1333* [从 claude.ai 同步的插件](#synced-plugins) 在 Claude Code v2.1.239 或更高版本上出现在 `claude plugin list` 中，并在 `/plugin` 界面中出现，但不出现在内联 `/plugin list` 输出中。
1334* 使用 `--plugin-dir` 或 `--plugin-url` 为会话加载的插件出现在 `/plugin` 界面中，仅当相同标志在子命令前时才出现在 `claude plugin list` 中，如 `claude --plugin-dir <dir> plugin list`。仅标志名称标识其位置，因此裸 `claude plugin list` 无法找到它们，不同于同步插件和技能目录插件，其固定目录 Claude Code 扫描。
1335
1336交互式形式接受 `--enabled` 或 `--disabled` 以仅显示该状态中的插件，以及 `ls` 作为 `list` 的简写。
1337
1338<h3 id="plugin-details">
1339 plugin details
1340</h3>
1341
1342显示插件的组件清单和预计令牌成本。输出列出插件贡献的所有组件，分组为 Skills、Agents、Hooks、MCP 服务器和 LSP 服务器，以及它为每个会话添加多少令牌的估计。Skills 组包括 `skills/` 和 `commands/` 条目。
1343
1344```bash theme={null}
1345claude plugin details <name>
1346```
1347
1348该命令接受这些参数：
1349
1350* `<name>`：插件名称或 `plugin-name@marketplace-name`
1351
1352该命令接受这些选项：
1353
1354| 选项 | 描述 | 默认值 |
1355| :----------- | :----- | :-- |
1356| `-h, --help` | 显示命令帮助 | |
1357
1358输出为每个组件显示两个成本数字：
1359
1360* **Always-on：** 插件的列表文本（如技能描述、代理描述和命令名称）添加到每个会话的令牌，无论任何组件是否触发。
1361* **On-invoke：** 组件触发时的成本。按组件显示，而不是作为插件总计，因为典型会话仅调用组件的子集。
1362
1363此示例显示具有两个技能的插件的输出外观：
1364
1365```
1366dependency-guard 1.2.0
1367 Dependency analysis for Claude Code sessions
1368 Source: dependency-guard@example-marketplace
1369
1370Component inventory
1371 Skills (2) scan-dependencies, review-changes
1372 Agents (0)
1373 Hooks (1) SessionStart (harness-only — no model context cost)
1374 MCP servers (0)
1375 LSP servers (0)
1376
1377Projected token cost
1378 Always-on: ~180 tok added to every session
1379
1380Per-component (rounded)
1381 component always-on on-invoke
1382 scan-dependencies ~100 ~2400
1383 review-changes ~80 ~1800
1384
1385 On-invoke cost is paid each time a skill or agent fires.
1386 Token counts are estimates and may differ from actual usage.
1387```
1388
1389always-on 总计通过您的活跃模型的 `count_tokens` API 计算。按组件的数字按比例从该总计缩放。如果 API 无法访问，该命令回退到基于字符的估计。
1390
1391<h3 id="plugin-validate">
1392 plugin validate
1393</h3>
1394
1395在发布前检查插件或市场的语法和架构错误。
1396
1397当验证通过时命令退出 0，失败时退出 1，验证运行本身失败时退出 2，例如当您传递的路径不可读时。
1398
1399```bash theme={null}
1400claude plugin validate <path> [options]
1401```
1402
1403该命令接受这些参数：
1404
1405* `<path>`：插件目录或市场目录的路径。请参阅 [Validate a plugin or a directory without a manifest](/docs/zh-CN/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) 了解插件运行涵盖的文件。
1406
1407该命令接受这些选项：
1408
1409| 选项 | 描述 | 默认值 |
1410| :----------- | :---------------------------------------------------------------------------------- | :-- |
1411| `--strict` | 将警告视为错误，在警告时退出 1。在 CI 中使用以捕获运行时容忍的问题，例如 [unrecognized fields](#unrecognized-fields) | |
1412| `--json` | 将验证报告输出为一个 JSON 对象，具有相同的退出代码。需要 Claude Code v2.1.259 或更高版本 | |
1413| `-h, --help` | 显示命令帮助 | |
1414
1415使用 `--json`，Claude Code 将报告写入 stdout 作为一个 JSON 对象，具有这些顶级字段：
1416
1417* `success`：退出代码给出的相同判决
1418* `strict`：运行是否将警告视为错误
1419* `target`：Claude Code 验证的已解析路径
1420* `manifest`：清单自己的结果，或 `null` 用于 [run without a manifest](/docs/zh-CN/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)
1421* `contents`：按文件结果，每个命名其 `file` 并携带 `errors`、`warnings` 和 `notes` 数组
1422
1423在退出 2 时，该命令不向 stdout 写入任何内容；错误消息转到 stderr。
1424
1425在交互式会话中，`/plugin validate <path>` 内联运行相同的检查。
1426
1427<h3 id="plugin-eval">
1428 plugin eval
1429</h3>
1430
1431运行插件的 [eval cases](/docs/zh-CN/plugin-evals) 并报告评分结果。需要 Claude Code v2.1.269 或更高版本。每个案例都是一个提示加评分器；Claude Code 在隔离会话中运行它多次，仅加载目标插件，默认情况下也不加载插件，以便报告显示差异。请参阅 [Test plugins with evals](/docs/zh-CN/plugin-evals) 了解案例格式、评分器、结果和 CI 使用。
1432
1433```bash theme={null}
1434claude plugin eval [target] [options]
1435```
1436
1437可选的 `target` 是一个插件目录、单个 `prompt.md` 或 `case.yaml` 文件、已安装的插件作为 `name` 或 `name@marketplace`，或 `name@skills-dir`，默认为当前目录。将其放在 `--tag`、`--allow-tools` 和 `--json` 之前。
1438
1439此表列出大多数运行使用的选项。运行 `claude plugin eval --help` 以获取完整集合，包括 `--case`、`--tag`、`--output-dir`、`--report`、`--allow-real-servers`、`--keep-temp` 和 `--verbose`。
1440
1441| 选项 | 描述 | 默认值 |
1442| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------- |
1443| `--runs <n>` | 每个案例每个分支的运行次数 | 每个案例的 `runs`，否则 3 |
1444| `-j, --concurrency <n>` | 一次运行的代理会话数，1 到 8。它们共享您的速率限制 | `1` |
1445| `--model <model>` | 被测试代理的模型 | 每个案例的 `model`，否则 `ANTHROPIC_MODEL`（如果设置），否则 Claude Code 的默认值 |
1446| `--judge-model <model>` | `llm` 和 `baseline` 评分器的模型 | 一个小的快速模型 |
1447| `--ablation <mode>` | `none` 或 `with-without`。请参阅 [Compare against a no-plugin baseline](/docs/zh-CN/plugin-evals#compare-against-a-no-plugin-baseline) | 当插件解析时为 `with-without`，否则为 `none` |
1448| `--threshold <0..1>` | 如果任何案例评分低于此值则退出 1 | `1.0` |
1449| `--max-cost-usd <usd>` | 一旦支出达到此值就停止下一次运行，退出 2，并报告部分结果 | 无上限 |
1450| `--allow-tools <tools...>` | 授予超出只读集合的工具，例如 `Bash`、`Write`、`Edit` 或 `"mcp__plugin_<plugin>_<server>__*"`。请参阅 [Grant tools](/docs/zh-CN/plugin-evals#grant-tools) | |
1451| `--scaffold` | 运行每个案例的 [`scaffold_script`](/docs/zh-CN/plugin-evals#add-setup-or-history-with-case-yaml) | 关闭 |
1452| `--trust-plugin` | 跳过首次运行信任提示，用于 CI。请参阅 [What a run can access](/docs/zh-CN/plugin-evals#security) | 关闭 |
1453| `--mocks <mode>` | `record` 或 `off`。请参阅 [Mock MCP servers](/docs/zh-CN/plugin-evals#mock-mcp-servers) | `record` |
1454| `--eval-dir <dir>` | 保存案例的插件下方的目录 | 清单的 `experimental.evals`，否则 `evals` |
1455| `--json [path]` | 将 [result document](/docs/zh-CN/plugin-evals#json-result) 打印到 stdout，或将其写入 `.json` 路径 | |
1456| `--no-publish` | 保持 HTML 报告本地 | |
1457| `-h, --help` | 显示命令帮助 | |
1458
1459当每个案例都满足阈值时命令退出 0，在失败案例、加载错误或不受信任的插件目录时退出 1，在部分运行时退出 2，中断时退出 130，终止时退出 143。请参阅 [Run evals in CI](/docs/zh-CN/plugin-evals#run-evals-in-ci)。
1460
1461<h3 id="plugin-eval-init">
1462 plugin eval init
1463</h3>
1464
1465为当前目录中的插件创建一个 eval 套件。需要 Claude Code v2.1.269 或更高版本。在终端中，这会启动一个创作访谈，读取插件、提议案例和评分器、试验它们并写入文件。使用 `--bare`，或没有终端时，它会写入一个空白的单案例模板。从交互式 Claude Code 会话内运行，它会打印该会话要遵循的访谈说明，而不是写入模板。请参阅 [Create your first eval suite](/docs/zh-CN/plugin-evals#create-your-first-eval-suite)。
1466
1467```bash theme={null}
1468claude plugin eval init [name] [options]
1469```
1470
1471可选的 `name` 是一个案例名称：访谈不需要一个，而 `--bare` 和无终端模板路径需要一个。它接受这些选项：
1472
1473| 选项 | 描述 | 默认值 |
1474| :------------------ | :------------------------------------------------------------- | :---------------------------------- |
1475| `--bare` | 为 `<name>` 写入一个空白的 `prompt.md` 和 `graders/criteria.md`，而不是运行访谈 | |
1476| `-i, --interactive` | 需要访谈。没有终端时失败，而不是写入模板 | |
1477| `--eval-dir <dir>` | 当前目录下方写入案例的目录 | 清单的 `experimental.evals`，否则 `evals` |
1478| `-h, --help` | 显示命令帮助 | |
1479
1480<h3 id="plugin-tag">
1481 plugin tag
1482</h3>
1483
1484为插件创建发布 git 标签。默认情况下，该命令标记当前目录中的插件；传递路径以标记其他地方的插件。请参阅 [Tag plugin releases](/docs/zh-CN/plugin-dependencies#tag-plugin-releases-for-version-resolution)。
1485
1486```bash theme={null}
1487claude plugin tag [path] [options]
1488```
1489
1490该命令接受这些参数：
1491
1492* `[path]`：插件目录的路径。默认为当前目录。
1493
1494该命令接受这些选项：
1495
1496| 选项 | 描述 | 默认值 |
1497| :-------------------- | :---------------------- | :------- |
1498| `--push` | 创建标签后将其推送到远程 | |
1499| `--dry-run` | 打印将被标记的内容而不创建标签 | |
1500| `-f, --force` | 即使工作树脏或标签已存在也创建标签 | |
1501| `-m, --message <msg>` | 标签注释消息。使用 `%s` 作为版本的占位符 | |
1502| `--remote <name>` | 使用 `--push` 推送到的远程 | `origin` |
1503| `-h, --help` | 显示命令帮助 | |
1504
1505***
1506
1507<h2 id="debugging-and-development-tools">
1508 调试和开发工具
1509</h2>
1510
1511<h3 id="debugging-commands">
1512 调试命令
1513</h3>
1514
1515使用 `claude --debug` 查看插件加载详情：
1516
1517这会显示：
1518
1519* 正在加载哪些插件
1520* 插件清单中的任何错误
1521* Skill、agent 和 hook 注册
1522* MCP 服务器初始化
1523
1524<h3 id="common-issues">
1525 常见问题
1526</h3>
1527
1528| 问题 | 原因 | 解决方案 |
1529| :---------------------------------- | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1530| 插件未加载 | 无效的 `plugin.json` | 运行 `claude plugin validate ./my-plugin` 或 `/plugin validate ./my-plugin`，其中 `./my-plugin` 是你的插件目录，以检查 `plugin.json`、`hooks/hooks.json` 以及插件默认目录中的 skills、agents 和 commands 的前置元数据是否存在语法和模式错误。参见 [验证插件或没有清单的目录](/docs/zh-CN/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) 了解运行涵盖的内容 |
1531| Skills 未显示 | 目录结构错误 | 确保 `skills/` 或 `commands/` 在插件根目录，而不是在 `.claude-plugin/` 内 |
1532| Hooks 未触发 | 脚本不可执行 | 运行 `chmod +x script.sh` |
1533| MCP 服务器失败 | 缺少 `${CLAUDE_PLUGIN_ROOT}` | 对所有插件路径使用变量 |
1534| 路径错误 | 使用了绝对路径 | 使路径相对，以 `./` 开头；参见 [路径行为规则](#path-behavior-rules)，其中涵盖了 `skills` 字段的 `"."` 例外 |
1535| LSP `Executable not found in $PATH` | 语言服务器未安装 | 安装二进制文件（例如，`npm install -g typescript-language-server typescript`） |
1536
1537<h3 id="example-error-messages">
1538 示例错误消息
1539</h3>
1540
1541**清单验证错误**：
1542
1543* `Invalid JSON syntax: Unexpected token } in JSON at position 142`：检查是否缺少逗号、多余逗号或未引用的字符串
1544* `Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined`：缺少必需字段
1545* `Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...`：JSON 语法错误。在 v2.1.246 之前，Claude Code 也会为保存为带有字节顺序标记 (BOM) 的 UTF-8 的 `plugin.json` 产生此错误，即使 JSON 在其他方面有效。
1546
1547**插件加载错误**：
1548
1549* `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`：命令路径存在但不包含有效的命令文件
1550* `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`：marketplace.json 中的 `source` 路径指向不存在的目录
1551* `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`：删除重复的组件定义或在 marketplace 条目中删除 `strict: false`
1552
1553<h3 id="hook-troubleshooting">
1554 Hook 故障排除
1555</h3>
1556
1557**Hook 脚本未执行**：
1558
15591. 检查脚本是否可执行：`chmod +x ./scripts/your-script.sh`
15602. 验证 shebang 行：第一行应为 `#!/bin/bash` 或 `#!/usr/bin/env bash`
15613. 检查路径是否使用 `${CLAUDE_PLUGIN_ROOT}`：`"command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"`
15624. 手动测试脚本：`./scripts/your-script.sh`
1563
1564**Hook 未在预期事件上触发**：
1565
15661. 验证事件名称正确（区分大小写）：`PostToolUse`，而不是 `postToolUse`
15672. 检查匹配器模式是否与你的工具匹配：`"matcher": "Write|Edit"` 用于文件操作
15683. 确认 hook 类型有效：`command`、`http`、`mcp_tool`、`prompt` 或 `agent`
1569
1570<h3 id="mcp-server-troubleshooting">
1571 MCP 服务器故障排除
1572</h3>
1573
1574**服务器未启动**：
1575
15761. 检查命令是否存在且可执行
15772. 验证所有路径是否使用 `${CLAUDE_PLUGIN_ROOT}` 变量
15783. 检查 MCP 服务器日志：`claude --debug` 显示初始化错误
15794. 在 Claude Code 外手动测试服务器
1580
1581**服务器工具未显示**：
1582
15831. 确保服务器在 `.mcp.json` 或 `plugin.json` 中正确配置
15842. 验证服务器是否正确实现 MCP 协议
15853. 检查调试输出中的连接超时
1586
1587<h3 id="directory-structure-mistakes">
1588 目录结构错误
1589</h3>
1590
1591**症状**：插件加载但组件（skills、agents、hooks）缺失。
1592
1593**正确结构**：组件必须在插件根目录，而不是在 `.claude-plugin/` 内。只有 `plugin.json` 属于 `.claude-plugin/`。
1594
1595**调试检查清单**：
1596
15971. 运行 `claude --debug` 并查找"loading plugin"消息
15982. 检查每个组件目录是否在调试输出中列出
15993. 验证文件权限允许读取插件文件
1600
1601***
1602
1603<h2 id="distribution-and-versioning-reference">
1604 分发和版本管理参考
1605</h2>
1606
1607<h3 id="version-management">
1608 版本管理
1609</h3>
1610
1611Claude Code 使用插件的版本作为缓存键，以确定是否有可用的更新。当你运行 `/plugin update` 或自动更新触发时，Claude Code 会计算当前版本，如果与已安装的版本匹配，则跳过更新。从[本地目录市场](#plugin-caching-and-file-resolution)加载的插件会在每个会话开始时加载其当前源文件，无论其版本字符串如何。
1612
1613对于除 `command` 之外的每种源类型，Claude Code 从以下第一个设置的项中解析版本：
1614
16151. 插件 `plugin.json` 中的 `version` 字段
16162. 插件在 `marketplace.json` 中的市场条目中的 `version` 字段
16173. 插件源的 git 提交 SHA，适用于 git 托管市场中的 `github`、`url`、`git-subdir` 和相对路径源
16184. SHA-256 摘要，适用于 [`archive` 源](/docs/zh-CN/plugin-marketplaces#zip-archives)：市场条目中的 `sha256` 固定值，或当你未设置固定值时下载文件的摘要。Claude Code 将其缩短为前 12 个字符
16195. `unknown`，适用于 `npm` 源或不在 git 仓库内的本地目录。Claude Code 不会从包含安装路径的仓库（例如 git 管理的 `~/.claude`）中获取版本
1620
1621对于 [`command` 源](/docs/zh-CN/plugin-marketplaces#command-sources)，Claude Code 始终从命令生成的内容中派生版本：单独的 12 字符内容哈希，或在设置了版本时附加到 `plugin.json` 版本作为 `<version>-<hash>`。Claude Code 忽略命令源的市场条目中的 `version` 字段。因此，命令的哈希输出发生变化会产生新版本，即使编写的版本字符串保持不变。在 [link mode](/docs/zh-CN/plugin-marketplaces#copy-mode-and-link-mode) 中，哈希覆盖打印目录的真实路径及其顶级条目，而不是文件内容。
1622
1623对于这些源类型，这为你提供了三种版本控制插件的方式：
1624
1625| 方法 | 如何操作 | 更新行为 | 最适合 |
1626| :------------ | :--------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- | :------------------------ |
1627| **显式版本** | 在 `plugin.json` 中设置 `"version": "2.1.0"` | 用户仅在你更新此字段时获得更新。推送新提交而不更新它没有效果，`/plugin update` 报告"已是最新版本"。对于[从本地加载](#plugin-caching-and-file-resolution)的插件，新内容仍会加载。 | 具有稳定发布周期的已发布插件 |
1628| **提交 SHA 版本** | 从 `plugin.json` 和市场条目中都省略 `version` | 每当源的已解析提交发生变化时，用户获得更新 | 正在积极开发的内部或团队插件 |
1629| **摘要版本** | 使用 [`archive` 源](/docs/zh-CN/plugin-marketplaces#zip-archives) 并从 `plugin.json` 和市场条目中都省略 `version` | 使用 `sha256` 固定值时，当你更改固定值时用户获得更新。没有固定值时，每当托管 zip 文件的字节发生变化时用户获得更新 | 作为 zip 文件发布到静态服务器或工件仓库的插件 |
1630
1631如果你使用显式版本，请遵循 [semantic versioning](https://semver.org)（`MAJOR.MINOR.PATCH`）：对于破坏性更改，增加 MAJOR；对于新功能，增加 MINOR；对于错误修复，增加 PATCH。在 `CHANGELOG.md` 中记录更改。
1632
1633***
1634
1635<h2 id="see-also">
1636 另请参阅
1637</h2>
1638
1639* [Plugins](/docs/zh-CN/plugins) - 教程和实际用法
1640* [Plugin marketplaces](/docs/zh-CN/plugin-marketplaces) - 创建和管理市场
1641* [Skills](/docs/zh-CN/skills) - Skill 开发详情
1642* [Subagents](/docs/zh-CN/sub-agents) - Agent 配置和功能
1643* [Hooks](/docs/zh-CN/hooks) - 事件处理和自动化
1644* [MCP](/docs/zh-CN/mcp) - 外部工具集成
1645* [Settings](/docs/zh-CN/settings) - Plugins 的配置选项
