chore(i18n): refresh zh-CN translations

2026-04-08 04:39:38 +00:00 · 2026-04-08 04:39:38 +00:00 · d5417a569c
commit d5417a569c
parent b082e97f33
2 changed files with 183 additions and 177 deletions
--- a/docs/zh-CN/concepts/qa-e2e-automation.md
+++ b/docs/zh-CN/concepts/qa-e2e-automation.md
@ -1,43 +1,43 @@
 ---
 read_when:
-    - 扩展 qa-lab 或 qa-channel 时
+    - 扩展 `qa-lab` 或 `qa-channel` 时
    - 添加仓库支持的 QA 场景时
-    - 围绕 Gateway 网关仪表板构建更高真实度的 QA 自动化时
-summary: 用于 qa-lab、qa-channel、种子场景和协议报告的私有 QA 自动化形态
+    - 围绕 Gateway 网关仪表板构建更高真实性的 QA 自动化时
+summary: 面向 `qa-lab`、`qa-channel`、种子场景和协议报告的私有 QA 自动化形态
 title: QA 端到端自动化
 x-i18n:
-    generated_at: "2026-04-07T22:41:21Z"
+    generated_at: "2026-04-08T04:39:08Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 3b4aa5acc8e77303f4045d4f04372494cae21b89d2fdaba856dbb4855ced9d27
+    source_hash: 57da147dc06abf9620290104e01a83b42182db1806514114fd9e8467492cda99
    source_path: concepts/qa-e2e-automation.md
    workflow: 15
 ---

 # QA 端到端自动化

-私有 QA 技术栈旨在以比单个单元测试更贴近真实渠道形态的方式来验证 OpenClaw。
+私有 QA 栈旨在以比单个单元测试更贴近真实渠道形态的方式来验证 OpenClaw。

 当前组成部分：

- `extensions/qa-channel`：合成消息渠道，包含私信、频道、线程、反应、编辑和删除等交互界面。
- `extensions/qa-lab`：调试器 UI 和 QA 总线，用于观察对话记录、注入入站消息，以及导出 Markdown 报告。
- `qa/`：用于启动任务和基线 QA 场景的仓库支持种子资源。
+- `extensions/qa-channel`：合成消息渠道，支持私信、频道、线程、反应、编辑和删除等交互面。
+- `extensions/qa-lab`：调试器 UI 和 QA 总线，用于观察转录内容、注入入站消息，以及导出 Markdown 报告。
+- `qa/`：为启动任务和基础 QA 场景提供的仓库支持种子资源。

-当前的 QA 操作流程是一个双窗格 QA 站点：
+当前的 QA 操作流程是一个双栏 QA 站点：

 - 左侧：带有智能体的 Gateway 网关仪表板（Control UI）。
- 右侧：QA Lab，显示类 Slack 风格的对话记录和场景计划。
+- 右侧：QA Lab，显示类似 Slack 的转录内容和场景计划。

-使用以下命令运行：
+运行方式：

 ```bash
 pnpm qa:lab:up
 ```

-这会构建 QA 站点，启动基于 Docker 的 Gateway 网关通道，并暴露 QA Lab 页面，供操作员或自动化循环为智能体分配 QA 任务、观察真实渠道行为，并记录哪些有效、哪些失败，或哪些仍被阻塞。
+这会构建 QA 站点，启动由 Docker 支持的 Gateway 网关通道，并暴露 QA Lab 页面。操作员或自动化循环可以在该页面中为智能体分配 QA 任务、观察真实渠道行为，并记录哪些内容已生效、失败了，或仍然受阻。

-如果你想更快地迭代 QA Lab UI，而不必每次都重建 Docker 镜像，可以使用绑定挂载的 QA Lab bundle 启动该技术栈：
+如果你想更快地迭代 QA Lab UI，而不必每次都重建 Docker 镜像，可以使用绑定挂载的 QA Lab bundle 启动整个栈：

 ```bash
 pnpm openclaw qa docker-build-image
@ -46,15 +46,16 @@ pnpm qa:lab:up:fast
 pnpm qa:lab:watch
 ```

