Skillquality 0.46

forge-qa

QA 验收与测试报告。纯验收模式：测试+报告，不修代码。两种调用模式： Mode A（完整 QA）：test-spec 生成 → 10 维度 Playwright 断言引擎 → 智能分析。 Mode B（单 bug 修复回归）：配合 forge-bugfix 的 P6 调用，读取 docs/bugfix/reviews/BF-XX.md，针对 Bug 修复验收报告里的人工验收指南跑自动化测试，把逐步截图、深度断言、前后端环境身份校验回填到报告。QA 全过 → 单 bug 模式进 P6.5，批量模式进入 qa-pass

Price

free

Protocol

skill

Verified

Endpoint

https://skills.sh/yike-gunshi/forge-skills/forge-qa

What it does

/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（回修）

模式判断逻辑（前置脚本执行）：

模式判断优先级（从高到低）：

显式参数 — Skill 调用时 args 含 mode=B 和 review_doc=<路径> → 直接 Mode B
调用来源 — 触发消息里出现 "forge-bugfix"、"review-checklist"、BF-\d+-\d+.md 文件路径 → Mode B
默认 — Mode A

# AI 从 args 或触发消息中解析
# 优先级 1: 显式 args
if echo "$ARGS" | grep -q "mode=B"; then
  MODE="B"
  REVIEW_DOC=$(echo "$ARGS" | grep -oE "review_doc=[^ ]+" | cut -d= -f2)
  BUG_ID=$(echo "$ARGS" | grep -oE "bug_id=[^ ]+" | cut -d= -f2)
  WORKTREE=$(echo "$ARGS" | grep -oE "worktree=[^ ]+" | cut -d= -f2)
  COMMIT=$(echo "$ARGS" | grep -oE "commit=[^ ]+" | cut -d= -f2)
  APP_URL=$(echo "$ARGS" | grep -oE "app_url=[^ ]+" | cut -d= -f2)
  echo "QA Mode: B（单 bug 修复验收报告）"
  echo "  review_doc: $REVIEW_DOC"
  echo "  bug_id: $BUG_ID"
  echo "  worktree: $WORKTREE"
  echo "  commit: $COMMIT"
  [ -n "$APP_URL" ] && echo "  app_url: $APP_URL"
# 优先级 2: 启发式识别
elif echo "$USER_MESSAGE" | grep -qE "forge-bugfix|review-checklist|docs/bugfix/reviews/BF-[0-9]+-[0-9]+\.md"; then
  MODE="B"
  # 从消息里捞 review_doc 路径
  REVIEW_DOC=$(echo "$USER_MESSAGE" | grep -oE "docs/bugfix/reviews/BF-[0-9]+-[0-9]+\.md" | head -1)
  echo "QA Mode: B（启发式判定）"
  echo "  review_doc: $REVIEW_DOC"
  # AI 必须验证：报告存在 + 其他必需参数从报告或上下文推断
else
  MODE="A"
  echo "QA Mode: A（完整 QA）"
fi

# Mode B 必需参数校验
if [ "$MODE" = "B" ]; then
  [ -f "$REVIEW_DOC" ] || { echo "❌ Bug 修复验收报告不存在: $REVIEW_DOC"; exit 1; }
  [ -n "$BUG_ID" ] || BUG_ID=$(basename "$REVIEW_DOC" .md)
  if [ -n "$WORKTREE" ] && [ -d "$WORKTREE" ] && [ -z "$APP_URL" ]; then
    if [ -f "$WORKTREE/package.json" ] && (cd "$WORKTREE" && npm run 2>/dev/null | grep -q "dev:status"); then
      echo "⚠️ 当前项目提供 dev:status，但 Mode B 未传 app_url。若验收项涉及浏览器、curl 或截图，调用方必须先运行 npm run dev:status，并把 Frontend URL 作为 app_url 传入。"
    elif [ -x "$WORKTREE/scripts/dev-stack.sh" ]; then
      echo "⚠️ 当前项目提供 scripts/dev-stack.sh，但 Mode B 未传 app_url。若验收项涉及浏览器、curl 或截图，调用方必须先运行 dev-stack status，并把 Frontend URL 作为 app_url 传入。"
    fi
  fi
fi

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 交叉引用                │
└─────────────────────────────────────────────────┘

铁律

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

定位说明

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

前置脚本

_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"

# === 测试引擎 1: gstack/browse ===
B=""
[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/browse/dist/browse" ] && B="$_ROOT/.claude/skills/gstack/browse/dist/browse"
[ -z "$B" ] && [ -x "$HOME/.claude/skills/gstack/browse/dist/browse" ] && B="$HOME/.claude/skills/gstack/browse/dist/browse"
[ -n "$B" ] && echo "gstack/browse: $B" || echo "gstack/browse: 不可用"

# === 测试引擎 2: 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"

AskUserQuestion 格式规范

每次提问结构：

重新聚焦：当前项目、分支、正在测试的功能
通俗解释：高中生能懂的语言描述问题
给出建议：推荐选项 + 完整度评分
列出选项：A) B) C) + 工作量估算

第0步：上下文探测与环境准备

0.1 Worktree 检测（铁律：在正确的分支上测试）

按优先级检测工作环境：

forge-dev 调度传入：如果 Agent prompt 中包含 worktree_path，直接 cd 进入
当前目录检测：前置脚本已检测 _IN_WORKTREE，如果是则直接使用
扫描已有 worktree：git worktree list 查找最近的 eng/* 分支
当前分支为 feature 分支：如果当前在 eng/* 或非 main 分支，可以直接测试
询问用户：如果当前在 main 且无 worktree，通过 AskUserQuestion 询问

确认后输出：

🔧 测试环境：
  Worktree: /path/to/.worktrees/feature-slug (或 "当前目录")
  Branch:   eng/feature-slug-2026-03-28
  Base:     main

0.2 文档链定位

按搜索模式定位所有参考文档，forge-dev 传入的路径优先级最高：

# PRD
for f in docs/PRD.md PRD.md docs/*PRD*; do [ -f "$f" ] && echo "PRD: $f" && break; done

# DESIGN
for f in DESIGN.md docs/DESIGN.md docs/DESIGN-BLUEPRINT.md; do [ -f "$f" ] && echo "DESIGN: $f" && break; done

# ENGINEERING
for f in docs/ENGINEERING.md ENGINEERING.md; do [ -f "$f" ] && echo "ENGINEERING: $f" && break; done

# FEEDBACK（历史用户反馈，回归测试用）
for f in FEEDBACK.md docs/FEEDBACK.md; do [ -f "$f" ] && echo "FEEDBACK: $f" && break; done

# QA
for f in docs/QA.md QA.md; do [ -f "$f" ] && echo "QA: $f" && break; done

# .features/status
ls .features/*/status.md 2>/dev/null | head -5

文档版本校验：读取文档后提取版本号，与 .features/status.md 中记录的 PRD 版本对比。不一致则警告。

降级模式：如果找不到 PRD/DESIGN → 降级为"无文档模式"（只做 console + 响应式 + 可访问性基础测试）。

0.3 变更范围分析

# 基准分支
BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || echo "main")

