QA-AGENTS

多 Agent 协作的自动化测试系统
覆盖 Desktop、Web、Extension 三个平台
下面带你看看它是怎么运转的

🎬 想象一下：你操作一遍 App，AI 就自动帮你写好测试剧本，以后每次更新都替你演一遍，确保没出岔子。
↓

三层架构：像一个测试团队

就像一家公司有老板、技术骨干和一线员工一样，QA-AGENTS 也分成三层，各司其职。点击每一层看看里面都有谁。

👔
决策层 — "老板"
负责拍板：该做什么、先做哪个、出了问题怎么办。
🎬
QA 总导演 (Director)
整个测试流程的总调度。它决定先跑哪些测试、检查前置条件够不够、测试失败了要不要重试。就像电影导演喊"Action!"的那个人。
👆 点击展开
↕
🧠
智能层 — "技术骨干"
出主意、做诊断、维护团队的"记忆库"。
📝
用例设计师 (Test Designer)
把产品需求翻译成"要测什么"。比如产品经理说"用户能搜索代币"，它就写出"搜索 BTC 应该出现比特币"这样的测试场景。
📚
知识管理员 (Knowledge Builder)
维护整个团队的"笔记本"——哪个按钮在页面的什么位置、之前遇到过什么坑、怎么找到特定元素。它是唯一能修改知识库的角色。
🔍
质检经理 (QA Manager)
测试失败时的"医生"。它只负责诊断问题出在哪（是按钮找不到了？还是网络太慢？），但不动手修——修的活儿交给别人。
👆 点击展开
↕
⚡
执行层 — "一线员工"
真正动手干活的：录操作、跑测试、写报告。
🎥
录制员 (Recorder)
像一台摄像机，你在 App 上点哪里、输入什么，它都记下来。录完之后会问你"我记对了吗？"，确认后才交给下一步。
🏃
执行员 (Runner)
拿着写好的"测试剧本"在 App 上自动跑一遍。它按顺序点击、输入、检查结果，就像一个不知疲倦的测试工程师。
📊
报告员 (Reporter)
把测试结果整理成一目了然的报告：多少通过、多少失败、失败率是涨了还是降了，帮团队快速了解质量状况。
👆 点击展开

三步搞定自动化测试

从"手动操作一遍"到"自动反复测试"，只需要三步。

1

🎬 录制

你在 OneKey App 上正常操作——点按钮、输文字、切页面。录制员在后台默默记下你的每一步。

就像有人拿手机帮你录屏，但记录的不是画面，而是"你点了哪个按钮"。

→
2

⚙️ 生成

AI 把你的操作翻译成测试脚本——一段能自动重复你刚才操作的代码。它还会验证脚本能跑通。

你教了 AI 一遍，它就学会了，以后可以自己来。

→
3

🔄 回归

每次 App 更新后，打开测试面板（Dashboard），勾选要测的用例，点一下"执行"，AI 就自动帮你跑一遍。

就像每次装修完房子，自动检查一遍水电是不是都正常。

技术工具箱

这些是 QA-AGENTS 用到的核心技术。别被名字吓到，每一个都有大白话解释。

🔌

CDP

大白话：一根"遥控线"。把这根线插到 OneKey App 上，我们的测试工具就能远程控制它——帮你点按钮、输文字、读页面内容。
Chrome DevTools Protocol — Chrome/Electron 应用的远程调试协议
🎭

Playwright

大白话：一个"虚拟手指"。它能模拟人的操作——点击、滚动、打字，而且速度飞快、永不手抖。通过上面说的 CDP "遥控线"来操作 App。
Microsoft 开发的浏览器自动化库，支持多浏览器
📦

Electron

大白话：OneKey 桌面版的"外壳"。它让网页技术做的界面可以像普通软件一样安装在电脑上运行。所以我们用网页测试工具就能测桌面 App。
用 Web 技术构建跨平台桌面应用的框架
🤖

