Documentation 2026-10-08 22:58 UTC to 2026-10-09 00:01 UTC

146| `auto` | 模型分类批准 | 模型分类器审查 shell 命令和网络请求等操作，允许或阻止它审查的每一个操作。有关可用性和决策顺序，请参阅[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) |146| `auto` | 模型分类批准 | 模型分类器审查 shell 命令和网络请求等操作，允许或阻止它审查的每一个操作。有关可用性和决策顺序，请参阅[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) |

147 147 

148<Warning>148<Warning>

149 **子代理继承：** 子代理在父会话的权限模式下运行，除非您在其[`AgentDefinition`](/docs/zh-CN/agent-sdk/typescript#agentdefinition)上设置 `permissionMode`，且父会话处于 `default`、`dontAsk` 或 `plan` 模式。即使这样，Claude Code 也永远不会应用 `"bypassPermissions"` 值。子代理仅在父会话本身处于 `bypassPermissions` 模式时才在该模式下运行。 `bypassPermissions` 异常需要 Claude Code v2.1.267 或更高版本。149 **子代理继承：** 子代理在父会话的权限模式下运行，除非您在其[`AgentDefinition`](/docs/zh-CN/agent-sdk/typescript#agentdefinition)上设置 `permissionMode`，且父会话处于 `default`、`dontAsk` 或 `plan` 模式。即使这样，Claude Code 也永远不会应用 `"bypassPermissions"` 值，并且仅当该子代理[可以使用自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)时才会应用 `"auto"` 值。子代理仅在父会话本身处于 `bypassPermissions` 模式时才在该模式下运行。 `bypassPermissions` 异常需要 Claude Code v2.1.267 或更高版本。

150 150 

151 子代理可能具有不同的系统提示和比主代理更少受限的行为，因此继承 `bypassPermissions` 会授予它们完整的自主系统访问权限。[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)仍然适用。151 子代理可能具有不同的系统提示和比主代理更少受限的行为，因此继承 `bypassPermissions` 会授予它们完整的自主系统访问权限。[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)仍然适用。

152</Warning>152</Warning>

323 检测子代理调用323 检测子代理调用

324</h2>324</h2>

325 325 

326Claude 通过 Agent 工具调用子代理。要检测何时调用子代理，请检查 `tool_use` 块，其中 `name` 为 `"Agent"`。来自子代理上下文内的消息包含 `parent_tool_use_id` 字段。326Claude 通过 Agent 工具调用子代理。要检测何时调用子代理，请检查 `tool_use` 块，其中 `name` 为 `"Agent"`。

327 

328来自子代理上下文内的消息包含 `parent_tool_use_id` 字段。在 TypeScript 中，子代理生成的每条 assistant 消息和 user 消息还带有 [`agent_id`](/docs/zh-CN/agent-sdk/typescript#sdkassistantmessage)：即该子代理的[任务事件](/docs/zh-CN/agent-sdk/typescript#sdktaskstartedmessage)中的 `task_id`。`agent_id` 需要 TypeScript Agent SDK v0.3.292 或更高版本。

327 329 

328<Note>330<Note>

329 该工具在 `tool_use` 块中显示为 `"Agent"`，但在 `system:init` 工具列表中显示为 `"Task"`。在 Claude Code v2.1.63 之前，`tool_use` 块也将其命名为 `"Task"`。为了保持检测在不同 SDK 版本中的工作，请在 `block.name` 中匹配两个值。331 该工具在 `tool_use` 块中显示为 `"Agent"`，但在 `system:init` 工具列表中显示为 `"Task"`。在 Claude Code v2.1.63 之前，`tool_use` 块也将其命名为 `"Task"`。为了保持检测在不同 SDK 版本中的工作，请在 `block.name` 中匹配两个值。

331 333 

332消息结构在不同 SDK 中有所不同。在 Python 中，您可以通过 `message.content` 直接访问内容块。在 TypeScript 中，`SDKAssistantMessage` 包装 Claude API 消息，因此您通过 `message.message.content` 访问内容。334消息结构在不同 SDK 中有所不同。在 Python 中，您可以通过 `message.content` 直接访问内容块。在 TypeScript 中，`SDKAssistantMessage` 包装 Claude API 消息，因此您通过 `message.message.content` 访问内容。

333 335 

334此示例遍历流式消息，记录何时调用子代理以及后续消息来自该子代理执行上下文内的时间。336此示例遍历流式消息，记录何时调用子代理以及后续消息来自该子代理执行上下文内的时间。TypeScript 版本还会为每条带有 `agent_id` 的子代理消息记录该 `agent_id`。

335 337 

336<CodeGroup>338<CodeGroup>

337 ```python Python theme={null}339 ```python Python theme={null}

403 // Check if this message is from within a subagent's context405 // Check if this message is from within a subagent's context

404 if (msg.parent_tool_use_id) {406 if (msg.parent_tool_use_id) {

405 console.log(" (running inside subagent)");407 console.log(" (running inside subagent)");

408 // On assistant and user messages, agent_id matches the task_id

409 // on that subagent's task_started and other task events

410 if (msg.agent_id) {

411 console.log(` agent_id: ${msg.agent_id}`);

412 }

406 }413 }

407 414 

408 if ("result" in message) {415 if ("result" in message) {

1561 parent_tool_use_id: string | null;1561 parent_tool_use_id: string | null;

1562 error?: SDKAssistantMessageError;1562 error?: SDKAssistantMessageError;

1563 aborted?: true;1563 aborted?: true;

1564 agent_id?: string;

1564 timestamp?: string;1565 timestamp?: string;

1565 context_usage?: SDKContextUsage;1566 context_usage?: SDKContextUsage;

1566 user_message_uuid?: string;1567 user_message_uuid?: string;

1580 1581 

1581当中断或中止在流完成前截断助手消息时，`aborted` 为 `true`：消息没有 `stop_reason`，内容可能在单词中间结束。该字段在正常完成的消息上不存在。它需要 Agent SDK v0.3.214 或更高版本。1582当中断或中止在流完成前截断助手消息时，`aborted` 为 `true`：消息没有 `stop_reason`，内容可能在单词中间结束。该字段在正常完成的消息上不存在。它需要 Agent SDK v0.3.214 或更高版本。

1582 1583 

1584`agent_id` 标识生成该消息的子代理，主线程消息中不包含此字段。其值等于该子代理的 [`task_started`](#sdktaskstartedmessage) 及其他任务事件上的 `task_id`，并且在子代理被[恢复](/docs/zh-CN/agent-sdk/subagents#resume-subagents)时保持不变。该字段需要 Agent SDK v0.3.292 或更高版本。

1585 

1586请通过 `agent_id` 将子代理的消息与其任务事件进行匹配，而不是将消息的 `parent_tool_use_id` 与任务事件的 `tool_use_id` 配对。当某个工具调用恢复子代理时，任务事件携带的是该调用的 `tool_use_id`，而消息保留的是最初启动该子代理的工具调用的 `parent_tool_use_id`，因此两者不再匹配。

1587 

1583Claude Code 在该轮的第一条助手消息上设置 `user_message_uuid` 和 `user_message_uuids`，条件在 [`user_message_uuid`](#user_message_uuid) 中。当 Claude Code 重新运行被重启中断的轮时，重新运行的携带这些字段的助手消息也携带 [`resume_reason`](#resume_reason)。1588Claude Code 在该轮的第一条助手消息上设置 `user_message_uuid` 和 `user_message_uuids`，条件在 [`user_message_uuid`](#user_message_uuid) 中。当 Claude Code 重新运行被重启中断的轮时，重新运行的携带这些字段的助手消息也携带 [`resume_reason`](#resume_reason)。

1584 1589 

1585`timestamp` 是消息内容在生成它的进程上完成生成的 ISO 8601 时间。该值来自该机器的时钟，因此仅用于显示，不要按它排序消息。一个 API 轮可以产生多条共享 `message.id` 的助手消息，每条都有自己的 `timestamp`。当字段不存在时，回退到您收到消息的时间。1590`timestamp` 是消息内容在生成它的进程上完成生成的 ISO 8601 时间。该值来自该机器的时钟，因此仅用于显示，不要按它排序消息。一个 API 轮可以产生多条共享 `message.id` 的助手消息，每条都有自己的 `timestamp`。当字段不存在时，回退到您收到消息的时间。

1597 type: "user";1602 type: "user";

1598 uuid?: UUID;1603 uuid?: UUID;

1599 session_id?: string;1604 session_id?: string;

1605 agent_id?: string;

1600 message: MessageParam; // From Anthropic SDK1606 message: MessageParam; // From Anthropic SDK

1601 pasted_content?: MessageParam["content"][];1607 pasted_content?: MessageParam["content"][];

1602 parent_tool_use_id: string | null;1608 parent_tool_use_id: string | null;

1636};1642};

1637```1643```

1638 1644 

1645由子代理生成的用户消息（例如其自身某个工具调用的 `tool_result`）会携带 `agent_id`。请参阅 [`SDKAssistantMessage`](#sdkassistantmessage)，其中定义了该字段及其版本要求。

1646 

1639在携带 `tool_result` 块的消息上，`tool_use_result` 是工具的结构化输出对象，而不是发送给模型的文本。其结构取决于对应 `tool_use` 块所指定的工具，因此该字段的类型为 `unknown`；内置结构列在[工具输出类型](#tool-output-types)下。以下结果需要超出其所列结构的额外处理：1647在携带 `tool_result` 块的消息上，`tool_use_result` 是工具的结构化输出对象，而不是发送给模型的文本。其结构取决于对应 `tool_use` 块所指定的工具，因此该字段的类型为 `unknown`；内置结构列在[工具输出类型](#tool-output-types)下。以下结果需要超出其所列结构的额外处理：

1640 1648 

1641* `Agent` 工具：`tool_use_result` 为 [`AgentOutput`](#agent-2)。请据此进行渲染，而不是解析 `tool_result` 文本。`completed` 结果的 `content` 包含子代理的报告；对于通过 `SubagentHandback` 工具调用提交报告的子代理，则包含一条关于该交接的简短说明来代替报告。在 Claude Code v2.1.271 或更高版本的[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)下，每个产生 `completed` 结果的子代理都以这种方式报告（[fork](/docs/zh-CN/sub-agents#fork-the-current-conversation) 除外），Claude 会以来自子代理的单独消息接收报告。1649* `Agent` 工具：`tool_use_result` 为 [`AgentOutput`](#agent-2)。请据此进行渲染，而不是解析 `tool_result` 文本。`completed` 结果的 `content` 包含子代理的报告；对于通过 `SubagentHandback` 工具调用提交报告的子代理，则包含一条关于该交接的简短说明来代替报告。在 Claude Code v2.1.271 或更高版本的[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)下，每个产生 `completed` 结果的子代理都以这种方式报告（[fork](/docs/zh-CN/sub-agents#fork-the-current-conversation) 除外），Claude 会以来自子代理的单独消息接收报告。

1992 `SDKPartialAssistantMessage`2000 `SDKPartialAssistantMessage`

1993</h3>2001</h3>

1994 2002 

1995流式部分消息（仅当 `includePartialMessages` 为 true 时）。`parent_tool_use_id` 字段始终为 `null`：流事件仅为主会话发出。对于子代理归因，使用完整消息，它们携带 `parent_tool_use_id`，或启用 [`forwardSubagentText`](#options) 以接收子代理文本和思考作为完整消息。2003流式部分消息（仅当 `includePartialMessages` 为 true 时）。

2004 

2005`parent_tool_use_id` 字段始终为 `null`：流事件仅针对主会话发出。要进行子代理归属，请使用完整消息（它们携带 [`agent_id`](#sdkassistantmessage) 和 `parent_tool_use_id`），或启用 [`forwardSubagentText`](#options) 以完整消息的形式接收子代理的文本和思考内容。

1996 2006 

1997```typescript theme={null}2007```typescript theme={null}

1998type SDKPartialAssistantMessage = {2008type SDKPartialAssistantMessage = {

5775 task_type?: string;5785 task_type?: string;

5776 is_backgrounded?: boolean;5786 is_backgrounded?: boolean;

5777 spawn_depth?: number;5787 spawn_depth?: number;

5788 parent_task_id?: string;

5778 ambient?: boolean;5789 ambient?: boolean;

5779 uuid: UUID;5790 uuid: UUID;

5780 session_id: string;5791 session_id: string;

5792 5803 

5793[恢复的子代理](/docs/zh-CN/agent-sdk/subagents#resume-subagents)始终报告 `is_backgrounded: true`，因为 Claude Code 会在后台运行每个恢复的子代理。当前台任务稍后移到后台时，Claude Code 会在 [`task_updated`](#sdktaskupdatedmessage) 消息中报告新的 `is_backgrounded` 值，而不是发送第二条 `task_started`。5804[恢复的子代理](/docs/zh-CN/agent-sdk/subagents#resume-subagents)始终报告 `is_backgrounded: true`，因为 Claude Code 会在后台运行每个恢复的子代理。当前台任务稍后移到后台时，Claude Code 会在 [`task_updated`](#sdktaskupdatedmessage) 消息中报告新的 `is_backgrounded` 值，而不是发送第二条 `task_started`。

5794 5805 

5806`parent_task_id` 保存启动此任务的子代理的 `task_id`。使用它将每个任务归组到启动它的子代理之下。Claude Code 会在子代理、Bash 和 [Monitor](#monitor) 任务上设置它。该字段需要 Agent SDK v0.3.292 或更高版本。在以下情况下该字段不存在：

5807 

5808* 任务由主线程启动

5809* Claude Code 不再跟踪父任务

5810* 任务由 [teammate](/docs/zh-CN/agent-teams) 或工作流中的 Agent 启动

5811 

5812父任务可能是前台任务，也可能是已经结束的任务，因此请将无法识别的 ID 视为没有父任务。

5813 

5795<h3 id="sdktaskprogressmessage">5814<h3 id="sdktaskprogressmessage">

5796 `SDKTaskProgressMessage`5815 `SDKTaskProgressMessage`

5797</h3>5816</h3>

5848 `SDKBackgroundTasksChangedMessage`5867 `SDKBackgroundTasksChangedMessage`

5849</h3>5868</h3>

5850 5869 

5851每当活动后台任务集合发生变化时发出：任务启动、完成、被终止、前台 Agent 被移到后台，或任务的 `description` 或 `ambient` 字段发生变化。5870每当活动后台任务集合发生变化时发出：任务启动、完成、被终止、前台 Agent 被移到后台，或任务的 `description`、`ambient` 或 `parent_task_id` 字段发生变化。有关每个条目上的 `parent_task_id` 字段，请参阅 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，其中定义了该字段及其版本要求。

5852 5871 

5853`tasks` 数组是完整的活动集合。请用每次的负载替换任何缓存的集合，而不是对 `task_started` 和 `task_notification` 事件进行配对，这样下一次成员变化就会纠正您错过的任何事件。5872`tasks` 数组是完整的活动集合。请用每次的负载替换任何缓存的集合，而不是对 `task_started` 和 `task_notification` 事件进行配对，这样下一次成员变化就会纠正您错过的任何事件。

5854 5873 

5855相对于这些逐任务事件的顺序是未指定的，因此不要将这两个流相互关联。5874当任务结束时，其 [`task_updated`](#sdktaskupdatedmessage) 和 [`task_notification`](#sdktasknotificationmessage) 会先于将其从列表中移除的 `background_tasks_changed` 到达。除此之外，相对于这些逐任务事件的顺序是未指定的。

5856 5875 

5857启动时不会发出任何内容。每当会话的 CLI 进程启动或重启时，请重置为空集合，并由下一次成员变化重新填充。5876启动时不会发出任何内容。每当会话的 CLI 进程启动或重启时，请重置为空集合，并由下一次成员变化重新填充。

5858 5877 

5869 task_type: string;5888 task_type: string;

5870 subagent_type?: string;5889 subagent_type?: string;

5871 description: string;5890 description: string;

5891 parent_task_id?: string;

5872 ambient?: boolean;5892 ambient?: boolean;

5873 }[];5893 }[];

5874 uuid: UUID;5894 uuid: UUID;

4064 Marketplace 已从不同的来源添加4064 Marketplace 已从不同的来源添加

4065</h3>4065</h3>

4066 4066 

4067您通过[`/plugin install <plugin> --marketplace <source>`](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command)确认添加了 marketplace，Claude Code 从该来源获取的目录将自己命名为与您已从不同来源添加的 marketplace 相同。Claude Code 保留现有的 marketplace 而不是替换它，插件未安装。4067您在会话中或从 shell 中，通过[安装命令上的`--marketplace <source>`](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command)指定了一个新的市场来源。Claude Code 从该来源获取的目录与您已从不同来源添加的市场同名。Claude Code 保留现有的市场而不是替换它，插件未安装。

4068 4068 

4069```text theme={null}4069```text theme={null}

4070Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.4070Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

1237 SessionStart 决策控制1237 SessionStart 决策控制

1238</h4>1238</h4>

1239 1239 

1240Claude Code 会将其[视为纯文本](#exit-code-0)的 stdout 添加到 Claude 的上下文中。除所有 hook 都可用的 [JSON 输出字段](#json-output)外，您还可以返回以下事件专属字段：1240SessionStart hook 可以为 Claude 添加上下文、提供第一条用户消息、设置会话标题、监视文件以及重新加载 skill。除所有 hook 都可用的 [JSON 输出字段](#json-output)外，为每项功能返回相应字段：

1241 1241 

1242| 字段 | 描述 |1242| 字段 | 描述 |

1243| :- | :- |1243| :- | :- |

1244| `additionalContext` | 在对话开始时、第一个提示词之前添加到 Claude 上下文中的字符串。关于文本的传递方式以及应放入的内容，请参阅[为 Claude 添加上下文](#add-context-for-claude) |1244| `additionalContext` | 在对话开始时、第一个提示词之前添加到 Claude 上下文中的字符串。关于文本的传递方式以及应放入的内容，请参阅[为 Claude 添加上下文](#add-context-for-claude) |

1245| `initialUserMessage` | 用作会话第一条用户消息的字符串。适用于使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)，此时即使未提供提示词，它也会成为第一个轮次。如果提供了提示词，该提示词将作为下一个轮次跟随其后。与附加到现有轮次的 `additionalContext` 不同，此字段会创建轮次 |1245| `initialUserMessage` | 在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)下，用作会话第一条用户消息的字符串。即使您未传入提示词，它也会成为第一轮。您传入的提示词会作为下一轮紧随其后 |

1246| `sessionTitle` | 设置会话标题，效果与 `/rename` 相同。可用于根据启动文件夹、git 分支或 worktree 名称自动命名会话。当 `source` 为 `"startup"`、`"resume"` 或 `"fork"` 时生效；在 `"clear"` 和 `"compact"` 时被忽略 |1246| `sessionTitle` | 设置会话标题，效果与 `/rename` 相同。在 `source` 为 `"startup"`、`"resume"` 或 `"fork"` 时生效 |

1247| `watchPaths` | 在此会话期间监视 [FileChanged](#filechanged) 事件的绝对路径数组 |1247| `watchPaths` | 在此会话期间监视 [FileChanged](#filechanged) 事件的绝对路径数组 |

1248| `reloadSkills` | 布尔值。为 `true` 时，Claude Code 会在 SessionStart hook 完成后重新扫描 [skill](/docs/zh-CN/skills) 和命令目录，使 hook 安装的 skill 在同一会话中（从第一个提示词开始）即可使用 |1248| `reloadSkills` | 布尔值。为 `true` 时，Claude Code 会在 SessionStart hook 完成后重新扫描 [skill](/docs/zh-CN/skills) 和命令目录。请参阅[重新加载 hook 安装的 skill](#reload-skills-that-a-hook-installs) |

1249 

1250以下输出添加上下文并为会话命名：

1249 1251 

1250```json theme={null}1252```json theme={null}

1251{1253{

1257}1259}

1258```1260```

1259 1261 

1260由于对于此事件，纯 stdout 已经会传达给 Claude，因此仅加载上下文的 hook 可以直接打印到 stdout，而无需构建 JSON。当您需要将上下文与 `sessionTitle` 等其他字段结合使用时，请使用 JSON 形式。1262仅添加上下文的 hook 可以直接打印内容而无需构建 JSON，因为 Claude Code 会将 SessionStart hook 的[纯文本 stdout](#exit-code-0) 添加到 Claude 的上下文中。

1263 

1264如果您的插件的 SessionStart hook 提供 `initialUserMessage` 或 `sessionTitle`，请在会话开始前安装该插件。对于在 SessionStart hook 运行之后才完成安装的插件，Claude Code 会忽略这两个字段。

1265 

1266<h4 id="reload-skills-that-a-hook-installs">

1267 重新加载 hook 安装的 skill

1268</h4>

1269 

1270要使 SessionStart hook 安装的 skill 在同一会话中可用，请返回 `reloadSkills`。skill 发现通常在 SessionStart hook 完成之前运行，因此如果不这样做，hook 写入 `~/.claude/skills/` 或 `.claude/skills/` 的文件在第一个提示词运行时可能缺失。

1261 1271 

1262当 SessionStart hook 安装或更新 skill 时，请使用 `reloadSkills`。skill 发现通常在 SessionStart hook 完成之前运行，因此 hook 写入 `~/.claude/skills/` 或 `.claude/skills/` 的文件否则只会在下一个会话中出现。此示例同步一个共享的 skill 仓库并请求重新扫描：1272此示例同步共享的 skill 仓库并请求重新扫描：

1263 1273 

1264```bash theme={null}1274```bash theme={null}

1265#!/bin/bash1275#!/bin/bash

1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1280echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

1271```1281```

1272 1282 

1273仓库 URL 只是一个占位符；请将其替换为您自己的 skill 仓库。使用占位符时，clone 会失败并向 stderr 打印一条 `fatal:` 消息。以 0 退出的 SessionStart hook 的 stderr 仅供参考，因此 `reloadSkills` 请求仍然有效。1283仓库 URL 是占位符。请将其替换为您自己的 skill 仓库。

1274 1284 

1275<h4 id="persist-environment-variables">1285<h4 id="persist-environment-variables">

1276 持久化环境变量1286 持久化环境变量

91| `-y, --yes` | 接受显示的安装命令，不出现 `Run this command now?` 提示。在 Claude Code 会话内运行命令时（例如从 Bash 工具或 hook 运行）会被忽略。需要 Claude Code v2.1.229 或更高版本 |91| `-y, --yes` | 接受显示的安装命令，不出现 `Run this command now?` 提示。在 Claude Code 会话内运行命令时（例如从 Bash 工具或 hook 运行）会被忽略。需要 Claude Code v2.1.229 或更高版本 |

92| `--accept-command <sha256>` | 代替 `-y`，接受之前某次 [`--json` 运行](#plugin-json-result)在 `shownCommand` 中报告了其 `sha256` 的显示安装命令。不能与 `-y` 组合使用。请参阅[接受显示的安装命令](#accept-a-displayed-install-command)。需要 Claude Code v2.1.271 或更高版本 |92| `--accept-command <sha256>` | 代替 `-y`，接受之前某次 [`--json` 运行](#plugin-json-result)在 `shownCommand` 中报告了其 `sha256` 的显示安装命令。不能与 `-y` 组合使用。请参阅[接受显示的安装命令](#accept-a-displayed-install-command)。需要 Claude Code v2.1.271 或更高版本 |

93| `--json` | 将结果作为一个 JSON 对象打印在 stdout 的最后一行，而不是人类可读的消息，供脚本使用。请参阅 [JSON 结果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 |93| `--json` | 将结果作为一个 JSON 对象打印在 stdout 的最后一行，而不是人类可读的消息，供脚本使用。请参阅 [JSON 结果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 |

94| `--marketplace <source>` | 从位于 `<source>` 的市场安装以裸名称指定的 `<plugin>`，如果您尚未添加该市场，则先添加它。请参阅[通过一条命令添加市场并安装](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command)。需要 Claude Code v2.1.292 或更高版本 |

94 95 

95在 shell 中运行 `claude plugin install --help`，可查看您的版本支持的所有选项。96在 shell 中运行 `claude plugin install --help`，可查看您的版本支持的所有选项。

96 97 

189 189 

190* **Scope**：默认为用户范围。传递 `--scope project` 或 `--scope local` 以更改它。190* **Scope**：默认为用户范围。传递 `--scope project` 或 `--scope local` 以更改它。

191* **When the plugins load**：它安装的插件在您下次启动 Claude Code 时加载，或当您在已打开的会话中运行 `/reload-plugins` 时加载。191* **When the plugins load**：它安装的插件在您下次启动 Claude Code 时加载，或当您在已打开的会话中运行 `/reload-plugins` 时加载。

192* **The marketplace must be added first**：在没有人打开交互式 Claude Code 会话的机器上，官方市场未注册，因此从它安装的脚本在安装前运行 `claude plugin marketplace add anthropics/claude-plugins-official`。192* **The marketplace on a new machine**：在还没有人打开过交互式 Claude Code 会话的机器上，官方市场未注册，因此从它安装的脚本在安装前运行 `claude plugin marketplace add anthropics/claude-plugins-official`。请参阅[从 shell 添加和安装](#add-and-install-from-your-shell)。

193 193 

194```bash theme={null}194```bash theme={null}

195claude plugin install formatter@your-org --scope project195claude plugin install formatter@your-org --scope project

232 Add a marketplace and install in one command232 Add a marketplace and install in one command

233</h3>233</h3>

234 234 

235要从您尚未添加的市场安装插件，请在 Claude Code 会话中运行 `/plugin install` 并使用 `--marketplace` 命名市场来源。需要 Claude Code v2.1.275 或更高版本。235要从您尚未添加的市场安装插件，请在安装命令中使用 `--marketplace` 命名市场来源，可以在会话中或从 shell 中执行。来源采用 [the same forms as `/plugin marketplace add`](#add-a-marketplace)，例如 GitHub `owner/repo`、git URL 或本地路径。单独给出插件名称，不带 `@marketplace` 后缀。

236 

237<h4 id="add-and-install-in-a-session">

238 Add and install in a session

239</h4>

240 

241在 Claude Code 会话中运行 `/plugin install`，并指定插件和来源。需要 Claude Code v2.1.275 或更高版本。在会话中，来源不能包含空格。

236 242 

237```text theme={null}243```text theme={null}

238/plugin install deploy-helper --marketplace your-org/plugins244/plugin install deploy-helper --marketplace your-org/plugins

239```245```

240 246 

241来源采用 [the same forms as `/plugin marketplace add`](#add-a-marketplace)，例如 GitHub `owner/repo`、git URL 或本地路径，除了它不能包含空格。单独给出插件名称，不带 `@marketplace` 后缀。

242 

243如果您尚未添加该市场，Claude Code 显示它解析的来源并要求您在添加前确认。一旦添加了市场，插件的详细信息打开，您选择 [installation scope](#install-a-plugin)。如果来源与您已添加的市场匹配，Claude Code 跳过确认并在该市场中打开插件的详细信息。247如果您尚未添加该市场，Claude Code 显示它解析的来源并要求您在添加前确认。一旦添加了市场，插件的详细信息打开，您选择 [installation scope](#install-a-plugin)。如果来源与您已添加的市场匹配，Claude Code 跳过确认并在该市场中打开插件的详细信息。

244 248 

249<h4 id="add-and-install-from-your-shell">

250 Add and install from your shell

251</h4>

252 

253在 shell 中，无需启动会话，运行 `claude plugin install` 并指定插件和来源。需要 Claude Code v2.1.292 或更高版本。

254 

255```bash theme={null}

256claude plugin install deploy-helper --marketplace your-org/plugins

257```

258 

259shell 命令添加市场时没有确认步骤。您已从该来源添加的市场会被重用。新市场会经过与 `claude plugin marketplace add` 相同的 [organization policy checks](/docs/zh-CN/plugins/org#restrict-what-users-can-install) 后添加，并且即使您传递 `--scope project`，也会在您的用户设置中声明。

260 

245<h3 id="add-a-private-marketplace">261<h3 id="add-a-private-marketplace">

246 Add a private marketplace262 Add a private marketplace

247</h3>263</h3>

138| `$.mcp.call` | 在连接的 MCP 服务器上调用工具，在会话的权限规则下 |138| `$.mcp.call` | 在连接的 MCP 服务器上调用工具，在会话的权限规则下 |

139| `$.model.complete` | 使用用户的计划或 API 密钥进行模型调用 |139| `$.model.complete` | 使用用户的计划或 API 密钥进行模型调用 |

140| `$.prompt.submit` | 提交提示，可以将其作为用户自己的话语发送 |140| `$.prompt.submit` | 提交提示，可以将其作为用户自己的话语发送 |

141| `$.session.send` | 发送另一个会话或子代理的 Claude 读取的消息 |141| `$.session.send` | 发送另一个会话、子代理或[队友](/docs/zh-CN/agent-teams)的 Claude 读取的消息 |

142 142 

143在 `hooks:` 行中，[`tool.call`](/docs/zh-CN/plugins/mods/reference#tools) 和 [`prompt.submit`](/docs/zh-CN/plugins/mods/reference#prompts-and-what-claude-reads) 意味着 mod 看到每个工具调用和每个提示，并可以更改它们。[`session.append`](/docs/zh-CN/plugins/mods/reference#session) 意味着 mod 可以在存储之前重写对话的每一行。[`ui.render{component=AskUserQuestion}`](/docs/zh-CN/plugins/mods/interface#change-what-claude-code-already-draws) 意味着 mod 可以重新绘制 Claude 用来询问用户问题的对话框。`tool.check` 意味着 mod 可以在权限提示出现之前批准或拒绝工具调用。[了解默认情况下会发生什么](#know-what-happens-by-default)列出了您的哪些规则和 hooks 优先于其答案。143在 `hooks:` 行中，[`tool.call`](/docs/zh-CN/plugins/mods/reference#tools) 和 [`prompt.submit`](/docs/zh-CN/plugins/mods/reference#prompts-and-what-claude-reads) 意味着 mod 看到每个工具调用和每个提示，并可以更改它们。[`session.append`](/docs/zh-CN/plugins/mods/reference#session) 意味着 mod 可以在存储之前重写对话的每一行。[`ui.render{component=AskUserQuestion}`](/docs/zh-CN/plugins/mods/interface#change-what-claude-code-already-draws) 意味着 mod 可以重新绘制 Claude 用来询问用户问题的对话框。`tool.check` 意味着 mod 可以在权限提示出现之前批准或拒绝工具调用。[了解默认情况下会发生什么](#know-what-happens-by-default)列出了您的哪些规则和 hooks 优先于其答案。

144 144 

159 在会话之间发送和接收消息159 在会话之间发送和接收消息

160</h2>160</h2>

161 161 

162mod 可以向您的另一个会话或此会话的子代理之一发送纯文本消息，并观察到达和离开的消息。`$.session.send({ to, text })` 发送一个，与 SendMessage 工具进行相同的传递。`to` 是 `{ sessionId }` 用于会话，`{ agentId }` 用于来自 `$.agent.list()` 的子代理，或接收消息来自的字符串地址。调用在消息排队后解析，带有 `{ isDelivered: true }`。当没有传递任何内容时，它使用 `{ isDelivered: false, reason }` 解析，`reason` 说明原因。162mod 可以向您的另一个会话、此会话的子代理之一或其 [agent team](/docs/zh-CN/agent-teams) 中的队友发送纯文本消息，还可以观察到达和离开的消息。

163 

164要发送消息，请调用 `$.session.send({ to, text })`，它与 SendMessage 工具进行相同的传递。根据消息的接收者设置 `to`：

165 

166* **您的另一个会话**：`{ sessionId }`

167* **子代理或队友**：`{ agentId }`，使用来自 `$.agent.list()` 的 id

168* **您收到的某条消息的发送者**：该消息来源的字符串地址

169 

170调用在消息排队后解析，带有 `{ isDelivered: true }`。当没有传递任何内容时，它使用 `{ isDelivered: false, reason }` 解析，`reason` 说明原因。

163 171 

164此 hook 通过要求您在其后键入的 id 的会话获取状态来回答 `/ping` 命令（[注册为命令](#add-a-command)）：172此 hook 通过要求您在其后键入的 id 的会话获取状态来回答 `/ping` 命令（[注册为命令](#add-a-command)）：

165 173 

281 281 

282`result.usage` 保存 Claude API 为某个请求报告的 token 计数，以及作出回答的 `model`：`input_tokens`、`output_tokens`、`cache_read_input_tokens` 和 `cache_creation_input_tokens`。该 hook 也会针对子代理的请求运行，因此如果您只想处理主对话，请检查 `e.agentId`。282`result.usage` 保存 Claude API 为某个请求报告的 token 计数，以及作出回答的 `model`：`input_tokens`、`output_tokens`、`cache_read_input_tokens` 和 `cache_creation_input_tokens`。该 hook 也会针对子代理的请求运行，因此如果您只想处理主对话，请检查 `e.agentId`。

283 283 

284要查看 API 在请求期间自行运行的工具调用（例如对 [advisor 工具](/docs/zh-CN/advisor)的调用），请读取 `result.serverToolUses`。Claude Code 不会运行这些调用，因此不会为它们触发任何 `tool.call` 或 `tool.check` hook。当响应中没有此类调用时，该字段不存在；该字段需要 Claude Code v2.1.290 或更高版本。

285 

284<h3 id="hook-the-settings-hook-events">286<h3 id="hook-the-settings-hook-events">

285 处理设置 hook 事件287 处理设置 hook 事件

286</h3>288</h3>

209| [`$.ui`](/docs/zh-CN/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、`focus`、`scroll`、`toast`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit` |209| [`$.ui`](/docs/zh-CN/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、`focus`、`scroll`、`toast`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit` |

210| [`$.command`](/docs/zh-CN/plugins/mods/api#add-a-command) | `register`、`run`、`list` |210| [`$.command`](/docs/zh-CN/plugins/mods/api#add-a-command) | `register`、`run`、`list` |

211| [`$.tool`](/docs/zh-CN/plugins/mods/api#add-a-tool) | `register`、`call`、`check`、`list` |211| [`$.tool`](/docs/zh-CN/plugins/mods/api#add-a-tool) | `register`、`call`、`check`、`list` |

212| `$.agent` | `register`、`spawn`、`list` |212| `$.agent` | `register`、`spawn`、`list`。`list()` 返回此会话的子代理和队友，每项都带有 `status`，其值为 `pending`、`running`、`waiting`、`idle`、`completed`、`failed` 或 `killed` 之一，其中 `idle` 和 `waiting` 需要 Claude Code v2.1.289 或更高版本。 |

213| [`$.model`](/docs/zh-CN/plugins/mods/api#call-a-model) | `complete`、`fork`、`classify` |213| [`$.model`](/docs/zh-CN/plugins/mods/api#call-a-model) | `complete`、`fork`、`classify` |

214| [`$.prompt`](/docs/zh-CN/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`、`read`、`fill`、`suggest`、`compose`。Claude 读取来自 `submit({ text })` 的文本时，前面会有一句指明您的 mod 为发送者的话。`submit({ text, asUser: true })` 将文本作为用户自己的话发送，不带那句话。 |214| [`$.prompt`](/docs/zh-CN/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`、`read`、`fill`、`suggest`、`compose`。Claude 读取来自 `submit({ text })` 的文本时，前面会有一句指明您的 mod 为发送者的话。`submit({ text, asUser: true })` 将文本作为用户自己的话发送，不带那句话。 |

215| `$.turn` | `abort` |215| `$.turn` | `abort` |

317| `$.process.run` 超时时间 | 默认 30 秒，最长 10 分钟 |317| `$.process.run` 超时时间 | 默认 30 秒，最长 10 分钟 |

318| `$.model.complete` `maxTokens` | 默认 1024，最多 64,000 或模型的输出上限 |318| `$.model.complete` `maxTokens` | 默认 1024，最多 64,000 或模型的输出上限 |

319| `$.fs.read` 和 `$.fs.write` | 单个文件 4 MiB |319| `$.fs.read` 和 `$.fs.write` | 单个文件 4 MiB |

320| hook 的 `drop` 原因或 `config.set` 的 `deny` 原因 | 4,096 个字符。更长的原因会被截去末尾部分，drop 或 deny 仍然生效。截断需要 Claude Code v2.1.292 或更高版本；在更早的版本中，该 hook 会改为[失败](/docs/zh-CN/plugins/mods/events#handle-a-hook-that-fails)。 |

320| 单个树中的文本 | 仅绘制前 100,000 个字符 |321| 单个树中的文本 | 仅绘制前 100,000 个字符 |

321| `Code` 的 `language` 或 `path`、`Select` 选项的 `value`，或 `Client` 的 `module` | 10,000 个字符。如果其中任何一项超出此长度，Claude Code 会[在该位置绘制其自身的版本](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements)。 |322| `Code` 的 `language` 或 `path`、`Select` 选项的 `value`，或 `Client` 的 `module` | 10,000 个字符。如果其中任何一项超出此长度，Claude Code 会[在该位置绘制其自身的版本](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements)。 |

322| `Link` 的 `href` | 2,048 个字符。更长的 `href` 会导致整个树无法绘制。 |323| `Link` 的 `href` | 2,048 个字符。更长的 `href` 会导致整个树无法绘制。 |

110* `returned neither { value } nor { deny }`：mods API 调用的 stub 返回了一个裸值，这会导致测试失败110* `returned neither { value } nor { deny }`：mods API 调用的 stub 返回了一个裸值，这会导致测试失败

111* `no implementation for` 后跟一个名称：您的 mod 进行了该调用，没有 stub 回答它111* `no implementation for` 后跟一个名称：您的 mod 进行了该调用，没有 stub 回答它

112 112 

113工具包还导出内存中的 mocks，为您回答整个命名空间。`mock.clock(on)` 回答 [`$.clock`](/docs/zh-CN/plugins/mods/api#run-work-in-the-background)，`mock.store(on, { count: 7 })` 从以这些条目开始的存储中回答 `$.store`，`mock.env(on, { CI: 'true' })` 从这些变量中回答 `$.env.get`。`mock.clock` 返回一个您的测试可以推进的 mock 时钟，因此计时器的测试不会等待。`mock.store` 返回 nothing，因此要检查您的 mod 保存了什么，请自己编写两个 `store` stubs，如 [drawing test](#test-a-drawing) 所做的那样。113工具包还导出现成的 mocks，用于时钟、存储、环境变量以及追加到对话中的行：

114 

115* **`mock.clock(on)`**：回答 [`$.clock`](/docs/zh-CN/plugins/mods/api#run-work-in-the-background)，并返回一个您的测试可以推进的 mock 时钟，因此计时器的测试不会等待。

116* **`mock.store(on, { count: 7 })`**：从以这些条目开始的存储中回答 `$.store`。它不返回任何内容，因此要检查您的 mod 保存了什么，请自己编写两个 `store` stubs，如 [drawing test](#test-a-drawing) 所做的那样。

117* **`mock.env(on, { CI: 'true' })`**：从这些变量中回答 `$.env.get`。

118* **`mock.session(on)`**：返回一个 mock 会话，其 `appended()` 方法按从旧到新的顺序列出您的 mod 通过 [`$.session.append`](/docs/zh-CN/plugins/mods/reference#session) 添加的行；需要 Claude Code v2.1.293 或更高版本。

114 119 

115<h3 id="follow-the-test-kit’s-rules">120<h3 id="follow-the-test-kit’s-rules">

116 遵循测试工具包的规则121 遵循测试工具包的规则

168 查看 stub 返回的内容173 查看 stub 返回的内容

169</h3>174</h3>

170 175 

171您的 mod 在测试中进行的每个 mods API 调用都需要一个 stub 来回答，除了工具包自己回答的少数几个：[`$.ui.invalidate`](/docs/zh-CN/plugins/mods/interface#redraw-when-something-changes) 和 [`$.state`](/docs/zh-CN/plugins/mods/interface#keep-state) 调用。对于 `$.clock` 调用，使用 `mock.clock(on)`，否则您的 mod 的 `$.clock.now()` 会失败并显示 `no implementation for clock.now`。176您的 mod 在测试中进行的每个 mods API 调用都需要一个 stub 来回答，除了工具包自己回答的少数几个：[`$.ui.invalidate`](/docs/zh-CN/plugins/mods/interface#redraw-when-something-changes)、[`$.state`](/docs/zh-CN/plugins/mods/interface#keep-state) 和 `$.session.append` 调用。对于 `$.clock` 调用，使用 `mock.clock(on)`，否则您的 mod 的 `$.clock.now()` 会失败并显示 `no implementation for clock.now`。

172 177 

173此表列出了 mods 最常使用的。第一列是您的 mod 进行的调用或它使用 `next(e)` 传递的事件。第二列是传递给 `on` 的函数，使用该名称，因此 `$.store.get` 行变成 `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`。stub 中的 `'...'` 标记您需要填写的文本：178此表列出了 mods 最常使用的。第一列是您的 mod 进行的调用或它使用 `next(e)` 传递的事件。第二列是传递给 `on` 的函数，使用该名称，因此 `$.store.get` 行变成 `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`。stub 中的 `'...'` 标记您需要填写的文本：

174 179 

129* 添加市场一次：`claude plugin marketplace add your-org/your-marketplace`，其中参数是 GitHub `owner/repo` 简写、URL 或路径129* 添加市场一次：`claude plugin marketplace add your-org/your-marketplace`，其中参数是 GitHub `owner/repo` 简写、URL 或路径

130* 安装插件：`claude plugin install deploy-helper@your-marketplace`130* 安装插件：`claude plugin install deploy-helper@your-marketplace`

131* 或从会话内同时执行两者：`/plugin install deploy-helper --marketplace your-org/your-marketplace`。需要 Claude Code v2.1.275 或更高版本。请参阅[在一个命令中添加市场和安装](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command)131* 或从会话内同时执行两者：`/plugin install deploy-helper --marketplace your-org/your-marketplace`。需要 Claude Code v2.1.275 或更高版本。请参阅[在一个命令中添加市场和安装](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command)

132* 或在 shell 中用一个命令同时执行两者：`claude plugin install deploy-helper --marketplace your-org/your-marketplace`。需要 Claude Code v2.1.292 或更高版本

132 133 

133<h3 id="ship-updates-to-users">134<h3 id="ship-updates-to-users">

134 向用户发布更新135 向用户发布更新

163 `Invalid marketplace source format`163 `Invalid marketplace source format`

164</h3>164</h3>

165 165 

166您运行了 `/plugin marketplace add <source>` 或 `claude plugin marketplace add <source>`，Claude Code 回复 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`。166您运行了 `/plugin marketplace add <source>`、`claude plugin marketplace add <source>` 或 `claude plugin install <plugin> --marketplace <source>`，Claude Code 回复 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`。

167 167 

168Claude Code 接受以下形式之一的源：168Claude Code 接受以下形式之一的源：

169 169 

568 `Marketplace "<name>" is already added from a different source`568 `Marketplace "<name>" is already added from a different source`

569</h3>569</h3>

570 570 

571您通过 [`/plugin install <plugin> --marketplace <source>`](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command) 确认添加市场，Claude Code 从该源获取的目录与您已从不同源添加的市场具有相同的名称。Claude Code 保留现有市场而不是替换它，插件未安装。571您在会话中或从 shell 中，通过 [安装命令上的 `--marketplace <source>`](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command) 指定了一个新的市场源。Claude Code 从该源获取的目录与您已从不同源添加的市场具有相同的名称。Claude Code 保留现有市场而不是替换它，插件未安装。

572 572 

573完整消息如下所示：573完整消息如下所示：

574 574 

609主对话的权限模式决定 Claude Code 是否使用您设置的值：609主对话的权限模式决定 Claude Code 是否使用您设置的值：

610 610 

611* 当主对话在 `bypassPermissions`、`acceptEdits` 或 [auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 时，subagent 在该相同模式中运行，Claude Code 忽略您设置的 `permissionMode`。在自动模式下，分类器使用主对话的块和允许规则评估 subagent 的工具调用。当 subagent 完成时，分类器也会在报告被传递之前审查其工作和最终报告，如 [How auto mode handles subagents](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 所述。611* 当主对话在 `bypassPermissions`、`acceptEdits` 或 [auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 时，subagent 在该相同模式中运行，Claude Code 忽略您设置的 `permissionMode`。在自动模式下，分类器使用主对话的块和允许规则评估 subagent 的工具调用。当 subagent 完成时，分类器也会在报告被传递之前审查其工作和最终报告，如 [How auto mode handles subagents](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 所述。

612* 当主对话在 `default`、`dontAsk` 或 `plan` 模式时，subagent 在您设置的权限模式中运行，除了 `bypassPermissions`。声明 `bypassPermissions` 的 subagent 改为保持主对话的模式。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更高版本。612* 当主对话处于 `default`、`dontAsk` 或 `plan` 模式时，子代理会在您设置的权限模式下运行。在以下情况下，它会改为保持主对话的权限模式：

613 * 您设置了 `bypassPermissions`。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更高版本。

614 * 您设置了 `auto`，但子代理[无法使用自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，例如某个设置文件设置了 [`disableAutoMode`](/docs/zh-CN/settings-reference#disableautomode)，或子代理的模型不支持自动模式。

613 615 

614`permissionMode` 接受这些值，以及 `manual` 作为 `default` 的别名：616`permissionMode` 接受这些值，以及 `manual` 作为 `default` 的别名：

615 617