| name | acceptance-checklist |
| description | Generates a step-by-step user acceptance test (UAT) checklist that a real human executes by hand, with expected results and failure playbooks at every checkpoint. Covers CLI + Web UI scenarios, supports cold-start injection, and is checkbox-driven so the operator can mark progress. Trigger words: "/uat", "验收清单", "真人验收", "acceptance test", "让我验收". |
真人验收清单
版本：v1.0.0 | 状态：已落地 | 触发：/uat、"验收清单"、"真人验收"、"acceptance test"、"让我验收"
给即将亲手操作系统的真人用的结构化打勾清单。不是代码审查，不是 curl 冒烟——是"按这张表操作，每一步都告诉我应该看到什么、看不到时按哪个键排错"。
目录
核心理念
四个不妥协：
- 真人视角，不是代码视角：每步动作必须是"敲这条命令/点这个按钮"，不是"调用这个函数"
- 可打勾可回溯：每个 checkpoint 有
[ ] 符号，跑完一项打一个 [x] 通过 / [!] 失败
- 失败不留悬案：任何失败都必须有对应的排查路径（failurePlaybook），不能光说"失败了"
- 禁止空白等待：长操作必须有进度反馈（参照
CLAUDE.md 规则 #6），不是让用户盯着黑屏猜
灵感来源：借鉴 gsd-verify-work（开源 UAT skill）的四个核心模式——单步打卡 / 关键词分级 / 冷启动注入 / 降级 fallback——本地化为中文 + 对接本项目的 CLI 集群命令 + Web Dashboard 双场景。
何时用 / 何时别用
该用
- 一项功能代码已完成、单元测试通过，准备交给真人跑一遍
- 涉及用户操作路径：CLI 命令序列 / Dashboard 页面 / 桌面端交互
- 新增 Agent / 新增页面 / 新增配置流程 / 新增集群能力
- PR 合并前的最终确认（比
/handoff 更细粒度，要真动手跑）
别用
- 纯库函数重构（没有真人入口）→ 用
/verify 做代码审查
- API 契约验证（没有 UI）→ 用
/smoke 做 curl 链式冒烟
- 纯文档变更 → 不需要 UAT
和其他 skill 的关系
| 维度 | /verify (human-verify) | /smoke (smoke-test) | /handoff (task-handoff-checklist) | /uat (acceptance-checklist) |
|---|
| 视角 | 代码 reviewer | 开发者 | 移交文档作者 | 真人用户 |
| 产出 | 问题清单 | curl 脚本 | 交接报告 | 打勾清单 + 排错手册 |
| 何时用 | 写完代码 | 写完 API | 提交 PR 前 | 真人动手前 |
| 自动/手动 | 自动（AI 做） | 自动 | 自动 | 半自动：AI 生成清单，真人执行 |
执行流程
UAT 生成进度：
- [ ] Phase 1: 场景收集（问 3 个关键问题）
- [ ] Phase 2: 冷启动注入判定（涉及服务/集群/容器时强制加）
- [ ] Phase 3: 分阶段清单生成（0-准备 → 1-执行 → 2-验证 → 3-回归 → 4-回滚）
- [ ] Phase 4: 失败处置路径逐项填写
- [ ] Phase 5: 输出 Markdown 打勾表 + 总体验收汇总
- [ ] Phase 6: 串联下游 skill 建议
Phase 1: 场景收集（必须先问）
调用此 skill 时必须先收集以下 3 条信息（如果用户没说齐，用 AskUserQuestion 追问，不猜）：
| 必填项 | 示例 |
|---|
| 功能描述：这次验收的是什么 | "CDS 集群引导：一条命令让 B 加入 A" |
| 入口：真人从哪开始操作 | CLI：./exec_cds.sh connect / Web：https://x.miduo.org/review |
| 场景类型：CLI / Web UI / 混合 | 混合（先 CLI 建集群，再 Web 验证容量） |
可选项（有会更好，没有 AI 自己推断）：
- 预期耗时估算
- 依赖的外部服务（数据库/外部 API/LLM 模型池）
- 已知风险点（从
/risk 或 /verify 继承）
Phase 2: 冷启动注入判定
强制触发条件：场景描述命中以下任一关键词时，必须在 Phase 0 之前插入"冷启动自检"：
| 触发词 | 冷启动动作 |
|---|
| 集群 / cluster / 节点 | systemctl status / 进程存活检查 / 端口占用 |
| 服务 / 容器 / daemon | docker ps / 相关容器健康检查 |
| 部署 / deploy | 检查构建产物、最新提交哈希 |
| 数据库 / db / mongo / redis | 连接探活 |
| LLM / 模型 | curl /api/llm-health 或等效探活端点 |
原因：真人经常在"上次失败的残留状态"上测试，测出来的是假阳性。冷启动是 GSD 社区总结的"最容易省略、最致命"的一步。
Phase 3: 分阶段清单生成
每个 UAT 文档必须包含以下 5 个 Phase（某阶段为空时明确写"本场景无此阶段"）：
| Phase | 含义 | 典型内容 |
|---|
| Phase 0: 前置检查 | 跑测试之前必须满足的环境 | 版本、依赖、网络、时间同步 |
| Phase 1: 核心执行 | 真正要测的新功能主路径 | 敲命令 / 点按钮 / 等结果 |
| Phase 2: 验证效果 | 检查核心执行是否产生了期望副作用 | 数据库落盘 / UI 更新 / 日志出现 |
| Phase 3: 回归检查 | 确认老功能没被新改动搞坏 | 既有页面还能访问 / 老 API 还能调 |
| Phase 4: 回滚演练 | 撤销操作也要能工作 | disconnect / delete / undo |
每个 Phase 内部的行项必须遵循 UAT 文档模板 的表格结构。
Phase 4: 失败处置路径（failurePlaybook）
每个 checkpoint 必须附加一个 failurePlaybook 字段，即"预期结果没出现时，按这个手册排查"。格式：
**如果 X.Y 失败**：
- 常见原因 1 → 诊断命令 / 修复步骤
- 常见原因 2 → 诊断命令 / 修复步骤
- 仍然不行 → 贴这几条日志给开发者
留一条"仍然不行"兜底的好处：真人遇到非预期情况知道去哪求助，不会卡死。
Phase 5: 输出格式
见下一节 UAT 文档模板。
Phase 6: 串联下游 skill
UAT 完成后，根据结果提示下一步 skill：
- 全绿通过 → 建议
/handoff 生成交接文档
- 部分失败 → 建议
/verify 复查代码 或 /risk 重评风险
- 回归检查发现老功能坏了 → 建议
/trace 追数据流
- 反复出现冷启动相关问题 → 建议把场景写进
doc/guide.* 长期沉淀
UAT 文档模板
文件名：acceptance-{feature-slug}-{YYYYMMDD}.md（不写盘除非用户确认，默认只打印到对话）
顶部元信息：
# {功能名称} 验收清单
> **验收目标**：{一句话说明}
> **分支**：{branch name}
> **入口**：{CLI 命令 | Web URL}
> **场景类型**：CLI / Web / 混合
> **估算总时长**：{N} 分钟
> **打勾方式**：每个 checkpoint 有 `[ ]`，跑完一项写 `[x]` 通过 / `[!]` 失败 / `[-]` 跳过
每个 Phase 的表格结构：
## Phase N: {阶段名}（{预计耗时}）
> {可选的一句话说明：这个阶段在验什么}
| # | 操作 | 预期结果 | 状态 |
|---|---|---|---|
| N.1 | {具体命令或点击动作} | {看到什么 stdout / UI 元素 / 状态码} | `[ ]` |
| N.2 | ... | ... | `[ ]` |
**如果 N.1 失败**：
- 原因 A → 诊断命令
- 原因 B → 排查步骤
- 都不行 → 贴 `./exec_cds.sh logs | tail -30` 给我
**验收点 N**：{这个 Phase 的核心价值判断，一句话说清楚跑这组 checkpoint 是在验什么关键事实}
文末总结：
## 整体验收汇总
| 验收点 | Phase | 你的结论（通过/失败/跳过）|
|---|---|---|
| {point 1} | 1 | |
| {point 2} | 2 | |
| ... | | |
**任一失败**：按对应 Phase 的"失败处置"排查；还不行就贴日志
**全部通过**：功能正式验收通过 → 建议下一步跑 `/handoff`
双通道支持：CLI / Web UI
UAT 往往是混合场景，清单必须对两种通道都有标准化的表述：
CLI 通道
| # | 操作 | 预期结果 | 状态 |
|---|---|---|---|
| 1.1 | `./exec_cds.sh connect https://... <token>` | 看到 `[OK] 已加入集群` | `[ ]` |
预期结果的三要素（任选其一或组合）：
- stdout 关键字（
grep -q "..." logs）
- exit code（
echo $? = 0）
- 副作用文件（
.cds.env 新增行 / state.json 字段变化）
Web UI 通道
| # | 操作 | 预期结果 | 状态 |
|---|---|---|---|
| 2.3 | 浏览器打开 `https://xxx/review` | 看到标题"PRD 评论" + 列表至少 1 条 | `[ ]` |
| 2.4 | 点击第一条评论 | 弹出侧边栏，显示作者头像、评论内容、时间 | `[ ]` |
| 2.5 | 按 F12 打开 DevTools → Network | 有一条 `GET /api/reviews` 返回 200 | `[ ]` |
Web 通道的强制项（参照 .claude/rules/e2e-verification.md）：
- 不能只调 API，必须真的开浏览器看渲染
- 必须 F12 检查 Network（API 返回 200 ≠ UI 渲染正确）
- 新旧数据都要测（fallback 路径）
- 如有设计稿，对照逐项打勾
混合场景示范
Phase 1 (CLI)：启动服务
Phase 2 (Web)：Dashboard 验证 UI 同步
Phase 3 (CLI)：再次操作
Phase 4 (Web)：浏览器看到状态变化
交互模式：逐步打勾
半自动执行（默认，推荐）：
- AI 打印完整清单给用户（顶部总览 + 所有 Phase）
- 用户自己按顺序操作，每完成一个 Phase 在对话里回复：
pass 1.1-1.5 → 标记 1.1-1.5 为通过fail 2.3 + 错误信息 → AI 查 failurePlaybook 给建议skip 4.* → Phase 4 全部跳过
- AI 维护进度面板，每收到一次反馈就更新汇总表
自动监督模式（可选，需用户明确请求）：
如果用户说"你帮我一步一步执行"：
- AI 一次只打印一步
- 用户执行完回
y（通过）/ n 错误信息（失败）
- 失败时 AI 给排查建议，用户尝试修复后回
retry
- 禁止 AI 一次性 dump 全部清单（会让用户跟丢）
关键字自动分级（借鉴 gsd-verify-work）：
| 用户回复包含 | 自动分级 |
|---|
| "crash" / "炸了" / "502" / "timeout" | blocker（阻断） |
| "慢" / "slow" / "等了很久" | minor（次要） |
| "样式不对" / "布局乱了" | minor（UI polish） |
| "不符合预期" / "不对" | blocker（阻断） |
| "看到了" / "对的" / "通过" | pass（通过） |
失败处置手册
每个 failurePlaybook 必须同时覆盖三类失败：
- 预期失败：文档里列的常见错误 → 给确定的修复命令
- 环境失败：依赖没装 / 端口占用 / 时间不同步 → 给探活命令
- 未知失败：日志 + 贴给开发者 → 给明确的日志抓取命令
绝不能写：
- "失败就重试" （空话）
- "看日志" （不告诉看哪里）
- "问一下管理员" （不告诉问什么）
必须写：
- "日志第 X 行会有
executor registered 字样，没有的话贴 ./exec_cds.sh logs | tail -50 给我"
上下游技能
/verify → 代码审查通过
↓
/smoke → API 契约冒烟通过
↓
/cds-deploy → 部署到预览环境
↓
→ /uat ← 本技能（真人打勾验收）
↓
/handoff → 生成交接文档
↓
PR
不是替代而是组合
/smoke 告诉你 API 接口是技术正确的/uat 告诉你从真人体验看是业务正确的- 两者都过 = 可以合 PR
/smoke 过但 /uat 没过 = API 对但用户用不上/uat 过但 /smoke 没过 = 偶发的测试未覆盖路径
参考资料
合规要求（项目特定）
- 中文输出：所有 checkpoint 描述和错误提示必须中文
- 不写盘默认：生成的 UAT 文档默认只打印到对话。仅当用户明确说"保存"时才 Write 到
/tmp/ 或 doc/report.*
- 禁止创建
doc/ 下的永久文档：UAT 是一次性产物，不要污染 doc/ 目录结构
- 预览地址自动化：Web 场景跑
python3 .claude/skills/cds/cli/cdscli.py --human preview-url 拿 URL，禁止任何形式的手拼。SSOT: cds/src/services/preview-slug.ts:computePreviewSlug
- 参考
CLAUDE.md 规则 #9：新 Agent / 新页面交付必须同时声明【位置】和【路径】两行，UAT 清单顶部应复述这两行
