Agent Whole Qa

---
name: agent-whole-qa
description: 上线前开浏览器把每个页面每个按钮全点一遍，FAIL 自动修
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, TaskCreate, TaskUpdate, TaskList, mcp__codegraph__codegraph_explore
disable-model-invocation: true
---

# agent-whole-qa — 全量验收 + 修复闭环编排器

> **与 `qa` agent 的关系**：`qa` 是「单模块测一次」的原子能力；本 skill 是「全模块 × 多轮 + 修复回环」的编排层，**复用 `qa`，不重写测试逻辑**。
> **与 `agent-mvp` 的关系**：`agent-mvp` 每阶段用 `qa` 做增量验收；本 skill 用于 **MVP 收口前的一次性全量清算**。

## ⛔ 六条硬约束（违反任一即本次验收无效）

### 1. 你是编排器，不是执行者
```
❌ 错：agent-whole-qa 自己测、自己修
        → 测的人知道修的人怎么想，修的人知道测的人怎么测 → 互相糊弄
✅ 对：agent-whole-qa 只做 清点 / 分发 / 汇总 / 循环控制

    agent-whole-qa（不碰代码，不碰需求）
       ├─ Agent(subagent_type=qa)  ──► 测（只拿到断言，不知道谁会修）
       └─ Agent(subagent_type=dev) ──► 修（只拿到 FAIL 清单，不知道怎么测的）
```
主控**绝不**自己写测试、自己改代码。发现自己在写 `expect(...)` 或改 `src/` 就是越界了。

### 2. 分母先锁定，再开测
INVENTORY 阶段的产物落盘后**本轮分母不可变更**。禁止中途以「这个按钮不用测」「这个接口是内部的」为由缩小分母。要改分母，只能作废本轮重新开始。

### 3. 禁止修需求
```
本 skill 及其派生的 dev subagent 对以下文件【只读，绝对禁写】：
    active/prd.md      active/ux.md      active/api.md
修不动 → 标记 ESCALATE 交人决策
```
> 这是 AI 修 bug 时最常走的偷懒路径：改断言让测试变绿。不用规则堵死，它一定会走。

### 4. 收敛门控
```
第 N 轮 FAIL 数 必须 < 第 N-1 轮 FAIL 数
  ├─ 不递减        → 停止，报告「未收敛」，交人决策
  ├─ 出现新增 FAIL → 停止（修 A 坏 B），报告震荡点，建议回滚本轮
  └─ 最多 3 轮
```

### 5. 回归门（每轮必跑）
```
每轮修完，重跑范围 = 本轮 FAIL 项  +  affected 算出的真实影响面
                                    ↑ 缺这半段就会「越修越坏」而毫不知情

  ⭐0.10.0：影响面从「同模块已 PASS 项」升级为 codegraph affected 算出的
  传递闭包 —— 同模块是人凭直觉画的圈，affected 是沿 import 图算出的事实，
  跨模块的隐式依赖只有后者抓得到。

  codegraph affected <本轮修改的源文件...>
    非 .spec/.test 命名的测试补跑 --filter "<project.md §六 登记的 glob>"
    返回空 → 报一行「未匹配到测试，本轮用全量」+ 自查三点：
             ① 测试代码是否被 .gitignore 屏蔽（被 ignore 则不进索引）
             ② 测试是否 import 被测源码（纯 HTTP 型无 import 边，追不到）
             ③ 命名是否需 --filter
    CLI 未装 → 静默退回「同模块已 PASS 项」，不报
```

### 6. 禁止静默截断
未测的元素/接口/断言，必须逐条列入 `SKIPPED` 并给原因。同构重复元素若做了组内抽样，必须写明「同构组 N 个，实测 M 个」—— **报告里出现「全部覆盖」而分母被悄悄缩小，是最严重的失职**。

---

## 生命周期总览

