QA Test Runner 是 QA 流程中的执行与修复阶段。它的输入是已经确认的用例、spec-task 和测试脚本；输出是执行证据、修复后的代码、completion 门禁结果和更新后的 test-cases.json。报告生成和最终判定不属于本阶段。
【工作方式】 本工具包通过 CLI 调用，脚本为 quality-assurance-agent/scripts/qa_agent.py，不以 PATH 命令形式分发，命令由 agent 执行。开工前需解析一次 skill 目录，之后所有命令统一写成 python "$QA_AGENT_DIR/scripts/qa_agent.py" <cmd>。完整命令语法见主 skill 的 CLI 命令参考，测试脚本执行推荐使用 run-with-env（自动处理 CRLF、环境变量和日志）。
【前置条件】 需要 .qa-agent/current/test-cases.json 已确认、test-spec-tasks.json 存在、coverage-balance.json 通过，可通过 manifest.json 确认状态。
【执行流程】 按 spec-task 顺序执行，同时注意数据依赖：需要余额充足的用例先跑；余额不足的用例可临时下调余额、跑完立即还原；已使用资产的用例可复用前置正向用例消耗后的资产；过期资产或不可购买商品的用例临时修改数据字段后立即还原。执行方式按层区分：api 层用 bash 脚本配合 run-with-env；需数据库验证的 integration 层先读 mysql-mcp-integration.md，跑脚本后按 oracle.db 结构化逐条校验并记录查询摘要、期望、实际、状态；verificationMode 为 direct-db 的数据完整性 task 直接通过 MySQL MCP read_query 执行断言，不允许降级为手工核对；e2e 层先读 playwright-agent-integration.md，通过 Playwright MCP 真实浏览器操作。每个 task 执行后立即更新 executionStatus 和 evidence，evidence 必须是非空数组且至少包含一条命令行加输出摘要，含 DB 断言的 task 必须包含逐条 DB 校验结果。
【失败分类与修复循环】 每个失败必须先分类再决定是否修：测试脚本 bug（断言与 API 实际行为不符但 API 符合业务预期）修测试脚本；产品缺陷（返回值或数据库状态违反业务规则）修产品代码；环境问题（服务未启动、端口占用、MCP 断开、数据前提不符）修环境；测试基础设施 bug（fixture、配置加载、共享 setup/teardown 缺陷）修基础设施代码；需求歧义（不同来源预期不一致且本地证据无法判断）记录 blocker 并向上游报告。失败修复循环遵循 failure-repair-loop.md：分析失败、制定修复方案、最小改动执行、按最小失败范围重跑、验证；循环上限 maxRepairLoops（默认 5）轮，每轮必须换假设，重复相同结论即停止并按 blocker 上报。每修复一个产品缺陷或测试基础设施 bug，应立即沉淀为 bug-pattern。
【数据还原与门禁】 临时测试数据优先使用 PRE/POST 自声明并在 task 执行后立刻还原，统一还原作为兜底，通过 MySQL MCP 或后端 API 核实。之后运行 assert-completion 门禁，若出现 case-without-spec-tasks 且 tasks=0，通常是 task 缺少 priority 字段导致被过滤，补全后重跑。completion-check 通过后，连同执行证据移交 qa-code-reviewer 做代码审查，再由 qa-report-generator 汇总报告。
【经验沉淀与状态回写】 通过 save-knowledge 把新知识追加到项目经验库，分类包括 api-quirk、environment、data-prep、test-pattern、bug-pattern；应记录 API 响应特殊约定、环境特性、测试数据构造技巧、前端防御机制等，不记录通用编程知识和已有项目规范。最后把 passed/failed/blocked 状态写回 test-cases.json，补充每个用例的 result.executedAt 和 result.outcome。
【容错与限制】 未分类失败套用三分类框架，无法归类则标记 blocker；MCP 全部不可用时所有 task 标记 blocked，不降级为手动验证通过；编码需通过 check-mojibake --strict。明确禁止：completion gate 失败时声称全部通过；把 gate 通过当作所有业务用例自动通过；给没有映射和证据的 task 标记 passed；用“手动验证/核对”冒充真实执行；未侦察数据就标 blocked；绕过或临时变更 spec-task 的 layer 与断言；以前端代码无变更为由跳过 E2E；用 browser_evaluate 直接调 API 代替真实 UI 操作；E2E 无独立脚本时现场手写脚本凑数。