diff --git a/docs/zh-CN/cli/skills.md b/docs/zh-CN/cli/skills.md index 518e5569f..1f0ebf97b 100644 --- a/docs/zh-CN/cli/skills.md +++ b/docs/zh-CN/cli/skills.md @@ -1,15 +1,15 @@ --- read_when: - - 你想查看哪些 Skills 可用并已准备好运行 + - 你想查看哪些 Skills 可用并且已准备好运行 - 你想从 ClawHub 搜索、安装或更新 Skills - - 你想调试 Skills 缺少的二进制文件、环境变量或配置问题 -summary: '`openclaw skills` 的 CLI 参考（搜索/安装/更新/列出/信息/检查）' + - 你想调试 Skills 缺失的二进制文件、环境变量或配置 +summary: '`openclaw skills` 的 CLI 参考（search/install/update/list/info/check）' title: Skills x-i18n: - generated_at: "2026-04-24T03:15:20Z" + generated_at: "2026-04-28T00:10:31Z" model: gpt-5.4 provider: openai - source_hash: 31cd7647a15cd5df6cf5a2311e63bb11cc3aabfe8beefda7be57dc76adc509ea + source_hash: 5059bf04c68dabe289d2c376407a52989c970e3d16e7637a2c83f4e24ad6564c source_path: cli/skills.md workflow: 15 --- @@ -20,9 +20,9 @@ x-i18n: 相关内容： -- Skills 系统： [Skills](/zh-CN/tools/skills) -- Skills 配置： [Skills config](/zh-CN/tools/skills-config) -- ClawHub 安装： [ClawHub](/zh-CN/tools/clawhub) +- Skills 系统：[Skills](/zh-CN/tools/skills) +- Skills 配置：[Skills 配置](/zh-CN/tools/skills-config) +- ClawHub 安装：[ClawHub](/zh-CN/tools/clawhub) ## 命令 @@ -32,38 +32,38 @@ openclaw skills search --limit 20 --json openclaw skills install openclaw skills install --version openclaw skills install --force +openclaw skills install --agent openclaw skills update openclaw skills update --all +openclaw skills update --all --agent openclaw skills list openclaw skills list --eligible openclaw skills list --json openclaw skills list --verbose +openclaw skills list --agent openclaw skills info openclaw skills info --json +openclaw skills info --agent openclaw skills check openclaw skills check --json +openclaw skills check --agent ``` -`search`/`install`/`update` 会直接使用 ClawHub，并安装到当前活动工作区的 -`skills/` 目录中。`list`/`info`/`check` 仍然会检查当前工作区和配置可见的本地 -Skills。 +`search`/`install`/`update` 直接使用 ClawHub，并安装到当前工作区的 `skills/` 目录中。`list`/`info`/`check` 仍会检查当前工作区和配置可见的本地 Skills。基于工作区的命令会按以下顺序解析目标工作区：先看 `--agent `，然后看当前工作目录是否位于已配置的 Agent 工作区内，最后回退到默认智能体。 -这个 CLI `install` 命令会从 ClawHub 下载 skill 文件夹。由新手引导或 Skills 设置触发的、 -基于 Gateway 网关的 skill 依赖安装，则会改用单独的 `skills.install` 请求路径。 +这个 CLI `install` 命令会从 ClawHub 下载 skill 文件夹。由新手引导或 Skills 设置触发、基于 Gateway 网关的 skill 依赖安装，则会改用独立的 `skills.install` 请求路径。 -注意事项： +说明： -- `search [query...]` 接受可选查询；省略时会浏览默认的 - ClawHub 搜索源。 -- `search --limit ` 会限制返回结果数量。 -- `install --force` 会覆盖工作区中同一 slug 的现有 skill 文件夹。 -- `update --all` 只会更新当前活动工作区中已跟踪的 ClawHub 安装。 +- `search [query...]` 接受可选查询；省略时会浏览默认的 ClawHub 搜索流。 +- `search --limit ` 用于限制返回结果数量。 +- `install --force` 会覆盖工作区中相同 slug 的现有 skill 文件夹。 +- `--agent ` 会指定一个已配置的智能体工作区，并覆盖当前工作目录推断。 +- `update --all` 只会更新当前工作区中已跟踪的 ClawHub 安装项。 - 未提供子命令时，`list` 是默认操作。 -- `list`、`info` 和 `check` 会将渲染后的输出写入 stdout。使用 - `--json` 时，这意味着机器可读负载会保留在 stdout 中，以便用于管道 - 和脚本。 +- `list`、`info` 和 `check` 会将渲染后的输出写入 stdout。使用 `--json` 时，这意味着机器可读的负载会保留在 stdout 中，便于管道和脚本使用。 -## 相关内容 +## 相关 - [CLI 参考](/zh-CN/cli) - [Skills](/zh-CN/tools/skills) diff --git a/docs/zh-CN/plugins/hooks.md b/docs/zh-CN/plugins/hooks.md index d437befbd..c99fe93f2 100644 --- a/docs/zh-CN/plugins/hooks.md +++ b/docs/zh-CN/plugins/hooks.md @@ -1,26 +1,26 @@ --- read_when: - 你正在构建一个插件，需要 `before_tool_call`、`before_agent_reply`、消息钩子或生命周期钩子 - - 你需要从插件中阻止、重写或要求批准工具调用 + - 你需要从插件中拦截、重写或要求批准工具调用 - 你正在内部钩子和插件钩子之间做选择 -summary: 插件钩子：拦截智能体、工具、消息、会话和 Gateway 网关生命周期事件 +summary: 插件钩子：拦截智能体、工具、消息、会话以及 Gateway 网关生命周期事件 title: 插件钩子 x-i18n: - generated_at: "2026-04-27T22:37:13Z" + generated_at: "2026-04-28T00:10:29Z" model: gpt-5.4 provider: openai - source_hash: 0aae1c2321491ed0eb82b6306be61cd7e4bffccf8e22d1455267110fdf4fc62b + source_hash: 2bdc52ada8f8949f24b7930ee1daac254477ef678396ea61102775173f68e0d5 source_path: plugins/hooks.md workflow: 15 --- -插件钩子是 OpenClaw 插件的进程内扩展点。当插件需要检查或更改智能体运行、工具调用、消息流、会话生命周期、子智能体路由、安装流程或 Gateway 网关启动时，请使用它们。 +插件钩子是 OpenClaw 插件的进程内扩展点。当插件需要检查或更改智能体运行、工具调用、消息流、会话生命周期、子智能体路由、安装或 Gateway 网关启动时，请使用它们。 -如果你想为命令和 Gateway 网关事件（如 `/new`、`/reset`、`/stop`、`agent:bootstrap` 或 `gateway:startup`）使用一个由运维安装的小型 `HOOK.md` 脚本，请改用 [内部钩子](/zh-CN/automation/hooks)。 +如果你想要一个由操作员安装的、用于处理命令和 Gateway 网关事件（例如 `/new`、`/reset`、`/stop`、`agent:bootstrap` 或 `gateway:startup`）的小型 `HOOK.md` 脚本，请改用 [内部钩子](/zh-CN/automation/hooks)。 ## 快速开始 -在你的插件入口中，使用 `api.on(...)` 注册类型化的插件钩子： +在你的插件入口中，使用 `api.on(...)` 注册带类型的插件钩子： ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -52,35 +52,37 @@ export default definePluginEntry({ }); ``` -钩子处理程序会按 `priority` 降序依次运行。同一优先级的钩子会保留注册顺序。 +钩子处理器会按 `priority` 降序依次运行。相同优先级的钩子会保留注册顺序。 -每个钩子都会接收 `event.context.pluginConfig`，即注册该处理程序的插件的已解析配置。当钩子决策需要当前插件选项时，请使用它；OpenClaw 会按处理程序注入它，而不会修改其他插件看到的共享事件对象。 +每个钩子都会收到 `event.context.pluginConfig`，即为注册该处理器的插件解析出的配置。对于需要使用当前插件选项来做决策的钩子，请使用它；OpenClaw 会按处理器为其注入，而不会修改其他插件所见的共享事件对象。 ## 钩子目录 -钩子按其扩展的表面分组。**粗体**中的名称接受决策结果（阻止、取消、覆盖或要求批准）；其他所有钩子仅用于观察。 +钩子按其扩展的表面分组。**加粗** 的名称接受决策结果（阻止、取消、覆盖或要求批准）；其他所有钩子都仅用于观察。 **智能体轮次** -- `before_model_resolve` — 在加载会话消息之前覆盖提供商或模型 -- `before_prompt_build` — 在模型调用之前添加动态上下文或系统提示文本 -- `before_agent_start` — 仅为兼容性保留的合并阶段；优先使用上面的两个钩子 -- **`before_agent_reply`** — 用合成回复或静默短路模型轮次 +- `before_model_resolve` — 在加载会话消息前覆盖提供商或模型 +- `agent_turn_prepare` — 消费排队的插件轮次注入，并在提示词钩子之前添加同一轮次上下文 +- `before_prompt_build` — 在模型调用前添加动态上下文或系统提示词文本 +- `before_agent_start` — 仅用于兼容性的合并阶段；优先使用上面的两个钩子 +- **`before_agent_reply`** — 用合成回复或静默来短路模型轮次 - **`before_agent_finalize`** — 检查自然生成的最终答案，并请求再进行一次模型传递 - `agent_end` — 观察最终消息、成功状态和运行时长 +- `heartbeat_prompt_contribution` — 为后台监控和生命周期插件添加仅心跳可见的上下文 **对话观察** -- `model_call_started` / `model_call_ended` — 观察已脱敏的提供商/模型调用元数据、计时、结果和有界请求 ID 哈希，不包含提示或响应内容 -- `llm_input` — 观察提供商输入（系统提示、提示、历史记录） +- `model_call_started` / `model_call_ended` — 观察已脱敏的提供商/模型调用元数据、时序、结果以及有界的请求 ID 哈希，不包含提示词或响应内容 +- `llm_input` — 观察提供商输入（系统提示词、提示词、历史记录） - `llm_output` — 观察提供商输出 **工具** - **`before_tool_call`** — 重写工具参数、阻止执行或要求批准 -- `after_tool_call` — 观察工具结果、错误和持续时间 -- **`tool_result_persist`** — 重写根据工具结果生成的助手消息 -- **`before_message_write`** — 检查或阻止正在进行中的消息写入（较少见） +- `after_tool_call` — 观察工具结果、错误和时长 +- **`tool_result_persist`** — 重写由工具结果生成的助手消息 +- **`before_message_write`** — 检查或阻止正在进行中的消息写入（较少使用） **消息与投递** @@ -88,7 +90,7 @@ export default definePluginEntry({ - `message_received` — 观察入站内容、发送者、线程和元数据 - **`message_sending`** — 重写出站内容或取消投递 - `message_sent` — 观察出站投递成功或失败 -- **`before_dispatch`** — 在移交给渠道之前检查或重写出站分发 +- **`before_dispatch`** — 在交给渠道前检查或重写一次出站分发 - **`reply_dispatch`** — 参与最终回复分发流水线 **会话与压缩** @@ -108,14 +110,14 @@ export default definePluginEntry({ ## 工具调用策略 -`before_tool_call` 接收： +`before_tool_call` 会收到： - `event.toolName` - `event.params` - 可选的 `event.runId` - 可选的 `event.toolCallId` -- 上下文字段，如 `ctx.agentId`、`ctx.sessionKey`、`ctx.sessionId`、 - `ctx.runId`、`ctx.jobId`（在 cron 驱动的运行中设置），以及诊断用的 `ctx.trace` +- 上下文字段，例如 `ctx.agentId`、`ctx.sessionKey`、`ctx.sessionId`、 + `ctx.runId`、`ctx.jobId`（在由 cron 驱动的运行中设置）以及诊断用的 `ctx.trace` 它可以返回： @@ -140,46 +142,44 @@ type BeforeToolCallResult = { 规则： -- `block: true` 是终止性决定，会跳过更低优先级的处理程序。 -- `block: false` 会被视为无决策。 -- `params` 会重写用于执行的工具参数。 -- `requireApproval` 会暂停智能体运行，并通过插件批准机制向用户发起请求。`/approve` 命令既可以批准 exec 批准，也可以批准插件批准。 +- `block: true` 是终止性的，并会跳过更低优先级的处理器。 +- `block: false` 会被视为没有做出决策。 +- `params` 会重写执行时使用的工具参数。 +- `requireApproval` 会暂停智能体运行，并通过插件审批请求用户确认。`/approve` 命令可以同时批准 exec 审批和插件审批。 - 即使更高优先级的钩子请求了批准，更低优先级的 `block: true` 仍然可以阻止执行。 -- `onResolution` 会接收已解析的批准决定 —— `allow-once`、 - `allow-always`、`deny`、`timeout` 或 `cancelled`。 +- `onResolution` 会收到最终解析出的审批决定 —— `allow-once`、`allow-always`、`deny`、`timeout` 或 `cancelled`。 + +需要宿主级策略的内置插件可以通过 `api.registerTrustedToolPolicy(...)` 注册受信任的工具策略。这些策略会在普通 `before_tool_call` 钩子和外部插件决策之前运行。仅应将它们用于诸如工作区策略、预算强制或保留工作流安全之类的宿主可信门控。外部插件应使用普通的 `before_tool_call` 钩子。 ### 工具结果持久化 -工具结果可以包含结构化的 `details`，用于 UI 渲染、诊断、媒体路由或插件自有元数据。请将 `details` 视为运行时元数据，而不是提示内容： +工具结果可以包含结构化的 `details`，用于 UI 渲染、诊断、媒体路由或插件拥有的元数据。请将 `details` 视为运行时元数据，而不是提示词内容： -- OpenClaw 会在提供商重放和压缩输入之前去除 `toolResult.details`，以避免元数据成为模型上下文。 -- 持久化的会话条目只保留有界的 `details`。过大的 details 会被替换为紧凑摘要，并设置 `persistedDetailsTruncated: true`。 -- `tool_result_persist` 和 `before_message_write` 会在最终持久化上限之前运行。钩子仍应保持返回的 `details` 足够小，并避免只将与提示相关的文本放在 `details` 中；把模型可见的工具输出放在 `content` 中。 +- OpenClaw 会在提供商重放和压缩输入前去除 `toolResult.details`，以避免元数据变成模型上下文。 +- 持久化的会话条目只会保留有界的 `details`。超大的 details 会被替换为紧凑摘要，并带上 `persistedDetailsTruncated: true`。 +- `tool_result_persist` 和 `before_message_write` 会在最终持久化大小限制之前运行。钩子仍应保持返回的 `details` 较小，并避免只把与提示词相关的文本放在 `details` 中；应将模型可见的工具输出放在 `content` 中。 -## 提示和模型钩子 +## 提示词与模型钩子 对于新插件，请使用按阶段划分的钩子： -- `before_model_resolve`：只接收当前提示和附件元数据。返回 `providerOverride` 或 `modelOverride`。 -- `before_prompt_build`：接收当前提示和会话消息。返回 `prependContext`、`systemPrompt`、`prependSystemContext` 或 `appendSystemContext`。 +- `before_model_resolve`：仅接收当前提示词和附件元数据。返回 `providerOverride` 或 `modelOverride`。 +- `agent_turn_prepare`：接收当前提示词、已准备的会话消息，以及为该会话排空的任何“恰好一次”队列注入。返回 `prependContext` 或 `appendContext`。 +- `before_prompt_build`：接收当前提示词和会话消息。返回 `prependContext`、`appendContext`、`systemPrompt`、 + `prependSystemContext` 或 `appendSystemContext`。 +- `heartbeat_prompt_contribution`：仅在心跳轮次中运行，并返回 `prependContext` 或 `appendContext`。它适用于需要汇总当前状态、但不应改变用户发起轮次的后台监控器。 -`before_agent_start` 仍为兼容性保留。优先使用上面的显式钩子，这样你的插件就不会依赖旧的合并阶段。 +`before_agent_start` 仍然保留用于兼容性。优先使用上面的显式钩子，这样你的插件就不会依赖旧的合并阶段。 -当 OpenClaw 能识别当前活动运行时，`before_agent_start` 和 `agent_end` 会包含 `event.runId`。同样的值也可以从 `ctx.runId` 获取。 +当 OpenClaw 能识别当前活动运行时，`before_agent_start` 和 `agent_end` 会包含 `event.runId`。同一个值也可通过 `ctx.runId` 获取。由 cron 驱动的运行还会暴露 `ctx.jobId`（源 cron 作业 ID），这样插件钩子就可以将指标、副作用或状态限定到特定的计划任务上。 -由 cron 驱动的运行还会公开 `ctx.jobId`（源 cron 作业 ID），以便插件钩子将指标、副作用或状态限定到特定的定时作业。 +对于不应接收原始提示词、历史记录、响应、请求头、请求体或提供商请求 ID 的提供商调用遥测，请使用 `model_call_started` 和 `model_call_ended`。这些钩子包含稳定的元数据，例如 `runId`、`callId`、`provider`、`model`、可选的 `api`/`transport`、最终的 `durationMs`/`outcome`，以及当 OpenClaw 能推导出有界的提供商请求 ID 哈希时提供的 `upstreamRequestIdHash`。 -如果你需要不接收原始提示、历史记录、响应、标头、请求体或提供商请求 ID 的提供商调用遥测，请使用 `model_call_started` 和 `model_call_ended`。这些钩子包含稳定元数据，例如 -`runId`、`callId`、`provider`、`model`、可选的 `api`/`transport`、终态的 -`durationMs`/`outcome`，以及当 OpenClaw 能推导时的 -`upstreamRequestIdHash`（有界的提供商请求 ID 哈希）。 - -`before_agent_finalize` 仅在某个 harness 即将接受一个自然生成的最终助手答案时运行。它不是 `/stop` 取消路径，也不会在用户中止某轮时运行。返回 `{ action: "revise", reason }` 可请求 harness 在最终确定前再进行一次模型传递；返回 `{ action: -"finalize", reason? }` 可强制最终确定；也可以省略返回结果以继续。Codex 原生 `Stop` 钩子会作为 OpenClaw 的 -`before_agent_finalize` 决策转发到这里。 +`before_agent_finalize` 仅在某个 harness 即将接受自然生成的最终助手答案时运行。它不是 `/stop` 取消路径，在用户中止某一轮时也不会运行。返回 `{ action: "revise", reason }` 以请求 harness 在最终确定前再进行一次模型传递，返回 `{ action: +"finalize", reason? }` 以强制最终确定，或省略结果以继续。Codex 原生的 `Stop` 钩子会作为 OpenClaw 的 `before_agent_finalize` 决策被转发到这里。 需要使用 `llm_input`、`llm_output`、 -`before_agent_finalize` 或 `agent_end` 的非内置插件，必须设置： +`before_agent_finalize` 或 `agent_end` 的非内置插件必须设置： ```json { @@ -195,64 +195,70 @@ type BeforeToolCallResult = { } ``` -可以通过 -`plugins.entries..hooks.allowPromptInjection=false` -按插件禁用会修改提示的钩子。 +会修改提示词的钩子和持久化的下一轮注入可以通过 `plugins.entries..hooks.allowPromptInjection=false` 按插件禁用。 + +### 会话扩展与下一轮注入 + +工作流插件可以通过 `api.registerSessionExtension(...)` 持久化小型 JSON 兼容会话状态，并通过 Gateway 网关的 `sessions.pluginPatch` 方法更新它。会话行会通过 `pluginExtensions` 投影已注册的扩展状态，使 Control UI 和其他客户端能够在不了解插件内部细节的情况下渲染插件拥有的状态。 + +当插件需要让持久上下文恰好一次地传递到下一次模型轮次时，请使用 `api.enqueueNextTurnInjection(...)`。OpenClaw 会在提示词钩子之前排空已排队的注入、丢弃过期注入，并按插件基于 `idempotencyKey` 去重。这是用于审批恢复、策略摘要、后台监控增量以及命令延续的正确接缝：这些内容应在下一轮对模型可见，但不应成为永久性的系统提示词文本。 + +清理语义是契约的一部分。会话扩展清理和运行时生命周期清理回调会收到 `reset`、`delete`、`disable` 或 `restart`。对于 reset/delete/disable，宿主会移除所属插件的持久化会话扩展状态和待处理的下一轮注入；对于 restart，则会保留持久化会话状态，同时清理回调允许插件释放旧运行时代的调度器任务、运行上下文及其他带外资源。 ## 消息钩子 -将消息钩子用于渠道级路由和投递策略： +对渠道级路由和投递策略，请使用消息钩子： - `message_received`：观察入站内容、发送者、`threadId`、`messageId`、 `senderId`、可选的运行/会话关联以及元数据。 - `message_sending`：重写 `content` 或返回 `{ cancel: true }`。 - `message_sent`：观察最终成功或失败。 -对于仅音频的 TTS 回复，即使渠道负载中没有可见文本/标题，`content` 也可能包含隐藏的语音转录文本。重写该 `content` 只会更新钩子可见的转录文本；它不会作为媒体标题呈现。 +对于纯音频 TTS 回复，即使渠道负载没有可见文本/说明，`content` 也可能包含隐藏的口述转录文本。重写该 `content` 只会更新钩子可见的转录文本；它不会被渲染为媒体说明。 -消息钩子的上下文在可用时会公开稳定的关联字段： +消息钩子上下文会在可用时暴露稳定的关联字段： `ctx.sessionKey`、`ctx.runId`、`ctx.messageId`、`ctx.senderId`、`ctx.trace`、 -`ctx.traceId`、`ctx.spanId`、`ctx.parentSpanId` 和 `ctx.callDepth`。优先使用这些一等字段，而不是读取旧版元数据。 +`ctx.traceId`、`ctx.spanId`、`ctx.parentSpanId` 和 `ctx.callDepth`。在读取旧版元数据之前，优先使用这些一等字段。 -优先使用类型化的 `threadId` 和 `replyToId` 字段，而不是使用渠道特定的元数据。 +在使用特定渠道的元数据之前，优先使用带类型的 `threadId` 和 `replyToId` 字段。 决策规则： -- 带有 `cancel: true` 的 `message_sending` 是终止性决定。 -- 带有 `cancel: false` 的 `message_sending` 会被视为无决策。 +- 带有 `cancel: true` 的 `message_sending` 是终止性的。 +- 带有 `cancel: false` 的 `message_sending` 会被视为没有做出决策。 - 被重写的 `content` 会继续传递给更低优先级的钩子，除非后续钩子取消投递。 ## 安装钩子 -`before_install` 会在内置的 Skills 和插件安装扫描之后运行。返回附加发现项，或返回 `{ block: true, blockReason }` 以停止安装。 +`before_install` 会在 Skills 和插件安装的内置扫描之后运行。返回额外的发现结果，或返回 `{ block: true, blockReason }` 以停止安装。 -`block: true` 是终止性决定。`block: false` 会被视为无决策。 +`block: true` 是终止性的。`block: false` 会被视为没有做出决策。 ## Gateway 网关生命周期 -对于需要 Gateway 网关自有状态的插件服务，请使用 `gateway_start`。上下文会公开 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()`，用于 cron 检查和更新。使用 `gateway_stop` 清理长时间运行的资源。 +对于需要 Gateway 网关持有状态的插件服务，请使用 `gateway_start`。上下文会暴露 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()` 以供检查和更新 cron。使用 `gateway_stop` 清理长时间运行的资源。 -不要依赖内部的 `gateway:startup` 钩子来运行插件自有的运行时服务。 +不要依赖内部的 `gateway:startup` 钩子来管理由插件拥有的运行时服务。 -## 即将弃用的内容 +## 即将弃用的功能 -有一些与钩子相邻的表面已弃用，但仍受支持。请在下一个主要版本发布前迁移： +有一些与钩子相邻的表面已经弃用，但仍受支持。请在下一个主要版本发布前完成迁移： -- **`inbound_claim` 和 `message_received` 处理程序中的纯文本渠道封套**。请读取 `BodyForAgent` 和结构化的用户上下文块，而不是解析扁平封套文本。参见 - [纯文本渠道封套 → BodyForAgent](/zh-CN/plugins/sdk-migration#active-deprecations)。 -- **`before_agent_start`** 仍为兼容性保留。新插件应使用 +- **`inbound_claim` 和 `message_received` 处理器中的纯文本渠道信封**。请读取 `BodyForAgent` 和结构化的用户上下文块，而不是解析扁平信封文本。参见 + [纯文本渠道信封 → BodyForAgent](/zh-CN/plugins/sdk-migration#active-deprecations)。 +- **`before_agent_start`** 仍保留用于兼容性。新插件应使用 `before_model_resolve` 和 `before_prompt_build`，而不是这个合并阶段。 -- **`before_tool_call` 中的 `onResolution`** 现在使用类型化的 +- **`before_tool_call` 中的 `onResolution`** 现在使用带类型的 `PluginApprovalResolution` 联合类型（`allow-once` / `allow-always` / `deny` / - `timeout` / `cancelled`），而不是自由格式的 `string`。 + `timeout` / `cancelled`），而不是自由形式的 `string`。 -完整列表——内存能力注册、提供商 thinking -profile、外部身份验证提供商、提供商发现类型、任务运行时访问器，以及 `command-auth` → `command-status` 重命名——请参见 +完整列表——包括内存能力注册、提供商 thinking +profile、外部认证提供商、提供商发现类型、任务运行时访问器，以及 `command-auth` → `command-status` 重命名——请参见 [插件 SDK 迁移 → 当前弃用项](/zh-CN/plugins/sdk-migration#active-deprecations)。 ## 相关内容 -- [插件 SDK 迁移](/zh-CN/plugins/sdk-migration) — 当前弃用项和移除时间线 +- [插件 SDK 迁移](/zh-CN/plugins/sdk-migration) — 当前弃用项及移除时间线 - [构建插件](/zh-CN/plugins/building-plugins) - [插件 SDK 概览](/zh-CN/plugins/sdk-overview) - [插件入口点](/zh-CN/plugins/sdk-entrypoints) diff --git a/docs/zh-CN/plugins/sdk-overview.md b/docs/zh-CN/plugins/sdk-overview.md index 5962968bf..f717d7a18 100644 --- a/docs/zh-CN/plugins/sdk-overview.md +++ b/docs/zh-CN/plugins/sdk-overview.md @@ -1,29 +1,29 @@ --- read_when: - - 你需要知道应该从哪个 SDK 子路径导入 + - 你需要知道应从哪个 SDK 子路径导入 - 你想要一份 OpenClawPluginApi 上所有注册方法的参考文档 - 你正在查找某个特定的 SDK 导出项 sidebarTitle: SDK overview summary: 导入映射、注册 API 参考和 SDK 架构 title: 插件 SDK 概览 x-i18n: - generated_at: "2026-04-27T10:59:55Z" + generated_at: "2026-04-28T00:10:30Z" model: gpt-5.4 provider: openai - source_hash: 205c57492fd2c90c01a87bae34716d6abcf420c7bdc2f51bd3042e52a3872ec6 + source_hash: f9b00b189c2a5e632a1c7e614a3e9371dcc3114d3582d795e3c88fb5d5a0f13a source_path: plugins/sdk-overview.md workflow: 15 --- -插件 SDK 是插件与核心之间的类型化契约。本页是关于**导入什么**以及**你可以注册什么**的参考文档。 +插件 SDK 是插件与核心之间的类型化契约。本页是关于**该导入什么**以及**你可以注册什么**的参考文档。 - 你是在找操作指南吗？ + 想找操作指南而不是参考文档？ -- 第一个插件？从[构建插件](/zh-CN/plugins/building-plugins)开始。 -- 渠道插件？参见[渠道插件](/zh-CN/plugins/sdk-channel-plugins)。 -- 提供商插件？参见[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。 -- 工具或生命周期钩子插件？参见[插件钩子](/zh-CN/plugins/hooks)。 +- 第一个插件？从 [构建插件](/zh-CN/plugins/building-plugins) 开始。 +- 渠道插件？请参阅 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。 +- 提供商插件？请参阅 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。 +- 工具或生命周期钩子插件？请参阅 [插件钩子](/zh-CN/plugins/hooks)。 ## 导入约定 @@ -35,90 +35,117 @@ 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` 保留给更广泛的总入口 surface 和共享辅助函数，例如 `buildChannelConfigSchema`。 +每个子路径都是一个小型、自包含模块。这样可以保持快速启动，并防止循环依赖问题。对于渠道特定的入口点/构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的聚合表面和共享辅助函数，例如 `buildChannelConfigSchema`。 -对于渠道配置，请通过 `openclaw.plugin.json#channelConfigs` 发布由渠道拥有的 JSON Schema。`plugin-sdk/channel-config-schema` 子路径用于共享的 schema 原语和通用构建器。已弃用的内置渠道 schema 导出位于 `plugin-sdk/channel-config-schema-legacy`，仅用于内置兼容性；它们不是新插件应采用的模式。 +对于渠道配置，请通过 `openclaw.plugin.json#channelConfigs` 发布由渠道拥有的 JSON Schema。`plugin-sdk/channel-config-schema` 子路径用于共享 schema 基元和通用构建器。已弃用的内置渠道 schema 导出保留在 `plugin-sdk/channel-config-schema-legacy` 中，仅用于内置兼容性；它们不应作为新插件的模式。 - 不要导入带有 provider 或渠道品牌色彩的便捷 seams（例如 - `openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。 + 不要导入带有提供商或渠道品牌色彩的便捷 seam（例如 `openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。 内置插件会在它们自己的 `api.ts` / - `runtime-api.ts` barrels 中组合通用 SDK 子路径；核心使用方应当要么使用这些插件本地 - barrels，要么在确实属于跨渠道需求时新增一个狭窄的通用 SDK 契约。 + `runtime-api.ts` barrel 中组合通用 SDK 子路径；核心使用方应当改用这些插件本地的 + barrel，或者在确实存在跨渠道需求时添加一个狭义的通用 SDK 契约。 -生成的导出映射中仍会出现一小组内置插件辅助 seams（`plugin-sdk/feishu`、 -`plugin-sdk/zalo`、`plugin-sdk/matrix*` 等）。它们仅用于内置插件维护， -不推荐作为新的第三方插件导入路径。 +在生成的导出映射中，仍会出现一小部分内置插件辅助 seam（`plugin-sdk/feishu`、`plugin-sdk/zalo`、`plugin-sdk/matrix*` 及类似项）。它们仅供内置插件维护使用，不建议作为新的第三方插件导入路径。 ## 子路径参考 -插件 SDK 以一组按领域划分的狭窄子路径形式公开（插件入口、渠道、provider、认证、运行时、能力、内存，以及为内置插件保留的辅助项）。完整目录——按组分类并附带链接——参见 -[插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)。 +插件 SDK 以一组按领域分组的狭义子路径形式暴露（插件入口点、渠道、提供商、认证、运行时、能力、记忆，以及保留的内置插件辅助函数）。完整目录——按组分类并附带链接——请参阅 [插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)。 包含 200 多个子路径的生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。 ## 注册 API -`register(api)` 回调会收到一个 `OpenClawPluginApi` 对象，包含以下方法： +`register(api)` 回调会接收一个 `OpenClawPluginApi` 对象，它包含以下方法： ### 能力注册 -| 方法 | 注册内容 | -| ------------------------------------------------ | ----------------------------- | -| `api.registerProvider(...)` | 文本推理（LLM） | -| `api.registerAgentHarness(...)` | 实验性的低层智能体执行器 | -| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | -| `api.registerChannel(...)` | 消息渠道 | -| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | -| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 | -| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 | -| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 | -| `api.registerImageGenerationProvider(...)` | 图像生成 | -| `api.registerMusicGenerationProvider(...)` | 音乐生成 | -| `api.registerVideoGenerationProvider(...)` | 视频生成 | -| `api.registerWebFetchProvider(...)` | Web 抓取 / 抓页提供商 | -| `api.registerWebSearchProvider(...)` | Web 搜索 | +| Method | 它注册的内容 | +| ------------------------------------------------ | ---------------------------- | +| `api.registerProvider(...)` | 文本推理（LLM） | +| `api.registerAgentHarness(...)` | 实验性的底层智能体执行器 | +| `api.registerCliBackend(...)` | 本地 CLI 推理后端 | +| `api.registerChannel(...)` | 消息渠道 | +| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 | +| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转写 | +| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 | +| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 | +| `api.registerImageGenerationProvider(...)` | 图像生成 | +| `api.registerMusicGenerationProvider(...)` | 音乐生成 | +| `api.registerVideoGenerationProvider(...)` | 视频生成 | +| `api.registerWebFetchProvider(...)` | Web 抓取 / 抓取提供商 | +| `api.registerWebSearchProvider(...)` | Web 搜索 | ### 工具和命令 -| 方法 | 注册内容 | -| ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | 智能体工具（必需，或 `{ optional: true }`） | -| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | +| Method | 它注册的内容 | +| ------------------------------- | -------------------------------------------- | +| `api.registerTool(tool, opts?)` | 智能体工具（必需，或 `{ optional: true }`） | +| `api.registerCommand(def)` | 自定义命令（绕过 LLM） | -当智能体需要简短的、命令自身拥有的路由提示时，插件命令可以设置 `agentPromptGuidance`。保持这段文本只描述命令本身；不要向核心提示词构建器添加特定于 provider 或插件的策略。 +当智能体需要简短的、由命令自身拥有的路由提示时，插件命令可以设置 `agentPromptGuidance`。请将这段文本限定为命令本身；不要把提供商或插件特定策略添加到核心提示构建器中。 ### 基础设施 -| 方法 | 注册内容 | -| ---------------------------------------------- | ------------------------------- | -| `api.registerHook(events, handler, opts?)` | 事件钩子 | +| Method | 它注册的内容 | +| ---------------------------------------------- | -------------------------------- | +| `api.registerHook(events, handler, opts?)` | 事件钩子 | | `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 | | `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 | | `api.registerGatewayDiscoveryService(service)` | 本地 Gateway 网关发现广播器 | | `api.registerCli(registrar, opts?)` | CLI 子命令 | -| `api.registerService(service)` | 后台服务 | -| `api.registerInteractiveHandler(registration)` | 交互式处理器 | -| `api.registerAgentToolResultMiddleware(...)` | 运行时工具结果中间件 | -| `api.registerMemoryPromptSupplement(builder)` | 可叠加的 memory 邻接提示词区段 | -| `api.registerMemoryCorpusSupplement(adapter)` | 可叠加的 memory 搜索/读取语料库 | +| `api.registerService(service)` | 后台服务 | +| `api.registerInteractiveHandler(registration)` | 交互处理器 | +| `api.registerAgentToolResultMiddleware(...)` | 运行时工具结果中间件 | +| `api.registerMemoryPromptSupplement(builder)` | 追加式的记忆邻近提示区段 | +| `api.registerMemoryCorpusSupplement(adapter)` | 追加式的记忆搜索/读取语料库 | + +### 面向工作流插件的宿主钩子 + +宿主钩子是供需要参与宿主生命周期的插件使用的 SDK seam，而不仅仅是添加一个提供商、渠道或工具。它们是通用契约；Plan Mode 可以使用它们，但审批工作流、工作区策略门禁、后台监视器、设置向导和 UI 配套插件也可以使用。 + +| Method | 它拥有的契约 | +| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | +| `api.registerSessionExtension(...)` | 由插件拥有、与 JSON 兼容的会话状态，通过 Gateway 网关会话投射 | +| `api.enqueueNextTurnInjection(...)` | 持久化且严格一次的上下文，为单个会话注入到下一次智能体轮次中 | +| `api.registerTrustedToolPolicy(...)` | 内置/受信任的预插件工具策略，可阻止或重写工具参数 | +| `api.registerToolMetadata(...)` | 工具目录显示元数据，不改变工具实现 | +| `api.registerCommand(...)` | 作用域化插件命令；命令结果可设置 `continueAgent: true` | +| `api.registerControlUiDescriptor(...)` | 面向会话、工具、运行或设置界面的 Control UI 贡献描述符 | +| `api.registerRuntimeLifecycle(...)` | 在重置/删除/重载路径上清理插件拥有的运行时资源的回调 | +| `api.registerAgentEventSubscription(...)` | 用于工作流状态和监视器的净化事件订阅 | +| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | 每次运行的插件临时状态，在终止运行生命周期时清除 | +| `api.registerSessionSchedulerJob(...)` | 由插件拥有的会话调度器作业记录，带有确定性的清理机制 | + +这些契约有意拆分了权限边界： + +- 外部插件可以拥有会话扩展、UI 描述符、命令、工具元数据、下一轮注入以及常规钩子。 +- 受信任的工具策略会在普通 `before_tool_call` 钩子之前运行，并且仅限内置插件，因为它们参与宿主安全策略。 +- 保留命令所有权仅限内置插件。外部插件应使用它们自己的命令名称或别名。 +- `allowPromptInjection=false` 会禁用会修改提示的钩子，包括 `agent_turn_prepare`、`before_prompt_build`、`heartbeat_prompt_contribution`、旧版 `before_agent_start` 中的提示字段，以及 `enqueueNextTurnInjection`。 + +非 Plan 使用者的示例： + +| 插件原型 | 使用的钩子 | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| 审批工作流 | 会话扩展、命令延续、下一轮注入、UI 描述符 | +| 预算/工作区策略门禁 | 受信任工具策略、工具元数据、会话投射 | +| 后台生命周期监视器 | 运行时生命周期清理、智能体事件订阅、会话调度器所有权/清理、心跳提示贡献、UI 描述符 | +| 设置或新手引导向导 | 会话扩展、作用域化命令、Control UI 描述符 | - 保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、 - `update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。对于插件拥有的方法，请优先使用插件专属前缀。 + 保留的核心管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件试图为其分配更窄的 Gateway 网关方法作用域也是如此。对于插件拥有的方法，优先使用插件特定前缀。 - 当内置插件需要在工具执行后、运行时将结果反馈给模型之前重写工具结果时，可以使用 `api.registerAgentToolResultMiddleware(...)`。这是一个受信任、与运行时无关的 seam，适用于 tokenjuice 这类异步输出归约器。 + 当内置插件需要在工具执行后、运行时将该结果反馈给模型之前重写工具结果时，可以使用 `api.registerAgentToolResultMiddleware(...)`。这是用于异步输出归约器（如 tokenjuice）的受信任、运行时中立 seam。 -内置插件必须为每个目标运行时声明 `contracts.agentToolResultMiddleware`，例如 `["pi", "codex"]`。外部插件 -不能注册此中间件；对于不需要模型前工具结果时序的工作，请继续使用普通的 OpenClaw 插件钩子。旧的仅 Pi 可用的嵌入式扩展工厂注册路径已被移除。 +内置插件必须为每个目标运行时声明 `contracts.agentToolResultMiddleware`，例如 `["pi", "codex"]`。外部插件不能注册此中间件；对于不需要模型前工具结果时机的工作，请继续使用普通的 OpenClaw 插件钩子。旧的仅限 Pi 的嵌入式扩展工厂注册路径已被移除。 ### Gateway 网关发现注册 -`api.registerGatewayDiscoveryService(...)` 允许插件在本地发现传输（例如 mDNS/Bonjour）上广播活跃的 Gateway 网关。启用本地发现时，OpenClaw 会在 Gateway 网关启动期间调用该服务，传入当前 Gateway 网关端口和非敏感 TXT 提示数据，并在 Gateway 网关关闭期间调用返回的 `stop` 处理器。 +`api.registerGatewayDiscoveryService(...)` 允许插件通过本地发现传输协议（例如 mDNS/Bonjour）广播活动中的 Gateway 网关。当启用本地设备发现时，OpenClaw 会在 Gateway 网关启动期间调用该服务，传入当前 Gateway 网关端口和非机密 TXT 提示数据，并在 Gateway 网关关闭期间调用返回的 `stop` 处理器。 ```typescript api.registerGatewayDiscoveryService({ @@ -134,16 +161,16 @@ api.registerGatewayDiscoveryService({ }); ``` -Gateway 网关发现插件不得将广播的 TXT 值视为密钥或认证信息。设备发现只是路由提示；Gateway 网关认证和 TLS pinning 仍然负责信任机制。 +Gateway 网关发现插件不得将广播的 TXT 值视为机密信息或身份验证手段。设备发现只是路由提示；信任仍由 Gateway 网关认证和 TLS 固定负责。 ### CLI 注册元数据 `api.registerCli(registrar, opts?)` 接受两类顶层元数据： - `commands`：由 registrar 拥有的显式命令根 -- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析期命令描述符 +- `descriptors`：在解析阶段使用的命令描述符，用于根 CLI 帮助、路由和延迟插件 CLI 注册 -如果你希望插件命令在普通根 CLI 路径中保持延迟加载，请提供 `descriptors`，覆盖该 registrar 暴露的每个顶层命令根。 +如果你希望插件命令在正常的根 CLI 路径中保持延迟加载，请提供 `descriptors`，覆盖该 registrar 暴露的每个顶层命令根。 ```typescript api.registerCli( @@ -155,7 +182,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "管理 Matrix 账户、验证、设备和个人资料状态", + description: "Manage Matrix accounts, verification, devices, and profile state", hasSubcommands: true, }, ], @@ -163,113 +190,106 @@ api.registerCli( ); ``` -仅在你不需要延迟根 CLI 注册时，才单独使用 `commands`。这种预加载兼容路径仍受支持，但它不会安装由 descriptor 支持的占位符，以进行解析期延迟加载。 +只有在你不需要延迟根 CLI 注册时，才单独使用 `commands`。这种急切兼容路径仍然受支持，但它不会安装由 descriptor 支持的占位符来实现解析时的延迟加载。 ### CLI 后端注册 -`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（如 `codex-cli`）的默认配置。 +`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（例如 `codex-cli`）的默认配置。 -- 后端 `id` 会成为模型引用中的 provider 前缀，例如 `codex-cli/gpt-5`。 +- 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。 - 后端 `config` 使用与 `agents.defaults.cliBackends.` 相同的结构。 -- 用户配置仍然优先。OpenClaw 会先将 `agents.defaults.cliBackends.` 合并到插件默认值之上，然后再运行 CLI。 -- 当后端在合并后需要做兼容性重写时，使用 `normalizeConfig`（例如标准化旧版 flag 结构）。 +- 用户配置仍然优先。OpenClaw 会在运行 CLI 之前，将 `agents.defaults.cliBackends.` 合并到插件默认值之上。 +- 当后端在合并后需要兼容性重写时，使用 `normalizeConfig`（例如规范化旧的 flag 形式）。 ### 独占槽位 -| 方法 | 注册内容 | -| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | 上下文引擎（同一时间只激活一个）。`assemble()` 回调会收到 `availableTools` 和 `citationsMode`，这样引擎就能定制提示词附加内容。 | -| `api.registerMemoryCapability(capability)` | 统一 memory 能力 | -| `api.registerMemoryPromptSection(builder)` | Memory 提示词区段构建器 | -| `api.registerMemoryFlushPlan(resolver)` | Memory 刷新计划解析器 | -| `api.registerMemoryRuntime(runtime)` | Memory 运行时适配器 | +| Method | 它注册的内容 | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只能有一个处于激活状态）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便引擎可据此定制提示附加内容。 | +| `api.registerMemoryCapability(capability)` | 统一记忆能力 | +| `api.registerMemoryPromptSection(builder)` | 记忆提示区段构建器 | +| `api.registerMemoryFlushPlan(resolver)` | 记忆刷新计划解析器 | +| `api.registerMemoryRuntime(runtime)` | 记忆运行时适配器 | -### Memory 嵌入适配器 +### 记忆嵌入适配器 -| 方法 | 注册内容 | -| ---------------------------------------------- | --------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | 面向当前插件的 Memory 嵌入适配器 | +| Method | 它注册的内容 | +| ---------------------------------------------- | ------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | 当前活动插件的记忆嵌入适配器 | -- `registerMemoryCapability` 是首选的独占 memory 插件 API。 -- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`，这样配套插件就能通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的 memory artifact，而不必深入某个特定 memory 插件的私有布局。 -- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占 memory 插件 API。 -- `registerMemoryEmbeddingProvider` 允许活跃的 memory 插件注册一个或多个嵌入适配器 id（例如 `openai`、`gemini` 或插件自定义 id）。 -- 用户配置（例如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会根据这些已注册的适配器 id 进行解析。 +- `registerMemoryCapability` 是首选的独占记忆插件 API。 +- `registerMemoryCapability` 还可以暴露 `publicArtifacts.listArtifacts(...)`，这样配套插件就能通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的记忆工件，而不必深入某个特定记忆插件的私有布局。 +- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占记忆插件 API。 +- `registerMemoryEmbeddingProvider` 允许活动记忆插件注册一个或多个嵌入适配器 id（例如 `openai`、`gemini` 或自定义的插件定义 id）。 +- 用户配置（如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会根据这些已注册的适配器 id 进行解析。 -### 事件和生命周期 +### 事件与生命周期 -| 方法 | 作用 | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | 类型化生命周期钩子 | -| `api.onConversationBindingResolved(handler)` | 会话绑定回调 | +| Method | 它的作用 | +| -------------------------------------------- | ------------------------ | +| `api.on(hookName, handler, opts?)` | 类型化生命周期钩子 | +| `api.onConversationBindingResolved(handler)` | 会话绑定回调 | -示例、常见钩子名称和守卫语义，参见[插件钩子](/zh-CN/plugins/hooks)。 +示例、常见钩子名称和守卫语义，请参阅 [插件钩子](/zh-CN/plugins/hooks)。 ### 钩子决策语义 -- `before_tool_call`：返回 `{ block: true }` 是终止性决定。一旦任意处理器设置了它，就会跳过更低优先级的处理器。 -- `before_tool_call`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。 -- `before_install`：返回 `{ block: true }` 是终止性决定。一旦任意处理器设置了它，就会跳过更低优先级的处理器。 -- `before_install`：返回 `{ block: false }` 会被视为未作决定（与省略 `block` 相同），而不是覆盖。 -- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性决定。一旦任意处理器声明已处理分发，就会跳过更低优先级的处理器以及默认模型分发路径。 -- `message_sending`：返回 `{ cancel: true }` 是终止性决定。一旦任意处理器设置了它，就会跳过更低优先级的处理器。 -- `message_sending`：返回 `{ cancel: false }` 会被视为未作决定（与省略 `cancel` 相同），而不是覆盖。 -- `message_received`：当你需要入站线程/话题路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道专属扩展信息。 -- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，再回退到渠道专属的 `metadata`。 -- `gateway_start`：对于 Gateway 网关拥有的启动状态，请使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()`，而不要依赖内部 `gateway:startup` 钩子。 +- `before_tool_call`：返回 `{ block: true }` 表示终止。一旦任意处理器设置了它，就会跳过优先级更低的处理器。 +- `before_tool_call`：返回 `{ block: false }` 会被视为没有做出决定（等同于省略 `block`），而不是覆盖。 +- `before_install`：返回 `{ block: true }` 表示终止。一旦任意处理器设置了它，就会跳过优先级更低的处理器。 +- `before_install`：返回 `{ block: false }` 会被视为没有做出决定（等同于省略 `block`），而不是覆盖。 +- `reply_dispatch`：返回 `{ handled: true, ... }` 表示终止。一旦任意处理器声明已处理分发，就会跳过优先级更低的处理器以及默认的模型分发路径。 +- `message_sending`：返回 `{ cancel: true }` 表示终止。一旦任意处理器设置了它，就会跳过优先级更低的处理器。 +- `message_sending`：返回 `{ cancel: false }` 会被视为没有做出决定（等同于省略 `cancel`），而不是覆盖。 +- `message_received`：当你需要入站线程/话题路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的附加信息。 +- `message_sending`：请先使用类型化的 `replyToId` / `threadId` 路由字段，再回退到渠道特定的 `metadata`。 +- `gateway_start`：请使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()` 来获取 Gateway 网关拥有的启动状态，而不要依赖内部的 `gateway:startup` 钩子。 ### API 对象字段 -| 字段 | 类型 | 描述 | -| ------------------------ | ------------------------- | ---------------------------------------------------------------------------------------- | -| `api.id` | `string` | 插件 id | -| `api.name` | `string` | 显示名称 | -| `api.version` | `string?` | 插件版本（可选） | -| `api.description` | `string?` | 插件描述（可选） | -| `api.source` | `string` | 插件源路径 | -| `api.rootDir` | `string?` | 插件根目录（可选） | -| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活跃的内存中运行时快照） | -| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件专属配置 | -| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | 作用域日志记录器（`debug`、`info`、`warn`、`error`） | -| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是完整入口启动/设置前的轻量级窗口 | -| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | +| Field | Type | 描述 | +| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- | +| `api.id` | `string` | 插件 id | +| `api.name` | `string` | 显示名称 | +| `api.version` | `string?` | 插件版本（可选） | +| `api.description` | `string?` | 插件描述（可选） | +| `api.source` | `string` | 插件源路径 | +| `api.rootDir` | `string?` | 插件根目录（可选） | +| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动的内存中运行时快照） | +| `api.pluginConfig` | `Record` | 来自 `plugins.entries..config` 的插件特定配置 | +| `api.runtime` | `PluginRuntime` | [运行时辅助函数](/zh-CN/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | 有作用域的日志记录器（`debug`、`info`、`warn`、`error`） | +| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是轻量级的完整入口点前启动/设置窗口 | +| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 | ## 内部模块约定 -在你的插件内部，使用本地 barrel 文件进行内部导入： +在你的插件内部，请使用本地 barrel 文件进行内部导入： ``` my-plugin/ api.ts # 面向外部使用方的公共导出 - runtime-api.ts # 仅供内部使用的运行时导出 + runtime-api.ts # 仅限内部使用的运行时导出 index.ts # 插件入口点 - setup-entry.ts # 仅设置使用的轻量入口（可选） + setup-entry.ts # 仅用于轻量设置的入口点（可选） ``` - 不要在生产代码中通过 `openclaw/plugin-sdk/` - 导入你自己的插件。内部导入应通过 `./api.ts` 或 - `./runtime-api.ts`。SDK 路径仅是外部契约。 + 永远不要在生产代码中通过 `openclaw/plugin-sdk/` 导入你自己的插件。 + 请通过 `./api.ts` 或 `./runtime-api.ts` 进行内部导入。SDK 路径仅是对外契约。 -通过 facade 加载的内置插件公共 surface（`api.ts`、`runtime-api.ts`、 -`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）会在 OpenClaw 已运行时优先使用活跃的运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上已解析的配置文件。 +由 facade 加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）在 OpenClaw 已经运行时，会优先使用活动运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上已解析的配置文件。 -当某个辅助函数明确属于 provider 专属，且暂时还不适合放入通用 SDK 子路径时，provider 插件可以暴露一个狭窄的插件本地契约 barrel。内置示例： +提供商插件可以暴露一个狭义的插件本地契约 barrel，用于那些有意设计为提供商特定、且暂时不属于通用 SDK 子路径的辅助函数。内置示例： -- **Anthropic**：公共 `api.ts` / `contract-api.ts` seam，用于 Claude - beta-header 和 `service_tier` 流辅助函数。 -- **`@openclaw/openai-provider`**：`api.ts` 导出 provider 构建器、 - 默认模型辅助函数和实时 provider 构建器。 -- **`@openclaw/openrouter-provider`**：`api.ts` 导出 provider 构建器 - 以及新手引导/配置辅助函数。 +- **Anthropic**：公共 `api.ts` / `contract-api.ts` seam，用于 Claude beta-header 和 `service_tier` 流辅助函数。 +- **`@openclaw/openai-provider`**：`api.ts` 导出提供商构建器、默认模型辅助函数和实时提供商构建器。 +- **`@openclaw/openrouter-provider`**：`api.ts` 导出提供商构建器，以及新手引导/配置辅助函数。 - 扩展生产代码也应避免导入 `openclaw/plugin-sdk/`。 - 如果某个辅助函数确实需要共享，请将它提升到中立的 SDK 子路径， - 例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他 - 面向能力的 surface，而不是把两个插件耦合在一起。 + 扩展生产代码同样应避免导入 `openclaw/plugin-sdk/`。 + 如果某个辅助函数确实是共享的，应将其提升为中立的 SDK 子路径，例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared` 或其他面向能力的表面，而不是让两个插件彼此耦合。 ## 相关内容 @@ -288,9 +308,9 @@ my-plugin/ 测试工具和 lint 规则。 - 从已弃用 surface 迁移。 + 从已弃用表面迁移。 - 深入的架构和能力模型。 + 深入了解架构和能力模型。