Ralph

Ralph Wiggum 自主循环技术在 Claude Code 中的一个可用实现。

背景

Anthropic 插件市场中的官方 ralph-wiggum 插件目前因 Claude Code v1.0.20（2025 年 8 月）的安全更新而无法正常工作。

该安全补丁（CVE-2025-54795）正确阻止了 $() 命令替换和多行 bash 命令，以防止命令注入攻击。然而，官方插件的命令文件包含多行 bash，从而触发此保护：

Error: Bash command permission check failed for pattern "...": 
Command contains newlines that could separate multiple commands

已有多份问题报告被提交：

• #12170 - 2025年11月23日
• #15640 - 2025年12月29日
• #15708 - 2025年12月29日
• #16037 - 2026年1月1日

截至 2026 年 1 月 3 日，这些问题仍未修复。

本插件

这是一个干净的重实现，能够在当前的 Claude Code 安全限制下正常工作。

关键架构区别： 官方插件尝试直接从命令文件执行 bash。而本插件指示 Claude 使用其 Write 工具创建状态文件，使命令文件保持纯 markdown，不执行任何 bash。停止钩子（stop hook）作为独立的 shell 脚本在权限系统之外运行。

安装

选项 1：开发模式（用于测试）

claude --plugin-dir /path/to/ralph

选项 2：本地市场（用于永久使用）

# Create marketplace
mkdir -p ~/claude-plugins/.claude-plugin
echo '{"name": "local", "owner": {"name": "You"}}' > ~/claude-plugins/.claude-plugin/marketplace.json

# Move plugin into marketplace
mv /path/to/ralph ~/claude-plugins/

# In Claude Code:
/plugin marketplace add ~/claude-plugins
/plugin install ralph@local

用法

/ralph:ralph-loop "Your task" --max-iterations 30 --completion-promise "DONE"

参数

示例

/ralph:ralph-loop "Build a REST API with tests" --completion-promise "API_COMPLETE"

/ralph:ralph-loop "Follow the instructions in CLAUDE.md" --max-iterations 50 --completion-promise "BENCHMARK_COMPLETE"

取消

/ralph:cancel-ralph

工作原理

1. 命令（Command） 指示 Claude 创建包含任务和配置的 .claude/ralph-loop.local.md 文件。
2. Claude 处理该任务。
3. Claude 完成其回合（自然停止）。
4. 停止钩子 触发，在对话记录中检查是否存在 <promise>COMPLETION_PROMISE</promise>。
5. 未找到？ → 钩子返回 {"decision": "block", "reason": "..."}，Claude 继续。
6. 找到？ → 钩子允许停止，并清理状态文件。
7. 达到最大迭代次数？ → 钩子无条件允许停止。

要求

• Claude Code 1.0.20+
• jq（用于停止钩子中的 JSON 解析）

致谢

• Geoffrey Huntley — 原始 Ralph 技术
• Boris Cherny — 官方插件
• Ralph — 本可用的重实现

许可证

MIT