From d5417a569cc2e64aa56ff563b3697f2225233608 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 8 Apr 2026 04:39:38 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/qa-e2e-automation.md | 49 ++-- docs/zh-CN/refactor/qa.md | 311 ++++++++++++----------- 2 files changed, 183 insertions(+), 177 deletions(-) diff --git a/docs/zh-CN/concepts/qa-e2e-automation.md b/docs/zh-CN/concepts/qa-e2e-automation.md index 49bc6e99e..6ad2c35af 100644 --- 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) diff --git a/docs/zh-CN/refactor/qa.md b/docs/zh-CN/refactor/qa.md index 0ff23374e..54f32e4db 100644 --- 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 兼容文件是否应继续纳入版本控制