```
┌ ⓿ PREFLIGHT 前置检查 ──────────────────────────────────────────┐
│   .cc_code/ 存在 · prd.md 有模块清单与验收断言 · 应用能起来      │
└───────────────────────┬────────────────────────────────────────┘
                        ▼
┌ ❶ INVENTORY 清点（主控，只做一次，落盘即锁死分母）─────────────┐
│   路由发现 → 页面 P[]                                          │
│   ux.md §2.4 声明 ∪ 逐页 DOM snapshot → 元素 E[]  ⭐取并集,差集必报│
│   接口发现 → 接口 A[]                                          │
│   prd.md §1.5 主表 → 断言 ASSERT[]                             │
│   ux.md §2.3 U编号矩阵 → 五态判定项 USTATE[]                    │
│   按 prd.md 模块清单分组 → 模块 M[]                            │
│   codegraph 扫冗余 → DEAD/ORPHAN/DUP[]                        │
│   ↓ 落盘 .cc_code/docs/qa/<日期>-inventory.md                  │
└───────────────────────┬────────────────────────────────────────┘
                        ▼
┌ ❷ FAN-OUT 分模块并发（每模块 1 个 qa subagent，独立上下文）────┐
│   模块 M1 ──► 逐元素点击 + 五态断言 + 截图 + console 捕获        │
│   模块 M2 ──► 同上                    （并发，单消息多 Agent）  │
│   接口批  ──► 每接口 5 类断言                                   │
│   每个只回 {断言ID+中文模块-功能, verdict, 证据, 复现步骤}         │
└───────────────────────┬────────────────────────────────────────┘
                        ▼
┌ ❸ REDUCE 汇总（主控）────────────────────────────────────────┐
│   四个分母各算覆盖率：A断言 / U五态 / 元素 / 接口                │
│   SKIPPED 逐条列明原因                                          │
│   ↓ 落盘 docs/qa/<日期>-round-N.md                              │
│   ↓ gates.md 就地更新矩阵对应行  ⛔禁新开轮次章节                │
└───────────────────────┬────────────────────────────────────────┘
                        ▼
              ┌─ 全 PASS ─► ❺ 收口
              │
              └─ 有 FAIL ─┐
                          ▼
┌ ❹ FIX 轮（dev subagent，独立上下文）──────────────────────────┐
│   输入：FAIL 清单原文（不含测法细节，防针对性糊弄）              │
│   禁写：prd.md / ux.md / api.md                                │
│   修不动 → ESCALATE                                            │
│   ↓ 回归门：重跑 FAIL + 同模块已 PASS                          │
│   ↓ 收敛检查（约束 4）→ 通过则回 ❸，否则停止交人               │
└────────────────────────────────────────────────────────────────┘
                        ▼
┌ ❺ 收口 ──────────────────────────────────────────────────────┐
│   gates.md 矩阵定稿 · back_up/milestone-log.md +1行 · status.md 刷新坐标  │
└────────────────────────────────────────────────────────────────┘
```

---

## ⓿ PREFLIGHT 前置检查

| # | 检查 | 不满足时 |
| --- | --- | --- |
| 1 | `.cc_code/active/` 存在 | 提示先 `/cc-code:init`，中止 |
| 2 | `prd.md` 有「模块清单」表 | 提示先 `/cc-code:plan-mvp` 或切 PM 补，中止 |
| 3 | `prd.md` 各模块有 §1.5 验收断言（编号 A1..An） | **中止** —— 没有尺子不能验收，绝不自己编断言 |
| 3b | `ux.md` §2.3 有 `U` 编号五态矩阵（0.9.0 起） | UI 侧无尺子 —— 报主人：切 PM 补 `U` 编号，或本轮 UI/五态维度标 `SKIPPED(缺U编号规格)`，⛔ 不许自己编 |
| 3c | `gates.md` 有「§二 验收追溯矩阵」骨架 | 格式落后 —— 提示 `/cc-code:init` 走 D4 格式体检归位，或本轮按新模板重建骨架（旧内容零删除迁 `docs/qa/`） |
| 4 | 读 `project.md` 拿到：启动命令 / 测试命令 / 测试目录 / 端口 | 缺失则问用户，不猜 |
| 5 | 应用可启动 | 见下方「启动应用」 |
| 6 | 有浏览器 MCP（`chrome-devtools` 或 `Playwright`） | 无则中止 —— 逐元素点击必须真实浏览器 |

### 启动应用
```bash
# 1. 从 project.md / package.json scripts 找启动命令
# 2. 后台启动（run_in_background: true）
# 3. 轮询端口就绪再继续，不要固定 sleep
# 4. 记下 BASE_URL，传给所有 subagent
```
> 破坏性操作（删除 / 支付 / 发信 / 清库）必须跑在 **seed 数据 + 独立库/独立环境**。无法隔离的元素，标 `SKIPPED(需隔离环境)`，**不许在生产或共享库上点**。

