chore(i18n): refresh zh-CN translations

2026-04-17 15:09:01 +00:00 · 2026-04-17 15:09:01 +00:00 · c168cbbdb1
commit c168cbbdb1
parent f32814642a
3 changed files with 575 additions and 579 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 场景
-    - 围绕 Gateway 网关仪表板构建更高真实性的 QA 自动化
-summary: 用于 qa-lab、qa-channel、种子场景和协议报告的私有 QA 自动化结构
+    - 添加仓库支持的 QA 场景
+    - 围绕 Gateway 网关仪表板构建更高真实度的 QA 自动化
+summary: qa-lab、qa-channel、种子场景和协议报告的私有 QA 自动化形态
 title: QA 端到端自动化
 x-i18n:
-    generated_at: "2026-04-17T01:26:34Z"
+    generated_at: "2026-04-17T15:05:29Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0
+    source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4
    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 站点：

 - 左侧：带有智能体的 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,64 +46,67 @@ 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 资源哈希发生变化时，浏览器会自动重新加载。

-如果你想运行一个基于真实传输的 Matrix 烟雾测试通道，请执行：
+如果要运行一个传输层真实的 Matrix 冒烟测试通道，请执行：

 ```bash
 pnpm openclaw qa matrix
 ```

-该通道会在 Docker 中预配一个一次性的 Tuwunel homeserver，注册临时的驱动、SUT 和观察者用户，创建一个私有房间，然后在 QA Gateway 网关子进程中运行真实的 Matrix 插件。这个实时传输通道会将子配置限定在被测传输范围内，因此 Matrix 会在子配置中不包含 `qa-channel` 的情况下运行。它会将结构化报告产物以及合并后的 stdout/stderr 日志写入所选的 Matrix QA 输出目录。若还想捕获外层 `scripts/run-node.mjs` 的构建/启动输出，可将 `OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` 设置为仓库内的某个日志文件路径。
+该通道会在 Docker 中配置一个一次性的 Tuwunel homeserver，注册临时的驱动端、SUT 和观察者用户，创建一个私有房间，然后在 QA Gateway 网关子进程中运行真实的 Matrix 插件。这个实时传输测试通道会将子进程配置限定在被测传输协议范围内，因此 Matrix 会在不包含 `qa-channel` 的子进程配置下运行。它会将结构化报告产物以及合并后的 stdout/stderr 日志写入所选的 Matrix QA 输出目录。若还要捕获外层 `scripts/run-node.mjs` 的构建/启动输出，请将 `OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` 设置为一个仓库内本地日志文件路径。

-如果你想运行一个基于真实传输的 Telegram 烟雾测试通道，请执行：
+如果要运行一个传输层真实的 Telegram 冒烟测试通道，请执行：

 ```bash
 pnpm openclaw qa telegram
 ```

-该通道会面向一个真实的私有 Telegram 群组，而不是预配一次性服务器。它要求设置 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`，并要求两个不同的机器人位于同一个私有群组中。SUT 机器人必须具有 Telegram 用户名，而当两个机器人都在 `@BotFather` 中启用了 Bot-to-Bot Communication Mode 时，机器人之间的观察效果最佳。
+该通道会针对一个真实的私有 Telegram 群组，而不是配置一次性服务器。它要求设置 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`，并且需要两个不同的机器人位于同一个私有群组中。SUT 机器人必须具有 Telegram 用户名，并且当两个机器人都在 `@BotFather` 中启用了 Bot-to-Bot Communication Mode 时，机器人间观察效果最佳。

-实时传输通道现在共享一套更小的统一契约，而不是每条通道各自发明自己的场景列表结构：
+实时传输测试通道现在共享同一个更小的契约，而不是各自定义自己的场景列表结构：

-`qa-channel` 仍然是覆盖面广泛的合成产品行为测试套件，不属于实时传输覆盖矩阵的一部分。
+`qa-channel` 仍然是覆盖面更广的合成产品行为测试套件，不属于实时传输覆盖矩阵的一部分。

-| 通道 | Canary | 提及门控 | allowlist 拦截 | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | 表情回应观察 | 帮助命令 |
-| ---- | ------ | -------- | -------------- | -------- | -------- | -------- | -------- | ------------ | -------- |
-| Matrix | x | x | x | x | x | x | x | x |  |
-| Telegram | x |  |  |  |  |  |  |  | x |
+| 通道 | Canary | 提及门控 | Allowlist 拦截 | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | 表情回应观察 | Help 命令 |
+| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ |
+| Matrix   | x      | x              | x               | x               | x              | x                | x                | x                    |              |
+| Telegram | x      |                |                 |                 |                |                  |                  |                      | x            |

