user-acceptance

用户验收证据

操作说明

此技能触发时，收集真实证据，证明功能分支、工单或 PR 正常工作。将请求视为：“通过实际操作并生成可供人工检查的产物，证明已完成的工作。”

验收证据应来自实际体验，且可复现：

• 对于 UI 变更，在可行时录制视频，然后在有代表性的检查点截图。视频可记录时序、过渡效果、焦点和端到端流程。
• 对于 CLI 和 TUI 应用，收集终端记录、截图、录屏、生成的文件和退出代码。
• 对于 API 和 SDK，收集请求、响应、输出文件、日志和简短的可运行示例。
• 对于原生应用（包括 Electron 类型的应用），优先使用 Agent Browser 或 Playwright，通过应用的浏览器自动化接口（Electron CDP 或内嵌 Web 视图）驱动应用，并通过用户正常可见的行为验证验收标准。

首先进行演练验证。使用 Agent Browser 或 Playwright 完成演练验证后，创建覆盖新功能产品区域的端到端测试；这些测试是主要证据，演练产物则作为辅助证据。仅有预先存在的测试不能代替演练。

支持的目标

在以下目标中使用此技能：

1. Web 应用
2. CLI 和 TUI 应用
3. API 和 SDK
4. 原生应用（包括 Electron 类型的应用）

如果请求的目标不在此列表中，请询问是否继续制定尽力而为的证据计划。

硬性要求

1. 首先锁定范围

   • 以 UAT Scope: <ticket/PR/branch scope only> 开始。
   • 如果范围不明确，请检查分支差异、PR、工单，或询问用户。

2. 先收集证据，再给出建议

   • 不得仅根据摘要、静态代码审查或通过的测试建议合并。
   • 实际操作变更涉及的功能，并保存产物。

3. UI 变更优先提供视频可见证据

   • 对于 Web、TUI 和原生应用的工作，在可行时录制视频，尤其是变更会影响交互、布局、过渡效果、状态变化或错误处理时。
   • 同时在有代表性的检查点截图，方便审阅者检查静态状态。
   • 如果无法录制视频，请说明跳过的原因。

4. 必须提供手动运行说明

   • 始终提供人类可自行执行的步骤。
   • 对于 UI 工作，主要说明必须使用产品用户的正常操作。
   • 对于 CLI、TUI、API 或 SDK 工作，提供可复制粘贴的命令或代码片段，并说明预期结果。

5. 未经明确的人工验收，不得给出 GO 判定

   • 在用户确认之前，使用 Recommendation: Pending user sign-off。
   • 只有在用户明确接受后，才可使用 GO 或 GO with follow-ups。

6. 不得单方面宣称验收已完成

   • 收集证据是为了支持验收。
   • 验收由人类作出。

7. 对抗性证据审查

   • 有子 Agent 时，至少请一位对抗性审查者，将收集到的证据与规范、验收标准、需求、PR 描述或工单进行对比。
   • 审查者必须对每项标准给出 Pass 或 Fail，并引用支持其判断的产物路径或日志行。
   • 如果没有可用的子 Agent，请在正文中执行相同审查，并标注为 Inline adversarial review。

工具选择

为目标加载并使用最合适的技能或 CLI。对于 UI 目标，优先选择 Agent Browser 或 Playwright。如果所需技能不可用，请使用以下命令安装：

npx skills add vercel-labs/agent-browser --skill agent-browser -y
npx skills add microsoft/playwright-cli --skill playwright-cli -y

然后验证所选技能所需的底层 CLI。

目标	首选工具	要收集的证据
Web 应用	agent-browser（首选）；当仓库已使用 Playwright、需要跟踪记录，或 agent-browser 无法完成流程时使用 playwright；只有在已打开的 Chrome 页面且获得用户批准时才使用 chrome-cdp	视频、屏幕截图、DOM/无障碍快照、控制台/网络记录、端到端测试运行结果
CLI 应用	Shell 命令、script、生成的输出文件；有助于直观展示时，通过 script、VHS 或 asciinema 录制终端视频/GIF	终端记录、退出代码、输出文件、JSON、交互流程的屏幕截图/视频
TUI 应用	通过 script、VHS 或 asciinema 录制终端；尽可能保存终端记录	视频/GIF、屏幕截图、记录、配置/输出文件
API	curl、HTTP 客户端、仓库脚本、日志	请求/响应 JSON、状态代码、日志、已保存的负载
SDK	使用目标语言编写的最小可运行示例；仓库示例/测试仅作补充	源代码片段、命令输出、生成的文件、日志
原生应用，包括 Electron 类型应用	当应用支持浏览器自动化或 CDP 时，优先使用 agent-browser 进行 Electron/CDP 自动化；当仓库已使用 Playwright 或 agent-browser 无法完成流程时，使用 playwright 进行 Electron 自动化；对于没有 Web 视图的纯原生应用，使用操作系统屏幕截图和无障碍快照	窗口视频、屏幕截图、无障碍/DOM 快照、日志、端到端测试运行结果

安装检查：

command -v agent-browser || true
command -v playwright || true

