chore(i18n): refresh zh-CN translations

2026-05-01 08:07:15 +00:00 · 2026-05-01 08:07:15 +00:00 · 3f5df42340
commit 3f5df42340
parent 86babe0fba
2 changed files with 425 additions and 291 deletions
--- a/docs/zh-CN/plugins/google-meet.md
+++ b/docs/zh-CN/plugins/google-meet.md
--- a/docs/zh-CN/plugins/sdk-provider-plugins.md
+++ b/docs/zh-CN/plugins/sdk-provider-plugins.md
@ -1,21 +1,21 @@
 ---
 read_when:
-    - 你正在构建一个新的模型提供商插件
-    - 你想将兼容 OpenAI 的代理或自定义 LLM 添加到 OpenClaw
-    - 你需要了解提供商身份验证、目录和运行时钩子
+    - 你正在构建新的模型提供商插件
+    - 你想向 OpenClaw 添加一个 OpenAI 兼容代理或自定义大型语言模型
+    - 你需要了解提供商凭证、目录和运行时钩子
 sidebarTitle: Provider plugins
 summary: 构建 OpenClaw 模型提供商插件的分步指南
 title: 构建提供商插件
 x-i18n:
-    generated_at: "2026-04-29T04:06:10Z"
+    generated_at: "2026-05-01T08:04:54Z"
    model: gpt-5.5
    provider: openai
-    source_hash: 1404594fe1d1e11a612f903512c1002c8f3a804dee53d4204457b534eae93381
+    source_hash: 3f9d721673bdfef0b9c1979b4b8b4c86f19d114374d6b941facb928c3574cd1b
    source_path: plugins/sdk-provider-plugins.md
    workflow: 16
 ---

-本指南将介绍如何构建一个提供商插件，用于向 OpenClaw 添加模型提供商（LLM）。完成后，你将拥有一个带有模型目录、API 密钥凭证和动态模型解析的提供商。
+本指南讲解如何构建一个为 OpenClaw 添加模型提供商（LLM）的提供商插件。完成后，你将拥有一个包含模型目录、API key 凭证和动态模型解析的提供商。

 <Info>
  如果你之前没有构建过任何 OpenClaw 插件，请先阅读
@ -23,13 +23,13 @@ x-i18n:
 </Info>

 <Tip>
-  提供商插件会把模型添加到 OpenClaw 的常规推理循环中。如果模型必须通过拥有线程、压缩或工具事件的原生智能体守护进程运行，请将该提供商与 [agent harness](/zh-CN/plugins/sdk-agent-harness) 搭配使用，而不是把守护进程协议细节放进核心。
+  提供商插件会把模型添加到 OpenClaw 的常规推理循环中。如果模型必须通过一个原生智能体守护进程运行，并由它拥有线程、压缩或工具事件，请将提供商与 [agent harness](/zh-CN/plugins/sdk-agent-harness) 配合使用，而不要把守护进程协议细节放进核心。
 </Tip>

 ## 演练

 <Steps>
-  <Step title="Package and manifest">
+  <Step title="包和清单">
    <CodeGroup>
    ```json package.json
    {
@ -87,11 +87,11 @@ x-i18n:
    ```
    </CodeGroup>

-    清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就可以在不加载你的插件运行时的情况下检测凭证。当某个提供商变体应复用另一个提供商 id 的凭证时，添加 `providerAuthAliases`。`modelSupport` 是可选的，它允许 OpenClaw 在运行时钩子存在之前，根据 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你在 ClawHub 上发布该提供商，则 `package.json` 中必须包含这些 `openclaw.compat` 和 `openclaw.build` 字段。
+    该清单声明了 `providerAuthEnvVars`，这样 OpenClaw 可以在不加载你的插件运行时的情况下检测凭据。当某个提供商变体应复用另一个提供商 ID 的凭证时，添加 `providerAuthAliases`。`modelSupport` 是可选项，它让 OpenClaw 能够在运行时钩子存在之前，根据 `acme-large` 这样的模型 ID 简写自动加载你的提供商插件。如果你在 ClawHub 上发布该提供商，则 `package.json` 中必须包含这些 `openclaw.compat` 和 `openclaw.build` 字段。

  </Step>

-  <Step title="Register the provider">
+  <Step title="注册提供商">
    一个最小提供商需要 `id`、`label`、`auth` 和 `catalog`：

    ```typescript index.ts
@ -163,7 +163,7 @@ x-i18n:
    });
    ```

