diff --git a/docs/zh-CN/plugins/compatibility.md b/docs/zh-CN/plugins/compatibility.md index 7ccb74c44..723e420a3 100644 --- a/docs/zh-CN/plugins/compatibility.md +++ b/docs/zh-CN/plugins/compatibility.md @@ -6,40 +6,40 @@ read_when: summary: 插件兼容性契约、弃用元数据和迁移预期 title: 插件兼容性 x-i18n: - generated_at: "2026-04-28T00:32:28Z" + generated_at: "2026-04-28T01:06:39Z" model: gpt-5.4 provider: openai - source_hash: f097e51beb57790dc8b491793edb398adf3ab0457cc2404f5fe4b1c89159d112 + source_hash: 9cb004d9959f1892f3bebcdfb9bee3fd78fc3322a2cbee4e8078c41a3f6706c6 source_path: plugins/compatibility.md workflow: 15 --- -OpenClaw 会在移除旧版插件契约之前，通过具名兼容性适配器继续接通较旧的插件契约。这样可以在 SDK、清单、设置、配置和智能体运行时契约演进的过程中，保护现有的内置插件和外部插件。 +OpenClaw 会在移除旧版插件契约之前，通过具名兼容性适配器继续接入这些旧契约。这样可以在 SDK、清单、设置、配置和智能体运行时契约不断演进时，保护现有的内置插件和外部插件。 ## 兼容性注册表 -插件兼容性契约记录在核心注册表 `src/plugins/compat/registry.ts` 中。 +插件兼容性契约会在核心注册表 `src/plugins/compat/registry.ts` 中跟踪。 每条记录都包含： - 一个稳定的兼容性代码 - 状态：`active`、`deprecated`、`removal-pending` 或 `removed` -- 所有者：SDK、配置、设置、渠道、提供商、插件执行、智能体运行时或核心 +- 所属方：SDK、配置、设置、渠道、提供商、插件执行、智能体运行时或核心 - 适用时的引入日期和弃用日期 - 替代方案指引 -- 覆盖旧行为和新行为的文档、诊断信息和测试 +- 覆盖旧行为和新行为的文档、诊断和测试 -该注册表是维护者规划和未来插件检查器检查的来源。如果某项面向插件的行为发生变化，请在添加适配器的同一项变更中新增或更新对应的兼容性记录。 +该注册表是维护者规划和未来插件检查器检查的来源。如果某个面向插件的行为发生变化，请在添加适配器的同一变更中新增或更新对应的兼容性记录。 -Doctor 修复和迁移兼容性会单独记录在 `src/commands/doctor/shared/deprecation-compat.ts`。这些记录覆盖旧版配置结构、安装账本布局以及修复垫片；即使运行时兼容路径已被移除，它们仍可能需要继续保留。 +Doctor 修复和迁移兼容性会在 `src/commands/doctor/shared/deprecation-compat.ts` 中单独跟踪。这些记录涵盖旧版配置结构、安装台账布局以及修复垫片；即使运行时兼容路径被移除，它们也可能仍需继续保留。 -发布巡检应同时检查这两个注册表。不要仅因为对应的运行时或配置兼容性记录已过期，就删除某个 Doctor 迁移；首先要确认不存在任何仍受支持、且仍需要该修复的升级路径。还要在发布规划期间重新验证每条替代说明，因为随着提供商和渠道移出核心，插件归属和配置范围可能会发生变化。 +发布前的全面检查应同时检查这两个注册表。不要仅因为对应的运行时或配置兼容性记录已过期，就删除某个 Doctor 迁移；首先要确认不存在仍然需要该修复的受支持升级路径。还要在发布规划期间重新验证每条替代说明，因为随着提供商和渠道移出核心，插件归属和配置范围可能会发生变化。 ## 插件检查器包 -插件检查器应位于核心 OpenClaw 仓库之外，作为一个独立的包或仓库，并以带版本的兼容性契约和清单契约为基础。 +插件检查器应作为独立的包或仓库，存放在 OpenClaw 核心仓库之外，并以带版本的兼容性契约和清单契约为基础。 -第一天上线的 CLI 应该是： +首个版本的 CLI 应该是： ```sh openclaw-plugin-inspector ./my-plugin @@ -47,57 +47,57 @@ openclaw-plugin-inspector ./my-plugin 它应输出： -- 清单 / schema 验证 -- 正在检查的契约兼容版本 +- 清单 / 模式验证 +- 正在检查的契约兼容性版本 - 安装 / 来源元数据检查 - 冷路径导入检查 - 弃用和兼容性警告 -在 CI 注释中使用 `--json` 可获得稳定的机器可读输出。OpenClaw 核心应暴露检查器可消费的契约和夹具，但不应从主 `openclaw` 包发布检查器二进制文件。 +在 CI 注释中，如果需要稳定的机器可读输出，请使用 `--json`。OpenClaw 核心应暴露检查器可消费的契约和夹具，但不应从主 `openclaw` 包发布该检查器二进制文件。 ## 弃用策略 -OpenClaw 不应在引入替代方案的同一版本中移除已文档化的插件契约。 +OpenClaw 不应在引入某个插件契约替代方案的同一版本中移除已文档化的原契约。 迁移顺序如下： 1. 添加新契约。 -2. 通过具名兼容性适配器继续接通旧行为。 -3. 当插件作者可以采取行动时，发出诊断信息或警告。 +2. 通过具名兼容性适配器继续接入旧行为。 +3. 当插件作者可以采取行动时，发出诊断或警告。 4. 记录替代方案和时间线。 5. 测试旧路径和新路径。 6. 等待已宣布的迁移窗口结束。 -7. 仅在获得明确的破坏性发布批准后再移除。 +7. 只有在获得明确的破坏性发布批准后才移除。 -已弃用记录必须包含警告开始日期、替代方案、文档链接，以及不晚于警告开始后三个月的最终移除日期。除非维护者明确决定该兼容路径将永久保留并将其标记为 `active`，否则不要添加移除时间窗口不明确的已弃用兼容路径。 +已弃用记录必须包含警告开始日期、替代方案、文档链接，以及不晚于警告开始后三个月的最终移除日期。除非维护者明确决定它应作为永久兼容性保留并将其标记为 `active`，否则不要添加一个移除窗口不明确的已弃用兼容路径。 ## 当前兼容性领域 当前的兼容性记录包括： - 旧版宽泛 SDK 导入，例如 `openclaw/plugin-sdk/compat` -- 旧版仅钩子插件形态以及 `before_agent_start` -- 旧版 `activate(api)` 插件入口点，同时插件正迁移到 `register(api)` -- 旧版 SDK 别名，例如 `openclaw/extension-api`、`openclaw/plugin-sdk/channel-runtime`、`openclaw/plugin-sdk/command-auth` 状态构建器、`openclaw/plugin-sdk/test-utils`，以及 `ClawdbotConfig` / `OpenClawSchemaType` 类型别名 +- 旧版仅钩子插件结构和 `before_agent_start` +- 旧版 `activate(api)` 插件入口点，在插件迁移到 `register(api)` 期间继续支持 +- 旧版 SDK 别名，例如 `openclaw/extension-api`、`openclaw/plugin-sdk/channel-runtime`、`openclaw/plugin-sdk/command-auth` Status 构建器、`openclaw/plugin-sdk/test-utils`（由更聚焦的 `openclaw/plugin-sdk/*` 测试子路径替代），以及 `ClawdbotConfig` / `OpenClawSchemaType` 类型别名 - 内置插件允许列表和启用行为 - 旧版提供商 / 渠道环境变量清单元数据 -- 旧版提供商插件钩子和类型别名，同时提供商正迁移到显式目录、认证、思考、回放和传输钩子 +- 旧版提供商插件钩子和类型别名，在提供商迁移到显式目录、认证、思考、回放和传输钩子期间继续支持 - 旧版运行时别名，例如 `api.runtime.taskFlow`、`api.runtime.subagent.getSession`、`api.runtime.stt`，以及已弃用的 `api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)` -- 旧版 memory 插件拆分注册方式，同时 memory 插件正迁移到 `registerMemoryCapability` -- 旧版渠道 SDK 辅助工具，用于原生消息 schema、提及门控、入站信封格式化和批准能力嵌套 -- 旧版渠道路由键和可比较目标辅助别名，同时插件正迁移到 `openclaw/plugin-sdk/channel-route` +- 旧版 memory 插件拆分注册方式，在 memory 插件迁移到 `registerMemoryCapability` 期间继续支持 +- 旧版渠道 SDK 辅助方法，用于原生消息模式、提及门控、入站信封格式化和审批能力嵌套 +- 旧版渠道路由键和可比较目标辅助别名，在插件迁移到 `openclaw/plugin-sdk/channel-route` 期间继续支持 - 正在被清单贡献归属替代的激活提示 -- `setup-api` 运行时回退，同时设置描述符正迁移到冷路径 `setup.requiresRuntime: false` 元数据 -- 提供商 `discovery` 钩子，同时提供商目录钩子正迁移到 `catalog.run(...)` -- 渠道 `showConfigured` / `showInSetup` 元数据，同时渠道包正迁移到 `openclaw.channel.exposure` -- 旧版 runtime-policy 配置键，同时 Doctor 正将操作员迁移到 `agentRuntime` -- 已生成的内置渠道配置元数据回退，同时注册表优先的 `channelConfigs` 元数据正在落地 -- 持久化插件注册表禁用和安装迁移环境变量标志，同时修复流程正将操作员迁移到 `openclaw plugins registry --refresh` 和 `openclaw doctor --fix` -- 旧版由插件持有的 web search、web fetch 和 x_search 配置路径，同时 Doctor 正将它们迁移到 `plugins.entries..config` -- 旧版 `plugins.installs` 手写配置和内置插件加载路径别名，同时安装元数据正迁移到由状态管理的插件账本中 +- `setup-api` 运行时回退，在设置描述符迁移到冷路径 `setup.requiresRuntime: false` 元数据期间继续支持 +- 提供商 `discovery` 钩子，在提供商目录钩子迁移到 `catalog.run(...)` 期间继续支持 +- 渠道 `showConfigured` / `showInSetup` 元数据，在渠道包迁移到 `openclaw.channel.exposure` 期间继续支持 +- 旧版运行时策略配置键，在 Doctor 将操作员迁移到 `agentRuntime` 期间继续支持 +- 生成的内置渠道配置元数据回退，在注册表优先的 `channelConfigs` 元数据落地期间继续支持 +- 持久化插件注册表禁用和安装迁移环境变量标志，在修复流程将操作员迁移到 `openclaw plugins registry --refresh` 和 `openclaw doctor --fix` 期间继续支持 +- 旧版插件自有的 web search、web fetch 和 x_search 配置路径，在 Doctor 将它们迁移到 `plugins.entries..config` 期间继续支持 +- 旧版 `plugins.installs` 手写配置和内置插件加载路径别名，在安装元数据迁移到状态管理的插件台账期间继续支持 -新的插件代码应优先使用注册表和特定迁移指南中列出的替代方案。现有插件可以继续使用兼容路径，直到文档、诊断信息和发布说明宣布移除窗口。 +新插件代码应优先使用注册表和特定迁移指南中列出的替代方案。现有插件可以继续使用兼容路径，直到文档、诊断和发布说明宣布移除窗口。 ## 发布说明 -发布说明应包含即将到来的插件弃用项、目标日期以及迁移文档链接。必须先发出该警告，然后兼容路径才能转为 `removal-pending` 或 `removed`。 +发布说明应包含即将到来的插件弃用信息，并附上目标日期和迁移文档链接。必须先发出这类警告，兼容路径才能转为 `removal-pending` 或 `removed`。 diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index 07756227b..abbf261f4 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -2,75 +2,71 @@ read_when: - 你看到了 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告 - 你看到了 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告 - - 你在 OpenClaw 2026.4.25 之前使用过 `api.registerEmbeddedExtensionFactory` + - 你在 OpenClaw 2026.4.25 之前使用了 `api.registerEmbeddedExtensionFactory` - 你正在将一个插件更新到现代插件架构 - 你在维护一个外部 OpenClaw 插件 sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-28T00:32:57Z" + generated_at: "2026-04-28T01:06:47Z" model: gpt-5.4 provider: openai - source_hash: d3c04ccf641cbcaf34c015d079e5403be738a87fc4bddd974b14455c9cafe0ee + source_hash: 0620977a2ded8518b00fa7b14c8860ff351530926af76c02d08c699028f0fbc3 source_path: plugins/sdk-migration.md workflow: 15 --- -OpenClaw 已经从宽泛的向后兼容层迁移到现代插件架构，后者提供聚焦且有文档说明的导入路径。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 +OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，提供聚焦且有文档说明的导入路径。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。 -## 正在发生什么变化 +## 正在发生的变化 -旧插件系统提供了两个高度开放的接口，使插件能够通过单一入口点导入所需的任何内容： +旧插件系统提供了两个开放度很高的接口面，允许插件从单一入口点导入所需的任何内容： -- **`openclaw/plugin-sdk/compat`** — 单一导入路径，重新导出数十个辅助工具。它的引入是为了在构建新插件架构期间，让较旧的基于钩子的插件继续工作。 -- **`openclaw/plugin-sdk/infra-runtime`** — 宽泛的运行时辅助 barrel，混合了系统事件、心跳状态、投递队列、fetch/proxy 辅助工具、文件辅助工具、审批类型以及其他不相关的实用工具。 -- **`openclaw/plugin-sdk/config-runtime`** — 宽泛的配置兼容性 barrel，在迁移窗口期间仍然保留了已弃用的直接加载/写入辅助工具。 -- **`openclaw/extension-api`** — 一个桥接层，使插件能够直接访问宿主侧辅助工具，例如嵌入式智能体运行器。 -- **`api.registerEmbeddedExtensionFactory(...)`** — 已移除的、仅限 Pi 的内置扩展钩子，它曾可观察嵌入式运行器事件，例如 `tool_result`。 +- **`openclaw/plugin-sdk/compat`** — 一个单一导入路径，重新导出了几十个辅助工具。它的引入是为了在构建新插件架构期间，让旧的基于钩子的插件继续工作。 +- **`openclaw/plugin-sdk/infra-runtime`** — 一个宽泛的运行时辅助 barrel，混合了系统事件、heartbeat 状态、投递队列、fetch/proxy 辅助工具、文件辅助工具、审批类型以及无关的实用工具。 +- **`openclaw/plugin-sdk/config-runtime`** — 一个宽泛的配置兼容性 barrel，在迁移窗口期间仍然承载已弃用的直接加载/写入辅助工具。 +- **`openclaw/extension-api`** — 一个桥接层，让插件能够直接访问宿主侧辅助工具，例如内嵌智能体运行器。 +- **`api.registerEmbeddedExtensionFactory(...)`** — 一个已移除的、仅限 Pi 的内置扩展钩子，它曾可观察内嵌运行器事件，例如 `tool_result`。 -这些宽泛的导入接口现已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件应在下一个主要版本移除它们之前完成迁移。仅限 Pi 的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。 +这些宽泛的导入接口面现已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件应在下一个主要版本移除它们之前完成迁移。仅限 Pi 的内嵌扩展工厂注册 API 已被移除；请改用工具结果中间件。 -OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已有文档说明的插件行为。破坏性契约变更必须先经过兼容性适配器、诊断、文档和弃用窗口。这一原则适用于 SDK 导入、manifest 字段、设置 API、钩子和运行时注册行为。 +OpenClaw 不会在引入替代方案的同一次变更中，移除或重新解释已有文档说明的插件行为。破坏性契约变更必须先经过兼容适配器、诊断信息、文档以及弃用窗口。这适用于 SDK 导入、manifest 字段、设置 API、钩子和运行时注册行为。 - 向后兼容层将在未来的主要版本中移除。 - 仍然从这些接口导入的插件会在那时失效。 - 仅限 Pi 的嵌入式扩展工厂注册已无法再加载。 + 向后兼容层将在未来的主要版本中移除。届时，仍从这些接口面导入的插件将会失效。仅限 Pi 的内嵌扩展工厂注册现在已经不再加载。 -## 为什么会这样变更 +## 为什么会有这项变化 -旧方法带来了这些问题： +旧方法会导致一些问题： - **启动缓慢** — 导入一个辅助工具会加载几十个无关模块 -- **循环依赖** — 宽泛的重新导出很容易造成导入循环 -- **API 接口不清晰** — 无法判断哪些导出是稳定接口，哪些是内部实现 +- **循环依赖** — 宽泛的重新导出让导入循环更容易出现 +- **API 接口面不清晰** — 无法判断哪些导出是稳定的，哪些属于内部实现 -现代插件 SDK 修复了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、独立的模块，具备清晰的用途和有文档说明的契约。 +现代插件 SDK 修复了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含模块，具有明确用途和有文档说明的契约。 -面向内置渠道的旧版提供商便利接口也已移除。 -带有渠道品牌的辅助接口属于私有 mono-repo 快捷方式，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内部，请将提供商自有辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 +用于内置渠道的旧版 provider 便捷接缝也已移除。带有渠道品牌的辅助工具接缝属于私有 mono-repo 快捷方式，而不是稳定的插件契约。请改用狭义的通用 SDK 子路径。在内置插件工作区中，请将 provider 自有辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 -当前内置提供商示例： +当前内置 provider 示例： -- Anthropic 将 Claude 专用的流辅助工具保留在其自己的 `api.ts` / - `contract-api.ts` 接口中 -- OpenAI 将提供商构建器、默认模型辅助工具和实时提供商构建器保留在其自己的 `api.ts` 中 -- OpenRouter 将提供商构建器以及新手引导/配置辅助工具保留在其自己的 `api.ts` 中 +- Anthropic 将 Claude 专用的流式辅助工具保留在它自己的 `api.ts` / `contract-api.ts` 接缝中 +- OpenAI 将 provider builder、default-model 辅助工具以及 realtime provider builder 保留在它自己的 `api.ts` 中 +- OpenRouter 将 provider builder 和 onboarding/config 辅助工具保留在它自己的 `api.ts` 中 ## 兼容性策略 对于外部插件，兼容性工作遵循以下顺序： 1. 添加新契约 -2. 通过兼容性适配器继续保留旧行为 -3. 发出诊断或警告，明确指出旧路径及其替代方案 +2. 通过兼容适配器保持旧行为仍然可用 +3. 发出诊断信息或警告，明确指出旧路径和替代方案 4. 在测试中覆盖两条路径 -5. 记录弃用和迁移路径 -6. 仅在公告的迁移窗口结束后移除，通常是在主要版本中 +5. 记录弃用信息和迁移路径 +6. 仅在已公告的迁移窗口结束后移除，通常是在主要版本中 -如果某个 manifest 字段仍然被接受，那么在文档和诊断另有说明之前，插件作者都可以继续使用它。新代码应优先使用有文档说明的替代方案，但现有插件不应在普通次要版本发布期间损坏。 +如果某个 manifest 字段仍然被接受，插件作者就可以继续使用它，直到文档和诊断信息另行说明为止。新代码应优先使用文档说明的替代方案，但现有插件不应在普通次要版本中被破坏。 ## 如何迁移 @@ -78,9 +74,9 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 内置插件应停止直接调用 `api.runtime.config.loadConfig()` 和 - `api.runtime.config.writeConfigFile(...)`。应优先使用当前活跃调用路径中已经传入的配置。对于需要当前进程快照的长生命周期处理器，可以使用 `api.runtime.config.current()`。长生命周期的智能体工具应在 `execute` 内使用工具上下文的 `ctx.getRuntimeConfig()`，这样即使工具创建于配置写入之前，也仍能看到已刷新的运行时配置。 + `api.runtime.config.writeConfigFile(...)`。应优先使用已经传入当前调用路径的配置。需要当前进程快照的长生命周期处理器可以使用 `api.runtime.config.current()`。长生命周期的智能体工具应在 `execute` 内使用工具上下文的 `ctx.getRuntimeConfig()`，这样即使工具是在配置写入之前创建的，也仍能看到刷新后的运行时配置。 - 配置写入必须通过事务性辅助工具完成，并选择写入后的策略： + 配置写入必须通过事务性辅助工具进行，并选择一种写入后策略： ```typescript await api.runtime.config.mutateConfigFile({ @@ -91,17 +87,18 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 }); ``` - 当调用方明确知道该变更需要干净重启 Gateway 网关时，请使用 + 当调用方明确知道该更改需要一次干净的 Gateway 网关重启时，请使用 `afterWrite: { mode: "restart", reason: "..." }`；只有当调用方自行负责后续处理并且有意抑制重载规划器时，才使用 `afterWrite: { mode: "none", reason: "..." }`。 - 变更结果包含一个带类型的 `followUp` 摘要，供测试和日志使用；Gateway 网关仍负责应用或调度重启。 - `loadConfig` 和 `writeConfigFile` 在迁移窗口期间仍作为外部插件的已弃用兼容性辅助工具保留，并会通过 `runtime-config-load-write` 兼容性代码发出一次警告。内置插件和仓库运行时代码受以下扫描器护栏保护： + 变更结果会包含一个带类型的 `followUp` 摘要，供测试和日志使用；Gateway 网关仍然负责应用或调度重启。 + `loadConfig` 和 `writeConfigFile` 在迁移窗口期间仍作为外部插件的已弃用兼容辅助工具保留，并会以 + `runtime-config-load-write` 兼容代码发出一次警告。内置插件和仓库运行时代码受到 `pnpm check:deprecated-internal-config-api` 和 - `pnpm check:no-runtime-action-load-config`：新的生产插件用法会被直接判定失败，直接配置写入会失败，Gateway 网关服务器方法必须使用请求运行时快照，运行时渠道发送/操作/客户端辅助工具必须从其边界接收配置，长生命周期运行时模块不得存在环境式 `loadConfig()` 调用。 + `pnpm check:no-runtime-action-load-config` + 中扫描器护栏的保护：新的生产插件用法会被直接判失败，直接配置写入会失败，Gateway 网关服务器方法必须使用请求运行时快照，运行时渠道 send/action/client 辅助工具必须从其边界接收配置，而长生命周期运行时模块中不允许存在任何环境式 `loadConfig()` 调用。 新插件代码也应避免导入宽泛的 - `openclaw/plugin-sdk/config-runtime` - 兼容性 barrel。请使用与任务匹配的窄化 SDK 子路径： + `openclaw/plugin-sdk/config-runtime` 兼容性 barrel。请使用与任务匹配的狭义 SDK 子路径： | 需求 | 导入 | | --- | --- | @@ -112,17 +109,17 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | 会话存储辅助工具 | `openclaw/plugin-sdk/session-store-runtime` | | Markdown 表格配置 | `openclaw/plugin-sdk/markdown-table-runtime` | | 组策略运行时辅助工具 | `openclaw/plugin-sdk/runtime-group-policy` | - | Secret 输入解析 | `openclaw/plugin-sdk/secret-input-runtime` | + | secret 输入解析 | `openclaw/plugin-sdk/secret-input-runtime` | | 模型/会话覆盖 | `openclaw/plugin-sdk/model-session-runtime` | - 内置插件及其测试对这个宽泛 barrel 受扫描器保护，因此导入和 mock 都会保持局部化，只覆盖其所需行为。这个宽泛 barrel 仍然存在以保持外部兼容性，但新代码不应依赖它。 + 内置插件及其测试受到扫描器保护，禁止使用该宽泛 barrel，因此导入和 mock 都会局部化到它们所需的行为。该宽泛 barrel 仍然存在以兼容外部插件，但新代码不应再依赖它。 内置插件必须将仅限 Pi 的 - `api.registerEmbeddedExtensionFactory(...)` - 工具结果处理器替换为运行时中立的中间件。 + `api.registerEmbeddedExtensionFactory(...)` 工具结果处理器替换为 + runtime-neutral 中间件。 ```typescript // Pi 和 Codex 运行时动态工具 @@ -143,34 +140,35 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 } ``` - 外部插件不能注册工具结果中间件，因为它可以在模型看到高信任工具输出之前对其进行重写。 + 外部插件不能注册工具结果中间件，因为它会在模型看到高信任度工具输出之前对其进行改写。 - - 支持审批的渠道插件现在通过 - `approvalCapability.nativeRuntime` - 加上共享运行时上下文注册表来暴露原生审批行为。 + + 具备审批能力的渠道插件现在通过 + `approvalCapability.nativeRuntime` 以及共享的 runtime-context registry + 暴露原生审批行为。 - 关键变更： + 关键变化： - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 `approvalCapability.nativeRuntime` - - 将审批专用的认证/投递从旧版 `plugin.auth` / - `plugin.approvals` 线路迁移到 `approvalCapability` + - 将审批专用 auth/delivery 从旧版 `plugin.auth` / + `plugin.approvals` 接线迁移到 `approvalCapability` - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；请将 delivery/native/render 字段迁移到 `approvalCapability` - - `plugin.auth` 仅保留用于渠道登录/登出流程；其中的审批认证钩子不再被核心读取 - - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册由渠道拥有的运行时对象，例如客户端、令牌或 Bolt 应用 - - 不要从原生审批处理器发送由插件拥有的改道通知；核心现在根据实际投递结果统一负责“已路由到其他位置”的通知 - - 在将 `channelRuntime` 传入 `createChannelManager(...)` 时，必须提供真实的 `createPluginRuntime().channel` 接口。部分 stub 会被拒绝。 + - `plugin.auth` 仍仅用于渠道登录/登出流程；其中的审批 auth 钩子不再被核心读取 + - 通过 `openclaw/plugin-sdk/channel-runtime-context` + 注册渠道自有运行时对象，例如 clients、tokens 或 Bolt apps + - 不要从原生审批处理器中发送插件自有的 reroute notices；核心现在会根据实际投递结果统一负责“已路由到其他位置”的通知 + - 当把 `channelRuntime` 传给 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 接口面。不接受部分 stub。 - 有关当前审批能力布局，请参见 `/plugins/sdk-channel-plugins`。 + 有关当前 approval capability 布局，请参阅 `/plugins/sdk-channel-plugins`。 - - 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`， - 那么无法解析的 Windows `.cmd`/`.bat` 包装器现在会默认失败关闭，除非你显式传入 + + 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，现在未解析的 Windows + `.cmd`/`.bat` wrapper 会默认失败关闭，除非你显式传入 `allowShellFallback: true`。 ```typescript @@ -180,19 +178,18 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 // 之后 const program = applyWindowsSpawnProgramPolicy({ candidate, - // 仅对受信任的兼容性调用方设置此项， - // 且这些调用方明确接受通过 shell 进行的回退。 + // 仅对有意接受 shell 中介回退的受信任兼容性调用方设置此项。 allowShellFallback: true, }); ``` 如果你的调用方并不有意依赖 shell 回退，请不要设置 - `allowShellFallback`，而应改为处理抛出的错误。 + `allowShellFallback`，而是改为处理抛出的错误。 - - 在你的插件中搜索来自任一已弃用接口的导入： + + 在你的插件中搜索从任一已弃用接口面导入的代码： ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -204,7 +201,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - 旧接口中的每个导出都映射到一个特定的现代导入路径： + 旧接口面中的每个导出都映射到一个特定的现代导入路径： ```typescript // 之前（已弃用的向后兼容层） @@ -223,17 +220,17 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 对于宿主侧辅助工具，请使用注入的插件运行时，而不是直接导入： ```typescript - // 之前（已弃用的 extension-api 桥接层） + // 之前（已弃用的 extension-api 桥接） import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // 之后（注入式运行时） + // 之后（注入的运行时） const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` 同样的模式也适用于其他旧版桥接辅助工具： - | 旧导入 | 现代等价项 | + | 旧导入 | 现代等价物 | | --- | --- | | `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` | | `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` | @@ -246,36 +243,36 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - `openclaw/plugin-sdk/infra-runtime` 仍然保留以兼容外部插件，但新代码应导入其实际需要的聚焦辅助接口： + `openclaw/plugin-sdk/infra-runtime` 仍然保留用于外部兼容性，但新代码应导入其实际所需的聚焦辅助工具接口面： | 需求 | 导入 | | --- | --- | | 系统事件队列辅助工具 | `openclaw/plugin-sdk/system-event-runtime` | - | 心跳事件和可见性辅助工具 | `openclaw/plugin-sdk/heartbeat-runtime` | - | 待处理投递队列排空 | `openclaw/plugin-sdk/delivery-queue-runtime` | + | Heartbeat 事件与可见性辅助工具 | `openclaw/plugin-sdk/heartbeat-runtime` | + | 待处理投递队列清空 | `openclaw/plugin-sdk/delivery-queue-runtime` | | 渠道活动遥测 | `openclaw/plugin-sdk/channel-activity-runtime` | - | 内存去重缓存 | `openclaw/plugin-sdk/dedupe-runtime` | + | 内存内去重缓存 | `openclaw/plugin-sdk/dedupe-runtime` | | 安全的本地文件/媒体路径辅助工具 | `openclaw/plugin-sdk/file-access-runtime` | - | 感知 dispatcher 的 fetch | `openclaw/plugin-sdk/runtime-fetch` | + | 具备 dispatcher 感知能力的 fetch | `openclaw/plugin-sdk/runtime-fetch` | | 代理和受保护的 fetch 辅助工具 | `openclaw/plugin-sdk/fetch-runtime` | | SSRF dispatcher 策略类型 | `openclaw/plugin-sdk/ssrf-dispatcher` | | 审批请求/解析类型 | `openclaw/plugin-sdk/approval-runtime` | | 审批回复负载和命令辅助工具 | `openclaw/plugin-sdk/approval-reply-runtime` | | 错误格式化辅助工具 | `openclaw/plugin-sdk/error-runtime` | | 传输就绪等待 | `openclaw/plugin-sdk/transport-ready-runtime` | - | 安全令牌辅助工具 | `openclaw/plugin-sdk/secure-random-runtime` | + | 安全 token 辅助工具 | `openclaw/plugin-sdk/secure-random-runtime` | | 有界异步任务并发 | `openclaw/plugin-sdk/concurrency-runtime` | | 数值强制转换 | `openclaw/plugin-sdk/number-runtime` | | 进程本地异步锁 | `openclaw/plugin-sdk/async-lock-runtime` | | 文件锁 | `openclaw/plugin-sdk/file-lock` | - 内置插件受扫描器保护，不能使用 `infra-runtime`，因此仓库代码无法回退到这个宽泛 barrel。 + 内置插件受扫描器保护，不允许使用 `infra-runtime`，因此仓库代码不能回退到这个宽泛 barrel。 新的渠道路由代码应使用 `openclaw/plugin-sdk/channel-route`。 - 在迁移窗口期间，旧的 route-key 和 comparable-target 名称仍保留为兼容性别名，但新插件应使用能够更直接描述行为的路由命名： + 旧的 route-key 和 comparable-target 名称在迁移窗口期间仍作为兼容性别名保留，但新插件应使用能更直接描述行为的路由名称： | 旧辅助工具 | 现代辅助工具 | | --- | --- | @@ -287,12 +284,12 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `comparableChannelTargetsMatch(...)` | `channelRouteTargetsMatchExact(...)` | | `comparableChannelTargetsShareRoute(...)` | `channelRouteTargetsShareConversation(...)` | - 现代路由辅助工具会在原生审批、回复抑制、入站去重、cron 投递和会话路由中，一致地规范化 `{ channel, to, accountId, threadId }`。 - 如果你的插件拥有自定义目标语法，请使用 `resolveChannelRouteTargetWithParser(...)`，将该解析器适配到相同的路由目标契约中。 + 现代路由辅助工具会在原生审批、回复抑制、入站去重、cron 投递和会话路由之间一致地规范化 `{ channel, to, accountId, threadId }`。 + 如果你的插件拥有自定义目标语法，请使用 `resolveChannelRouteTargetWithParser(...)`，将该解析器适配到同一套路由目标契约中。 - + ```bash pnpm build pnpm test -- my-plugin/ @@ -305,67 +302,67 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | 导入路径 | 用途 | 关键导出 | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` | - | `plugin-sdk/core` | 用于渠道入口定义/构建器的旧版聚合重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/plugin-entry` | 规范的插件入口辅助工具 | `definePluginEntry` | + | `plugin-sdk/core` | 用于渠道入口定义/builders 的旧版 umbrella 重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | 单提供商入口辅助工具 | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享设置向导辅助工具 | 允许列表提示、设置状态构建器 | - | `plugin-sdk/setup-runtime` | 设置阶段运行时辅助工具 | 导入安全的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 | - | `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/provider-entry` | 单一 provider 入口辅助工具 | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和 builders | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | 共享的设置向导辅助工具 | Allowlist 提示、设置状态 builders | + | `plugin-sdk/setup-runtime` | 设置阶段运行时辅助工具 | 导入安全的设置 patch adapters、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托式设置代理 | + | `plugin-sdk/setup-adapter-runtime` | 设置 adapter 辅助工具 | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表/配置/操作门控辅助工具 | + | `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` | 窄化的账户辅助工具 | 账户列表/账户操作辅助工具 | - | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` | - | `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入 wiring | `createChannelReplyPipeline` | - | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 共享渠道配置 schema 原语和通用构建器本身 | - | `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置配置 schema | 仅用于内置兼容；新插件必须定义插件本地 schema | + | `plugin-sdk/account-resolution` | 账号查找辅助工具 | 账号查找 + 默认回退辅助工具 | + | `plugin-sdk/account-helpers` | 狭义账号辅助工具 | 账号列表/account-action 辅助工具 | + | `plugin-sdk/channel-setup` | 设置向导 adapters | `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` | 配置 adapter 工厂 | `createHybridChannelConfigAdapter` | + | `plugin-sdk/channel-config-schema` | 配置 schema builders | 共享渠道配置 schema 基础组件和仅通用 builder | + | `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置配置 schema | 仅用于内置兼容性；新插件必须定义插件本地 schema | | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复/冲突校验 | - | `plugin-sdk/channel-policy` | 群组/私信策略解析 | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | 账户状态和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览完成辅助工具 | - | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享 route + envelope 构建器辅助工具 | - | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录并分发辅助工具 | + | `plugin-sdk/channel-policy` | 群组/私信 策略解析 | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | 账号 Status 和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览完成辅助工具 | + | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope builder 辅助工具 | + | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享 record-and-dispatch 辅助工具 | | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助工具 | | `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 | - | `plugin-sdk/outbound-send-deps` | 出站发送依赖辅助工具 | 轻量级 `resolveOutboundSendDep` 查找，无需导入完整的出站运行时 | - | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站投递、身份/发送委托、会话、格式化和负载规划辅助工具 | - | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 | - | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 用于旧字段布局的智能体媒体负载构建器 | + | `plugin-sdk/outbound-send-deps` | 出站发送依赖辅助工具 | 轻量级 `resolveOutboundSendDep` 查找，无需导入完整出站运行时 | + | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站投递、identity/send delegate、会话、格式化和 payload 规划辅助工具 | + | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和 adapter 辅助工具 | + | `plugin-sdk/agent-media-payload` | 旧版媒体 payload 辅助工具 | 用于旧字段布局的智能体媒体 payload builder | | `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/runtime-env` | 狭义运行时环境辅助工具 | logger/运行时环境、超时、重试和退避辅助工具 | | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/钩子/http/交互式辅助工具 | | `plugin-sdk/hook-runtime` | 钩子管道辅助工具 | 共享 webhook/内部钩子管道辅助工具 | | `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 网关客户端和渠道状态 patch 辅助工具 | | `plugin-sdk/config-runtime` | 已弃用的配置兼容性 shim | 优先使用 `config-types`、`plugin-config-runtime`、`runtime-config-snapshot` 和 `config-mutation` | - | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供回退稳定的 Telegram 命令校验辅助工具 | - | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec/插件审批负载、approval capability/profile 辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示路径格式化 | - | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | approver 解析、同聊天操作认证 | + | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口面不可用时，提供具有稳定回退能力的 Telegram 命令校验辅助工具 | + | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec/插件审批 payload、approval capability/profile 辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示路径格式化 | + | `plugin-sdk/approval-auth-runtime` | 审批 auth 辅助工具 | approver 解析、同聊天 action auth | | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批 profile/filter 辅助工具 | - | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生 approval capability/delivery 适配器 | + | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生 approval capability/delivery adapters | | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 用于高频渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽泛的审批处理器运行时辅助工具；若较窄的 adapter/gateway 接口已足够，应优先使用它们 | - | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标/账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec/插件审批回复负载辅助工具 | - | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register/get/watch 辅助工具 | - | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享 trust、私信门控、外部内容和 Secret 收集辅助工具 | - | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机允许列表和私有网络策略辅助工具 | + | `plugin-sdk/approval-handler-adapter-runtime` | 审批 adapter 辅助工具 | 用于高频渠道入口点的轻量级原生审批 adapter 加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽泛的审批处理器运行时辅助工具；当更狭义的 adapter/gateway 接缝已足够时，应优先使用后者 | + | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标/account 绑定辅助工具 | + | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec/插件审批回复 payload 辅助工具 | + | `plugin-sdk/channel-runtime-context` | 渠道 runtime-context 辅助工具 | 通用渠道 runtime-context register/get/watch 辅助工具 | + | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信 门控、外部内容和 secret 收集辅助工具 | + | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 allowlist 和私有网络策略辅助工具 | | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | pinned-dispatcher、受保护 fetch、SSRF 策略辅助工具 | | `plugin-sdk/system-event-runtime` | 系统事件辅助工具 | `enqueueSystemEvent`, `peekSystemEventEntries` | - | `plugin-sdk/heartbeat-runtime` | 心跳辅助工具 | 心跳事件和可见性辅助工具 | + | `plugin-sdk/heartbeat-runtime` | Heartbeat 辅助工具 | Heartbeat 事件和可见性辅助工具 | | `plugin-sdk/delivery-queue-runtime` | 投递队列辅助工具 | `drainPendingDeliveries` | | `plugin-sdk/channel-activity-runtime` | 渠道活动辅助工具 | `recordChannelActivity` | - | `plugin-sdk/dedupe-runtime` | 去重辅助工具 | 内存去重缓存 | + | `plugin-sdk/dedupe-runtime` | 去重辅助工具 | 内存内去重缓存 | | `plugin-sdk/file-access-runtime` | 文件访问辅助工具 | 安全的本地文件/媒体路径辅助工具 | | `plugin-sdk/transport-ready-runtime` | 传输就绪辅助工具 | `waitForTransportReady` | | `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` | @@ -374,150 +371,150 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `plugin-sdk/fetch-runtime` | 封装的 fetch/proxy 辅助工具 | `resolveFetch`、代理辅助工具 | | `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | | `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 | - | `plugin-sdk/allow-from` | 允许列表格式化 | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | 允许列表输入映射 | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | 命令门控和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具（包括动态参数菜单格式化） | - | `plugin-sdk/command-status` | 命令 Status/帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | Secret 输入解析 | Secret 输入辅助工具 | + | `plugin-sdk/allow-from` | Allowlist 格式化 | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | Allowlist 输入映射 | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | 命令门控和命令接口面辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具，包括动态参数菜单格式化 | + | `plugin-sdk/command-status` | 命令 Status /帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | secret 输入解析 | secret 输入辅助工具 | | `plugin-sdk/webhook-ingress` | Webhook 请求辅助工具 | Webhook 目标实用工具 | - | `plugin-sdk/webhook-request-guards` | Webhook 请求体守卫辅助工具 | 请求体读取/限制辅助工具 | - | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 | - | `plugin-sdk/reply-dispatch-runtime` | 窄化的回复分发辅助工具 | 完成、提供商分发和会话标签辅助工具 | + | `plugin-sdk/webhook-request-guards` | Webhook 请求体保护辅助工具 | 请求体读取/限制辅助工具 | + | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、heartbeat、回复规划器、分块 | + | `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/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` | 渠道 Status 辅助工具 | 渠道/账户 Status 摘要构建器、运行时状态默认值、问题元数据辅助工具 | + | `plugin-sdk/status-helpers` | 渠道 Status 辅助工具 | 渠道/账号状态摘要 builders、运行时状态默认值、问题元数据辅助工具 | | `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-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 | + | `plugin-sdk/tool-payload` | 工具 payload 提取 | 从工具结果对象中提取规范化 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/reply-payload` | 消息回复类型 | 回复 payload 类型 | | `plugin-sdk/provider-setup` | 精选的本地/自托管 provider 设置辅助工具 | 自托管 provider 发现/配置辅助工具 | | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管 provider 设置辅助工具 | 同样的自托管 provider 发现/配置辅助工具 | - | `plugin-sdk/provider-auth-runtime` | provider 运行时认证辅助工具 | 运行时 API 密钥解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | provider API 密钥设置辅助工具 | API 密钥新手引导/profile 写入辅助工具 | - | `plugin-sdk/provider-auth-result` | provider auth-result 辅助工具 | 标准 OAuth auth-result 构建器 | + | `plugin-sdk/provider-auth-runtime` | provider 运行时 auth 辅助工具 | 运行时 API key 解析辅助工具 | + | `plugin-sdk/provider-auth-api-key` | provider API key 设置辅助工具 | API key 新手引导/profile 写入辅助工具 | + | `plugin-sdk/provider-auth-result` | provider auth-result 辅助工具 | 标准 OAuth auth-result builder | | `plugin-sdk/provider-auth-login` | provider 交互式登录辅助工具 | 共享交互式登录辅助工具 | - | `plugin-sdk/provider-selection-runtime` | provider 选择辅助工具 | 已配置或自动 provider 选择，以及原始 provider 配置合并 | - | `plugin-sdk/provider-env-vars` | provider 环境变量辅助工具 | provider 认证环境变量查找辅助工具 | - | `plugin-sdk/provider-model-shared` | 共享 provider 模型/replay 辅助工具 | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、provider 端点辅助工具，以及 model-id 规范化辅助工具 | - | `plugin-sdk/provider-catalog-shared` | 共享 provider 目录辅助工具 | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-selection-runtime` | provider 选择辅助工具 | 已配置或自动 provider 选择以及原始 provider 配置合并 | + | `plugin-sdk/provider-env-vars` | provider 环境变量辅助工具 | provider auth 环境变量查找辅助工具 | + | `plugin-sdk/provider-model-shared` | 共享 provider 模型/replay 辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy builders、provider endpoint 辅助工具，以及 model-id 规范化辅助工具 | + | `plugin-sdk/provider-catalog-shared` | 共享 provider catalog 辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | | `plugin-sdk/provider-onboard` | provider 新手引导补丁 | 新手引导配置辅助工具 | - | `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP/端点能力辅助工具，包括音频转写 multipart form 辅助工具 | + | `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP/endpoint capability 辅助工具，包括音频转录 multipart form 辅助工具 | | `plugin-sdk/provider-web-fetch` | provider web-fetch 辅助工具 | web-fetch provider 注册/缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | provider web-search 配置辅助工具 | 面向不需要插件启用 wiring 的 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` 以及作用域化的凭证 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/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装辅助工具 | - | `plugin-sdk/provider-transport-runtime` | provider 传输辅助工具 | 原生 provider 传输辅助工具，例如受保护 fetch、传输消息转换和可写传输事件流 | + | `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/DeepSeek V4/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` | 媒体理解辅助工具 | 媒体理解 provider 类型，以及面向 provider 的图像/音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本实用工具，以及相关文本/日志辅助工具 | + | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取/转换/存储辅助工具，以及媒体 payload builders | + | `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` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的指令、注册表和校验辅助工具 | - | `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、指令、规范化 | - | `plugin-sdk/realtime-transcription` | 实时转写辅助工具 | provider 类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | - | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型、注册表/解析辅助工具和桥接会话辅助工具 | - | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表辅助工具 | + | `plugin-sdk/speech` | Speech 辅助工具 | Speech provider 类型，以及面向 provider 的 directive、注册表和校验辅助工具 | + | `plugin-sdk/speech-core` | 共享 Speech 核心 | Speech provider 类型、注册表、directives、规范化 | + | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型、注册表辅助工具，以及共享 WebSocket 会话辅助工具 | + | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型、注册表/解析辅助工具，以及 bridge 会话辅助工具 | + | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、auth 和注册表辅助工具 | | `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/interactive-runtime` | 交互式回复辅助工具 | 交互式回复 payload 规范化/归约 | + | `plugin-sdk/channel-config-primitives` | 渠道配置基础组件 | 狭义渠道 config-schema 基础组件 | | `plugin-sdk/channel-config-writes` | 渠道配置写入辅助工具 | 渠道配置写入授权辅助工具 | | `plugin-sdk/channel-plugin-common` | 共享渠道前导模块 | 共享渠道插件前导导出 | - | `plugin-sdk/channel-status` | 渠道 Status 辅助工具 | 共享渠道 Status 快照/摘要辅助工具 | - | `plugin-sdk/allowlist-config-edit` | 允许列表配置辅助工具 | 允许列表配置编辑/读取辅助工具 | + | `plugin-sdk/channel-status` | 渠道 Status 辅助工具 | 共享渠道状态快照/摘要辅助工具 | + | `plugin-sdk/allowlist-config-edit` | Allowlist 配置辅助工具 | Allowlist 配置编辑/读取辅助工具 | | `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证/守卫辅助工具 | - | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/Status 和环境代理辅助原语 | + | `plugin-sdk/direct-dm` | 直接私信 辅助工具 | 共享直接私信 auth/保护辅助工具 | + | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/状态和环境代理辅助工具基础组件 | | `plugin-sdk/webhook-targets` | Webhook 目标辅助工具 | Webhook 目标注册表和路由安装辅助工具 | | `plugin-sdk/webhook-path` | Webhook 路径辅助工具 | Webhook 路径规范化辅助工具 | | `plugin-sdk/web-media` | 共享 Web 媒体辅助工具 | 远程/本地媒体加载辅助工具 | - | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用方重新导出的 `zod` | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | Memory 管理器/配置/文件/CLI 辅助接口 | + | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用者重新导出的 `zod` | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | Memory 管理器/配置/文件/CLI 辅助工具接口面 | | `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时门面 | Memory 索引/搜索运行时门面 | | `plugin-sdk/memory-core-host-engine-foundation` | Memory 宿主基础引擎 | Memory 宿主基础引擎导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 宿主嵌入引擎 | Memory 嵌入契约、注册表访问、本地 provider 以及通用批处理/远程辅助工具；具体远程 provider 位于各自所属插件中 | + | `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-secret` | Memory 宿主 secret 辅助工具 | Memory 宿主 secret 辅助工具 | | `plugin-sdk/memory-core-host-events` | Memory 宿主事件日志辅助工具 | Memory 宿主事件日志辅助工具 | | `plugin-sdk/memory-core-host-status` | Memory 宿主 Status 辅助工具 | Memory 宿主 Status 辅助工具 | | `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 搜索门面 | 惰性活动记忆搜索管理器运行时门面 | - | `plugin-sdk/memory-host-status` | Memory 宿主 Status 别名 | 面向供应商中立的 Memory 宿主 Status 辅助工具别名 | - | `plugin-sdk/memory-lancedb` | 内置 Memory LanceDB 辅助工具 | Memory LanceDB 辅助接口 | - | `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mock | + | `plugin-sdk/memory-host-core` | Memory 宿主核心运行时别名 | 面向 vendor-neutral 的 Memory 宿主核心运行时辅助工具别名 | + | `plugin-sdk/memory-host-events` | Memory 宿主事件日志别名 | 面向 vendor-neutral 的 Memory 宿主事件日志辅助工具别名 | + | `plugin-sdk/memory-host-files` | Memory 宿主文件/运行时别名 | 面向 vendor-neutral 的 Memory 宿主文件/运行时辅助工具别名 | + | `plugin-sdk/memory-host-markdown` | 托管 Markdown 辅助工具 | 供内存相关插件使用的共享托管 Markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索门面 | 惰性活跃 Memory 搜索管理器运行时门面 | + | `plugin-sdk/memory-host-status` | Memory 宿主 Status 别名 | 面向 vendor-neutral 的 Memory 宿主 Status 辅助工具别名 | + | `plugin-sdk/memory-lancedb` | 内置 Memory LanceDB 辅助工具 | Memory LanceDB 辅助工具接口面 | + | `plugin-sdk/testing` | 测试工具 | 旧版宽泛兼容性 barrel；优先使用聚焦的测试子路径，例如 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/channel-target-testing`、`plugin-sdk/test-env` 和 `plugin-sdk/test-fixtures` | -这个表刻意只包含常见迁移子集，而不是完整的 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`、 `plugin-sdk/twitch`、 `plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、 `plugin-sdk/diagnostics-otel`、`plugin-sdk/diagnostics-prometheus`、 - `plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/thread-ownership`、 + `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`、 +`plugin-sdk/github-copilot-token` 当前暴露了狭义 token-helper +接口面 `DEFAULT_COPILOT_API_BASE_URL`、 `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。 -请使用与你任务最匹配的最窄导入路径。如果你找不到某个导出， -请检查 `src/plugin-sdk/` 下的源码，或在 Discord 中提问。 +请使用与任务最匹配的最狭义导入路径。如果你找不到某个导出， +请检查 `src/plugin-sdk/` 中的源代码，或在 Discord 中提问。 -## 当前已启用的弃用项 +## 当前弃用项 -这些是跨插件 SDK、provider 契约、运行时接口和 manifest 生效的更窄粒度弃用项。它们目前仍然可用，但将在未来的主要版本中移除。每一项下方的条目都给出了从旧 API 到规范替代方案的映射。 +以下是适用于整个插件 SDK、provider 契约、 +运行时接口面和 manifest 的更狭义弃用项。它们目前仍然可用，但会在未来的主要版本中移除。每个条目下方都将旧 API 映射到其规范替代方案。 - + **旧版（`openclaw/plugin-sdk/command-auth`）**：`buildCommandsMessage`、 `buildCommandsMessagePaginated`、`buildHelpMessage`。 - **新版（`openclaw/plugin-sdk/command-status`）**：签名相同，导出相同—— - 只是改为从更窄的子路径导入。`command-auth` - 会将它们作为兼容性 stub 重新导出。 + **新版（`openclaw/plugin-sdk/command-status`）**：相同签名、相同 + 导出——只是改为从更狭义的子路径导入。`command-auth` + 会将它们重新导出为 compat 存根。 ```typescript // 之前 @@ -529,56 +526,61 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - + **旧版**：`resolveInboundMentionRequirement({ facts, policy })` 和 `shouldDropInboundForMention(...)`，来自 `openclaw/plugin-sdk/channel-inbound` 或 `openclaw/plugin-sdk/channel-mention-gating`。 - **新版**：`resolveInboundMentionDecision({ facts, policy })`——返回单个决策对象，而不是拆分成两个调用。 + **新版**：`resolveInboundMentionDecision({ facts, policy })`——它会返回一个 + 单一决策对象，而不是拆分成两次调用。 - 下游渠道插件（Slack、Discord、Matrix、Microsoft Teams）都已经完成切换。 + 下游渠道插件（Slack、Discord、Matrix、Microsoft Teams）已经完成切换。 - - `openclaw/plugin-sdk/channel-runtime` 是面向旧渠道插件的兼容性 shim。 - 新代码不要导入它；应使用 - `openclaw/plugin-sdk/channel-runtime-context` 来注册运行时对象。 + + `openclaw/plugin-sdk/channel-runtime` 是面向旧版 + 渠道插件的兼容性 shim。新代码不要导入它；请使用 + `openclaw/plugin-sdk/channel-runtime-context` 来注册运行时 + 对象。 - `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` 辅助工具 - 会和原始的“actions”渠道导出一起被弃用。请改为通过语义化的 - `presentation` 接口暴露能力——渠道插件应声明自己能渲染什么 - （卡片、按钮、选择器），而不是声明自己接受哪些原始操作名称。 + `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` + 辅助工具会与原始“actions”渠道导出一起被弃用。请改为通过语义化的 + `presentation` 接口面暴露能力——渠道插件声明它们渲染什么 + （cards、buttons、selects），而不是声明它们接受哪些原始 + action 名称。 - **旧版**：来自 `openclaw/plugin-sdk/provider-web-search` 的 `tool()` 工厂。 + **旧版**：来自 `openclaw/plugin-sdk/provider-web-search` 的 `tool()` + 工厂。 **新版**：直接在 provider 插件上实现 `createTool(...)`。 OpenClaw 不再需要 SDK 辅助工具来注册这个工具包装器。 - + **旧版**：`formatInboundEnvelope(...)`（以及 - `ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建扁平的纯文本提示 envelope。 + `ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建扁平的纯文本提示 + envelope。 - **新版**：`BodyForAgent` 加上结构化用户上下文块。 - 渠道插件会将路由元数据（线程、主题、reply-to、reactions）作为带类型字段附加， - 而不是把它们拼接进一个提示字符串中。 - `formatAgentEnvelope(...)` 辅助工具仍然支持用于合成的、面向助手的 envelope， - 但入站纯文本 envelope 正在逐步淘汰。 + **新版**：`BodyForAgent` 加上结构化用户上下文块。渠道 + 插件会将路由元数据（thread、topic、reply-to、reactions）作为 + 类型化字段附加，而不是把它们拼接成提示字符串。 + `formatAgentEnvelope(...)` 辅助工具仍然支持用于合成的 + 面向 assistant 的 envelope，但入站纯文本 envelope 正在 + 逐步淘汰。 受影响区域：`inbound_claim`、`message_received`，以及任何对 - `channelEnvelope` 文本做后处理的自定义渠道插件。 + `channelEnvelope` 文本进行后处理的自定义渠道插件。 - - 现在有四个 discovery 类型别名已经变成对 - catalog 时代类型的薄包装： + + 四个发现类型别名现在已变成 catalog 时代类型上的薄包装： | 旧别名 | 新类型 | | ------------------------- | ------------------------- | @@ -587,32 +589,34 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `ProviderDiscoveryResult` | `ProviderCatalogResult` | | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | - 此外还有旧版的 `ProviderCapabilities` 静态对象——provider 插件 - 应通过 provider 运行时契约附加 capability 事实，而不是使用静态对象。 + 此外还有旧版 `ProviderCapabilities` 静态对象——provider 插件 + 应通过 provider 运行时契约附加 capability facts， + 而不是通过静态对象。 - + **旧版**（`ProviderThinkingPolicy` 上的三个独立钩子）： `isBinaryThinking(ctx)`、`supportsXHighThinking(ctx)` 和 `resolveDefaultThinkingLevel(ctx)`。 - **新版**：单一的 `resolveThinkingProfile(ctx)`，它返回一个 - `ProviderThinkingProfile`，其中包含规范的 `id`、可选的 `label`， - 以及按等级排序的级别列表。OpenClaw 会根据 profile 排名自动降级过时的已存储值。 + **新版**：单个 `resolveThinkingProfile(ctx)`，返回一个 + `ProviderThinkingProfile`，其中包含规范的 `id`、可选的 `label` 以及 + 按等级排序的 level 列表。OpenClaw 会按 profile 排名自动降级 + 过期的已存储值。 - 现在只需实现一个钩子，而不是三个。旧钩子在弃用窗口期间仍然可用， - 但不会与 profile 结果进行组合。 + 现在实现一个钩子即可，不必实现三个。旧钩子在 + 弃用窗口期间仍然可用，但不会与 profile 结果组合使用。 - **旧版**：实现 `resolveExternalOAuthProfiles(...)`， - 但不在插件 manifest 中声明该 provider。 + **旧版**：在插件 manifest 中未声明 provider 的情况下，实现 + `resolveExternalOAuthProfiles(...)`。 **新版**：在插件 manifest 中声明 `contracts.externalAuthProviders` - **并且**实现 `resolveExternalAuthProfiles(...)`。旧的“认证回退” - 路径会在运行时发出警告，并将在未来被移除。 + **并且**实现 `resolveExternalAuthProfiles(...)`。旧的“auth + fallback”路径会在运行时发出警告，并将在未来被移除。 ```json { @@ -624,14 +628,15 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - + **旧版** manifest 字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。 - **新版**：将相同的环境变量查找信息镜像到 manifest 中的 - `setup.providers[].envVars`。这样可以把设置/Status 环境变量元数据集中到同一个位置， - 并避免仅为了回答环境变量查找而启动插件运行时。 + **新版**：将相同的环境变量查找镜像到 manifest 中的 `setup.providers[].envVars` + 中。这样可以把设置/Status 的环境变量元数据集中到同一个 + 位置，并避免仅为了回答环境变量查找而启动插件运行时。 - `providerAuthEnvVars` 在弃用窗口结束前仍会通过兼容性适配器继续受支持。 + `providerAuthEnvVars` 会通过兼容适配器继续受支持， + 直到弃用窗口结束。 @@ -644,30 +649,31 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 **新版**：在 memory-state API 上使用一次调用—— `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`。 - 槽位相同，只是改为单次注册调用。增量 Memory 辅助工具 + 相同的插槽，单次注册调用。新增的 Memory 辅助工具 （`registerMemoryPromptSupplement`、`registerMemoryCorpusSupplement`、 `registerMemoryEmbeddingProvider`）不受影响。 - - 仍然从 `src/plugins/runtime/types.ts` 导出的两个旧类型别名： + + 仍从 `src/plugins/runtime/types.ts` 导出的两个旧版类型别名： | 旧版 | 新版 | | ----------------------------- | ------------------------------- | | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | - 运行时方法 `readSession` 已弃用，改用 - `getSessionMessages`。签名相同；旧方法会转调到新方法。 + 运行时方法 `readSession` 已弃用，建议改用 + `getSessionMessages`。签名相同；旧方法会转调到 + 新方法。 **旧版**：`runtime.tasks.flow`（单数）返回一个实时 task-flow 访问器。 - **新版**：`runtime.tasks.flows`（复数）返回基于 DTO 的 TaskFlow 访问方式， - 它是导入安全的，不需要加载完整的任务运行时。 + **新版**：`runtime.tasks.flows`（复数）返回基于 DTO 的 TaskFlow 访问， + 它是导入安全的，并且不要求加载完整任务运行时。 ```typescript // 之前 @@ -678,12 +684,13 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - - 上文“如何迁移 → 将 Pi 工具结果扩展迁移到中间件”中已覆盖。 - 这里为了完整性再次列出：已移除的仅限 Pi 的 - `api.registerEmbeddedExtensionFactory(...)` 路径，现由 + + 上文“如何迁移 → 将 Pi 工具结果扩展迁移到 + 中间件”中已介绍。这里为完整性再次列出：已移除的、仅限 Pi 的 + `api.registerEmbeddedExtensionFactory(...)` 路径现由 `api.registerAgentToolResultMiddleware(...)` 取代，并在 - `contracts.agentToolResultMiddleware` 中显式声明运行时列表。 + `contracts.agentToolResultMiddleware` 中显式声明运行时 + 列表。 @@ -701,38 +708,38 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 -位于 `extensions/` 下内置渠道/provider 插件内部的扩展级弃用项， -会在它们自己的 `api.ts` 和 `runtime-api.ts` -barrel 中进行跟踪。它们不影响第三方插件契约，因此未在此列出。 -如果你直接使用某个内置插件的本地 barrel，请在升级前阅读该 -barrel 中的弃用注释。 +扩展级别的弃用项（位于 `extensions/` 下的内置渠道/provider 插件内部） +会在它们各自的 `api.ts` 和 `runtime-api.ts` +barrels 中追踪。它们不会影响第三方插件契约，因此未在此处列出。 +如果你直接使用某个内置插件的本地 barrel，请在升级前阅读该 barrel 中的 +弃用注释。 ## 移除时间线 -| 时间 | 会发生什么 | +| 时间 | 将发生什么 | | ---------------------- | ----------------------------------------------------------------------- | -| **现在** | 已弃用接口会发出运行时警告 | -| **下一个主要版本** | 已弃用接口将被移除；仍在使用它们的插件会失效 | +| **现在** | 已弃用接口面会发出运行时警告 | +| **下一个主要版本** | 已弃用接口面将被移除；仍在使用它们的插件将会失效 | -所有核心插件都已经完成迁移。外部插件应在下一个主要版本之前完成迁移。 +所有核心插件都已完成迁移。外部插件应在下一个主要版本之前完成迁移。 ## 临时抑制警告 -在迁移期间工作时，设置这些环境变量： +在你进行迁移时，可以设置以下环境变量： ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -这只是临时逃生舱口，不是永久解决方案。 +这只是临时的应急出口，不是永久解决方案。 ## 相关内容 - [入门指南](/zh-CN/plugins/building-plugins) — 构建你的第一个插件 - [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 -- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件 -- [插件架构内部机制](/zh-CN/plugins/architecture) — 架构深入解析 +- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建 provider 插件 +- [插件内部机制](/zh-CN/plugins/architecture) — 架构深度解析 - [插件 Manifest](/zh-CN/plugins/manifest) — manifest schema 参考 diff --git a/docs/zh-CN/plugins/sdk-subpaths.md b/docs/zh-CN/plugins/sdk-subpaths.md index 081b594b9..eff95ff93 100644 --- a/docs/zh-CN/plugins/sdk-subpaths.md +++ b/docs/zh-CN/plugins/sdk-subpaths.md @@ -1,23 +1,22 @@ --- read_when: - 为插件导入选择合适的 plugin-sdk 子路径 - - 审计 bundled-plugin 子路径和辅助接口 -summary: 插件 SDK 子路径目录：按领域分组，各导入位于何处 + - 审查 bundled-plugin 子路径和辅助接口 surface +summary: 插件 SDK 子路径目录：按领域分组说明各个导入所在位置 title: 插件 SDK 子路径 x-i18n: - generated_at: "2026-04-28T00:49:38Z" + generated_at: "2026-04-28T01:06:38Z" model: gpt-5.4 provider: openai - source_hash: c0ddfb6f206e88eff92009f379d391972e7ec6c8ebe168962239b3663b7d0c4d + source_hash: 63abca6e6246162215a95c0f9351f4b36d0cd481a9710a0464db013385ae68bc source_path: plugins/sdk-subpaths.md workflow: 15 --- - 插件 SDK 以一组位于 `openclaw/plugin-sdk/` 下的精简子路径形式公开。 - 本页按用途对常用子路径进行归类整理。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`； - 其中也包含保留给 bundled-plugin 辅助接口的子路径，但除非文档页面明确将其列为公开能力，否则它们都属于实现细节。 + 插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组精细子路径对外暴露。 + 本页按用途对常用子路径进行分类目录整理。完整的 200 多个子路径生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`；其中也会出现保留的 bundled-plugin 辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。 - 有关插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 + 关于插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 ## 插件入口 @@ -27,107 +26,108 @@ x-i18n: | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | | `plugin-sdk/config-schema` | `OpenClawSchema` | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/testing` | 面向旧版插件测试的广泛兼容 barrel；新扩展测试应优先使用更聚焦的测试子路径 | - | `plugin-sdk/plugin-test-api` | 用于直接插件注册单元测试的最小 `OpenClawPluginApi` mock 构建器 | - | `plugin-sdk/channel-test-helpers` | 渠道账号生命周期、目录、发送配置、运行时 mock、钩子，以及通用渠道契约测试辅助工具 | - | `plugin-sdk/plugin-test-contracts` | 插件注册、包清单、公共产物、运行时 API、导入副作用和直接导入契约辅助工具 | - | `plugin-sdk/plugin-test-runtime` | 用于测试的插件运行时、注册表、提供商注册、设置向导和运行时任务流夹具 | - | `plugin-sdk/provider-test-contracts` | 提供商运行时、认证、发现、新手引导、目录、web 搜索/抓取和向导契约辅助工具 | - | `plugin-sdk/test-env` | 测试环境、抓取/网络、实时测试、临时文件系统和时间控制夹具 | - | `plugin-sdk/test-fixtures` | 通用 CLI、沙箱、Skill、智能体消息、系统事件、终端、分块、认证令牌和类型化测试用例夹具 | - | `plugin-sdk/migration` | 迁移提供商条目辅助工具，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助工具，以及 `summarizeMigrationItems` | - | `plugin-sdk/migration-runtime` | 运行时迁移辅助工具，例如 `copyMigrationFileItem` 和 `writeMigrationReport` | + | `plugin-sdk/testing` | 面向旧版插件测试的宽兼容 barrel；新扩展测试应优先使用更聚焦的测试子路径 | + | `plugin-sdk/plugin-test-api` | 用于直接插件注册单元测试的最小 `OpenClawPluginApi` mock builder | + | `plugin-sdk/channel-test-helpers` | 渠道账户生命周期、目录、发送配置、运行时 mock、钩子，以及通用渠道契约测试辅助工具 | + | `plugin-sdk/channel-target-testing` | 共享的渠道目标解析错误场景测试套件 | + | `plugin-sdk/plugin-test-contracts` | 插件注册、package manifest、公共产物、运行时 API、导入副作用，以及直接导入契约辅助工具 | + | `plugin-sdk/plugin-test-runtime` | 用于测试的插件运行时、注册表、提供商注册、设置向导和运行时任务流夹具 | + | `plugin-sdk/provider-test-contracts` | 提供商运行时、认证、发现、引导、新手引导、目录、web-search/fetch 和向导契约辅助工具 | + | `plugin-sdk/test-env` | 测试环境、fetch/网络、实时测试、临时文件系统和时间控制夹具 | + | `plugin-sdk/test-fixtures` | 通用 CLI、沙箱、技能、智能体消息、系统事件、终端、分块处理、auth-token 和类型化用例测试夹具 | + | `plugin-sdk/migration` | 迁移提供商条目辅助工具，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助工具，以及 `summarizeMigrationItems` | + | `plugin-sdk/migration-runtime` | 运行时迁移辅助工具，例如 `copyMigrationFileItem` 和 `writeMigrationReport` | | 子路径 | 关键导出 | | --- | --- | | `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-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-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/channel-config-schema-legacy` | 已弃用的 bundled-channel 配置 schema，仅用于内置兼容性 | - | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，带 bundled 契约回退 | - | `plugin-sdk/command-gating` | 精简的命令授权门控辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，带 bundled-contract 回退 | + | `plugin-sdk/command-gating` | 精细的命令授权门控辅助工具 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/收尾辅助工具 | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/完成辅助工具 | | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助工具 | | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助工具 | | `plugin-sdk/messaging-targets` | 目标解析/匹配辅助工具 | | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 | | `plugin-sdk/outbound-send-deps` | 面向渠道适配器的轻量级出站发送依赖查找 | | `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-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-inbound-debounce` | 精简的入站防抖辅助工具 | - | `plugin-sdk/channel-mention-gating` | 精简的提及策略、提及标记和提及文本辅助工具，不包含更广泛的入站运行时接口 | - | `plugin-sdk/channel-envelope` | 精简的入站 envelope 格式化辅助工具 | + | `plugin-sdk/direct-dm` | 共享私信认证/守卫辅助工具 | + | `plugin-sdk/interactive-runtime` | 语义消息呈现、投递和旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | 面向入站去抖动、提及匹配、提及策略辅助工具和 envelope 辅助工具的兼容性 barrel | + | `plugin-sdk/channel-inbound-debounce` | 精细的入站去抖动辅助工具 | + | `plugin-sdk/channel-mention-gating` | 精细的提及策略、提及标记和提及文本辅助工具，不包含更广泛的入站运行时接口 | + | `plugin-sdk/channel-envelope` | 精细的入站 envelope 格式化辅助工具 | | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 | | `plugin-sdk/channel-logging` | 用于入站丢弃和 typing/ack 失败的渠道日志辅助工具 | | `plugin-sdk/channel-send-result` | 回复结果类型 | | `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 | - | `plugin-sdk/channel-route` | 共享路由规范化、基于解析器的目标解析、线程 ID 字符串化、去重/紧凑路由键、已解析目标类型，以及路由/目标比较辅助工具 | + | `plugin-sdk/channel-route` | 共享路由规范化、parser 驱动的目标解析、thread-id 字符串化、去重/压缩路由键、已解析目标类型，以及路由/目标比较辅助工具 | | `plugin-sdk/channel-targets` | 目标解析辅助工具；路由比较调用方应使用 `plugin-sdk/channel-route` | | `plugin-sdk/channel-contract` | 渠道契约类型 | | `plugin-sdk/channel-feedback` | 反馈/反应接线 | - | `plugin-sdk/channel-secret-runtime` | 精简的密钥契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment`，以及密钥目标类型 | + | `plugin-sdk/channel-secret-runtime` | 精细的 secret-contract 辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret 目标类型 | | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/lmstudio` | 面向设置、目录发现和运行时模型准备的受支持 LM Studio 提供商外观层 | - | `plugin-sdk/lmstudio-runtime` | 面向本地服务器默认值、模型发现、请求头和已加载模型辅助工具的受支持 LM Studio 运行时外观层 | + | `plugin-sdk/lmstudio` | 受支持的 LM Studio 提供商门面，用于设置、目录发现和运行时模型准备 | + | `plugin-sdk/lmstudio-runtime` | 受支持的 LM Studio 运行时门面，用于本地服务器默认值、模型发现、请求头和已加载模型辅助工具 | | `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦于 OpenAI 兼容自托管提供商的设置辅助工具 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦 OpenAI 兼容自托管提供商的设置辅助工具 | | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 | - | `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API key 解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | API key 新手引导/配置文件写入辅助工具，例如 `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 | + | `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API 密钥解析辅助工具 | + | `plugin-sdk/provider-auth-api-key` | API 密钥新手引导/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 策略构建器、提供商端点辅助工具，以及诸如 `normalizeNativeXaiModelId` 之类的模型 ID 规范化辅助工具 | - | `plugin-sdk/provider-catalog-runtime` | 面向契约测试的提供商目录运行时钩子和 plugin-provider 注册表接缝 | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及 `normalizeNativeXaiModelId` 等模型 ID 规范化辅助工具 | + | `plugin-sdk/provider-catalog-runtime` | 用于契约测试的提供商目录运行时钩子和 plugin-provider 注册表接缝 | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | | `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助工具、提供商 HTTP 错误，以及音频转录 multipart form 辅助工具 | - | `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch-contract` | 精细的 web-fetch 配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册/缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | 适用于不需要插件启用接线的提供商的精简 web 搜索配置/凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | 精简的 web 搜索配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter/getter | - | `plugin-sdk/provider-web-search` | web 搜索提供商注册/缓存/运行时辅助工具 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容性辅助工具 | + | `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-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 等 xAI 兼容性辅助工具 | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似功能 | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 | - | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护 fetch、传输消息转换和可写传输事件流 | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/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/group-activation` | 精简的群组激活模式和命令解析辅助工具 | + | `plugin-sdk/group-activation` | 精细的群组激活模式和命令解析辅助工具 | @@ -135,29 +135,29 @@ x-i18n: | --- | --- | | `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-auth-runtime` | 审批者解析和同聊天 action-auth 辅助工具 | + | `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-handler-adapter-runtime` | 面向高频渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 范围更广的审批处理器运行时辅助工具；当更精细的 adapter/gateway 接缝已足够时，优先使用它们 | + | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 | | `plugin-sdk/approval-reply-runtime` | exec/插件审批回复载荷辅助工具 | - | `plugin-sdk/approval-runtime` | exec/插件审批载荷辅助工具、原生审批路由/运行时辅助工具，以及诸如 `formatApprovalDisplayPath` 之类的结构化审批显示辅助工具 | - | `plugin-sdk/reply-dedupe` | 精简的入站回复去重重置辅助工具 | - | `plugin-sdk/channel-contract-testing` | 不依赖广泛测试 barrel 的精简渠道契约测试辅助工具 | - | `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化，以及原生会话目标辅助工具 | + | `plugin-sdk/approval-runtime` | exec/插件审批载荷辅助工具、原生审批路由/运行时辅助工具，以及 `formatApprovalDisplayPath` 等结构化审批显示辅助工具 | + | `plugin-sdk/reply-dedupe` | 精细的入站回复去重重置辅助工具 | + | `plugin-sdk/channel-contract-testing` | 不带宽泛 testing barrel 的精细渠道契约测试辅助工具 | + | `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化和原生 session-target 辅助工具 | | `plugin-sdk/command-detection` | 共享命令检测辅助工具 | - | `plugin-sdk/command-primitives-runtime` | 面向热渠道路径的轻量级命令文本谓词 | - | `plugin-sdk/command-surface` | 命令主体规范化和命令表面辅助工具 | + | `plugin-sdk/command-primitives-runtime` | 面向高频渠道路径的轻量级命令文本谓词 | + | `plugin-sdk/command-surface` | 命令体规范化和命令 interface 辅助工具 | | `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` | 面向渠道/插件 secret interface 的精细 secret-contract 收集辅助工具 | + | `plugin-sdk/secret-ref-runtime` | 面向 secret-contract/配置解析的精细 `coerceSecretRef` 和 `SecretRef` 类型辅助工具 | + | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容、敏感文本脱敏、常量时间 secret 比较和 secret 收集辅助工具 | | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 | - | `plugin-sdk/ssrf-dispatcher` | 不包含广泛基础设施运行时接口的精简 pinned-dispatcher 辅助工具 | - | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、SSRF 保护 fetch、SSRF 错误和 SSRF 策略辅助工具 | - | `plugin-sdk/secret-input` | 密钥输入解析辅助工具 | + | `plugin-sdk/ssrf-dispatcher` | 不带宽泛基础设施运行时接口的精细 pinned-dispatcher 辅助工具 | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch、SSRF 错误和 SSRF 策略辅助工具 | + | `plugin-sdk/secret-input` | secret 输入解析辅助工具 | | `plugin-sdk/webhook-ingress` | webhook 请求/目标辅助工具，以及原始 websocket/body 强制转换 | | `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 | @@ -165,41 +165,41 @@ x-i18n: | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 精简的运行时环境、logger、timeout、retry 和 backoff 辅助工具 | - | `plugin-sdk/browser-config` | 受支持的浏览器配置外观层，用于规范化配置文件/默认值、CDP URL 解析和浏览器控制认证辅助工具 | + | `plugin-sdk/runtime` | 宽泛的运行时/日志/备份/插件安装辅助工具 | + | `plugin-sdk/runtime-env` | 精细的运行时环境、logger、超时、重试和退避辅助工具 | + | `plugin-sdk/browser-config` | 受支持的浏览器配置门面，用于规范化的 profile/默认值、CDP URL 解析和浏览器控制认证辅助工具 | | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助工具 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | | `plugin-sdk/plugin-runtime` | 共享插件命令/钩子/http/交互式辅助工具 | - | `plugin-sdk/hook-runtime` | 共享 webhook/内部钩子流水线辅助工具 | - | `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | + | `plugin-sdk/hook-runtime` | 共享 webhook/内部钩子管道辅助工具 | + | `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`, `createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | 进程 exec 辅助工具 | | `plugin-sdk/cli-runtime` | CLI 格式化、等待、版本、参数调用和惰性命令组辅助工具 | - | `plugin-sdk/gateway-runtime` | Gateway 网关客户端、Gateway 网关 CLI RPC、Gateway 网关协议错误和渠道状态补丁辅助工具 | - | `plugin-sdk/config-types` | 面向插件配置形状的纯类型配置接口，例如 `OpenClawConfig` 以及渠道/提供商配置类型 | - | `plugin-sdk/plugin-config-runtime` | 运行时插件配置查找辅助工具，例如 `requireRuntimeConfig`、`resolvePluginConfigObject` 和 `resolveLivePluginConfigObject` | - | `plugin-sdk/config-mutation` | 事务型配置变更辅助工具，例如 `mutateConfigFile`、`replaceConfigFile` 和 `logConfigUpdated` | - | `plugin-sdk/runtime-config-snapshot` | 当前进程配置快照辅助工具，例如 `getRuntimeConfig`、`getRuntimeConfigSnapshot` 和测试快照 setter | - | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约接口不可用时也可使用 | - | `plugin-sdk/text-autolink-runtime` | 文件引用自动链接检测，不依赖广泛的 text-runtime barrel | - | `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、认证/配置文件辅助工具、原生路由/运行时辅助工具，以及结构化审批显示路径格式化 | - | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、心跳、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发/收尾和对话标签辅助工具 | - | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助工具和标记，例如 `buildHistoryContext`、`HISTORY_CONTEXT_MARKER`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/gateway-runtime` | Gateway 网关客户端、Gateway 网关 CLI RPC、Gateway 网关协议错误，以及 channel-status 补丁辅助工具 | + | `plugin-sdk/config-types` | 仅类型的插件配置 interface，用于 `OpenClawConfig` 以及渠道/提供商配置类型等插件配置结构 | + | `plugin-sdk/plugin-config-runtime` | 运行时插件配置查找辅助工具，例如 `requireRuntimeConfig`, `resolvePluginConfigObject` 和 `resolveLivePluginConfigObject` | + | `plugin-sdk/config-mutation` | 事务式配置变更辅助工具，例如 `mutateConfigFile`, `replaceConfigFile` 和 `logConfigUpdated` | + | `plugin-sdk/runtime-config-snapshot` | 当前进程配置快照辅助工具，例如 `getRuntimeConfig`, `getRuntimeConfigSnapshot` 和测试快照 setter | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约 interface 不可用时也可使用 | + | `plugin-sdk/text-autolink-runtime` | 不依赖宽泛 text-runtime barrel 的文件引用自动链接检测 | + | `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、认证/profile 辅助工具、原生路由/运行时辅助工具，以及结构化审批显示路径格式化 | + | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块处理、分发、心跳和回复规划器 | + | `plugin-sdk/reply-dispatch-runtime` | 精细的回复分发/完成以及会话标签辅助工具 | + | `plugin-sdk/reply-history` | 共享短时间窗口 reply-history 辅助工具和标记，例如 `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 精简的文本/Markdown 分块辅助工具 | - | `plugin-sdk/session-store-runtime` | 会话存储路径、会话键、updated-at 和存储变更辅助工具 | + | `plugin-sdk/reply-chunking` | 精细的文本/Markdown 分块辅助工具 | + | `plugin-sdk/session-store-runtime` | 会话存储路径、session-key、updated-at 和存储变更辅助工具 | | `plugin-sdk/cron-store-runtime` | cron 存储路径/加载/保存辅助工具 | | `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助工具 | - | `plugin-sdk/routing` | 路由/会话键/账号绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | 共享渠道/账号状态摘要辅助工具、运行时状态默认值和问题元数据辅助工具 | + | `plugin-sdk/routing` | 路由/session-key/账户绑定辅助工具，例如 `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/param-readers` | 常用工具/CLI 参数读取器 | | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化载荷 | - | `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 | + | `plugin-sdk/tool-send` | 从工具参数中提取规范化发送目标字段 | | `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 | | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助工具 | @@ -207,20 +207,20 @@ x-i18n: | `plugin-sdk/talk-config-runtime` | Talk 提供商配置解析辅助工具 | | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 | | `plugin-sdk/file-lock` | 可重入文件锁辅助工具 | - | `plugin-sdk/persistent-dedupe` | 磁盘后备去重缓存辅助工具 | - | `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 | + | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 | + | `plugin-sdk/acp-runtime` | ACP 运行时/会话和 reply-dispatch 辅助工具 | | `plugin-sdk/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 | - | `plugin-sdk/agent-config-primitives` | 精简的智能体运行时配置 schema 原语 | + | `plugin-sdk/agent-config-primitives` | 精细的智能体运行时配置 schema 原语 | | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 | | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 | | `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助原语 | | `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 | - | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 | + | `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助工具 | | `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 | - | `plugin-sdk/agent-harness` | 面向低层级智能体 harness 的实验性受信任插件接口：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具、运行时计划工具策略辅助工具、终端结果分类、工具进度格式化/详情辅助工具，以及尝试结果工具函数 | - | `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 | - | `plugin-sdk/async-lock-runtime` | 面向小型运行时状态文件的进程本地异步锁辅助工具 | + | `plugin-sdk/agent-harness` | 面向低层智能体 harness 的实验性受信任插件 interface：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具、运行时计划工具策略辅助工具、终端结果分类、工具进度格式化/细节辅助工具，以及尝试结果工具 | + | `plugin-sdk/provider-zai-endpoint` | Z.A.I 端点检测辅助工具 | + | `plugin-sdk/async-lock-runtime` | 用于小型运行时状态文件的进程本地异步锁辅助工具 | | `plugin-sdk/channel-activity-runtime` | 渠道活动遥测辅助工具 | | `plugin-sdk/concurrency-runtime` | 有界异步任务并发辅助工具 | | `plugin-sdk/dedupe-runtime` | 内存去重缓存辅助工具 | @@ -233,19 +233,19 @@ x-i18n: | `plugin-sdk/transport-ready-runtime` | 传输就绪等待辅助工具 | | `plugin-sdk/infra-runtime` | 已弃用的兼容性 shim；请使用上面更聚焦的运行时子路径 | | `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 | - | `plugin-sdk/diagnostic-runtime` | 诊断标志、事件和 trace-context 辅助工具 | - | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和 pinned 查找辅助工具 | - | `plugin-sdk/runtime-fetch` | 具备 dispatcher 感知能力的运行时 fetch，不引入 proxy/guarded-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/diagnostic-runtime` | 诊断标记、事件和 trace-context 辅助工具 | + | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具，以及 `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和 pinned 查找辅助工具 | + | `plugin-sdk/runtime-fetch` | 感知 dispatcher 的运行时 fetch，不引入代理/受保护 fetch 导入 | + | `plugin-sdk/response-limit-runtime` | 不依赖宽泛 media runtime interface 的有界响应体读取器 | + | `plugin-sdk/session-binding-runtime` | 当前会话绑定状态，不包含已配置绑定路由或配对存储 | + | `plugin-sdk/session-store-runtime` | 不引入宽泛配置写入/维护导入的会话存储辅助工具 | + | `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不引入宽泛配置/安全导入 | + | `plugin-sdk/string-coerce-runtime` | 不引入 Markdown/日志导入的精细原始值 record/字符串强制转换与规范化辅助工具 | | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 | - | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 | + | `plugin-sdk/retry-runtime` | 重试配置和重试执行器辅助工具 | | `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 | - | `plugin-sdk/directory-runtime` | 由配置支持的目录查询/去重 | + | `plugin-sdk/directory-runtime` | 配置支持的目录查询/去重 | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | @@ -253,68 +253,69 @@ x-i18n: | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具，以及媒体载荷构建器 | - | `plugin-sdk/media-store` | 精简的媒体存储辅助工具，例如 `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障切换辅助工具、候选项选择和缺失模型提示消息 | - | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助工具导出 | - | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如对智能体可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本工具 | + | `plugin-sdk/media-store` | 精细的媒体存储辅助工具，例如 `saveMediaBuffer` | + | `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/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/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` | 面向旧版插件测试的广泛兼容 barrel。新的扩展测试应改为导入更聚焦的 SDK 子路径，例如 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/test-env` 或 `plugin-sdk/test-fixtures` | - | `plugin-sdk/plugin-test-api` | 最小化的 `createTestPluginApi` 辅助工具，用于直接插件注册单元测试，无需导入仓库测试辅助桥接 | - | `plugin-sdk/channel-test-helpers` | 面向渠道的测试辅助工具，适用于通用操作/设置/状态契约、目录断言、账号启动生命周期、发送配置线程化、运行时 mock、状态问题、出站投递和钩子注册 | - | `plugin-sdk/plugin-test-contracts` | 插件包、注册、公共产物、直接导入、运行时 API 和导入副作用契约辅助工具 | - | `plugin-sdk/provider-test-contracts` | 提供商运行时、认证、发现、新手引导、目录、向导、web 搜索/抓取和流契约辅助工具 | - | `plugin-sdk/test-fixtures` | 通用 CLI 运行时捕获、沙箱上下文、Skill 写入器、智能体消息、系统事件、终端文本、分块、认证令牌和类型化测试用例夹具 | + | `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` | + | `plugin-sdk/testing` | 面向旧版插件测试的宽兼容 barrel。新的扩展测试应改为导入更聚焦的 SDK 子路径，例如 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/test-env` 或 `plugin-sdk/test-fixtures` | + | `plugin-sdk/plugin-test-api` | 最小 `createTestPluginApi` 辅助工具，用于直接插件注册单元测试，无需导入仓库测试辅助桥接 | + | `plugin-sdk/channel-test-helpers` | 面向渠道的测试辅助工具，用于通用 actions/setup/status 契约、目录断言、账户启动生命周期、send-config 线程、运行时 mock、状态问题、出站投递和钩子注册 | + | `plugin-sdk/channel-target-testing` | 面向渠道测试的共享目标解析错误场景套件 | + | `plugin-sdk/plugin-test-contracts` | 插件 package、注册、公共产物、直接导入、运行时 API 和导入副作用契约辅助工具 | + | `plugin-sdk/provider-test-contracts` | 提供商运行时、认证、发现、新手引导、目录、向导、web-search/fetch 和流契约辅助工具 | + | `plugin-sdk/test-fixtures` | 通用 CLI 运行时捕获、沙箱上下文、Skills 写入器、智能体消息、系统事件、终端文本、分块处理、auth-token 和类型化用例夹具 | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/memory-core` | 用于 manager/config/file/CLI 辅助工具的内置 memory-core 辅助接口 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时外观层 | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助 interface，用于 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-embeddings` | Memory 主机 embedding 契约、注册表访问、本地提供商，以及通用批处理/远程辅助工具 | | `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-secret` | Memory 主机 secret 辅助工具 | | `plugin-sdk/memory-core-host-events` | Memory 主机事件日志辅助工具 | | `plugin-sdk/memory-core-host-status` | Memory 主机状态辅助工具 | | `plugin-sdk/memory-core-host-runtime-cli` | Memory 主机 CLI 运行时辅助工具 | | `plugin-sdk/memory-core-host-runtime-core` | Memory 主机核心运行时辅助工具 | | `plugin-sdk/memory-core-host-runtime-files` | Memory 主机文件/运行时辅助工具 | - | `plugin-sdk/memory-host-core` | 面向厂商中立的别名，用于 Memory 主机核心运行时辅助工具 | - | `plugin-sdk/memory-host-events` | 面向厂商中立的别名，用于 Memory 主机事件日志辅助工具 | - | `plugin-sdk/memory-host-files` | 面向厂商中立的别名，用于 Memory 主机文件/运行时辅助工具 | - | `plugin-sdk/memory-host-markdown` | 面向与 Memory 相邻插件的共享托管 Markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 面向搜索管理器访问的活动 Memory 运行时外观层 | - | `plugin-sdk/memory-host-status` | 面向厂商中立的别名，用于 Memory 主机状态辅助工具 | - | `plugin-sdk/memory-lancedb` | 内置的 Memory LanceDB 辅助接口 | + | `plugin-sdk/memory-host-core` | 面向供应商中立的别名，用于 Memory 主机核心运行时辅助工具 | + | `plugin-sdk/memory-host-events` | 面向供应商中立的别名，用于 Memory 主机事件日志辅助工具 | + | `plugin-sdk/memory-host-files` | 面向供应商中立的别名，用于 Memory 主机文件/运行时辅助工具 | + | `plugin-sdk/memory-host-markdown` | 面向 Memory 相关插件的共享托管 Markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活动 Memory 运行时门面 | + | `plugin-sdk/memory-host-status` | 面向供应商中立的别名，用于 Memory 主机状态辅助工具 | + | `plugin-sdk/memory-lancedb` | 内置 Memory LanceDB 辅助 interface | - | 家族 | 当前子路径 | 预期用途 | + | Family | 当前子路径 | 预期用途 | | --- | --- | --- | - | 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-profiles` 导出 `resolveBrowserConfig`、`resolveProfile`、`ResolvedBrowserConfig`、`ResolvedBrowserProfile` 和 `ResolvedBrowserTabCleanupConfig`，用于规范化后的 `browser.tabCleanup` 结构。`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/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | 已弃用的内置渠道兼容性/辅助接缝。新插件应导入通用 SDK 子路径或插件本地 barrel。 | - | 认证/插件专用辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接缝；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | + | 浏览器 | `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-profiles` 导出 `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` 和 `ResolvedBrowserTabCleanupConfig`，用于规范化后的 `browser.tabCleanup` 结构。`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 辅助/运行时 interface | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时 interface | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助 interface | + | 渠道特定辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | 已弃用的内置渠道兼容性/辅助接缝。新插件应导入通用 SDK 子路径或插件本地 barrel。 | + | 认证/插件特定辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接缝；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | diff --git a/docs/zh-CN/plugins/sdk-testing.md b/docs/zh-CN/plugins/sdk-testing.md index 7cbfc9a94..bd1b2c0b1 100644 --- a/docs/zh-CN/plugins/sdk-testing.md +++ b/docs/zh-CN/plugins/sdk-testing.md @@ -1,16 +1,16 @@ --- read_when: - 你正在为一个插件编写测试 - - 你需要使用来自插件 SDK 的测试工具 + - 你需要来自插件 SDK 的测试工具 - 你想了解内置插件的契约测试 sidebarTitle: Testing -summary: OpenClaw 插件的测试工具和模式 +summary: OpenClaw 插件的测试工具与模式 title: 插件测试 x-i18n: - generated_at: "2026-04-28T00:49:38Z" + generated_at: "2026-04-28T01:06:38Z" model: gpt-5.4 provider: openai - source_hash: 7094c305cb48978b6d5fb1afd964d10e088a5d7195b65255574afa1dac719502 + source_hash: 0f9a601a4e4eb479c242ea3c59771c6a033dad6b75d616d9977c1614087dc002 source_path: plugins/sdk-testing.md workflow: 15 --- @@ -18,7 +18,7 @@ x-i18n: OpenClaw 插件的测试工具、模式以及 lint 强制规则参考。 - **在找测试示例？** 操作指南中包含可直接参考的测试示例： + **在找测试示例？** 操作指南包含完整的测试示例： [渠道插件测试](/zh-CN/plugins/sdk-channel-plugins#step-6-test) 和 [提供商插件测试](/zh-CN/plugins/sdk-provider-plugins#step-6-test)。 @@ -27,28 +27,34 @@ OpenClaw 插件的测试工具、模式以及 lint 强制规则参考。 **兼容性导入：** `openclaw/plugin-sdk/testing` -**插件 API 模拟导入：** `openclaw/plugin-sdk/plugin-test-api` +**插件 API mock 导入：** `openclaw/plugin-sdk/plugin-test-api` **渠道契约导入：** `openclaw/plugin-sdk/channel-contract-testing` **渠道测试辅助导入：** `openclaw/plugin-sdk/channel-test-helpers` +**渠道目标测试导入：** `openclaw/plugin-sdk/channel-target-testing` + **插件契约导入：** `openclaw/plugin-sdk/plugin-test-contracts` **插件运行时测试导入：** `openclaw/plugin-sdk/plugin-test-runtime` **提供商契约导入：** `openclaw/plugin-sdk/provider-test-contracts` -**环境/网络测试导入：** `openclaw/plugin-sdk/test-env` +**环境 / 网络测试导入：** `openclaw/plugin-sdk/test-env` **通用夹具导入：** `openclaw/plugin-sdk/test-fixtures` 对于新的插件测试，优先使用下面这些聚焦的子路径。较宽泛的 -`openclaw/plugin-sdk/testing` barrel 仍保留，用于兼容旧测试 -以及尚未迁移到更窄、已文档化接口的辅助工具。 +`openclaw/plugin-sdk/testing` barrel 仍保留，用于兼容较旧的测试 +以及尚未迁移到更窄且已有文档说明的公开接口的辅助工具。 ```typescript -import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/testing"; +import { + shouldAckReaction, + removeAckReactionAfterReply, +} from "openclaw/plugin-sdk/channel-feedback"; +import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/channel-target-testing"; import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api"; import { expectChannelInboundContextContract } from "openclaw/plugin-sdk/channel-contract-testing"; import { createStartAccountContext } from "openclaw/plugin-sdk/channel-test-helpers"; @@ -61,61 +67,60 @@ import { createCliRuntimeCapture, typedCases } from "openclaw/plugin-sdk/test-fi ### 可用导出 -| 导出 | 用途 | -| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `createTestPluginApi` | 为直接注册的单元测试构建一个最小插件 API 模拟对象。从 `plugin-sdk/plugin-test-api` 导入 | -| `expectChannelInboundContextContract` | 断言渠道入站上下文的结构。从 `plugin-sdk/channel-contract-testing` 导入 | -| `installChannelOutboundPayloadContractSuite` | 安装渠道出站负载契约用例。从 `plugin-sdk/channel-contract-testing` 导入 | -| `createStartAccountContext` | 构建渠道账户生命周期上下文。从 `plugin-sdk/channel-test-helpers` 导入 | -| `installChannelActionsContractSuite` | 安装通用渠道消息操作契约用例。从 `plugin-sdk/channel-test-helpers` 导入 | -| `installChannelSetupContractSuite` | 安装通用渠道设置契约用例。从 `plugin-sdk/channel-test-helpers` 导入 | -| `installChannelStatusContractSuite` | 安装通用渠道 Status 契约用例。从 `plugin-sdk/channel-test-helpers` 导入 | -| `expectDirectoryIds` | 从目录列表函数中断言渠道目录 id。从 `plugin-sdk/channel-test-helpers` 导入 | -| `describePluginRegistrationContract` | 安装插件注册契约检查。从 `plugin-sdk/plugin-test-contracts` 导入 | -| `registerSingleProviderPlugin` | 在加载器冒烟测试中注册单个提供商插件。从 `plugin-sdk/plugin-test-runtime` 导入 | -| `registerProviderPlugin` | 从单个插件中捕获所有提供商类型。从 `plugin-sdk/plugin-test-runtime` 导入 | -| `registerProviderPlugins` | 跨多个插件捕获提供商注册。从 `plugin-sdk/plugin-test-runtime` 导入 | -| `requireRegisteredProvider` | 断言一个提供商集合包含某个 id。从 `plugin-sdk/plugin-test-runtime` 导入 | -| `createRuntimeEnv` | 构建一个模拟的 CLI/插件运行时环境。从 `plugin-sdk/plugin-test-runtime` 导入 | -| `createPluginSetupWizardStatus` | 为渠道插件构建设置向导 Status 辅助工具。从 `plugin-sdk/plugin-test-runtime` 导入 | -| `describeOpenAIProviderRuntimeContract` | 安装提供商家族运行时契约检查。从 `plugin-sdk/provider-test-contracts` 导入 | -| `installCommonResolveTargetErrorCases` | 用于目标解析错误处理的共享测试用例。在出现更窄的目标解析测试子路径之前，从 `plugin-sdk/testing` 导入 | -| `shouldAckReaction` | 检查某个渠道是否应添加 ack 反应。在出现更窄的反应测试子路径之前，从 `plugin-sdk/testing` 导入 | -| `removeAckReactionAfterReply` | 在回复送达后移除 ack 反应。在出现更窄的反应测试子路径之前，从 `plugin-sdk/testing` 导入 | -| `createTestRegistry` | 构建渠道插件注册表夹具。从 `plugin-sdk/plugin-test-runtime` 或 `plugin-sdk/channel-test-helpers` 导入 | -| `createEmptyPluginRegistry` | 构建空插件注册表夹具。从 `plugin-sdk/plugin-test-runtime` 或 `plugin-sdk/channel-test-helpers` 导入 | -| `setActivePluginRegistry` | 为插件运行时测试安装注册表夹具。从 `plugin-sdk/plugin-test-runtime` 或 `plugin-sdk/channel-test-helpers` 导入 | -| `createRequestCaptureJsonFetch` | 在媒体辅助测试中捕获 JSON fetch 请求。从 `plugin-sdk/test-env` 导入 | -| `withFetchPreconnect` | 在安装了 preconnect 钩子的情况下运行 fetch 测试。从 `plugin-sdk/test-env` 导入 | -| `withEnv` / `withEnvAsync` | 临时修改环境变量。从 `plugin-sdk/test-env` 导入 | -| `createTempHomeEnv` / `withTempDir` | 创建隔离的文件系统测试夹具。从 `plugin-sdk/test-env` 导入 | -| `createMockServerResponse` | 创建一个最小 HTTP 服务器响应模拟对象。从 `plugin-sdk/test-env` 导入 | -| `createCliRuntimeCapture` | 在测试中捕获 CLI 运行时输出。从 `plugin-sdk/test-fixtures` 导入 | -| `createSandboxTestContext` | 构建沙箱测试上下文。从 `plugin-sdk/test-fixtures` 导入 | -| `writeSkill` | 写入 Skills 夹具。从 `plugin-sdk/test-fixtures` 导入 | -| `makeAgentAssistantMessage` | 构建智能体转录消息夹具。从 `plugin-sdk/test-fixtures` 导入 | -| `peekSystemEvents` / `resetSystemEventsForTest` | 检查并重置系统事件夹具。从 `plugin-sdk/test-fixtures` 导入 | -| `sanitizeTerminalText` | 对终端输出进行净化以便断言。从 `plugin-sdk/test-fixtures` 导入 | -| `countLines` / `hasBalancedFences` | 断言分块输出的结构。从 `plugin-sdk/test-fixtures` 导入 | -| `runProviderCatalog` | 使用测试依赖执行提供商目录钩子 | -| `resolveProviderWizardOptions` | 在契约测试中解析提供商设置向导选项 | -| `resolveProviderModelPickerEntries` | 在契约测试中解析提供商模型选择器条目 | -| `buildProviderPluginMethodChoice` | 构建用于断言的提供商向导选项 id | -| `setProviderWizardProvidersResolverForTest` | 为隔离测试注入提供商向导提供商 | -| `createProviderUsageFetch` | 构建提供商使用量 fetch 夹具 | -| `useFrozenTime` / `useRealTime` | 为时间敏感测试冻结并恢复计时器。从 `plugin-sdk/test-env` 导入 | -| `createTestWizardPrompter` | 构建一个模拟的设置向导提示器 | -| `createRuntimeTaskFlow` | 创建隔离的运行时任务流状态 | -| `typedCases` | 为表驱动测试保留字面量类型。从 `plugin-sdk/test-fixtures` 导入 | +| 导出 | 用途 | +| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `createTestPluginApi` | 为直接注册单元测试构建最小化的插件 API mock。从 `plugin-sdk/plugin-test-api` 导入 | +| `expectChannelInboundContextContract` | 断言渠道入站上下文的结构。从 `plugin-sdk/channel-contract-testing` 导入 | +| `installChannelOutboundPayloadContractSuite` | 安装渠道出站负载契约测试用例。从 `plugin-sdk/channel-contract-testing` 导入 | +| `createStartAccountContext` | 构建渠道账户生命周期上下文。从 `plugin-sdk/channel-test-helpers` 导入 | +| `installChannelActionsContractSuite` | 安装通用的渠道消息操作契约测试用例。从 `plugin-sdk/channel-test-helpers` 导入 | +| `installChannelSetupContractSuite` | 安装通用的渠道设置契约测试用例。从 `plugin-sdk/channel-test-helpers` 导入 | +| `installChannelStatusContractSuite` | 安装通用的渠道 Status 契约测试用例。从 `plugin-sdk/channel-test-helpers` 导入 | +| `expectDirectoryIds` | 从目录列表函数中断言渠道目录 id。从 `plugin-sdk/channel-test-helpers` 导入 | +| `describePluginRegistrationContract` | 安装插件注册契约检查。从 `plugin-sdk/plugin-test-contracts` 导入 | +| `registerSingleProviderPlugin` | 在加载器冒烟测试中注册一个 provider 插件。从 `plugin-sdk/plugin-test-runtime` 导入 | +| `registerProviderPlugin` | 从单个插件中捕获所有 provider 类型。从 `plugin-sdk/plugin-test-runtime` 导入 | +| `registerProviderPlugins` | 跨多个插件捕获 provider 注册。从 `plugin-sdk/plugin-test-runtime` 导入 | +| `requireRegisteredProvider` | 断言某个 provider 集合包含一个 id。从 `plugin-sdk/plugin-test-runtime` 导入 | +| `createRuntimeEnv` | 构建一个已 mock 的 CLI / 插件运行时环境。从 `plugin-sdk/plugin-test-runtime` 导入 | +| `createPluginSetupWizardStatus` | 为渠道插件构建设置向导 Status 辅助工具。从 `plugin-sdk/plugin-test-runtime` 导入 | +| `describeOpenAIProviderRuntimeContract` | 安装 provider 系列运行时契约检查。从 `plugin-sdk/provider-test-contracts` 导入 | +| `installCommonResolveTargetErrorCases` | 用于目标解析错误处理的共享测试用例。从 `plugin-sdk/channel-target-testing` 导入 | +| `shouldAckReaction` | 检查渠道是否应添加确认反应。从 `plugin-sdk/channel-feedback` 导入 | +| `removeAckReactionAfterReply` | 在回复发送后移除确认反应。从 `plugin-sdk/channel-feedback` 导入 | +| `createTestRegistry` | 构建渠道插件注册表夹具。从 `plugin-sdk/plugin-test-runtime` 或 `plugin-sdk/channel-test-helpers` 导入 | +| `createEmptyPluginRegistry` | 构建空的插件注册表夹具。从 `plugin-sdk/plugin-test-runtime` 或 `plugin-sdk/channel-test-helpers` 导入 | +| `setActivePluginRegistry` | 为插件运行时测试安装注册表夹具。从 `plugin-sdk/plugin-test-runtime` 或 `plugin-sdk/channel-test-helpers` 导入 | +| `createRequestCaptureJsonFetch` | 在媒体辅助测试中捕获 JSON fetch 请求。从 `plugin-sdk/test-env` 导入 | +| `withFetchPreconnect` | 在安装了预连接钩子的情况下运行 fetch 测试。从 `plugin-sdk/test-env` 导入 | +| `withEnv` / `withEnvAsync` | 临时修补环境变量。从 `plugin-sdk/test-env` 导入 | +| `createTempHomeEnv` / `withTempDir` | 创建隔离的文件系统测试夹具。从 `plugin-sdk/test-env` 导入 | +| `createMockServerResponse` | 创建最小化的 HTTP 服务器响应 mock。从 `plugin-sdk/test-env` 导入 | +| `createCliRuntimeCapture` | 在测试中捕获 CLI 运行时输出。从 `plugin-sdk/test-fixtures` 导入 | +| `createSandboxTestContext` | 构建沙箱测试上下文。从 `plugin-sdk/test-fixtures` 导入 | +| `writeSkill` | 写入 Skills 夹具。从 `plugin-sdk/test-fixtures` 导入 | +| `makeAgentAssistantMessage` | 构建智能体对话消息夹具。从 `plugin-sdk/test-fixtures` 导入 | +| `peekSystemEvents` / `resetSystemEventsForTest` | 检查并重置系统事件夹具。从 `plugin-sdk/test-fixtures` 导入 | +| `sanitizeTerminalText` | 清理终端输出以便断言。从 `plugin-sdk/test-fixtures` 导入 | +| `countLines` / `hasBalancedFences` | 断言分块输出的结构。从 `plugin-sdk/test-fixtures` 导入 | +| `runProviderCatalog` | 使用测试依赖执行 provider 目录钩子 | +| `resolveProviderWizardOptions` | 在契约测试中解析 provider 设置向导选项 | +| `resolveProviderModelPickerEntries` | 在契约测试中解析 provider 模型选择器条目 | +| `buildProviderPluginMethodChoice` | 为断言构建 provider 向导选项 id | +| `setProviderWizardProvidersResolverForTest` | 为隔离测试注入 provider 向导提供商 | +| `createProviderUsageFetch` | 构建 provider 使用量 fetch 夹具 | +| `useFrozenTime` / `useRealTime` | 为时间敏感测试冻结和恢复计时器。从 `plugin-sdk/test-env` 导入 | +| `createTestWizardPrompter` | 构建一个已 mock 的设置向导提示器 | +| `createRuntimeTaskFlow` | 创建隔离的运行时任务流状态 | +| `typedCases` | 为表驱动测试保留字面量类型。从 `plugin-sdk/test-fixtures` 导入 | -内置插件契约测试套件也会使用 SDK 测试子路径中的仅测试用注册表、 -manifest、公共构件和运行时夹具辅助工具。依赖 OpenClaw 内置清单的仅核心测试套件仍保留在 `src/plugins/contracts` 下。 -新的扩展测试应放在已文档化的聚焦 SDK 子路径上，例如 +内置插件契约测试套件也会使用 SDK 测试子路径中的仅测试用注册表、清单、公共产物和运行时夹具辅助工具。依赖内置 OpenClaw 清单的仅 core 测试套件仍保留在 `src/plugins/contracts` 下。 +新的扩展测试应放在有文档说明的聚焦 SDK 子路径上，例如 `plugin-sdk/plugin-test-api`、`plugin-sdk/channel-contract-testing`、 `plugin-sdk/channel-test-helpers`、`plugin-sdk/plugin-test-contracts`、 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/provider-test-contracts`、 `plugin-sdk/test-env` 或 `plugin-sdk/test-fixtures`，而不是导入宽泛的 -`plugin-sdk/testing` 兼容性 barrel、仓库中的 `src/**` 文件，或直接导入仓库中的 +`plugin-sdk/testing` 兼容 barrel、仓库中的 `src/**` 文件，或直接导入仓库 `test/helpers/plugins/*` 桥接层。 ### 类型 @@ -139,7 +144,7 @@ import type { ```typescript import { describe } from "vitest"; -import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/testing"; +import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/channel-target-testing"; describe("my-channel target resolution", () => { installCommonResolveTargetErrorCases({ @@ -161,20 +166,20 @@ describe("my-channel target resolution", () => { ### 测试注册契约 -将手写的 `api` 模拟对象传给 `register(api)` 的单元测试，并不会覆盖 -OpenClaw 加载器的验收门禁。对于你的插件所依赖的每个注册入口面，至少添加一个由加载器驱动的冒烟测试，尤其是钩子和内存这类独占能力。 +将手写的 `api` mock 传给 `register(api)` 的单元测试，并不会覆盖 +OpenClaw 加载器的接入门禁。对于你的插件所依赖的每一种注册接口，至少添加一个由加载器驱动的冒烟测试，尤其是钩子以及像 memory 这类独占能力。 -如果缺少必需的元数据，或者插件调用了其并不拥有的能力 API，真实加载器会使插件注册失败。例如， -`api.registerHook(...)` 需要提供钩子名称，而 +真实加载器会在缺少必需元数据，或插件调用了自己并不拥有的能力 API 时使插件注册失败。例如， +`api.registerHook(...)` 需要一个钩子名称，而 `api.registerMemoryCapability(...)` 则要求插件 manifest 或导出的入口声明 `kind: "memory"`。 ### 测试运行时配置访问 -在测试内置渠道插件时，优先使用来自 `openclaw/plugin-sdk/channel-test-helpers` -的共享插件运行时模拟对象。它已弃用的 `runtime.config.loadConfig()` 和 -`runtime.config.writeConfigFile(...)` 模拟实现默认会抛出异常，这样测试就能捕获对兼容性 API 的新使用。只有当测试明确覆盖旧版兼容行为时，才应覆盖这些模拟实现。 +在测试内置渠道插件时，优先使用来自 `openclaw/plugin-sdk/channel-test-helpers` 的共享插件运行时 mock。 +其中已弃用的 `runtime.config.loadConfig()` 和 +`runtime.config.writeConfigFile(...)` mock 默认会抛出异常，这样测试就能捕获对兼容性 API 的新使用。只有当测试明确覆盖旧版兼容行为时，才重写这些 mock。 -### 对渠道插件做单元测试 +### 对渠道插件进行单元测试 ```typescript import { describe, it, expect, vi } from "vitest"; @@ -210,7 +215,7 @@ describe("my-channel plugin", () => { }); ``` -### 对提供商插件做单元测试 +### 对 provider 插件进行单元测试 ```typescript import { describe, it, expect } from "vitest"; @@ -238,9 +243,9 @@ describe("my-provider plugin", () => { }); ``` -### 模拟插件运行时 +### mock 插件运行时 -对于使用 `createPluginRuntimeStore` 的代码，在测试中应模拟运行时： +对于使用 `createPluginRuntimeStore` 的代码，请在测试中 mock 运行时： ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; @@ -271,9 +276,9 @@ store.setRuntime(mockRuntime); store.clearRuntime(); ``` -### 使用按实例 stub 进行测试 +### 使用实例级 stub 进行测试 -优先使用按实例 stub，而不是修改原型： +优先使用实例级 stub，而不是修改原型： ```typescript // Preferred: per-instance stub @@ -294,14 +299,14 @@ pnpm test -- src/plugins/contracts/ 这些测试会断言： -- 哪些插件注册了哪些提供商 -- 哪些插件注册了哪些语音提供商 -- 注册结构是否正确 -- 是否符合运行时契约 +- 哪些插件注册了哪些 provider +- 哪些插件注册了哪些语音 provider +- 注册结构的正确性 +- 运行时契约合规性 -### 运行指定范围的测试 +### 运行特定范围的测试 -针对某个特定插件： +对于某个特定插件： ```bash pnpm test -- /my-channel/ @@ -315,15 +320,15 @@ pnpm test -- src/plugins/contracts/auth.contract.test.ts pnpm test -- src/plugins/contracts/runtime.contract.test.ts ``` -## lint 强制规则（仓库内插件） +## Lint 强制规则（仓库内插件） 对于仓库内插件，`pnpm check` 会强制执行三条规则： -1. **禁止使用单体根导入** —— 会拒绝 `openclaw/plugin-sdk` 根 barrel +1. **禁止使用单体根导入** —— 拒绝使用 `openclaw/plugin-sdk` 根 barrel 2. **禁止直接导入 `src/`** —— 插件不能直接导入 `../../src/` -3. **禁止自导入** —— 插件不能导入它们自己的 `plugin-sdk/` 子路径 +3. **禁止自我导入** —— 插件不能导入它们自己的 `plugin-sdk/` 子路径 -外部插件不受这些 lint 规则约束，但仍建议遵循相同的模式。 +外部插件不受这些 lint 规则约束，但仍建议遵循相同模式。 ## 测试配置