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，输出以下纯文本消息并继续（非阻塞）：

text

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

Step 1: 文件选择#

如果提供了路径参数#

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

如果没有提供路径参数#

1. 扫描 {workspace}/spec/ 中所有匹配 feature_*/spec-human-verify.md 的文件

2. 按 修改时间 排序（最新优先）

3. 通过 AskUserQuestion 展示 最新的 3 个 文件：

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

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

边界情况：未找到文件#

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

Step 2: 恢复点检测#

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

text

^####\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：「继续」/「中止」
5. 修复后重试，最多 3 轮
6. 3 轮后仍然失败 → AskUserQuestion：「跳过」/「中止验收」

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

1. 从行中提取命令和端口号（正则： \(port:\s*(\d+)\)）

2. 先检查端口：运行 ss -tlnp | grep :PORT 或 lsof -i :PORT

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

3. 后台启动服务：使用 Bash， run_in_background: true

4. 等待就绪：轮询端口可用性（最多 30 秒，每 2 秒检查一次）

   • 就绪 → 显示 ✓ [description]（服务已启动，PID: xxx）

   • 超时 → 不要只报告错误，自主排查：

     • 检查后台进程输出/日志
     • 分析错误原因（编译错误？缺失依赖？配置问题？）
     • 尝试修复并重启
     • 修复后仍然失败 → AskUserQuestion：「重试」/「跳过」/「中止」

5. 在 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 显示项目概览#

展示验收项的简要概览：

text

---
## [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" 添加详情）

3. 「是」 → 显示 ✓ [步骤描述]

4. 「否」 → 进入 修复并重新验证循环： 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 显示进度#

每个项目后，显示进度：

text

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

4.6 继续下一个待处理项目#

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

Step 5: 最终总结#

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

text

## 验收执行完毕

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

如果有失败项目：#

text

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

如果有跳过的项目：#

text

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

如果全部通过：#

text

🎉 所有验收项全部通过！

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

Step 6: 服务清理#

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

1. 检查 Step 3 中记录的 started_services 列表
2. 如果列表为空（所有服务都是预先存在的并被复用）→ 跳过，不显示任何内容
3. 如果有本次技能启动的服务 → 终止每个服务：
   • 对于 started_services 中的每个条目，按 PID 终止进程
   • 显示： 已清理 N 个后台服务。
4. 只清理本次技能启动的进程 — 绝不碰触会话前已在运行的服务

规则#

• 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），修复代码，提醒用户重新检查，然后重新询问。循环继续直到人类确认或输入 "跳过"。修复后通过的步骤计为 "修复后通过"，并视为项目结果通过
• 无外部技能依赖 — 完全独立