sdd-start-human-verify（SDD 启动人工验证）

SDD Start Human Verify — AI 驱动验收执行

Overview

加载 spec-human-verify.md 验收清单，以 AI 作为驱动执行。 AI 自主运行所有 [A]（自动化）子步骤，仅对 [H]（人工）子步骤调用人类，人类只需回答是/否。

启动时声明： "我正在使用 sdd-start-human-verify 技能来执行 AI 驱动验收。"

关键概念

• 工作区 (Workspace)： 通过 .sdd-workspace 配置文件中 workspace_path 指定的根目录
• Spec 目录： 所有 SDD 文档存储在 {workspace}/spec/ 下

Step 0: 读取工作区配置

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

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

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

Step 1: 模型检查

检查当前模型是否为 Opus。如果是 Opus，输出以下纯文本消息并继续（非阻塞）：

⚠️ 当前模型是 Opus，验收执行任务不需要 Opus 级别的推理能力，建议切换到更快的模型以提升执行效率。输入 /model 切换模型。

Step 1: 文件选择

如果提供了路径参数

• 直接使用它作为清单文件路径
• 读取文件并继续 Step 2

如果没有提供路径参数

1. 扫描 {workspace}/spec/ 中所有匹配 feature_*/spec-human-verify.md 的文件
2. 按修改时间排序（最新优先）
3. 通过 AskUserQuestion 展示最新的 3 个文件：

- 每个选项显示目录名和文件修改日期 - 用户也可以通过 "Other" 输入自定义路径 - 所有问题文本用中文

1. 读取选中的 spec-human-verify.md

边界情况：未找到文件

• 显示："未找到 spec-human-verify.md 文件。请先运行 /sdd-plan-human-verify 生成验收清单。"
• 停止。

Step 2: 恢复点检测

使用此正则解析文件中所有验证项标题：

^####\s+-\s+\[([ x!])\]\s+(\d+\.\d+)\s+(.+)$

匹配如下格式的行：

• #### - [ ] 1.1 验收项名称 → status: pending (space)
• #### - [x] 1.1 验收项名称 → status: passed (x)
• #### - [!] 1.1 验收项名称 → status: failed (!)

构建项目列表：索引、编号（例如 "1.1"）、名称、状态。

恢复逻辑

• 如果有些项目是 [x] 或 [!]（部分完成）：

- 统计已完成项目（通过 + 失败） - 找到第一个 [ ]（待处理）项目 - 显示："已完成 N/Total 项（通过: X, 不通过: Y），从 [number] [name] 继续。" - 跳到 Step 4 的那个项目

• 如果所有项目都是 [x] 或 [!]（完全完成）：

- 显示汇总（与 Step 5 相同）并停止 - 建议："所有验收项已完成。如需重新验收，请手动将 [x]/[!] 改回 [ ] 后重新运行。"

• 如果所有项目都是 [ ]（全新开始）：

- 显示："共 N 个验收项，开始 AI 驱动验收。" - 继续 Step 3

Step 3: 自主执行准备步骤

读取清单的 ## 验收前准备 部分。解析每个 - [ ] 行并按标签分类。 为 Step 6 清理维护一个 started_services 列表（条目：{pid, port, description}）。

3.1 [AUTO] 项目 — 一次性命令执行

1. 从行中的反引号提取命令
2. 通过 Bash 执行
3. 成功 → 显示 ✓ [description]，继续下一个项目
4. 失败 → 分析输出并尝试修复简单问题：

- .env 缺失变量 → 自动追加该变量 - 编译错误 → 显示错误，尝试修复，重新编译 - 版本不匹配 → 报告实际版本，AskUserQuestion：「继续」/「中止」

1. 修复后重试，最多 3 轮
2. 3 轮后仍然失败 → AskUserQuestion：「跳过」/「中止验收」

3.2 [AUTO/SERVICE] 项目 — 长运行服务管理

1. 从行中提取命令和端口号（正则：\(port:\s*(\d+)\)）
2. 先检查端口：运行 ss -tlnp | grep :PORT 或 lsof -i :PORT

- 端口已在使用 → 显示 ✓ [description]（端口 PORT 已在使用，复用已有服务），跳过启动 - 端口空闲 → 继续启动

1. 后台启动服务：使用 Bash，run_in_background: true
2. 等待就绪：轮询端口可用性（最多 30 秒，每 2 秒检查一次）

- 就绪 → 显示 ✓ [description]（服务已启动，PID: xxx） - 超时 → 不要只报告错误，自主排查： - 检查后台进程输出/日志 - 分析错误原因（编译错误？缺失依赖？配置问题？） - 尝试修复并重启 - 修复后仍然失败 → AskUserQuestion：「重试」/「跳过」/「中止」

1. 在 started_services 列表中记录启动服务的 PID，用于 Step 6 清理

3.3 [MANUAL] 项目 — 人工确认

1. 显示准备项描述
2. AskUserQuestion：「已完成」/「跳过」/「中止验收」

3.4 旧格式兼容（无标签）

如果准备项没有 [AUTO]/[AUTO/SERVICE]/[MANUAL] 标签：

• 包含反引号命令 → 视为 [AUTO]
• 没有反引号命令 → 视为 [MANUAL]

所有准备项完成后

显示："准备工作完成，开始 AI 驱动验收。"

Step 4: AI 驱动验证循环 — 核心逻辑

按顺序处理每个待处理（#### - [ ]）项目。

4.1 显示项目概览

展示验收项的简要概览：

---
## [N.M] [验收项名称]
共 X 个步骤（自动: Y, 人工: Z）
---

4.2 顺序执行子步骤

解析 **操作步骤:** 部分。每个编号步骤以 [A] 或 [H] 开头。

[A] 步骤 — 自动化执行：

