扩展 QA 技术栈
仓库支持的种子¶
种子资产位于 qa/ 目录下:
qa/scenarios/index.yamlqa/scenarios/<theme>/*.yaml
涉及身份信息的频道变更使用隔离的
channel-participant-identity-inspection QA 频道流程。它驱动一个真实的
临时 Gateway 和 mock provider,然后使用操作员所用的同一
openclaw audit --run ... --explain JSON 和人工界面检查被准入的运行。
该流程包括生命周期管理的重启,以及对被拒绝的运行前入站数据进行行数检查。
这些内容有意放在 git 中,以便 QA 计划对人类和 agent 都可见。
qa-lab 仍然是一个通用的 YAML 场景运行器。每个场景 YAML 文件是一个测试运行的
唯一事实来源,并应定义以下内容:
- 顶层
title scenario元数据scenario中可选的 category、capability、lane 和 risk 元数据scenario中的文档引用和代码引用(docsRefs/codeRefs)scenario中可选的插件要求scenario中可选的 Gateway 配置补丁- 对于 flow 场景,使用可执行的顶层
flow;对于 Vitest 和 Playwright 场景,使用scenario.execution.kind/scenario.execution.path
支撑 flow 的可复用运行时界面保持通用,并具有横切性。
例如,YAML 场景可以将传输端辅助函数与浏览器端辅助函数组合使用,
通过 Gateway 的 browser.request 接缝驱动内嵌的 Control UI,而无需添加特例化
runner。
场景文件应按产品能力分组,而不是按源码树目录分组。
文件移动时,应保持场景 ID 稳定;使用 docsRefs 和 codeRefs 进行实现追溯。
基线列表应保持足够广泛,以覆盖以下内容:
- DM 和频道聊天
- 话题(thread)行为
- 消息操作生命周期
- cron 回调
- 记忆召回
- 模型切换
- subagent 交接
- 仓库阅读和文档阅读
- 一项小型构建任务,例如 Lobster Invaders
原生工具发现证明¶
flow 可以声明一条模型特定的已配置运行时路由:
仅当 --model 和 --alt-model 都选择所声明模型时,此路由才在 live-frontier 中生效。
启动器通过同一条运行时路由准备 singleton 和 partitioned 运行。
其他选择保留其通用模型路由;显式强制的运行时和 runtime-pair 单元保留各自的准备方式。
该元数据不会覆盖模型选择或产品工具加载。
原生发现通道为两个模型槽位都选择 openai/gpt-5.5。
其 Codex 目录支持原生工具搜索,无需 code_mode_only 覆盖。
仅凭 provider 身份并不能确立该能力。
共享的可搜索 fixtures 仅要求在 Codex 执行单元中关联 tool_search 收据;
直接 OpenClaw 单元仍然证明工具调用和结果。
sessions_spawn 仍然是始终直接的控制,并且不需要发现收据。
Provider 模拟通道¶
qa suite 有两条本地 provider 模拟通道:
mock-openai是场景感知的 OpenClaw 模拟器。它仍然是基于仓库的 QA 和一致性门禁的默认确定性模拟通道。aimock启动由 AIMock 支持的 provider 服务器,用于实验性协议、fixture、录制/回放和混沌覆盖。它是补充性的,不会取代mock-openai场景调度器。
场景感知的模拟器会独立于 agent 轮次响应 Activity recap 请求。
Recap 将对话文本作为数据引用,因此它们无法触发场景工具,也不会进入 /debug/requests 返回的场景请求证据。
对于 IPv6 回环服务器,请运行 pnpm openclaw qa mock-openai --host ::1。
打印出的 URL 包含方括号,例如 http://[::1]:<port>;配置客户端时请使用该 URL。
QA Lab 也会在其监听和通告的 URL 中用方括号括起 IPv6 主机。
将裸地址(不含方括号)传给 --host。
Provider 通道实现位于 extensions/qa-lab/src/providers/ 下。
每个 provider 拥有自己的默认配置、本地服务器启动、Gateway 模型配置、auth-profile 暂存需求以及 live/mock 能力标志。
共享的 suite 和 Gateway 代码通过 provider 注册表路由,而不是按 provider 名称分支。
传输适配器¶
qa-lab 拥有一个用于 YAML QA 场景的通用传输接缝。qa-channel 是合成默认传输。
crabline 启动独立的本地 provider 服务器,并针对其 provider 形态的 REST 和流式边界运行 OpenClaw 的正常 channel 插件;它不使用 Crabline 的 fixture 级本地 mock provider。
live 保留给真实 provider 凭据和外部频道。
在架构层面,职责划分如下:
qa-lab负责通用场景执行、worker 并发、artifact 写入和报告。- 传输适配器负责 Gateway 配置、就绪状态、入站和出站观察、传输操作以及规范化的传输状态。
qa/scenarios/下的 YAML 场景文件定义测试运行;qa-lab提供执行这些运行的可复用运行时界面。
适配器关闭与失败钩子¶
可选的 QA runner 钩子遵循由宿主主导的拆除顺序:
cleanup()停止新的 fixture 操作,同时保留凭据权限和待处理写入的所有权。最终收据所需的观察者可以在 Gateway 关闭期间保持活动。已绑定的传输请求本身也如此;场景截止时间不会落定已派发的请求。- 宿主停止 Gateway 并确认进程关闭。
captureBeforeGatewayCleanup()在临时 Gateway 状态被移除前,对最终原生收据进行快照。成功捕获在每次 Gateway 生命周期中只运行一次。抛出的错误会保留运行时证据并使拆除失败;但不会阻止停止后的 fixture 清理。cleanupAfterGatewayStop()落定待处理写入和自有 fixture 清理,然后释放凭据租约。如果 Gateway 关闭未被确认,宿主将不调用此钩子。应报告失败,而不是声称清理成功。
省略的钩子不执行任何适配器特有工作;正常的宿主拆除流程仍会运行。 错误会在各个清理阶段中累积。 应明确未知的远程写入结果,而不是推断所有权或重放写入。
可选的 whenUnhealthy Promise 会 resolve,而不是 reject,并带有终止错误。宿主会中止活动流程准入;适配器在清理期间仍拥有结算。省略它的适配器保留其显式健康检查和场景截止时间。
添加通道¶
将通道添加到 YAML QA 系统需要通道实现,以及一个验证通道契约的场景包。对于冒烟 CI 覆盖,请添加匹配的 Crabline 本地 provider 服务器,并通过 crabline 驱动暴露它。
当共享的 qa-lab 宿主可以拥有该流程时,不要添加新的顶层 QA 命令根。
qa-lab 拥有共享宿主机制:
openclaw qa命令根- 套件启动和拆除
- 工作器并发
- 工件写入
- 报告生成
- 场景执行
- 旧版
qa-channel场景的兼容性别名
Runner 插件拥有传输契约:
openclaw qa <runner>如何挂载在共享qa根之下- 如何为该传输配置 Gateway
- 如何检查就绪状态
- 如何注入入站事件
- 如何观察出站消息
- 如何暴露转录和规范化传输状态
- 如何执行由传输支撑的操作
- Gateway 运行时所需的哪些受信任模块预加载
- 如何处理特定于传输的重置或清理
新通道的最低采用标准:
- 保持
qa-lab作为共享qa根的所有者。 - 在共享的
qa-lab宿主接缝上实现传输 runner。 - 将特定于传输的机制保留在 runner 插件或通道 harness 内。
- 将 runner 挂载为
openclaw qa <runner>,而不是注册一个竞争性的根命令。Runner 插件应在openclaw.plugin.json中声明qaRunners,并从轻量级qa-runner-api.ts表面导出匹配的qaRunnerCliRegistrations数组。使用随附runtime-api.ts契约的已安装插件在作者迁移期间将继续获得支持,直至 2026-10-01。将 runner 执行保留在懒加载入口点之后。可选的adapterFactory在不更改命令现有场景目录的情况下,将传输暴露给共享场景。同一通道的分区是串行的,除非工厂声明每个实例都拥有隔离的凭据或一次性服务器、Gateway 状态和工件路径。模块支持的流程场景还要求adapterFactory.supportsModuleFlows: true;这些工厂必须返回实现prepareFlow的适配器。 - 在主题化的
qa/scenarios/目录下创建或适配 YAML 场景。 - 对新场景使用通用场景辅助函数。
- 除非仓库正在进行有意迁移,否则保持现有兼容性别名可用。
决策规则是严格的:
- 如果行为可以在
qa-lab中表达一次,就将其放在qa-lab中。 - 如果行为依赖于一个通道传输,就将其保留在该 runner 插件或插件 harness 中。
- 如果场景需要一个多个通道都可以使用的新能力,请添加通用辅助函数,而不是在
suite.ts中添加特定于通道的分支。 - 如果某个行为仅对一个传输有意义,请保持场景特定于传输,并在场景契约中明确说明。
场景辅助函数名称¶
新场景首选的通用辅助函数:
waitForTransportReadywaitForChannelReadyinjectInboundMessageinjectOutboundMessagewaitForOutboundMessagewaitForNoTransportOutboundgetTransportSnapshotreadTransportMessagereadTransportTranscriptformatTransportTranscriptresetTransport
兼容性别名对现有场景仍然可用 -
waitForQaChannelReady、waitForNoOutbound、formatConversationTranscript
和 resetBus - 但新场景编写应使用通用名称。
对于出站检查,请使用规范的 waitForOutboundMessage,而不是
添加特定于传输或通道的出站等待别名。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw