diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index 96cb9170d..21c4e2895 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -1,100 +1,111 @@ --- read_when: - - 你看到 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告 - - 你看到 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告 + - 你看到了 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告 + - 你看到了 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告 - 你正在将插件更新到现代插件架构 - - 你在维护一个外部 OpenClaw 插件 + - 你在维护外部 OpenClaw 插件 sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-08T08:10:35Z" + generated_at: "2026-04-09T00:37:52Z" model: gpt-5.4 provider: openai - source_hash: d9a2ce7f5553563516a549ca87e776a6a71e8dd8533a773c5ddbecfae43e7b77 + source_hash: 60cbb6c8be30d17770887d490c14e3a4538563339a5206fb419e51e0558bbc07 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`** — 一个桥接层，让插件能够直接访问宿主侧辅助工具，例如嵌入式 agent 运行器。 -这两个接口现在都已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。 +这两个接口现在都已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主要版本移除它们之前完成迁移。 - 这个向后兼容层将在未来的主版本中移除。 - 到那时，仍然从这些接口导入的插件将会失效。 + 向后兼容层将在未来的一个主要版本中移除。 + 如果插件仍然从这些接口导入内容，到那时将会失效。 -## 为什么会有这个变化 +## 为什么会有这项变更 -旧方案带来了这些问题： +旧方案会带来一些问题： -- **启动缓慢** — 导入一个辅助工具会加载数十个不相关模块 -- **循环依赖** — 宽泛的重新导出很容易造成导入循环 -- **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`、带有 channel 品牌的辅助接口，以及 `openclaw/plugin-sdk/telegram-core` 这样的导入，都是私有 monorepo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区中，应将 provider 自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 -当前内置提供商示例： +当前内置 provider 示例： -- Anthropic 将 Claude 专属的流式传输辅助工具保留在自己的 `api.ts` / `contract-api.ts` 接口中 -- OpenAI 将 provider 构建器、默认模型辅助工具和 realtime provider 构建器保留在自己的 `api.ts` 中 -- OpenRouter 将 provider 构建器以及新手引导 / 配置辅助工具保留在自己的 `api.ts` 中 +- Anthropic 将 Claude 专用的流式辅助工具保留在其自己的 `api.ts` / `contract-api.ts` 接口中 +- OpenAI 将 provider 构建器、默认模型辅助工具和 realtime provider 构建器保留在其自己的 `api.ts` 中 +- OpenRouter 将 provider 构建器以及新手引导 / 配置辅助工具保留在其自己的 `api.ts` 中 ## 如何迁移 - - 具备审批能力的渠道插件现在通过 `approvalCapability.nativeRuntime` 加上共享的运行时上下文注册表来公开原生审批行为。 + + 具备审批能力的渠道插件现在通过 + `approvalCapability.nativeRuntime` 以及共享的运行时上下文注册表公开原生审批行为。 关键变化： - - 用 `approvalCapability.nativeRuntime` 替换 `approvalCapability.handler.loadRuntime(...)` - - 将审批相关的 auth / delivery 从旧版 `plugin.auth` / - `plugin.approvals` 配置迁移到 `approvalCapability` - - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；请将 delivery / native / render 字段迁移到 `approvalCapability` - - `plugin.auth` 仅保留给渠道 login / logout 流程使用；其中的审批 auth hook 不再被 core 读取 - - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道自有的运行时对象，例如客户端、令牌或 Bolt app - - 不要从原生审批处理器发送插件自有的重新路由通知；core 现在会根据实际投递结果负责 “已路由到其他位置” 通知 - - 将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 接口。部分 stub 将被拒绝。 + - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 + `approvalCapability.nativeRuntime` + - 将审批专用的 auth / delivery 从旧版 `plugin.auth` / + `plugin.approvals` 连接方式迁移到 `approvalCapability` + - `ChannelPlugin.approvals` 已从公开的渠道插件契约中移除； + 请将 delivery / native / render 字段迁移到 `approvalCapability` + - `plugin.auth` 仅保留用于渠道登录 / 登出流程；其中的审批 auth + hook 不再被 core 读取 + - 通过 `openclaw/plugin-sdk/channel-runtime-context` + 注册渠道自有的运行时对象，例如客户端、令牌或 Bolt + 应用 + - 不要从原生审批处理器发送插件自有的重路由通知； + 现在 core 会根据实际投递结果处理“已路由到其他位置”的通知 + - 当把 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供一个真实的 + `createPluginRuntime().channel` 接口。部分 stub 会被拒绝。 - 当前审批能力布局请参见 `/plugins/sdk-channel-plugins`。 + 当前审批 capability 布局请参见 `/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/ @@ -107,33 +118,33 @@ 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` | @@ -159,125 +170,126 @@ OpenClaw 已经从一个宽泛的向后兼容层迁移到现代插件架构， | 导入路径 | 用途 | 关键导出 | | --- | --- | --- | | `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` | - | `plugin-sdk/core` | 面向渠道入口定义 / 构建器的旧版总入口重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/core` | 面向渠道入口定义 / 构建器的旧版总括重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | 单提供商入口辅助工具 | `defineSingleProviderPluginEntry` | + | `plugin-sdk/provider-entry` | 单 provider 入口辅助工具 | `defineSingleProviderPluginEntry` | | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享设置向导辅助工具 | 允许列表提示、设置状态构建器 | - | `plugin-sdk/setup-runtime` | 设置时运行时辅助工具 | 可安全导入的设置补丁适配器、查找说明辅助工具、`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` | 多账户辅助工具 | 账户列表 / 配置 / action-gate 辅助工具 | + | `plugin-sdk/account-core` | 多账号辅助工具 | 账号列表 / 配置 / action-gate 辅助工具 | | `plugin-sdk/account-id` | account-id 辅助工具 | `DEFAULT_ACCOUNT_ID`、account-id 规范化 | - | `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表 / account-action 辅助工具 | + | `plugin-sdk/account-resolution` | 账号查找辅助工具 | 账号查找 + 默认回退辅助工具 | + | `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-reply-pipeline` | 回复前缀 + 正在输入连接逻辑 | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 渠道配置 schema 类型 | | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复 / 冲突校验 | | `plugin-sdk/channel-policy` | 群组 / 私信策略解析 | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | 账户状态跟踪 | `createAccountStatusSink` | + | `plugin-sdk/channel-lifecycle` | 账号状态跟踪 | `createAccountStatusSink` | | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope 构建器辅助工具 | - | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享 record-and-dispatch 辅助工具 | + | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录与派发辅助工具 | | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析 / 匹配辅助工具 | | `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 | | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站身份 / 发送委托辅助工具 | | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 | - | `plugin-sdk/agent-media-payload` | 旧版媒体载荷辅助工具 | 面向旧字段布局的智能体媒体载荷构建器 | - | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅旧版渠道运行时工具 | + | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 面向旧字段布局的 agent 媒体负载构建器 | + | `plugin-sdk/channel-runtime` | 已弃用的兼容性垫片 | 仅限旧版渠道运行时工具 | | `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 | | `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | 宽范围运行时辅助工具 | runtime / logging / backup / 插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 窄范围运行时 env 辅助工具 | logger / runtime env、timeout、retry 和 backoff 辅助工具 | - | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令 / hooks / http / interactive 辅助工具 | - | `plugin-sdk/hook-runtime` | Hook 管道辅助工具 | 共享 webhook / internal hook 管道辅助工具 | - | `plugin-sdk/lazy-runtime` | 延迟运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/runtime` | 宽范围运行时辅助工具 | 运行时 / 日志 / 备份 / 插件安装辅助工具 | + | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | logger / 运行时环境、超时、重试与退避辅助工具 | + | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令 / hooks / http / 交互式辅助工具 | + | `plugin-sdk/hook-runtime` | Hook 管道辅助工具 | 共享 webhook / 内部 hook 管道辅助工具 | + | `plugin-sdk/lazy-runtime` | 惰性运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 | | `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 | | `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道状态补丁辅助工具 | | `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载 / 写入辅助工具 | | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供稳定回退的 Telegram 命令校验辅助工具 | - | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec / 插件审批载荷、审批能力 / 配置文件辅助工具、原生审批路由 / 运行时辅助工具 | + | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec / 插件审批负载、审批 capability / profile 辅助工具、原生审批路由 / 运行时辅助工具 | | `plugin-sdk/approval-auth-runtime` | 审批 auth 辅助工具 | approver 解析、同聊天 action auth | - | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置文件 / 过滤辅助工具 | - | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力 / 投递适配器 | + | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批 profile / filter 辅助工具 | + | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批 capability / delivery 适配器 | | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 面向热点渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽范围的审批处理器运行时辅助工具；如果更窄的 adapter / gateway 接口已经足够，优先使用后者 | - | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标 / 账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec / 插件审批回复载荷辅助工具 | + | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 面向高频渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 范围更广的审批处理器运行时辅助工具；如果更窄的 adapter / gateway 接口已足够，优先使用后者 | + | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标 / 账号绑定辅助工具 | + | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec / 插件审批回复负载辅助工具 | | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register / get / watch 辅助工具 | - | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和密钥收集辅助工具 | + | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信 gating、外部内容和密钥收集辅助工具 | | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 allowlist 和私有网络策略辅助工具 | - | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | pinned-dispatcher、guarded fetch、SSRF 策略辅助工具 | + | `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 / proxy 辅助工具 | `resolveFetch`、proxy 辅助工具 | + | `plugin-sdk/diagnostic-runtime` | 诊断 gating 辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`, 错误图辅助工具 | + | `plugin-sdk/fetch-runtime` | 包装后的 fetch / proxy 辅助工具 | `resolveFetch`、proxy 辅助工具 | | `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | retry 辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 | + | `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/command-auth` | 命令 gating 和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具 | + | `plugin-sdk/command-status` | 命令状态 / 帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | | `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助工具 | | `plugin-sdk/webhook-ingress` | webhook 请求辅助工具 | webhook 目标工具 | - | `plugin-sdk/webhook-request-guards` | webhook 请求体保护辅助工具 | 请求体读取 / 限制辅助工具 | - | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、heartbeat、回复规划器、分块 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | finalize + provider 分发辅助工具 | + | `plugin-sdk/webhook-request-guards` | webhook 请求体守卫辅助工具 | 请求体读取 / 限制辅助工具 | + | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站派发、heartbeat、回复规划器、分块 | + | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复派发辅助工具 | finalize + provider 派发辅助工具 | | `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本 / markdown 分块辅助工具 | - | `plugin-sdk/session-store-runtime` | session store 辅助工具 | 存储路径 + updated-at 辅助工具 | + | `plugin-sdk/session-store-runtime` | 会话存储辅助工具 | 存储路径 + updated-at 辅助工具 | | `plugin-sdk/state-paths` | 状态路径辅助工具 | 状态和 OAuth 目录辅助工具 | | `plugin-sdk/routing` | 路由 / session-key 辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、session-key 规范化辅助工具 | - | `plugin-sdk/status-helpers` | 渠道状态辅助工具 | 渠道 / 账户状态摘要构建器、运行时状态默认值、问题元数据辅助工具 | + | `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/request-url` | 请求 URL 辅助工具 | 从类请求输入中提取字符串 URL | + | `plugin-sdk/run-command` | 定时命令辅助工具 | 带标准化 stdout / stderr 的定时命令运行器 | | `plugin-sdk/param-readers` | 参数读取器 | 常用工具 / CLI 参数读取器 | - | `plugin-sdk/tool-payload` | 工具载荷提取 | 从工具结果对象中提取规范化载荷 | + | `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` | 精选的本地 / 自托管 provider 设置辅助工具 | 自托管 provider 发现 / 配置辅助工具 | + | `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 运行时 auth 辅助工具 | 运行时 API key 解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | provider API key 设置辅助工具 | API key onboarding / profile-write 辅助工具 | + | `plugin-sdk/provider-auth-api-key` | provider API key 设置辅助工具 | API key 新手引导 / profile 写入辅助工具 | | `plugin-sdk/provider-auth-result` | provider auth-result 辅助工具 | 标准 OAuth auth-result 构建器 | | `plugin-sdk/provider-auth-login` | provider 交互式登录辅助工具 | 共享交互式登录辅助工具 | | `plugin-sdk/provider-env-vars` | provider 环境变量辅助工具 | provider auth 环境变量查找辅助工具 | - | `plugin-sdk/provider-model-shared` | 共享 provider 模型 / replay 辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider endpoint 辅助工具以及 model-id 规范化辅助工具 | + | `plugin-sdk/provider-model-shared` | 共享 provider 模型 / replay 辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider endpoint 辅助工具，以及 model-id 规范化辅助工具 | | `plugin-sdk/provider-catalog-shared` | 共享 provider catalog 辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | provider onboarding 补丁 | onboarding 配置辅助工具 | + | `plugin-sdk/provider-onboard` | provider 新手引导补丁 | 新手引导配置辅助工具 | | `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP / endpoint capability 辅助工具 | | `plugin-sdk/provider-web-fetch` | provider web-fetch 辅助工具 | web-fetch provider 注册 / 缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | provider web-search 配置辅助工具 | 面向不需要插件启用配置的 provider 的窄范围 web-search 配置 / 凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | provider web-search 契约辅助工具 | 窄范围 web-search 配置 / 凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域凭证 setter / getter | + | `plugin-sdk/provider-web-search-config-contract` | provider web-search 配置辅助工具 | 面向不需要插件启用连接逻辑的 provider 的窄范围 web-search 配置 / 凭据辅助工具 | + | `plugin-sdk/provider-web-search-contract` | provider web-search 契约辅助工具 | 窄范围 web-search 配置 / 凭据契约辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` 以及作用域化的凭据设置 / 获取器 | | `plugin-sdk/provider-web-search` | provider web-search 辅助工具 | web-search provider 注册 / 缓存 / 运行时辅助工具 | - | `plugin-sdk/provider-tools` | provider 工具 / schema 兼容辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + diagnostics，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | provider usage 辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` 以及其他 provider usage 辅助工具 | - | `plugin-sdk/provider-stream` | provider stream 封装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、stream wrapper 类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot AI / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot wrapper 辅助工具 | + | `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/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体 fetch / transform / store 辅助工具以及媒体载荷构建器 | - | `plugin-sdk/media-generation-runtime` | 共享 media-generation 辅助工具 | 图像 / 视频 / 音乐生成的共享故障切换辅助工具、候选项选择和缺失模型提示 | - | `plugin-sdk/media-understanding` | media-understanding 辅助工具 | 媒体理解 provider 类型以及面向 provider 的图像 / 音频辅助导出 | - | `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` | speech 辅助工具 | speech provider 类型以及面向 provider 的 directive、注册表和校验辅助工具 | - | `plugin-sdk/speech-core` | 共享 speech core | speech provider 类型、注册表、directives、规范化 | - | `plugin-sdk/realtime-transcription` | realtime transcription 辅助工具 | provider 类型和注册表辅助工具 | - | `plugin-sdk/realtime-voice` | realtime voice 辅助工具 | provider 类型和注册表辅助工具 | - | `plugin-sdk/image-generation-core` | 共享 image-generation core | 图像生成类型、故障切换、auth 和注册表辅助工具 | - | `plugin-sdk/music-generation` | music-generation 辅助工具 | 音乐生成 provider / request / result 类型 | - | `plugin-sdk/music-generation-core` | 共享 music-generation core | 音乐生成类型、故障切换辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/video-generation` | video-generation 辅助工具 | 视频生成 provider / request / result 类型 | - | `plugin-sdk/video-generation-core` | 共享 video-generation core | 视频生成类型、故障切换辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复载荷规范化 / 归约 | + | `plugin-sdk/speech` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的 directive、注册表和校验辅助工具 | + | `plugin-sdk/speech-core` | 共享语音 core | 语音 provider 类型、注册表、directives、规范化 | + | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型和注册表辅助工具 | + | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型和注册表辅助工具 | + | `plugin-sdk/image-generation-core` | 共享图像生成 core | 图像生成类型、故障转移、auth 和注册表辅助工具 | + | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider / request / result 类型 | + | `plugin-sdk/music-generation-core` | 共享音乐生成 core | 音乐生成类型、故障转移辅助工具、provider 查找和 model-ref 解析 | + | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider / request / result 类型 | + | `plugin-sdk/video-generation-core` | 共享视频生成 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` | 共享渠道前导模块 | 共享渠道插件前导导出 | @@ -285,49 +297,52 @@ OpenClaw 已经从一个宽泛的向后兼容层迁移到现代插件架构， | `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助工具 | allowlist 配置编辑 / 读取辅助工具 | | `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 | | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信 auth / guard 辅助工具 | - | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道 / 状态及环境代理辅助原语 | - | `plugin-sdk/webhook-targets` | webhook 目标辅助工具 | webhook 目标注册表和 route-install 辅助工具 | + | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道 / 状态和 ambient proxy 辅助原语 | + | `plugin-sdk/webhook-targets` | webhook 目标辅助工具 | webhook 目标注册表和路由安装辅助工具 | | `plugin-sdk/webhook-path` | webhook 路径辅助工具 | webhook 路径规范化辅助工具 | - | `plugin-sdk/web-media` | 共享 Web 媒体辅助工具 | 远程 / 本地媒体加载辅助工具 | - | `plugin-sdk/zod` | Zod 重新导出 | 面向插件 SDK 使用者重新导出的 `zod` | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | 内存管理器 / 配置 / 文件 / CLI 辅助工具接口 | - | `plugin-sdk/memory-core-engine-runtime` | 内存引擎运行时外观 | 内存索引 / 搜索运行时外观 | - | `plugin-sdk/memory-core-host-engine-foundation` | 内存宿主基础引擎 | 内存宿主基础引擎导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | 内存宿主嵌入引擎 | 内存宿主嵌入引擎导出 | - | `plugin-sdk/memory-core-host-engine-qmd` | 内存宿主 QMD 引擎 | 内存宿主 QMD 引擎导出 | - | `plugin-sdk/memory-core-host-engine-storage` | 内存宿主存储引擎 | 内存宿主持储引擎导出 | - | `plugin-sdk/memory-core-host-multimodal` | 内存宿主多模态辅助工具 | 内存宿主多模态辅助工具 | - | `plugin-sdk/memory-core-host-query` | 内存宿主查询辅助工具 | 内存宿主查询辅助工具 | - | `plugin-sdk/memory-core-host-secret` | 内存宿主密钥辅助工具 | 内存宿主密钥辅助工具 | - | `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 辅助工具 | 面向 memory 相邻插件的共享托管 markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 活跃内存搜索外观 | 延迟加载的活跃内存 search-manager 运行时外观 | - | `plugin-sdk/memory-host-status` | 内存宿主状态别名 | 面向厂商无关的内存宿主状态辅助工具别名 | - | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | memory-lancedb 辅助工具接口 | + | `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` | 记忆宿主 core 运行时 | 记忆宿主 core 运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-files` | 记忆宿主文件 / 运行时辅助工具 | 记忆宿主文件 / 运行时辅助工具 | + | `plugin-sdk/memory-host-core` | 记忆宿主 core 运行时别名 | 面向厂商中立的记忆宿主 core 运行时辅助工具别名 | + | `plugin-sdk/memory-host-events` | 记忆宿主事件日志别名 | 面向厂商中立的记忆宿主事件日志辅助工具别名 | + | `plugin-sdk/memory-host-files` | 记忆宿主文件 / 运行时别名 | 面向厂商中立的记忆宿主文件 / 运行时辅助工具别名 | + | `plugin-sdk/memory-host-markdown` | 托管 markdown 辅助工具 | 面向记忆相关插件的共享托管 markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 活跃记忆搜索门面 | 惰性 active-memory search-manager 运行时门面 | + | `plugin-sdk/memory-host-status` | 记忆宿主状态别名 | 面向厂商中立的记忆宿主状态辅助工具别名 | + | `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` +- 浏览器支持辅助工具：`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`、 @@ -336,37 +351,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-helper 接口： -`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 中询问。 ## 移除时间线 -| 时间 | 发生的事情 | +| 时间 | 会发生什么 | | ---------------------- | ----------------------------------------------------------------------- | | **现在** | 已弃用接口会发出运行时警告 | -| **下一个主版本** | 已弃用接口将被移除；仍在使用它们的插件将会失效 | +| **下一个主要版本** | 已弃用接口将被移除；仍在使用它们的插件将会失效 | -所有 core 插件都已经完成迁移。外部插件应在下一个主版本之前完成迁移。 +所有 core 插件都已经完成迁移。外部插件应在下一个主要版本之前完成迁移。 -## 临时抑制警告 +## 暂时抑制警告 -在迁移期间，你可以设置这些环境变量： +在你迁移期间，可以设置这些环境变量： ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -这只是一个临时逃生口，不是永久解决方案。 +这只是临时逃生口，不是永久解决方案。 ## 相关内容 - [入门指南](/zh-CN/plugins/building-plugins) — 构建你的第一个插件 -- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整的子路径导入参考 +- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 -- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件 +- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建 provider 插件 - [插件内部机制](/zh-CN/plugins/architecture) — 架构深入解析 -- [插件清单](/zh-CN/plugins/manifest) — manifest schema 参考 +- [插件清单](/zh-CN/plugins/manifest) — 清单 schema 参考 diff --git a/docs/zh-CN/plugins/sdk-overview.md b/docs/zh-CN/plugins/sdk-overview.md index e7c57f69c..657e6ca92 100644 --- a/docs/zh-CN/plugins/sdk-overview.md +++ b/docs/zh-CN/plugins/sdk-overview.md @@ -1,338 +1,339 @@ --- read_when: - 你需要知道应从哪个 SDK 子路径导入 - - 你想查看 OpenClawPluginApi 上所有注册方法的参考 - - 你正在查找某个特定的 SDK 导出项 + - 你想查阅 OpenClawPluginApi 上所有注册方法的参考说明 + - 你正在查找某个特定的 SDK 导出 sidebarTitle: SDK Overview summary: 导入映射、注册 API 参考和 SDK 架构 title: 插件 SDK 概览 x-i18n: - generated_at: "2026-04-08T08:10:58Z" + generated_at: "2026-04-09T00:38:10Z" model: gpt-5.4 provider: openai - source_hash: 6e7b420eb0f3faa8916357d52df949f6c9a46f1c843a1e6a0c0b8bb26db6cbff + source_hash: bf205af060971931df97dca4af5110ce173d2b7c12f56ad7c62d664a402f2381 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/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/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带有渠道品牌的辅助接缝。内置插件应在各自的 `api.ts` 或 `runtime-api.ts` barrel 文件中组合通用 SDK 子路径，而核心则应使用这些插件本地 barrel，或者仅在确实属于跨渠道需求时添加一个狭义的通用 SDK 契约。 -生成的导出映射中仍然包含一小组内置插件辅助接口层，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅用于内置插件维护和兼容性；它们有意未出现在下面的常用表格中，也不是新第三方插件的推荐导入路径。 +生成的导出映射仍然包含一小组内置插件辅助接缝，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅为内置插件维护和兼容性而存在；它们有意未包含在下方的常用表格中，也不是新第三方插件推荐的导入路径。 ## 子路径参考 -最常用的子路径，按用途分组。包含 200+ 个子路径的生成完整列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 +最常用的子路径，按用途分组。完整的生成列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`。 -保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其标记为公共接口，否则应将它们视为实现细节/兼容性接口。 +保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其推广为公共接口，否则应将其视为实现细节/兼容性表面。 -### 插件入口点 +### 插件入口 -| 子路径 | 关键导出项 | -| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `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` | 共享设置向导辅助工具、允许列表提示、设置状态构建器 | + | `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` | 多账户 config/操作门控辅助工具、默认账户回退辅助工具 | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、账户 ID 规范化辅助工具 | - | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 更窄的账户列表/账户操作辅助工具 | + | `plugin-sdk/account-core` | 多账户配置/操作门控辅助函数、默认账户回退辅助函数 | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助函数 | + | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 | + | `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/telegram-command-config` | 带有内置契约回退的 Telegram 自定义命令规范化/校验辅助函数 | | `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/outbound-runtime` | 出站身份/发送委托辅助工具 | - | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 | - | `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 | - | `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对和已配置绑定辅助工具 | - | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 | - | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 | - | `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助工具 | - | `plugin-sdk/channel-config-primitives` | 更窄的渠道配置 schema 基元 | - | `plugin-sdk/channel-config-writes` | 渠道 config 写入授权辅助工具 | - | `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出项 | - | `plugin-sdk/allowlist-config-edit` | 允许列表 config 编辑/读取辅助工具 | - | `plugin-sdk/group-access` | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 共享私信鉴权/保护辅助工具 | - | `plugin-sdk/interactive-runtime` | 交互式回复负载规范化/归约辅助工具 | - | `plugin-sdk/channel-inbound` | 入站去抖、提及匹配、提及策略辅助工具，以及 envelope 辅助工具 | + | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助函数 | + | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助函数 | + | `plugin-sdk/messaging-targets` | 目标解析/匹配辅助函数 | + | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助函数 | + | `plugin-sdk/outbound-runtime` | 出站身份/发送委托辅助函数 | + | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助函数 | + | `plugin-sdk/agent-media-payload` | 旧版智能体媒体载荷构建器 | + | `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对和已配置绑定辅助函数 | + | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 | + | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 | + | `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助函数 | + | `plugin-sdk/channel-config-primitives` | 狭义的渠道配置 schema 基元 | + | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 | + | `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 | + | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助函数 | + | `plugin-sdk/group-access` | 共享群组访问决策辅助函数 | + | `plugin-sdk/direct-dm` | 共享直接私信认证/防护辅助函数 | + | `plugin-sdk/interactive-runtime` | 交互式回复载荷规范化/归约辅助函数 | + | `plugin-sdk/channel-inbound` | 入站去抖、提及匹配、提及策略辅助函数以及 envelope 辅助函数 | | `plugin-sdk/channel-send-result` | 回复结果类型 | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `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` | 狭义的 secret 契约辅助函数，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret 目标类型 | - | 子路径 | 关键导出项 | + | 子路径 | 关键导出 | | --- | --- | | `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-result` | 标准 OAuth 鉴权结果构建器 | - | `plugin-sdk/provider-auth-login` | 提供商插件共享的交互式登录辅助工具 | - | `plugin-sdk/provider-env-vars` | 提供商鉴权环境变量查找辅助工具 | + | `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API key 解析辅助函数 | + | `plugin-sdk/provider-auth-api-key` | API key 新手引导/profile 写入辅助函数，例如 `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | 标准 OAuth auth-result 构建器 | + | `plugin-sdk/provider-auth-login` | 提供商插件的共享交互式登录辅助函数 | + | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助函数 | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助工具，以及诸如 `normalizeNativeXaiModelId` 的模型 ID 规范化辅助工具 | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助函数 | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助工具 | - | `plugin-sdk/provider-web-fetch-contract` | 更窄的 web-fetch config/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Web-fetch 提供商注册/缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | 适用于不需要插件启用连线的提供商的更窄 web-search config/凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | 更窄的 web-search config/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` 以及有作用域的凭证设置器/获取器 | - | `plugin-sdk/provider-web-search` | Web 搜索提供商注册/缓存/运行时辅助工具 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似内容 | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 | - | `plugin-sdk/provider-onboard` | 新手引导 config 补丁辅助工具 | - | `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 | + | `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`，以及作用域化的凭证设置器/获取器 | + | `plugin-sdk/provider-web-search` | web-search 提供商注册/缓存/运行时辅助函数 | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似函数 | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助函数 | + | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 | + | `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助函数 | - - | 子路径 | 关键导出项 | + + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 | - | `plugin-sdk/approval-auth-runtime` | 审批者解析和同聊天操作鉴权辅助工具 | - | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤辅助工具 | - | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 | - | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 用于高频渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；如果更窄的 adapter/gateway 接口已足够，应优先使用它们 | - | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助工具 | - | `plugin-sdk/command-auth-native` | 原生命令鉴权 + 原生会话目标辅助工具 | - | `plugin-sdk/command-detection` | 共享命令检测辅助工具 | - | `plugin-sdk/command-surface` | 命令体规范化和命令接口辅助工具 | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 | + | `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天 action-auth 辅助函数 | + | `plugin-sdk/approval-client-runtime` | 原生执行审批 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/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 用于渠道/插件密钥接口的更窄密钥契约收集辅助工具 | - | `plugin-sdk/secret-ref-runtime` | 更窄的 `coerceSecretRef` 和 SecretRef 类型辅助工具，用于密钥契约/config 解析 | - | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和密钥收集辅助工具 | - | `plugin-sdk/ssrf-policy` | 主机允许列表和私有网络 SSRF 策略辅助工具 | - | `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/channel-secret-runtime` | 用于渠道/plugin secret 表面的狭义 secret 契约收集辅助函数 | + | `plugin-sdk/secret-ref-runtime` | 狭义的 `coerceSecretRef` 和 SecretRef 类型辅助函数，用于 secret 契约/配置解析 | + | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和 secret 收集辅助函数 | + | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 防护的 fetch，以及 SSRF 策略辅助函数 | + | `plugin-sdk/secret-input` | secret 输入解析辅助函数 | + | `plugin-sdk/webhook-ingress` | webhook 请求/目标辅助函数 | + | `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助函数 | - | 子路径 | 关键导出项 | + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 更广泛的运行时/日志/备份/插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 更窄的运行时 env、logger、timeout、retry 和 backoff 辅助工具 | - | `plugin-sdk/channel-runtime-context` | 通用渠道 runtime-context 注册与查找辅助工具 | + | `plugin-sdk/runtime` | 广义的运行时/日志/备份/插件安装辅助函数 | + | `plugin-sdk/runtime-env` | 狭义的运行时环境、logger、timeout、retry 和 backoff 辅助函数 | + | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助函数 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | 共享插件命令/hook/http/交互式辅助工具 | - | `plugin-sdk/hook-runtime` | 共享 webhook/内部 hook 管道辅助工具 | - | `plugin-sdk/lazy-runtime` | 延迟运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`, `createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | 进程 exec 辅助工具 | - | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 | - | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 | - | `plugin-sdk/config-runtime` | config 加载/写入辅助工具 | - | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化及重复/冲突检查，即使内置 Telegram 契约接口不可用时也适用 | - | `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、鉴权/配置文件辅助工具、原生路由/运行时辅助工具 | - | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、心跳、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 更窄的回复分发/完成辅助工具 | - | `plugin-sdk/reply-history` | 共享的短时间窗口回复历史辅助工具，例如 `buildHistoryContext`, `recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | 共享插件命令/hook/http/interactive 辅助函数 | + | `plugin-sdk/hook-runtime` | 共享 webhook/internal hook 管道辅助函数 | + | `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助函数，例如 `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | 进程执行辅助函数 | + | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助函数 | + | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助函数 | + | `plugin-sdk/config-runtime` | 配置加载/写入辅助函数 | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约表面不可用也可使用 | + | `plugin-sdk/approval-runtime` | exec/plugin 审批辅助函数、审批能力构建器、认证/profile 辅助函数、原生路由/运行时辅助函数 | + | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助函数、分块、分发、heartbeat、回复规划器 | + | `plugin-sdk/reply-dispatch-runtime` | 狭义的回复分发/完成辅助函数 | + | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助函数，例如 `buildHistoryContext`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 更窄的文本/Markdown 分块辅助工具 | - | `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 | - | `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助工具 | - | `plugin-sdk/routing` | 路由/会话键/账户绑定辅助工具，例如 `resolveAgentRoute`, `buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | 共享渠道/账户状态摘要辅助工具、运行时状态默认值和问题元数据辅助工具 | - | `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助工具 | - | `plugin-sdk/string-normalization-runtime` | slug/字符串规范化辅助工具 | + | `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/string-normalization-runtime` | slug/字符串规范化辅助函数 | | `plugin-sdk/request-url` | 从 fetch/request 类输入中提取字符串 URL | - | `plugin-sdk/run-command` | 带定时功能的命令运行器，返回规范化的 stdout/stderr 结果 | - | `plugin-sdk/param-readers` | 常用工具/CLI 参数读取器 | - | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 | + | `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/markdown-table-runtime` | Markdown 表格模式辅助工具 | - | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 | - | `plugin-sdk/file-lock` | 可重入文件锁辅助工具 | - | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 | - | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 | - | `plugin-sdk/agent-config-primitives` | 更窄的智能体运行时配置 schema 基元 | + | `plugin-sdk/temp-path` | 共享临时下载路径辅助函数 | + | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助函数 | + | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助函数 | + | `plugin-sdk/json-store` | 小型 JSON 状态读取/写入辅助函数 | + | `plugin-sdk/file-lock` | 可重入文件锁辅助函数 | + | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 | + | `plugin-sdk/acp-runtime` | ACP 运行时/会话和 reply-dispatch 辅助函数 | + | `plugin-sdk/agent-config-primitives` | 狭义的智能体运行时配置 schema 基元 | | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | - | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 | - | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 | + | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 | + | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 | | `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助基元 | - | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 | - | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 | - | `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 | - | `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 | - | `plugin-sdk/infra-runtime` | 系统事件/心跳辅助工具 | - | `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 | - | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 | - | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具，`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 封装后的 fetch、代理和 pinned 查找辅助工具 | - | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 | - | `plugin-sdk/retry-runtime` | 重试 config 和重试运行器辅助工具 | - | `plugin-sdk/agent-runtime` | 智能体目录/身份/workspace 辅助工具 | - | `plugin-sdk/directory-runtime` | 基于 config 的目录查询/去重 | + | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助函数 | + | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助函数 | + | `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助函数 | + | `plugin-sdk/provider-zai-endpoint` | Z.AI endpoint 检测辅助函数 | + | `plugin-sdk/infra-runtime` | 系统事件/heartbeat 辅助函数 | + | `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 | + | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助函数 | + | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和固定查找辅助函数 | + | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 | + | `plugin-sdk/retry-runtime` | retry 配置和 retry 运行器辅助函数 | + | `plugin-sdk/agent-runtime` | 智能体目录/身份/workspace 辅助函数 | + | `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/text-chunking` | 出站文本分块辅助工具 | - | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助工具 | - | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助工具 | - | `plugin-sdk/realtime-transcription` | 实时转写提供商类型和注册表辅助工具 | - | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 | + | `plugin-sdk/media-runtime` | 共享媒体抓取/转换/存储辅助函数，以及媒体载荷构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障切换辅助函数、候选项选择和模型缺失提示 | + | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图片/音频辅助导出 | + | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助函数，例如去除 assistant 可见文本、Markdown 渲染/分块/表格辅助函数、脱敏辅助函数、directive-tag 辅助函数以及安全文本工具 | + | `plugin-sdk/text-chunking` | 出站文本分块辅助函数 | + | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助函数 | + | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助函数 | + | `plugin-sdk/realtime-transcription` | 实时转录提供商类型和注册表辅助函数 | + | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 | | `plugin-sdk/image-generation` | 图像生成提供商类型 | - | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、鉴权和注册表辅助工具 | + | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障切换、认证和注册表辅助函数 | | `plugin-sdk/music-generation` | 音乐生成提供商/请求/结果类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 | + | `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/video-generation-core` | 共享视频生成类型、故障切换辅助函数、提供商查找和 model-ref 解析 | + | `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助函数 | + | `plugin-sdk/webhook-path` | webhook 路径规范化辅助函数 | + | `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助函数 | | `plugin-sdk/zod` | 面向插件 SDK 使用者重新导出的 `zod` | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - | 子路径 | 关键导出项 | + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助接口，用于管理器/config/文件/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 engine 导出项 | - | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出项 | - | `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出项 | - | `plugin-sdk/memory-core-host-multimodal` | Memory host multimodal 辅助工具 | - | `plugin-sdk/memory-core-host-query` | Memory host query 辅助工具 | - | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助工具 | - | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 | - | `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助工具 | - | `plugin-sdk/memory-host-core` | 面向供应商中立的 Memory host 核心运行时辅助工具别名 | - | `plugin-sdk/memory-host-events` | 面向供应商中立的 Memory host 事件日志辅助工具别名 | - | `plugin-sdk/memory-host-files` | 面向供应商中立的 Memory host 文件/运行时辅助工具别名 | - | `plugin-sdk/memory-host-markdown` | 面向 Memory 邻近插件的共享托管 Markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 用于访问搜索管理器的活动 Memory 运行时门面 | - | `plugin-sdk/memory-host-status` | 面向供应商中立的 Memory host 状态辅助工具别名 | - | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助接口 | + | `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 engine 导出 | + | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 | + | `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 | + | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助函数 | + | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助函数 | + | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助函数 | + | `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 辅助表面 | - | 系列 | 当前子路径 | 预期用途 | + | 家族 | 当前子路径 | 预期用途 | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 Browser 插件支持辅助工具（`browser-support` 仍是兼容性 barrel） | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时接口 | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时接口 | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 | - | 渠道专用辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容/辅助接口 | - | 鉴权/插件专用辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 Browser 插件支持辅助函数（`browser-support` 仍是兼容性 barrel） | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时表面 | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时表面 | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助表面 | + | 渠道特定辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性/辅助接缝 | + | 认证/插件特定辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接缝；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | ## 注册 API -`register(api)` 回调会收到一个 `OpenClawPluginApi` 对象，其中包含以下方法： +`register(api)` 回调会收到一个带有以下方法的 `OpenClawPluginApi` 对象： ### 能力注册 -| 方法 | 注册内容 | -| ---------------------------------------------- | ---------------------------- | -| `api.registerProvider(...)` | 文本推理（LLM） | -| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | -| `api.registerChannel(...)` | 消息渠道 | -| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | -| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转写 | -| `api.registerRealtimeVoiceProvider(...)` | 双向实时语音会话 | -| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 | -| `api.registerImageGenerationProvider(...)` | 图像生成 | -| `api.registerMusicGenerationProvider(...)` | 音乐生成 | -| `api.registerVideoGenerationProvider(...)` | 视频生成 | -| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 | -| `api.registerWebSearchProvider(...)` | Web 搜索 | +| 方法 | 注册内容 | +| ------------------------------------------------ | ------------------------ | +| `api.registerProvider(...)` | 文本推理（LLM） | +| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | +| `api.registerChannel(...)` | 消息渠道 | +| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | +| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 | +| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 | +| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 | +| `api.registerImageGenerationProvider(...)` | 图像生成 | +| `api.registerMusicGenerationProvider(...)` | 音乐生成 | +| `api.registerVideoGenerationProvider(...)` | 视频生成 | +| `api.registerWebFetchProvider(...)` | Web 抓取 / 爬取提供商 | +| `api.registerWebSearchProvider(...)` | Web 搜索 | -### 工具与命令 +### 工具和命令 -| 方法 | 注册内容 | -| ----------------------------- | ----------------------------------------- | +| 方法 | 注册内容 | +| ------------------------------- | --------------------------------------------- | | `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） | -| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | +| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | ### 基础设施 -| 方法 | 注册内容 | -| -------------------------------------------- | ------------------------------- | -| `api.registerHook(events, handler, opts?)` | 事件 hook | -| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | -| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | -| `api.registerCli(registrar, opts?)` | CLI 子命令 | -| `api.registerService(service)` | 后台服务 | -| `api.registerInteractiveHandler(registration)` | 交互式处理器 | -| `api.registerMemoryPromptSupplement(builder)` | 附加型 Memory 邻近提示区段 | -| `api.registerMemoryCorpusSupplement(adapter)` | 附加型 Memory 搜索/读取语料库 | +| 方法 | 注册内容 | +| ---------------------------------------------- | -------------------------------- | +| `api.registerHook(events, handler, opts?)` | 事件 hook | +| `api.registerHttpRoute(params)` | Gateway 网关 HTTP endpoint | +| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | +| `api.registerCli(registrar, opts?)` | CLI 子命令 | +| `api.registerService(service)` | 后台服务 | +| `api.registerInteractiveHandler(registration)` | 交互处理器 | +| `api.registerMemoryPromptSupplement(builder)` | 增量 Memory 邻接提示区段 | +| `api.registerMemoryCorpusSupplement(adapter)` | 增量 Memory 搜索/读取语料库 | -保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用插件专用前缀。 +保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用插件特定前缀。 ### CLI 注册元数据 `api.registerCli(registrar, opts?)` 接受两类顶层元数据： - `commands`：由注册器拥有的显式命令根 -- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析期命令描述符 +- `descriptors`：用于根 CLI 帮助、路由和惰性插件 CLI 注册的解析期命令描述符 -如果你希望插件命令在普通根 CLI 路径中保持延迟加载，请提供覆盖该注册器暴露的每个顶层命令根的 `descriptors`。 +如果你希望插件命令在常规根 CLI 路径中保持惰性加载，请提供 `descriptors`，覆盖该注册器暴露的每个顶层命令根。 ```typescript api.registerCli( @@ -344,7 +345,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "管理 Matrix 账户、验证、设备和配置文件状态", + description: "Manage Matrix accounts, verification, devices, and profile state", hasSubcommands: true, }, ], @@ -352,107 +353,112 @@ api.registerCli( ); ``` -仅在你不需要延迟根 CLI 注册时才单独使用 `commands`。这种急切兼容路径仍受支持，但它不会安装由描述符支持的占位符以实现解析期延迟加载。 +仅在你不需要惰性根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍受支持，但它不会安装由 descriptor 支持的占位符来实现解析期惰性加载。 ### CLI 后端注册 -`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（如 `codex-cli`）的默认 config。 +`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。 - 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。 - 后端 `config` 使用与 `agents.defaults.cliBackends.` 相同的结构。 -- 用户 config 仍然优先生效。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 适配器 | 方法 | 注册内容 | -| -------------------------------------------- | ----------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory embedding 适配器 | +| ---------------------------------------------- | ----------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory embedding 适配器 | - `registerMemoryCapability` 是首选的独占 Memory 插件 API。 -- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`，这样配套插件就可以通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的 Memory artifact，而不是深入某个特定 Memory 插件的私有布局。 +- `registerMemoryCapability` 还可以暴露 `publicArtifacts.listArtifacts(...)`，以便配套插件可以通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的 Memory 工件，而不是深入访问特定 Memory 插件的私有布局。 - `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占 Memory 插件 API。 -- `registerMemoryEmbeddingProvider` 允许活动 Memory 插件注册一个或多个 embedding 适配器 ID（例如 `openai`、`gemini` 或自定义的插件定义 ID）。 -- 用户 config，例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`，会根据这些已注册的适配器 ID 进行解析。 +- `registerMemoryEmbeddingProvider` 允许活动 Memory 插件注册一个或多个 embedding 适配器 id（例如 `openai`、`gemini` 或自定义插件定义的 id）。 +- 用户配置（例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会根据这些已注册的适配器 id 进行解析。 ### 事件与生命周期 | 方法 | 作用 | -| ------------------------------------------ | ----------------------- | +| -------------------------------------------- | ----------------------- | | `api.on(hookName, handler, opts?)` | 类型化生命周期 hook | | `api.onConversationBindingResolved(handler)` | 会话绑定回调 | ### Hook 决策语义 -- `before_tool_call`：返回 `{ block: true }` 为终局决定。一旦任一处理器设置它，将跳过更低优先级的处理器。 -- `before_tool_call`：返回 `{ block: false }` 视为未作决定（与省略 `block` 相同），而不是覆盖。 -- `before_install`：返回 `{ block: true }` 为终局决定。一旦任一处理器设置它，将跳过更低优先级的处理器。 -- `before_install`：返回 `{ block: false }` 视为未作决定（与省略 `block` 相同），而不是覆盖。 -- `reply_dispatch`：返回 `{ handled: true, ... }` 为终局决定。一旦任一处理器声明已分发，将跳过更低优先级的处理器和默认模型分发路径。 -- `message_sending`：返回 `{ cancel: true }` 为终局决定。一旦任一处理器设置它，将跳过更低优先级的处理器。 -- `message_sending`：返回 `{ cancel: false }` 视为未作决定（与省略 `cancel` 相同），而不是覆盖。 +- `before_tool_call`：返回 `{ block: true }` 为终止性决定。一旦任一处理器设置它，就会跳过优先级更低的处理器。 +- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。 +- `before_install`：返回 `{ block: true }` 为终止性决定。一旦任一处理器设置它，就会跳过优先级更低的处理器。 +- `before_install`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。 +- `reply_dispatch`：返回 `{ handled: true, ... }` 为终止性决定。一旦任一处理器声明已分发，就会跳过优先级更低的处理器以及默认模型分发路径。 +- `message_sending`：返回 `{ cancel: true }` 为终止性决定。一旦任一处理器设置它，就会跳过优先级更低的处理器。 +- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（与省略 `cancel` 相同），而不是覆盖。 ### API 对象字段 -| 字段 | 类型 | 说明 | -| ----------------------- | ------------------------- | ----------------------------------------------------------------------------------------- | -| `api.id` | `string` | 插件 ID | -| `api.name` | `string` | 显示名称 | -| `api.version` | `string?` | 插件版本（可选） | -| `api.description` | `string?` | 插件描述（可选） | -| `api.source` | `string` | 插件源路径 | -| `api.rootDir` | `string?` | 插件根目录（可选） | -| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动的内存中运行时快照） | -| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件专用配置 | -| `api.runtime` | `PluginRuntime` | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | 有作用域的 logger（`debug`、`info`、`warn`、`error`） | -| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是轻量级的完整入口启动前/设置阶段窗口 | -| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | +| 字段 | 类型 | 说明 | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------ | +| `api.id` | `string` | 插件 id | +| `api.name` | `string` | 显示名称 | +| `api.version` | `string?` | 插件版本（可选） | +| `api.description` | `string?` | 插件说明（可选） | +| `api.source` | `string` | 插件源路径 | +| `api.rootDir` | `string?` | 插件根目录（可选） | +| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动的内存运行时快照） | +| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件专属配置 | +| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | 作用域 logger（`debug`, `info`, `warn`, `error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置前的轻量级预启动/设置窗口 | +| `api.resolvePath(input)` | `(string) => string` | 相对于插件根目录解析路径 | ## 内部模块约定 -在你的插件内部，请使用本地 barrel 文件进行内部导入： +在你的插件内部，使用本地 barrel 文件进行内部导入： ``` my-plugin/ - api.ts # 供外部使用者使用的公共导出项 - runtime-api.ts # 仅供内部使用的运行时导出项 + api.ts # 面向外部使用者的公共导出 + runtime-api.ts # 仅供内部使用的运行时导出 index.ts # 插件入口点 - setup-entry.ts # 仅设置使用的轻量入口点（可选） + setup-entry.ts # 轻量级仅设置入口（可选） ``` - 不要在生产代码中通过 `openclaw/plugin-sdk/` 导入你自己的插件。内部导入应通过 `./api.ts` 或 `./runtime-api.ts`。SDK 路径仅是对外契约。 + 永远不要在生产代码中通过 `openclaw/plugin-sdk/` + 导入你自己的插件。请通过 `./api.ts` 或 + `./runtime-api.ts` 进行内部导入。SDK 路径仅是对外契约。 -通过 facade 加载的内置插件公共接口（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）现在在 OpenClaw 已运行时会优先使用活动运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上解析得到的配置文件。 +门面加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似公共入口文件）现在会在 OpenClaw 已运行时优先使用活动运行时配置快照。如果尚不存在运行时快照，则会回退到磁盘上已解析的配置文件。 -当某个辅助工具本质上是提供商专用、且尚不适合放入通用 SDK 子路径时，提供商插件也可以暴露一个更窄的插件本地契约 barrel。当前内置示例：Anthropic 提供商将其 Claude 流辅助工具保留在自己的公共 `api.ts` / `contract-api.ts` 接口中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升到通用 `plugin-sdk/*` 契约中。 +当某个辅助函数有意是提供商专属且暂时不属于通用 SDK 子路径时，提供商插件也可以暴露一个狭义的插件本地契约 barrel。当前内置示例：Anthropic 提供商将其 Claude 流辅助函数保留在自己的公共 `api.ts` / `contract-api.ts` 接缝中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升到通用 `plugin-sdk/*` 契约中。 其他当前内置示例： -- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、默认模型辅助工具和实时提供商构建器 -- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及新手引导/config 辅助工具 +- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、默认模型辅助函数和实时提供商构建器 +- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及新手引导/配置辅助函数 - 扩展生产代码也应避免导入 `openclaw/plugin-sdk/`。如果某个辅助工具确实是共享的，应将其提升到中立的 SDK 子路径，例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他面向能力的接口，而不是将两个插件耦合在一起。 + 扩展生产代码也应避免导入 `openclaw/plugin-sdk/`。 + 如果某个辅助函数确实需要共享，请将其提升为中立的 SDK 子路径， + 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他 + 面向能力的表面，而不是将两个插件耦合在一起。 ## 相关内容 - [入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry` 选项 -- [运行时辅助工具](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考 +- [运行时辅助函数](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考 - [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、清单、配置 schema - [测试](/zh-CN/plugins/sdk-testing) — 测试工具和 lint 规则 -- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用接口迁移 -- [插件内部原理](/zh-CN/plugins/architecture) — 深入的架构和能力模型 +- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用表面迁移 +- [插件内部机制](/zh-CN/plugins/architecture) — 深入架构和能力模型