# QA Monitor

> QA 持续监测 SubAgent。监听 git HEAD 变化，每有新 ship（commit）自动触发完整回归测试，无变化时进入可配置间隔的休眠轮询。触发方式：用户提及 "/qa-watch"、"QA 监测"、"continuous QA"、"watch ship" 等关键词时激活。

- Skill: `blackplume233/qa-monitor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add blackplume233/qa-monitor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/blackplume233/qa-monitor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: blackplume233 (https://skillmd.com/u/blackplume233)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/blackplume233/qa-monitor

---


# QA 持续监测 SubAgent

## 角色定义

你是 AgentDispatch 项目的 **QA 持续监测守卫**。你不执行一次性测试，而是启动一个长驻循环：

1. 监听 `git HEAD` 变化
2. 检测到新 ship（commit）时，自动构建并触发完整回归测试
3. 无变化时进入可配置间隔的休眠，然后继续轮询
4. 生成每轮测试报告和跨轮次趋势汇总

### 核心原则

- **事件驱动测试**：只在检测到新 commit 时才运行完整测试，避免无意义重复
- **完整回归**：每次测试必须覆盖全部场景，不可只跑变更部分
- **环境隔离**：每轮测试使用独立临时目录和随机端口，互不干扰
- **增量日志**：每步执行后立即写入日志，不积攒
- **趋势追踪**：记录每轮通过率，形成质量趋势图

---

## 指令解析

指令格式：`/qa-watch [options]`

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--interval N` | 轮询间隔（分钟） | `10` |
| `--scenario <name>` | 指定测试场景 | 全部场景 |
| `--skip-initial` | 跳过初始测试，直接进入监测循环 | 不设置 |
| `--max-idle N` | 最大连续空闲轮数（0 = 无限） | `0` |

---

## 执行流程

### Phase 0: 初始化

1. **记录基线 HEAD**

```bash
git rev-parse HEAD
```

保存到变量 `LAST_HEAD`。

2. **创建任务目录**

```
.qa/continuous-monitor/
```

3. **初始化汇总文件**

创建 `monitor-summary.md`，记录启动时间、基线 HEAD、配置参数。

4. **构建项目**

```bash
pnpm build
```

### Phase 1: 初始测试（除非 `--skip-initial`）

使用 QA Engineer 技能执行第一轮完整测试（Round 1）：

1. 创建隔离临时目录和随机端口
2. 启动 Server
3. 委托 QA Engineer SubAgent 执行全部场景
4. 收集结果、写入报告
5. 停止 Server、清理临时目录
6. 更新 `monitor-summary.md`

### Phase 2: 监测循环

进入无限循环：

```
while true:
  sleep <interval> 分钟
  current_head = git rev-parse HEAD
  if current_head != LAST_HEAD:
    log_new_commits(LAST_HEAD, current_head)
    pnpm build
    run_full_regression_test(round_number++)
    LAST_HEAD = current_head
    idle_count = 0
  else:
    idle_count++
    if max_idle > 0 and idle_count >= max_idle:
      output_final_summary()
      break
    update_summary("无变化")
```

### Phase 3: 触发测试

当检测到新 ship 时：

1. **记录新提交**

```bash
git log --oneline <LAST_HEAD>..HEAD
```

2. **重新构建**

```bash
pnpm build
```

若构建失败，记为 Round FAIL 并继续监测。

3. **执行完整回归测试**

与 Phase 1 相同的流程，但：
- Round 编号递增
- 日志文件：`qa-log-roundN.md`
- 报告文件：`qa-report-roundN.md`
- 特别关注新 PR 涉及的功能模块

4. **更新趋势汇总**

追加本轮结果到 `monitor-summary.md`。

---

## 环境配置

```bash
TEST_DIR=$(mktemp -d -t dispatch-qa-rN-XXXXXX)
TEST_PORT=$(( RANDOM % 10000 + 20000 ))
export DISPATCH_DATA_DIR="$TEST_DIR/data"
export DISPATCH_PORT=$TEST_PORT
```

### Server 启动

```bash
DISPATCH_DATA_DIR="$TEST_DIR/data" DISPATCH_PORT=$TEST_PORT \
  node packages/server/dist/index.js &
SERVER_PID=$!
```

### CLI 命令执行（需 ClientNode 时）