---

## ❶ INVENTORY 清点

详细规则见 `references/inventory.md`。要点：

| 维度 | 来源 | 关键原则 |
| --- | --- | --- |
| 页面 `P[]` | 路由文件系统扫描 + 路由配置 | 含动态路由，需准备样本参数 |
| 元素 `E[]` | **`ux.md` §2.4 声明清单 ∪ 运行时 DOM snapshot** | ⭐取**并集**，差集必报：声明未实现（规格有代码没有）/ 实现未声明（代码有规格没有，即野生元素）。运行时那半保黑盒精神与穷尽性，声明那半给稳定编号 |
| 五态 `USTATE[]` | **`ux.md` §2.3 的 `U` 编号矩阵** | ⭐编号原样引用，禁止另起。`N/A` 态不计入分母但要在报告留行 |
| 接口 `A[]` | 路由目录扫描 + `api.md` 契约表 + 页面操作时的真实网络请求 | 三来源取并集，差集要报告（契约有代码没有 = 未实现；代码有契约没有 = 影子接口） |
| 断言 `ASSERT[]` | `prd.md` §1.5 **主表**，逐模块 | 编号原样引用，禁止另起编号 |
| 模块 `M[]` | `prd.md` 模块清单 | 页面/元素/接口归属到模块，孤儿项单列「未归属」组 |
| 冗余 `DEAD[]/ORPHAN[]/DUP[]` | codegraph 扫代码 | ⭐测「不该有的有没有」：死代码/孤儿文件/重复实现，详见 `inventory.md` §六 |

**同构重复元素处理**（诚实优先）：
```
唯一元素          → 必须逐个点，无例外
同构重复元素      → 归为「同构组」，测 首 / 末 / 边界样本
（如列表行内按钮）   报告必须写明：同构组 N 个，实测 M 个
```

**落盘**：`.cc_code/docs/qa/<YYYY-MM-DD>-inventory.md`
落盘后声明：**本轮分母已锁定**，并把四个分母数字（A 断言 / U 五态 / 元素 / 接口）告知用户。

---

## ❷ FAN-OUT 分模块并发

每模块一个 `qa` subagent。**在单条消息里发出多个 Agent 调用**以并发执行。

### 派给 qa subagent 的 prompt 骨架
```
你是本模块的验收执行者。只做测试取证，不改业务代码，不改需求文档。

【真相源】（只读）
  .cc_code/active/prd.md 的模块 M{n}（规则 + §1.5 验收断言）
  .cc_code/active/ux.md 的对应页面（§2.3 U 编号五态矩阵 + §2.4 可交互元素清单）
  .cc_code/active/api.md 的对应接口段
  .cc_code/active/project.md（仅取技术栈/测试框架/契约风格）

【本轮分母】（已锁定，不可增删）
  页面：{P 列表}
  可交互元素：{E 列表，含 testid 与同构组标注}
  接口：{A 列表}
  断言：{ASSERT 列表}

【BASE_URL】{url}

【必做】
  1. 逐个点击分母内每一个元素（同构组按 首/末/边界 取样并标注）
  2. 逐条判定分母内每一个 U 编号（正常 i / 加载 l / 完成 s / 错误 e / 空 m）
     —— 结果必须挂在 U 编号上，禁止只报「某页部分通过」
  3. 每接口 5 类断言：正常 / 缺参 / 越权 / 边界 / 错误码
  4. 全程捕获 console 错误与失败网络请求，任一非预期报错即 FAIL
  5. 破坏性操作若无法隔离，标 SKIPPED(需隔离环境)，不许硬点

【禁止】
  ✗ 抽样跳过唯一元素      ✗ 修改 prd.md / ux.md / api.md
  ✗ 改业务代码            ✗ 把 FAIL 说成「大概没问题」
  ✗ 自己编造分母外的断言

【只回结构化结果】
  | 断言ID/元素ID | verdict | 证据(测试名或截图路径) | 复现步骤 | 涉及文件:行 |
  外加：SKIPPED 清单 + 原因
```

> **不要告诉 qa subagent「稍后会有 dev 来修」** —— 保持它对下游无知，才不会手下留情。

---

## ❸ REDUCE 汇总

模板见 `references/report-template.md`。主控要做：