-    这就是一个可工作的提供商。用户现在可以执行
+    这就是一个可工作的提供商。用户现在可以运行
    `openclaw onboard --acme-ai-api-key <key>`，并选择
    `acme-ai/acme-large` 作为他们的模型。

@ -186,8 +186,7 @@ x-i18n:

    `input` 会在传输前重写最终系统提示词和文本消息内容。`output` 会在 OpenClaw 解析自己的控制标记或渠道投递之前，重写助手文本增量和最终文本。

-    对于仅注册一个带 API 密钥凭证且由单个目录支持运行时的文本提供商的内置提供商，优先使用范围更窄的
-    `defineSingleProviderPluginEntry(...)` 辅助函数：
+    对于只注册一个带 API-key 凭证的文本提供商，并且只有一个由目录支持的运行时的内置提供商，优先使用范围更窄的 `defineSingleProviderPluginEntry(...)` 辅助函数：

    ```typescript
    import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry";
@ -227,21 +226,19 @@ x-i18n:
    });
    ```

-    `buildProvider` 是 OpenClaw 能够解析真实提供商凭证时使用的实时目录路径。它可以执行提供商特定的设备发现。仅将 `buildStaticProvider` 用于在配置凭证前可以安全显示的离线行；它不得要求凭证，也不得发起网络请求。OpenClaw 当前的 `models list --all` 显示只会为内置提供商插件执行静态目录，并且使用空配置、空环境，且没有智能体/工作区路径。
+    `buildProvider` 是 OpenClaw 能够解析真实提供商凭证时使用的实时目录路径。它可以执行提供商特定的发现。仅将 `buildStaticProvider` 用于在配置凭证前可安全展示的离线行；它不得需要凭据或发起网络请求。OpenClaw 的 `models list --all` 显示目前只会对内置提供商插件执行静态目录，并使用空配置、空环境且不提供智能体/工作区路径。

-    如果你的凭证流程还需要在新手引导期间修补 `models.providers.*`、别名以及智能体默认模型，请使用来自
-    `openclaw/plugin-sdk/provider-onboard` 的预设辅助函数。范围最窄的辅助函数是
+    如果你的凭证流程还需要在新手引导期间修补 `models.providers.*`、别名和智能体默认模型，请使用来自 `openclaw/plugin-sdk/provider-onboard` 的预设辅助函数。范围最窄的辅助函数是
    `createDefaultModelPresetAppliers(...)`、
    `createDefaultModelsPresetAppliers(...)` 和
    `createModelCatalogPresetAppliers(...)`。

-    当提供商的原生端点在常规 `openai-completions` 传输上支持流式 usage 块时，优先使用
-    `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 id 检查。`supportsNativeStreamingUsageCompat(...)` 和
-    `applyProviderNativeStreamingUsageCompat(...)` 会从端点能力映射中检测支持，因此即使插件使用自定义提供商 id，原生 Moonshot/DashScope 风格端点仍可选择启用。
+    当提供商的原生端点在常规 `openai-completions` 传输上支持流式 usage 块时，优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 ID 检查。`supportsNativeStreamingUsageCompat(...)` 和
+    `applyProviderNativeStreamingUsageCompat(...)` 会从端点能力映射中检测支持情况，因此即使某个插件使用自定义提供商 ID，原生 Moonshot/DashScope 风格端点仍会选择启用。

  </Step>

-  <Step title="Add dynamic model resolution">
+  <Step title="添加动态模型解析">
    如果你的提供商接受任意模型 ID（例如代理或路由器），请添加 `resolveDynamicModel`：

    ```typescript
@ -263,14 +260,14 @@ x-i18n:
    });
    ```

-    如果解析需要网络调用，请使用 `prepareDynamicModel` 进行异步预热——它完成后会再次运行 `resolveDynamicModel`。
+    如果解析需要网络调用，请使用 `prepareDynamicModel` 进行异步预热 — 它完成后会再次运行 `resolveDynamicModel`。

  </Step>

-  <Step title="Add runtime hooks (as needed)">
-    大多数提供商只需要 `catalog` + `resolveDynamicModel`。根据提供商需求逐步添加钩子。
+  <Step title="按需添加运行时钩子">
+    大多数提供商只需要 `catalog` + `resolveDynamicModel`。随着你的提供商需要它们，再逐步添加钩子。

-    共享辅助构建器现在覆盖了最常见的重放/工具兼容系列，因此插件通常不需要逐个手动接线每个钩子：
+    共享辅助构建器现在覆盖了最常见的重放/工具兼容系列，因此插件通常不需要逐个手动连接每个钩子：

    ```typescript
    import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
