qa

QA

你正在对某项功能、错误修复或部署进行功能验证。你的工作是执行测试场景并收集证据，以证明它有效（或无效）。

协作约定

所有面向用户的问题都必须通过 AskUserQuestion 提出（Autopilot 模式下除外）——有关约定，请参阅 desplega:ask-user。

文件审查默认开启——准备好后，对 QA 报告执行文件审查（仅 Autopilot 模式下跳过）。

归属：QA 文档放在此处，而非计划中

QA 测试用例应放在 QA 文档中（thoughts/<username|shared>/qa/YYYY-MM-DD-<feature>.md），而非直接写在计划中。如果计划中有 ### QA Spec (optional): 区块，该区块会链接到此技能生成的 QA 文档。

此技能用于跨阶段或需要大量证据的 QA 工作，而非每个常规阶段的检查。常规的阶段 Agent 验证应放在计划内的 #### Automated QA: 部分，并由 phase-running 执行。以下情况请使用此技能：

• QA 工作跨越多个阶段或覆盖整个功能
• 证据（截图、录屏、日志）需要持久保存
• 需要正式判定结果（通过／失败／受阻）

调用方式：

• Planning Step 3（“生成 QA 文档”）会在交接前调用此技能，适用于 QA 需要单独文档的阶段。
• Implementing / phase-running 会在阶段完成时调用此技能，前提是该阶段报告了 QA Doc: <path>。
• 用户直接调用（/qa）会创建一份未关联到计划的独立文档。

QA 方法

除 Autopilot 模式外，在开始时询问一次：

问题	选项
“你希望如何执行测试用例？”	1. 如果可用，则使用浏览器自动化（agent-browser）；2. 按指导步骤手动测试；3. 混合方式：能自动化的部分自动化，其余手动测试

关于 agent-browser 是否可用的说明：运行 command -v agent-browser。这是 agent-browser npm CLI（vercel-labs），通过 CDP 驱动无头 Chromium。还要检查项目的 CLAUDE.md 是否指定了其他测试工具。如果 agent-browser 不可用且未指定其他工具，则默认手动测试。除非用户指定，否则绝不使用 qa-use。

适用情形

出现以下情况时启用此技能：

• 用户调用 /qa 命令
• 其他技能引用 desplega:qa
• 用户要求测试、验证或对某项功能进行 QA
• 实施技能遇到包含 QA 规范的阶段

自主模式

QA 开始时，根据自主模式调整交互程度：

模式	行为
Autopilot	执行所有测试用例、收集证据，并在最后提供摘要
Critical（默认）	询问测试用例的设计方式，并提交结果供审查
Verbose	逐一讲解每个测试用例，并在执行前确认

调用命令会传递自主模式。如果未指定，则默认为 Critical。

流程步骤

Step 1：背景与范围

确定 QA 规范的来源：

计划驱动（由 planning/implementing/phase-running 调用） → 系统会提供计划路径和阶段引用。阅读相关阶段，根据其 Overview 中指定的交付内容设计测试用例，并生成计划的 QA Spec 区块将要链接的 QA 文档。

已提供独立 QA 规范文档 → 阅读独立规范，并以其为基础开展 QA。

用户直接调用，未提供来源 → 与用户一起从头编写测试用例。使用 AskUserQuestion 确定：

问题	选项
“我们要验证什么？请描述该功能或提供相关背景。”	[自由文本回复]

所有情况下，都要使用 cc-plugin/base/skills/qa/template.md 创建 QA 文档，存放在 thoughts/<username|shared>/qa/YYYY-MM-DD-<topic>.md。已知用户名时使用该用户名；否则使用 thoughts/shared/qa/。

计划驱动调用时：文档创建后，在相关阶段的计划 ### QA Spec (optional): 区块中更新文档路径。不要将测试场景直接写入计划。

步骤 2：设计测试用例

定义涵盖以下内容的测试用例：

• 成功路径 — 主要场景按预期运行
• 边界情况 — 边界条件、空输入、大量输入
• 错误场景 — 无效输入、权限失败、网络错误

如果来源是计划：将各阶段的 QA 规范汇总到测试用例列表中，并补充其他探索性用例。

如果来源是单独的规范：以其中的场景为起点，并补充探索性用例。

如果选择了浏览器自动化且 agent-browser 可用：为每个测试用例设计 agent-browser 步骤（打开、快照、对 refs 执行操作、截图）。

将所有测试用例写入 QA 文档的 ## Test Cases 部分。

步骤 3：执行测试

对于浏览器自动化（agent-browser）：如果已安装 agent-browser 技能（swarm 会预置一个），请遵循该技能。否则：