Claude Code

大白话：整个系统的"大脑"。它是一个 AI 助手，能理解你说的话、分析测试用例文档、生成测试代码，还能诊断失败原因。你对它说中文就行。
Anthropic 的 AI 编程助手，驱动多智能体协作
🗂️

Node.js

大白话：运行测试脚本的"引擎"。就像汽车需要发动机来跑起来，测试脚本需要 Node.js 来执行。它还负责启动 Dashboard 面板。
基于 V8 的 JavaScript 运行时环境
📋

JSON

大白话：系统内部的"便签纸"格式。所有的配置、测试数据、知识库都用这种格式存储——它就像一种特别整齐的笔记格式，人能看懂，机器也能读。
JavaScript Object Notation — 轻量级数据交换格式

它们是怎么"聊天"的？

每个 Agent 之间的协作，就像同事在群里发消息一样。选择一个场景，看看它们是怎么配合的。

三个平台，一套测试

OneKey 有 Desktop、Web 和 Extension 三种形态。QA-AGENTS 能分别连接它们，用类似的方式测试。

🖥️

Desktop

装在电脑上的 OneKey 应用。通过 Electron一种让网页技术变成桌面软件的技术。你用的 VS Code、Discord 都是用它做的。 技术开发，所以能用网页测试工具来测。

端口 9222

录制监控：localhost:3210

🌐

Web

在浏览器里打开的 OneKey 网页版。直接用 Chrome 打开测试，会自动复制你的浏览器配置，这样登录状态什么的都在。

端口 9223

录制监控：localhost:3211

🧩

Extension

安装在 Chrome 浏览器里的 OneKey 扩展。测试时会复制完整的浏览器数据目录，保留扩展和设置，就像克隆了一个你的浏览器。

端口 9224

录制监控：localhost:3212

连接方式一句话总结：
测试脚本 → Playwright（虚拟手指）→ CDP（遥控线）→ App（被测应用）

学习系统：越测越聪明

QA-AGENTS 有一套"记忆系统"，能从每次测试中学习，下次遇到类似问题时更快解决。

📝

原始记忆

每次测试的结果都会被记下来：用了哪个选择器、花了多长时间、成功还是失败。就像一个人的日记本，什么都记。

→
🗂️

归类整理

把相似的记忆分组。比如"在桌面端经常找不到搜索按钮"会被归成一个场景。就像把散乱的笔记整理成一本错题集。

→
💡

智能回忆

下次碰到类似问题时，系统会自动翻错题集，找出之前是怎么解决的。不用每次都从头分析，效率越来越高。

举个例子 🌰

搜索按钮找不到 ×3 → 归类：桌面端选择器失效 → 回忆：用 fallback 选择器解决

系统发现同一个按钮连续 3 次找不到，自动归类为"选择器失效"，下次直接用备选方案，不再浪费时间重试。

数据流转：谁写谁读？

每个 Agent 都有自己的"专属笔记本"，只有指定的 Agent 能往里写，其他人只能看。这样就不会互相打架了。

