# Forge QA

> QA 纯验收（只测不修）：Mode A 完整验收（test-spec → 10 维度断言引擎 → 报告 + User Gate）；Mode B 供 forge-bugfix P6 调用做单 bug 回归并回填 BF 报告。 铁律：每个测试必须有 pass/fail 和深层断言；console.error 零容忍；不猜端口，只用传入的 app_url。 触发方式：Mode A 用户说"测试"、"QA"、"forge-qa"或 forge-dev 调度；Mode B 由 forge-bugfix P6 调用（传 review_doc）。

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

---


> **文档落地路径**：遵循 forge-doc-policy 规范。完整白名单 + frontmatter schema 见
> `~/.claude/skills/forge-doc-policy/doc-paths.md`。
> **当前文档加载顺序**：完整 QA 先读项目 `CLAUDE.md`、`docs/README.md`、`docs/INDEX.md`、
> `docs/QA.md` 当前验收手册和相关 `.features/{feature-id}/feature-spec.md`；单 bug 回归读取活跃 BF 报告。
> 详细规则见 `~/.claude/skills/_shared/current-doc-loading.md`。

# /forge-qa：QA 验收与测试报告

**纯验收模式：测试 + 报告，不修代码。** 发现的问题生成结构化 bug 记录；单 bug 回归时回填 Bug 修复验收报告。

## 调用模式

forge-qa 支持两种调用模式，**入口判断在前置脚本阶段**完成（见"前置脚本"节）。

| 模式 | 触发条件 | 输入 | 输出 | 下游 |
|---|---|---|---|---|
| **Mode A：完整 QA** | 用户直接触发，或 forge-dev 调度 | PRD / DESIGN / git diff | QA.md 报告 + 结构化 bug 候选 + User Gate | forge-ship / forge-bugfix / forge-eng |
| **Mode B：单 bug 修复验收报告** | forge-bugfix 的 P6 调用；入口带参数 `review_doc=docs/bugfix/reviews/BF-XX.md` | 单 bug Bug 修复验收报告 | 报告内 QA 证据区、环境身份校验、逐步截图回填 | forge-bugfix 的 P6.5 / 批次最终验收 / P5（回修）|

**模式判断优先级**（AI 从 args 或触发消息中判断，从高到低）：

1. **显式参数** — Skill 调用时 args 含 `mode=B` 和 `review_doc=<路径>` → 直接 Mode B
2. **调用来源** — 触发消息里出现 "forge-bugfix"、"review-checklist"、`BF-\d+-\d+.md` 文件路径 → Mode B（从消息里提取 review_doc 路径，其余必需参数从报告或上下文推断）
3. **默认** — Mode A

**Mode B 入口校验**：`review_doc` 不存在 → 直接终止并报错；`bug_id` 缺失时取报告文件名。有 `worktree` 但没传 `app_url` 时，若验收项涉及浏览器/curl/截图，要求调用方先运行项目的 `dev:status` / `dev-stack status`，把 Frontend URL 作为 `app_url` 传入后再调用。

Mode B 详见"## Mode B：单 bug 修复验收报告模式"节（本文档末尾）。

Mode A 详见"## 三层架构"往下的完整流程。

**Mode B 的 args 契约（forge-bugfix 必须传，forge-qa 必须接收）**：

| 参数 | 必填 | 含义 |
|---|---|---|
| `mode=B` | ✅ | 强制信号，优先级最高 |
| `review_doc=<路径>` | ✅ | Bug 修复验收报告（存在性校验失败直接 exit） |
| `bug_id=BF-{MMDD}-{N}` | ✅ | 用于命名截图 / 日志 |
| `worktree=<路径>` | ✅ | 在该 worktree 内运行测试 |
| `commit=<hash>` | ✅ | 用于定位修复范围 |
| `app_url=<URL>` | 条件 | 仅当 bug 类型涉及应用运行时；必须来自调用方的 `dev:status` / `dev-stack status` 输出 |

## 三层架构

```
┌─────────────────────────────────────────────────┐
│  Layer 1: 测试规格生成（文档 → test-spec.json）     │
│  输入: PRD / DESIGN.md / git diff / 会话上下文       │
├─────────────────────────────────────────────────┤
│  Layer 2: 10 维度 Playwright 断言引擎               │
│  控制台|数据驱动|网络|视觉|交互|响应式|可访问|SSE|URL|懒加载│
├─────────────────────────────────────────────────┤
│  Layer 3: 智能分析（失败归因 + 根因定位）            │
│  console → 源码 → git diff 交叉引用                │
└─────────────────────────────────────────────────┘
```

## 铁律

