acceptance-checklist

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 冒烟——是"按这张表操作，每一步都告诉我应该看到什么、看不到时按哪个键排错"。

目录

• 核心理念
• 何时用 / 何时别用
• 执行流程
• UAT 文档模板
• 双通道支持：CLI / Web UI
• 交互模式：逐步打勾
• 失败处置手册
• 上下游技能
• 参考资料

核心理念

四个不妥协：

1. 真人视角，不是代码视角：每步动作必须是"敲这条命令/点这个按钮"，不是"调用这个函数"
2. 可打勾可回溯：每个 checkpoint 有 [ ] 符号，跑完一项打一个 [x] 通过 / [!] 失败
3. 失败不留悬案：任何失败都必须有对应的排查路径（failurePlaybook），不能光说"失败了"
4. 禁止空白等待：长操作必须有进度反馈（参照 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)：浏览器看到状态变化

交互模式：逐步打勾

半自动执行（默认，推荐）：

1. AI 打印完整清单给用户（顶部总览 + 所有 Phase）
2. 用户自己按顺序操作，每完成一个 Phase 在对话里回复：
   • pass 1.1-1.5 → 标记 1.1-1.5 为通过
   • fail 2.3 + 错误信息 → AI 查 failurePlaybook 给建议
   • skip 4.* → Phase 4 全部跳过
3. AI 维护进度面板，每收到一次反馈就更新汇总表

自动监督模式（可选，需用户明确请求）：

如果用户说"你帮我一步一步执行"：

• AI 一次只打印一步
• 用户执行完回 y（通过）/ n 错误信息（失败）
• 失败时 AI 给排查建议，用户尝试修复后回 retry
• 禁止 AI 一次性 dump 全部清单（会让用户跟丢）

关键字自动分级（借鉴 gsd-verify-work）：

用户回复包含	自动分级
"crash" / "炸了" / "502" / "timeout"	blocker（阻断）
"慢" / "slow" / "等了很久"	minor（次要）
"样式不对" / "布局乱了"	minor（UI polish）
"不符合预期" / "不对"	blocker（阻断）
"看到了" / "对的" / "通过"	pass（通过）

失败处置手册

每个 failurePlaybook 必须同时覆盖三类失败：

1. 预期失败：文档里列的常见错误 → 给确定的修复命令
2. 环境失败：依赖没装 / 端口占用 / 时间不同步 → 给探活命令
3. 未知失败：日志 + 贴给开发者 → 给明确的日志抓取命令

绝不能写：

• "失败就重试" （空话）
• "看日志" （不告诉看哪里）
• "问一下管理员" （不告诉问什么）

必须写：

• "日志第 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 没过 = 偶发的测试未覆盖路径

参考资料

• 标准模板：reference/checklist-template.md — 空白模板复制粘贴即用
• 完整示例：reference/example-cds-cluster.md — CDS 集群引导功能的 8 Phase 填好版
• 架构灵感来源：gsd-verify-work（GSD 社区开源 skill）
• 项目规则：
  • .claude/rules/e2e-verification.md — 端到端验收强制规则
  • CLAUDE.md 规则 #6 — 禁止空白等待
  • CLAUDE.md 规则 #8 — Agent 开发"完成"标准

合规要求（项目特定）

• 中文输出：所有 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 清单顶部应复述这两行