chore(i18n): refresh zh-CN translations

docs/zh-CN/plugins/building-plugins.md

@@ -1,33 +1,33 @@
 ---
 read_when:
-    - 你想创建一个新的 OpenClaw 插件
-    - 你需要一个用于插件开发的快速开始指南
-    - 你正在为 OpenClaw 添加一个新的渠道、提供商、工具或其他能力
+    - 你想要创建一个新的 OpenClaw 插件
+    - 你需要一份插件开发快速开始指南
+    - 你正在为 OpenClaw 添加新的渠道、提供商、工具或其他能力
 sidebarTitle: Getting Started
 summary: 在几分钟内创建你的第一个 OpenClaw 插件
 title: 构建插件
 x-i18n:
-    generated_at: "2026-04-22T07:00:34Z"
+    generated_at: "2026-04-22T17:55:46Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 67368be311537f984f14bea9239b88c3eccf72a76c9dd1347bb041e02697ae24
+    source_hash: 35faa4e2722a58aa12330103b42d2dd6e14e56ee46720883d0945a984d991f79
     source_path: plugins/building-plugins.md
     workflow: 15
 ---
 
 # 构建插件
 
-插件通过新能力扩展 OpenClaw：渠道、模型提供商、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、智能体工具，或这些能力的任意组合。
+插件通过新增能力来扩展 OpenClaw：渠道、模型提供商、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、智能体工具，或这些能力的任意组合。
 
-你不需要将你的插件添加到 OpenClaw 仓库中。发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm，用户即可使用 `openclaw plugins install <package-name>` 安装。OpenClaw 会先尝试 ClawHub，然后自动回退到 npm。
+你不需要把你的插件添加到 OpenClaw 仓库中。发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm，用户即可通过 `openclaw plugins install <package-name>` 安装。OpenClaw 会优先尝试 ClawHub，并在需要时自动回退到 npm。
 
 ## 先决条件
 
-- Node >= 22 和一个包管理器（npm 或 pnpm）
+- Node >= 22，以及一个包管理器（npm 或 pnpm）
 - 熟悉 TypeScript（ESM）
 - 对于仓库内插件：已克隆仓库并执行 `pnpm install`
 
-## 这是什么类型的插件？
+## 你要创建哪种插件？
 
 <CardGroup cols={3}>
   <Card title="渠道插件" icon="messages-square" href="/zh-CN/plugins/sdk-channel-plugins">
@@ -37,15 +37,15 @@ x-i18n:
     添加一个模型提供商（LLM、代理或自定义端点）
   </Card>
   <Card title="工具 / hook 插件" icon="wrench">
-    注册智能体工具、事件 hooks 或服务——继续阅读下文
+    注册智能体工具、事件 hook 或服务——继续阅读下文
   </Card>
 </CardGroup>
 
-如果某个渠道插件是可选的，并且在新手引导 / 设置运行时可能尚未安装，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导组合，用于提示安装要求，并在插件安装之前，对真实配置写入执行封闭失败保护。
+如果某个渠道插件是可选的，并且在新手引导 / 设置运行时可能尚未安装，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导组合，用于提示安装要求，并在插件安装完成前对实际配置写入采取失败关闭策略。
 
 ## 快速开始：工具插件
 
-本演练将创建一个用于注册智能体工具的最小插件。渠道插件和提供商插件有上方链接的专门指南。
+本指南将创建一个最小插件，用来注册一个智能体工具。渠道插件和提供商插件有上方链接中的专门指南。
 
 <Steps>
   <Step title="创建包和清单">
@@ -82,8 +82,8 @@ x-i18n:
     ```
     </CodeGroup>
 
-    每个插件都需要一个清单，即使没有配置也是如此。完整模式请参见
-    [Manifest](/zh-CN/plugins/manifest)。ClawHub 发布的规范代码片段位于 `docs/snippets/plugin-publish/`。
+    每个插件都需要一个清单，即使没有配置也一样。完整 schema 请参见
+    [Manifest](/zh-CN/plugins/manifest)。规范的 ClawHub 发布片段位于 `docs/snippets/plugin-publish/`。
 
   </Step>
 
@@ -112,8 +112,8 @@ x-i18n:
     ```
 
     `definePluginEntry` 用于非渠道插件。对于渠道，请使用
-    `defineChannelPluginEntry`——参见 [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins)。
-    完整的入口点选项请参见 [Entry Points](/zh-CN/plugins/sdk-entrypoints)。
+    `defineChannelPluginEntry` —— 参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。
+    关于完整的入口点选项，请参见 [入口点](/zh-CN/plugins/sdk-entrypoints)。
 
   </Step>
 
@@ -127,9 +127,9 @@ x-i18n:
     openclaw plugins install clawhub:@myorg/openclaw-my-plugin
     ```
 
-    对于像 `@myorg/openclaw-my-plugin` 这样的裸包说明符，OpenClaw 也会在 npm 之前先检查 ClawHub。
+    对于像 `@myorg/openclaw-my-plugin` 这样的裸包规格，OpenClaw 也会在 npm 之前先检查 ClawHub。
 
-    **仓库内插件：** 放在内置插件工作区树下——会被自动发现。
+    **仓库内插件：** 放在内置插件工作区目录树下——会自动发现。
 
     ```bash
     pnpm test -- <bundled-plugin-root>/my-plugin/
@@ -144,54 +144,56 @@ x-i18n:
 
 | 能力 | 注册方法 | 详细指南 |
 | ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
-| 文本推理（LLM） | `api.registerProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins) |
-| CLI 推理后端 | `api.registerCliBackend(...)` | [CLI Backends](/zh-CN/gateway/cli-backends) |
-| 渠道 / 消息 | `api.registerChannel(...)` | [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins) |
-| 语音（TTS/STT） | `api.registerSpeechProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
-| 实时转写 | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
-| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
-| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
-| 图像生成 | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
-| 音乐生成 | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
-| 视频生成 | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
-| 网页抓取 | `api.registerWebFetchProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
-| 网页搜索 | `api.registerWebSearchProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| 文本推理（LLM） | `api.registerProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins) |
+| CLI 推理后端 | `api.registerCliBackend(...)` | [CLI 后端](/zh-CN/gateway/cli-backends) |
+| 渠道 / 消息传递 | `api.registerChannel(...)` | [渠道插件](/zh-CN/plugins/sdk-channel-plugins) |
+| 语音（TTS/STT） | `api.registerSpeechProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| 实时转录 | `api.registerRealtimeTranscriptionProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| 图像生成 | `api.registerImageGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| 音乐生成 | `api.registerMusicGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| 视频生成 | `api.registerVideoGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| 网页抓取 | `api.registerWebFetchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
+| 网页搜索 | `api.registerWebSearchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
 | 内嵌 Pi 扩展 | `api.registerEmbeddedExtensionFactory(...)` | [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api) |
 | 智能体工具 | `api.registerTool(...)` | 下文 |
