QA Agent

QA Agent 是一个项目级 AI 测试运行时。它让开发者直接用自然语言发起真实 UI 检查，同时自动保存 Task、Run、截图、业务观察、Cleanup 和测试报告。

当前版本：v0.3.110（变更说明）

v0.3.110 更新亮点

• 回归脚本可编辑化 — 已发布的 .steps.json 可直接修改后重复回放；历史 Source Run 中的失败步骤或 terminate 不再阻塞脚本修复。
• 脚本版本历史 — 自动保存 revision、脚本 hash、快照和 diff。
• TestPlan rebase — 测试意图不变时可用 qa-agent regression rebase 重新绑定当前计划，无需重新跑 Source Run。
• 支持 v0.3.109 迁移 — qa-agent update 可将上一版本项目迁移到 v0.3.110。

v0.3.109 更新亮点

• iOS 系统 UI act 兜底 — 优先使用 describe-system、wait-system 和 tap-system；系统桥接无法提供树或语义定位时，允许根据最新 act 截图使用 act tap --locator coordinate=x,y，仍由统一 Runner 截图和记录。
• Runner 连接自恢复 — iOS Runner 检测到失效的 IDB companion 连接后自动重连一次，连续 qa-agent act 不需要切换到其他 UI 工具。

v0.3.107 更新亮点

• Hash 改为可审计警告 — scriptHash 不再阻断回归发布或回放；不一致时记录 expected/observed hash，并在报告和验证结果中提示。
• 修复 0.3.106 迁移 — qa-agent update 同步并修复 regression manifest 的脚本 hash。

v0.3.106 更新亮点

• 统一测试确认 — 除 Guided 外，所有测试类型都只需一次“确认测试并开始执行”；不再按风险、读写、测试数据或 Release 分支增加确认。
• Guided 直接进入 — Guided 由 Skill 唤起，不请求入口确认；执行时逐步确认每个操作和结果。
• 仅迁移上一版本 — qa-agent update 只将 v0.3.107 项目迁移到当前格式，迁移完成后运行时不再兼容更早旧逻辑。
• 回归脚本先生成后补齐 — 缺少 locator、inputRef 或证据时先生成带 missingBindings 的草稿，补齐后再发布，不再强制重跑 Source Run。

v0.3.103 更新亮点

• 修复连续 qa-agent act 调用反复关闭并重新打开浏览器的问题；同一 Run 现在复用持久化 Runner、页面和登录态。
• 修复 Runner 并发访问和截图序号覆盖问题。

v0.3.102 更新亮点

• Web 测试启动前可选择可视化或后台模式；回归执行默认无头，也支持人工显式打开浏览器。

v0.3.101 更新亮点

• Agent 自动判断平台 — Agent 读取源码、配置和可用能力后，将唯一 Web 或 iOS 平台写入 PlanDraft；只有平台不明确时才询问 QA。

• 统一执行契约 — 标题、语言和报告展示变化不触发重新确认；步骤、预期结果、平台等执行契约变化会让旧确认失效。

• 锁定内置 Runner — 当前仅支持 Web 和 iOS Simulator；所有 UI 测试、qa-agent act 和回归回放都经过统一 Runner，禁止 MCP 绕过。

• 平台不匹配先 Doctor — Web/iOS 切换会先运行 qa-agent doctor --platforms ...，再重新应用正确平台的 PlanDraft。

• 全局 Runner 解析 — 优先使用 QA_AGENT_RUNNER_DIR 和 npm 包内 Runner，初始化不再复制执行器到项目。

• 执行契约哈希简化 — 标题、描述、模块展示快照变化不再让回归步骤失效；平台、步骤、断言、安全和数据变化仍会标记 stale。

• 统一 Python 执行器打包 — npm 包现在包含 runner/，JSON 回放使用统一执行器；

• qa-agent-doctor — 新增首次环境引导 Skill，区分阻塞能力和推荐工具，并按步骤提示修复；

• 回归步骤导出 — 新增 qa-agent regression export，可从 Source Run 中提取已记录步骤并立即导出 JSON 回放草稿；

• 能力检测系统 — qa-agent doctor 增强，自动检测浏览器、模拟器、设备及 Python 回归环境就绪状态；

• UI 交互原语 — 新增 act / driver 模块，统一管理宿主 Agent 的 UI 操作调用与结果判定；

• 任务生命周期管理 — 引擎重构，Source Run 冻结、回归运行隔离、TestPlan 变更时脚本状态自动标记为 stale；

• 托管 Runtime 升级 — 仅支持从上一版本 v0.3.107 迁移；更早版本请重新初始化项目。

适合解决什么问题

• 测试 Web 或 iOS Simulator 功能；
• 让 Agent 读取项目源码后规划测试入口；
• 保存每次真实操作、截图和业务结果；
• 中断后继续当前测试；
• 将验证过的流程升级为可重复回归；
• 发布前执行影响分析和 GO/NO-GO 检查。

QA Agent 只通过内置 Runner 执行 Web 和 iOS Simulator。Agent 只能调用 qa-agent act 和 Runtime 命令，不能直接调用 MCP、Playwright、ADB、xcrun、idb 或其他 UI 工具。

对于 iOS 系统权限弹窗和系统相册选择器，优先使用 qa-agent act describe-system、tap-system 和 wait-system。这些命令通过 Runner 内置的短生命周期 XCTest 桥接访问指定系统进程；例如 --bundle-id com.apple.springboard 可查询权限弹窗。若系统桥接无法提供 UI 树或语义定位，则根据最新 act 截图使用 qa-agent act tap --locator coordinate=x,y 兜底；系统 UI 仍会自动截图并记录到当前 Run。

