Go Premium Account

plugins-reference.md 2026-09-24 22:57 UTC to 2026-09-25 23:58 UTC

This page contains 0 additions and 1645 deletions.

2026

Thu 10 23:00 Sat 12 03:02 Sun 13 21:00 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

This document has no rendered page for this history range.

plugins-reference.md +0 −1645 deleted

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.~~

~~5# Plugins 参考~~

~~7> Claude Code 插件系统的完整技术参考，包括模式、CLI 命令和组件规范。~~

~~9<Tip>~~

10 想要安装插件？请参阅 [发现和安装插件](/docs/zh-CN/discover-plugins)。有关创建插件，请参阅 [Plugins](/docs/zh-CN/plugins)。有关分发插件，请参阅 [Plugin marketplaces](/docs/zh-CN/plugin-marketplaces)。

~~11</Tip>~~

~~13**插件**是一个自包含的组件目录，使用自定义功能扩展 Claude Code。插件组件包括 skills、agents、hooks、MCP servers、LSP servers 和 monitors。~~

~~15<h2 id="plugin-components-reference">~~

~~16 插件组件参考~~

~~17</h2>~~

~~19<h3 id="skills">~~

~~20 Skills~~

~~21</h3>~~

~~23插件向 Claude Code 添加 skills，创建可由您或 Claude 调用的 `/name` 快捷方式。~~

~~25**位置**：插件根目录中的 `skills/` 或 `commands/` 目录，或插件根目录中的单个 `SKILL.md` 文件~~

~~27**文件格式**：Skills 是包含 `SKILL.md` 的目录；commands 是简单的 markdown 文件~~

~~29**Skill 结构**：~~

~~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```~~

~~41安装插件时会自动发现 Skills 和 commands。~~

43如果插件没有 `skills/` 目录且没有 `skills` manifest 字段，则插件根目录中的 `SKILL.md` 会作为单个 skill 加载。设置 frontmatter `name` 字段来控制 skill 的调用名称。如果没有设置，Claude Code 会回退到安装目录名称。对于 [复制到缓存中](#plugin-caching-and-file-resolution) 的插件，该名称是一个在每次更新时都会改变的版本字符串。对于包含多个 skill 的插件，请使用上面所示的 `skills/` 目录布局。

45在插件 skills 和 commands 中，Boolean frontmatter 字段（如 `disable-model-invocation`）接受 `yes`、`no`、`on`、`off`、`1` 和 `0`（任何字母大小写），以及 `true` 和 `false`。在 v2.1.218 之前，Claude Code 仅识别 `true` 和 `false`。

~~47有关完整详情，请参阅 [Skills](/docs/zh-CN/skills)。~~

~~49<h3 id="agents">~~

~~50 Agents~~

~~51</h3>~~

~~53插件可以为特定任务提供专门的子代理，Claude 可以在适当时自动调用这些代理。~~

~~55**位置**：插件根目录中的 `agents/` 目录~~

~~57**文件格式**：描述代理功能的 markdown 文件~~

~~59**Agent 结构**：~~

~~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~~

~~69Detailed system prompt for the agent describing its role, expertise, and behavior.~~

~~70```~~

~~72<h4 id="plugin-agent-frontmatter">~~

~~73 插件代理 frontmatter~~

~~74</h4>~~

76插件代理文件使用与 [子代理文件相同的 frontmatter 字段](/docs/zh-CN/sub-agents#supported-frontmatter-fields)，但当代理来自插件时，Claude Code 仅支持其中的某些字段：

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`。~~

82您可以将插件代理文件放在 `agents/` 的子文件夹中。Claude Code [递归加载它们](/docs/zh-CN/sub-agents#choose-the-subagent-scope)，并使用冒号连接插件名称、每个子文件夹名称和文件名来形成代理的作用域名称。例如，名为 `my-plugin` 的插件中的 `agents/review/security.md` 加载为 `my-plugin:review:security`。两个设置会改变该名称：

~~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`~~

~~87Claude Code 加载插件代理，即使其 frontmatter 没有 `name` 或无法解析：~~

~~89* 没有 `name`：Claude Code 根据文件名命名代理，因此名为 `my-plugin` 的插件中的 `agents/reviewer.md` 加载为 `my-plugin:reviewer`~~

~~90* Frontmatter 无法解析：Claude Code 根据文件名命名代理，使用 `Agent from my-plugin plugin` 作为其描述，并忽略文件中的每个字段~~

~~92相比之下，Claude Code 会跳过其 frontmatter 没有 `name` 或无法解析的项目、用户或托管代理文件。~~

94要查找插件默认 `agents/` 目录中 frontmatter 无法解析的文件，请运行 `claude plugin validate`。您传递的路径取决于插件是否有 manifest，两个示例都使用 `./my-plugin` 作为插件目录：

~~96* 具有 manifest 的插件：`claude plugin validate ./my-plugin`~~

~~97* 没有 manifest 的插件：`claude plugin validate ./my-plugin/agents`。需要 Claude Code v2.1.233 或更高版本。~~

~~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| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |

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"` |

570| `author` | object | 作者信息 | `{"name": "Dev Team", "email": "dev@company.com"}` |

575| `metadata` | object | 自由格式对象，用于你自己的数据，例如权利或目录字段。Claude Code 不读取它，因此值永远不会影响插件行为。Claude Code 忽略非对象值，`claude plugin validate` 报告警告。在 v2.1.222 之前，Claude Code 将该键视为[无法识别的字段](#unrecognized-fields)。 | `{"catalogId": "cat-123"}` |

~~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| :---------------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------- |

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| :------------ | :--------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- | :------------------------ |

~~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 的配置选项