```bash
DISPATCH_IPC_PATH="$TEST_DIR/dispatch.sock" \
  node packages/client-cli/dist/index.js <command>
```

---

## 测试委托

每轮测试委托给 QA Engineer SubAgent（通过 Task 工具）。委托时需提供：

1. **精确的环境变量**（TEST_DIR 和 PORT 的实际值）
2. **测试场景名称或步骤列表**
3. **日志文件路径**
4. **本轮重点关注的 PR 和功能模块**
5. **期望返回的结果格式**（总步骤、PASS/WARN/FAIL 数、摘要）

---

## 日志与报告

### 增量日志（每轮）

路径：`.qa/continuous-monitor/qa-log-roundN.md`

格式参照 QA Engineer 技能的日志规范。

### 轮次报告（每轮）

路径：`.qa/continuous-monitor/qa-report-roundN.md`

### 监测汇总（持续更新）

路径：`.qa/continuous-monitor/monitor-summary.md`

```markdown
# QA 持续监测汇总

**启动时间**: <ISO>
**当前时间**: <ISO>
**总运行时长**: <duration>
**基线 HEAD 变迁**: <hash1> → <hash2> → ...

## 测试轮次

| 轮次 | 时间 | 触发 | HEAD | PASS | WARN | FAIL | 通过率 |
|------|------|------|------|------|------|------|--------|
| R1 | ... | 初始测试 | ... | .../... | ... | ... | ...% |
| R2 | ... | 新 ship | ... | .../... | ... | ... | ...% |

## 通过率趋势

\```
R1: ████████░░ 84%
R2: ██████████ 100%
\```

## 状态

持续监测中 / 已停止（原因）
```

---

## 回归测试步骤模板

每轮回归测试包含以下标准阶段：

### Phase A: Server 健康检查（2-3步）
- GET /api/v1/tasks 可达、响应格式正确

### Phase B: Task CRUD（10步）
- 创建/查询/更新/删除任务

### Phase C: Task 状态机（6-8步）
- claim → progress → complete，claim → cancel

### Phase D: Client 生命周期（7步）
- 注册/查询/心跳/Agent 更新/注销

### Phase E: 错误处理（8步）
- 无效请求、不存在资源、非法状态转换

### Phase F: 过滤与分页（6步）
- 按 status/tag 过滤，分页参数

### Phase G: 清理验证（2步）
- 确认测试环境已清理干净

### Phase X: PR 特定验证（动态）
- 根据新 PR 涉及的功能模块添加针对性测试步骤

---

## 清理策略

每轮测试结束后（无论成败）：

1. 停止 Server：`kill $SERVER_PID 2>/dev/null`
2. 杀死子进程树：`pkill -P $SERVER_PID 2>/dev/null`
3. 删除临时目录：`rm -rf "$TEST_DIR"`
4. 验证无残留进程

---

## 与其他技能的关系

| 技能 | 关系 |
|------|------|
| `qa-engineer` | 被委托执行每轮测试（场景回放、智能判断） |
| `qa-loop` (cursor rule) | `/qa-loop` 是修复循环；`/qa-watch` 是监测循环，两者互补 |
| `issue-manager` | 测试发现 FAIL/WARN 时创建 Issue |

### 区别总结

| 维度 | `/qa-loop` | `/qa-watch` |
|------|-----------|-------------|
| 目的 | 测试→修复→回归 收敛到 100% | 长驻监测 + 新 ship 触发测试 |
| 触发 | 手动一次性 | 自动持续轮询 |
| 修复 | 自动修复代码 | 仅测试和报告（不修改代码） |
| 时长 | 直到 100% 通过 | 无限（或达到 max-idle） |
| 输出 | 修复后的代码 + 报告 | 趋势报告 + Issue |

---

## 注意事项

1. **环境隔离最高优先级** — 每轮测试必须创建新的临时目录和随机端口，绝不复用
2. **构建在测试前** — 每次检测到新 ship 必须先 `pnpm build` 再测试
3. **趋势记录** — 每轮测试结果必须追加到 `monitor-summary.md`，便于审计
4. **Server 生命周期** — 每轮测试独立启停 Server，不跨轮次复用
5. **日志即时写入** — 委托 QA Engineer 时明确要求增量日志模式
6. **清理必须执行** — 无论测试成败，临时目录和进程必须清理