-`qa:lab:up:fast` 会让 Docker 服务继续使用预构建镜像，并将 `extensions/qa-lab/web/dist` 绑定挂载到 `qa-lab` 容器中。`qa:lab:watch` 会在变更时重建该 bundle，并且当 QA Lab 资源哈希发生变化时，浏览器会自动重新加载。
+`qa:lab:up:fast` 会让 Docker 服务继续使用预构建镜像，并将 `extensions/qa-lab/web/dist` 绑定挂载到 `qa-lab` 容器中。`qa:lab:watch` 会在变更时重建该 bundle，而当 QA Lab 资源哈希发生变化时，浏览器会自动重新加载。

-## 仓库支持的种子资源
+## 仓库支持的种子

 种子资源位于 `qa/` 中：

- `qa/scenarios.md`
+- `qa/scenarios/index.md`
+- `qa/scenarios/*.md`

-这些内容有意保存在 git 中，以便人类和智能体都能看到 QA 计划。基线列表应保持足够广泛，以覆盖：
+这些内容有意保存在 git 中，这样人类和智能体都能看到 QA 计划。基础列表应保持足够广泛，以覆盖：

 - 私信和频道聊天
 - 线程行为
@ -62,22 +63,22 @@ pnpm qa:lab:watch
 - cron 回调
 - 记忆召回
 - 模型切换
- 子智能体切换交接
+- 子智能体移交
 - 读取仓库和读取文档
 - 一个小型构建任务，例如 Lobster Invaders

 ## 报告

 `qa-lab` 会根据观察到的总线时间线导出一份 Markdown 协议报告。
-该报告应回答：
+报告应回答：

- 哪些有效
- 哪些失败
- 哪些仍被阻塞
+- 哪些内容已生效
+- 哪些内容失败了
+- 哪些内容仍然受阻
 - 值得添加哪些后续场景

 ## 相关文档

 - [测试](/zh-CN/help/testing)
- [QA 渠道](/zh-CN/channels/qa-channel)
+- [QA Channel](/zh-CN/channels/qa-channel)
 - [仪表板](/web/dashboard)
--- a/docs/zh-CN/refactor/qa.md
+++ b/docs/zh-CN/refactor/qa.md
@ -1,63 +1,67 @@
 ---
 x-i18n:
-    generated_at: "2026-04-08T02:01:57Z"
+    generated_at: "2026-04-08T04:39:37Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 0e156cc8e2fe946a0423862f937754a7caa1fe7e6863b50a80bff49a1c86e1e8
+    source_hash: 4a9066b2a939c5a9ba69141d75405f0e8097997b523164340e2f0e9a0d5060dd
    source_path: refactor/qa.md
    workflow: 15
 ---

 # QA 重构

-状态：基础迁移已落地。
+状态：基础迁移已完成。

 ## 目标

-将 OpenClaw QA 从“定义分散”的模型迁移为单一事实来源：
+将 OpenClaw QA 从拆分定义模型迁移到单一事实来源：

 - 场景元数据
 - 发送给模型的提示词
 - 设置与清理
 - harness 逻辑
 - 断言与成功标准
- 产物与报告提示
+- 工件与报告提示

-理想的最终状态是：一个通用 QA harness 加载功能强大的场景定义文件，而不是将大多数行为硬编码在 TypeScript 中。
+期望的最终状态是一个通用 QA harness，它加载功能强大的场景定义文件，而不是将大部分行为硬编码在 TypeScript 中。

 ## 当前状态

-当前的主要事实来源位于 `qa/scenarios.md`。
+当前的主要事实来源现在位于 `qa/scenarios/index.md`，并且每个
+场景在 `qa/scenarios/*.md` 下各有一个文件。

 已实现：

- `qa/scenarios.md`
-  - 规范 QA 包
+- `qa/scenarios/index.md`
+  - 规范的 QA 包元数据
  - 操作员身份
  - 启动任务
+- `qa/scenarios/*.md`
+  - 每个场景对应一个 markdown 文件
  - 场景元数据
-  - handler 绑定
+  - 处理器绑定
+  - 场景专用执行配置
 - `extensions/qa-lab/src/scenario-catalog.ts`
-  - markdown 包解析器 + zod 校验
+  - markdown 包解析器 + zod 验证
 - `extensions/qa-lab/src/qa-agent-bootstrap.ts`
