From ec719c140e9adb50bb24a2fff7d72c35955e78fe Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 28 Apr 2026 03:11:52 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/cli/backup.md | 69 ++-- docs/zh-CN/plugins/sdk-migration.md | 490 +++++++++++++--------------- docs/zh-CN/plugins/sdk-subpaths.md | 293 ++++++++--------- 3 files changed, 413 insertions(+), 439 deletions(-) diff --git a/docs/zh-CN/cli/backup.md b/docs/zh-CN/cli/backup.md index b7ccf2718..4c212a89c 100644 --- a/docs/zh-CN/cli/backup.md +++ b/docs/zh-CN/cli/backup.md @@ -1,21 +1,21 @@ --- read_when: - - 你希望为本地 OpenClaw 状态创建一份一流的备份归档。 - - 在重置或卸载之前，你想先预览将会包含哪些路径。 -summary: 用于 `openclaw backup` 的 CLI 参考（创建本地备份归档） + - 你想为本地 OpenClaw 状态创建一份一流的备份归档 + - 你想在重置或卸载之前预览将包含哪些路径 +summary: '`openclaw backup` 的 CLI 参考（创建本地备份归档）' title: 备份 x-i18n: - generated_at: "2026-04-24T04:00:22Z" + generated_at: "2026-04-28T03:09:13Z" model: gpt-5.4 provider: openai - source_hash: 88d83cf04c163d76658575aa6d90be1dd7379934fa2822a07e13311c4324f8fd + source_hash: 5c16f953bb32a1613181448f0e4c6ba8777383bce95bddc856dc7e1c3afe8550 source_path: cli/backup.md workflow: 15 --- # `openclaw backup` -为 OpenClaw 状态、配置、认证配置文件、渠道/提供商凭证、会话，以及可选的工作区创建本地备份归档。 +为 OpenClaw 的状态、配置、auth 配置文件、渠道/提供商凭证、会话以及可选的工作区创建本地备份归档。 ```bash openclaw backup create @@ -29,60 +29,61 @@ openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz ## 注意事项 -- 归档中包含一个 `manifest.json` 文件，其中记录了解析后的源路径和归档布局。 -- 默认输出是在当前工作目录中生成一个带时间戳的 `.tar.gz` 归档文件。 -- 如果当前工作目录位于某个已备份的源树内，OpenClaw 会回退到你的主目录作为默认归档位置。 -- 现有的归档文件绝不会被覆盖。 -- 位于源状态树或工作区树内部的输出路径会被拒绝，以避免将归档文件自身包含进去。 -- `openclaw backup verify ` 会验证归档是否只包含一个根 `manifest`，拒绝类似路径穿越的归档路径，并检查 `manifest` 中声明的每个有效负载是否都存在于 tarball 中。 +- 该归档包含一个 `manifest.json` 文件，其中记录了解析后的源路径和归档布局。 +- 默认输出为当前工作目录中的一个带时间戳的 `.tar.gz` 归档文件。 +- 如果当前工作目录位于某个已备份的源目录树内，OpenClaw 会回退到你的主目录作为默认归档位置。 +- 现有归档文件绝不会被覆盖。 +- 为避免将归档文件自身包含进去，位于源状态/工作区目录树内的输出路径会被拒绝。 +- `openclaw backup verify ` 会验证归档是否恰好包含一个根清单文件，拒绝类似路径遍历的归档路径，并检查清单中声明的每个有效载荷是否都存在于 tarball 中。 - `openclaw backup create --verify` 会在写入归档后立即运行该验证。 -- `openclaw backup create --only-config` 只会备份当前激活的 JSON 配置文件。 +- `openclaw backup create --only-config` 只会备份当前启用的 JSON 配置文件。 -## 会备份哪些内容 +## 备份内容 -`openclaw backup create` 会根据你的本地 OpenClaw 安装规划备份源： +`openclaw backup create` 会根据你的本地 OpenClaw 安装来规划备份源： -- 由 OpenClaw 本地状态解析器返回的状态目录，通常是 `~/.openclaw` -- 当前激活的配置文件路径 -- 当 `credentials/` 目录位于状态目录之外时，解析得到的 `credentials/` 目录 +- 由 OpenClaw 本地状态解析器返回的状态目录，通常为 `~/.openclaw` +- 当前启用的配置文件路径 +- 当其位于状态目录之外时，解析得到的 `credentials/` 目录 - 从当前配置中发现的工作区目录，除非你传入 `--no-include-workspace` -模型认证配置文件本身已位于状态目录下的 -`agents//agent/auth-profiles.json`，因此通常已经包含在 -状态备份项中。 +模型 auth 配置文件本身已经位于状态目录下的 +`agents//agent/auth-profiles.json`，因此通常已经包含在状态备份条目中。 -如果你使用 `--only-config`，OpenClaw 会跳过状态、凭证目录和工作区发现，仅归档当前激活的配置文件路径。 +如果你使用 `--only-config`，OpenClaw 会跳过状态、凭证目录和工作区发现，仅归档当前启用的配置文件路径。 -OpenClaw 会在构建归档前规范化路径。如果配置、凭证目录或工作区本身已经位于状态目录中，它们不会作为单独的顶级备份源重复收录。缺失的路径会被跳过。 +OpenClaw 会在构建归档前对路径进行规范化。如果配置文件、凭证目录或某个工作区本身已经位于状态目录中，它们不会再作为单独的顶层备份源重复收录。缺失的路径会被跳过。 -归档有效负载会存储这些源树中的文件内容，而内嵌的 `manifest.json` 会记录解析后的绝对源路径，以及每个资源所使用的归档布局。 +归档有效载荷会存储这些源目录树中的文件内容，而嵌入的 `manifest.json` 会记录每个资源对应的已解析绝对源路径以及所使用的归档布局。 + +状态目录下 `extensions/` 目录树中的已安装插件源码和清单文件会被包含，但其嵌套的 `node_modules/` 依赖目录树会被跳过。这些依赖属于可重建的安装产物；恢复归档后，如果某个已恢复的插件报告缺少依赖，请使用 `openclaw plugins update `，或通过 `openclaw plugins install --force` 重新安装该插件。 ## 无效配置时的行为 -`openclaw backup` 会有意绕过常规的配置预检，这样它在恢复场景中仍然可以提供帮助。由于工作区发现依赖于有效配置，当配置文件存在但无效且工作区备份仍然启用时，`openclaw backup create` 现在会快速失败。 +`openclaw backup` 会有意绕过常规的配置预检，因此即使在恢复场景中也能继续提供帮助。由于工作区发现依赖有效配置，当配置文件存在但无效且仍启用了工作区备份时，`openclaw backup create` 现在会快速失败。 -如果在这种情况下你仍然想进行部分备份，请重新运行： +如果你在这种情况下仍想进行部分备份，请重新运行： ```bash openclaw backup create --no-include-workspace ``` -这样会保留状态、配置和外部凭证目录的备份范围，同时完全跳过工作区发现。 +这样会保留状态、配置和外部凭证目录，同时完全跳过工作区发现。 -如果你只需要配置文件本身的副本，`--only-config` 在配置格式错误时也同样可用，因为它不依赖解析配置来发现工作区。 +如果你只需要配置文件本身的副本，`--only-config` 在配置格式错误时同样可用，因为它不依赖解析配置来发现工作区。 -## 大小与性能 +## 大小和性能 -OpenClaw 不会对备份总大小或单个文件大小施加内置上限。 +OpenClaw 不会对备份大小或单个文件大小施加内置上限。 实际限制来自本地机器和目标文件系统： -- 写入临时归档和最终归档所需的可用空间 -- 遍历大型工作区树并将其压缩为 `.tar.gz` 所需的时间 +- 用于临时写入归档以及最终归档的可用空间 +- 遍历大型工作区目录树并将其压缩为 `.tar.gz` 所需的时间 - 如果你使用 `openclaw backup create --verify` 或运行 `openclaw backup verify`，重新扫描归档所需的时间 -- 目标路径上的文件系统行为。OpenClaw 会优先使用“不覆盖”的硬链接发布步骤；当不支持硬链接时，则回退为排他性复制 +- 目标路径上的文件系统行为。OpenClaw 会优先使用“不覆盖”的硬链接发布步骤；当不支持硬链接时，则回退为独占复制 -大型工作区通常是归档体积变大的主要原因。如果你想要更小或更快的备份，请使用 `--no-include-workspace`。 +大型工作区通常是归档体积的主要来源。如果你想要更小或更快的备份，请使用 `--no-include-workspace`。 如果想要最小的归档，请使用 `--only-config`。 diff --git a/docs/zh-CN/plugins/sdk-migration.md b/docs/zh-CN/plugins/sdk-migration.md index 915ff701c..934881b08 100644 --- a/docs/zh-CN/plugins/sdk-migration.md +++ b/docs/zh-CN/plugins/sdk-migration.md @@ -3,71 +3,73 @@ read_when: - 你看到了 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告 - 你看到了 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告 - 你在 OpenClaw 2026.4.25 之前使用了 `api.registerEmbeddedExtensionFactory` - - 你正在将插件更新到现代插件架构 - - 你维护一个外部 OpenClaw 插件 + - 你正在将一个插件更新到现代插件架构 + - 你在维护一个外部 OpenClaw 插件 sidebarTitle: Migrate to SDK summary: 从旧版向后兼容层迁移到现代插件 SDK title: 插件 SDK 迁移 x-i18n: - generated_at: "2026-04-28T01:47:24Z" + generated_at: "2026-04-28T03:09:21Z" model: gpt-5.4 provider: openai - source_hash: 3d7a656413c7829ba65c81c5d1a96ebea9835ec205b4a08ec0ea6d53ce15141c + source_hash: 330ae4446c56e1a596e6c1b8e198a98bb03b616104efd1b25b4285c2700166c3 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/compat`** —— 一个会重新导出数十个辅助工具的单一导入入口。它的引入是为了在构建新插件架构期间，保持较旧的基于 hook 的插件继续工作。 +- **`openclaw/plugin-sdk/infra-runtime`** —— 一个宽泛的运行时辅助 barrel，混合了系统事件、心跳状态、投递队列、fetch/proxy 辅助工具、文件辅助工具、审批类型以及无关的实用工具。 - **`openclaw/plugin-sdk/config-runtime`** —— 一个宽泛的配置兼容性 barrel，在迁移窗口期间仍然承载已弃用的直接加载/写入辅助工具。 - **`openclaw/extension-api`** —— 一个桥接层，使插件能够直接访问宿主侧辅助工具，例如嵌入式智能体运行器。 -- **`api.registerEmbeddedExtensionFactory(...)`** —— 一个已移除、仅限 Pi 的内置扩展钩子，可观察诸如 `tool_result` 之类的嵌入式运行器事件。 +- **`api.registerEmbeddedExtensionFactory(...)`** —— 一个已移除、仅供 Pi 使用的内置扩展 hook，它曾可观察诸如 `tool_result` 之类的嵌入式运行器事件。 -这些宽泛的导入接口现已被**弃用**。它们在运行时仍然有效，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。仅限 Pi 的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。 +这些宽泛的导入接口现在都已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件则应在下一个主版本移除它们之前完成迁移。仅供 Pi 使用的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。 -OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已有文档说明的插件行为。破坏契约的变更必须先经过兼容适配器、诊断、文档以及弃用窗口。这一规则适用于 SDK 导入、manifest 字段、设置 API、钩子以及运行时注册行为。 +OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已文档化的插件行为。破坏性契约变更必须先经过兼容性适配器、诊断、文档和弃用窗口。这同样适用于 SDK 导入、manifest 字段、设置 API、hooks 和运行时注册行为。 - 向后兼容层将在未来的主版本中移除。到那时，仍从这些接口导入的插件将会失效。仅限 Pi 的嵌入式扩展工厂注册现在已经不再加载。 + 向后兼容层将在未来的主版本中被移除。届时，仍从这些接口面导入内容的插件将会失效。 + 仅供 Pi 使用的嵌入式扩展工厂注册已不再加载。 -## 为什么会有这次变化 +## 为什么会有这项变更 -旧方法会带来这些问题： +旧方法带来了这些问题： - **启动缓慢** —— 导入一个辅助工具会加载数十个无关模块 -- **循环依赖** —— 宽泛的重新导出很容易造成导入循环 +- **循环依赖** —— 宽泛的重新导出使创建导入循环变得很容易 - **API 接口面不清晰** —— 无法判断哪些导出是稳定的，哪些属于内部实现 -现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有明确用途和文档化契约。 +现代插件 SDK 解决了这一点：每个导入路径（`openclaw/plugin-sdk/\`）都是一个小型、自包含的模块，具有明确用途和已文档化的契约。 -面向内置渠道的旧版提供商便捷接口也已移除。 -带有渠道品牌的辅助工具接口属于私有单体仓库捷径，而不是稳定的插件契约。请改用狭窄、通用的 SDK 子路径。在内置插件工作区中，应将提供商自有辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 +面向内置渠道的旧版 provider 便捷接口也已移除。 +带有渠道品牌的辅助接口是私有 monorepo 捷径，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内部，请将 provider 自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。 -当前内置提供商示例： +当前内置 provider 示例： -- Anthropic 将 Claude 专用流式辅助工具保留在自己的 `api.ts` / `contract-api.ts` 接口中 -- OpenAI 将 provider 构建器、默认模型辅助工具和 realtime provider 构建器保留在自己的 `api.ts` 中 -- OpenRouter 将 provider 构建器和新手引导/配置辅助工具保留在自己的 `api.ts` 中 +- Anthropic 将 Claude 专用的流式辅助工具保留在其自己的 `api.ts` / + `contract-api.ts` 接口中 +- OpenAI 将 provider 构建器、默认模型辅助工具和实时 provider 构建器保留在其自己的 `api.ts` 中 +- OpenRouter 将 provider 构建器以及新手引导/配置辅助工具保留在其自己的 `api.ts` 中 ## 兼容性策略 对于外部插件，兼容性工作遵循以下顺序： 1. 添加新契约 -2. 通过兼容适配器保持旧行为继续连通 -3. 发出诊断或警告，明确指出旧路径及其替代方案 +2. 通过兼容性适配器保持旧行为继续连通 +3. 发出点明旧路径及其替代项的诊断或警告 4. 在测试中覆盖两条路径 -5. 为弃用和迁移路径编写文档 -6. 仅在已公布的迁移窗口结束后移除，通常是在主版本中 +5. 记录弃用信息和迁移路径 +6. 仅在已公告的迁移窗口之后移除，通常是在主版本中 -如果某个 manifest 字段仍然被接受，插件作者就可以继续使用它，直到文档和诊断另有说明。新代码应优先使用文档说明的替代方案，但现有插件不应在普通的小版本发布中被破坏。 +如果某个 manifest 字段仍被接受，插件作者就可以继续使用它，直到文档和诊断另有说明。新代码应优先使用已文档化的替代方案，但现有插件不应在普通的次版本发布中被破坏。 ## 如何迁移 @@ -75,9 +77,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({ @@ -88,17 +90,16 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 }); ``` - 当调用方明确知道变更需要一次干净的 Gateway 网关重启时，请使用 - `afterWrite: { mode: "restart", reason: "..." }`；只有当调用方自行负责后续处理，并且有意抑制重载规划器时，才使用 + 当调用方明确知道该变更需要一次干净的 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 网关服务器方法必须使用请求运行时快照，运行时渠道发送/动作/客户端辅助工具必须从其边界接收配置，而长生命周期运行时模块中环境式 `loadConfig()` 调用的允许数量为零。 - 新插件代码还应避免导入宽泛的 - `openclaw/plugin-sdk/config-runtime` 兼容性 barrel。请使用与任务匹配的狭窄 SDK 子路径： + 新插件代码也应避免导入宽泛的 + `openclaw/plugin-sdk/config-runtime` 兼容性 barrel。请使用与任务匹配的窄化 SDK 子路径： | 需求 | 导入 | | --- | --- | @@ -108,19 +109,17 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | 配置写入 | `openclaw/plugin-sdk/config-mutation` | | 会话存储辅助工具 | `openclaw/plugin-sdk/session-store-runtime` | | Markdown 表格配置 | `openclaw/plugin-sdk/markdown-table-runtime` | - | 组策略运行时辅助工具 | `openclaw/plugin-sdk/runtime-group-policy` | + | 群组策略运行时辅助工具 | `openclaw/plugin-sdk/runtime-group-policy` | | Secret 输入解析 | `openclaw/plugin-sdk/secret-input-runtime` | | 模型/会话覆盖 | `openclaw/plugin-sdk/model-session-runtime` | - 内置插件及其测试受到扫描器保护，不得依赖这个宽泛 barrel，这样导入和 mock 才能保持局部且只针对其所需行为。 - 该宽泛 barrel 为了外部兼容性仍然存在，但新代码不应依赖它。 + 内置插件及其测试受到扫描器保护，不得依赖这个宽泛的 barrel，因此导入和 mock 都应局部化到它们实际需要的行为。这个宽泛的 barrel 仍然存在以保持外部兼容性，但新代码不应依赖它。 - 内置插件必须将仅限 Pi 的 - `api.registerEmbeddedExtensionFactory(...)` 工具结果处理器替换为 - 运行时中立的中间件。 + 内置插件必须将仅供 Pi 使用的 + `api.registerEmbeddedExtensionFactory(...)` 工具结果处理器替换为与运行时无关的中间件。 ```typescript // Pi 和 Codex 运行时动态工具 @@ -141,31 +140,32 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 } ``` - 外部插件不能注册工具结果中间件，因为它可以在模型看到高信任工具输出之前对其进行重写。 + 外部插件不能注册工具结果中间件，因为它可以在模型看到高信任度工具输出之前重写这些输出。 支持审批的渠道插件现在通过 - `approvalCapability.nativeRuntime` 加上共享运行时上下文注册表来公开原生审批行为。 + `approvalCapability.nativeRuntime` 加上共享的运行时上下文注册表来暴露原生审批行为。 关键变化： - - 用 `approvalCapability.nativeRuntime` 替换 `approvalCapability.handler.loadRuntime(...)` - - 将审批专用的身份验证/投递从旧版 `plugin.auth` / - `plugin.approvals` 连接方式迁移到 `approvalCapability` + - 将 `approvalCapability.handler.loadRuntime(...)` 替换为 + `approvalCapability.nativeRuntime` + - 将审批专用的 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 hooks 不再由核心读取 + - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道自有的运行时对象，例如客户端、令牌或 Bolt app + - 不要从原生审批处理器发送插件自有的重新路由通知；核心现在根据实际投递结果负责“已路由到其他位置”的通知 + - 在将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 接口。部分 stub 将被拒绝。 - 当前审批能力布局请参见 `/plugins/sdk-channel-plugins`。 + 请参阅 `/plugins/sdk-channel-plugins` 了解当前审批能力布局。 - 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，那么在 Windows 上无法解析的 + 如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，未解析的 Windows `.cmd`/`.bat` wrapper 现在会默认失败关闭，除非你显式传入 `allowShellFallback: true`。 @@ -176,7 +176,8 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 // 之后 const program = applyWindowsSpawnProgramPolicy({ candidate, - // 仅对有意接受 shell 中介回退的受信任兼容调用方设置此项。 + // 仅对受信任的兼容性调用方设置此项，这些调用方明确接受 + // 通过 shell 中介的回退。 allowShellFallback: true, }); ``` @@ -187,7 +188,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - 在你的插件中搜索来自任一已弃用接口的导入： + 在你的插件中搜索来自任一已弃用接口面的导入： ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -198,8 +199,8 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - - 旧接口中的每个导出都映射到一个特定的现代导入路径： + + 旧接口面的每个导出都映射到一个特定的现代导入路径： ```typescript // 之前（已弃用的向后兼容层） @@ -209,7 +210,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // 之后（现代聚焦导入） + // 之后（现代聚焦式导入） import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; @@ -218,15 +219,15 @@ 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 }); ``` - 相同模式也适用于其他旧版桥接辅助工具： + 其他旧版桥接辅助工具也遵循相同模式： | 旧导入 | 现代等价项 | | --- | --- | @@ -236,26 +237,26 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | 会话存储辅助工具 | `api.runtime.agent.session.*` | + | session store helpers | `api.runtime.agent.session.*` | - `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` | + | 待处理投递队列清空 | `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` | - | 代理和受保护的 fetch 辅助工具 | `openclaw/plugin-sdk/fetch-runtime` | + | proxy 和受保护的 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/approval-reply-runtime` | | 错误格式化辅助工具 | `openclaw/plugin-sdk/error-runtime` | | 传输就绪等待 | `openclaw/plugin-sdk/transport-ready-runtime` | | 安全令牌辅助工具 | `openclaw/plugin-sdk/secure-random-runtime` | @@ -264,13 +265,13 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | 进程本地异步锁 | `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 名称仍作为兼容性别名保留，但新插件应使用能够直接描述行为的路由名称： | 旧辅助工具 | 现代辅助工具 | | --- | --- | @@ -282,12 +283,12 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | `comparableChannelTargetsMatch(...)` | `channelRouteTargetsMatchExact(...)` | | `comparableChannelTargetsShareRoute(...)` | `channelRouteTargetsShareConversation(...)` | - 现代路由辅助工具会在原生审批、回复抑制、入站去重、cron 投递和会话路由之间，一致地规范化 `{ channel, to, accountId, threadId }`。 + 现代路由辅助工具会在原生审批、回复抑制、入站去重、cron 投递和会话路由之间，以一致方式规范化 `{ channel, to, accountId, threadId }`。 如果你的插件拥有自定义目标语法，请使用 `resolveChannelRouteTargetWithParser(...)`，将该解析器适配到相同的路由目标契约中。 - + ```bash pnpm build pnpm test -- my-plugin/ @@ -301,182 +302,182 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 | 导入路径 | 用途 | 关键导出 | | --- | --- | --- | | `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` | - | `plugin-sdk/core` | 面向渠道入口定义/构建器的旧版总括重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/core` | 面向渠道入口定义/构建器的旧版总括式重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` | | `plugin-sdk/provider-entry` | 单一 provider 入口辅助工具 | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | 共享设置向导辅助工具 | Allowlist 提示、设置状态构建器 | - | `plugin-sdk/setup-runtime` | 设置阶段运行时辅助工具 | 可安全导入的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 | + | `plugin-sdk/channel-core` | 聚焦式渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | 共享设置向导辅助工具 | Allowlist 提示、设置 Status 构建器 | + | `plugin-sdk/setup-runtime` | 设置阶段运行时辅助工具 | 导入安全的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托式设置代理 | | `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表/配置/动作门控辅助工具 | - | `plugin-sdk/account-id` | account-id 辅助工具 | `DEFAULT_ACCOUNT_ID`、account-id 规范化 | - | `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 狭窄的账户辅助工具 | 账户列表/账户动作辅助工具 | + | `plugin-sdk/account-core` | 多账号辅助工具 | 账号列表/配置/动作门控辅助工具 | + | `plugin-sdk/account-id` | 账号 ID 辅助工具 | `DEFAULT_ACCOUNT_ID`、账号 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` | 回复前缀 + 正在输入连接逻辑 | `createChannelReplyPipeline` | + | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + typing 接线 | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 共享渠道配置 schema 原语和通用构建器本身 | + | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 共享渠道配置 schema 原语和仅通用构建器 | | `plugin-sdk/bundled-channel-config-schema` | 内置配置 schema | 仅供 OpenClaw 维护的内置插件使用；新插件必须定义插件本地 schema | - | `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置配置 schema | 仅为兼容别名；维护中的内置插件请使用 `plugin-sdk/bundled-channel-config-schema` | + | `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置配置 schema | 仅兼容性别名；维护中的内置插件请使用 `plugin-sdk/bundled-channel-config-schema` | | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复/冲突校验 | | `plugin-sdk/channel-policy` | 群组/私信策略解析 | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | 账户状态和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览最终化辅助工具 | + | `plugin-sdk/channel-lifecycle` | 账号状态和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览终结辅助工具 | | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享 route + envelope 构建器辅助工具 | | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录并分发辅助工具 | | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助工具 | | `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 | | `plugin-sdk/outbound-send-deps` | 出站发送依赖辅助工具 | 轻量级 `resolveOutboundSendDep` 查找，无需导入完整出站运行时 | - | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站投递、身份/发送委托、会话、格式化和负载规划辅助工具 | + | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站投递、identity/send delegate、会话、格式化和载荷规划辅助工具 | | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 | - | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 面向旧版字段布局的智能体媒体负载构建器 | - | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅旧版渠道运行时工具 | + | `plugin-sdk/agent-media-payload` | 旧版媒体载荷辅助工具 | 面向旧版字段布局的智能体媒体载荷构建器 | + | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅旧版渠道运行时实用工具 | | `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 | | `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | 宽泛的运行时辅助工具 | 运行时/日志/备份/插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 狭窄的运行时环境辅助工具 | 日志器/运行时环境、超时、重试和退避辅助工具 | - | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/钩子/http/交互辅助工具 | - | `plugin-sdk/hook-runtime` | 钩子管线辅助工具 | 共享 webhook/内部钩子管线辅助工具 | + | `plugin-sdk/runtime` | 宽泛运行时辅助工具 | 运行时/日志/备份/插件安装辅助工具 | + | `plugin-sdk/runtime-env` | 窄化运行时环境辅助工具 | logger/运行时环境、超时、重试和退避辅助工具 | + | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/hooks/http/交互式辅助工具 | + | `plugin-sdk/hook-runtime` | hook 管道辅助工具 | 共享 webhook/内部 hook 管道辅助工具 | | `plugin-sdk/lazy-runtime` | 惰性运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 | | `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 | | `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道状态补丁辅助工具 | | `plugin-sdk/config-runtime` | 已弃用的配置兼容性 shim | 优先使用 `config-types`、`plugin-config-runtime`、`runtime-config-snapshot` 和 `config-mutation` | | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供回退稳定的 Telegram 命令校验辅助工具 | - | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec/插件审批负载、审批能力/profile 辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示路径格式化 | - | `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | 审批人解析、同聊天动作认证 | + | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec/插件审批载荷、审批 capability/profile 辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示路径格式化 | + | `plugin-sdk/approval-auth-runtime` | 审批 auth 辅助工具 | approver 解析、同聊天动作 auth | | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批 profile/filter 辅助工具 | - | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力/投递适配器 | + | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批 capability/delivery 适配器 | | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 面向高热渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽泛的审批处理器运行时辅助工具；如果更狭窄的 adapter/gateway 接口已经足够，应优先使用它们 | - | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标/账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec/插件审批回复负载辅助工具 | + | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 面向热路径渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽泛的审批处理器运行时辅助工具；如果更窄的 adapter/gateway 接口已足够，应优先使用它们 | + | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标/账号绑定辅助工具 | + | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec/插件审批回复载荷辅助工具 | | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register/get/watch 辅助工具 | | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和 secret 收集辅助工具 | - | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 Allowlist 和私有网络策略辅助工具 | + | `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/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` | | `plugin-sdk/diagnostic-runtime` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | | `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 | | `plugin-sdk/fetch-runtime` | 包装后的 fetch/proxy 辅助工具 | `resolveFetch`、proxy 辅助工具 | - | `plugin-sdk/host-runtime` | 宿主规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` | | `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 | | `plugin-sdk/allow-from` | Allowlist 格式化 | `formatAllowFromLowercase` | | `plugin-sdk/allowlist-resolution` | Allowlist 输入映射 | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | 命令门控和命令接口辅助工具 | `resolveControlCommandGate`、发送方授权辅助工具、命令注册表辅助工具（包括动态参数菜单格式化） | - | `plugin-sdk/command-status` | 命令状态/帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `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/webhook-ingress` | webhook 请求辅助工具 | webhook 目标实用工具 | + | `plugin-sdk/webhook-request-guards` | webhook 请求体守卫辅助工具 | 请求体读取/限制辅助工具 | | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 | - | `plugin-sdk/reply-dispatch-runtime` | 狭窄的回复分发辅助工具 | 最终化、provider 分发和会话标签辅助工具 | + | `plugin-sdk/reply-dispatch-runtime` | 窄化回复分发辅助工具 | 终结、provider 分发和会话标签辅助工具 | | `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本/markdown 分块辅助工具 | | `plugin-sdk/session-store-runtime` | 会话存储辅助工具 | 存储路径 + updated-at 辅助工具 | | `plugin-sdk/state-paths` | 状态路径辅助工具 | 状态和 OAuth 目录辅助工具 | | `plugin-sdk/routing` | 路由/会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 | - | `plugin-sdk/status-helpers` | 渠道 Status 辅助工具 | 渠道/账户状态摘要构建器、运行时状态默认值、问题元数据辅助工具 | + | `plugin-sdk/status-helpers` | 渠道 Status 辅助工具 | 渠道/账号 Status 摘要构建器、运行时状态默认值、问题元数据辅助工具 | | `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/param-readers` | 参数读取器 | 常用工具/CLI 参数读取器 | - | `plugin-sdk/tool-payload` | 工具负载提取 | 从工具结果对象中提取规范化负载 | + | `plugin-sdk/param-readers` | 参数读取器 | 通用工具/CLI 参数读取器 | + | `plugin-sdk/tool-payload` | 工具载荷提取 | 从工具结果对象中提取规范化载荷 | | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 | | `plugin-sdk/temp-path` | 临时路径辅助工具 | 共享临时下载路径辅助工具 | | `plugin-sdk/logging-core` | Logging 辅助工具 | 子系统 logger 和脱敏辅助工具 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助工具 | Markdown 表格模式辅助工具 | - | `plugin-sdk/reply-payload` | 消息回复类型 | 回复负载类型 | + | `plugin-sdk/reply-payload` | 消息回复类型 | 回复载荷类型 | | `plugin-sdk/provider-setup` | 精选的本地/自托管 provider 设置辅助工具 | 自托管 provider 发现/配置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管 provider 设置辅助工具 | 相同的自托管 provider 发现/配置辅助工具 | - | `plugin-sdk/provider-auth-runtime` | provider 运行时认证辅助工具 | 运行时 API key 解析辅助工具 | + | `plugin-sdk/self-hosted-provider-setup` | 聚焦式 OpenAI 兼容自托管 provider 设置辅助工具 | 同一组自托管 provider 发现/配置辅助工具 | + | `plugin-sdk/provider-auth-runtime` | provider 运行时 auth 辅助工具 | 运行时 API key 解析辅助工具 | | `plugin-sdk/provider-auth-api-key` | provider API key 设置辅助工具 | API key 新手引导/profile 写入辅助工具 | | `plugin-sdk/provider-auth-result` | provider auth-result 辅助工具 | 标准 OAuth auth-result 构建器 | | `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 endpoint 辅助工具，以及 model-id 规范化辅助工具 | - | `plugin-sdk/provider-catalog-shared` | 共享 provider catalog 辅助工具 | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-env-vars` | provider 环境变量辅助工具 | provider auth 环境变量查找辅助工具 | + | `plugin-sdk/provider-model-shared` | 共享 provider 模型/replay 辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider endpoint 辅助工具，以及 model-id 规范化辅助工具 | + | `plugin-sdk/provider-catalog-shared` | 共享 provider catalog 辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | | `plugin-sdk/provider-onboard` | provider 新手引导补丁 | 新手引导配置辅助工具 | - | `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP/endpoint 能力辅助工具，包括音频转写 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 搜索配置辅助工具 | 适用于不需要插件启用连接逻辑的 provider 的狭窄 web-search 配置/凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | provider Web 搜索契约辅助工具 | 狭窄的 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及有作用域的凭证 setter/getter | - | `plugin-sdk/provider-web-search` | provider Web 搜索辅助工具 | 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-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/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取/转换/存储辅助工具，以及媒体负载构建器 | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 图像/视频/音乐生成的共享故障转移辅助工具、候选项选择和缺失模型提示 | + | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体 fetch/转换/存储辅助工具，以及媒体载荷构建器 | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 图像/视频/音乐生成的共享 failover 辅助工具、候选项选择和缺失模型提示 | | `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解 provider 类型，以及面向 provider 的图像/音频辅助工具导出 | - | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 对智能体可见文本的剥离、markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具，以及相关文本/日志辅助工具 | + | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 对智能体可见文本的剥离、markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本实用工具，以及相关文本/Logging 辅助工具 | | `plugin-sdk/text-chunking` | 文本分块辅助工具 | 出站文本分块辅助工具 | - | `plugin-sdk/speech` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的指令、注册表、校验辅助工具和 OpenAI 兼容的 TTS 构建器 | - | `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、指令、规范化 | - | `plugin-sdk/realtime-transcription` | 实时转写辅助工具 | provider 类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | - | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型、注册表/解析辅助工具，以及桥接会话辅助工具 | - | `plugin-sdk/image-generation` | 图像生成辅助工具 | 图像生成 provider 类型，以及图像资源/data URL 辅助工具 | - | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、认证和注册表辅助工具 | - | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider/请求/结果类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider/请求/结果类型 | - | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载规范化/归约 | - | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 狭窄的渠道配置 schema 原语 | + | `plugin-sdk/speech` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的 directive、注册表、校验辅助工具和 OpenAI 兼容 TTS 构建器 | + | `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、directives、规范化 | + | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | + | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型、注册表/解析辅助工具和 bridge 会话辅助工具 | + | `plugin-sdk/image-generation` | 图像生成辅助工具 | 图像生成 provider 类型，以及图像资产/data URL 辅助工具和 OpenAI 兼容图像 provider 构建器 | + | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、failover、auth 和注册表辅助工具 | + | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider/request/result 类型 | + | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、failover 辅助工具、provider 查找和 model-ref 解析 | + | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider/request/result 类型 | + | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、failover 辅助工具、provider 查找和 model-ref 解析 | + | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复载荷规范化/归约 | + | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄化渠道 config-schema 原语 | | `plugin-sdk/channel-config-writes` | 渠道配置写入辅助工具 | 渠道配置写入授权辅助工具 | | `plugin-sdk/channel-plugin-common` | 共享渠道前导模块 | 共享渠道插件前导导出 | | `plugin-sdk/channel-status` | 渠道 Status 辅助工具 | 共享渠道 Status 快照/摘要辅助工具 | | `plugin-sdk/allowlist-config-edit` | Allowlist 配置辅助工具 | Allowlist 配置编辑/读取辅助工具 | | `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证/守卫辅助工具 | - | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/Status 和环境代理辅助工具原语 | - | `plugin-sdk/webhook-targets` | Webhook 目标辅助工具 | Webhook 目标注册表和路由安装辅助工具 | - | `plugin-sdk/webhook-path` | Webhook 路径辅助工具 | Webhook 路径规范化辅助工具 | + | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信 auth/守卫辅助工具 | + | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/Status 和环境式 proxy 辅助原语 | + | `plugin-sdk/webhook-targets` | webhook 目标辅助工具 | webhook 目标注册表和路由安装辅助工具 | + | `plugin-sdk/webhook-path` | webhook 路径辅助工具 | webhook 路径规范化辅助工具 | | `plugin-sdk/web-media` | 共享 Web 媒体辅助工具 | 远程/本地媒体加载辅助工具 | - | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用方重新导出的 `zod` | - | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | Memory 管理器/配置/文件/CLI 辅助工具接口 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时外观 | Memory 索引/搜索运行时外观 | - | `plugin-sdk/memory-core-host-engine-foundation` | Memory 宿主基础引擎 | Memory 宿主基础引擎导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 宿主嵌入引擎 | Memory 嵌入契约、注册表访问、本地 provider 和通用批处理/远程辅助工具；具体远程 provider 位于各自所属插件中 | - | `plugin-sdk/memory-core-host-engine-qmd` | Memory 宿主 QMD 引擎 | Memory 宿主 QMD 引擎导出 | - | `plugin-sdk/memory-core-host-engine-storage` | Memory 宿主存储引擎 | Memory 宿主存储引擎导出 | - | `plugin-sdk/memory-core-host-multimodal` | Memory 宿主多模态辅助工具 | Memory 宿主多模态辅助工具 | - | `plugin-sdk/memory-core-host-query` | Memory 宿主查询辅助工具 | Memory 宿主查询辅助工具 | - | `plugin-sdk/memory-core-host-secret` | Memory 宿主 secret 辅助工具 | Memory 宿主 secret 辅助工具 | - | `plugin-sdk/memory-core-host-events` | Memory 宿主事件日志辅助工具 | Memory 宿主事件日志辅助工具 | - | `plugin-sdk/memory-core-host-status` | Memory 宿主状态辅助工具 | Memory 宿主状态辅助工具 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory 宿主 CLI 运行时 | Memory 宿主 CLI 运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory 宿主核心运行时 | Memory 宿主核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory 宿主文件/运行时辅助工具 | Memory 宿主文件/运行时辅助工具 | - | `plugin-sdk/memory-host-core` | Memory 宿主核心运行时别名 | 面向厂商中立的 Memory 宿主核心运行时辅助工具别名 | - | `plugin-sdk/memory-host-events` | Memory 宿主事件日志别名 | 面向厂商中立的 Memory 宿主事件日志辅助工具别名 | - | `plugin-sdk/memory-host-files` | Memory 宿主文件/运行时别名 | 面向厂商中立的 Memory 宿主文件/运行时辅助工具别名 | - | `plugin-sdk/memory-host-markdown` | 托管 Markdown 辅助工具 | 面向 Memory 邻接插件的共享托管 Markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 活跃 Memory 搜索外观 | 惰性 active-memory search-manager 运行时外观 | - | `plugin-sdk/memory-host-status` | Memory 宿主状态别名 | 面向厂商中立的 Memory 宿主状态辅助工具别名 | - | `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` | + | `plugin-sdk/zod` | Zod 重新导出 | 面向插件 SDK 使用者重新导出的 `zod` | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | 内存管理器/配置/文件/CLI 辅助接口 | + | `plugin-sdk/memory-core-engine-runtime` | 内存引擎运行时门面 | 内存索引/搜索运行时门面 | + | `plugin-sdk/memory-core-host-engine-foundation` | 内存宿主基础引擎 | 内存宿主基础引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | 内存宿主嵌入引擎 | 内存嵌入契约、注册表访问、本地 provider 和通用批处理/远程辅助工具；具体远程 provider 位于其所属插件中 | + | `plugin-sdk/memory-core-host-engine-qmd` | 内存宿主 QMD 引擎 | 内存宿主 QMD 引擎导出 | + | `plugin-sdk/memory-core-host-engine-storage` | 内存宿主存储引擎 | 内存宿主存储引擎导出 | + | `plugin-sdk/memory-core-host-multimodal` | 内存宿主多模态辅助工具 | 内存宿主多模态辅助工具 | + | `plugin-sdk/memory-core-host-query` | 内存宿主查询辅助工具 | 内存宿主查询辅助工具 | + | `plugin-sdk/memory-core-host-secret` | 内存宿主 secret 辅助工具 | 内存宿主 secret 辅助工具 | + | `plugin-sdk/memory-core-host-events` | 内存宿主事件日志辅助工具 | 内存宿主事件日志辅助工具 | + | `plugin-sdk/memory-core-host-status` | 内存宿主 Status 辅助工具 | 内存宿主 Status 辅助工具 | + | `plugin-sdk/memory-core-host-runtime-cli` | 内存宿主 CLI 运行时 | 内存宿主 CLI 运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-core` | 内存宿主核心运行时 | 内存宿主核心运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-files` | 内存宿主文件/运行时辅助工具 | 内存宿主文件/运行时辅助工具 | + | `plugin-sdk/memory-host-core` | 内存宿主核心运行时别名 | 面向供应商中立的内存宿主核心运行时辅助工具别名 | + | `plugin-sdk/memory-host-events` | 内存宿主事件日志别名 | 面向供应商中立的内存宿主事件日志辅助工具别名 | + | `plugin-sdk/memory-host-files` | 内存宿主文件/运行时别名 | 面向供应商中立的内存宿主文件/运行时辅助工具别名 | + | `plugin-sdk/memory-host-markdown` | 托管 markdown 辅助工具 | 面向 memory 相关插件的共享托管 markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 活跃内存搜索门面 | 惰性 active-memory search-manager 运行时门面 | + | `plugin-sdk/memory-host-status` | 内存宿主 Status 别名 | 面向供应商中立的内存宿主 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 +这个表格刻意只包含常见迁移子集，而不是完整的 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*`。这些接口仍会继续导出，以支持内置插件维护和兼容性，但它们被有意排除在常见迁移表之外，也不是新插件代码的推荐目标。 同样的规则也适用于其他内置辅助工具家族，例如： @@ -494,25 +495,23 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 `plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/thread-ownership`， 以及 `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` 当前公开的是狭窄的令牌辅助工具接口： +`plugin-sdk/github-copilot-token` 当前暴露的是窄化的令牌辅助工具接口： `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` + 会将它们作为兼容性 stub 重新导出。 ```typescript // 之前 @@ -524,94 +523,76 @@ 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` 接口来暴露能力——渠道插件声明它们能够渲染什么 - （卡片、按钮、选择器），而不是声明它们接受哪些原始 - action 名称。 + `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` 辅助工具与原始的 “actions” 渠道导出一同被弃用。请改为通过语义化的 `presentation` 接口暴露 capabilities —— 渠道插件声明它们渲染什么（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(...)` 辅助工具对合成的面向助手的 envelope 仍然受支持，但入站纯文本 envelope 正在逐步淘汰。 - 受影响区域：`inbound_claim`、`message_received`，以及任何会对 - `channelEnvelope` 文本进行后处理的自定义渠道插件。 + 受影响区域：`inbound_claim`、`message_received`，以及任何会后处理 `channelEnvelope` 文本的自定义渠道插件。 - - 四个 discovery 类型别名现在都只是 catalog 时代 - 类型的轻量包装： + + 四个发现类型别名现在已变成 catalog 时代类型的薄包装： | 旧别名 | 新类型 | | ------------------------- | ------------------------- | - | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | - | `ProviderDiscoveryContext`| `ProviderCatalogContext` | - | `ProviderDiscoveryResult` | `ProviderCatalogResult` | - | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | + | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | + | `ProviderDiscoveryContext`| `ProviderCatalogContext` | + | `ProviderDiscoveryResult` | `ProviderCatalogResult` | + | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | - 以及旧版的 `ProviderCapabilities` 静态对象——provider 插件 - 应通过 provider 运行时契约附加能力事实，而不是使用静态对象。 + 此外，还有旧版 `ProviderCapabilities` 静态对象——provider 插件应通过 provider 运行时契约附加 capability 事实，而不是使用静态对象。 - - **旧版**（`ProviderThinkingPolicy` 上的三个独立钩子）： - `isBinaryThinking(ctx)`、`supportsXHighThinking(ctx)`，以及 + + **旧版**（`ProviderThinkingPolicy` 上的三个独立 hook）： + `isBinaryThinking(ctx)`、`supportsXHighThinking(ctx)` 和 `resolveDefaultThinkingLevel(ctx)`。 - **新版**：单一的 `resolveThinkingProfile(ctx)`，返回一个 - `ProviderThinkingProfile`，其中包含规范 `id`、可选 `label` 和 - 排序后的级别列表。OpenClaw 会根据 profile 排名，自动降级过时的已存储值。 + **新版**：单一的 `resolveThinkingProfile(ctx)`，它返回一个 + `ProviderThinkingProfile`，其中包含规范的 `id`、可选的 `label` 以及按等级排序的 level 列表。OpenClaw 会根据 profile rank 自动降级过时的已存储值。 - 只需实现一个钩子，而不是三个。旧版钩子在弃用窗口期间仍然可用， - 但不会与 profile 结果进行组合。 + 现在实现一个 hook 即可，不再需要三个。旧版 hooks 在弃用窗口期间仍可继续使用，但不会与 profile 结果进行组合。 - - **旧版**：实现 `resolveExternalOAuthProfiles(...)`， - 但没有在插件 manifest 中声明该 provider。 + + **旧版**：在插件 manifest 中未声明 provider 的情况下，实现 `resolveExternalOAuthProfiles(...)`。 **新版**：在插件 manifest 中声明 `contracts.externalAuthProviders` - **并且**实现 `resolveExternalAuthProfiles(...)`。旧版 “auth + **并且**实现 `resolveExternalAuthProfiles(...)`。旧版的 “auth fallback” 路径会在运行时发出警告，并将在未来被移除。 ```json @@ -624,52 +605,49 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - + **旧版** manifest 字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。 - **新版**：将相同的环境变量查找镜像到 manifest 中的 `setup.providers[].envVars` - 上。这样可以将设置/状态环境变量元数据集中到同一个 - 位置，并避免仅仅为了回答环境变量查找而启动插件运行时。 + **新版**：将相同的环境变量查找镜像到 manifest 中的 `setup.providers[].envVars`。 + 这样可以将设置/Status 环境变量元数据整合到一个位置，并避免仅为回答环境变量查找而启动插件运行时。 - `providerAuthEnvVars` 在弃用窗口关闭之前， - 仍会通过兼容适配器继续受支持。 + `providerAuthEnvVars` 会通过兼容性适配器继续受支持，直到弃用窗口结束。 - + **旧版**：三个独立调用—— `api.registerMemoryPromptSection(...)`、 `api.registerMemoryFlushPlan(...)`、 `api.registerMemoryRuntime(...)`。 - **新版**：在 memory-state API 上统一调用一次—— + **新版**：在内存状态 API 上使用一次调用—— `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`。 - 相同插槽，单次注册调用。增量式 Memory 辅助工具 + 相同的插槽，单一的注册调用。附加型内存辅助工具 （`registerMemoryPromptSupplement`、`registerMemoryCorpusSupplement`、 `registerMemoryEmbeddingProvider`）不受影响。 - - 仍然从 `src/plugins/runtime/types.ts` 导出的两个旧版类型别名： + + 两个旧版类型别名仍然从 `src/plugins/runtime/types.ts` 导出： | 旧版 | 新版 | | ----------------------------- | ------------------------------- | - | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | - | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | + | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | + | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | 运行时方法 `readSession` 已弃用，改用 `getSessionMessages`。 - 签名相同；旧方法会调用新方法。 + 签名相同；旧方法会透传调用新方法。 - **旧版**：`runtime.tasks.flow`（单数）返回一个实时 task-flow 访问器。 + **旧版**：`runtime.tasks.flow`（单数）返回一个实时任务流访问器。 - **新版**：`runtime.tasks.flows`（复数）返回基于 DTO 的 TaskFlow 访问， - 这种方式可安全导入，并且不需要加载完整任务运行时。 + **新版**：`runtime.tasks.flows`（复数）返回基于 DTO 的 TaskFlow 访问，这种方式是导入安全的，而且不需要加载完整的任务运行时。 ```typescript // 之前 @@ -680,18 +658,15 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 - - 上文“如何迁移 → 将 Pi 工具结果扩展迁移到中间件” - 已经覆盖。这里为了完整性再次列出：已移除的仅限 Pi 的 - `api.registerEmbeddedExtensionFactory(...)` 路径，已被 - `api.registerAgentToolResultMiddleware(...)` 所替代，并且需要在 - `contracts.agentToolResultMiddleware` 中显式声明运行时 - 列表。 + + 上文“如何迁移 → 将 Pi 工具结果扩展迁移到中间件”中已覆盖。这里为完整起见再次列出：已移除、仅供 Pi 使用的 + `api.registerEmbeddedExtensionFactory(...)` 路径，现由 + `api.registerAgentToolResultMiddleware(...)` 替代，并在 `contracts.agentToolResultMiddleware` 中显式声明运行时列表。 - + 从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType` - 现在只是 `OpenClawConfig` 的一行别名。请优先使用规范名称。 + 现在只是 `OpenClawConfig` 的单行别名。请优先使用规范名称。 ```typescript // 之前 @@ -704,11 +679,8 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释 -扩展级别的弃用项（位于 `extensions/` 下内置渠道/provider 插件内部） -会在它们各自的 `api.ts` 和 `runtime-api.ts` -barrel 中跟踪。它们不影响第三方插件契约，因此不会在这里列出。 -如果你直接使用某个内置插件的本地 barrel，请在升级前先阅读该 -barrel 中的弃用注释。 +扩展级弃用项（位于 `extensions/` 下的内置渠道/provider 插件内部）会在它们各自的 `api.ts` 和 `runtime-api.ts` +barrel 中进行跟踪。它们不影响第三方插件契约，因此不在此列出。如果你直接使用某个内置插件的本地 barrel，请在升级前阅读该 barrel 中的弃用注释。 ## 移除时间线 @@ -722,20 +694,20 @@ 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) — 完整子路径导入参考 +- [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/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 e238ad177..4879503bc 100644 --- a/docs/zh-CN/plugins/sdk-subpaths.md +++ b/docs/zh-CN/plugins/sdk-subpaths.md @@ -1,22 +1,23 @@ --- read_when: - 为插件导入选择合适的 plugin-sdk 子路径 - - 审查 bundled-plugin 子路径和辅助接口 -summary: 插件 SDK 子路径目录：按领域分组说明各个导入分别位于哪里 + - 审计内置插件子路径和辅助接口 surface +summary: 插件 SDK 子路径目录：按领域分组，哪些导入位于哪里 title: 插件 SDK 子路径 x-i18n: - generated_at: "2026-04-28T02:44:49Z" + generated_at: "2026-04-28T03:09:11Z" model: gpt-5.4 provider: openai - source_hash: 0c4eab29c94c207a616599216655448dd33ab9e07be1a5391cd5fec63c07d93d + source_hash: 466bde9b1ba40a916e5d352497ff3c5c39758f075d6975d559c4207598ad659f 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`； + 其中也包含为内置插件保留的辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。 - 有关插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 + 有关插件编写指南，请参见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 ## 插件入口 @@ -26,19 +27,19 @@ 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/testing` | 面向旧版插件测试的宽泛兼容性 barrel；新的扩展测试应优先使用聚焦的测试子路径 | | `plugin-sdk/plugin-test-api` | 用于直接插件注册单元测试的最小化 `OpenClawPluginApi` mock 构建器 | - | `plugin-sdk/agent-runtime-test-contracts` | 面向原生 agent-runtime 适配器契约的测试夹具，涵盖 auth profile、交付抑制、回退分类、工具钩子、提示词叠加层、schema 和转录修复 | + | `plugin-sdk/agent-runtime-test-contracts` | 面向原生智能体运行时适配器契约的夹具，涵盖 auth profile、投递抑制、回退分类、工具钩子、提示词覆盖、schema 和转录修复 | | `plugin-sdk/channel-test-helpers` | 渠道账户生命周期、目录、发送配置、运行时 mock、钩子、内置渠道入口、信封时间戳、配对回复，以及通用渠道契约测试辅助工具 | | `plugin-sdk/channel-target-testing` | 共享的渠道目标解析错误场景测试套件 | - | `plugin-sdk/plugin-test-contracts` | 插件注册、包清单、公开产物、运行时 API、导入副作用，以及直接导入契约辅助工具 | - | `plugin-sdk/plugin-test-runtime` | 用于测试的插件运行时、注册表、提供商注册、设置向导，以及运行时任务流夹具 | + | `plugin-sdk/plugin-test-contracts` | 插件注册、包清单、公开构件、运行时 API、导入副作用，以及直接导入契约辅助工具 | + | `plugin-sdk/plugin-test-runtime` | 用于测试的插件运行时、注册表、提供商注册、设置向导和运行时任务流夹具 | | `plugin-sdk/provider-test-contracts` | 提供商运行时、认证、发现、新手引导、目录、媒体能力、重放策略、实时 STT 实时音频、web 搜索 / 抓取，以及向导契约辅助工具 | - | `plugin-sdk/provider-http-test-mocks` | 供提供商测试按需启用的 Vitest HTTP / auth mock，用于覆盖会调用 `plugin-sdk/provider-http` 的场景 | - | `plugin-sdk/test-env` | 测试环境、fetch / 网络、可释放的 HTTP 服务器、传入请求、实时测试、临时文件系统，以及时间控制夹具 | - | `plugin-sdk/test-fixtures` | 通用 CLI、沙箱、Skills、智能体消息、系统事件、模块重载、内置插件路径、终端、分块、auth token，以及类型化测试用例夹具 | + | `plugin-sdk/provider-http-test-mocks` | 为使用 `plugin-sdk/provider-http` 的提供商测试提供可选启用的 Vitest HTTP / 认证 mocks | + | `plugin-sdk/test-env` | 测试环境、fetch / 网络、可释放 HTTP 服务器、传入请求、实时测试、临时文件系统和时间控制夹具 | + | `plugin-sdk/test-fixtures` | 通用 CLI、沙箱、Skills、智能体消息、系统事件、模块重载、内置插件路径、终端、分块、认证令牌，以及类型化测试用例夹具 | | `plugin-sdk/test-node-mocks` | 可在 Vitest `vi.mock("node:*")` 工厂中使用的聚焦型 Node 内置 mock 辅助工具 | - | `plugin-sdk/migration` | 迁移提供商条目辅助工具，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助工具，以及 `summarizeMigrationItems` | + | `plugin-sdk/migration` | 迁移提供商条目辅助工具，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助工具和 `summarizeMigrationItems` | | `plugin-sdk/migration-runtime` | 运行时迁移辅助工具，例如 `copyMigrationFileItem` 和 `writeMigrationReport` | @@ -46,69 +47,69 @@ x-i18n: | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | 根级 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | + | `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | 共享设置向导辅助工具、allowlist 提示、设置状态构建器 | + | `plugin-sdk/setup` | 共享设置向导辅助工具、allowlist 提示和设置状态构建器 | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助工具，默认账户回退辅助工具 | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助工具 | + | `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助工具，以及默认账户回退辅助工具 | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、账户 ID 规范化辅助工具 | | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 精简的账户列表 / 账户操作辅助工具 | + | `plugin-sdk/account-helpers` | 聚焦的账户列表 / 账户操作辅助工具 | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | 共享渠道配置 schema 原语和通用构建器 | - | `plugin-sdk/bundled-channel-config-schema` | 仅供维护中的内置插件使用的内置 OpenClaw 渠道配置 schema | - | `plugin-sdk/channel-config-schema-legacy` | 面向内置渠道配置 schema 的已弃用兼容别名 | - | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 校验辅助工具，带内置契约回退 | - | `plugin-sdk/command-gating` | 精简的命令授权门控辅助工具 | + | `plugin-sdk/bundled-channel-config-schema` | 仅供受维护的内置插件使用的内置 OpenClaw 渠道配置 schemas | + | `plugin-sdk/channel-config-schema-legacy` | 面向内置渠道配置 schemas 的已弃用兼容别名 | + | `plugin-sdk/telegram-command-config` | 带有内置契约回退的 Telegram 自定义命令规范化 / 校验辅助工具 | + | `plugin-sdk/command-gating` | 聚焦的命令授权门控辅助工具 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 最终化辅助工具 | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 完成辅助工具 | | `plugin-sdk/inbound-envelope` | 共享入站路由 + 信封构建辅助工具 | | `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/runtime-config-snapshot` | 运行时配置快照辅助工具 | | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 | - | `plugin-sdk/channel-status` | 共享渠道 Status 快照 / 摘要辅助工具 | - | `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 原语 | + | `plugin-sdk/channel-status` | 共享渠道状态快照 / 摘要辅助工具 | + | `plugin-sdk/channel-config-primitives` | 聚焦的渠道配置 schema 原语 | | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 | | `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 | | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助工具 | | `plugin-sdk/group-access` | 共享群组访问决策辅助工具 | | `plugin-sdk/direct-dm` | 共享直接私信认证 / 守卫辅助工具 | - | `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递，以及旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | 面向入站防抖、提及匹配、提及策略辅助工具和信封辅助工具的兼容性 barrel | - | `plugin-sdk/channel-inbound-debounce` | 精简的入站防抖辅助工具 | - | `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时接口的精简提及策略、提及标记和提及文本辅助工具 | - | `plugin-sdk/channel-envelope` | 精简的入站信封格式化辅助工具 | + | `plugin-sdk/interactive-runtime` | 语义消息呈现、投递和旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | 面向入站去抖动、提及匹配、提及策略辅助工具和信封辅助工具的兼容性 barrel | + | `plugin-sdk/channel-inbound-debounce` | 聚焦的入站去抖动辅助工具 | + | `plugin-sdk/channel-mention-gating` | 不包含更宽泛入站运行时接口的聚焦型提及策略、提及标记和提及文本辅助工具 | + | `plugin-sdk/channel-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` | 共享路由规范化、基于解析器的目标解析、thread-id 字符串化、去重 / 紧凑路由键、已解析目标类型，以及路由 / 目标比较辅助工具 | + | `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为保持插件兼容性而保留的已弃用原生 schema 辅助工具 | + | `plugin-sdk/channel-route` | 共享路由规范化、基于解析器的目标解析、线程 ID 字符串化、去重 / 压缩路由键、已解析目标类型，以及路由 / 目标比较辅助工具 | | `plugin-sdk/channel-targets` | 目标解析辅助工具；路由比较调用方应使用 `plugin-sdk/channel-route` | | `plugin-sdk/channel-contract` | 渠道契约类型 | | `plugin-sdk/channel-feedback` | 反馈 / reaction 接线 | - | `plugin-sdk/channel-secret-runtime` | 精简的 secret 契约辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret 目标类型 | + | `plugin-sdk/channel-secret-runtime` | 聚焦的 secret 契约辅助工具，例如 `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 提供商 facade，用于设置、目录发现和运行时模型准备 | + | `plugin-sdk/lmstudio-runtime` | 受支持的 LM Studio 运行时 facade，用于本地服务器默认值、模型发现、请求头和已加载模型辅助工具 | | `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 新手引导 / profile 写入辅助工具，例如 `upsertApiKeyProfile` | @@ -116,136 +117,136 @@ x-i18n: | `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助工具 | | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助工具 | - | `plugin-sdk/provider-catalog-runtime` | 提供商目录增强运行时钩子，以及面向契约测试的 plugin-provider 注册表接缝 | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助工具，以及 `normalizeNativeXaiModelId` 等模型 ID 规范化辅助工具 | + | `plugin-sdk/provider-catalog-runtime` | 提供商目录增强运行时钩子，以及用于契约测试的插件提供商注册表接缝 | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint 能力辅助工具、提供商 HTTP 错误，以及音频转录 multipart form 辅助工具 | - | `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置 / 选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | + | `plugin-sdk/provider-http` | 通用提供商 HTTP / 端点能力辅助工具、提供商 HTTP 错误，以及音频转录 multipart form 辅助工具 | + | `plugin-sdk/provider-web-fetch-contract` | 聚焦的 web-fetch 配置 / 选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的精简 web-search 配置 / 凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置 / 凭证契约辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及带作用域的凭证 setter / getter | - | `plugin-sdk/provider-web-search` | web-search 提供商注册 / 缓存 / 运行时辅助工具 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容辅助工具 | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似导出 | + | `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-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-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息转换和可写传输事件流 | | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 | | `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助工具 | - | `plugin-sdk/group-activation` | 精简的群组激活模式和命令解析辅助工具 | + | `plugin-sdk/group-activation` | 聚焦的群组激活模式和命令解析辅助工具 | - + | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具（包括动态参数菜单格式化）、发送者授权辅助工具 | | `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天内操作认证辅助工具 | + | `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天中的操作认证辅助工具 | | `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile / 过滤辅助工具 | | `plugin-sdk/approval-delivery-runtime` | 原生审批能力 / 投递适配器 | | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 面向热渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；当更精简的适配器 / Gateway 网关接缝已足够时，优先使用后者 | + | `plugin-sdk/approval-handler-adapter-runtime` | 面向高频渠道入口点的轻量级原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 范围更广的审批处理器运行时辅助工具；如果更窄的 adapter / gateway 接缝已足够，应优先使用它们 | | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 | | `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复负载辅助工具 | - | `plugin-sdk/approval-runtime` | exec / 插件审批负载辅助工具、原生审批路由 / 运行时辅助工具，以及结构化审批显示辅助工具，例如 `formatApprovalDisplayPath` | - | `plugin-sdk/reply-dedupe` | 精简的入站回复去重重置辅助工具 | - | `plugin-sdk/channel-contract-testing` | 不包含宽泛 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` | 原生命令认证、动态参数菜单格式化和原生会话目标辅助工具 | | `plugin-sdk/command-detection` | 共享命令检测辅助工具 | - | `plugin-sdk/command-primitives-runtime` | 面向热渠道路径的轻量级命令文本谓词 | - | `plugin-sdk/command-surface` | 命令体规范化和命令接口辅助工具 | + | `plugin-sdk/command-primitives-runtime` | 面向高频渠道路径的轻量级命令文本谓词 | + | `plugin-sdk/command-surface` | 命令体规范化和命令 surface 辅助工具 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret 接口的精简 secret 契约收集辅助工具 | - | `plugin-sdk/secret-ref-runtime` | 面向 secret 契约 / 配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助工具 | + | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret surface 的聚焦型 secret 契约收集辅助工具 | + | `plugin-sdk/secret-ref-runtime` | 面向 secret 契约 / 配置解析的聚焦型 `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/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` | 请求体大小 / 超时辅助工具 | - + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 广泛的运行时 / 日志 / 备份 / 插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 精简的运行时环境、logger、超时、重试和退避辅助工具 | - | `plugin-sdk/browser-config` | 受支持的浏览器配置门面，用于规范化 profile / 默认值、CDP URL 解析和 browser-control 认证辅助工具 | - | `plugin-sdk/channel-runtime-context` | 通用渠道 runtime-context 注册和查找辅助工具 | + | `plugin-sdk/runtime` | 宽泛的运行时 / 日志 / 备份 / 插件安装辅助工具 | + | `plugin-sdk/runtime-env` | 聚焦的运行时环境、logger、超时、重试和退避辅助工具 | + | `plugin-sdk/browser-config` | 受支持的浏览器配置 facade，用于规范化 profile / 默认值、CDP URL 解析和浏览器控制认证辅助工具 | + | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助工具 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | 共享插件命令 / hook / HTTP / 交互式辅助工具 | - | `plugin-sdk/hook-runtime` | 共享 webhook / 内部钩子管道辅助工具 | - | `plugin-sdk/lazy-runtime` | 惰性运行时导入 / 绑定辅助工具，例如 `createLazyRuntimeModule`, `createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | + | `plugin-sdk/plugin-runtime` | 共享插件命令 / 钩子 / HTTP / 交互式辅助工具 | + | `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 网关协议错误，以及渠道 Status 补丁辅助工具 | + | `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/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/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` | 共享短时间窗口回复历史辅助工具及标记，例如 `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-dispatch-runtime` | 聚焦的回复分发 / 完成和会话标签辅助工具 | + | `plugin-sdk/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/cron-store-runtime` | cron 存储路径 / 加载 / 保存辅助工具 | + | `plugin-sdk/reply-chunking` | 聚焦的文本 / Markdown 分块辅助工具 | + | `plugin-sdk/session-store-runtime` | 会话存储路径、会话键、更新时间和存储变更辅助工具 | + | `plugin-sdk/cron-store-runtime` | Cron 存储路径 / 加载 / 保存辅助工具 | | `plugin-sdk/state-paths` | 状态 / OAuth 目录路径辅助工具 | - | `plugin-sdk/routing` | 路由 / 会话键 / 账户绑定辅助工具，例如 `resolveAgentRoute`, `buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/routing` | 路由 / 会话键 / 账户绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | | `plugin-sdk/status-helpers` | 共享渠道 / 账户 Status 摘要辅助工具、运行时状态默认值和问题元数据辅助工具 | | `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/run-command` | 带计时的命令运行器，返回规范化的 stdout / stderr 结果 | | `plugin-sdk/param-readers` | 通用工具 / CLI 参数读取器 | | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 | - | `plugin-sdk/tool-send` | 从工具参数中提取规范的发送目标字段 | + | `plugin-sdk/tool-send` | 从工具参数中提取规范化发送目标字段 | | `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 | | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 | | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助工具 | | `plugin-sdk/model-session-runtime` | 模型 / 会话覆盖辅助工具，例如 `applyModelOverrideToSessionEntry` 和 `resolveAgentMaxConcurrent` | - | `plugin-sdk/talk-config-runtime` | Talk 提供商配置解析辅助工具 | + | `plugin-sdk/talk-config-runtime` | talk 提供商配置解析辅助工具 | | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 | | `plugin-sdk/file-lock` | 可重入文件锁辅助工具 | - | `plugin-sdk/persistent-dedupe` | 基于磁盘的去重缓存辅助工具 | + | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 | | `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复分发辅助工具 | - | `plugin-sdk/acp-binding-resolve-runtime` | 无生命周期启动导入的只读 ACP 绑定解析 | - | `plugin-sdk/agent-config-primitives` | 精简的智能体运行时配置 schema 原语 | + | `plugin-sdk/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 | + | `plugin-sdk/agent-config-primitives` | 聚焦的智能体运行时配置 schema 原语 | | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 | - | `plugin-sdk/device-bootstrap` | 设备引导和配对 token 辅助工具 | + | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 | | `plugin-sdk/extension-shared` | 共享被动渠道、Status 和环境代理辅助原语 | | `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` | 面向低层 Agent harness 的实验性可信插件接口：harness 类型、活动运行 steer / abort 辅助工具、OpenClaw 工具桥接辅助工具、运行时计划工具策略辅助工具、终端结果分类、工具进度格式化 / 详情辅助工具，以及尝试结果工具函数 | - | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助工具 | + | `plugin-sdk/agent-harness` | 面向低层 Agent harness 的实验性受信插件接口：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` | 内存去重缓存辅助工具 | - | `plugin-sdk/delivery-queue-runtime` | 出站待投递排空辅助工具 | + | `plugin-sdk/dedupe-runtime` | 内存中去重缓存辅助工具 | + | `plugin-sdk/delivery-queue-runtime` | 出站待投递 drain 辅助工具 | | `plugin-sdk/file-access-runtime` | 安全本地文件和媒体源路径辅助工具 | | `plugin-sdk/heartbeat-runtime` | 心跳事件和可见性辅助工具 | | `plugin-sdk/number-runtime` | 数值强制转换辅助工具 | - | `plugin-sdk/secure-random-runtime` | 安全 token / UUID 辅助工具 | + | `plugin-sdk/secure-random-runtime` | 安全令牌 / UUID 辅助工具 | | `plugin-sdk/system-event-runtime` | 系统事件队列辅助工具 | | `plugin-sdk/transport-ready-runtime` | 传输就绪等待辅助工具 | - | `plugin-sdk/infra-runtime` | 已弃用的兼容性 shim；请使用上面更聚焦的运行时子路径 | + | `plugin-sdk/infra-runtime` | 已弃用兼容垫片；请使用上面更聚焦的运行时子路径 | | `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` | 无需 proxy / guarded-fetch 导入的 dispatcher 感知型运行时 fetch | - | `plugin-sdk/response-limit-runtime` | 无需宽泛媒体运行时接口的有界响应体读取器 | - | `plugin-sdk/session-binding-runtime` | 不包含已配置绑定路由或配对存储的当前会话绑定状态 | - | `plugin-sdk/session-store-runtime` | 不包含宽泛配置写入 / 维护导入的会话存储辅助工具 | - | `plugin-sdk/context-visibility-runtime` | 无需宽泛配置 / 安全导入的上下文可见性解析和补充上下文过滤 | - | `plugin-sdk/string-coerce-runtime` | 无需 markdown / 日志导入的精简原始类型记录 / 字符串强制转换与规范化辅助工具 | + | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | 包装后的 fetch、proxy 和固定查找辅助工具 | + | `plugin-sdk/runtime-fetch` | 不引入 proxy / guarded-fetch 导入、具备 dispatcher 感知能力的运行时 fetch | + | `plugin-sdk/response-limit-runtime` | 不依赖宽泛媒体运行时接口的有界响应体读取器 | + | `plugin-sdk/session-binding-runtime` | 当前会话绑定状态，不包含已配置绑定路由或配对存储 | + | `plugin-sdk/session-store-runtime` | 不引入宽泛配置写入 / 维护导入的会话存储辅助工具 | + | `plugin-sdk/context-visibility-runtime` | 不引入宽泛配置 / 安全导入的上下文可见性解析和补充上下文过滤 | + | `plugin-sdk/string-coerce-runtime` | 不依赖 Markdown / 日志导入的聚焦型原始记录 / 字符串强制转换与规范化辅助工具 | | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 | | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 | | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助工具 | @@ -253,20 +254,20 @@ x-i18n: | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - + | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/media-runtime` | 共享媒体获取 / 转换 / 存储辅助工具，以及媒体负载构建器 | - | `plugin-sdk/media-store` | 精简的媒体存储辅助工具，例如 `saveMediaBuffer` | - | `plugin-sdk/media-generation-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/text-runtime` | 共享文本 / Markdown / 日志辅助工具，例如去除对助手可见文本、Markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive 标签辅助工具和安全文本工具 | | `plugin-sdk/text-chunking` | 出站文本分块辅助工具 | - | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表、校验、OpenAI 兼容 TTS 构建器和语音辅助导出 | + | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表、校验、兼容 OpenAI 的 TTS 构建器和语音辅助导出 | | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive、规范化和语音辅助导出 | | `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 | - | `plugin-sdk/image-generation` | 图像生成提供商类型，以及图像资源 / data URL 辅助工具 | + | `plugin-sdk/image-generation` | 图像生成提供商类型，以及图像资源 / data URL 辅助工具和兼容 OpenAI 的图像提供商构建器 | | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助工具 | | `plugin-sdk/music-generation` | 音乐生成提供商 / 请求 / 结果类型 | | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 | @@ -275,54 +276,54 @@ x-i18n: | `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/agent-runtime-test-contracts`、`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/agent-runtime-test-contracts` | 面向原生 agent-runtime 适配器契约的测试夹具，用于认证、交付、回退、工具钩子、提示词叠加层、schema 和转录投影测试 | - | `plugin-sdk/channel-test-helpers` | 面向渠道的测试辅助工具，用于通用操作 / 设置 / Status 契约、目录断言、账户启动生命周期、发送配置线程化、运行时 mock、Status 问题、出站投递和钩子注册 | - | `plugin-sdk/channel-target-testing` | 面向渠道测试的共享目标解析错误场景测试套件 | - | `plugin-sdk/plugin-test-contracts` | 插件包、注册、公开产物、直接导入、运行时 API 和导入副作用契约辅助工具 | + | `plugin-sdk/zod` | 为插件 SDK 使用方重新导出的 `zod` | + | `plugin-sdk/testing` | 面向旧版插件测试的宽泛兼容性 barrel。新的扩展测试应改为导入聚焦的 SDK 子路径，例如 `plugin-sdk/agent-runtime-test-contracts`、`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/agent-runtime-test-contracts` | 面向原生智能体运行时适配器契约的夹具，用于 auth、投递、回退、工具钩子、提示词覆盖、schema 和转录投影测试 | + | `plugin-sdk/channel-test-helpers` | 面向渠道的测试辅助工具，用于通用操作 / 设置 / Status 契约、目录断言、账户启动生命周期、发送配置线程化、运行时 mocks、Status 问题、出站投递和钩子注册 | + | `plugin-sdk/channel-target-testing` | 面向渠道测试的共享目标解析错误场景套件 | + | `plugin-sdk/plugin-test-contracts` | 插件包、注册、公开构件、直接导入、运行时 API 和导入副作用契约辅助工具 | | `plugin-sdk/provider-test-contracts` | 提供商运行时、认证、发现、新手引导、目录、向导、媒体能力、重放策略、实时 STT 实时音频、web 搜索 / 抓取和流契约辅助工具 | - | `plugin-sdk/provider-http-test-mocks` | 供提供商测试按需启用的 Vitest HTTP / auth mock，用于覆盖会调用 `plugin-sdk/provider-http` 的场景 | - | `plugin-sdk/test-fixtures` | 通用 CLI 运行时捕获、沙箱上下文、Skill writer、智能体消息、系统事件、模块重载、内置插件路径、终端文本、分块、auth token 和类型化测试用例夹具 | + | `plugin-sdk/provider-http-test-mocks` | 为使用 `plugin-sdk/provider-http` 的提供商测试提供可选启用的 Vitest HTTP / 认证 mocks | + | `plugin-sdk/test-fixtures` | 通用 CLI 运行时捕获、沙箱上下文、Skills 写入器、智能体消息、系统事件、模块重载、内置插件路径、终端文本、分块、认证令牌和类型化用例夹具 | | `plugin-sdk/test-node-mocks` | 可在 Vitest `vi.mock("node:*")` 工厂中使用的聚焦型 Node 内置 mock 辅助工具 | - + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/memory-core` | 内置的 memory-core 辅助接口，用于 manager / config / file / CLI 辅助工具 | - | `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时门面 | - | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商和通用批处理 / 远程辅助工具 | - | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 | - | `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 | - | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 | - | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 | - | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助工具 | - | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 | - | `plugin-sdk/memory-core-host-status` | Memory host Status 辅助工具 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助工具 | - | `plugin-sdk/memory-host-core` | 面向供应商无关场景的 memory host 核心运行时辅助工具别名 | - | `plugin-sdk/memory-host-events` | 面向供应商无关场景的 memory host 事件日志辅助工具别名 | - | `plugin-sdk/memory-host-files` | 面向供应商无关场景的 memory host 文件 / 运行时辅助工具别名 | - | `plugin-sdk/memory-host-markdown` | 面向与 Memory 相邻插件的共享托管 Markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活动 Memory 运行时门面 | - | `plugin-sdk/memory-host-status` | 面向供应商无关场景的 memory host Status 辅助工具别名 | - | `plugin-sdk/memory-lancedb` | 内置的 Memory LanceDB 辅助接口 | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助接口，用于 manager / 配置 / 文件 / CLI 辅助工具 | + | `plugin-sdk/memory-core-engine-runtime` | 内存索引 / 搜索运行时 facade | + | `plugin-sdk/memory-core-host-engine-foundation` | 内存主机基础引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | 内存主机 embedding 契约、注册表访问、本地提供商和通用批处理 / 远程辅助工具 | + | `plugin-sdk/memory-core-host-engine-qmd` | 内存主机 QMD 引擎导出 | + | `plugin-sdk/memory-core-host-engine-storage` | 内存主机存储引擎导出 | + | `plugin-sdk/memory-core-host-multimodal` | 内存主机多模态辅助工具 | + | `plugin-sdk/memory-core-host-query` | 内存主机查询辅助工具 | + | `plugin-sdk/memory-core-host-secret` | 内存主机 secret 辅助工具 | + | `plugin-sdk/memory-core-host-events` | 内存主机事件日志辅助工具 | + | `plugin-sdk/memory-core-host-status` | 内存主机 Status 辅助工具 | + | `plugin-sdk/memory-core-host-runtime-cli` | 内存主机 CLI 运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-core` | 内存主机核心运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-files` | 内存主机文件 / 运行时辅助工具 | + | `plugin-sdk/memory-host-core` | 面向供应商中立的内存主机核心运行时辅助工具别名 | + | `plugin-sdk/memory-host-events` | 面向供应商中立的内存主机事件日志辅助工具别名 | + | `plugin-sdk/memory-host-files` | 面向供应商中立的内存主机文件 / 运行时辅助工具别名 | + | `plugin-sdk/memory-host-markdown` | 面向内存相关插件的共享托管 Markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 用于访问搜索管理器的活动内存运行时 facade | + | `plugin-sdk/memory-host-status` | 面向供应商中立的内存主机 Status 辅助工具别名 | + | `plugin-sdk/memory-lancedb` | 内置 Memory LanceDB 辅助接口 | - + | 家族 | 当前子路径 | 预期用途 | | --- | --- | --- | - | 浏览器 | `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。 | + | 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-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/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 子路径或插件本地 barrels。 | + | 认证 / 插件专用辅助工具 | `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` |