不要安装与目标无关的工具。

证据工作区

适用时使用随附的辅助工具。请以此技能目录为基准解析脚本路径。

# Create the evidence directory and starter manifest.
node <skill-dir>/scripts/init-evidence.mjs --target electron --scope "validated behavior"

# Run commands while saving logs, exit codes, and manifest entries.
node <skill-dir>/scripts/run-capture-command.mjs --evidence <dir> --name focused-vitest -- pnpm test

# Capture a CDP-accessible web/Electron page when agent-browser screenshots fail.
node <skill-dir>/scripts/cdp-capture-page.mjs --evidence <dir> --cdp http://127.0.0.1:9222 --title "Kata Desktop" --screenshot screenshots/start.png --text logs/start-text.txt

# Generate and check final artifacts before responding.
node <skill-dir>/scripts/write-report.mjs --evidence <dir>
node <skill-dir>/scripts/verify-evidence.mjs --evidence <dir>

辅助工具不能替代判断。它们可以避免常见的证据问题：缺少退出代码、报告为空、evidence.json 无效、缺少 UI 屏幕截图/视频，以及命令输出未保存。

将生成的证据写入仓库本地文件夹：

uat-evidence/<target>-<YYYYMMDD-HHMMSS>/

按需创建产物：

evidence.json          # machine-readable manifest
evidence.md            # concise human report
screenshots/           # PNG/JPG checkpoints
recordings/            # MP4/GIF terminal or UI recordings
responses/             # JSON/API/SDK outputs
logs/                  # command logs, server logs, console excerpts
outputs/               # generated files from the feature
tests/                 # end-to-end tests covering the new feature product area

保持证据路径稳定，并在最终答复中列出。如果 uat-evidence/ 未被 git 忽略，请说明提交前应将其加入忽略规则，除非用户明确要求提交这些产物。

最精简的 evidence.json 应包含：

{
  "scope": "validated behavior",
  "target": "web|cli|tui|api|sdk|native|electron",
  "timestamp": "ISO-8601",
  "git_commit": "short sha",
  "artifacts": [
    {"type": "video|screenshot|json|log|output", "path": "relative/path", "description": "what it proves"}
  ],
  "commands": [
    {"command": "command run", "exit_code": 0, "output_path": "logs/example.log"}
  ],
  "slices": [
    {"name": "slice name", "result": "Pass|Fail", "evidence": ["relative/path"]}
  ]
}

工作流

1. 确定范围、目标和验收项

• 按需检查分支差异、PR 描述、工单、README、package 脚本和应用入口。
• 声明 UAT Scope: ...。
• 声明 Target: web | cli | tui | api | sdk | native | electron | mixed。
• 将范围拆分为 2 到 5 个验收项。
• 为每个验收项定义明确的通过/失败标准。

2. 准备应用或服务

• 启动演练所需的开发服务器、服务、CLI、TUI、API、SDK 夹具或原生/Electron 类型应用。
• 优先使用真实的本地行为，而非模拟。
• 对于 Web 和原生/Electron 类型目标，启动前检查端口和现有进程。在 logs/ 中记录任何清理操作。
• 产品冒烟测试流程使用用户常用的产品命令。如果需要 CDP、跟踪记录或确定性屏幕截图，请另行运行一条经过插桩的流程，并标明这是插桩流程。
• 选择空闲的调试端口，不要默认使用 9222；如果端口已被占用，保存监听进程证据并选择其他端口。
• 如果凭据、服务、硬件或权限导致无法提供证明，请记录阻碍因素并提供最接近的可复现方案。不要将受阻的验收项标记为通过。

3. 执行功能路径

使用对应的操作指南：

• Web 应用 UI 流程：references/web-playbook.md
• Native/Electron 类型的 UI 流程：references/native-electron-playbook.md
• CLI、TUI、API 和 SDK：references/cli-api-sdk-playbook.md

验证 Native/Electron 类型应用窗口时，优先使用 Agent Browser（Electron CDP）或 Playwright，以确保证据反映用户实际看到的应用界面。

对于混合工作，先运行面向用户的路径，再提供与相同结果相关的技术验证。

4. 为产品功能区域创建端到端测试

使用 Agent Browser 或 Playwright 完成演练验证后，创建覆盖新功能产品区域的端到端测试。这些测试是主要验收证据。

• 实际可行时，使用与演练相同的工具：针对 Web 和 Electron 目标使用 Playwright，或者使用仓库中现有的 e2e 框架（如果已有）。
• 将测试放在 uat-evidence/<target>-<timestamp>/tests/ 下；如果项目惯例要求，则放在仓库的 e2e 目录中，并在 evidence.md 中记录所选路径。
• 每个验收项至少对应一个 e2e 测试，用于验证用户可见的流程，而不只是单元级断言。
• 运行测试并将运行输出（每项的通过/失败情况、退出代码，以及可用时的 trace 或 HTML 报告）保存在 logs/ 或 tests/ 下。
• 演练用于证明路径；测试则将其固化为主要证据。未经前置演练，不得仅凭测试接受某项验收。