-  - 从 markdown 包渲染计划
+  - 根据 markdown 包渲染计划
 - `extensions/qa-lab/src/qa-agent-workspace.ts`
-  - 生成兼容性文件种子以及 `QA_SCENARIOS.md`
+  - 生成兼容性文件以及 `QA_SCENARIOS.md`
 - `extensions/qa-lab/src/suite.ts`
-  - 通过 markdown 定义的 handler 绑定选择可执行场景
- QA bus 协议 + UI
-  - 用于渲染图片 / 视频 / 音频 / 文件的通用内联附件
+  - 通过 markdown 定义的处理器绑定选择可执行场景
+- QA 总线协议 + UI
+  - 用于渲染图像 / 视频 / 音频 / 文件的通用内联附件

-仍然分散的部分：
+仍然拆分的表面：

 - `extensions/qa-lab/src/suite.ts`
-  - 仍然承载大部分可执行的自定义 handler 逻辑
+  - 仍然拥有大部分可执行的自定义处理器逻辑
 - `extensions/qa-lab/src/report.ts`
  - 仍然从运行时输出推导报告结构

-所以，事实来源的分散问题已经修复，但执行层仍然主要依赖 handler 支撑，而不是完全声明式。
+因此，事实来源拆分问题已经修复，但执行仍然主要依赖处理器支持，而不是完全声明式。

-## 真实的场景层长什么样
+## 真实的场景表面是什么样的

 阅读当前 suite 可以看出几类不同的场景。

@ -68,69 +72,69 @@ x-i18n:
 - 线程后续跟进
 - 模型切换
 - 审批后续执行
- reaction / edit / delete
+- 反应 / 编辑 / 删除

 ### 配置与运行时变更

- config patch skill disable
- config apply restart wake-up
- config restart capability flip
- runtime inventory drift check
+- config patch 技能禁用
+- config apply 重启唤醒
+- config 重启能力切换
+- 运行时清单漂移检查

 ### 文件系统与仓库断言

- source/docs discovery report
- build Lobster Invaders
- generated image artifact lookup
+- source / docs 发现报告
+- 构建 Lobster Invaders
+- 生成图像工件查找

-### 内存编排
+### 记忆编排

- memory recall
- 渠道上下文中的 memory tools
- memory failure fallback
- session memory ranking
- 线程 memory 隔离
- memory dreaming sweep
+- 记忆召回
+- 渠道上下文中的记忆工具
+- 记忆失败回退
+- 会话记忆排序
+- 线程记忆隔离
+- 记忆 dreaming sweep

 ### 工具与插件集成

- MCP plugin-tools call
- skill visibility
- skill hot install
- native image generation
- image roundtrip
- 从附件进行图片理解
+- MCP plugin-tools 调用
+- skill 可见性
+- skill 热安装
+- 原生图像生成
+- 图像往返
+- 来自附件的图像理解

 ### 多轮与多参与者

- subagent handoff
- subagent fanout synthesis
- restart recovery style flows
+- subagent 交接
+- subagent 扇出汇总
+- 重启恢复类流程

-这些分类很重要，因为它们会驱动 DSL 的需求。仅有“提示词 + 期望文本”的平面列表是不够的。
+这些类别很重要，因为它们决定 DSL 需求。仅有提示词 + 期望文本的平面列表是不够的。

 ## 方向

 ### 单一事实来源

-使用 `qa/scenarios.md` 作为编写时的单一事实来源。
+使用 `qa/scenarios/index.md` 加 `qa/scenarios/*.md` 作为编写时的事实来源。

-这个包应保持：
+该包应保持：

- 便于在评审中阅读
- 可被机器解析
- 足够丰富，能够驱动：
+- 在代码审查中便于人类阅读
+- 可供机器解析
+- 足够丰富，以驱动：
  - suite 执行
-  - QA 工作区 bootstrap
+  - QA 工作区引导
  - QA Lab UI 元数据
  - docs / discovery 提示词
  - 报告生成

 ### 首选编写格式

-使用 markdown 作为顶层格式，并在其中嵌入结构化 YAML。
+使用 markdown 作为顶层格式，内部嵌入结构化 YAML。

-推荐结构：
+推荐形状：

 - YAML frontmatter
  - id
