chore(i18n): refresh zh-CN translations

docs/zh-CN/help/index.md

@@ -1,33 +1,45 @@
 ---
 read_when:
-    - 你是新手，想要一份“我该点什么 / 运行什么”的指南
-    - 某些地方出问题了，你想用最快的路径修复它
-summary: 帮助中心：常见修复、安装完整性检查，以及出问题时应查看的位置
+    - 你是新手，想要一份“我该点击/运行什么”的指南
+    - 出了问题，你想要最快的修复路径
+summary: 帮助中心：常见修复、安装完整性检查，以及出现问题时该去哪里查看
 title: 帮助
 x-i18n:
-    generated_at: "2026-04-23T20:51:09Z"
+    generated_at: "2026-04-24T06:58:56Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 22d4649ba47cfbd8ca3e415a1ae99884867ca80c44cbe39f8a30b29d64e95a05
+    source_hash: f4ea596c304ceee2422fd0ba67f61ad6e38c423a476a41cabec06f53f7a55b38
     source_path: help/index.md
     workflow: 15
 ---
 
-如果你想要一条快速“解决问题”的路径，请从这里开始：
+最常见问题的快速“解决问题”路径：
 
-- **故障排除：** [从这里开始](/zh-CN/help/troubleshooting)
-- **安装完整性检查（Node/npm/PATH）：** [安装](/zh-CN/install/node#troubleshooting)
-- **Gateway 网关问题：** [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting)
-- **日志：** [日志](/zh-CN/logging) 和 [Gateway 网关日志](/zh-CN/gateway/logging)
-- **修复：** [Doctor](/zh-CN/gateway/doctor)
+- [故障排除](/zh-CN/help/troubleshooting) — 按症状优先的决策树
+- [调试](/zh-CN/help/debugging) — 监视模式、原始流、开发配置文件
+- [安装完整性检查](/zh-CN/install/node#troubleshooting) — Node / npm / PATH 检查
+- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting) — Gateway 网关特定问题
+- [Doctor](/zh-CN/gateway/doctor) — 自动修复 + 诊断包
 
-如果你想找的是概念性问题（而不是“某些地方坏了”）：
+## 常见问题
 
-- [常见问题（概念）](/zh-CN/help/faq)
+- [常见问题](/zh-CN/help/faq) — 日常概念与操作问题
+- [首次运行常见问题](/zh-CN/help/faq-first-run) — 安装、新手引导、凭证、订阅、早期失败
+- [模型常见问题](/zh-CN/help/faq-models) — 模型选择、故障切换、认证配置文件
 
-## 环境与调试
+## 诊断
 
-- **环境变量：** [OpenClaw 在哪里加载环境变量及其优先级](/zh-CN/help/environment)
-- **调试：** [监视模式、原始流和开发 profile](/zh-CN/help/debugging)
-- **测试：** [测试套件、实时测试和 Docker runners](/zh-CN/help/testing)
-- **脚本：** [仓库辅助脚本](/zh-CN/help/scripts)
+- [环境变量](/zh-CN/help/environment) — OpenClaw 在哪里加载环境变量以及优先级
+- [诊断标志](/zh-CN/diagnostics/flags) — 运行时诊断与详细模式
+- [Node + tsx 崩溃](/zh-CN/debug/node-issue) — 特定的 Node / tsx 运行时崩溃场景
+
+## 测试
+
+- [测试](/zh-CN/help/testing) — 测试套件与 Docker 运行器
+- [实时测试](/zh-CN/help/testing-live) — 涉及网络的提供商与 CLI 冒烟测试
+
+## 社区与其他
+
+- [OpenClaw 背景故事](/zh-CN/start/lore) — 故事背景
+- [文档中心](/zh-CN/start/hubs) — 本文档的组织方式
+- [文档目录](/zh-CN/start/docs-directory) — 完整文件映射

docs/zh-CN/help/troubleshooting.md

@@ -1,25 +1,23 @@
 ---
 read_when:
-    - OpenClaw 无法正常工作，你需要最快的修复路径
-    - 你希望在深入查看详细操作手册之前，先走一遍分诊流程
-summary: OpenClaw 按症状分类的故障排除中心
-title: 常规故障排除
+    - OpenClaw 无法正常工作，而你需要最快速的解决方案。
+    - 你想在深入查看详细操作手册之前，先进行分诊流程。
+summary: OpenClaw 的按症状排查故障中心
+title: 常见故障排除
 x-i18n:
-    generated_at: "2026-04-23T20:51:23Z"
+    generated_at: "2026-04-24T06:58:59Z"
     model: gpt-5.4
     provider: openai
-    source_hash: ce06ddce9de9e5824b4c5e8c182df07b29ce3ff113eb8e29c62aef9a4682e8e9
+    source_hash: c832c3f7609c56a5461515ed0f693d2255310bf2d3958f69f57c482bcbef97f0
     source_path: help/troubleshooting.md
     workflow: 15
 ---
 
-# 故障排除
-
-如果你只有 2 分钟时间，请把本页当作分诊入口。
+如果你只有 2 分钟，请把这个页面当作分诊入口。
 
 ## 最初的六十秒
 
-按顺序运行下面这组命令：
+按顺序运行这组命令，不要跳步：
 
 ```bash
 openclaw status
@@ -31,15 +29,15 @@ openclaw channels status --probe
 openclaw logs --follow
 ```
 
-良好的输出可以概括为：
+一行判断“正常输出”：
 
-- `openclaw status` → 显示已配置的渠道，且没有明显的认证错误。
-- `openclaw status --all` → 完整报告存在且可分享。
-- `openclaw gateway probe` → 预期的 gateway 目标可达（`Reachable: yes`）。`Capability: ...` 表示探测所能证明的认证级别，而 `Read probe: limited - missing scope: operator.read` 表示诊断能力受限，不代表连接失败。
-- `openclaw gateway status` → 显示 `Runtime: running`、`Connectivity probe: ok` 以及合理的 `Capability: ...` 行。如果你还需要读作用域的 RPC 证明，可使用 `--require-rpc`。
-- `openclaw doctor` → 没有阻塞性的配置/服务错误。
-- `openclaw channels status --probe` → 当 gateway 可达时，会返回实时的逐账户传输状态，以及如 `works` 或 `audit ok` 之类的 probe/audit 结果；如果 gateway 不可达，该命令会回退为仅配置摘要。
-- `openclaw logs --follow` → 有稳定活动，没有重复出现的致命错误。
+- `openclaw status` → 显示已配置的渠道，且没有明显的身份验证错误。
+- `openclaw status --all` → 完整报告存在，并且可以分享。
+- `openclaw gateway probe` → 预期的 Gateway 网关目标可达（`Reachable: yes`）。`Capability: ...` 会告诉你探测能够证明的认证级别，而 `Read probe: limited - missing scope: operator.read` 表示诊断能力受限，不是连接失败。
+- `openclaw gateway status` → 显示 `Runtime: running`、`Connectivity probe: ok`，以及合理的 `Capability: ...` 行。如果你还需要具备读取作用域的 RPC 证明，可使用 `--require-rpc`。
+- `openclaw doctor` → 没有阻塞性的配置或服务错误。
+- `openclaw channels status --probe` → 如果 Gateway 网关可达，会返回每个账号的实时传输状态，以及 `works` 或 `audit ok` 之类的探测 / 审计结果；如果 Gateway 网关不可达，该命令会回退为仅基于配置的摘要。
+- `openclaw logs --follow` → 活动稳定，没有重复出现的致命错误。
 
 ## Anthropic 长上下文 429
 
@@ -47,30 +45,28 @@ openclaw logs --follow
 `HTTP 429: rate_limit_error: Extra usage is required for long context requests`，
 请前往 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/zh-CN/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。
 
-## 本地 OpenAI 兼容后端可直接工作，但在 OpenClaw 中失败
+## 本地 OpenAI 兼容后端直接可用，但在 OpenClaw 中失败
 
-如果你的本地或自托管 `/v1` 后端能响应小型直接
+如果你的本地或自托管 `/v1` 后端能够响应小型直接
 `/v1/chat/completions` 探测，但在 `openclaw infer model run` 或正常
-智能体轮次中失败：
+智能体对话中失败：
 
-1. 如果错误提到 `messages[].content` 需要字符串，请设置
+1. 如果错误提到 `messages[].content` 需要是字符串，请设置
    `models.providers.<provider>.models[].compat.requiresStringContent: true`。
-2. 如果后端仍只在 OpenClaw 智能体轮次中失败，请设置
-   `models.providers.<provider>.models[].compat.supportsTools: false` 并重试。
-3. 如果微小的直接调用仍然可以工作，但更大的 OpenClaw 提示导致后端崩溃，
-   则应将剩余问题视为上游模型/服务器限制，并继续阅读详细操作手册：
+2. 如果后端仍然只在 OpenClaw 智能体对话中失败，请设置
+   `models.providers.<provider>.models[].compat.supportsTools: false` 然后重试。
+3. 如果很小的直接调用仍然可用，但较大的 OpenClaw 提示词会让后端崩溃，请将剩余问题视为上游模型 / 服务器限制，并继续查看详细操作手册：
    [/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/zh-CN/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
 
-## 插件安装因缺少 openclaw extensions 而失败
+## 插件安装失败，并提示缺少 openclaw extensions
 
-如果安装因 `package.json missing openclaw.extensions` 失败，说明该插件包
-使用了 OpenClaw 已不再接受的旧结构。
+如果安装失败并提示 `package.json missing openclaw.extensions`，说明该插件包使用了 OpenClaw 已不再接受的旧结构。
 
-在插件包中修复：
+在插件包中这样修复：
 
 1. 在 `package.json` 中添加 `openclaw.extensions`。
-2. 将条目指向已构建的运行时文件（通常是 `./dist/index.js`）。
-3. 重新发布插件，再次运行 `openclaw plugins install <package>`。
+2. 将条目指向构建后的运行时文件（通常是 `./dist/index.js`）。
+3. 重新发布该插件，然后再次运行 `openclaw plugins install <package>`。
 
 示例：
 
@@ -84,25 +80,25 @@ openclaw logs --follow
 }
 ```
 
-参考：[插件架构](/zh-CN/plugins/architecture)
+参考：[Plugin architecture](/zh-CN/plugins/architecture)
 
 ## 决策树
 
 ```mermaid
 flowchart TD
-  A[OpenClaw 无法正常工作] --> B{首先坏掉的是什么}
+  A[OpenClaw 无法正常工作] --> B{最先出问题的是什么}
   B --> C[没有回复]
   B --> D[Dashboard 或 Control UI 无法连接]
-  B --> E[Gateway 无法启动或服务未运行]
-  B --> F[渠道已连接，但消息无法流动]
+  B --> E[Gateway 网关无法启动或服务未运行]
+  B --> F[渠道已连接但消息没有流动]
   B --> G[Cron 或 heartbeat 未触发或未送达]
-  B --> H[节点已配对，但 camera canvas screen exec 失败]
+  B --> H[节点已配对但 camera canvas screen exec 工具失败]
   B --> I[浏览器工具失败]
 
   C --> C1[/“没有回复”部分/]
   D --> D1[/“Control UI”部分/]
-  E --> E1[/“Gateway”部分/]
-  F --> F1[/“渠道流动”部分/]
+  E --> E1[/“Gateway 网关”部分/]
+  F --> F1[/“渠道流转”部分/]
   G --> G1[/“自动化”部分/]
   H --> H1[/“节点工具”部分/]
   I --> I1[/“浏览器”部分/]
@@ -118,21 +114,21 @@ flowchart TD
     openclaw logs --follow
     ```
 
-    良好的输出应表现为：
+    正常输出通常如下：
 
     - `Runtime: running`
     - `Connectivity probe: ok`
     - `Capability: read-only`、`write-capable` 或 `admin-capable`
-    - 你的渠道显示传输已连接，并且在支持时，`channels status --probe` 中会出现 `works` 或 `audit ok`
-    - 发送者显示为已批准（或私信策略为 open/allowlist）
+    - 你的渠道显示传输已连接，并且在支持的情况下，`channels status --probe` 中会显示 `works` 或 `audit ok`
+    - 发送者显示已获批准（或私信策略为 open / allowlist）
 
     常见日志特征：
 
-    - `drop guild message (mention required` → Discord 中，提及门控阻止了该消息。
+    - `drop guild message (mention required` → 在 Discord 中，提及门控阻止了该消息。
     - `pairing request` → 发送者尚未获批，正在等待私信配对批准。
     - 渠道日志中的 `blocked` / `allowlist` → 发送者、房间或群组被过滤。
 
-    深入页面：
+    详细页面：
 
     - [/gateway/troubleshooting#no-replies](/zh-CN/gateway/troubleshooting#no-replies)
     - [/channels/troubleshooting](/zh-CN/channels/troubleshooting)
@@ -149,28 +145,27 @@ flowchart TD
     openclaw channels status --probe
     ```
 
-    良好的输出应表现为：
+    正常输出通常如下：
 
-    - `openclaw gateway status` 中显示 `Dashboard: http://...`
+    - 在 `openclaw gateway status` 中显示 `Dashboard: http://...`
     - `Connectivity probe: ok`
     - `Capability: read-only`、`write-capable` 或 `admin-capable`
     - 日志中没有认证循环
 
     常见日志特征：
 
-    - `device identity required` → HTTP/非安全上下文无法完成设备认证。
-    - `origin not allowed` → 浏览器 `Origin` 不在 Control UI
-      gateway 目标的允许范围内。
-    - `AUTH_TOKEN_MISMATCH` 并带有重试提示（`canRetryWithDeviceToken=true`）→ 可能会自动进行一次受信任的 device-token 重试。
-    - 该缓存 token 重试会复用与已配对
-      设备 token 一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留其请求的作用域集合。
-    - 在异步 Tailscale Serve Control UI 路径中，对于相同
-      `{scope, ip}` 的失败尝试，会在 limiter 记录失败前进行串行化，因此第二个并发错误重试可能已经显示 `retry later`。
-    - 来自 localhost 浏览器 origin 的 `too many failed authentication attempts (retry later)` → 同一 `Origin` 的重复失败已被暂时锁定；另一个 localhost origin 使用的是单独的配额桶。
-    - 在那次重试之后仍反复出现 `unauthorized` → token/密码错误、认证模式不匹配，或已配对设备 token 已过期。
-    - `gateway connect failed:` → UI 指向了错误的 URL/端口，或 gateway 不可达。
+    - `device identity required` → HTTP / 非安全上下文无法完成设备认证。
+    - `origin not allowed` → 浏览器 `Origin` 不在 Control UI 的
+      Gateway 网关目标允许范围内。
+    - 带有重试提示（`canRetryWithDeviceToken=true`）的 `AUTH_TOKEN_MISMATCH` → 可能会自动执行一次受信任的设备令牌重试。
+    - 该缓存令牌重试会复用与已配对设备令牌一起存储的缓存作用域集合。显式传入 `deviceToken` / 显式传入 `scopes` 的调用方则会保留它们请求的作用域集合。
+    - 在异步 Tailscale Serve Control UI 路径上，同一
+      `{scope, ip}` 的失败尝试会在限流器记录失败之前被串行化，因此第二个并发的错误重试可能已经显示 `retry later`。
+    - 来自 localhost 浏览器来源的 `too many failed authentication attempts (retry later)` → 同一 `Origin` 的重复失败会被暂时锁定；另一个 localhost 来源会使用单独的桶。
+    - 该次重试之后仍反复出现 `unauthorized` → 令牌 / 密码错误、认证模式不匹配，或已配对的设备令牌已过期。
+    - `gateway connect failed:` → UI 指向了错误的 URL / 端口，或 Gateway 网关不可达。
 
-    深入页面：
+    详细页面：
 
     - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/zh-CN/gateway/troubleshooting#dashboard-control-ui-connectivity)
     - [/web/control-ui](/zh-CN/web/control-ui)
@@ -178,7 +173,7 @@ flowchart TD
 
   </Accordion>
 
-  <Accordion title="Gateway 无法启动，或服务已安装但未运行">
+  <Accordion title="Gateway 网关无法启动，或服务已安装但未运行">
     ```bash
     openclaw status
     openclaw gateway status
@@ -187,7 +182,7 @@ flowchart TD
     openclaw channels status --probe
     ```
 
-    良好的输出应表现为：
+    正常输出通常如下：
 
     - `Service: ... (loaded)`
     - `Runtime: running`
@@ -196,11 +191,11 @@ flowchart TD
 
     常见日志特征：
 
-    - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → gateway 模式是 remote，或者配置文件缺少 local-mode 标记，需要修复。
-    - `refusing to bind gateway ... without auth` → 在没有有效 gateway 认证路径（token/password，或在已配置时使用 trusted-proxy）的情况下，尝试进行非 loopback 绑定。
+    - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → Gateway 网关模式为 remote，或配置文件缺少 local 模式标记，需要修复。
+    - `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下尝试绑定到非 loopback 地址（令牌 / 密码，或在已配置时使用 trusted-proxy）。
     - `another gateway instance is already listening` 或 `EADDRINUSE` → 端口已被占用。
 
-    深入页面：
+    详细页面：
 
     - [/gateway/troubleshooting#gateway-service-not-running](/zh-CN/gateway/troubleshooting#gateway-service-not-running)
     - [/gateway/background-process](/zh-CN/gateway/background-process)
@@ -208,7 +203,7 @@ flowchart TD
 
   </Accordion>
 
-  <Accordion title="渠道已连接，但消息无法流动">
+  <Accordion title="渠道已连接但消息没有流动">
     ```bash
     openclaw status
     openclaw gateway status
@@ -217,19 +212,19 @@ flowchart TD
     openclaw channels status --probe
     ```
 
-    良好的输出应表现为：
+    正常输出通常如下：
 
     - 渠道传输已连接。
-    - 配对/允许列表检查通过。
-    - 在需要时，提及可被检测到。
+    - 配对 / allowlist 检查通过。
+    - 在需要时，能够检测到提及。
 
     常见日志特征：
 
     - `mention required` → 群组提及门控阻止了处理。
     - `pairing` / `pending` → 私信发送者尚未获批。
-    - `not_in_channel`、`missing_scope`、`Forbidden`、`401/403` → 渠道权限 token 问题。
+    - `not_in_channel`、`missing_scope`、`Forbidden`、`401/403` → 渠道权限令牌问题。
 
-    深入页面：
+    详细页面：
 
     - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/zh-CN/gateway/troubleshooting#channel-connected-messages-not-flowing)
     - [/channels/troubleshooting](/zh-CN/channels/troubleshooting)
@@ -246,23 +241,23 @@ flowchart TD
     openclaw logs --follow
     ```
 
-    良好的输出应表现为：
+    正常输出通常如下：
 
-    - `cron.status` 显示已启用，并有下次唤醒时间。
-    - `cron runs` 显示最近的 `ok` 条目。
-    - heartbeat 已启用，且不在静默时段之外。
+    - `cron.status` 显示已启用，并带有下一次唤醒时间。
+    - `cron runs` 显示最近的 `ok` 记录。
+    - heartbeat 已启用，且不在活跃时间之外。
 
     常见日志特征：
 
     - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。
-    - `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于配置的静默时段外。
-    - `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空白/仅标题脚手架。
-    - `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 任务模式已启用，但当前没有到期的任务间隔。
-    - `heartbeat skipped` 且 `reason=alerts-disabled` → 所有 heartbeat 可见性都被禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭）。
+    - `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于配置的活跃时间之外。
+    - `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空白 / 仅标题的骨架内容。
+    - `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 任务模式已启用，但目前还没有任何任务到达间隔时间。
+    - `heartbeat skipped` 且 `reason=alerts-disabled` → 所有 heartbeat 可见性都已禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭）。
     - `requests-in-flight` → 主通道繁忙；heartbeat 唤醒被延后。
-    - `unknown accountId` → heartbeat 投递目标账户不存在。
+    - `unknown accountId` → heartbeat 投递目标账号不存在。
 
-    深入页面：
+    详细页面：
 
     - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/zh-CN/gateway/troubleshooting#cron-and-heartbeat-delivery)
     - [/automation/cron-jobs#troubleshooting](/zh-CN/automation/cron-jobs#troubleshooting)
@@ -270,7 +265,7 @@ flowchart TD
 
   </Accordion>
 
-  <Accordion title="节点已配对，但工具失败：camera canvas screen exec">
+  <Accordion title="节点已配对，但工具的 camera canvas screen exec 失败">
     ```bash
     openclaw status
     openclaw gateway status
@@ -279,20 +274,20 @@ flowchart TD
     openclaw logs --follow
     ```
 
-    良好的输出应表现为：
+    正常输出通常如下：
 
-    - 节点被列为已连接，并以 `node` 角色完成配对。
-    - 你调用的命令所需能力存在。
-    - 工具的权限状态已授予。
+    - 节点列为已连接，并已针对 `node` 角色完成配对。
+    - 你调用的命令具备相应能力。
+    - 该工具的权限状态为已授予。
 
     常见日志特征：
 
-    - `NODE_BACKGROUND_UNAVAILABLE` → 请将节点应用切回前台。
-    - `*_PERMISSION_REQUIRED` → OS 权限被拒绝或缺失。
-    - `SYSTEM_RUN_DENIED: approval required` → exec 批准仍在等待中。
-    - `SYSTEM_RUN_DENIED: allowlist miss` → 命令不在 exec 允许列表中。
+    - `NODE_BACKGROUND_UNAVAILABLE` → 将节点应用切换到前台。
+    - `*_PERMISSION_REQUIRED` → 操作系统权限被拒绝或缺失。
+    - `SYSTEM_RUN_DENIED: approval required` → exec 批准正在等待中。
+    - `SYSTEM_RUN_DENIED: allowlist miss` → 该命令不在 exec allowlist 中。
 
-    深入页面：
+    详细页面：
 
     - [/gateway/troubleshooting#node-paired-tool-fails](/zh-CN/gateway/troubleshooting#node-paired-tool-fails)
     - [/nodes/troubleshooting](/zh-CN/nodes/troubleshooting)
@@ -300,7 +295,7 @@ flowchart TD
 
   </Accordion>
 
-  <Accordion title="Exec 突然开始请求批准">
+  <Accordion title="Exec 突然开始要求批准">
     ```bash
     openclaw config get tools.exec.host
     openclaw config get tools.exec.security
@@ -310,14 +305,14 @@ flowchart TD
 
     发生了什么变化：
 
-    - 如果未设置 `tools.exec.host`，默认值是 `auto`。
-    - `host=auto` 在存在沙箱运行时时会解析为 `sandbox`，否则解析为 `gateway`。
-    - `host=auto` 只负责路由；无提示的 “YOLO” 行为来自于 gateway/node 上的 `security=full` 加 `ask=off`。
-    - 在 `gateway` 和 `node` 上，未设置的 `tools.exec.security` 默认值为 `full`。
-    - 未设置的 `tools.exec.ask` 默认值为 `off`。
-    - 结果是：如果你现在看到了批准提示，说明某些宿主机本地策略或按会话策略，相对于当前默认值收紧了 exec。
+    - 如果 `tools.exec.host` 未设置，默认值是 `auto`。
+    - 当沙箱运行时处于激活状态时，`host=auto` 会解析为 `sandbox`；否则解析为 `gateway`。
+    - `host=auto` 仅影响路由；无提示的 “YOLO” 行为来自 gateway/node 上的 `security=full` 加 `ask=off`。
+    - 在 `gateway` 和 `node` 上，未设置的 `tools.exec.security` 默认是 `full`。
+    - 未设置的 `tools.exec.ask` 默认是 `off`。
+    - 结果：如果你现在看到了批准请求，说明某些主机本地或按会话生效的策略，相比当前默认值收紧了 exec 行为。
 
-    恢复为当前默认的无批准行为：
+    恢复当前默认的无批准行为：
 
     ```bash
     openclaw config set tools.exec.host gateway
@@ -328,17 +323,17 @@ flowchart TD
 
     更安全的替代方案：
 
-    - 如果你只是想要稳定的宿主机路由，只设置 `tools.exec.host=gateway`。
-    - 如果你想使用宿主机 exec，但仍希望在 allowlist 未命中时进行审核，可使用 `security=allowlist` 搭配 `ask=on-miss`。
-    - 如果你希望 `host=auto` 重新解析为 `sandbox`，请启用沙箱模式。
+    - 如果你只想要稳定的主机路由，仅设置 `tools.exec.host=gateway`。
+    - 如果你希望使用主机 exec，但在 allowlist 未命中时仍进行审查，请使用 `security=allowlist` 搭配 `ask=on-miss`。
+    - 如果你希望 `host=auto` 重新解析回 `sandbox`，请启用沙箱模式。
 
     常见日志特征：
 
     - `Approval required.` → 命令正在等待 `/approve ...`。
-    - `SYSTEM_RUN_DENIED: approval required` → node-host exec 批准仍在等待中。
-    - `exec host=sandbox requires a sandbox runtime for this session` → 已隐式/显式选择了 sandbox，但当前会话的沙箱模式已关闭。
+    - `SYSTEM_RUN_DENIED: approval required` → node 主机 exec 批准正在等待中。
+    - `exec host=sandbox requires a sandbox runtime for this session` → 已隐式 / 显式选择沙箱，但沙箱模式处于关闭状态。
 
-    深入页面：
+    详细页面：
 
     - [/tools/exec](/zh-CN/tools/exec)
     - [/tools/exec-approvals](/zh-CN/tools/exec-approvals)
@@ -355,24 +350,24 @@ flowchart TD
     openclaw doctor
     ```
 
-    良好的输出应表现为：
+    正常输出通常如下：
 
-    - 浏览器状态显示 `running: true`，并已选定某个浏览器/profile。
-    - `openclaw` 能启动，或者 `user` 能看到本地 Chrome 标签页。
+    - 浏览器状态显示 `running: true`，并且已选定浏览器 / 配置文件。
+    - `openclaw` 已启动，或者 `user` 能看到本地 Chrome 标签页。
 
     常见日志特征：
 
     - `unknown command "browser"` 或 `unknown command 'browser'` → 设置了 `plugins.allow`，但其中不包含 `browser`。
     - `Failed to start Chrome CDP on port` → 本地浏览器启动失败。
     - `browser.executablePath not found` → 配置的二进制路径错误。
-    - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的 scheme。
-    - `browser.cdpUrl has invalid port` → 配置的 CDP URL 使用了错误或超范围的端口。
-    - `No Chrome tabs found for profile="user"` → Chrome MCP 附加 profile 没有打开的本地 Chrome 标签页。
-    - `Remote CDP for profile "<name>" is not reachable` → 从当前主机无法访问所配置的远程 CDP 端点。
-    - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加 profile 没有可用的实时 CDP 目标。
-    - attach-only 或远程 CDP profile 上出现过期的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>`，即可关闭当前控制会话并释放仿真状态，而无需重启 gateway。
+    - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的协议。
+    - `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。
+    - `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。
+    - `Remote CDP for profile "<name>" is not reachable` → 配置的远程 CDP 端点从当前主机无法访问。
+    - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可用的实时 CDP 目标。
+    - 对 attach-only 或远程 CDP 配置文件，若存在陈旧的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>`，关闭当前活动控制会话并释放模拟状态，而无需重启 Gateway 网关。
 
-    深入页面：
+    详细页面：
 
     - [/gateway/troubleshooting#browser-tool-fails](/zh-CN/gateway/troubleshooting#browser-tool-fails)
     - [/tools/browser#missing-browser-command-or-tool](/zh-CN/tools/browser#missing-browser-command-or-tool)
@@ -385,8 +380,8 @@ flowchart TD
 
 ## 相关内容
 
-- [常见问题](/zh-CN/help/faq) — 常见问题
-- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting) — Gateway 网关特定问题
-- [Doctor](/zh-CN/gateway/doctor) — 自动健康检查与修复
-- [渠道故障排除](/zh-CN/channels/troubleshooting) — 渠道连接问题
-- [自动化故障排除](/zh-CN/automation/cron-jobs#troubleshooting) — cron 和 heartbeat 问题
+- [常见问题](/zh-CN/help/faq) — 常见问题解答
+- [Gateway Troubleshooting](/zh-CN/gateway/troubleshooting) — Gateway 网关专属问题
+- [Doctor](/zh-CN/gateway/doctor) — 自动化健康检查与修复
+- [Channel Troubleshooting](/zh-CN/channels/troubleshooting) — 渠道连接问题
+- [Automation Troubleshooting](/zh-CN/automation/cron-jobs#troubleshooting) — cron 和 heartbeat 问题

docs/zh-CN/plugins/sdk-subpaths.md

@@ -1,27 +1,26 @@
 ---
 read_when:
     - 为插件导入选择合适的 plugin-sdk 子路径
-    - 审查 bundled-plugin 子路径和辅助接口
-summary: 插件 SDK 子路径目录：按领域分组说明各个导入位于何处
-title: Plugin SDK 子路径
+    - 审查 bundled-plugin 子路径和辅助接口 surface
+summary: 插件 SDK 子路径目录：按领域分组，哪些导入位于哪里
+title: 插件 SDK 子路径
 x-i18n:
-    generated_at: "2026-04-24T04:27:27Z"
+    generated_at: "2026-04-24T06:58:59Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 753c7202a8a59ae9e420d436c7f3770ea455d810f2af52b716d438b84b8b986e
+    source_hash: ff4b934501a3163e36b402db72dd75a260fe9f849b3823a7a05e4867a1a5e655
     source_path: plugins/sdk-subpaths.md
     workflow: 15
 ---
 
-  插件 SDK 以 `openclaw/plugin-sdk/` 下的一组窄子路径形式公开。
-  本页按用途对常用子路径进行归类整理。生成的完整 200+ 子路径列表位于 `scripts/lib/plugin-sdk-entrypoints.json`；
-  其中也包含保留给 bundled-plugin 辅助接口的子路径，但除非某个文档页面明确将其作为公开能力推荐，否则它们都属于实现细节。
+  插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径公开。
+  本页按用途对常用子路径进行归类整理。生成的完整清单包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`；其中也会列出保留给 bundled-plugin 辅助功能的子路径，但除非某个文档页面明确将其作为公开能力推广，否则它们都属于实现细节。
 
-  有关插件编写指南，参见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。
+  关于插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。
 
   ## 插件入口
 
-  | 子路径 | 关键导出 |
+  | 子路径                      | 关键导出                                                                                                                               |
   | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
   | `plugin-sdk/plugin-entry`   | `definePluginEntry`                                                                                                                    |
   | `plugin-sdk/core`           | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
@@ -33,183 +32,183 @@ x-i18n:
     | 子路径 | 关键导出 |
     | --- | --- |
     | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
-    | `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
+    | `plugin-sdk/config-schema` | 根级 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
     | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
-    | `plugin-sdk/setup` | 共享的设置向导辅助函数、allowlist 提示、设置状态构建器 |
+    | `plugin-sdk/setup` | 共享设置向导辅助工具、allowlist 提示、设置状态构建器 |
     | `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`、account-id 规范化辅助函数 |
-    | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 |
-    | `plugin-sdk/account-helpers` | 窄范围的账户列表 / 账户操作辅助函数 |
+    | `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助工具、默认账户回退辅助工具 |
+    | `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 自定义命令规范化 / 校验辅助函数，并在需要时回退到 bundled contract |
-    | `plugin-sdk/command-gating` | 窄范围的命令授权门控辅助函数 |
+    | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 校验辅助工具，带 bundled-contract 回退 |
+    | `plugin-sdk/command-gating` | 精简的命令授权门控辅助工具 |
     | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
-    | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 完成辅助函数 |
-    | `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建辅助函数 |
-    | `plugin-sdk/inbound-reply-dispatch` | 共享的入站记录与分发辅助函数 |
-    | `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助函数 |
-    | `plugin-sdk/outbound-media` | 共享的出站媒体加载辅助函数 |
-    | `plugin-sdk/outbound-runtime` | 出站身份、发送委托和负载规划辅助函数 |
-    | `plugin-sdk/poll-runtime` | 窄范围的投票规范化辅助函数 |
-    | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助函数 |
-    | `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 |
-    | `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-writes` | 渠道配置写入授权辅助函数 |
-    | `plugin-sdk/channel-plugin-common` | 共享的渠道插件前导导出 |
-    | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助函数 |
-    | `plugin-sdk/group-access` | 共享的群组访问决策辅助函数 |
-    | `plugin-sdk/direct-dm` | 共享的直接私信认证 / 守卫辅助函数 |
-    | `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递以及旧版交互式回复辅助函数。参见 [消息呈现](/zh-CN/plugins/message-presentation) |
-    | `plugin-sdk/channel-inbound` | 面向兼容性的 barrel，包含入站防抖、提及匹配、提及策略辅助函数以及 envelope 辅助函数 |
-    | `plugin-sdk/channel-inbound-debounce` | 窄范围的入站防抖辅助函数 |
-    | `plugin-sdk/channel-mention-gating` | 不包含更大范围入站运行时接口的窄范围提及策略和提及文本辅助函数 |
-    | `plugin-sdk/channel-envelope` | 窄范围的入站 envelope 格式化辅助函数 |
-    | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助函数 |
-    | `plugin-sdk/channel-logging` | 用于入站丢弃以及 typing / ack 失败的渠道日志辅助函数 |
+    | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 完成辅助工具 |
+    | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助工具 |
+    | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助工具 |
+    | `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助工具 |
+    | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 |
+    | `plugin-sdk/outbound-runtime` | 出站身份、发送委托和载荷规划辅助工具 |
+    | `plugin-sdk/poll-runtime` | 精简的投票规范化辅助工具 |
+    | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 |
+    | `plugin-sdk/agent-media-payload` | 旧版智能体媒体载荷构建器 |
+    | `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-writes` | 渠道配置写入授权辅助工具 |
+    | `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 |
+    | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助工具 |
+    | `plugin-sdk/group-access` | 共享群组访问决策辅助工具 |
+    | `plugin-sdk/direct-dm` | 共享直接私信认证 / 守卫辅助工具 |
+    | `plugin-sdk/interactive-runtime` | 语义消息呈现、投递和旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) |
+    | `plugin-sdk/channel-inbound` | 兼容性 barrel，包含入站去抖、提及匹配、提及策略辅助工具和 envelope 辅助工具 |
+    | `plugin-sdk/channel-inbound-debounce` | 精简的入站去抖辅助工具 |
+    | `plugin-sdk/channel-mention-gating` | 精简的提及策略和提及文本辅助工具，不包含更广泛的入站运行时接口 |
+    | `plugin-sdk/channel-envelope` | 精简的入站 envelope 格式化辅助工具 |
+    | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 |
+    | `plugin-sdk/channel-logging` | 用于入站丢弃以及 typing / ack 失败的渠道日志辅助工具 |
     | `plugin-sdk/channel-send-result` | 回复结果类型 |
-    | `plugin-sdk/channel-actions` | 渠道消息操作辅助函数，以及为插件兼容性保留的已弃用原生 schema 辅助函数 |
-    | `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助函数 |
-    | `plugin-sdk/channel-contract` | 渠道 contract 类型 |
+    | `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 |
+    | `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助工具 |
+    | `plugin-sdk/channel-contract` | 渠道契约类型 |
     | `plugin-sdk/channel-feedback` | 反馈 / reaction 接线 |
-    | `plugin-sdk/channel-secret-runtime` | 窄范围的 secret-contract 辅助函数，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 以及 secret target 类型 |
+    | `plugin-sdk/channel-secret-runtime` | 精简的 secret 契约辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret target 类型 |
   </Accordion>
 
   <Accordion title="提供商子路径">
     | 子路径 | 关键导出 |
     | --- | --- |
     | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
-    | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助函数 |
-    | `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商的专用设置辅助函数 |
+    | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助工具 |
+    | `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商的聚焦设置辅助工具 |
     | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 |
-    | `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API key 解析辅助函数 |
-    | `plugin-sdk/provider-auth-api-key` | API key 新手引导 / 配置档写入辅助函数，例如 `upsertApiKeyProfile` |
+    | `plugin-sdk/provider-auth-runtime` | 用于提供商插件的运行时 API key 解析辅助工具 |
+    | `plugin-sdk/provider-auth-api-key` | API key 新手引导 / 配置文件写入辅助工具，例如 `upsertApiKeyProfile` |
     | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 |
-    | `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助函数 |
-    | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助函数 |
+    | `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 构建器、provider-endpoint 辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助函数 |
+    | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及模型 ID 规范化辅助工具，例如 `normalizeNativeXaiModelId` |
     | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
-    | `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint 能力辅助函数，包括音频转写 multipart form 辅助函数 |
-    | `plugin-sdk/provider-web-fetch-contract` | 窄范围的 web-fetch 配置 / 选择 contract 辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
-    | `plugin-sdk/provider-web-fetch` | Web-fetch 提供商注册 / 缓存辅助函数 |
-    | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的窄范围 web-search 配置 / 凭证辅助函数 |
-    | `plugin-sdk/provider-web-search-contract` | 窄范围的 web-search 配置 / 凭证 contract 辅助函数，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及有作用域的凭证 setter / getter |
-    | `plugin-sdk/provider-web-search` | Web-search 提供商注册 / 缓存 / 运行时辅助函数 |
-    | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容辅助函数 |
-    | `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-transport-runtime` | 原生提供商传输辅助函数，例如受保护的 fetch、传输消息转换以及可写的传输事件流 |
-    | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 |
-    | `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助函数 |
-    | `plugin-sdk/group-activation` | 窄范围的群组激活模式和命令解析辅助函数 |
+    | `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint 能力辅助工具，包括音频转录 multipart form 辅助工具 |
+    | `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置 / 选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
+    | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助工具 |
+    | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的精简 web-search 配置 / 凭证辅助工具 |
+    | `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置 / 凭证契约辅助工具，例如 `createWebSearchProviderContractFields`, `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-usage` | `fetchClaudeUsage` 及类似功能 |
+    | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助工具 |
+    | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息转换和可写传输事件流 |
+    | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 |
+    | `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助工具 |
+    | `plugin-sdk/group-activation` | 精简的群组激活模式和命令解析辅助工具 |
   </Accordion>
 
   <Accordion title="认证与安全子路径">
     | 子路径 | 关键导出 |
     | --- | --- |
-    | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 |
+    | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 |
     | `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` |
-    | `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天操作认证辅助函数 |
-    | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置档 / 过滤器辅助函数 |
+    | `plugin-sdk/approval-auth-runtime` | 审批者解析和同聊天操作认证辅助工具 |
+    | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件 / 过滤器辅助工具 |
     | `plugin-sdk/approval-delivery-runtime` | 原生审批能力 / 投递适配器 |
-    | `plugin-sdk/approval-gateway-runtime` | 共享的审批 Gateway 网关解析辅助函数 |
-    | `plugin-sdk/approval-handler-adapter-runtime` | 用于热渠道入口点的轻量级原生审批适配器加载辅助函数 |
-    | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助函数；如果更窄的 adapter / gateway 接口已经足够，优先使用它们 |
-    | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助函数 |
-    | `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复负载辅助函数 |
-    | `plugin-sdk/reply-dedupe` | 窄范围的入站回复去重重置辅助函数 |
-    | `plugin-sdk/channel-contract-testing` | 不包含宽泛 testing barrel 的窄范围渠道 contract 测试辅助函数 |
-    | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助函数 |
-    | `plugin-sdk/command-detection` | 共享的命令检测辅助函数 |
-    | `plugin-sdk/command-primitives-runtime` | 用于热渠道路径的轻量级命令文本谓词 |
-    | `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助函数 |
+    | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 |
+    | `plugin-sdk/approval-handler-adapter-runtime` | 面向高频渠道入口点的轻量原生审批适配器加载辅助工具 |
+    | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；如果更精简的 adapter / gateway 接口已足够，优先使用它们 |
+    | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 |
+    | `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复载荷辅助工具 |
+    | `plugin-sdk/reply-dedupe` | 精简的入站回复去重重置辅助工具 |
+    | `plugin-sdk/channel-contract-testing` | 精简的渠道契约测试辅助工具，不包含宽泛的 testing barrel |
+    | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生 session target 辅助工具 |
+    | `plugin-sdk/command-detection` | 共享命令检测辅助工具 |
+    | `plugin-sdk/command-primitives-runtime` | 面向高频渠道路径的轻量命令文本谓词 |
+    | `plugin-sdk/command-surface` | 命令体规范化和命令接口辅助工具 |
     | `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
-    | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret 接口的窄范围 secret-contract 收集辅助函数 |
-    | `plugin-sdk/secret-ref-runtime` | 面向 secret-contract / 配置解析的窄范围 `coerceSecretRef` 和 SecretRef 类型辅助函数 |
-    | `plugin-sdk/security-runtime` | 共享的信任、私信门控、外部内容和 secret 收集辅助函数 |
-    | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 |
-    | `plugin-sdk/ssrf-dispatcher` | 不包含宽泛基础设施运行时接口的窄范围固定 dispatcher 辅助函数 |
-    | `plugin-sdk/ssrf-runtime` | 固定 dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助函数 |
-    | `plugin-sdk/secret-input` | secret 输入解析辅助函数 |
-    | `plugin-sdk/webhook-ingress` | Webhook 请求 / 目标辅助函数 |
-    | `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助函数 |
+    | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret 接口的精简 secret 契约收集辅助工具 |
+    | `plugin-sdk/secret-ref-runtime` | 用于 secret 契约 / 配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助工具 |
+    | `plugin-sdk/security-runtime` | 共享 trust、私信门控、外部内容和 secret 收集辅助工具 |
+    | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 |
+    | `plugin-sdk/ssrf-dispatcher` | 精简的 pinned-dispatcher 辅助工具，不包含宽泛的基础设施运行时接口 |
+    | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助工具 |
+    | `plugin-sdk/secret-input` | secret 输入解析辅助工具 |
+    | `plugin-sdk/webhook-ingress` | webhook 请求 / 目标辅助工具 |
+    | `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助工具 |
   </Accordion>
 
   <Accordion title="运行时与存储子路径">
     | 子路径 | 关键导出 |
     | --- | --- |
-    | `plugin-sdk/runtime` | 宽泛的运行时 / 日志 / 备份 / 插件安装辅助函数 |
-    | `plugin-sdk/runtime-env` | 窄范围的运行时环境、日志器、超时、重试和退避辅助函数 |
-    | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助函数 |
+    | `plugin-sdk/runtime` | 宽泛的运行时 / 日志 / 备份 / 插件安装辅助工具 |
+    | `plugin-sdk/runtime-env` | 精简的运行时环境、logger、超时、重试和 backoff 辅助工具 |
+    | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 |
     | `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/cli-runtime` | CLI 格式化、等待和版本辅助函数 |
-    | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助函数 |
-    | `plugin-sdk/config-runtime` | 配置加载 / 写入辅助函数，以及插件配置查找辅助函数 |
-    | `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化以及重复 / 冲突检查，即使 bundled Telegram contract 接口不可用也可使用 |
-    | `plugin-sdk/text-autolink-runtime` | 不依赖宽泛 text-runtime barrel 的文件引用自动链接检测 |
-    | `plugin-sdk/approval-runtime` | exec / 插件审批辅助函数、审批能力构建器、认证 / 配置档辅助函数、原生路由 / 运行时辅助函数 |
-    | `plugin-sdk/reply-runtime` | 共享的入站 / 回复运行时辅助函数、分块、分发、心跳、回复规划器 |
-    | `plugin-sdk/reply-dispatch-runtime` | 窄范围的回复分发 / 完成辅助函数 |
-    | `plugin-sdk/reply-history` | 共享的短窗口回复历史辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
+    | `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/cli-runtime` | CLI 格式化、等待和版本辅助工具 |
+    | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 |
+    | `plugin-sdk/config-runtime` | 配置加载 / 写入辅助工具，以及插件配置查找辅助工具 |
+    | `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化及重复 / 冲突检查，即使 bundled Telegram 契约接口不可用时也可使用 |
+    | `plugin-sdk/text-autolink-runtime` | 文件引用自动链接检测，不包含宽泛的 text-runtime barrel |
+    | `plugin-sdk/approval-runtime` | exec / 插件审批辅助工具、审批能力构建器、认证 / 配置文件辅助工具、原生路由 / 运行时辅助工具 |
+    | `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/status-helpers` | 共享的渠道 / 账户状态摘要辅助函数、运行时状态默认值，以及问题元数据辅助函数 |
-    | `plugin-sdk/target-resolver-runtime` | 共享的目标解析器辅助函数 |
-    | `plugin-sdk/string-normalization-runtime` | slug / 字符串规范化辅助函数 |
+    | `plugin-sdk/reply-chunking` | 精简的文本 / Markdown 分块辅助工具 |
+    | `plugin-sdk/session-store-runtime` | session store 路径 + updated-at 辅助工具 |
+    | `plugin-sdk/state-paths` | 状态 / OAuth 目录路径辅助工具 |
+    | `plugin-sdk/routing` | 路由 / session-key / 账户绑定辅助工具，例如 `resolveAgentRoute`, `buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` |
+    | `plugin-sdk/status-helpers` | 共享渠道 / 账户状态摘要辅助工具、运行时状态默认值，以及 issue 元数据辅助工具 |
+    | `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/run-command` | 带超时的命令运行器，返回规范化的 stdout / stderr 结果 |
     | `plugin-sdk/param-readers` | 通用工具 / CLI 参数读取器 |
-    | `plugin-sdk/tool-payload` | 从工具结果对象中提取已规范化的负载 |
-    | `plugin-sdk/tool-send` | 从工具参数中提取规范的发送目标字段 |
-    | `plugin-sdk/temp-path` | 共享的临时下载路径辅助函数 |
-    | `plugin-sdk/logging-core` | 子系统日志器和脱敏辅助函数 |
-    | `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/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 |
-    | `plugin-sdk/agent-config-primitives` | 窄范围的智能体运行时 config-schema 原语 |
-    | `plugin-sdk/boolean-param` | 宽松的布尔参数读取器 |
-    | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 |
-    | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 |
-    | `plugin-sdk/extension-shared` | 共享的被动渠道、状态和环境代理辅助原语 |
-    | `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助函数 |
-    | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助函数 |
-    | `plugin-sdk/native-command-registry` | 原生命令注册表构建 / 序列化辅助函数 |
-    | `plugin-sdk/agent-harness` | 面向受信任插件的实验性低层 agent harness 接口：harness 类型、活动运行 steer / abort 辅助函数、OpenClaw 工具桥接辅助函数，以及 attempt 结果工具函数 |
-    | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助函数 |
-    | `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助函数 |
-    | `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 |
-    | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助函数 |
-    | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` |
-    | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和固定查找辅助函数 |
-    | `plugin-sdk/runtime-fetch` | 感知 dispatcher 的运行时 fetch，不引入 proxy / guarded-fetch 导入 |
-    | `plugin-sdk/response-limit-runtime` | 不依赖宽泛 media runtime 接口的有界响应体读取器 |
+    | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化载荷 |
+    | `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` | 可重入 file-lock 辅助工具 |
+    | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 |
+    | `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复分发辅助工具 |
+    | `plugin-sdk/acp-binding-resolve-runtime` | 只读 ACP 绑定解析，不引入生命周期启动导入 |
+    | `plugin-sdk/agent-config-primitives` | 精简的智能体运行时配置 schema 基元 |
+    | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
+    | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 |
+    | `plugin-sdk/device-bootstrap` | 设备 bootstrap 和配对令牌辅助工具 |
+    | `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助基元 |
+    | `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助工具 |
+    | `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助工具 |
+    | `plugin-sdk/native-command-registry` | 原生命令注册表构建 / 序列化辅助工具 |
+    | `plugin-sdk/agent-harness` | 面向可信插件的实验性低层智能体 harness 接口：harness 类型、活动运行 steer / abort 辅助工具、OpenClaw 工具桥接辅助工具、工具进度格式化 / 详情辅助工具，以及尝试结果实用工具 |
+    | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助工具 |
+    | `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/runtime-fetch` | 具备 dispatcher 感知能力的运行时 fetch，不包含 proxy / guarded-fetch 导入 |
+    | `plugin-sdk/response-limit-runtime` | 有界响应体读取器，不包含宽泛的媒体运行时接口 |
     | `plugin-sdk/session-binding-runtime` | 当前会话绑定状态，不包含已配置绑定路由或配对存储 |
-    | `plugin-sdk/session-store-runtime` | 不引入宽泛配置写入 / 维护导入的会话存储读取辅助函数 |
-    | `plugin-sdk/context-visibility-runtime` | 不引入宽泛配置 / 安全导入的上下文可见性解析和补充上下文过滤 |
-    | `plugin-sdk/string-coerce-runtime` | 不依赖 markdown / logging 导入的窄范围原始记录 / 字符串强制转换与规范化辅助函数 |
-    | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 |
-    | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助函数 |
-    | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助函数 |
+    | `plugin-sdk/session-store-runtime` | session-store 读取辅助工具，不包含宽泛的配置写入 / 维护导入 |
+    | `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不包含宽泛的配置 / 安全导入 |
+    | `plugin-sdk/string-coerce-runtime` | 精简的原始 record / 字符串强制转换与规范化辅助工具，不包含 markdown / 日志导入 |
+    | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 |
+    | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 |
+    | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助工具 |
     | `plugin-sdk/directory-runtime` | 基于配置的目录查询 / 去重 |
     | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
   </Accordion>
@@ -217,64 +216,64 @@ x-i18n:
   <Accordion title="能力与测试子路径">
     | 子路径 | 关键导出 |
     | --- | --- |
-    | `plugin-sdk/media-runtime` | 共享的媒体获取 / 转换 / 存储辅助函数，以及媒体负载构建器 |
-    | `plugin-sdk/media-store` | 窄范围媒体存储辅助函数，例如 `saveMediaBuffer` |
-    | `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-core` | 共享的语音提供商类型、注册表、directive 和规范化辅助函数 |
-    | `plugin-sdk/realtime-transcription` | 实时转写提供商类型、注册表辅助函数以及共享 WebSocket 会话辅助函数 |
-    | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 |
+    | `plugin-sdk/media-runtime` | 共享媒体获取 / 转换 / 存储辅助工具，以及媒体载荷构建器 |
+    | `plugin-sdk/media-store` | 精简的媒体存储辅助工具，例如 `saveMediaBuffer` |
+    | `plugin-sdk/media-generation-runtime` | 共享媒体生成功能故障转移辅助工具、候选项选择和缺失模型消息 |
+    | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 |
+    | `plugin-sdk/text-runtime` | 共享文本 / Markdown / 日志辅助工具，例如对 assistant 可见文本的剥离、Markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 |
+    | `plugin-sdk/text-chunking` | 出站文本分块辅助工具 |
+    | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助工具 |
+    | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助工具 |
+    | `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助工具和共享 WebSocket 会话辅助工具 |
+    | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 |
     | `plugin-sdk/image-generation` | 图像生成提供商类型 |
-    | `plugin-sdk/image-generation-core` | 共享的图像生成类型、故障切换、认证和注册表辅助函数 |
+    | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助工具 |
     | `plugin-sdk/music-generation` | 音乐生成提供商 / 请求 / 结果类型 |
-    | `plugin-sdk/music-generation-core` | 共享的音乐生成类型、故障切换辅助函数、提供商查找和 model-ref 解析 |
+    | `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-path` | Webhook 路径规范化辅助函数 |
-    | `plugin-sdk/web-media` | 共享的远程 / 本地媒体加载辅助函数 |
-    | `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` |
+    | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 |
+    | `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助工具 |
+    | `plugin-sdk/webhook-path` | webhook 路径规范化辅助工具 |
+    | `plugin-sdk/web-media` | 共享远程 / 本地媒体加载辅助工具 |
+    | `plugin-sdk/zod` | 为插件 SDK 使用方重新导出的 `zod` |
     | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
   </Accordion>
 
   <Accordion title="Memory 子路径">
     | 子路径 | 关键导出 |
     | --- | --- |
-    | `plugin-sdk/memory-core` | bundled memory-core 辅助接口，用于 manager / config / file / CLI 辅助函数 |
+    | `plugin-sdk/memory-core` | bundled memory-core 辅助接口，用于 manager / config / file / CLI 辅助工具 |
     | `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时门面 |
     | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 |
-    | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding contract、注册表访问、本地提供商以及通用批处理 / 远程辅助函数 |
+    | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商，以及通用批处理 / 远程辅助工具 |
     | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 |
-    | `plugin-sdk/memory-core-host-engine-storage` | Memory host 存储 engine 导出 |
-    | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助函数 |
-    | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助函数 |
-    | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助函数 |
-    | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助函数 |
-    | `plugin-sdk/memory-core-host-status` | Memory host 状态辅助函数 |
-    | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助函数 |
-    | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助函数 |
-    | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助函数 |
-    | `plugin-sdk/memory-host-core` | 面向厂商中立的 memory host 核心运行时辅助函数别名 |
-    | `plugin-sdk/memory-host-events` | 面向厂商中立的 memory host 事件日志辅助函数别名 |
-    | `plugin-sdk/memory-host-files` | 面向厂商中立的 memory host 文件 / 运行时辅助函数别名 |
-    | `plugin-sdk/memory-host-markdown` | 面向 memory 邻接插件的共享托管 Markdown 辅助函数 |
-    | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活动 Memory 运行时门面 |
-    | `plugin-sdk/memory-host-status` | 面向厂商中立的 memory host 状态辅助函数别名 |
+    | `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 |
+    | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 |
+    | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 |
+    | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助工具 |
+    | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 |
+    | `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 |
+    | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 |
+    | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 |
+    | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助工具 |
+    | `plugin-sdk/memory-host-core` | 面向供应商中立的 memory host 核心运行时辅助工具别名 |
+    | `plugin-sdk/memory-host-events` | 面向供应商中立的 memory host 事件日志辅助工具别名 |
+    | `plugin-sdk/memory-host-files` | 面向供应商中立的 memory host 文件 / 运行时辅助工具别名 |
+    | `plugin-sdk/memory-host-markdown` | 面向 memory 邻接插件的共享托管 Markdown 辅助工具 |
+    | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活跃 Memory 运行时门面 |
+    | `plugin-sdk/memory-host-status` | 面向供应商中立的 memory host 状态辅助工具别名 |
     | `plugin-sdk/memory-lancedb` | bundled memory-lancedb 辅助接口 |
   </Accordion>
 
   <Accordion title="保留的 bundled-helper 子路径">
     | 家族 | 当前子路径 | 预期用途 |
     | --- | --- | --- |
-    | 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` | bundled browser 插件支持辅助函数（`browser-support` 仍然是兼容性 barrel） |
+    | 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` | bundled 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` | bundled Matrix 辅助 / 运行时接口 |
     | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | bundled LINE 辅助 / 运行时接口 |
     | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | bundled 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` | bundled 渠道兼容性 / 辅助接口 |
-    | 认证 / 插件专用辅助函数 | `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` | bundled 功能 / 插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
+    | 渠道特定辅助工具 | `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` | bundled 渠道兼容性 / 辅助接口 |
+    | 认证 / 插件特定辅助工具 | `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` | bundled 功能 / 插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
   </Accordion>
 </AccordionGroup>