diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index 08c799c17..3a15cbc56 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -8,92 +8,101 @@ sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-23T02:58:49Z" + generated_at: "2026-04-23T03:31:37Z" model: gpt-5.4 provider: openai - source_hash: 0abdf5135b0e0a029348b77447ca713e43762a65934310088a098fee93cf9981 + source_hash: 8f21fc911a961bf88f6487dae0c1c2f54c0759911b2a992ae6285aa2f8704006 source_path: plugins/sdk-migration.md workflow: 15 --- # 插件 SDK 迁移 -OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚焦且有文档说明的导入路径。如果你的插件构建于新架构之前，本指南将帮助你完成迁移。 +OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚焦且有文档说明的导入路径。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 -## 正在发生哪些变化 +## 正在发生的变化 -旧版插件系统提供了两个开放范围很大的接口，让插件可以从单一入口点导入所需的任何内容： +旧版插件系统提供了两个完全开放的入口，使插件可以通过单一入口点导入所需的任何内容： -- **`openclaw/plugin-sdk/compat`** — 一个单一导入入口，重新导出了数十个辅助工具。它最初被引入，是为了在新的插件架构构建期间，让旧的基于 hook 的插件继续工作。 -- **`openclaw/extension-api`** — 一个桥接层，让插件可以直接访问宿主侧辅助工具，例如嵌入式 Pi 智能体运行器。 +- **`openclaw/plugin-sdk/compat`** —— 一个单一导入入口，重新导出了数十个辅助工具。它的引入是为了在构建新插件架构期间，保持较旧的基于 hook 的插件继续工作。 +- **`openclaw/extension-api`** —— 一个桥接层，使插件能够直接访问宿主端辅助工具，例如嵌入式智能体运行器。 -这两个接口现在都已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主要版本移除它们之前完成迁移。 +这两个入口现在都已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。 - 向后兼容层将在未来的一个主要版本中移除。 - 到那时，仍从这些接口导入内容的插件将会失效。 + 向后兼容层将在未来的某个主版本中移除。 + 到那时，仍从这些入口导入的插件将会失效。 ## 为什么会有这个变化 -旧方法带来了多个问题： +旧方法带来了几个问题： -- **启动缓慢** — 导入一个辅助工具会连带加载数十个无关模块 -- **循环依赖** — 宽泛的重新导出使创建导入循环变得很容易 -- **API 接口不清晰** — 无法判断哪些导出是稳定的，哪些是内部实现 +- **启动缓慢** —— 导入一个辅助工具会加载数十个无关模块 +- **循环依赖** —— 宽泛的重新导出使创建导入循环变得很容易 +- **API 表面不清晰** —— 无法区分哪些导出是稳定的，哪些是内部实现 -现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、独立的模块，具有明确用途和文档化契约。 +现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、独立的模块，具有清晰用途和文档化契约。 -面向内置渠道的旧版提供商便捷接口也已移除。诸如 `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 便捷入口也已移除。诸如 `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` 中。 -当前内置提供商示例： +当前内置 provider 示例： -- Anthropic 在其自己的 `api.ts` / `contract-api.ts` 接口中保留了 Claude 专用的流辅助工具 -- OpenAI 在其自己的 `api.ts` 中保留了提供商构建器、默认模型辅助工具以及 realtime 提供商构建器 -- OpenRouter 在其自己的 `api.ts` 中保留了提供商构建器以及新手引导 / 配置辅助工具 +- Anthropic 将 Claude 专用的流式辅助工具保留在它自己的 `api.ts` / `contract-api.ts` 入口中 +- OpenAI 将 provider 构建器、默认模型辅助工具和实时 provider 构建器保留在它自己的 `api.ts` 中 +- OpenRouter 将 provider 构建器以及新手引导 / 配置辅助工具保留在它自己的 `api.ts` 中 ## 如何迁移 - - 支持审批的渠道插件现在通过 `approvalCapability.nativeRuntime` 以及共享运行时上下文注册表来公开原生审批行为。 + + 具备审批能力的渠道插件现在通过 `approvalCapability.nativeRuntime` 和共享运行时上下文注册表暴露原生审批行为。 关键变化： - - 用 `approvalCapability.nativeRuntime` 替换 `approvalCapability.handler.loadRuntime(...)` - - 将审批专用的认证 / 传递逻辑从旧版 `plugin.auth` / `plugin.approvals` 接线迁移到 `approvalCapability` - - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；请将 delivery / native / render 字段迁移到 `approvalCapability` - - `plugin.auth` 仅保留给渠道登录 / 登出流程使用；其中的审批认证 hook 将不再被核心读取 - - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道自有的运行时对象，例如客户端、令牌或 Bolt 应用 - - 不要从原生审批处理器发送插件自有的改道通知；核心现在会根据实际传递结果统一处理“已路由到其他位置”的通知 - - 当把 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 接口。部分 stub 将被拒绝。 + - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 `approvalCapability.nativeRuntime` + - 将审批专用的认证 / 投递逻辑从旧版 `plugin.auth` / + `plugin.approvals` 接线迁移到 `approvalCapability` + - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除； + 请将 delivery / native / render 字段迁移到 `approvalCapability` + - `plugin.auth` 仅保留用于渠道登录 / 登出流程；其中的审批认证 + hook 不再被核心读取 + - 通过 `openclaw/plugin-sdk/channel-runtime-context` + 注册由渠道拥有的运行时对象，例如客户端、令牌或 Bolt + 应用 + - 不要从原生审批处理器发送由插件拥有的重路由通知； + 核心现在会基于实际投递结果负责 routed-elsewhere 通知 + - 将 `channelRuntime` 传入 `createChannelManager(...)` 时，需提供 + 真实的 `createPluginRuntime().channel` 表面。部分 stub 将被拒绝。 - 当前的 approval capability 布局请参见 `/plugins/sdk-channel-plugins`。 + 当前审批能力布局请参见 `/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 const program = applyWindowsSpawnProgramPolicy({ candidate }); - // 之后 + // After const program = applyWindowsSpawnProgramPolicy({ candidate, - // 仅对受信任的兼容性调用方设置此项，这些调用方明确接受 - // 通过 shell 中介的回退行为。 + // Only set this for trusted compatibility callers that intentionally + // accept shell-mediated fallback. allowShellFallback: true, }); ``` - 如果你的调用方并不有意依赖 shell 回退，请不要设置 `allowShellFallback`，而应改为处理抛出的错误。 + 如果你的调用方并非有意依赖 shell 回退，请不要设置 + `allowShellFallback`，而应改为处理抛出的错误。 - 在你的插件中搜索来自任一已弃用接口的导入： + 在你的插件中搜索来自这两个已弃用入口的导入： ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -103,36 +112,36 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 - 旧接口中的每个导出都映射到一个特定的现代导入路径： + 旧入口中的每个导出都映射到一个特定的现代导入路径： ```typescript - // 之前（已弃用的向后兼容层） + // Before (deprecated backwards-compatibility layer) import { createChannelReplyPipeline, createPluginRuntimeStore, resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // 之后（现代聚焦导入） + // After (modern focused imports) import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - 对于宿主侧辅助工具，请使用注入的插件运行时，而不是直接导入： + 对于宿主端辅助工具，请使用注入的插件运行时，而不是直接导入： ```typescript - // 之前（已弃用的 extension-api 桥接层） + // Before (deprecated extension-api bridge) import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // 之后（注入的运行时） + // After (injected runtime) const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` 同样的模式也适用于其他旧版桥接辅助工具： - | 旧导入 | 现代等价项 | + | 旧导入 | 现代等价方式 | | --- | --- | | `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` | | `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` | @@ -140,7 +149,7 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | 会话存储辅助工具 | `api.runtime.agent.session.*` | + | session store helpers | `api.runtime.agent.session.*` | @@ -157,24 +166,24 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 | 导入路径 | 用途 | 关键导出 | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` | - | `plugin-sdk/core` | 旧版总括式重新导出，用于渠道入口定义 / 构建器 | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | 单提供商入口辅助工具 | `defineSingleProviderPluginEntry` | + | `plugin-sdk/plugin-entry` | 规范的插件入口辅助工具 | `definePluginEntry` | + | `plugin-sdk/core` | 用于渠道入口定义 / 构建器的旧版统一重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | 根配置模式导出 | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | 单一 provider 入口辅助工具 | `defineSingleProviderPluginEntry` | | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享设置向导辅助工具 | Allowlist 提示、设置状态构建器 | - | `plugin-sdk/setup-runtime` | 设置阶段运行时辅助工具 | 可安全导入的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 | + | `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` | 多账户辅助工具 | 账户列表 / 配置 / 操作门控辅助工具 | | `plugin-sdk/account-id` | account-id 辅助工具 | `DEFAULT_ACCOUNT_ID`、account-id 规范化 | | `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表 / 账户操作辅助工具 | - | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` | + | `plugin-sdk/account-helpers` | 精简的账户辅助工具 | 账户列表 / account-action 辅助工具 | + | `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 构建器 | 渠道配置 schema 类型 | + | `plugin-sdk/channel-config-schema` | 配置模式构建器 | 渠道配置模式类型 | | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复 / 冲突校验 | | `plugin-sdk/channel-policy` | 群组 / 私信策略解析 | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | 账户状态和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览最终化辅助工具 | @@ -182,156 +191,156 @@ OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚 | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录并分发辅助工具 | | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析 / 匹配辅助工具 | | `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 | - | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站身份 / 发送委托和载荷规划辅助工具 | + | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站身份 / send 委托和负载规划辅助工具 | | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 | - | `plugin-sdk/agent-media-payload` | 旧版媒体载荷辅助工具 | 面向旧字段布局的智能体媒体载荷构建器 | - | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅保留旧版渠道运行时工具 | + | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 面向旧字段布局的智能体媒体负载构建器 | + | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅旧版渠道运行时工具 | | `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 | | `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | 宽范围运行时辅助工具 | 运行时 / 日志 / 备份 / 插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | Logger / 运行时环境、超时、重试和退避辅助工具 | - | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令 / hook / 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/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和 channel-status 补丁辅助工具 | | `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载 / 写入辅助工具 | - | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供回退稳定的 Telegram 命令校验辅助工具 | - | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec / plugin 审批载荷、approval capability / profile 辅助工具、原生审批路由 / 运行时辅助工具 | - | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | 审批人解析、同聊天操作认证 | - | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批 profile / 过滤器辅助工具 | - | `plugin-sdk/approval-delivery-runtime` | 审批传递辅助工具 | 原生 approval capability / 传递适配器 | + | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约表面不可用时，提供具备稳定回退能力的 Telegram 命令校验辅助工具 | + | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec / 插件审批负载、审批能力 / 配置文件辅助工具、原生审批路由 / 运行时辅助工具 | + | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | approver 解析、同聊天操作认证 | + | `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-handler-adapter-runtime` | 审批适配器辅助工具 | 面向高频渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽泛的审批处理器运行时辅助工具；如果更精简的 adapter / gateway 入口已足够，则优先使用它们 | | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标 / 账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec / plugin 审批回复载荷辅助工具 | + | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec / 插件审批回复负载辅助工具 | | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register / get / watch 辅助工具 | - | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和机密收集辅助工具 | - | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 Allowlist 和私有网络策略辅助工具 | + | `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` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | | `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 | - | `plugin-sdk/fetch-runtime` | 封装的 fetch / 代理辅助工具 | `resolveFetch`、代理辅助工具 | + | `plugin-sdk/fetch-runtime` | 包装后的 fetch / proxy 辅助工具 | `resolveFetch`、proxy 辅助工具 | | `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | | `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 | - | `plugin-sdk/allow-from` | Allowlist 格式化 | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Allowlist 输入映射 | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | 命令门控和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 | + | `plugin-sdk/allow-from` | allowlist 格式化 | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | allowlist 输入映射 | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | 命令门控和命令表面辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 | | `plugin-sdk/command-status` | 命令状态 / 帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | 机密输入解析 | 机密输入辅助工具 | + | `plugin-sdk/secret-input` | secret 输入解析 | secret 输入辅助工具 | | `plugin-sdk/webhook-ingress` | webhook 请求辅助工具 | webhook 目标工具 | - | `plugin-sdk/webhook-request-guards` | webhook 请求体保护辅助工具 | 请求体读取 / 限制辅助工具 | + | `plugin-sdk/webhook-request-guards` | webhook 请求体守卫辅助工具 | 请求体读取 / 限制辅助工具 | | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | finalize + 提供商分发辅助工具 | + | `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发辅助工具 | 最终化 + provider 分发辅助工具 | | `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `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/routing` | 路由 / session-key 辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、session-key 规范化辅助工具 | | `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道 / 账户状态摘要构建器、运行时状态默认值、问题元数据辅助工具 | | `plugin-sdk/target-resolver-runtime` | 目标解析器辅助工具 | 共享目标解析器辅助工具 | | `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug / 字符串规范化辅助工具 | | `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类请求输入中提取字符串 URL | - | `plugin-sdk/run-command` | 定时命令辅助工具 | 具有规范化 stdout / stderr 的定时命令运行器 | + | `plugin-sdk/run-command` | 定时命令辅助工具 | 带标准化 stdout / stderr 的定时命令运行器 | | `plugin-sdk/param-readers` | 参数读取器 | 通用工具 / CLI 参数读取器 | - | `plugin-sdk/tool-payload` | 工具载荷提取 | 从工具结果对象中提取规范化载荷 | - | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范化发送目标字段 | + | `plugin-sdk/tool-payload` | 工具负载提取 | 从工具结果对象中提取标准化负载 | + | `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` | 精选的本地 / 自托管提供商设置辅助工具 | 自托管提供商发现 / 配置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管提供商设置辅助工具 | 同样的自托管提供商发现 / 配置辅助工具 | - | `plugin-sdk/provider-auth-runtime` | 提供商运行时认证辅助工具 | 运行时 API key 解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | 提供商 API key 设置辅助工具 | API key 新手引导 / profile 写入辅助工具 | - | `plugin-sdk/provider-auth-result` | 提供商认证结果辅助工具 | 标准 OAuth auth-result 构建器 | - | `plugin-sdk/provider-auth-login` | 提供商交互式登录辅助工具 | 共享交互式登录辅助工具 | - | `plugin-sdk/provider-env-vars` | 提供商环境变量辅助工具 | 提供商认证环境变量查找辅助工具 | - | `plugin-sdk/provider-model-shared` | 共享提供商模型 / replay 辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助工具以及 model-id 规范化辅助工具 | - | `plugin-sdk/provider-catalog-shared` | 共享提供商目录辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | 提供商新手引导补丁 | 新手引导配置辅助工具 | - | `plugin-sdk/provider-http` | 提供商 HTTP 辅助工具 | 通用提供商 HTTP / 端点能力辅助工具 | - | `plugin-sdk/provider-web-fetch` | 提供商 web-fetch 辅助工具 | web-fetch 提供商注册 / 缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | 提供商 web-search 配置辅助工具 | 面向不需要插件启用接线的提供商的窄范围 web-search 配置 / 凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | 提供商 web-search 契约辅助工具 | 窄范围 web-search 配置 / 凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`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/provider-transport-runtime` | 提供商传输辅助工具 | 原生提供商传输辅助工具，例如受保护 fetch、传输消息转换以及可写传输事件流 | + | `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-key 解析辅助工具 | + | `plugin-sdk/provider-auth-api-key` | provider API-key 设置辅助工具 | API-key 新手引导 / 配置文件写入辅助工具 | + | `plugin-sdk/provider-auth-result` | provider auth-result 辅助工具 | 标准 OAuth auth-result 构建器 | + | `plugin-sdk/provider-auth-login` | provider 交互式登录辅助工具 | 共享交互式登录辅助工具 | + | `plugin-sdk/provider-env-vars` | provider 环境变量辅助工具 | provider 认证环境变量查找辅助工具 | + | `plugin-sdk/provider-model-shared` | 共享 provider 模型 / 重放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具以及 model-id 规范化辅助工具 | + | `plugin-sdk/provider-catalog-shared` | 共享 provider 目录辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | provider 新手引导补丁 | 新手引导配置辅助工具 | + | `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP / endpoint 能力辅助工具，包括音频转录 multipart form 辅助工具 | + | `plugin-sdk/provider-web-fetch` | provider web-fetch 辅助工具 | web-fetch provider 注册 / 缓存辅助工具 | + | `plugin-sdk/provider-web-search-config-contract` | provider web-search 配置辅助工具 | 面向不需要 plugin-enable 接线的 provider 的精简 web-search 配置 / 凭证辅助工具 | + | `plugin-sdk/provider-web-search-contract` | provider web-search 契约辅助工具 | 精简的 web-search 配置 / 凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域化的凭证 setter / getter | + | `plugin-sdk/provider-web-search` | provider web-search 辅助工具 | web-search 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-transport-runtime` | provider 传输辅助工具 | 原生 provider 传输辅助工具，例如受保护的 fetch、传输消息转换以及可写的传输事件流 | | `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取 / 转换 / 存储辅助工具，以及媒体载荷构建器 | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 面向图像 / 视频 / 音乐生成的共享故障转移辅助工具、候选项选择以及缺失模型提示 | - | `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助工具导出 | - | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本剥离、markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具，以及相关文本 / 日志辅助工具 | + | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取 / 转换 / 存储辅助工具，以及媒体负载构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 图像 / 视频 / 音乐生成的共享故障切换辅助工具、候选项选择和缺失模型提示 | + | `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解 provider 类型，以及面向 provider 的图像 / 音频辅助导出 | + | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本的剥离、markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具，以及相关文本 / 日志辅助工具 | | `plugin-sdk/text-chunking` | 文本分块辅助工具 | 出站文本分块辅助工具 | - | `plugin-sdk/speech` | 语音辅助工具 | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助工具 | - | `plugin-sdk/speech-core` | 共享语音核心 | 语音提供商类型、注册表、directive、规范化 | - | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | 提供商类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | - | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | 提供商类型和注册表辅助工具 | - | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表辅助工具 | - | `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/speech` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的 directive、注册表和校验辅助工具 | + | `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、directives、规范化 | + | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | + | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型和注册表辅助工具 | + | `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` | 渠道配置原语 | 精简的渠道 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/allowlist-config-edit` | allowlist 配置辅助工具 | allowlist 配置编辑 / 读取辅助工具 | | `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证 / 保护辅助工具 | + | `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/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` | 内存宿主机密辅助工具 | 内存宿主机密辅助工具 | - | `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 | + | `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 嵌入契约、注册表访问、本地 provider 和通用批处理 / 远程辅助工具；具体远程 provider 位于其所属插件中 | + | `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 宿主 secret 辅助工具 | Memory 宿主 secret 辅助工具 | + | `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 宿主核心运行时别名 | 面向供应商中立的 Memory 宿主核心运行时辅助工具别名 | + | `plugin-sdk/memory-host-events` | Memory 宿主事件日志别名 | 面向供应商中立的 Memory 宿主事件日志辅助工具别名 | + | `plugin-sdk/memory-host-files` | Memory 宿主文件 / 运行时别名 | 面向供应商中立的 Memory 宿主文件 / 运行时辅助工具别名 | + | `plugin-sdk/memory-host-markdown` | 托管 markdown 辅助工具 | 面向与 Memory 邻接插件的共享托管 markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索门面 | 延迟加载的活跃 Memory 搜索管理器运行时门面 | + | `plugin-sdk/memory-host-status` | Memory 宿主状态别名 | 面向供应商中立的 Memory 宿主状态辅助工具别名 | + | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | Memory-lancedb 辅助表面 | + | `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mocks | -此表有意只包含常见迁移子集，而不是完整的 SDK 接口。 -完整的 200+ 入口点列表位于 +此表特意只包含常见迁移子集，而不是完整的 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/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`、 @@ -340,38 +349,38 @@ 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`、 +`plugin-sdk/github-copilot-token` 当前暴露了精简的 token-helper +表面：`DEFAULT_COPILOT_API_BASE_URL`、 `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。 -请使用与你任务最匹配的最窄导入路径。如果你找不到某个导出， -请查看 `src/plugin-sdk/` 中的源码，或在 Discord 中提问。 +请使用与你的任务最匹配、最精简的导入路径。如果你找不到某个导出， +请查看 `src/plugin-sdk/` 下的源码，或在 Discord 中提问。 -## 移除时间线 +## 移除时间表 | 时间 | 会发生什么 | | ---------------------- | ----------------------------------------------------------------------- | -| **现在** | 已弃用接口会发出运行时警告 | -| **下一个主要版本** | 已弃用接口将被移除；仍在使用它们的插件将会失效 | +| **现在** | 已弃用入口会发出运行时警告 | +| **下一个主版本发布时** | 已弃用入口将被移除；仍在使用它们的插件将会失效 | -所有核心插件都已经完成迁移。外部插件应在下一个主要版本之前完成迁移。 +所有核心插件都已经完成迁移。外部插件应在下一个主版本发布前完成迁移。 ## 临时抑制警告 -在你进行迁移期间，可设置以下环境变量： +在你进行迁移时，设置以下环境变量： ```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) — 完整子路径导入参考 +- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整的子路径导入参考 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件 -- [插件内部机制](/zh-CN/plugins/architecture) — 架构深入解析 -- [插件清单](/zh-CN/plugins/manifest) — 清单 schema 参考 +- [插件内部机制](/zh-CN/plugins/architecture) — 架构深度解析 +- [插件清单](/zh-CN/plugins/manifest) — 清单模式参考 diff --git a/docs/zh-CN/plugins/sdk-overview.md b/docs/zh-CN/plugins/sdk-overview.md index b00ae7c35..6e024f8e5 100644 --- a/docs/zh-CN/plugins/sdk-overview.md +++ b/docs/zh-CN/plugins/sdk-overview.md @@ -1,362 +1,376 @@ --- read_when: - - 你需要知道要从哪个 SDK 子路径导入 - - 你想要一份 OpenClawPluginApi 上所有注册方法的参考资料 - - 你正在查找某个特定的 SDK 导出项 + - 你需要知道应从哪个 SDK 子路径导入 + - 你想查看 OpenClawPluginApi 上所有注册方法的参考文档 + - 你正在查找某个特定的 SDK 导出内容 sidebarTitle: SDK Overview -summary: 导入映射、注册 API 参考和 SDK 架构 +summary: Import map、注册 API 参考和 SDK 架构 title: 插件 SDK 概览 x-i18n: - generated_at: "2026-04-23T02:58:47Z" + generated_at: "2026-04-23T03:31:38Z" model: gpt-5.4 provider: openai - source_hash: 947f309c36e0a4d9c20639f5e18bc1b9d9e07af333414741ad36f24017716ae1 + source_hash: 5f9608fa3194b1b1609d16d7e2077ea58de097e9e8d4cedef4cb975adfb92938 source_path: plugins/sdk-overview.md workflow: 15 --- # 插件 SDK 概览 -插件 SDK 是插件与核心之间的类型化契约。本页是关于**该导入什么**以及**你可以注册什么**的参考资料。 +插件 SDK 是插件与核心之间的类型化契约。本页面是关于**导入什么**以及**你可以注册什么**的参考文档。 **在找操作指南？** - - 第一个插件？从 [入门指南](/zh-CN/plugins/building-plugins) 开始 - - 渠道插件？参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins) - - 提供商插件？参见 [提供商插件](/zh-CN/plugins/sdk-provider-plugins) + - 第一个插件？从[入门指南](/zh-CN/plugins/building-plugins)开始 + - 渠道插件？参见[渠道插件](/zh-CN/plugins/sdk-channel-plugins) + - 提供商插件？参见[提供商插件](/zh-CN/plugins/sdk-provider-plugins) ## 导入约定 -始终从特定的子路径导入： +始终从特定子路径导入： ```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/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`。 -保留给内置插件的辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其推广为公开接口，否则应将它们视为实现细节 / 兼容性入口面。 +保留的内置插件辅助子路径仍会出现在该生成列表中。 +除非某个文档页面明确将其推广为公开接口，否则请将它们视为实现细节/兼容性接口。 -### 插件入口 +### 插件入口点 -| 子路径 | 关键导出项 | -| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| 子路径 | 关键导出 | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | 子路径 | 关键导出项 | + | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出项（`OpenClawSchema`） | + | `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | 共享的设置向导辅助函数、allowlist 提示、设置状态构建器 | + | `plugin-sdk/setup` | 共享设置向导辅助函数、allowlist 提示、设置状态构建器 | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助函数、默认账户回退辅助函数 | + | `plugin-sdk/account-core` | 多账户配置/操作门控辅助函数、默认账户回退辅助函数 | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助函数 | | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 | - | `plugin-sdk/account-helpers` | 狭义的账户列表 / 账户操作辅助函数 | + | `plugin-sdk/account-helpers` | 精简的账户列表/账户操作辅助函数 | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 | - | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 校验辅助函数，带有内置契约回退 | - | `plugin-sdk/command-gating` | 狭义的命令授权门控辅助函数 | + | `plugin-sdk/telegram-command-config` | 带有内置契约回退的 Telegram 自定义命令规范化/验证辅助函数 | + | `plugin-sdk/command-gating` | 精简的命令授权门控辅助函数 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 收尾辅助函数 | - | `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建器辅助函数 | - | `plugin-sdk/inbound-reply-dispatch` | 共享的入站记录与分发辅助函数 | - | `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助函数 | - | `plugin-sdk/outbound-media` | 共享的出站媒体加载辅助函数 | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/最终化辅助函数 | + | `plugin-sdk/inbound-envelope` | 共享入站路由 + 信封构建器辅助函数 | + | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助函数 | + | `plugin-sdk/messaging-targets` | 目标解析/匹配辅助函数 | + | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助函数 | | `plugin-sdk/outbound-runtime` | 出站身份、发送委托和载荷规划辅助函数 | - | `plugin-sdk/poll-runtime` | 狭义的投票规范化辅助函数 | + | `plugin-sdk/poll-runtime` | 精简的投票规范化辅助函数 | | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助函数 | | `plugin-sdk/agent-media-payload` | 旧版智能体媒体载荷构建器 | - | `plugin-sdk/conversation-runtime` | 对话 / 线程绑定、配对和已配置绑定辅助函数 | + | `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对和已配置绑定辅助函数 | | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 | | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 | - | `plugin-sdk/channel-status` | 共享的渠道状态快照 / 摘要辅助函数 | - | `plugin-sdk/channel-config-primitives` | 狭义的渠道配置 schema 基元 | + | `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助函数 | + | `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 原语 | | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 | - | `plugin-sdk/channel-plugin-common` | 共享的渠道插件前导导出项 | - | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助函数 | - | `plugin-sdk/group-access` | 共享的群组访问决策辅助函数 | - | `plugin-sdk/direct-dm` | 共享的直接私信认证 / 守卫辅助函数 | - | `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递以及旧版交互式回复辅助函数。参见 [消息呈现](/zh-CN/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | 入站防抖、提及匹配、提及策略辅助函数和 envelope 辅助函数的兼容性 barrel | - | `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时入口面的狭义提及策略辅助函数 | + | `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 | + | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助函数 | + | `plugin-sdk/group-access` | 共享群组访问决策辅助函数 | + | `plugin-sdk/direct-dm` | 共享直接私信认证/保护辅助函数 | + | `plugin-sdk/interactive-runtime` | 语义消息呈现、投递和旧版交互式回复辅助函数。参见[消息呈现](/zh-CN/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | 入站防抖、提及匹配、提及策略辅助函数和信封辅助函数的兼容性 barrel | + | `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时接口的精简提及策略辅助函数 | | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助函数 | - | `plugin-sdk/channel-logging` | 用于入站丢弃和输入中 / 确认失败的渠道日志辅助函数 | + | `plugin-sdk/channel-logging` | 用于入站丢弃及 typing/ack 失败的渠道日志辅助函数 | | `plugin-sdk/channel-send-result` | 回复结果类型 | | `plugin-sdk/channel-actions` | 渠道消息操作辅助函数，以及为插件兼容性保留的已弃用原生 schema 辅助函数 | - | `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助函数 | + | `plugin-sdk/channel-targets` | 目标解析/匹配辅助函数 | | `plugin-sdk/channel-contract` | 渠道契约类型 | - | `plugin-sdk/channel-feedback` | 反馈 / 反应接线 | - | `plugin-sdk/channel-secret-runtime` | 狭义的密钥契约辅助函数，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 以及密钥目标类型 | + | `plugin-sdk/channel-feedback` | 反馈/反应接线 | + | `plugin-sdk/channel-secret-runtime` | 精简的密钥契约辅助函数，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和密钥目标类型 | - | 子路径 | 关键导出项 | + | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助函数 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦于 OpenAI 兼容自托管提供商的设置辅助函数 | + | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助函数 | + | `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 key 解析辅助函数 | + | `plugin-sdk/provider-auth-api-key` | API key 新手引导/profile 写入辅助函数，例如 `upsertApiKeyProfile` | | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 | - | `plugin-sdk/provider-auth-login` | 供提供商插件使用的共享交互式登录辅助函数 | + | `plugin-sdk/provider-auth-login` | 用于提供商插件的共享交互式登录辅助函数 | | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助函数 | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助函数 | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint 能力辅助函数 | - | `plugin-sdk/provider-web-fetch-contract` | 狭义的 web-fetch 配置 / 选择契约辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助函数 | - | `plugin-sdk/provider-web-search-config-contract` | 适用于不需要插件启用接线的提供商的狭义 web-search 配置 / 凭证辅助函数 | - | `plugin-sdk/provider-web-search-contract` | 狭义的 web-search 配置 / 凭证契约辅助函数，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及有作用域的凭证 setter / getter | - | `plugin-sdk/provider-web-search` | web-search 提供商注册 / 缓存 / 运行时辅助函数 | + | `plugin-sdk/provider-http` | 通用提供商 HTTP/endpoint 能力辅助函数，包括音频转录 multipart form 辅助函数 | + | `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置/选择契约辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Web-fetch 提供商注册/缓存辅助函数 | + | `plugin-sdk/provider-web-search-config-contract` | 为不需要插件启用接线的提供商提供的精简 web-search 配置/凭证辅助函数 | + | `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置/凭证契约辅助函数，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 和作用域凭证 setter/getter | + | `plugin-sdk/provider-web-search` | 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-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助函数 | | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助函数，例如受保护的 fetch、传输消息转换和可写传输事件流 | | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 | - | `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助函数 | + | `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助函数 | - - | 子路径 | 关键导出项 | + + | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 | - | `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作认证辅助函数 | - | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件 / 过滤器辅助函数 | - | `plugin-sdk/approval-delivery-runtime` | 原生审批能力 / 投递适配器 | - | `plugin-sdk/approval-gateway-runtime` | 共享的审批 Gateway 网关解析辅助函数 | - | `plugin-sdk/approval-handler-adapter-runtime` | 适用于热渠道入口点的轻量级原生审批适配器加载辅助函数 | - | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助函数；当更狭义的 adapter/gateway 入口面已足够时，优先使用它们 | + | `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | 审批者解析和同聊天操作认证辅助函数 | + | `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile/filter 辅助函数 | + | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 | + | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助函数 | + | `plugin-sdk/approval-handler-adapter-runtime` | 用于热渠道入口点的轻量级原生审批适配器加载辅助函数 | + | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助函数；当精简的 adapter/gateway 接口已足够时，优先使用它们 | | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助函数 | | `plugin-sdk/approval-reply-runtime` | exec/plugin 审批回复载荷辅助函数 | | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助函数 | - | `plugin-sdk/command-detection` | 共享的命令检测辅助函数 | - | `plugin-sdk/command-surface` | 命令体规范化和命令入口面辅助函数 | + | `plugin-sdk/command-detection` | 共享命令检测辅助函数 | + | `plugin-sdk/command-surface` | 命令体规范化和命令接口辅助函数 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 用于渠道 / 插件密钥入口面的狭义密钥契约收集辅助函数 | - | `plugin-sdk/secret-ref-runtime` | 用于密钥契约 / 配置解析的狭义 `coerceSecretRef` 和 SecretRef 类型辅助函数 | - | `plugin-sdk/security-runtime` | 共享的信任、私信门控、外部内容和密钥收集辅助函数 | + | `plugin-sdk/channel-secret-runtime` | 面向渠道/plugin 密钥接口的精简密钥契约收集辅助函数 | + | `plugin-sdk/secret-ref-runtime` | 用于密钥契约/配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助函数 | + | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和密钥收集辅助函数 | | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 | - | `plugin-sdk/ssrf-dispatcher` | 不带广泛基础设施运行时入口面的狭义固定 dispatcher 辅助函数 | - | `plugin-sdk/ssrf-runtime` | 固定 dispatcher、受 SSRF 保护的 fetch 和 SSRF 策略辅助函数 | + | `plugin-sdk/ssrf-dispatcher` | 不包含广泛基础设施运行时接口的精简 pinned-dispatcher 辅助函数 | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch 和 SSRF 策略辅助函数 | | `plugin-sdk/secret-input` | 密钥输入解析辅助函数 | - | `plugin-sdk/webhook-ingress` | webhook 请求 / 目标辅助函数 | - | `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助函数 | + | `plugin-sdk/webhook-ingress` | webhook 请求/目标辅助函数 | + | `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助函数 | - - | 子路径 | 关键导出项 | + + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 广泛的运行时 / 日志 / 备份 / 插件安装辅助函数 | - | `plugin-sdk/runtime-env` | 狭义的运行时环境、logger、超时、重试和退避辅助函数 | - | `plugin-sdk/channel-runtime-context` | 通用的渠道运行时上下文注册和查找辅助函数 | + | `plugin-sdk/runtime` | 广泛的运行时/日志/备份/plugin 安装辅助函数 | + | `plugin-sdk/runtime-env` | 精简的运行时环境、记录器、超时、重试和退避辅助函数 | + | `plugin-sdk/channel-runtime-context` | 通用渠道 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/plugin-runtime` | 共享 plugin 命令/hook/http/交互式辅助函数 | + | `plugin-sdk/hook-runtime` | 共享 webhook/内部 hook 流水线辅助函数 | + | `plugin-sdk/lazy-runtime` | 延迟运行时导入/绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | | `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/text-autolink-runtime` | 不依赖广泛 `text-runtime` barrel 的文件引用自动链接检测 | - | `plugin-sdk/approval-runtime` | exec/plugin 审批辅助函数、审批能力构建器、认证 / 配置文件辅助函数、原生路由 / 运行时辅助函数 | - | `plugin-sdk/reply-runtime` | 共享的入站 / 回复运行时辅助函数、分块、分发、心跳、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 狭义的回复分发 / 收尾辅助函数 | - | `plugin-sdk/reply-history` | 共享的短窗口回复历史辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/config-runtime` | 配置加载/写入辅助函数和 plugin 配置查找辅助函数 | + | `plugin-sdk/telegram-command-config` | Telegram 命令名/描述规范化以及重复/冲突检查，即使内置的 Telegram 契约接口不可用也可使用 | + | `plugin-sdk/text-autolink-runtime` | 不依赖广泛 text-runtime barrel 的文件引用自动链接检测 | + | `plugin-sdk/approval-runtime` | exec/plugin 审批辅助函数、审批能力构建器、认证/profile 辅助函数、原生路由/运行时辅助函数 | + | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助函数、分块、分发、心跳、回复规划器 | + | `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发/最终化辅助函数 | + | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 狭义的文本 / Markdown 分块辅助函数 | + | `plugin-sdk/reply-chunking` | 精简的文本/Markdown 分块辅助函数 | | `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助函数 | - | `plugin-sdk/state-paths` | 状态 / OAuth 目录路径辅助函数 | - | `plugin-sdk/routing` | 路由 / 会话键 / 账户绑定辅助函数，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | 共享的渠道 / 账户状态摘要辅助函数、运行时状态默认值和问题元数据辅助函数 | - | `plugin-sdk/target-resolver-runtime` | 共享的目标解析器辅助函数 | + | `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助函数 | + | `plugin-sdk/routing` | 路由/会话键/账户绑定辅助函数，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | 共享渠道/账户状态摘要辅助函数、运行时状态默认值和问题元数据辅助函数 | + | `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助函数 | | `plugin-sdk/string-normalization-runtime` | slug/字符串规范化辅助函数 | - | `plugin-sdk/request-url` | 从 fetch/类似 request 的输入中提取字符串 URL | - | `plugin-sdk/run-command` | 带计时功能的命令运行器，返回已规范化的 stdout/stderr 结果 | - | `plugin-sdk/param-readers` | 常用工具 / CLI 参数读取器 | + | `plugin-sdk/request-url` | 从 fetch/request 类输入中提取字符串 URL | + | `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化的 stdout/stderr 结果 | + | `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 | | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化载荷 | - | `plugin-sdk/tool-send` | 从工具参数中提取规范化发送目标字段 | - | `plugin-sdk/temp-path` | 共享的临时下载路径辅助函数 | - | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助函数 | + | `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 | + | `plugin-sdk/temp-path` | 共享临时下载路径辅助函数 | + | `plugin-sdk/logging-core` | 子系统记录器和脱敏辅助函数 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助函数 | | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助函数 | | `plugin-sdk/file-lock` | 可重入文件锁辅助函数 | | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 | - | `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复分发辅助函数 | + | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助函数 | | `plugin-sdk/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 | - | `plugin-sdk/agent-config-primitives` | 狭义的智能体运行时配置 schema 基元 | - | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | + | `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/models-provider-runtime` | `/models` 命令 / 提供商回复辅助函数 | - | `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助函数 | - | `plugin-sdk/native-command-registry` | 原生命令注册表 / 构建 / 序列化辅助函数 | - | `plugin-sdk/agent-harness` | 面向低层智能体 harness 的实验性受信任插件入口面：harness 类型、活动运行 steer/abort 辅助函数、OpenClaw 工具桥接辅助函数和 attempt 结果工具 | - | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助函数 | - | `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助函数 | + | `plugin-sdk/device-bootstrap` | 设备 bootstrap 和配对令牌辅助函数 | + | `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助原语 | + | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助函数 | + | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助函数 | + | `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助函数 | + | `plugin-sdk/agent-harness` | 面向低级智能体 harness 的实验性可信 plugin 接口：harness 类型、活动运行 steer/abort 辅助函数、OpenClaw 工具桥接辅助函数和尝试结果工具 | + | `plugin-sdk/provider-zai-endpoint` | Z.AI endpoint 检测辅助函数 | + | `plugin-sdk/infra-runtime` | 系统事件/心跳辅助函数 | | `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 | | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助函数 | | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和固定查找辅助函数 | - | `plugin-sdk/runtime-fetch` | 不引入代理 / guarded-fetch 导入的 dispatcher 感知型运行时 fetch | - | `plugin-sdk/response-limit-runtime` | 不依赖广泛媒体运行时入口面的有界响应体读取器 | - | `plugin-sdk/session-binding-runtime` | 不包含已配置绑定路由或配对存储的当前对话绑定状态 | - | `plugin-sdk/session-store-runtime` | 不引入广泛配置写入 / 维护导入的会话存储读取辅助函数 | - | `plugin-sdk/context-visibility-runtime` | 不引入广泛配置 / 安全导入的上下文可见性解析和补充上下文过滤 | - | `plugin-sdk/string-coerce-runtime` | 不引入 Markdown/日志的狭义原始记录 / 字符串强制转换和规范化辅助函数 | + | `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和固定查找辅助函数 | + | `plugin-sdk/runtime-fetch` | 不引入代理/受保护 fetch 导入的 dispatcher 感知运行时 fetch | + | `plugin-sdk/response-limit-runtime` | 不依赖广泛媒体运行时接口的有界响应体读取器 | + | `plugin-sdk/session-binding-runtime` | 不包含已配置绑定路由或配对存储的当前会话绑定状态 | + | `plugin-sdk/session-store-runtime` | 不引入广泛配置写入/维护导入的会话存储读取辅助函数 | + | `plugin-sdk/context-visibility-runtime` | 不引入广泛配置/安全导入的上下文可见性解析和补充上下文过滤 | + | `plugin-sdk/string-coerce-runtime` | 不引入 markdown/日志导入的精简原始记录/字符串强制转换和规范化辅助函数 | | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 | | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助函数 | - | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助函数 | - | `plugin-sdk/directory-runtime` | 基于配置的目录查询 / 去重 | + | `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助函数 | + | `plugin-sdk/directory-runtime` | 配置支持的目录查询/去重 | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - - | 子路径 | 关键导出项 | + + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/media-runtime` | 共享的媒体获取 / 转换 / 存储辅助函数，以及媒体载荷构建器 | - | `plugin-sdk/media-generation-runtime` | 共享的媒体生成故障转移辅助函数、候选项选择和缺失模型提示 | - | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出项 | - | `plugin-sdk/text-runtime` | 共享的文本 / Markdown/日志辅助函数，例如对助手可见文本剥离、Markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 | + | `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助函数以及媒体载荷构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助函数、候选项选择和缺失模型提示 | + | `plugin-sdk/media-understanding` | 媒体理解提供商类型以及面向提供商的图像/音频辅助导出 | + | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助函数，例如助手可见文本剥离、Markdown 渲染/分块/表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 | | `plugin-sdk/text-chunking` | 出站文本分块辅助函数 | - | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助函数 | - | `plugin-sdk/speech-core` | 共享的语音提供商类型、注册表、directive 和规范化辅助函数 | + | `plugin-sdk/speech` | 语音提供商类型以及面向提供商的 directive、注册表和验证辅助函数 | + | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助函数 | | `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助函数和共享 WebSocket 会话辅助函数 | | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 | | `plugin-sdk/image-generation` | 图像生成提供商类型 | - | `plugin-sdk/image-generation-core` | 共享的图像生成类型、故障转移、认证和注册表辅助函数 | - | `plugin-sdk/music-generation` | 音乐生成提供商 / 请求 / 结果类型 | - | `plugin-sdk/music-generation-core` | 共享的音乐生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | - | `plugin-sdk/video-generation` | 视频生成提供商 / 请求 / 结果类型 | - | `plugin-sdk/video-generation-core` | 共享的视频生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | + | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助函数 | + | `plugin-sdk/music-generation` | 音乐生成提供商/请求/结果类型 | + | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | + | `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 | + | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | | `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助函数 | | `plugin-sdk/webhook-path` | webhook 路径规范化辅助函数 | - | `plugin-sdk/web-media` | 共享的远程 / 本地媒体加载辅助函数 | + | `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助函数 | | `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` | - | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` | + | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - | 子路径 | 关键导出项 | + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/memory-core` | 内置 `memory-core` 辅助入口面，用于 manager/config/file/CLI 辅助函数 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时外观 | - | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出项 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商，以及通用 batch/remote 辅助函数 | - | `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` | 用于 search-manager 访问的活动 Memory 运行时外观 | - | `plugin-sdk/memory-host-status` | 面向供应商中立的别名，用于 memory host 状态辅助函数 | - | `plugin-sdk/memory-lancedb` | 内置 `memory-lancedb` 辅助入口面 | + | `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 主机密钥辅助函数 | + | `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` | 用于搜索管理器访问的活动 Memory 运行时门面 | + | `plugin-sdk/memory-host-status` | Memory 主机状态辅助函数的供应商中立别名 | + | `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 专用辅助函数 | `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 辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | ## 注册 API -`register(api)` 回调会收到一个 `OpenClawPluginApi` 对象，其中包含这些方法： +`register(api)` 回调会接收一个带有以下方法的 `OpenClawPluginApi` 对象： ### 能力注册 -| 方法 | 注册内容 | -| ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | 文本推理（LLM） | -| `api.registerAgentHarness(...)` | 实验性的低层智能体执行器 | -| `api.registerCliBackend(...)` | 本地 AI 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.registerProvider(...)` | 文本推理（LLM） | +| `api.registerAgentHarness(...)` | 实验性的低层智能体执行器 | +| `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.registerTool(tool, opts?)` | 智能体工具（必需，或 `{ optional: true }`） | -| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | +| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | ### 基础设施 -| 方法 | 注册内容 | -| ----------------------------------------------- | --------------------------------------- | -| `api.registerHook(events, handler, opts?)` | 事件 hook | -| `api.registerHttpRoute(params)` | Gateway 网关 HTTP endpoint | -| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | -| `api.registerCli(registrar, opts?)` | CLI 子命令 | -| `api.registerService(service)` | 后台服务 | -| `api.registerInteractiveHandler(registration)` | 交互式处理器 | -| `api.registerEmbeddedExtensionFactory(factory)` | Pi 嵌入式运行器扩展工厂 | -| `api.registerMemoryPromptSupplement(builder)` | 增量式 memory 相关提示词部分 | -| `api.registerMemoryCorpusSupplement(adapter)` | 增量式 memory 搜索 / 读取语料 | +| 方法 | 注册内容 | +| --------------------------------------------- | -------------------------------- | +| `api.registerHook(events, handler, opts?)` | 事件 hook | +| `api.registerHttpRoute(params)` | Gateway 网关 HTTP endpoint | +| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | +| `api.registerCli(registrar, opts?)` | CLI 子命令 | +| `api.registerService(service)` | 后台服务 | +| `api.registerInteractiveHandler(registration)` | 交互式处理器 | +| `api.registerEmbeddedExtensionFactory(factory)` | Pi 嵌入式运行器扩展工厂 | +| `api.registerMemoryPromptSupplement(builder)` | 附加型 Memory 相关提示区段 | +| `api.registerMemoryCorpusSupplement(adapter)` | 附加型 Memory 搜索/读取语料库 | 保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、 -`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用特定于插件的前缀。 +`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 +Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用 +插件专属前缀。 -当插件需要在 OpenClaw 嵌入式运行期间使用 Pi 原生事件时序时，使用 `api.registerEmbeddedExtensionFactory(...)`，例如必须在最终工具结果消息发出之前完成的异步 `tool_result` 重写。如今这是一个内置插件入口面：只有内置插件可以注册它，并且它们必须在 `openclaw.plugin.json` 中声明 `contracts.embeddedExtensionFactories: ["pi"]`。对于不需要该更低层入口面的所有场景，请继续使用普通 OpenClaw 插件 hook。 +当插件在 OpenClaw 嵌入式运行期间需要 Pi 原生事件时序时，使用 `api.registerEmbeddedExtensionFactory(...)`， +例如那些必须在最终工具结果消息发出之前发生的异步 `tool_result` +重写。当前这是一个内置插件接口：只有内置插件可以注册它，并且 +它们必须在 `openclaw.plugin.json` 中声明 `contracts.embeddedExtensionFactories: ["pi"]`。 +对于不需要该更低层接口的所有场景，请继续使用普通的 OpenClaw 插件 hook。 ### CLI 注册元数据 `api.registerCli(registrar, opts?)` 接受两类顶层元数据： -- `commands`：由该 registrar 拥有的显式命令根 -- `descriptors`：用于根 CLI 帮助、路由和懒加载插件 CLI 注册的解析时命令描述符 +- `commands`：由注册器拥有的显式命令根 +- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析时命令描述符 -如果你希望某个插件命令在常规根 CLI 路径中保持懒加载，请提供 `descriptors`，覆盖该 registrar 暴露的每个顶层命令根。 +如果你希望插件命令在普通根 CLI 路径中保持延迟加载，请提供 `descriptors`， +覆盖该注册器暴露的每个顶层命令根。 ```typescript api.registerCli( @@ -368,7 +382,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "管理 Matrix 账户、验证、设备和配置文件状态", + description: "管理 Matrix 账户、验证、设备和 profile 状态", hasSubcommands: true, }, ], @@ -376,77 +390,85 @@ api.registerCli( ); ``` -仅在你不需要懒加载根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍然受支持，但它不会安装由 descriptor 支持、用于解析时懒加载的占位符。 +仅在你不需要延迟根 CLI 注册时才单独使用 `commands`。 +这种预加载兼容路径仍受支持，但它不会安装由描述符支持的占位符来实现解析时延迟加载。 ### CLI 后端注册 -`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。 +`api.registerCliBackend(...)` 允许插件拥有本地 +AI CLI 后端（例如 `codex-cli`）的默认配置。 - 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。 - 后端 `config` 使用与 `agents.defaults.cliBackends.` 相同的结构。 -- 用户配置仍然优先生效。OpenClaw 会在运行 CLI 之前，将 `agents.defaults.cliBackends.` 合并到插件默认值之上。 -- 当后端在合并后需要兼容性重写时，使用 `normalizeConfig`（例如规范化旧版 flag 结构）。 +- 用户配置仍然优先生效。OpenClaw 会在运行 CLI 前，将 `agents.defaults.cliBackends.` 合并到 + 插件默认值之上。 +- 当后端在合并后需要进行兼容性重写时，使用 `normalizeConfig` + （例如规范化旧版 flag 结构）。 ### 独占槽位 -| 方法 | 注册内容 | -| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | 上下文引擎（同一时间仅一个处于活动状态）。`assemble()` 回调会收到 `availableTools` 和 `citationsMode`，因此该引擎可以定制提示词补充内容。 | -| `api.registerMemoryCapability(capability)` | 统一 Memory 能力 | -| `api.registerMemoryPromptSection(builder)` | Memory 提示词部分构建器 | -| `api.registerMemoryFlushPlan(resolver)` | Memory flush plan 解析器 | -| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 | +| 方法 | 注册内容 | +| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个处于激活状态）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便该引擎定制提示附加内容。 | +| `api.registerMemoryCapability(capability)` | 统一 Memory 能力 | +| `api.registerMemoryPromptSection(builder)` | Memory 提示区段构建器 | +| `api.registerMemoryFlushPlan(resolver)` | Memory flush plan 解析器 | +| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 | -### Memory embedding 适配器 +### Memory 嵌入适配器 -| 方法 | 注册内容 | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | 当前活动插件的 Memory embedding 适配器 | +| 方法 | 注册内容 | +| -------------------------------------------- | -------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | 当前活动插件的 Memory 嵌入适配器 | -- `registerMemoryCapability` 是首选的独占 memory 插件 API。 -- `registerMemoryCapability` 也可以公开 `publicArtifacts.listArtifacts(...)`，这样配套插件就可以通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的 memory 工件，而不必深入访问某个 memory 插件的私有布局。 +- `registerMemoryCapability` 是首选的独占式 Memory 插件 API。 +- `registerMemoryCapability` 还可以暴露 `publicArtifacts.listArtifacts(...)`， + 这样配套插件就能通过 `openclaw/plugin-sdk/memory-host-core` + 使用导出的 Memory 工件，而不必深入某个特定 Memory 插件的私有布局。 - `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 - `registerMemoryRuntime` 是兼容旧版的独占 memory 插件 API。 -- `registerMemoryEmbeddingProvider` 允许活动 memory 插件注册一个或多个 embedding 适配器 id（例如 `openai`、`gemini`，或插件自定义的 id）。 -- 用户配置，例如 `agents.defaults.memorySearch.provider` 和 - `agents.defaults.memorySearch.fallback`，会根据这些已注册的适配器 id 进行解析。 + `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.onConversationBindingResolved(handler)` | 对话绑定回调 | +| -------------------------------------------- | ---------------------------- | +| `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` 相同），而不是覆盖已有决策。 -- `message_received`：当你需要入站线程 / 主题路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给特定于渠道的额外信息。 -- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，再回退到特定于渠道的 `metadata`。 -- `gateway_start`：对于 Gateway 网关自有的启动状态，请使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()`，而不是依赖内部 `gateway:startup` hooks。 +- `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` 相同），而不是覆盖已有决定。 +- `message_received`：当你需要入站线程/话题路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的附加信息。 +- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，再回退到渠道特定的 `metadata`。 +- `gateway_start`：对于 Gateway 网关自有的启动状态，请使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()`，而不要依赖内部 `gateway:startup` hook。 ### 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` | 作用域记录器（`debug`、`info`、`warn`、`error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置前的轻量级启动/设置窗口 | +| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | ## 内部模块约定 @@ -454,8 +476,8 @@ api.registerCli( ``` my-plugin/ - api.ts # 面向外部使用者的公共导出项 - runtime-api.ts # 仅内部使用的运行时导出项 + api.ts # 供外部使用者使用的公开导出 + runtime-api.ts # 仅供内部使用的运行时导出 index.ts # 插件入口点 setup-entry.ts # 仅用于轻量设置的入口点（可选） ``` @@ -463,30 +485,38 @@ my-plugin/ 不要在生产代码中通过 `openclaw/plugin-sdk/` 导入你自己的插件。请通过 `./api.ts` 或 - `./runtime-api.ts` 路由内部导入。SDK 路径只是对外契约。 + `./runtime-api.ts` 进行内部导入。SDK 路径仅是对外契约。 -由 facade 加载的内置插件公共入口面（`api.ts`、`runtime-api.ts`、 -`index.ts`、`setup-entry.ts` 以及类似公共入口文件）现在会在 OpenClaw 已经运行时优先使用活动运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上已解析的配置文件。 +当 OpenClaw 已经运行时，由外观模式加载的内置插件公开接口（`api.ts`、`runtime-api.ts`、 +`index.ts`、`setup-entry.ts` 以及类似的公开入口文件）现在会优先使用活动运行时配置快照。 +如果运行时快照尚不存在，它们会回退到磁盘上已解析的配置文件。 -提供商插件也可以暴露一个狭义的插件本地契约 barrel，用于那些有意特定于提供商、且目前还不属于通用 SDK 子路径的辅助函数。当前内置示例：Anthropic 提供商将其 Claude 流辅助函数保留在它自己的公共 `api.ts` / `contract-api.ts` 入口面中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升到通用的 `plugin-sdk/*` 契约中。 +当某个辅助函数有意保持提供商专属，且暂时还不适合放入通用 SDK +子路径时，提供商插件也可以暴露一个精简的插件本地契约 barrel。当前内置示例：Anthropic +提供商将其 Claude 流辅助函数保留在自己的公开 `api.ts` / `contract-api.ts` +接口中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升为通用 +`plugin-sdk/*` 契约的一部分。 -其他当前内置示例： +其他当前的内置示例： -- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、默认模型辅助函数和实时提供商构建器 -- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及新手引导 / 配置辅助函数 +- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、 + 默认模型辅助函数和实时提供商构建器 +- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及 + 新手引导/配置辅助函数 扩展生产代码也应避免导入 `openclaw/plugin-sdk/`。 - 如果某个辅助函数确实需要共享，请将它提升到中立的 SDK 子路径， - 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他面向能力的入口面，而不是将两个插件耦合在一起。 + 如果某个辅助函数确实应被共享，请将其提升到中立的 SDK 子路径， + 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他 + 面向能力的接口，而不是将两个插件耦合在一起。 ## 相关内容 - [入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry` 选项 - [运行时辅助函数](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考 -- [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、manifest、配置 schema +- [设置与配置](/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) — 深入的架构和能力模型 diff --git a/docs/zh-CN/plugins/sdk-provider-plugins.md b/docs/zh-CN/plugins/sdk-provider-plugins.md index 38f6b3882..cd781dc0c 100644 --- a/docs/zh-CN/plugins/sdk-provider-plugins.md +++ b/docs/zh-CN/plugins/sdk-provider-plugins.md @@ -1,30 +1,30 @@ --- read_when: - 你正在构建一个新的模型提供商插件 - - 你想将一个兼容 OpenAI 的代理或自定义 LLM 添加到 OpenClaw 中 - - 你需要了解提供商身份验证、目录和运行时钩子 + - 你想将一个与 OpenAI 兼容的代理或自定义 LLM 添加到 OpenClaw 中 + - 你需要理解提供商认证、目录和运行时钩子 sidebarTitle: Provider Plugins summary: 为 OpenClaw 构建模型提供商插件的分步指南 title: 构建提供商插件 x-i18n: - generated_at: "2026-04-23T02:58:47Z" + generated_at: "2026-04-23T03:31:37Z" model: gpt-5.4 provider: openai - source_hash: b46f72d7f636caf4b072ce84db2af5b6e6f4c8d4b75f6ea102c948c3865353c7 + source_hash: ba14ad9c9ac35c6209b6533e50ab3a6da0ef0de2ea6a6a4e7bf69bc65d39c484 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- # 构建提供商插件 -本指南将带你构建一个提供商插件，用于向 OpenClaw 添加模型提供商（LLM）。完成后，你将拥有一个具备模型目录、API key 身份验证和动态模型解析功能的提供商。 +本指南将带你构建一个提供商插件，把一个模型提供商（LLM）添加到 OpenClaw。完成后，你将拥有一个带有模型目录、API 密钥认证和动态模型解析的提供商。 - 如果你之前从未构建过任何 OpenClaw 插件，请先阅读 [入门指南](/zh-CN/plugins/building-plugins)，了解基础包结构和清单设置。 + 如果你之前还没有构建过任何 OpenClaw 插件，请先阅读 [入门指南](/zh-CN/plugins/building-plugins)，了解基础包结构和清单设置。 - 提供商插件会将模型添加到 OpenClaw 的常规推理循环中。如果该模型必须通过一个原生智能体守护进程运行，并由它管理线程、压缩或工具事件，那么应将该提供商与一个 [agent harness](/zh-CN/plugins/sdk-agent-harness) 搭配使用，而不是把守护进程协议细节放进核心中。 + 提供商插件会将模型添加到 OpenClaw 的常规推理循环中。如果模型必须通过一个拥有线程、压缩或工具事件的原生智能体守护进程运行，请将该提供商与一个 [智能体 harness](/zh-CN/plugins/sdk-agent-harness) 搭配使用，而不是把守护进程协议细节放进核心中。 ## 演练 @@ -57,7 +57,7 @@ x-i18n: { "id": "acme-ai", "name": "Acme AI", - "description": "Acme AI model provider", + "description": "Acme AI 模型提供商", "providers": ["acme-ai"], "modelSupport": { "modelPrefixes": ["acme-"] @@ -73,12 +73,12 @@ x-i18n: "provider": "acme-ai", "method": "api-key", "choiceId": "acme-ai-api-key", - "choiceLabel": "Acme AI API key", + "choiceLabel": "Acme AI API 密钥", "groupId": "acme-ai", "groupLabel": "Acme AI", "cliFlag": "--acme-ai-api-key", "cliOption": "--acme-ai-api-key ", - "cliDescription": "Acme AI API key" + "cliDescription": "Acme AI API 密钥" } ], "configSchema": { @@ -89,7 +89,7 @@ x-i18n: ``` - 清单声明了 `providerAuthEnvVars`，这样 OpenClaw 无需加载你的插件运行时就能检测凭证。当某个提供商变体应复用另一个提供商 id 的身份验证时，可添加 `providerAuthAliases`。`modelSupport` 是可选的，它允许 OpenClaw 在运行时钩子存在之前，就根据像 `acme-large` 这样的简写模型 id 自动加载你的提供商插件。如果你在 ClawHub 上发布该提供商，那么 `package.json` 中这些 `openclaw.compat` 和 `openclaw.build` 字段是必需的。 + 该清单声明了 `providerAuthEnvVars`，这样 OpenClaw 就可以在不加载你的插件运行时的情况下检测凭证。当某个提供商变体应复用另一个提供商 ID 的认证时，添加 `providerAuthAliases`。`modelSupport` 是可选的，它让 OpenClaw 可以在运行时钩子存在之前，根据像 `acme-large` 这样的简写模型 ID 自动加载你的提供商插件。如果你要在 ClawHub 上发布该提供商，那么 `package.json` 中的这些 `openclaw.compat` 和 `openclaw.build` 字段是必需的。 @@ -165,11 +165,9 @@ x-i18n: }); ``` - 这就是一个可运行的提供商。用户现在可以执行 - `openclaw onboard --acme-ai-api-key `，并选择 - `acme-ai/acme-large` 作为他们的模型。 + 这就是一个可工作的提供商。现在用户可以运行 `openclaw onboard --acme-ai-api-key `，并选择 `acme-ai/acme-large` 作为他们的模型。 - 如果上游提供商使用的控制令牌与 OpenClaw 不同，请添加一个小型双向文本转换，而不是替换流传输路径： + 如果上游提供商使用的控制令牌与 OpenClaw 不同，请添加一个小型双向文本转换，而不是替换流路径： ```typescript api.registerTextTransforms({ @@ -186,9 +184,9 @@ x-i18n: }); ``` - `input` 会在传输前重写最终系统提示词和文本消息内容。`output` 会在 OpenClaw 解析其自身控制标记或进行渠道投递之前，重写助手文本增量和最终文本。 + `input` 会在传输前重写最终的系统提示词和文本消息内容。`output` 会在 OpenClaw 解析其自身的控制标记或进行渠道投递之前，重写助手文本增量和最终文本。 - 对于仅注册一个使用 API-key 身份验证的文本提供商，并带有单一目录支持运行时的内置提供商，优先使用更窄范围的 `defineSingleProviderPluginEntry(...)` 辅助函数： + 对于只注册一个带有 API 密钥认证和单个基于目录运行时的文本提供商的内置提供商，优先使用更窄的 `defineSingleProviderPluginEntry(...)` 辅助函数： ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -228,20 +226,16 @@ x-i18n: }); ``` - `buildProvider` 是实时目录路径，当 OpenClaw 能解析真实的提供商身份验证时会使用它。它可以执行提供商特定的发现逻辑。仅在需要显示离线条目且这些内容在身份验证配置前即可安全展示时，才使用 `buildStaticProvider`；它不得需要凭证，也不得发起网络请求。OpenClaw 当前的 `models list --all` 显示仅对内置提供商插件执行静态目录，并且会使用空配置、空环境，以及无智能体/工作区路径的上下文。 + `buildProvider` 是 OpenClaw 能够解析真实提供商认证时所使用的实时目录路径。它可以执行提供商特定的发现逻辑。只有在离线条目可以在认证配置之前安全显示时，才使用 `buildStaticProvider`；它不能要求凭证，也不能发起网络请求。OpenClaw 的 `models list --all` 显示当前只会对内置提供商插件执行静态目录，并使用空配置、空环境以及无智能体/工作区路径。 - 如果你的身份验证流程在新手引导期间还需要修补 `models.providers.*`、别名以及智能体默认模型，请使用 `openclaw/plugin-sdk/provider-onboard` 中的预设辅助函数。最窄范围的辅助函数是 - `createDefaultModelPresetAppliers(...)`、 - `createDefaultModelsPresetAppliers(...)` 和 - `createModelCatalogPresetAppliers(...)`。 + 如果你的认证流程还需要在新手引导期间修补 `models.providers.*`、别名以及智能体默认模型，请使用 `openclaw/plugin-sdk/provider-onboard` 中的预设辅助函数。最窄的辅助函数是 `createDefaultModelPresetAppliers(...)`、`createDefaultModelsPresetAppliers(...)` 和 `createModelCatalogPresetAppliers(...)`。 - 当某个提供商的原生端点在常规 `openai-completions` 传输上支持流式 usage block 时，优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 id 检查。`supportsNativeStreamingUsageCompat(...)` 和 - `applyProviderNativeStreamingUsageCompat(...)` 会根据端点能力映射检测支持情况，因此即使插件使用的是自定义提供商 id，原生 Moonshot/DashScope 风格端点仍然可以选择启用。 + 当某个提供商的原生端点在常规 `openai-completions` 传输上支持流式 usage 块时，优先使用 `openclaw/plugin-sdk/provider-catalog-shared` 中的共享目录辅助函数，而不是硬编码提供商 ID 检查。`supportsNativeStreamingUsageCompat(...)` 和 `applyProviderNativeStreamingUsageCompat(...)` 会从端点能力映射中检测支持情况，因此即使插件使用的是自定义提供商 ID，原生 Moonshot/DashScope 风格的端点仍然可以选择启用。 - 如果你的提供商接受任意模型 id（例如代理或路由器），请添加 `resolveDynamicModel`： + 如果你的提供商接受任意模型 ID（比如代理或路由器），请添加 `resolveDynamicModel`： ```typescript api.registerProvider({ @@ -262,14 +256,14 @@ x-i18n: }); ``` - 如果解析需要发起网络调用，请使用 `prepareDynamicModel` 进行异步预热——在它完成后，`resolveDynamicModel` 会再次运行。 + 如果解析需要网络调用，请使用 `prepareDynamicModel` 进行异步预热——`resolveDynamicModel` 会在其完成后再次运行。 - + 大多数提供商只需要 `catalog` + `resolveDynamicModel`。随着你的提供商需求增加，再逐步添加钩子。 - 共享辅助构建器现在已经覆盖最常见的 replay/tool-compat 系列，因此插件通常不需要逐个手动连接每一个钩子： + 共享辅助构建器现在已经覆盖最常见的回放/工具兼容性家族，因此插件通常不需要再手动逐个连接每个钩子： ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -289,15 +283,15 @@ x-i18n: }); ``` - 当前可用的 replay 系列： + 当前可用的回放家族： - | 系列 | 它会接入的内容 | + | 家族 | 它会连接的内容 | | --- | --- | - | `openai-compatible` | 适用于兼容 OpenAI 传输的共享 OpenAI 风格 replay 策略，包括 tool-call-id 清洗、assistant-first 顺序修复，以及在传输需要时进行通用 Gemini turn 验证 | - | `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知 replay 策略，因此 Anthropic-message 传输仅会在解析出的模型确实是 Claude id 时，才启用 Claude 特定的 thinking-block 清理 | - | `google-gemini` | 原生 Gemini replay 策略，外加 bootstrap replay 清洗和带标签的 reasoning-output 模式 | - | `passthrough-gemini` | 适用于通过兼容 OpenAI 的代理传输运行的 Gemini 模型的 Gemini thought-signature 清洗；不会启用原生 Gemini replay 验证或 bootstrap 重写 | - | `hybrid-anthropic-openai` | 适用于在同一个插件中混合 Anthropic-message 和兼容 OpenAI 模型表面的提供商的混合策略；可选的仅 Claude thinking-block 丢弃逻辑仍然限定在 Anthropic 一侧 | + | `openai-compatible` | 面向与 OpenAI 兼容传输的共享 OpenAI 风格回放策略，包括工具调用 ID 清理、assistant-first 顺序修复，以及传输需要时的通用 Gemini 轮次校验 | + | `anthropic-by-model` | 按 `modelId` 选择的 Claude 感知回放策略，因此 Anthropic-message 传输只有在已解析模型实际是 Claude ID 时，才会获得 Claude 特定的思考块清理 | + | `google-gemini` | 原生 Gemini 回放策略，加上 bootstrap 回放清理和带标签的推理输出模式 | + | `passthrough-gemini` | 面向通过与 OpenAI 兼容的代理传输运行的 Gemini 模型的 Gemini thought-signature 清理；不会启用原生 Gemini 回放校验或 bootstrap 重写 | + | `hybrid-anthropic-openai` | 面向在一个插件中混合 Anthropic-message 和与 OpenAI 兼容模型表面的提供商的混合策略；可选的仅 Claude 思考块丢弃仍然仅作用于 Anthropic 一侧 | 真实的内置示例： @@ -307,17 +301,17 @@ x-i18n: - `minimax`：`hybrid-anthropic-openai` - `moonshot`、`ollama`、`xai` 和 `zai`：`openai-compatible` - 当前可用的 stream 系列： + 当前可用的流式传输家族： - | 系列 | 它会接入的内容 | + | 家族 | 它会连接的内容 | | --- | --- | - | `google-thinking` | 在共享流路径上进行 Gemini thinking 负载归一化 | - | `kilocode-thinking` | 在共享代理流路径上提供 Kilo reasoning 包装器，其中 `kilo/auto` 和不受支持的代理 reasoning id 会跳过注入的 thinking | - | `moonshot-thinking` | 根据配置和 `/think` 级别进行 Moonshot 二进制 native-thinking 负载映射 | - | `minimax-fast-mode` | 在共享流路径上进行 MiniMax fast-mode 模型重写 | - | `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归因头、`/fast`/`serviceTier`、文本详细程度、原生 Codex web 搜索、reasoning-compat 负载整形，以及 Responses 上下文管理 | - | `openrouter-thinking` | 面向代理路由的 OpenRouter reasoning 包装器，并集中处理不支持模型/`auto` 的跳过逻辑 | - | `tool-stream-default-on` | 对于像 Z.AI 这样希望默认启用工具流式传输，除非显式禁用的提供商，提供默认开启的 `tool_stream` 包装器 | + | `google-thinking` | 共享流路径上的 Gemini thinking 负载规范化 | + | `kilocode-thinking` | 共享代理流路径上的 Kilo 推理包装器，其中 `kilo/auto` 和不受支持的代理推理 ID 会跳过注入的 thinking | + | `moonshot-thinking` | 根据配置和 `/think` 级别进行 Moonshot 二进制原生 thinking 负载映射 | + | `minimax-fast-mode` | 共享流路径上的 MiniMax fast-mode 模型重写 | + | `openai-responses-defaults` | 共享的原生 OpenAI/Codex Responses 包装器：归因请求头、`/fast`/`serviceTier`、文本详细程度、原生 Codex web search、reasoning 兼容负载整形，以及 Responses 上下文管理 | + | `openrouter-thinking` | 面向代理路由的 OpenRouter 推理包装器，集中处理不受支持模型/`auto` 跳过逻辑 | + | `tool-stream-default-on` | 面向像 Z.AI 这样希望默认启用工具流式传输、除非显式禁用的提供商的默认开启 `tool_stream` 包装器 | 真实的内置示例： @@ -329,70 +323,55 @@ x-i18n: - `openrouter`：`openrouter-thinking` - `zai`：`tool-stream-default-on` - `openclaw/plugin-sdk/provider-model-shared` 还会导出 replay-family - 枚举，以及这些系列所基于的共享辅助函数。常见公共导出包括： + `openclaw/plugin-sdk/provider-model-shared` 还导出了 replay-family 枚举，以及这些家族所基于的共享辅助函数。常见的公共导出包括： - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` - - 共享 replay 构建器，例如 `buildOpenAICompatibleReplayPolicy(...)`、 + - 共享回放构建器，例如 `buildOpenAICompatibleReplayPolicy(...)`、 `buildAnthropicReplayPolicyForModel(...)`、 `buildGoogleGeminiReplayPolicy(...)` 和 `buildHybridAnthropicOrOpenAIReplayPolicy(...)` - - Gemini replay 辅助函数，例如 `sanitizeGoogleGeminiReplayHistory(...)` + - Gemini 回放辅助函数，例如 `sanitizeGoogleGeminiReplayHistory(...)` 和 `resolveTaggedReasoningOutputMode()` - 端点/模型辅助函数，例如 `resolveProviderEndpoint(...)`、 `normalizeProviderId(...)`、`normalizeGooglePreviewModelId(...)` 和 `normalizeNativeXaiModelId(...)` - `openclaw/plugin-sdk/provider-stream` 同时公开 family builder - 以及这些系列复用的公共包装辅助函数。常见公共导出 - 包括： + `openclaw/plugin-sdk/provider-stream` 同时暴露了家族构建器和这些家族复用的公共包装器辅助函数。常见的公共导出包括： - `ProviderStreamFamily` - `buildProviderStreamFamilyHooks(...)` - `composeProviderStreamWrappers(...)` - - 共享 OpenAI/Codex 包装器，例如 + - 共享的 OpenAI/Codex 包装器，例如 `createOpenAIAttributionHeadersWrapper(...)`、 `createOpenAIFastModeWrapper(...)`、 `createOpenAIServiceTierWrapper(...)`、 `createOpenAIResponsesContextManagementWrapper(...)` 和 `createCodexNativeWebSearchWrapper(...)` - - 共享代理/提供商包装器，例如 `createOpenRouterWrapper(...)`、 + - 共享的代理/提供商包装器，例如 `createOpenRouterWrapper(...)`、 `createToolStreamWrapper(...)` 和 `createMinimaxFastModeWrapper(...)` - 有些 stream 辅助函数会有意保留为提供商本地实现。当前的内置 - 示例：`@openclaw/anthropic-provider` 导出 - `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、 - `resolveAnthropicFastMode`、`resolveAnthropicServiceTier`，以及来自其公共 `api.ts` / - `contract-api.ts` 接缝的底层 Anthropic 包装器构建器。这些辅助函数之所以仍保持为 Anthropic 专属，是因为 - 它们还编码了 Claude OAuth beta 处理和 `context1m` 门控。 + 有些流式传输辅助函数会有意保留为提供商本地实现。当前的内置示例：`@openclaw/anthropic-provider` 通过其公共 `api.ts` / `contract-api.ts` 接缝导出 `wrapAnthropicProviderStream`、`resolveAnthropicBetas`、`resolveAnthropicFastMode`、`resolveAnthropicServiceTier`，以及更底层的 Anthropic 包装器构建器。这些辅助函数仍然保持为 Anthropic 特有，因为它们还编码了 Claude OAuth beta 处理和 `context1m` 门控。 - 其他内置提供商也会在行为无法在各个系列之间干净共享时，将传输特定包装器保留为本地实现。当前示例：内置 xAI 插件将原生 xAI Responses 整形保留在其自己的 - `wrapStreamFn` 中，包括 `/fast` 别名重写、默认 `tool_stream`、 - 不支持的 strict-tool 清理，以及 xAI 特定的 reasoning-payload - 移除。 + 其他内置提供商在行为无法干净地跨家族共享时，也会将传输特定包装器保留为本地实现。当前示例：内置 xAI 插件将原生 xAI Responses 整形保留在它自己的 `wrapStreamFn` 中，其中包括 `/fast` 别名重写、默认 `tool_stream`、不受支持的 strict-tool 清理，以及 xAI 特定的 reasoning 负载移除。 - `openclaw/plugin-sdk/provider-tools` 当前公开一个共享 - tool-schema 系列，以及共享 schema/compat 辅助函数： + `openclaw/plugin-sdk/provider-tools` 当前暴露了一个共享工具模式家族，以及共享的 schema/兼容性辅助函数： - - `ProviderToolCompatFamily` 记录了当前共享系列清单。 - - `buildProviderToolCompatFamilyHooks("gemini")` 为需要 Gemini 安全工具 schema 的提供商接入 Gemini schema - 清理 + 诊断。 - - `normalizeGeminiToolSchemas(...)` 和 `inspectGeminiToolSchemas(...)` - 是底层公共 Gemini schema 辅助函数。 - - `resolveXaiModelCompatPatch()` 返回内置 xAI compat 补丁： - `toolSchemaProfile: "xai"`、不支持的 schema 关键字、原生 + - `ProviderToolCompatFamily` 记录了当前共享家族清单。 + - `buildProviderToolCompatFamilyHooks("gemini")` 为需要 Gemini 安全工具 schema 的提供商连接 Gemini schema 清理 + 诊断。 + - `normalizeGeminiToolSchemas(...)` 和 `inspectGeminiToolSchemas(...)` 是底层公共 Gemini schema 辅助函数。 + - `resolveXaiModelCompatPatch()` 返回内置的 xAI 兼容性补丁： + `toolSchemaProfile: "xai"`、不受支持的 schema 关键字、原生 `web_search` 支持，以及 HTML 实体工具调用参数解码。 - - `applyXaiModelCompat(model)` 会在解析后的模型到达运行器之前，对其应用相同的 xAI compat 补丁。 + - `applyXaiModelCompat(model)` 会在已解析模型到达运行器之前，将同样的 xAI 兼容性补丁应用到该模型上。 - 真实的内置示例：xAI 插件使用 `normalizeResolvedModel` 加上 - `contributeResolvedModelCompat`，以保持该 compat 元数据由提供商拥有，而不是在核心中硬编码 xAI 规则。 + 真实的内置示例：xAI 插件使用 `normalizeResolvedModel` 加上 `contributeResolvedModelCompat`，从而让这类兼容性元数据由提供商自身负责，而不是在核心中硬编码 xAI 规则。 - 同样的包根模式也支持其他内置提供商： + 同样的包根模式也支撑了其他内置提供商： - `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、 - 默认模型辅助函数和实时提供商构建器 - - `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器 + 默认模型辅助函数，以及实时提供商构建器 + - `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器， 以及新手引导/配置辅助函数 @@ -411,7 +390,7 @@ x-i18n: ``` - 对于需要自定义请求头或修改请求体的提供商： + 对于需要自定义请求头或请求体修改的提供商： ```typescript // wrapStreamFn returns a StreamFn derived from ctx.streamFn @@ -429,7 +408,7 @@ x-i18n: ``` - 对于需要在通用 HTTP 或 WebSocket 传输上附加原生请求/会话头或元数据的提供商： + 对于需要在通用 HTTP 或 WebSocket 传输中使用原生请求/会话请求头或元数据的提供商： ```typescript resolveTransportTurnState: (ctx) => ({ @@ -450,7 +429,7 @@ x-i18n: ``` - 对于公开用量/计费数据的提供商： + 对于暴露用量/计费数据的提供商： ```typescript resolveUsageAuth: async (ctx) => { @@ -465,84 +444,75 @@ x-i18n: - OpenClaw 会按以下顺序调用钩子。大多数提供商只会用到 2 到 3 个： + OpenClaw 按以下顺序调用钩子。大多数提供商只会使用其中 2 到 3 个： | # | Hook | 何时使用 | | --- | --- | --- | - | 1 | `catalog` | 模型目录或 base URL 默认值 | - | 2 | `applyConfigDefaults` | 在配置具体化期间应用由提供商拥有的全局默认值 | - | 3 | `normalizeModelId` | 在查找前清理旧版/预览版模型 id 别名 | - | 4 | `normalizeTransport` | 在通用模型组装前清理提供商系列的 `api` / `baseUrl` | - | 5 | `normalizeConfig` | 归一化 `models.providers.` 配置 | - | 6 | `applyNativeStreamingUsageCompat` | 针对配置提供商的原生流式 usage compat 重写 | - | 7 | `resolveConfigApiKey` | 由提供商拥有的 env 标记身份验证解析 | - | 8 | `resolveSyntheticAuth` | 本地/自托管或由配置支持的 synthetic 身份验证 | - | 9 | `shouldDeferSyntheticProfileAuth` | 将 synthetic 存储配置文件占位符降级到 env/config 身份验证之后 | - | 10 | `resolveDynamicModel` | 接受任意上游模型 id | - | 11 | `prepareDynamicModel` | 在解析前异步获取元数据 | - | 12 | `normalizeResolvedModel` | 在运行器之前进行传输重写 | + | 1 | `catalog` | 模型目录或基础 URL 默认值 | + | 2 | `applyConfigDefaults` | 配置具体化期间由提供商负责的全局默认值 | + | 3 | `normalizeModelId` | 查找前对旧版/预览模型 ID 别名进行清理 | + | 4 | `normalizeTransport` | 通用模型组装前对提供商家族 `api` / `baseUrl` 进行清理 | + | 5 | `normalizeConfig` | 规范化 `models.providers.` 配置 | + | 6 | `applyNativeStreamingUsageCompat` | 针对配置提供商的原生流式 usage 兼容重写 | + | 7 | `resolveConfigApiKey` | 由提供商负责的环境标记认证解析 | + | 8 | `resolveSyntheticAuth` | 本地/自托管或由配置支持的合成认证 | + | 9 | `shouldDeferSyntheticProfileAuth` | 将合成存储配置文件占位符置于环境/配置认证之后 | + | 10 | `resolveDynamicModel` | 接受任意上游模型 ID | + | 11 | `prepareDynamicModel` | 解析前异步获取元数据 | + | 12 | `normalizeResolvedModel` | 运行器前的传输重写 | 运行时回退说明： - - `normalizeConfig` 会先检查匹配的提供商，然后再检查其他 - 具备 hook 能力的提供商插件，直到某个插件实际修改配置。 - 如果没有提供商 hook 重写受支持的 Google 系列配置项，那么 - 内置 Google 配置归一化器仍会生效。 - - `resolveConfigApiKey` 在提供商暴露该 hook 时会使用它。内置 - `amazon-bedrock` 路径这里还有一个内建 AWS env-marker 解析器， - 即使 Bedrock 运行时身份验证本身仍然使用 AWS SDK 默认 - 链。 - | 13 | `contributeResolvedModelCompat` | 为通过另一种兼容传输访问的供应商模型提供 compat 标记 | + - `normalizeConfig` 会先检查匹配的提供商，然后再检查其他具备钩子能力的提供商插件，直到某个插件实际修改配置为止。 + 如果没有任何提供商钩子重写受支持的 Google 家族配置项，仍会应用内置的 Google 配置规范化逻辑。 + - `resolveConfigApiKey` 在暴露时会使用提供商钩子。内置的 + `amazon-bedrock` 路径在这里也有一个内建的 AWS 环境标记解析器， + 尽管 Bedrock 运行时认证本身仍然使用 AWS SDK 默认链。 + | 13 | `contributeResolvedModelCompat` | 面向通过另一种兼容传输暴露的厂商模型的兼容性标志 | | 14 | `capabilities` | 旧版静态能力包；仅用于兼容性 | - | 15 | `normalizeToolSchemas` | 在注册前执行由提供商拥有的工具 schema 清理 | - | 16 | `inspectToolSchemas` | 由提供商拥有的工具 schema 诊断 | - | 17 | `resolveReasoningOutputMode` | 带标签与原生 reasoning-output 合约 | + | 15 | `normalizeToolSchemas` | 注册前由提供商负责的工具 schema 清理 | + | 16 | `inspectToolSchemas` | 由提供商负责的工具 schema 诊断 | + | 17 | `resolveReasoningOutputMode` | 带标签与原生 reasoning-output 契约 | | 18 | `prepareExtraParams` | 默认请求参数 | | 19 | `createStreamFn` | 完全自定义的 StreamFn 传输 | - | 20 | `wrapStreamFn` | 在常规流路径上包装自定义请求头/请求体 | + | 20 | `wrapStreamFn` | 常规流路径上的自定义请求头/请求体包装器 | | 21 | `resolveTransportTurnState` | 原生逐轮请求头/元数据 | - | 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话头/冷却时间 | + | 22 | `resolveWebSocketSessionPolicy` | 原生 WS 会话请求头/冷却策略 | | 23 | `formatApiKey` | 自定义运行时令牌形态 | | 24 | `refreshOAuth` | 自定义 OAuth 刷新 | - | 25 | `buildAuthDoctorHint` | 身份验证修复指导 | - | 26 | `matchesContextOverflowError` | 由提供商拥有的上下文溢出检测 | - | 27 | `classifyFailoverReason` | 由提供商拥有的限流/过载分类 | - | 28 | `isCacheTtlEligible` | 提示词缓存 TTL 门控 | - | 29 | `buildMissingAuthMessage` | 自定义缺失身份验证提示 | + | 25 | `buildAuthDoctorHint` | 认证修复指引 | + | 26 | `matchesContextOverflowError` | 由提供商负责的上下文溢出检测 | + | 27 | `classifyFailoverReason` | 由提供商负责的限流/过载分类 | + | 28 | `isCacheTtlEligible` | 提示缓存 TTL 门控 | + | 29 | `buildMissingAuthMessage` | 自定义缺失认证提示 | | 30 | `suppressBuiltInModel` | 隐藏过时的上游条目 | - | 31 | `augmentModelCatalog` | synthetic 前向兼容条目 | - | 32 | `resolveThinkingProfile` | 针对特定模型的 `/think` 选项集 | + | 31 | `augmentModelCatalog` | 合成的前向兼容条目 | + | 32 | `resolveThinkingProfile` | 模型特定的 `/think` 选项集 | | 33 | `isBinaryThinking` | 二进制 thinking 开/关兼容性 | - | 34 | `supportsXHighThinking` | `xhigh` reasoning 支持兼容性 | + | 34 | `supportsXHighThinking` | `xhigh` 推理支持兼容性 | | 35 | `resolveDefaultThinkingLevel` | 默认 `/think` 策略兼容性 | - | 36 | `isModernModelRef` | 实时/smoke 模型匹配 | - | 37 | `prepareRuntimeAuth` | 在推理前进行令牌交换 | + | 36 | `isModernModelRef` | 实时/冒烟模型匹配 | + | 37 | `prepareRuntimeAuth` | 推理前令牌交换 | | 38 | `resolveUsageAuth` | 自定义用量凭证解析 | | 39 | `fetchUsageSnapshot` | 自定义用量端点 | - | 40 | `createEmbeddingProvider` | 用于记忆/搜索的由提供商拥有的嵌入适配器 | - | 41 | `buildReplayPolicy` | 自定义 transcript replay/压缩策略 | - | 42 | `sanitizeReplayHistory` | 在通用清理之后执行提供商特定的 replay 重写 | - | 43 | `validateReplayTurns` | 在嵌入式运行器之前进行严格 replay-turn 验证 | + | 40 | `createEmbeddingProvider` | 面向 memory/search 的提供商自有嵌入适配器 | + | 41 | `buildReplayPolicy` | 自定义转录回放/压缩策略 | + | 42 | `sanitizeReplayHistory` | 通用清理后的提供商特定回放重写 | + | 43 | `validateReplayTurns` | 嵌入式运行器前的严格回放轮次校验 | | 44 | `onModelSelected` | 选择模型后的回调（例如遥测） | - 提示词调优说明： + Prompt 调优说明： - - `resolveSystemPromptContribution` 允许提供商为某个模型系列注入具备缓存感知能力的 - system-prompt 指导。对于属于单个提供商/模型 - 系列且应保留 stable/dynamic 缓存拆分的行为，优先使用它，而不是 - `before_prompt_build`。 + - `resolveSystemPromptContribution` 允许提供商为某个模型家族注入具备缓存感知能力的 system prompt 指引。当该行为属于某一个提供商/模型家族，并且应保留稳定/动态缓存拆分时，优先使用它，而不是 `before_prompt_build`。 - 如需详细说明和真实示例，请参阅 - [Internals: Provider Runtime Hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。 + 如需详细说明和真实示例，请参阅 [内部机制：提供商运行时钩子](/zh-CN/plugins/architecture#provider-runtime-hooks)。 - 提供商插件除了文本推理之外，还可以注册语音、实时转录、实时 - 语音、媒体理解、图像生成、视频生成、网页抓取 - 和 web 搜索： + 提供商插件除了文本推理外，还可以注册语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和网页搜索： ```typescript register(api) { @@ -647,7 +617,7 @@ x-i18n: api.registerWebFetchProvider({ id: "acme-ai-fetch", label: "Acme Fetch", - hint: "通过 Acme 的渲染后端抓取页面。", + hint: "Fetch pages through Acme's rendering backend.", envVars: ["ACME_FETCH_API_KEY"], placeholder: "acme-...", signupUrl: "https://acme.example.com/fetch", @@ -658,7 +628,7 @@ x-i18n: acme.apiKey = value; }, createTool: () => ({ - description: "通过 Acme Fetch 抓取页面。", + description: "Fetch a page through Acme Fetch.", parameters: {}, execute: async (args) => ({ content: [] }), }), @@ -672,19 +642,15 @@ x-i18n: } ``` - OpenClaw 会将其归类为 **hybrid-capability** 插件。这是公司插件（每个供应商一个插件）的推荐模式。请参阅 - [Internals: Capability Ownership](/zh-CN/plugins/architecture#capability-ownership-model)。 + OpenClaw 将其归类为 **hybrid-capability** 插件。这是公司级插件（每个厂商一个插件）的推荐模式。参见 [内部机制：能力归属](/zh-CN/plugins/architecture#capability-ownership-model)。 - 对于视频生成，优先使用上面展示的模式感知能力结构： - `generate`、`imageToVideo` 和 `videoToVideo`。像 - `maxInputImages`、`maxInputVideos` 和 `maxDurationSeconds` 这样的扁平聚合字段 - 不足以清晰表达变换模式支持或已禁用模式。 + 对于视频生成，优先使用上面展示的具备模式感知的能力结构：`generate`、`imageToVideo` 和 `videoToVideo`。像 `maxInputImages`、`maxInputVideos` 和 `maxDurationSeconds` 这样的扁平聚合字段，不足以清晰地声明转换模式支持或已禁用模式。 - 音乐生成提供商也应遵循相同模式： - `generate` 用于仅提示词生成，`edit` 用于基于参考图像的 - 生成。像 `maxInputImages`、 - `supportsLyrics` 和 `supportsFormat` 这样的扁平聚合字段 - 不足以表达 edit 支持；明确的 `generate` / `edit` 块才是预期合约。 + 对于流式 STT 提供商，优先使用共享的 WebSocket 辅助函数。它可以让代理捕获、重连退避、关闭时刷新、ready 握手、音频排队和关闭事件诊断在各提供商之间保持一致，同时让提供商代码只负责上游事件映射。 + + 以 POST multipart 音频方式工作的批量 STT 提供商，应结合提供商 HTTP 请求辅助函数，使用 `openclaw/plugin-sdk/provider-http` 中的 `buildAudioTranscriptionFormData(...)`。该表单辅助函数会规范化上传文件名，包括需要使用 M4A 风格文件名才能兼容转录 API 的 AAC 上传。 + + 音乐生成提供商也应遵循相同模式：`generate` 用于仅提示词生成，`edit` 用于基于参考图像的生成。像 `maxInputImages`、`supportsLyrics` 和 `supportsFormat` 这样的扁平聚合字段，不足以声明 edit 支持；显式的 `generate` / `edit` 块才是预期契约。 @@ -732,36 +698,34 @@ clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -这里不要使用旧版仅限 Skills 的发布别名；插件包应使用 -`clawhub package publish`。 +这里不要使用旧版的仅 Skills 发布别名；插件包应使用 `clawhub package publish`。 ## 文件结构 ``` /acme-ai/ -├── package.json # openclaw.providers metadata -├── openclaw.plugin.json # Manifest with provider auth metadata +├── package.json # openclaw.providers 元数据 +├── openclaw.plugin.json # 带有提供商认证元数据的清单 ├── index.ts # definePluginEntry + registerProvider └── src/ - ├── provider.test.ts # Tests - └── usage.ts # Usage endpoint (optional) + ├── provider.test.ts # 测试 + └── usage.ts # 用量端点（可选） ``` ## 目录顺序参考 -`catalog.order` 用于控制你的目录相对于内置 -提供商的合并时机： +`catalog.order` 控制你的目录相对于内置提供商的合并时机： -| 顺序 | 时机 | 使用场景 | -| --------- | ------------- | ----------------------------------------------- | -| `simple` | 第一轮 | 纯 API-key 提供商 | -| `profile` | 在 simple 之后 | 受 auth profiles 限制的提供商 | -| `paired` | 在 profile 之后 | 合成多个相关条目 | -| `late` | 最后一轮 | 覆盖现有提供商（冲突时获胜） | +| Order | 时机 | 用例 | +| --------- | ------------- | ------------------------------------------- | +| `simple` | 第一轮 | 纯 API 密钥提供商 | +| `profile` | 在 simple 之后 | 受认证配置文件控制的提供商 | +| `paired` | 在 profile 之后 | 合成多个相关条目 | +| `late` | 最后一轮 | 覆盖现有提供商（冲突时获胜） | ## 后续步骤 -- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 如果你的插件还提供一个渠道 -- [SDK 运行时](/zh-CN/plugins/sdk-runtime) — `api.runtime` 辅助函数（TTS、搜索、subagent） -- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 -- [Plugin Internals](/zh-CN/plugins/architecture#provider-runtime-hooks) — hook 细节和内置示例 +- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) —— 如果你的插件也提供一个渠道 +- [SDK 运行时](/zh-CN/plugins/sdk-runtime) —— `api.runtime` 辅助函数（TTS、搜索、子智能体） +- [SDK 概览](/zh-CN/plugins/sdk-overview) —— 完整的子路径导入参考 +- [插件内部机制](/zh-CN/plugins/architecture#provider-runtime-hooks) —— 钩子细节和内置示例 diff --git a/docs/zh-CN/plugins/voice-call.md b/docs/zh-CN/plugins/voice-call.md index 11bcbb3f5..a0ee6c1a6 100644 --- a/docs/zh-CN/plugins/voice-call.md +++ b/docs/zh-CN/plugins/voice-call.md @@ -2,40 +2,40 @@ read_when: - 你想从 OpenClaw 发起一个呼出语音通话 - 你正在配置或开发 voice-call 插件 -summary: Voice Call 插件：通过 Twilio/Telnyx/Plivo 进行呼出与呼入通话（插件安装 + 配置 + CLI） +summary: Voice Call 插件：通过 Twilio/Telnyx/Plivo 进行呼出 + 呼入通话（插件安装 + 配置 + CLI） title: Voice Call 插件 x-i18n: - generated_at: "2026-04-23T00:39:54Z" + generated_at: "2026-04-23T03:31:37Z" model: gpt-5.4 provider: openai - source_hash: 4106c156a52e06047d31a149b2944f50b38c41e5db664efa1f2a96b2b20fa88d + source_hash: 2fbfe1aba459dd4fbe1b5c100430ff8cbe8987d7d34b875d115afcaee6e56412 source_path: plugins/voice-call.md workflow: 15 --- # Voice Call（插件） -通过插件为 OpenClaw 提供语音通话。支持呼出通知以及带有呼入策略的多轮对话。 +通过插件为 OpenClaw 提供语音通话。支持呼出通知，以及带有呼入策略的多轮对话。 当前提供商： - `twilio`（Programmable Voice + Media Streams） - `telnyx`（Call Control v2） - `plivo`（Voice API + XML transfer + GetInput speech） -- `mock`（开发/无网络） +- `mock`（开发用 / 无网络） -快速理解模型： +快速心智模型： - 安装插件 - 重启 Gateway 网关 -- 在 `plugins.entries.voice-call.config` 下进行配置 +- 在 `plugins.entries.voice-call.config` 下配置 - 使用 `openclaw voicecall ...` 或 `voice_call` 工具 ## 运行位置（本地 vs 远程） -Voice Call 插件**运行在 Gateway 网关进程内部**。 +Voice Call 插件运行在 **Gateway 网关进程内部**。 -如果你使用远程 Gateway 网关，请在**运行 Gateway 网关的机器**上安装/配置该插件，然后重启 Gateway 网关以加载它。 +如果你使用远程 Gateway 网关，请在**运行 Gateway 网关的机器**上安装 / 配置该插件，然后重启 Gateway 网关以加载它。 ## 安装 @@ -47,7 +47,7 @@ openclaw plugins install @openclaw/voice-call 之后重启 Gateway 网关。 -### 选项 B：从本地文件夹安装（开发，无需复制） +### 选项 B：从本地文件夹安装（开发用，不复制文件） ```bash PLUGIN_SRC=./path/to/local/voice-call-plugin @@ -80,8 +80,8 @@ cd "$PLUGIN_SRC" && pnpm install telnyx: { apiKey: "...", connectionId: "...", - // 来自 Telnyx Mission Control Portal 的 Telnyx webhook 公钥 - // （Base64 字符串；也可以通过 TELNYX_PUBLIC_KEY 设置）。 + // Telnyx Mission Control Portal 中的 Telnyx webhook 公钥 + // （Base64 字符串；也可通过 TELNYX_PUBLIC_KEY 设置）。 publicKey: "...", }, @@ -96,13 +96,13 @@ cd "$PLUGIN_SRC" && pnpm install path: "/voice/webhook", }, - // Webhook 安全性（推荐用于隧道/代理） + // Webhook 安全性（建议用于隧道 / 代理） webhookSecurity: { allowedHosts: ["voice.example.com"], trustedProxyIPs: ["100.64.0.1"], }, - // 公网暴露方式（任选其一） + // 对外暴露方式（任选一种） // publicUrl: "https://example.ngrok.app/voice/webhook", // tunnel: { provider: "ngrok" }, // tailscale: { mode: "funnel", path: "/voice/webhook" } @@ -113,7 +113,7 @@ cd "$PLUGIN_SRC" && pnpm install streaming: { enabled: true, - provider: "openai", // 可选；未设置时使用第一个已注册的实时转录提供商 + provider: "openai", // 可选；未设置时使用首个已注册的实时转录提供商 streamPath: "/voice/stream", providers: { openai: { @@ -137,32 +137,32 @@ cd "$PLUGIN_SRC" && pnpm install 说明： -- Twilio/Telnyx 需要一个**可从公网访问**的 webhook URL。 +- Twilio / Telnyx 需要一个**可从公网访问**的 webhook URL。 - Plivo 需要一个**可从公网访问**的 webhook URL。 - `mock` 是本地开发提供商（不发起网络调用）。 -- 如果旧配置仍使用 `provider: "log"`、`twilio.from` 或旧版 `streaming.*` OpenAI 键，请运行 `openclaw doctor --fix` 以重写它们。 +- 如果旧配置仍使用 `provider: "log"`、`twilio.from` 或旧版 `streaming.*` OpenAI 键，请运行 `openclaw doctor --fix` 进行重写。 - 除非 `skipSignatureVerification` 为 true，否则 Telnyx 需要 `telnyx.publicKey`（或 `TELNYX_PUBLIC_KEY`）。 - `skipSignatureVerification` 仅用于本地测试。 -- 如果你使用 ngrok 免费层，请将 `publicUrl` 设置为精确的 ngrok URL；签名校验始终会被强制执行。 -- `tunnel.allowNgrokFreeTierLoopbackBypass: true` 仅在 `tunnel.provider="ngrok"` 且 `serve.bind` 为 loopback（ngrok 本地 agent）时，允许 Twilio webhook 使用无效签名。仅用于本地开发。 -- Ngrok 免费层 URL 可能会变化或插入中间页行为；如果 `publicUrl` 发生漂移，Twilio 签名会校验失败。在生产环境中，优先使用稳定域名或 Tailscale funnel。 +- 如果你使用 ngrok 免费套餐，请将 `publicUrl` 设置为精确的 ngrok URL；签名校验始终会强制执行。 +- `tunnel.allowNgrokFreeTierLoopbackBypass: true` 仅在 `tunnel.provider="ngrok"` 且 `serve.bind` 为 loopback（ngrok 本地代理）时，允许 Twilio webhook 使用无效签名。仅用于本地开发。 +- Ngrok 免费套餐 URL 可能变化，或增加中间页行为；如果 `publicUrl` 漂移，Twilio 签名将会校验失败。生产环境中，建议优先使用稳定域名或 Tailscale funnel。 - 流式传输安全默认值： - - `streaming.preStartTimeoutMs` 会关闭那些从未发送有效 `start` 帧的套接字。 -- `streaming.maxPendingConnections` 限制未认证、预启动状态套接字的总数。 -- `streaming.maxPendingConnectionsPerIp` 限制每个源 IP 的未认证、预启动状态套接字数量。 -- `streaming.maxConnections` 限制媒体流套接字的总打开数量（待处理 + 活动中）。 -- 运行时回退目前仍接受这些旧的 voice-call 键，但重写路径是 `openclaw doctor --fix`，兼容性垫片只是临时方案。 + - `streaming.preStartTimeoutMs` 会关闭那些始终未发送有效 `start` 帧的 socket。 +- `streaming.maxPendingConnections` 限制总的未认证、启动前 socket 数量。 +- `streaming.maxPendingConnectionsPerIp` 限制每个源 IP 的未认证、启动前 socket 数量。 +- `streaming.maxConnections` 限制总的已打开媒体流 socket 数量（待启动 + 活跃）。 +- 运行时目前仍会接受这些旧版 voice-call 键作为回退，但推荐的重写方式是 `openclaw doctor --fix`，且该兼容层只是临时方案。 ## 流式转录 -`streaming` 为实时通话音频选择一个实时转录提供商。 +`streaming` 用于为实时通话音频选择一个实时转录提供商。 当前运行时行为： -- `streaming.provider` 是可选的。未设置时，Voice Call 会使用第一个已注册的实时转录提供商。 -- 内置的实时转录提供商包括 OpenAI（`openai`）和 xAI（`xai`），它们由各自的提供商插件注册。 +- `streaming.provider` 是可选项。未设置时，Voice Call 会使用首个已注册的实时转录提供商。 +- 内置的实时转录提供商包括 Deepgram（`deepgram`）、ElevenLabs（`elevenlabs`）、Mistral（`mistral`）、OpenAI（`openai`）和 xAI（`xai`），由各自的提供商插件注册。 - 提供商自有的原始配置位于 `streaming.providers.` 下。 -- 如果 `streaming.provider` 指向一个未注册的提供商，或者根本没有注册任何实时转录提供商，Voice Call 会记录一条警告并跳过媒体流传输，而不是让整个插件失败。 +- 如果 `streaming.provider` 指向一个未注册的提供商，或根本没有注册任何实时转录提供商，Voice Call 会记录一条警告，并跳过媒体流式传输，而不是让整个插件失败。 OpenAI 流式转录默认值： @@ -235,7 +235,7 @@ xAI 流式转录默认值： } ``` -旧版键仍会由 `openclaw doctor --fix` 自动迁移： +旧版键仍可通过 `openclaw doctor --fix` 自动迁移： - `streaming.sttProvider` → `streaming.provider` - `streaming.openaiApiKey` → `streaming.providers.openai.apiKey` @@ -245,12 +245,12 @@ xAI 流式转录默认值： ## 陈旧通话清理器 -使用 `staleCallReaperSeconds` 来结束那些从未收到终态 webhook 的通话（例如，永远未完成的 notify 模式通话）。默认值为 `0`（禁用）。 +使用 `staleCallReaperSeconds` 来结束那些始终未收到终态 webhook 的通话（例如永远未完成的 notify 模式通话）。默认值为 `0`（禁用）。 -推荐范围： +建议范围： -- **生产环境：** 对于通知类流程，使用 `120`–`300` 秒。 -- 保持此值**高于 `maxDurationSeconds`**，这样正常通话才能完成。一个不错的起始值是 `maxDurationSeconds + 30–60` 秒。 +- **生产环境：** 对于 notify 风格流程，建议设为 `120`–`300` 秒。 +- 保持该值**高于 `maxDurationSeconds`**，这样正常通话才能完成。一个不错的起始值是 `maxDurationSeconds + 30–60` 秒。 示例： @@ -271,23 +271,23 @@ xAI 流式转录默认值： ## Webhook 安全性 -当代理或隧道位于 Gateway 网关前方时，插件会重建用于签名校验的公网 URL。这些选项控制哪些转发头会被信任。 +当 Gateway 网关前面有代理或隧道时，插件会重建公开 URL 以进行签名校验。这些选项用于控制信任哪些转发头。 -`webhookSecurity.allowedHosts` 允许通过转发头携带的主机名白名单。 +`webhookSecurity.allowedHosts` 用于将转发头中的主机名加入允许列表。 -`webhookSecurity.trustForwardingHeaders` 在没有 allowlist 的情况下信任转发头。 +`webhookSecurity.trustForwardingHeaders` 表示在没有允许列表的情况下信任转发头。 -仅当请求的远程 IP 与列表匹配时，`webhookSecurity.trustedProxyIPs` 才会信任转发头。 +`webhookSecurity.trustedProxyIPs` 表示只有当请求的远端 IP 与列表匹配时，才信任转发头。 -Twilio 和 Plivo 启用了 webhook 重放保护。被重放的有效 webhook 请求会被确认，但会跳过副作用处理。 +Twilio 和 Plivo 已启用 webhook 重放保护。对于被重放但签名有效的 webhook 请求，系统会确认接收，但跳过副作用处理。 -Twilio 对话轮次会在 `` 回调中包含每轮专属 token，因此陈旧/重放的语音回调无法满足较新的待处理转录轮次。 +Twilio 对话轮次在 `` 回调中包含每轮唯一 token，因此陈旧 / 重放的语音回调无法满足较新的待处理转录轮次。 -如果提供商所需的签名头缺失，未经认证的 webhook 请求会在读取正文之前被拒绝。 +对于缺少提供商所需签名头的未认证 webhook 请求，系统会在读取请求体之前直接拒绝。 -voice-call webhook 在签名校验之前使用共享的预认证正文配置（64 KB / 5 秒）以及每个 IP 的进行中请求数量上限。 +voice-call webhook 使用共享的预认证请求体配置（64 KB / 5 秒），并在签名校验前施加每 IP 的进行中请求上限。 -使用稳定公网主机的示例： +使用稳定公开主机的示例： ```json5 { @@ -306,9 +306,9 @@ voice-call webhook 在签名校验之前使用共享的预认证正文配置（6 } ``` -## 用于通话的 TTS +## 通话的 TTS -Voice Call 在通话中使用核心 `messages.tts` 配置来进行流式语音播放。你也可以在插件配置下使用**相同的结构**进行覆盖——它会与 `messages.tts` 深度合并。 +Voice Call 会使用核心 `messages.tts` 配置，在通话中进行语音流式播放。你可以在插件配置下使用**相同的结构**覆盖它——它会与 `messages.tts` 进行深度合并。 ```json5 { @@ -326,11 +326,11 @@ Voice Call 在通话中使用核心 `messages.tts` 配置来进行流式语音 说明： -- 插件配置中的旧版 `tts.` 键（`openai`、`elevenlabs`、`microsoft`、`edge`）会在加载时自动迁移到 `tts.providers.`。在提交的配置中优先使用 `providers` 结构。 -- **Microsoft speech 会被语音通话忽略**（电话音频需要 PCM；当前 Microsoft 传输方式不提供电话场景所需的 PCM 输出）。 -- 启用 Twilio 媒体流时会使用核心 TTS；否则通话会回退到提供商原生语音。 -- 如果 Twilio 媒体流已经处于活动状态，Voice Call 不会回退到 TwiML ``。如果该状态下电话 TTS 不可用，则播放请求会失败，而不是混用两条播放路径。 -- 当电话 TTS 回退到次级提供商时，Voice Call 会记录一条带有提供商链（`from`、`to`、`attempts`）的警告，便于调试。 +- 插件配置中的旧版 `tts.` 键（`openai`、`elevenlabs`、`microsoft`、`edge`）会在加载时自动迁移到 `tts.providers.`。提交到配置文件时，优先使用 `providers` 结构。 +- **Microsoft speech 会被忽略用于语音通话**（电话音频需要 PCM；当前 Microsoft 传输不提供电话场景所需的 PCM 输出）。 +- 启用 Twilio 媒体流式传输时，会使用核心 TTS；否则通话会回退到提供商原生语音。 +- 如果 Twilio 媒体流已经处于激活状态，Voice Call 不会回退到 TwiML ``。在该状态下如果电话 TTS 不可用，则播放请求会失败，而不是混用两种播放路径。 +- 当电话 TTS 回退到次级提供商时，Voice Call 会记录一条包含提供商链（`from`、`to`、`attempts`）的警告日志，以便调试。 ### 更多示例 @@ -349,7 +349,7 @@ Voice Call 在通话中使用核心 `messages.tts` 配置来进行流式语音 } ``` -仅为通话覆盖为 ElevenLabs（其他地方保留核心默认值）： +仅对通话覆盖为 ElevenLabs（其他地方保留核心默认值）： ```json5 { @@ -374,7 +374,7 @@ Voice Call 在通话中使用核心 `messages.tts` 配置来进行流式语音 } ``` -仅为通话覆盖 OpenAI model（深度合并示例）： +仅覆盖通话的 OpenAI model（深度合并示例）： ```json5 { @@ -399,68 +399,69 @@ Voice Call 在通话中使用核心 `messages.tts` 配置来进行流式语音 ## 呼入通话 -呼入策略默认值为 `disabled`。要启用呼入通话，请设置： +呼入策略默认是 `disabled`。要启用呼入通话，请设置： ```json5 { inboundPolicy: "allowlist", allowFrom: ["+15550001234"], - inboundGreeting: "你好！有什么可以帮你？", + inboundGreeting: "你好！我能帮你什么？", } ``` -`inboundPolicy: "allowlist"` 是一种低保障级别的来电号码筛选。插件会将提供商提供的 `From` 值标准化，并与 `allowFrom` 进行比较。Webhook 校验可以验证提供商投递来源和载荷完整性，但它**不能**证明 PSTN/VoIP 来电号码的实际所有权。请将 `allowFrom` 视为来电显示筛选，而不是强身份认证。 +`inboundPolicy: "allowlist"` 是一种低保证级别的来电号码筛选。插件会对提供商提供的 `From` 值进行规范化，并将其与 `allowFrom` 比较。Webhook 校验可以验证提供商投递来源和负载完整性，但**不能**证明 PSTN/VoIP 来电号码的实际归属权。请将 `allowFrom` 视为来电显示过滤，而不是强来电身份验证。 -自动响应使用智能体系统。可通过以下项进行调优： +自动响应使用智能体系统。可通过以下项调整： - `responseModel` - `responseSystemPrompt` - `responseTimeoutMs` -### 语音输出约定 +### 口语化输出约定 -对于自动响应，Voice Call 会在系统提示词后追加一个严格的语音输出约定： +对于自动响应，Voice Call 会在系统提示词后追加一个严格的口语化输出约定： - `{"spoken":"..."}` -随后，Voice Call 会以防御性方式提取语音文本： +随后 Voice Call 会以防御性方式提取语音文本： -- 忽略被标记为推理/错误内容的载荷。 +- 忽略被标记为推理 / 错误内容的负载。 - 解析直接 JSON、带围栏的 JSON，或内联 `"spoken"` 键。 -- 回退到纯文本，并移除可能的规划/元信息引导段落。 +- 回退到纯文本，并移除看起来像计划 / 元信息引导段落的内容。 -这样可以让语音播放聚焦于面向来电者的文本，并避免将规划性文本泄露到音频中。 +这样可以让语音播放聚焦于面向来电者的文本，并避免将规划性文字泄露到音频中。 ### 对话启动行为 -对于呼出的 `conversation` 通话，首条消息处理与实时播放状态绑定： +对于呼出的 `conversation` 通话，首条消息的处理与实时播放状态绑定： -- 仅当初始问候语正在主动播放时，才会抑制打断清队列和自动响应。 -- 如果初始播放失败，通话会返回 `listening` 状态，初始消息会继续排队以供重试。 -- 对于 Twilio 流式传输，初始播放会在流连接建立时立即开始，不会额外延迟。 +- 只有在初始问候语正在主动播放时，才会抑制打断清队列和自动响应。 +- 如果初始播放失败，通话会返回 `listening`，并且初始消息会继续保留在队列中以供重试。 +- 对于 Twilio 流式传输，初始播放会在流连接建立时立即开始，不会有额外延迟。 ### Twilio 流断开宽限期 -当 Twilio 媒体流断开时，Voice Call 会等待 `2000ms`，然后才自动结束通话： +当 Twilio 媒体流断开时，Voice Call 会等待 `2000ms` 后才自动结束通话： -- 如果流在这段时间内重新连接，自动结束会被取消。 -- 如果宽限期结束后仍未重新注册任何流，则会结束该通话，以防止通话卡在活动状态。 +- 如果流在该时间窗口内重新连接，则会取消自动结束。 +- 如果宽限期后仍未重新注册流，则会结束通话，以防止通话卡在活跃状态。 ## CLI ```bash openclaw voicecall call --to "+15555550123" --message "Hello from OpenClaw" -openclaw voicecall start --to "+15555550123" # call 的别名 +openclaw voicecall start --to "+15555550123" # `call` 的别名 openclaw voicecall continue --call-id --message "Any questions?" openclaw voicecall speak --call-id --message "One moment" openclaw voicecall end --call-id openclaw voicecall status --call-id openclaw voicecall tail -openclaw voicecall latency # 从日志中汇总轮次延迟 +openclaw voicecall latency # 从日志汇总轮次延迟 openclaw voicecall expose --mode funnel ``` -`latency` 会从默认的 voice-call 存储路径读取 `calls.jsonl`。使用 `--file ` 可指定不同的日志文件，使用 `--last ` 可将分析限制为最后 N 条记录（默认 200）。输出包括轮次延迟和监听等待时间的 p50/p90/p99。 +`latency` 会从默认的 voice-call 存储路径读取 `calls.jsonl`。使用 +`--file ` 可指向其他日志文件，使用 `--last ` 可将分析限制为最后 N 条记录（默认 200）。输出包括轮次延迟和监听等待时间的 p50 / p90 / p99。 ## 智能体工具 @@ -474,7 +475,7 @@ openclaw voicecall expose --mode funnel - `end_call`（callId） - `get_status`（callId） -此仓库附带了对应的 Skills 文档：`skills/voice-call/SKILL.md`。 +此仓库附带对应的 skill 文档：`skills/voice-call/SKILL.md`。 ## Gateway 网关 RPC