chore(i18n): refresh zh-CN translations

2026-04-29 13:07:06 +00:00 · 2026-04-29 13:07:06 +00:00 · 554ee57efa
commit 554ee57efa
parent ef8c1d15e9
1 changed files with 70 additions and 49 deletions
--- 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` 对象，这是其参考说明。请使用这些辅助工具，而不是直接导入主机内部机制。

 <CardGroup cols={2}>
  <Card title="渠道插件" href="/zh-CN/plugins/sdk-channel-plugins">
-    面向渠道插件的分步指南，会在上下文中使用这些辅助函数。
+    分步指南，展示如何在渠道插件的上下文中使用这些辅助工具。
  </Card>
  <Card title="提供商插件" href="/zh-CN/plugins/sdk-provider-plugins">
-    面向提供商插件的分步指南，会在上下文中使用这些辅助函数。
+    分步指南，展示如何在提供商插件的上下文中使用这些辅助工具。
  </Card>
 </CardGroup>

@ -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 网关

  </Accordion>
  <Accordion title="api.runtime.subagent">
-    启动和管理后台子智能体运行。
+    启动并管理后台子智能体运行。

    ```typescript
    // Start a subagent run
@ -163,11 +168,11 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    模型覆盖（`provider`/`model`）需要操作员通过配置中的 `plugins.entries.<id>.subagent.allowModelOverride: true` 选择启用。不受信任的插件仍然可以运行子智能体，但覆盖请求会被拒绝。
    </Warning>

-    `deleteSession(...)` 可以删除同一插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作员会话仍然需要管理员范围的 Gateway 网关请求。
+    `deleteSession(...)` 可以删除由同一插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作员会话仍需要管理员范围的 Gateway 网关请求。

  </Accordion>
  <Accordion title="api.runtime.nodes">
-    列出已连接节点，并从 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 网关节点配对、命令允许列表和节点本地命令处理。

  </Accordion>
  <Accordion title="api.runtime.tasks.managedFlows">
-    将 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 })`。不要从原始用户输入进行绑定。

  </Accordion>
  <Accordion title="api.runtime.tts">
@ -271,7 +276,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    });
    ```

-    当没有生成输出时（例如跳过的输入），返回 `{ text: undefined }`。
+    未产生输出时（例如跳过的输入），返回 `{ text: undefined }`。

    <Info>
    `api.runtime.stt.transcribeAudioFile(...)` 仍作为 `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容性别名保留。
@ -305,7 +310,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关

  </Accordion>
  <Accordion title="api.runtime.media">
-    底层媒体工具。
+    底层媒体实用工具。

    ```typescript
    const webMedia = await api.runtime.media.loadWebMedia(url);
@ -330,7 +335,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关

  </Accordion>
  <Accordion title="api.runtime.config">
-    当前运行时配置快照和事务式配置写入。优先使用已传入当前活动调用路径的配置；仅当处理程序需要直接读取进程快照时才使用 `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 网关手中接管重启控制。

  </Accordion>
  <Accordion title="api.runtime.system">
-    系统级工具。
+    系统级实用工具。

    ```typescript
    await api.runtime.system.enqueueSystemEvent(event);
@ -391,12 +396,28 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关

  </Accordion>
  <Accordion title="api.runtime.state">
-    状态目录解析。
+    状态目录解析和基于 SQLite 的键控存储。

    ```typescript
-    const stateDir = api.runtime.state.resolveStateDir();
+    const stateDir = api.runtime.state.resolveStateDir(process.env);
+    const store = api.runtime.state.openKeyedStore<MyRecord>({
+      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 过期。
+
+    <Warning>
+    此版本仅限内置插件。
+    </Warning>
+
  </Accordion>
  <Accordion title="api.runtime.tools">
    Memory 工具工厂和 CLI。
@ -409,9 +430,9 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关

  </Accordion>
  <Accordion title="api.runtime.channel">
-    渠道专用运行时辅助函数（在加载渠道插件时可用）。
+    渠道特定的运行时辅助工具（在加载渠道插件时可用）。

-    `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 }` 路径。

  </Accordion>
 </AccordionGroup>
@ -456,7 +477,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
 使用 `createPluginRuntimeStore` 存储运行时引用，以便在 `register` 回调之外使用：

 <Steps>
-  <Step title="Create the store">
+  <Step title="创建存储">
    ```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 网关
    ```

  </Step>
-  <Step title="Wire into the entry point">
+  <Step title="接入入口点">
    ```typescript
    export default defineChannelPluginEntry({
      id: "my-plugin",
@ -479,7 +500,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
    });
    ```
  </Step>
-  <Step title="Access from other files">
+  <Step title="从其他文件访问">
    ```typescript
    export function getRuntime() {
      return store.getRuntime(); // throws if not initialized
@ -494,12 +515,12 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
 </Steps>

 <Note>
-运行时存储标识优先使用 `pluginId`。较底层的 `key` 形式用于少见场景，即一个插件有意需要多个运行时槽位。
+运行时存储身份优先使用 `pluginId`。较底层的 `key` 形式用于一个插件有意需要多个运行时槽位的少见情况。
 </Note>

 ## 其他顶层 `api` 字段

-除了 `api.runtime`，API 对象还提供：
+除了 `api.runtime` 之外，API 对象还提供：

 <ParamField path="api.id" type="string">
  插件 ID。
@ -511,7 +532,7 @@ OpenClaw 内部运行时代码也遵循同一方向：在 CLI、Gateway 网关
  当前配置快照（可用时为活动的内存中运行时快照）。
 </ParamField>
 <ParamField path="api.pluginConfig" type="Record<string, unknown>">
-  来自 `plugins.entries.<id>.config` 的插件专用配置。
+  来自 `plugins.entries.<id>.config` 的插件特定配置。
 </ParamField>
 <ParamField path="api.logger" type="PluginLogger">
  作用域日志记录器（`debug`、`info`、`warn`、`error`）。