diff --git a/docs/zh-CN/plugins/sdk-runtime.md b/docs/zh-CN/plugins/sdk-runtime.md index 5dadf2b12..ea083982a 100644 --- a/docs/zh-CN/plugins/sdk-runtime.md +++ b/docs/zh-CN/plugins/sdk-runtime.md @@ -1,28 +1,28 @@ --- read_when: - 你需要从插件调用核心辅助函数（TTS、STT、图像生成、Web 搜索、子智能体、节点） - - 你想了解 api.runtime 公开了什么 + - 你想了解 api.runtime 暴露了什么 - 你正在从插件代码访问配置、智能体或媒体辅助工具 sidebarTitle: Runtime helpers summary: api.runtime -- 可供插件使用的注入式运行时辅助工具 -title: 插件运行时辅助函数 +title: 插件运行时辅助工具 x-i18n: - generated_at: "2026-05-02T13:56:43Z" + generated_at: "2026-05-04T08:24:36Z" model: gpt-5.5 provider: openai - source_hash: 26df37a2ad0dcd29648e382eb579b6892068af4dea1c47460cfd379458a8081c + source_hash: c968f30052ecba4359bdaa9b1c640c1220268933ce01ccef06bcade225b50b7d source_path: plugins/sdk-runtime.md workflow: 16 --- -`api.runtime` 对象的参考文档，该对象会在注册期间注入到每个插件中。使用这些辅助函数，而不是直接导入主机内部实现。 +Reference for the `api.runtime` object injected into every plugin during registration. Use these helpers instead of importing host internals directly. - 渠道插件的分步指南，会在上下文中使用这些辅助函数。 + Step-by-step guide that uses these helpers in context for channel plugins. - 提供商插件的分步指南，会在上下文中使用这些辅助函数。 + Step-by-step guide that uses these helpers in context for provider plugins. @@ -32,39 +32,40 @@ register(api) { } ``` -## 配置加载和写入 +## Config Loading And Writes -优先使用已经传入当前活跃调用路径的配置，例如注册期间的 `api.config`，或渠道/提供商回调中的 `cfg` 参数。这样可以让同一个进程快照贯穿整个工作流，而不是在热路径上重新解析配置。 +Prefer config that was already passed into the active call path, for example `api.config` during registration or a `cfg` argument on channel/provider callbacks. This keeps one process snapshot flowing through the work instead of reparsing config on hot paths. -仅当长生命周期处理程序需要当前进程快照，且没有配置传入该函数时，才使用 `api.runtime.config.current()`。返回值是只读的；编辑前请克隆，或使用变更辅助函数。 +Use `api.runtime.config.current()` only when a long-lived handler needs the current process snapshot and no config was passed to that function. The returned value is readonly; clone or use a mutation helper before editing. -工具工厂会收到 `ctx.runtimeConfig` 和 `ctx.getRuntimeConfig()`。当工具定义创建后配置可能发生变化时，请在长生命周期工具的 `execute` 回调中使用该 getter。 +Tool factories receive `ctx.runtimeConfig` plus `ctx.getRuntimeConfig()`. Use the getter inside a long-lived tool's `execute` callback when config can change after the tool definition was created. -使用 `api.runtime.config.mutateConfigFile(...)` 或 `api.runtime.config.replaceConfigFile(...)` 持久化更改。每次写入都必须选择一个显式的 `afterWrite` 策略： +Persist changes with `api.runtime.config.mutateConfigFile(...)` or `api.runtime.config.replaceConfigFile(...)`. Each write must choose an explicit `afterWrite` policy: -- `afterWrite: { mode: "auto" }` 让 Gateway 网关重载规划器决定。 -- `afterWrite: { mode: "restart", reason: "..." }` 会在写入方知道热重载不安全时强制干净重启。 -- `afterWrite: { mode: "none", reason: "..." }` 仅在调用方拥有后续处理时，才抑制自动重载/重启。 +- `afterWrite: { mode: "auto" }` lets the gateway reload planner decide. +- `afterWrite: { mode: "restart", reason: "..." }` forces a clean restart when the writer knows hot reload is unsafe. +- `afterWrite: { mode: "none", reason: "..." }` suppresses automatic reload/restart only when the caller owns the follow-up. -变更辅助函数会返回 `afterWrite` 以及一个类型化的 `followUp` 摘要，因此调用方可以记录或测试自己是否请求了重启。Gateway 网关仍然负责决定实际何时重启。 +The mutation helpers return `afterWrite` plus a typed `followUp` summary so callers can log or test whether they requested a restart. The gateway still owns when that restart actually happens. -`api.runtime.config.loadConfig()` 和 `api.runtime.config.writeConfigFile(...)` 是 `runtime-config-load-write` 下已弃用的兼容辅助函数。它们会在运行时警告一次，并在迁移窗口期间继续供旧的外部插件使用。内置插件不得使用它们；如果插件代码调用这些辅助函数，或从插件 SDK 子路径导入这些辅助函数，配置边界守卫会失败。 +`api.runtime.config.loadConfig()` and `api.runtime.config.writeConfigFile(...)` are deprecated compatibility helpers under `runtime-config-load-write`. They warn once at runtime, and remain available for old external plugins during the migration window. Bundled plugins must not use them; the config boundary guards fail if plugin code calls them or imports those helpers from plugin SDK subpaths. -对于直接 SDK 导入，请使用聚焦的配置子路径，而不是宽泛的 -`openclaw/plugin-sdk/config-runtime` 兼容 barrel：`config-types` 用于 -类型，`plugin-config-runtime` 用于已加载配置断言和插件 -入口查找，`runtime-config-snapshot` 用于当前进程快照，`config-mutation` 用于写入。内置插件测试应直接 mock 这些聚焦的 -子路径，而不是 mock 宽泛的兼容 barrel。 +For direct SDK imports, use the focused config subpaths instead of the broad +`openclaw/plugin-sdk/config-runtime` compatibility barrel: `config-types` for +types, `plugin-config-runtime` for already-loaded config assertions and plugin +entry lookup, `runtime-config-snapshot` for current process snapshots, and +`config-mutation` for writes. Bundled plugin tests should mock these focused +subpaths directly instead of mocking the broad compatibility barrel. -OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关或进程边界加载一次配置，然后将该值继续传递下去。成功的变更写入会刷新进程运行时快照并推进其内部修订版本；长生命周期缓存应基于运行时拥有的缓存键，而不是在本地序列化配置。长生命周期运行时模块对环境中的 `loadConfig()` 调用实行零容忍扫描；请使用传入的 `cfg`、请求的 `context.getRuntimeConfig()`，或在显式进程边界使用 `getRuntimeConfig()`。 +Internal OpenClaw runtime code has the same direction: load config once at the CLI, gateway, or process boundary, then pass that value through. Successful mutation writes refresh the process runtime snapshot and advance its internal revision; long-lived caches should key off the runtime-owned cache key instead of serializing config locally. Long-lived runtime modules have a zero-tolerance scanner for ambient `loadConfig()` calls; use a passed `cfg`, a request `context.getRuntimeConfig()`, or `getRuntimeConfig()` at an explicit process boundary. -提供商和渠道执行路径必须使用活跃的运行时配置快照，而不是用于配置读回或编辑的文件快照。文件快照会保留源值，例如供 UI 和写入使用的 SecretRef 标记；提供商回调需要的是已解析的运行时视图。当某个辅助函数可能收到活跃源快照或活跃运行时快照时，请先通过 `selectApplicableRuntimeConfig()` 再读取凭证。 +Provider and channel execution paths must use the active runtime config snapshot, not a file snapshot returned for config readback or editing. File snapshots preserve source values such as SecretRef markers for UI and writes; provider callbacks need the resolved runtime view. When a helper may be called with either the active source snapshot or the active runtime snapshot, route through `selectApplicableRuntimeConfig()` before reading credentials. -## 运行时命名空间 +## Runtime namespaces - 智能体身份、目录和会话管理。 + Agent identity, directories, and session management. ```typescript // Resolve the agent's working directory @@ -108,15 +109,15 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); ``` - `runEmbeddedAgent(...)` 是从插件代码启动普通 OpenClaw 智能体轮次的中立辅助函数。它使用与渠道触发回复相同的提供商/模型解析和 agent harness 选择。 + `runEmbeddedAgent(...)` is the neutral helper for starting a normal OpenClaw agent turn from plugin code. It uses the same provider/model resolution and agent-harness selection as channel-triggered replies. - `runEmbeddedPiAgent(...)` 保留为兼容别名。 + `runEmbeddedPiAgent(...)` remains as a compatibility alias. - `resolveThinkingPolicy(...)` 返回提供商/模型支持的思考等级和可选默认值。提供商插件通过其思考钩子拥有模型特定的配置文件，因此工具插件应调用此运行时辅助函数，而不是导入或重复维护提供商列表。 + `resolveThinkingPolicy(...)` returns the provider/model's supported thinking levels and optional default. Provider plugins own the model-specific profile through their thinking hooks, so tool plugins should call this runtime helper instead of importing or duplicating provider lists. - `normalizeThinkingLevel(...)` 会将 `on`、`x-high` 或 `extra high` 等用户文本转换为规范存储等级，然后再与解析出的策略比对。 + `normalizeThinkingLevel(...)` converts user text such as `on`, `x-high`, or `extra high` to the canonical stored level before checking it against the resolved policy. - **会话存储辅助函数** 位于 `api.runtime.agent.session` 下： + **Session store helpers** are under `api.runtime.agent.session`: ```typescript const storePath = api.runtime.agent.session.resolveStorePath(cfg); @@ -128,11 +129,11 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId); ``` - 对运行时写入，优先使用 `updateSessionStore(...)` 或 `updateSessionStoreEntry(...)`。它们会通过 Gateway 网关拥有的会话存储写入器执行，保留并发更新，并复用热缓存。`saveSessionStore(...)` 会继续作为兼容和离线维护式重写用途提供。 + Prefer `updateSessionStore(...)` or `updateSessionStoreEntry(...)` for runtime writes. They route through the Gateway-owned session-store writer, preserve concurrent updates, and reuse the hot cache. `saveSessionStore(...)` remains available for compatibility and offline maintenance-style rewrites. - 默认模型和提供商常量： + Default model and provider constants: ```typescript const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6" @@ -141,7 +142,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 - 启动和管理后台子智能体运行。 + Launch and manage background subagent runs. ```typescript // Start a subagent run @@ -169,14 +170,14 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 ``` - 模型覆盖（`provider`/`model`）需要操作者在配置中通过 `plugins.entries..subagent.allowModelOverride: true` 选择启用。不受信任的插件仍然可以运行子智能体，但覆盖请求会被拒绝。 + Model overrides (`provider`/`model`) require operator opt-in via `plugins.entries..subagent.allowModelOverride: true` in config. Untrusted plugins can still run subagents, but override requests are rejected. - `deleteSession(...)` 可以删除同一插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作者会话仍然需要管理员范围的 Gateway 网关请求。 + `deleteSession(...)` can delete sessions created by the same plugin through `api.runtime.subagent.run(...)`. Deleting arbitrary user or operator sessions still requires an admin-scoped Gateway request. - 列出已连接节点，并从 Gateway 网关加载的插件代码或插件 CLI 命令调用节点宿主命令。当插件拥有配对设备上的本地工作时使用它，例如另一台 Mac 上的浏览器或音频桥接。 + List connected nodes and invoke a node-host command from Gateway-loaded plugin code or from plugin CLI commands. Use this when a plugin owns local work on a paired device, for example a browser or audio bridge on another Mac. ```typescript const { nodes } = await api.runtime.nodes.list({ connected: true }); @@ -189,13 +190,13 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); ``` - 在 Gateway 网关内部，此运行时位于进程内。在插件 CLI 命令中，它会通过 RPC 调用已配置的 Gateway 网关，因此 `openclaw googlemeet recover-tab` 等命令可以从终端检查配对节点。节点命令仍然会经过正常的 Gateway 网关节点配对、命令 allowlist、插件节点调用策略和节点本地命令处理。 + Inside the Gateway this runtime is in-process. In plugin CLI commands it calls the configured Gateway over RPC, so commands such as `openclaw googlemeet recover-tab` can inspect paired nodes from the terminal. Node commands still go through normal Gateway node pairing, command allowlists, plugin node-invoke policies, and node-local command handling. - 暴露危险节点宿主命令的插件应使用 `api.registerNodeInvokePolicy(...)` 注册节点调用策略。该策略会在 Gateway 网关中运行，位于命令 allowlist 检查之后、命令转发到节点之前，因此直接 `node.invoke` 调用和更高层级的插件工具会共享同一执行控制路径。 + Plugins that expose dangerous node-host commands should register a node-invoke policy with `api.registerNodeInvokePolicy(...)`. The policy runs in the Gateway after command allowlist checks and before the command is forwarded to the node, so direct `node.invoke` calls and higher-level plugin tools share the same enforcement path. - 将 Task Flow 运行时绑定到现有 OpenClaw 会话键或受信任的工具上下文，然后无需在每次调用时传入所有者即可创建和管理 Task Flow。 + Bind a Task Flow runtime to an existing OpenClaw session key or trusted tool context, then create and manage Task Flows without passing an owner on every call. ```typescript const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx); @@ -222,11 +223,11 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); ``` - 当你已经从自己的绑定层获得受信任的 OpenClaw 会话键时，请使用 `bindSession({ sessionKey, requesterOrigin })`。不要从原始用户输入进行绑定。 + Use `bindSession({ sessionKey, requesterOrigin })` when you already have a trusted OpenClaw session key from your own binding layer. Do not bind from raw user input. - 文本转语音合成。 + Text-to-speech synthesis. ```typescript // Standard TTS @@ -248,11 +249,11 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); ``` - 使用核心 `messages.tts` 配置和提供商选择。返回 PCM 音频缓冲区 + 采样率。 + Uses core `messages.tts` configuration and provider selection. Returns PCM audio buffer + sample rate. - 图像、音频和视频分析。 + Image, audio, and video analysis. ```typescript // Describe an image @@ -341,7 +342,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 - 当前运行时配置快照，以及事务式配置写入。优先使用已传入当前活动调用路径的配置；只有当处理程序需要直接访问进程快照时，才使用 `current()`。 + 当前运行时配置快照和事务式配置写入。优先使用已传入当前活动调用路径的配置；只有当处理程序需要直接访问进程快照时，才使用 `current()`。 ```typescript const cfg = api.runtime.config.current(); @@ -353,9 +354,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); ``` - `mutateConfigFile(...)` 和 `replaceConfigFile(...)` 会返回一个 `followUp` - 值，例如 `{ mode: "restart", requiresRestart: true, reason }`， - 它会记录写入方的意图，同时不会从 Gateway 网关手中接管重启控制。 + `mutateConfigFile(...)` 和 `replaceConfigFile(...)` 会返回一个 `followUp` 值，例如 `{ mode: "restart", requiresRestart: true, reason }`，它会记录写入方意图，而不会从 Gateway 网关手中接管重启控制权。 @@ -409,7 +408,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 - 状态目录解析，以及基于 SQLite 的键值存储。 + 状态目录解析和基于 SQLite 的键值存储。 ```typescript const stateDir = api.runtime.state.resolveStateDir(process.env); @@ -420,15 +419,16 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); await store.register("key-1", { value: "hello" }); + const claimed = await store.registerIfAbsent("dedupe-key", { value: "first" }); const value = await store.lookup("key-1"); await store.consume("key-1"); await store.clear(); ``` - 键值存储会在重启后保留，并按运行时绑定的插件 id 隔离。限制：每个命名空间 `maxEntries`、每个插件 1,000 个存活行、JSON 值小于 64KB，以及可选的 TTL 过期。 + 键值存储会在重启后保留，并按运行时绑定的插件 ID 隔离。使用 `registerIfAbsent(...)` 进行原子去重声明：当键缺失或已过期并成功注册时，它返回 `true`；当已有有效值存在时，它返回 `false`，且不会覆盖该值、创建时间或 TTL。限制：每个命名空间 `maxEntries`、每个插件 1,000 个有效行、64KB 以下的 JSON 值，以及可选的 TTL 过期。 - 此版本仅限内置插件。 + 此版本仅支持内置插件。 @@ -443,9 +443,9 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 - 渠道专用运行时辅助工具（加载渠道插件时可用）。 + 渠道特定的运行时辅助工具（加载渠道插件时可用）。 - `api.runtime.channel.mentions` 是使用运行时注入的内置渠道插件共享的入站提及策略表面： + `api.runtime.channel.mentions` 是使用运行时注入的内置渠道插件的共享入站提及策略界面： ```typescript const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, { @@ -480,7 +480,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 - `implicitMentionKindWhen` - `resolveInboundMentionDecision` - `api.runtime.channel.mentions` 有意不暴露旧的 `resolveMentionGating*` 兼容性辅助工具。优先使用规范化的 `{ facts, policy }` 路径。 + `api.runtime.channel.mentions` 有意不暴露较旧的 `resolveMentionGating*` 兼容性辅助工具。优先使用标准化的 `{ facts, policy }` 路径。 @@ -490,7 +490,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 使用 `createPluginRuntimeStore` 存储运行时引用，以便在 `register` 回调之外使用： - + ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store"; @@ -502,7 +502,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 ``` - + ```typescript export default defineChannelPluginEntry({ id: "my-plugin", @@ -513,7 +513,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); ``` - + ```typescript export function getRuntime() { return store.getRuntime(); // throws if not initialized @@ -528,7 +528,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 -运行时存储身份优先使用 `pluginId`。较低层级的 `key` 形式适用于少见情况，即一个插件有意需要多个运行时槽位。 +运行时存储标识优先使用 `pluginId`。较底层的 `key` 形式适用于少见情况，即一个插件有意需要多个运行时槽位。 ## 其他顶层 `api` 字段 @@ -536,7 +536,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 除 `api.runtime` 外，API 对象还提供： - 插件 id。 + 插件 ID。 插件显示名称。 @@ -545,13 +545,13 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 当前配置快照（可用时为活动的内存中运行时快照）。 - 来自 `plugins.entries..config` 的插件专用配置。 + 来自 `plugins.entries..config` 的插件特定配置。 作用域日志记录器（`debug`、`info`、`warn`、`error`）。 - 当前加载模式；`"setup-runtime"` 是轻量级的完整入口前启动/设置窗口。 + 当前加载模式；`"setup-runtime"` 是轻量级的完整入口启动前/设置窗口。 解析相对于插件根目录的路径。