1. 在每个会话中使用 agent-browser skills get core 加载与版本匹配的指南一次（不要凭记忆猜测标志），然后运行 agent-browser open <url>
2. 运行 agent-browser snapshot -i 读取页面状态及其 @eN refs
3. 对 refs 执行操作（click @eN、fill @eN "text"、type、press），并在每次导航或状态变更后重新获取快照；refs 仅对生成它们的快照有效
4. 使用 agent-browser screenshot /tmp/<name>.png 获取证据，然后运行 agent-browser close
5. 如需在机器外分享截图，请使用 agent-fs write <path> --file /tmp/<name>.png -m "<what it shows>" 将其上传到 agent-fs（可安全处理二进制文件；--content 会损坏 PNG），将其作为原件保留在那里，并通过 GitHub 用户附件（github-attach 技能）将其嵌入 PR 或 GitHub 评论中：![caption](https://github.com/user-attachments/assets/<uuid>)。如需在 Slack 或 Linear 中分享，请使用 agent-fs share-create <path>。如果未配置 agent-fs，请报告本地路径并说明已跳过上传

对于手动测试：

1. 向用户展示每个测试用例的步骤
2. 引导用户完成测试
3. 使用 AskUserQuestion 收集结果：

问题	选项
"TC-N: [测试用例名称]。是否通过？"	1. 通过，2. 失败 — [描述实际情况]，3. 受阻 — [描述阻碍]，4. 跳过

对于 CLI 验证：

1. 直接执行 CLI 命令
2. 将输出与预期结果进行比较
3. 自动记录通过/失败状态

可选子技能： 当 CLI 测试用例需要在之后重新运行相同的多步探测（回归覆盖、部署后冒烟测试、多环境验证），且没有现有脚本可执行该操作时，可内联调用 desplega:script-builder。生成的脚本会提交到项目的 scripts/ 目录，并采用 PASS/FAIL + /tmp 日志约定；本次 QA 会话会用它执行当前测试，后续 QA/验证会话可通过自动添加到 CLAUDE.md 中的 <important if> 块发现该脚本。

对于每个测试用例，记录实际结果以及通过/失败状态。

步骤 4：收集证据

为 QA 报告收集证据：

• 截图：通过 agent-browser screenshot 获取（保存在 agent-fs 上；在 PR 中使用 GitHub 用户附件，在其他地方使用 share-create 链接），或由用户提供
• 视频：会话录制 URL（Loom 等）
• 日志：控制台输出、错误消息、相关日志行
• 外部链接：Sentry 问题、CI/CD 运行记录、Grafana 仪表板、PR URL

将所有证据添加到 QA 文档的 ## Evidence 部分。

步骤 5：记录结果

更新 QA 文档，包含：

• 每个测试用例的实际结果
• 每个测试用例的通过/失败/受阻/跳过状态
• 与相关测试用例内联的证据链接
• 在 ## Issues Found 部分记录发现的任何问题，并标注严重程度（critical/major/minor）

第 6 步：判定结果

汇总结果，给出总体判定：

判定结果	条件
PASS	所有测试用例均通过，且没有严重/重大问题
FAIL	任一测试用例失败，或发现严重/重大问题
BLOCKED	因环境/依赖问题而无法完成测试

在 QA 文档的 ## Verdict 部分用 1-2 句话撰写总结。更新 frontmatter 中的 status 字段，使其与判定结果一致（pass/fail/blocked）。

第 7 步：沉淀 QA 知识

如果项目的 CLAUDE.md 或 agents.md 没有说明该项目如何进行 QA，请提出添加一个 QA 部分，说明：

• 使用的测试方法（手动、浏览器自动化、CLI）
• 使用的工具（agent-browser、Playwright 等）
• 发现的常见测试模式

使用 AskUserQuestion 提问：

问题	选项
"This project doesn't have documented QA practices. Would you like me to add a QA section to CLAUDE.md?"	1. 是，添加 QA 文档，2. 不，跳过

如果在多次 QA 会话中发现了有用的模式，也请将其保存到记忆中。

评审集成

默认启用文件评审（Autopilot 模式除外）：

• QA 报告完成后，调用 /file-review:file-review <qa-report-path> 添加行内人工评论
• 使用 file-review:process-review 技能处理反馈

学习记录

可选子技能： 如果此工作流中出现了重要见解、模式、注意事项或决策，请考虑使用 desplega:learning 通过 /learning capture 进行记录。重点记录能帮助他人在未来会话中受益的经验。

工作流交接

QA 报告完成后，使用 AskUserQuestion 提问：

问题	选项
"QA complete. What's next?"	1. 运行 QA 后验证（→ /verify-plan），2. 评审 QA 报告（→ /review），3. 完成

根据回答执行：

• Verify：调用 desplega:verifying 技能
• Review：对 QA 文档调用 desplega:reviewing 技能
• Done：完成 QA 报告