跳转至

扩展 QA 技术栈

仓库支持的种子

种子资产位于 qa/ 目录下:

  • qa/scenarios/index.yaml
  • qa/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 可以声明一条模型特定的已配置运行时路由:

execution:
  kind: flow
  liveConfiguredRuntime:
    id: codex
    model: openai/gpt-5.5

仅当 --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 钩子遵循由宿主主导的拆除顺序:

  1. cleanup() 停止新的 fixture 操作,同时保留凭据权限和待处理写入的所有权。最终收据所需的观察者可以在 Gateway 关闭期间保持活动。已绑定的传输请求本身也如此;场景截止时间不会落定已派发的请求。
  2. 宿主停止 Gateway 并确认进程关闭。
  3. captureBeforeGatewayCleanup() 在临时 Gateway 状态被移除前,对最终原生收据进行快照。成功捕获在每次 Gateway 生命周期中只运行一次。抛出的错误会保留运行时证据并使拆除失败;但不会阻止停止后的 fixture 清理。
  4. 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 运行时所需的哪些受信任模块预加载
  • 如何处理特定于传输的重置或清理

新通道的最低采用标准:

  1. 保持 qa-lab 作为共享 qa 根的所有者。
  2. 在共享的 qa-lab 宿主接缝上实现传输 runner。
  3. 将特定于传输的机制保留在 runner 插件或通道 harness 内。
  4. 将 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 的适配器。
  5. 在主题化的 qa/scenarios/ 目录下创建或适配 YAML 场景。
  6. 对新场景使用通用场景辅助函数。
  7. 除非仓库正在进行有意迁移,否则保持现有兼容性别名可用。

决策规则是严格的:

  • 如果行为可以在 qa-lab 中表达一次,就将其放在 qa-lab 中。
  • 如果行为依赖于一个通道传输,就将其保留在该 runner 插件或插件 harness 中。
  • 如果场景需要一个多个通道都可以使用的新能力,请添加通用辅助函数,而不是在 suite.ts 中添加特定于通道的分支。
  • 如果某个行为仅对一个传输有意义,请保持场景特定于传输,并在场景契约中明确说明。

场景辅助函数名称

新场景首选的通用辅助函数:

  • waitForTransportReady
  • waitForChannelReady
  • injectInboundMessage
  • injectOutboundMessage
  • waitForOutboundMessage
  • waitForNoTransportOutbound
  • getTransportSnapshot
  • readTransportMessage
  • readTransportTranscript
  • formatTransportTranscript
  • resetTransport

兼容性别名对现有场景仍然可用 - waitForQaChannelReady、waitForNoOutbound、formatConversationTranscript 和 resetBus - 但新场景编写应使用通用名称。 对于出站检查,请使用规范的 waitForOutboundMessage,而不是 添加特定于传输或通道的出站等待别名。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw