Docs: update zh-CN translations and pipeline

What:
- update zh-CN glossary, TM, and translator prompt
- regenerate zh-CN docs and apply targeted fixes
- add zh-CN AGENTS pipeline guidance

Why:
- address terminology/spacing feedback from #6995

Tests:
- pnpm build && pnpm check && pnpm test
This commit is contained in:
Josh Palmer
2026-02-03 13:23:00 -08:00
parent 9f03791aa9
commit a3ec2d0734
228 changed files with 10651 additions and 10475 deletions
+102 -102
View File
@@ -1,12 +1,12 @@
---
read_when:
- 设计执行主机路由或执行审批
- 设计 exec 主机路由或 exec 批准
- 实现节点运行器 + UI IPC
- 添加执行主机安全模式和斜杠命令
summary: 重构计划:执行主机路由、节点批和无头运行器
title: 执行主机重构
- 添加 exec 主机安全模式和斜杠命令
summary: 重构计划:exec 主机路由、节点批和无头运行器
title: Exec 主机重构
x-i18n:
generated_at: "2026-02-01T21:36:56Z"
generated_at: "2026-02-03T07:54:43Z"
model: claude-opus-4-5
provider: pi
source_hash: 53a9059cbeb1f3f1dbb48c2b5345f88ca92372654fef26f8481e651609e45e3a
@@ -14,49 +14,49 @@ x-i18n:
workflow: 15
---
# 执行主机重构计划
# Exec 主机重构计划
## 目标
- 添加 `exec.host` + `exec.security` 以在 **sandbox**、**gateway** 和 **node** 之间路由执行。
- 保持默认**安全**:除非明确启用,否则不进行跨主机执行。
- 将执行拆分为**无头运行器服务**通过本地 IPC 提供可选 UImacOS 应用)。
- 提供**智能体**策略、允许列表、询问模式和节点绑定。
- 支持与允许列表*配合*或*不配合*使用的**询问模式**。
- 添加 `exec.host` + `exec.security` 以在**沙箱**、**Gateway 网关**和**节点**之间路由执行。
- 保持默认**安全**:除非明确启用,否则不进行跨主机执行。
- 将执行拆分为**无头运行器服务**,通过本地 IPC 连接可选 UImacOS 应用)。
- 提供**智能体**策略、允许列表、询问模式和节点绑定。
- 支持*与*或*不与*允许列表一起使用的**询问模式**。
- 跨平台:Unix socket + token 认证(macOS/Linux/Windows 一致性)。
## 非目标
- 不进行旧版允许列表迁移或旧版 schema 支持。
- 不为节点执行提供 PTY/流式输出(仅支持聚合输出)。
- 不在现有 Bridge + Gateway网关之外新增网络层。
- 无遗留允许列表迁移或遗留 schema 支持。
- 节点 exec 无 PTY/流式传输(仅聚合输出)。
- 现有 Bridge + Gateway 网关外无新网络层。
## 决(已锁定)
## 决(已锁定)
- **配置键:**`exec.host` + `exec.security`(允许智能体覆盖)。
- **提**保留 `/elevated` 作为 gateway 完全访问的别名。
- **询问默认**`on-miss`
- **批存储:**`~/.openclaw/exec-approvals.json`JSON不迁移旧版)。
- **运行器:**无头系统服务;UI 应用托管 Unix socket 用于批。
- **节点身份:**使用现有 `nodeId`
- **Socket 认证:**Unix socket + token(跨平台);后续需要时再拆分。
- **节点主机状态:**`~/.openclaw/node.json`(节点 ID + 配对 token)。
- **macOS 执行主机:**在 macOS 应用内运行 `system.run`;节点主机服务通过本地 IPC 转发请求。
- **不使用 XPC helper**坚持使用 Unix socket + token + 对检查。
- **配置键:** `exec.host` + `exec.security`(允许智能体覆盖)。
- **提** 保留 `/elevated` 作为 Gateway 网关完全访问的别名。
- **询问默认:** `on-miss`
- **批存储:** `~/.openclaw/exec-approvals.json`JSON无遗留迁移)。
- **运行器:** 无头系统服务;UI 应用托管 Unix socket 用于批
- **节点身份:** 使用现有 `nodeId`
- **Socket 认证:** Unix socket + token(跨平台);如需要稍后拆分。
- **节点主机状态:** `~/.openclaw/node.json`(节点 id + 配对 token)。
- **macOS exec 主机:** 在 macOS 应用内运行 `system.run`;节点主机服务通过本地 IPC 转发请求。
- ** XPC helper** 坚持使用 Unix socket + token + 对检查。
## 核心概念
## 关键概念
### 主机
- `sandbox`Docker 执行(当前行为)。
- `gateway`:在 gateway 主机上执行。
- `sandbox`Docker exec(当前行为)。
- `gateway`:在 Gateway 网关主机上执行。
- `node`:通过 Bridge 在节点运行器上执行(`system.run`)。
### 安全模式
- `deny`:始终阻止。
- `allowlist`:仅允许匹配项。
- `full`:允许所有(等同于提模式)。
- `full`:允许一切(等同于提模式)。
### 询问模式
@@ -64,30 +64,30 @@ x-i18n:
- `on-miss`:仅在允许列表不匹配时询问。
- `always`:每次都询问。
询问与允许列表**相互独立**;允许列表可与 `always``on-miss` 配合使用。
询问**独立**允许列表;允许列表可与 `always``on-miss` 一起使用。
### 策略解析(每次执行)
1. 解析 `exec.host`(工具参数 → 智能体覆盖 → 全局默认)。
1. 解析 `exec.host`(工具参数 → 智能体覆盖 → 全局默认)。
2. 解析 `exec.security``exec.ask`(相同优先级)。
3. 如果主机是 `sandbox`使用本地沙箱执行。
3. 如果主机是 `sandbox`继续本地沙箱执行。
4. 如果主机是 `gateway``node`,在该主机上应用安全 + 询问策略。
## 默认安全
- 默认 `exec.host = sandbox`
- `gateway``node` 默认 `exec.security = deny`
- 默认 `exec.ask = on-miss`(仅在安全策略允许时相关)。
- 如果未设置节点绑定,**智能体可以向任何节点**,但仅在策略允许时。
- 默认 `exec.ask = on-miss`(仅在安全允许时相关)。
- 如果未设置节点绑定,**智能体可以向任何节点**,但仅在策略允许时。
## 配置接口
## 配置表面
### 工具参数
- `exec.host`(可选):`sandbox | gateway | node`
- `exec.security`(可选):`deny | allowlist | full`
- `exec.ask`(可选):`off | on-miss | always`
- `exec.node`(可选):当 `host=node` 时使用的节点 ID/名称。
- `exec.node`(可选):当 `host=node` 时使用的节点 id/名称。
### 配置键(全局)
@@ -96,7 +96,7 @@ x-i18n:
- `tools.exec.ask`
- `tools.exec.node`(默认节点绑定)
### 配置键(智能体)
### 配置键(智能体)
- `agents.list[].tools.exec.host`
- `agents.list[].tools.exec.security`
@@ -106,17 +106,17 @@ x-i18n:
### 别名
- `/elevated on` = 为智能体会话设置 `tools.exec.host=gateway``tools.exec.security=full`
- `/elevated off` = 为智能体会话恢复之前的执行设置。
- `/elevated off` = 为智能体会话恢复之前的 exec 设置。
## 批存储(JSON
## 批存储(JSON
路径:`~/.openclaw/exec-approvals.json`
用途:
- **执行主机**gateway 或节点运行器)的本地策略 + 允许列表。
- **执行主机**Gateway 网关或节点运行器)的本地策略 + 允许列表。
- 无 UI 可用时的询问回退。
- UI 客户端的 IPC 凭
- UI 客户端的 IPC 凭
建议的 schemav1):
@@ -151,8 +151,8 @@ x-i18n:
注意事项:
- 不支持旧版允许列表格式。
- `askFallback` 仅在需要询问但无 UI 可达时生效
- 无遗留允许列表格式。
- `askFallback` 仅在需要 `ask` 且无法访问 UI 时应用
- 文件权限:`0600`
## 运行器服务(无头)
@@ -161,12 +161,12 @@ x-i18n:
- 在本地强制执行 `exec.security` + `exec.ask`
- 执行系统命令并返回输出。
- 发送 Bridge 事件用于执行生命周期(可选但建议启用)。
- 为 exec 生命周期发出 Bridge 事件(可选但推荐)。
### 服务生命周期
- macOS 上 Launchd/daemonLinux/Windows 上系统服务。
- 批 JSON 执行主机本地文件
- macOS 上 Launchd/daemonLinux/Windows 上系统服务。
- JSON 执行主机本地
- UI 托管本地 Unix socket;运行器按需连接。
## UI 集成(macOS 应用)
@@ -175,26 +175,26 @@ x-i18n:
- Unix socket 位于 `~/.openclaw/exec-approvals.sock`0600)。
- Token 存储在 `exec-approvals.json`0600)中。
-检查:仅限相同 UID。
- 质询/响应:nonce + HMAC(token, request-hash) 防止重放。
- 短 TTL(例如 10+ 最大负载 + 速率限制。
-检查:仅同 UID。
- 挑战/响应:nonce + HMAC(token, request-hash) 防止重放。
- 短 TTL(例如 10s+ 最大负载 + 速率限制。
### 询问流程(macOS 应用执行主机)
### 询问流程(macOS 应用 exec 主机)
1. 节点服务从 gateway 接收 `system.run`
2. 节点服务连接本地 socket 并发送提示/执行请求。
3. 应用验证对 + token + HMAC + TTL,然后在需要时显示对话框。
1. 节点服务从 Gateway 网关接收 `system.run`
2. 节点服务连接本地 socket 并发送提示/exec 请求。
3. 应用验证对 + token + HMAC + TTL,然后在需要时显示对话框。
4. 应用在 UI 上下文中执行命令并返回输出。
5. 节点服务将输出返回给 gateway。
5. 节点服务将输出返回给 Gateway 网关
如果 UI 不可用
如果 UI 缺失
- 应用 `askFallback``deny|allowlist|full`)。
### 图示(SCI
```
Agent -> Gateway网关 -> Bridge -> Node Service (TS)
Agent -> Gateway -> Bridge -> Node Service (TS)
| IPC (UDS + token + HMAC + TTL)
v
Mac App (UI + TCC + system.run)
@@ -202,122 +202,122 @@ Agent -> Gateway网关 -> Bridge -> Node Service (TS)
## 节点身份 + 绑定
- 使用 Bridge 配对中现有 `nodeId`
- 使用 Bridge 配对中现有 `nodeId`
- 绑定模型:
- `tools.exec.node` 将智能体限制特定节点。
- 如果未设置,智能体可以选择任何节点(策略仍强制执行默认值)。
- `tools.exec.node` 将智能体限制特定节点。
- 如果未设置,智能体可以选择任何节点(策略仍强制执行默认值)。
- 节点选择解析:
- `nodeId` 精确匹配
- `displayName`(规范化)
- `remoteIp`
- `nodeId` 前缀(>= 6 字符)
- `nodeId` 前缀(>= 6 字符)
## 事件
### 谁可以看到事件
### 谁看到事件
- 系统事件是**会话**的,在下一个提示时示给智能体。
- 存储在 gateway 内存队列中(`enqueueSystemEvent`)。
- 系统事件是**会话**的,在下一个提示时示给智能体。
- 存储在 Gateway 网关内存队列中(`enqueueSystemEvent`)。
### 事件文本
- `Exec started (node=<id>, id=<runId>)`
- `Exec finished (node=<id>, id=<runId>, code=<code>)` + 可选输出尾部
- `Exec finished (node=<id>, id=<runId>, code=<code>)` + 可选输出尾部
- `Exec denied (node=<id>, id=<runId>, <reason>)`
### 传输
方案 A(推荐):
选项 A(推荐):
- 运行器发送 Bridge `event``exec.started` / `exec.finished`
- Gateway网关 `handleBridgeEvent`映射 `enqueueSystemEvent`
- Gateway 网关 `handleBridgeEvent`这些映射 `enqueueSystemEvent`
方案 B
选项 B
- Gateway网关 `exec` 工具直接处理生命周期(仅同步)。
- Gateway 网关 `exec` 工具直接处理生命周期(仅同步)。
## 执行流程
## Exec 流程
### Sandbox 主机
### 沙箱主机
- 现有 `exec` 行为(Docker 或沙箱时的主机执行)。
- 现有 `exec` 行为(Docker 或沙箱时的主机)。
- 仅在非沙箱模式下支持 PTY。
### Gateway网关主机
### Gateway 网关主机
- Gateway网关进程在自身机器上执行。
- Gateway 网关进程在其自己的机器上执行。
- 强制执行本地 `exec-approvals.json`(安全/询问/允许列表)。
### Node 主机
### 节点主机
- Gateway网关通过 `node.invoke` 调用 `system.run`
- 运行器强制执行本地批。
- Gateway 网关调用 `node.invoke` 配合 `system.run`
- 运行器强制执行本地批
- 运行器返回聚合的 stdout/stderr。
- 可选的 Bridge 事件用于启动/完成/拒绝。
- 可选的 Bridge 事件用于开始/完成/拒绝。
## 输出限
## 输出
- stdout+stderr 合计上限为 **200k**;事件保留**尾部 20k**。
- 截断时添加明确后缀(例如 `"… (truncated)"`)。
- 组合 stdout+stderr 上限为 **200k**事件保留**尾部 20k**。
- 使用清晰的后缀截断(例如 `"… (truncated)"`)。
## 斜杠命令
- `/exec host=<sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>`
- 智能体、会话覆盖;除非通过配置保存,否则持久
- `/elevated on|off|ask|full`作为 `host=gateway security=full` 的快捷方式(`full` 跳过批)。
- 智能体、会话覆盖;除非通过配置保存,否则持久。
- `/elevated on|off|ask|full`然是 `host=gateway security=full` 的快捷方式(`full` 跳过批)。
## 跨平台方案
- 运行器服务是可移植的执行目标。
- UI 是可选的;如果不可用,则应用 `askFallback`
- Windows/Linux 支持相同的批 JSON + socket 协议。
- UI 是可选的;如果缺失,应用 `askFallback`
- Windows/Linux 支持相同的批 JSON + socket 协议。
## 实阶段
## 实阶段
### 阶段 1:配置 + 执行路由
### 阶段 1:配置 + exec 路由
- 添加 `exec.host``exec.security``exec.ask``exec.node` 配置 schema。
- 更新工具管道以遵 `exec.host`
- `exec.host``exec.security``exec.ask``exec.node` 添加配置 schema。
- 更新工具管道以遵 `exec.host`
- 添加 `/exec` 斜杠命令并保留 `/elevated` 别名。
### 阶段 2批存储 + gateway 强制执行
### 阶段 2:批存储 + Gateway 网关强制执行
- 实现 `exec-approvals.json`器。
- 实现 `exec-approvals.json`取器/写入器。
-`gateway` 主机强制执行允许列表 + 询问模式。
- 添加输出限
- 添加输出限。
### 阶段 3:节点运行器强制执行
- 更新节点运行器以强制执行允许列表 + 询问。
- 添加 Unix socket 提示桥接到 macOS 应用 UI。
- `askFallback`
- `askFallback`
### 阶段 4:事件
- 添加节点 → gateway Bridge 事件用于执行生命周期
- 为 exec 生命周期添加节点 → Gateway 网关 Bridge 事件。
- 映射到 `enqueueSystemEvent` 用于智能体提示。
### 阶段 5UI 完善
- Mac 应用:允许列表编辑器、智能体切换器、询问策略 UI。
- Mac 应用:允许列表编辑器、智能体切换器、询问策略 UI。
- 节点绑定控制(可选)。
## 测试计划
- 单元测试:允许列表匹配(glob + 大小写不敏感)。
- 单元测试:允许列表匹配(glob + 不区分大小写)。
- 单元测试:策略解析优先级(工具参数 → 智能体覆盖 → 全局)。
- 集成测试:节点运行器拒绝/允许/询问流程。
- Bridge 事件测试:节点事件 → 系统事件路由。
## 未解决风险
## 开放风险
- UI 不可用:确保 `askFallback` 被正确执行
- 长时间运行的命令:依赖超时 + 输出限
- 多节点歧义:除非有节点绑定或明确的节点参数,否则报错。
- UI 不可用:确保遵守 `askFallback`
- 长时间运行的命令:依赖超时 + 输出限。
- 多节点歧义:除非有节点绑定或显式节点参数,否则报错。
## 相关文档
- [执行工具](/tools/exec)
- [执行](/tools/exec-approvals)
- [Exec 工具](/tools/exec)
- [执行批](/tools/exec-approvals)
- [节点](/nodes)
- [模式](/tools/elevated)
- [模式](/tools/elevated)