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: 读取工作区配置

在任何操作之前，必须读取工作区配置：

1. 1. 检查当前 OpenClaw workspace 中是否存在 INLINECODE7
2. 如果存在，读取 workspace_path 作为工作区根目录 INLINECODE9
3. 如果不存在，显示错误："请先运行 /sdd-global-init 初始化工作区。" 并停止

验证工作区目录存在，如果不存在提示用户重新初始化。

Step 1: 模型检查

检查当前模型是否为 Opus。如果不是 Opus，显示建议：

CODEBLOCK0

这是非阻塞的 — 无论如何都继续。

Step 1: 计划选择

如果提供了路径参数

• - 直接使用它作为计划文件路径
• 读取文件并继续 Step 2

如果没有提供路径参数

1. 1. 扫描 {workspace}/spec/ 中所有匹配 feature_*/spec-plan.md 的文件
2. 按目录名排序（feature 目录包含日期，所以字母排序 = 时间顺序）
3. 通过 AskUserQuestion 展示最新的 3 个计划：

1. 4. 读取选中的 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]。只有当步骤必须依赖人工视觉/物理交互时才标记为 INLINECODE19
• 单个验收项可以是：纯 [A]（完全自动化）、纯 [H]（完全人工）或混合 [A] + INLINECODE23
• INLINECODE24 步骤必须是精确的微指令：告诉人类具体要看哪里和检查什么；人类只需回答是/否

何时使用 [H]：

1. 1. 视觉/UI 检查 — 布局、样式、颜色、动画、响应式
2. 浏览器交互 — 点击真实用户流程、表单交互
3. 浏览器 DevTools — Network 面板、Application/Storage 面板、Console 面板
4. 主观体验 — 感知的加载速度、动画流畅度
5. 跨浏览器/设备 — 不同浏览器、移动端、响应式
6. 可访问性 — 屏幕阅读器、键盘导航

何时使用 [A]：

1. 1. HTTP 请求 — curl、wget、任何 API 调用
2. Shell 命令 — grep、find、diff、cat、文件存在性检查
3. 构建/编译 — npm run build、tsc、cargo test
4. JSON/输出比较 — 检查响应结构、状态码
5. 进程/端口检查 — ss、lsof、ps

边界情况

• - 所有项目都是纯 [A]（不需要 [H] 步骤）：

• - 未找到 spec-design.md：

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 显示汇总表 CODEBLOCK2 ### 4.2 显示项目列表表 CODEBLOCK3 ### 4.3 询问确认 使用 AskUserQuestion 提供两个选项： - **「确认写入」** — 写入文件 - **「需要修改」** — 收集反馈并重新生成 ### 4.4 处理 "需要修改" 如果用户选择 "需要修改"： 1. 通过 "Other" 文本输入或后续问题收集反馈 2. 重新生成包含反馈的清单 3. 重新显示汇总和项目列表 4. 再次询问确认（循环直到确认或用户取消） ### 4.5 处理现有文件 写入前，检查目标目录是否已存在 spec-human-verify.md： - 如果存在 → AskUserQuestion: 「覆盖现有文件」/「取消」 - 如果用户取消 → 不写入，停止 ### 4.6 写入文件 确认后，将 spec-human-verify.md 写入与 spec-plan.md 相同的目录。 ## Step 5: 生成后 向用户显示汇总： CODEBLOCK4 ## 规则 - **无外部技能依赖** — 完全独立 - **无 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
• 按场景分组 — 项目必须按业务场景分组，而非平铺
• 写入前确认 — 永远不要在没有用户确认的情况下写入文件