# 变更文件列表
git diff $BASE...HEAD --name-only 2>/dev/null
git diff $BASE...HEAD --stat 2>/dev/null

# 变更摘要
git log $BASE..HEAD --oneline 2>/dev/null

变更文件 → 推断影响范围 → 决定测试重点（Diff-aware 模式）。

0.4 选择器审计（铁律：不盲猜选择器）

在生成 test-spec 前，必须扫描代码确认可用选择器。 不同项目的 DOM 结构完全不同，不能假设任何 data-testid 或 ARIA 属性存在。

# 扫描项目中可用的选择器锚点
echo "=== data-testid ==="
grep -r 'data-testid' src/ --include='*.tsx' --include='*.jsx' --include='*.vue' --include='*.html' -l 2>/dev/null | head -10

echo "=== data-* 属性 ==="
grep -roh 'data-[a-z_-]*=' src/ --include='*.tsx' --include='*.jsx' --include='*.vue' -h 2>/dev/null | sort -u | head -20

echo "=== ARIA 属性 ==="
grep -roh 'role="[^"]*"\|aria-[a-z]*=' src/ --include='*.tsx' --include='*.jsx' --include='*.vue' -h 2>/dev/null | sort -u | head -20

echo "=== 语义化 HTML ==="
grep -roh '<\(nav\|main\|aside\|header\|footer\|section\|article\|dialog\)[> ]' src/ --include='*.tsx' --include='*.jsx' --include='*.vue' -h 2>/dev/null | sort | uniq -c | sort -rn | head -10

根据扫描结果决定选择器策略：

项目状态	选择器策略	test-spec 中使用
有丰富 `data-testid`	直接使用 testid	`[data-testid='feed-section']`
有 `data-*` 属性但非 testid	使用已有 data 属性	`[data-platform='twitter']`, `[data-item-id]`
有 ARIA 属性	使用 role + aria	`[role='tab']`, `[aria-selected='true']`
有语义化 HTML	使用语义标签	`main`, `nav`, `dialog`
以上都没有	文本 + CSS 组合	`button:has-text("搜索")`, `.card-container > .card:nth-child(1)`

选择器优先级（从稳定到脆弱）：

1. getByRole('tab', { name: '推荐' })    ← 最稳定，语义化
2. [data-testid='feed-section']           ← 专为测试设计
3. [data-platform='twitter']              ← 业务语义属性
4. [role='dialog']                        ← ARIA 属性
5. button:has-text("搜索")                ← 可见文本
6. main > section:first-child             ← 结构选择器
7. .bg-card.rounded-lg                    ← CSS class（最脆弱）

如果项目零 data-testid：

不要在 test-spec 中编造 data-testid——这会导致所有测试因选择器找不到而假性 FAIL
使用上述优先级中实际存在的选择器
在 QA 报告的"改进建议"中标注：建议 forge-eng 在关键交互元素上补充 data-testid

输出选择器映射表（供 test-spec 生成时引用）：

🔍 选择器审计结果：
  data-testid: 0 个（项目未使用 testid）
  data-* 属性: data-platform, data-item-id, data-section
  ARIA: role="dialog" (1处), role="button" (3处)
  语义标签: main, nav, section, header

  推荐策略：data-* 属性 + 文本选择器 + 语义标签组合

  关键元素映射：
  ├── 信息卡片: [data-platform] 或 .cursor-pointer:has(h3)
  ├── 详情面板: [role="dialog"] 或 [class*="detail"]
  ├── Tab 导航: button:has-text("推荐") 等
  └── 搜索框: input[type="search"] 或 input[placeholder*="搜索"]

0.5 测试级别与模式

测试级别（如用户未指定，通过 AskUserQuestion 确认）：

A) 快速 — 只测 P0 核心流程（约5-10分钟）→ Phase 1+2
B) 标准 — 快速 + P1 视觉/响应式（约15-30分钟）→ Phase 1+2+3
C) 详尽 — 标准 + P2-P3 可访问性和边界（约30-60分钟）→ Phase 1+2+3+4

测试模式（自动选择）：

模式	触发条件	行为
Diff-aware	在 feature 分支且有 base diff	从 diff 推断影响范围，聚焦测试
Full	指定了 URL 或用户要求	系统性遍历所有页面
Regression	存在 FEEDBACK.md 或历史 QA 报告	优先测试历史反馈项 + 变更回归

第1步：建立健康基准

在测试前打分（0-100分）：

维度	权重	评估方式
控制台错误	15%	JS 错误数量（0→100, 1-3→70, 4-10→40, 10+→10）
链接完整性	10%	死链数量（每个 -15，最低 0）
核心功能	20%	主要用户流程是否可用
视觉呈现	10%	页面布局、样式是否正确
用户体验	15%	交互流畅度、反馈及时性
性能	10%	首屏加载、LCP、CLS
内容	5%	文案、数据展示是否正确
无障碍	15%	键盘导航、对比度、语义化

使用 gstack/browse 或 Playwright 截取基准截图和控制台状态。

第2步：理解现状

迭代模式（已有 QA.md）

读取 PRD 最新迭代摘要，提取验收标准
读取 ENGINEERING.md，提取 API 契约和测试矩阵
读取 DESIGN.md，提取视觉硬规则（字号、颜色、间距）
读取 FEEDBACK.md（如有），提取历史用户反馈 → 纳入回归基线
读取 QA.md + QA CHANGELOG，做热点分析
向用户总结当前状态

从零创建模式（无 QA.md）

分析项目测试现状（检查 tests/、覆盖率、CI 配置）
与用户多轮确认（测试策略、范围、验收标准）
产出 QA.md 初稿（参考 references/qa-template.md）

第2.5步：生成 test-spec（铁律：不生成就不执行）

输入 → 输出映射

输入源	提取内容	转化为
PRD 验收标准	"用户点击卡片，弹出详情面板"	`functional` 断言
DESIGN.md 规则	"最小字号 12px"、"4px 间距网格"	`visual` CSS 断言
ENGINEERING.md API	"GET /api/feed → { items: [...] }"	`network` 断言
git diff	"修改了 DetailPanel.tsx"	`regression` 聚焦断言
会话上下文	"刚实现了频道切换功能"	`functional` 断言
FEEDBACK.md	历史用户反馈	`regression` 回归断言

test-spec.json 结构

重要：选择器必须来自 Step 0.4 的审计结果，不能编造不存在的 data-testid。 下面的示例用 $SELECTOR_* 占位符表示"根据审计结果填充实际选择器"。