@ -294,39 +291,39 @@ x-i18n:

    | 系列 | 接入内容 | 内置示例 |
    | --- | --- | --- |
-    | `openai-compatible` | 用于 OpenAI 兼容传输的共享 OpenAI 风格重放策略，包括工具调用 id 清理、assistant-first 排序修复，以及传输需要时的通用 Gemini 轮次校验 | `moonshot`, `ollama`, `xai`, `zai` |
-    | `anthropic-by-model` | 由 `modelId` 选择的 Claude 感知重放策略，因此 Anthropic 消息传输只有在解析后的模型确实是 Claude id 时，才会获得 Claude 特定的思考块清理 | `amazon-bedrock`, `anthropic-vertex` |
-    | `google-gemini` | 原生 Gemini 重放策略，以及引导重放清理和带标签的推理输出模式 | `google`, `google-gemini-cli` |
-    | `passthrough-gemini` | 适用于通过 OpenAI 兼容代理传输运行的 Gemini 模型的 Gemini 思考签名清理；不会启用原生 Gemini 重放校验或引导重写 | `openrouter`, `kilocode`, `opencode`, `opencode-go` |
-    | `hybrid-anthropic-openai` | 适用于在一个插件中混合 Anthropic 消息和 OpenAI 兼容模型表面的提供商的混合策略；可选的仅 Claude 思考块丢弃会保持在 Anthropic 侧范围内 | `minimax` |
+    | `openai-compatible` | 面向 OpenAI 兼容传输的共享 OpenAI 风格重放策略，包括工具调用 ID 清理、助手优先顺序修正，以及传输需要时的通用 Gemini 轮次校验 | `moonshot`、`ollama`、`xai`、`zai` |
+    | `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知重放策略，因此 Anthropic 消息传输仅在解析后的模型确实是 Claude ID 时，才获得 Claude 特定的 thinking-block 清理 | `amazon-bedrock`、`anthropic-vertex` |
+    | `google-gemini` | 原生 Gemini 重放策略，以及启动重放清理和带标签的 reasoning-output 模式 | `google`、`google-gemini-cli` |
+    | `passthrough-gemini` | 通过 OpenAI 兼容代理传输运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini 重放校验或启动重写 | `openrouter`、`kilocode`、`opencode`、`opencode-go` |
+    | `hybrid-anthropic-openai` | 面向在一个插件中混合 Anthropic 消息和 OpenAI 兼容模型表面的提供商的混合策略；可选的仅 Claude thinking-block 丢弃会限定在 Anthropic 侧 | `minimax` |

-    当前可用的流系列：
+    当前可用的流式传输系列：

    | 系列 | 接入内容 | 内置示例 |
    | --- | --- | --- |
-    | `google-thinking` | 共享流路径上的 Gemini thinking 载荷规范化 | `google`, `google-gemini-cli` |
-    | `kilocode-thinking` | 共享代理流路径上的 Kilo 推理包装器，带有 `kilo/auto`，且不支持的代理推理 ID 会跳过注入的 thinking | `kilocode` |
-    | `moonshot-thinking` | 从配置 + `/think` 级别映射 Moonshot 二进制原生 thinking 载荷 | `moonshot` |
-    | `minimax-fast-mode` | 共享流路径上的 MiniMax 快速模式模型改写 | `minimax`, `minimax-portal` |
-    | `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归因标头、`/fast`/`serviceTier`、文本详略度、原生 Codex Web 搜索、推理兼容载荷整形，以及 Responses 上下文管理 | `openai`, `openai-codex` |
-    | `openrouter-thinking` | 代理路由的 OpenRouter 推理包装器，集中处理不支持模型/`auto` 跳过 | `openrouter` |
-    | `tool-stream-default-on` | 面向 Z.AI 等提供商的默认开启 `tool_stream` 包装器，除非显式禁用，否则它们需要工具流式传输 | `zai` |
+    | `google-thinking` | 共享流路径上的 Gemini 思考载荷规范化 | `google`, `google-gemini-cli` |
+    | `kilocode-thinking` | 共享代理流路径上的 Kilo 推理包装器，并会跳过 `kilo/auto` 和不受支持的代理推理 ID 的注入思考 | `kilocode` |
+    | `moonshot-thinking` | 从配置 + `/think` 级别映射 Moonshot 二进制原生思考载荷 | `moonshot` |
+    | `minimax-fast-mode` | 共享流路径上的 MiniMax 快速模式模型重写 | `minimax`, `minimax-portal` |
+    | `openai-responses-defaults` | 共享原生 OpenAI/Codex Responses 包装器：归因标头、`/fast`/`serviceTier`、文本详略度、原生 Codex Web 搜索、推理兼容载荷整形，以及 Responses 上下文管理 | `openai`, `openai-codex` |
+    | `openrouter-thinking` | 用于代理路由的 OpenRouter 推理包装器，并集中处理不受支持模型/`auto` 的跳过逻辑 | `openrouter` |
+    | `tool-stream-default-on` | 面向 Z.AI 这类提供商的默认开启 `tool_stream` 包装器，除非显式禁用，否则启用工具流式传输 | `zai` |