1. **只测不修** — forge-qa 不修改任何业务代码。发现 bug 记录到报告，由 forge-eng 修复。
2. **不生成 test-spec 就不执行测试** — 先从文档提取验收项，结构化后再执行。
3. **每个测试必须有 pass/fail** — 不允许 `.catch(() => {})` 吞错误，不允许"只截图不断言"。
4. **断言必须验证功能正确性，不能只验证元素存在** — `visible` 和 `count_gte` 是前置条件，不是验收断言。每个测试用例必须至少包含一个验证**数据值/文本内容/状态变化**的深层断言（`contains_text`、`has_attribute`、`css_value`、`matches_regex`、自定义 `evaluate`）。详见下方"断言深度规则"。
5. **证据先于结论** — 每个测试结果必须有截图、输出、或日志作为证据。
6. **控制台零容忍** — 任何 `pageerror` 或 `console.error` 自动 FAIL。
7. **不得猜本地端口** — 有 `app_url` 就只测该 URL；没有 `app_url` 时，优先读取 `dev:status` / `dev-stack status`，不得自行发明 `localhost:3000`、`5173`、`8080` 等地址。

**环境适配**：在 Codex 中做本地前端页面/交互 QA 时，若 Browser Use 插件可用，优先使用 `browser-use:browser`（Computer Use 只作明确兜底）；Claude Code 环境用 Playwright（qa-runner.mjs）。

## 定位说明

| forge-eng 负责 | forge-qa 负责 |
|----------------|--------------|
| 单元测试（TDD 红绿重构） | **端到端用户流程测试** |
| 原子 commit 验证（exit code） | **跨模块集成测试** |
| 任务级验证 | **10 维度断言（视觉+响应式+可访问性+网络+数据驱动）** |
| — | **验收标准逐项核对** |
| — | **User Gate（用户验收关卡）** |

## 完整流程

```
第0步 上下文探测
  ├── 0.1 Worktree 检测
  ├── 0.2 文档链定位（PRD/DESIGN/ENGINEERING/FEEDBACK）
  ├── 0.3 变更范围分析（git diff）
  ├── 0.4 选择器审计（铁律：不盲猜选择器）
  └── 0.5 测试级别确认
  │
第1步 建立健康基准
  │
  ├── 已有 QA.md → 第2步 理解现状
  └── 无 QA.md   → 第2步(替代) 从零创建
  │
第2.5步 生成 test-spec（铁律：不生成就不执行）
  │
第3步 测试计划确认（用户审查 test-spec 摘要）
  │
第4步 更新 QA 文档
  │
第5步 10 维度测试执行
  ├── Phase 1: 控制台[console] + 网络[network]
  ├── Phase 2: 交互[functional] + 数据驱动[data-driven] + SSE[streaming] + URL状态[url-state] + 懒加载[async-content]
  ├── Phase 3: 视觉[visual] + 响应式[responsive]
  └── Phase 4: 可访问性[accessibility]
  │
第6步 智能分析 + Bug 报告
  │
第7步 User Gate（用户验收 — 不可跳过）
  │
  ├── accept → forge-ship
  └── reject → FEEDBACK.md → forge-eng → forge-qa (回归) → User Gate
```

全程中文。关键测试策略需用户确认后再执行。

## 报告产出后的出口

```
QA 验收完成。下一步：

[全部通过 + 用户验收通过]
→ /forge-ship 或 /forge-review

[有 FAIL 或用户 reject]
→ 生成修复清单 + FEEDBACK.md → /forge-eng 修复 → /forge-qa 回归
```

---

## 前置脚本