{
  "metadata": {
    "source": "PRD.md v10.1 + DESIGN.md v2",
    "branch": "eng/feature-slug-2026-03-28",
    "generated_at": "2026-03-28T10:00:00Z",
    "scope": "full | diff-aware | regression",
    "app_url": "http://localhost:8080",
    "selector_strategy": "data-* + text + semantic"
  },
  "selector_map": {
    "_comment": "Step 0.4 审计产出，所有 case 引用此映射",
    "feed_section": "main > section:first-child",
    "info_card": ".cursor-pointer:has(h3)",
    "detail_panel": "[role='dialog']",
    "tab_nav": "nav button",
    "search_input": "input[placeholder*='搜索']"
  },
  "suites": [
    {
      "id": "feed-display",
      "name": "信息流展示",
      "source_ref": "PRD.md#v10.0-信息流",
      "priority": "P0",
      "cases": [
        {
          "id": "feed-001",
          "description": "首页加载后展示信息卡片",
          "dimension": "functional",
          "steps": [
            { "action": "navigate", "url": "/" },
            { "action": "wait", "selector": "main > section:first-child", "timeout": 8000 }
          ],
          "assertions": [
            { "type": "visible", "selector": "main > section:first-child" },
            { "type": "count_gte", "selector": ".cursor-pointer:has(h3)", "min": 1 },
            { "type": "contains_text", "selector": "main", "texts": ["$EXPECTED_SECTION_TITLE"] },
            { "type": "no_console_errors" }
          ]
        },
        {
          "id": "feed-002",
          "description": "卡片点击→详情面板，验证内容完整性（数据驱动）",
          "dimension": "data-driven",
          "data_driven": {
            "selector": ".cursor-pointer:has(h3)",
            "sample_size": 15,
            "strategy": "stratified"
          },
          "steps": [
            { "action": "click", "selector": "$item" },
            { "action": "wait", "selector": "[role='dialog']", "timeout": 5000 }
          ],
          "assertions": [
            { "type": "visible", "selector": "[role='dialog']" },
            { "type": "evaluate", "description": "详情面板有标题且文本长度 > 0",
              "script": "const panel = document.querySelector('[role=\"dialog\"]'); const title = panel?.querySelector('h2, h3'); if (!title || title.textContent.trim().length === 0) throw new Error('详情面板标题为空')" },
            { "type": "evaluate", "description": "详情面板有实质内容（不只是骨架屏）",
              "script": "const panel = document.querySelector('[role=\"dialog\"]'); const textLen = panel?.innerText?.trim().length || 0; if (textLen < 50) throw new Error(`面板内容过短: ${textLen} 字符`)" },
            { "type": "no_console_errors" }
          ]
        }
      ]
    }
  ]
}

选择器规则（参考 Step 0.4 审计 + Playwright 最佳实践）：

只使用审计中确认存在的选择器，绝不编造不存在的 data-testid
优先级：role/aria > data-* 属性 > 语义标签 > 可见文本 > CSS class 组合
如果项目缺乏稳定选择器，在 QA 报告的"改进建议"中提出，交由 forge-eng 补充

断言深度规则（铁律 4 的展开）

核心原则："it renders" ≠ "it works correctly"。

每个 test case 的 assertions 数组必须包含至少一个深层断言。visible 和 count_gte 只能作为前置条件（确认元素在 DOM 中），不能作为验收断言。

❌ 反面示例（浅断言 — 只验证"存在"不验证"正确"）

{
  "id": "starred-001",
  "description": "收藏页展示收藏的卡片",
  "assertions": [
    { "type": "visible", "selector": "section.starred-view" },
    { "type": "count_gte", "selector": ".cursor-pointer:has(h3)", "min": 1 }
  ]
}

问题：只验证了"收藏页有卡片"，没验证卡片确实是收藏的、内容确实渲染了。

✅ 正面示例（深层断言 — 验证数据正确性和功能完整性）

{
  "id": "starred-001",
  "description": "收藏页展示收藏的卡片",
  "assertions": [
    { "type": "visible", "selector": "section.starred-view" },
    { "type": "count_gte", "selector": ".cursor-pointer:has(h3)", "min": 1 },
    { "type": "evaluate", "description": "每张卡片有标题且标题非空",
      "script": "const cards = document.querySelectorAll('.cursor-pointer:has(h3)'); cards.forEach((c, i) => { const title = c.querySelector('h3'); if (!title || title.textContent.trim().length === 0) throw new Error(`第 ${i+1} 张卡片标题为空`) })" },
    { "type": "evaluate", "description": "收藏页卡片数量与页面显示的统计数一致",
      "script": "const displayed = document.querySelectorAll('.cursor-pointer:has(h3)').length; const header = document.querySelector('h2, [class*=\"header\"]')?.textContent || ''; const match = header.match(/(\\d+)/); if (match && displayed !== parseInt(match[1])) throw new Error(`显示 ${displayed} 张但标题显示 ${match[1]}`)" }
  ]
}

测试场景	浅断言（❌ 不够）	深层断言（✅ 必须）
详情/弹窗	`panel.isVisible()`	`panel.innerText.length > 50` + 包含标题/关键区块
列表/收藏	`cards.count() > 0`	每张卡片有标题且非空，数量与页头统计一致
Tab/频道切换	`section.isVisible()`	切换后内容区文本变化（不是切前的旧内容）
SSE/流式生成	`button.isVisible()`	触发 → 中间态可观测 → 完成后结果持久化（reload 仍在）
搜索/过滤	`results.isVisible()`	结果包含关键词，数量合理，空结果有空状态提示
模态框/对话框	`dialog.isVisible()`	有标题 + 正文文本长度 > 0 + Escape 可关闭
表单提交	`form.isVisible()`	填充 → 提交 → 反馈出现（toast/跳转/数据变化）
URL/深度链接	`page.loaded()`	直接访问带参数的 URL → 视图状态与参数一致
懒加载内容	`skeleton.gone()`	等待加载完成 → 内容非空 → 数量/值与预期一致

自检规则

生成 test-spec 后，自动扫描所有 case：

如果某个 case 的 assertions 只有 visible/count_gte/hidden 类型 → 标记为 ⚠️ 浅断言，必须补充深层断言
如果某个 case 没有任何 contains_text/evaluate/has_attribute/css_value/matches_regex → 拒绝执行，回到 test-spec 生成步骤补充

test-spec 不是手写的

test-spec 由 Claude 基于文档理解自动生成，但它是结构化的、可审查的。生成后必须输出摘要供用户确认。

第3步：生成验收计划并请用户确认

铁律：不是技术 test-spec 的摘要，而是用户可读的验收计划。 用户需要先理解"要验什么"，才能判断测试是否充分。

3.1 检查 Feature Spec

读取 PRD 中的 Feature Spec 章节。如果存在：

从 Feature Spec 的验收检查表提取所有验收项
将 Given/When/Then 场景映射为 test-spec 用例
Feature Spec 的验收检查表是 QA 的主要输入，test-spec 的每个用例 SHALL 可追溯到 Feature Spec 中的某个场景

如果 Feature Spec 不存在：

通过 AskUserQuestion 警告：「PRD 中没有 Feature Spec，QA 将基于 PRD 功能描述生成测试，但验收标准可能不够精确。建议先运行 /forge-prd 补充 Feature Spec。」
如果用户选择继续，降级为从 PRD 功能描述 + DESIGN.md 提取验收项

3.2 生成验收计划文档

基于 Feature Spec（或降级来源），生成一份先全局后细节的验收计划：

## QA 验收计划：{功能名}

### 全局验证（先看整体是否符合预期）

#### 用户流程完整性（对标 Feature Spec 第一节）
- [ ] 用户流程从 {入口} 到 {出口} 无断点
- [ ] 异常路径均有对应的错误处理
- [ ] 流程图中的每个步骤在实际页面中都可达