-这使 `qa-channel` 保持为广泛的产品行为测试套件，而 Matrix、Telegram 以及未来的实时传输则共享一份明确的传输契约检查清单。
+这样可以让 `qa-channel` 继续作为广泛的产品行为测试套件，而 Matrix、Telegram 以及未来的实时传输协议则共享同一个明确的传输契约检查清单。

-如果你想运行一个一次性的 Linux VM 通道，并且不把 Docker 纳入 QA 路径，请执行：
+如果要运行一个一次性的 Linux VM 测试通道，并且不把 Docker 引入 QA 路径中，请执行：

 ```bash
 pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
 ```

-这会启动一个全新的 Multipass 来宾实例，在来宾中安装依赖、构建 OpenClaw、运行 `qa suite`，然后把常规 QA 报告和摘要复制回主机上的 `.artifacts/qa-e2e/...`。
-它会复用与主机上 `qa suite` 相同的场景选择行为。
-主机和 Multipass 的 suite 运行默认都会并行执行多个已选场景，并为每个场景使用隔离的 Gateway 网关 worker，最多 64 个 worker 或已选场景数，以较小者为准。使用 `--concurrency <count>` 可调整 worker 数量，或使用 `--concurrency 1` 进行串行执行。
-实时运行会转发适合来宾环境使用的受支持 QA 凭证输入：基于环境变量的提供商密钥、QA 实时提供商配置路径，以及在存在时的 `CODEX_HOME`。请将 `--output-dir` 保持在仓库根目录下，以便来宾能够通过挂载的工作区回写结果。
+这会启动一个全新的 Multipass guest，在 guest 内安装依赖、构建 OpenClaw、运行 `qa suite`，然后将常规 QA 报告和摘要复制回宿主机上的 `.artifacts/qa-e2e/...`。
+它会复用与宿主机上 `qa suite` 相同的场景选择行为。
+宿主机和 Multipass 套件运行默认都会使用隔离的 Gateway 网关工作进程并行执行多个已选场景，并发数最多为 64 个工作进程或所选场景数量。可使用 `--concurrency <count>` 调整工作进程数量，或使用 `--concurrency 1` 串行执行。
+实时运行会转发那些适合 guest 使用的受支持 QA 凭证输入：基于环境变量的提供商密钥、QA 实时提供商配置路径，以及存在时的 `CODEX_HOME`。请将 `--output-dir` 保持在仓库根目录下，以便 guest 能通过挂载的工作区写回结果。

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

-种子资源位于 `qa/`：
+种子资源位于 `qa/` 下：

 - `qa/scenarios/index.md`
- `qa/scenarios/*.md`
+- `qa/scenarios/<theme>/*.md`

-这些内容会有意保存在 git 中，以便人类和智能体都能看到 QA 计划。
+这些文件有意保存在 git 中，这样 QA 计划对人类和智能体都可见。

-`qa-lab` 应保持为一个通用的 Markdown 运行器。每个场景 Markdown 文件都是一次测试运行的事实来源，并且应定义：
+`qa-lab` 应保持为一个通用的 Markdown 运行器。每个场景 Markdown 文件都是一次测试运行的唯一事实来源，并且应定义：

 - 场景元数据
+- 可选的 category、capability、lane 和 risk 元数据
 - 文档和代码引用
- 可选的插件需求
+- 可选的插件要求
 - 可选的 Gateway 网关配置补丁
 - 可执行的 `qa-flow`

-支持 `qa-flow` 的可复用运行时表面可以保持通用且跨领域。例如，Markdown 场景可以将传输侧辅助工具与浏览器侧辅助工具结合起来，通过 Gateway 网关的 `browser.request` 接缝驱动嵌入式 Control UI，而无需新增专用场景运行器。
+支撑 `qa-flow` 的可复用运行时表面可以保持通用且跨领域。例如，Markdown 场景可以组合传输侧辅助工具与浏览器侧辅助工具，后者通过 Gateway 网关 `browser.request` 接缝驱动嵌入式 Control UI，而无需添加特定场景运行器。
+
+场景文件应按产品能力分组，而不是按源码树文件夹分组。文件移动时应保持场景 ID 稳定；使用 `docsRefs` 和 `codeRefs` 来追踪实现。

 基线列表应足够广泛，以覆盖：

@ -111,47 +114,46 @@ pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
 - 线程行为
 - 消息动作生命周期
 - cron 回调
- 记忆召回
+- memory recall
 - 模型切换
- 子智能体交接
+- subagent 交接
 - 读取仓库和读取文档
 - 一个小型构建任务，例如 Lobster Invaders

 ## 提供商 mock 通道

-`qa suite` 有两条本地提供商 mock 通道：
+`qa suite` 有两个本地提供商 mock 通道：

- `mock-openai` 是面向场景的 OpenClaw mock。它仍然是用于由仓库支持的 QA 和一致性门禁的默认确定性 mock 通道。
- `aimock` 会启动一个由 AIMock 支持的提供商服务器，用于实验性的协议、夹具、录制/回放和混沌覆盖。它是附加能力，不替代 `mock-openai` 的场景分发器。
+- `mock-openai` 是具备场景感知能力的 OpenClaw mock。它仍然是仓库支持 QA 和一致性门禁的默认确定性 mock 通道。
+- `aimock` 会启动一个基于 AIMock 的提供商服务器，用于实验性的协议、夹具、录制/回放和混沌测试覆盖。它是增量补充，不替代 `mock-openai` 场景分发器。

-提供商通道实现位于 `extensions/qa-lab/src/providers/` 下。
-每个提供商都拥有自己的默认设置、本地服务器启动方式、Gateway 网关模型配置、凭证配置文件暂存需求，以及实时/mock 能力标志。共享的 suite 和 Gateway 网关代码应通过提供商注册表进行路由，而不是根据提供商名称分支。
+提供商通道实现位于 `extensions/qa-lab/src/providers/` 下。每个提供商负责自己的默认值、本地服务器启动、Gateway 网关模型配置、auth profile 暂存需求，以及实时/mock 能力标志。共享套件和 Gateway 网关代码应通过提供商注册表进行路由，而不是根据提供商名称分支。

 ## 传输适配器

-`qa-lab` 拥有一个面向 Markdown QA 场景的通用传输接缝。
-`qa-channel` 是该接缝上的第一个适配器，但设计目标更广：未来的真实或合成渠道都应接入同一个 suite 运行器，而不是新增一个传输专用的 QA 运行器。
+`qa-lab` 为 Markdown QA 场景提供一个通用传输接缝。
+`qa-channel` 是这个接缝上的第一个适配器，但设计目标更广：未来无论是真实渠道还是合成渠道，都应插入同一个 suite 运行器，而不是新增一个传输专用的 QA 运行器。

-在架构层面，拆分如下：
+从架构层面看，拆分如下：

- `qa-lab` 负责通用场景执行、worker 并发、产物写入和报告。
- 传输适配器负责 Gateway 网关配置、就绪性、入站与出站观察、传输动作以及规范化的传输状态。
- `qa/scenarios/` 下的 Markdown 场景文件定义测试运行；`qa-lab` 提供执行它们的可复用运行时表面。
+- `qa-lab` 负责通用场景执行、工作进程并发、产物写入和报告生成。
+- 传输适配器负责 Gateway 网关配置、就绪性、入站与出站观察、传输动作以及标准化传输状态。
+- `qa/scenarios/` 下的 Markdown 场景文件定义测试运行；`qa-lab` 提供执行这些场景的可复用运行时表面。

