20 20
21## claude plugin 命令21## claude plugin 命令
22 22
23在 Claude Code 会话外部，从 shell 或脚本运行 `claude plugin <subcommand>`。这些子命令用于安装和管理插件，无需打开 [`/plugin`](#plugin-in-a-session) 面板。23在 Claude Code 会话之外，从 shell 或脚本中运行 `claude plugin <subcommand>`。这些子命令无需打开 [`/plugin`](#plugin-in-a-session) 面板即可安装和管理插件。
24 24
25`claude plugins` 是 `claude plugin` 的别名。25`claude plugins` 是 `claude plugin` 的别名。
26 26
27每个子命令共享以下退出码、插件参数和作用域值：27所有子命令共享以下退出码、插件参数和作用域值：
28 28
29* **退出码**：成功时为 `0`，失败时为 `1`。`validate` 额外使用退出码 `2` 表示意外错误，`eval` 额外使用[其章节](#plugin-eval)中列出的退出码。29* **退出码**：成功时为 `0`，失败时为 `1`。`validate` 额外使用退出码 `2` 表示意外错误，`eval` 额外使用[其章节](#plugin-eval)中列出的退出码。
30* **插件参数**：`<plugin>` 参数是插件 `name` 或 `name@marketplace`。当两个市场提供相同的名称时，请使用限定形式。`configure` 仅接受限定形式。30* **插件参数**：`<plugin>` 参数是插件的 `name` 或 `name@marketplace`。当两个市场提供同名插件时，请使用限定形式。`configure` 只接受限定形式。
31* **作用域**：`--scope` 接受 `user`、`project` 或 `local`，用于指定命令写入的设置文件。`update` 还接受 `managed`。31* **作用域**：`--scope` 接受 `user`、`project` 或 `local`，用于指定命令写入的设置文件。`update` 还接受 `managed`。
32 32
33### plugin init33### plugin init
34 34
35在 `~/.claude/skills/<name>/` 处搭建新插件。除非您的管理员已[阻止 skills-directory 插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings)，否则它会在您的下一个会话中作为 `<name>@skills-dir` 加载，无需安装步骤。35在 `~/.claude/skills/<name>/` 创建新插件的脚手架。除非您的管理员已[阻止 skills 目录插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings)，否则它会在您的下一个会话中以 `<name>@skills-dir` 的形式加载，无需安装步骤。
36 36
37`new` 是 `init` 的别名。37`new` 是 `init` 的别名。
38 38
42claude plugin init <name> [options]42claude plugin init <name> [options]
43```43```
44 44
45`<name>` 将成为 `~/.claude/skills/` 下的目录名称以及插件清单中的 `name`。45`<name>` 会成为 `~/.claude/skills/` 下的目录名，以及插件清单中的 `name`。
46 46
47该命令没有用于指定其他位置的标志。如需在项目内搭建，请参阅[创建插件](https://code.claude.com/docs/zh-CN/plugins/create.md)。47该命令没有用于指定其他位置的标志。如需改为在项目内创建脚手架，请参阅[创建插件](https://code.claude.com/docs/zh-CN/plugins/create.md)。
48 48
49| 标志 | 描述 |49| 标志 | 说明 |
50| :- | :- |50| :- | :- |
51| `--description <text>` | 清单描述 |51| `--description <text>` | 清单描述 |
52| `--author <name>` | 作者名称。默认为 `git config user.name` |52| `--author <name>` | 作者名称。默认为 `git config user.name` |
53| `--author-email <email>` | 作者电子邮件。默认为 `git config user.email` |53| `--author-email <email>` | 作者邮箱。默认为 `git config user.email` |
54| `--with <components...>` | 同时为 `skills`、`agents`、`hooks`、`mcp`、`lsp`、`output-style` 或 `channel` 搭建起始文件 |54| `--with <components...>` | 同时为 `skills`、`agents`、`hooks`、`mcp`、`lsp`、`output-style` 或 `channel` 创建初始文件 |
55| `-f, --force` | 覆盖目标处现有的 `.claude-plugin/` |55| `-f, --force` | 覆盖目标位置已有的 `.claude-plugin/` |
56 56
57搭建带有起始 skill 和 hook 文件的插件：57创建带有初始 skill 和 hook 文件的插件脚手架：
58 58
59```bash theme={null}59```bash theme={null}
60claude plugin init my-helper --with skills hooks60claude plugin init my-helper --with skills hooks
61```61```
62 62
63Claude Code 会验证其写入的内容并打印 `Created plugin "my-helper" at ~/.claude/skills/my-helper`，随后打印其加载时使用的 id，以及用于关闭它的 `claude plugin disable` 命令。63Claude Code 会验证其写入的内容并打印 `Created plugin "my-helper" at ~/.claude/skills/my-helper`，随后显示该插件加载时使用的 id，以及用于关闭它的 `claude plugin disable` 命令。
64 64
65当 Claude Code 无法安全搭建时，它会以 `1` 退出且不写入任何内容，并在消息中说明原因。常见原因如下：65当 Claude Code 无法安全地创建脚手架时，它会以 `1` 退出且不写入任何内容，消息中会说明原因。常见原因如下：
66 66
67* 未知的 `--with` 值67* 未知的 `--with` 值
68* 目标处已存在搭建内容，且未使用 `--force`68* 目标位置已有脚手架，且未指定 `--force`
69* 托管的市场允许列表未包含 `skills-dir` 来源，或拒绝列表中列出了该来源。消息为 [`Plugins from ~/.claude/skills/ are blocked by your organization's managed settings`](https://code.claude.com/docs/zh-CN/plugins/troubleshooting#plugins-from-claude-skills-are-blocked-by-your-organizations-managed-s)。69* 托管的市场允许列表不包含 `skills-dir` 来源，或拒绝列表中列出了该来源。消息为 [`Plugins from ~/.claude/skills/ are blocked by your organization's managed settings`](https://code.claude.com/docs/zh-CN/plugins/troubleshooting#plugins-from-claude-skills-are-blocked-by-your-organizations-managed-s)。
70 70
71### plugin install71### plugin install
72 72
73从您已添加的市场安装插件。`i` 是 `install` 的别名。73从您的某个市场安装插件。`i` 是 `install` 的别名。
74 74
75```bash theme={null}75```bash theme={null}
76claude plugin install <plugin> [options]76claude plugin install <plugin> [options]
77```77```
78 78
79大多数插件无需提示即可安装。对于其市场条目[通过运行命令来安装](https://code.claude.com/docs/zh-CN/plugins/host-marketplace.md)或[为下载设置了 `headersHelper`](https://code.claude.com/docs/zh-CN/plugins/host-marketplace#how-users-accept-a-headershelper-command) 的插件，Claude Code 会先打印该命令并询问 `Run this command now? [y/N]`。79大多数插件在安装时不会出现提示。对于其市场条目[通过运行命令来安装](https://code.claude.com/docs/zh-CN/plugins/host-marketplace.md)或[为下载设置了 `headersHelper`](https://code.claude.com/docs/zh-CN/plugins/host-marketplace#how-users-accept-a-headershelper-command) 的插件，Claude Code 会先打印该命令并询问 `Run this command now? [y/N]`。
80 80
81| 标志 | 描述 |81| 标志 | 说明 |
82| :- | :- |82| :- | :- |
83| `-s, --scope <scope>` | 安装作用域：`user`、`project` 或 `local`。默认为 `user` |83| `-s, --scope <scope>` | 安装作用域：`user`、`project` 或 `local`。默认为 `user` |
84| `--config <key=value>` | 设置插件清单声明的 [`userConfig`](https://code.claude.com/docs/zh-CN/plugins/manifest-reference) 选项。每个选项重复一次该标志。写作 `<server>.<key>` 的键改为设置[捆绑 MCP 服务器](https://code.claude.com/docs/zh-CN/plugins/components.md#include-a-packaged-mcpb-server)在其自身 `user_config` 中声明的设置，适用于随插件附带的捆绑文件。`<server>.<key>` 形式需要 Claude Code v2.1.285 或更高版本 |84| `--config <key=value>` | 设置插件清单中声明的 [`userConfig`](https://code.claude.com/docs/zh-CN/plugins/manifest-reference) 选项。每个选项重复使用一次该标志。写作 `<server>.<key>` 的键会改为设置[捆绑的 MCP 服务器](https://code.claude.com/docs/zh-CN/plugins/components.md#include-a-packaged-mcpb-server)在其自身 `user_config` 中声明的设置项，适用于随插件一起提供的 bundle 文件。`<server>.<key>` 形式需要 Claude Code v2.1.285 或更高版本 |
85| `-y, --yes` | 接受显示的安装命令，不出现 `Run this command now?` 提示。在 Claude Code 会话内运行命令时（例如从 Bash 工具或 hook 运行）会被忽略。需要 Claude Code v2.1.229 或更高版本 |85| `-y, --yes` | 接受所显示的安装命令，不出现 `Run this command now?` 提示。当命令在 Claude Code 会话内运行时（例如通过 Bash 工具或 hook 运行）会被忽略。需要 Claude Code v2.1.229 或更高版本 |
86| `--accept-command <sha256>` | 代替 `-y`，接受之前某次 [`--json` 运行](#plugin-json-result)在 `shownCommand` 中报告了其 `sha256` 的显示安装命令。不能与 `-y` 组合使用。请参阅[接受显示的安装命令](#accept-a-displayed-install-command)。需要 Claude Code v2.1.271 或更高版本 |86| `--accept-command <sha256>` | 代替 `-y`，接受之前某次 [`--json` 运行](#plugin-json-result)在 `shownCommand` 中报告了其 `sha256` 的已显示安装命令。不能与 `-y` 同时使用。请参阅[接受已显示的安装命令](#accept-a-displayed-install-command)。需要 Claude Code v2.1.271 或更高版本 |
87| `--json` | 将结果作为一个 JSON 对象打印在 stdout 的最后一行，而不是人类可读的消息，供脚本使用。请参阅 [JSON 结果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 |87| `--json` | 在 stdout 的最后一行以一个 JSON 对象打印结果，而不是人类可读的消息，便于在脚本中使用。请参阅 [JSON 结果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 |
88| `--marketplace <source>` | 从位于 `<source>` 的市场安装以裸名称指定的 `<plugin>`，如果您尚未添加该市场，则先添加它。请参阅[通过一条命令添加市场并安装](https://code.claude.com/docs/zh-CN/plugins/install.md#add-a-marketplace-and-install-in-one-command)。需要 Claude Code v2.1.292 或更高版本 |88| `--marketplace <source>` | 从位于 `<source>` 的市场安装以裸名称指定的 `<plugin>`，如果您尚未添加该市场，则会先添加它。请参阅[用一条命令添加市场并安装](https://code.claude.com/docs/zh-CN/plugins/install.md#add-a-marketplace-and-install-in-one-command)。需要 Claude Code v2.1.292 或更高版本 |
89 89
90在 shell 中运行 `claude plugin install --help`，可查看您的版本支持的所有选项。90在 shell 中运行 `claude plugin install --help` 可查看您的版本支持的所有选项。
91 91
92从您自己的终端传递 `-y`，即可接受显示的命令而不出现提示。以下是没有 TTY 以及由 Claude 运行命令时的情况：92从您自己的终端传入 `-y`，即可接受所显示的命令而不出现提示。以下是在没有 TTY 时以及由 Claude 运行该命令时的情况：
93 93
94* **stdin 或 stdout 不是 TTY，且既未传递 `-y` 也未传递 `--accept-command`**：安装被拒绝。输出会说明命令仅被显示，退出码为 `1`94* **stdin 或 stdout 不是 TTY，且您既未传入 `-y` 也未传入 `--accept-command`**：安装会被拒绝。输出会说明该命令仅被显示，退出码为 `1`
95* **Claude 通过其 Bash 工具运行命令**：`-y` 会被忽略。请改为从您自己的终端运行该命令95* **Claude 通过其 Bash 工具运行该命令**：`-y` 会被忽略。请改为从您自己的终端运行该命令
96 96
97为克隆该项目的所有人安装插件：97为克隆该项目的所有人安装插件：
98 98
100claude plugin install formatter@my-marketplace --scope project100claude plugin install formatter@my-marketplace --scope project
101```101```
102 102
103Claude Code 打印 `Successfully installed plugin: formatter@my-marketplace (scope: project)`。当没有安装任何新内容时，输出会说明原因：103Claude Code 会打印 `Successfully installed plugin: formatter@my-marketplace (scope: project)`。当没有安装任何新内容时，输出会说明原因：
104 104
105* **已在该作用域安装**：输出为 `Plugin "formatter@my-marketplace" is already installed (scope: project)`，退出码为 `0`105* **已在该作用域安装**：输出为 `Plugin "formatter@my-marketplace" is already installed (scope: project)`，退出码为 `0`
106* **您拒绝了命令源提示**：输出为 `Aborted.`，退出码为 `1`106* **您拒绝了命令来源的提示**：输出为 `Aborted.`，退出码为 `1`
107* **您拒绝了 `headersHelper` 提示，或在没有 TTY 的情况下无法确认**：输出为 `Aborted — the command was not run.`，退出码为 `1`107* **您拒绝了 `headersHelper` 提示，或在没有 TTY 时无法确认**：输出为 `Aborted — the command was not run.`，退出码为 `1`
108 108
109#### JSON 结果格式109#### JSON 结果格式
110 110
111向 `plugin install` 传递 `--json` 时，stdout 的最后一行是一个 JSON 对象。请仅解析该行，因为 Claude Code 会在其之前打印市场声明的任何命令。111当您向 `plugin install` 传入 `--json` 时，stdout 的最后一行是一个 JSON 对象。请只解析这一行，因为 Claude Code 会在其之前打印市场声明的任何命令。
112 112
113以下三个字段始终存在：113以下三个字段始终存在：
114 114
115* `command`：运行的子命令，例如 `install`115* `command`：运行的子命令，例如 `install`
116* `outcome`：`ok` 或 `failed`116* `outcome`：`ok` 或 `failed`
117* `message`：结果的人类可读描述117* `message`：对结果的人类可读描述
118 118
119其他字段（例如 `pluginId`、`scope` 和 `failureCode`）仅在适用时出现。119其他字段（例如 `pluginId`、`scope` 和 `failureCode`）仅在适用时出现。
120 120
121`plugin uninstall`、`plugin update`、`plugin enable` 和 `plugin disable` 上的 `--json` 选项会打印相同的对象，并带有各子命令自己的字段。121`plugin uninstall`、`plugin update`、`plugin enable` 和 `plugin disable` 上的 `--json` 选项会打印相同的对象，并带有该子命令自身的字段。
122 122
123使用错误（例如无效的 `--scope`）不会打印结果行，而是以 `1` 退出，并在 stderr 上给出原因。123用法错误（例如无效的 `--scope`）不会打印结果行，并以 `1` 退出，原因输出到 stderr。
124 124
125#### 市场命令的 JSON 结果125#### 市场命令的 JSON 结果
126 126
137 137
138当参数为[保留名称](https://code.claude.com/docs/zh-CN/plugins/marketplace-reference.md#reserved-names) `anthropic-plugin-directory` 时，`plugin marketplace add` 和 `plugin marketplace remove` 可能不打印结果行，因此对于该名称请检查退出码。138当参数为[保留名称](https://code.claude.com/docs/zh-CN/plugins/marketplace-reference.md#reserved-names) `anthropic-plugin-directory` 时，`plugin marketplace add` 和 `plugin marketplace remove` 可能不打印结果行，因此对于该名称请检查退出码。
139 139
140#### 接受显示的安装命令140#### 接受已显示的安装命令
141 141
142当 `--json` 运行显示了市场声明的命令但未运行它时，`failed` 结果还会携带一个 `shownCommand` 对象。其字段包括显示的命令、该命令所属的插件以及命令的 `sha256`。142当某次 `--json` 运行显示了市场声明的命令但未运行它时，`failed` 结果还会带有一个 `shownCommand` 对象。其字段包括所显示的命令、该命令所属的插件，以及该命令的 `sha256`。
143 143
144要恰好接受该命令，请从您自己的终端重新运行，并将该 `sha256` 作为 `--accept-command` 传入，因为该标志在 Claude Code 会话内无效。需要 Claude Code v2.1.271 或更高版本。144要精确接受该命令，请从您自己的终端以该 `sha256` 作为 `--accept-command` 重新运行，因为该标志在 Claude Code 会话内无效。需要 Claude Code v2.1.271 或更高版本。
145 145
146`sha256` 仅对完全相同的命令、插件和市场目录视为接受。如果自命令显示以来其中任何一项发生了变化，Claude Code 不会接受该 `sha256`，并会再次显示命令。运行自身的市场刷新所获取的更改也算作此类变化。146该 `sha256` 仅对完全相同的命令、插件和市场目录视为接受。如果自命令显示以来其中任何一项发生了变化，Claude Code 不会接受该 `sha256`，而是再次显示该命令。本次运行自身的市场刷新所获取到的变化也算作此类变化。
147 147
148如果 `shownCommand.acceptCommandMatched` 为 `false`，则您传递的 `sha256` 与当前显示的命令不匹配。请在使用其 `sha256` 重新运行之前检查该命令。148如果 `shownCommand.acceptCommandMatched` 为 `false`，则您传入的 `sha256` 与当前显示的命令不匹配。请先检查该命令，再以其 `sha256` 重新运行。
149 149
150### plugin uninstall150### plugin uninstall
151 151
152从一个作用域移除已安装的插件。`remove` 和 `rm` 是 `uninstall` 的别名。152从某个作用域移除已安装的插件。`remove` 和 `rm` 是 `uninstall` 的别名。
153 153
154```bash theme={null}154```bash theme={null}
155claude plugin uninstall <plugin> [options]155claude plugin uninstall <plugin> [options]
156```156```
157 157
158| 标志 | 描述 |158| 标志 | 说明 |
159| :- | :- |159| :- | :- |
160| `-s, --scope <scope>` | 从指定作用域卸载：`user`、`project` 或 `local`。默认为 `user` |160| `-s, --scope <scope>` | 从以下作用域卸载：`user`、`project` 或 `local`。默认为 `user` |
161| `--keep-data` | 保留插件的持久数据目录 `~/.claude/plugins/data/<id>/` |161| `--keep-data` | 保留插件的持久数据目录 `~/.claude/plugins/data/<id>/` |
162| `--prune` | 同时移除不再被任何剩余插件需要的自动安装[依赖项](https://code.claude.com/docs/zh-CN/plugins/dependencies.md) |162| `--prune` | 同时移除剩余插件都不再需要的自动安装的[依赖](https://code.claude.com/docs/zh-CN/plugins/dependencies.md) |
163| `-y, --yes` | 跳过 `--prune` 确认提示。当 stdin 或 stdout 不是 TTY 时，与 `--prune` 一起使用时必须提供 |163| `-y, --yes` | 跳过 `--prune` 的确认提示。当 stdin 或 stdout 不是 TTY 时，与 `--prune` 一起使用是必需的 |
164| `--json` | 将结果作为一个 JSON 对象打印在 stdout 的最后一行，格式与 [`plugin install --json`](#plugin-json-result) 相同。不能与 `--prune` 组合使用。需要 Claude Code v2.1.268 或更高版本 |164| `--json` | 在 stdout 的最后一行以一个 JSON 对象打印结果，格式[与 `plugin install --json` 相同](#plugin-json-result)。不能与 `--prune` 同时使用。需要 Claude Code v2.1.268 或更高版本 |
165 165
166从项目作用域卸载插件：166从项目作用域卸载插件：
167 167
169claude plugin uninstall formatter@my-marketplace --scope project169claude plugin uninstall formatter@my-marketplace --scope project
170```170```
171 171
172Claude Code 打印 `Successfully uninstalled plugin: formatter (scope: project)`。当插件未在该作用域安装时，命令会打印以 `Failed to uninstall plugin "formatter@my-marketplace":` 开头的行并以 `1` 退出。172Claude Code 会打印 `Successfully uninstalled plugin: formatter (scope: project)`。当插件未在该作用域安装时，命令会打印以 `Failed to uninstall plugin "formatter@my-marketplace":` 开头的一行，并以 `1` 退出。
173 173
174如果失败行后接 `"formatter" was not uninstalled:` 并指出某个设置文件，说明 Claude Code 无法确认该作用域的设置已不再启用该插件，因此插件保持安装状态，其保存的所有内容也都保留。使用 `--json` 时，结果携带 `failureCode: "settings_still_on"`。此设置检查需要 Claude Code v2.1.282 或更高版本。174如果失败行后续为 `"formatter" was not uninstalled:` 并指出某个设置文件，说明 Claude Code 无法确认该作用域的设置不再启用该插件，因此插件及其保存的所有内容都保持安装状态。使用 `--json` 时，结果会带有 `failureCode: "settings_still_on"`。此设置检查需要 Claude Code v2.1.282 或更高版本。
175 175
176#### 卸载会删除和保留的内容176#### 卸载会删除和保留的内容
177 177
178当您从插件安装所在的最后一个作用域卸载插件时，Claude Code 还会删除插件存储的[选项和密钥](https://code.claude.com/docs/zh-CN/plugins/manifest-reference.md#user-configuration)及其数据目录 `~/.claude/plugins/data/<id>/`。有三个例外：178当您从插件安装所在的最后一个作用域卸载该插件时，Claude Code 还会删除插件存储的[选项和密钥](https://code.claude.com/docs/zh-CN/plugins/manifest-reference.md#user-configuration)及其数据目录 `~/.claude/plugins/data/<id>/`。有三种例外情况：
179 179
180* 使用 `--keep-data` 时，数据目录会保留180* 使用 `--keep-data` 时，数据目录会保留
181* 当另一个已安装的插件使用相同的文件夹时（例如其 ID 与此插件仅在字母大小写上不同），数据目录会保留181* 当另一个已安装的插件使用同一文件夹时（例如其 ID 与此插件仅在字母大小写上不同），数据目录会保留
182* 当 Claude Code 从该作用域移除插件后无法读回已安装插件列表时，选项、密钥和数据目录都会保留，因为插件可能仍安装在另一个作用域。卸载仍然成功。消息会列出保留的内容以及如何删除它们，使用 `--json` 时结果携带 `savedKept: "install_records_unreadable"`182* 当 Claude Code 从该作用域移除插件后无法重新读取已安装插件列表时，选项、密钥和数据目录都会保留，因为该插件可能仍安装在其他作用域。卸载仍会成功。消息会列出保留的内容以及删除方法，使用 `--json` 时结果会带有 `savedKept: "install_records_unreadable"`
183 183
184使用 `--json` 时，`keptData` 报告目录是否保留，目录保留时 `/plugin` 会显示 `· data preserved`。对于未使用 `--keep-data` 却保留的目录，此报告需要 Claude Code v2.1.281 或更高版本。`savedKept` 字段需要 Claude Code v2.1.282 或更高版本。184使用 `--json` 时，`keptData` 会报告目录是否被保留；若被保留，`/plugin` 会显示 `· data preserved`。对于未使用 `--keep-data` 而被保留的目录，此报告需要 Claude Code v2.1.281 或更高版本。`savedKept` 字段需要 Claude Code v2.1.282 或更高版本。
185 185
186### plugin enable186### plugin enable
187 187
188启用已禁用的插件。对于[从 claude.ai 同步的插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#synced-plugins)，请传递 `<name>@synced` 作为插件。188启用已禁用的插件。对于[从 claude.ai 同步的插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#synced-plugins)，请传入 `<name>@synced` 作为插件。
189 189
190```bash theme={null}190```bash theme={null}
191claude plugin enable <plugin> [options]191claude plugin enable <plugin> [options]
192```192```
193 193
194| 标志 | 描述 |194| 标志 | 说明 |
195| :- | :- |195| :- | :- |
196| `-s, --scope <scope>` | 启用的作用域：`user`、`project` 或 `local`。省略时自动检测 |196| `-s, --scope <scope>` | 启用所在的作用域：`user`、`project` 或 `local`。省略时自动检测 |
197| `--json` | 将结果作为一个 JSON 对象打印在 stdout 的最后一行，格式与 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更高版本 |197| `--json` | 在 stdout 的最后一行以一个 JSON 对象打印结果，格式[与 `plugin install --json` 相同](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 |
198 198
199不使用 `--scope` 时，命令按 local、project、user 的顺序检查您的设置文件，并使用第一个提及该插件的作用域。199未指定 `--scope` 时，命令会按 local、project、user 的顺序检查您的设置文件，并使用第一个提及该插件的作用域。
200 200
201如果传递的 `--scope` 并非插件声明所在的作用域，命令要么写入覆盖，要么失败：201如果您传入的 `--scope` 中未声明该插件，命令会写入覆盖或失败：
202 202
203* **[优先级高于](https://code.claude.com/docs/zh-CN/plugins/loading.md)声明作用域的作用域**：Claude Code 在您传递的作用域写入覆盖。例如，`claude plugin disable formatter --scope local` 仅为您自己关闭在项目中启用的插件203* **[优先于](https://code.claude.com/docs/zh-CN/plugins/loading.md)声明所在作用域的作用域**：Claude Code 会在您传入的作用域写入覆盖。例如，`claude plugin disable formatter --scope local` 仅为您自己关闭在项目中启用的插件
204* **任何其他作用域**：命令失败，并显示 `Plugin "formatter" is installed at project scope, not user. Use --scope project or omit --scope to auto-detect.`204* **任何其他作用域**：命令失败并显示 `Plugin "formatter" is installed at project scope, not user. Use --scope project or omit --scope to auto-detect.`
205 205
206如果插件已在解析出的作用域中启用，命令会打印 `Plugin "formatter" is already enabled` 并以 `1` 退出。使用 `--json` 时，结果包含 `"failureCode": "already_in_goal_state"` 和 `"alreadyInGoalState": true`，因此脚本可以将这种情况视为成功。206如果插件在解析出的作用域中已启用，命令会打印 `Plugin "formatter" is already enabled` 并以 `1` 退出。使用 `--json` 时，结果带有 `"failureCode": "already_in_goal_state"` 和 `"alreadyInGoalState": true`，因此脚本可以将这种情况视为成功。
207 207
208当插件声明了[依赖](https://code.claude.com/docs/zh-CN/plugins/dependencies.md)时，Claude Code 也会启用这些依赖。在以下情况下命令会失败：208当插件声明了[依赖](https://code.claude.com/docs/zh-CN/plugins/dependencies.md)时，Claude Code 也会启用它们。在以下情况下命令会失败：
209 209
210* **某个依赖未安装**：启用失败，并为每个缺失的依赖打印 `claude plugin install` 命令210* **某个依赖未安装**：启用失败，并为每个缺失的依赖打印 `claude plugin install` 命令
211* **某个依赖被您组织的插件策略阻止**：启用失败，并指出被阻止的依赖211* **某个依赖被您组织的插件策略阻止**：启用失败，并指出被阻止的依赖
212* **某个依赖在优先级高于目标作用域的作用域中被设置为 `false`**：启用失败。请在该作用域启用该依赖，或传递 `--scope` 以写入该作用域212* **某个依赖在优先级高于目标作用域的作用域中被设为 `false`**：启用失败。请在该作用域启用该依赖，或传入 `--scope` 写入该作用域
213 213
214在插件声明所在的任何位置重新启用插件：214在插件声明所在的任何位置重新启用插件：
215 215
217claude plugin enable formatter217claude plugin enable formatter
218```218```
219 219
220Claude Code 打印 `Successfully enabled plugin: formatter (scope: project)`，并指出它检测到的作用域。220Claude Code 会打印 `Successfully enabled plugin: formatter (scope: project)`，并指出其检测到的作用域。
221 221
222### plugin disable222### plugin disable
223 223
224禁用插件而不卸载它。对于[从 claude.ai 同步的插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#synced-plugins)，请传递 `<name>@synced` 作为插件。224禁用插件但不卸载。对于[从 claude.ai 同步的插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#synced-plugins)，请传入 `<name>@synced` 作为插件。
225 225
226```bash theme={null}226```bash theme={null}
227claude plugin disable [plugin] [options]227claude plugin disable [plugin] [options]
228```228```
229 229
230| 标志 | 描述 |230| 标志 | 说明 |
231| :- | :- |231| :- | :- |
232| `-a, --all` | 禁用所有已启用的插件。不能与插件名称或 `--scope` 组合使用 |232| `-a, --all` | 禁用所有已启用的插件。不能与插件名称或 `--scope` 同时使用 |
233| `-s, --scope <scope>` | 禁用的作用域：`user`、`project` 或 `local`。省略时自动检测 |233| `-s, --scope <scope>` | 禁用所在的作用域：`user`、`project` 或 `local`。省略时自动检测 |
234| `--json` | 将结果作为一个 JSON 对象打印在 stdout 的最后一行，格式与 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更高版本 |234| `--json` | 在 stdout 的最后一行以一个 JSON 对象打印结果，格式[与 `plugin install --json` 相同](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 |
235 235
236不使用 `--scope` 时，作用域按与 [`plugin enable`](#plugin-enable) 相同的 local、project、user 顺序自动检测。236未指定 `--scope` 时，作用域会按与 [`plugin enable`](#plugin-enable) 相同的 local、project、user 顺序自动检测。
237 237
238如果既未传递插件名称也未传递 `--all`，Claude Code 会打印 `Please specify a plugin name or use --all to disable all plugins` 并以 `1` 退出。禁用已禁用的插件会打印 `Plugin "formatter" is already disabled` 并以 `1` 退出，与 [`plugin enable`](#plugin-enable) 对已启用插件的处理方式相同。238如果您既未传入插件名称也未传入 `--all`，Claude Code 会打印 `Please specify a plugin name or use --all to disable all plugins` 并以 `1` 退出。禁用已禁用的插件会打印 `Plugin "formatter" is already disabled` 并以 `1` 退出，这与 [`plugin enable`](#plugin-enable) 对已启用插件的处理方式相同。
239 239
240对于仍被需要的插件，命令会失败：240对于仍被需要的插件，命令会失败：
241 241
242* **另一个已启用的插件[依赖](https://code.claude.com/docs/zh-CN/plugins/dependencies.md)它**：命令失败，并列出需要先禁用的依赖方插件242* **另一个已启用的插件[依赖](https://code.claude.com/docs/zh-CN/plugins/dependencies.md)它**：命令失败，并指出需要先禁用的依赖方
243* **您的组织要求将其作为同步插件**：命令失败且不保存任何内容243* **您的组织要求将其作为同步插件**：命令失败且不保存任何内容
244 244
245禁用一个插件：245禁用一个插件：
248claude plugin disable formatter248claude plugin disable formatter
249```249```
250 250
251Claude Code 打印 `Successfully disabled plugin: formatter (scope: project)`。251Claude Code 会打印 `Successfully disabled plugin: formatter (scope: project)`。
252 252
253### plugin update253### plugin update
254 254
258claude plugin update <plugin> [options]258claude plugin update <plugin> [options]
259```259```
260 260
261| 标志 | 描述 |261| 标志 | 说明 |
262| :- | :- |262| :- | :- |
263| `-s, --scope <scope>` | 要更新的作用域：`user`、`project`、`local` 或 `managed`。省略时自动检测 |263| `-s, --scope <scope>` | 要更新的作用域：`user`、`project`、`local` 或 `managed`。省略时自动检测 |
264| `-y, --yes` | 接受[命令源](https://code.claude.com/docs/zh-CN/plugins/host-marketplace.md)插件已更改的安装命令，不出现提示。当 stdin 或 stdout 不是 TTY 时必须提供，除非传递了 `--accept-command`。需要 Claude Code v2.1.229 或更高版本 |264| `-y, --yes` | 接受[命令来源](https://code.claude.com/docs/zh-CN/plugins/host-marketplace.md)插件已更改的安装命令，不出现提示。当 stdin 或 stdout 不是 TTY 时为必需，除非您传入 `--accept-command`。需要 Claude Code v2.1.229 或更高版本 |
265| `--accept-command <sha256>` | 代替 `-y`，接受之前某次 [`--json` 运行](#plugin-json-result)在 `shownCommand` 中报告了其 `sha256` 的市场声明命令。不能与 `-y` 组合使用。需要 Claude Code v2.1.271 或更高版本 |265| `--accept-command <sha256>` | 代替 `-y`，接受之前某次 [`--json` 运行](#plugin-json-result)在 `shownCommand` 中报告了其 `sha256` 的市场声明命令。不能与 `-y` 同时使用。需要 Claude Code v2.1.271 或更高版本 |
266| `--json` | 将结果作为一个 JSON 对象打印在 stdout 的最后一行，格式与 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更高版本 |266| `--json` | 在 stdout 的最后一行以一个 JSON 对象打印结果，格式[与 `plugin install --json` 相同](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 |
267 267
268更新插件：268更新插件：
269 269
271claude plugin update formatter@my-marketplace271claude plugin update formatter@my-marketplace
272```272```
273 273
274Claude Code 打印 `Checking for updates for plugin "formatter@my-marketplace"…`，然后打印结果。当没有更新的版本时，它会打印 `formatter is already at the latest version (1.0.0).` 并以 `0` 退出，除非它[重试插件的依赖安装](#retry-an-unfinished-dependency-install)且该安装失败。274Claude Code 会打印 `Checking for updates for plugin "formatter@my-marketplace"…`，然后显示结果。当没有更新的版本时，它会打印 `formatter is already at the latest version (1.0.0).` 并以 `0` 退出，除非它[重试了插件的依赖安装](#retry-an-unfinished-dependency-install)且该安装失败。
275 275
276#### 命令更新哪个作用域276#### 命令更新哪个作用域
277 277
278如果省略 `--scope`，命令会在当前项目中插件安装所在的最具体作用域更新插件，依次检查 local、project、user，然后是 managed。278如果您省略 `--scope`，命令会在当前项目中该插件安装所在的最具体作用域更新插件，依次检查 local、project、user，然后是 managed。
279 279
280在 v2.1.281 之前，省略 `--scope` 时命令使用 `user`，因此更新仅安装在 project 或 local 作用域的插件会失败，并显示 `Plugin "<name>" is not installed at scope user`。在这些版本上，请传递 `--scope`。280在 v2.1.281 之前，省略 `--scope` 时命令使用 `user`，因此更新仅安装在 project 或 local 作用域的插件会失败并显示 `Plugin "<name>" is not installed at scope user`。在这些版本上，请传入 `--scope`。
281 281
282`managed` 是唯一可以更新但不能安装到的作用域。有关管理员安装的插件，请参阅[为组织管理插件](https://code.claude.com/docs/zh-CN/plugins/org.md)。282`managed` 是唯一一个可以更新但不能安装到的作用域。对于管理员安装的插件，请参阅[为您的组织管理插件](https://code.claude.com/docs/zh-CN/plugins/org.md)。
283 283
284#### 按裸名称更新284#### 按裸名称更新
285 285
286您可以传递不带市场的插件名称，命令会将其与已安装的插件进行匹配。当来自不同市场的已安装插件同名时，命令会拒绝更新，并列出应改为运行的限定 `plugin-name@marketplace-name` 命令。按裸名称更新需要 Claude Code v2.1.246 或更高版本。286您可以传入裸插件名称，命令会将其与您已安装的插件进行匹配。当来自不同市场的已安装插件同名时，命令会拒绝更新，并列出应改为运行的限定形式 `plugin-name@marketplace-name` 命令。按裸名称更新需要 Claude Code v2.1.246 或更高版本。
287 287
288#### 重试未完成的依赖安装288#### 重试未完成的依赖安装
289 289
290当插件已是最新版本时，该命令还可以在其缓存副本中重试未完成的依赖安装。有关该重试会运行或被跳过的情况，请参阅[其列出的软件包未安装](https://code.claude.com/docs/zh-CN/plugins/troubleshooting.md#the-packages-it-lists-are-not-installed)。如果重试失败，输出为 `Failed to update plugin "formatter@my-marketplace"` 及原因，退出码为 `1`。在 v2.1.287 之前，该命令会报告插件已是最新版本，而不重试安装。290当插件已是最新版本时，命令还可以在其缓存副本中重试未完成的依赖安装。有关该重试何时运行或被跳过，请参阅[其列出的软件包未安装](https://code.claude.com/docs/zh-CN/plugins/troubleshooting.md#the-packages-it-lists-are-not-installed)。如果重试失败，输出为带有原因的 `Failed to update plugin "formatter@my-marketplace"`，退出码为 `1`。在 v2.1.287 之前，命令会报告插件已是最新版本，而不重试安装。
291 291
292### plugin list292### plugin list
293 293
297claude plugin list [options]297claude plugin list [options]
298```298```
299 299
300| 标志 | 描述 |300| 标志 | 说明 |
301| :- | :- |301| :- | :- |
302| `--json` | 以 JSON 格式打印列表 |302| `--json` | 以 JSON 格式打印列表 |
303| `--available` | 同时列出您的市场提供但尚未安装的插件。不使用 `--json` 时无效 |303| `--available` | 同时列出您的市场提供但您尚未安装的插件。不使用 `--json` 时无效 |
304| `--data-size [plugin]` | 测量每个已安装插件的[已保存数据目录](#what-an-uninstall-deletes-and-keeps)，或仅测量以 `name@marketplace` 形式指定的插件。不使用 `--json` 时无效。如果该名称没有安装记录，命令会打印 `--data-size names a plugin that is not installed` 并以 `1` 退出，而不是打印列表。需要 Claude Code v2.1.285 或更高版本 |304| `--data-size [plugin]` | 测量每个已安装插件的[已保存数据目录](#what-an-uninstall-deletes-and-keeps)，或仅测量以 `name@marketplace` 指定的插件。不使用 `--json` 时无效。如果该名称没有安装记录，命令会打印 `--data-size names a plugin that is not installed` 并以 `1` 退出，而不打印列表。需要 Claude Code v2.1.285 或更高版本 |
305 305
306Claude Code 按各插件的加载方式对人类可读的输出进行分组：306Claude Code 按每个插件的加载方式对人类可读输出进行分组：
307 307
308* **`Installed plugins:`**：您从市场安装的插件308* **`Installed plugins:`**：您从市场安装的插件
309* **`Session-only plugins (--plugin-dir / --plugin-url):`**：由同一命令中的这些标志加载的插件，如 `claude --plugin-dir ./my-plugin plugin list`309* **`Session-only plugins (--plugin-dir / --plugin-url):`**：在同一命令中通过这些标志加载的插件，例如 `claude --plugin-dir ./my-plugin plugin list`
310* **`Skills-directory plugins (.claude/skills/*):`**：Claude Code 在 skills 目录中找到的插件310* **`Skills-directory plugins (.claude/skills/*):`**：Claude Code 在 skills 目录中发现的插件
311* **`Synced from claude.ai`**：[从您的 claude.ai 账户同步的插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#synced-plugins)311* **`Synced from claude.ai`**：[从您的 claude.ai 账户同步的插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#synced-plugins)
312 312
313当所有分组都为空时，Claude Code 打印 ``No plugins installed. Use `claude plugin install` to install a plugin.``313当所有分组都为空时，Claude Code 会打印 ``No plugins installed. Use `claude plugin install` to install a plugin.``
314 314
315#### JSON 输出315#### JSON 输出
316 316
317使用 `--json` 时，Claude Code 打印一个数组，每个安装对应一个对象。每个对象携带以下字段。`id`、`version`、`scope`、`enabled` 和 `installPath` 始终存在，其他字段仅在适用时出现。317使用 `--json` 时，Claude Code 会打印一个数组，每个安装对应一个对象。每个对象带有以下字段。`id`、`version`、`scope`、`enabled` 和 `installPath` 始终存在，其他字段仅在适用时出现。
318 318
319| 字段 | 类型 | 描述 |319| 字段 | 类型 | 说明 |
320| :- | :- | :- |320| :- | :- | :- |
321| `id` | string | 安装的插件为 `name@marketplace`，仅限会话的插件为 `name@inline`，skills-directory 插件为 `name@skills-dir`，从 claude.ai 同步的插件为 `name@synced` |321| `id` | string | 安装的插件为 `name@marketplace`，仅限会话的插件为 `name@inline`，skills 目录插件为 `name@skills-dir`，从 claude.ai 同步的插件为 `name@synced` |
322| `version` | string | 对于市场安装，为 [Claude Code 在安装时计算的版本](https://code.claude.com/docs/zh-CN/plugins/loading.md#versions-and-updates)。对于仅限会话、skills-directory 或同步插件，为清单的 `version`，未声明时为 `unknown` |322| `version` | string | 对于市场安装，为安装时 [Claude Code 计算出的版本](https://code.claude.com/docs/zh-CN/plugins/loading.md#versions-and-updates)。对于仅限会话、skills 目录或同步的插件，为清单中的 `version`，未声明时为 `unknown` |
323| `scope` | string | 安装的插件为 `user`、`project`、`local` 或 `managed`；skills-directory 插件为 `user` 或 `project`；仅限会话的插件为 `session`；从 claude.ai 同步的插件为 `synced` |323| `scope` | string | 安装的插件为 `user`、`project`、`local` 或 `managed`；skills 目录插件为 `user` 或 `project`；仅限会话的插件为 `session`；从 claude.ai 同步的插件为 `synced` |
324| `enabled` | boolean | 插件在合并后的设置中是否启用 |324| `enabled` | boolean | 插件在您合并后的设置中是否已启用 |
325| `installPath` | string | 插件加载所在的目录，但会话从其市场文件夹中[就地加载](https://code.claude.com/docs/zh-CN/plugins/loading.md#in-place-and-copied-plugins)的插件除外 |325| `installPath` | string | 插件加载所在的目录，但会话从其市场文件夹[就地加载](https://code.claude.com/docs/zh-CN/plugins/loading.md#in-place-and-copied-plugins)的插件除外 |
326| `readFromFolder` | string | 对于会话从其市场文件夹中[就地加载](https://code.claude.com/docs/zh-CN/plugins/loading.md#in-place-and-copied-plugins)的插件，为该文件夹内插件的源目录。需要 Claude Code v2.1.289 或更高版本 |326| `readFromFolder` | string | 对于会话从其市场文件夹[就地加载](https://code.claude.com/docs/zh-CN/plugins/loading.md#in-place-and-copied-plugins)的插件，为该插件在该文件夹内的源目录。需要 Claude Code v2.1.289 或更高版本 |
327| `folderVersion` | string | 与 `readFromFolder` 一起出现，为 Claude Code 从该文件夹加载插件时插件的 `version`，可能与上面的 `version` 字段不同。插件未加载或未声明版本时不存在。需要 Claude Code v2.1.289 或更高版本 |327| `folderVersion` | string | 与 `readFromFolder` 一起出现，为 Claude Code 从该文件夹加载的插件 `version`，可能与上面的 `version` 字段不同。当插件未加载或未声明版本时不存在。需要 Claude Code v2.1.289 或更高版本 |
328| `installedAt` | string | 安装的 ISO 时间戳。仅限市场安装 |328| `installedAt` | string | 安装的 ISO 时间戳。仅限市场安装 |
329| `lastUpdated` | string | 最后更新的 ISO 时间戳。仅限市场安装 |329| `lastUpdated` | string | 上次更新的 ISO 时间戳。仅限市场安装 |
330| `projectPath` | string | 安装所属的项目。仅限 `project` 和 `local` 作用域 |330| `projectPath` | string | 安装所属的项目。仅限 `project` 和 `local` 作用域 |
331| `mcpServers` | object | 插件的 MCP 服务器定义，仅当市场安装的插件包含 MCP 服务器时出现 |331| `mcpServers` | object | 插件的 MCP 服务器定义，当从市场安装的插件有定义时出现 |
332| `errors` | array of strings | 加载错误，仅当插件加载失败时出现 |332| `errors` | array of strings | 加载错误，当插件加载失败时出现 |
333| `notes` | array of strings | 非加载错误的警告，例如编写问题或[未安装的软件包](https://code.claude.com/docs/zh-CN/plugins/loading.md#when-the-dependency-install-fails-or-is-skipped) |333| `notes` | array of strings | 非加载错误的警告，例如编写问题或[未安装的软件包](https://code.claude.com/docs/zh-CN/plugins/loading.md#when-the-dependency-install-fails-or-is-skipped) |
334| `errorDetails` | array of objects | 每个 `errors` 条目对应一个对象，给出其诊断 `type` 以及它所引用的名称，例如插件、市场、服务器或文件。需要 Claude Code v2.1.268 或更高版本 |334| `errorDetails` | array of objects | 每个 `errors` 条目对应一个对象，给出其诊断 `type` 及其引用的名称，例如插件、市场、服务器或文件。需要 Claude Code v2.1.268 或更高版本 |
335| `noteDetails` | array of objects | 每个 `notes` 条目对应的相同详细对象。需要 Claude Code v2.1.268 或更高版本 |335| `noteDetails` | array of objects | 每个 `notes` 条目对应的相同详情对象。需要 Claude Code v2.1.268 或更高版本 |
336| `hasUserConfig` | boolean | 当插件已加载且其清单声明了 [`userConfig` 选项](https://code.claude.com/docs/zh-CN/plugins/manifest-reference#user-configuration)时存在且为 `true`。对于加载失败的插件，无论其清单声明什么，该字段都不存在。永远不包含已保存的值。需要 Claude Code v2.1.285 或更高版本 |336| `hasUserConfig` | boolean | 当插件已加载且其清单声明了 [`userConfig` 选项](https://code.claude.com/docs/zh-CN/plugins/manifest-reference#user-configuration)时存在且为 `true`。对于加载失败的插件，无论其清单声明了什么都不存在。从不包含已保存的值。需要 Claude Code v2.1.285 或更高版本 |
337| `projectEnabled` | boolean | 项目共享的 `.claude/settings.json` 是否启用该插件。仅限市场安装。需要 Claude Code v2.1.285 或更高版本 |337| `projectEnabled` | boolean | 项目共享的 `.claude/settings.json` 是否启用该插件。仅限市场安装。需要 Claude Code v2.1.285 或更高版本 |
338| `dataDirSize` | object | 使用 `--data-size` 时，以 `bytes` 和 `human` 表示的插件[已保存数据目录](#what-an-uninstall-deletes-and-keeps)大小；目录缺失或为空时不存在。仅限市场安装。需要 Claude Code v2.1.285 或更高版本 |338| `dataDirSize` | object | 使用 `--data-size` 时，插件[已保存数据目录](#what-an-uninstall-deletes-and-keeps)的大小，以 `bytes` 和 `human` 表示；当目录缺失或为空时不存在。仅限市场安装。需要 Claude Code v2.1.285 或更高版本 |
339| `dataDirUnreadable` | boolean | 使用 `--data-size` 时，如果已保存的数据目录存在但无法测量，则为 `true`。仅限市场安装。需要 Claude Code v2.1.285 或更高版本 |339| `dataDirUnreadable` | boolean | 使用 `--data-size` 时，如果已保存数据目录存在但无法测量，则为 `true`。仅限市场安装。需要 Claude Code v2.1.285 或更高版本 |
340 340
341使用 `--json --available` 时，Claude Code 打印一个对象而不是数组。其 `installed` 字段包含已安装插件对象的数组，其 `available` 字段为每个未安装的市场插件包含一个对象，带有以下字段。341使用 `--json --available` 时，Claude Code 会打印一个对象而不是数组。其 `installed` 字段包含已安装插件对象的数组，其 `available` 字段为每个未安装的市场插件包含一个对象，带有以下字段。
342 342
343| 字段 | 类型 | 描述 |343| 字段 | 类型 | 说明 |
344| :- | :- | :- |344| :- | :- | :- |
345| `pluginId` | string | `name@marketplace` |345| `pluginId` | string | `name@marketplace` |
346| `name` | string | 插件在市场中的名称 |346| `name` | string | 插件在市场中的名称 |
347| `marketplaceName` | string | 提供该插件的市场 |347| `marketplaceName` | string | 提供该插件的市场 |
348| `source` | string or object | 市场条目的 [source](https://code.claude.com/docs/zh-CN/plugins/marketplace-reference.md)：相对路径为字符串，否则为对象 |348| `source` | string or object | 市场条目的[来源](https://code.claude.com/docs/zh-CN/plugins/marketplace-reference.md)：相对路径为字符串，否则为对象 |
349| `description` | string | 条目的描述（如有） |349| `description` | string | 条目的描述（如有） |
350| `version` | string | 条目的版本（如有声明） |350| `version` | string | 条目的版本（如有声明） |
351| `installCount` | number | 安装次数（当 Claude Code 有该插件的安装次数时） |351| `installCount` | number | 安装次数（当 Claude Code 有该插件的数据时） |
352 352
353### plugin details353### plugin details
354 354
355显示插件的组件清单及其预计 token 成本。355显示插件的组件清单及其预估 token 开销。
356 356
357插件必须已加载：已安装、在 skills 目录中找到，或在同一命令中通过 `--plugin-dir` 或 `--plugin-url` 传入。`<name>` 是插件 `name` 或 `name@marketplace`。357插件必须已加载：已安装、在 skills 目录中被发现，或在同一命令中通过 `--plugin-dir` 或 `--plugin-url` 传入。`<name>` 是插件的 `name` 或 `name@marketplace`。
358 358
359```bash theme={null}359```bash theme={null}
360claude plugin details <name>360claude plugin details <name>
362 362
363该命令除 `--help` 外不接受任何标志。363该命令除 `--help` 外不接受任何标志。
364 364
365显示已安装插件提供的内容：365显示已安装插件所提供的内容：
366 366
367```bash theme={null}367```bash theme={null}
368claude plugin details formatter368claude plugin details formatter
369```369```
370 370
371Claude Code 打印插件的名称、版本、描述和来源，然后打印以下部分：371Claude Code 会打印插件的名称、版本、描述和来源，然后显示以下部分：
372 372
373* **`Component inventory`**：插件的 skill、Agent、hook、MCP 服务器和 LSP 服务器373* **`Component inventory`**：插件的 skill、Agent、hook、MCP 服务器和 LSP 服务器
374* **`Projected token cost`**：插件添加到每个会话的常驻 token374* **`Projected token cost`**：插件在每个会话中添加的常驻 token
375* **`Per-component (rounded)`**：每个 skill、Agent 和命令的常驻和调用时估算值。插件没有这些组件时省略375* **`Per-component (rounded)`**：每个 skill、Agent 和命令的常驻及调用时估算值。插件没有这些组件时省略
376 376
377有关这两个成本数字的含义，请参阅[衡量插件成本和使用情况](https://code.claude.com/docs/zh-CN/plugins/measure.md)。377有关这两个开销数字的含义，请参阅[衡量插件开销和使用情况](https://code.claude.com/docs/zh-CN/plugins/measure.md)。
378 378
379对于未加载的插件，Claude Code 打印以下消息并以 `1` 退出：379对于未加载的插件，Claude Code 会打印以下消息并以 `1` 退出：
380 380
381```text theme={null}381```text theme={null}
382Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.382Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.
383```383```
384 384
385以 `@builtin` 结尾的 ID 指代某个 [Claude Code 内置插件](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md#mods-built-into-claude-code)。如果您传递此类 ID 而 Claude Code 找不到该插件，消息将改为：385以 `@builtin` 结尾的 ID 指向某个 [Claude Code 内置插件](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md#mods-built-into-claude-code)。如果您传入这样的 ID 而 Claude Code 未找到该插件，消息会改为：
386 386
387```text theme={null}387```text theme={null}
388Plugin "<name>@builtin" not found. Built-in plugins don't appear in `claude plugin list`. To see the ones available in a session, run /plugin in Claude Code and open the Installed tab.388Plugin "<name>@builtin" not found. Built-in plugins don't appear in `claude plugin list`. To see the ones available in a session, run /plugin in Claude Code and open the Installed tab.
390 390
391### plugin configure391### plugin configure
392 392
393显示已安装插件的 [`userConfig`](https://code.claude.com/docs/zh-CN/plugins/manifest-reference#user-configuration) 选项及哪些已设置，或保存通过 stdin 管道传入的值。需要 Claude Code v2.1.285 或更高版本。393显示已安装插件的 [`userConfig`](https://code.claude.com/docs/zh-CN/plugins/manifest-reference#user-configuration) 选项及其中哪些已设置，或保存通过 stdin 传入的值。需要 Claude Code v2.1.285 或更高版本。
394 394
395```bash theme={null}395```bash theme={null}
396claude plugin configure <plugin>396claude plugin configure <plugin>
397```397```
398 398
399| 标志 | 描述 |399| 标志 | 说明 |
400| :- | :- |400| :- | :- |
401| `--values-stdin` | 从 stdin 读取以单行字符串组成的 JSON 对象形式的选项值并保存。未提供的选项保留其已保存的值 |401| `--values-stdin` | 从 stdin 读取选项值（一个由单行字符串组成的 JSON 对象）并保存。您未提供的选项会保留其已保存的值 |
402| `--json` | 将结果作为一个 JSON 对象打印在 stdout 上。不使用 `--values-stdin` 时，该对象携带选项的 `schema` 和 `choices`、它们的初始 `inputs`，以及 `configured` 和 `unconfigured` 选项名称。使用 `--values-stdin` 时，它携带 `saved` 选项名称，以及在可读回时的 `unconfigured` 选项名称 |402| `--json` | 在 stdout 上以一个 JSON 对象打印结果。不使用 `--values-stdin` 时，该对象带有选项的 `schema` 和 `choices`、其初始 `inputs`，以及 `configured` 和 `unconfigured` 选项名称。使用 `--values-stdin` 时，它带有 `saved` 选项名称，以及（在能够读回时）`unconfigured` 选项名称 |
403 403
404不使用标志时，命令列出每个选项，最多带三个标签：`required` 或 `optional`，然后是用于清单声明为敏感的选项的 `sensitive`，然后是 `set` 或 `not set`。它不打印已保存的值。使用 `--json` 时，输出包括非敏感选项的已保存值，但永远不包括敏感选项的文本。404不带标志时，命令会列出每个选项，并最多带有三个标签：先是 `required` 或 `optional`，然后对于清单声明为敏感的选项显示 `sensitive`，最后是 `set` 或 `not set`。它不会打印已保存的值。使用 `--json` 时，输出包含非敏感选项的已保存值，但从不包含敏感选项的文本。
405 405
406要保存值，请将其写入一个文件，作为将选项键映射到字符串值的 JSON 对象，然后通过 stdin 传入该文件。将 `formatter@my-marketplace` 替换为 `claude plugin list` 中显示的您自己插件的 id。此示例从包含 `{"api_url": "https://example.com"}` 的文件 `values.json` 设置一个名为 `api_url` 的选项：406要保存值，请将其写入一个文件，内容为将选项键映射到字符串值的 JSON 对象，然后通过 stdin 传入该文件。将 `formatter@my-marketplace` 替换为 `claude plugin list` 所显示的您自己插件的 id。此示例从包含 `{"api_url": "https://example.com"}` 的文件 `values.json` 设置一个名为 `api_url` 的选项：
407 407
408```bash theme={null}408```bash theme={null}
409claude plugin configure formatter@my-marketplace --values-stdin < values.json409claude plugin configure formatter@my-marketplace --values-stdin < values.json
410```410```
411 411
412Claude Code 根据选项声明的类型验证每个值，并打印 `Configuration saved. Restart Claude Code to apply it.` 如果传递了清单未声明的键，或未通过验证的值，命令不保存任何内容，打印 `Failed to save configuration:` 及原因，并以 `1` 退出。使用 `--json` 时，被拒绝的值还会在 stdout 上打印一个对象，其 `refused` 字段携带 `message`，以及在某个选项出错时该选项的 `option` 键。412Claude Code 会根据选项声明的类型验证每个值，并打印 `Configuration saved. Restart Claude Code to apply it.` 如果您传入了清单未声明的键，或者某个值未通过验证，命令不会保存任何内容，会打印带有原因的 `Failed to save configuration:`，并以 `1` 退出。使用 `--json` 时，被拒绝的值还会在 stdout 上打印一个对象，其 `refused` 字段带有 `message`，以及（当问题出在某一个选项时）该选项的 `option` 键。
413 413
414请传递 `claude plugin list` 中显示的插件完整 `name@marketplace` id。`configure` 不接受裸 `name`。当没有已加载的插件具有该 id 时，命令打印 `No installed plugin has the id "<plugin>".` 并以 `1` 退出。414请按照 `claude plugin list` 显示的那样传入插件完整的 `name@marketplace` id。`configure` 不接受裸 `name`。当没有已加载的插件具有该 id 时，命令会打印 `No installed plugin has the id "<plugin>".` 并以 `1` 退出。
415 415
416有关捆绑 MCP 服务器的设置，请参阅 [`plugin install --config`](#plugin-install) 或 `/plugin` 中的 **Configure** 项。416有关捆绑的 MCP 服务器的设置，请参阅 [`plugin install --config`](#plugin-install) 或 `/plugin` 中的 **Configure** 项。
417 417
418### plugin prune418### plugin prune
419 419
420移除不再被任何已安装插件需要的自动安装[依赖项](https://code.claude.com/docs/zh-CN/plugins/dependencies.md)。该命令永远不会移除您自己安装的插件。`autoremove` 是 `prune` 的别名。420移除已没有任何已安装插件需要的自动安装的[依赖](https://code.claude.com/docs/zh-CN/plugins/dependencies.md)。该命令绝不会移除您自己安装的插件。`autoremove` 是 `prune` 的别名。
421 421
422```bash theme={null}422```bash theme={null}
423claude plugin prune [options]423claude plugin prune [options]
424```424```
425 425
426| 标志 | 描述 |426| 标志 | 说明 |
427| :- | :- |427| :- | :- |
428| `-s, --scope <scope>` | 在指定作用域清理：`user`、`project` 或 `local`。默认为 `user` |428| `-s, --scope <scope>` | 在以下作用域清理：`user`、`project` 或 `local`。默认为 `user` |
429| `--dry-run` | 列出将被移除的内容，但不实际移除 |429| `--dry-run` | 列出将被移除的内容，但不实际移除 |
430| `-y, --yes` | 跳过确认提示。当 stdin 或 stdout 不是 TTY 时必须提供 |430| `-y, --yes` | 跳过确认提示。当 stdin 或 stdout 不是 TTY 时为必需 |
431 431
432预览清理将移除的内容：432预览清理将移除的内容：
433 433
435claude plugin prune --dry-run435claude plugin prune --dry-run
436```436```
437 437
438Claude Code 列出孤立的依赖项，并以 `(dry run — nothing removed)` 结尾。没有可移除的内容时，它会打印以 `Nothing to prune` 开头的行。438Claude Code 会列出孤立的依赖，并以 `(dry run — nothing removed)` 结尾。如果没有可移除的内容，它会打印以 `Nothing to prune` 开头的一行。
439 439
440不使用 `--dry-run` 时，命令仅在您于提示处确认或传递 `-y` 后才移除孤立的依赖项。440不使用 `--dry-run` 时，命令仅在您在提示中确认或传入 `-y` 后才移除孤立的依赖。
441 441
442无论您在提示处如何回答，退出码都是 `0`。442无论您在提示中如何回答，退出码都是 `0`。
443 443
444`prune` 的行为取决于是否连接了终端以及是否传递了 `-y`：444`prune` 的行为取决于是否连接了终端以及您是否传入 `-y`：
445 445
446| 终端和标志 | 发生的情况 |446| 终端和标志 | 结果 |
447| :- | :- |447| :- | :- |
448| 交互式终端，无 `-y` | 列出孤立的依赖项并询问 `Remove? [y/N]` |448| 交互式终端，未传入 `-y` | 列出孤立的依赖并询问 `Remove? [y/N]` |
449| 任何终端，`-y` | 移除它们并打印 `Removed N auto-installed plugins: <names>` |449| 任意终端，传入 `-y` | 移除它们并打印 `Removed N auto-installed plugins: <names>` |
450| 非 TTY stdin 或 stdout，无 `-y` | 打印列表并显示 ``Not a TTY — run `claude plugin prune -y` to remove.``，不移除任何内容 |450| stdin 或 stdout 不是 TTY，未传入 `-y` | 打印列表和 ``Not a TTY — run `claude plugin prune -y` to remove.``，不移除任何内容 |
451 451
452### plugin eval452### plugin eval
453 453
454运行插件的 [eval 案例](https://code.claude.com/docs/zh-CN/plugin-evals.md)并报告评分结果。需要 Claude Code v2.1.269 或更高版本。454运行插件的 [eval 用例](https://code.claude.com/docs/zh-CN/plugin-evals.md)并报告评分结果。需要 Claude Code v2.1.269 或更高版本。
455 455
456每个案例由一个提示词加评分器组成。Claude Code 在仅加载目标插件的隔离会话中多次运行它，并且默认还会在不加载插件的情况下运行，以便报告显示两者的差异。456每个用例由一个提示词加上评分器组成。Claude Code 会在仅加载目标插件的隔离会话中多次运行它，并且默认还会在不加载该插件的情况下运行，以便报告显示差异。
457 457
458有关案例格式、评分器、结果和 CI 用法，请参阅[使用 evals 测试插件](https://code.claude.com/docs/zh-CN/plugin-evals.md)。458有关用例格式、评分器、结果和 CI 用法，请参阅[使用 eval 测试插件](https://code.claude.com/docs/zh-CN/plugin-evals.md)。
459 459
460```bash theme={null}460```bash theme={null}
461claude plugin eval [target] [options]461claude plugin eval [target] [options]
465 465
466* 插件目录466* 插件目录
467* 单个 `prompt.md` 或 `case.yaml` 文件467* 单个 `prompt.md` 或 `case.yaml` 文件
468* 以 `name` 或 `name@marketplace` 形式指定的已安装插件468* 以 `name` 或 `name@marketplace` 表示的已安装插件
469* `name@skills-dir`469* `name@skills-dir`
470 470
471请将目标放在 `--tag`、`--allow-tools` 和 `--json` 之前。这些选项会将其后的单词都作为自己的值，因此写在它们之后的目标会被读作标签、工具名称或 JSON 输出路径，而不是目标。471请将目标放在 `--tag`、`--allow-tools` 和 `--json` 之前。这些选项中的每一个都会把其后的词作为自己的值，因此写在其中某个选项之后的目标会被读作标签、工具名称或 JSON 输出路径，而不是目标。
472 472
473此表列出大多数运行使用的选项。运行 `claude plugin eval --help` 可查看完整选项集，包括 `--case`、`--tag`、`--output-dir`、`--report`、`--allow-real-servers`、`--keep-temp` 和 `--verbose`。473下表列出了大多数运行会用到的选项。运行 `claude plugin eval --help` 可查看完整的选项集，包括 `--case`、`--tag`、`--output-dir`、`--report`、`--allow-real-servers`、`--keep-temp` 和 `--verbose`。
474 474
475| 选项 | 描述 | 默认值 |475| 选项 | 说明 | 默认值 |
476| :- | :- | :- |476| :- | :- | :- |
477| `--runs <n>` | 每个 [arm](https://code.claude.com/docs/zh-CN/plugin-evals.md#compare-against-a-no-plugin-baseline) 中每个案例的运行次数 | 每个案例的 `runs`，否则为 3 |477| `--runs <n>` | 每个[分组](https://code.claude.com/docs/zh-CN/plugin-evals.md#compare-against-a-no-plugin-baseline)中每个用例的运行次数 | 每个用例的 `runs`，否则为 3 |
478| `-j, --concurrency <n>` | 同时运行的 Agent 会话数，1 到 8。它们共享您的速率限制 | `1` |478| `-j, --concurrency <n>` | 同时运行的 Agent 会话数，1 到 8。它们共享您的速率限制 | `1` |
479| `--model <model>` | 被测 Agent 使用的模型 | 每个案例的 `model`；否则如已设置则为 `ANTHROPIC_MODEL`；否则为 Claude Code 的默认模型 |479| `--model <model>` | 被测 Agent 使用的模型 | 每个用例的 `model`，否则为 `ANTHROPIC_MODEL`（如已设置），否则为 Claude Code 的默认模型 |
480| `--judge-model <model>` | `llm` 和 `baseline` 评分器使用的模型 | [后台任务](https://code.claude.com/docs/zh-CN/plugin-evals.md#grade-the-result)使用的模型 |480| `--judge-model <model>` | `llm` 和 `baseline` 评分器使用的模型 | 用于[后台任务](https://code.claude.com/docs/zh-CN/plugin-evals.md#grade-the-result)的模型 |
481| `--ablation <mode>` | `none` 或 `with-without`。请参阅[根据无插件基线评分](https://code.claude.com/docs/zh-CN/plugin-evals.md#compare-against-a-no-plugin-baseline) | 按案例决定，如该章节所述 |481| `--ablation <mode>` | `none` 或 `with-without`。请参阅[与无插件基线进行对比评分](https://code.claude.com/docs/zh-CN/plugin-evals.md#compare-against-a-no-plugin-baseline) | 按用例决定，如该章节所述 |
482| `--threshold <0..1>` | 如果任何案例的得分低于此值，则以 1 退出 | `1.0` |482| `--threshold <0..1>` | 如果任何用例的得分低于此值，则以 1 退出 | `1.0` |
483| `--max-cost-usd <usd>` | 一旦支出达到此值，在下一次运行前停止，以 2 退出，并报告部分结果 | 无限制 |483| `--max-cost-usd <usd>` | 当花费达到此值时，在下一次运行前停止，以 2 退出，并报告部分结果 | 无限制 |
484| `--allow-tools <tools...>` | 授予只读工具集之外的工具，例如 `Bash`、`Write`、`Edit` 或 `"mcp__plugin_<plugin>_<server>__*"`。请参阅[授予工具](https://code.claude.com/docs/zh-CN/plugin-evals.md#grant-tools) | |484| `--allow-tools <tools...>` | 授予只读集合之外的工具，例如 `Bash`、`Write`、`Edit` 或 `"mcp__plugin_<plugin>_<server>__*"`。请参阅[授予工具](https://code.claude.com/docs/zh-CN/plugin-evals.md#grant-tools) | |
485| `--scaffold` | 运行每个案例的 [`scaffold_script`](https://code.claude.com/docs/zh-CN/plugin-evals#add-setup-or-history-with-case-yaml) | 关闭 |485| `--scaffold` | 运行每个用例的 [`scaffold_script`](https://code.claude.com/docs/zh-CN/plugin-evals#add-setup-or-history-with-case-yaml) | 关闭 |
486| `--trust-plugin` | 跳过首次运行的信任提示，用于 CI。请参阅[运行可以访问的内容](https://code.claude.com/docs/zh-CN/plugin-evals.md#security) | 关闭 |486| `--trust-plugin` | 跳过首次运行的信任提示，适用于 CI。请参阅[运行可以访问的内容](https://code.claude.com/docs/zh-CN/plugin-evals.md#security) | 关闭 |
487| `--mocks <mode>` | `record` 或 `off`。请参阅[模拟 MCP 服务器](https://code.claude.com/docs/zh-CN/plugin-evals.md#mock-mcp-servers) | `record` |487| `--mocks <mode>` | `record` 或 `off`。请参阅[模拟 MCP 服务器](https://code.claude.com/docs/zh-CN/plugin-evals.md#mock-mcp-servers) | `record` |
488| `--eval-dir <dir>` | 插件下存放案例的目录 | 清单的 `experimental.evals`，否则为 `evals` |488| `--eval-dir <dir>` | 插件下存放用例的目录 | 清单中的 `experimental.evals`，否则为 `evals` |
489| `--json [path]` | 将[结果文档](https://code.claude.com/docs/zh-CN/plugin-evals.md#json-result)打印到 stdout，或写入 `.json` 路径 | |489| `--json [path]` | 将[结果文档](https://code.claude.com/docs/zh-CN/plugin-evals.md#json-result)打印到 stdout，或写入某个 `.json` 路径 | |
490| `--no-publish` | 将 HTML 报告保留在本地 | |490| `--no-publish` | 将 HTML 报告保留在本地 | |
491 491
492退出码反映运行的结束方式。如需在流水线中据此采取操作，请参阅[在 CI 中运行 evals](https://code.claude.com/docs/zh-CN/plugin-evals.md#run-evals-in-ci)。492退出码报告运行的结束方式。要在流水线中据此采取行动，请参阅[在 CI 中运行 eval](https://code.claude.com/docs/zh-CN/plugin-evals.md#run-evals-in-ci)。
493 493
494| 退出码 | 含义 |494| 退出码 | 含义 |
495| :- | :- |495| :- | :- |
496| `0` | 套件通过：每个案例都达到阈值，且没有其他原因导致运行失败 |496| `0` | 套件通过：每个用例都达到阈值，且没有其他原因导致运行失败 |
497| `1` | 存在失败的案例、加载错误、不受信任的插件目录、[因 API 错误而结束](https://code.claude.com/docs/zh-CN/plugin-evals.md#runs-ended-on-an-api-error)的运行，或[在 CI 中运行 evals](https://code.claude.com/docs/zh-CN/plugin-evals.md#run-evals-in-ci) 下列出的其他原因 |497| `1` | 存在失败的用例、加载错误、不受信任的插件目录、[因 API 错误结束](https://code.claude.com/docs/zh-CN/plugin-evals.md#runs-ended-on-an-api-error)的运行，或[在 CI 中运行 eval](https://code.claude.com/docs/zh-CN/plugin-evals.md#run-evals-in-ci) 下列出的其他原因 |
498| `2` | 部分运行 |498| `2` | 部分运行 |
499| `130` | 被中断 |499| `130` | 被中断 |
500| `143` | 被终止 |500| `143` | 被终止 |
507claude plugin eval init [name] [options]507claude plugin eval init [name] [options]
508```508```
509 509
510请从插件的根文件夹运行该命令，即包含 `.claude-plugin/plugin.json` 或 skill 的 `SKILL.md` 的目录。如需有意在其他目录中搭建套件，请传递 `--eval-dir`。510请从插件的根文件夹运行该命令，即包含 `.claude-plugin/plugin.json` 或 skill 的 `SKILL.md` 的目录。如需有意在其他目录中创建套件脚手架，请传入 `--eval-dir`。
511 511
512在终端中，该命令会打开一个交互式 Claude Code 会话进行编写访谈。在访谈中，Claude 会执行以下操作：512在终端中，该命令会打开一个交互式 Claude Code 会话进行编写访谈。在访谈中，Claude 会执行以下操作：
513 513
5141. 读取插件5141. 读取插件
5152. 询问您插件应擅长做什么5152. 询问您它应该擅长做什么
5163. 提议案例和评分器5163. 提出用例和评分器
5174. 写入案例文件5174. 编写用例文件
5185. 运行案例并与您一起审查评分，以检查评分器的打分方式是否与您一致5185. 运行用例并与您一起审查评分，以检查评分器的打分方式是否与您一致
519 519
520使用 `--bare` 或没有终端时，该命令改为写入一个空白的单案例模板。当 Claude 从 Claude Code 会话内运行该命令时，命令会打印供该会话遵循的访谈说明，而不是写入模板。520使用 `--bare` 或没有终端时，命令会改为写入一个空白的单用例模板。当 Claude 在 Claude Code 会话内运行该命令时，命令会打印访谈说明供该会话遵循，而不是写入模板。
521 521
522可选的 `name` 是案例名称。使用 `--bare` 或没有终端时必须提供，因为命令会为该案例写入空白模板。案例名称以字母或数字开头，且仅包含字母、数字、`.`、`_` 和 `-`。在所有平台上，命令还会拒绝 Windows 无法存储的名称，例如 `con` 或以 `.` 结尾的名称。522可选的 `name` 是用例名称。使用 `--bare` 或没有终端时它是必需的，因为命令会为该用例写入空白模板。用例名称以字母或数字开头，且仅包含字母、数字、`.`、`_` 和 `-`。在所有平台上，命令还会拒绝 Windows 无法存储的名称，例如 `con` 或以 `.` 结尾的名称。
523 523
524该命令接受以下选项：524该命令接受以下选项：
525 525
526| 选项 | 描述 | 默认值 |526| 选项 | 说明 | 默认值 |
527| :- | :- | :- |527| :- | :- | :- |
528| `--bare` | 为 `<name>` 写入空白的 `prompt.md` 和 `graders/criteria.md`，而不是运行访谈 | |528| `--bare` | 为 `<name>` 写入空白的 `prompt.md` 和 `graders/criteria.md`，而不是运行访谈 | |
529| `-i, --interactive` | 要求进行访谈。没有终端时失败，而不是写入模板 | |529| `-i, --interactive` | 要求进行访谈。没有终端时会失败，而不是写入模板 | |
530| `--eval-dir <dir>` | 当前目录下写入案例的目录 | 清单的 `experimental.evals`，否则为 `evals` |530| `--eval-dir <dir>` | 当前目录下用于写入用例的目录 | 清单中的 `experimental.evals`，否则为 `evals` |
531 531
532### plugin tag532### plugin tag
533 533
534为插件发布创建名为 `<name>--v<version>` 的带注释 git 标签。在打标签之前，命令会检查插件的 `plugin.json` 与列出该插件的任何市场条目在版本上是否一致。534为插件发布创建名为 `<name>--v<version>` 的附注 git 标签。在打标签之前，命令会检查插件的 `plugin.json` 与列出该插件的任何市场条目在版本上是否一致。
535 535
536有关何时为发布打标签，请参阅[发布插件](https://code.claude.com/docs/zh-CN/plugins/publish.md)。536有关何时为发布打标签，请参阅[发布插件](https://code.claude.com/docs/zh-CN/plugins/publish.md)。
537 537
539claude plugin tag [path] [options]539claude plugin tag [path] [options]
540```540```
541 541
542`[path]` 是插件目录，默认为当前目录。命令从该目录向上查找，直到找到列出该插件的 `.claude-plugin/marketplace.json`，以此定位市场条目。542`[path]` 是插件目录，默认为当前目录。命令从该目录向上查找列出该插件的 `.claude-plugin/marketplace.json`，以找到市场条目。
543 543
544| 标志 | 描述 |544| 标志 | 说明 |
545| :- | :- |545| :- | :- |
546| `--push` | 创建标签后将其推送到 `--remote` |546| `--push` | 创建标签后将其推送到 `--remote` |
547| `--dry-run` | 打印将要打的标签，但不创建标签 |547| `--dry-run` | 打印将要打的标签，但不创建标签 |
548| `-f, --force` | 跳过工作树不干净和标签已存在的检查 |548| `-f, --force` | 跳过工作树不干净和标签已存在的检查 |
549| `-m, --message <msg>` | 标签注释消息。`%s` 代表版本。默认为 `<name> <version>` |549| `-m, --message <msg>` | 标签附注消息。`%s` 代表版本。默认为 `<name> <version>` |
550| `--remote <name>` | 使用 `--push` 时推送到的远程。默认为 `origin` |550| `--remote <name>` | 使用 `--push` 时推送到的远程。默认为 `origin` |
551 551
552预览市场检出中某个插件的标签：552在市场检出中预览插件的标签：
553 553
554```bash theme={null}554```bash theme={null}
555claude plugin tag plugins/formatter --dry-run555claude plugin tag plugins/formatter --dry-run
556```556```
557 557
558Claude Code 打印计划：558Claude Code 会打印计划：
559 559
560* 插件名称560* 插件名称
561* 版本及其来源文件561* 版本及其来源文件
563* 标签名称563* 标签名称
564* 它将运行的 `git tag` 和 `git push` 命令564* 它将运行的 `git tag` 和 `git push` 命令
565 565
566不使用 `--dry-run` 时，Claude Code 打印 `Created tag formatter--v1.0.0`，并打印 `Pushed to origin` 或需要您自己运行的推送命令。如果推送失败，标签仍会在本地创建，命令以错误退出。566不使用 `--dry-run` 时，Claude Code 会打印 `Created tag formatter--v1.0.0`，以及 `Pushed to origin` 或需要您自行运行的推送命令。如果推送失败，标签仍会在本地创建，命令会以错误退出。
567 567
568当无法安全打标签时，命令以 `1` 退出并打印原因。常见原因如下：568当无法安全地打标签时，命令会以 `1` 退出并打印原因。常见原因有：
569 569
570* `plugin.json` 或市场条目中没有 `version`570* `plugin.json` 或市场条目中没有 `version`
571* 标签已存在571* 标签已存在
573 573
574### plugin test574### plugin test
575 575
576运行 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 的测试，mod 是通过代码注册事件处理程序的插件。该命令无需会话、登录或网络。有关如何编写测试，请参阅[测试 mod](https://code.claude.com/docs/zh-CN/plugins/mods/test.md)。576运行 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md)（即其代码会注册事件处理程序的插件）的测试。该命令不需要会话、登录或网络。有关如何编写测试，请参阅[测试 mod](https://code.claude.com/docs/zh-CN/plugins/mods/test.md)。
577 577
578```bash theme={null}578```bash theme={null}
579claude plugin test [directory]579claude plugin test [directory]
580```580```
581 581
582`[directory]` 是 mod 的目录，默认为当前目录。该命令会运行其下所有名称以 `.test.ts` 或 `.test.tsx` 结尾的文件，并在有测试失败时以状态 1 退出。582`[directory]` 是 mod 的目录，默认为当前目录。命令会运行其下名称以 `.test.ts` 或 `.test.tsx` 结尾的每个文件，并在测试失败时以状态 1 退出。
583 583
584运行 `./first-mod` 中 mod 的测试：584运行 `./first-mod` 中 mod 的测试：
585 585
589 589
590### plugin validate590### plugin validate
591 591
592验证插件清单、市场清单或目录中的 skill、Agent 和命令，并以 CI 作业可据此操作的退出码退出。有关创建、测试和编辑工作流，请参阅[创建插件](https://code.claude.com/docs/zh-CN/plugins/create.md)。有关验证器在各清单中检查的内容，请参阅[插件清单参考](https://code.claude.com/docs/zh-CN/plugins/manifest-reference.md)和[市场参考](https://code.claude.com/docs/zh-CN/plugins/marketplace-reference.md)。592验证插件清单、市场清单或某个目录中的 skill、Agent 和命令，并以 CI 作业可据以操作的退出码退出。有关创建、测试和编辑工作流，请参阅[创建插件](https://code.claude.com/docs/zh-CN/plugins/create.md)。有关验证器在每种清单中检查的内容，请参阅[插件清单参考](https://code.claude.com/docs/zh-CN/plugins/manifest-reference.md)和[市场参考](https://code.claude.com/docs/zh-CN/plugins/marketplace-reference.md)。
593 593
594```bash theme={null}594```bash theme={null}
595claude plugin validate <path> [options]595claude plugin validate <path> [options]
596```596```
597 597
598| 标志 | 描述 |598| 标志 | 说明 |
599| :- | :- |599| :- | :- |
600| `--strict` | 将警告视为错误，使运行时可容忍的未识别字段和缺失元数据导致运行失败 |600| `--strict` | 将警告视为错误，使运行时可容忍的无法识别字段和缺失元数据导致运行失败 |
601| `--json` | 将验证报告输出为一个 JSON 对象，退出码相同。需要 Claude Code v2.1.259 或更高版本 |601| `--json` | 将验证报告输出为一个 JSON 对象，退出码相同。需要 Claude Code v2.1.259 或更高版本 |
602 602
603在提交前验证插件：603在提交前验证插件：
608 608
609#### 验证目录609#### 验证目录
610 610
611`<path>` 是清单文件或目录。给定目录时，Claude Code 根据在其中找到的内容选择要验证的对象：611`<path>` 是一个[清单文件](#validate-a-manifest-file)或目录。给定目录时，Claude Code 根据在其中找到的内容决定要验证什么：
612 612
613* `.claude-plugin/marketplace.json`（如果存在）613* `.claude-plugin/marketplace.json`（如果存在）
614* 否则为 `.claude-plugin/plugin.json`614* 否则为 `.claude-plugin/plugin.json`
619 619
620当目录同时包含 `.claude-plugin/marketplace.json` 和 `.claude-plugin/plugin.json` 时，Claude Code 会验证市场，同时也验证插件的清单和组件文件。这需要 Claude Code v2.1.289 或更高版本。620当目录同时包含 `.claude-plugin/marketplace.json` 和 `.claude-plugin/plugin.json` 时，Claude Code 会验证市场，同时也验证插件的清单和组件文件。这需要 Claude Code v2.1.289 或更高版本。
621 621
622Claude Code 不会跟随您指定的目录内的符号链接。其行为取决于链接所在的位置：622Claude Code 不会跟随您所指定目录内的符号链接。其行为取决于链接所在的位置：
623 623
624* **插件或 `.claude` 根目录下作为链接的 `skills`、`agents` 或 `commands` 目录**：Claude Code 会警告其中的任何内容都未被读取。624* **插件或 `.claude` 根目录下的 `skills`、`agents` 或 `commands` 目录是链接**：Claude Code 会警告其中的任何内容都未被读取。
625* **`skills`、`agents` 或 `commands` 目录内的链接条目**：Claude Code 会跳过它，并按目录警告跳过了多少会话本会加载的条目。625* **`skills`、`agents` 或 `commands` 目录内的某个条目是链接**：Claude Code 会跳过它，并按目录警告跳过了多少个会话本会加载的条目。
626* **您指定的 `skills`、`agents` 或 `commands` 目录本身是符号链接，或其父级 `.claude` 目录是符号链接**：Claude Code 报告错误，不检查其中的任何内容。请改为指定真实目录。626* **您指定的 `skills`、`agents` 或 `commands` 目录本身是符号链接，或其父目录 `.claude` 是符号链接**：Claude Code 会报告错误，且不检查其中任何内容。请改为指定真实目录。
627 627
628有少数文件不会被验证运行读取：628验证运行不会读取以下几类文件：
629 629
630* **插件根目录下的 `SKILL.md`**：针对插件目录运行 `claude plugin validate` 时，Claude Code 不会检查插件根目录下的 `SKILL.md`630* **插件根目录下的 `SKILL.md`**：当您针对插件目录运行 `claude plugin validate` 时，Claude Code 不会检查插件根目录下的 `SKILL.md`
631* **插件根目录下的 `CLAUDE.md`**：在插件运行中，Claude Code 还会对插件根目录下的 `CLAUDE.md` 发出警告631* **插件根目录下的 `CLAUDE.md`**：在插件运行中，Claude Code 还会对插件根目录下的 `CLAUDE.md` 发出警告
632* **市场运行中的插件文件**：从市场目录运行时，Claude Code 不会打开市场在其他目录中列出的插件的 skill、Agent、命令或 hook 文件，也不会打开它们捆绑的 MCP 服务器文件。要查找这些文件中的错误，请分别验证每个插件目录632* **市场运行中的插件文件**：从市场目录运行时，Claude Code 不会打开该市场在其他目录中列出的插件的 skill、Agent、命令或 hook 文件，也不会打开它们捆绑的 MCP 服务器文件。要查找这些文件中的错误，请逐一验证每个插件目录
633
634#### 验证清单文件
635
636当文件既不名为 `plugin.json` 或 `marketplace.json`，也不在 `.claude-plugin` 目录中时，Claude Code 会根据其字段判断它是什么。在以下情况下，它会将文件作为市场进行验证，否则作为插件清单进行验证：
637
638* `plugins` 是一个数组
639* `plugins` 和 `owner` 同时存在
640* 文件具有仅 `marketplace.json` 定义的字段（例如 `owner`），且没有仅 `plugin.json` 定义的字段（例如 `author`）
641
642要自行选择检查类型，请将文件命名为 `plugin.json` 或 `marketplace.json`。Claude Code 会将 `.claude-plugin` 目录中的任何其他文件作为插件清单进行验证。
633 643
634#### 输出和退出码644#### 输出和退出码
635 645
636Claude Code 打印所验证的文件、所有错误和警告及其路径，以及一行结论。退出码与结论一致：646Claude Code 会打印其验证的文件、带有路径的所有错误和警告，以及一行结论。退出码与结论一致：
637 647
638| 退出码 | 结论行 | 含义 |648| 退出码 | 结论行 | 含义 |
639| :- | :- | :- |649| :- | :- | :- |
640| `0` | `Validation passed` 或 `Validation passed with warnings` | 清单可以加载。使用 `--strict` 时，也没有警告 |650| `0` | `Validation passed` 或 `Validation passed with warnings` | 清单可以加载。使用 `--strict` 时，也没有警告 |
641| `1` | `Validation failed` 或 `Validation failed (--strict treats warnings as errors)` | 存在错误，或在 `--strict` 下存在警告。无论是否使用 `--strict`，[建议](#advice-on-the-readme)都不计入 |651| `1` | `Validation failed` 或 `Validation failed (--strict treats warnings as errors)` | 存在错误，或在 `--strict` 下存在警告。无论是否使用 `--strict`，[建议](#advice-on-the-readme)都不计入 |
642| `2` | `Unexpected error during validation: <reason>` | 验证器本身失败，例如遇到不可读的路径 |652| `2` | `Unexpected error during validation: <reason>` | 验证器本身失败，例如遇到无法读取的路径 |
643 653
644使用 `--json` 时，Claude Code 将报告作为一个 JSON 对象写入 stdout，包含以下顶级字段：654使用 `--json` 时，Claude Code 会将报告以一个 JSON 对象写入 stdout，包含以下顶层字段：
645 655
646* `success`：与退出码相同的结论656* `success`：与退出码相同的结论
647* `strict`：运行是否将警告视为错误657* `strict`：本次运行是否将警告视为错误
648* `target`：Claude Code 验证的解析后路径658* `target`：Claude Code 验证的已解析路径
649* `manifest`：清单自身的结果，对于没有清单的运行为 `null`659* `manifest`：清单自身的结果，对于没有清单的运行为 `null`
650* `contents`：每个文件的结果，各自指明其 `file`，并携带 `errors`、`warnings` 和 `notes` 数组。没有错误、警告或说明的文件不会有条目，因此没有可报告的内容时 `contents` 为空。对于[同时包含 `marketplace.json` 和 `plugin.json` 的目录](#validate-a-directory)，`manifest` 为 `marketplace.json` 的结果，`plugin.json` 的结果放在 `contents` 中660* `contents`：按文件的结果，每项指明其 `file`，并带有 `errors`、`warnings` 和 `notes` 数组。没有错误、警告或说明的文件没有条目，因此当没有可报告的内容时 `contents` 为空。对于[同时含有 `marketplace.json` 和 `plugin.json` 的目录](#validate-a-directory)，`manifest` 是 `marketplace.json` 的结果，`plugin.json` 的结果放在 `contents` 中
651 * `gatingHooks`：每个可以拒绝操作的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) hook（例如 `tool.call` hook）是否具有 [`.catch` 处理程序](https://code.claude.com/docs/zh-CN/plugins/mods/events#handle-a-hook-that-fails)。每一项给出 `module`、`pattern`、`hook` 和 `hasCatch`。需要 Claude Code v2.1.290 或更高版本661 * `gatingHooks`：每个可以拒绝操作的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) hook（例如 `tool.call` hook）是否具有 [`.catch` 处理程序](https://code.claude.com/docs/zh-CN/plugins/mods/events#handle-a-hook-that-fails)。每项给出 `module`、`pattern`、`hook` 和 `hasCatch`。需要 Claude Code v2.1.290 或更高版本
652* `advice`：本次运行给出的[建议](#advice-on-the-readme)，每个条目以 `file` 指明 README，并携带 `message` 以及要粘贴的 `installLine`。没有建议时为空。需要 Claude Code v2.1.295 或更高版本662* `advice`：本次运行的[建议](#advice-on-the-readme)，每个条目以 `file` 指明 README，并带有 `message` 和可粘贴的 `installLine`。没有建议时为空。需要 Claude Code v2.1.295 或更高版本
653 663
654以 `2` 退出时，命令不向 stdout 写入任何内容。错误消息输出到 stderr。664以 `2` 退出时，命令不会向 stdout 写入任何内容。错误消息输出到 stderr。
655 665
656#### 关于 README 的建议666#### 关于 README 的建议
657 667
658`claude plugin validate` 输出中的 `Advice` 块表示某个插件的 README 中没有从市场安装该插件的行，并为您提供一行可添加的内容。建议既不是错误也不是警告。无论是否使用 `--strict`，它都不会改变结论行或退出码。它需要 Claude Code v2.1.295 或更高版本。668`claude plugin validate` 输出中的 `Advice` 块表示插件的 README 中没有从市场安装该插件的行，并会给出一行供您添加。建议既不是错误也不是警告。无论是否使用 `--strict`，它都不会改变结论行或退出码。它需要 Claude Code v2.1.295 或更高版本。
659 669
660例如，验证 `acme-tools` 市场的目录时，会为其 `deploy-helper` 插件打印以下建议：670例如，验证 `acme-tools` 市场的目录时，会为其 `deploy-helper` 插件打印以下建议：
661 671
670✔ Validation passed680✔ Validation passed
671```681```
672 682
673要清除该建议，请将建议的行粘贴到其指出的 README 中，然后在 shell 中再次运行 `claude plugin validate`。`Advice` 块将消失。683要清除该建议，请将建议的行粘贴到其指出的 README 中，然后在 shell 中再次运行 `claude plugin validate`。`Advice` 块就会消失。
674 684
675如果建议的行包含占位符 `<owner>/<repo>`，原样粘贴不会清除该建议。请先获取真实来源：685如果建议的行包含占位符 `<owner>/<repo>`，原样粘贴不会清除该建议。请先获取真实来源：
676 686
677* **您验证的是插件自身的目录**：当市场从其自身内部的某个目录列出该插件时，请改为验证该市场的目录。当市场从其他位置（例如 GitHub 仓库）列出该插件时，请自行填写 `<owner>/<repo>`687* **您验证的是插件自身的目录**：当市场从其自身目录内的某个目录列出该插件时，请改为验证市场自身目录内的那个目录。当市场从其他位置（例如 GitHub 仓库）列出该插件时，请自行填写 `<owner>/<repo>`
678* **您验证的是市场的目录**：Claude Code 会根据该目录顶层 `.git` 目录的 `origin` 远程填写来源。当无法使用该远程时（例如不存在远程），请自行将 `<owner>/<repo>` 替换为您市场的来源688* **您验证的是市场的目录**：Claude Code 会根据该目录顶层 `.git` 目录的 `origin` 远程填写来源。当它无法使用该远程时（例如不存在远程），请自行将 `<owner>/<repo>` 替换为您市场的来源
679 689
680当 `plugin install` 或其简写形式 `plugin i` 在同一行后接以下任一内容时，您已编写的安装行会被计入。`/plugin` 和 `claude plugin` 两种写法都计入：690当您已写的安装行中，`plugin install` 或其简写 `plugin i` 在同一行后跟以下任一内容时，该行即被计入。`/plugin` 和 `claude plugin` 两种写法均可：
681 691
682* `<plugin>@<marketplace>`，例如 `/plugin install deploy-helper@acme-tools`692* `<plugin>@<marketplace>`，例如 `/plugin install deploy-helper@acme-tools`
683* 插件名称和 `--marketplace <source>`，例如 `/plugin install deploy-helper --marketplace acme/tools`693* 插件名称加 `--marketplace <source>`，例如 `/plugin install deploy-helper --marketplace acme/tools`
684 694
685## claude plugin marketplace 命令695## claude plugin marketplace 命令
686 696