#### 页面/系统结构合规性（对标 Feature Spec 第二节）
- [ ] 整体布局与 Feature Spec 的结构图一致
- [ ] 各区块职责与描述匹配
- [ ] 组件列表完整，无遗漏无多余

---

### 逐项验证（再看具体细节）

| # | 验收项 | 来源 | 测试方法 | 断言类型 |
|---|--------|------|---------|---------|
| 1 | {场景描述} | Feature Spec: {Requirement名}.正常 | {Playwright/gstack} | {contains_text/css_value/...} |
| 2 | {场景描述} | Feature Spec: {Requirement名}.异常 | ... | ... |
| ... | ... | ... | ... | ... |

---

### 视觉合规验证（对标 DESIGN.md + Feature Spec CSS 约束）

| # | 组件 | CSS 属性 | 预期值 | 断言方式 |
|---|------|---------|--------|---------|
| V1 | {组件名} | font-size | {值} | css_value |
| V2 | {组件名} | color | {值} | css_value |
| V3 | {组件名} | padding | {值} | css_value |
| ... | ... | ... | ... | ... |

如果存在 Image 2 视觉稿、`.do-dev/visual-decision.md` 或 `.deliver/visual-decision.md`，在计划中单列「视觉意图参考」：说明会用真实浏览器截图对比信息层级、密度、主操作和空态/错态覆盖。Image 2 不作为 pass/fail 证据，pass/fail 只来自 Feature Spec、DESIGN.md、CSS 属性、行为断言和真实截图。

---

共 {N} 项验收（功能 {X} 项 + 视觉 {Y} 项 + 流程 {Z} 项），预计 {时间}。

3.3 用户确认

通过 AskUserQuestion 展示验收计划摘要并等待确认：

📋 验收计划已生成（基于 Feature Spec + DESIGN.md）

全局验证：
  - 用户流程完整性：{步骤数} 步
  - 页面结构合规性：{区块数} 区块，{组件数} 组件

逐项验证：
  - 功能场景：{X} 项（{功能点数} 个功能点 × 3 场景）
  - 视觉合规：{Y} 项（CSS 属性断言）
  - 流程完整：{Z} 项

A) 确认执行
B) 需要增减测试项（说明哪些）
C) 需要看完整验收计划再决定
D) Feature Spec 有误，需要先修正

⚠️ 用户确认后才执行测试。

第4步：更新 QA 文档

更新/创建 QA.md（参考 references/qa-template.md）
更新 QA CHANGELOG
将 test-spec.json 保存到报告目录

第5步：7 维度测试执行

使用 qa-runner.mjs 框架。 详细代码模板参考 references/test-dimensions.md。

测试脚本编写规范

必须使用 qa-runner.mjs 框架，不从零写脚本：

import { TestCollector, attachMonitors, snap, snapElement, createPage, pickStratified, writeResults } from '$QA_RUNNER';

const collector = new TestCollector();
const { browser, page } = await createPage();
attachMonitors(page, collector);

// ... 测试逻辑（使用 collector.pass/fail/skip）...

collector.printSummary();
writeResults(collector);
await browser.close();
process.exit(collector.summary().failed > 0 ? 1 : 0);

$QA_RUNNER 替换为前置脚本检测到的路径。

执行分阶段（快速失败）

