161 lines
3.3 KiB
Markdown
161 lines
3.3 KiB
Markdown
---
|
||
name: ralph-loop
|
||
description: Ralph Loop 自动化编码循环 - 让 AI 代理持续工作直到完成任务。支持 PLANNING（规划）和 BUILDING（构建）两种模式，使用 exec + process 工具监控进度。
|
||
allowed-tools: Read, Write, Edit, Exec, Process
|
||
---
|
||
|
||
# Ralph Loop (Agent Mode)
|
||
|
||
自动化 AI 编码代理循环工作流。
|
||
|
||
## 工作流程
|
||
|
||
```
|
||
需求定义 → PLANNING Loop → BUILDING Loop → 完成
|
||
```
|
||
|
||
1. **PLANNING Loop** - 创建/更新 IMPLEMENTATION_PLAN.md（不实现）
|
||
2. **BUILDING Loop** - 实现任务、运行测试、更新计划、提交
|
||
|
||
## 支持的 CLI
|
||
|
||
| CLI | 命令模式 | TTY 需求 |
|
||
|-----|---------|---------|
|
||
| OpenCode | `opencode run --model <MODEL> "$(cat PROMPT.md)"` | ✅ |
|
||
| Codex | `codex exec --full-auto "$(cat PROMPT.md)"` | ✅ |
|
||
| Claude Code | `claude --dangerously-skip-permissions "$(cat PROMPT.md)"` | ✅ |
|
||
| Pi | `pi --provider <PROVIDER> -p "$(cat PROMPT.md)"` | ✅ |
|
||
| Goose | `goose run "$(cat PROMPT.md)"` | ✅ |
|
||
|
||
## 使用方法
|
||
|
||
### 1. 准备项目文件
|
||
|
||
创建 `PROMPT.md`:
|
||
```markdown
|
||
# 目标
|
||
<你的任务描述>
|
||
|
||
## 参考文件
|
||
- specs/*.md
|
||
- IMPLEMENTATION_PLAN.md
|
||
```
|
||
|
||
创建 `AGENTS.md`:
|
||
```markdown
|
||
# 项目说明
|
||
|
||
## 测试命令
|
||
npm test
|
||
|
||
## 构建命令
|
||
npm run build
|
||
```
|
||
|
||
### 2. 启动循环
|
||
|
||
**PLANNING 模式**:
|
||
```bash
|
||
# 我会执行
|
||
exec(
|
||
command: 'opencode run --model claude-opus-4 "$(cat PROMPT.md)"',
|
||
workdir: "/path/to/project",
|
||
background: true,
|
||
pty: true,
|
||
timeout: 3600
|
||
)
|
||
```
|
||
|
||
**BUILDING 模式**:
|
||
```bash
|
||
# 同上，但 PROMPT.md 内容不同
|
||
```
|
||
|
||
### 3. 监控进度
|
||
|
||
```bash
|
||
# 轮询状态
|
||
process(action: "poll", sessionId: "xxx")
|
||
|
||
# 查看日志
|
||
process(action: "log", sessionId: "xxx", offset: -30)
|
||
```
|
||
|
||
### 4. 检测完成
|
||
|
||
检查 `IMPLEMENTATION_PLAN.md`:
|
||
- `STATUS: PLANNING_COMPLETE` - 规划完成
|
||
- `STATUS: COMPLETE` - 构建完成
|
||
|
||
## 提示词模板
|
||
|
||
### PLANNING 模式
|
||
|
||
```markdown
|
||
You are running a Ralph PLANNING loop for this goal: <goal>.
|
||
|
||
Read specs/* and the current codebase. Only update IMPLEMENTATION_PLAN.md.
|
||
|
||
Rules:
|
||
- Do not implement
|
||
- Do not commit
|
||
- Create a prioritized task list
|
||
- Write down questions if unclear
|
||
|
||
Completion:
|
||
When plan is ready, add: STATUS: PLANNING_COMPLETE
|
||
```
|
||
|
||
### BUILDING 模式
|
||
|
||
```markdown
|
||
You are running a Ralph BUILDING loop for this goal: <goal>.
|
||
|
||
Context: specs/*, IMPLEMENTATION_PLAN.md, AGENTS.md
|
||
|
||
Tasks:
|
||
1) Pick the most important task
|
||
2) Investigate code
|
||
3) Implement
|
||
4) Run backpressure commands from AGENTS.md
|
||
5) Update IMPLEMENTATION_PLAN.md
|
||
6) Update AGENTS.md with learnings
|
||
7) Commit with clear message
|
||
|
||
Completion:
|
||
When all done, add: STATUS: COMPLETE
|
||
```
|
||
|
||
## 安全注意事项
|
||
|
||
- 使用沙盒环境
|
||
- 设置合理超时
|
||
- 重要项目先备份
|
||
- 监控进度，不要过早终止
|
||
|
||
## 故障排除
|
||
|
||
| 问题 | 解决方案 |
|
||
|------|---------|
|
||
| CLI 卡住 | 确保 pty: true |
|
||
| 无法启动 | 检查 CLI 路径和 git 仓库 |
|
||
| 未检测到完成 | 验证 IMPLEMENTATION_PLAN.md 中的格式 |
|
||
| 超时 | 增加 timeout 参数 |
|
||
|
||
## 示例
|
||
|
||
### 完整工作流
|
||
|
||
1. 用户: "帮我实现用户认证模块"
|
||
2. 我创建 specs/auth.md, PROMPT.md, AGENTS.md
|
||
3. 我启动 PLANNING 循环
|
||
4. AI 生成 IMPLEMENTATION_PLAN.md
|
||
5. 我启动 BUILDING 循环
|
||
6. AI 逐个实现任务
|
||
7. 检测到 STATUS: COMPLETE
|
||
8. 完成！
|
||
|
||
## License
|
||
|
||
MIT
|