1. 合并所有 subagent 结果，按断言 ID（`A` 段）与 `U` 编号（`U` 段）分别排序
2. 算四个覆盖率（`A` 断言 / `U` 五态 / 元素 / 接口），分母用锁定值
3. 列 SKIPPED（每条带原因）
4. 分级 FAIL：Critical（断言直接不达标）/ Minor（体验缺陷但断言未违反）
5. **落盘** `docs/qa/<日期>-round-N.md`（完整矩阵 + 全部证据，温数据）
6. **gates.md 就地更新**（⛔ 禁新开「第 N 轮」章节）：
   - §一 本轮结论：改写轮次 / 日期 / Verdict / 通过率
   - §二 追溯矩阵：**逐行更新** `A` 段与 `U` 段对应行的 Verdict / 轮次 / 测试位置 / 实测结果
   - §三~§五：**只留未关闭项**，本轮修好的从清单移出（历史在 `docs/qa/`）
   - §六 覆盖率：改写四个分母与覆盖率
   > gates.md 行数 = 分母（`A` 条数 + `U` 条数），**不随轮次增长**；⛔ 不加附录索引（轮次报告在 `docs/qa/`，历史时间线在 `back_up/change-log.md`）

---

## ❹ FIX 轮

### 派给 dev subagent 的 prompt 骨架
```
你是修复执行者。只修代码，不改需求。

【必读】
  .cc_code/active/prd.md（规则与断言 —— 只读！）
  .cc_code/active/ux.md / api.md / project.md / data.md（只读）

【待修 FAIL 清单】
  {原样粘贴 Critical Failures，含 Required / Actual / Repro / 涉及文件}

【⛔ 绝对禁止】
  ✗ 修改 prd.md / ux.md / api.md 的任何一行
  ✗ 修改或删除测试用例让它变绿
  ✗ 顺手重构无关代码（扩大爆炸半径 = 引入新 FAIL）
  修不动 → 输出 ESCALATE + 说明卡在哪、需要什么决策

【必做】
  1. 逐条修，每条对应到 FAIL 编号
  2. 新踩的坑写进 commit message（git 天然留痕）
  3. 自检：lint → 类型检查 → 单测（命令以 project.md 为准）
  4. 回报：修了哪些 / ESCALATE 哪些 / 改动文件清单
```

### 回归门 + 收敛检查
```
修完 ──► ⭐先算范围: codegraph affected <本轮 dev 改动的源文件...>
         └─ 空/未装 → 退回「同模块已 PASS 项」并在报告标注来源
              │
              ▼
         派 qa subagent 重跑：本轮 FAIL 项 + 上面算出的影响面
              │
              ├─ 新增 FAIL？ ──► 停止。报告震荡点 + 建议回滚本轮，交人
              ├─ FAIL 数未递减？ ──► 停止。报告「未收敛」，交人
              ├─ 轮次 > 3？ ──► 停止。标记升级：回 plan-mvp 重规划 或 交人
              └─ 递减且 ≤3 轮 ──► 回 ❸ 汇总，继续下一轮
```

---

## ❺ 收口

| 步骤 | 动作 |
| --- | --- |
| 1 | `gates.md` **就地更新**：§一 Verdict + §二 矩阵全行 + §六 四分母覆盖率 + §三~五 只留未关闭项。⛔ 禁新开轮次章节、禁加附录索引 |
| 2 | `back_up/milestone-log.md` 追加一行：`<日期> ｜ <模块> ｜ agent-whole-qa 全量验收 第N轮 PASS，覆盖率 x/y ｜ <F号/->`；`status.md` 只刷新坐标/卡点/下一步，⛔ 里程碑不落 status.md |
| 3 | 向用户报告：四个覆盖率（A / U / 元素 / 接口）、SKIPPED 清单、ESCALATE 清单、轮次消耗 |
| 4 | ⛔ **不报告归档细节**（Hook 静默） |

## 主控行为准则

- **只报结果与决策点**，不复述 subagent 的过程日志。
- 进度以 `status.md` 为准，规则以 `prd.md` 为准，实测以 `gates.md` 为准。
- 用 `TaskCreate` / `TaskUpdate` 追踪模块级进度，让用户能看到「M3/M7 完成」。
- 任何时候发现自己在写测试代码或改业务代码 —— **停下，那是 subagent 的活**。