| name | ralph-verification |
| description | Ralph Verification — AI Agent 驱动的结构化软件开发流程框架。 面向通用 Agent（OpenClaw / Hermes / 等），将编码任务委派给 Claude Code / Kimi CLI 等专用编码 Agent。 Router-in-the-Loop 架构：编写 PRD → 逐 Story 委派编码 Agent → Router 独立验收 → 失败则升级/纠偏。 支持双 Agent 调度、升级协议、PRD 审批门。
|
| trigger | ralph|用ralph|按ralph流程|ralph方式|ralph开发 |
| tools | ["exec","terminal","read","write","script"] |
| user-invocable | true |
Ralph Verification — Router-in-the-Loop 软件开发流程
定位：本 Skill 专为 OpenClaw、Hermes 等通用型 Agent 设计。通用 Agent 负责高层规划、PRD 编写、验收和流程编排；繁重的编码实现通过本 Skill 委派给 Claude Code、Kimi CLI 等专用编码 Agent。
核心逻辑：通用 Agent（你）= Router（编排层）→ 调用编码 Agent（执行层）→ 你独立验收 → 失败则写 feedback 升级。
前置条件 / Prerequisites
在首次使用前，必须确保以下依赖就绪。
必需依赖（Required）
| 工具 | 检查命令 | 安装方式 | 用途 |
|---|
| Python 3 | python3 --version | brew install python3 / apt install python3 | 运行调度脚本 scripts/invoke_agent.py |
| Git | git --version | brew install git / apt install git | 版本控制、分支管理、diff 验收 |
可选依赖（至少安装一种编码 Agent）
| 工具 | 检查命令 | 安装方式 | 用途 |
|---|
| Claude Code | claude --version | npm install -g @anthropic-ai/claude-code | 默认编码 Agent（推荐） |
| Kimi CLI | kimi --version | 参考 https://platform.moonshot.ai | 备选编码 Agent |
环境自动检查
运行以下命令检查环境：
bash {skillDir}/scripts/check-env.sh
如果缺少依赖，运行以下命令自动安装：
bash {skillDir}/scripts/setup.sh
OpenClaw 用户：使用 exec 工具运行上述命令。
Hermes 用户：使用 terminal 工具运行上述命令。
触发条件
当 User 说以下任意内容时，激活本 Skill：
- 「用 ralph 方式做 XXX」
- 「ralph 开发 XXX」
- 「按 ralph 流程 XXX」
- 「用 ralph 做 XXX」
- 或明确提到「ralph」+ 软件开发需求
工作流程（5 个阶段）
Phase 0 — 环境准备
每次触发本 Skill 时，先执行以下检查：
□ 运行 bash {skillDir}/scripts/check-env.sh 确认依赖就绪
□ 若缺少依赖，运行 bash {skillDir}/scripts/setup.sh --auto
□ 确认目标项目目录存在且有 git 仓库
□ 确认分支干净（无未提交变更）
□ 确认 .ralph/config.json 存在（setup.sh 会自动创建）
配置说明：.ralph/config.json 定义了可用的编码 Agent 及其调用方式。
默认配置使用 Claude Code 作为 agent1，Kimi CLI 作为 agent2。
Phase 1 — PRD 编写（Router 执行）
⚠️ 必须遵循 prd skill 流程！ 先问澄清问题，再生成 PRD，最后审批。
1.1 澄清问题（强制步骤）
Router 必须先问 3-5 个关键澄清问题，格式：
📋 开始规划 PRD，需要先确认几个问题：
1. **目标 Agent** — 使用哪个 Agent 执行开发？
A. Claude Code（默认，高代码质量）
B. Kimi CLI（成本优先）
C. 双 Agent 组合（Claude×2 → Kimi×2）
D. 其他: [指定]
2. **Story 拆分偏好** — 如何切分 User Stories？
A. 最小化（3-5个），每个 Story 极小
B. 平衡（5-8个），推荐
C. 最大化（8-12个），每个 Story 完整
3. **Scope 边界** — 哪些不做？
A. 只做核心功能
B. 含基础测试
C. 含完整测试 + 文档
4. **优先级规则** — Story 排序依据？
A. 依赖关系（数据库→API→UI）
B. 风险高低（高风险先做）
C. 价值大小（高价值先做）
请回复如「1A, 2B, 3B, 4A」，或直接描述需求。
1.2 生成 PRD
收到回复后，Router 按以下结构生成 Markdown PRD（不是 JSON！）：
# PRD: [项目名称]
## 1. Introduction/Overview
[功能概述 + 解决什么问题]
## 2. Goals
- [具体可衡量的目标]
- ...
## 3. User Stories
### US-001: [标题]
**Description:** As a [user], I want [feature] so that [benefit].
**Acceptance Criteria:**
- [ ] 具体可验证的标准
- [ ] 另一个标准
- [ ] 类型检查/测试通过
[... 更多 Story ...]
## 4. Functional Requirements
- FR-1: [编号功能需求]
- FR-2: ...
## 5. Non-Goals (Out of Scope)
- [明确不做什么]
## 6. Design Considerations (Optional)
- [UI/UX/技术约束]
## 7. Technical Considerations (Optional)
- [已知约束/集成点]
## 8. Success Metrics
- [如何衡量成功]
## 9. Open Questions
- [待确认问题]
1.3 保存位置
项目根目录/
└── tasks/
└── prd-[feature-name].md ← PRD 存放位置（不是 prd.json）
同时初始化 progress.txt 和 .ralph/ 目录结构。
⭐ PRD 审批门（必须停等）：
PRD 编写原则：
- 每个 Story 应小而独立，单 Agent 一次上下文窗口可完成
- 验收标准必须可验证（具体、可测试、无歧义）
- 优先级考虑依赖关系（数据库 → API → UI）
- Story 数量控制在 5-8 个（除非 User 选择其他粒度）
Phase 2 — 迭代开发循环（Router 调度编码 Agent）
对每个 passes: false 的 Story 执行：
Step 1: Router 构建编码 Agent Prompt
- 加载
templates/agent_prompt.md 模板
- 注入当前 Story 详情 + Acceptance Criteria
- 若有上次驳回反馈 → 注入 feedback
- 保存到
.ralph/agent_prompt.md
Step 2: 调用编码 Agent 实现
- 根据
.ralph/config.json 和升级协议决定使用哪个 Agent
- 使用
terminal 或 exec 工具调用编码 Agent CLI
- 等待 Agent 完成并 commit
默认调用方式：
claude --dangerously-skip-permissions --print "$(cat .ralph/agent_prompt.md)"
kimi --quiet -w . -p "$(cat .ralph/agent_prompt.md)"
Step 3: Router 独立验收
git diff HEAD~1 查看变更- 逐条对照 Acceptance Criteria 检查
- 运行项目测试（如有）
- 给出判定: ✅ PASS / ❌ FAIL
结果处理：
- PASS → 更新 prd.json 设
passes: true → 追加 progress.txt → 下一 Story
- FAIL → 驳回计数 +1 → 写 feedback.txt（具体、可操作）→ 进入 Phase 2.5
Phase 2.5 — 升级协议（Escalation Protocol）
Story 验收失败
│
├─ agent1_rejections < 2
│ └─ Agent1 修复: Router 写 feedback.txt → Agent1 复验
│ ┌─ PASS → 下一 Story
│ └─ FAIL → agent1_rejections + 1
│
├─ agent1_rejections == 2
│ └─ ⚠️ 升级 Agent2 介入
│ └─ Agent2 修复: Router 写 feedback.txt → Agent2 复验
│ ┌─ PASS → 下一 Story
│ └─ FAIL → agent2_rejections + 1
│
├─ agent2_rejections == 2
│ └─ ⚠️ 升级 Router 直接修复
│ └─ Router 写代码修复
│ ┌─ 成功 → 标记 passes: true
│ └─ 失败 → 升级给 User
│
└─ router_attempts == 1
└─ 🚨 升级给 User（人工决策）
升级给 User 时：停手，汇报问题症结 + 已尝试方案，等待人工决策。
Phase 3 — 全量验收
所有 Stories passes: true 后：
□ 运行全量测试套件
□ 检查是否有未提交变更
□ 生成开发总结报告
□ 标记 PRD status: "complete"
Phase 4 — 交付
- 汇报完成情况（Story 列表 + 状态 + 各 Agent 贡献统计）
- 列出关键文件变更
- 提供下一步建议
验收协议（Router 验收标准）
验收检查清单
对每个 Story 的变更，必须逐项检查：
- 功能完整性 — 是否实现了所有 Acceptance Criteria？
- 代码质量 — 是否遵循项目现有代码风格？无明显的代码异味？
- 测试通过 — 现有测试是否全部通过？新增代码是否有对应测试？
- 无副作用 — 是否引入了无关变更？是否破坏了其他功能？
- Git 规范 — commit message 是否符合
feat: US-XXX - Title 格式？
- 最小变更 — 变更是否聚焦在当前 Story，无越界实现？
- Agent 过程规范 — 是否遵守各 Agent 的禁止规则？
各编码 Agent 禁止规则
Claude Code：
- ❌ 不修改
passes 字段（Router 验收后统一修改）
- ❌ 不写「Router 验收: ✅ PASS」—— 验收是 Router 职责
- ❌ 不跳过测试
- ❌ 不一次实现多个 Story
Kimi CLI：
- ❌ 不修改
passes 字段
- ❌ 不写「Router 验收: ✅ PASS」
- ❌ 不跳过测试
- ❌ 不一次实现多个 Story
- ❌ 不产生多个 commit（一个 Story 一个 commit）
驳回反馈格式
驳回时必须给出具体、可操作的反馈：
## ❌ Story US-XXX 验收驳回（第 N 次 by [Agent1/Agent2]）
### 未通过的验收标准
- [ ] 标准1：具体哪里没通过
### 需要修复的问题
1. **问题描述** (文件路径:行号)
- 当前行为: ...
- 期望行为: ...
- 修复建议: ...
### 通过的部分（给予肯定）
- ✅ 标准2：已正确实现
文件结构
项目根目录/
├── tasks/
│ └── prd-[feature-name].md ← Router 生成，Agent 只读（Markdown 格式）
├── progress.txt ← Router + Agent 共同维护
│ 记录每个 Story 的实现过程、验收结果和学习
├── .ralph/
│ ├── config.json ← Agent CLI 配置（默认 Claude + Kimi）
│ ├── feedback.txt ← Router 写入的驳回反馈（临时）
│ └── agent_prompt.md ← 当前轮的 Agent prompt（临时）
├── scripts/
│ ├── invoke_agent.py ← 核心调度脚本
│ ├── check-env.sh ← 环境依赖检查
│ └── setup.sh ← 环境自动配置
└── templates/
├── agent_prompt.md ← Agent Prompt 模板
├── claude_prompt.md ← Claude 专用 Prompt（可选）
└── prd_template.json ← PRD 空模板
Agent Prompt 模板
见 templates/agent_prompt.md。关键约定：
- Agent 只实现指定 Story，不越界
- Agent 不修改
passes 字段（Router 验收后统一修改）
- Agent 完成后输出
<ralph>STORY_DONE</ralph> 信号
- 若有
feedback.txt，Agent 必须优先处理反馈中的问题
陷阱与注意事项
1. 编码 Agent 特性差异
Claude Code：
- ✅ 代码质量可以很高
- ❌ 过程纪律容易出错（commit 不全、越权写验收）
- 应对：prompt 中 FORBIDDEN 反复强调，Router 验收严查过程
Claude Code subprocess 调用陷阱：
- ❌ 不要用
stdin=subprocess.PIPE + input=prompt — Claude 的 --print 不接受 stdin
- ✅ 正确方式：
subprocess.run(["claude", "--print", prompt], ...) — prompt 作为 positional argument
- ❌ 不要用 Python 3.10+ 语法
dict | None — 系统默认 Python 可能是 3.9
- ✅ 正确方式：用
Optional[dict] from typing
Kimi CLI：
--quiet 输出干净，无结构化噪声- Kimi 输出
<ralph>STORY_DONE</ralph> 时机与 Claude 相同
- 若超步数限制，加
--max-steps-per-turn 50
- Kimi session 可 resume：
kimi -r <session_id>
- ⚠️ subprocess 调用：
subprocess.run(["kimi", "--quiet", "-w", project_dir, "-p", prompt], ...)
2. Router 验收要严
- 验收时先
git status — 检查是否有未提交变更
- 验收时检查 progress.txt 是否有「Router 验收」字样（Agent 越权模式）
- 反馈要极其具体 — 文件路径、当前行为、期望行为
- 纠偏反馈写完后立即保存到
feedback.txt，再调用 Agent
3. 升级链路关键原则
- Agent 切换时必须重置上下文：每次切换 Agent，feedback.txt 包含完整问题描述
- Router 介入写代码时：直接用 write_file/patch 等工具，不通过 Agent CLI
- 升级到 User 时：停手等指示，不继续尝试
4. 超时处理
- 单 Story 超时 300s → 驳回并视为一次失败
- Agent 后台运行时用
notify_on_complete=true 自动通知
- Kimi 若出现步数限制，加
--max-steps-per-turn 50 或更高
5. Git 状态检查
- 每次调用 Agent 前确认 working tree clean
- 验收时第一件事：
git status + git diff HEAD~1 --stat
- 验收时确认 commit 数 = 1（单 Story 单 commit 原则）
一键安装
本 Skill 支持一键安装到 OpenClaw 或 Hermes：
bash install.sh
bash install.sh --target openclaw
bash install.sh --target hermes
安装脚本会自动：
- 检测 OpenClaw / Hermes 环境
- 将 Skill 复制到正确的 skills 目录
- 运行
scripts/setup.sh 检查并安装依赖
- 初始化
.ralph/config.json
版本历史
- v1.8 (2026-05-03): 重大变更：PRD 格式从 JSON 改为 Markdown，强制先问澄清问题再生成 PRD。PRD 存放位置改为
tasks/prd-[feature-name].md。
- v1.7 (2026-05-03): 新增一键安装支持（install.sh + setup.sh + check-env.sh）。SKILL.md 增加 trigger/tools/前置条件声明，适配 OpenClaw 和 Hermes 技能标准。
- v1.6 (2026-05-03): 新增 PRD 审批门，Phase 1 完成后必须等待 User 确认。去除特定人名依赖，适配开源即插即用。
- v1.5 (2026-05-02): 修复 Python 3.9 兼容性。修复 Claude CLI 调用方式。
- v1.4 (2026-05-02): Kimi CLI 参数修正：--print -y → --quiet。
- v1.3 (2026-05-02): 支持双 Agent（Claude + Kimi）。升级链路更新。
- v1.2 (2026-05-02): 新增 Phase 2.5 升级协议。
- v1.1 (2026-05-02): 触发测试完成，更新陷阱章节。
- v1.0 (2026-05-02): 初始版本，基于 ralph v0 原版增强 Router 验收环。