安装

要求：

• Node.js 22.6 或更高版本；
• 一个支持 Skill、命令或项目规则的 Agent 宿主；
• 执行真实 UI 测试时，需要浏览器、模拟器或设备操作能力。

npm install -g qa-agent-skill
qa-agent --version   # 应输出 0.3.110

进入被测项目并初始化，同时配置宿主（可多选）：

cd /path/to/project
qa-agent init --cursor --codex --claude

支持的宿主 flag：--cursor、--codex、--claude、--copilot、--gemini、--opencode、--agents。

初始化后运行 Doctor 检查能力是否就绪：

qa-agent doctor

Doctor 会检查项目初始化完整性、统一 Runner、Python、Playwright，或 iOS 的 xcrun simctl、idb 和模拟器状态。当前平台的执行前置条件缺失会阻塞测试，并提示下一条修复命令；其他建议项不会替代内置 Runner。

推荐回归技术栈详见 skill/qa-agent/references/recommended-regression-stack.md。

Python Runtime Agent 详见 skill/qa-agent/references/regression-runner.md。

5 分钟 Quick Start

1. qa-agent init --cursor        # 初始化项目和宿主
2. qa-agent doctor               # 确认能力就绪
3. 在 Agent 对话中说：帮我测试登录流程
4. Agent 阅读源码、生成 PRD 并展示
5. Agent 阅读源码并将唯一平台写入 PlanDraft；只有平台不明确时才询问 QA
6. Agent 明确 `executionIntent` 并重新应用 PlanDraft
7. 普通测试：QA 回复“确认测试并开始执行”；Guided 测试由 Skill 直接进入，之后逐步确认操作和结果
8. Agent 执行测试并生成报告

两种模式可选：

• 普通模式（默认）：帮我测试登录流程。 — AI 按已批准 PRD 连续执行。
• Guided 模式：以 QA 引导模式测试首次安装的 Welcome Dialog。 — QA 逐步批准每个操作并判定结果。

完整 10 步流程详见 skill/qa-agent/references/full-workflow.md。

统一 Runner 的 iOS 示例见 ios-search-bvl.steps.json：它会在 com.rechic.apps 中输入并清空搜索框、搜索 bvl、点击 Bvlgari 商品进入详情页、滚动并断言商品信息。命令、locator 和 JSON 回放契约详见 skill/qa-agent/references/cli-command-reference.md 与 skill/qa-agent/references/regression-runner.md。

常用命令速查

qa-agent init                  # 初始化项目和宿主
qa-agent check --request TEXT  # 创建或恢复 Task（不启动 Run）
qa-agent test                  # 执行已审批的 Task
qa-agent continue              # 继续当前 Session 绑定的 Task
qa-agent finish                # 关闭当前 Session（不归档 Task）
qa-agent doctor                # 检查项目和宿主能力
qa-agent update                # 刷新同版本 Runtime 托管文件

Guided 模式命令

qa-agent check --mode guided --request "测试 Welcome Dialog"
qa-agent run guide-approve RUN --scenario SCENARIO --planned-step STEP
qa-agent act COMMAND --run RUN --planned-step STEP ...
qa-agent run guide-verdict RUN --step STEP --status passed

回归相关命令

qa-agent regression export --module MODULE --task TASK --run RUN_ID [--id SCRIPT_ID]
                               # 从 Source Run 导出 JSON steps 草稿
qa-agent regression drafts      # 查看当前 Session 的草稿
qa-agent regression draft-show SCRIPT_ID
                               # 查看完整 JSON steps
qa-agent regression bind SCRIPT_ID --module MODULE --task TASK --step STEP_ID [--locator "strategy=value"] [--input-ref KEY]
                               # 补齐草稿中的定位器或输入引用
qa-agent regression publish --module MODULE --task TASK --draft SCRIPT_ID --confirmed-by HUMAN
                               # 经单独审核后发布
qa-agent regression rebase SCRIPT_ID --module MODULE --task TASK --confirmed-by HUMAN
                               # 测试意图不变时重新绑定当前 TestPlan，不重新跑 Source Run
qa-agent regression run SCRIPT_ID --module MODULE --task TASK
                               # 直接回放可编辑的已发布 steps；修改后无需重新发布

发布后的 regression/SCRIPT_ID.steps.json 是可维护脚本。修复 locator、inputRef、等待或删除错误步骤后，直接再次执行 regression run 即可。每次执行的脚本 revision、hash、历史快照和 diff 会保存在 regression/history/SCRIPT_ID/。

查看高级命令：

qa-agent help --advanced

完整命令参考详见 skill/qa-agent/references/cli-command-reference.md。

生成文件与目录结构详见 skill/qa-agent/references/directory-structure.md。

项目验证

qa-agent doctor
qa-agent validate

开发本项目：

npm install
npm run verify      # TypeScript 检查 + 构建 + 完整测试
npm run pack:check

四个 Skill

• qa-agent：非 Guided 测试统一使用一次确认，Guided 由 Skill 直接进入，并提供发布计划、JSON steps 导出与发布（统一 Runner 负责回放）；
• qa-agent-doctor：首次初始化、Runner、Python、浏览器/模拟器和 Host capability 的环境检测与分步引导；
• qa-agent-guided：QA 主导的单步测试，每个操作前批准、操作后判定，完成后自动生成场景回归草稿；
• qa-agent-regression-test：通过统一 Runner 回放 Task 中已发布的 JSON steps，支持 Web（Playwright）和 iOS 模拟器执行，并审视自动生成的回归报告。