SDD Plan Human Verify — 生成验收清单
Overview
读取已完成的（或部分完成的）spec-plan.md 及其关联的 spec-design.md，提取所有验证项，生成详细的验收清单，其中每个项目预分解为 [A]（自动化）和 [H]（人工）子步骤。
AI 将在验收期间自主执行 [A] 步骤；[H] 步骤是精确的微指令，人类只需回答是/否。
启动时声明： "我正在使用 sdd-plan-human-verify 技能来生成验收清单。"
关键概念
- 工作区 (Workspace)： 通过
.sdd-workspace 配置文件中 workspace_path 指定的根目录
- Spec 目录： 所有 SDD 文档存储在
{workspace}/spec/ 下
Step 0: 读取工作区配置
在任何操作之前，必须读取工作区配置：
- 检查当前 OpenClaw workspace 中是否存在
.sdd-workspace
- 如果存在，读取
workspace_path 作为工作区根目录 {workspace}
- 如果不存在，显示错误："请先运行
/sdd-global-init 初始化工作区。" 并停止
验证工作区目录存在，如果不存在提示用户重新初始化。
Step 1: 模型检查
检查当前模型是否为 Opus。如果不是 Opus，显示建议：
⚠️ 当前模型不是 Opus，建议切换到 Opus 以获得最佳验收清单质量。输入 /model 切换模型。
这是非阻塞的 — 无论如何都继续。
Step 1: 计划选择
如果提供了路径参数
- 直接使用它作为计划文件路径
- 读取文件并继续 Step 2
如果没有提供路径参数
- 扫描
{workspace}/spec/ 中所有匹配 feature_*/spec-plan.md 的文件
- 按目录名排序（feature 目录包含日期，所以字母排序 = 时间顺序）
- 通过
AskUserQuestion 展示最新的 3 个计划：
- 每个选项显示目录名和计划标题（第一个标题）
- 用户也可以通过 "Other" 输入自定义路径
- 所有问题文本和选项用中文
- 读取选中的 spec-plan.md
Step 2: 源分析
从同一目录读取两个文件：
2.1 从 spec-plan.md — 收集所有验证项
- 从所有 Task 的
**检查步骤:** 部分收集所有项目
- 从
**End-to-end verification:** 部分收集所有项目
- 对于每个项目，记录：Task 编号、步骤描述、关联的命令和预期结果
- 不要按任何标签过滤 — 收集所有内容
2.2 从 spec-design.md — 提取可验证行为
- 收集验收标准、功能需求和任何可验证的行为描述
- 包括 UI 行为、API 契约、错误处理、边界情况
- 不要用关键词白名单过滤 — 包含所有可验证的项目
2.3 交叉引用去重
合并计划项目和设计文档项目；移除重复项（相同的验证意图 = 重复）。
2.4 将每个项目分解为 [A]/[H] 子步骤
对于每个验收项，确定每个操作步骤是否可以自动化：
- 可自动化 → 标记为
[A]，包含可执行命令和预期结果
- 需要人工 → 标记为
[H]，写为精确的微指令（具体 URL + 具体观察点 + 是/否判断）
分解原则：
- 默认为
[A]。只有当步骤必须依赖人工视觉/物理交互时才标记为 [H]
- 单个验收项可以是：纯
[A]（完全自动化）、纯 [H]（完全人工）或混合 [A] + [H]
[H] 步骤必须是精确的微指令：告诉人类具体要看哪里和检查什么；人类只需回答是/否
何时使用 [H]：
- 视觉/UI 检查 — 布局、样式、颜色、动画、响应式
- 浏览器交互 — 点击真实用户流程、表单交互
- 浏览器 DevTools — Network 面板、Application/Storage 面板、Console 面板
- 主观体验 — 感知的加载速度、动画流畅度
- 跨浏览器/设备 — 不同浏览器、移动端、响应式
- 可访问性 — 屏幕阅读器、键盘导航
何时使用 [A]：
- HTTP 请求 — curl、wget、任何 API 调用
- Shell 命令 — grep、find、diff、cat、文件存在性检查
- 构建/编译 — npm run build、tsc、cargo test
- JSON/输出比较 — 检查响应结构、状态码
- 进程/端口检查 — ss、lsof、ps
边界情况
Step 3: 生成验收清单
在 spec-plan.md 所在的同一目录生成 spec-human-verify.md 的内容。
详细程度要求
- 为零项目知识的人撰写
- 每个
[A] 步骤包含：反引号中的精确命令和 → 期望: 后的预期结果
- 每个
[H] 步骤包含：精确 URL、精确观察点、是/否问题格式
- 包括从零开始的环境设置（服务启动命令、浏览器说明）
- 包括每个项目的故障排查指南
分组：按业务场景
按业务场景分组验证项（例如"用户登录流程"、"管理员操作"、"数据展示"）。
每个场景是一个 ### 场景 N 部分。
准备项标签定义
供 sdd-start-human-verify 用于自主执行。每个准备项必须有以下标签之一：
[AUTO] — 一次性命令，直接执行并检查退出码。格式：- [ ] [AUTO] description: \command``[AUTO/SERVICE] — 长运行服务，后台启动 + 端口检测 + 就绪等待。格式必须包含 (port: NNNN)：- [ ] [AUTO/SERVICE] description: \command` (port: NNNN)`[MANUAL] — 需要人工操作，无法表达为 shell 命令。仅用于：需要目视观察 UI、需要操作物理设备或外部硬件、需要操作第三方 GUI 系统、需要人类主观判断。
分类原则：默认为 [AUTO]。如果准备步骤可以通过 shell 命令验证或执行，必须是 [AUTO]，不是 [MANUAL]。
以下类别始终是 [AUTO]，永不是 [MANUAL]：
- 文件/配置检查 — 文件是否存在、配置项是否包含某值、环境变量是否设置 →
grep, test -f, env | grep
- 版本/依赖检查 — 运行时版本、包是否安装、工具是否可用 →
node -v, npm ls, which xxx
- 编译/构建 — 任何 build、compile、transpile 命令 →
npm run build, tsc, make
- 安装依赖 —
npm install, pip install, apt-get install
- 数据库/迁移 — schema 迁移、seed 数据 →
npx prisma migrate, python manage.py migrate
[MANUAL] 仅用于以下场景：
- 需要在浏览器中目视观察 UI
- 需要操作物理设备或外部硬件
- 需要在第三方 GUI 系统中操作（如在云控制台创建资源）
- 需要人类主观判断（如审查设计稿）
模板格式
使用以下模板 — 注意项目标题使用 #### - [ ] N.M 格式（h4 + 复选框）：
# [功能名称] 人工验收清单
**生成时间:** YYYY-MM-DD HH:mm
**关联计划:** [spec-plan.md 相对路径]
**关联设计:** [spec-design.md 相对路径]
---
## 验收前准备
### 环境要求
- [ ] [AUTO] 检查 Node.js >= 18: `node -v`
- [ ] [AUTO] 编译后端: `cd key-portal/server && npx tsc`
- [ ] [AUTO/SERVICE] 启动后端服务: `cd key-portal/server && NODE_ENV=development node dist/index.js` (port: 3001)
- [ ] [AUTO/SERVICE] 启动前端开发服务器: `cd key-portal/web && npm run dev` (port: 5173)
- [ ] [AUTO] 检查 .env 包含必要变量: `grep -q 'NODE_ENV=development' .env && grep -q 'ADMIN_MIPS=' .env`
- [ ] [MANUAL] [手动准备项说明，无可执行命令]
### 测试数据准备
- [ ] [具体测试数据，如: 准备测试账号 testuser / password123]
---
## 验收项目
### 场景 1：[场景名称]
#### - [ ] 1.1 验收项名称
- **来源:** Task N 检查步骤 / spec-design.md
- **操作步骤:**
1. [A] `curl -s http://localhost:3001/api/auth/me -H 'X-Dev-UserCode: chenwx57'` → 期望: 返回 JSON 含 userCode: "chenwx57"
2. [A] `curl -s http://localhost:3001/api/tokens -H 'X-Dev-UserCode: chenwx57'` → 期望: HTTP 200
3. [H] 打开 http://localhost:5173，查看右上角是否显示 "chenwx57" → 是/否
- **异常排查:**
- 如果 [具体异常]: 检查 [排查方向和命令]
#### - [ ] 1.2 验收项名称
- **来源:** ...
- **操作步骤:**
1. [A] `command` → 期望: ...
2. [H] 微指令 → 是/否
- **异常排查:**
- ...
### 场景 2：[场景名称]
#### - [ ] 2.1 验收项名称
...
---
## 验收结果汇总
| 场景 | 序号 | 验收项 | 自动步骤 | 人工步骤 | 结果 | 备注 |
|------|------|--------|----------|----------|------|------|
| 场景 1 | 1.1 | [名称] | N 个 | M 个 | ⬜ | |
**验收结论:** ⬜ 全部通过 / ⬜ 存在问题
与旧模板的关键格式差异：
- 移除
**类型:** 字段（不再分类为 UI 检查/浏览器调试等）
- 移除 独立的
**预期结果:** 块（预期结果与每个步骤内联，在 → 期望: 后）
[A] 步骤：反引号命令 + → 期望: 描述预期输出[H] 步骤：精确微指令 + → 是/否- 汇总表包含自动/人工步骤数的单独列
Step 4: 确认流程
不要直接写入文件。 而是先展示给用户确认：
4.1 显示汇总表
## 验收清单预览
| 统计项 | 数量 |
|--------|------|
| 场景数 | N |
| 验收项数 | M |
| 自动步骤 [A] | X 个 |
| 人工步骤 [H] | Y 个 |
| 纯自动项（无需人类） | Z 个 |
4.2 显示项目列表表
| 场景 | 序号 | 验收项 | [A] 步骤 | [H] 步骤 | 来源 |
|------|------|--------|----------|----------|------|
| 场景 1 | 1.1 | [名称] | 2 | 1 | Task 3 |
| ... | ... | ... | ... | ... | ... |
4.3 询问确认
使用 AskUserQuestion 提供两个选项：
- 「确认写入」 — 写入文件
- 「需要修改」 — 收集反馈并重新生成
4.4 处理 "需要修改"
如果用户选择 "需要修改"：
- 通过 "Other" 文本输入或后续问题收集反馈
- 重新生成包含反馈的清单
- 重新显示汇总和项目列表
- 再次询问确认（循环直到确认或用户取消）
4.5 处理现有文件
写入前，检查目标目录是否已存在 spec-human-verify.md：
- 如果存在 →
AskUserQuestion: 「覆盖现有文件」/「取消」
- 如果用户取消 → 不写入，停止
4.6 写入文件
确认后，将 spec-human-verify.md 写入与 spec-plan.md 相同的目录。
Step 5: 生成后
向用户显示汇总：
## 验收清单已生成
- 文件: [path to spec-human-verify.md]
- 场景数: N
- 验收项数量: M 项
- 自动步骤 [A]: X 个
- 人工步骤 [H]: Y 个
- 纯自动项（无需人类参与）: Z 个
- 💡 **建议下一步：** 运行 `/sdd-start-human-verify` 开始执行验收
规则
- 无外部技能依赖 — 完全独立
- 无 git 操作 — 不进行 branch、commit、merge、push
- 中文输出 — 验收清单和所有用户-facing 信息用中文
- 英文指令 — SKILL.md 内部逻辑用英文
- 极度详细 — 每个步骤必须可以在没有项目先验知识的情况下执行
- 完整覆盖 — 从 spec-plan.md 和 spec-design.md 收集所有验证项，不仅是 [HUMAN] 标记的
- [A]/[H] 分解 — 每个验收项必须有预标记为 [A] 或 [H] 的子步骤
- 默认为 [A] — 仅在真正需要人工视觉/物理交互时使用 [H]
- 精确的 [H] 微指令 — 告诉人类具体要看哪里、要观察什么、只需回答是/否
- 复选框格式 — 项目标题必须使用
#### - [ ] N.M 格式以兼容 sdd-start-human-verify
- 按场景分组 — 项目必须按业务场景分组，而非平铺
- 写入前确认 — 永远不要在没有用户确认的情况下写入文件
