From 554ee57efadd7d4c368454634deefe7546a905e6 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 29 Apr 2026 13:07:06 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/plugins/sdk-runtime.md | 119 ++++++++++++++++++------------ 1 file changed, 70 insertions(+), 49 deletions(-) diff --git a/docs/zh-CN/plugins/sdk-runtime.md b/docs/zh-CN/plugins/sdk-runtime.md index 44320c465..37e0bae86 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-04-28T11:59:59Z" + generated_at: "2026-04-29T13:06:12Z" model: gpt-5.5 provider: openai - source_hash: d332e9ab4a163a55b7edaefc420d845cfda8486646e13a758ec3133097c17be1 + source_hash: 399e2433e272fe30e7451690a64826df8e30a064269b8d9a7aa2dd2b0c5688b8 source_path: plugins/sdk-runtime.md workflow: 16 --- -注入到每个插件注册过程中的 `api.runtime` 对象参考。请使用这些辅助函数，而不是直接导入宿主内部机制。 +每个插件注册期间都会注入 `api.runtime` 对象，这是其参考说明。请使用这些辅助工具，而不是直接导入主机内部机制。 - 面向渠道插件的分步指南，会在上下文中使用这些辅助函数。 + 分步指南，展示如何在渠道插件的上下文中使用这些辅助工具。 - 面向提供商插件的分步指南，会在上下文中使用这些辅助函数。 + 分步指南，展示如何在提供商插件的上下文中使用这些辅助工具。 @@ -32,29 +32,34 @@ register(api) { } ``` -## 配置加载和写入 +## 配置加载与写入 -优先使用已经传入当前活动调用路径的配置，例如注册过程中的 `api.config`，或渠道/提供商回调中的 `cfg` 参数。这样可以让同一个进程快照贯穿整个工作流程，而不是在热路径上重新解析配置。 +优先使用已经传入当前活动调用路径的配置，例如注册期间的 `api.config`，或渠道/提供商回调中的 `cfg` 参数。这样可以让一个进程快照贯穿整个工作流程，而不是在热路径上重新解析配置。 -仅当长生命周期处理程序需要当前进程快照，并且没有配置传入该函数时，才使用 `api.runtime.config.current()`。返回值是只读的；编辑前请先克隆，或使用变更辅助函数。 +只有当长期存在的处理程序需要当前进程快照，且没有配置传给该函数时，才使用 `api.runtime.config.current()`。返回值是只读的；编辑前请先克隆，或使用变更辅助工具。 -工具工厂会收到 `ctx.runtimeConfig` 和 `ctx.getRuntimeConfig()`。当工具定义创建后配置可能发生变化时，请在长生命周期工具的 `execute` 回调内使用这个 getter。 +工具工厂会收到 `ctx.runtimeConfig` 和 `ctx.getRuntimeConfig()`。当配置可能在工具定义创建后发生变化时，请在长期存在的工具 `execute` 回调中使用这个 getter。 -使用 `api.runtime.config.mutateConfigFile(...)` 或 `api.runtime.config.replaceConfigFile(...)` 持久化更改。每次写入都必须选择一个明确的 `afterWrite` 策略： +使用 `api.runtime.config.mutateConfigFile(...)` 或 `api.runtime.config.replaceConfigFile(...)` 持久化更改。每次写入都必须选择显式的 `afterWrite` 策略： -- `afterWrite: { mode: "auto" }` 让 Gateway 网关重新加载规划器决定。 -- `afterWrite: { mode: "restart", reason: "..." }` 在写入方知道热重载不安全时强制干净重启。 -- `afterWrite: { mode: "none", reason: "..." }` 仅当调用方负责后续处理时，才抑制自动重新加载/重启。 +- `afterWrite: { mode: "auto" }` 让 Gateway 网关重载规划器决定。 +- `afterWrite: { mode: "restart", reason: "..." }` 会在写入方知道热重载不安全时强制干净重启。 +- `afterWrite: { mode: "none", reason: "..." }` 仅在调用方负责后续处理时抑制自动重载/重启。 -这些变更辅助函数会返回 `afterWrite` 和一个类型化的 `followUp` 摘要，让调用方可以记录或测试是否请求了重启。Gateway 网关仍然负责决定该重启实际何时发生。 +变更辅助工具会返回 `afterWrite` 以及类型化的 `followUp` 摘要，让调用方可以记录或测试自己是否请求了重启。Gateway 网关仍然负责决定实际何时重启。 -`api.runtime.config.loadConfig()` 和 `api.runtime.config.writeConfigFile(...)` 是 `runtime-config-load-write` 下已弃用的兼容性辅助函数。它们会在运行时警告一次，并且会在迁移窗口期间继续为旧的外部插件提供。内置插件不得使用它们；如果插件代码调用它们，或从插件 SDK 子路径导入这些辅助函数，配置边界守卫会失败。 +`api.runtime.config.loadConfig()` 和 `api.runtime.config.writeConfigFile(...)` 是 `runtime-config-load-write` 下已弃用的兼容性辅助工具。它们会在运行时警告一次，并且在迁移窗口期间仍可供旧的外部插件使用。内置插件不得使用它们；如果插件代码调用它们，或从插件 SDK 子路径导入这些辅助工具，配置边界守卫会失败。 -对于直接 SDK 导入，请使用聚焦的配置子路径，而不是宽泛的 `openclaw/plugin-sdk/config-runtime` 兼容性 barrel：`config-types` 用于类型，`plugin-config-runtime` 用于已加载配置断言和插件入口查找，`runtime-config-snapshot` 用于当前进程快照，`config-mutation` 用于写入。内置插件测试应直接 mock 这些聚焦子路径，而不是 mock 宽泛的兼容性 barrel。 +对于直接 SDK 导入，请使用聚焦的配置子路径，而不是宽泛的 +`openclaw/plugin-sdk/config-runtime` 兼容性 barrel：`config-types` 用于 +类型，`plugin-config-runtime` 用于已加载配置断言和插件 +入口查找，`runtime-config-snapshot` 用于当前进程快照，`config-mutation` +用于写入。内置插件测试应直接 mock 这些聚焦的 +子路径，而不是 mock 宽泛的兼容性 barrel。 -OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关或进程边界加载一次配置，然后将该值传递下去。成功的变更写入会刷新进程运行时快照，并推进其内部修订版本；长生命周期缓存应基于运行时拥有的缓存键，而不是在本地序列化配置。长生命周期运行时模块对环境中的 `loadConfig()` 调用采用零容忍扫描；请使用传入的 `cfg`、请求的 `context.getRuntimeConfig()`，或在明确的进程边界使用 `getRuntimeConfig()`。 +OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关或进程边界加载一次配置，然后传递该值。成功的变更写入会刷新进程运行时快照并推进其内部修订版本；长期存在的缓存应基于运行时拥有的缓存键，而不是在本地序列化配置。长期存在的运行时模块对环境中的 `loadConfig()` 调用执行零容忍扫描；请使用传入的 `cfg`、请求的 `context.getRuntimeConfig()`，或在显式进程边界使用 `getRuntimeConfig()`。 -提供商和渠道执行路径必须使用活动运行时配置快照，而不是为配置回读或编辑返回的文件快照。文件快照会保留 UI 和写入所需的源值，例如 SecretRef 标记；提供商回调需要解析后的运行时视图。当一个辅助函数可能以活动源快照或活动运行时快照调用时，请先通过 `selectApplicableRuntimeConfig()` 再读取凭证。 +提供商和渠道执行路径必须使用活动的运行时配置快照，而不是用于配置读回或编辑的文件快照。文件快照会保留源值，例如 UI 和写入所需的 SecretRef 标记；提供商回调需要已解析的运行时视图。当某个辅助工具可能被传入活动源快照或活动运行时快照时，请在读取凭证前通过 `selectApplicableRuntimeConfig()` 路由。 ## 运行时命名空间 @@ -104,15 +109,15 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); ``` - `runEmbeddedAgent(...)` 是从插件代码启动常规 OpenClaw 智能体轮次的中立辅助函数。它使用与渠道触发回复相同的提供商/模型解析和 agent-harness 选择。 + `runEmbeddedAgent(...)` 是从插件代码启动普通 OpenClaw 智能体轮次的中立辅助工具。它使用与渠道触发回复相同的提供商/模型解析和 agent-harness 选择。 - `runEmbeddedPiAgent(...)` 会继续作为兼容性别名保留。 + `runEmbeddedPiAgent(...)` 仍作为兼容性别名保留。 - `resolveThinkingPolicy(...)` 返回提供商/模型支持的思考级别和可选默认值。提供商插件通过它们的 thinking 钩子拥有特定模型的 profile，因此工具插件应调用这个运行时辅助函数，而不是导入或复制提供商列表。 + `resolveThinkingPolicy(...)` 会返回提供商/模型支持的 thinking 级别和可选默认值。提供商插件通过自己的 thinking 钩子拥有模型专属配置文件，因此工具插件应调用这个运行时辅助工具，而不是导入或复制提供商列表。 - `normalizeThinkingLevel(...)` 会在对照解析后的策略检查之前，将 `on`、`x-high` 或 `extra high` 等用户文本转换为规范的存储级别。 + `normalizeThinkingLevel(...)` 会将 `on`、`x-high` 或 `extra high` 等用户文本转换为规范的已存储级别，然后再对照解析后的策略进行检查。 - **会话存储辅助函数**位于 `api.runtime.agent.session` 下： + **会话存储辅助工具** 位于 `api.runtime.agent.session` 下： ```typescript const storePath = api.runtime.agent.session.resolveStorePath(cfg); @@ -132,7 +137,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 - 启动和管理后台子智能体运行。 + 启动并管理后台子智能体运行。 ```typescript // Start a subagent run @@ -163,11 +168,11 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 模型覆盖（`provider`/`model`）需要操作员通过配置中的 `plugins.entries..subagent.allowModelOverride: true` 选择启用。不受信任的插件仍然可以运行子智能体，但覆盖请求会被拒绝。 - `deleteSession(...)` 可以删除同一插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作员会话仍然需要管理员范围的 Gateway 网关请求。 + `deleteSession(...)` 可以删除由同一插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作员会话仍需要管理员范围的 Gateway 网关请求。 - 列出已连接节点，并从 Gateway 网关加载的插件代码或插件 CLI 命令调用节点宿主命令。当插件负责配对设备上的本地工作时使用它，例如另一台 Mac 上的浏览器或音频桥接。 + 列出已连接节点，并从 Gateway 网关加载的插件代码或插件 CLI 命令调用节点托管命令。当插件拥有配对设备上的本地工作时使用它，例如另一台 Mac 上的浏览器或音频桥接。 ```typescript const { nodes } = await api.runtime.nodes.list({ connected: true }); @@ -180,11 +185,11 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); ``` - 在 Gateway 网关内部，这个运行时处于进程内。在插件 CLI 命令中，它会通过 RPC 调用已配置的 Gateway 网关，因此 `openclaw googlemeet recover-tab` 等命令可以从终端检查配对节点。节点命令仍然会经过正常的 Gateway 网关节点配对、命令允许列表和节点本地命令处理。 + 在 Gateway 网关内部，这个运行时位于进程内。在插件 CLI 命令中，它会通过 RPC 调用已配置的 Gateway 网关，因此 `openclaw googlemeet recover-tab` 等命令可以从终端检查配对节点。节点命令仍会经过正常的 Gateway 网关节点配对、命令允许列表和节点本地命令处理。 - 将 Task Flow 运行时绑定到现有 OpenClaw 会话键或受信任的工具上下文，然后创建和管理 Task Flow，而无需在每次调用时传入 owner。 + 将 Task Flow 运行时绑定到现有 OpenClaw 会话键或受信任的工具上下文，然后创建和管理 Task Flow，而无需在每次调用时传递所有者。 ```typescript const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx); @@ -211,7 +216,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); ``` - 当你已经从自己的绑定层获得受信任的 OpenClaw 会话键时，请使用 `bindSession({ sessionKey, requesterOrigin })`。不要从原始用户输入绑定。 + 当你已经从自己的绑定层获得受信任的 OpenClaw 会话键时，请使用 `bindSession({ sessionKey, requesterOrigin })`。不要从原始用户输入进行绑定。 @@ -271,7 +276,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); ``` - 当没有生成输出时（例如跳过的输入），返回 `{ text: undefined }`。 + 未产生输出时（例如跳过的输入），返回 `{ text: undefined }`。 `api.runtime.stt.transcribeAudioFile(...)` 仍作为 `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容性别名保留。 @@ -305,7 +310,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 - 底层媒体工具。 + 底层媒体实用工具。 ```typescript const webMedia = await api.runtime.media.loadWebMedia(url); @@ -330,7 +335,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 - 当前运行时配置快照和事务式配置写入。优先使用已传入当前活动调用路径的配置；仅当处理程序需要直接读取进程快照时才使用 `current()`。 + 当前运行时配置快照和事务性配置写入。优先使用已经传入活动调用路径的配置；仅在处理器需要直接使用进程快照时才使用 `current()`。 ```typescript const cfg = api.runtime.config.current(); @@ -342,11 +347,11 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); ``` - `mutateConfigFile(...)` 和 `replaceConfigFile(...)` 会返回一个 `followUp` 值，例如 `{ mode: "restart", requiresRestart: true, reason }`，它记录写入方意图，而不会从 Gateway 网关手中接管重启控制权。 + `mutateConfigFile(...)` 和 `replaceConfigFile(...)` 返回一个 `followUp` 值，例如 `{ mode: "restart", requiresRestart: true, reason }`，它会记录写入方意图，而不会从 Gateway 网关手中接管重启控制。 - 系统级工具。 + 系统级实用工具。 ```typescript await api.runtime.system.enqueueSystemEvent(event); @@ -391,12 +396,28 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 - 状态目录解析。 + 状态目录解析和基于 SQLite 的键控存储。 ```typescript - const stateDir = api.runtime.state.resolveStateDir(); + const stateDir = api.runtime.state.resolveStateDir(process.env); + const store = api.runtime.state.openKeyedStore({ + namespace: "my-feature", + maxEntries: 200, + defaultTtlMs: 15 * 60_000, + }); + + await store.register("key-1", { value: "hello" }); + const value = await store.lookup("key-1"); + await store.consume("key-1"); + await store.clear(); ``` + 键控存储会在重启后保留，并按运行时绑定的插件 ID 隔离。限制：每个命名空间 `maxEntries`，每个插件 1,000 行存活记录，JSON 值小于 64KB，以及可选的 TTL 过期。 + + + 此版本仅限内置插件。 + + Memory 工具工厂和 CLI。 @@ -409,9 +430,9 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 - 渠道专用运行时辅助函数（在加载渠道插件时可用）。 + 渠道特定的运行时辅助工具（在加载渠道插件时可用）。 - `api.runtime.channel.mentions` 是使用运行时注入的内置渠道插件共享入站提及策略表面： + `api.runtime.channel.mentions` 是使用运行时注入的内置渠道插件共享的入站提及策略表面： ```typescript const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, { @@ -438,7 +459,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); ``` - 可用的提及辅助函数： + 可用的提及辅助工具： - `buildMentionRegexes` - `matchesMentionPatterns` @@ -446,7 +467,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 - `implicitMentionKindWhen` - `resolveInboundMentionDecision` - `api.runtime.channel.mentions` 有意不暴露较旧的 `resolveMentionGating*` 兼容性辅助函数。优先使用规范化的 `{ facts, policy }` 路径。 + `api.runtime.channel.mentions` 有意不暴露较旧的 `resolveMentionGating*` 兼容性辅助工具。优先使用规范化的 `{ facts, policy }` 路径。 @@ -456,7 +477,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 使用 `createPluginRuntimeStore` 存储运行时引用，以便在 `register` 回调之外使用： - + ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store"; @@ -468,7 +489,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 ``` - + ```typescript export default defineChannelPluginEntry({ id: "my-plugin", @@ -479,7 +500,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 }); ``` - + ```typescript export function getRuntime() { return store.getRuntime(); // throws if not initialized @@ -494,12 +515,12 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 -运行时存储标识优先使用 `pluginId`。较底层的 `key` 形式用于少见场景，即一个插件有意需要多个运行时槽位。 +运行时存储身份优先使用 `pluginId`。较底层的 `key` 形式用于一个插件有意需要多个运行时槽位的少见情况。 ## 其他顶层 `api` 字段 -除了 `api.runtime`，API 对象还提供： +除了 `api.runtime` 之外，API 对象还提供： 插件 ID。 @@ -511,7 +532,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关 当前配置快照（可用时为活动的内存中运行时快照）。 - 来自 `plugins.entries..config` 的插件专用配置。 + 来自 `plugins.entries..config` 的插件特定配置。 作用域日志记录器（`debug`、`info`、`warn`、`error`）。