1. 从步骤中的反引号提取命令
2. 通过 Bash 执行
3. 将实际输出与 → 期望: 后的预期结果比较
4. 匹配 → 显示 ✓ [步骤描述]
5. 不匹配 → 分析原因，尝试修复（例如重启服务、修复配置）：

- 重试命令（最多 3 轮） - 修复后 → 显示 ✓ [步骤描述]（重试后通过） - 3 轮后仍然失败 → 记录步骤为失败，显示 ✗ [步骤描述]，包含实际 vs 预期输出 - 继续下一个子步骤（不要停止整个项目）

[H] 步骤 — 调用人类并提供微指令：

1. 显示步骤中精确的微指令文本（→ 之前的所有内容）
2. 使用 AskUserQuestion 提供正好 2 个选项：

- 「是」 — 观察结果符合预期 - 「否」 — 观察结果不符合预期（用户可以通过 "Other" 添加详情）

1. 「是」 → 显示 ✓ [步骤描述]
2. 「否」 → 进入修复并重新验证循环：

a. 用纯文本（不要用 AskUserQuestion）询问用户："请描述观察到的异常情况：" b. AI 根据用户描述分析问题并修复代码 c. 修复后，显示纯文本提醒："✅ 已修复，请重新刷新页面/重新操作后再次检查。" d. 重新显示同一步骤的微指令文本 e. 使用 AskUserQuestion 提供正好 2 个选项：「是」 / 「否」 f. 「是」 → 显示 ✓ [步骤描述]（修复后通过），跳出循环 g. 「否」 → 回到步骤 a，继续循环 h. 无重试限制 — 用户可以随时通过 Other 输入 "跳过" 跳过，这将记录步骤为失败，带有 ✗ [步骤描述]

4.3 确定项目结果

项目的所有子步骤处理完后：

• 所有子步骤通过（包括修复后通过的步骤） → 标记 #### - [x]（通过）

- 立即更新文件 - 显示：✓ [N.M] [名称]

• 任何子步骤失败 → 标记 #### - [!]（失败）

- 立即更新文件 - 显示：✗ [N.M] [名称]，包含失败步骤列表 - 如果存在矛盾（[A] 步骤通过但相关的 [H] 步骤失败）： - 人类优先 — 标记为失败 - 在标题后插入块引用注释：> **矛盾备注:** API 层验证通过但 UI 层验证失败，以人工观察为准

4.4 特殊处理：纯自动化项目（全部 [A]）

当项目的所有子步骤都是 [A] 时：

• 自动执行全部，无需人工交互
• 全部通过 → 标记 #### - [x]，显示：✓ [N.M] [名称]（自动验证通过）
• 任何失败 → 标记 #### - [!]，显示：✗ [N.M] [名称]（自动验证失败），包含详情

4.5 显示进度

每个项目后，显示进度：

[N/Total] 已处理 — 通过: X, 不通过: Y, 跳过: Z

4.6 继续下一个待处理项目

重复 4.1–4.5，直到处理完所有项目。

Step 5: 最终总结

所有项目处理完成后（或所有待处理项目完成后）：

## 验收执行完毕

- 通过: X 项 ✓（其中修复后通过: R 项）
- 不通过: Y 项 ✗
- 跳过: Z 项 -
- 总计: N 项
- 自动执行步骤: A 个
- 人工确认步骤: H 个

如果有失败项目：

### 不通过项目
| 序号 | 验收项 | 失败步骤 | 备注 |
|------|--------|----------|------|
| 1.2 | [名称] | [A] step 2, [H] step 3 | [备注或无] |
| ... | ... | ... | ... |

如果有跳过的项目：

💡 有 Z 个跳过的验收项，可重新运行 `/sdd-start-human-verify` 继续验收。

如果全部通过：

🎉 所有验收项全部通过！

💡 **建议下一步：** 运行 `/sdd-archive` 将此 feature 归档到全局知识库。

Step 6: 服务清理

最终总结（Step 5）后，清理本次会话启动的服务：

1. 检查 Step 3 中记录的 started_services 列表
2. 如果列表为空（所有服务都是预先存在的并被复用）→ 跳过，不显示任何内容
3. 如果有本次技能启动的服务 → 终止每个服务：

- 对于 started_services 中的每个条目，按 PID 终止进程 - 显示：已清理 N 个后台服务。

1. 只清理本次技能启动的进程 — 绝不碰触会话前已在运行的服务

规则

• AI 驱动执行 — AI 自主运行 [A] 步骤，仅对 [H] 步骤调用人类
• 人类作为 oracle — 当 AI（[A]）和人类（[H]）结果冲突时，人类优先
• 精确微指令 — [H] 步骤必须告诉人类具体要看什么；人类只需回答是/否
• 开始时检测模型 — 检测到 Opus 时，输出纯文本建议切换到更快的模型；非阻塞，始终继续
• 无 git 操作 — 不进行 branch、commit、merge、push
• 中文输出 — 所有用户-facing 信息用中文
• 英文指令 — SKILL.md 内部逻辑用英文
• 即时文件写入 — 每个项目后立即更新 spec-human-verify.md，用于恢复点恢复
• 不要更新 spec-plan.md — 只修改 spec-human-verify.md
• 三状态复选框 — [x] 通过，[!] 失败，[ ] 待处理/跳过
• 尊重现有状态 — 永不重新处理 [x] 或 [!] 项目
• [H] 步骤的修复并重新验证循环 — 当人类回答 "否" 时，AI 收集问题描述（纯文本，不是 AskUserQuestion），修复代码，提醒用户重新检查，然后重新询问。循环继续直到人类确认或输入 "跳过"。修复后通过的步骤计为 "修复后通过"，并视为项目结果通过
• 无外部技能依赖 — 完全独立