OneKey QA-AGENTS — 一图看懂自动化测试系统

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

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

👔

决策层 — "老板"

负责拍板：该做什么、先做哪个、出了问题怎么办。

🎬

QA 总导演 (Director)

整个测试流程的总调度。它决定先跑哪些测试、检查前置条件够不够、测试失败了要不要重试。就像电影导演喊"Action!"的那个人。

🚦

环境准备员 (QATest)

说一句"qatest 开始执行"，它就自动检查/启动 OneKey CDP 和 Dashboard 面板，把执行环境一键准备好，省得你手动开一堆终端。

👆 点击展开

↕

🧠

智能层 — "技术骨干"

出主意、做诊断、维护团队的"记忆库"。

📝

用例设计师 (Test Designer)

把产品需求翻译成"要测什么"。比如产品经理说"用户能搜索代币"，它就写出"搜索 BTC 应该出现比特币"这样的测试场景。

📚

知识管理员 (Knowledge Builder)

维护整个团队的"笔记本"——哪个按钮在页面的什么位置、之前遇到过什么坑、怎么找到特定元素。它是唯一能修改知识库的角色。

🔍

质检经理 (QA Manager)

测试失败时的"医生"。它只负责诊断问题出在哪（是按钮找不到了？还是网络太慢？），但不动手修——修的活儿交给别人。

🔎

代码审查员 (QA Review)

提交前的最后一道把关。检查用例 / 规则 / 脚本 / Skill 的规范性、一致性和安全性。安全问题硬拦截，其他可确认跳过。审查报告存到 shared/reports/review-*.md。

👆 点击展开

↕

⚡

执行层 — "一线员工"

真正动手干活的：录操作、跑测试、写报告。

🎥

录制员 (Recorder)

像一台摄像机，你在 App 上点哪里、输入什么，它都记下来。桌面 / Web / Extension 三种端各有专门的录制监控页面。录完之后会问你"我记对了吗？"，确认后才交给下一步。

📂

用例录制员 (Record From File)

指着一个用例文档说"@这个文件开始录制"——它会先把里面的场景重新编排成连续操作流、列出覆盖映射，再引导你一段段录，最后生成可执行的 .test.mjs。

📱

手机录制员 (Record to Test)

专门负责 Android：你在真机上操作，它录下来 → 列操作清单让你确认 → 生成 Midscene Hybrid 测试脚本（UIAutomator 优先 + AI Vision 兜底）。

🏃

执行员 (Runner)

拿着写好的"测试剧本"在 App 上自动跑一遍。它按顺序点击、输入、检查结果，就像一个不知疲倦的测试工程师。统一入口：src/tests/run.mjs。

📊

报告员 (Reporter)

把测试结果整理成一目了然的报告：多少通过、多少失败、失败率是涨了还是降了，帮团队快速了解质量状况。

👆 点击展开

三步搞定自动化测试

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

🎬 录制

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

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

→

⚙️ 生成

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

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

→

🔄 回归

每次 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、Android 四种形态。QA-AGENTS 能分别连接它们，用类似的方式测试。每次会话首次连接时会让你 4 选 1。

🖥️

Desktop

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

端口 9222

录制监控：localhost:3210
路径配置：ONEKEY_BIN

🌐

Web

在浏览器里打开的 OneKey 网页版。直接用 Chrome 打开测试，会自动扫描可用 Chrome Profile 让你选，登录状态保留。

端口 9222 (复用)

录制监控：localhost:3211

🧩

Extension

安装在 Chrome 浏览器里的 OneKey 扩展。需要提供 Extension ID + Chrome Profile，自动通过 CDP 连接。

端口 9222 (复用)

录制监控：localhost:3210

📱

Android

真机 USB 连接，通过 UIAutomatorAndroid 系统自带的 UI 测试框架，可以读 App 内的按钮、文字等元素。 + AI Vision无 testid 时用 AI 看截图找元素，类似肉眼定位。混合执行。Midscene 框架。

adb USB

录制监控：localhost:3210
引擎：Midscene Hybrid

连接方式一句话总结：
测试脚本 → 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	知识管理员	归类后的"错题集"，相似问题归到一起
ui-semantic-map.json	知识管理员	新版"语义定位层"：生成用例和维护时优先引用，比 ui-map 更稳定
generated/app-monorepo-testid-index.json	知识管理员	从 app-monorepo 源码 `x` 分支同步过来的 testID 全集
runtime-config.json	Dashboard UI	本机钱包账户配置（转账用例需要），gitignored，每人本地配一次
checklists.json	Dashboard UI	回归 Checklist 集合，Dashboard 左侧面板可视化管理
reports/review-*.md	代码审查员	提交前 `/qa-review` 跑出来的审查报告

项目文件一览

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

▶ 📁 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/ — 所有测试脚本（按平台分层）
- 📄run.mjs— 统一 CLI Runner 入口
- ▶ 📁 desktop/ — 桌面端用例（TF / MAS 包）
  - ▶ 📁 market/ — 行情模块（搜索 / 收藏 / 图表）
    - 📄search.test.mjs— 搜索代币
    - 📄favorite.test.mjs— 收藏功能
    - 📄chart.test.mjs— K线图表
  - ▶ 📁 perps/ — 合约交易（图表 / 收藏 / 搜索 / 持仓）
  - ▶ 📁 swap/ — 兑换
  - ▶ 📁 transfer/ — 多链转账（含 Cosmos 等）
  - ▶ 📁 wallet/ — 钱包创建 / 导入
  - ▶ 📁 settings/ — 语言 / 主题 / 通用设置
  - ▶ 📁 referral/ — 推荐返佣
  - ▶ 📁 utility/ — 地址簿 / 全局搜索 / 货币切换等通用工具
