chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
7a0de1fbbd
commit
f50bf3d03c
@ -6,10 +6,10 @@ read_when:
|
||||
summary: 上下文引擎：可插拔的上下文组装、压缩和子智能体生命周期
|
||||
title: 上下文引擎
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T08:21:09Z"
|
||||
generated_at: "2026-04-07T08:01:12Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 19fd8cbb0e953f58fd84637fc4ceefc65984312cf2896d338318bc8cf860e6d9
|
||||
source_hash: e8290ac73272eee275bce8e481ac7959b65386752caa68044d0c6f3e450acfb1
|
||||
source_path: concepts/context-engine.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -17,111 +17,96 @@ x-i18n:
|
||||
# 上下文引擎
|
||||
|
||||
**上下文引擎**控制 OpenClaw 如何为每次运行构建模型上下文。
|
||||
它决定包含哪些消息、如何总结较早的历史，以及
|
||||
如何跨子智能体边界管理上下文。
|
||||
它决定包含哪些消息、如何总结较早的历史记录，以及如何跨子智能体边界管理上下文。
|
||||
|
||||
OpenClaw 内置了一个 `legacy` 引擎。插件可以注册
|
||||
替代引擎，用来替换当前活动的上下文引擎生命周期。
|
||||
OpenClaw 内置了一个 `legacy` 引擎。插件可以注册其他引擎，以替换当前激活的上下文引擎生命周期。
|
||||
|
||||
## 快速开始
|
||||
|
||||
检查当前活动的是哪个引擎：
|
||||
检查当前激活的是哪个引擎：
|
||||
|
||||
```bash
|
||||
openclaw doctor
|
||||
# 或直接检查配置：
|
||||
# or inspect config directly:
|
||||
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'
|
||||
```
|
||||
|
||||
### 安装上下文引擎插件
|
||||
|
||||
上下文引擎插件的安装方式与其他 OpenClaw 插件相同。先安装，
|
||||
再在槽位中选择该引擎：
|
||||
上下文引擎插件的安装方式与其他 OpenClaw 插件相同。先安装，然后在槽位中选择该引擎：
|
||||
|
||||
```bash
|
||||
# 从 npm 安装
|
||||
# Install from npm
|
||||
openclaw plugins install @martian-engineering/lossless-claw
|
||||
|
||||
# 或从本地路径安装（用于开发）
|
||||
# Or install from a local path (for development)
|
||||
openclaw plugins install -l ./my-context-engine
|
||||
```
|
||||
|
||||
然后在配置中启用该插件，并将其选为活动引擎：
|
||||
然后在配置中启用该插件，并将其选为当前激活的引擎：
|
||||
|
||||
```json5
|
||||
// openclaw.json
|
||||
{
|
||||
plugins: {
|
||||
slots: {
|
||||
contextEngine: "lossless-claw", // 必须与插件注册的引擎 id 匹配
|
||||
contextEngine: "lossless-claw", // must match the plugin's registered engine id
|
||||
},
|
||||
entries: {
|
||||
"lossless-claw": {
|
||||
enabled: true,
|
||||
// 插件特定配置放在这里（参见该插件的文档）
|
||||
// Plugin-specific config goes here (see the plugin's docs)
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
安装并配置后，重启 Gateway 网关。
|
||||
安装并配置完成后，重启 Gateway 网关。
|
||||
|
||||
要切换回内置引擎，将 `contextEngine` 设为 `"legacy"`（或者
|
||||
直接删除该键——`"legacy"` 是默认值）。
|
||||
如果要切回内置引擎，将 `contextEngine` 设置为 `"legacy"`（或完全删除该键——`"legacy"` 是默认值）。
|
||||
|
||||
## 工作原理
|
||||
|
||||
每次 OpenClaw 运行一次模型提示时，上下文引擎都会参与
|
||||
四个生命周期节点：
|
||||
每次 OpenClaw 运行模型提示时，上下文引擎都会参与四个生命周期节点：
|
||||
|
||||
1. **摄取** — 当新消息被添加到会话时调用。引擎
|
||||
可以将该消息存储或索引到它自己的数据存储中。
|
||||
2. **组装** — 在每次模型运行之前调用。引擎返回一个有序
|
||||
消息集合（以及一个可选的 `systemPromptAddition`），并确保其适配
|
||||
token 预算。
|
||||
3. **压缩** — 当上下文窗口已满，或用户运行
|
||||
`/compact` 时调用。引擎会总结较旧的历史以释放空间。
|
||||
4. **轮次后** — 在一次运行完成后调用。引擎可以持久化状态、
|
||||
触发后台压缩，或更新索引。
|
||||
1. **摄取**——当新消息被添加到会话时调用。引擎可以将该消息存储或索引到它自己的数据存储中。
|
||||
2. **组装**——在每次模型运行前调用。引擎返回一组有序消息（以及可选的 `systemPromptAddition`），这些内容会适配令牌预算。
|
||||
3. **压缩**——当上下文窗口已满，或用户运行 `/compact` 时调用。引擎会总结较早的历史记录以释放空间。
|
||||
4. **回合后**——在一次运行完成后调用。引擎可以持久化状态、触发后台压缩，或更新索引。
|
||||
|
||||
### 子智能体生命周期（可选）
|
||||
|
||||
OpenClaw 当前会调用一个子智能体生命周期 hook：
|
||||
OpenClaw 当前会调用一个子智能体生命周期钩子：
|
||||
|
||||
- **onSubagentEnded** — 当子智能体会话完成或被清理时进行清理。
|
||||
- **onSubagentEnded**——当子智能体会话完成或被清扫时执行清理。
|
||||
|
||||
`prepareSubagentSpawn` hook 是接口的一部分，供未来使用，但
|
||||
运行时尚未调用它。
|
||||
`prepareSubagentSpawn` 钩子是接口的一部分，供未来使用，但运行时目前尚未调用它。
|
||||
|
||||
### 系统提示附加内容
|
||||
|
||||
`assemble` 方法可以返回一个 `systemPromptAddition` 字符串。OpenClaw
|
||||
会将其前置到本次运行的系统提示中。这使引擎能够注入
|
||||
动态召回指引、检索说明或上下文感知提示，
|
||||
而无需依赖静态工作区文件。
|
||||
`assemble` 方法可以返回一个 `systemPromptAddition` 字符串。OpenClaw 会将它预先添加到本次运行的系统提示前面。这样，引擎就可以注入动态回忆指引、检索说明或上下文感知提示，而无需依赖静态工作区文件。
|
||||
|
||||
## 旧版引擎
|
||||
## legacy 引擎
|
||||
|
||||
内置的 `legacy` 引擎保留了 OpenClaw 的原始行为：
|
||||
|
||||
- **摄取**：无操作（会话管理器直接处理消息持久化）。
|
||||
- **组装**：直通（运行时中的现有 sanitize → validate → limit 流程
|
||||
负责上下文组装）。
|
||||
- **压缩**：委托给内置的总结式压缩，它会创建
|
||||
一条较旧消息的摘要，并保留最近消息不变。
|
||||
- **轮次后**：无操作。
|
||||
- **摄取**：空操作（消息持久化直接由会话管理器处理）。
|
||||
- **组装**：直接透传（运行时中的现有 sanitize → validate → limit 流水线负责上下文组装）。
|
||||
- **压缩**：委托给内置的总结式压缩机制，它会为较早的消息创建单个摘要，并保留最近的消息不变。
|
||||
- **回合后**：空操作。
|
||||
|
||||
旧版引擎不会注册工具，也不会提供 `systemPromptAddition`。
|
||||
legacy 引擎不会注册工具，也不会提供 `systemPromptAddition`。
|
||||
|
||||
当未设置 `plugins.slots.contextEngine`（或其值为 `"legacy"`）时，
|
||||
会自动使用该引擎。
|
||||
当未设置 `plugins.slots.contextEngine`（或将其设置为 `"legacy"`）时，会自动使用此引擎。
|
||||
|
||||
## 插件引擎
|
||||
|
||||
插件可以使用插件 API 注册一个上下文引擎：
|
||||
|
||||
```ts
|
||||
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
|
||||
|
||||
export default function register(api) {
|
||||
api.registerContextEngine("my-engine", () => ({
|
||||
info: {
|
||||
@ -131,21 +116,24 @@ export default function register(api) {
|
||||
},
|
||||
|
||||
async ingest({ sessionId, message, isHeartbeat }) {
|
||||
// 将消息存储到你的数据存储中
|
||||
// Store the message in your data store
|
||||
return { ingested: true };
|
||||
},
|
||||
|
||||
async assemble({ sessionId, messages, tokenBudget }) {
|
||||
// 返回适配预算的消息
|
||||
async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) {
|
||||
// Return messages that fit the budget
|
||||
return {
|
||||
messages: buildContext(messages, tokenBudget),
|
||||
estimatedTokens: countTokens(messages),
|
||||
systemPromptAddition: "Use lcm_grep to search history...",
|
||||
systemPromptAddition: buildMemorySystemPromptAddition({
|
||||
availableTools: availableTools ?? new Set(),
|
||||
citationsMode,
|
||||
}),
|
||||
};
|
||||
},
|
||||
|
||||
async compact({ sessionId, force }) {
|
||||
// 总结较旧上下文
|
||||
// Summarize older context
|
||||
return { ok: true, compacted: true };
|
||||
},
|
||||
}));
|
||||
@ -173,57 +161,45 @@ export default function register(api) {
|
||||
|
||||
必需成员：
|
||||
|
||||
| Member | Kind | Purpose |
|
||||
| ------------------ | -------- | ------------------------------------ |
|
||||
| `info` | Property | 引擎 id、名称、版本，以及它是否拥有压缩控制权 |
|
||||
| `ingest(params)` | Method | 存储单条消息 |
|
||||
| `assemble(params)` | Method | 为模型运行构建上下文（返回 `AssembleResult`） |
|
||||
| `compact(params)` | Method | 总结/缩减上下文 |
|
||||
| Member | Kind | Purpose |
|
||||
| ------------------ | -------- | -------------------------------------------------------- |
|
||||
| `info` | Property | 引擎 id、名称、版本，以及它是否负责压缩 |
|
||||
| `ingest(params)` | Method | 存储单条消息 |
|
||||
| `assemble(params)` | Method | 为一次模型运行构建上下文（返回 `AssembleResult`） |
|
||||
| `compact(params)` | Method | 总结/缩减上下文 |
|
||||
|
||||
`assemble` 返回一个 `AssembleResult`，其中包含：
|
||||
`assemble` 返回一个 `AssembleResult`，包含：
|
||||
|
||||
- `messages` —— 要发送给模型的有序消息。
|
||||
- `estimatedTokens`（必填，`number`）—— 引擎对
|
||||
已组装上下文总 token 数的估计。OpenClaw 会用它来进行压缩阈值
|
||||
决策和诊断报告。
|
||||
- `systemPromptAddition`（可选，`string`）—— 前置到系统提示中的附加内容。
|
||||
- `messages`——要发送给模型的有序消息。
|
||||
- `estimatedTokens`（必需，`number`）——引擎对组装后上下文总令牌数的估算。OpenClaw 会将它用于压缩阈值判断和诊断报告。
|
||||
- `systemPromptAddition`（可选，`string`）——预先添加到系统提示之前的内容。
|
||||
|
||||
可选成员：
|
||||
|
||||
| Member | Kind | Purpose |
|
||||
| ------------------------------ | ------ | ----------------------------------------------------------------------------------------------- |
|
||||
| `bootstrap(params)` | Method | 为一个会话初始化引擎状态。当引擎首次看到某个会话时调用一次（例如导入历史）。 |
|
||||
| `ingestBatch(params)` | Method | 以批处理方式摄取一个已完成轮次。一次运行完成后调用，其中包含该轮次的全部消息。 |
|
||||
| `afterTurn(params)` | Method | 运行后的生命周期工作（持久化状态、触发后台压缩）。 |
|
||||
| `prepareSubagentSpawn(params)` | Method | 为子会话设置共享状态。 |
|
||||
| `onSubagentEnded(params)` | Method | 在子智能体结束后执行清理。 |
|
||||
| `dispose()` | Method | 释放资源。在 Gateway 网关关闭或插件重载期间调用——不是按会话调用。 |
|
||||
| Member | Kind | Purpose |
|
||||
| ------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------- |
|
||||
| `bootstrap(params)` | Method | 为会话初始化引擎状态。首次看到某个会话时调用一次（例如导入历史记录）。 |
|
||||
| `ingestBatch(params)` | Method | 以批处理方式摄取一个已完成的回合。在一次运行完成后调用，并一次性提供该回合中的所有消息。 |
|
||||
| `afterTurn(params)` | Method | 运行后的生命周期工作（持久化状态、触发后台压缩）。 |
|
||||
| `prepareSubagentSpawn(params)` | Method | 为子会话设置共享状态。 |
|
||||
| `onSubagentEnded(params)` | Method | 在子智能体结束后执行清理。 |
|
||||
| `dispose()` | Method | 释放资源。在 Gateway 网关关闭或插件重载时调用——不是按会话调用。 |
|
||||
|
||||
### ownsCompaction
|
||||
|
||||
`ownsCompaction` 控制 Pi 内置的尝试内自动压缩是否在本次运行中
|
||||
保持启用：
|
||||
`ownsCompaction` 控制 Pi 内置的尝试内自动压缩是否在本次运行中保持启用：
|
||||
|
||||
- `true` —— 该引擎拥有压缩行为的控制权。OpenClaw 会禁用 Pi 内置的
|
||||
本次运行自动压缩，而引擎的 `compact()` 实现需要负责 `/compact`、溢出恢复压缩，以及它希望在 `afterTurn()` 中执行的任何主动
|
||||
压缩。
|
||||
- `false` 或未设置 —— Pi 内置的自动压缩在提示
|
||||
执行期间仍可能运行，但活动引擎的 `compact()` 方法仍会在
|
||||
`/compact` 和溢出恢复时被调用。
|
||||
- `true`——该引擎负责压缩行为。OpenClaw 会为该次运行禁用 Pi 的内置自动压缩，而引擎的 `compact()` 实现需要负责 `/compact`、溢出恢复压缩，以及它希望在 `afterTurn()` 中执行的任何主动压缩。
|
||||
- `false` 或未设置——Pi 的内置自动压缩在提示执行期间仍可能运行，但当前激活引擎的 `compact()` 方法仍会用于 `/compact` 和溢出恢复。
|
||||
|
||||
`ownsCompaction: false` **并不**意味着 OpenClaw 会自动回退到
|
||||
旧版引擎的压缩路径。
|
||||
`ownsCompaction: false` **不**意味着 OpenClaw 会自动回退到 legacy 引擎的压缩路径。
|
||||
|
||||
这意味着插件有两种有效模式：
|
||||
|
||||
- **接管模式** —— 实现你自己的压缩算法，并设置
|
||||
`ownsCompaction: true`。
|
||||
- **委托模式** —— 设置 `ownsCompaction: false`，并让 `compact()` 调用
|
||||
`openclaw/plugin-sdk/core` 中的 `delegateCompactionToRuntime(...)`，以使用
|
||||
OpenClaw 内置的压缩行为。
|
||||
- **自主管理模式**——实现你自己的压缩算法，并设置 `ownsCompaction: true`。
|
||||
- **委托模式**——设置 `ownsCompaction: false`，并让 `compact()` 调用 `openclaw/plugin-sdk/core` 中的 `delegateCompactionToRuntime(...)`，以使用 OpenClaw 的内置压缩行为。
|
||||
|
||||
对于一个活动的非接管型引擎来说，无操作的 `compact()` 是不安全的，因为它
|
||||
会为该引擎槽位禁用正常的 `/compact` 和溢出恢复压缩路径。
|
||||
对于一个处于激活状态、但不自主管理压缩的引擎来说，空操作 `compact()` 是不安全的，因为它会禁用该引擎槽位的正常 `/compact` 和溢出恢复压缩路径。
|
||||
|
||||
## 配置参考
|
||||
|
||||
@ -231,49 +207,33 @@ export default function register(api) {
|
||||
{
|
||||
plugins: {
|
||||
slots: {
|
||||
// 选择当前活动的上下文引擎。默认值："legacy"。
|
||||
// 设为某个插件 id 以使用插件引擎。
|
||||
// Select the active context engine. Default: "legacy".
|
||||
// Set to a plugin id to use a plugin engine.
|
||||
contextEngine: "legacy",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
该槽位在运行时是互斥的——对于给定的一次运行或压缩操作，
|
||||
只会解析一个已注册的上下文引擎。其他已启用的
|
||||
`kind: "context-engine"` 插件仍然可以加载并运行它们的注册
|
||||
代码；`plugins.slots.contextEngine` 只决定当 OpenClaw
|
||||
需要上下文引擎时，会解析哪个已注册的引擎 id。
|
||||
该槽位在运行时是互斥的——对于给定的一次运行或压缩操作，只会解析一个已注册的上下文引擎。其他已启用的 `kind: "context-engine"` 插件仍然可以加载并运行其注册代码；`plugins.slots.contextEngine` 只决定当 OpenClaw 需要上下文引擎时，解析哪个已注册的引擎 id。
|
||||
|
||||
## 与压缩和记忆的关系
|
||||
|
||||
- **压缩**是上下文引擎的一项职责。旧版引擎
|
||||
委托给 OpenClaw 内置的总结功能。插件引擎可以实现
|
||||
任意压缩策略（DAG 摘要、向量检索等）。
|
||||
- **记忆插件**（`plugins.slots.memory`）与上下文引擎是分开的。
|
||||
记忆插件提供搜索/检索；上下文引擎控制
|
||||
模型能看到什么。它们可以协同工作——上下文引擎可能会在组装期间使用记忆
|
||||
插件的数据。
|
||||
- **会话修剪**（在内存中裁剪旧工具结果）仍会运行，
|
||||
无论当前活动的是哪个上下文引擎。
|
||||
- **压缩**是上下文引擎的一项职责。legacy 引擎会委托给 OpenClaw 的内置总结机制。插件引擎可以实现任何压缩策略（DAG 摘要、向量检索等）。
|
||||
- **记忆插件**（`plugins.slots.memory`）与上下文引擎是分开的。记忆插件提供搜索/检索；上下文引擎控制模型能看到什么。它们可以协同工作——上下文引擎可能会在组装期间使用记忆插件数据。想使用当前激活记忆提示路径的插件引擎，应优先使用 `openclaw/plugin-sdk/core` 中的 `buildMemorySystemPromptAddition(...)`，它会将当前激活的记忆提示片段转换为可直接预加的 `systemPromptAddition`。如果引擎需要更底层的控制，它仍然可以通过 `openclaw/plugin-sdk/memory-host-core` 中的 `buildActiveMemoryPromptSection(...)` 拉取原始行。
|
||||
- **会话修剪**（在内存中裁剪旧的工具结果）仍会运行，无论当前激活的是哪个上下文引擎。
|
||||
|
||||
## 提示
|
||||
|
||||
- 使用 `openclaw doctor` 验证你的引擎是否正确加载。
|
||||
- 如果正在切换引擎，现有会话会继续保留其当前历史。
|
||||
新引擎会接管后续运行。
|
||||
- 引擎错误会被记录并显示在诊断信息中。如果某个插件引擎
|
||||
注册失败，或无法解析所选引擎 id，OpenClaw
|
||||
不会自动回退；在你修复插件或将
|
||||
`plugins.slots.contextEngine` 切回 `"legacy"` 之前，运行都会失败。
|
||||
- 在开发时，使用 `openclaw plugins install -l ./my-engine` 将本地
|
||||
插件目录以链接方式接入，而无需复制。
|
||||
- 如果你正在切换引擎，现有会话会继续保留其当前历史记录。新引擎会接管未来的运行。
|
||||
- 引擎错误会被记录并显示在诊断信息中。如果插件引擎注册失败，或无法解析所选的引擎 id，OpenClaw 不会自动回退；在你修复插件或将 `plugins.slots.contextEngine` 切回 `"legacy"` 之前，运行将会失败。
|
||||
- 在开发时，使用 `openclaw plugins install -l ./my-engine` 可以链接本地插件目录，而无需复制。
|
||||
|
||||
另请参阅：[压缩](/concepts/compaction)、[上下文](/concepts/context)、
|
||||
[插件](/tools/plugin)、[插件清单](/plugins/manifest)。
|
||||
另请参阅：[压缩](/zh-CN/concepts/compaction)、[上下文](/zh-CN/concepts/context)、[插件](/zh-CN/tools/plugin)、[插件清单](/zh-CN/plugins/manifest)。
|
||||
|
||||
## 相关
|
||||
|
||||
- [上下文](/concepts/context) — 如何为智能体轮次构建上下文
|
||||
- [插件架构](/plugins/architecture) — 注册上下文引擎插件
|
||||
- [压缩](/concepts/compaction) — 总结长对话
|
||||
- [上下文](/zh-CN/concepts/context)——如何为智能体回合构建上下文
|
||||
- [插件架构](/zh-CN/plugins/architecture)——注册上下文引擎插件
|
||||
- [压缩](/zh-CN/concepts/compaction)——总结长对话
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,16 +1,16 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要知道应从哪个 SDK 子路径导入
|
||||
- 你需要知道应该从哪个 SDK 子路径导入
|
||||
- 你想查看 OpenClawPluginApi 上所有注册方法的参考
|
||||
- 你正在查找某个特定的 SDK 导出
|
||||
sidebarTitle: SDK Overview
|
||||
summary: 导入映射、注册 API 参考和 SDK 架构
|
||||
title: 插件 SDK 概览
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T07:38:26Z"
|
||||
generated_at: "2026-04-07T08:02:18Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 9f05178454058038cd69a58bc8392e2574a48a61fbaef9b7db9eba2ffa9f1374
|
||||
source_hash: 6ba11d1708a117f3872a09fd0bebb0481d36b89b473aec861192e8c2745ef727
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -35,19 +35,19 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
每个子路径都是一个小型、独立的模块。这样可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口/构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 用于更广泛的总括性表面和共享辅助函数，例如 `buildChannelConfigSchema`。
|
||||
每个子路径都是一个小型、独立的模块。这样可以保持快速启动，并防止循环依赖问题。对于特定于渠道的入口/构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广义的总入口层和共享辅助函数，例如 `buildChannelConfigSchema`。
|
||||
|
||||
不要添加或依赖带有提供商名称的便捷接口，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带有渠道品牌的辅助接口。内置插件应在它们自己的 `api.ts` 或 `runtime-api.ts` barrel 文件中组合通用 SDK 子路径，而核心则应使用这些插件本地 barrel，或者在需求确实跨渠道时添加一个狭义的通用 SDK 契约。
|
||||
不要添加或依赖带有提供商名称的便捷层，例如 `openclaw/plugin-sdk/slack`、`openclaw/plugin-sdk/discord`、`openclaw/plugin-sdk/signal`、`openclaw/plugin-sdk/whatsapp`，或带有渠道品牌的辅助层。内置插件应在自己的 `api.ts` 或 `runtime-api.ts` barrel 中组合通用 SDK 子路径，而核心则应使用这些插件本地的 barrel，或在需求确实跨渠道时添加一个狭义的通用 SDK 契约。
|
||||
|
||||
生成的导出映射仍包含一小组内置插件辅助接口，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅用于内置插件维护和兼容性；它们有意未包含在下方的常用表格中，也不是新第三方插件推荐的导入路径。
|
||||
生成的导出映射仍然包含一小部分内置插件辅助层，例如 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些子路径仅用于内置插件维护和兼容性；它们在下方的常用表格中被有意省略，也不是新第三方插件推荐使用的导入路径。
|
||||
|
||||
## 子路径参考
|
||||
|
||||
最常用的子路径，按用途分组。完整的 200 多个子路径生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。
|
||||
最常用的子路径，按用途分组。生成的完整列表包含 200+ 个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`。
|
||||
|
||||
保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其作为公共接口推广，否则应将它们视为实现细节/兼容性表面。
|
||||
保留的内置插件辅助子路径仍会出现在该生成列表中。除非某个文档页面明确将其作为公开接口推广，否则应将它们视为实现细节/兼容性层。
|
||||
|
||||
### 插件入口点
|
||||
### 插件入口
|
||||
|
||||
| 子路径 | 关键导出 |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
@ -62,20 +62,20 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
| --- | --- |
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、`createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` |
|
||||
| `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-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/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | 多账户 config/action-gate 辅助函数、默认账户回退辅助函数 |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助函数 |
|
||||
| `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 |
|
||||
| `plugin-sdk/account-helpers` | 狭义的账户列表/账户操作辅助函数 |
|
||||
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助函数，并带有内置契约回退 |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/验证辅助函数，带内置契约回退 |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助函数 |
|
||||
@ -85,24 +85,24 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
| `plugin-sdk/outbound-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` | 交互式回复负载规范化/缩减辅助函数 |
|
||||
| `plugin-sdk/channel-inbound` | 入站去抖、提及匹配、提及策略辅助函数以及 envelope 辅助函数 |
|
||||
| `plugin-sdk/interactive-runtime` | 交互式回复负载规范化/归约辅助函数 |
|
||||
| `plugin-sdk/channel-inbound` | 入站去抖动、提及匹配、提及策略辅助函数，以及 envelope 辅助函数 |
|
||||
| `plugin-sdk/channel-send-result` | 回复结果类型 |
|
||||
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`、`createMessageToolCardSchema` |
|
||||
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
|
||||
| `plugin-sdk/channel-targets` | 目标解析/匹配辅助函数 |
|
||||
| `plugin-sdk/channel-contract` | 渠道契约类型 |
|
||||
| `plugin-sdk/channel-feedback` | 反馈/反应接线 |
|
||||
| `plugin-sdk/channel-secret-runtime` | 狭义 secret 契约辅助函数，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment`，以及 secret target 类型 |
|
||||
| `plugin-sdk/channel-secret-runtime` | 狭义 secret 契约辅助函数，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` 以及 secret 目标类型 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="提供商子路径">
|
||||
@ -112,22 +112,22 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
| `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助函数 |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | 聚焦 OpenAI 兼容自托管提供商的设置辅助函数 |
|
||||
| `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 |
|
||||
| `plugin-sdk/provider-auth-runtime` | 为提供商插件提供的运行时 API 密钥解析辅助函数 |
|
||||
| `plugin-sdk/provider-auth-runtime` | 提供商插件的运行时 API 密钥解析辅助函数 |
|
||||
| `plugin-sdk/provider-auth-api-key` | API 密钥新手引导/配置文件写入辅助函数，例如 `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 |
|
||||
| `plugin-sdk/provider-auth-login` | 为提供商插件提供的共享交互式登录辅助函数 |
|
||||
| `plugin-sdk/provider-auth-result` | 标准 OAuth auth-result 构建器 |
|
||||
| `plugin-sdk/provider-auth-login` | 提供商插件共享的交互式登录辅助函数 |
|
||||
| `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助函数 |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`、`ensureApiKeyFromOptionEnvOrPrompt`、`upsertAuthProfile`、`upsertApiKeyProfile`、`writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助函数，以及模型 ID 规范化辅助函数，例如 `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助函数 |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助函数 |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | 狭义 web-fetch 配置/选择契约辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册/缓存辅助函数 |
|
||||
| `plugin-sdk/provider-web-search-contract` | 狭义 web-search 配置/凭证契约辅助函数，例如 `enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 和作用域凭证 setter/getter |
|
||||
| `plugin-sdk/provider-web-search-contract` | 狭义 web-search 配置/凭证契约辅助函数，例如 `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及作用域凭证 setter/getter |
|
||||
| `plugin-sdk/provider-web-search` | web-search 提供商注册/缓存/运行时辅助函数 |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 等 |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助函数 |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助函数 |
|
||||
| `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 |
|
||||
| `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助函数 |
|
||||
</Accordion>
|
||||
@ -136,18 +136,18 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 |
|
||||
| `plugin-sdk/approval-auth-runtime` | 审批者解析和同聊天操作认证辅助函数 |
|
||||
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤辅助函数 |
|
||||
| `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 |
|
||||
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天 action-auth 辅助函数 |
|
||||
| `plugin-sdk/approval-client-runtime` | 原生执行审批配置文件/过滤器辅助函数 |
|
||||
| `plugin-sdk/approval-delivery-runtime` | 原生审批能力/传递适配器 |
|
||||
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助函数 |
|
||||
| `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助函数 |
|
||||
| `plugin-sdk/approval-reply-runtime` | exec/plugin 审批回复负载辅助函数 |
|
||||
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助函数 |
|
||||
| `plugin-sdk/command-detection` | 共享命令检测辅助函数 |
|
||||
| `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助函数 |
|
||||
| `plugin-sdk/command-surface` | 命令体规范化和命令 surface 辅助函数 |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/channel-secret-runtime` | 用于渠道/插件 secret 表面的狭义 secret 契约收集辅助函数 |
|
||||
| `plugin-sdk/channel-secret-runtime` | 面向渠道/插件 secret surface 的狭义 secret 契约收集辅助函数 |
|
||||
| `plugin-sdk/secret-ref-runtime` | 狭义 `coerceSecretRef` 和用于 secret 契约/配置解析的 SecretRef 类型辅助函数 |
|
||||
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和 secret 收集辅助函数 |
|
||||
| `plugin-sdk/security-runtime` | 共享信任、私信 gating、外部内容和 secret 收集辅助函数 |
|
||||
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 |
|
||||
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助函数 |
|
||||
| `plugin-sdk/secret-input` | secret 输入解析辅助函数 |
|
||||
@ -158,57 +158,57 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
<Accordion title="运行时与存储子路径">
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助函数 |
|
||||
| `plugin-sdk/runtime` | 广义运行时/日志/备份/插件安装辅助函数 |
|
||||
| `plugin-sdk/runtime-env` | 狭义运行时环境、logger、超时、重试和退避辅助函数 |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | 共享插件命令/hook/http/交互辅助函数 |
|
||||
| `plugin-sdk/hook-runtime` | 共享 webhook/内部 hook 管道辅助函数 |
|
||||
| `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | 进程 exec 辅助函数 |
|
||||
| `plugin-sdk/hook-runtime` | 共享 webhook/internal hook pipeline 辅助函数 |
|
||||
| `plugin-sdk/lazy-runtime` | 惰性运行时导入/绑定辅助函数，例如 `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | 进程执行辅助函数 |
|
||||
| `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助函数 |
|
||||
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助函数 |
|
||||
| `plugin-sdk/config-runtime` | 配置加载/写入辅助函数 |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约表面不可用时也可使用 |
|
||||
| `plugin-sdk/approval-runtime` | exec/插件审批辅助函数、审批能力构建器、认证/配置文件辅助函数、原生路由/运行时辅助函数 |
|
||||
| `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助函数、分块、分发、heartbeat、回复规划器 |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | 狭义回复分发/完成辅助函数 |
|
||||
| `plugin-sdk/reply-history` | 共享短窗口回复历史辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化和重复/冲突检查，即使内置 Telegram 契约 surface 不可用时也适用 |
|
||||
| `plugin-sdk/approval-runtime` | exec/plugin 审批辅助函数、审批能力构建器、认证/配置文件辅助函数、原生路由/运行时辅助函数 |
|
||||
| `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助函数、分块、分发、心跳、回复规划器 |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | 狭义回复分发/最终化辅助函数 |
|
||||
| `plugin-sdk/reply-history` | 共享短窗口回复历史辅助函数，例如 `buildHistoryContext`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | 狭义文本/Markdown 分块辅助函数 |
|
||||
| `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助函数 |
|
||||
| `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助函数 |
|
||||
| `plugin-sdk/routing` | 路由/会话键/账户绑定辅助函数，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/routing` | 路由/会话键/账户绑定辅助函数，例如 `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | 共享渠道/账户状态摘要辅助函数、运行时状态默认值和问题元数据辅助函数 |
|
||||
| `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助函数 |
|
||||
| `plugin-sdk/string-normalization-runtime` | slug/字符串规范化辅助函数 |
|
||||
| `plugin-sdk/request-url` | 从 fetch/request 类输入中提取字符串 URL |
|
||||
| `plugin-sdk/run-command` | 带计时功能的命令运行器，输出规范化的 stdout/stderr 结果 |
|
||||
| `plugin-sdk/request-url` | 从 fetch/request-like 输入中提取字符串 URL |
|
||||
| `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化 stdout/stderr 结果 |
|
||||
| `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 |
|
||||
| `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/json-store` | 小型 JSON 状态读写辅助函数 |
|
||||
| `plugin-sdk/file-lock` | 可重入文件锁辅助函数 |
|
||||
| `plugin-sdk/persistent-dedupe` | 基于磁盘的去重缓存辅助函数 |
|
||||
| `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助函数 |
|
||||
| `plugin-sdk/agent-config-primitives` | 狭义智能体运行时配置 schema 基元 |
|
||||
| `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 |
|
||||
| `plugin-sdk/acp-runtime` | ACP 运行时/会话和 reply-dispatch 辅助函数 |
|
||||
| `plugin-sdk/agent-config-primitives` | 狭义智能体运行时配置 schema 原语 |
|
||||
| `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
|
||||
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 |
|
||||
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 |
|
||||
| `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助基元 |
|
||||
| `plugin-sdk/extension-shared` | 共享被动渠道、状态和 ambient proxy 辅助原语 |
|
||||
| `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/provider-zai-endpoint` | Z.AI 端点检测辅助函数 |
|
||||
| `plugin-sdk/infra-runtime` | 系统事件/heartbeat 辅助函数 |
|
||||
| `plugin-sdk/infra-runtime` | 系统事件/心跳辅助函数 |
|
||||
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 |
|
||||
| `plugin-sdk/diagnostic-runtime` | 诊断标记和事件辅助函数 |
|
||||
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和 pinned lookup 辅助函数 |
|
||||
| `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和 pinned lookup 辅助函数 |
|
||||
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 |
|
||||
| `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助函数 |
|
||||
| `plugin-sdk/agent-runtime` | 智能体目录/身份/workspace 辅助函数 |
|
||||
| `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助函数 |
|
||||
| `plugin-sdk/directory-runtime` | 基于配置的目录查询/去重 |
|
||||
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
|
||||
</Accordion>
|
||||
@ -216,12 +216,12 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
<Accordion title="能力与测试子路径">
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助函数以及媒体负载构建器 |
|
||||
| `plugin-sdk/media-generation-runtime` | 共享媒体生成故障切换辅助函数、候选选择和缺失模型消息 |
|
||||
| `plugin-sdk/media-understanding` | 媒体理解提供商类型以及面向提供商的图片/音频辅助函数导出 |
|
||||
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助函数，例如剥离对助手可见的文本、Markdown 渲染/分块/表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 |
|
||||
| `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助函数，以及媒体负载构建器 |
|
||||
| `plugin-sdk/media-generation-runtime` | 共享媒体生成故障切换辅助函数、候选项选择和缺失模型消息 |
|
||||
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助函数导出 |
|
||||
| `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助函数，例如仅对助手可见文本剥离、Markdown 渲染/分块/表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 |
|
||||
| `plugin-sdk/text-chunking` | 出站文本分块辅助函数 |
|
||||
| `plugin-sdk/speech` | 语音提供商类型以及面向提供商的 directive、注册表和校验辅助函数 |
|
||||
| `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和验证辅助函数 |
|
||||
| `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助函数 |
|
||||
| `plugin-sdk/realtime-transcription` | 实时转写提供商类型和注册表辅助函数 |
|
||||
| `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 |
|
||||
@ -231,20 +231,20 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
| `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障切换辅助函数、提供商查找和 model-ref 解析 |
|
||||
| `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 |
|
||||
| `plugin-sdk/video-generation-core` | 共享视频生成类型、故障切换辅助函数、提供商查找和 model-ref 解析 |
|
||||
| `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助函数 |
|
||||
| `plugin-sdk/webhook-targets` | webhook 目标注册表和 route-install 辅助函数 |
|
||||
| `plugin-sdk/webhook-path` | webhook 路径规范化辅助函数 |
|
||||
| `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助函数 |
|
||||
| `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` |
|
||||
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` |
|
||||
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Memory 子路径">
|
||||
<Accordion title="记忆子路径">
|
||||
| 子路径 | 关键导出 |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | 内置 memory-core 辅助表面，用于 manager/config/file/CLI 辅助函数 |
|
||||
| `plugin-sdk/memory-core` | 内置 memory-core 辅助 surface，用于 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 主机 embedding 引擎导出 |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory 主机嵌入引擎导出 |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Memory 主机 QMD 引擎导出 |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Memory 主机存储引擎导出 |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Memory 主机多模态辅助函数 |
|
||||
@ -255,78 +255,78 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
| `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 辅助 surface |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="保留的内置辅助子路径">
|
||||
| 系列 | 当前子路径 | 预期用途 |
|
||||
| 类别 | 当前子路径 | 预期用途 |
|
||||
| --- | --- | --- |
|
||||
| Browser | `plugin-sdk/browser-cdp`、`plugin-sdk/browser-config-runtime`、`plugin-sdk/browser-config-support`、`plugin-sdk/browser-control-auth`、`plugin-sdk/browser-node-runtime`、`plugin-sdk/browser-profiles`、`plugin-sdk/browser-security-runtime`、`plugin-sdk/browser-setup-tools`、`plugin-sdk/browser-support` | 内置 Browser 插件支持辅助函数（`browser-support` 仍是兼容性 barrel） |
|
||||
| Matrix | `plugin-sdk/matrix`、`plugin-sdk/matrix-helper`、`plugin-sdk/matrix-runtime-heavy`、`plugin-sdk/matrix-runtime-shared`、`plugin-sdk/matrix-runtime-surface`、`plugin-sdk/matrix-surface`、`plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时表面 |
|
||||
| Line | `plugin-sdk/line`、`plugin-sdk/line-core`、`plugin-sdk/line-runtime`、`plugin-sdk/line-surface` | 内置 LINE 辅助/运行时表面 |
|
||||
| IRC | `plugin-sdk/irc`、`plugin-sdk/irc-surface` | 内置 IRC 辅助表面 |
|
||||
| 特定于渠道的辅助函数 | `plugin-sdk/googlechat`、`plugin-sdk/zalouser`、`plugin-sdk/bluebubbles`、`plugin-sdk/bluebubbles-policy`、`plugin-sdk/mattermost`、`plugin-sdk/mattermost-policy`、`plugin-sdk/feishu-conversation`、`plugin-sdk/msteams`、`plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、`plugin-sdk/twitch` | 内置渠道兼容性/辅助接口 |
|
||||
| 认证/插件特定辅助函数 | `plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、`plugin-sdk/diagnostics-otel`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/thread-ownership`、`plugin-sdk/voice-call` | 内置功能/插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 Browser 插件支持辅助函数（`browser-support` 仍为兼容性 barrel） |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时 surface |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时 surface |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助 surface |
|
||||
| 特定渠道辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性/辅助层 |
|
||||
| 认证/插件特定辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助层；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, 和 `resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 注册 API
|
||||
|
||||
`register(api)` 回调会接收一个带有这些方法的 `OpenClawPluginApi` 对象：
|
||||
`register(api)` 回调接收一个 `OpenClawPluginApi` 对象，包含以下方法：
|
||||
|
||||
### 能力注册
|
||||
|
||||
| 方法 | 它注册的内容 |
|
||||
| 方法 | 注册内容 |
|
||||
| ------------------------------------------------ | -------------------------------- |
|
||||
| `api.registerProvider(...)` | 文本推理（LLM） |
|
||||
| `api.registerCliBackend(...)` | 本地 CLI 推理后端 |
|
||||
| `api.registerChannel(...)` | 消息渠道 |
|
||||
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
|
||||
| `api.registerProvider(...)` | 文本推理（LLM） |
|
||||
| `api.registerCliBackend(...)` | 本地 CLI 推理后端 |
|
||||
| `api.registerChannel(...)` | 消息渠道 |
|
||||
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转写 |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 |
|
||||
| `api.registerImageGenerationProvider(...)` | 图像生成 |
|
||||
| `api.registerMusicGenerationProvider(...)` | 音乐生成 |
|
||||
| `api.registerVideoGenerationProvider(...)` | 视频生成 |
|
||||
| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 |
|
||||
| `api.registerWebSearchProvider(...)` | Web 搜索 |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 |
|
||||
| `api.registerImageGenerationProvider(...)` | 图像生成 |
|
||||
| `api.registerMusicGenerationProvider(...)` | 音乐生成 |
|
||||
| `api.registerVideoGenerationProvider(...)` | 视频生成 |
|
||||
| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 |
|
||||
| `api.registerWebSearchProvider(...)` | Web 搜索 |
|
||||
|
||||
### 工具和命令
|
||||
### 工具与命令
|
||||
|
||||
| 方法 | 它注册的内容 |
|
||||
| 方法 | 注册内容 |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） |
|
||||
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
|
||||
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
|
||||
|
||||
### 基础设施
|
||||
|
||||
| 方法 | 它注册的内容 |
|
||||
| 方法 | 注册内容 |
|
||||
| ---------------------------------------------- | --------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | 事件 hook |
|
||||
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 |
|
||||
| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 |
|
||||
| `api.registerCli(registrar, opts?)` | CLI 子命令 |
|
||||
| `api.registerService(service)` | 后台服务 |
|
||||
| `api.registerInteractiveHandler(registration)` | 交互式处理器 |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | 附加式 memory 相邻提示词部分 |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | 附加式 memory 搜索/读取语料 |
|
||||
| `api.registerHook(events, handler, opts?)` | 事件 hook |
|
||||
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 |
|
||||
| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 |
|
||||
| `api.registerCli(registrar, opts?)` | CLI 子命令 |
|
||||
| `api.registerService(service)` | 后台服务 |
|
||||
| `api.registerInteractiveHandler(registration)` | 交互式处理器 |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | 增量式 Memory 相邻提示词区段 |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | 增量式 Memory 搜索/读取语料 |
|
||||
|
||||
保留的核心管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使某个插件尝试为其分配更窄的 Gateway 网关方法作用域也是如此。对于插件自有方法，优先使用插件特定前缀。
|
||||
保留的核心管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件拥有的方法，优先使用插件特定前缀。
|
||||
|
||||
### CLI 注册元数据
|
||||
|
||||
`api.registerCli(registrar, opts?)` 接受两类顶层元数据：
|
||||
|
||||
- `commands`：由 registrar 拥有的显式命令根
|
||||
- `commands`：由注册器拥有的显式命令根
|
||||
- `descriptors`：用于根 CLI 帮助、路由和惰性插件 CLI 注册的解析时命令描述符
|
||||
|
||||
如果你希望插件命令在普通根 CLI 路径中保持惰性加载，请提供 `descriptors`，覆盖该 registrar 暴露的每个顶层命令根。
|
||||
如果你希望某个插件命令在常规根 CLI 路径中保持惰性加载，请提供 `descriptors`，覆盖该注册器暴露的每一个顶层命令根。
|
||||
|
||||
```typescript
|
||||
api.registerCli(
|
||||
@ -346,69 +346,72 @@ api.registerCli(
|
||||
);
|
||||
```
|
||||
|
||||
仅在你不需要惰性根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍受支持，但不会为解析时惰性加载安装基于 descriptor 的占位符。
|
||||
只有在你不需要惰性根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍然受支持，但它不会安装基于描述符的占位符来实现解析时惰性加载。
|
||||
|
||||
### CLI 后端注册
|
||||
|
||||
`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。
|
||||
`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端的默认配置，例如 `codex-cli`。
|
||||
|
||||
- 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。
|
||||
- 后端 `config` 使用与 `agents.defaults.cliBackends.<id>` 相同的结构。
|
||||
- 用户配置仍然优先。OpenClaw 会在运行 CLI 前，将 `agents.defaults.cliBackends.<id>` 合并到插件默认值之上。
|
||||
- 当某个后端在合并后需要兼容性重写时，请使用 `normalizeConfig`（例如规范化旧版 flag 结构）。
|
||||
- 用户配置仍然优先生效。OpenClaw 会在运行 CLI 前，将 `agents.defaults.cliBackends.<id>` 合并到插件默认值之上。
|
||||
- 当后端在合并后需要兼容性重写时，使用 `normalizeConfig`（例如规范化旧版标志结构）。
|
||||
|
||||
### 独占槽位
|
||||
|
||||
| 方法 | 它注册的内容 |
|
||||
| 方法 | 注册内容 |
|
||||
| ------------------------------------------ | ------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | 上下文引擎（一次仅一个活动） |
|
||||
| `api.registerMemoryPromptSection(builder)` | Memory 提示词部分构建器 |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Memory 刷新计划解析器 |
|
||||
| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 |
|
||||
| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只激活一个） |
|
||||
| `api.registerMemoryCapability(capability)` | 统一 Memory 能力 |
|
||||
| `api.registerMemoryPromptSection(builder)` | Memory 提示词区段构建器 |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Memory 刷新计划解析器 |
|
||||
| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 |
|
||||
|
||||
### Memory embedding 适配器
|
||||
### Memory 嵌入适配器
|
||||
|
||||
| 方法 | 它注册的内容 |
|
||||
| 方法 | 注册内容 |
|
||||
| ---------------------------------------------- | ---------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory embedding 适配器 |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的 Memory 嵌入适配器 |
|
||||
|
||||
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是 Memory 插件独占的。
|
||||
- `registerMemoryEmbeddingProvider` 允许活动 Memory 插件注册一个或多个 embedding 适配器 ID（例如 `openai`、`gemini` 或自定义插件定义的 ID）。
|
||||
- 用户配置（例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会根据这些已注册的适配器 ID 进行解析。
|
||||
- `registerMemoryCapability` 是首选的独占 Memory 插件 API。
|
||||
- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`，这样配套插件就可以通过 `openclaw/plugin-sdk/memory-host-core` 消费导出的 Memory 制品，而不必深入某个特定 Memory 插件的私有布局。
|
||||
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占 Memory 插件 API。
|
||||
- `registerMemoryEmbeddingProvider` 允许活动 Memory 插件注册一个或多个嵌入适配器 id（例如 `openai`、`gemini` 或自定义的插件定义 id）。
|
||||
- 用户配置，例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`，会基于这些已注册的适配器 id 进行解析。
|
||||
|
||||
### 事件和生命周期
|
||||
### 事件与生命周期
|
||||
|
||||
| 方法 | 它的作用 |
|
||||
| 方法 | 作用 |
|
||||
| -------------------------------------------- | ----------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook |
|
||||
| `api.onConversationBindingResolved(handler)` | 会话绑定回调 |
|
||||
| `api.on(hookName, handler, opts?)` | 类型化生命周期 hook |
|
||||
| `api.onConversationBindingResolved(handler)` | 对话绑定回调 |
|
||||
|
||||
### Hook 决策语义
|
||||
|
||||
- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦有任意处理器设置它，就会跳过更低优先级的处理器。
|
||||
- `before_tool_call`：返回 `{ block: false }` 会被视为没有决策（等同于省略 `block`），而不是覆盖。
|
||||
- `before_install`：返回 `{ block: true }` 是终止性的。一旦有任意处理器设置它，就会跳过更低优先级的处理器。
|
||||
- `before_install`：返回 `{ block: false }` 会被视为没有决策（等同于省略 `block`），而不是覆盖。
|
||||
- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦有任意处理器声明已分发，就会跳过更低优先级的处理器以及默认模型分发路径。
|
||||
- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦有任意处理器设置它，就会跳过更低优先级的处理器。
|
||||
- `message_sending`：返回 `{ cancel: false }` 会被视为没有决策（等同于省略 `cancel`），而不是覆盖。
|
||||
- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。
|
||||
- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。
|
||||
- `before_install`：返回 `{ block: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。
|
||||
- `before_install`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。
|
||||
- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任意处理器声明已分发，就会跳过更低优先级的处理器以及默认模型分发路径。
|
||||
- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任意处理器设置它，就会跳过更低优先级的处理器。
|
||||
- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（与省略 `cancel` 相同），而不是覆盖。
|
||||
|
||||
### API 对象字段
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
| 字段 | 类型 | 说明 |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | 插件 ID |
|
||||
| `api.name` | `string` | 显示名称 |
|
||||
| `api.version` | `string?` | 插件版本（可选） |
|
||||
| `api.description` | `string?` | 插件描述（可选） |
|
||||
| `api.source` | `string` | 插件源路径 |
|
||||
| `api.rootDir` | `string?` | 插件根目录（可选） |
|
||||
| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动内存运行时快照） |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件专用配置 |
|
||||
| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | 作用域 logger（`debug`、`info`、`warn`、`error`） |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是轻量级的完整入口点前启动/设置窗口 |
|
||||
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
|
||||
| `api.id` | `string` | 插件 id |
|
||||
| `api.name` | `string` | 显示名称 |
|
||||
| `api.version` | `string?` | 插件版本（可选） |
|
||||
| `api.description` | `string?` | 插件描述（可选） |
|
||||
| `api.source` | `string` | 插件源路径 |
|
||||
| `api.rootDir` | `string?` | 插件根目录（可选） |
|
||||
| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动内存运行时快照） |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件特定配置 |
|
||||
| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | 作用域 logger（`debug`、`info`、`warn`、`error`） |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口之前的轻量级启动/设置窗口 |
|
||||
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
|
||||
|
||||
## 内部模块约定
|
||||
|
||||
@ -419,24 +422,31 @@ my-plugin/
|
||||
api.ts # 面向外部使用者的公共导出
|
||||
runtime-api.ts # 仅供内部使用的运行时导出
|
||||
index.ts # 插件入口点
|
||||
setup-entry.ts # 轻量级仅设置入口点（可选）
|
||||
setup-entry.ts # 仅设置用的轻量入口（可选）
|
||||
```
|
||||
|
||||
<Warning>
|
||||
不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>` 导入你自己的插件。请通过 `./api.ts` 或 `./runtime-api.ts` 路由内部导入。SDK 路径仅是对外契约。
|
||||
不要在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>`
|
||||
导入你自己的插件。请通过 `./api.ts` 或
|
||||
`./runtime-api.ts` 进行内部导入。SDK 路径只是外部契约。
|
||||
</Warning>
|
||||
|
||||
门面加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）现在在 OpenClaw 已运行时优先使用活动运行时配置快照。如果尚不存在运行时快照，则回退到磁盘上解析得到的配置文件。
|
||||
通过门面加载的内置插件公共 surface（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似公共入口文件）现在会在 OpenClaw 已运行时优先使用活动运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上解析得到的配置文件。
|
||||
|
||||
当某个辅助函数有意是提供商特定的，且暂时还不适合放入通用 SDK 子路径时，提供商插件也可以暴露一个狭义的插件本地契约 barrel。当前内置示例：Anthropic 提供商将其 Claude 流辅助函数保留在自己的公共 `api.ts` / `contract-api.ts` 接口中，而不是将 Anthropic beta-header 和 `service_tier` 逻辑提升为通用 `plugin-sdk/*` 契约。
|
||||
如果某个辅助函数有意设计为提供商特定，且暂时还不适合放入通用 SDK 子路径中，提供商插件也可以暴露一个狭义的插件本地契约 barrel。当前的内置示例：Anthropic 提供商将其 Claude 流辅助函数保留在自己的公共 `api.ts` / `contract-api.ts` 层中，而不是把 Anthropic beta-header 和 `service_tier` 逻辑提升为通用的 `plugin-sdk/*` 契约。
|
||||
|
||||
其他当前内置示例：
|
||||
|
||||
- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、默认模型辅助函数和实时提供商构建器
|
||||
- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及新手引导/配置辅助函数
|
||||
- `@openclaw/openai-provider`：`api.ts` 导出提供商构建器、
|
||||
默认模型辅助函数和实时提供商构建器
|
||||
- `@openclaw/openrouter-provider`：`api.ts` 导出提供商构建器以及
|
||||
新手引导/配置辅助函数
|
||||
|
||||
<Warning>
|
||||
扩展生产代码也应避免导入 `openclaw/plugin-sdk/<other-plugin>`。如果某个辅助函数确实需要共享，请将其提升为中立的 SDK 子路径，例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他面向能力的表面，而不是让两个插件彼此耦合。
|
||||
扩展生产代码也应避免导入 `openclaw/plugin-sdk/<other-plugin>`。
|
||||
如果某个辅助函数确实是共享的，应将其提升到一个中立的 SDK 子路径，
|
||||
例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他
|
||||
面向能力的 surface，而不是让两个插件耦合在一起。
|
||||
</Warning>
|
||||
|
||||
## 相关内容
|
||||
@ -445,5 +455,5 @@ my-plugin/
|
||||
- [运行时辅助函数](/zh-CN/plugins/sdk-runtime) — 完整的 `api.runtime` 命名空间参考
|
||||
- [设置和配置](/zh-CN/plugins/sdk-setup) — 打包、manifest、配置 schema
|
||||
- [测试](/zh-CN/plugins/sdk-testing) — 测试工具和 lint 规则
|
||||
- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用表面迁移
|
||||
- [插件内部原理](/zh-CN/plugins/architecture) — 深入的架构和能力模型
|
||||
- [SDK 迁移](/zh-CN/plugins/sdk-migration) — 从已弃用 surface 迁移
|
||||
- [插件内部机制](/zh-CN/plugins/architecture) — 深入架构和能力模型
|
||||
|
||||
Loading…
Reference in New Issue
Block a user