Phase 1 冒烟（所有级别都执行）
  ├── 控制台零容忍 [console]：page.on('pageerror') + page.on('console error')
  ├── 首页加载：导航 → 等待 → 断言核心元素可见
  └── API/网络基础 [network]：检查 /api/* 状态码 < 400
  → 如果 Phase 1 全 FAIL → 停止测试（环境问题），报告并退出

Phase 2 核心功能（快速+标准+详尽）
  ├── 交互完整性 [functional]：Tab 切换、按钮点击、模态框开关
  ├── 数据驱动遍历 [data-driven]：采样 N 个元素，逐一验证
  ├── SSE/流式生成 [streaming]：全链路（触发→中间态→完成→持久化），有 SSE 时启用
  ├── URL 状态 [url-state]：正反向验证（操作→URL + URL→视图恢复），有路由状态时启用
  └── 懒加载/异步 [async-content]：加载态→内容验证→分页/进度，有异步加载时启用
  → 覆盖 P0 用例

Phase 3 视觉+响应式（标准+详尽）
  ├── 视觉规则断言 [visual]：CSS 属性验证（字号、颜色、间距）
  └── 响应式断点 [responsive]：375/768/1440 三个视口
  → 覆盖 P1 用例

Phase 4 深度（仅详尽级别）
  ├── 可访问性 [accessibility]：axe-core WCAG 2.0 AA
  └── 边界条件：空数据、超长文本、网络异常
  → 覆盖 P2-P3 用例

7 维度概述

维度 1: 控制台零容忍 [console]

attachMonitors() 自动挂载。每个导航/交互后通过 collector.checkConsoleErrors() 检查。任何 pageerror = 自动 FAIL，包含错误文本和 stack trace。

能发现：React 渲染崩溃、未捕获异常、404 资源 不能发现：被 try-catch 包裹的静默错误

维度 2: 数据驱动遍历 [data-driven]

不测 1 个元素，采样 N 个。使用 pickStratified() 分层采样（首尾 + 均匀分布）。每个元素独立 pass/fail，统计崩溃率并推算总体影响。

能发现：27% 卡片因数据类型不一致崩溃（当前完全测不到的） 不能发现：需要特定数据组合才触发的 bug

维度 3: 网络契约验证 [network]

attachMonitors() 自动收集 /api/* 响应。断言：状态码 < 400 + 响应结构匹配。如果 ENGINEERING.md 定义了 API schema，验证响应 JSON 结构。

能发现：API 404、响应结构变更、后端未启动 不能发现：语义正确但数据错误的响应

维度 4: 视觉规则断言 [visual]

从 DESIGN.md 提取硬规则 → CSS 断言。使用 page.evaluate(el => getComputedStyle(el))。检查项：字号 ≥ 12px、间距遵循 4px 网格、平台配色正确。如果有 Image 2 视觉稿，仅用作解释偏差的参考，不能替代 CSS 断言或真实截图。

能发现：字号不达标、间距违规、颜色错误 不能发现："看起来不对但 CSS 值合规"的美学问题

维度 5: 交互完整性 [functional]

每个可交互元素：操作 → 状态变化断言 → 可逆性验证。 Tab: click → aria-selected === true → panel visible 模态框: click → modal visible → Escape → modal gone

能发现：Tab 崩溃、按钮无响应、模态框不可关闭 不能发现：交互流畅度、动画是否自然

维度 6: 响应式断点 [responsive]

三个断点：mobile(375×812) / tablet(768×1024) / desktop(1440×900)。每个断点检查：无水平溢出 + 触控目标 ≥ 44px + 截图留证。

维度 7: 可访问性 [accessibility]

axe-core WCAG 2.0 AA 扫描 + 键盘导航验证（Tab 遍历 + Enter 激活 + Escape 关闭）。

维度 8: SSE / 流式生成全链路 [streaming]

适用条件：项目包含 SSE 端点、WebSocket、流式 AI 生成等实时特性。通过 Step 0.4 扫描 EventSource、fetch.*stream、WebSocket 判断是否启用。

测试全生命周期，不只是"按钮存在"：

触发入口（按钮/表单）→ 中间态（loading/thinking/progress）→ 数据流（逐步到达）→ 完成态 → 持久化验证（reload 后数据仍在）

关键断言：

触发后：中间态 UI 出现（spinner/进度条/thinking 动画），按钮变为不可操作
流式期间：内容区逐步增长（textContent.length 单调递增）
完成后：loading 消失，最终内容完整渲染
取消/中断：如果有取消按钮，点击后回到 idle 态，无残留
持久化：刷新页面后，生成的内容仍然存在（最关键的深层断言）
错误恢复：模拟网络中断（page.route 拦截 → abort），UI 显示错误态而非卡死

维度 9: URL 状态 / 深度链接 [url-state]

适用条件：项目使用 hash 路由（#view=xxx）、query 参数（?tab=xxx）、或 SPA 路由（/page/xxx）管理视图状态。通过 Step 0.4 扫描 useHash、useRouter、history.pushState、window.location.hash 判断是否启用。

测试双向一致性：

操作 → URL 变化        （正向：UI 操作驱动 URL 更新）
URL → 视图恢复         （反向：直接访问 URL 恢复完整状态）

关键断言：

正向：点击 Tab/频道/卡片 → page.url() 包含对应参数
反向：直接 page.goto(url_with_params) → 视图状态正确恢复（Tab 选中、内容加载）
深度链接：带完整参数的 URL（如 #l1=recommend&d=item-123）→ 详情面板自动打开，内容正确
浏览器前进/后退：page.goBack() / page.goForward() → 视图正确切换
边界：无效参数的 URL（如 #d=nonexistent-id）→ 优雅降级，不白屏

维度 10: 懒加载 / 异步内容 [async-content]

适用条件：项目包含分页加载、无限滚动、骨架屏、点击后异步获取详情等模式。几乎所有现代 SPA 都适用。

测试加载全生命周期：

触发加载 → 加载态（skeleton/spinner）→ 内容到达 → 加载态消失 → 内容正确

关键断言：

等待策略：不用 waitForTimeout 硬等，使用 waitForResponse 或 waitForSelector 等具体条件
骨架屏消失：如果有 skeleton，等待 .skeleton 消失再断言内容
内容非空：加载完成后，内容区 textContent.length > 0（不只是 skeleton 被替换为空 div）
分页/进度：如果有进度提示（"加载中 500/10740"），验证进度文本格式正确，全部加载完成后进度消失
滚动加载：page.mouse.wheel 或 scrollIntoView 触发加载 → 新内容出现 → 总量增加
加载失败：page.route 拦截 API 返回 500 → 显示错误提示而非无限 loading

通用等待模式（替代 waitForTimeout）：

// ❌ 硬等（不可靠，慢）
await page.waitForTimeout(3000);

// ✅ 等 API 响应（精确）
await page.waitForResponse(resp => resp.url().includes('/api/feed') && resp.status() === 200);

// ✅ 等骨架屏消失（语义化）
await page.waitForSelector('.skeleton', { state: 'hidden', timeout: 10000 });

// ✅ 等内容出现（直接）
await page.waitForSelector('main .cursor-pointer:has(h3)', { timeout: 10000 });

// ✅ 等网络空闲（兜底）
await page.waitForLoadState('networkidle');

Codex Browser Use 引擎（用户视角浏览器验收）

在 Codex 环境中，如果 Browser Use 插件可用，前端页面、交互、视觉、控制台检查优先使用 browser-use:browser：

使用 Codex in-app browser 打开调用方传入的 APP_URL
通过 DOM snapshot 构造稳定 locator，不盲猜选择器
每次点击、输入、切换、提交后采集最小必要状态：DOM snapshot 或截图
关键状态节点截图保存到 QA 报告或 Bug 修复验收报告指定目录，并用 Markdown 内嵌
读取 console logs，任何 error 进入 FAIL
如果代码或 build 刚变更，测试本地页面前先 reload，再重新采集 DOM/screenshot

使用规则：

执行浏览器动作前必须先加载并遵守 browser-use:browser skill。
初始化 Browser 时使用 iab backend 和 Node REPL 的 browser-client runtime。
不用 Computer Use 操作浏览器，除非 Browser Use 不可用、被中断或目标不是浏览器页面；兜底原因必须写入报告。
Browser Use 负责用户视角证据，仍需配合断言。截图不能单独作为 PASS。
需要可重复批量回归时，Browser Use 证据可与 Playwright 脚本断言并行使用。

gstack/browse 引擎（快速探索和截图标注）

当 gstack/browse 可用时，可作为 Playwright 的补充：

$B goto <URL>
$B snapshot -i -a     # 标注所有可交互元素
$B console --errors   # 控制台错误
$B network            # 网络请求
$B perf               # LCP、CLS 性能
$B screenshot $REPORT_DIR/screenshots/overview.png
$B responsive         # 三视口截图

引擎协同：

browser-use:browser：Codex in-app browser 用户视角操作、DOM 快照、截图证据
Playwright + qa-runner：结构化断言、数据驱动、网络拦截、可重复回归
gstack/browse：快速探索、截图标注、性能指标

纯代码测试（无浏览器引擎时）

逐文件读取实现代码，检查边界情况
验证错误处理完整性
检查 API 输入验证
运行项目已有的测试框架（npm test / pytest 等）

第6步：智能分析 + Bug 报告

分析流程

对每个 FAIL 的测试用例：

错误分类
- Console Error → 提取 stack trace → 定位源文件:行号
- 元素不存在 → 检查选择器 → 检查组件是否渲染
- 网络错误 → 检查后端日志 → 检查 API 路由
- 视觉偏差 → 检查 CSS 来源 → 对比 DESIGN.md 规则
交叉验证
- 将 console error 中的文件路径 → 对应到 git diff 中的变更文件
- 在 diff 中 → 标记 [本次引入]
- 不在 diff 中 → 标记 [已有问题]
影响范围估算
- data-driven 测试：5/20 崩溃 → 推算 25% 数据受影响
- 功能测试：特定 tab 崩溃 → 标记该 tab 下所有功能受影响

Bug 登记格式

### BUG-001 [严重度] 标题

**现象：** 用户看到了什么
**影响：** 影响范围（如"25% 的卡片无法打开详情"）
**证据：**
  - Console: "错误信息原文"
  - Stack: `文件:行号`
  - 截图: qa_screenshots/XX_name.png
**根因定位：**
  - 文件: `src/components/DetailPanel.tsx:360`
  - 原因: 一句话说明
**本次引入：** 是/否（基于 git diff 交叉引用）
**修复建议：** 简要描述修复思路

严重度分类

严重度	定义	处理
严重	核心功能崩溃/不可用	必须修复
高	功能可用但结果错误	必须修复
中	功能可用但体验差	建议修复
低	外观/措辞/细节问题	可延后

修复清单产出

# 修复清单（forge-qa 生成）

## 必须修复（严重 + 高）
- [ ] BUG-001: {现象} — {文件:行号} — {修复方向}
- [ ] BUG-002: ...

## 建议修复（中）
- [ ] BUG-003: ...

## 可延后（低）
- [ ] BUG-005: ...

QA 自动闭环交付给 forge-bugfix

当 forge-qa 处于功能开发后的自动闭环场景，发现属于本轮 Feature Spec 或本次 diff 引入的 bug 时，不能只写散文报告，必须为 forge-bugfix 准备结构化输入：

### BF-CANDIDATE: {标题}

**建议严重度**：P0 / P1 / P2
**是否属于本轮范围**：是 / 否 / 待用户判断
**关联 Feature Spec**：docs/PRD.md#...
**用户可见现象**：...
**复现步骤**：
1. ...
2. ...
3. ...
**前端地址**：...
**后端/API 地址**：...
**环境身份摘要**：Frontend PID/cwd, Backend PID/cwd, commit
**截图证据**：
![](./qa_screenshots/BUG-001-step-01.png)
![](./qa_screenshots/BUG-001-step-02.png)
**深度断言失败**：文本/状态/URL/CSS/网络/数据断言摘要
**console/network 证据**：...
**建议交给 forge-bugfix 的原因**：...

调度层或 forge-dev 可以把这些候选写入 docs/bugfix/backlog.md，创建对应 docs/bugfix/reviews/BF-XX.md，然后逐个调用 forge-bugfix。forge-qa 自己仍然只测不修。

自动闭环分类规则：

分类	处理
属于本轮 Feature Spec / 本次 diff 引入	自动登记 BF，进入 forge-bugfix
回归破坏核心流程	自动登记 BF，进入 forge-bugfix
新需求或设计取舍	登记为待用户判断，不自动修
范围外低优先级问题	登记 backlog，不阻塞本轮
环境身份无法确认	BLOCKED_HUMAN，不进入 bugfix

第7步：User Gate（用户验收关卡）

铁律：不可跳过。 QA 自动化测试无法覆盖设计意图偏差、功能遗漏等只有用户能判断的问题。

输出与等待

QA 报告生成后，输出以下内容并等待用户操作：

╔══════════════════════════════════════════╗
║           QA 报告已生成                   ║
╠══════════════════════════════════════════╣
║  通过: 10  失败: 3  跳过: 1              ║
║  健康评分: 72/100                        ║
║  报告: .gstack/qa-reports/qa-report-*.md ║
╠══════════════════════════════════════════╣
║  请验收后选择：                            ║
║  A) 验收通过 → 进入发布流程                ║
║  B) 验收不通过 → 填写反馈，回 forge-eng     ║
║  C) 我需要先自己体验一下                    ║
╚══════════════════════════════════════════╝

用户操作

A) 验收通过（accept）

更新 .features/status.md qa 行为 [✅ 已完成]
建议下一步：/forge-review 或 /forge-ship

B) 验收不通过（reject）

引导用户描述问题（可以直接在会话中描述）
Claude 自动提取为 FEEDBACK.md 格式
⚠️ 触发举一反三机制（见下方）
合并 qa-report 中未修复的 BUG + 用户 FEEDBACK + 举一反三发现
生成统一修复清单 → /forge-eng

举一反三机制（用户反馈问题时 SHALL 执行）

当用户报告任何问题时，SHALL 按以下步骤执行：

修复用户指出的问题
搜索相似模式：
- 使用 Grep 在代码库中搜索与该问题相同的模式（同类 CSS 属性、同类组件、同类逻辑）
- 示例：用户报告「某组件间距不对」→ Grep 搜索所有使用相同 margin/padding 值的组件
回查 Feature Spec：
- 读取 PRD 中的 Feature Spec，检查其他行为场景是否可能存在同类问题
- 检查验收检查表中未测试的项是否包含类似约束

产出「类似风险清单」：

### 举一反三：类似风险清单

用户反馈：{用户描述的问题}
根因：{问题的根本原因}

发现 {N} 处类似风险：
1. {文件路径:行号} — {组件/模块名} 使用了相同的 {模式}，可能存在同样问题
2. {文件路径:行号} — Feature Spec 场景 {场景名} 的 THEN 要求 {约束}，当前实现为 {实际值}
3. ...

请用户确认：

发现 {N} 处类似风险，要一并修复吗？
A) 全部修复
B) 选择性修复（指定哪些）
C) 只修复用户指出的问题，其余记录到 FEEDBACK.md

SHALL NOT 仅修复用户明确指出的单点问题就声称完成。

C) 用户自行体验

暂停，等待用户回来反馈
用户可以随时在会话中描述问题

FEEDBACK.md 结构

# User Feedback — {feature-name}

## 元数据
- 日期: YYYY-MM-DD
- QA 报告参考: qa-report-YYYY-MM-DD.md
- 分支: eng/feature-name-YYYY-MM-DD

## 反馈项

### UF-001 [Design Intent] 标题
**期望：** 用户期望的行为
**现状：** 实际看到的行为
**参考：** DESIGN.md#section 或 PRD.md#version
**截图：** feedback_screenshots/001.png（可选）

### UF-002 [Missing] 标题
**期望：** PRD 中描述的功能
**现状：** 功能缺失或未实现
**参考：** PRD.md#section

反馈类型：

[Design Intent] — 设计意图偏差（QA 测不到的，只有用户能判断）
[Missing] — 功能缺失（PRD 有但没实现）
[Regression] — 回归问题（之前好的现在坏了）
[Polish] — 打磨细节（能用但不够好）

FEEDBACK.md 的流转

谁	怎么用
forge-eng	读取 → 作为 fix list，和 qa-report BUG 一起修
forge-qa（下一轮）	读取 → 纳入 test-spec 回归项，确保不再漏测
forge-qa（长期）	历史 FEEDBACK 累积为项目回归测试基线
用户	只写"发现了什么 + 期望什么"，不需要定位根因

反馈闭环流程

QA 报告 → User Gate → reject
                        │
                        ↓
                  FEEDBACK.md（用户反馈）
                        │
                        ↓
                  合并修复清单 = qa-report BUG + FEEDBACK
                        │
                        ↓
                  forge-eng（修复）
                        │
                        ↓
                  forge-qa（回归）
                    ├── test-spec 自动包含 FEEDBACK 项
                    └── 只测变更 + FEEDBACK 涉及范围
                        │
                        ↓
                  User Gate（再次验收）
                        │
                        └── ... 直到 accept

第8步：健康评分与报告

健康评分计算

维度	权重	评分方式
控制台错误	15%	0 错误→100, 1-3→70, 4-10→40, 10+→10
链接完整性	10%	每个死链 -15，最低 0
核心功能	20%	每个严重 -25, 高 -15, 中 -8, 低 -3
视觉呈现	10%	同上
用户体验	15%	同上
性能	10%	同上
内容	5%	同上
无障碍	15%	同上

报告结构（先全局后细节）

QA 报告 SHALL 采用以下结构，让用户先看整体是否符合预期，再审阅细节：

# QA 验收报告：{功能名}

**日期**: YYYY-MM-DD  **分支**: {branch}  **PRD 版本**: vX.Y

---

## 一、全局评估（先看整体）

### 用户流程完整性
- 状态：PASS / FAIL
- 说明：{流程是否通畅，哪些步骤有问题}
- 证据：{流程截图或描述}

### 页面/系统结构合规性
- 状态：PASS / FAIL
- 说明：{整体布局是否符合 Feature Spec 第二节的结构图}
- 偏差项：{列出与 Feature Spec 不一致的区块/组件}

### 整体健康评分：XX/100

---

## 二、逐项验收结果（再看细节）

| # | 验收项 | 来源场景 | 结果 | 证据 |
|---|--------|---------|------|------|
| 1 | {描述} | {Feature Spec 场景} | ✅ PASS | {截图/日志} |
| 2 | {描述} | {Feature Spec 场景} | ❌ FAIL | {错误详情} |
| ... | ... | ... | ... | ... |

通过率：{X}/{Y} ({Z}%)

---

## 三、视觉合规结果

| # | 组件 | CSS 属性 | 预期值 | 实际值 | 结果 |
|---|------|---------|--------|--------|------|
| V1 | {名} | font-size | 14px | 14px | ✅ |
| V2 | {名} | color | #1e293b | #333 | ❌ |
| ... | ... | ... | ... | ... | ... |

---

## 四、发现的问题（按严重度排序）

{BUG 登记，格式同第6步}

---

## 五、验收结论

- 上线就绪：✅ / ⚠️ / ❌
- 必须修复：{N} 项
- 建议修复：{N} 项
- 举一反三风险：{N} 项（如有用户反馈触发）

报告输出

输出到项目目录：$REPORT_DIR/qa-report-{YYYY-MM-DD}.md

.gstack/qa-reports/
├── qa-report-{YYYY-MM-DD}.md      # 结构化报告（先全局后细节）
├── test-results.json               # 结构化结果（机器可读，qa-runner 产出）
├── test-spec.json                  # 测试规格（用于回归）
├── screenshots/                    # 截图证据
└── baseline.json                   # 回归基准数据

终端报告

+============================================================+
|                     QA 交付完成                              |
+============================================================+
| 项目：[项目名]      分支：[分支名]                            |
| 测试级别：快速 / 标准 / 详尽                                   |
| 测试引擎：qa-runner + gstack/browse                          |
+------------------------------------------------------------+
| 测试结果                                                     |
|   总计: XX  通过: XX  失败: XX  跳过: XX                      |
|   通过率: XX%  控制台错误: XX  网络错误: XX                    |
+------------------------------------------------------------+
| 健康评分：XX/100                                             |
| 上线就绪：✅ 可以上线 / ⚠️ 需关注 / ❌ 不建议                  |
+------------------------------------------------------------+
| 等待用户验收（User Gate）...                                   |
+============================================================+

Feature 状态管理

启动时

读取 .features/{feature-id}/status.md，确认 eng 行为 [✅ 已完成]
将 qa 行更新为 [🔄 进行中]

执行中

更新 QA Items 表，每个测试项独立状态

完成时

通过：qa 行 [✅ 已完成]，note: {passed}/{total} PASS, {score}/100
未通过：qa 行 [❌ 失败]，note: {failed} FAIL, 需修复后重测
更新 _registry.md heartbeat

重要规则

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

资源

QA 文档模板：references/qa-template.md
10 维度代码模板：references/test-dimensions.md
通用测试引擎：scripts/qa-runner.mjs

Mode B：单 bug 修复验收报告模式

🎯 配合 forge-bugfix 的 P6 调用。目标：针对一个 bug 的 Bug 修复验收报告跑自动化测试，把环境身份、逐步截图、深度断言回填到同一份报告里。

B.1 前提与入口

触发方：forge-bugfix 的 P6 节点
传入参数：REVIEW_DOC（Bug 修复验收报告路径，形如 docs/bugfix/reviews/BF-0419-2.md）
跳过的节点：不做 test-spec 生成（Layer 1）、不做 User Gate（那一步由 forge-bugfix 的 P6.5 做）
继承的能力：仍然用 10 维度断言引擎和三种测试引擎（gstack / Playwright / 纯代码）

B.2 读取 Bug 修复验收报告

# 必须存在
[ -f "$REVIEW_DOC" ] || { echo "❌ Bug 修复验收报告不存在: $REVIEW_DOC"; exit 1; }

# 读取报告全部内容
cat "$REVIEW_DOC"

AI 解析出：

BUG_ID
修复 commit hash（用于定位修复范围）
涉及文件列表（用于缩小测试范围）
TDD / 回归用例区
验收入口与环境身份校验区
人工验收指南的每一行（检查点 / 操作步骤 / 预期效果）

B.3 为每个验证项选择测试引擎

验证项性质	默认引擎	选择理由
UI 交互 / 视觉 / 控制台	browser-use:browser（Codex 可用时优先）或 Playwright	需要真实浏览器和用户视角截图
API / 数据 / 业务逻辑	curl / 代码单元测试	更快更直接
响应式 / 可访问性	Playwright	专业断言库
静态代码属性（文件存在 / import 正确）	Grep / Bash	无需运行时

B.4 执行验证 + 回填

对每条验证项：

按"人工验收指南"的"怎么操作"执行
每个有意义的状态节点截图：打开页面、操作前、操作后、加载态、结果态、错误态
按"预期效果"做深度断言
截图保存到 docs/bugfix/reviews/assets/${BUG_ID}/，并在 Markdown 中用 ![](...) 内嵌
回填"QA 测试过程与截图证据"节和"验收入口与环境身份校验"节

在 Codex 环境中，前端验证默认用 browser-use:browser 采集截图和 DOM 证据；需要更强可重复性时，再补 Playwright 脚本断言。若 Browser Use 不可用或被用户/插件中断，报告必须写明 fallback 原因。

截图命名建议：

docs/bugfix/reviews/assets/${BUG_ID}/qa-1-01-open-page.png
docs/bugfix/reviews/assets/${BUG_ID}/qa-1-02-click-submit.png
docs/bugfix/reviews/assets/${BUG_ID}/qa-1-03-final-state.png

报告中必须写成：

![](./assets/BF-0419-2/qa-1-01-open-page.png)

断言原则（和 Mode A 一致）：

必须基于"用户视角可见的内容变化"
不得单独用技术指标（HTTP 200 数量 / DOM 节点存在）
每个测试至少包含一个内容、状态、URL、CSS、网络响应或数据变化断言
必须核对前后端进程身份（优先看 dev:status / dev-stack status；兜底用 ps aux | grep <服务> + lsof -p $PID | grep cwd）
QA 使用的 Frontend/Backend 地址必须和报告中交给用户验收的地址一致

B.5 控制台零容忍（强制）

任何 pageerror 或 console.error 自动标记为 FAIL，即使该验证项的主逻辑通过。

B.6 环境身份强校验

forge-qa 必须在报告的"验收入口与环境身份校验"区写入：

Frontend URL、来源、PID、cwd、branch/commit（能获取时）
Backend/API URL、来源、PID、cwd、branch/commit（涉及后端时）
API health 或关键接口探活结果（涉及后端时）
QA 执行时间
环境一致性结论：PASS / FAIL / EXPIRED

硬性 FAIL 条件：

QA 实际访问的 URL 与报告交给用户验收的 URL 不一致
能拿到 PID/cwd，但 cwd 不属于当前 worktree
前端页面来自旧进程或主仓库，而不是当前 bug worktree
涉及后端但 Backend/API 地址无法确认
交给用户前再次检查发现地址或进程身份已变化

B.7 回填"QA 测试过程与截图证据"节

forge-qa 必须填充报告里的"## QA 测试过程与截图证据（forge-qa 填）"：

## QA 测试过程与截图证据（forge-qa 填）

**模式**：Mode B（单 bug 修复回归）
**执行时间**：2026-04-19 15:45

**自动化测试范围**：
- 跑了 Playwright 重放（3 步：打开登录 / 登录 / 查看头像）
- 跑了 tests/auth.test.ts（2 个相关 case）
- 控制台检查：0 error, 0 warning

### 验证项 1：登录后头像刷新

**结论**：PASS

**操作轨迹与截图**

1. 打开登录页

   ![](./assets/BF-0419-2/qa-1-01-open-login.png)

2. 提交登录

   ![](./assets/BF-0419-2/qa-1-02-submit-login.png)

3. 检查右上角头像

   ![](./assets/BF-0419-2/qa-1-03-avatar-updated.png)

**断言**
- 头像元素可见：PASS
- 头像 URL 已更新：PASS
- console.error：0
- network error：0

**Bug 复现核对**：
- 修复前：重现了 BF-0419-2 的原始症状（已对比 before 截图）
- 修复后：原始症状消失（after 截图）

B.8 QA 自动闭环状态信号和退出

所有验证项 PASS 且环境一致性 PASS：

✅ QA_PASS (BF-0419-2)
报告已回填：docs/bugfix/reviews/BF-0419-2.md
下一步：交还 forge-bugfix。单 bug 模式进入 P6.5；批量模式进入 qa-pass-pending-final-review。

至少一条 FAIL 或环境一致性 FAIL：

❌ QA_FAIL (BF-0419-2)
失败项: 第 3 条（控制台 TypeError）
报告已回填 FAIL + 截图/日志证据。
下一步：交还 forge-bugfix，有界回 P5 继续修复。

需求/设计/环境身份无法判断：

⚠️ BLOCKED_HUMAN (BF-0419-2)
原因: 保存后是否必须 toast 提示，Feature Spec 未定义。
报告已写入决策卡。
下一步：交还 forge-bugfix，询问用户。

B.9 Mode B 不做的事

明确禁止：

❌ 不生成 docs/QA.md（那是 Mode A 的产物）
❌ 不做 User Gate（那由 forge-bugfix 的 P6.5 做）
❌ 不写 FEEDBACK.md（那是 Mode A 的 reject 闭环）
❌ 不主动判断"产品上是否接受"（只按报告和 Feature Spec 断言，最终由用户/批次验收决定）
❌ 不修改代码（和 Mode A 一样，只测不修）

B.10 Mode B 的铁律

只填 Bug 修复验收报告，不新建散乱 QA 文档
每条验证项必须有 pass/fail（和 Mode A 第 3 条铁律一致）
每个前端交互关键步骤必须有 Markdown 内嵌截图
控制台零容忍（一致）
不能越界修改用户验收列和最终结论
应用 URL 必须由调用方或 dev-status 提供，不得在 Mode B 中猜测本地端口。
环境身份校验失败就是 QA_FAIL，不能用“页面能打开”替代。
发现疑似新需求、范围外问题或设计歧义时输出 BLOCKED_HUMAN，不要替用户决定。
Codex 中优先使用 browser-use:browser 做本地浏览器验收；Computer Use 不是浏览器首选兜底。

Capabilities

skillsource-yike-gunshiskill-forge-qatopic-agent-skillstopic-ai-developmenttopic-claude-codetopic-forgetopic-skill-mdtopic-skillsmp

Install

Installnpx skills add yike-gunshi/forge-skills

Sourcehttps://github.com/yike-gunshi/forge-skills/tree/main/skills/forge-qa

skills.shhttps://skills.sh/yike-gunshi/forge-skills/forge-qa

Transportskills-sh

Protocolskill

Quality

0.46/ 1.00

deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 11 github stars · SKILL.md body (40,168 chars)

Provenance

Indexed fromgithub

Enriched2026-04-25 19:02:45Z · deterministic:skill-github:v1 · v1

First seen2026-04-24

Last seen2026-04-25

Agent access

JSONhttps://clawmart.sh/api/listings/t2ARYB

What it does

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

调用模式

三层架构

铁律

定位说明

完整流程

报告产出后的出口

前置脚本

AskUserQuestion 格式规范

第0步：上下文探测与环境准备

0.1 Worktree 检测（铁律：在正确的分支上测试）

0.2 文档链定位

0.3 变更范围分析

0.4 选择器审计（铁律：不盲猜选择器）

0.5 测试级别与模式

第1步：建立健康基准

第2步：理解现状

迭代模式（已有 QA.md）

从零创建模式（无 QA.md）

第2.5步：生成 test-spec（铁律：不生成就不执行）

输入 → 输出映射

test-spec.json 结构

断言深度规则（铁律 4 的展开）

❌ 反面示例（浅断言 — 只验证"存在"不验证"正确"）

✅ 正面示例（深层断言 — 验证数据正确性和功能完整性）

更多断言深度检查表（生成 test-spec 时逐条对照）

自检规则

test-spec 不是手写的

第3步：生成验收计划并请用户确认

3.1 检查 Feature Spec

3.2 生成验收计划文档

3.3 用户确认

第4步：更新 QA 文档

第5步：7 维度测试执行

测试脚本编写规范

执行分阶段（快速失败）

7 维度概述

维度 1: 控制台零容忍 [console]

维度 2: 数据驱动遍历 [data-driven]

维度 3: 网络契约验证 [network]

维度 4: 视觉规则断言 [visual]

维度 5: 交互完整性 [functional]

维度 6: 响应式断点 [responsive]

维度 7: 可访问性 [accessibility]

维度 8: SSE / 流式生成全链路 [streaming]

维度 9: URL 状态 / 深度链接 [url-state]

维度 10: 懒加载 / 异步内容 [async-content]

Codex Browser Use 引擎（用户视角浏览器验收）

gstack/browse 引擎（快速探索和截图标注）

纯代码测试（无浏览器引擎时）

第6步：智能分析 + Bug 报告

分析流程

Bug 登记格式

严重度分类

修复清单产出

QA 自动闭环交付给 forge-bugfix

第7步：User Gate（用户验收关卡）

输出与等待

用户操作

举一反三机制（用户反馈问题时 SHALL 执行）

FEEDBACK.md 结构

FEEDBACK.md 的流转

反馈闭环流程

第8步：健康评分与报告

健康评分计算

报告结构（先全局后细节）

报告输出

终端报告

Feature 状态管理

启动时

执行中

完成时

重要规则

资源

Mode B：单 bug 修复验收报告模式

B.1 前提与入口

B.2 读取 Bug 修复验收报告

B.3 为每个验证项选择测试引擎

B.4 执行验证 + 回填