- ▶ 📁 extension/ — 浏览器插件端用例（市场 / 合约 / 钱包 / 转账 / 推荐...）
- ▶ 📁 web/ — Web 端用例（app.onekey.so）
- ▶ 📁 android/ — Android 真机用例（Midscene Hybrid + UIAutomator）
  - 📄recorder.mjs— Android 录制器
  - 📄runner.mjs— Android 执行器
  - 📁helpers/— smartTap / hybridTap / hasText 等
  - 📁wallet/ contract/ ...— 各模块用例
- ▶ 📁 mobile/ — 部分跨端 mobile 通用脚本
- ▶ 📁 helpers/ — 共享工具函数
  - 📄index.mjs— CDP 连接、截图、基础工具
  - 📄navigation.mjs— 页面导航、关闭弹窗
  - 📄accounts.mjs— 账户/钱包操作
  - 📄network.mjs— 网络请求工具
  - 📄transfer.mjs— 转账操作工具
  - 📄preconditions.mjs— 前置条件检查 + 跟踪
  - 📄components.mjs— 公共组件（safeStep / createStepTracker）
  - 📄runtime-config.mjs— 读取 Dashboard 配置的钱包账户
▶ 📁 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/ — ⚠️ 已废弃，请用 src/tests/run.mjs
▶ 📁 scripts/ — 项目脚本
- 📄clean.mjs— npm run clean 清理产物
- 📄build-locator-map.mjs— 构建定位器映射
- 📄sync-app-monorepo-selectors.mjs— 同步 app-monorepo x 分支 testID
- 📄start-chrome-debug.sh— 带 CDP 启动 Chrome
▶ 📁 shared/ — 共享数据文件 (Agent 间通信)
- 📋test_cases.json— 测试用例清单
- 📋ui-map.json— 页面元素地址簿（执行期，三层选择器）
- 📋ui-semantic-map.json— 语义定位层（生成/维护优先引用）
- 📋knowledge.json— 经验知识库
- 📋diagnosis.json— 失败诊断表
- 📋preconditions.json— 公共前置条件
- 📋mem_cells.json— 原始记忆事件
- 📋mem_scenes.json— 聚类场景
- 📋profile.json— Agent 能力画像
- 📋runtime-config.json— 钱包账户配置（本机，gitignored）
- 📋checklists.json— 回归 Checklist 集合（Dashboard 管理）
- 📋tasks.json— 任务队列
- 📁generated/— app-monorepo 同步产物（testID 索引等）
- 📁results/— 执行结果文件 (<TEST-ID>.json)
- 📁reports/— 质量报告 + Review 报告

快捷指令速查

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

录制相关

你说	AI 做什么
@用例文件.md 开始录制	读取用例 → 启动录制器 → 引导你逐场景操作（Desktop/Web/Extension）
@文件 /onekey-record-from-file	用例文件 → 场景重编排 → 输出覆盖映射 → 引导录制 → 生成 `.test.mjs`
录完了	展示录制到的每一步，等你确认
录制测试	Android 流程：真机录制 → 确认 → 生成 Midscene 脚本 → 验证

执行相关

你说	AI 做什么
qatest 开始执行	启动 App + Dashboard，打开执行面板
跑测试	执行 → 汇总结果 → 失败自动诊断
执行测试 MARKET-SEARCH-002	只跑指定的那一个用例

诊断和报告

你说	AI 做什么
诊断失败	分析最近失败的用例，给出根因和修复建议
为什么失败 MARKET-FAV-003	分析指定用例的失败原因
更新选择器	修复失效的页面元素定位
生成报告	生成测试质量报告

设计相关

你说	AI 做什么
设计用例	从需求文档分析，设计测试场景
写用例	同上
@需求文档生成测试用例	PRD → 结构化用例 → 输出到 `docs/qa/testcases/cases/<模块>/`

审查 / 清理

你说	AI 做什么
/qa-review 或审查提交	提交前检查用例 / 规则 / 脚本 / Skill 的规范性 + 安全性，报告存到 `shared/reports/review-*.md`
npm run clean	清理 dist、录制截图、Android session、DS_Store（保留 result JSON）

环境准备

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

需要安装的软件

OneKey Desktop TF / MAS 包（桌面端测试用，自动启动）

Google Chrome Web / 插件端测试用（自动扫描 Profile）

Android 真机 + adb Android 测试用，USB 连接

Node.js 20+ 运行脚本和面板

npm install playwright-core / midscene / webdriverio 等

端口分配

CDP（统一） 9222

Dashboard 面板 5050

桌面端录制监控 3210

Web 端录制监控 3211

Android adb (USB)

环境变量（.env 文件）

ONEKEY_BIN OneKey 桌面端可执行文件路径（必填，桌面测试用）— 默认 /Applications/OneKey-3.localized/OneKey.app/Contents/MacOS/OneKey

CDP_URL CDP 连接地址，默认 http://127.0.0.1:9222

WALLET_PASSWORD 钱包解锁密码

AI 视觉模型 (Android) OpenAI / Anthropic API key（Android 测试需要）

常见问题

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

录制完成后 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
• 需要硬件钱包的操作 — 需要物理按键确认
• 短信 / 邮件验证 — 涉及外部系统