数据文件 谁能写 用大白话说
test_cases.json 用例设计师 所有要测的内容清单，类似"考试大纲"
ui-map.json 知识管理员 页面上每个按钮/输入框的"地址"，方便测试工具找到它们
knowledge.json 知识管理员 积累的经验和技巧，比如"这个弹窗要等 2 秒才出来"
diagnosis.json 质检经理 失败原因分析，类似"病历表"
results/*.json 执行员 每次测试跑完的成绩单：通过/失败/跳过
reports/*.md 报告员 整理好的质量报告，给人看的那种
mem_cells.json 知识管理员 原始记忆条目，测试过程的"流水账"
mem_scenes.json 知识管理员 归类后的"错题集"，相似问题归到一起

项目文件一览

点击文件夹可以展开/收起。每个文件旁边都标注了它的作用。

  • ▶ 📁 src/cli/ — CLI JSON 接口 (外部编排入口)
    • 📄index.ts— CLI 主入口、命令分发
    • 📄run-handler.ts— 执行用例命令
    • 📄preflight-handler.ts— 前置条件检查命令
    • 📄result-handler.ts— 查询执行结果
    • 📄report-handler.ts— 生成报告
  • ▶ 📁 src/core/ — 核心基础模块
    • 📄knowledge-base.ts— 知识库读写
    • 📄logger.ts— 统一日志
    • 📄mailbox.ts— Agent 间消息通信
    • 📄task-board.ts— 任务看板
  • ▶ 📁 src/converters/ — 格式转换器
    • 📄bdd-to-json.ts— BDD 场景 → JSON 用例
    • 📄result-parser.ts— 执行结果解析
  • ▶ 📁 src/types/ — TypeScript 类型定义
    • 📄index.ts— 类型导出入口
    • 📄testcase.ts— 测试用例类型
    • 📄result.ts— 执行结果类型
    • 📄task.ts— 任务类型
    • 📄message.ts— 消息类型
    • 📄knowledge.ts— 知识库类型
  • ▶ 📁 src/schemas/ — JSON Schema 校验
    • 📄test-case.schema.json— 测试用例 schema
    • 📄ui-map.schema.json— UI 映射 schema
    • 📄diagnosis.schema.json— 诊断结果 schema
    • 📄mem-cell.schema.json— 记忆单元 schema
    • 📄mem-scene.schema.json— 记忆场景 schema
    • 📄profile.schema.json— Agent 能力 schema
    • 📄patch.schema.json— 回滚补丁 schema
  • ▶ 📁 src/utils/ — 通用工具
    • 📄file-utils.ts— 文件读写工具
  • ▶ 📁 src/tests/ — 所有测试脚本
    • ▶ 📁 desktop/ — 桌面端用例 (端口 9222)
      • ▶ 📁 market/ — 行情模块
        • 📄search.test.mjs— 搜索代币 (5个用例)
        • 📄favorite.test.mjs— 收藏功能 (6个用例)
        • 📄chart.test.mjs— K线图表
      • ▶ 📁 perps/ — 合约交易
        • 📄favorites.test.mjs— 合约收藏
        • 📄token-search.test.mjs— 合约代币搜索
      • ▶ 📁 settings/ — 系统设置
        • 📄language-switch.test.mjs— 切换语言
        • 📄theme-switch.test.mjs— 切换主题
      • ▶ 📁 wallet/ — 钱包操作
        • 📄create-mnemonic.test.mjs— 创建助记词钱包
      • ▶ 📁 referral/ — 推荐返佣
        • 📄bind-invite-code.test.mjs— 绑定邀请码
      • ▶ 📁 transfer/cosmos/ — Cosmos 转账
        • 📄transfer.test.mjs— Cosmos 链转账
      • ▶ 📁 utility/ — 通用功能
        • 📄universal-search.test.mjs— 全局搜索
    • ▶ 📁 web/ — 网页端用例 (端口 9223)
      • ▶ 📁 market/ — 行情模块
        • 📄search.test.mjs— WEB 搜索用例
        • 📄chart.test.mjs— WEB K线图表
      • ▶ 📁 perps/ — 合约交易
        • 📄favorites.test.mjs— WEB 合约收藏
        • 📄token-search.test.mjs— WEB 合约代币搜索
      • ▶ 📁 utility/ — 通用功能
        • 📄universal-search.test.mjs— WEB 全局搜索
    • ▶ 📁 extension/ — 插件端用例 (端口 9224)
      • ▶ 📁 market/ — 行情模块
        • 📄search.test.mjs— 插件搜索用例
        • 📄chart.test.mjs— 插件 K线图表
      • ▶ 📁 perps/ — 合约交易
        • 📄favorites.test.mjs— 插件合约收藏
        • 📄token-search.test.mjs— 插件合约代币搜索
      • ▶ 📁 utility/ — 通用功能
        • 📄universal-search.test.mjs— 插件全局搜索
    • ▶ 📁 helpers/ — 共享工具函数
      • 📄index.mjs— CDP 连接、截图、基础工具
      • 📄market-search.mjs— 搜索逻辑 (三端复用)
      • 📄market-chart.mjs— K线图表逻辑 (三端复用)
      • 📄preconditions.mjs— 前置条件检查
      • 📄navigation.mjs— 页面导航、关闭弹窗
      • 📄accounts.mjs— 账户/钱包操作
      • 📄extension-cdp.mjs— 插件端 CDP 连接
      • 📄network.mjs— 网络请求工具
      • 📄transfer.mjs— 转账操作工具
    • 📄run.mjs— 测试批量执行入口
  • ▶ 📁 src/recorder/ — 操作录制器
    • 📄index.mjs— 录制器入口
    • 📄listen.mjs— 桌面端录制 (监控页 :3210)
    • 📄listen-web.mjs— 网页端录制 (监控页 :3211)
    • 📄listen-ext.mjs— 插件端录制
    • 📄generate.mjs— 录制 → 测试代码生成
    • 📄capture-step.mjs— 单步捕获
    • 📄live-record.mjs— 实时录制
    • 📄record-flow.mjs— 流程录制
    • 📄review.mjs— 录制回放审查
    • 📄video.mjs— 视频录制
  • ▶ 📁 src/dashboard/ — 测试执行面板
    • 📄server.ts— 面板服务 (端口 5050)
    • 📄index.html— 面板页面
    • 📄recorder.html— 录制监控页面
    • 📄test-registry.ts— 自动发现用例文件
    • 📄test-executor.ts— 执行引擎
  • ▶ 📁 src/knowledge/ — 记忆与学习系统
    • 📄memory-pipeline.mjs— 三阶段记忆管线
  • ▶ 📁 src/runner/ — 测试执行引擎
    • 📄index.mjs— Runner 主逻辑 (状态恢复 + 多策略选择器)
  • ▶ 📁 shared/ — 共享数据文件 (Agent 间通信)
    • 📋test_cases.json— 测试用例清单
    • 📋ui-map.json— 页面元素地址簿
    • 📋knowledge.json— 经验知识库
    • 📋diagnosis.json— 失败诊断表
    • 📋preconditions.json— 公共前置条件
    • 📋mem_cells.json— 原始记忆事件
    • 📋mem_scenes.json— 聚类场景
    • 📋profile.json— Agent 能力画像
    • 📁results/— 执行结果文件
    • 📁reports/— 质量报告

快捷指令速查

在 Claude Code 对话框里直接输入这些话，AI 就知道你要干嘛。跟发微信一样简单。

录制相关
你说AI 做什么
@用例文件.md 开始录制读取用例 → 启动录制器 → 引导你逐场景操作
录完了展示录制到的每一步，等你确认
录制测试完整流程：录制 → 确认 → 生成脚本 → 验证通过
执行相关
你说AI 做什么
qatest 开始执行启动 App + Dashboard，打开执行面板
跑测试执行 → 汇总结果 → 失败自动诊断
执行测试 MARKET-SEARCH-002只跑指定的那一个用例
诊断和报告
你说AI 做什么
诊断失败分析最近失败的用例，给出根因和修复建议
为什么失败 MARKET-FAV-003分析指定用例的失败原因
更新选择器修复失效的页面元素定位
生成报告生成测试质量报告
设计相关
你说AI 做什么
设计用例从需求文档分析，设计测试场景
写用例同上

环境准备

开始之前需要准备这些东西。大部分都是"装好就不用管"的。

需要安装的软件

OneKey Desktop 桌面端测试用（自动启动）
Google Chrome Web / 插件端测试用
Node.js 20+ 运行脚本和面板
playwright-core npm install 即可

端口分配

桌面端 CDP 9222
Web 端 CDP 9223
插件端 CDP 9224
Dashboard 面板 5050
桌面端录制监控 3210
Web 端录制监控 3211

环境变量（可选，不设也能跑）

CDP_URL 桌面端连接地址，默认 http://127.0.0.1:9222
WEB_CDP_URL Web 端连接地址，默认 http://127.0.0.1:9223
EXT_CDP_URL 插件端连接地址，默认 http://127.0.0.1:9224
ONEKEY_EXT_ID 插件 ID（默认自动检测）
WALLET_PASSWORD 钱包解锁密码

常见问题

遇到问题先看这里，大部分情况都能自己解决。

录制完成后 AI 会列出所有步骤。监控页面（localhost:3210）上每一步旁边都有删除按钮，直接点掉多余的步骤就行。也可以直接告诉 AI "第 3 步多余了"或者"第 5 步应该是点另一个按钮"，AI 会帮你修正。
直接用口头描述告诉 AI 哪里不对。比如：
• "第 2 步应该是长按，不是点击"
• "漏了一步，在点搜索之前要先关掉弹窗"
• "最后还需要验证一下搜索结果里有没有价格"

AI 会根据你的描述补充或修改录制结果，不需要重新录一遍。
不用每端都从头录一遍。先录一个端（比如桌面端），确认脚本通过后，再告诉 AI "把这个用例覆盖到 Web 端和插件端"。AI 会自动复用核心逻辑，只适配各端不同的入口方式（比如桌面端点搜索框、Web 端点搜索图标、插件端先试输入框再 fallback 到图标）。大部分情况下只需要微调一两个地方。
这种情况需要告诉 AI 当前状态可能不同，让脚本先判断再操作。比如测试收藏功能：

• 默认推荐卡片不一定有本地数据，可能已经被收藏了
• 跟 AI 说："如果已收藏就先取消，再重新收藏来测试"

AI 会在脚本里加一段状态判断逻辑：先检查当前是什么状态，根据实际情况选择不同的操作路径。这样同一个脚本在不同环境下都能跑通。
先杀掉旧进程，再重新启动： pkill -f "OneKey" && sleep 2 /Applications/OneKey-3.localized/OneKey.app/Contents/MacOS/OneKey --remote-debugging-port=9222 & Web / 插件端同理，杀掉 Chrome 后脚本会自动重启。
打开录制监控页面（localhost:3210），看 CDP 状态指示灯。断开时点 Reconnect 按钮一键重连。录制器不会超时退出，别担心。
Node.js 会缓存模块，改了脚本后必须重启 Dashboard： pkill -f "tsx src/dashboard" && npx tsx src/dashboard/server.ts
清理旧的临时数据目录，重新运行时会自动复制： rm -rf /tmp/chrome-ext-cdp-profile
大概率是 UI 改版导致页面元素的定位（选择器）批量失效。不用一个个重录，直接告诉 AI "更新选择器"，知识管理员会自动扫描并修复失效的定位。修完后重跑一遍就行。
App 有时会弹出升级提示、公告通知等意外弹窗，挡住正常操作导致测试卡住或失败。跟 AI 说 "脚本前面加一步自动关弹窗"，它会在测试开始前自动检测并关闭这些弹窗。系统里已经有现成的 dismissOverlays 工具函数来做这件事。
这不是代码 bug，是环境问题。可以告诉 AI "这个步骤网络比较慢，多等一会儿"，AI 会增加轮询重试次数或调整等待时间。默认是重试 10 次、每次间隔 500ms，如果经常超时可以让 AI 调高。
三类操作目前没法自动化，AI 会提前告诉你：
• DApp 网页内的操作（比如点 Connect Wallet 按钮）— CDP 无法访问内置浏览器的 webview
• 需要硬件钱包的操作 — 需要物理按键确认
• 短信 / 邮件验证 — 涉及外部系统