openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-24 01:54:59 +00:00
parent 0a9a76d2be
commit b3edea4d90
2 changed files with 503 additions and 512 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
docs/zh-CN/concepts/qa-e2e-automation.md
View File

@ -1,31 +1,31 @@
---
read_when:
- 扩展 qa-lab 或 qa-channel
- 添加基于仓库的 QA 场景
- 添加仓库支持的 QA 场景
- 围绕 Gateway 网关仪表板构建更高真实性的 QA 自动化
summary: 用于 qa-lab、qa-channel、种子场景和协议报告的私有 QA 自动化形态
title: QA E2E 自动化
summary: qa-lab、qa-channel、种子场景和协议报告的私有 QA 自动化形态
title: QA 端到端自动化
x-i18n:
generated_at: "2026-04-23T22:57:06Z"
generated_at: "2026-04-24T01:50:42Z"
model: gpt-5.4
provider: openai
source_hash: 8cf607af9e85c1f6908049da2b31a1c6c9eaa1fc95bc3af2136babb1a3b9b48f
source_hash: f6924a05faebdd22ac5222db6b9579b57d9c7f3dfac71df6c5f2ee7d2bf0a5f8
source_path: concepts/qa-e2e-automation.md
workflow: 15
---
私有 QA 堆栈旨在以比单个单元测试更贴近真实渠道形态的方式演练 OpenClaw。
私有 QA 栈的目标，是以比单个单元测试更贴近真实、更加符合渠道形态的方式来演练 OpenClaw。
当前组成部分：
- `extensions/qa-channel`：合成消息渠道，具有私信、渠道、线程、reaction、编辑和删除界面。
- `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 的对话记录和场景计划。
使用以下命令运行：
@ -33,9 +33,9 @@ x-i18n:
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
@ -44,78 +44,78 @@ 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，注册临时的 driver、SUT 和 observer 用户，创建一个私有房间，然后在 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 时，机器人到机器人的观测效果最佳。
当任一场景失败时，该命令会以非零状态退出。如果你希望在不以失败退出码结束的情况下获取工件，请使用 `--allow-failures`。
Telegram 报告和摘要会包含每条回复的 RTT，时间范围从 driver 消息发送请求开始，到观察到 SUT 回复为止，包含 canary。
该通道会针对一个真实的私有 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 时，机器人之间的观察效果最佳。
当任一场景失败时，该命令会以非零状态退出。如果你想保留产物但不希望退出码失败，请使用 `--allow-failures`。
Telegram 报告和摘要包含每次回复的 RTT，从驱动消息发送请求开始，到观察到 SUT 回复结束，金丝雀场景也包含在内。
实时传输通道现在共享一个更小的契约，而不是各自发明自己的场景列表结构：
`qa-channel` 仍然是覆盖面更广的合成产品行为套件，不属于实时传输覆盖矩阵的一部分。
`qa-channel` 仍然是覆盖范围广泛的合成产品行为测试套件，不属于实时传输覆盖矩阵的一部分。
| 通道 | Canary | 提及门控 | 允许列表拦截 | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | Reaction 观测 | 帮助命令 |
| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ |
| Matrix | x | x | x | x | x | x | x | x | |
| Telegram | x | | | | | | | | x |
| 通道 | 金丝雀 | 提及门控 | Allowlist 拦截 | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | 表情反应观察 | 帮助命令 |
| ---- | ------ | -------- | -------------- | -------- | -------- | -------- | -------- | ------------ | -------- |
| Matrix | x | x | x | x | x | x | x | x | |
| Telegram | x | | | | | | | | x |
这样可以让 `qa-channel` 保持为广覆盖的产品行为套件，同时让 Matrix、Telegram 和未来的实时传输共享一个明确的传输契约检查清单。
这使 `qa-channel` 保持为覆盖广泛产品行为的测试套件，而 Matrix、Telegram 以及未来的实时传输则共享一份明确的传输契约检查清单。
如果你想在不将 Docker 引入 QA 路径的情况下运行一个一次性 Linux VM 通道，请执行：
如果要运行一个一次性的 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 套件运行默认都会通过隔离的 Gateway 网关 worker 并行执行多个已选场景。`qa-channel` 默认并发数为 4，并受所选场景数量上限约束。使用 `--concurrency <count>` 可调整 worker 数量，或使用 `--concurrency 1` 进行串行执行。
当任一场景失败时，该命令会以非零状态退出。如果你希望在不以失败退出码结束的情况下获取工件，请使用 `--allow-failures`。
实时运行会转发适合来宾机使用的受支持 QA auth 输入：基于环境变量的 provider 密钥、QA 实时 provider 配置路径，以及存在时的 `CODEX_HOME`。请将 `--output-dir` 保持在仓库根目录下，这样来宾机才能通过挂载的工作区写回结果。
该命令会启动一个全新的 Multipass 来宾系统、安装依赖、在来宾系统内构建 OpenClaw、运行 `qa suite`，然后把标准 QA 报告和摘要复制回主机上的 `.artifacts/qa-e2e/...`。
它复用了与主机上 `qa suite` 相同的场景选择行为。
主机和 Multipass 套件运行默认都会并行执行多个已选场景，并使用隔离的 Gateway 网关工作进程。`qa-channel` 默认并发数为 4，但不会超过所选场景数量。使用 `--concurrency <count>` 可调节工作进程数量，或使用 `--concurrency 1` 进行串行执行。
当任一场景失败时，该命令会以非零状态退出。如果你想保留产物但不希望退出码失败，请使用 `--allow-failures`。
实时运行会转发那些对来宾系统来说可行的受支持 QA 凭证输入：基于环境变量的提供商密钥、QA 实时提供商配置路径，以及存在时的 `CODEX_HOME`。请将 `--output-dir` 保持在仓库根目录下，以便来宾系统能通过挂载的工作区回写内容。
## 基于仓库的种子资源
## 由仓库支持的种子
种子资源位于 `qa/` 中：
种子资源位于 `qa/`：
- `qa/scenarios/index.md`
- `qa/scenarios/<theme>/*.md`
这些内容有意保存在 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` 实现实现层面的可追溯性。
场景文件应按产品能力而非源码树目录来分组。即使文件移动，也要保持场景 ID 稳定；使用 `docsRefs` 和 `codeRefs` 来提供实现可追踪性。
基线列表应保持足够宽广，以覆盖：
基线列表应保持足够广泛，以覆盖：
- 私信和渠道聊天
- 线程行为
- 消息操作生命周期
- 消息动作生命周期
- cron 回调
- 记忆回溯
- 记忆召回
- 模型切换
- 子智能体交接
- 读取仓库和读取文档
@ -123,42 +123,42 @@ pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
## 提供商 mock 通道
`qa suite` 有两个本地 provider mock 通道：
`qa suite` 有两个本地提供商 mock 通道：
- `mock-openai` 是面向场景的 OpenClaw mock。它仍然是基于仓库 QA 和一致性关卡的默认确定性 mock 通道。
- `aimock` 会启动一个由 AIMock 支撑的 provider 服务器，用于实验性协议、夹具、录制/回放和混沌测试覆盖。它是增量补充，不替代 `mock-openai` 场景分发器。
- `mock-openai` 是具备场景感知能力的 OpenClaw mock。它仍然是用于仓库支持 QA 和一致性门禁的默认确定性 mock 通道。
- `aimock` 会启动一个基于 AIMock 的提供商服务器，用于实验性的协议、夹具、录制/回放和混沌覆盖。它是补充性的，不会替代 `mock-openai` 场景分发器。
provider 通道实现位于 `extensions/qa-lab/src/providers/` 下。每个 provider 自行管理其默认值、本地服务器启动、Gateway 网关模型配置、auth-profile 暂存需求以及 live/mock 能力标志。共享套件和 Gateway 网关代码应通过 provider 注册表进行路由，而不是基于 provider 名称分支。
提供商通道实现位于 `extensions/qa-lab/src/providers/` 下。每个提供商都负责其默认值、本地服务器启动、Gateway 网关模型配置、auth-profile 暂存需求，以及实时/mock 能力标志。共享的套件和 Gateway 网关代码应通过提供商注册表进行路由，而不是根据提供商名称做分支。
## 传输适配器
`qa-lab` 拥有一个用于 Markdown QA 场景的通用传输接缝。
`qa-channel` 是该接缝上的第一个适配器，但设计目标更广：未来的真实或合成渠道应接入同一个套件运行器，而不是新增一个传输专用 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` 提供执行它们的可复用运行时能力面。
面向维护者的新渠道适配器接入指南位于
[Testing](/zh-CN/help/testing#adding-a-channel-to-qa)。
面向维护者的新渠道适配器采用指南位于
[测试](/zh-CN/help/testing#adding-a-channel-to-qa)。
## 报告
`qa-lab` 会根据观察到的总线时间线导出 Markdown 协议报告。
`qa-lab` 会根据观察到的总线时间线导出 Markdown 协议报告。
报告应回答：
- 哪些内容成功了
- 哪些内容失败了
- 哪些内容仍被阻塞
- 哪些有效
- 哪些失败
- 哪些仍然受阻
- 值得补充哪些后续场景
对于角色与风格检查，可以让同一场景在多个实时模型引用上运行，并写出一份经过评判的 Markdown 报告：
对于角色和风格检查，请在多个实时模型引用上运行同一场景，并写出一份经评审的 Markdown 报告：
```bash
pnpm openclaw qa character-eval \
--model openai-codex/gpt-5.5,thinking=xhigh \
--model openai/gpt-5.4,thinking=medium,fast \
--model openai/gpt-5.2,thinking=xhigh \
--model openai/gpt-5,thinking=xhigh \
--model anthropic/claude-opus-4-6,thinking=high \
@ -166,30 +166,25 @@ pnpm openclaw qa character-eval \
--model zai/glm-5.1,thinking=high \
--model moonshot/kimi-k2.5,thinking=high \
--model google/gemini-3.1-pro-preview,thinking=high \
--judge-model openai-codex/gpt-5.5,thinking=xhigh,fast \
--judge-model openai/gpt-5.4,thinking=xhigh,fast \
--judge-model anthropic/claude-opus-4-6,thinking=high \
--blind-judge-models \
--concurrency 16 \
--judge-concurrency 16
```
该命令运行的是本地 QA Gateway 网关子进程，而不是 Docker。角色评测场景应通过 `SOUL.md` 设置人格，然后运行普通用户轮次，例如聊天、工作区帮助和小型文件任务。不应告知候选模型自己正在被评估。该命令会保留每份完整记录，记录基本运行统计信息，然后以 fast 模式和 `xhigh` 推理要求评审模型根据自然度、氛围和幽默感对运行结果进行排序。
在比较不同 provider 时，请使用 `--blind-judge-models`：评审提示仍会获得每份记录和运行状态，但候选引用会被替换为类似 `candidate-01` 的中性标签；报告会在解析后将排名映射回真实引用。
候选运行默认使用 `high` thinking，而支持该能力的 OpenAI 模型默认使用 `xhigh`。可通过 `--model provider/model,thinking=<level>` 内联覆盖某个特定候选。`--thinking <level>` 仍可设置全局后备值，而旧版 `--model-thinking <provider/model=level>` 形式也会保留以保持兼容性。
OpenAI 候选引用默认使用 fast 模式，以便在 provider 支持时使用优先处理。若单个候选或评审需要覆盖，可内联添加 `,fast`、`,no-fast` 或 `,fast=false`。仅当你希望对每个候选模型都强制启用 fast 模式时，才传入 `--fast`。
候选和评审的持续时间都会记录在报告中用于基准分析，但评审提示会明确说明不要按速度进行排名。
候选模型运行和评审模型运行的默认并发数均为 16。当 provider 限制或本地 Gateway 网关压力导致运行噪声过大时，可降低 `--concurrency` 或 `--judge-concurrency`。
如果未传入候选 `--model`，角色评测默认会使用
`openai-codex/gpt-5.5`、`openai/gpt-5.4`、`openai/gpt-5.2`、`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`，评审默认使用
`openai-codex/gpt-5.5,thinking=xhigh,fast` 和
`anthropic/claude-opus-4-6,thinking=high`。
该命令运行的是本地 QA Gateway 网关子进程，而不是 Docker。角色评估场景应通过 `SOUL.md` 设置人格，然后运行普通用户轮次，例如聊天、工作区帮助和小型文件任务。候选模型不应被告知自己正在被评估。
该命令会保留每一份完整对话记录、记录基本运行统计信息，然后要求评审模型在快速模式下、在支持时使用 `xhigh` 推理，按自然度、氛围和幽默感对运行结果进行排序。
在比较不同提供商时，请使用 `--blind-judge-models`：评审提示词仍会拿到每份对话记录和运行状态，但候选引用会被替换为诸如 `candidate-01` 这样的中性标签；报告会在解析后将排名映射回真实引用。
候选运行默认使用 `high` thinking，而 GPT-5.4 使用 `medium`，支持该能力的旧版 OpenAI 评估引用使用 `xhigh`。可通过 `--model provider/model,thinking=<level>` 为特定候选单独覆盖。`--thinking <level>` 仍然设置全局回退值，旧的 `--model-thinking <provider/model=level>` 形式也会保留以兼容。
OpenAI 候选引用默认启用 fast 模式，因此在提供商支持时会使用优先处理。若某个单独候选或评审需要覆盖，可内联添加 `,fast`、`,no-fast` 或 `,fast=false`。只有当你希望为每个候选模型都强制启用 fast 模式时，才使用 `--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`、`moonshot/kimi-k2.5` 和 `google/gemini-3.1-pro-preview`。
当未传入 `--judge-model` 时，评审默认使用 `openai/gpt-5.4,thinking=xhigh,fast` 和 `anthropic/claude-opus-4-6,thinking=high`。
## 相关文档
- [Testing](/zh-CN/help/testing)
- [QA 渠道](/zh-CN/channels/qa-channel)
- [测试](/zh-CN/help/testing)
- [QA Channel](/zh-CN/channels/qa-channel)
- [仪表板](/zh-CN/web/dashboard)

868
docs/zh-CN/help/testing.md
View File

File diff suppressed because it is too large Load Diff