ralph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ralph - Self-Referential Completion Loop

ralph - 自引用完成循环

When to use this skill

何时使用该Skill

Long-running implementation tasks that tend to stop early
Tasks that need autonomous multi-turn iteration without manual intervention
Workflows where the agent must self-correct and refine output across turns
Sessions where exact completion signaling is required before stopping

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

Core Concept

核心概念

The loop happens across agent turns, controlled by an

AfterAgent

hook.

You run ONCE:

/ralph "Your task description" --completion-promise "DONE"

Agent works: Performs actions (modifies files, runs tests, writes code)
Hook intercepts: When the agent finishes its turn, the
```
AfterAgent
```
hook intercepts the exit
Loop continuation: Hook evaluates state (max iterations, promise) and starts a new turn with the original prompt, clearing the previous turn's context
Repeat: Continues autonomously until completion or user interruption

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

AfterAgent

钩子控制。

仅需运行一次：

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

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

Why this works

为什么这种方式有效

Stable Context & No Compaction: Prompt never changes between iterations; previous conversational context is cleared. The agent relies on current file state, not stale chat history.
Persistent State: The agent's work persists in files and git history across iterations.
Autonomous Improvement: Each iteration sees the current codebase state and improves on past work.
Ghost Protection: If you interrupt the loop and start a new task, the hook detects the prompt mismatch and silently cleans up.

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

1. Core Command Pattern

1. 核心命令格式

text

/ralph "<task description>" [--completion-promise=TEXT] [--max-iterations=N]

Defaults:

Completion promise:
```
DONE
```
Max iterations:
```
100
```

text

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

默认值：

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

2. How the Loop Behaves

2. 循环运行机制

Starts with your task prompt.
On each turn end, the
```
AfterAgent
```
hook checks whether the assistant output contains:

xml

<promise>DONE</promise>

If not found, hook starts a new agent turn with the same original prompt (context cleared).
Stops only when:
- Completion promise is detected in output, or
- Max iterations is reached, or
- You run
```
/ralph:cancel
```

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

xml

<promise>DONE</promise>

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

3. Practical Usage

3. 实际使用场景

Standard run

标准运行

text

/ralph "Build a Python CLI task manager with full test coverage"

text

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

With completion promise

自定义完成标识

text

/ralph "Build a REST API for todos. When all CRUD endpoints work and tests pass with >80% coverage, output TASK_COMPLETE" --completion-promise="TASK_COMPLETE"

text

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

Bounded iteration run

限制迭代次数运行

text

/ralph "Attempt to refactor the authentication module" --max-iterations=20

text

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

TDD workflow with self-correction

包含自我修正的TDD工作流

text

/ralph "Implement feature X by following TDD:
1. Write failing tests for the feature.
2. Implement the code to make the tests pass.
3. Run the test suite.
4. If any tests fail, analyze the errors and debug.
5. Refactor for clarity and efficiency.
6. Repeat until all tests are green.
7. When complete, output <promise>TESTS_PASSED</promise>" --completion-promise="TESTS_PASSED"

text

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

Cancel active loop

取消活跃循环

text

/ralph:cancel

text

/ralph:cancel

View help

查看帮助

text

/ralph:help

text

/ralph:help

4. Prompt Writing Best Practices

4. 提示词编写最佳实践

1. Clear Completion Criteria

1. 明确完成标准

Provide a verifiable definition of "done." The

--completion-promise

is crucial.

Good:

text

/ralph "Build a REST API for todos. When all CRUD endpoints are working and all tests pass with >80% coverage, you're complete." --completion-promise="TASK_COMPLETE"

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

--completion-promise

参数至关重要。

示例（良好）：

text

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

2. Use Safety Hatches

2. 使用安全机制

Always use

--max-iterations

as a safety net to prevent infinite loops.

text

/ralph "Attempt to refactor the authentication module" --max-iterations=20

始终使用

--max-iterations

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

text

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

3. Encourage Self-Correction

3. 鼓励自我修正

Structure the prompt to guide the agent through work → verify → debug cycles.

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

5. Launch Safely

5. 安全启动

Always run in sandbox mode for safety. Enabling YOLO mode (

-y

) prevents constant tool execution prompts during the loop:

bash

gemini -s -y

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

-y

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

bash

gemini -s -y

6. Installation (Gemini CLI)

6. 安装（Gemini CLI）

bash

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

Required in

~/.gemini/settings.json

json

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

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에서 사용 (권장 보정)

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

Usage:
  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
```
누락, promise 누락, max 반복 초과)를 줄여줍니다.

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 extension 설치
Claude Code	네이티브(권장)	스킬/오케스트레이션 적재 후 `/ralph` 사용
OpenCode	네이티브(동일 경로)	`ralph` 키워드 등록 후 동일 명령어 사용
Codex	보정 모드	`setup-codex-hook.sh` 실행 후 `/prompts:ralph` 기반 반복 운영

현재 스킬만

으로 가능한지:

Gemini-CLI/Claude Code/OpenCode: 가능
Codex:
```
setup-codex-hook.sh
```
로 보정한 뒤 운영 가능

平台	当前支持方式	核心条件
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
```
修正后可用

Quick Reference

快速参考

Action	Command
Start loop	`/ralph "task"`
Custom promise	`/ralph "task" --completion-promise=TEXT`
Iteration cap	`/ralph "task" --max-iterations=N`
Cancel	`/ralph:cancel`
Help	`/ralph:help`

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