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-29 05:46:32 +00:00
parent 14d20ac689
commit 3e3563817d
1 changed files with 58 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
docs/zh-CN/concepts/qa-matrix.md
View File

@ -2,23 +2,23 @@
read_when:
- 在本地运行 pnpm openclaw qa matrix
- 添加或选择 Matrix QA 场景
- 排查 Matrix QA 失败、超时或卡住的清理
summary: Docker 支持的 Matrix QA 实时 QA 通道维护者参考：CLI、配置档案、环境变量、场景和输出工件。
- 排查 Matrix QA 失败、超时或清理卡住的问题
summary: Docker 支撑的 Matrix 实时 QA 通道的维护者参考：CLI、配置档、环境变量、场景和输出工件。
title: Matrix QA
x-i18n:
generated_at: "2026-04-28T11:50:02Z"
generated_at: "2026-04-29T05:45:48Z"
model: gpt-5.5
provider: openai
source_hash: 6282e8a65fb5af46a67f8240d5a9ce095e614b6cc68621745ffe79cf88a5131f
source_hash: 6ab862474e2abe45a1dcd66f025e3a3dd52a3417b0c1f42a26cd7944dd4053f5
source_path: concepts/qa-matrix.md
workflow: 16
---
Matrix QA 车道会在 Docker 中使用一次性 Tuwunel homeserver 运行内置的 `@openclaw/matrix` 插件，并创建临时的 driver、SUT 和 observer 账号以及预置房间。它为 Matrix 提供真实传输层的 live 覆盖。
Matrix QA 测试通道会在 Docker 中使用一次性的 Tuwunel homeserver，针对内置的 `@openclaw/matrix` 插件运行测试，并配备临时的 driver、SUT 和 observer 账号以及预置房间。它为 Matrix 提供真实传输层的实时覆盖。
这是仅供维护者使用的工具。打包的 OpenClaw 发行版会有意省略 `qa-lab`，因此 `openclaw qa` 只能在源码检出中使用。源码检出会直接加载内置 runner，无需安装插件。
这是仅供维护者使用的工具。打包后的 OpenClaw 版本会有意省略 `qa-lab`，因此 `openclaw qa` 只能从源码检出中使用。源码检出会直接加载内置 runner，无需安装插件。
有关更广泛的 QA 框架上下文，请参见 [QA overview](/zh-CN/concepts/qa-e2e-automation)。
如需更广泛的 QA 框架背景，请参阅 [QA overview](/zh-CN/concepts/qa-e2e-automation)。
## 快速开始
@ -26,16 +26,16 @@ Matrix QA 车道会在 Docker 中使用一次性 Tuwunel homeserver 运行内置
pnpm openclaw qa matrix --profile fast --fail-fast
```
普通的 `pnpm openclaw qa matrix` 会运行 `--profile all`，并且不会在第一次失败时停止。发布门禁请使用 `--profile fast --fail-fast`；并行运行完整清单时，可用 `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli` 对目录分片。
普通的 `pnpm openclaw qa matrix` 会运行 `--profile all`，并且不会在首次失败时停止。发布门禁请使用 `--profile fast --fail-fast`；并行运行完整清单时，可用 `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli` 对目录分片。
## 该车道会做什么
## 该测试通道做什么
1. 在 Docker 中配置一个一次性 Tuwunel homeserver（默认镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`，服务器名称 `matrix-qa.test`，端口 `28008`）。
1. 在 Docker 中预配一次性的 Tuwunel homeserver（默认镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`，服务器名 `matrix-qa.test`，端口 `28008`）。
2. 注册三个临时用户：`driver`（发送入站流量）、`sut`（被测 OpenClaw Matrix 账号）、`observer`（第三方流量捕获）。
3. 为所选场景预置所需房间（main、threading、media、restart、secondary、allowlist、E2EE、verification 私信等）。
4. 启动一个子 OpenClaw Gateway 网关，并将真实 Matrix 插件限定到 SUT 账号；子进程中不会加载 `qa-channel`。
3. 预置所选场景需要的房间（main、threading、media、restart、secondary、allowlist、E2EE、verification DM 等）。
4. 启动一个子 OpenClaw Gateway 网关，其中真实 Matrix 插件限定到 SUT 账号；`qa-channel` 不会加载到子进程中。
5. 按顺序运行场景，并通过 driver/observer Matrix 客户端观察事件。
6. 拆除 homeserver，写入报告和摘要产物，然后退出。
6. 关闭 homeserver，写入报告和摘要构件，然后退出。
## CLI
@ -47,25 +47,25 @@ pnpm openclaw qa matrix [options]
| 标志 | 默认值 | 描述 |
| --------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `--profile <profile>` | `all` | 场景配置文件。参见 [配置文件](#profiles)。 |
| `--fail-fast` | 关闭 | 在第一次检查或场景失败后停止。 |
| `--scenario <id>` | — | 只运行此场景。可重复。参见 [场景](#scenarios)。 |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` | 写入报告、摘要、已观察事件和输出日志的位置。相对路径会基于 `--repo-root` 解析。 |
| `--profile <profile>` | `all` | 场景配置文件。请参阅 [配置文件](#profiles)。 |
| `--fail-fast` | 关闭 | 在第一个失败的检查或场景之后停止。 |
| `--scenario <id>` | — | 只运行此场景。可重复。请参阅 [场景](#scenarios)。 |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` | 写入报告、摘要、观察到的事件和输出日志的位置。相对路径会基于 `--repo-root` 解析。 |
| `--repo-root <path>` | `process.cwd()` | 从中性工作目录调用时的仓库根目录。 |
| `--sut-account <id>` | `sut` | QA Gateway 网关配置中的 Matrix 账号 id。 |
### 提供商标志
该车道使用真实 Matrix 传输层，但模型提供商可配置：
该测试通道使用真实的 Matrix 传输，但模型提供商可配置：
| 标志 | 默认值 | 描述 |
| ------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` 用于确定性 mock 分发，`live-frontier` 用于 live frontier 提供商。旧别名 `live-openai` 仍然可用。 |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` 用于确定性的模拟分发，`live-frontier` 用于实时前沿提供商。旧别名 `live-openai` 仍可使用。 |
| `--model <ref>` | 提供商默认值 | 主 `provider/model` 引用。 |
| `--alt-model <ref>` | 提供商默认值 | 场景在运行中切换时使用的备用 `provider/model` 引用。 |
| `--fast` | 关闭 | 在支持的情况下启用提供商快速模式。 |
| `--fast` | 关闭 | 在支持时启用提供商快速模式。 |
Matrix QA 不接受 `--credential-source` 或 `--credential-role`。该车道会在本地配置一次性用户；没有可租用的共享凭证池。
Matrix QA 不接受 `--credential-source` 或 `--credential-role`。该测试通道会在本地预配一次性用户；没有可供租用的共享凭证池。
## 配置文件
@ -74,14 +74,14 @@ Matrix QA 不接受 `--credential-source` 或 `--credential-role`。该车道会
| 配置文件 | 用途 |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `all`（默认） | 完整目录。较慢但覆盖全面。 |
| `fast` | 发布门禁子集，用于测试 live 传输契约：canary、提及门控、allowlist 阻止、回复形状、重启恢复、线程跟进、线程隔离、回应观察和 exec 审批元数据递送。 |
| `transport` | 传输层线程、私信、房间、自动加入、提及/allowlist、审批和回应场景。 |
| `fast` | 发布门禁子集，用于演练实时传输契约：canary、提及门控、allowlist 拦截、回复形状、重启恢复、线程跟进、线程隔离、反应观察，以及 exec 审批元数据投递。 |
| `transport` | 传输级线程、私信、房间、自动加入、提及/allowlist、审批和反应场景。 |
| `media` | 图片、音频、视频、PDF、EPUB 附件覆盖。 |
| `e2ee-smoke` | 最小 E2EE 覆盖：基本加密回复、线程跟进、bootstrap 成功。 |
| `e2ee-smoke` | 最小 E2EE 覆盖：基本加密回复、线程跟进、引导成功。 |
| `e2ee-deep` | 全面的 E2EE 状态丢失、备份、密钥和恢复场景。 |
| `e2ee-cli` | 通过 QA harness 驱动的 `openclaw matrix encryption setup` 和 `verify *` CLI 场景。 |
精确映射位于 `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts`。
确切映射位于 `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts`。
## 场景
@ -92,54 +92,55 @@ Matrix QA 不接受 `--credential-source` 或 `--credential-role`。该车道会
- 流式传输和工具进度：`matrix-room-partial-streaming-preview`、`matrix-room-quiet-streaming-preview`、`matrix-room-tool-progress-*`、`matrix-room-block-streaming`
- 媒体：`matrix-media-type-coverage`、`matrix-room-image-understanding-attachment`、`matrix-attachment-only-ignored`、`matrix-unsupported-media-safe`
- 路由：`matrix-room-autojoin-invite`、`matrix-secondary-room-*`
- 回应：`matrix-reaction-*`
- 审批：`matrix-approval-*`（exec/插件元数据、分块回退、拒绝回应、线程和 `target: "both"` 路由）
- 反应：`matrix-reaction-*`
- 审批：`matrix-approval-*`（exec/插件元数据、分块 fallback、拒绝反应、线程，以及 `target: "both"` 路由）
- 重启和重放：`matrix-restart-*`、`matrix-stale-sync-replay-dedupe`、`matrix-room-membership-loss`、`matrix-homeserver-restart-resume`、`matrix-initial-catchup-then-incremental`
- 提及门控、bot-to-bot 和 allowlist：`matrix-mention-*`、`matrix-allowbots-*`、`matrix-allowlist-*`、`matrix-multi-actor-ordering`、`matrix-inbound-edit-*`、`matrix-mxid-prefixed-command-block`、`matrix-observer-allowlist-override`
- E2EE：`matrix-e2ee-*`（基本回复、线程跟进、bootstrap、恢复密钥生命周期、状态丢失变体、服务器备份行为、设备卫生、SAS / QR / 私信验证、重启、产物隐去）
- E2EE CLI：`matrix-e2ee-cli-*`（加密设置、幂等设置、bootstrap 失败、恢复密钥生命周期、多账号、Gateway 网关回复往返、自验证）
- 提及门控、bot 到 bot，以及 allowlist：`matrix-mention-*`、`matrix-allowbots-*`、`matrix-allowlist-*`、`matrix-multi-actor-ordering`、`matrix-inbound-edit-*`、`matrix-mxid-prefixed-command-block`、`matrix-observer-allowlist-override`
- E2EE：`matrix-e2ee-*`（基本回复、线程跟进、引导、恢复密钥生命周期、状态丢失变体、服务器备份行为、设备卫生、SAS / QR / 私信验证、重启、构件脱敏）
- E2EE CLI：`matrix-e2ee-cli-*`（加密设置、幂等设置、引导失败、恢复密钥生命周期、多账号、Gateway 网关回复往返、自验证）
传入 `--scenario <id>`（可重复）以运行手选集合；与 `--profile all` 组合可忽略配置文件门控。
传入 `--scenario <id>`（可重复）可运行手动挑选的一组场景；与 `--profile all` 结合使用可忽略配置文件门控。
## 环境变量
| 变量 | 默认值 | 效果 |
| 变量 | 默认值 | 作用 |
| --------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_QA_MATRIX_TIMEOUT_MS` | `1800000`（30 分钟） | 整次运行的硬性上限。 |
| `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` | `8000` | 用于负向无回复断言的静默窗口。会被限制为 `≤` 运行超时。 |
| `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` | `90000` | Docker 拆除的上限。失败表面会包含恢复用的 `docker compose ... down --remove-orphans` 命令。 |
| `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` | `ghcr.io/matrix-construct/tuwunel:v1.5.1` | 在针对不同 Tuwunel 版本验证时覆盖 homeserver 镜像。 |
| `OPENCLAW_QA_MATRIX_PROGRESS` | 开启 | `0` 会静默 stderr 上的 `[matrix-qa] ...` 进度行。`1` 会强制开启。 |
| `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT` | 已隐去 | `1` 会在 `matrix-qa-observed-events.json` 中保留消息正文和 `formatted_body`。默认会隐去，以确保 CI 产物安全。 |
| `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT` | 关闭 | `1` 会跳过产物写入后的确定性 `process.exit`。默认会强制退出，因为 matrix-js-sdk 的原生加密句柄可能让事件循环在产物完成后仍保持活动状态。 |
| `OPENCLAW_RUN_NODE_OUTPUT_LOG` | 未设置 | 当由外层 launcher（例如 `scripts/run-node.mjs`）设置时，Matrix QA 会复用该日志路径，而不是启动自己的 tee。 |
| `OPENCLAW_QA_MATRIX_TIMEOUT_MS` | `1800000`（30 分钟） | 整个运行的硬性上限。 |
| `OPENCLAW_QA_MATRIX_CANARY_TIMEOUT_MS` | `45000` | 初始金丝雀回复的上限。Release CI 会在共享运行器上提高此值，以免缓慢的首次 Gateway 网关轮次在场景覆盖开始前就失败。 |
| `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` | `8000` | 用于否定式无回复断言的静默窗口。会被限制为 `≤` 运行超时。 |
| `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` | `90000` | Docker 清理的上限。失败输出中会包含恢复用的 `docker compose ... down --remove-orphans` 命令。 |
| `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` | `ghcr.io/matrix-construct/tuwunel:v1.5.1` | 在针对其他 Tuwunel 版本验证时，覆盖 homeserver 镜像。 |
| `OPENCLAW_QA_MATRIX_PROGRESS` | 开启 | `0` 会静默 stderr 上的 `[matrix-qa] ...` 进度行。`1` 会强制开启。 |
| `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT` | 已脱敏 | `1` 会在 `matrix-qa-observed-events.json` 中保留消息正文和 `formatted_body`。默认会脱敏，以保证 CI 构件安全。 |
| `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT` | 关闭 | `1` 会跳过构件写入后的确定性 `process.exit`。默认会强制退出，因为 matrix-js-sdk 的原生加密句柄可能让事件循环在构件完成后仍保持活动。 |
| `OPENCLAW_RUN_NODE_OUTPUT_LOG` | 未设置 | 当由外层启动器（例如 `scripts/run-node.mjs`）设置时，Matrix QA 会复用该日志路径，而不是启动自己的 tee。 |
## 输出产物
## 输出构件
写入 `--output-dir`：
写入到 `--output-dir`：
- `matrix-qa-report.md` — Markdown 协议报告（通过、失败、跳过的内容及原因）。
- `matrix-qa-summary.json` — 适合 CI 解析和仪表盘使用的结构化摘要。
- `matrix-qa-observed-events.json` — 来自驱动和观察者客户端的已观测 Matrix 事件。除非设置了 `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1`，否则正文会被遮盖；审批元数据会以选定的安全字段和截断后的命令预览进行汇总。
- `matrix-qa-output.log` — 本次运行的合并 stdout/stderr。如果设置了 `OPENCLAW_RUN_NODE_OUTPUT_LOG`，则改为复用外层启动器的日志。
- `matrix-qa-report.md` — Markdown 协议报告（哪些通过、失败、被跳过，以及原因）。
- `matrix-qa-summary.json` — 适合 CI 解析和仪表板使用的结构化摘要。
- `matrix-qa-observed-events.json` — 来自驱动程序和观察者客户端的已观察 Matrix 事件。除非设置 `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1`，否则正文会被脱敏；审批元数据会用选定的安全字段和截断后的命令预览进行汇总。
- `matrix-qa-output.log` — 本次运行的合并 stdout/stderr。如果设置了 `OPENCLAW_RUN_NODE_OUTPUT_LOG`，则会改为复用外层启动器的日志。
默认输出目录为 `<repo>/.artifacts/qa-e2e/matrix-<timestamp>`，因此连续运行不会相互覆盖。
默认输出目录是 `<repo>/.artifacts/qa-e2e/matrix-<timestamp>`，因此连续运行不会相互覆盖。
## 分流提示
## 分诊提示
- **运行在接近结束时挂起：** `matrix-js-sdk` 原生加密句柄的存活时间可能超过测试框架。默认会在写入构件后强制执行干净的 `process.exit`；如果你取消设置了 `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1`，预期进程会继续停留。
- **清理错误：** 查找打印出的恢复命令（一个 `docker compose ... down --remove-orphans` 调用），并手动运行它来释放 homeserver 端口。
- **CI 中负向断言窗口不稳定：** 当 CI 较快时，降低 `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS`（默认 8 秒）；在较慢的共享 runner 上提高它。
- **需要为错误报告提供已遮盖的正文：** 使用 `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1` 重新运行，并附上 `matrix-qa-observed-events.json`。将生成的构件视为敏感内容。
- **不同的 Tuwunel 版本：** 将 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 指向正在测试的版本。该通道仅检入固定的默认镜像。
- **运行在接近结束时挂起：** `matrix-js-sdk` 原生加密句柄可能比 harness 存活更久。默认会在构件写入后强制执行干净的 `process.exit`；如果你已取消设置 `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1`，预计进程会继续停留。
- **清理错误：** 查找打印出的恢复命令（一次 `docker compose ... down --remove-orphans` 调用），并手动运行它以释放 homeserver 端口。
- **CI 中的否定断言窗口不稳定：** 当 CI 速度较快时，降低 `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS`（默认 8 秒）；在较慢的共享运行器上提高它。
- **错误报告需要未脱敏正文：** 使用 `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1` 重新运行，并附上 `matrix-qa-observed-events.json`。将生成的构件视为敏感内容。
- **不同的 Tuwunel 版本：** 将 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 指向正在测试的版本。该通道只签入固定的默认镜像。
## 实时传输契约
Matrix 是三个实时传输通道（Matrix、Telegram、Discord）之一，它们共享 [QA overview → 实时传输覆盖范围](/zh-CN/concepts/qa-e2e-automation#live-transport-coverage) 中定义的单一契约检查清单。`qa-channel` 仍然是广泛的合成套件，并且有意不包含在该矩阵中。
Matrix 是三个实时传输通道（Matrix、Telegram、Discord）之一，它们共享 [QA overview → 实时传输覆盖范围](/zh-CN/concepts/qa-e2e-automation#live-transport-coverage) 中定义的单一契约清单。`qa-channel` 仍是广泛的合成套件，并且有意不属于该矩阵。
## 相关内容
## 相关
- [QA overview](/zh-CN/concepts/qa-e2e-automation) — 整体 QA 栈和实时传输契约
- [QA Channel](/zh-CN/channels/qa-channel) — 用于仓库支持场景的合成渠道适配器
- [测试](/zh-CN/help/testing) — 运行测试并添加 QA 覆盖范围
- [QA 渠道](/zh-CN/channels/qa-channel) — 用于仓库支持场景的合成渠道适配器
- [测试](/zh-CN/help/testing) — 运行测试并添加 QA 覆盖
- [Matrix](/zh-CN/channels/matrix) — 正在测试的渠道插件