-    <Accordion title="驱动系列构建器的 SDK 接缝">
-      每个系列构建器都由同一包导出的较低层级公共辅助工具组成；当某个提供商需要偏离通用模式时，你可以使用这些辅助工具：
+    <Accordion title="驱动系列构建器的 SDK 接口">
+      每个系列构建器都由同一包导出的较低层级公开辅助函数组合而成。当某个提供商需要偏离通用模式时，你可以使用它们：

-      - `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`、`buildProviderReplayFamilyHooks(...)`，以及原始重放构建器（`buildOpenAICompatibleReplayPolicy`、`buildAnthropicReplayPolicyForModel`、`buildGoogleGeminiReplayPolicy`、`buildHybridAnthropicOrOpenAIReplayPolicy`）。还导出 Gemini 重放辅助工具（`sanitizeGoogleGeminiReplayHistory`、`resolveTaggedReasoningOutputMode`）和端点/模型辅助工具（`resolveProviderEndpoint`、`normalizeProviderId`、`normalizeGooglePreviewModelId`、`normalizeNativeXaiModelId`）。
-      - `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`、`buildProviderStreamFamilyHooks(...)`、`composeProviderStreamWrappers(...)`，以及共享的 OpenAI/Codex 包装器（`createOpenAIAttributionHeadersWrapper`、`createOpenAIFastModeWrapper`、`createOpenAIServiceTierWrapper`、`createOpenAIResponsesContextManagementWrapper`、`createCodexNativeWebSearchWrapper`）、DeepSeek V4 OpenAI 兼容包装器（`createDeepSeekV4OpenAICompatibleThinkingWrapper`）、Anthropic Messages thinking 预填充清理（`createAnthropicThinkingPrefillPayloadWrapper`），以及共享代理/提供商包装器（`createOpenRouterWrapper`、`createToolStreamWrapper`、`createMinimaxFastModeWrapper`）。
-      - `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks("gemini")`、底层 Gemini schema 辅助工具（`normalizeGeminiToolSchemas`、`inspectGeminiToolSchemas`），以及 xAI 兼容辅助工具（`resolveXaiModelCompatPatch()`、`applyXaiModelCompat(model)`）。内置 xAI 插件将 `normalizeResolvedModel` + `contributeResolvedModelCompat` 与这些工具结合使用，确保 xAI 规则由提供商自行拥有。
+      - `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`、`buildProviderReplayFamilyHooks(...)`，以及原始重放构建器（`buildOpenAICompatibleReplayPolicy`、`buildAnthropicReplayPolicyForModel`、`buildGoogleGeminiReplayPolicy`、`buildHybridAnthropicOrOpenAIReplayPolicy`）。还导出 Gemini 重放辅助函数（`sanitizeGoogleGeminiReplayHistory`、`resolveTaggedReasoningOutputMode`）以及端点/模型辅助函数（`resolveProviderEndpoint`、`normalizeProviderId`、`normalizeGooglePreviewModelId`、`normalizeNativeXaiModelId`）。
+      - `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`、`buildProviderStreamFamilyHooks(...)`、`composeProviderStreamWrappers(...)`，以及共享的 OpenAI/Codex 包装器（`createOpenAIAttributionHeadersWrapper`、`createOpenAIFastModeWrapper`、`createOpenAIServiceTierWrapper`、`createOpenAIResponsesContextManagementWrapper`、`createCodexNativeWebSearchWrapper`）、DeepSeek V4 OpenAI 兼容包装器（`createDeepSeekV4OpenAICompatibleThinkingWrapper`）、Anthropic Messages 思考预填充清理（`createAnthropicThinkingPrefillPayloadWrapper`），以及共享代理/提供商包装器（`createOpenRouterWrapper`、`createToolStreamWrapper`、`createMinimaxFastModeWrapper`）。
+      - `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks("gemini")`、底层 Gemini schema 辅助函数（`normalizeGeminiToolSchemas`、`inspectGeminiToolSchemas`），以及 xAI 兼容辅助函数（`resolveXaiModelCompatPatch()`、`applyXaiModelCompat(model)`）。内置的 xAI 插件会配合这些辅助函数使用 `normalizeResolvedModel` + `contributeResolvedModelCompat`，以确保 xAI 规则由该提供商拥有。