5. 收集持久证据

• 将产物保存在 uat-evidence/<target>-<timestamp>/ 下。
• 实际可行时，为 Web、Native/Electron 类型和 TUI 捕获视频。
• 在开始时、关键状态变化时以及最终成功状态时捕获屏幕截图。
• 使用 tee、script 或 scripts/run-capture-command.mjs 捕获命令输出；始终保存退出代码。
• 保存 API/SDK JSON 响应和生成的输出文件。
• 将端到端测试运行输出（每项的通过/失败情况、退出代码，以及 trace 或 HTML 报告）与演练产物一起保存为主要证据。
• 对于 Bug 修复 UAT，捕获旧问题已不存在的反向证据：在日志中搜索旧错误字符串，在活动源码/文档中搜索已删除的标志或过时命令，并保存零匹配结果。
• 对失败的检查进行分类。如果分支中有文件或行为发生变化，则将该验收项视为失败。如果问题不在分支差异范围内，则将其报告为无关的验证失败，并提供文件/错误证据。
• 编写 evidence.json 和 evidence.md，然后在回复前运行 scripts/verify-evidence.mjs。

6. 进行对抗性证据审查

• 如有可用的对抗性审查子 Agent，请提供规范、验收标准、需求、PR 描述或工单以及保存的产物。
• 请审查者对每项标准判定 Pass 或 Fail，并引用确切的证据路径。
• 对于受影响的标准，缺失、含糊或无法访问的产物均视为失败。
• 如果审查者指出缺口，请收集更多证据，或在报告前将该验收项标记为失败。

7. 报告结果

按以下顺序报告：

1. UAT Scope: ...
2. Target: ...
3. Slice-by-slice result
4. Evidence
5. End-to-end Tests
6. Adversarial Review
7. Manual Run Instructions
8. Recommendation: Pending user sign-off
9. Please reply: accept / reject

报告应简洁。提供产物路径链接，并说明每个产物能证明什么。

输出约定

每次 UAT 响应都必须包含以下部分。如果演练使用了 Agent Browser 或 Playwright（适用于 Web 和原生/Electron 类型目标），则还要包含 End-to-end Tests 部分。

UAT Scope: <scope>
Target: <web|cli|tui|api|sdk|native|electron|mixed>

Slice-by-slice result:
- Pass/Fail: <slice> - <one-line evidence summary>

Evidence:
- <artifact path> - <what it proves>

End-to-end Tests:
- <test path> - <slice it covers> - Pass/Fail (run: <log/report path>)

Adversarial Review:
- Pass/Fail: <criterion> - <artifact-backed reason>

Manual Run Instructions:
1. <human step or command>
   Expected: <visible result or output>

Recommendation: Pending user sign-off
Please reply: accept / reject

对于 UI 目标，手动操作说明必须从运行中的应用里的常规用户操作开始。自动化命令或测试框架只能放在明确标注为 Fallback (Engineering Only) 的部分。

对于 CLI、TUI、API 和 SDK 目标，手动操作说明可以使用命令或代码片段，但必须包含预期输出和所需的环境变量。

工单更新指南

如果已知工单或 PR，请提供或执行状态更新，其中包括：

• 已验证的范围
• 使用的目标和工具
• 各切片的通过/失败摘要
• 证据路径或链接
• 手动运行说明
• 当前建议

在用户明确接受前，将更新标记为 Pending user sign-off。用户明确接受后，如果项目工作流有要求，则记录最终判定。

响应前自检

响应前，请确认：

• 已说明范围。
• 已说明目标。
• 每个切片都有通过/失败状态。
• 证据文件已存在，或明确标注了阻碍因素。
• evidence.json 有效，且 evidence.md 非空。
• UI 证据包含视频和截图（如可行），或说明了跳过视频的原因。
• UI 截图/视频文件存在且可读取。
• 原生/Electron 类型应用的验证使用了 Agent Browser（Electron CDP）或 Playwright，或说明了使用其他工具的原因。
• 已创建并运行涵盖新功能所属产品领域的端到端测试，并将各切片的通过/失败状态和运行输出保存为主要证据（适用于 UI 目标）。
• 对抗性审查已根据证据检查每项标准，并给出通过/失败判定。
• 命令日志包含退出代码。
• 验证修复时，已保存旧 Bug 的负面证据。
• UAT 启动的开发服务器、原生/Electron 类型应用或后台进程均已清理，或已明确说明将其留给用户继续运行。
• 已包含手动运行说明。
• 除非用户已接受，否则建议仍为 Pending user sign-off。

常见错误

• 只运行已有测试，没有进行演练，也没有新建涵盖该产品领域的端到端测试。
• 只报告代码摘要，没有提供证据文件。
• UI 工作未提供视频或截图，也未说明原因。
• 将 Playwright 或测试命令作为 UI 的主要手动操作路径。
• 忘记提供 TUI 视觉证据。
• 遗漏 API 请求和响应文件。
• 用户尚未接受就宣布 GO。
• 没有针对目标选择最合适的工具，而是把所有工具都安装一遍。