ralph - 自引用完成循环

何时使用该Skill

容易提前终止的长期实现任务
无需人工干预、需要自主多轮迭代的任务
Agent必须在多轮过程中自我修正并优化输出的工作流
需要明确完成信号后再停止的会话

核心概念

循环在Agent的多轮交互中进行，由

AfterAgent

钩子控制。

仅需运行一次：

/ralph "你的任务描述" --completion-promise "DONE"

Agent执行任务：执行操作（修改文件、运行测试、编写代码）
钩子拦截：当Agent完成当前轮次后，
```
AfterAgent
```
钩子会拦截退出操作
循环继续：钩子评估当前状态（最大迭代次数、完成标识），并使用原始提示词启动新的轮次，同时清除上一轮的上下文
重复执行：自主持续循环，直到任务完成或用户中断

为什么这种方式有效

稳定上下文且无压缩：迭代过程中提示词保持不变；之前的对话上下文会被清除。Agent依赖当前文件状态，而非过时的聊天历史。
状态持久化：Agent的工作成果会在多轮迭代中保留在文件和Git历史中。
自主优化：每一轮迭代都会基于当前代码库状态，对之前的工作进行改进。
干扰防护：如果您中断循环并启动新任务，钩子会检测到提示词不匹配，并自动清理相关状态。

1. 核心命令格式

text

/ralph "<任务描述>" [--completion-promise=TEXT] [--max-iterations=N]

默认值：

完成标识：
```
DONE
```
最大迭代次数：
```
100
```

2. 循环运行机制

从您的任务提示词开始执行。
在每轮结束时，
```
AfterAgent
```
钩子会检查助手的输出中是否包含：

xml

<promise>DONE</promise>

如果未找到该标识，钩子会使用相同的原始提示词启动新的Agent轮次（上下文已清除）。
仅在以下情况停止：
- 输出中检测到完成标识，或
- 达到最大迭代次数，或
- 您执行
```
/ralph:cancel
```
  命令

3. 实际使用场景

标准运行

text

/ralph "构建一个具备完整测试覆盖率的Python CLI任务管理器"

自定义完成标识

text

/ralph "构建一个待办事项REST API。当所有CRUD端点正常工作且测试覆盖率超过80%时，输出TASK_COMPLETE" --completion-promise="TASK_COMPLETE"

限制迭代次数运行

text

/ralph "尝试重构认证模块" --max-iterations=20

包含自我修正的TDD工作流

text

/ralph "遵循TDD流程实现功能X：
1. 为该功能编写失败的测试用例。
2. 实现代码使测试通过。
3. 运行测试套件。
4. 如果有测试失败，分析错误并调试。
5. 重构代码以提升清晰度和效率。
6. 重复上述步骤直到所有测试通过。
7. 完成后输出 <promise>TESTS_PASSED</promise>" --completion-promise="TESTS_PASSED"

取消活跃循环

text

/ralph:cancel

查看帮助

text

/ralph:help

4. 提示词编写最佳实践

1. 明确完成标准

提供可验证的“完成”定义。

--completion-promise

参数至关重要。

示例（良好）：

text

/ralph "构建一个待办事项REST API。当所有CRUD端点正常工作且所有测试通过、覆盖率超过80%时，任务完成。" --completion-promise="TASK_COMPLETE"

2. 使用安全机制

始终使用

--max-iterations

作为安全保障，防止无限循环。

text

/ralph "尝试重构认证模块" --max-iterations=20

3. 鼓励自我修正

设计提示词以引导Agent遵循“工作→验证→调试”的循环流程。

5. 安全启动

为了安全起见，始终在沙箱模式下运行。启用YOLO模式（

-y

）可避免循环过程中频繁出现工具执行提示：

bash

gemini -s -y

6. 安装（Gemini CLI）

bash

gemini extensions install https://github.com/gemini-cli-extensions/ralph --auto-update

~/.gemini/settings.json

中需配置以下内容：

json

{
  "hooksConfig": { "enabled": true },
  "context": {
    "includeDirectories": ["~/.gemini/extensions/ralph"]
  }
}

6. 在Codex中使用（推荐修正方案）

ralph在Gemini中基于AfterAgent钩子实现自动循环，但Codex目前不支持原生的结束钩子。

因此，在Codex中使用ralph时，建议安装以下修正脚本：

bash

bash <your-agent-skills>/ralph/scripts/setup-codex-hook.sh

该脚本会执行以下操作：

在

~/.codex/config.toml

的

developer_instructions

中记录ralph的重启协议信息

创建
```
~/.codex/prompts/ralph.md
```
文件（可通过
```
/prompts:ralph
```
快速执行）
支持
```
--dry-run
```
选项，可在应用前预览效果

text

使用方法:
  bash <your-agent-skills>/ralph/scripts/setup-codex-hook.sh
bash <your-agent-skills>/ralph/scripts/setup-codex-hook.sh --dry-run

⚠️ 注意准确性：

Codex目前对强制实现完全自动循环的原生钩子支持有限。
上述配置会固化ralph的运行协议，减少后续重复任务时的人为失误（如遗漏
```
/prompts:ralph
```
、遗漏完成标识、超出最大迭代次数等）。

各平台适配状态（当前支持标准）

平台	当前支持方式	核心条件
Gemini-CLI	原生支持	安装 `AfterAgent` 钩子 + ralph扩展
Claude Code	原生支持（推荐）	加载Skill/编排后使用 `/ralph` 命令
OpenCode	原生支持（路径一致）	注册 `ralph` 关键词后使用相同命令
Codex	修正模式	执行 `setup-codex-hook.sh` 后基于 `/prompts:ralph` 进行循环运行

仅通过当前Skill是否可用：

Gemini-CLI/Claude Code/OpenCode：是
Codex：执行
```
setup-codex-hook.sh
```
修正后可用

快速参考

操作	命令
启动循环	`/ralph "task"`
自定义完成标识	`/ralph "task" --completion-promise=TEXT`
限制迭代次数	`/ralph "task" --max-iterations=N`
取消循环	`/ralph:cancel`
查看帮助	`/ralph:help`

ralph

NPX安装

标签

SKILL.md 内容（中文）

ralph - 自引用完成循环

何时使用该Skill

核心概念

为什么这种方式有效

1. 核心命令格式

2. 循环运行机制

3. 实际使用场景

标准运行

自定义完成标识

限制迭代次数运行

包含自我修正的TDD工作流

取消活跃循环

查看帮助

4. 提示词编写最佳实践

1. 明确完成标准

2. 使用安全机制

3. 鼓励自我修正

5. 安全启动

6. 安装（Gemini CLI）

6. 在Codex中使用（推荐修正方案）

各平台适配状态（当前支持标准）

快速参考