-      有些流辅助工具会有意保留在提供商本地。`@openclaw/anthropic-provider` 将 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及较低层级的 Anthropic 包装器构建器保留在它自己的公共 `api.ts` / `contract-api.ts` 接缝中，因为它们编码了 Claude OAuth beta 处理和 `context1m` 门控。xAI 插件同样将原生 xAI Responses 整形保留在自己的 `wrapStreamFn` 中（`/fast` 别名、默认 `tool_stream`、不支持严格工具清理、移除 xAI 专属推理载荷）。
+      有些流辅助函数会有意保留在提供商本地。`@openclaw/anthropic-provider` 将 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`，以及较低层级的 Anthropic 包装器构建器保留在自己的公开 `api.ts` / `contract-api.ts` 接口中，因为它们编码了 Claude OAuth beta 处理和 `context1m` 门控。xAI 插件也同样将原生 xAI Responses 整形保留在自己的 `wrapStreamFn` 中（`/fast` 别名、默认 `tool_stream`、不受支持的严格工具清理、xAI 专属推理载荷移除）。

-      同一个包根模式也支撑 `@openclaw/openai-provider`（提供商构建器、默认模型辅助工具、实时提供商构建器）和 `@openclaw/openrouter-provider`（提供商构建器以及新手引导/配置辅助工具）。
+      同样的包根模式也支撑 `@openclaw/openai-provider`（提供商构建器、默认模型辅助函数、实时提供商构建器）和 `@openclaw/openrouter-provider`（提供商构建器，以及新手引导/配置辅助函数）。
    </Accordion>

    <Tabs>
      <Tab title="令牌交换">
-        对于需要在每次推理调用前进行令牌交换的提供商：
+        对于每次推理调用前都需要令牌交换的提供商：

        ```typescript
        prepareRuntimeAuth: async (ctx) => {
@ -340,7 +337,7 @@ x-i18n:
        ```
      </Tab>
      <Tab title="自定义标头">
-        对于需要自定义请求标头或正文修改的提供商：
+        对于需要自定义请求标头或修改请求体的提供商：

        ```typescript
        // wrapStreamFn returns a StreamFn derived from ctx.streamFn
@ -358,7 +355,7 @@ x-i18n:
        ```
      </Tab>
      <Tab title="原生传输身份">
-        对于需要在通用 HTTP 或 WebSocket 传输上使用原生请求/会话标头或元数据的提供商：
+        对于需要在通用 HTTP 或 WebSocket 传输上设置原生请求/会话标头或元数据的提供商：

        ```typescript
        resolveTransportTurnState: (ctx) => ({
@ -379,7 +376,7 @@ x-i18n:
        ```
      </Tab>
      <Tab title="用量和计费">
-        对于公开用量/计费数据的提供商：
+        对于暴露用量/计费数据的提供商：

        ```typescript
        resolveUsageAuth: async (ctx) => {
@ -394,70 +391,73 @@ x-i18n:
    </Tabs>

    <Accordion title="所有可用的提供商钩子">
-      OpenClaw 会按此顺序调用钩子。大多数提供商只使用 2-3 个：
-      OpenClaw 不再调用的仅兼容提供商字段，例如 `ProviderPlugin.capabilities` 和 `suppressBuiltInModel`，未在此列出。
+      OpenClaw 按以下顺序调用钩子。大多数提供商只使用 2-3 个：
+      仅用于兼容性的提供商字段，例如 OpenClaw 不再调用的 `ProviderPlugin.capabilities` 和 `suppressBuiltInModel`，未在此列出。

-      | # | 钩子 | 使用场景 |
+      | # | 钩子 | 使用时机 |
      | --- | --- | --- |
      | 1 | `catalog` | 模型目录或基础 URL 默认值 |
-      | 2 | `applyConfigDefaults` | 配置具象化期间由提供商拥有的全局默认值 |
+      | 2 | `applyConfigDefaults` | 配置物化期间由提供商拥有的全局默认值 |
      | 3 | `normalizeModelId` | 查找前清理旧版/预览模型 ID 别名 |
-      | 4 | `normalizeTransport` | 通用模型组装前清理提供商系列 `api` / `baseUrl` |
+      | 4 | `normalizeTransport` | 通用模型组装前清理提供商系列的 `api` / `baseUrl` |
      | 5 | `normalizeConfig` | 规范化 `models.providers.<id>` 配置 |
-      | 6 | `applyNativeStreamingUsageCompat` | 配置提供商的原生流式用量兼容改写 |
+      | 6 | `applyNativeStreamingUsageCompat` | 面向配置提供商的原生流式用量兼容重写 |
      | 7 | `resolveConfigApiKey` | 由提供商拥有的环境标记凭证解析 |
      | 8 | `resolveSyntheticAuth` | 本地/自托管或配置支持的合成凭证 |
-      | 9 | `shouldDeferSyntheticProfileAuth` | 将合成的已存储 profile 占位符降级到环境/配置凭证之后 |
+      | 9 | `shouldDeferSyntheticProfileAuth` | 将合成的已存储配置档占位符降到环境/配置凭证之后 |
      | 10 | `resolveDynamicModel` | 接受任意上游模型 ID |
      | 11 | `prepareDynamicModel` | 解析前异步获取元数据 |
-      | 12 | `normalizeResolvedModel` | 运行器前的传输改写 |
-      | 13 | `contributeResolvedModelCompat` | 另一个兼容传输背后的厂商模型兼容标志 |
+      | 12 | `normalizeResolvedModel` | 运行器前的传输重写 |
+      | 13 | `contributeResolvedModelCompat` | 面向位于另一种兼容传输之后的厂商模型的兼容标志 |
      | 14 | `normalizeToolSchemas` | 注册前由提供商拥有的工具 schema 清理 |
      | 15 | `inspectToolSchemas` | 由提供商拥有的工具 schema 诊断 |
-      | 16 | `resolveReasoningOutputMode` | 标记式与原生推理输出契约 |
+      | 16 | `resolveReasoningOutputMode` | 标签式与原生推理输出契约 |
      | 17 | `prepareExtraParams` | 默认请求参数 |
      | 18 | `createStreamFn` | 完全自定义的 StreamFn 传输 |
-      | 19 | `wrapStreamFn` | 普通流路径上的自定义标头/正文包装器 |
+      | 19 | `wrapStreamFn` | 正常流路径上的自定义标头/请求体包装器 |
      | 20 | `resolveTransportTurnState` | 原生逐轮标头/元数据 |
-      | 21 | `resolveWebSocketSessionPolicy` | 原生 WS 会话标头/冷却时间 |
-      | 22 | `formatApiKey` | 自定义运行时令牌形态 |
+      | 21 | `resolveWebSocketSessionPolicy` | 原生 WS 会话标头/冷却 |
+      | 22 | `formatApiKey` | 自定义运行时令牌形状 |
      | 23 | `refreshOAuth` | 自定义 OAuth 刷新 |
      | 24 | `buildAuthDoctorHint` | 凭证修复指引 |
      | 25 | `matchesContextOverflowError` | 由提供商拥有的溢出检测 |
-      | 26 | `classifyFailoverReason` | 由提供商拥有的速率限制/过载分类 |
-      | 27 | `isCacheTtlEligible` | 提示词缓存 TTL 门控 |
+      | 26 | `classifyFailoverReason` | 由提供商拥有的限速/过载分类 |
+      | 27 | `isCacheTtlEligible` | 提示缓存 TTL 门控 |
      | 28 | `buildMissingAuthMessage` | 自定义缺失凭证提示 |
      | 29 | `augmentModelCatalog` | 合成的前向兼容行 |
      | 30 | `resolveThinkingProfile` | 模型专属 `/think` 选项集 |
-      | 31 | `isBinaryThinking` | 二进制 thinking 开/关兼容性 |
+      | 31 | `isBinaryThinking` | 二进制思考开/关兼容性 |
      | 32 | `supportsXHighThinking` | `xhigh` 推理支持兼容性 |
      | 33 | `resolveDefaultThinkingLevel` | 默认 `/think` 策略兼容性 |
-      | 34 | `isModernModelRef` | 实时/smoke 模型匹配 |
+      | 34 | `isModernModelRef` | 实时/冒烟模型匹配 |
      | 35 | `prepareRuntimeAuth` | 推理前令牌交换 |
      | 36 | `resolveUsageAuth` | 自定义用量凭证解析 |
      | 37 | `fetchUsageSnapshot` | 自定义用量端点 |
-      | 38 | `createEmbeddingProvider` | 由提供商拥有、用于 memory/search 的嵌入适配器 |
+      | 38 | `createEmbeddingProvider` | 用于记忆/搜索且由提供商拥有的嵌入适配器 |
      | 39 | `buildReplayPolicy` | 自定义转录重放/压缩策略 |
-      | 40 | `sanitizeReplayHistory` | 通用清理后的提供商专属重放改写 |
+      | 40 | `sanitizeReplayHistory` | 通用清理后按提供商执行的重放重写 |
      | 41 | `validateReplayTurns` | 嵌入式运行器前的严格重放轮次验证 |
      | 42 | `onModelSelected` | 选择后的回调（例如遥测） |

      运行时回退说明：

-      - `normalizeConfig` 会先检查匹配的提供商，然后检查其他具备钩子能力的提供商插件，直到某个钩子确实修改了配置。如果没有提供商钩子改写受支持的 Google 系列配置条目，内置 Google 配置规范化器仍会应用。
-      - `resolveConfigApiKey` 在暴露时使用提供商钩子。内置 `amazon-bedrock` 路径在这里也有内置 AWS 环境标记解析器，尽管 Bedrock 运行时凭证本身仍使用 AWS SDK 默认链。
-      - `resolveSystemPromptContribution` 允许提供商为某个模型系列注入具备缓存感知能力的系统提示词指引。当行为属于一个提供商/模型系列，并且应保留稳定/动态缓存拆分时，优先使用它，而不是 `before_prompt_build`。
+      - `normalizeConfig` 会先检查匹配的提供商，然后检查其他支持钩子的提供商插件，直到有一个真正更改配置为止。如果没有提供商钩子重写受支持的 Google 系列配置条目，仍会应用内置 Google 配置规范化器。
+      - `resolveConfigApiKey` 会在暴露时使用提供商钩子。内置的 `amazon-bedrock` 路径在这里也有内置 AWS 环境标记解析器，即使 Bedrock 运行时凭证本身仍使用 AWS SDK 默认链。
+      - `resolveSystemPromptContribution` 允许提供商为某个模型系列注入缓存感知的系统提示指引。当行为属于一个提供商/模型系列，并且应保留稳定/动态缓存拆分时，优先使用它，而不是 `before_prompt_build`。

-      有关详细描述和真实示例，请参阅 [内部机制：提供商运行时钩子](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。
+      如需详细说明和真实示例，请参阅 [内部机制：提供商运行时钩子](/zh-CN/plugins/architecture-internals#provider-runtime-hooks)。
    </Accordion>

  </Step>

  <Step title="添加额外能力（可选）">
-    提供商插件可以在文本推理之外，同时注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页获取和 Web 搜索。OpenClaw 将此归类为 **混合能力** 插件，这是公司插件（每个厂商一个插件）的推荐模式。请参阅
-    [内部机制：能力所有权](/zh-CN/plugins/architecture#capability-ownership-model)。
+    提供商插件可以在文本推理之外注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页获取和 Web 搜索。OpenClaw 将其归类为
+    **混合能力** 插件，这是公司插件的推荐模式
+    （每个厂商一个插件）。请参阅
+    [内部机制：能力归属](/zh-CN/plugins/architecture#capability-ownership-model)。

-    在 `register(api)` 中，将每项能力与现有的 `api.registerProvider(...)` 调用一起注册。只选择你需要的标签页：
+    在 `register(api)` 内、与你现有的
+    `api.registerProvider(...)` 调用一起注册每项能力。只选择你需要的标签页：

    <Tabs>
      <Tab title="语音（TTS）">
@ -495,10 +495,15 @@ x-i18n:
        });
        ```

-        对提供商 HTTP 失败使用 `assertOkOrThrowProviderError(...)`，这样插件可共享有上限的错误正文读取、JSON 错误解析和请求 ID 后缀。
+        对提供商 HTTP 失败使用 `assertOkOrThrowProviderError(...)`，这样
+        插件会共享受限的错误正文读取、JSON 错误解析和
+        请求 ID 后缀。
      </Tab>
      <Tab title="实时转录">
-        优先使用 `createRealtimeTranscriptionWebSocketSession(...)` —— 这个共享辅助函数会处理代理捕获、重连退避、关闭刷新、就绪握手、音频排队和关闭事件诊断。你的插件只需要映射上游事件。
+        优先使用 `createRealtimeTranscriptionWebSocketSession(...)` — 这个共享
+        helper 会处理代理捕获、重连退避、关闭时刷新、就绪
+        握手、音频排队和关闭事件诊断。你的插件
+        只需映射上游事件。

        ```typescript
        api.registerRealtimeTranscriptionProvider({
@ -536,7 +541,11 @@ x-i18n:
        });
        ```

-        通过 POST 上传 multipart 音频的批处理 STT 提供商应使用来自 `openclaw/plugin-sdk/provider-http` 的 `buildAudioTranscriptionFormData(...)`。该辅助函数会规范化上传文件名，包括为兼容的转录 API 需要 M4A 风格文件名的 AAC 上传。
+        通过 POST 发送 multipart 音频的批量 STT 提供商应使用
+        `openclaw/plugin-sdk/provider-http` 中的
+        `buildAudioTranscriptionFormData(...)`。该 helper 会规范化上传
+        文件名，包括需要 M4A 风格文件名以兼容
+        转录 API 的 AAC 上传。
      </Tab>
      <Tab title="实时语音">
        ```typescript
@ -552,6 +561,7 @@ x-i18n:
            connect: async () => {},
            sendAudio: () => {},
            setMediaTimestamp: () => {},
+            handleBargeIn: () => {},
            submitToolResult: () => {},
            acknowledgeMark: () => {},
            close: () => {},
@ -559,6 +569,9 @@ x-i18n:
          }),
        });
        ```
+
+        当传输协议可以检测到人工正在打断助手播放，且提供商支持截断或
+        清除当前音频响应时，实现 `handleBargeIn`。
      </Tab>
      <Tab title="媒体理解">
        ```typescript
@ -571,7 +584,12 @@ x-i18n:
        ```
      </Tab>
      <Tab title="图像和视频生成">
-        视频能力使用一种**模式感知**的结构：`generate`、`imageToVideo` 和 `videoToVideo`。像 `maxInputImages` / `maxInputVideos` / `maxDurationSeconds` 这样的扁平聚合字段不足以清晰声明转换模式支持或已禁用的模式。音乐生成也遵循相同模式，使用显式的 `generate` / `edit` 块。
+        视频能力使用一种**模式感知**的形状：`generate`、
+        `imageToVideo` 和 `videoToVideo`。像
+        `maxInputImages` / `maxInputVideos` / `maxDurationSeconds` 这样的扁平聚合字段不足以
+        清晰地表明对转换模式的支持或已禁用的模式。
+        音乐生成也遵循相同模式，使用显式的 `generate` /
+        `edit` 块。

        ```typescript
        api.registerImageGenerationProvider({
@ -598,7 +616,7 @@ x-i18n:
        });
        ```
      </Tab>
-      <Tab title="Web 获取和搜索">
+      <Tab title="网页获取和搜索">
        ```typescript
        api.registerWebFetchProvider({
          id: "acme-ai-fetch",
@ -674,7 +692,8 @@ clawhub package publish your-org/your-plugin --dry-run
 clawhub package publish your-org/your-plugin
 ```

-不要在这里使用旧的仅技能发布别名；插件包应使用 `clawhub package publish`。
+不要在这里使用旧版的仅 Skills 发布别名；插件包应使用
+`clawhub package publish`。

 ## 文件结构

@ -690,21 +709,22 @@ clawhub package publish your-org/your-plugin

 ## 目录顺序参考

-`catalog.order` 控制你的目录相对于内置提供商的合并时机：
+`catalog.order` 控制你的目录相对于内置
+提供商的合并时机：

-| 顺序      | 时机          | 用例                                            |
+| 顺序      | 时机          | 使用场景                                        |
 | --------- | ------------- | ----------------------------------------------- |
 | `simple`  | 第一轮        | 普通 API key 提供商                             |
-| `profile` | 在 simple 后  | 由认证档案控制的提供商                          |
-| `paired`  | 在 profile 后 | 合成多个相关条目                                |
+| `profile` | simple 之后   | 受凭证档案限制的提供商                          |
+| `paired`  | profile 之后  | 合成多个相关条目                                |
 | `late`    | 最后一轮      | 覆盖现有提供商（冲突时胜出）                    |

 ## 后续步骤

- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) —— 如果你的插件也提供渠道
- [SDK 运行时](/zh-CN/plugins/sdk-runtime) —— `api.runtime` 辅助函数（TTS、搜索、子智能体）
- [SDK 概览](/zh-CN/plugins/sdk-overview) —— 完整的子路径导入参考
- [插件内部机制](/zh-CN/plugins/architecture-internals#provider-runtime-hooks) —— 钩子细节和内置示例
+- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 如果你的插件还提供渠道
+- [SDK 运行时](/zh-CN/plugins/sdk-runtime) — `api.runtime` helper（TTS、搜索、子智能体）
+- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整的子路径导入参考
+- [插件内部机制](/zh-CN/plugins/architecture-internals#provider-runtime-hooks) — 钩子细节和内置示例

 ## 相关内容