@ -142,24 +146,24 @@ x-i18n:
  - model / provider overrides
  - prerequisites
 - prose sections
-  - objective
-  - notes
-  - debugging hints
+  - 目标
+  - 注释
+  - 调试提示
 - fenced YAML blocks
  - setup
  - steps
  - assertions
  - cleanup

-这样可以带来：
+这样可以得到：

- 比庞大的 JSON 更适合 PR 阅读
- 比纯 YAML 提供更丰富的上下文
- 严格解析和 zod 校验
+- 比庞大的 JSON 更好的 PR 可读性
+- 比纯 YAML 更丰富的上下文
+- 严格解析与 zod 验证

-原始 JSON 仅可作为中间生成格式接受。
+原始 JSON 仅在作为中间生成形式时可接受。

-## 提议的场景文件结构
+## 拟议的场景文件形状

 示例：

@ -232,9 +236,9 @@ Verify generated media is reattached on the follow-up turn.
 ```
 ````

-## DSL 必须覆盖的 runner 能力
+## 该 DSL 必须覆盖的运行器能力

-基于当前 suite，通用 runner 需要的不仅仅是提示词执行。
+根据当前 suite，通用运行器需要的不只是提示词执行。

 ### 环境与设置操作

@ -261,7 +265,7 @@ Verify generated media is reattached on the follow-up turn.
 - `tools.effective`
 - `skills.status`

-### 文件与产物操作
+### 文件与工件操作

 - `file.write`
 - `file.read`
@ -270,7 +274,7 @@ Verify generated media is reattached on the follow-up turn.
 - `artifact.captureGeneratedImage`
 - `artifact.capturePath`

-### memory 与 cron 操作
+### 记忆与 cron 操作

 - `memory.indexForce`
 - `memory.searchCli`
@ -300,48 +304,48 @@ Verify generated media is reattached on the follow-up turn.
 - `cron.managedPresent`
 - `artifact.exists`

-## 变量与产物引用
+## 变量与工件引用

-DSL 必须支持保存输出并在后续引用。
+该 DSL 必须支持已保存输出及其后续引用。

 当前 suite 中的示例：

- 创建一个 thread，然后复用 `threadId`
- 创建一个 session，然后复用 `sessionKey`
- 生成一张图片，然后在下一轮将该文件作为附件附上
- 生成一个 wake marker 字符串，然后断言它稍后会出现
+- 创建一个线程，然后复用 `threadId`
+- 创建一个会话，然后复用 `sessionKey`
+- 生成一张图像，然后在下一轮附加该文件
+- 生成一个唤醒标记字符串，然后断言它稍后会出现

 所需能力：

 - `saveAs`
 - `${vars.name}`
 - `${artifacts.name}`
- 针对路径、session key、thread id、marker、tool 输出的强类型引用
+- 路径、会话键、线程 id、标记、工具输出的类型化引用

-如果没有变量支持，harness 就会继续把场景逻辑泄漏回 TypeScript 中。
+如果没有变量支持，harness 将继续把场景逻辑泄漏回 TypeScript。

-## 哪些应保留为逃生口
+## 哪些内容应保留为逃生口

-在第一阶段，实现一个完全纯粹的声明式 runner 并不现实。
+在第 1 阶段，实现一个完全纯声明式的运行器并不现实。

-有些场景天然就是高度编排型的：
+有些场景本质上就是高度依赖编排的：

- memory dreaming sweep
- config apply restart wake-up
- config restart capability flip
- 按时间戳 / 路径解析 generated image artifact
- discovery-report evaluation
+- 记忆 dreaming sweep
+- config apply 重启唤醒
+- config 重启能力切换
+- 依据时间戳 / 路径解析生成图像工件
+- discovery-report 评估

-这些场景目前应继续使用显式的自定义 handler。
+这些场景目前应继续使用显式自定义处理器。

 推荐规则：

- 85–90% 声明式
- 剩余困难部分使用显式 `customHandler` 步骤
- 仅允许具名且有文档说明的自定义 handler
+- 85 - 90% 声明式
+- 对于剩余困难部分，使用显式 `customHandler` 步骤
+- 仅允许具名且有文档说明的自定义处理器
 - 场景文件中不允许匿名内联代码

-这样可以保持通用引擎整洁，同时仍能持续推进。
+这样可以保持通用引擎整洁，同时仍然允许推进工作。

 ## 架构变更

@ -350,30 +354,31 @@ DSL 必须支持保存输出并在后续引用。
 场景 markdown 已经是以下内容的事实来源：

 - suite 执行
- 工作区 bootstrap 文件
+- 工作区引导文件
 - QA Lab UI 场景目录
 - 报告元数据
 - discovery 提示词

-生成的兼容性内容：
+已生成的兼容内容：

- 种子工作区仍包含 `QA_KICKOFF_TASK.md`
- 种子工作区仍包含 `QA_SCENARIO_PLAN.md`
+- 种子工作区仍然包含 `QA_KICKOFF_TASK.md`
+- 种子工作区仍然包含 `QA_SCENARIO_PLAN.md`
 - 种子工作区现在还包含 `QA_SCENARIOS.md`

 ## 重构计划

-### Phase 1：loader 与 schema
+### 第 1 阶段：加载器与 schema

 已完成。

- 添加了 `qa/scenarios.md`
- 添加了针对具名 markdown YAML 包内容的解析器
- 使用 zod 进行了校验
- 将各个消费者切换为使用已解析的包
- 移除了仓库级 `qa/seed-scenarios.json` 和 `qa/QA_KICKOFF_TASK.md`
+- 添加了 `qa/scenarios/index.md`
+- 将场景拆分到 `qa/scenarios/*.md`
+- 为具名 markdown YAML 包内容添加了解析器
+- 使用 zod 进行验证
+- 将消费者切换为使用已解析的包
+- 删除了仓库级别的 `qa/seed-scenarios.json` 和 `qa/QA_KICKOFF_TASK.md`

-### Phase 2：通用引擎
+### 第 2 阶段：通用引擎

 - 将 `extensions/qa-lab/src/suite.ts` 拆分为：
  - loader
@ -383,53 +388,53 @@ DSL 必须支持保存输出并在后续引用。
  - custom handlers
 - 保留现有辅助函数作为引擎操作

-交付物：
+交付成果：

- 引擎可执行简单的声明式场景
+- 引擎执行简单的声明式场景

-先从主要是“提示词 + 等待 + 断言”的场景开始：
+先从主要是 prompt + wait + assert 的场景开始：

 - 线程后续跟进
- 从附件进行图片理解
+- 来自附件的图像理解
 - skill 可见性与调用
 - 渠道基线

-交付物：
+交付成果：

 - 第一批真正由 markdown 定义的场景通过通用引擎发布

-### Phase 4：迁移中等复杂度场景
+### 第 4 阶段：迁移中等复杂度场景

- image generation roundtrip
- 渠道上下文中的 memory tools
- session memory ranking
- subagent handoff
- subagent fanout synthesis
+- 图像生成往返
+- 渠道上下文中的记忆工具
+- 会话记忆排序
+- subagent 交接
+- subagent 扇出汇总

-交付物：
+交付成果：

- 变量、产物、工具断言、request-log 断言得到验证
+- 变量、工件、工具断言、请求日志断言得到验证

-### Phase 5：困难场景继续使用自定义 handler
+### 第 5 阶段：将复杂场景保留在自定义处理器上

- memory dreaming sweep
- config apply restart wake-up
- config restart capability flip
- runtime inventory drift
+- 记忆 dreaming sweep
+- config apply 重启唤醒
+- config 重启能力切换
+- 运行时清单漂移

-交付物：
+交付成果：

- 保持相同的编写格式，但在需要时使用显式 custom-step block
+- 保持相同的编写格式，但在需要时使用显式自定义步骤块

-### Phase 6：删除硬编码的场景映射
+### 第 6 阶段：删除硬编码场景映射

-当包覆盖率足够好之后：
+一旦包覆盖率足够高：

- 移除 `extensions/qa-lab/src/suite.ts` 中大部分按场景分支的 TypeScript 逻辑
+- 移除 `extensions/qa-lab/src/suite.ts` 中大部分按场景区分的 TypeScript 分支

 ## Fake Slack / 富媒体支持

-当前 QA bus 以文本为主。
+当前 QA 总线以文本优先。

 相关文件：

@ -439,17 +444,17 @@ DSL 必须支持保存输出并在后续引用。
 - `extensions/qa-lab/src/bus-server.ts`
 - `extensions/qa-lab/web/src/ui-render.ts`

-当前 QA bus 支持：
+如今 QA 总线支持：

 - 文本
- reactions
- threads
+- 反应
+- 线程

-它还不能对内联媒体附件建模。
+它尚未对内联媒体附件建模。

-### 所需的传输契约
+### 所需传输契约

-添加一个通用 QA bus 附件模型：
+添加一个通用 QA 总线附件模型：

 ```ts
 type QaBusAttachment = {
@ -468,7 +473,7 @@ type QaBusAttachment = {
 };
 ```

-然后为以下类型添加 `attachments?: QaBusAttachment[]`：
+然后向以下类型添加 `attachments?: QaBusAttachment[]`：

 - `QaBusMessage`
 - `QaBusInboundMessageInput`
@ -476,59 +481,59 @@ type QaBusAttachment = {

 ### 为什么要先做通用模型

-不要构建一个仅限 Slack 的媒体模型。
+不要构建仅适用于 Slack 的媒体模型。

-而应采用：
+而应使用：

 - 一个通用 QA 传输模型
- 在其之上构建多个渲染器
-  - 当前 QA Lab chat
+- 在其上构建多个渲染器
+  - 当前 QA Lab 聊天
  - 未来的 fake Slack web
  - 任何其他 fake transport 视图

 这样可以避免重复逻辑，并让媒体场景保持与传输层无关。

-### 所需的 UI 工作
+### 所需 UI 工作

-更新 QA UI，使其能够渲染：
+更新 QA UI 以渲染：

- 内联图片预览
+- 内联图像预览
 - 内联音频播放器
 - 内联视频播放器
 - 文件附件 chip

-当前 UI 已经可以渲染 threads 和 reactions，因此附件渲染应能叠加到同一套消息卡片模型上。
+当前 UI 已经可以渲染线程和反应，因此附件渲染应能叠加到同一消息卡片模型上。

-### 媒体传输启用后的场景工作
+### 媒体传输启用的场景工作

-一旦附件可以通过 QA bus 流转，我们就可以添加更丰富的 fake-chat 场景：
+一旦附件能通过 QA 总线流转，我们就可以添加更丰富的 fake-chat 场景：

- fake Slack 中的内联图片回复
+- fake Slack 中的内联图像回复
 - 音频附件理解
 - 视频附件理解
 - 混合附件顺序
- 保留媒体的 thread reply
+- 保留媒体的线程回复

 ## 建议

-下一块实现工作应当是：
+下一个实现阶段应是：

-1. 添加 markdown 场景 loader + zod schema
+1. 添加 markdown 场景加载器 + zod schema
 2. 从 markdown 生成当前目录
-3. 先迁移少量简单场景
-4. 添加通用 QA bus 附件支持
-5. 在 QA UI 中渲染内联图片
+3. 先迁移几个简单场景
+4. 添加通用 QA 总线附件支持
+5. 在 QA UI 中渲染内联图像
 6. 然后扩展到音频和视频

-这是同时验证两个目标的最小路径：
+这是能够同时验证两个目标的最小路径：

 - 通用的 markdown 定义 QA
- 更丰富的 fake messaging surfaces
+- 更丰富的 fake messaging 表面

-## 开放问题
+## 未决问题

 - 场景文件是否应允许嵌入带变量插值的 markdown 提示词模板
- setup / cleanup 应该是具名 section，还是仅仅使用有序 action 列表
- artifact 引用应在 schema 中强类型化，还是基于字符串
- custom handlers 应放在一个 registry 中，还是按 surface 分 registry
- 在迁移期间，生成的 JSON 兼容性文件是否应继续保留并纳入版本控制
+- setup / cleanup 应该是具名章节，还是仅作为有序操作列表
+- 工件引用在 schema 中应为强类型，还是基于字符串
+- 自定义处理器应放在一个 registry 中，还是按 surface 分 registry
+- 迁移期间生成的 JSON 兼容文件是否应继续纳入版本控制