back
loading skill details...
AI 驱动验收执行 — 自主运行 [A] 步骤,对 [H] 步骤调用人类并提供精确的微指令。
---
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),修复代码,提醒用户重新检查,然后重新询问。循环继续直到人类确认或输入 "跳过"。修复后通过的步骤计为 "修复后通过",并视为项目结果通过
- **无外部技能依赖** — 完全独立
don't have the plugin yet? install it then click "run inline in claude" again.