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

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

检查当前 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-human-verify.md 的文件
按修改时间排序（最新优先）
通过 AskUserQuestion 展示最新的 3 个文件：

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

读取选中的 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]` 项目 — 一次性命令执行

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

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

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

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

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

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

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

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

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

3.3 `[MANUAL]` 项目 — 人工确认

显示准备项描述
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]` 步骤 — 自动化执行：

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

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

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

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

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

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

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）后，清理本次会话启动的服务：

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

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

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

规则

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

SDD Start Human Verify

概述