From 66dd652e7d8511af7a5bf3ac76b95fa56bacbf20 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 7 Apr 2026 20:11:24 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/plugins/architecture.md | 958 ++++++++++++---------- docs/zh-CN/plugins/sdk-channel-plugins.md | 229 +++--- docs/zh-CN/plugins/sdk-migration.md | 320 ++++---- docs/zh-CN/plugins/sdk-overview.md | 325 ++++---- 4 files changed, 941 insertions(+), 891 deletions(-) diff --git a/docs/zh-CN/plugins/architecture.md b/docs/zh-CN/plugins/architecture.md index f81cd1845..576d72238 100644 --- a/docs/zh-CN/plugins/architecture.md +++ b/docs/zh-CN/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - - 构建或调试原生 OpenClaw 插件时 - - 了解插件能力模型或所有权边界时 - - 处理插件加载流水线或注册表时 - - 实现 provider 运行时 hook 或渠道插件时 + - 构建或调试原生 OpenClaw 插件 + - 理解插件能力模型或所有权边界 + - 处理插件加载流水线或注册表 + - 实现提供商运行时钩子或渠道插件 sidebarTitle: Internals -summary: 插件内部机制：能力模型、所有权、契约、加载流水线与运行时辅助工具 +summary: 插件内部机制：能力模型、所有权、契约、加载流水线和运行时辅助工具 title: 插件内部机制 x-i18n: - generated_at: "2026-04-07T18:45:24Z" + generated_at: "2026-04-07T20:11:24Z" model: gpt-5.4 provider: openai - source_hash: fc5a62710390dc6ad064b818222c1bb7609b3d076741f80bb5bbd9edb90342f1 + source_hash: c40ecf14e2a0b2b8d332027aed939cd61fb4289a489f4cd4c076c96d707d1138 source_path: plugins/architecture.md workflow: 15 --- @@ -24,16 +24,16 @@ x-i18n: - [入门指南](/zh-CN/plugins/building-plugins) — 第一个插件教程 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建消息渠道 - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建模型提供商 - - [SDK 概览](/zh-CN/plugins/sdk-overview) — 导入映射与注册 API + - [SDK 概览](/zh-CN/plugins/sdk-overview) — 导入映射和注册 API 本页介绍 OpenClaw 插件系统的内部架构。 ## 公共能力模型 -能力是 OpenClaw 内部公开的**原生插件**模型。每个原生 OpenClaw 插件都会针对一种或多种能力类型进行注册： +能力是 OpenClaw 内部公共的**原生插件**模型。每个原生 OpenClaw 插件都会针对一种或多种能力类型进行注册： -| 能力 | 注册方式 | 示例插件 | +| 能力 | 注册方法 | 示例插件 | | ---------------------- | ------------------------------------------------ | ------------------------------------ | | 文本推理 | `api.registerProvider(...)` | `openai`, `anthropic` | | CLI 推理后端 | `api.registerCliBackend(...)` | `openai`, `anthropic` | @@ -46,48 +46,48 @@ x-i18n: | 视频生成 | `api.registerVideoGenerationProvider(...)` | `qwen` | | Web 抓取 | `api.registerWebFetchProvider(...)` | `firecrawl` | | Web 搜索 | `api.registerWebSearchProvider(...)` | `google` | -| 渠道 / 消息 | `api.registerChannel(...)` | `msteams`, `matrix` | +| 渠道 / 消息传递 | `api.registerChannel(...)` | `msteams`, `matrix` | -一个注册了零个能力、但提供 hooks、工具或服务的插件，属于**传统仅 hook**插件。该模式仍然被完全支持。 +一个注册了零个能力，但提供钩子、工具或服务的插件，属于**仅旧版钩子**插件。该模式仍然受到完整支持。 ### 外部兼容性立场 -能力模型已经落地到核心中，并已被当前的内置/原生插件使用，但外部插件兼容性仍需要比“它被导出了，所以它就是冻结的”更严格的标准。 +能力模型已经在核心中落地，并且如今已被内置 / 原生插件使用，但外部插件兼容性仍需要比“它已导出，所以它被冻结了”更严格的标准。 -当前指引： +当前指导如下： -- **现有外部插件：** 保持基于 hook 的集成继续可用；将其视为兼容性基线 -- **新的内置/原生插件：** 优先使用显式能力注册，而不是 vendor 特定的深层调用或新的仅 hook 设计 -- **采用能力注册的外部插件：** 允许，但除非文档明确将某个契约标记为稳定，否则应将能力专用辅助接口视为仍在演进中 +- **现有外部插件：**保持基于钩子的集成继续可用；将此视为兼容性基线 +- **新的内置 / 原生插件：**优先使用显式能力注册，而不是供应商特定的深层调用或新的仅钩子设计 +- **采用能力注册的外部插件：**允许，但除非文档明确将某个契约标记为稳定，否则应将能力特定的辅助工具表面视为仍在演进中 -实际规则： +实践规则： - 能力注册 API 是预期的发展方向 -- 在过渡期间，传统 hooks 仍是外部插件最稳妥、最不易破坏的路径 -- 被导出的辅助子路径并不都一样；优先使用文档化的窄契约，而不是偶然暴露的辅助导出 +- 在过渡期间，旧版钩子仍然是外部插件最安全、最不易破坏的路径 +- 已导出的辅助工具子路径并不完全等价；优先使用范围更窄、已有文档说明的契约，而不是偶然暴露出的辅助工具导出 ### 插件形态 -OpenClaw 会根据每个已加载插件的实际注册行为来将其归类为某种形态（而不只是看静态元数据）： +OpenClaw 会根据每个已加载插件的实际注册行为，而不只是静态元数据，将其归类为一种形态： -- **plain-capability** -- 只注册一种能力类型（例如仅 provider 插件 `mistral`） -- **hybrid-capability** -- 注册多种能力类型（例如 `openai` 同时拥有文本推理、语音、媒体理解和图像生成） -- **hook-only** -- 只注册 hooks（类型化或自定义），没有能力、工具、命令或服务 -- **non-capability** -- 注册工具、命令、服务或路由，但不注册能力 +- **plain-capability** —— 恰好注册一种能力类型（例如仅提供商插件 `mistral`） +- **hybrid-capability** —— 注册多种能力类型（例如 `openai` 拥有文本推理、语音、媒体理解和图像生成） +- **hook-only** —— 仅注册钩子（类型化或自定义），不注册能力、工具、命令或服务 +- **non-capability** —— 注册工具、命令、服务或路由，但不注册能力 -使用 `openclaw plugins inspect ` 可查看插件的形态及能力拆分。详情参见 [CLI 参考](/cli/plugins#inspect)。 +使用 `openclaw plugins inspect ` 可查看插件的形态和能力明细。详见 [CLI 参考](/cli/plugins#inspect)。 -### 传统 hooks +### 旧版钩子 -`before_agent_start` hook 仍作为仅 hook 插件的兼容性路径被支持。现实中仍有传统插件依赖它。 +`before_agent_start` 钩子仍作为仅钩子插件的兼容路径受到支持。现实中的旧版插件仍依赖它。 -方向： +方向如下： - 保持其可用 -- 将其文档标记为传统方式 -- 对于模型/provider 覆盖工作，优先使用 `before_model_resolve` +- 将其记录为旧版 +- 对于模型 / 提供商覆盖工作，优先使用 `before_model_resolve` - 对于提示词变更工作，优先使用 `before_prompt_build` -- 只有在真实使用量下降，且固定装置覆盖证明迁移安全之后，才考虑移除 +- 只有在实际使用量下降并且夹具覆盖证明迁移安全后才移除 ### 兼容性信号 @@ -95,53 +95,53 @@ OpenClaw 会根据每个已加载插件的实际注册行为来将其归类为 | 信号 | 含义 | | -------------------------- | ------------------------------------------------------------ | -| **config valid** | 配置解析正常，插件可正常解析 | -| **compatibility advisory** | 插件使用的是受支持但较旧的模式（例如 `hook-only`） | -| **legacy warning** | 插件使用 `before_agent_start`，该方式已弃用 | +| **config valid** | 配置解析正常且插件可解析 | +| **compatibility advisory** | 插件使用受支持但较旧的模式（例如 `hook-only`） | +| **legacy warning** | 插件使用 `before_agent_start`，该接口已弃用 | | **hard error** | 配置无效或插件加载失败 | -`hook-only` 和 `before_agent_start` 当前都不会破坏你的插件——`hook-only` 只是提示，而 `before_agent_start` 只会触发警告。这些信号也会出现在 `openclaw status --all` 和 `openclaw plugins doctor` 中。 +当前，`hook-only` 和 `before_agent_start` 都不会导致你的插件损坏——`hook-only` 只是提示信息，而 `before_agent_start` 只会触发警告。这些信号也会出现在 `openclaw status --all` 和 `openclaw plugins doctor` 中。 ## 架构概览 -OpenClaw 的插件系统分为四层： +OpenClaw 的插件系统有四层： -1. **Manifest + 设备发现** - OpenClaw 会从已配置路径、workspace 根目录、全局扩展根目录以及内置扩展中查找候选插件。设备发现会先读取原生 `openclaw.plugin.json` manifest 以及受支持的 bundle manifest。 +1. **清单 + 发现** + OpenClaw 会从已配置路径、工作区根目录、全局扩展根目录和内置扩展中查找候选插件。发现阶段会优先读取原生 `openclaw.plugin.json` 清单以及受支持的 bundle 清单。 2. **启用 + 验证** - 核心会决定某个已发现插件是启用、禁用、阻止，还是被选入类似内存这样的独占槽位。 + 核心决定某个已发现的插件是启用、禁用、阻止，还是被选中用于某个独占槽位，例如 memory。 3. **运行时加载** - 原生 OpenClaw 插件通过 jiti 在进程内加载，并将能力注册到中央注册表中。兼容 bundle 会被规范化为注册表记录，而无需导入运行时代码。 -4. **接口消费** - OpenClaw 的其余部分会读取注册表，以暴露工具、渠道、provider 设置、hooks、HTTP 路由、CLI 命令和服务。 + 原生 OpenClaw 插件通过 jiti 在进程内加载，并将能力注册到中央注册表中。兼容 bundle 会在不导入运行时代码的情况下被规范化为注册表记录。 +4. **表面消费** + OpenClaw 的其余部分读取注册表，以暴露工具、渠道、提供商设置、钩子、HTTP 路由、CLI 命令和服务。 -对于插件 CLI，本身的根命令发现分为两个阶段： +专门针对插件 CLI，根命令发现分为两个阶段： -- 解析期元数据来自 `registerCli(..., { descriptors: [...] })` -- 真正的插件 CLI 模块可以保持惰性，并在首次调用时再注册 +- 解析阶段元数据来自 `registerCli(..., { descriptors: [...] })` +- 真正的插件 CLI 模块可以保持延迟加载，并在首次调用时完成注册 -这样既能让插件拥有自己的 CLI 代码，又能让 OpenClaw 在解析前预留根命令名称。 +这样可以让插件自有的 CLI 代码保留在插件内部，同时仍然让 OpenClaw 在解析前预留根命令名称。 -重要的设计边界： +重要的设计边界是： -- 设备发现 + 配置验证应基于**manifest/schema 元数据**工作，而不执行插件代码 +- 发现 + 配置验证应基于**清单 / schema 元数据**完成，而不执行插件代码 - 原生运行时行为来自插件模块的 `register(api)` 路径 -这种拆分使 OpenClaw 能在完整运行时尚未激活前，就完成配置验证、解释缺失/已禁用插件，并构建 UI/schema 提示。 +这种拆分使 OpenClaw 能在完整运行时尚未激活前，验证配置、解释缺失 / 已禁用的插件，并构建 UI / schema 提示。 -### 渠道插件与共享 message 工具 +### 渠道插件和共享 message 工具 -渠道插件在正常聊天操作中，不需要单独注册发送/编辑/回应工具。OpenClaw 在核心中保留一个共享的 `message` 工具，而渠道插件则负责其背后的渠道特定发现与执行。 +对于常规聊天操作，渠道插件不需要单独注册发送 / 编辑 / 反应工具。OpenClaw 在核心中保留了一个共享的 `message` 工具，而渠道插件负责其背后的渠道特定发现和执行。 当前边界如下： -- 核心负责共享 `message` 工具宿主、提示词接线、会话/线程记录，以及执行分发 -- 渠道插件负责作用域内动作发现、能力发现，以及所有渠道特定 schema 片段 -- 渠道插件负责 provider 特定的会话对话语法，例如会话 id 如何编码线程 id，或如何从父会话继承 -- 渠道插件通过其动作适配器执行最终动作 +- 核心拥有共享 `message` 工具宿主、提示词接线、会话 / 线程簿记以及执行分发 +- 渠道插件拥有作用域动作发现、能力发现以及任何渠道特定的 schema 片段 +- 渠道插件拥有提供商特定的会话对话语法，例如对话 id 如何编码线程 id 或从父对话继承 +- 渠道插件通过自己的动作适配器执行最终动作 -对于渠道插件，SDK 接口为 -`ChannelMessageActionAdapter.describeMessageTool(...)`。这个统一的发现调用允许插件一并返回其可见动作、能力和 schema 贡献，从而避免这些部分发生漂移。 +对于渠道插件，SDK 表面是 +`ChannelMessageActionAdapter.describeMessageTool(...)`。这个统一的发现调用让插件可以一起返回其可见动作、能力和 schema 贡献，从而避免这些部分发生漂移。 核心会将运行时作用域传入该发现步骤。重要字段包括： @@ -154,84 +154,84 @@ OpenClaw 的插件系统分为四层： - `agentId` - 受信任的入站 `requesterSenderId` -这对上下文敏感型插件非常重要。渠道可以根据当前账户、当前房间/线程/消息，或受信任的请求者身份，来隐藏或暴露消息动作，而无需在核心 `message` 工具中硬编码渠道特定分支。 +这对依赖上下文的插件很重要。一个渠道可以根据活动账户、当前房间 / 线程 / 消息，或受信任的请求方身份，隐藏或暴露消息动作，而无需在核心 `message` 工具中硬编码渠道特定分支。 -这也是为什么嵌入式 runner 路由变更仍然属于插件工作：runner 负责把当前聊天/会话身份转发到插件发现边界，使共享 `message` 工具能在当前轮次暴露正确的渠道自有接口。 +这也是为什么嵌入式运行器路由变更仍然属于插件工作：运行器负责将当前聊天 / 会话身份转发到插件发现边界，从而让共享 `message` 工具在当前轮次暴露正确的渠道自有表面。 -对于渠道自有执行辅助工具，内置插件应将执行运行时保留在自己的扩展模块内。核心不再拥有位于 `src/agents/tools` 下的 Discord、Slack、Telegram 或 WhatsApp 消息动作运行时。我们不会发布单独的 `plugin-sdk/*-action-runtime` 子路径，内置插件应直接从其自有扩展模块导入本地运行时代码。 +对于渠道自有的执行辅助工具，内置插件应将执行运行时保留在它们自己的扩展模块中。核心不再拥有 `src/agents/tools` 下的 Discord、Slack、Telegram 或 WhatsApp 消息动作运行时。我们不会发布单独的 `plugin-sdk/*-action-runtime` 子路径，内置插件应直接从其扩展自有模块导入自己的本地运行时代码。 -同样的边界也适用于一般的 provider 命名 SDK 接缝：核心不应导入 Slack、Discord、Signal、WhatsApp 或类似扩展的渠道特定便捷 barrel。如果核心需要某种行为，要么使用内置插件自己的 `api.ts` / `runtime-api.ts` barrel，要么将该需求提升为共享 SDK 中的窄而通用的能力。 +同样的边界通常也适用于以提供商命名的 SDK 接缝：核心不应导入面向 Slack、Discord、Signal、WhatsApp 或类似扩展的渠道特定便利 barrel。如果核心需要某种行为，要么使用内置插件自己的 `api.ts` / `runtime-api.ts` barrel，要么将该需求提升为共享 SDK 中一个范围更窄的通用能力。 -对于投票，当前有两条执行路径： +对于投票，存在两条执行路径： -- `outbound.sendPoll` 是适用于通用投票模型渠道的共享基线 +- `outbound.sendPoll` 是适用于符合通用投票模型渠道的共享基线 - `actions.handleAction("poll")` 是用于渠道特定投票语义或额外投票参数的首选路径 -现在，核心会在插件投票分发拒绝该动作之后，才延迟进行共享投票解析，因此插件自有投票处理器可以接受渠道特定的投票字段，而不会先被通用投票解析器拦住。 +现在，核心会在插件投票分发拒绝该动作后，才延迟进行共享投票解析，因此插件自有的投票处理器可以接受渠道特定的投票字段，而不会先被通用投票解析器拦住。 -完整启动顺序请参见 [加载流水线](#load-pipeline)。 +完整启动顺序请参阅 [加载流水线](#load-pipeline)。 ## 能力所有权模型 -OpenClaw 将原生插件视为一个**公司**或一个**功能**的所有权边界，而不是无关集成的大杂烩。 +OpenClaw 将原生插件视为**公司**或**功能**的所有权边界，而不是无关集成的杂物袋。 这意味着： -- 一个公司插件通常应拥有该公司的所有 OpenClaw 对外接口 -- 一个功能插件通常应拥有其引入的完整功能接口 -- 渠道应消费共享的核心能力，而不是临时自行实现 provider 行为 +- 一个公司插件通常应拥有该公司面向 OpenClaw 的全部表面 +- 一个功能插件通常应拥有其引入的完整功能表面 +- 渠道应消费共享核心能力，而不是临时重新实现提供商行为 示例： -- 内置 `openai` 插件拥有 OpenAI 模型 provider 行为，以及 OpenAI 语音 + 实时语音 + 媒体理解 + 图像生成行为 +- 内置 `openai` 插件拥有 OpenAI 模型提供商行为，以及 OpenAI 的语音 + 实时语音 + 媒体理解 + 图像生成行为 - 内置 `elevenlabs` 插件拥有 ElevenLabs 语音行为 - 内置 `microsoft` 插件拥有 Microsoft 语音行为 -- 内置 `google` 插件拥有 Google 模型 provider 行为，以及 Google 媒体理解 + 图像生成 + Web 搜索行为 +- 内置 `google` 插件拥有 Google 模型提供商行为，以及 Google 的媒体理解 + 图像生成 + Web 搜索行为 - 内置 `firecrawl` 插件拥有 Firecrawl Web 抓取行为 -- 内置 `minimax`、`mistral`、`moonshot` 和 `zai` 插件拥有其媒体理解后端 -- `voice-call` 插件是一个功能插件：它拥有通话传输、工具、CLI、路由和 Twilio 媒体流桥接，但它消费共享的语音、实时转录和实时语音能力，而不是直接导入 vendor 插件 +- 内置 `minimax`、`mistral`、`moonshot` 和 `zai` 插件拥有它们各自的媒体理解后端 +- `voice-call` 插件是一个功能插件：它拥有通话传输、工具、CLI、路由和 Twilio 媒体流桥接，但它消费共享的语音、实时转录和实时语音能力，而不是直接导入供应商插件 预期的最终状态是： -- 即便 OpenAI 横跨文本模型、语音、图像和未来的视频，也都集中在一个插件里 -- 其他 vendor 也可以用同样方式管理自己的接口范围 -- 渠道不关心哪个 vendor 插件拥有该 provider；它们只消费核心暴露的共享能力契约 +- OpenAI 即使横跨文本模型、语音、图像和未来视频，也只存在于一个插件中 +- 其他供应商也可以对自己的表面采用相同方式 +- 渠道不关心哪个供应商插件拥有该提供商；它们消费的是核心暴露出来的共享能力契约 这是关键区别： - **plugin** = 所有权边界 -- **capability** = 可被多个插件实现或消费的核心契约 +- **capability** = 多个插件都可实现或消费的核心契约 -因此，如果 OpenClaw 增加一个新领域，比如视频，首要问题不是“哪个 provider 应该硬编码处理视频？”首要问题是“核心的视频能力契约是什么？”一旦该契约存在，vendor 插件就可以注册实现，而渠道/功能插件则可以消费它。 +因此，如果 OpenClaw 新增一个如视频这样的领域，首先不该问“哪个提供商应该硬编码视频处理？”而应该问“核心的视频能力契约是什么？”一旦这个契约存在，供应商插件就可以针对它注册，而渠道 / 功能插件也可以消费它。 如果该能力尚不存在，通常正确的做法是： 1. 在核心中定义缺失的能力 -2. 通过插件 API/运行时以类型化方式暴露它 -3. 让渠道/功能对接这个能力 -4. 让 vendor 插件注册实现 +2. 通过插件 API / 运行时以类型化方式暴露它 +3. 让渠道 / 功能围绕该能力接线 +4. 让供应商插件注册实现 -这样既能保持所有权明确，又能避免核心行为依赖某个单一 vendor 或某条一次性的插件专用代码路径。 +这样可以保持所有权清晰，同时避免核心行为依赖单一供应商或某条一次性的插件特定代码路径。 ### 能力分层 -在决定代码归属时，可以使用这个思维模型： +当你决定代码应放在哪里时，可以使用以下思维模型： - **核心能力层**：共享编排、策略、回退、配置合并规则、交付语义和类型化契约 -- **vendor 插件层**：vendor 特定 API、凭证、模型目录、语音合成、图像生成、未来视频后端、用量端点 -- **渠道/功能插件层**：Slack/Discord/voice-call 等集成，消费核心能力并在某个接口上呈现 +- **供应商插件层**：供应商特定的 API、凭证、模型目录、语音合成、图像生成、未来视频后端、使用量端点 +- **渠道 / 功能插件层**：Slack / Discord / voice-call / 等集成，它们消费核心能力并将其呈现在某个表面上 -例如，TTS 遵循以下形态： +例如，TTS 采用以下结构： -- 核心拥有回复时 TTS 策略、回退顺序、偏好和渠道投递 +- 核心拥有回复时 TTS 策略、回退顺序、偏好和渠道交付 - `openai`、`elevenlabs` 和 `microsoft` 拥有合成实现 - `voice-call` 消费电话 TTS 运行时辅助工具 -未来能力也应优先沿用这一模式。 +未来的能力也应优先沿用相同模式。 ### 多能力公司插件示例 -从外部看，一个公司插件应当是内聚的。如果 OpenClaw 拥有模型、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、Web 抓取和 Web 搜索的共享契约，那么某个 vendor 就可以在一个地方拥有其所有接口： +一个公司插件从外部看应当是统一且内聚的。如果 OpenClaw 为模型、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、Web 抓取和 Web 搜索提供了共享契约，那么一个供应商就可以在一个地方拥有自己全部的表面： ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -285,147 +285,143 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -重要的不是具体的辅助函数名称，而是这种形态： +重要的不是辅助工具的确切名称，而是其结构： -- 一个插件拥有 vendor 接口范围 -- 核心仍拥有能力契约 -- 渠道和功能插件消费 `api.runtime.*` 辅助工具，而不是 vendor 代码 -- 契约测试可以断言该插件已注册其声称拥有的能力 +- 一个插件拥有供应商表面 +- 核心仍然拥有能力契约 +- 渠道和功能插件消费 `api.runtime.*` 辅助工具，而不是供应商代码 +- 契约测试可以断言该插件注册了它声称拥有的能力 ### 能力示例：视频理解 -OpenClaw 已经将图像/音频/视频理解视为一个共享能力。同样的所有权模型也适用于这里： +OpenClaw 已经将图像 / 音频 / 视频理解视为一个共享能力。在这里同样适用相同的所有权模型： 1. 核心定义媒体理解契约 -2. vendor 插件按需注册 `describeImage`、`transcribeAudio` 和 `describeVideo` -3. 渠道和功能插件消费共享核心行为，而不是直接接到 vendor 代码 +2. 供应商插件按需注册 `describeImage`、`transcribeAudio` 和 `describeVideo` +3. 渠道和功能插件消费共享核心行为，而不是直接连接到供应商代码 -这样可以避免将某个 provider 的视频假设固化进核心。插件拥有 vendor 接口，核心拥有能力契约和回退行为。 +这样可以避免将某一家提供商对视频的假设写死在核心中。插件拥有供应商表面；核心拥有能力契约和回退行为。 -视频生成也已经遵循同样的顺序：核心拥有类型化能力契约和运行时辅助工具，vendor 插件针对它注册 `api.registerVideoGenerationProvider(...)` 实现。 +视频生成已经采用同样的顺序：核心拥有类型化能力契约和运行时辅助工具，供应商插件则针对它注册 `api.registerVideoGenerationProvider(...)` 实现。 -需要一个具体的发布清单吗？请参见 +需要具体的发布清单吗？请参阅 [能力扩展手册](/zh-CN/plugins/architecture)。 ## 契约与强制执行 -插件 API 接口被有意设计为类型化，并集中在 -`OpenClawPluginApi` 中。该契约定义了受支持的注册点，以及插件可依赖的运行时辅助工具。 +插件 API 表面刻意以 `OpenClawPluginApi` 为中心，并保持类型化和集中化。该契约定义了受支持的注册点以及插件可以依赖的运行时辅助工具。 这很重要，因为： -- 插件作者可以获得一个稳定的内部标准 +- 插件作者获得了一套稳定的内部标准 - 核心可以拒绝重复所有权，例如两个插件注册相同的 provider id -- 启动时可以为格式错误的注册给出可执行的诊断 -- 契约测试可以强制约束内置插件的所有权，并防止静默漂移 +- 启动过程可以为格式错误的注册暴露可操作的诊断信息 +- 契约测试可以强制执行内置插件的所有权，并防止静默漂移 -这里有两层强制执行： +强制执行分为两层： 1. **运行时注册强制执行** - 插件注册表会在插件加载时验证注册内容。例如：重复 provider id、重复语音 provider id，以及格式错误的注册，都会产生插件诊断，而不是导致未定义行为。 + 插件注册表会在插件加载时验证注册。例如：重复的 provider id、重复的 speech provider id，以及格式错误的注册，都会生成插件诊断信息，而不是产生未定义行为。 2. **契约测试** - 在测试运行期间，内置插件会被捕获到契约注册表中，使 OpenClaw 可以显式断言所有权。目前这已用于模型 provider、语音 provider、Web 搜索 provider，以及内置注册所有权。 + 在测试运行期间，内置插件会被捕获到契约注册表中，以便 OpenClaw 可以明确断言所有权。如今这已用于模型提供商、语音提供商、Web 搜索提供商以及内置注册所有权。 -实际效果是，OpenClaw 可以预先知道哪个插件拥有哪个接口。这让核心和渠道能够无缝组合，因为所有权是显式声明、类型化且可测试的，而不是隐式的。 +实际效果是，OpenClaw 能够预先知道哪个插件拥有哪个表面。这让核心和渠道能够无缝组合，因为所有权是显式声明、类型化且可测试的，而不是隐式存在的。 -### 什么应该属于契约 +### 什么应该属于一个契约 -好的插件契约应该是： +好的插件契约应当是： -- 类型化的 -- 小而精的 -- 能力专用的 +- 类型化 +- 小而精 +- 能力特定 - 由核心拥有 - 可被多个插件复用 -- 可被渠道/功能消费，而无需了解 vendor +- 可被渠道 / 功能在不了解供应商细节的情况下消费 -差的插件契约则包括： +糟糕的插件契约包括： -- 隐藏在核心中的 vendor 特定策略 +- 隐藏在核心中的供应商特定策略 - 绕过注册表的一次性插件逃生口 -- 渠道代码直接深入 vendor 实现 +- 直接深入供应商实现的渠道代码 - 不属于 `OpenClawPluginApi` 或 `api.runtime` 的临时运行时对象 -如果拿不准，就提升抽象层级：先定义能力，再让插件接入它。 +如果拿不准，就提高抽象层级：先定义能力，再让插件接入它。 ## 执行模型 -原生 OpenClaw 插件与 Gateway 网关 **在同一进程内**运行。它们不是沙箱隔离的。一个已加载的原生插件与核心代码共享同样的进程级信任边界。 +原生 OpenClaw 插件与 Gateway 网关 **在同一进程内**运行。它们不是沙箱隔离的。一个已加载的原生插件，与核心代码处于同样的进程级信任边界内。 -这意味着： +其影响包括： -- 原生插件可以注册工具、网络处理器、hooks 和服务 -- 原生插件中的 bug 可能导致 gateway 崩溃或不稳定 +- 原生插件可以注册工具、网络处理器、钩子和服务 +- 原生插件中的 bug 可能导致 Gateway 网关崩溃或不稳定 - 恶意原生插件等同于在 OpenClaw 进程内执行任意代码 -兼容 bundle 默认更安全，因为 OpenClaw 当前将它们视为元数据/内容包。在当前版本中，这主要指内置 Skills。 +兼容 bundle 默认更安全，因为 OpenClaw 当前将它们视为元数据 / 内容包。在当前版本中，这主要意味着内置 skills。 -对于非内置插件，请使用 allowlist 和显式安装/加载路径。将 workspace 插件视为开发期代码，而不是生产默认项。 +对于非内置插件，请使用 allowlist 和显式的安装 / 加载路径。将工作区插件视为开发期代码，而不是生产默认项。 -对于内置 workspace 包名称，保持插件 id 与 npm 名称对齐：默认使用 `@openclaw/`，或在包有意暴露更窄插件角色时，使用获批的类型后缀，例如 `-provider`、`-plugin`、`-speech`、`-sandbox` 或 `-media-understanding`。 +对于内置工作区包名，请保持插件 id 锚定在 npm 名称中：默认使用 `@openclaw/`，或者使用经过批准的类型化后缀，例如 `-provider`、`-plugin`、`-speech`、`-sandbox` 或 `-media-understanding`，当该包有意暴露更窄的插件角色时可使用这些后缀。 重要的信任说明： - `plugins.allow` 信任的是**插件 id**，而不是来源出处。 -- 如果某个 workspace 插件与一个内置插件拥有相同 id，那么当该 workspace 插件被启用/加入 allowlist 时，它会有意覆盖内置副本。 -- 这是正常且有用的，适用于本地开发、补丁测试和热修复。 +- 与内置插件同 id 的工作区插件，在该工作区插件启用 / 被 allowlist 后，会有意覆盖内置副本。 +- 这属于正常且有用的行为，适用于本地开发、补丁测试和热修复。 ## 导出边界 -OpenClaw 导出的是能力，而不是实现便利接口。 +OpenClaw 导出的是能力，而不是实现层面的便利接口。 -保持能力注册公开。收紧非契约辅助导出： +保持能力注册为公共接口。裁剪非契约辅助工具导出： -- 内置插件专用辅助子路径 -- 不打算作为公共 API 的运行时管线子路径 -- vendor 特定便捷辅助工具 -- 属于实现细节的 setup/新手引导辅助工具 +- 内置插件特定的辅助工具子路径 +- 无意作为公共 API 的运行时接线子路径 +- 供应商特定的便利辅助工具 +- 属于实现细节的设置 / onboarding 辅助工具 -某些内置插件辅助子路径仍为了兼容性和内置插件维护，而保留在生成的 SDK 导出映射中。当前示例包括 -`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、 -`plugin-sdk/zalo-setup` 以及多个 `plugin-sdk/matrix*` 接缝。应将这些视为保留的实现细节导出，而不是新第三方插件推荐使用的 SDK 模式。 +为了兼容性和内置插件维护，一些内置插件辅助工具子路径仍然保留在生成的 SDK 导出映射中。当前示例包括 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 以及若干 `plugin-sdk/matrix*` 接缝。应将它们视为保留的实现细节导出，而不是面向新第三方插件的推荐 SDK 模式。 ## 加载流水线 -启动时，OpenClaw 大致会执行以下步骤： +在启动时，OpenClaw 大致会执行以下步骤： 1. 发现候选插件根目录 -2. 读取原生或兼容 bundle 的 manifest 和包元数据 +2. 读取原生或兼容 bundle 的清单及包元数据 3. 拒绝不安全的候选项 -4. 规范化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、 - `slots`、`load.paths`） -5. 决定每个候选项的启用状态 +4. 规范化插件配置（`plugins.enabled`、`allow`、`deny`、`entries`、`slots`、`load.paths`） +5. 为每个候选项决定启用状态 6. 通过 jiti 加载已启用的原生模块 -7. 调用原生 `register(api)`（或 `activate(api)` —— 一个传统别名）hook，并将注册内容收集到插件注册表中 -8. 将注册表暴露给命令/运行时接口 +7. 调用原生 `register(api)`（或 `activate(api)`——旧版别名）钩子，并将注册收集到插件注册表中 +8. 将注册表暴露给命令 / 运行时表面 -`activate` 是 `register` 的传统别名——加载器会解析其中存在的那个（`def.register ?? def.activate`），并在同一点调用。所有内置插件都使用 `register`；新插件请优先使用 `register`。 +`activate` 是 `register` 的旧版别名——加载器会解析存在的那个（`def.register ?? def.activate`），并在同一位置调用它。所有内置插件都使用 `register`；新插件请优先使用 `register`。 -安全门会发生在**运行时执行之前**。如果入口逃出插件根目录、路径对全体可写，或对于非内置插件来说路径所有权看起来可疑，候选项就会被阻止。 +安全门禁发生在**运行时代码执行之前**。如果入口逃离插件根目录、路径对全体用户可写，或对于非内置插件而言路径所有权看起来可疑，候选项就会被阻止。 -### Manifest 优先行为 +### 清单优先行为 -manifest 是控制平面的事实来源。OpenClaw 用它来： +清单是控制平面的事实来源。OpenClaw 使用它来： - 标识插件 -- 发现声明的渠道/Skills/配置 schema 或 bundle 能力 +- 发现声明的渠道 / skills / 配置 schema 或 bundle 能力 - 验证 `plugins.entries..config` -- 补充 Control UI 标签/占位符 -- 显示安装/目录元数据 +- 增强控制 UI 标签 / 占位符 +- 显示安装 / 目录元数据 -对于原生插件，运行时模块则是数据平面部分。它会注册 hooks、工具、命令或 provider 流程等实际行为。 +对于原生插件，运行时模块属于数据平面部分。它会注册诸如钩子、工具、命令或提供商流程等实际行为。 -### 加载器缓存的内容 +### 加载器会缓存什么 -OpenClaw 会维护短期的进程内缓存，用于： +OpenClaw 会在进程内维护短期缓存，用于： - 发现结果 -- manifest 注册表数据 +- 清单注册表数据 - 已加载的插件注册表 -这些缓存用于降低启动突发与重复命令开销。可以把它们理解为短生命周期的性能缓存，而不是持久化。 +这些缓存可减少突发启动开销和重复命令开销。你可以安全地将它们理解为短期性能缓存，而不是持久化机制。 性能说明： @@ -436,33 +432,33 @@ OpenClaw 会维护短期的进程内缓存，用于： ## 注册表模型 -已加载插件不会直接改写随机的核心全局状态。它们会注册到中央插件注册表中。 +已加载的插件不会直接修改任意核心全局状态。它们会注册到一个中央插件注册表中。 -注册表会追踪： +该注册表会跟踪： -- 插件记录（标识、来源、出处、状态、诊断） +- 插件记录（身份、来源、起源、状态、诊断信息） - 工具 -- 传统 hooks 和类型化 hooks +- 旧版钩子和类型化钩子 - 渠道 -- providers +- 提供商 - Gateway 网关 RPC 处理器 - HTTP 路由 - CLI 注册器 - 后台服务 - 插件自有命令 -随后，核心功能会从这个注册表读取，而不是直接与插件模块交互。这让加载保持单向： +核心功能随后从这个注册表读取信息，而不是直接与插件模块交互。这使加载保持单向： - 插件模块 -> 注册表注册 - 核心运行时 -> 注册表消费 -这种分离对可维护性非常重要。它意味着大多数核心接口只需要一个集成点：“读取注册表”，而不是“为每个插件模块写特殊分支”。 +这种分离对可维护性很重要。它意味着大多数核心表面只需要一个集成点：“读取注册表”，而不是“为每个插件模块写特例”。 ## 会话绑定回调 -绑定会话的插件可以在审批结果确定后作出响应。 +绑定会话的插件可以在批准被解析时做出响应。 -使用 `api.onConversationBindingResolved(...)` 可在绑定请求获批或被拒后接收回调： +使用 `api.onConversationBindingResolved(...)`，在绑定请求被批准或拒绝后接收一个回调： ```ts export default { @@ -486,18 +482,18 @@ export default { - `status`：`"approved"` 或 `"denied"` - `decision`：`"allow-once"`、`"allow-always"` 或 `"deny"` -- `binding`：适用于已批准请求的已解析绑定 -- `request`：原始请求摘要、分离提示、发送者 id，以及会话元数据 +- `binding`：用于已批准请求的已解析绑定 +- `request`：原始请求摘要、分离提示、发送者 id 以及会话元数据 -该回调仅用于通知。它不会改变谁可以绑定会话，并且会在核心审批处理完成后才运行。 +该回调仅用于通知。它不会改变谁被允许绑定会话，并且会在核心审批处理完成后运行。 -## Provider 运行时 hooks +## 提供商运行时钩子 -Provider 插件现在有两层： +提供商插件现在有两层： -- manifest 元数据：`providerAuthEnvVars` 用于在运行时加载前进行廉价的 provider 环境凭证查询，`channelEnvVars` 用于在运行时加载前进行廉价的渠道环境/setup 查询，以及 `providerAuthChoices` 用于在运行时加载前提供廉价的新手引导/凭证选择标签和 CLI flag 元数据 -- 配置期 hooks：`catalog` / 传统 `discovery` 以及 `applyConfigDefaults` -- 运行时 hooks：`normalizeModelId`、`normalizeTransport`、 +- 清单元数据：`providerAuthEnvVars` 用于在运行时加载前进行低成本的提供商环境凭证查找，`channelEnvVars` 用于在运行时加载前进行低成本的渠道环境 / 设置查找，此外还有 `providerAuthChoices`，用于在运行时加载前进行低成本 onboarding / 认证选项标签和 CLI 标志元数据 +- 配置时钩子：`catalog` / 旧版 `discovery`，以及 `applyConfigDefaults` +- 运行时钩子：`normalizeModelId`、`normalizeTransport`、 `normalizeConfig`、 `applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、 `resolveSyntheticAuth`、`resolveExternalAuthProfiles`、 @@ -517,70 +513,70 @@ Provider 插件现在有两层： `buildReplayPolicy`、 `sanitizeReplayHistory`、`validateReplayTurns`、`onModelSelected` -OpenClaw 仍然拥有通用智能体循环、故障转移、转录处理和工具策略。这些 hooks 是 provider 特定行为的扩展接口，而无需实现一整套自定义推理传输。 +OpenClaw 仍然拥有通用智能体循环、故障转移、转录处理和工具策略。这些钩子是提供商特定行为的扩展表面，而无需一整套自定义推理传输层。 -当 provider 具有基于环境变量的凭证，且通用凭证/状态/模型选择器路径需要在不加载插件运行时的情况下看到这些凭证时，请使用 manifest `providerAuthEnvVars`。当新手引导/凭证选择 CLI 接口需要在不加载 provider 运行时的情况下了解 provider 的 choice id、分组标签和简单的单 flag 凭证接线时，请使用 manifest `providerAuthChoices`。将 provider 运行时 `envVars` 保留给面向操作员的提示，例如新手引导标签或 OAuth client id/client secret 设置变量。 +当某个提供商具有基于环境变量的凭证，并且通用 auth / status / model-picker 路径需要在不加载插件运行时的情况下看到这些凭证时，请使用清单中的 `providerAuthEnvVars`。当 onboarding / 认证选项 CLI 表面需要在不加载提供商运行时的情况下，知道该提供商的 choice id、分组标签和简单的单标志认证接线时，请使用清单中的 `providerAuthChoices`。保留提供商运行时中的 `envVars`，用于面向运维人员的提示，例如 onboarding 标签或 OAuth client-id / client-secret 设置变量。 -当某个渠道具有由环境变量驱动的凭证或 setup，且通用 shell 环境变量回退、配置/状态检查或 setup 提示需要在不加载渠道运行时的情况下看到这些信息时，请使用 manifest `channelEnvVars`。 +当某个渠道具有由环境变量驱动的认证或设置，并且通用 shell-env 回退、配置 / 状态检查或设置提示需要在不加载渠道运行时的情况下看到它时，请使用清单中的 `channelEnvVars`。 -### Hook 顺序与使用时机 +### 钩子顺序和用法 -对于模型/provider 插件，OpenClaw 大致按以下顺序调用 hooks。 +对于模型 / 提供商插件，OpenClaw 会大致按以下顺序调用钩子。 “何时使用”列是快速决策指南。 -| # | Hook | 作用 | 何时使用 | +| # | 钩子 | 它的作用 | 何时使用 | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | 在生成 `models.json` 时，将 provider 配置发布到 `models.providers` | provider 拥有目录或 base URL 默认值时 | -| 2 | `applyConfigDefaults` | 在配置具体化期间应用 provider 自有的全局配置默认值 | 默认值取决于凭证模式、环境变量或 provider 模型家族语义时 | -| -- | _(内置模型查找)_ | OpenClaw 会先尝试常规注册表/目录路径 | _(不是插件 hook)_ | -| 3 | `normalizeModelId` | 在查找前规范化传统或预览 model id 别名 | provider 在规范模型解析前拥有别名清理逻辑时 | -| 4 | `normalizeTransport` | 在通用模型组装前规范化 provider 家族的 `api` / `baseUrl` | provider 需要为同一传输家族中的自定义 provider id 做传输清理时 | -| 5 | `normalizeConfig` | 在运行时/provider 解析前规范化 `models.providers.` | provider 需要将配置清理逻辑放在插件内；内置 Google 家族辅助工具也会为受支持的 Google 配置项提供兜底 | -| 6 | `applyNativeStreamingUsageCompat` | 对配置 providers 应用原生流式用量兼容性重写 | provider 需要基于端点修复原生流式用量元数据时 | -| 7 | `resolveConfigApiKey` | 在加载运行时凭证前，为配置 providers 解析环境标记凭证 | provider 拥有自有的环境标记 API key 解析逻辑；`amazon-bedrock` 这里也有内置 AWS 环境标记解析器 | -| 8 | `resolveSyntheticAuth` | 在不持久化明文的情况下暴露本地/自托管或配置支持的凭证 | provider 可通过合成/本地凭证标记运行时 | -| 9 | `resolveExternalAuthProfiles` | 叠加 provider 自有的外部凭证档案；默认 `persistence` 为 `runtime-only`，适用于 CLI/应用自有凭证 | provider 复用外部凭证，而不持久化复制的 refresh token | -| 10 | `shouldDeferSyntheticProfileAuth` | 让已存储的合成档案占位符优先级低于环境/配置支持的凭证 | provider 存储了不应具有优先级的合成占位档案时 | -| 11 | `resolveDynamicModel` | 对本地注册表中尚不存在的 provider 自有 model id 进行同步回退解析 | provider 接受任意上游 model id 时 | -| 12 | `prepareDynamicModel` | 异步预热，然后再次运行 `resolveDynamicModel` | provider 需要在解析未知 id 前获取网络元数据时 | -| 13 | `normalizeResolvedModel` | 在嵌入式 runner 使用已解析模型前做最终重写 | provider 需要传输重写，但仍使用核心传输时 | -| 14 | `contributeResolvedModelCompat` | 为另一兼容传输背后的 vendor 模型贡献兼容标志 | provider 能在不接管 provider 的情况下识别自己的代理传输模型时 | -| 15 | `capabilities` | 共享核心逻辑使用的 provider 自有转录/工具元数据 | provider 需要处理转录/provider 家族特性时 | -| 16 | `normalizeToolSchemas` | 在嵌入式 runner 看到它们前规范化工具 schema | provider 需要做传输家族 schema 清理时 | -| 17 | `inspectToolSchemas` | 在规范化后暴露 provider 自有 schema 诊断 | provider 想要关键字警告，而不希望核心学习 provider 特定规则时 | -| 18 | `resolveReasoningOutputMode` | 选择原生或带标签的推理输出契约 | provider 需要带标签的推理/最终输出，而不是原生字段时 | -| 19 | `prepareExtraParams` | 在通用流式选项包装器前进行请求参数规范化 | provider 需要默认请求参数或按 provider 进行参数清理时 | -| 20 | `createStreamFn` | 用自定义传输完全替换正常流路径 | provider 需要自定义线协议，而不仅仅是包装器时 | -| 21 | `wrapStreamFn` | 在应用通用包装器之后再包装流 | provider 需要请求头/请求体/模型兼容包装器，而不是自定义传输时 | -| 22 | `resolveTransportTurnState` | 附加原生的逐轮传输头或元数据 | provider 希望通用传输发送 provider 原生轮次标识时 | -| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 头或会话冷却策略 | provider 希望通用 WS 传输调整会话头或回退策略时 | -| 24 | `formatApiKey` | 凭证档案格式化器：已存储档案转换为运行时 `apiKey` 字符串 | provider 存储额外凭证元数据，需要自定义运行时 token 形态时 | -| 25 | `refreshOAuth` | 为自定义刷新端点或刷新失败策略覆盖 OAuth 刷新逻辑 | provider 不适合共享 `pi-ai` 刷新器时 | -| 26 | `buildAuthDoctorHint` | 在 OAuth 刷新失败时追加修复提示 | provider 需要在刷新失败后给出 provider 自有的凭证修复指引时 | -| 27 | `matchesContextOverflowError` | provider 自有的上下文窗口溢出匹配器 | provider 存在通用启发式无法识别的原始溢出错误时 | -| 28 | `classifyFailoverReason` | provider 自有的故障转移原因分类 | provider 能将原始 API/传输错误映射到限流/过载等原因时 | -| 29 | `isCacheTtlEligible` | 面向代理/回传 providers 的提示词缓存策略 | provider 需要代理特定的缓存 TTL 门控时 | -| 30 | `buildMissingAuthMessage` | 替代通用的缺失凭证恢复消息 | provider 需要 provider 特定的缺失凭证恢复提示时 | -| 31 | `suppressBuiltInModel` | 过时上游模型抑制，并可附带面向用户的错误提示 | provider 需要隐藏过时上游行，或用 vendor 提示替换它们时 | -| 32 | `augmentModelCatalog` | 在设备发现后追加合成/最终目录行 | provider 需要在 `models list` 和选择器中添加合成的前向兼容条目时 | -| 33 | `isBinaryThinking` | 为二元 thinking provider 提供开/关推理切换 | provider 只暴露二元 thinking 开/关时 | -| 34 | `supportsXHighThinking` | 为选定模型提供 `xhigh` 推理支持 | provider 希望仅对部分模型支持 `xhigh` 时 | -| 35 | `resolveDefaultThinkingLevel` | 为特定模型家族提供默认 `/think` 级别 | provider 拥有某个模型家族的默认 `/think` 策略时 | -| 36 | `isModernModelRef` | 面向实时档案过滤和 smoke 选择的现代模型匹配器 | provider 拥有实时/smoke 首选模型匹配逻辑时 | -| 37 | `prepareRuntimeAuth` | 在推理前将已配置凭证交换为实际运行时 token/key | provider 需要 token 交换或短期请求凭证时 | -| 38 | `resolveUsageAuth` | 为 `/usage` 及相关状态接口解析用量/计费凭证 | provider 需要自定义用量/配额 token 解析，或需要不同的用量凭证时 | -| 39 | `fetchUsageSnapshot` | 在凭证解析后获取并规范化 provider 特定的用量/配额快照 | provider 需要 provider 特定的用量端点或载荷解析器时 | -| 40 | `createEmbeddingProvider` | 为 memory/search 构建 provider 自有嵌入适配器 | 内存嵌入行为应归属于 provider 插件时 | -| 41 | `buildReplayPolicy` | 返回控制 provider 转录处理的 replay 策略 | provider 需要自定义转录策略（例如移除 thinking block）时 | -| 42 | `sanitizeReplayHistory` | 在通用转录清理之后重写 replay 历史 | provider 需要在共享压缩辅助工具之外做 provider 特定 replay 重写时 | -| 43 | `validateReplayTurns` | 在嵌入式 runner 之前做最终 replay 轮次校验或整形 | provider 传输在通用清理后仍需要更严格的轮次校验时 | -| 44 | `onModelSelected` | 在模型被选中后执行 provider 自有副作用 | provider 需要在模型激活时记录遥测或更新 provider 自有状态时 | +| 1 | `catalog` | 在生成 `models.json` 时将提供商配置发布到 `models.providers` 中 | 提供商拥有目录或 base URL 默认值 | +| 2 | `applyConfigDefaults` | 在配置具体化期间应用提供商自有的全局配置默认值 | 默认值取决于认证模式、环境或提供商模型族语义 | +| -- | _(内置模型查找)_ | OpenClaw 会先尝试正常的注册表 / 目录路径 | _(不是插件钩子)_ | +| 3 | `normalizeModelId` | 在查找前规范化旧版或预览 model-id 别名 | 提供商在标准模型解析前拥有别名清理逻辑 | +| 4 | `normalizeTransport` | 在通用模型组装前规范化提供商家族的 `api` / `baseUrl` | 提供商在同一传输家族中拥有用于自定义 provider id 的传输清理逻辑 | +| 5 | `normalizeConfig` | 在运行时 / 提供商解析前规范化 `models.providers.` | 提供商需要由插件持有的配置清理逻辑；内置的 Google 家族辅助工具也会为受支持的 Google 配置项兜底 | +| 6 | `applyNativeStreamingUsageCompat` | 将原生流式 usage 兼容重写应用到配置提供商 | 提供商需要基于端点的原生流式 usage 元数据修复 | +| 7 | `resolveConfigApiKey` | 在加载运行时 auth 之前，为配置提供商解析 env-marker 认证 | 提供商拥有自有的 env-marker API key 解析逻辑；`amazon-bedrock` 在此也有内置 AWS env-marker 解析器 | +| 8 | `resolveSyntheticAuth` | 暴露 local / self-hosted 或基于配置的 auth，而不持久化明文 | 提供商可以使用 synthetic / local 凭证标记运行 | +| 9 | `resolveExternalAuthProfiles` | 叠加提供商自有的外部 auth 配置；默认 `persistence` 为 `runtime-only`，用于 CLI / 应用自有凭证 | 提供商复用外部 auth 凭证，而不持久化复制来的 refresh token | +| 10 | `shouldDeferSyntheticProfileAuth` | 将已存储的 synthetic profile 占位符降级到 env / config 支持的 auth 之后 | 提供商会存储 synthetic 占位 profile，而这些 profile 不应具有更高优先级 | +| 11 | `resolveDynamicModel` | 为尚未进入本地注册表的提供商自有 model id 提供同步回退 | 提供商接受任意上游 model id | +| 12 | `prepareDynamicModel` | 执行异步预热，然后再次运行 `resolveDynamicModel` | 提供商在解析未知 id 前需要网络元数据 | +| 13 | `normalizeResolvedModel` | 在嵌入式运行器使用已解析模型前做最终重写 | 提供商需要传输重写，但仍使用核心传输 | +| 14 | `contributeResolvedModelCompat` | 为位于其他兼容传输背后的供应商模型贡献兼容标志 | 提供商在代理传输上识别自己的模型，而不接管该提供商 | +| 15 | `capabilities` | 由共享核心逻辑使用的提供商自有转录 / 工具元数据 | 提供商需要转录 / 提供商家族特性处理 | +| 16 | `normalizeToolSchemas` | 在嵌入式运行器看到工具 schema 前进行规范化 | 提供商需要传输家族的 schema 清理 | +| 17 | `inspectToolSchemas` | 在规范化后暴露提供商自有 schema 诊断 | 提供商希望发出关键字警告，而不需要让核心理解提供商特定规则 | +| 18 | `resolveReasoningOutputMode` | 选择原生还是带标签的推理输出契约 | 提供商需要使用带标签的推理 / 最终输出，而不是原生字段 | +| 19 | `prepareExtraParams` | 在通用流式选项包装器之前进行请求参数规范化 | 提供商需要默认请求参数或每个提供商的参数清理 | +| 20 | `createStreamFn` | 用自定义传输完全替换正常流路径 | 提供商需要自定义线协议，而不仅是包装器 | +| 21 | `wrapStreamFn` | 在通用包装器应用后再进行流包装 | 提供商需要请求头 / 请求体 / 模型兼容包装器，但不需要自定义传输 | +| 22 | `resolveTransportTurnState` | 附加原生的逐轮传输头或元数据 | 提供商希望通用传输发送提供商原生的轮次身份 | +| 23 | `resolveWebSocketSessionPolicy` | 附加原生 WebSocket 头或会话冷却策略 | 提供商希望通用 WS 传输调整会话头或回退策略 | +| 24 | `formatApiKey` | auth profile 格式化器：存储的 profile 变成运行时 `apiKey` 字符串 | 提供商会存储额外 auth 元数据，并需要自定义运行时 token 形态 | +| 25 | `refreshOAuth` | 针对自定义刷新端点或刷新失败策略覆盖 OAuth 刷新 | 提供商不适配共享 `pi-ai` 刷新器 | +| 26 | `buildAuthDoctorHint` | 在 OAuth 刷新失败时附加修复提示 | 提供商需要在刷新失败后提供自有 auth 修复指引 | +| 27 | `matchesContextOverflowError` | 提供商自有的上下文窗口溢出匹配器 | 提供商存在通用启发式无法识别的原始溢出错误 | +| 28 | `classifyFailoverReason` | 提供商自有的故障转移原因分类 | 提供商可以将原始 API / 传输错误映射为限流 / 过载等 | +| 29 | `isCacheTtlEligible` | 面向代理 / 回程提供商的提示词缓存策略 | 提供商需要代理特定的缓存 TTL 门控 | +| 30 | `buildMissingAuthMessage` | 替换通用缺失认证恢复消息 | 提供商需要特定的缺失认证恢复提示 | +| 31 | `suppressBuiltInModel` | 过期上游模型抑制以及可选的面向用户错误提示 | 提供商需要隐藏过期上游条目或用供应商提示替代 | +| 32 | `augmentModelCatalog` | 在发现之后追加 synthetic / 最终目录行 | 提供商需要在 `models list` 和选择器中加入 synthetic 前向兼容条目 | +| 33 | `isBinaryThinking` | 面向二元 thinking 提供商的开 / 关推理切换 | 提供商只暴露二元 thinking 开 / 关 | +| 34 | `supportsXHighThinking` | 为特定模型提供 `xhigh` 推理支持 | 提供商只希望在部分模型上提供 `xhigh` | +| 35 | `resolveDefaultThinkingLevel` | 某个特定模型族的默认 `/think` 级别 | 提供商拥有某个模型族默认 `/think` 策略 | +| 36 | `isModernModelRef` | 面向实时 profile 过滤和 smoke 选择的现代模型匹配器 | 提供商拥有 live / smoke 首选模型匹配逻辑 | +| 37 | `prepareRuntimeAuth` | 在推理前将已配置凭证交换为实际运行时 token / key | 提供商需要 token 交换或短期请求凭证 | +| 38 | `resolveUsageAuth` | 为 `/usage` 及相关状态表面解析使用量 / 计费凭证 | 提供商需要自定义使用量 / 配额 token 解析，或使用不同的使用量凭证 | +| 39 | `fetchUsageSnapshot` | 在解析 auth 后抓取并规范化提供商特定的使用量 / 配额快照 | 提供商需要特定的使用量端点或载荷解析器 | +| 40 | `createEmbeddingProvider` | 为 memory / search 构建提供商自有的 embedding 适配器 | memory embedding 行为应归属于提供商插件 | +| 41 | `buildReplayPolicy` | 返回控制提供商转录处理的 replay 策略 | 提供商需要自定义转录策略（例如去除 thinking block） | +| 42 | `sanitizeReplayHistory` | 在通用转录清理后重写 replay 历史 | 提供商需要超出共享压缩辅助工具之外的 replay 重写 | +| 43 | `validateReplayTurns` | 在嵌入式运行器之前对 replay turn 做最终验证或重塑 | 提供商传输在通用清理后需要更严格的 turn 验证 | +| 44 | `onModelSelected` | 运行提供商自有的选择后副作用 | 当模型变为活动状态时，提供商需要遥测或自有状态处理 | -`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查已匹配的 provider 插件，然后回退到其他具备 hook 能力的 provider 插件，直到有一个实际改变 model id 或 transport/config 为止。这样可以让别名/兼容 provider shim 正常工作，而不要求调用方知道哪个内置插件拥有该重写逻辑。如果没有任何 provider hook 重写受支持的 Google 家族配置项，则内置 Google 配置规范化器仍会应用相应兼容性清理。 +`normalizeModelId`、`normalizeTransport` 和 `normalizeConfig` 会先检查已匹配的提供商插件，然后回退到其他具备相应钩子能力的提供商插件，直到某个插件真正修改了模型 id 或传输 / 配置。这让别名 / 兼容提供商 shim 可以继续工作，而不要求调用方必须知道哪个内置插件拥有该重写逻辑。如果没有提供商钩子重写受支持的 Google 家族配置项，内置 Google 配置规范化器仍会应用该兼容性清理。 -如果 provider 需要完全自定义的线协议或自定义请求执行器，那就属于另一类扩展。这些 hooks 适用于仍在 OpenClaw 常规推理循环上运行的 provider 行为。 +如果提供商需要完全自定义的线协议或自定义请求执行器，那就是另一类扩展。这些钩子适用于仍运行在 OpenClaw 正常推理循环上的提供商行为。 -### Provider 示例 +### 提供商示例 ```ts api.registerProvider({ @@ -639,58 +635,101 @@ api.registerProvider({ - Anthropic 使用 `resolveDynamicModel`、`capabilities`、`buildAuthDoctorHint`、 `resolveUsageAuth`、`fetchUsageSnapshot`、`isCacheTtlEligible`、 `resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`， - 以及 `wrapStreamFn`，因为它拥有 Claude 4.6 前向兼容、provider 家族提示、凭证修复指引、用量端点集成、提示词缓存适用性、具备凭证感知的配置默认值、Claude 默认/自适应 thinking 策略，以及针对 beta headers、`/fast` / `serviceTier` 和 `context1m` 的 Anthropic 特定流整形。 -- Anthropic 的 Claude 特定流辅助工具暂时保留在内置插件自己的公开 `api.ts` / `contract-api.ts` 接缝中。该包接口会导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、 - `resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及更底层的 Anthropic 包装器构建工具，而不是为了某一个 provider 的 beta header 规则去扩大通用 SDK。 + 以及 `wrapStreamFn`，因为它拥有 Claude 4.6 前向兼容、 + 提供商家族提示、auth 修复指导、使用量端点集成、 + 提示词缓存资格、auth 感知配置默认值、Claude + 默认 / 自适应 thinking 策略，以及 Anthropic 特定的流式整形，用于 beta headers、`/fast` / `serviceTier` 和 `context1m`。 +- Anthropic 的 Claude 特定流式辅助工具目前仍保留在内置插件自己的 + 公共 `api.ts` / `contract-api.ts` 接缝中。该包表面会导出 + `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、 + `resolveAnthropicFastMode`、`resolveAnthropicServiceTier` 以及更底层的 + Anthropic 包装器构建器，而不是围绕某个提供商的 beta-header 规则扩大通用 SDK。 - OpenAI 使用 `resolveDynamicModel`、`normalizeResolvedModel` 和 `capabilities`，以及 `buildMissingAuthMessage`、`suppressBuiltInModel`、 `augmentModelCatalog`、`supportsXHighThinking` 和 `isModernModelRef`， 因为它拥有 GPT-5.4 前向兼容、直接的 OpenAI - `openai-completions` -> `openai-responses` 规范化、面向 Codex 的凭证提示、Spark 抑制、合成的 OpenAI 列表条目，以及 GPT-5 thinking / 实时模型策略；`openai-responses-defaults` 流家族则拥有共享的原生 OpenAI Responses 包装器，用于 attribution headers、 - `/fast`/`serviceTier`、文本冗长度、原生 Codex Web 搜索、推理兼容载荷整形，以及 Responses 上下文管理。 + `openai-completions` -> `openai-responses` 规范化、面向 Codex 的 auth + 提示、Spark 抑制、synthetic OpenAI 列表行，以及 GPT-5 thinking / + live-model 策略；`openai-responses-defaults` 流家族则拥有共享的原生 OpenAI Responses 包装器，用于 attribution headers、 + `/fast`/`serviceTier`、文本详细度、原生 Codex Web 搜索、 + 推理兼容载荷整形以及 Responses 上下文管理。 - OpenRouter 使用 `catalog` 以及 `resolveDynamicModel` 和 - `prepareDynamicModel`，因为该 provider 是透传型的，可能会在 OpenClaw 的静态目录更新之前暴露新 model id；它还使用 - `capabilities`、`wrapStreamFn` 和 `isCacheTtlEligible`，以便将 provider 特定的请求头、路由元数据、推理补丁和提示词缓存策略保持在核心之外。它的 replay 策略来自 - `passthrough-gemini` 家族，而 `openrouter-thinking` 流家族负责代理推理注入以及对不支持模型 / `auto` 的跳过逻辑。 + `prepareDynamicModel`，因为该提供商是透传式的，可能会在 OpenClaw 的静态目录更新之前暴露新的 + model id；它还使用 `capabilities`、`wrapStreamFn` 和 `isCacheTtlEligible`，以便将 + 提供商特定请求头、路由元数据、推理补丁和提示词缓存策略保留在核心之外。它的 replay 策略来自 + `passthrough-gemini` 家族，而 `openrouter-thinking` 流家族 + 拥有代理推理注入以及不受支持模型 / `auto` 跳过逻辑。 - GitHub Copilot 使用 `catalog`、`auth`、`resolveDynamicModel` 和 - `capabilities`，以及 `prepareRuntimeAuth` 和 `fetchUsageSnapshot`，因为它需要 provider 自有的设备登录、模型回退行为、Claude 转录特性、GitHub token -> Copilot token 交换，以及 provider 自有的用量端点。 + `capabilities`，以及 `prepareRuntimeAuth` 和 `fetchUsageSnapshot`， + 因为它需要提供商自有的设备登录、模型回退行为、Claude 转录特性、GitHub token -> Copilot token 交换，以及提供商自有的使用量端点。 - OpenAI Codex 使用 `catalog`、`resolveDynamicModel`、 `normalizeResolvedModel`、`refreshOAuth` 和 `augmentModelCatalog`，以及 - `prepareExtraParams`、`resolveUsageAuth` 和 `fetchUsageSnapshot`，因为它仍运行在核心 OpenAI 传输之上，但拥有自己的传输/base URL 规范化、OAuth 刷新回退策略、默认传输选择、合成 Codex 目录条目和 ChatGPT 用量端点集成；它与直接 OpenAI 共享同一个 `openai-responses-defaults` 流家族。 + `prepareExtraParams`、`resolveUsageAuth` 和 `fetchUsageSnapshot`，因为它 + 仍运行在核心 OpenAI 传输之上，但拥有自己的传输 / base URL + 规范化、OAuth 刷新回退策略、默认传输选择、 + synthetic Codex 目录行，以及 ChatGPT 使用量端点集成；它与直接 OpenAI 共享同一个 `openai-responses-defaults` 流家族。 - Google AI Studio 和 Gemini CLI OAuth 使用 `resolveDynamicModel`、 `buildReplayPolicy`、`sanitizeReplayHistory`、 `resolveReasoningOutputMode`、`wrapStreamFn` 和 `isModernModelRef`，因为 - `google-gemini` replay 家族拥有 Gemini 3.1 前向兼容回退、原生 Gemini replay 校验、引导 replay 清理、带标签的推理输出模式以及现代模型匹配，而 `google-thinking` 流家族负责 Gemini thinking 载荷规范化；Gemini CLI OAuth 还使用 `formatApiKey`、`resolveUsageAuth` 和 + `google-gemini` replay 家族拥有 Gemini 3.1 前向兼容回退、 + 原生 Gemini replay 验证、启动 replay 清洗、带标签的 + 推理输出模式，以及现代模型匹配，而 + `google-thinking` 流家族拥有 Gemini thinking 载荷规范化； + Gemini CLI OAuth 还使用 `formatApiKey`、`resolveUsageAuth` 和 `fetchUsageSnapshot` 来处理 token 格式化、token 解析和配额端点接线。 - Anthropic Vertex 通过 - `anthropic-by-model` replay 家族使用 `buildReplayPolicy`，从而让 Claude 特定 replay 清理只作用于 Claude id，而不是每一个 `anthropic-messages` 传输。 + `anthropic-by-model` replay 家族使用 `buildReplayPolicy`，这样 Claude 特定的 replay 清理就只作用于 Claude id，而不是每个 `anthropic-messages` 传输。 - Amazon Bedrock 使用 `buildReplayPolicy`、`matchesContextOverflowError`、 - `classifyFailoverReason` 和 `resolveDefaultThinkingLevel`，因为它拥有面向 Anthropic-on-Bedrock 流量的 Bedrock 特定限流/未就绪/上下文溢出错误分类；其 replay 策略仍共享相同的仅 Claude `anthropic-by-model` 防护。 -- OpenRouter、Kilocode、Opencode 和 Opencode Go 通过 - `passthrough-gemini` replay 家族使用 `buildReplayPolicy`，因为它们通过 OpenAI 兼容传输代理 Gemini 模型，并需要 Gemini thought-signature 清理，而不需要原生 Gemini replay 校验或引导重写。 + `classifyFailoverReason` 和 `resolveDefaultThinkingLevel`，因为它拥有 + 面向 Bedrock 特定的 throttle / not-ready / context-overflow 错误分类， + 用于 Anthropic-on-Bedrock 流量；其 replay 策略仍共享同一个只针对 Claude 的 + `anthropic-by-model` 防护。 +- OpenRouter、Kilocode、Opencode 和 Opencode Go 通过 `passthrough-gemini` replay 家族使用 `buildReplayPolicy`， + 因为它们通过 OpenAI 兼容传输代理 Gemini + 模型，并需要 Gemini + thought-signature 清洗，而不需要原生 Gemini replay 验证或 + 启动重写。 - MiniMax 通过 - `hybrid-anthropic-openai` replay 家族使用 `buildReplayPolicy`，因为同一个 provider 同时拥有 Anthropic-message 和 OpenAI 兼容语义；它在 Anthropic 侧保留仅 Claude 的 thinking block 丢弃，同时将推理输出模式覆盖回原生，而 `minimax-fast-mode` 流家族则在共享流路径上拥有 fast-mode 模型重写。 -- Moonshot 使用 `catalog` 以及 `wrapStreamFn`，因为它仍使用共享的 OpenAI 传输，但需要 provider 自有的 thinking 载荷规范化；`moonshot-thinking` 流家族将配置和 `/think` 状态映射到其原生二元 thinking 载荷。 + `hybrid-anthropic-openai` replay 家族使用 `buildReplayPolicy`，因为同一个提供商同时拥有 + Anthropic-message 和 OpenAI 兼容语义；它会在 Anthropic 侧保留只针对 Claude 的 + thinking-block 丢弃，同时将推理输出模式覆盖回原生，而 + `minimax-fast-mode` 流家族则拥有共享流路径上的快速模式模型重写。 +- Moonshot 使用 `catalog` 加 `wrapStreamFn`，因为它仍使用共享 + OpenAI 传输，但需要提供商自有的 thinking 载荷规范化； + `moonshot-thinking` 流家族会将配置加 `/think` 状态映射到其 + 原生二元 thinking 载荷。 - Kilocode 使用 `catalog`、`capabilities`、`wrapStreamFn` 和 - `isCacheTtlEligible`，因为它需要 provider 自有请求头、推理载荷规范化、Gemini 转录提示和 Anthropic 缓存 TTL 门控；`kilocode-thinking` 流家族则在共享代理流路径上保留 Kilo thinking 注入，同时跳过 `kilo/auto` 以及其他不支持显式推理载荷的代理 model id。 + `isCacheTtlEligible`，因为它需要提供商自有请求头、 + 推理载荷规范化、Gemini 转录提示和 Anthropic + 缓存 TTL 门控；`kilocode-thinking` 流家族在共享代理流路径上保留 Kilo thinking + 注入，同时跳过 `kilo/auto` 和 + 其他不支持显式推理载荷的代理模型 id。 - Z.AI 使用 `resolveDynamicModel`、`prepareExtraParams`、`wrapStreamFn`、 `isCacheTtlEligible`、`isBinaryThinking`、`isModernModelRef`、 `resolveUsageAuth` 和 `fetchUsageSnapshot`，因为它拥有 GLM-5 回退、 - `tool_stream` 默认值、二元 thinking UX、现代模型匹配，以及用量凭证 + 配额抓取；`tool-stream-default-on` 流家族则让默认开启的 `tool_stream` 包装器不必写进各个 provider 的手写胶水代码中。 + `tool_stream` 默认值、二元 thinking UX、现代模型匹配，以及 + 使用量 auth + 配额抓取；`tool-stream-default-on` 流家族则让默认开启的 + `tool_stream` 包装器脱离每个提供商手写胶水代码。 - xAI 使用 `normalizeResolvedModel`、`normalizeTransport`、 `contributeResolvedModelCompat`、`prepareExtraParams`、`wrapStreamFn`、 `resolveSyntheticAuth`、`resolveDynamicModel` 和 `isModernModelRef`， - 因为它拥有原生 xAI Responses 传输规范化、Grok fast-mode 别名重写、默认 `tool_stream`、严格工具 / 推理载荷清理、用于插件自有工具的回退凭证复用、前向兼容的 Grok 模型解析，以及 provider 自有兼容性补丁，例如 xAI 工具 schema 档案、不支持的 schema 关键字、原生 `web_search`，以及 HTML 实体工具调用参数解码。 -- Mistral、OpenCode Zen 和 OpenCode Go 仅使用 `capabilities`，以将转录/工具特性保留在核心之外。 -- 仅目录型内置 providers，例如 `byteplus`、`cloudflare-ai-gateway`、 + 因为它拥有原生 xAI Responses 传输规范化、Grok 快速模式 + 别名重写、默认 `tool_stream`、严格工具 / 推理载荷 + 清理、面向插件自有工具的回退 auth 复用、前向兼容的 Grok + 模型解析，以及提供商自有兼容补丁，如 xAI 工具 schema + 配置文件、不受支持的 schema 关键字、原生 `web_search` 和 HTML 实体 + 工具调用参数解码。 +- Mistral、OpenCode Zen 和 OpenCode Go 只使用 `capabilities`，以便将转录 / 工具特性保留在核心之外。 +- 仅目录型的内置提供商，如 `byteplus`、`cloudflare-ai-gateway`、 `huggingface`、`kimi-coding`、`nvidia`、`qianfan`、 - `synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine`，仅使用 `catalog`。 -- Qwen 对其文本 provider 使用 `catalog`，并对其多模态接口注册共享的媒体理解和视频生成能力。 -- MiniMax 和 Xiaomi 使用 `catalog` 以及用量 hooks，因为尽管推理仍通过共享传输运行，但它们的 `/usage` 行为属于插件自有。 + `synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine` 仅使用 + `catalog`。 +- Qwen 使用 `catalog` 作为其文本提供商，同时为其多模态表面注册共享媒体理解和视频生成能力。 +- MiniMax 和 Xiaomi 使用 `catalog` 加使用量钩子，因为虽然推理仍通过共享传输运行，但它们的 `/usage` 行为由插件拥有。 ## 运行时辅助工具 -插件可以通过 `api.runtime` 访问部分核心辅助工具。对于 TTS： +插件可以通过 `api.runtime` 访问部分核心辅助工具。以 TTS 为例： ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -711,14 +750,14 @@ const voices = await api.runtime.tts.listVoices({ 说明： -- `textToSpeech` 返回适用于文件/语音便笺接口的标准核心 TTS 输出载荷。 -- 使用核心 `messages.tts` 配置和 provider 选择。 -- 返回 PCM 音频缓冲区 + 采样率。插件必须为 providers 重新采样/编码。 -- `listVoices` 对每个 provider 都是可选的。可将其用于 vendor 自有语音选择器或 setup 流程。 -- 语音列表可以包含更丰富的元数据，例如区域设置、性别和个性标签，以支持 provider 感知的选择器。 -- 当前支持电话模式的是 OpenAI 和 ElevenLabs。Microsoft 不支持。 +- `textToSpeech` 返回普通核心 TTS 输出载荷，用于文件 / 语音便笺表面。 +- 使用核心 `messages.tts` 配置和提供商选择。 +- 返回 PCM 音频缓冲区 + 采样率。插件必须针对各提供商自行重采样 / 编码。 +- `listVoices` 对每个提供商来说都是可选的。可将其用于供应商自有的语音选择器或设置流程。 +- 语音列表可以包含更丰富的元数据，例如 locale、gender 和 personality 标签，以供提供商感知型选择器使用。 +- 目前 OpenAI 和 ElevenLabs 支持电话场景。Microsoft 不支持。 -插件还可以通过 `api.registerSpeechProvider(...)` 注册语音 providers。 +插件还可以通过 `api.registerSpeechProvider(...)` 注册语音提供商。 ```ts api.registerSpeechProvider({ @@ -738,12 +777,12 @@ api.registerSpeechProvider({ 说明： -- 将 TTS 策略、回退和回复投递保留在核心中。 -- 使用语音 providers 承载 vendor 自有合成行为。 -- 传统 Microsoft `edge` 输入会被规范化为 `microsoft` provider id。 -- 推荐的所有权模型是面向公司的：随着 OpenClaw 增加这些能力契约，一个 vendor 插件可以同时拥有文本、语音、图像和未来的媒体 providers。 +- 将 TTS 策略、回退和回复交付保留在核心中。 +- 使用语音提供商承载供应商自有的合成行为。 +- 旧版 Microsoft `edge` 输入会被规范化为 `microsoft` provider id。 +- 首选的所有权模型是面向公司的：随着 OpenClaw 增加这些能力契约，一个供应商插件可以拥有文本、语音、图像和未来媒体提供商。 -对于图像/音频/视频理解，插件应注册一个类型化的媒体理解 provider，而不是通用键值包： +对于图像 / 音频 / 视频理解，插件会注册一个类型化的媒体理解提供商，而不是通用 key/value 包： ```ts api.registerMediaUnderstandingProvider({ @@ -758,12 +797,12 @@ api.registerMediaUnderstandingProvider({ 说明： - 将编排、回退、配置和渠道接线保留在核心中。 -- 将 vendor 行为保留在 provider 插件中。 +- 将供应商行为保留在提供商插件中。 - 增量扩展应保持类型化：新的可选方法、新的可选结果字段、新的可选能力。 -- 视频生成也已遵循相同模式： +- 视频生成也已经采用同样的模式： - 核心拥有能力契约和运行时辅助工具 - - vendor 插件注册 `api.registerVideoGenerationProvider(...)` - - 功能/渠道插件消费 `api.runtime.videoGeneration.*` + - 供应商插件注册 `api.registerVideoGenerationProvider(...)` + - 功能 / 渠道插件消费 `api.runtime.videoGeneration.*` 对于媒体理解运行时辅助工具，插件可以调用： @@ -780,7 +819,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -对于音频转录，插件既可以使用媒体理解运行时，也可以使用旧的 STT 别名： +对于音频转录，插件可以使用媒体理解运行时，也可以使用较旧的 STT 别名： ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -793,10 +832,10 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ 说明： -- `api.runtime.mediaUnderstanding.*` 是图像/音频/视频理解的首选共享接口。 -- 使用核心媒体理解音频配置（`tools.media.audio`）和 provider 回退顺序。 -- 当没有产生转录输出时（例如输入被跳过/不受支持），返回 `{ text: undefined }`。 -- `api.runtime.stt.transcribeAudioFile(...)` 仍保留为兼容性别名。 +- `api.runtime.mediaUnderstanding.*` 是图像 / 音频 / 视频理解的首选共享表面。 +- 使用核心媒体理解音频配置（`tools.media.audio`）和提供商回退顺序。 +- 当没有产生转录输出时，返回 `{ text: undefined }`（例如跳过 / 不受支持的输入）。 +- `api.runtime.stt.transcribeAudioFile(...)` 仍作为兼容别名保留。 插件还可以通过 `api.runtime.subagent` 启动后台子智能体运行： @@ -812,13 +851,13 @@ const result = await api.runtime.subagent.run({ 说明： -- `provider` 和 `model` 是每次运行的可选覆盖项，不是持久性会话变更。 -- OpenClaw 只会为受信任调用方启用这些覆盖字段。 -- 对于插件自有回退运行，操作员必须通过 `plugins.entries..subagent.allowModelOverride: true` 显式启用。 -- 使用 `plugins.entries..subagent.allowedModels` 可将受信任插件限制到特定的规范 `provider/model` 目标，或使用 `"*"` 明确允许任意目标。 -- 不受信任插件的子智能体运行仍然可用，但其覆盖请求会被拒绝，而不是静默回退。 +- `provider` 和 `model` 是每次运行可选覆盖项，不会持久化改变会话设置。 +- OpenClaw 仅对受信任调用方启用这些覆盖字段。 +- 对于插件自有回退运行，操作员必须通过 `plugins.entries..subagent.allowModelOverride: true` 明确启用。 +- 使用 `plugins.entries..subagent.allowedModels` 将受信任插件限制到特定规范 `provider/model` 目标，或显式使用 `"*"` 允许任意目标。 +- 不受信任插件的子智能体运行仍然可用，但覆盖请求会被拒绝，而不是静默回退。 -对于 Web 搜索，插件可以消费共享运行时辅助工具，而不必深入智能体工具接线： +对于 Web 搜索，插件可以消费共享运行时辅助工具，而不是深入智能体工具接线： ```ts const providers = api.runtime.webSearch.listProviders({ @@ -835,13 +874,13 @@ const result = await api.runtime.webSearch.search({ ``` 插件还可以通过 -`api.registerWebSearchProvider(...)` 注册 Web 搜索 providers。 +`api.registerWebSearchProvider(...)` 注册 Web 搜索提供商。 说明： -- 将 provider 选择、凭证解析和共享请求语义保留在核心中。 -- 使用 Web 搜索 providers 承载 vendor 特定搜索传输。 -- `api.runtime.webSearch.*` 是功能/渠道插件在不依赖智能体工具包装器的情况下获取搜索能力的首选共享接口。 +- 将提供商选择、凭证解析和共享请求语义保留在核心中。 +- 使用 Web 搜索提供商承载供应商特定的搜索传输。 +- `api.runtime.webSearch.*` 是功能 / 渠道插件在需要搜索行为但不依赖智能体工具包装器时的首选共享表面。 ### `api.runtime.imageGeneration` @@ -856,8 +895,8 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`：使用已配置的图像生成 provider 链生成图像。 -- `listProviders(...)`：列出可用的图像生成 providers 及其能力。 +- `generate(...)`：使用已配置的图像生成提供商链生成图像。 +- `listProviders(...)`：列出可用的图像生成提供商及其能力。 ## Gateway 网关 HTTP 路由 @@ -879,31 +918,31 @@ api.registerHttpRoute({ 路由字段： - `path`：Gateway 网关 HTTP 服务器下的路由路径。 -- `auth`：必填。使用 `"gateway"` 表示要求常规 Gateway 网关认证，或使用 `"plugin"` 表示使用插件管理的认证/webhook 校验。 +- `auth`：必填。使用 `"gateway"` 表示要求常规 Gateway 网关认证，或使用 `"plugin"` 表示由插件管理认证 / webhook 验证。 - `match`：可选。`"exact"`（默认）或 `"prefix"`。 -- `replaceExisting`：可选。允许同一插件替换其已存在的路由注册。 -- `handler`：当路由已处理请求时返回 `true`。 +- `replaceExisting`：可选。允许同一插件替换其自己现有的路由注册。 +- `handler`：当路由处理了请求时返回 `true`。 说明： - `api.registerHttpHandler(...)` 已被移除，并会导致插件加载错误。请改用 `api.registerHttpRoute(...)`。 - 插件路由必须显式声明 `auth`。 -- 精确的 `path + match` 冲突会被拒绝，除非设置 `replaceExisting: true`，且一个插件不能替换另一个插件的路由。 -- 不同 `auth` 级别的重叠路由会被拒绝。仅应在相同认证级别下保留 `exact`/`prefix` 级联链。 -- `auth: "plugin"` 路由**不会**自动接收操作员运行时作用域。它们用于插件管理的 webhook/签名校验，而不是特权 Gateway 网关辅助调用。 -- `auth: "gateway"` 路由会在 Gateway 网关请求运行时作用域内执行，但该作用域有意保持保守： +- 精确的 `path + match` 冲突会被拒绝，除非设置 `replaceExisting: true`，并且一个插件不能替换另一个插件的路由。 +- `auth` 级别不同的重叠路由会被拒绝。请仅在相同 auth 级别内保留 `exact` / `prefix` 的贯穿链。 +- `auth: "plugin"` 路由**不会**自动接收运维人员运行时作用域。它们用于插件管理的 webhook / 签名验证，而不是特权 Gateway 网关辅助工具调用。 +- `auth: "gateway"` 路由会在 Gateway 网关请求运行时作用域中运行，但该作用域被有意保持保守： - 共享密钥 bearer 认证（`gateway.auth.mode = "token"` / `"password"`）会将插件路由运行时作用域固定为 `operator.write`，即使调用方发送了 `x-openclaw-scopes` - - 可信、携带身份的 HTTP 模式（例如 `trusted-proxy` 或私有入口下的 `gateway.auth.mode = "none"`）仅会在请求显式携带该 header 时尊重 `x-openclaw-scopes` - - 如果这些携带身份的插件路由请求缺少 `x-openclaw-scopes`，则运行时作用域会回退为 `operator.write` -- 实际规则：不要假设一个 Gateway 网关认证的插件路由天然就是管理接口。如果你的路由需要仅管理员可用的行为，请要求使用携带身份的认证模式，并文档化显式的 `x-openclaw-scopes` header 契约。 + - 受信任且携带身份的 HTTP 模式（例如 `trusted-proxy` 或私有入口上的 `gateway.auth.mode = "none"`）只有在显式存在 `x-openclaw-scopes` 头时，才会尊重它 + - 如果这些携带身份的插件路由请求中缺少 `x-openclaw-scopes`，运行时作用域会回退为 `operator.write` +- 实践规则：不要假设一个通过 gateway 认证的插件路由天然就是管理面。如果你的路由需要仅管理员行为，请要求使用带身份的认证模式，并记录显式 `x-openclaw-scopes` 头契约。 ## 插件 SDK 导入路径 -在编写插件时，请使用 SDK 子路径，而不是单体式 `openclaw/plugin-sdk` 导入： +编写插件时，请使用 SDK 子路径，而不是单体式 `openclaw/plugin-sdk` 导入： -- `openclaw/plugin-sdk/plugin-entry` 用于插件注册原语。 -- `openclaw/plugin-sdk/core` 用于通用共享的面向插件契约。 -- `openclaw/plugin-sdk/config-schema` 用于根 `openclaw.json` Zod schema +- `openclaw/plugin-sdk/plugin-entry`：用于插件注册原语。 +- `openclaw/plugin-sdk/core`：用于通用共享的面向插件契约。 +- `openclaw/plugin-sdk/config-schema`：用于根 `openclaw.json` Zod schema 导出（`OpenClawSchema`）。 - 稳定的渠道原语，例如 `openclaw/plugin-sdk/channel-setup`、 `openclaw/plugin-sdk/setup-runtime`、 @@ -916,13 +955,15 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-lifecycle`、 `openclaw/plugin-sdk/channel-reply-pipeline`、 `openclaw/plugin-sdk/command-auth`、 - `openclaw/plugin-sdk/secret-input`，以及 - `openclaw/plugin-sdk/webhook-ingress`，用于共享的 setup/凭证/回复/webhook - 接线。`channel-inbound` 是 debounce、mention 匹配、入站 mention-policy 辅助工具、envelope 格式化和入站 envelope 上下文辅助工具的共享归属。 - `channel-setup` 是可选安装 setup 的窄接缝。 - `setup-runtime` 是 `setupEntry` / 延迟启动使用的运行时安全 setup 接口，其中包括可安全导入的 setup patch 适配器。 - `setup-adapter-runtime` 是具备环境感知能力的账户 setup 适配器接缝。 - `setup-tools` 是小型 CLI/归档/文档辅助接缝（`formatCliCommand`、 + `openclaw/plugin-sdk/secret-input` 和 + `openclaw/plugin-sdk/webhook-ingress`，用于共享设置 / 认证 / 回复 / webhook + 接线。`channel-inbound` 是共享的归属位置，用于防抖、提及匹配、 + 入站提及策略辅助工具、信封格式化以及入站信封上下文辅助工具。 + `channel-setup` 是范围较窄的可选安装设置接缝。 + `setup-runtime` 是 `setupEntry` / + 延迟启动使用的运行时安全设置表面，其中包括导入安全的设置补丁适配器。 + `setup-adapter-runtime` 是感知环境的账户设置适配器接缝。 + `setup-tools` 是小型 CLI / archive / docs 辅助工具接缝（`formatCliCommand`、 `detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、 `CONFIG_DIR`）。 - 领域子路径，例如 `openclaw/plugin-sdk/channel-config-helpers`、 @@ -930,6 +971,8 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-config-schema`、 `openclaw/plugin-sdk/telegram-command-config`、 `openclaw/plugin-sdk/channel-policy`、 + `openclaw/plugin-sdk/approval-gateway-runtime`、 + `openclaw/plugin-sdk/approval-handler-adapter-runtime`、 `openclaw/plugin-sdk/approval-handler-runtime`、 `openclaw/plugin-sdk/approval-runtime`、 `openclaw/plugin-sdk/config-runtime`、 @@ -940,150 +983,169 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/routing`、 `openclaw/plugin-sdk/status-helpers`、 `openclaw/plugin-sdk/text-runtime`、 - `openclaw/plugin-sdk/runtime-store`，以及 - `openclaw/plugin-sdk/directory-runtime`，用于共享运行时/配置辅助工具。 - `telegram-command-config` 是 Telegram 自定义命令规范化/验证的狭义公共接缝，即使内置 Telegram 契约接口暂时不可用，它也仍可用。 - `text-runtime` 是共享的文本/Markdown/日志接缝，包括面向 assistant 可见文本的剥离、Markdown 渲染/分块辅助工具、脱敏辅助工具、directive tag 辅助工具和安全文本工具。 -- 审批专用的渠道接缝应优先采用插件上的单一 `approvalCapability` - 契约。随后核心会通过这一个能力读取审批认证、投递、渲染、原生路由和惰性原生处理器行为，而不是将审批行为混入不相关的插件字段中。 -- `openclaw/plugin-sdk/channel-runtime` 已弃用，仅作为旧插件的兼容性 shim 保留。新代码应改用更窄的通用原语导入，仓库代码也不应新增对该 shim 的导入。 -- 内置扩展内部实现仍然是私有的。外部插件应只使用 - `openclaw/plugin-sdk/*` 子路径。OpenClaw 核心/测试代码可以使用插件包根目录下的仓库公共入口点，例如 `index.js`、`api.js`、 + `openclaw/plugin-sdk/runtime-store` 和 + `openclaw/plugin-sdk/directory-runtime`，用于共享运行时 / 配置辅助工具。 + `telegram-command-config` 是 Telegram 自定义 + 命令规范化 / 验证的窄公共接缝，即使内置 + Telegram 契约表面暂时不可用，它也仍保持可用。 + `text-runtime` 是共享文本 / markdown / 日志接缝，其中包括 + 面向 assistant 的可见文本剥离、markdown 渲染 / 分块辅助工具、脱敏 + 辅助工具、directive-tag 辅助工具，以及 safe-text 工具。 +- 审批专用渠道接缝应优先使用插件上的单一 `approvalCapability` + 契约。然后核心通过这一能力读取审批认证、交付、渲染、 + 原生路由和延迟原生处理器行为，而不是将审批行为混入无关插件字段。 +- `openclaw/plugin-sdk/channel-runtime` 已弃用，仅作为旧版插件的 + 兼容 shim 保留。新代码应改为导入更窄的通用原语，仓库代码也不应新增对该 shim 的导入。 +- 内置扩展内部实现仍属于私有。外部插件应只使用 `openclaw/plugin-sdk/*` + 子路径。OpenClaw 核心 / 测试代码可以使用插件包根目录下的仓库公共入口点， + 例如 `index.js`、`api.js`、 `runtime-api.js`、`setup-entry.js`，以及范围更窄的文件，例如 - `login-qr-api.js`。绝不要从核心或其他扩展中导入某个插件包的 `src/*`。 + `login-qr-api.js`。切勿从核心或其他扩展中导入某个插件包的 `src/*`。 - 仓库入口点拆分： - `/api.js` 是辅助工具/类型 barrel， + `/api.js` 是辅助工具 / 类型 barrel， `/runtime-api.js` 是仅运行时 barrel， `/index.js` 是内置插件入口， - `/setup-entry.js` 是 setup 插件入口。 -- 当前内置 provider 示例： - - Anthropic 使用 `api.js` / `contract-api.js` 承载 Claude 流辅助工具，例如 `wrapAnthropicProviderStream`、beta header 辅助工具和 `service_tier` + `/setup-entry.js` 是设置插件入口。 +- 当前内置提供商示例： + - Anthropic 使用 `api.js` / `contract-api.js` 提供 Claude 流辅助工具， + 例如 `wrapAnthropicProviderStream`、beta-header 辅助工具和 `service_tier` 解析。 - - OpenAI 使用 `api.js` 承载 provider 构建器、默认模型辅助工具和实时 provider 构建器。 - - OpenRouter 使用 `api.js` 承载其 provider 构建器以及新手引导/配置辅助工具，而 `register.runtime.js` 仍可为仓库本地使用重新导出通用 + - OpenAI 使用 `api.js` 提供提供商构建器、默认模型辅助工具和 + 实时提供商构建器。 + - OpenRouter 使用 `api.js` 提供其提供商构建器以及 onboarding / 配置 + 辅助工具，而 `register.runtime.js` 仍可为仓库本地用途重新导出通用 `plugin-sdk/provider-stream` 辅助工具。 -- 通过 facade 加载的公共入口点会优先使用当前活动的运行时配置快照；若 OpenClaw 尚未提供运行时快照，则回退到磁盘上的已解析配置文件。 -- 通用共享原语仍是首选的公共 SDK 契约。仍然保留了一小部分带有内置渠道品牌的辅助工具接缝以作兼容。应将它们视为内置维护/兼容接缝，而不是新的第三方导入目标；新的跨渠道契约仍应落到通用 `plugin-sdk/*` 子路径或插件本地 `api.js` / - `runtime-api.js` barrel 上。 +- 通过 facade 加载的公共入口点，在存在活动运行时配置快照时会优先使用它， + 否则在 OpenClaw 尚未提供运行时快照时，会回退到磁盘上的已解析配置文件。 +- 通用共享原语仍然是首选的公共 SDK 契约。仍然存在一小组保留的、 + 带内置渠道品牌的兼容辅助工具接缝。应将它们视为内置维护 / 兼容性接缝，而不是新的 + 第三方导入目标；新的跨渠道契约仍应落在通用 `plugin-sdk/*` 子路径或 + 插件本地 `api.js` / `runtime-api.js` barrel 上。 兼容性说明： -- 新代码应避免使用根 `openclaw/plugin-sdk` barrel。 -- 优先使用更窄且稳定的原语。较新的 setup/pairing/reply/ - feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool 子路径，是新的内置和外部插件工作的预期契约。 - 目标解析/匹配应放在 `openclaw/plugin-sdk/channel-targets`。 - 消息动作 gate 和 reaction message id 辅助工具应放在 +- 新代码请避免使用根 `openclaw/plugin-sdk` barrel。 +- 优先使用范围更窄的稳定原语。较新的 setup / pairing / reply / + feedback / contract / inbound / threading / command / secret-input / webhook / infra / + allowlist / status / message-tool 子路径，是面向新 + 内置和外部插件工作的预期契约。 + 目标解析 / 匹配应放在 `openclaw/plugin-sdk/channel-targets`。 + 消息动作门禁和 reaction message-id 辅助工具应放在 `openclaw/plugin-sdk/channel-actions`。 -- 内置扩展专用辅助 barrel 默认不稳定。如果某个辅助工具只被内置扩展需要，请将其保留在扩展本地的 `api.js` 或 `runtime-api.js` 接缝后面，而不是提升为 +- 内置扩展特定的辅助工具 barrel 默认不稳定。如果一个 + 辅助工具只被某个内置扩展需要，请将它保留在该扩展本地的 + `api.js` 或 `runtime-api.js` 接缝之后，而不是将其提升到 `openclaw/plugin-sdk/`。 -- 新的共享辅助接缝应当是通用的，而不是渠道品牌化的。共享目标解析应放在 `openclaw/plugin-sdk/channel-targets`；渠道特定内部实现则保留在所属插件本地的 `api.js` 或 `runtime-api.js` 接缝之后。 -- `image-generation`、 - `media-understanding` 和 `speech` 这类能力专用子路径之所以存在，是因为当前内置/原生插件正在使用它们。但这并不自动意味着其中每个导出的辅助工具都是长期冻结的外部契约。 +- 新的共享辅助工具接缝应是通用的，而不是带渠道品牌的。共享目标 + 解析应归属于 `openclaw/plugin-sdk/channel-targets`；渠道特定 + 内部实现则保留在拥有它的插件本地 `api.js` 或 `runtime-api.js` + 接缝之后。 +- 诸如 `image-generation`、 + `media-understanding` 和 `speech` 之类的能力特定子路径之所以存在，是因为内置 / 原生插件今天正在使用它们。它们的存在本身并不意味着所有导出的辅助工具都是长期冻结的外部契约。 -## Message 工具 schema +## 消息工具 schema 插件应拥有渠道特定的 `describeMessageTool(...)` schema -贡献。将 provider 特定字段保留在插件中，而不是放入共享核心。 +贡献。请将提供商特定字段保留在插件中，而不是放在共享核心中。 对于共享的可移植 schema 片段，请复用通过 `openclaw/plugin-sdk/channel-actions` 导出的通用辅助工具： -- `createMessageToolButtonsSchema()` 用于按钮网格样式载荷 -- `createMessageToolCardSchema()` 用于结构化卡片载荷 +- `createMessageToolButtonsSchema()`：用于按钮网格样式载荷 +- `createMessageToolCardSchema()`：用于结构化卡片载荷 -如果某种 schema 形状只适用于某一个 provider，就应在该插件自己的源代码中定义，而不是提升进共享 SDK。 +如果某个 schema 形状只适用于一个提供商，请在该插件自己的 +源代码中定义它，而不是将其提升到共享 SDK 中。 ## 渠道目标解析 -渠道插件应拥有渠道特定的目标语义。保持共享出站宿主的通用性，并使用消息适配器接口承载 provider 规则： +渠道插件应拥有渠道特定的目标语义。请保持共享 outbound host 的通用性，并使用消息适配器表面承载提供商规则： -- `messaging.inferTargetChatType({ to })` 决定一个已规范化目标在目录查找前应被视为 `direct`、`group` 还是 `channel`。 -- `messaging.targetResolver.looksLikeId(raw, normalized)` 告诉核心某个输入是否应直接跳过目录搜索，转入类似 id 的解析。 -- `messaging.targetResolver.resolveTarget(...)` 是核心在规范化后或目录未命中后，需要最终 provider 自有解析时使用的插件回退路径。 -- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后负责 provider 特定的会话路由构造。 +- `messaging.inferTargetChatType({ to })` 用于在目录查找前，决定某个规范化目标应被视为 `direct`、`group` 还是 `channel`。 +- `messaging.targetResolver.looksLikeId(raw, normalized)` 用于告诉核心，某个输入是否应跳过目录搜索，直接进入类 id 解析。 +- `messaging.targetResolver.resolveTarget(...)` 是插件回退路径，用于核心在规范化后或目录未命中后，需要做最终的提供商自有解析。 +- `messaging.resolveOutboundSessionRoute(...)` 在目标解析完成后，拥有提供商特定的会话路由构建逻辑。 -推荐拆分方式： +推荐拆分： -- 使用 `inferTargetChatType` 处理应在搜索 peers/groups 之前发生的分类决策。 -- 使用 `looksLikeId` 处理“将其视为显式/原生目标 id”的判断。 -- 将 `resolveTarget` 用于 provider 特定规范化回退，而不是宽泛的目录搜索。 -- 将 provider 原生 id，例如 chat id、thread id、JID、handle 和 room id，保留在 `target` 值或 provider 特定参数中，而不是通用 SDK 字段里。 +- 对于应在搜索 peers / groups 之前完成的类别决策，使用 `inferTargetChatType`。 +- 对于“将此视为显式 / 原生目标 id”的检查，使用 `looksLikeId`。 +- 对于提供商特定的规范化回退，使用 `resolveTarget`，而不要把它用于广泛的目录搜索。 +- 将提供商原生 id，如 chat id、thread id、JID、handle 和 room id，保留在 `target` 值或提供商特定参数中，而不是放进通用 SDK 字段。 -## 配置支持的目录 +## 基于配置的目录 -如果插件需要从配置派生目录项，应将该逻辑保留在插件内部，并复用 +对于从配置派生目录条目的插件，应将这部分逻辑保留在插件中，并复用 `openclaw/plugin-sdk/directory-runtime` 中的共享辅助工具。 -当某个渠道需要配置支持的 peers/groups 时可使用它，例如： +当某个渠道需要基于配置的 peers / groups 时，可使用此方式，例如： - 基于 allowlist 的私信 peers -- 已配置的渠道/群组映射 -- 账户作用域的静态目录回退 +- 已配置的 channel / group 映射 +- 按账户划分的静态目录回退 `directory-runtime` 中的共享辅助工具只处理通用操作： - 查询过滤 -- 限制应用 -- 去重/规范化辅助工具 +- 限制数量应用 +- 去重 / 规范化辅助工具 - 构建 `ChannelDirectoryEntry[]` 渠道特定的账户检查和 id 规范化应保留在插件实现中。 -## Provider 目录 +## 提供商目录 -Provider 插件可以通过 -`registerProvider({ catalog: { run(...) { ... } } })` 定义推理模型目录。 +提供商插件可以通过 +`registerProvider({ catalog: { run(...) { ... } } })` 定义用于推理的模型目录。 `catalog.run(...)` 返回与 OpenClaw 写入 -`models.providers` 相同的结构： +`models.providers` 相同的形状： -- `{ provider }` 表示一个 provider 条目 -- `{ providers }` 表示多个 provider 条目 +- `{ provider }`：单个 provider 条目 +- `{ providers }`：多个 provider 条目 -当插件拥有 provider 特定 model id、base URL 默认值或受凭证控制的模型元数据时，请使用 `catalog`。 +当插件拥有提供商特定 model id、base URL 默认值或受 auth 门控的模型元数据时，请使用 `catalog`。 -`catalog.order` 控制插件目录相对于 OpenClaw 内置隐式 providers 的合并时机： +`catalog.order` 控制插件目录相对于 OpenClaw 内置隐式提供商的合并时机： -- `simple`：简单 API key 或环境变量驱动的 providers -- `profile`：存在凭证档案时出现的 providers -- `paired`：会合成多个相关 provider 条目的 providers -- `late`：最后阶段，在其他隐式 providers 之后 +- `simple`：纯 API key 或环境变量驱动的提供商 +- `profile`：存在 auth profile 时出现的提供商 +- `paired`：合成多个相关提供商条目的提供商 +- `late`：最后一轮，在其他隐式提供商之后 -后出现的 provider 在键冲突时获胜，因此插件可以有意用相同 provider id 覆盖内置 provider 条目。 +后合并的提供商在键冲突时获胜，因此插件可以有意用同一 provider id 覆盖某个内置提供商条目。 兼容性： -- `discovery` 仍可作为传统别名使用 +- `discovery` 仍然作为旧版别名可用 - 如果同时注册了 `catalog` 和 `discovery`，OpenClaw 会使用 `catalog` ## 只读渠道检查 -如果你的插件注册了某个渠道，请优先实现 -`plugin.config.inspectAccount(cfg, accountId)`，并同时实现 `resolveAccount(...)`。 +如果你的插件注册了一个渠道，请优先在 `resolveAccount(...)` 旁边实现 +`plugin.config.inspectAccount(cfg, accountId)`。 原因如下： -- `resolveAccount(...)` 是运行时路径。它可以假定凭证已经完全实体化，并在缺少必需 secret 时快速失败。 -- `openclaw status`、`openclaw status --all`、 - `openclaw channels status`、`openclaw channels resolve` 以及 doctor/配置修复流程等只读命令路径，不应为了描述配置就必须实体化运行时凭证。 +- `resolveAccount(...)` 是运行时路径。它可以假设凭证已经被完全具体化，并且在所需 secret 缺失时快速失败。 +- 诸如 `openclaw status`、`openclaw status --all`、 + `openclaw channels status`、`openclaw channels resolve` 以及 doctor / 配置修复流程等只读命令路径，不应该为了描述配置，就必须具体化运行时凭证。 推荐的 `inspectAccount(...)` 行为： -- 仅返回描述性的账户状态。 +- 只返回描述性的账户状态。 - 保留 `enabled` 和 `configured`。 -- 在相关时包含凭证来源/状态字段，例如： +- 在相关时包含凭证来源 / 状态字段，例如： - `tokenSource`、`tokenStatus` - `botTokenSource`、`botTokenStatus` - `appTokenSource`、`appTokenStatus` - `signingSecretSource`、`signingSecretStatus` -- 你不需要返回原始 token 值来报告只读可用性。返回 - `tokenStatus: "available"`（以及对应的来源字段）即可满足状态类命令。 +- 你不需要为了报告只读可用性而返回原始 token 值。返回 `tokenStatus: "available"`（以及匹配的 source 字段）就足以用于 status 类命令。 - 当凭证通过 SecretRef 配置，但在当前命令路径中不可用时，请使用 `configured_unavailable`。 -这样，只读命令就能报告“已配置，但在当前命令路径中不可用”，而不是崩溃或误报账户未配置。 +这样只读命令就能报告“已配置，但在当前命令路径中不可用”，而不是崩溃或错误地报告该账户尚未配置。 -## 包 pack +## Package packs 一个插件目录可以包含带有 `openclaw.extensions` 的 `package.json`： @@ -1097,43 +1159,47 @@ Provider 插件可以通过 } ``` -每个条目都会成为一个插件。如果 pack 列出多个扩展，插件 id -会变为 `name/`。 +每个条目都会成为一个插件。如果该 pack 列出了多个扩展，则插件 id +将变为 `name/`。 -如果你的插件导入了 npm 依赖，请在该目录中安装它们，以便 +如果你的插件导入了 npm 依赖，请在该目录中安装这些依赖，以便 `node_modules` 可用（`npm install` / `pnpm install`）。 -安全护栏：每个 `openclaw.extensions` 条目在解析符号链接后都必须保留在插件目录内。任何逃出包目录的条目都会被拒绝。 +安全护栏：每个 `openclaw.extensions` 条目在解析符号链接后都必须保持在插件目录内。逃离包目录的条目会被拒绝。 -安全说明：`openclaw plugins install` 会使用 -`npm install --omit=dev --ignore-scripts` 安装插件依赖（无生命周期脚本，运行时无开发依赖）。请保持插件依赖树为“纯 JS/TS”，并避免需要 `postinstall` 构建的包。 +安全说明：`openclaw plugins install` 会通过 +`npm install --omit=dev --ignore-scripts` 安装插件依赖（运行时不执行生命周期脚本，也不安装 dev 依赖）。请保持插件依赖树为“纯 JS/TS”，并避免使用那些需要 `postinstall` 构建的包。 -可选：`openclaw.setupEntry` 可以指向一个轻量级的仅 setup 模块。 -当 OpenClaw 需要为已禁用的渠道插件提供 setup 接口，或者某个渠道插件已启用但仍未配置时，它会加载 `setupEntry` 而不是完整插件入口。这样，当你的主插件入口还会接线工具、hooks 或其他仅运行时代码时，启动和 setup 都会更轻量。 +可选：`openclaw.setupEntry` 可以指向一个轻量级、仅用于设置的模块。 +当 OpenClaw 需要为已禁用的渠道插件提供设置表面时，或者 +当渠道插件已启用但仍未配置时，它会加载 `setupEntry`，而不是完整插件入口。这样在你的主插件入口还会接线工具、钩子或其他仅运行时代码时，可以让启动和设置更轻量。 可选：`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -可以让渠道插件在 gateway 的监听前启动阶段，即使渠道已经完成配置，也选择使用同样的 `setupEntry` 路径。 +可以让某个渠道插件在 Gateway 网关监听前的启动阶段，即使渠道已经配置好，也仍进入同一个 `setupEntry` 路径。 -仅当 `setupEntry` 已完整覆盖 gateway 开始监听前必须存在的启动接口时才应使用这一选项。实际来说，这意味着 setup 入口必须注册启动所依赖的每一种渠道自有能力，例如： +仅当 `setupEntry` 完全覆盖启动前必须存在的启动表面时，才应使用它。实际上，这意味着设置入口必须注册启动所依赖的每个渠道自有能力，例如： - 渠道注册本身 -- 任何必须在 gateway 开始监听前可用的 HTTP 路由 -- 在同一时间窗口中必须存在的任何 gateway 方法、工具或服务 +- 在 Gateway 网关开始监听前必须可用的所有 HTTP 路由 +- 在同一时间窗口内必须存在的所有 gateway 方法、工具或服务 -如果完整入口仍然拥有任何必需的启动能力，请不要启用此标志。保持插件使用默认行为，让 OpenClaw 在启动期间加载完整入口。 +如果你的完整入口仍拥有任何必需的启动能力，请不要启用此标志。请保留默认行为，让 OpenClaw 在启动期间加载完整入口。 -内置渠道还可以发布仅 setup 的契约接口辅助工具，供核心在完整渠道运行时加载前查询。当前 setup 提升接口为： +内置渠道还可以发布仅设置用的契约表面辅助工具，以便核心在完整渠道运行时加载前进行咨询。当前设置提升表面包括： - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -当核心需要在不加载完整插件入口的情况下，将传统单账户渠道配置提升为 `channels..accounts.*` 时，会使用这个接口。Matrix 是当前的内置示例：当已存在命名账户时，它只会将凭证/引导键移动到某个已命名的提升账户中，并且能够保留已配置的非规范默认账户键，而不是总创建 `accounts.default`。 +当核心需要在不加载完整插件入口的情况下，将旧版单账户渠道配置提升到 +`channels..accounts.*` 时，就会使用该表面。Matrix 是当前的内置示例：当已存在命名账户时，它只会将 auth / 启动键移动到一个命名提升账户中，并且能够保留一个已配置的非规范默认账户键，而不是总是创建 +`accounts.default`。 -这些 setup patch 适配器让内置契约接口发现保持惰性。导入时依然轻量；提升接口只会在首次使用时加载，而不会在模块导入时重新进入内置渠道启动过程。 +这些设置补丁适配器让内置契约表面发现保持延迟。导入时保持轻量；提升表面只会在首次使用时加载，而不是在模块导入时重新进入内置渠道启动过程。 -当这些启动接口包含 gateway RPC 方法时，请保持它们使用插件专用前缀。核心管理命名空间（`config.*`、 -`exec.approvals.*`、`wizard.*`、`update.*`）仍是保留的，并且始终解析为 `operator.admin`，即使某个插件请求更窄的作用域也是如此。 +当这些启动表面包含 Gateway 网关 RPC 方法时，请将它们保留在插件特定前缀下。核心管理命名空间（`config.*`、 +`exec.approvals.*`、`wizard.*`、`update.*`）仍然保留，并且始终解析为 +`operator.admin`，即使某个插件请求更窄的作用域也是如此。 示例： @@ -1152,8 +1218,7 @@ Provider 插件可以通过 ### 渠道目录元数据 -渠道插件可以通过 `openclaw.channel` 广告 setup/发现元数据，并通过 -`openclaw.install` 提供安装提示。这样核心目录即可保持无数据化。 +渠道插件可以通过 `openclaw.channel` 广告设置 / 发现元数据，并通过 `openclaw.install` 广告安装提示。这样可以保持核心目录无数据化。 示例： @@ -1181,37 +1246,37 @@ Provider 插件可以通过 } ``` -除最小示例外，还有一些实用的 `openclaw.channel` 字段： +除了最小示例之外，有用的 `openclaw.channel` 字段还包括： -- `detailLabel`：用于更丰富目录/状态接口的次级标签 +- `detailLabel`：更丰富目录 / 状态表面的次级标签 - `docsLabel`：覆盖文档链接文本 -- `preferOver`：该目录条目应优先于哪些低优先级插件/渠道 id -- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：选择界面文案控制 -- `markdownCapable`：将该渠道标记为支持 Markdown，用于出站格式决策 -- `exposure.configured`：设为 `false` 时，在已配置渠道列表界面中隐藏该渠道 -- `exposure.setup`：设为 `false` 时，在交互式 setup/配置选择器中隐藏该渠道 -- `exposure.docs`：在文档导航界面中将该渠道标记为内部/私有 -- `showConfigured` / `showInSetup`：仍因兼容性接受的传统别名；优先使用 `exposure` -- `quickstartAllowFrom`：使该渠道加入标准快速开始 `allowFrom` 流程 -- `forceAccountBinding`：即使仅存在一个账户，也要求显式账户绑定 -- `preferSessionLookupForAnnounceTarget`：在解析公告目标时优先使用会话查找 +- `preferOver`：该目录条目应优先于之显示的低优先级插件 / 渠道 id +- `selectionDocsPrefix`、`selectionDocsOmitLabel`、`selectionExtras`：选择表面文案控制 +- `markdownCapable`：将渠道标记为支持 markdown，以用于出站格式决策 +- `exposure.configured`：设为 `false` 时，在已配置渠道列表表面中隐藏该渠道 +- `exposure.setup`：设为 `false` 时，在交互式设置 / 配置选择器中隐藏该渠道 +- `exposure.docs`：将渠道标记为内部 / 私有，用于文档导航表面 +- `showConfigured` / `showInSetup`：旧版别名，出于兼容性仍可接受；推荐使用 `exposure` +- `quickstartAllowFrom`：让该渠道接入标准快速开始 `allowFrom` 流程 +- `forceAccountBinding`：即使只存在一个账户，也要求显式账户绑定 +- `preferSessionLookupForAnnounceTarget`：在解析 announce 目标时优先使用会话查找 -OpenClaw 还可以合并**外部渠道目录**（例如 MPM 注册表导出）。 -将 JSON 文件放在以下任一位置： +OpenClaw 还可以合并**外部渠道目录**（例如一个 MPM +注册表导出）。将 JSON 文件放在以下任一路径： - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（使用逗号/分号/`PATH` 分隔）。每个文件应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受将 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的传统别名。 +或者将 `OPENCLAW_PLUGIN_CATALOG_PATHS`（或 `OPENCLAW_MPM_CATALOG_PATHS`）指向一个或多个 JSON 文件（以逗号 / 分号 / `PATH` 分隔）。每个文件应包含 `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`。解析器也接受 `"packages"` 或 `"plugins"` 作为 `"entries"` 键的旧版别名。 ## 上下文引擎插件 -上下文引擎插件拥有会话上下文的摄取、组装和压缩编排。从你的插件中通过 -`api.registerContextEngine(id, factory)` 注册它们，然后使用 +上下文引擎插件拥有会话上下文编排，用于摄取、组装和压缩。可在你的插件中通过 +`api.registerContextEngine(id, factory)` 注册它们，然后用 `plugins.slots.contextEngine` 选择活动引擎。 -当你的插件需要替换或扩展默认上下文流水线，而不是仅添加内存搜索或 hooks 时，请使用这种方式。 +当你的插件需要替换或扩展默认上下文流水线，而不仅仅是增加 memory search 或钩子时，请使用此方式。 ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1239,7 +1304,8 @@ export default function (api) { } ``` -如果你的引擎**不**拥有压缩算法，请保持实现 `compact()`，并显式委托： +如果你的引擎**不**拥有压缩算法，请保持 `compact()` +已实现，并显式委托它： ```ts import { @@ -1276,37 +1342,39 @@ export default function (api) { ## 添加新能力 -当插件需要当前 API 无法容纳的行为时，不要通过私有深层调用绕过插件系统。应添加缺失的能力。 +当某个插件需要当前 API 不适配的行为时，不要通过私有深层调用绕过插件系统。请添加缺失的能力。 推荐顺序： 1. 定义核心契约 - 明确核心应拥有的共享行为：策略、回退、配置合并、生命周期、面向渠道的语义，以及运行时辅助工具形态。 -2. 添加类型化的插件注册/运行时接口 - 使用最小但有用的类型化能力接口扩展 `OpenClawPluginApi` 和/或 `api.runtime`。 -3. 对接核心 + 渠道/功能消费者 - 渠道和功能插件应通过核心消费新能力，而不是直接导入某个 vendor 实现。 -4. 注册 vendor 实现 - 然后由 vendor 插件将其后端注册到该能力上。 + 决定核心应拥有哪些共享行为：策略、回退、配置合并、 + 生命周期、面向渠道的语义以及运行时辅助工具形状。 +2. 添加类型化插件注册 / 运行时表面 + 以最小且有用的类型化能力表面扩展 `OpenClawPluginApi` 和 / 或 `api.runtime`。 +3. 连接核心 + 渠道 / 功能消费者 + 渠道和功能插件应通过核心消费该新能力， + 而不是直接导入某个供应商实现。 +4. 注册供应商实现 + 然后由供应商插件针对该能力注册它们的后端实现。 5. 添加契约覆盖 - 添加测试，以便所有权和注册形态在后续演进中保持显式。 + 添加测试，以便随着时间推移，所有权和注册形状仍保持显式。 -这就是 OpenClaw 保持有主见、却不被某个 provider 世界观硬编码绑死的方式。具体文件清单和完整示例请参见 [能力扩展手册](/zh-CN/plugins/architecture)。 +这正是 OpenClaw 能保持鲜明主张、同时又不被某个提供商世界观写死的方式。具体文件清单和完整示例，请参阅 [能力扩展手册](/zh-CN/plugins/architecture)。 ### 能力清单 -当你添加一个新能力时，通常应一并触及以下接口： +当你添加一个新能力时，通常应同时修改以下表面： - `src//types.ts` 中的核心契约类型 -- `src//runtime.ts` 中的核心 runner/运行时辅助工具 -- `src/plugins/types.ts` 中的插件 API 注册接口 +- `src//runtime.ts` 中的核心运行器 / 运行时辅助工具 +- `src/plugins/types.ts` 中的插件 API 注册表面 - `src/plugins/registry.ts` 中的插件注册表接线 -- 当功能/渠道插件需要消费它时，在 `src/plugins/runtime/*` 中暴露插件运行时 -- `src/test-utils/plugin-registration.ts` 中的捕获/测试辅助工具 -- `src/plugins/contracts/registry.ts` 中的所有权/契约断言 -- `docs/` 中面向操作员/插件的文档 +- 当功能 / 渠道插件需要消费它时，位于 `src/plugins/runtime/*` 中的插件运行时暴露 +- `src/test-utils/plugin-registration.ts` 中的捕获 / 测试辅助工具 +- `src/plugins/contracts/registry.ts` 中的所有权 / 契约断言 +- `docs/` 中的运维 / 插件文档 -如果其中某个接口缺失，通常说明该能力尚未被完整集成。 +如果其中某个表面缺失，通常意味着该能力尚未完全集成。 ### 能力模板 @@ -1342,9 +1410,9 @@ const clip = await api.runtime.videoGeneration.generate({ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -这样可以保持规则简单： +这样规则就很简单： - 核心拥有能力契约 + 编排 -- vendor 插件拥有 vendor 实现 -- 功能/渠道插件消费运行时辅助工具 -- 契约测试保持所有权显式化 +- 供应商插件拥有供应商实现 +- 功能 / 渠道插件消费运行时辅助工具 +- 契约测试保持所有权显式 diff --git a/docs/zh-CN/plugins/sdk-channel-plugins.md b/docs/zh-CN/plugins/sdk-channel-plugins.md index 944a83474..9d75f7bdb 100644 --- a/docs/zh-CN/plugins/sdk-channel-plugins.md +++ b/docs/zh-CN/plugins/sdk-channel-plugins.md @@ -1,160 +1,160 @@ --- read_when: - 你正在构建一个新的消息渠道插件 - - 你想将 OpenClaw 连接到一个消息平台 - - 你需要理解 ChannelPlugin 适配器接口 + - 你想要将 OpenClaw 连接到某个消息平台 + - 你需要理解 `ChannelPlugin` 适配器表面 sidebarTitle: Channel Plugins summary: 构建 OpenClaw 消息渠道插件的分步指南 title: 构建渠道插件 x-i18n: - generated_at: "2026-04-07T18:43:13Z" + generated_at: "2026-04-07T20:09:06Z" model: gpt-5.4 provider: openai - source_hash: b709fda7527fcf437b119c4668172804f2f9c9a46f5e39a2161467a4f5f1e42f + source_hash: d23365b6d92006b30e671f9f0afdba40a2b88c845c5d2299d71c52a52985672f source_path: plugins/sdk-channel-plugins.md workflow: 15 --- # 构建渠道插件 -本指南将带你逐步构建一个将 OpenClaw 连接到消息平台的渠道插件。完成后，你将拥有一个可用的渠道，支持私信安全、配对、回复线程和出站消息。 +本指南将带你完成一个渠道插件的构建，该插件用于将 OpenClaw 连接到某个消息平台。完成后，你将拥有一个可正常工作的渠道，具备私信安全、配对、回复线程和出站消息能力。 如果你之前还没有构建过任何 OpenClaw 插件，请先阅读 - [入门指南](/zh-CN/plugins/building-plugins) 以了解基础的软件包结构和清单设置。 + [入门指南](/zh-CN/plugins/building-plugins) 以了解基础包结构和清单设置。 ## 渠道插件如何工作 渠道插件不需要自己的发送/编辑/反应工具。OpenClaw 在核心中保留了一个共享的 `message` 工具。你的插件负责： -- **配置** — 账户解析和设置向导 +- **配置** — 账号解析和设置向导 - **安全** — 私信策略和允许列表 - **配对** — 私信批准流程 - **会话语法** — 提供商特定的会话 id 如何映射到基础聊天、线程 id 和父级回退 - **出站** — 向平台发送文本、媒体和投票 -- **线程** — 回复如何串入线程 +- **线程** — 回复如何在线程中组织 -核心负责共享的消息工具、提示词接线、外层会话键形状、通用的 `:thread:` 记录以及分发。 +核心负责共享消息工具、提示词接线、外层会话键形状、通用的 `:thread:` 记录，以及分发。 -如果你的平台在会话 id 中存储了额外作用域，请将该解析逻辑保留在插件中，并使用 `messaging.resolveSessionConversation(...)`。这是将 `rawId` 映射为基础会话 id、可选线程 id、显式 `baseConversationId` 以及任意 `parentConversationCandidates` 的规范钩子。 -当你返回 `parentConversationCandidates` 时，请按从最窄父级到最宽/基础会话的顺序排列。 +如果你的平台会在会话 id 中存储额外的作用域，请将该解析逻辑保留在插件中，使用 `messaging.resolveSessionConversation(...)`。这是将 `rawId` 映射到基础会话 id、可选线程 id、显式 `baseConversationId` 和任何 `parentConversationCandidates` 的规范钩子。 +当你返回 `parentConversationCandidates` 时，请保持它们按从最窄父级到最宽/基础会话的顺序排列。 -需要在渠道注册表启动前进行相同解析的内置插件，也可以暴露一个顶层 `session-key-api.ts` 文件，并导出匹配的 `resolveSessionConversation(...)`。只有在运行时插件注册表尚不可用时，核心才会使用这个对引导安全的接口。 +需要在渠道注册表启动前执行相同解析的内置插件，也可以公开一个顶层 `session-key-api.ts` 文件，并导出匹配的 `resolveSessionConversation(...)`。只有当运行时插件注册表尚不可用时，核心才会使用这个可安全引导的表面。 -当插件只需要在通用/原始 id 之上提供父级回退时，`messaging.resolveParentConversationCandidates(...)` 仍可作为旧版兼容回退使用。如果两个钩子都存在，核心会优先使用 `resolveSessionConversation(...).parentConversationCandidates`，仅当该规范钩子未提供这些值时，才回退到 `resolveParentConversationCandidates(...)`。 +当插件只需要在通用/原始 id 之上提供父级回退时，`messaging.resolveParentConversationCandidates(...)` 仍可作为旧版兼容回退使用。如果两个钩子都存在，核心会先使用 +`resolveSessionConversation(...).parentConversationCandidates`，只有当规范钩子省略它们时，才会回退到 `resolveParentConversationCandidates(...)`。 ## 批准和渠道能力 -大多数渠道插件不需要批准专用代码。 +大多数渠道插件不需要编写与批准特定相关的代码。 -- 核心负责同一聊天中的 `/approve`、共享的批准按钮负载，以及通用回退投递。 -- 当渠道需要批准专用行为时，优先在渠道插件上使用单个 `approvalCapability` 对象。 -- `ChannelPlugin.approvals` 已被移除。请将批准投递/原生/渲染/认证相关信息放到 `approvalCapability` 上。 -- `plugin.auth` 仅用于登录/登出；核心不再从该对象中读取批准认证钩子。 -- `approvalCapability.authorizeActorAction` 和 `approvalCapability.getActionAvailabilityState` 是规范的批准认证接口。 -- 对于同一聊天中的批准认证可用性，请使用 `approvalCapability.getActionAvailabilityState`。 -- 如果你的渠道暴露原生 exec 批准，当其与同一聊天批准认证不同时，请使用 `approvalCapability.getExecInitiatingSurfaceState` 来表示发起界面/原生客户端状态。核心使用这个 exec 专用钩子来区分 `enabled` 与 `disabled`、判断发起渠道是否支持原生 exec 批准，并在原生客户端回退指引中包含该渠道。`createApproverRestrictedNativeApprovalCapability(...)` 可为常见场景补齐这一点。 -- 对于渠道专用的负载生命周期行为，例如隐藏重复的本地批准提示或在投递前发送输入中指示，请使用 `outbound.shouldSuppressLocalPayloadPrompt` 或 `outbound.beforeDeliverPayload`。 +- 核心负责同聊天内的 `/approve`、共享批准按钮负载，以及通用回退投递。 +- 当渠道需要与批准相关的特定行为时，优先在渠道插件上使用一个 `approvalCapability` 对象。 +- `ChannelPlugin.approvals` 已移除。将批准投递/原生/渲染/授权相关信息放到 `approvalCapability` 上。 +- `plugin.auth` 仅用于登录/登出；核心不再从该对象读取批准授权钩子。 +- `approvalCapability.authorizeActorAction` 和 `approvalCapability.getActionAvailabilityState` 是规范的批准授权扩展点。 +- 对于同聊天批准授权可用性，使用 `approvalCapability.getActionAvailabilityState`。 +- 如果你的渠道公开原生 exec 批准，请在其与同聊天批准授权不同时，使用 `approvalCapability.getExecInitiatingSurfaceState` 表示发起表面/原生客户端状态。核心会使用这个 exec 专用钩子来区分 `enabled` 与 `disabled`，判断发起渠道是否支持原生 exec 批准，并在原生客户端回退指引中包含该渠道。`createApproverRestrictedNativeApprovalCapability(...)` 为常见场景填充了这一点。 +- 对于渠道特定的负载生命周期行为，例如隐藏重复的本地批准提示或在投递前发送输入中指示，请使用 `outbound.shouldSuppressLocalPayloadPrompt` 或 `outbound.beforeDeliverPayload`。 - 仅将 `approvalCapability.delivery` 用于原生批准路由或回退抑制。 -- 对于由渠道持有的原生批准信息，请使用 `approvalCapability.nativeRuntime`。在热门渠道入口点上，请通过 `createLazyChannelApprovalNativeRuntimeAdapter(...)` 保持其惰性加载，它可以按需导入你的运行时模块，同时仍让核心组装批准生命周期。 -- 仅当渠道确实需要自定义批准负载而不是共享渲染器时，才使用 `approvalCapability.render`。 -- 当渠道希望禁用路径回复解释启用原生 exec 批准所需的确切配置项时，请使用 `approvalCapability.describeExecApprovalSetup`。该钩子接收 `{ channel, channelLabel, accountId }`；具名账户渠道应渲染带账户作用域的路径，例如 `channels..accounts..execApprovals.*`，而不是顶层默认值。 -- 如果渠道可以从现有配置中推断出稳定的类所有者私信身份，请使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createResolvedApproverActionAuthAdapter` 来限制同一聊天中的 `/approve`，而无需添加批准专用的核心逻辑。 -- 如果渠道需要原生批准投递，请让渠道代码专注于目标规范化以及传输/呈现相关事实。请使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver` 和 `createApproverRestrictedNativeApprovalCapability`。将渠道特定事实放到 `approvalCapability.nativeRuntime` 后面，最好通过 `createChannelApprovalNativeRuntimeAdapter(...)` 或 `createLazyChannelApprovalNativeRuntimeAdapter(...)`，这样核心就可以组装处理器，并负责请求过滤、路由、去重、过期、Gateway 网关订阅以及“已在其他位置路由”的通知。`nativeRuntime` 被拆分为几个更小的接口： -- `availability` — 账户是否已配置，以及某个请求是否应被处理 -- `presentation` — 将共享的批准视图模型映射为待处理/已解决/已过期的原生负载或最终动作 -- `transport` — 准备目标，并发送/更新/删除原生批准消息 -- `interactions` — 原生按钮或反应的可选 bind/unbind/clear-action 钩子 +- 将 `approvalCapability.nativeRuntime` 用于渠道自有的原生批准信息。对于高频渠道入口点，请通过 `createLazyChannelApprovalNativeRuntimeAdapter(...)` 保持其惰性加载，这样它可以按需导入你的运行时模块，同时仍让核心组装批准生命周期。 +- 仅在渠道确实需要自定义批准负载而不是共享渲染器时，才使用 `approvalCapability.render`。 +- 当渠道希望禁用路径回复解释启用原生 exec 批准所需的确切配置项时，使用 `approvalCapability.describeExecApprovalSetup`。该钩子接收 `{ channel, channelLabel, accountId }`；命名账号渠道应渲染账号作用域路径，例如 `channels..accounts..execApprovals.*`，而不是顶层默认值。 +- 如果某个渠道可以从现有配置中推断出稳定的类似所有者的私信身份，请使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createResolvedApproverActionAuthAdapter` 来限制同聊天 `/approve`，而无需添加批准特定的核心逻辑。 +- 如果某个渠道需要原生批准投递，请让渠道代码专注于目标规范化以及传输/展示事实。使用 `openclaw/plugin-sdk/approval-runtime` 中的 `createChannelExecApprovalProfile`、`createChannelNativeOriginTargetResolver`、`createChannelApproverDmTargetResolver` 和 `createApproverRestrictedNativeApprovalCapability`。将渠道特定信息放在 `approvalCapability.nativeRuntime` 后面，理想情况下通过 `createChannelApprovalNativeRuntimeAdapter(...)` 或 `createLazyChannelApprovalNativeRuntimeAdapter(...)`，这样核心就可以组装处理器并负责请求过滤、路由、去重、过期、Gateway 网关订阅以及“已路由到其他地方”的通知。`nativeRuntime` 被拆分为几个更小的扩展点： +- `availability` — 账号是否已配置，以及请求是否应被处理 +- `presentation` — 将共享批准视图模型映射为待处理/已解决/已过期的原生负载或最终动作 +- `transport` — 准备目标并发送/更新/删除原生批准消息 +- `interactions` — 原生按钮或反应的可选绑定/解绑/清除动作钩子 - `observe` — 可选的投递诊断钩子 -- 如果渠道需要由运行时持有的对象，例如客户端、令牌、Bolt 应用或 webhook 接收器，请通过 `openclaw/plugin-sdk/channel-runtime-context` 进行注册。通用的运行时上下文注册表让核心能够从渠道启动状态引导基于能力的处理器，而无需添加批准专用的包装胶水代码。 -- 只有当基于能力的接口仍不足以表达你的需求时，才使用更底层的 `createChannelApprovalHandler` 或 `createChannelNativeApprovalRuntime`。 -- 原生批准渠道必须通过这些辅助工具同时传递 `accountId` 和 `approvalKind`。`accountId` 可使多账户批准策略限定在正确的机器人账户范围内，而 `approvalKind` 则使 exec 与插件批准行为可供渠道使用，而无需在核心中编写硬编码分支。 -- 核心现在也负责批准重路由通知。渠道插件不应再从 `createChannelNativeApprovalRuntime` 发送自己的“批准已发送到私信/另一个渠道”后续消息；相反，应通过共享的批准能力辅助工具暴露准确的来源 + 批准者私信路由，并让核心在向发起聊天回发任何通知前聚合实际投递结果。 -- 在端到端流程中保留已投递批准 id 的类型。原生客户端不应根据渠道本地状态猜测或重写 exec 与插件批准的路由。 -- 不同的批准类型可以有意暴露不同的原生界面。 - 当前内置示例： +- 如果渠道需要运行时自有对象，例如客户端、令牌、Bolt 应用或 webhook 接收器，请通过 `openclaw/plugin-sdk/channel-runtime-context` 注册它们。通用 runtime-context 注册表让核心能够从渠道启动状态引导由能力驱动的处理器，而无需添加批准特定的包装胶水代码。 +- 只有当能力驱动的扩展点仍不够表达需求时，才使用更底层的 `createChannelApprovalHandler` 或 `createChannelNativeApprovalRuntime`。 +- 原生批准渠道必须通过这些辅助工具同时传递 `accountId` 和 `approvalKind`。`accountId` 可使多账号批准策略限定在正确的机器人账号范围内，而 `approvalKind` 可让渠道在无需核心中硬编码分支的情况下区分 exec 与插件批准行为。 +- 核心现在也负责批准改道路由通知。渠道插件不应再从 `createChannelNativeApprovalRuntime` 发送它们自己的“批准已发送到私信/另一个渠道”后续消息；请改为通过共享批准能力辅助工具公开准确的源头 + approver 私信路由，让核心在向发起聊天发送任何通知前聚合实际投递结果。 +- 在端到端流程中保留已投递批准 id 的种类。原生客户端不应根据渠道本地状态去猜测或重写 exec 与插件批准路由。 +- 不同批准种类可以有意公开不同的原生表面。 + 当前的内置示例： - Slack 对 exec 和插件 id 都保留原生批准路由能力。 - - Matrix 对 exec 和插件批准保持相同的原生私信/渠道路由和反应 UX，同时仍允许批准类型之间的认证不同。 -- `createApproverRestrictedNativeApprovalAdapter` 仍作为兼容性包装器存在，但新代码应优先使用能力构建器，并在插件上暴露 `approvalCapability`。 + - Matrix 对 exec 和插件批准保留相同的原生私信/渠道路由和反应 UX，同时仍允许授权随批准种类而不同。 +- `createApproverRestrictedNativeApprovalAdapter` 仍然作为兼容性包装器存在，但新代码应优先使用能力构建器，并在插件上公开 `approvalCapability`。 -对于热门渠道入口点，当你只需要这一族中的某一部分时，优先使用更窄的运行时子路径： +对于高频渠道入口点，如果你只需要其中一个部分，请优先使用这一系列更窄的运行时子路径： - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` - `openclaw/plugin-sdk/approval-delivery-runtime` +- `openclaw/plugin-sdk/approval-gateway-runtime` +- `openclaw/plugin-sdk/approval-handler-adapter-runtime` - `openclaw/plugin-sdk/approval-handler-runtime` - `openclaw/plugin-sdk/approval-native-runtime` - `openclaw/plugin-sdk/approval-reply-runtime` - `openclaw/plugin-sdk/channel-runtime-context` -同样地，当你不需要更宽泛的总入口接口时，请优先使用 `openclaw/plugin-sdk/setup-runtime`、`openclaw/plugin-sdk/setup-adapter-runtime`、`openclaw/plugin-sdk/reply-runtime`、`openclaw/plugin-sdk/reply-dispatch-runtime`、`openclaw/plugin-sdk/reply-reference` 和 `openclaw/plugin-sdk/reply-chunking`。 +同样地，当你不需要更宽泛的总表面时，请优先使用 `openclaw/plugin-sdk/setup-runtime`、 +`openclaw/plugin-sdk/setup-adapter-runtime`、 +`openclaw/plugin-sdk/reply-runtime`、 +`openclaw/plugin-sdk/reply-dispatch-runtime`、 +`openclaw/plugin-sdk/reply-reference` 和 +`openclaw/plugin-sdk/reply-chunking`。 -对于设置，具体来说： +对于设置，具体如下： -- `openclaw/plugin-sdk/setup-runtime` 覆盖运行时安全的设置辅助工具： +- `openclaw/plugin-sdk/setup-runtime` 包含运行时安全的设置辅助工具： 可安全导入的设置补丁适配器（`createPatchedAccountSetupAdapter`、 `createEnvPatchedAccountSetupAdapter`、 `createSetupInputPresenceValidator`）、查找说明输出、 - `promptResolvedAllowFrom`、`splitSetupEntries` 和委托式 - 设置代理构建器 -- `openclaw/plugin-sdk/setup-adapter-runtime` 是面向环境变量的窄适配器接口， - 用于 `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` 覆盖可选安装设置构建器以及一些设置安全原语： + `promptResolvedAllowFrom`、`splitSetupEntries` 以及委托式 + setup-proxy 构建器 +- `openclaw/plugin-sdk/setup-adapter-runtime` 是用于 `createEnvPatchedAccountSetupAdapter` 的窄型环境感知适配器扩展点 +- `openclaw/plugin-sdk/channel-setup` 涵盖可选安装设置构建器以及少量设置安全原语： `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、 -如果你的渠道支持由环境变量驱动的设置或认证，并且通用启动/配置流程需要在运行时加载之前知道这些环境变量名，请在插件清单中通过 `channelEnvVars` 声明它们。将渠道运行时 `envVars` 或本地常量仅用于面向操作员的文案。 +如果你的渠道支持由环境变量驱动的设置或授权，并且通用启动/配置流程需要在运行时加载前知道这些环境变量名称，请在插件清单中通过 `channelEnvVars` 声明它们。将渠道运行时 `envVars` 或本地常量仅用于面向操作员的文案。 `createOptionalChannelSetupWizard`、`DEFAULT_ACCOUNT_ID`、 `createTopLevelChannelDmPolicy`、`setSetupChannelEnabled` 和 `splitSetupEntries` -- 仅当你还需要更重的共享设置/配置辅助工具时，才使用更宽泛的 `openclaw/plugin-sdk/setup` 接口，例如 +- 仅当你还需要更重的共享设置/配置辅助工具时，才使用更宽泛的 `openclaw/plugin-sdk/setup` 扩展点，例如 `moveSingleAccountChannelSectionToDefaultAccount(...)` -如果你的渠道只想在设置界面中提示“请先安装此插件”，请优先使用 `createOptionalChannelSetupSurface(...)`。生成的适配器/向导会在配置写入和最终确定时默认关闭，并在校验、finalize 和文档链接文案中复用同一条“需要安装”的消息。 +如果你的渠道只想在设置表面中提示“先安装这个插件”，请优先使用 `createOptionalChannelSetupSurface(...)`。生成的适配器/向导会在配置写入和最终化时采用默认拒绝行为，并在验证、完成和文档链接文案中复用相同的“需要安装”消息。 -对于其他热门渠道路径，请优先使用窄辅助工具，而不是更宽泛的旧版接口： +对于其他高频渠道路径，请优先使用窄型辅助工具，而不是更宽泛的旧版表面： - `openclaw/plugin-sdk/account-core`、 `openclaw/plugin-sdk/account-id`、 `openclaw/plugin-sdk/account-resolution` 和 - `openclaw/plugin-sdk/account-helpers` 用于多账户配置和 - 默认账户回退 + `openclaw/plugin-sdk/account-helpers` 用于多账号配置和默认账号回退 - `openclaw/plugin-sdk/inbound-envelope` 和 - `openclaw/plugin-sdk/inbound-reply-dispatch` 用于入站路由/信封以及 - 记录并分发的接线 + `openclaw/plugin-sdk/inbound-reply-dispatch` 用于入站路由/封装以及记录与分发接线 - `openclaw/plugin-sdk/messaging-targets` 用于目标解析/匹配 - `openclaw/plugin-sdk/outbound-media` 和 - `openclaw/plugin-sdk/outbound-runtime` 用于媒体加载以及出站 - 身份/发送委托 -- `openclaw/plugin-sdk/thread-bindings-runtime` 用于线程绑定生命周期 - 和适配器注册 -- 仅当仍需要旧版智能体/媒体负载字段布局时， - 才使用 `openclaw/plugin-sdk/agent-media-payload` -- `openclaw/plugin-sdk/telegram-command-config` 用于 Telegram 自定义命令 - 规范化、重复/冲突校验，以及稳定回退的命令 - 配置契约 + `openclaw/plugin-sdk/outbound-runtime` 用于媒体加载以及出站身份/发送委托 +- `openclaw/plugin-sdk/thread-bindings-runtime` 用于线程绑定生命周期和适配器注册 +- 仅当仍需要旧版智能体/媒体负载字段布局时，才使用 `openclaw/plugin-sdk/agent-media-payload` +- `openclaw/plugin-sdk/telegram-command-config` 用于 Telegram 自定义命令规范化、重复/冲突校验，以及一个可稳定回退的命令配置契约 -仅认证渠道通常可以止步于默认路径：核心处理批准，而插件只暴露出站/认证能力。像 Matrix、Slack、Telegram 和自定义聊天传输这类原生批准渠道，应使用共享的原生辅助工具，而不是自行实现批准生命周期。 +仅授权渠道通常只需走默认路径：核心处理批准，插件只暴露出站/授权能力。像 Matrix、Slack、Telegram 和自定义聊天传输这类原生批准渠道，应使用共享的原生辅助工具，而不是自行实现批准生命周期。 ## 入站提及策略 请将入站提及处理拆分为两层： -- 插件负责的证据收集 -- 共享的策略评估 +- 插件自有的证据收集 +- 共享策略评估 共享层请使用 `openclaw/plugin-sdk/channel-inbound`。 -适合插件本地逻辑的内容： +适合放在插件本地逻辑中的内容： - 回复机器人检测 - 引用机器人检测 - 线程参与检查 - 服务/系统消息排除 -- 用于证明机器人参与的平台原生缓存 +- 证明机器人参与所需的平台原生缓存 -适合共享辅助工具的内容： +适合放在共享辅助工具中的内容： - `requireMention` - 显式提及结果 @@ -205,7 +205,7 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions` 为已经依赖运行时注入的内置渠道插件暴露了相同的共享提及辅助工具： +对于已依赖运行时注入的内置渠道插件，`api.runtime.channel.mentions` 公开了相同的共享提及辅助工具： - `buildMentionRegexes` - `matchesMentionPatterns` @@ -214,16 +214,16 @@ if (decision.shouldSkip) return; - `resolveInboundMentionDecision` 较旧的 `resolveMentionGating*` 辅助工具仍保留在 -`openclaw/plugin-sdk/channel-inbound` 中，但仅作为兼容性导出。新代码 -应使用 `resolveInboundMentionDecision({ facts, policy })`。 +`openclaw/plugin-sdk/channel-inbound` 中，但仅作为兼容性导出。新代码应使用 +`resolveInboundMentionDecision({ facts, policy })`。 ## 演练 - + 创建标准插件文件。`package.json` 中的 `channel` 字段 - 用于将其标记为渠道插件。有关完整的软件包元数据接口， + 使其成为一个渠道插件。有关完整的包元数据表面， 请参见 [插件设置和配置](/zh-CN/plugins/sdk-setup#openclawchannel)： @@ -274,8 +274,7 @@ if (decision.shouldSkip) return; - `ChannelPlugin` 接口有许多可选适配器接口。先从最小集合开始 - —— `id` 和 `setup` —— 然后按需添加适配器。 + `ChannelPlugin` 接口有许多可选适配器表面。先从最小集合开始——`id` 和 `setup`——然后按需添加适配器。 创建 `src/channel.ts`： @@ -370,18 +369,17 @@ if (decision.shouldSkip) return; }); ``` - - 你无需手动实现底层适配器接口，只需传入声明式选项， - 构建器就会将它们组合起来： + + 你无需手动实现底层适配器接口，而是传入声明式选项，由构建器负责组合： - | 选项 | 它接线的内容 | + | 选项 | 接线内容 | | --- | --- | - | `security.dm` | 从配置字段解析带作用域的私信安全策略 | - | `pairing.text` | 通过验证码交换实现基于文本的私信配对流程 | - | `threading` | reply-to 模式解析器（固定、账户作用域或自定义） | - | `outbound.attachedResults` | 返回结果元数据（消息 ID）的发送函数 | + | `security.dm` | 基于配置字段的作用域私信安全解析器 | + | `pairing.text` | 基于文本和验证码交换的私信配对流程 | + | `threading` | 回复模式解析器（固定、账号作用域或自定义） | + | `outbound.attachedResults` | 返回结果元数据（消息 id）的发送函数 | - 如果你需要完全控制，也可以直接传入原始适配器对象，而不是声明式选项。 + 如果你需要完全控制，也可以传入原始适配器对象，而不是这些声明式选项。 @@ -422,21 +420,16 @@ if (decision.shouldSkip) return; }); ``` - 将渠道自有的 CLI 描述符放在 `registerCliMetadata(...)` 中，这样 OpenClaw - 就能在不激活完整渠道运行时的情况下，在根帮助中显示它们； - 同时，正常的完整加载也会拾取这些相同的描述符，用于真正的命令注册。 - 将 `registerFull(...)` 保留给仅运行时的工作。 - 如果 `registerFull(...)` 注册 Gateway 网关 RPC 方法，请使用 - 插件专属前缀。核心管理命名空间（`config.*`、 - `exec.approvals.*`、`wizard.*`、`update.*`）仍为保留项，并始终 - 解析到 `operator.admin`。 - `defineChannelPluginEntry` 会自动处理注册模式拆分。有关全部 - 选项，请参见 [入口点](/zh-CN/plugins/sdk-entrypoints#definechannelpluginentry)。 + 将渠道自有的 CLI 描述符放在 `registerCliMetadata(...)` 中，这样 OpenClaw 就能在不激活完整渠道运行时的情况下，在根帮助中显示它们；而普通完整加载仍会拾取相同的描述符以进行真实命令注册。将 `registerFull(...)` 保留给仅运行时工作。 + 如果 `registerFull(...)` 注册 Gateway 网关 RPC 方法，请使用插件特定前缀。核心管理命名空间（`config.*`、 + `exec.approvals.*`、`wizard.*`、`update.*`）保持保留，并始终解析到 `operator.admin`。 + `defineChannelPluginEntry` 会自动处理注册模式拆分。有关全部选项，请参见 + [入口点](/zh-CN/plugins/sdk-entrypoints#definechannelpluginentry)。 - 创建 `setup-entry.ts`，以便在新手引导期间进行轻量加载： + 创建 `setup-entry.ts`，用于在新手引导期间轻量加载： ```typescript setup-entry.ts import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -445,15 +438,14 @@ if (decision.shouldSkip) return; export default defineSetupPluginEntry(acmeChatPlugin); ``` - 当渠道被禁用或未配置时，OpenClaw 会加载这个入口，而不是完整入口。 + 当渠道被禁用或尚未配置时，OpenClaw 会加载它，而不是完整入口。 这样可以避免在设置流程中拉入沉重的运行时代码。 详情请参见 [设置和配置](/zh-CN/plugins/sdk-setup#setup-entry)。 - 你的插件需要从平台接收消息并将其转发给 OpenClaw。典型模式是 - 一个 webhook：验证请求，然后通过你渠道的入站处理器进行分发： + 你的插件需要从平台接收消息并将其转发给 OpenClaw。典型模式是一个 webhook：验证请求后，通过你渠道的入站处理器进行分发。 ```typescript registerFull(api) { @@ -477,8 +469,7 @@ if (decision.shouldSkip) return; ``` - 入站消息处理是渠道特定的。每个渠道插件都拥有 - 自己的入站处理流水线。请查看内置渠道插件 + 入站消息处理是渠道特定的。每个渠道插件都拥有自己的入站处理管线。请查看内置渠道插件 （例如 Microsoft Teams 或 Google Chat 插件包）以了解真实模式。 @@ -524,7 +515,7 @@ if (decision.shouldSkip) return; pnpm test -- /acme-chat/ ``` - 有关共享测试辅助工具，请参见 [测试](/zh-CN/plugins/sdk-testing)。 + 关于共享测试辅助工具，请参见 [测试](/zh-CN/plugins/sdk-testing)。 @@ -533,41 +524,39 @@ if (decision.shouldSkip) return; ``` /acme-chat/ -├── package.json # openclaw.channel metadata -├── openclaw.plugin.json # Manifest with config schema +├── package.json # openclaw.channel 元数据 +├── openclaw.plugin.json # 带有配置 schema 的清单 ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry -├── api.ts # Public exports (optional) -├── runtime-api.ts # Internal runtime exports (optional) +├── api.ts # 公共导出（可选） +├── runtime-api.ts # 内部运行时导出（可选） └── src/ - ├── channel.ts # ChannelPlugin via createChatChannelPlugin - ├── channel.test.ts # Tests - ├── client.ts # Platform API client - └── runtime.ts # Runtime store (if needed) + ├── channel.ts # 通过 createChatChannelPlugin 创建的 ChannelPlugin + ├── channel.test.ts # 测试 + ├── client.ts # 平台 API 客户端 + └── runtime.ts # 运行时存储（如需要） ``` ## 高级主题 - 固定、账户作用域或自定义回复模式 + 固定、账号作用域或自定义回复模式 - + describeMessageTool 和动作发现 inferTargetChatType、looksLikeId、resolveTarget - TTS、STT、媒体、通过 api.runtime 使用的子智能体 + 通过 api.runtime 使用 TTS、STT、媒体、子智能体 -一些内置辅助工具接口仍然存在，用于内置插件维护和 -兼容性。对于新的渠道插件，它们不是推荐模式； -除非你正在直接维护该内置插件家族，否则请优先使用通用 SDK -接口中的 channel/setup/reply/runtime 子路径。 +某些内置辅助扩展点仍保留，用于内置插件维护和兼容性。它们并不是新渠道插件的推荐模式； +除非你正在直接维护该内置插件家族，否则应优先使用公共 SDK 表面中的通用渠道/设置/回复/运行时子路径。 ## 后续步骤 diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index a16ebcbf9..4fd9ad728 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -1,56 +1,56 @@ --- read_when: - - 你看到 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告 - - 你看到 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告 + - 你看到了 OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED 警告 + - 你看到了 OPENCLAW_EXTENSION_API_DEPRECATED 警告 - 你正在将一个插件更新到现代插件架构 - - 你在维护一个外部 OpenClaw 插件 + - 你维护一个外部 OpenClaw 插件 sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-07T18:43:21Z" + generated_at: "2026-04-07T20:09:26Z" model: gpt-5.4 provider: openai - source_hash: 509699c3432191a1b2e4214c66d6d620e8d13a064cb2e7b9b38460c7ea45a20d + source_hash: 155a8b14bc345319c8516ebdb8a0ccdea2c5f7fa07dad343442996daee21ecad source_path: plugins/sdk-migration.md workflow: 15 --- # 插件 SDK 迁移 -OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚焦且有文档说明的导入方式。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 +OpenClaw 已从一个宽泛的向后兼容层迁移到一个现代插件架构，采用聚焦且文档完善的导入路径。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 ## 正在发生什么变化 -旧插件系统提供了两个完全开放的接口，让插件可以从单一入口点导入所需的任何内容： +旧插件系统提供了两个高度开放的接口，让插件可以从单一入口点导入它们所需的任何内容： -- **`openclaw/plugin-sdk/compat`** — 一个会重新导出数十个辅助工具的单一导入入口。它的引入是为了在构建新插件架构期间，让较旧的基于 hook 的插件继续工作。 -- **`openclaw/extension-api`** — 一个桥接层，让插件可以直接访问宿主端辅助工具，例如内嵌智能体运行器。 +- **`openclaw/plugin-sdk/compat`** — 一个单一导入路径，重新导出了数十个辅助工具。它的引入是为了在新插件架构构建期间，让较旧的基于 hook 的插件继续工作。 +- **`openclaw/extension-api`** — 一个桥接层，使插件能够直接访问主机侧辅助工具，例如嵌入式智能体运行器。 -这两个接口现在都已**弃用**。它们在运行时仍然可用，但新插件不得使用它们，现有插件也应在下一个主要版本移除它们之前完成迁移。 +这两个接口现在都已被**弃用**。它们在运行时仍然可用，但新插件不得使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。 - 向后兼容层将在未来的一个主要版本中移除。 - 到那时，仍然从这些接口导入内容的插件将会失效。 + 向后兼容层将在未来的一个主版本中被移除。 + 仍然从这些接口导入的插件届时将会中断。 -## 为什么会有这个变化 +## 为什么会发生这个变化 -旧方案带来了这些问题： +旧方法带来了这些问题： -- **启动缓慢** — 导入一个辅助工具会加载数十个无关模块 -- **循环依赖** — 宽泛的重新导出很容易产生导入循环 +- **启动缓慢** — 导入一个辅助工具会加载几十个无关模块 +- **循环依赖** — 宽泛的重新导出使得导入循环很容易产生 - **API 接口不清晰** — 无法判断哪些导出是稳定的，哪些是内部实现 -现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有清晰的用途和有文档说明的契约。 +现代插件 SDK 修复了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有明确用途和文档化契约。 -面向内置渠道的旧版 provider 便捷接口也已移除。类似 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助接口，以及 `openclaw/plugin-sdk/telegram-core` 这样的导入，都是私有 mono-repo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内部，应将 provider 自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 +面向内置渠道的旧版提供商便捷接口也已移除。诸如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`、带渠道品牌的辅助接口，以及 `openclaw/plugin-sdk/telegram-core` 这类导入路径，都是私有 mono-repo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内，请将提供商自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 -当前内置 provider 示例： +当前内置提供商示例： -- Anthropic 将 Claude 专用的流式辅助工具保留在它自己的 `api.ts` / `contract-api.ts` 接口中 -- OpenAI 将 provider builder、默认模型辅助工具以及实时 provider builder 保留在它自己的 `api.ts` 中 -- OpenRouter 将 provider builder 以及新手引导 / 配置辅助工具保留在它自己的 `api.ts` 中 +- Anthropic 将 Claude 专用的流式传输辅助工具保留在其自己的 `api.ts` / `contract-api.ts` 接口中 +- OpenAI 将提供商构建器、默认模型辅助工具以及实时提供商构建器保留在其自己的 `api.ts` 中 +- OpenRouter 将提供商构建器以及新手引导/配置辅助工具保留在其自己的 `api.ts` 中 ## 如何迁移 @@ -61,20 +61,20 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 关键变化： - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 `approvalCapability.nativeRuntime` - - 将审批专用的认证 / 投递从旧版 `plugin.auth` / + - 将审批专用的认证/投递从旧版 `plugin.auth` / `plugin.approvals` 线路迁移到 `approvalCapability` - - `ChannelPlugin.approvals` 已从公开的渠道插件契约中移除；请将 delivery / native / render 字段迁移到 `approvalCapability` - - `plugin.auth` 仅保留给渠道登录 / 登出流程使用；其中的审批认证 hook 不再被 core 读取 - - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道自有的运行时对象，例如客户端、令牌或 Bolt 应用 - - 不要从原生审批处理器发送插件自有的改道通知；core 现在会根据实际投递结果来处理“已路由到其他地方”的通知 - - 将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 接口。部分 stub 将被拒绝。 + - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；请将 delivery/native/render 字段迁移到 `approvalCapability` + - `plugin.auth` 仅保留用于渠道登录/登出流程；其中的审批认证 hook 不再被核心读取 + - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道自有运行时对象，例如客户端、令牌或 Bolt 应用 + - 不要从原生审批处理器发送插件自有的“已重定向到其他地方”通知；核心现在会根据实际投递结果统一处理这类通知 + - 当你将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供一个真实的 `createPluginRuntime().channel` 接口。部分 stub 将被拒绝。 当前审批能力布局请参见 `/plugins/sdk-channel-plugins`。 - 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，现在当 Windows 的 `.cmd` / `.bat` 包装器无法解析时，默认会以关闭方式失败，除非你显式传入 `allowShellFallback: true`。 + 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，现在无法解析的 Windows `.cmd`/`.bat` 包装器会默认失败关闭，除非你显式传入 `allowShellFallback: true`。 ```typescript // Before @@ -83,17 +83,18 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 // After const program = applyWindowsSpawnProgramPolicy({ candidate, - // 仅对受信任且明确接受 shell 中介回退的兼容性调用方设置此项。 + // 仅为受信任的兼容性调用方设置此项，这些调用方有意接受 + // 经过 shell 中介的回退行为。 allowShellFallback: true, }); ``` - 如果你的调用方并不有意依赖 shell 回退，就不要设置 `allowShellFallback`，而应改为处理抛出的错误。 + 如果你的调用方并非有意依赖 shell 回退，请不要设置 `allowShellFallback`，而应改为处理抛出的错误。 - 在你的插件中搜索来自任一已弃用接口的导入： + 在你的插件中搜索来自这两个已弃用接口的导入： ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -103,7 +104,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 - 旧接口中的每个导出都映射到一个明确的现代导入路径： + 旧接口中的每个导出都映射到一个特定的现代导入路径： ```typescript // Before (deprecated backwards-compatibility layer) @@ -119,7 +120,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - 对于宿主端辅助工具，请改用注入的插件运行时，而不是直接导入： + 对于主机侧辅助工具，请使用注入的插件运行时，而不是直接导入： ```typescript // Before (deprecated extension-api bridge) @@ -132,7 +133,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 同样的模式也适用于其他旧版桥接辅助工具： - | 旧导入 | 现代等价项 | + | 旧导入 | 现代等效项 | | --- | --- | | `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` | | `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` | @@ -158,172 +159,170 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 | 导入路径 | 用途 | 关键导出 | | --- | --- | --- | | `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` | - | `plugin-sdk/core` | 用于渠道入口定义 / builder 的旧版总括重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/core` | 用于渠道入口定义/构建器的旧版总括重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | 单 provider 入口辅助工具 | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和 builder | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享设置向导辅助工具 | Allowlist 提示、设置状态 builder | - | `plugin-sdk/setup-runtime` | 设置时运行时辅助工具 | 可安全导入的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 | + | `plugin-sdk/provider-entry` | 单一提供商入口辅助工具 | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | 共享设置向导辅助工具 | Allowlist 提示、设置状态构建器 | + | `plugin-sdk/setup-runtime` | 设置时运行时辅助工具 | 对导入安全的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 | | `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表 / 配置 / 操作 gate 辅助工具 | - | `plugin-sdk/account-id` | 账户 ID 辅助工具 | `DEFAULT_ACCOUNT_ID`、账户 ID 规范化 | + | `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表/配置/操作门控辅助工具 | + | `plugin-sdk/account-id` | account-id 辅助工具 | `DEFAULT_ACCOUNT_ID`、account-id 规范化 | | `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表 / 账户操作辅助工具 | + | `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表/账户操作辅助工具 | | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` | | `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入线路 | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | 配置 schema builder | 渠道配置 schema 类型 | - | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复 / 冲突校验 | - | `plugin-sdk/channel-policy` | 群组 / 私信策略解析 | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 渠道配置 schema 类型 | + | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复/冲突校验 | + | `plugin-sdk/channel-policy` | 群组/私信策略解析 | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | 账户状态跟踪 | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope builder 辅助工具 | + | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope 构建辅助工具 | | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录与分发辅助工具 | - | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析 / 匹配辅助工具 | + | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助工具 | | `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 | - | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站身份 / 发送委托辅助工具 | + | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站身份/发送委托辅助工具 | | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 | - | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 用于旧字段布局的智能体媒体负载 builder | - | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅旧版渠道运行时工具 | + | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 面向旧字段布局的智能体媒体负载构建器 | + | `plugin-sdk/channel-runtime` | 已弃用的兼容性垫片 | 仅旧版渠道运行时工具 | | `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 | | `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | 宽范围运行时辅助工具 | 运行时 / 日志 / 备份 / 插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | logger / 运行时环境、超时、重试和 backoff 辅助工具 | - | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令 / hooks / HTTP / 交互式辅助工具 | - | `plugin-sdk/hook-runtime` | hook 流水线辅助工具 | 共享 webhook / 内部 hook 流水线辅助工具 | - | `plugin-sdk/lazy-runtime` | 惰性运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/runtime` | 宽范围运行时辅助工具 | 运行时/日志/备份/插件安装辅助工具 | + | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | Logger/运行时环境、超时、重试和退避辅助工具 | + | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/hooks/http/交互辅助工具 | + | `plugin-sdk/hook-runtime` | Hook 管道辅助工具 | 共享 webhook/内部 hook 管道辅助工具 | + | `plugin-sdk/lazy-runtime` | 延迟运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 | | `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 | | `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道状态补丁辅助工具 | - | `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载 / 写入辅助工具 | - | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供回退稳定的 Telegram 命令校验辅助工具 | - | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec / 插件审批负载、审批能力 / 配置文件辅助工具、原生审批路由 / 运行时辅助工具 | + | `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载/写入辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供稳定回退的 Telegram 命令校验辅助工具 | + | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec/插件审批负载、审批能力/配置文件辅助工具、原生审批路由/运行时辅助工具 | | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | 审批人解析、同聊天操作认证 | - | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置文件 / 过滤辅助工具 | - | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力 / 投递适配器 | - | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 共享审批处理器运行时辅助工具，包括基于能力驱动的原生审批加载 | - | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标 / 账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec / 插件审批回复负载辅助工具 | - | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register / get / watch 辅助工具 | - | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信 gate、外部内容和密钥收集辅助工具 | + | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置文件/过滤辅助工具 | + | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力/投递适配器 | + | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 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/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register/get/watch 辅助工具 | + | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和 secret 收集辅助工具 | | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 allowlist 和私有网络策略辅助工具 | | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | 固定 dispatcher、受保护 fetch、SSRF 策略辅助工具 | | `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | 诊断 gate 辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/diagnostic-runtime` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | | `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 | - | `plugin-sdk/fetch-runtime` | 封装的 fetch / 代理辅助工具 | `resolveFetch`、代理辅助工具 | - | `plugin-sdk/host-runtime` | 宿主规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/fetch-runtime` | 封装的 fetch/代理辅助工具 | `resolveFetch`、代理辅助工具 | + | `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | | `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 | - | `plugin-sdk/allow-from` | allowlist 格式化 | `formatAllowFromLowercase` | + | `plugin-sdk/allow-from` | Allowlist 格式化 | `formatAllowFromLowercase` | | `plugin-sdk/allowlist-resolution` | Allowlist 输入映射 | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | 命令 gate 和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 | - | `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助工具 | - | `plugin-sdk/webhook-ingress` | webhook 请求辅助工具 | webhook 目标工具 | - | `plugin-sdk/webhook-request-guards` | webhook 请求体保护辅助工具 | 请求体读取 / 限制辅助工具 | - | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | finalize + provider 分发辅助工具 | + | `plugin-sdk/command-auth` | 命令门控和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 | + | `plugin-sdk/secret-input` | Secret 输入解析 | Secret 输入辅助工具 | + | `plugin-sdk/webhook-ingress` | Webhook 请求辅助工具 | Webhook 目标工具 | + | `plugin-sdk/webhook-request-guards` | Webhook 请求体防护辅助工具 | 请求体读取/限制辅助工具 | + | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划、分块 | + | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | Finalize + 提供商分发辅助工具 | | `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `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` | 状态路径辅助工具 | 状态和 OAuth 目录辅助工具 | - | `plugin-sdk/routing` | 路由 / 会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 | - | `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道 / 账户状态摘要 builder、运行时状态默认值、问题元数据辅助工具 | + | `plugin-sdk/routing` | 路由/会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 | + | `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道/账户状态摘要构建器、运行时状态默认值、问题元数据辅助工具 | | `plugin-sdk/target-resolver-runtime` | 目标解析器辅助工具 | 共享目标解析器辅助工具 | - | `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug / 字符串规范化辅助工具 | + | `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug/字符串规范化辅助工具 | | `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类请求输入中提取字符串 URL | - | `plugin-sdk/run-command` | 定时命令辅助工具 | 带规范化 stdout / stderr 的定时命令运行器 | - | `plugin-sdk/param-readers` | 参数读取器 | 通用工具 / CLI 参数读取器 | + | `plugin-sdk/run-command` | 定时命令辅助工具 | 带标准化 stdout/stderr 的定时命令运行器 | + | `plugin-sdk/param-readers` | 参数读取器 | 通用工具/CLI 参数读取器 | | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 | | `plugin-sdk/temp-path` | 临时路径辅助工具 | 共享临时下载路径辅助工具 | | `plugin-sdk/logging-core` | 日志辅助工具 | 子系统 logger 和脱敏辅助工具 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助工具 | Markdown 表格模式辅助工具 | | `plugin-sdk/reply-payload` | 消息回复类型 | 回复负载类型 | - | `plugin-sdk/provider-setup` | 经过整理的本地 / 自托管 provider 设置辅助工具 | 自托管 provider 发现 / 配置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管 provider 设置辅助工具 | 同样的自托管 provider 发现 / 配置辅助工具 | - | `plugin-sdk/provider-auth-runtime` | provider 运行时认证辅助工具 | 运行时 API 密钥解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | provider API 密钥设置辅助工具 | API 密钥新手引导 / 配置文件写入辅助工具 | - | `plugin-sdk/provider-auth-result` | provider auth-result 辅助工具 | 标准 OAuth auth-result builder | - | `plugin-sdk/provider-auth-login` | provider 交互式登录辅助工具 | 共享交互式登录辅助工具 | - | `plugin-sdk/provider-env-vars` | provider 环境变量辅助工具 | provider 认证环境变量查找辅助工具 | - | `plugin-sdk/provider-model-shared` | 共享 provider 模型 / 重放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略 builder、provider 端点辅助工具以及 model-id 规范化辅助工具 | - | `plugin-sdk/provider-catalog-shared` | 共享 provider catalog 辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | provider 新手引导补丁 | 新手引导配置辅助工具 | - | `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP / 端点能力辅助工具 | - | `plugin-sdk/provider-web-fetch` | provider web-fetch 辅助工具 | web-fetch provider 注册 / 缓存辅助工具 | - | `plugin-sdk/provider-web-search-contract` | provider web 搜索契约辅助工具 | 窄范围 web 搜索配置 / 凭证契约辅助工具，例如 `enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域化凭证 setter / getter | - | `plugin-sdk/provider-web-search` | provider web 搜索辅助工具 | web 搜索 provider 注册 / 缓存 / 运行时辅助工具 | - | `plugin-sdk/provider-tools` | provider 工具 / schema 兼容辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | provider 用量辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 以及其他 provider 用量辅助工具 | - | `plugin-sdk/provider-stream` | provider 流包装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装辅助工具 | + | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 | 自托管提供商发现/配置辅助工具 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管提供商设置辅助工具 | 相同的自托管提供商发现/配置辅助工具 | + | `plugin-sdk/provider-auth-runtime` | 提供商运行时认证辅助工具 | 运行时 API key 解析辅助工具 | + | `plugin-sdk/provider-auth-api-key` | 提供商 API key 设置辅助工具 | API key 新手引导/配置文件写入辅助工具 | + | `plugin-sdk/provider-auth-result` | 提供商 auth-result 辅助工具 | 标准 OAuth auth-result 构建器 | + | `plugin-sdk/provider-auth-login` | 提供商交互式登录辅助工具 | 共享交互式登录辅助工具 | + | `plugin-sdk/provider-env-vars` | 提供商环境变量辅助工具 | 提供商认证环境变量查找辅助工具 | + | `plugin-sdk/provider-model-shared` | 共享提供商模型/重放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、提供商 endpoint 辅助工具以及 model-id 规范化辅助工具 | + | `plugin-sdk/provider-catalog-shared` | 共享提供商目录辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | 提供商 onboarding 补丁 | onboarding 配置辅助工具 | + | `plugin-sdk/provider-http` | 提供商 HTTP 辅助工具 | 通用提供商 HTTP/endpoint 能力辅助工具 | + | `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 辅助工具 | Web-fetch 提供商注册/缓存辅助工具 | + | `plugin-sdk/provider-web-search-contract` | 提供商 web-search 契约辅助工具 | 窄范围 web-search 配置/凭证契约辅助工具，例如 `enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域凭证 setter/getter | + | `plugin-sdk/provider-web-search` | 提供商 web-search 辅助工具 | Web-search 提供商注册/缓存/运行时辅助工具 | + | `plugin-sdk/provider-tools` | 提供商工具/schema 兼容辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | 提供商用量辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 以及其他提供商用量辅助工具 | + | `plugin-sdk/provider-stream` | 提供商流包装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装类型，以及共享 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装辅助工具 | | `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体 fetch / transform / store 辅助工具以及媒体负载 builder | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 图像 / 视频 / 音乐生成的共享故障切换辅助工具、候选项选择和缺失模型消息 | - | `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解 provider 类型以及面向 provider 的图像 / 音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 去除助手可见文本、markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具以及相关文本 / 日志辅助工具 | + | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取/转换/存储辅助工具以及媒体负载构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 图像/视频/音乐生成的共享故障切换辅助工具、候选项选择和缺失模型提示 | + | `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解提供商类型以及面向提供商的图像/音频辅助工具导出 | + | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本剥离、markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具，以及相关文本/日志辅助工具 | | `plugin-sdk/text-chunking` | 文本分块辅助工具 | 出站文本分块辅助工具 | - | `plugin-sdk/speech` | 语音辅助工具 | 语音 provider 类型以及面向 provider 的 directive、注册表和校验辅助工具 | - | `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、指令、规范化 | - | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型和注册表辅助工具 | - | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型和注册表辅助工具 | + | `plugin-sdk/speech` | 语音辅助工具 | 语音提供商类型以及面向提供商的 directive、注册表和校验辅助工具 | + | `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、指令、规范化 | + | `plugin-sdk/realtime-transcription` | 实时转写辅助工具 | 提供商类型和注册表辅助工具 | + | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | 提供商类型和注册表辅助工具 | | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障切换、认证和注册表辅助工具 | - | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider / 请求 / 结果类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障切换辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider / 请求 / 结果类型 | - | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障切换辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载规范化 / 归约 | - | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄范围渠道配置 schema 原语 | + | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成提供商/请求/结果类型 | + | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 | + | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成提供商/请求/结果类型 | + | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 | + | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载规范化/归约 | + | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄范围渠道 config-schema 原语 | | `plugin-sdk/channel-config-writes` | 渠道配置写入辅助工具 | 渠道配置写入授权辅助工具 | - | `plugin-sdk/channel-plugin-common` | 共享渠道前导模块 | 共享渠道插件前导导出 | - | `plugin-sdk/channel-status` | 渠道状态辅助工具 | 共享渠道状态快照 / 摘要辅助工具 | - | `plugin-sdk/allowlist-config-edit` | Allowlist 配置辅助工具 | Allowlist 配置编辑 / 读取辅助工具 | + | `plugin-sdk/channel-plugin-common` | 共享渠道前导层 | 共享渠道插件前导导出 | + | `plugin-sdk/channel-status` | 渠道状态辅助工具 | 共享渠道状态快照/摘要辅助工具 | + | `plugin-sdk/allowlist-config-edit` | Allowlist 配置辅助工具 | Allowlist 配置编辑/读取辅助工具 | | `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证 / 保护辅助工具 | - | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道 / 状态和环境代理辅助原语 | - | `plugin-sdk/webhook-targets` | webhook 目标辅助工具 | webhook 目标注册表和路由安装辅助工具 | - | `plugin-sdk/webhook-path` | webhook 路径辅助工具 | webhook 路径规范化辅助工具 | - | `plugin-sdk/web-media` | 共享 Web 媒体辅助工具 | 远程 / 本地媒体加载辅助工具 | - | `plugin-sdk/zod` | Zod 重新导出 | 面向插件 SDK 使用者重新导出的 `zod` | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | memory 管理器 / 配置 / 文件 / CLI 辅助接口 | - | `plugin-sdk/memory-core-engine-runtime` | memory 引擎运行时门面 | memory 索引 / 搜索运行时门面 | - | `plugin-sdk/memory-core-host-engine-foundation` | memory 宿主基础引擎 | memory 宿主基础引擎导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | memory 宿主嵌入引擎 | memory 宿主嵌入引擎导出 | - | `plugin-sdk/memory-core-host-engine-qmd` | memory 宿主 QMD 引擎 | memory 宿主 QMD 引擎导出 | - | `plugin-sdk/memory-core-host-engine-storage` | memory 宿主存储引擎 | memory 宿主存储引擎导出 | - | `plugin-sdk/memory-core-host-multimodal` | memory 宿主多模态辅助工具 | memory 宿主多模态辅助工具 | - | `plugin-sdk/memory-core-host-query` | memory 宿主查询辅助工具 | memory 宿主查询辅助工具 | - | `plugin-sdk/memory-core-host-secret` | memory 宿主密钥辅助工具 | memory 宿主密钥辅助工具 | - | `plugin-sdk/memory-core-host-events` | memory 宿主事件日志辅助工具 | memory 宿主事件日志辅助工具 | - | `plugin-sdk/memory-core-host-status` | memory 宿主状态辅助工具 | memory 宿主状态辅助工具 | - | `plugin-sdk/memory-core-host-runtime-cli` | memory 宿主 CLI 运行时 | memory 宿主 CLI 运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-core` | memory 宿主核心运行时 | memory 宿主核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | memory 宿主文件 / 运行时辅助工具 | memory 宿主文件 / 运行时辅助工具 | - | `plugin-sdk/memory-host-core` | memory 宿主核心运行时别名 | 面向 vendor-neutral 的 memory 宿主核心运行时辅助工具别名 | - | `plugin-sdk/memory-host-events` | memory 宿主事件日志别名 | 面向 vendor-neutral 的 memory 宿主事件日志辅助工具别名 | - | `plugin-sdk/memory-host-files` | memory 宿主文件 / 运行时别名 | 面向 vendor-neutral 的 memory 宿主文件 / 运行时辅助工具别名 | - | `plugin-sdk/memory-host-markdown` | 受管 markdown 辅助工具 | 面向 memory 邻接插件的共享受管 markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 活跃 memory 搜索门面 | 惰性 active-memory search-manager 运行时门面 | - | `plugin-sdk/memory-host-status` | memory 宿主状态别名 | 面向 vendor-neutral 的 memory 宿主状态辅助工具别名 | + | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证/防护辅助工具 | + | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/状态和环境代理辅助原语 | + | `plugin-sdk/webhook-targets` | Webhook 目标辅助工具 | Webhook 目标注册表和路由安装辅助工具 | + | `plugin-sdk/webhook-path` | Webhook 路径辅助工具 | Webhook 路径规范化辅助工具 | + | `plugin-sdk/web-media` | 共享 Web 媒体辅助工具 | 远程/本地媒体加载辅助工具 | + | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用者重新导出的 `zod` | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | 内存管理器/配置/文件/CLI 辅助接口 | + | `plugin-sdk/memory-core-engine-runtime` | 内存引擎运行时外观层 | 内存索引/搜索运行时外观层 | + | `plugin-sdk/memory-core-host-engine-foundation` | 内存主机基础引擎 | 内存主机基础引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | 内存主机嵌入引擎 | 内存主机嵌入引擎导出 | + | `plugin-sdk/memory-core-host-engine-qmd` | 内存主机 QMD 引擎 | 内存主机 QMD 引擎导出 | + | `plugin-sdk/memory-core-host-engine-storage` | 内存主机存储引擎 | 内存主机存储引擎导出 | + | `plugin-sdk/memory-core-host-multimodal` | 内存主机多模态辅助工具 | 内存主机多模态辅助工具 | + | `plugin-sdk/memory-core-host-query` | 内存主机查询辅助工具 | 内存主机查询辅助工具 | + | `plugin-sdk/memory-core-host-secret` | 内存主机 secret 辅助工具 | 内存主机 secret 辅助工具 | + | `plugin-sdk/memory-core-host-events` | 内存主机事件日志辅助工具 | 内存主机事件日志辅助工具 | + | `plugin-sdk/memory-core-host-status` | 内存主机状态辅助工具 | 内存主机状态辅助工具 | + | `plugin-sdk/memory-core-host-runtime-cli` | 内存主机 CLI 运行时 | 内存主机 CLI 运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-core` | 内存主机核心运行时 | 内存主机核心运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-files` | 内存主机文件/运行时辅助工具 | 内存主机文件/运行时辅助工具 | + | `plugin-sdk/memory-host-core` | 内存主机核心运行时别名 | 面向厂商中立的内存主机核心运行时辅助工具别名 | + | `plugin-sdk/memory-host-events` | 内存主机事件日志别名 | 面向厂商中立的内存主机事件日志辅助工具别名 | + | `plugin-sdk/memory-host-files` | 内存主机文件/运行时别名 | 面向厂商中立的内存主机文件/运行时辅助工具别名 | + | `plugin-sdk/memory-host-markdown` | 托管 markdown 辅助工具 | 面向内存相关插件的共享托管 markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 活跃内存搜索外观层 | 延迟活跃内存 search-manager 运行时外观层 | + | `plugin-sdk/memory-host-status` | 内存主机状态别名 | 面向厂商中立的内存主机状态辅助工具别名 | | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | memory-lancedb 辅助接口 | | `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mock | -此表刻意只包含常见迁移子集，而不是完整的 SDK 接口。完整的 200+ 入口点列表位于 -`scripts/lib/plugin-sdk-entrypoints.json`。 +此表有意只包含常见迁移子集，而不是完整的 SDK 接口。完整的 200 多个入口点列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 -该列表仍然包含一些内置插件辅助接口，例如 -`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*`。这些接口仍然会为了内置插件维护和兼容性而导出，但它们被有意省略出常见迁移表，也不是新插件代码的推荐目标。 -同样的规则也适用于其他内置辅助工具族，例如： +同样的规则也适用于其他内置辅助工具家族，例如： - 浏览器支持辅助工具：`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` - Matrix：`plugin-sdk/matrix*` - LINE：`plugin-sdk/line*` - IRC：`plugin-sdk/irc*` -- 内置辅助工具 / 插件接口，例如 `plugin-sdk/googlechat`、 +- 内置辅助/插件接口，例如 `plugin-sdk/googlechat`、 `plugin-sdk/zalouser`、`plugin-sdk/bluebubbles*`、 `plugin-sdk/mattermost*`、`plugin-sdk/msteams`、 `plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、 @@ -332,38 +331,35 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 `plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、 `plugin-sdk/thread-ownership` 和 `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` 目前公开的窄范围 token 辅助接口包括 -`DEFAULT_COPILOT_API_BASE_URL`、 -`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。 +`plugin-sdk/github-copilot-token` 当前公开的窄范围 token 辅助接口包括 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。 -请使用与任务最匹配的最窄导入路径。如果你找不到某个导出， -请检查 `src/plugin-sdk/` 下的源码，或在 Discord 中提问。 +请使用与你任务最匹配的最窄导入路径。如果你找不到某个导出，请检查 `src/plugin-sdk/` 下的源代码，或在 Discord 中提问。 ## 移除时间线 | 时间 | 会发生什么 | | ---------------------- | ----------------------------------------------------------------------- | | **现在** | 已弃用接口会发出运行时警告 | -| **下一个主要版本** | 已弃用接口将被移除；仍在使用它们的插件将会失效 | +| **下一个主版本** | 已弃用接口将被移除；仍在使用它们的插件将会失败 | -所有 core 插件都已完成迁移。外部插件应在下一个主要版本之前完成迁移。 +所有核心插件都已经完成迁移。外部插件应在下一个主版本之前完成迁移。 -## 临时抑制警告 +## 暂时抑制警告 -在迁移期间，设置这些环境变量： +在你进行迁移期间，可以设置这些环境变量： ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -这只是临时的应急出口，不是永久解决方案。 +这是一个临时逃生口，而不是永久解决方案。 ## 相关内容 - [入门指南](/zh-CN/plugins/building-plugins) — 构建你的第一个插件 - [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 -- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建 provider 插件 -- [插件内部机制](/zh-CN/plugins/architecture) — 架构深入解析 +- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件 +- [插件内部机制](/zh-CN/plugins/architecture) — 架构深度解析 - [插件清单](/zh-CN/plugins/manifest) — 清单 schema 参考 diff --git a/docs/zh-CN/plugins/sdk-overview.md b/docs/zh-CN/plugins/sdk-overview.md index 85aa2b56c..59ce66613 100644 --- a/docs/zh-CN/plugins/sdk-overview.md +++ b/docs/zh-CN/plugins/sdk-overview.md @@ -2,22 +2,22 @@ read_when: - 你需要知道应该从哪个 SDK 子路径导入 - 你想查看 OpenClawPluginApi 上所有注册方法的参考 - - 你正在查找某个特定的 SDK 导出项 + - 你正在查找某个特定的 SDK 导出 sidebarTitle: SDK Overview summary: 导入映射、注册 API 参考和 SDK 架构 title: 插件 SDK 概览 x-i18n: - generated_at: "2026-04-07T18:43:29Z" + generated_at: "2026-04-07T20:09:23Z" model: gpt-5.4 provider: openai - source_hash: 68d9b78dab757747cfa0e315376af72040ef79453129c0fa051c4c9dd948060f + source_hash: c5a41bd82d165dfbb7fbd6e4528cf322e9133a51efe55fa8518a7a0a626d9d30 source_path: plugins/sdk-overview.md workflow: 15 --- # 插件 SDK 概览 -插件 SDK 是插件与核心之间的类型化契约。此页面是关于**导入什么**以及**你可以注册什么**的参考。 +插件 SDK 是插件与核心之间的类型化契约。本页是关于**该导入什么**以及**你可以注册什么**的参考。 **在找操作指南吗？** @@ -28,24 +28,24 @@ x-i18n: ## 导入约定 -始终从特定子路径导入： +始终从特定的子路径导入： ```typescript 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`。 -保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其宣传为公共接口，否则应将它们视为实现细节/兼容性表面。 +保留的内置插件辅助工具子路径仍会出现在该生成列表中。除非某个文档页面明确将其作为公开接口推广，否则应将它们视为实现细节/兼容性接口。 ### 插件入口点 @@ -75,7 +75,7 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `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/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，并带有内置契约回退 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助工具 | @@ -89,20 +89,20 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `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/channel-plugin-common` | 共享渠道插件前置导出 | | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助工具 | | `plugin-sdk/group-access` | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 共享直接私信认证/防护辅助工具 | + | `plugin-sdk/direct-dm` | 共享直接私信身份验证/保护辅助工具 | | `plugin-sdk/interactive-runtime` | 交互式回复负载规范化/归约辅助工具 | - | `plugin-sdk/channel-inbound` | 入站去抖、提及匹配、提及策略辅助工具以及 envelope 辅助工具 | + | `plugin-sdk/channel-inbound` | 入站去抖、提及匹配、提及策略辅助工具，以及 envelope 辅助工具 | | `plugin-sdk/channel-send-result` | 回复结果类型 | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`、`createMessageToolCardSchema` | | `plugin-sdk/channel-targets` | 目标解析/匹配辅助工具 | | `plugin-sdk/channel-contract` | 渠道契约类型 | | `plugin-sdk/channel-feedback` | 反馈/反应接线 | - | `plugin-sdk/channel-secret-runtime` | 狭义 secret 契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和 secret 目标类型 | + | `plugin-sdk/channel-secret-runtime` | 狭义密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和密钥目标类型 | @@ -110,48 +110,50 @@ 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-runtime` | 提供商插件的运行时 API 密钥解析辅助工具 | + | `plugin-sdk/provider-auth-api-key` | API 密钥新手引导/配置文件写入辅助工具，例如 `upsertApiKeyProfile` | | `plugin-sdk/provider-auth-result` | 标准 OAuth auth-result 构建器 | | `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 构建器、提供商端点辅助工具，以及像 `normalizeNativeXaiModelId` 这样的模型 ID 规范化辅助工具 | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助工具，以及模型 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` | web-fetch 提供商注册/缓存辅助工具 | - | `plugin-sdk/provider-web-search-contract` | 狭义 web-search 配置/凭证契约辅助工具，例如 `enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 和作用域凭证 setter/getter | - | `plugin-sdk/provider-web-search` | web-search 提供商注册/缓存/运行时辅助工具 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似功能 | + | `plugin-sdk/provider-web-fetch` | Web-fetch 提供商注册/缓存辅助工具 | + | `plugin-sdk/provider-web-search-contract` | 狭义 web-search 配置/凭证契约辅助工具，例如 `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-onboard` | 新手引导配置补丁辅助工具 | - | `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 | + | `plugin-sdk/global-singleton` | 进程内本地 singleton/map/cache 辅助工具 | | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 | - | `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天操作认证辅助工具 | - | `plugin-sdk/approval-client-runtime` | 原生执行审批配置文件/过滤器辅助工具 | + | `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作认证辅助工具 | + | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤辅助工具 | | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 | - | `plugin-sdk/approval-handler-runtime` | 共享审批处理器运行时辅助工具，包括能力驱动的原生审批加载 | + | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 | + | `plugin-sdk/approval-handler-adapter-runtime` | 面向高频渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；当狭义适配器/Gateway 网关接缝已足够时，优先使用后者 | | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | exec/plugin 审批回复负载辅助工具 | + | `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助工具 | | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 | | `plugin-sdk/command-detection` | 共享命令检测辅助工具 | - | `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助工具 | + | `plugin-sdk/command-surface` | 命令体规范化和命令接口辅助工具 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 用于渠道/插件 secret 表面的狭义 secret 契约收集辅助工具 | - | `plugin-sdk/secret-ref-runtime` | 用于 secret 契约/配置解析的狭义 `coerceSecretRef` 和 SecretRef 类型辅助工具 | - | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和 secret 收集辅助工具 | + | `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-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch 和 SSRF 策略辅助工具 | - | `plugin-sdk/secret-input` | secret 输入解析辅助工具 | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助工具 | + | `plugin-sdk/secret-input` | 密钥输入解析辅助工具 | | `plugin-sdk/webhook-ingress` | webhook 请求/目标辅助工具 | | `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 | @@ -160,54 +162,54 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/runtime` | 广义运行时/日志/备份/插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 狭义运行时环境、logger、timeout、retry 和 backoff 辅助工具 | + | `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 管道辅助工具 | | `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | 进程执行辅助工具 | + | `plugin-sdk/process-runtime` | 进程 exec 辅助工具 | | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 | | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 | | `plugin-sdk/config-runtime` | 配置加载/写入辅助工具 | - | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约表面不可用时也能工作 | - | `plugin-sdk/approval-runtime` | exec/plugin 审批辅助工具、审批能力构建器、认证/配置文件辅助工具、原生路由/运行时辅助工具 | - | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、心跳、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 狭义回复分发/完成辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约接口不可用时也适用 | + | `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-reference` | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | 狭义文本/Markdown 分块辅助工具 | | `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 | | `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助工具 | | `plugin-sdk/routing` | 路由/会话键/账户绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | 共享渠道/账户状态摘要辅助工具、运行时状态默认值和 issue 元数据辅助工具 | + | `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/param-readers` | 通用工具/CLI 参数读取器 | + | `plugin-sdk/request-url` | 从 fetch/request-like 输入中提取字符串 URL | + | `plugin-sdk/run-command` | 带定时功能的命令运行器，返回规范化的 stdout/stderr 结果 | + | `plugin-sdk/param-readers` | 常用工具/CLI 参数读取器 | | `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 | | `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 | | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助工具 | | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 | | `plugin-sdk/file-lock` | 可重入文件锁辅助工具 | - | `plugin-sdk/persistent-dedupe` | 基于磁盘的去重缓存辅助工具 | + | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 | | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 | - | `plugin-sdk/agent-config-primitives` | 狭义智能体运行时配置 schema 原语 | + | `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/extension-shared` | 共享被动渠道、状态和 ambient proxy 辅助基元 | | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 | | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 | | `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 | | `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 | - | `plugin-sdk/infra-runtime` | 系统事件/心跳辅助工具 | + | `plugin-sdk/infra-runtime` | 系统事件/heartbeat 辅助工具 | | `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 | | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 | - | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具，`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和 pinned 查找辅助工具 | + | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | 包装过的 fetch、代理和 pinned lookup 辅助工具 | | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 | | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 | | `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 | @@ -218,12 +220,12 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具以及媒体负载构建器 | + | `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具，以及媒体负载构建器 | | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择和缺失模型提示 | - | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助工具导出 | - | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如 assistant-visible-text 剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 | + | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 | + | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如助手可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本工具 | | `plugin-sdk/text-chunking` | 出站文本分块辅助工具 | - | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和验证辅助工具 | + | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助工具 | | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助工具 | | `plugin-sdk/realtime-transcription` | 实时转录提供商类型和注册表辅助工具 | | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 | @@ -243,38 +245,38 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助表面，用于 manager/config/file/CLI 辅助工具 | + | `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 主机基础引擎导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 主机嵌入引擎导出 | - | `plugin-sdk/memory-core-host-engine-qmd` | Memory 主机 QMD 引擎导出 | - | `plugin-sdk/memory-core-host-engine-storage` | Memory 主机存储引擎导出 | - | `plugin-sdk/memory-core-host-multimodal` | Memory 主机多模态辅助工具 | - | `plugin-sdk/memory-core-host-query` | Memory 主机查询辅助工具 | - | `plugin-sdk/memory-core-host-secret` | Memory 主机 secret 辅助工具 | - | `plugin-sdk/memory-core-host-events` | Memory 主机事件日志辅助工具 | - | `plugin-sdk/memory-core-host-status` | Memory 主机状态辅助工具 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory 主机 CLI 运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory 主机核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory 主机文件/运行时辅助工具 | - | `plugin-sdk/memory-host-core` | 面向供应商中立的别名，用于 memory 主机核心运行时辅助工具 | - | `plugin-sdk/memory-host-events` | 面向供应商中立的别名，用于 memory 主机事件日志辅助工具 | - | `plugin-sdk/memory-host-files` | 面向供应商中立的别名，用于 memory 主机文件/运行时辅助工具 | - | `plugin-sdk/memory-host-markdown` | 面向 memory 邻接插件的共享托管 Markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活动 memory 运行时门面 | - | `plugin-sdk/memory-host-status` | 面向供应商中立的别名，用于 memory 主机状态辅助工具 | - | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助表面 | + | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding engine 导出 | + | `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-host-multimodal` | Memory host 多模态辅助工具 | + | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 | + | `plugin-sdk/memory-core-host-secret` | Memory host 密钥辅助工具 | + | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 | + | `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 | + | `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` | 用于访问搜索管理器的活动 Memory 运行时门面 | + | `plugin-sdk/memory-host-status` | 面向供应商中立的 memory host 状态辅助工具别名 | + | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助接口 | - - | 系列 | 当前子路径 | 预期用途 | + + | 家族 | 当前子路径 | 预期用途 | | --- | --- | --- | - | 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-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` | @@ -284,51 +286,51 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ### 能力注册 -| 方法 | 注册内容 | +| 方法 | 它注册的内容 | | ------------------------------------------------ | -------------------------------- | -| `api.registerProvider(...)` | 文本推理（LLM） | -| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | -| `api.registerChannel(...)` | 消息渠道 | -| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | +| `api.registerProvider(...)` | 文本推理（LLM） | +| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | +| `api.registerChannel(...)` | 消息渠道 | +| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | | `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 | -| `api.registerRealtimeVoiceProvider(...)` | 双向实时语音会话 | -| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 | -| `api.registerImageGenerationProvider(...)` | 图像生成 | -| `api.registerMusicGenerationProvider(...)` | 音乐生成 | -| `api.registerVideoGenerationProvider(...)` | 视频生成 | -| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 | -| `api.registerWebSearchProvider(...)` | Web 搜索 | +| `api.registerRealtimeVoiceProvider(...)` | 双向实时语音会话 | +| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 | +| `api.registerImageGenerationProvider(...)` | 图像生成 | +| `api.registerMusicGenerationProvider(...)` | 音乐生成 | +| `api.registerVideoGenerationProvider(...)` | 视频生成 | +| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 | +| `api.registerWebSearchProvider(...)` | Web 搜索 | -### 工具与命令 +### 工具和命令 -| 方法 | 注册内容 | +| 方法 | 它注册的内容 | | ------------------------------- | --------------------------------------------- | | `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） | -| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | +| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | ### 基础设施 -| 方法 | 注册内容 | +| 方法 | 它注册的内容 | | ---------------------------------------------- | --------------------------------------- | -| `api.registerHook(events, handler, opts?)` | 事件 hook | -| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | -| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | -| `api.registerCli(registrar, opts?)` | CLI 子命令 | -| `api.registerService(service)` | 后台服务 | -| `api.registerInteractiveHandler(registration)` | 交互式处理器 | -| `api.registerMemoryPromptSupplement(builder)` | 追加式 memory 邻接提示区段 | -| `api.registerMemoryCorpusSupplement(adapter)` | 追加式 memory 搜索/读取语料库 | +| `api.registerHook(events, handler, opts?)` | 事件 hook | +| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | +| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | +| `api.registerCli(registrar, opts?)` | CLI 子命令 | +| `api.registerService(service)` | 后台服务 | +| `api.registerInteractiveHandler(registration)` | 交互式处理器 | +| `api.registerMemoryPromptSupplement(builder)` | 可叠加的、与 Memory 相邻的提示词区段 | +| `api.registerMemoryCorpusSupplement(adapter)` | 可叠加的 Memory 搜索/读取语料 | -保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用插件特定前缀。 +保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用特定于插件的前缀。 ### CLI 注册元数据 -`api.registerCli(registrar, opts?)` 接受两种顶层元数据： +`api.registerCli(registrar, opts?)` 接受两类顶层元数据： -- `commands`：由该 registrar 拥有的显式命令根 +- `commands`：由 registrar 拥有的显式命令根 - `descriptors`：用于根 CLI 帮助、路由和惰性插件 CLI 注册的解析时命令描述符 -如果你希望插件命令在正常的根 CLI 路径中保持惰性加载，请提供 `descriptors`，覆盖该 registrar 暴露的每个顶层命令根。 +如果你希望插件命令在普通根 CLI 路径中保持惰性加载，请提供覆盖该 registrar 暴露的每个顶层命令根的 `descriptors`。 ```typescript api.registerCli( @@ -348,72 +350,72 @@ api.registerCli( ); ``` -仅在你不需要惰性根 CLI 注册时才单独使用 `commands`。这种急切兼容路径仍受支持，但它不会为解析时惰性加载安装基于 descriptor 的占位符。 +仅当你不需要惰性的根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍然受支持，但它不会为解析时惰性加载安装基于 descriptor 的占位符。 ### CLI 后端注册 -`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端的默认配置，例如 `codex-cli`。 +`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。 - 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。 - 后端 `config` 使用与 `agents.defaults.cliBackends.` 相同的结构。 - 用户配置仍然优先生效。OpenClaw 会先将 `agents.defaults.cliBackends.` 合并到插件默认值之上，再运行 CLI。 -- 当后端在合并后需要兼容性重写时，请使用 `normalizeConfig`（例如规范化旧版 flag 结构）。 +- 当某个后端在合并后需要兼容性重写时，使用 `normalizeConfig`（例如规范化旧的 flag 结构）。 ### 独占槽位 -| 方法 | 注册内容 | +| 方法 | 它注册的内容 | | ------------------------------------------ | ------------------------------------- | -| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个处于激活状态） | -| `api.registerMemoryCapability(capability)` | 统一 memory 能力 | -| `api.registerMemoryPromptSection(builder)` | memory 提示区段构建器 | -| `api.registerMemoryFlushPlan(resolver)` | memory 刷新计划解析器 | -| `api.registerMemoryRuntime(runtime)` | memory 运行时适配器 | +| `api.registerContextEngine(id, factory)` | 上下文引擎（同一时间仅一个活动） | +| `api.registerMemoryCapability(capability)` | 统一 Memory 能力 | +| `api.registerMemoryPromptSection(builder)` | Memory 提示词区段构建器 | +| `api.registerMemoryFlushPlan(resolver)` | Memory 刷新计划解析器 | +| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 | ### Memory 嵌入适配器 -| 方法 | 注册内容 | +| 方法 | 它注册的内容 | | ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 memory 嵌入适配器 | +| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory 嵌入适配器 | -- `registerMemoryCapability` 是首选的独占 memory 插件 API。 -- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`，这样配套插件就可以通过 `openclaw/plugin-sdk/memory-host-core` 消费导出的 memory 工件，而不是深入特定 memory 插件的私有布局。 -- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占 memory 插件 API。 -- `registerMemoryEmbeddingProvider` 允许活动 memory 插件注册一个或多个嵌入适配器 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 插件注册一个或多个嵌入适配器 ID（例如 `openai`、`gemini` 或插件自定义 ID）。 +- 用户配置（例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会基于这些已注册的适配器 ID 进行解析。 ### 事件与生命周期 -| 方法 | 作用 | +| 方法 | 它的作用 | | -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook | +| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook | | `api.onConversationBindingResolved(handler)` | 会话绑定回调 | ### Hook 决策语义 -- `before_tool_call`：返回 `{ block: true }` 是终结性的。一旦任一处理器设置它，就会跳过更低优先级的处理器。 -- `before_tool_call`：返回 `{ block: false }` 会被视为未做决定（与省略 `block` 相同），而不是覆盖。 -- `before_install`：返回 `{ block: true }` 是终结性的。一旦任一处理器设置它，就会跳过更低优先级的处理器。 -- `before_install`：返回 `{ block: false }` 会被视为未做决定（与省略 `block` 相同），而不是覆盖。 -- `reply_dispatch`：返回 `{ handled: true, ... }` 是终结性的。一旦任一处理器声明接管分发，就会跳过更低优先级的处理器和默认模型分发路径。 -- `message_sending`：返回 `{ cancel: true }` 是终结性的。一旦任一处理器设置它，就会跳过更低优先级的处理器。 -- `message_sending`：返回 `{ cancel: false }` 会被视为未做决定（与省略 `cancel` 相同），而不是覆盖。 +- `before_tool_call`：返回 `{ block: true }` 是终止性决定。一旦任一处理器设置它，就会跳过更低优先级的处理器。 +- `before_tool_call`：返回 `{ block: false }` 会被视为没有决定（与省略 `block` 相同），而不是覆盖。 +- `before_install`：返回 `{ block: true }` 是终止性决定。一旦任一处理器设置它，就会跳过更低优先级的处理器。 +- `before_install`：返回 `{ block: false }` 会被视为没有决定（与省略 `block` 相同），而不是覆盖。 +- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性决定。一旦任一处理器声明已分发，就会跳过更低优先级的处理器以及默认模型分发路径。 +- `message_sending`：返回 `{ cancel: true }` 是终止性决定。一旦任一处理器设置它，就会跳过更低优先级的处理器。 +- `message_sending`：返回 `{ cancel: false }` 会被视为没有决定（与省略 `cancel` 相同），而不是覆盖。 ### API 对象字段 -| 字段 | 类型 | 说明 | +| 字段 | 类型 | 描述 | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `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` | 来自 `plugins.entries..config` 的插件特定配置 | -| `api.runtime` | `PluginRuntime` | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | 作用域 logger（`debug`、`info`、`warn`、`error`） | -| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置前的轻量窗口 | -| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | +| `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` | 来自 `plugins.entries..config` 的插件专用配置 | +| `api.runtime` | `PluginRuntime` | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | 作用域 logger（`debug`、`info`、`warn`、`error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口点之前的轻量启动/设置窗口 | +| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | ## 内部模块约定 @@ -421,32 +423,27 @@ api.registerCli( ``` my-plugin/ - api.ts # 面向外部使用者的公共导出 + api.ts # 面向外部使用者的公开导出 runtime-api.ts # 仅供内部使用的运行时导出 index.ts # 插件入口点 - setup-entry.ts # 轻量级仅设置入口（可选） + setup-entry.ts # 仅设置用的轻量入口点（可选） ``` - 永远不要在生产代码中通过 `openclaw/plugin-sdk/` - 导入你自己的插件。内部导入应通过 `./api.ts` 或 - `./runtime-api.ts`。SDK 路径仅是对外契约。 + 不要在生产代码中通过 `openclaw/plugin-sdk/` 导入你自己的插件。应通过 `./api.ts` 或 `./runtime-api.ts` 进行内部导入。SDK 路径仅是对外契约。 -通过门面加载的内置插件公共表面（`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/plugin-sdk/`。 - 如果某个辅助工具确实需要共享，应将其提升到中立的 SDK 子路径， - 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他 - 面向能力的表面，而不是把两个插件耦合在一起。 + 扩展生产代码也应避免导入 `openclaw/plugin-sdk/`。如果某个辅助工具确实需要共享，应将其提升到中立的 SDK 子路径，例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他面向能力的接口，而不是让两个插件彼此耦合。 ## 相关内容 @@ -455,5 +452,5 @@ my-plugin/ - [运行时辅助工具](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考 - [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、清单、配置 schema - [测试](/zh-CN/plugins/sdk-testing) — 测试工具和 lint 规则 -- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用表面迁移 -- [插件内部机制](/zh-CN/plugins/architecture) — 深入架构与能力模型 +- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用接口迁移 +- [插件内部机制](/zh-CN/plugins/architecture) — 深入架构和能力模型