SDD Start Human Verify

SKILL.md

---
name: sdd-start-human-verify
description: "AI 驱动验收执行 — 自主运行 [A] 步骤，对 [H] 步骤调用人类并提供精确的微指令。"
---

# 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" 输入自定义路径
   - 所有问题文本用中文
4. 读取选中的 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`：「继续」/「中止」
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 显示项目概览

展示验收项的简要概览：
```
---
## [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 显示进度

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