```bash
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
echo "当前分支: $_BRANCH"

# === Worktree 检测 ===
_IN_WORKTREE="no"
_WORKTREE_ROOT=""
git worktree list 2>/dev/null | while read line; do
  echo "  worktree: $line"
done
[ "$(git rev-parse --git-common-dir 2>/dev/null)" != "$(git rev-parse --git-dir 2>/dev/null)" ] && _IN_WORKTREE="yes" && _WORKTREE_ROOT="$_ROOT"
echo "在 Worktree 中: $_IN_WORKTREE"

# === 测试引擎: Playwright ===
PW=""
command -v npx >/dev/null 2>&1 && npx playwright --version >/dev/null 2>&1 && PW="npx"
[ -z "$PW" ] && python3 -c "from playwright.sync_api import sync_playwright" 2>/dev/null && PW="python"
[ -n "$PW" ] && echo "Playwright: 可用 ($PW)" || echo "Playwright: 不可用"

# === qa-runner.mjs 检测 ===
QA_RUNNER=""
[ -f "$HOME/.claude/skills/forge-qa/scripts/qa-runner.mjs" ] && QA_RUNNER="$HOME/.claude/skills/forge-qa/scripts/qa-runner.mjs"
[ -n "$QA_RUNNER" ] && echo "qa-runner: $QA_RUNNER" || echo "qa-runner: 不可用"

# === 框架检测 ===
[ -f "$_ROOT/package.json" ] && grep -q '"react"' "$_ROOT/package.json" 2>/dev/null && echo "框架: React"
[ -f "$_ROOT/package.json" ] && grep -q '"vue"' "$_ROOT/package.json" 2>/dev/null && echo "框架: Vue"
[ -f "$_ROOT/package.json" ] && grep -q '"next"' "$_ROOT/package.json" 2>/dev/null && echo "框架: Next.js"
[ -f "$_ROOT/requirements.txt" ] || [ -f "$_ROOT/pyproject.toml" ] && echo "运行时: Python"
[ -f "$_ROOT/package.json" ] && echo "运行时: Node.js"

# === 本地服务探测 ===
echo "本地服务:"
if [ -n "$APP_URL" ]; then
  echo "  APP_URL=$APP_URL（由调用方传入）"
elif [ -f "$_ROOT/package.json" ] && (cd "$_ROOT" && npm run 2>/dev/null | grep -q "dev:status"); then
  (cd "$_ROOT" && npm run dev:status)
  echo "  未传 APP_URL：如需浏览器验收，请使用 dev:status 输出中的 Frontend URL 重新调用 forge-qa。"
elif [ -x "$_ROOT/scripts/dev-stack.sh" ]; then
  (cd "$_ROOT" && bash scripts/dev-stack.sh status)
  echo "  未传 APP_URL：如需浏览器验收，请使用 dev-stack status 输出中的 Frontend URL 重新调用 forge-qa。"
else
  for port in 3000 3456 4000 5173 8080 8081; do
    curl -s -o /dev/null -w "%{http_code}" "http://localhost:$port" 2>/dev/null | grep -qE "200|301|302|304" && echo "  http://localhost:$port ✓（旧项目兜底探测）"
  done
fi

# === 报告目录 ===
REPORT_DIR="$_ROOT/.gstack/qa-reports"
mkdir -p "$REPORT_DIR/screenshots" 2>/dev/null
echo "报告目录: $REPORT_DIR"
```

---

> 提问格式与批量策略见 `~/.claude/skills/_shared/interaction-protocol.md`。

---

## 执行手册（按需加载，执行时必读）

本文件只保留契约、铁律和流程总览。**进入执行阶段前，必须先读对应手册**：

| 场景 | 必读文件 | 内容 |
|---|---|---|
| Mode A 完整 QA（第0步~第8步） | [references/mode-a-execution.md](references/mode-a-execution.md) | 上下文探测、健康基准、test-spec 生成、验收计划、10 维度执行、智能分析、User Gate、健康评分全细则 |
| Mode B 单 bug 回归（bugfix P6 调用） | [references/mode-b-regression.md](references/mode-b-regression.md) | 报告解析、环境身份校验、逐项测试与回填、判定与出口 |
| 写测试脚本时 | [references/test-dimensions.md](references/test-dimensions.md) | 10 维度逐个的代码模板与断言写法 |
| 产出报告时 | [references/qa-template.md](references/qa-template.md) | QA.md 结构、验收计划、健康评分表格式 |

**规矩**：不允许凭记忆执行细则——骨架没写的操作细节，一律以对应手册为准；手册与骨架冲突时，以骨架的铁律和契约为准。

---

## Feature 状态管理

> 状态标记与通用操作规则见 `~/.claude/skills/_shared/feature-status-protocol.md`。

qa 特有动作：启动前确认 eng 行为 `[✅ 已完成]`；执行中更新 QA Items 表（每个测试项独立状态）；完成时 note 填 `{passed}/{total} PASS, {score}/100`（未通过填 `{failed} FAIL, 需修复后重测`）。

---

## 重要规则

1. **像真实用户一样测试** — 点所有可点的，填所有表单，测试所有状态。
2. **截图留证** — 每个测试步骤至少一张截图。用 `snapElement()` 紧凑裁剪，不用 fullPage。截图后用 Read 工具展示给用户。
3. **不要只测 Happy Path** — 边界、空状态、超长输入、网络错误都要测。
4. **控制台是第一现场** — 每次交互后检查控制台。视觉上没问题不代表没有 JS 错误。
5. **数据驱动是核心** — 不只测一条数据。用 `pickStratified()` 采样多条。
6. **前后端联动是重点** — 验证 API 调用是否正确、响应是否合理。
7. **深度优于广度** — 5-10 个证据充分的 Bug > 20 个模糊描述。
8. **自我调节** — 拿不准就停下来问。
9. **绝不拒绝使用浏览器** — 后端变更也会影响应用行为，始终打开浏览器测试。
10. **User Gate 不可跳过** — 自动化测不到设计意图偏差，必须等用户验收。