BAT（Bot Acceptance Testing）用于从真实 AI 智能体的视角验证 MCP 工具是否正确工作。适用场景包括：PR 验证（确认工具改动在智能体视角下正常）、回归检测（比较不同分支行为）、集成验证（确保 MCP 工具与真实智能体 CLI 端到端可用）。
工作流程：分析改动并阅读 diff，确定受影响的工具；设计场景，生成包含 setup/test/teardown 提示词的场景 JSON；运行脚本，将场景通过管道传给 uv run python tests/uat/run_uat.py；评估摘要，检查每个智能体的 all_passed，为 true 即完成；失败时读取 results_file 查看完整输出、stderr 和原始 JSON；回归检查时用 --branch master 重新运行对比。
输出结构：运行器向 stdout 返回简洁摘要，包含 results_file、各智能体的 all_passed、test 阶段的 completed、duration_ms、exit_code、num_turns、tool_stats，以及跨阶段的 aggregate 统计。每个阶段包含 output，失败阶段在 stderr 非空时附带 stderr；完整原始 JSON 始终保存在 results_file。
场景设计指南：setup_prompt 创建测试所需实体或状态，test_prompt 调用被测工具并要求智能体清晰报告结果，teardown_prompt 清理创建的实体；每个场景只测试一种行为，并让智能体报告成功、失败和异常行为。
回归对比：从分支检出运行同一场景两次并比较统计。--branch master 会从 GitHub 安装 master 版 ha-mcp；省略 --branch 则运行本地代码，也覆盖未推送提交。主要指标为任务完成、准确性和工具成功率；次要指标为工具调用次数、轮次和耗时，耗时受网络、缓存和服务器负载影响，仅标记超过 2 倍的明显回退。
成本注意：每次场景调用消耗 API 额度（每个智能体每阶段一次），应合并相关检查、仅在需要特定状态时使用 setup/teardown，先用一个智能体，仅在需要跨智能体对比时扩展到两个。
调用参数：若参数包含场景描述，则生成 JSON 场景并运行；若为 --help 或无参数，显示帮助文本；否则将参数视为测试指令并据此设计运行场景。完整 CLI 参考和输出格式见 tests/uat/README.md。