-| 自定义命令 | `api.registerCommand(...)` | [Entry Points](/zh-CN/plugins/sdk-entrypoints) |
-| 事件 hooks | `api.registerHook(...)` | [Entry Points](/zh-CN/plugins/sdk-entrypoints) |
-| HTTP 路由 | `api.registerHttpRoute(...)` | [Internals](/zh-CN/plugins/architecture#gateway-http-routes) |
-| CLI 子命令 | `api.registerCli(...)` | [Entry Points](/zh-CN/plugins/sdk-entrypoints) |
+| 自定义命令 | `api.registerCommand(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
+| 事件 hook | `api.registerHook(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
+| HTTP 路由 | `api.registerHttpRoute(...)` | [内部机制](/zh-CN/plugins/architecture#gateway-http-routes) |
+| CLI 子命令 | `api.registerCli(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) |
 
-完整注册 API，请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。
+完整注册 API 请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。
 
-当插件需要 Pi 原生的嵌入式运行器 hooks 时，请使用 `api.registerEmbeddedExtensionFactory(...)`，例如在最终工具结果消息发出之前，异步重写 `tool_result`。如果工作不需要 Pi 扩展时序，应优先使用常规 OpenClaw 插件 hooks。
+当插件需要 Pi 原生的嵌入式运行器 hook 时，请使用 `api.registerEmbeddedExtensionFactory(...)`，例如在最终工具结果消息发出前，异步重写 `tool_result`。如果工作不需要 Pi 扩展时序，则优先使用常规 OpenClaw 插件 hook。
 
-如果你的插件注册自定义 Gateway 网关 RPC 方法，请将它们放在插件专属前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保留，并且总是解析为 `operator.admin`，即使插件请求更窄的作用域也是如此。
+如果你的插件注册了自定义 Gateway 网关 RPC 方法，请将它们放在插件专属前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）保持保留状态，并且始终解析为 `operator.admin`，即使插件请求更窄的作用域也是如此。
 
-需要注意的 hook 守卫语义：
+需要牢记的 hook 守卫语义：
 
-- `before_tool_call`：`{ block: true }` 为终止性决定，并会停止更低优先级的处理器。
-- `before_tool_call`：`{ block: false }` 会被视为未作决定。
+- `before_tool_call`：`{ block: true }` 是终止性结果，并会阻止更低优先级的处理器。
+- `before_tool_call`：`{ block: false }` 会被视为没有作出决定。
 - `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec 审批覆盖层、Telegram 按钮、Discord 交互，或任意渠道上的 `/approve` 命令提示用户审批。
-- `before_install`：`{ block: true }` 为终止性决定，并会停止更低优先级的处理器。
-- `before_install`：`{ block: false }` 会被视为未作决定。
-- `message_sending`：`{ cancel: true }` 为终止性决定，并会停止更低优先级的处理器。
-- `message_sending`：`{ cancel: false }` 会被视为未作决定。
+- `before_install`：`{ block: true }` 是终止性结果，并会阻止更低优先级的处理器。
+- `before_install`：`{ block: false }` 会被视为没有作出决定。
+- `message_sending`：`{ cancel: true }` 是终止性结果，并会阻止更低优先级的处理器。
+- `message_sending`：`{ cancel: false }` 会被视为没有作出决定。
+- `message_received`：当你需要入站线程 / 话题路由时，优先使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道专属的额外信息。
+- `message_sending`：在路由中优先使用类型化的 `replyToId` / `threadId` 字段，而不是渠道专属的 metadata 键。
 
-`/approve` 命令会同时处理 exec 审批和插件审批，并带有有界回退：当找不到 exec 审批 id 时，OpenClaw 会使用相同 id 通过插件审批重试。插件审批转发可通过配置中的 `approvals.plugin` 独立设置。
+`/approve` 命令同时处理 exec 审批和插件审批，并带有有界回退逻辑：当找不到 exec 审批 id 时，OpenClaw 会用同一个 id 重试插件审批。插件审批转发可通过配置中的 `approvals.plugin` 独立设置。
 
-如果自定义审批流程需要检测这个相同的有界回退场景，优先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，而不是手动匹配审批过期字符串。
+如果自定义审批流程需要检测这个相同的有界回退场景，请优先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，而不要手动匹配审批过期字符串。
 
-详见 [SDK 概览 hook 决策语义](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
+详情请参见 [SDK 概览 hook 决策语义](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。
 
 ## 注册智能体工具
 
-工具是 LLM 可以调用的类型化函数。它们可以是必需的（始终可用），也可以是可选的（用户选择启用）：
+工具是 LLM 可以调用的类型化函数。它们可以是必需的（始终可用），也可以是可选的（用户主动启用）：
 
 ```typescript
 register(api) {
-  // 必需工具——始终可用
+  // Required tool — always available
   api.registerTool({
     name: "my_tool",
     description: "Do a thing",
@@ -201,7 +203,7 @@ register(api) {
     },
   });
 
-  // 可选工具——用户必须添加到 allowlist
+  // Optional tool — user must add to allowlist
   api.registerTool(
     {
       name: "workflow_tool",
@@ -225,8 +227,8 @@ register(api) {
 ```
 
 - 工具名称不得与核心工具冲突（冲突项会被跳过）
-- 对于有副作用或有额外二进制依赖要求的工具，请使用 `optional: true`
-- 用户可以通过将插件 id 添加到 `tools.allow` 来启用某个插件的所有工具
+- 对有副作用或依赖额外二进制文件的工具使用 `optional: true`
+- 用户也可以通过将插件 id 添加到 `tools.allow`，启用某个插件中的所有工具
 
 ## 导入约定
 
@@ -236,42 +238,42 @@ register(api) {
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 
-// 错误：单体根入口（已弃用，将被移除）
+// Wrong: monolithic root (deprecated, will be removed)
 import { ... } from "openclaw/plugin-sdk";
 ```
 
-完整的子路径参考，请参见 [SDK 概览](/zh-CN/plugins/sdk-overview)。
+完整的子路径参考请参见 [SDK 概览](/zh-CN/plugins/sdk-overview)。
 
-在你的插件内部，使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）进行内部导入——绝不要通过其 SDK 路径导入你自己的插件。
+在你的插件内部，请使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）进行内部导入——不要通过它自己的 SDK 路径导入你自己的插件。
 
-对于提供商插件，除非该抽象接口确实是通用的，否则应将提供商专用辅助函数保留在这些包根 barrel 中。当前内置示例包括：
+对于提供商插件，除非某个接口确实具有通用性，否则请将提供商专属辅助工具保留在这些包根级 barrel 中。当前的内置示例包括：
 
-- Anthropic：Claude 流包装器，以及 `service_tier` / beta 辅助函数
-- OpenAI：提供商构建器、默认模型辅助函数、实时提供商
-- OpenRouter：提供商构建器以及新手引导 / 配置辅助函数
+- Anthropic：Claude 流包装器以及 `service_tier` / beta 辅助工具
+- OpenAI：提供商构建器、默认模型辅助工具、实时提供商
+- OpenRouter：提供商构建器以及新手引导 / 配置辅助工具
 
-如果某个辅助函数只在一个内置提供商包内部有用，请将其保留在该包根抽象接口上，而不是提升到 `openclaw/plugin-sdk/*` 中。
+如果某个辅助工具只在一个内置提供商包内有用，请将它保留在该包根级接口上，而不是将其提升到 `openclaw/plugin-sdk/*`。
 
-一些生成的 `openclaw/plugin-sdk/<bundled-id>` 辅助抽象接口仍然存在，用于内置插件维护和兼容性，例如 `plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。应将这些视为保留接口，而不是新第三方插件的默认模式。
+一些生成的 `openclaw/plugin-sdk/<bundled-id>` 辅助接口仍然存在，用于内置插件维护和兼容性，例如 `plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。请将这些视为保留接口，而不是新第三方插件的默认模式。
 
 ## 提交前检查清单
 
 <Check>**package.json** 具有正确的 `openclaw` 元数据</Check>
-<Check>**openclaw.plugin.json** 清单存在且有效</Check>
+<Check>**openclaw.plugin.json** 清单文件已存在且有效</Check>
 <Check>入口点使用 `defineChannelPluginEntry` 或 `definePluginEntry`</Check>
 <Check>所有导入都使用聚焦的 `plugin-sdk/<subpath>` 路径</Check>
 <Check>内部导入使用本地模块，而不是通过 SDK 自导入</Check>
 <Check>测试通过（`pnpm test -- <bundled-plugin-root>/my-plugin/`）</Check>
 <Check>`pnpm check` 通过（仓库内插件）</Check>
 
-## Beta 版本测试
+## Beta 发布测试
 
-1. 关注 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。Beta 标签类似 `v2026.3.N-beta.1`。你也可以为 OpenClaw 官方 X 账号 [@openclaw](https://x.com/openclaw) 开启通知，以获取发布公告。
-2. 一旦 beta 标签出现，立即针对该 beta 标签测试你的插件。稳定版发布前的窗口通常只有几个小时。
-3. 测试后，在 `plugin-forum` Discord 渠道中你插件对应的帖子里发送 `all good` 或说明损坏内容。如果你还没有帖子，请创建一个。
-4. 如果有功能损坏，请创建或更新一个标题为 `Beta blocker: <plugin-name> - <summary>` 的 issue，并添加 `beta-blocker` 标签。将该 issue 链接放到你的帖子中。
-5. 向 `main` 提交一个标题为 `fix(<plugin-id>): beta blocker - <summary>` 的 PR，并在 PR 和你的 Discord 帖子中都链接该 issue。贡献者不能给 PR 添加标签，因此该标题是给维护者和自动化系统的 PR 侧信号。带有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题也可能照常发布。维护者会在 beta 测试期间关注这些帖子。
-6. 没有消息就表示一切正常。如果你错过了这个窗口，你的修复很可能会进入下一个周期。
+1. 关注 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 的 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。Beta 标签通常类似 `v2026.3.N-beta.1`。你也可以为 OpenClaw 官方 X 账号 [@openclaw](https://x.com/openclaw) 开启通知，以获取发布公告。
+2. 一旦 beta 标签出现，立即用它测试你的插件。稳定版发布前的窗口期通常只有几个小时。
+3. 测试完成后，在 `plugin-forum` Discord 渠道中你插件对应的讨论串里发帖，内容写 `all good` 或说明出现了什么问题。如果你还没有讨论串，就创建一个。
+4. 如果出现问题，请新建或更新一个标题为 `Beta blocker: <plugin-name> - <summary>` 的 issue，并添加 `beta-blocker` 标签。将该 issue 链接发到你的讨论串中。
+5. 向 `main` 提交一个标题为 `fix(<plugin-id>): beta blocker - <summary>` 的 PR，并在 PR 和你的 Discord 讨论串中都关联该 issue。贡献者不能给 PR 添加标签，因此标题就是给维护者和自动化系统的 PR 侧信号。带有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题则仍有可能随版本发布。维护者会在 beta 测试期间关注这些讨论串。
+6. 没有消息就表示一切正常。如果你错过了这个窗口，你的修复很可能会在下一个周期落地。
 
 ## 后续步骤
 
@@ -283,16 +285,16 @@ import { ... } from "openclaw/plugin-sdk";
     构建一个模型提供商插件
   </Card>
   <Card title="SDK 概览" icon="book-open" href="/zh-CN/plugins/sdk-overview">
-    导入映射和注册 API 参考
+    导入映射与注册 API 参考
   </Card>
   <Card title="运行时辅助工具" icon="settings" href="/zh-CN/plugins/sdk-runtime">
     通过 api.runtime 使用 TTS、搜索、子智能体
   </Card>
   <Card title="测试" icon="test-tubes" href="/zh-CN/plugins/sdk-testing">
-    测试工具和模式
+    测试工具与模式
   </Card>
   <Card title="插件清单" icon="file-json" href="/zh-CN/plugins/manifest">
-    完整的清单模式参考
+    完整的清单 schema 参考
   </Card>
 </CardGroup>
 
@@ -301,5 +303,5 @@ import { ... } from "openclaw/plugin-sdk";
 - [插件架构](/zh-CN/plugins/architecture) — 内部架构深入解析
 - [SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考
 - [Manifest](/zh-CN/plugins/manifest) — 插件清单格式
-- [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件
-- [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件
+- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件
+- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件

docs/zh-CN/plugins/sdk-overview.md

@@ -1,29 +1,29 @@
 ---
 read_when:
     - 你需要知道应从哪个 SDK 子路径导入
-    - 你想查看 OpenClawPluginApi 上所有注册方法的参考文档
-    - 你正在查找某个特定的 SDK 导出内容
+    - 你想要一份 OpenClawPluginApi 上所有注册方法的参考文档
+    - 你正在查找一个特定的 SDK 导出项
 sidebarTitle: SDK Overview
-summary: Import map、注册 API 参考和 SDK 架构
+summary: 导入映射、注册 API 参考和 SDK 架构
 title: 插件 SDK 概览
 x-i18n:
-    generated_at: "2026-04-22T07:00:33Z"
+    generated_at: "2026-04-22T17:55:52Z"
     model: gpt-5.4
     provider: openai
-    source_hash: e57019e6f9a7fed7842ac575e025b6db41d125f5fa9d0d1de03923fdb1f6bcc3
+    source_hash: d010d8c8df684325b481e9e7b0709a079be4db10452fe64d29e2a2ccbbbf10e8
     source_path: plugins/sdk-overview.md
     workflow: 15
 ---
 
 # 插件 SDK 概览
 
-插件 SDK 是插件与核心之间的类型化契约。本页是关于**导入什么**以及**你可以注册什么**的参考文档。
+插件 SDK 是插件与核心之间的类型化契约。本页是关于**该导入什么**以及**你可以注册什么**的参考文档。
 
 <Tip>
   **在找操作指南？**
-  - 第一个插件？从[入门指南](/zh-CN/plugins/building-plugins)开始
-  - 渠道插件？参见[渠道插件](/zh-CN/plugins/sdk-channel-plugins)
-  - 提供商插件？参见[提供商插件](/zh-CN/plugins/sdk-provider-plugins)
+  - 第一个插件？从 [入门指南](/zh-CN/plugins/building-plugins) 开始
+  - 渠道插件？请参阅 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)
+  - 提供商插件？请参阅 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)
 </Tip>
 
 ## 导入约定
@@ -35,19 +35,19 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
 ```
 
-每个子路径都是一个小型、自包含的模块。这样可以保持快速启动，并防止循环依赖问题。对于渠道专用的入口/构建辅助工具，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总括性表面和共享辅助工具，例如 `buildChannelConfigSchema`。
+每个子路径都是一个小型、自包含模块。这样可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口点/构建辅助工具，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总括性表面和共享辅助工具，例如 `buildChannelConfigSchema`。
 
-不要添加或依赖带提供商名称的便捷接缝，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带渠道品牌的辅助接缝。内置插件应在它们自己的 `api.ts` 或 `runtime-api.ts` barrel 中组合通用 SDK 子路径；而核心要么应使用这些插件本地的 barrel，要么应在需求确实跨渠道时添加一个狭义的通用 SDK 契约。
+不要添加或依赖带有提供商名称的便捷接缝，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带有渠道品牌的辅助工具接缝。内置插件应在它们自己的 `api.ts` 或 `runtime-api.ts` barrel 文件中组合通用 SDK 子路径，而核心则应使用这些插件本地 barrel，或者在需求确实跨渠道时添加一个窄范围的通用 SDK 契约。
 
-生成的导出映射仍然包含一小部分内置插件辅助接缝，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅用于内置插件维护和兼容性；它们在下面的通用表格中被有意省略，也不是新第三方插件推荐的导入路径。
+生成的导出映射仍然包含一小组内置插件辅助工具接缝，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅用于内置插件维护和兼容性；它们被有意从下方的常用表格中省略，也不是新的第三方插件推荐使用的导入路径。
 
 ## 子路径参考
 
-最常用的子路径，按用途分组。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`。
+最常用的子路径，按用途分组。包含 200 多个子路径的完整生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。
 
-保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其提升为公开接口，否则应将其视为实现细节/兼容性表面。
+保留的内置插件辅助工具子路径仍会出现在该生成列表中。除非某个文档页面明确将其提升为公开接口，否则请将它们视为实现细节/兼容性表面。
 
-### 插件入口
+### 插件入口点
 
 | 子路径 | 关键导出 |
 | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
@@ -61,53 +61,53 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
     | 子路径 | 关键导出 |
     | --- | --- |
     | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
-    | `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
-    | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
+    | `plugin-sdk/config-schema` | 根级 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
+    | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、`createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` |
     | `plugin-sdk/setup` | 共享设置向导辅助工具、allowlist 提示、设置状态构建器 |
-    | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
+    | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`、`noteChannelLookupFailure`、`noteChannelLookupSummary`、`promptResolvedAllowFrom`、`splitSetupEntries`、`createAllowlistSetupWizardProxy`、`createDelegatedSetupWizardProxy` |
     | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
-    | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
-    | `plugin-sdk/account-core` | 多账户配置/操作门控辅助工具、默认账户回退辅助工具 |
+    | `plugin-sdk/setup-tools` | `formatCliCommand`、`detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、`CONFIG_DIR` |
+    | `plugin-sdk/account-core` | 多账户配置/动作门控辅助工具、默认账户回退辅助工具 |
     | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助工具 |
     | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 |
-    | `plugin-sdk/account-helpers` | 狭义的账户列表/账户操作辅助工具 |
+    | `plugin-sdk/account-helpers` | 窄范围的账户列表/账户操作辅助工具 |
     | `plugin-sdk/channel-pairing` | `createChannelPairingController` |
     | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
     | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
     | `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 |
-    | `plugin-sdk/telegram-command-config` | 带内置契约回退的 Telegram 自定义命令规范化/校验辅助工具 |
-    | `plugin-sdk/command-gating` | 狭义的命令授权门控辅助工具 |
+    | `plugin-sdk/telegram-command-config` | 带有内置契约回退的 Telegram 自定义命令规范化/校验辅助工具 |
+    | `plugin-sdk/command-gating` | 窄范围的命令授权门控辅助工具 |
     | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
-    | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/完成辅助工具 |
+    | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/最终化辅助工具 |
     | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助工具 |
     | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助工具 |
     | `plugin-sdk/messaging-targets` | 目标解析/匹配辅助工具 |
     | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 |
     | `plugin-sdk/outbound-runtime` | 出站身份、发送委托和负载规划辅助工具 |
-    | `plugin-sdk/poll-runtime` | 狭义的投票规范化辅助工具 |
+    | `plugin-sdk/poll-runtime` | 窄范围的投票规范化辅助工具 |
     | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 |
     | `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 |
     | `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对和已配置绑定辅助工具 |
     | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 |
     | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 |
     | `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助工具 |
-    | `plugin-sdk/channel-config-primitives` | 狭义的渠道配置 schema 基元 |
+    | `plugin-sdk/channel-config-primitives` | 窄范围的渠道配置 schema 基元 |
     | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 |
     | `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 |
     | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助工具 |
-    | `plugin-sdk/group-access` | 共享群组访问判定辅助工具 |
-    | `plugin-sdk/direct-dm` | 共享直接私信认证/保护辅助工具 |
-    | `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递和旧版交互式回复辅助工具。参见[消息呈现](/zh-CN/plugins/message-presentation) |
-    | `plugin-sdk/channel-inbound` | 入站去抖、提及匹配、提及策略辅助工具和 envelope 辅助工具的兼容性 barrel |
-    | `plugin-sdk/channel-mention-gating` | 不含更广泛入站运行时表面的狭义提及策略辅助工具 |
+    | `plugin-sdk/group-access` | 共享群组访问决策辅助工具 |
+    | `plugin-sdk/direct-dm` | 共享直接私信认证/守卫辅助工具 |
+    | `plugin-sdk/interactive-runtime` | 语义化消息展示、投递和旧版交互式回复辅助工具。请参阅 [消息展示](/zh-CN/plugins/message-presentation) |
+    | `plugin-sdk/channel-inbound` | 针对入站防抖、提及匹配、提及策略辅助工具和 envelope 辅助工具的兼容性 barrel |
+    | `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时表面的窄范围提及策略辅助工具 |
     | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 |
     | `plugin-sdk/channel-logging` | 用于入站丢弃和输入中/确认失败的渠道日志辅助工具 |
     | `plugin-sdk/channel-send-result` | 回复结果类型 |
-    | `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 |
+    | `plugin-sdk/channel-actions` | 渠道消息动作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 |
     | `plugin-sdk/channel-targets` | 目标解析/匹配辅助工具 |
     | `plugin-sdk/channel-contract` | 渠道契约类型 |
     | `plugin-sdk/channel-feedback` | 反馈/反应接线 |
-    | `plugin-sdk/channel-secret-runtime` | 狭义的密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和密钥目标类型 |
+    | `plugin-sdk/channel-secret-runtime` | 窄范围的密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和密钥目标类型 |
   </Accordion>
 
   <Accordion title="提供商子路径">
@@ -115,25 +115,25 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
     | --- | --- |
     | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
     | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 |
-    | `plugin-sdk/self-hosted-provider-setup` | 专注于 OpenAI 兼容自托管提供商的设置辅助工具 |
+    | `plugin-sdk/self-hosted-provider-setup` | 专注于兼容 OpenAI 的自托管提供商设置辅助工具 |
     | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 |
     | `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API key 解析辅助工具 |
     | `plugin-sdk/provider-auth-api-key` | API key 新手引导/配置文件写入辅助工具，例如 `upsertApiKeyProfile` |
-    | `plugin-sdk/provider-auth-result` | 标准 OAuth auth-result 构建器 |
-    | `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助工具 |
+    | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 |
+    | `plugin-sdk/provider-auth-login` | 提供商插件共享的交互式登录辅助工具 |
     | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 |
-    | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
-    | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及模型 ID 规范化辅助工具，例如 `normalizeNativeXaiModelId` |
-    | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
+    | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`、`ensureApiKeyFromOptionEnvOrPrompt`、`upsertAuthProfile`、`upsertApiKeyProfile`、`writeOAuthCredentials` |
+    | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享重放策略构建器、提供商端点辅助工具，以及模型 id 规范化辅助工具，例如 `normalizeNativeXaiModelId` |
+    | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` |
     | `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助工具 |
-    | `plugin-sdk/provider-web-fetch-contract` | 狭义的 web-fetch 配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
+    | `plugin-sdk/provider-web-fetch-contract` | 窄范围的 web-fetch 配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
     | `plugin-sdk/provider-web-fetch` | Web-fetch 提供商注册/缓存辅助工具 |
-    | `plugin-sdk/provider-web-search-config-contract` | 适用于不需要插件启用接线的提供商的狭义 web-search 配置/凭证辅助工具 |
-    | `plugin-sdk/provider-web-search-contract` | 狭义的 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及有作用域的凭证 setter/getter |
+    | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的窄范围 web-search 配置/凭证辅助工具 |
+    | `plugin-sdk/provider-web-search-contract` | 窄范围的 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及有作用域的凭证 setter/getter |
     | `plugin-sdk/provider-web-search` | Web 搜索提供商注册/缓存/运行时辅助工具 |
-    | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
-    | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似功能 |
-    | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 |
+    | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
+    | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似项 |
+    | `plugin-sdk/provider-stream` | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 |
     | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息转换和可写传输事件流 |
     | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 |
     | `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 |
@@ -144,35 +144,35 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
     | --- | --- |
     | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 |
     | `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` |
-    | `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天操作认证辅助工具 |
+    | `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天动作认证辅助工具 |
     | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤器辅助工具 |
     | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 |
     | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 |
-    | `plugin-sdk/approval-handler-adapter-runtime` | 用于热渠道入口点的轻量级原生审批适配器加载辅助工具 |
-    | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；如果更狭义的 adapter/gateway 接缝已足够，优先使用它们 |
+    | `plugin-sdk/approval-handler-adapter-runtime` | 面向高频渠道入口点的轻量级原生审批适配器加载辅助工具 |
+    | `plugin-sdk/approval-handler-runtime` | 范围更广的审批处理器运行时辅助工具；如果更窄的 adapter/gateway 接缝已足够，优先使用它们 |
     | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 |
     | `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助工具 |
     | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 |
     | `plugin-sdk/command-detection` | 共享命令检测辅助工具 |
     | `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助工具 |
     | `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
-    | `plugin-sdk/channel-secret-runtime` | 面向渠道/插件密钥表面的狭义密钥契约收集辅助工具 |
-    | `plugin-sdk/secret-ref-runtime` | 用于密钥契约/配置解析的狭义 `coerceSecretRef` 和 SecretRef 类型辅助工具 |
+    | `plugin-sdk/channel-secret-runtime` | 面向渠道/插件密钥表面的窄范围密钥契约收集辅助工具 |
+    | `plugin-sdk/secret-ref-runtime` | 面向密钥契约/配置解析的窄范围 `coerceSecretRef` 和 `SecretRef` 类型辅助工具 |
     | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和密钥收集辅助工具 |
     | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 |
-    | `plugin-sdk/ssrf-dispatcher` | 不带广泛基础设施运行时表面的狭义 pinned-dispatcher 辅助工具 |
+    | `plugin-sdk/ssrf-dispatcher` | 不带广泛基础设施运行时表面的窄范围 pinned-dispatcher 辅助工具 |
     | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch 和 SSRF 策略辅助工具 |
     | `plugin-sdk/secret-input` | 密钥输入解析辅助工具 |
-    | `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助工具 |
+    | `plugin-sdk/webhook-ingress` | webhook 请求/目标辅助工具 |
     | `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 |
   </Accordion>
 
   <Accordion title="运行时与存储子路径">
     | 子路径 | 关键导出 |
     | --- | --- |
-    | `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助工具 |
-    | `plugin-sdk/runtime-env` | 狭义的运行时 env、logger、timeout、retry 和 backoff 辅助工具 |
-    | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助工具 |
+    | `plugin-sdk/runtime` | 范围广泛的运行时/日志/备份/插件安装辅助工具 |
+    | `plugin-sdk/runtime-env` | 窄范围的运行时环境、logger、超时、重试和退避辅助工具 |
+    | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 |
     | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
     | `plugin-sdk/plugin-runtime` | 共享插件命令/hook/http/交互式辅助工具 |
     | `plugin-sdk/hook-runtime` | 共享 webhook/内部 hook 管道辅助工具 |
@@ -181,25 +181,25 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
     | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 |
     | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 |
     | `plugin-sdk/config-runtime` | 配置加载/写入辅助工具 |
-    | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化和重复/冲突检查，即使内置 Telegram 契约表面不可用时也适用 |
-    | `plugin-sdk/text-autolink-runtime` | 不带广泛 text-runtime barrel 的文件引用自动链接检测 |
+    | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化和重复/冲突检查，即使内置 Telegram 契约表面不可用时也能工作 |
+    | `plugin-sdk/text-autolink-runtime` | 不依赖广泛 text-runtime barrel 的文件引用自动链接检测 |
     | `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、认证/配置文件辅助工具、原生路由/运行时辅助工具 |
-    | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、heartbeat、回复规划器 |
-    | `plugin-sdk/reply-dispatch-runtime` | 狭义的回复分发/完成辅助工具 |
-    | `plugin-sdk/reply-history` | 共享短时间窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
+    | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、心跳、回复规划器 |
+    | `plugin-sdk/reply-dispatch-runtime` | 窄范围的回复分发/最终化辅助工具 |
+    | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
     | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
-    | `plugin-sdk/reply-chunking` | 狭义的文本/Markdown 分块辅助工具 |
+    | `plugin-sdk/reply-chunking` | 窄范围文本/Markdown 分块辅助工具 |
     | `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 |
-    | `plugin-sdk/state-paths` | state/OAuth 目录路径辅助工具 |
+    | `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助工具 |
     | `plugin-sdk/routing` | 路由/会话键/账户绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` |
     | `plugin-sdk/status-helpers` | 共享渠道/账户状态摘要辅助工具、运行时状态默认值和问题元数据辅助工具 |
     | `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助工具 |
     | `plugin-sdk/string-normalization-runtime` | slug/字符串规范化辅助工具 |
-    | `plugin-sdk/request-url` | 从 fetch/request 类输入中提取字符串 URL |
-    | `plugin-sdk/run-command` | 带计时功能的命令运行器，输出经规范化的 stdout/stderr 结果 |
+    | `plugin-sdk/request-url` | 从 fetch/类似 request 的输入中提取字符串 URL |
+    | `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化的 stdout/stderr 结果 |
     | `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 |
     | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 |
-    | `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 |
+    | `plugin-sdk/tool-send` | 从工具参数中提取规范化发送目标字段 |
     | `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 |
     | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 |
     | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助工具 |
@@ -207,30 +207,30 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
     | `plugin-sdk/file-lock` | 可重入文件锁辅助工具 |
     | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 |
     | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 |
-    | `plugin-sdk/acp-binding-resolve-runtime` | 不带生命周期启动导入的只读 ACP 绑定解析 |
-    | `plugin-sdk/agent-config-primitives` | 狭义的智能体运行时配置 schema 基元 |
+    | `plugin-sdk/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 |
+    | `plugin-sdk/agent-config-primitives` | 窄范围智能体运行时配置 schema 基元 |
     | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
     | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 |
-    | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 |
-    | `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助基元 |
+    | `plugin-sdk/device-bootstrap` | 设备 bootstrap 和配对令牌辅助工具 |
+    | `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助工具基元 |
     | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 |
-    | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 |
+    | `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助工具 |
     | `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 |
-    | `plugin-sdk/agent-harness` | 面向受信任插件的实验性低层智能体 harness 表面：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具以及尝试结果实用工具 |
-    | `plugin-sdk/provider-zai-endpoint` | Z.A.I 端点检测辅助工具 |
-    | `plugin-sdk/infra-runtime` | 系统事件/heartbeat 辅助工具 |
+    | `plugin-sdk/agent-harness` | 面向低级智能体 harness 的实验性受信任插件表面：harness 类型、活动运行引导/中止辅助工具、OpenClaw 工具桥接辅助工具和尝试结果实用工具 |
+    | `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 |
+    | `plugin-sdk/infra-runtime` | 系统事件/心跳辅助工具 |
     | `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 |
     | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 |
     | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` |
-    | `plugin-sdk/fetch-runtime` | 包装后的 fetch、proxy 和 pinned lookup 辅助工具 |
-    | `plugin-sdk/runtime-fetch` | 不带 proxy/guarded-fetch 导入的 dispatcher 感知型运行时 fetch |
-    | `plugin-sdk/response-limit-runtime` | 不带广泛 media 运行时表面的有界响应体读取器 |
-    | `plugin-sdk/session-binding-runtime` | 不带已配置绑定路由或配对存储的当前会话绑定状态 |
-    | `plugin-sdk/session-store-runtime` | 不带广泛配置写入/维护导入的会话存储读取辅助工具 |
-    | `plugin-sdk/context-visibility-runtime` | 不带广泛配置/安全导入的上下文可见性解析和补充上下文过滤 |
-    | `plugin-sdk/string-coerce-runtime` | 不带 Markdown/日志导入的狭义原始记录/字符串强制转换和规范化辅助工具 |
+    | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和 pinned 查找辅助工具 |
+    | `plugin-sdk/runtime-fetch` | 不引入 proxy/guarded-fetch 导入的 dispatcher 感知运行时 fetch |
+    | `plugin-sdk/response-limit-runtime` | 不依赖广泛媒体运行时表面的有界响应体读取器 |
+    | `plugin-sdk/session-binding-runtime` | 不包含已配置绑定路由或配对存储的当前会话绑定状态 |
+    | `plugin-sdk/session-store-runtime` | 不引入广泛配置写入/维护导入的会话存储读取辅助工具 |
+    | `plugin-sdk/context-visibility-runtime` | 不引入广泛配置/安全导入的上下文可见性解析和补充上下文过滤 |
+    | `plugin-sdk/string-coerce-runtime` | 不引入 Markdown/日志导入的窄范围原始记录/字符串强制转换与规范化辅助工具 |
     | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 |
-    | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 |
+    | `plugin-sdk/retry-runtime` | 重试配置和重试执行器辅助工具 |
     | `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 |
     | `plugin-sdk/directory-runtime` | 基于配置的目录查询/去重 |
     | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
@@ -242,11 +242,11 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
     | `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具，以及媒体负载构建器 |
     | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择和缺失模型消息 |
     | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 |
-    | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如面向 assistant 可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 |
+    | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如对智能体可见文本的剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本工具 |
     | `plugin-sdk/text-chunking` | 出站文本分块辅助工具 |
     | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助工具 |
     | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助工具 |
-    | `plugin-sdk/realtime-transcription` | 实时转录提供商类型和注册表辅助工具 |
+    | `plugin-sdk/realtime-transcription` | 实时转写提供商类型和注册表辅助工具 |
     | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 |
     | `plugin-sdk/image-generation` | 图像生成提供商类型 |
     | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助工具 |
@@ -254,8 +254,8 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
     | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 |
     | `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 |
     | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 |
-    | `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助工具 |
-    | `plugin-sdk/webhook-path` | Webhook 路径规范化辅助工具 |
+    | `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助工具 |
+    | `plugin-sdk/webhook-path` | webhook 路径规范化辅助工具 |
     | `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助工具 |
     | `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` |
     | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` |
@@ -264,12 +264,12 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
   <Accordion title="Memory 子路径">
     | 子路径 | 关键导出 |
     | --- | --- |
-    | `plugin-sdk/memory-core` | 内置 memory-core 辅助表面，用于 manager/config/file/CLI 辅助工具 |
-    | `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时外观 |
-    | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 |
-    | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商以及通用批处理/远程辅助工具 |
-    | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 |
-    | `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 |
+    | `plugin-sdk/memory-core` | 内置 `memory-core` 辅助工具表面，用于 manager/config/file/CLI 辅助工具 |
+    | `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时门面 |
+    | `plugin-sdk/memory-core-host-engine-foundation` | Memory host 基础引擎导出 |
+    | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商，以及通用批处理/远程辅助工具 |
+    | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD 引擎导出 |
+    | `plugin-sdk/memory-core-host-engine-storage` | Memory host 存储引擎导出 |
     | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 |
     | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 |
     | `plugin-sdk/memory-core-host-secret` | Memory host 密钥辅助工具 |
@@ -278,30 +278,30 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
     | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 |
     | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 |
     | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助工具 |
-    | `plugin-sdk/memory-host-core` | 面向厂商中立的 Memory host 核心运行时辅助工具别名 |
-    | `plugin-sdk/memory-host-events` | 面向厂商中立的 Memory host 事件日志辅助工具别名 |
-    | `plugin-sdk/memory-host-files` | 面向厂商中立的 Memory host 文件/运行时辅助工具别名 |
-    | `plugin-sdk/memory-host-markdown` | 用于与 memory 相邻插件的共享托管 Markdown 辅助工具 |
-    | `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活动 Memory 运行时外观 |
-    | `plugin-sdk/memory-host-status` | 面向厂商中立的 Memory host 状态辅助工具别名 |
-    | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助表面 |
+    | `plugin-sdk/memory-host-core` | 面向供应商中立的 memory host 核心运行时辅助工具别名 |
+    | `plugin-sdk/memory-host-events` | 面向供应商中立的 memory host 事件日志辅助工具别名 |
+    | `plugin-sdk/memory-host-files` | 面向供应商中立的 memory host 文件/运行时辅助工具别名 |
+    | `plugin-sdk/memory-host-markdown` | 面向 memory 邻接插件的共享托管 Markdown 辅助工具 |
+    | `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活动 Memory 运行时门面 |
+    | `plugin-sdk/memory-host-status` | 面向供应商中立的 memory host 状态辅助工具别名 |
+    | `plugin-sdk/memory-lancedb` | 内置 `memory-lancedb` 辅助工具表面 |
   </Accordion>
 
-  <Accordion title="保留的内置辅助子路径">
-    | 家族 | 当前子路径 | 预期用途 |
+  <Accordion title="保留的内置辅助工具子路径">
+    | 系列 | 当前子路径 | 预期用途 |
     | --- | --- | --- |
-    | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 browser 插件支持辅助工具（`browser-support` 仍是兼容性 barrel） |
-    | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时表面 |
-    | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时表面 |
-    | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助表面 |
-    | 渠道专用辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性/辅助接缝 |
-    | 认证/插件专用辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接缝；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
+    | Browser | `plugin-sdk/browser-cdp`、`plugin-sdk/browser-config-runtime`、`plugin-sdk/browser-config-support`、`plugin-sdk/browser-control-auth`、`plugin-sdk/browser-node-runtime`、`plugin-sdk/browser-profiles`、`plugin-sdk/browser-security-runtime`、`plugin-sdk/browser-setup-tools`、`plugin-sdk/browser-support` | 内置 Browser 插件支持辅助工具（`browser-support` 仍为兼容性 barrel） |
+    | Matrix | `plugin-sdk/matrix`、`plugin-sdk/matrix-helper`、`plugin-sdk/matrix-runtime-heavy`、`plugin-sdk/matrix-runtime-shared`、`plugin-sdk/matrix-runtime-surface`、`plugin-sdk/matrix-surface`、`plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助工具/运行时表面 |
+    | Line | `plugin-sdk/line`、`plugin-sdk/line-core`、`plugin-sdk/line-runtime`、`plugin-sdk/line-surface` | 内置 LINE 辅助工具/运行时表面 |
+    | IRC | `plugin-sdk/irc`、`plugin-sdk/irc-surface` | 内置 IRC 辅助工具表面 |
+    | 特定于渠道的辅助工具 | `plugin-sdk/googlechat`、`plugin-sdk/zalouser`、`plugin-sdk/bluebubbles`、`plugin-sdk/bluebubbles-policy`、`plugin-sdk/mattermost`、`plugin-sdk/mattermost-policy`、`plugin-sdk/feishu-conversation`、`plugin-sdk/msteams`、`plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、`plugin-sdk/twitch` | 内置渠道兼容性/辅助工具接缝 |
+    | 认证/特定于插件的辅助工具 | `plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、`plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/thread-ownership`、`plugin-sdk/voice-call` | 内置功能/插件辅助工具接缝；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
   </Accordion>
 </AccordionGroup>
 
 ## 注册 API
 
-`register(api)` 回调会接收一个带有以下方法的 `OpenClawPluginApi` 对象：
+`register(api)` 回调会接收一个带有这些方法的 `OpenClawPluginApi` 对象：
 
 ### 能力注册
 
@@ -312,16 +312,16 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
 | `api.registerCliBackend(...)`                    | 本地 CLI 推理后端 |
 | `api.registerChannel(...)`                       | 消息渠道 |
 | `api.registerSpeechProvider(...)`                | 文本转语音 / STT 合成 |
-| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 |
-| `api.registerRealtimeVoiceProvider(...)`         | 双向实时语音会话 |
+| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转写 |
+| `api.registerRealtimeVoiceProvider(...)`         | 双工实时语音会话 |
 | `api.registerMediaUnderstandingProvider(...)`    | 图像/音频/视频分析 |
 | `api.registerImageGenerationProvider(...)`       | 图像生成 |
 | `api.registerMusicGenerationProvider(...)`       | 音乐生成 |
 | `api.registerVideoGenerationProvider(...)`       | 视频生成 |
-| `api.registerWebFetchProvider(...)`              | Web 抓取 / 抓取提供商 |
+| `api.registerWebFetchProvider(...)`              | Web 抓取 / scrape 提供商 |
 | `api.registerWebSearchProvider(...)`             | Web 搜索 |
 
-### 工具和命令
+### 工具与命令
 
 | 方法 | 注册内容 |
 | ------------------------------- | --------------------------------------------- |
@@ -338,22 +338,22 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
 | `api.registerCli(registrar, opts?)`             | CLI 子命令 |
 | `api.registerService(service)`                  | 后台服务 |
 | `api.registerInteractiveHandler(registration)`  | 交互式处理器 |
-| `api.registerEmbeddedExtensionFactory(factory)` | Pi 内嵌运行器扩展工厂 |
-| `api.registerMemoryPromptSupplement(builder)`   | 可叠加的 memory 相邻提示区段 |
-| `api.registerMemoryCorpusSupplement(adapter)`   | 可叠加的 memory 搜索/读取语料库 |
+| `api.registerEmbeddedExtensionFactory(factory)` | Pi 嵌入式运行器扩展工厂 |
+| `api.registerMemoryPromptSupplement(builder)`   | 可叠加的 memory 邻接提示词区段 |
+| `api.registerMemoryCorpusSupplement(adapter)`   | 可叠加的 Memory 搜索/读取语料库 |
 
-保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件拥有的方法，优先使用插件专属前缀。
+保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用特定于插件的前缀。
 
-当插件在 OpenClaw 内嵌运行期间需要 Pi 原生事件时序时，请使用 `api.registerEmbeddedExtensionFactory(...)`，例如必须在最终工具结果消息发出之前完成的异步 `tool_result` 重写。这目前是一个内置插件接缝：只有内置插件可以注册它，并且它们必须在 `openclaw.plugin.json` 中声明 `contracts.embeddedExtensionFactories: ["pi"]`。对于不需要该更底层接缝的所有情况，继续使用普通 OpenClaw 插件 hooks。
+当插件在 OpenClaw 嵌入式运行期间需要 Pi 原生事件时序时，请使用 `api.registerEmbeddedExtensionFactory(...)`，例如必须在最终工具结果消息发出之前完成的异步 `tool_result` 重写。这目前是一个内置插件接缝：只有内置插件可以注册它，并且它们必须在 `openclaw.plugin.json` 中声明 `contracts.embeddedExtensionFactories: ["pi"]`。对于不需要这种更低层接缝的情况，请继续使用普通 OpenClaw 插件 hook。
 
 ### CLI 注册元数据
 
 `api.registerCli(registrar, opts?)` 接受两类顶层元数据：
 
-- `commands`：由 registrar 拥有的显式命令根
+- `commands`：由该注册器拥有的显式命令根
 - `descriptors`：用于根 CLI 帮助、路由和惰性插件 CLI 注册的解析时命令描述符
 
-如果你希望插件命令在正常的根 CLI 路径中保持惰性加载，请提供 `descriptors`，覆盖该 registrar 暴露的每个顶层命令根。
+如果你希望一个插件命令在普通根 CLI 路径中保持惰性加载，请提供覆盖该注册器公开的每个顶层命令根的 `descriptors`。
 
 ```typescript
 api.registerCli(
@@ -373,7 +373,7 @@ api.registerCli(
 );
 ```
 
-只有在你不需要惰性根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍受支持，但它不会为解析时惰性加载安装基于 descriptor 的占位符。
+仅在你不需要惰性根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍受支持，但它不会安装基于描述符的占位符来实现解析时惰性加载。
 
 ### CLI 后端注册
 
@@ -381,30 +381,30 @@ api.registerCli(
 
 - 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。
 - 后端 `config` 使用与 `agents.defaults.cliBackends.<id>` 相同的结构。
-- 用户配置仍然优先。OpenClaw 会在运行 CLI 之前，将 `agents.defaults.cliBackends.<id>` 合并到插件默认值之上。
-- 当后端在合并后需要兼容性重写时，请使用 `normalizeConfig`（例如规范化旧版 flag 结构）。
+- 用户配置仍然优先。OpenClaw 会先将 `agents.defaults.cliBackends.<id>` 合并到插件默认值之上，然后再运行 CLI。
+- 当后端在合并后需要兼容性重写时，请使用 `normalizeConfig`（例如将旧的 flag 结构规范化）。
 
 ### 独占槽位
 
 | 方法 | 注册内容 |
 | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `api.registerContextEngine(id, factory)`   | 上下文引擎（一次只激活一个）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便引擎可以定制提示补充内容。 |
+| `api.registerContextEngine(id, factory)`   | 上下文引擎（一次仅一个处于活动状态）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便该引擎定制提示词附加内容。 |
 | `api.registerMemoryCapability(capability)` | 统一 Memory 能力 |
-| `api.registerMemoryPromptSection(builder)` | Memory 提示区段构建器 |
-| `api.registerMemoryFlushPlan(resolver)`    | Memory flush plan 解析器 |
+| `api.registerMemoryPromptSection(builder)` | Memory 提示词区段构建器 |
+| `api.registerMemoryFlushPlan(resolver)`    | Memory 刷新计划解析器 |
 | `api.registerMemoryRuntime(runtime)`       | Memory 运行时适配器 |
 
 ### Memory embedding 适配器
 
 | 方法 | 注册内容 |
 | ---------------------------------------------- | ---------------------------------------------- |
-| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory embedding 适配器 |
+| `api.registerMemoryEmbeddingProvider(adapter)` | 当前活动插件的 Memory embedding 适配器 |
 
-- `registerMemoryCapability` 是首选的独占 Memory 插件 API。
-- `registerMemoryCapability` 还可以暴露 `publicArtifacts.listArtifacts(...)`，这样配套插件就可以通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的 Memory 工件，而不是深入某个特定 Memory 插件的私有布局。
-- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占 Memory 插件 API。
-- `registerMemoryEmbeddingProvider` 允许活动 Memory 插件注册一个或多个 embedding 适配器 ID（例如 `openai`、`gemini` 或插件自定义的 ID）。
-- 用户配置（例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会针对这些已注册的适配器 ID 进行解析。
+- `registerMemoryCapability` 是首选的独占式 Memory 插件 API。
+- `registerMemoryCapability` 也可以公开 `publicArtifacts.listArtifacts(...)`，这样配套插件就可以通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的 Memory 工件，而不是深入某个特定 Memory 插件的私有布局。
+- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占式 Memory 插件 API。
+- `registerMemoryEmbeddingProvider` 允许活动 Memory 插件注册一个或多个 embedding 适配器 id（例如 `openai`、`gemini` 或插件自定义的 id）。
+- 用户配置（如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会基于这些已注册的适配器 id 进行解析。
 
 ### 事件与生命周期
 
@@ -415,72 +415,72 @@ api.registerCli(
 
 ### Hook 决策语义
 
-- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任一处理器设置了它，就会跳过较低优先级的处理器。
+- `before_tool_call`：返回 `{ block: true }` 为终止性决定。一旦任何处理器设置了它，就会跳过更低优先级的处理器。
 - `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。
-- `before_install`：返回 `{ block: true }` 是终止性的。一旦任一处理器设置了它，就会跳过较低优先级的处理器。
+- `before_install`：返回 `{ block: true }` 为终止性决定。一旦任何处理器设置了它，就会跳过更低优先级的处理器。
 - `before_install`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。
-- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任一处理器声明接管分发，就会跳过较低优先级的处理器和默认模型分发路径。
-- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任一处理器设置了它，就会跳过较低优先级的处理器。
+- `reply_dispatch`：返回 `{ handled: true, ... }` 为终止性决定。一旦任何处理器声明已处理分发，就会跳过更低优先级的处理器以及默认模型分发路径。
+- `message_sending`：返回 `{ cancel: true }` 为终止性决定。一旦任何处理器设置了它，就会跳过更低优先级的处理器。
 - `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（与省略 `cancel` 相同），而不是覆盖。
+- `message_received`：当你需要入站线程/话题路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给特定于渠道的额外信息。
+- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，再回退到特定于渠道的 `metadata`。
 
 ### API 对象字段
 
 | 字段 | 类型 | 描述 |
 | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
-| `api.id`                 | `string`                  | 插件 ID |
+| `api.id`                 | `string`                  | 插件 id |
 | `api.name`               | `string`                  | 显示名称 |
 | `api.version`            | `string?`                 | 插件版本（可选） |
 | `api.description`        | `string?`                 | 插件描述（可选） |
 | `api.source`             | `string`                  | 插件源路径 |
 | `api.rootDir`            | `string?`                 | 插件根目录（可选） |
 | `api.config`             | `OpenClawConfig`          | 当前配置快照（可用时为活动内存运行时快照） |
-| `api.pluginConfig`       | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专属配置 |
+| `api.pluginConfig`       | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的特定于插件的配置 |
 | `api.runtime`            | `PluginRuntime`           | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) |
-| `api.logger`             | `PluginLogger`            | 有作用域的 logger（`debug`、`info`、`warn`、`error`） |
-| `api.registrationMode`   | `PluginRegistrationMode`  | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置前的轻量窗口 |
+| `api.logger`             | `PluginLogger`            | 作用域 logger（`debug`、`info`、`warn`、`error`） |
+| `api.registrationMode`   | `PluginRegistrationMode`  | 当前加载模式；`"setup-runtime"` 是完整入口点启动/设置前的轻量级窗口 |
 | `api.resolvePath(input)` | `(string) => string`      | 解析相对于插件根目录的路径 |
 
 ## 内部模块约定
 
-在你的插件内部，使用本地 barrel 文件进行内部导入：
+在你的插件内部，请使用本地 barrel 文件进行内部导入：
 
 ```
 my-plugin/
-  api.ts            # 面向外部使用者的公开导出
+  api.ts            # 供外部使用者使用的公开导出
   runtime-api.ts    # 仅供内部使用的运行时导出
   index.ts          # 插件入口点
-  setup-entry.ts    # 仅设置用的轻量入口（可选）
+  setup-entry.ts    # 仅用于轻量级设置的入口点（可选）
 ```
 
 <Warning>
-  不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>`
+  永远不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>`
   导入你自己的插件。请通过 `./api.ts` 或
-  `./runtime-api.ts` 路由内部导入。SDK 路径仅是外部契约。
+  `./runtime-api.ts` 路由内部导入。SDK 路径只是外部契约。
 </Warning>
 
-通过 facade 加载的内置插件公开表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公开入口文件）现在会在 OpenClaw 已经运行时优先使用活动运行时配置快照。如果运行时快照尚不存在，则会回退到磁盘上已解析的配置文件。
+由门面加载的内置插件公开表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）现在在 OpenClaw 已经运行时会优先使用活动运行时配置快照。如果尚不存在运行时快照，则会回退到磁盘上解析出的配置文件。
 
-当某个辅助工具是有意保持提供商专属、且暂时还不适合放入通用 SDK 子路径时，提供商插件也可以暴露一个狭义的插件本地契约 barrel。当前内置示例：Anthropic 提供商将其 Claude 流辅助工具保留在自己的公开 `api.ts` / `contract-api.ts` 接缝中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升到通用 `plugin-sdk/*` 契约中。
+当某个辅助工具有意保持为提供商特定、且尚不适合放入通用 SDK 子路径时，提供商插件也可以公开一个窄范围的插件本地契约 barrel。当前的内置示例：Anthropic 提供商将其 Claude 流辅助工具保留在自己的公开 `api.ts` / `contract-api.ts` 接缝中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升到通用 `plugin-sdk/*` 契约中。
 
-其他当前内置示例：
+其他当前的内置示例：
 
-- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、
-  默认模型辅助工具以及实时提供商构建器
-- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及
-  新手引导/配置辅助工具
+- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、默认模型辅助工具和实时提供商构建器
+- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及新手引导/配置辅助工具
 
 <Warning>
   扩展生产代码也应避免导入 `openclaw/plugin-sdk/<other-plugin>`。
-  如果某个辅助工具确实需要共享，请将它提升到中立的 SDK 子路径，
-  例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他
-  面向能力的表面，而不是把两个插件耦合在一起。
+  如果某个辅助工具确实需要共享，请将其提升到一个中立的 SDK 子路径，
+  例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他
+  面向能力的表面，而不是将两个插件耦合在一起。
 </Warning>
 
 ## 相关内容
 
 - [入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry` 选项
 - [运行时辅助工具](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考
-- [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、清单、配置 schema
-- [测试](/zh-CN/plugins/sdk-testing) — 测试实用工具和 lint 规则
+- [设置与配置](/zh-CN/plugins/sdk-setup) — 打包、清单、配置 schema
+- [测试](/zh-CN/plugins/sdk-testing) — 测试工具和 lint 规则
 - [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用表面迁移
 - [插件内部机制](/zh-CN/plugins/architecture) — 深入架构和能力模型