-面向维护者的新渠道适配器接入指南位于
+面向维护者的新渠道适配器采用指南位于
 [测试](/zh-CN/help/testing#adding-a-channel-to-qa)。

 ## 报告

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

- 哪些内容成功了
- 哪些内容失败了
- 哪些内容仍然受阻
+- 哪些成功了
+- 哪些失败了
+- 哪些仍然受阻
 - 值得补充哪些后续场景

-对于角色和风格检查，可在多个实时模型引用上运行同一场景，并生成一份经评判的 Markdown 报告：
+对于角色和风格检查，可在多个实时模型引用上运行同一场景，并写出一份经过评审的 Markdown 报告：

 ```bash
 pnpm openclaw qa character-eval \
@ -170,21 +172,22 @@ pnpm openclaw qa character-eval \
  --judge-concurrency 16
 ```

-该命令运行的是本地 QA Gateway 网关子进程，而不是 Docker。角色评估场景应通过 `SOUL.md` 设置人格，然后执行普通用户轮次，例如聊天、工作区帮助和小型文件任务。候选模型不应被告知自己正在被评估。该命令会保留每份完整转录、记录基本运行统计信息，然后要求评审模型以快速模式和 `xhigh` 推理来按自然度、氛围感和幽默感对这些运行进行排序。
-在比较不同提供商时，请使用 `--blind-judge-models`：评审提示仍会获得每份转录和运行状态，但候选引用会被替换为中性标签，例如 `candidate-01`；报告会在解析完成后再将排名映射回真实引用。
-候选运行默认使用 `high` thinking，而对支持该能力的 OpenAI 模型则默认使用 `xhigh`。你可以通过 `--model provider/model,thinking=<level>` 为某个候选项单独覆盖。`--thinking <level>` 仍然会设置全局后备值，而旧的 `--model-thinking <provider/model=level>` 形式则为兼容性保留。
-OpenAI 候选引用默认启用快速模式，以便在提供商支持时使用优先处理。若单个候选项或评审模型需要覆盖，请内联添加 `,fast`、`,no-fast` 或 `,fast=false`。只有在你想为每个候选模型都强制开启快速模式时，才传入 `--fast`。候选和评审模型的耗时都会记录在报告中用于基准分析，但评审提示会明确说明不要按速度排名。
-候选和评审模型运行默认都使用并发数 16。当提供商限制或本地 Gateway 网关压力使运行噪声过大时，请降低 `--concurrency` 或 `--judge-concurrency`。
-当未传入候选 `--model` 时，角色评估默认使用
-`openai/gpt-5.4`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、
+该命令运行的是本地 QA Gateway 网关子进程，而不是 Docker。角色评估场景应通过 `SOUL.md` 设置 persona，然后运行普通用户回合，例如聊天、工作区帮助和小型文件任务。候选模型不应被告知自己正在接受评估。该命令会保留每一份完整转录、记录基础运行统计信息，然后以快速模式要求评审模型使用 `xhigh` 推理，按自然度、氛围和幽默感对这些运行进行排序。
+在比较不同提供商时，请使用 `--blind-judge-models`：评审提示仍会获得每份转录和运行状态，但候选引用会被替换为中性标签，例如 `candidate-01`；解析后报告会将排序结果映射回真实引用。
+候选运行默认使用 `high` thinking，而支持该能力的 OpenAI 模型则默认使用 `xhigh`。你可以通过 `--model provider/model,thinking=<level>` 内联覆盖某个特定候选项。`--thinking <level>` 仍然用于设置全局回退值，旧的 `--model-thinking <provider/model=level>` 形式也会保留以兼容旧用法。
+OpenAI 候选引用默认启用快速模式，以便在提供商支持时使用优先处理。若某个单独候选项或评审项需要覆盖，请内联添加 `,fast`、`,no-fast` 或 `,fast=false`。只有当你想为所有候选模型强制开启快速模式时，才传入 `--fast`。候选项和评审项的耗时都会记录在报告中，用于基准分析，但评审提示会明确说明不要按速度排序。
+候选模型和评审模型运行的默认并发数都是 16。当提供商限制或本地 Gateway 网关压力导致运行噪声过大时，请降低 `--concurrency` 或 `--judge-concurrency`。
+当未传入候选 `--model` 时，character eval 默认使用
+`openai/gpt-5.4`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、
+`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、
 `moonshot/kimi-k2.5` 和
 `google/gemini-3.1-pro-preview`。
-当未传入 `--judge-model` 时，评审默认使用
+当未传入 `--judge-model` 时，评审模型默认使用
 `openai/gpt-5.4,thinking=xhigh,fast` 和
 `anthropic/claude-opus-4-6,thinking=high`。

 ## 相关文档

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

 # QA 重构

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

 ## 目标

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

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

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

 ## 当前状态

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

 已实现：

@ -36,34 +35,34 @@ x-i18n:
  - 规范的 QA 包元数据
  - 操作员身份
  - 启动任务
- `qa/scenarios/*.md`
-  - 每个场景对应一个 markdown 文件
+- `qa/scenarios/<theme>/*.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 定义的处理器绑定选择可执行场景
+  - 通过 Markdown 定义的 handler 绑定选择可执行场景
 - QA 总线协议 + UI
-  - 用于渲染图像 / 视频 / 音频 / 文件的通用内联附件
+  - 用于图片 / 视频 / 音频 / 文件渲染的通用内联附件

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

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

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

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

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

 ### 简单交互

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

 ### 配置与运行时变更

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

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

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

-### 记忆编排
+### Memory 编排

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

 ### 工具与插件集成

- MCP plugin-tools 调用
- skill 可见性
- skill 热安装
+- MCP plugin-tools call
+- Skills 可见性
+- Skills 热安装
 - 原生图像生成
 - 图像往返
- 来自附件的图像理解
+- 从附件理解图像

 ### 多轮与多参与者

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

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

 ## 方向

 ### 单一事实来源

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

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

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

 ### 首选编写格式

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

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

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

-这样可以得到：
+这样可以获得：

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

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

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

 示例：

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

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

 根据当前 suite，通用运行器需要的不只是提示词执行。

-### 环境与设置操作
+### 环境与设置动作

 - `bus.reset`
 - `gateway.waitHealthy`
@ -249,14 +248,14 @@ Verify generated media is reattached on the follow-up turn.
 - `thread.create`
 - `workspace.writeSkill`

-### 智能体轮次操作
+### 智能体轮次动作

 - `agent.send`
 - `agent.wait`
 - `bus.injectInbound`
 - `bus.injectOutbound`

-### 配置与运行时操作
+### 配置与运行时动作

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

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

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

-### 记忆与 cron 操作
+### Memory 与 cron 动作

 - `memory.indexForce`
 - `memory.searchCli`
@ -284,7 +283,7 @@ Verify generated media is reattached on the follow-up turn.
 - `cron.waitCompletion`
 - `sessionTranscript.write`

-### MCP 操作
+### MCP 动作

 - `mcp.callTool`

@ -304,66 +303,66 @@ Verify generated media is reattached on the follow-up turn.
 - `cron.managedPresent`
 - `artifact.exists`

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

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

 当前 suite 中的示例：

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

 所需能力：

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

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

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

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

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

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

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

 推荐规则：

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

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

 ## 架构变更

 ### 当前

-场景 markdown 已经是以下内容的事实来源：
+场景 Markdown 现在已经是以下内容的事实来源：

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

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

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

 ## 重构计划

@ -372,11 +371,11 @@ Verify generated media is reattached on the follow-up turn.
 已完成。

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

 ### 第 2 阶段：通用引擎

@ -386,55 +385,55 @@ Verify generated media is reattached on the follow-up turn.
  - action registry
  - assertion registry
  - custom handlers
- 保留现有辅助函数作为引擎操作
+- 保留现有 helper functions 作为引擎操作

-交付成果：
+交付物：

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

 先从主要是 prompt + wait + assert 的场景开始：

- 线程后续跟进
- 来自附件的图像理解
- skill 可见性与调用
- 渠道基线
+- threaded follow-up
+- 从附件理解图像
+- Skills 可见性与调用
+- channel baseline

-交付成果：
+交付物：

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

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

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

-交付成果：
+交付物：

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

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

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

-交付成果：
+交付物：

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

 ### 第 6 阶段：删除硬编码场景映射

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

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

 ## Fake Slack / 富媒体支持

-当前 QA 总线以文本优先。
+当前 QA 总线仍然是 text-first。

 相关文件：

@ -444,17 +443,17 @@ Verify generated media is reattached on the follow-up turn.
 - `extensions/qa-lab/src/bus-server.ts`
 - `extensions/qa-lab/web/src/ui-render.ts`

-如今 QA 总线支持：
+目前 QA 总线支持：

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

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

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

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

 ```ts
 type QaBusAttachment = {
@ -473,42 +472,42 @@ type QaBusAttachment = {
 };
 ```

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

 - `QaBusMessage`
 - `QaBusInboundMessageInput`
 - `QaBusOutboundMessageInput`

-### 为什么要先做通用模型
+### 为什么要先做通用层

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

-而应使用：
+而应该：

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

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

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

 更新 QA UI 以渲染：

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

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

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

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

- fake Slack 中的内联图像回复
+- fake Slack 中的内联图片回复
 - 音频附件理解
 - 视频附件理解
 - 混合附件顺序
@ -516,24 +515,24 @@ type QaBusAttachment = {

 ## 建议

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

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

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

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

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

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