# qa

> QA 测试套件编排：结构化测试规范 → 自动安装 bridge → 运行游戏 → 逐步执行 → 聚合报告 + 回归 diff。步骤类型：input/wait/wait_frames/freeze/unfreeze/step_until/snapshot/restore/set/call/watch_start|stop/monitor_start|stop/assert/screenshot/sleep；断言 8 种与各字段语义见 schema 字段 description。run 支持 mode:async 后台执行(qa status/cancel 管理)。报告落 ~/.godot-mcp/qa-reports/<run_id>.{json,md}。

| 属性 | 值 |
|------|-----|
| 所属层 | bridge |
| 安全级别 | guarded |
| 需要 Godot | 是 |
| 需要编辑器 | 否 |
| 只读 | 否 |
| 长耗时 | 是 |

## Actions

- `run`
- `report`
- `diff`
- `status`
- `cancel`

## Parameters

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `action` | enum (5 项) | ✓ | run=执行套件；report=读报告；diff=对比两份报告找回归；status=查运行注册表(进度/终态)；cancel=取消进行中的 run |
| `mode` | enum: sync | async |  | run: sync=同步等完整结果;async=立即返回 run_id 后台执行(用 qa status 轮询/qa cancel 取消)。默认:未显式指定时,客户端声明 MCP tasks 能力则自动 async,否则 sync |
| `run_id` | string |  | status/cancel: 目标 run_id(status 省略=列出全部注册 run) |
| `spec` | object |  | run: inline 套件 spec 对象。步骤为 discriminated union(type 字段决定形态)：input(method+params,bridge 原生参数)、wait(wait_for_node/wait_for_property 轮询)、wait_frames(1-60 帧确定性推进)、freeze/unfreeze、step_until(结构化条件{path,property,op,value}[]，规避 RCE)、snapshot/restore、set(写节点属性)、call(bridge 只读白名单方法，写方法需 GODOT_MCP_BRIDGE_EXTRA_METHODS)、watch_start(node_path+signal_name，单套件单 watch)、watch_stop、monitor_start(node_path+properties[]，单套件单 monitor)、monitor_stop、screenshot(证据落报告目录)、sleep。步骤带 label 便于 diff 对齐 |
| `spec_path` | string |  | run: spec 文件路径(.json 或含 ```qa-spec 围栏的 .md)，大套件建议用文件避免 token 截断；须在 ALLOWED_PROJECT_PATHS 白名单内 |
| `project_path` | string |  | run: 项目路径(覆盖 spec 内的 project_path；spec 未写时必填) |
| `report_path` | string |  | report: 报告路径或 run_id；latest=最新，prev=次新 |
| `base_path` | string |  | diff: 基线报告(默认 prev) |
| `head_path` | string |  | diff: 对比报告(默认 latest) |

## 风险分布

读 3 / 进程 2

---
<!-- AUTO-GENERATED by scripts/gen-tool-docs.mjs from capability-matrix.json v0.32.21. DO NOT edit manually; re-run npm run gen:tool-docs after tool changes. -->