[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-Th0rgal--open-ralph-wiggum":3,"tool-Th0rgal--open-ralph-wiggum":64},[4,17,27,35,43,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",138956,2,"2026-04-05T11:33:21",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},3704,"NextChat","ChatGPTNextWeb\u002FNextChat","NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。\n\n这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。\n\nNextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。",87618,"2026-04-05T07:20:52",[13,26],{"id":44,"name":45,"github_repo":46,"description_zh":47,"stars":48,"difficulty_score":23,"last_commit_at":49,"category_tags":50,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,51,52,53,15,54,26,13,55],"数据工具","视频","插件","其他","音频",{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,54],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":70,"readme_en":71,"readme_zh":72,"quickstart_zh":73,"use_case_zh":74,"hero_image_url":75,"owner_login":76,"owner_name":77,"owner_avatar_url":78,"owner_bio":79,"owner_company":80,"owner_location":81,"owner_email":82,"owner_twitter":83,"owner_website":84,"owner_url":85,"languages":86,"stars":103,"forks":104,"last_commit_at":105,"license":106,"difficulty_score":23,"env_os":107,"env_gpu":108,"env_ram":108,"env_deps":109,"category_tags":118,"github_topics":119,"view_count":23,"oss_zip_url":125,"oss_zip_packed_at":125,"status":16,"created_at":126,"updated_at":127,"faqs":128,"releases":159},1374,"Th0rgal\u002Fopen-ralph-wiggum","open-ralph-wiggum","Type `ralph \"prompt\"` to start open code in a ralph loop. Also supports a prompt file & status check. Open Code, Claude Code, Codex, Copilot","open-ralph-wiggum 是一款专为开发者设计的命令行工具，旨在通过“拉尔夫·威格姆（Ralph Wiggum）”技术实现 AI 编程的自动化闭环。它的核心功能是让 AI 编程助手（如 Claude Code、OpenAI Codex、GitHub Copilot CLI 或 OpenCode）在同一个提示词下反复运行，直到任务完成。\n\n在传统模式下，AI 代理往往因缺乏持续反馈而中途出错或停滞。open-ralph-wiggum 解决了这一痛点：它构建了一个持久化的开发循环，每次迭代中，AI 都能读取上一次生成的代码文件和 Git 历史记录，从而自动发现错误、自我修正并逐步推进，无需人工频繁干预。这种机制特别适用于需要多步调试、复杂功能构建或修复失败测试的场景。\n\n该工具适合熟悉命令行的软件开发者和技术研究人员使用，尤其是那些希望提升 AI 编码效率、减少重复操作的用户。其独特亮点在于“多代理灵活性”，用户只需通过简单的 `--agent` 参数即可在不同主流 AI 模型间无缝切换，且无需安装额外插件。基于 Bun 和 TypeScript 构建，open-ralph-wi","open-ralph-wiggum 是一款专为开发者设计的命令行工具，旨在通过“拉尔夫·威格姆（Ralph Wiggum）”技术实现 AI 编程的自动化闭环。它的核心功能是让 AI 编程助手（如 Claude Code、OpenAI Codex、GitHub Copilot CLI 或 OpenCode）在同一个提示词下反复运行，直到任务完成。\n\n在传统模式下，AI 代理往往因缺乏持续反馈而中途出错或停滞。open-ralph-wiggum 解决了这一痛点：它构建了一个持久化的开发循环，每次迭代中，AI 都能读取上一次生成的代码文件和 Git 历史记录，从而自动发现错误、自我修正并逐步推进，无需人工频繁干预。这种机制特别适用于需要多步调试、复杂功能构建或修复失败测试的场景。\n\n该工具适合熟悉命令行的软件开发者和技术研究人员使用，尤其是那些希望提升 AI 编码效率、减少重复操作的用户。其独特亮点在于“多代理灵活性”，用户只需通过简单的 `--agent` 参数即可在不同主流 AI 模型间无缝切换，且无需安装额外插件。基于 Bun 和 TypeScript 构建，open-ralph-wiggum 轻量高效，让 AI 真正成为能够独立闭环完成任务的编程伙伴。","\u003Cp align=\"center\">\n  \u003Ch1 align=\"center\">Open Ralph Wiggum\u003C\u002Fh1>\n  \u003Ch3 align=\"center\">Autonomous Agentic Loop for Claude Code, Codex, Copilot CLI & OpenCode\u003C\u002Fh3>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FTh0rgal_open-ralph-wiggum_readme_216e8c34bc6e.webp\" alt=\"Open Ralph Wiggum - Iterative AI coding loop for Claude Code and Codex\" \u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cem>Works with \u003Cb>Claude Code\u003C\u002Fb>, \u003Cb>OpenAI Codex\u003C\u002Fb>, \u003Cb>Copilot CLI\u003C\u002Fb>, and \u003Cb>OpenCode\u003C\u002Fb> — switch agents with \u003Ccode>--agent\u003C\u002Fcode>.\u003C\u002Fem>\u003Cbr>\n  \u003Cem>Based on the \u003Ca href=\"https:\u002F\u002Fghuntley.com\u002Fralph\u002F\">Ralph Wiggum technique\u003C\u002Fa> by Geoffrey Huntley\u003C\u002Fem>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\u002Fblob\u002Fmaster\u002FLICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue.svg\" alt=\"MIT License\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fbuilt%20with-Bun%20%2B%20TypeScript-f472b6.svg\" alt=\"Built with Bun + TypeScript\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\u002Freleases\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002FTh0rgal\u002Fralph-wiggum?include_prereleases\" alt=\"Release\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#supported-agents\">Supported Agents\u003C\u002Fa> •\n  \u003Ca href=\"#what-is-open-ralph-wiggum\">What is Ralph?\u003C\u002Fa> •\n  \u003Ca href=\"#installation\">Installation\u003C\u002Fa> •\n  \u003Ca href=\"#quick-start\">Quick Start\u003C\u002Fa> •\n  \u003Ca href=\"#commands\">Commands\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>Tired of agents breaking your local environment?\u003C\u002Fstrong>\u003Cbr>\n  🏝️ \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fsandboxed.sh\">sandboxed.sh\u003C\u002Fa> gives each task an isolated Linux workspace. Self-hosted. Git-backed.\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  💬 \u003Cstrong>Join the community:\u003C\u002Fstrong> \u003Ca href=\"https:\u002F\u002Frelens.ai\u002Fcommunity\">relens.ai\u002Fcommunity\u003C\u002Fa>\n\u003C\u002Fp>\n\n---\n\n## Supported Agents\n\nOpen Ralph Wiggum works with multiple AI coding agents. Switch between them using the `--agent` flag:\n\n| Agent | Flag | Description |\n|-------|------|-------------|\n| **Claude Code** | `--agent claude-code` | Anthropic's Claude Code CLI for autonomous coding |\n| **Codex** | `--agent codex` | OpenAI's Codex CLI for AI-powered development |\n| **Copilot CLI** | `--agent copilot` | GitHub Copilot CLI for agentic coding |\n| **OpenCode** | `--agent opencode` | Default agent, open-source AI coding assistant |\n\n```bash\n# Use Claude Code\nralph \"Build a REST API\" --agent claude-code --max-iterations 10\n\n# Use OpenAI Codex\nralph \"Create a CLI tool\" --agent codex --max-iterations 10\n\n# Use Copilot CLI\nralph \"Refactor the auth module\" --agent copilot --max-iterations 10\n\n# Use OpenCode (default)\nralph \"Fix the failing tests\" --max-iterations 10\n```\n\n---\n\n## What is Open Ralph Wiggum?\n\nOpen Ralph Wiggum implements the **Ralph Wiggum technique** — an autonomous agentic loop where an AI coding agent (Claude Code, Codex, or OpenCode) receives the **same prompt repeatedly** until it completes a task. Each iteration, the AI sees its previous work in files and git history, enabling self-correction and incremental progress.\n\nThis is a **CLI tool** that wraps any supported AI coding agent in a persistent development loop. No plugins required — just install and run.\n\n```bash\n# The essence of the Ralph loop:\nwhile true; do\n  claude-code \"Build feature X. Output \u003Cpromise>DONE\u003C\u002Fpromise> when complete.\"  # or codex, opencode\ndone\n```\n\n**Why this works:** The AI doesn't talk to itself between iterations. It sees the same prompt each time, but the codebase has changed from previous iterations. This creates a powerful feedback loop where the agent iteratively improves its work until all tests pass.\n\n### Multi-Agent Flexibility\n\nSwitch between AI coding agents without changing your workflow:\n\n- **Claude Code** (`--agent claude-code`) — Anthropic's powerful coding agent\n- **Codex** (`--agent codex`) — OpenAI's code-specialized model\n- **Copilot CLI** (`--agent copilot`) — GitHub's agentic coding tool\n- **OpenCode** (`--agent opencode`) — Open-source default option\n\n## Key Features\n\n- **Multi-Agent Support** — Use Claude Code, Codex, or OpenCode with the same workflow\n- **Self-Correcting Loops** — Agent sees its previous work and fixes its own mistakes\n- **Autonomous Execution** — Set it running and come back to finished code\n- **Task Tracking** — Built-in task management with `--tasks` mode\n- **Live Monitoring** — Check progress with `--status` from another terminal\n- **Mid-Loop Hints** — Inject guidance with `--add-context` without stopping\n\n## Why Use an Agentic Loop?\n\n| Benefit | How it works |\n|---------|--------------|\n| **Self-Correction** | AI sees test failures from previous runs, fixes them |\n| **Persistence** | Walk away, come back to completed work |\n| **Iteration** | Complex tasks broken into incremental progress |\n| **Automation** | No babysitting—loop handles retries |\n| **Observability** | Monitor progress with `--status`, see history and struggle indicators |\n| **Mid-Loop Guidance** | Inject hints with `--add-context` without stopping the loop |\n\n## Installation\n\n**Prerequisites:**\n- [Bun](https:\u002F\u002Fbun.sh) runtime\n- At least one AI coding agent CLI:\n  - [Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code) — Anthropic's Claude Code CLI\n  - [Codex](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex) — OpenAI's Codex CLI\n  - [Copilot CLI](https:\u002F\u002Fgithub.com\u002Fgithub\u002Fcopilot-cli) — GitHub's Copilot CLI\n  - [OpenCode](https:\u002F\u002Fopencode.ai) — Open-source AI coding assistant\n\n### npm (recommended)\n\n```bash\nnpm install -g @th0rgal\u002Fralph-wiggum\n```\n\n### Bun\n\n```bash\nbun add -g @th0rgal\u002Fralph-wiggum\n```\n\n### From source\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\ncd open-ralph-wiggum\n.\u002Finstall.sh\n```\n\n```powershell\ngit clone https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\ncd open-ralph-wiggum\n.\\install.ps1\n```\n\nThis installs the `ralph` CLI command globally.\n\n## Quick Start\n\n```bash\n# Simple task with iteration limit\nralph \"Create a hello.txt file with 'Hello World'. Output \u003Cpromise>DONE\u003C\u002Fpromise> when complete.\" \\\n  --max-iterations 5\n\n# Build something real\nralph \"Build a REST API for todos with CRUD operations and tests. \\\n  Run tests after each change. Output \u003Cpromise>COMPLETE\u003C\u002Fpromise> when all tests pass.\" \\\n  --max-iterations 20\n\n# Use Claude Code instead of OpenCode\nralph \"Create a small CLI and document usage. Output \u003Cpromise>COMPLETE\u003C\u002Fpromise> when done.\" \\\n  --agent claude-code --model claude-sonnet-4 --max-iterations 5\n\n# Use Codex instead of OpenCode\nralph \"Create a small CLI and document usage. Output \u003Cpromise>COMPLETE\u003C\u002Fpromise> when done.\" \\\n  --agent codex --model gpt-5-codex --max-iterations 5\n\n# Use Copilot CLI\nralph \"Create a small CLI and document usage. Output \u003Cpromise>COMPLETE\u003C\u002Fpromise> when done.\" \\\n  --agent copilot --max-iterations 5\n\n# Complex project with Tasks Mode\nralph \"Build a full-stack web application with user auth and database\" \\\n  --tasks --max-iterations 50\n```\n\n## Environment Variables\n\nConfigure agent binaries with these environment variables:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `RALPH_OPENCODE_BINARY` | Path to OpenCode CLI | `\"opencode\"` |\n| `RALPH_CLAUDE_BINARY` | Path to Claude Code CLI | `\"claude\"` |\n| `RALPH_CODEX_BINARY` | Path to Codex CLI | `\"codex\"` |\n| `RALPH_COPILOT_BINARY` | Path to Copilot CLI | `\"copilot\"` |\n\n**Note for Windows users:** Ralph automatically resolves `.cmd` extensions for npm-installed CLIs. If you encounter \"command not found\" errors, you can use these environment variables to specify the full path to the executable.\n\n## Commands\n\n### Running a Loop\n\n```bash\nralph \"\u003Cprompt>\" [options]\n\nOptions:\n  --agent AGENT            AI agent to use: opencode (default), claude-code, codex, copilot\n  --min-iterations N       Minimum iterations before completion allowed (default: 1)\n  --max-iterations N       Stop after N iterations (default: unlimited)\n  --completion-promise T   Text that signals completion (default: COMPLETE)\n  --abort-promise TEXT     Phrase that signals early abort (e.g., precondition failed)\n  --tasks, -t              Enable Tasks Mode for structured task tracking\n  --task-promise T         Text that signals task completion (default: READY_FOR_NEXT_TASK)\n  --model MODEL            Model to use (agent-specific)\n  --rotation LIST          Agent\u002Fmodel rotation for each iteration (comma-separated)\n  --prompt-file, --file, -f  Read prompt content from a file\n  --prompt-template PATH   Use custom prompt template (see Custom Prompts)\n  --no-stream              Buffer agent output and print at the end\n  --verbose-tools          Print every tool line (disable compact tool summary)\n  --questions              Enable interactive question handling (default: enabled)\n  --no-questions           Disable interactive question handling (agent will loop on questions)\n  --no-plugins             Disable non-auth OpenCode plugins for this run (opencode only)\n  --no-commit              Don't auto-commit after iterations\n  --allow-all              Auto-approve all tool permissions (default: on)\n  --no-allow-all           Require interactive permission prompts\n  --config PATH            Use custom agent config file\n  --init-config [PATH]     Write default agent config to PATH and exit\n  --help                   Show help\n```\n\n### Tasks Mode\n\nTasks Mode allows you to break complex projects into smaller, manageable tasks. Ralph works on one task at a time and tracks progress in a markdown file.\n\n```bash\n# Enable Tasks Mode\nralph \"Build a complete web application\" --tasks --max-iterations 20\n\n# Custom task completion signal\nralph \"Multi-feature project\" --tasks --task-promise \"TASK_DONE\"\n```\n\n#### Task Management Commands\n\n```bash\n# List current tasks\nralph --list-tasks\n\n# Add a new task\nralph --add-task \"Implement user authentication\"\n\n# Remove task by index\nralph --remove-task 3\n\n# Show status (tasks shown automatically when tasks mode is active)\nralph --status\n```\n\n#### How Tasks Mode Works\n\n1. **Task File**: Tasks are stored in `.ralph\u002Fralph-tasks.md`\n2. **One Task Per Iteration**: Ralph focuses on a single task to reduce confusion\n3. **Automatic Progression**: When a task completes (`\u003Cpromise>READY_FOR_NEXT_TASK\u003C\u002Fpromise>`), Ralph moves to the next\n4. **Persistent State**: Tasks survive loop restarts\n5. **Focused Context**: Smaller contexts per iteration reduce costs and improve reliability\n\nTask status indicators:\n- `[ ]` - Not started\n- `[\u002F]` - In progress\n- `[x]` - Complete\n\nExample task file:\n```markdown\n# Ralph Tasks\n\n- [ ] Set up project structure\n- [x] Initialize git repository\n- [\u002F] Implement user authentication\n  - [ ] Create login page\n  - [ ] Add JWT handling\n- [ ] Build dashboard UI\n```\n\n### Custom Prompt Templates\n\nYou can fully customize the prompt sent to the agent using `--prompt-template`. This is useful for integrating with custom workflows or tools.\n\n```bash\nralph \"Build a REST API\" --prompt-template .\u002Fmy-template.md\n```\n\n**Available variables:**\n\n| Variable | Description |\n|----------|-------------|\n| `{{iteration}}` | Current iteration number |\n| `{{max_iterations}}` | Maximum iterations (or \"unlimited\") |\n| `{{min_iterations}}` | Minimum iterations |\n| `{{prompt}}` | The user's task prompt |\n| `{{completion_promise}}` | Completion promise text (e.g., \"COMPLETE\") |\n| `{{abort_promise}}` | Abort promise text (if configured) |\n| `{{task_promise}}` | Task promise text (for tasks mode) |\n| `{{context}}` | Additional context added mid-loop |\n| `{{tasks}}` | Task list content (for tasks mode) |\n\n**Example template (`my-template.md`):**\n\n```markdown\n# Iteration {{iteration}} \u002F {{max_iterations}}\n\n## Task\n{{prompt}}\n\n## Instructions\n1. Check beads for current status\n2. Decide what to do next\n3. When the epic in beads is complete, output:\n   \u003Cpromise>{{completion_promise}}\u003C\u002Fpromise>\n\n{{context}}\n```\n\n### Monitoring & Control\n\n```bash\n# Check status of active loop (run from another terminal)\nralph --status\n\n# Add context\u002Fhints for the next iteration\nralph --add-context \"Focus on fixing the auth module first\"\n\n# Clear pending context\nralph --clear-context\n```\n\n### Status Dashboard\n\nThe `--status` command shows:\n- **Active loop info**: Current iteration, elapsed time, prompt\n- **Pending context**: Any hints queued for next iteration\n- **Current tasks**: Automatically shown when tasks mode is active (or use `--tasks`)\n- **Iteration history**: Last 5 iterations with tools used, duration\n- **Struggle indicators**: Warnings if agent is stuck (no progress, repeated errors)\n\n```\n╔══════════════════════════════════════════════════════════════════╗\n║                    Ralph Wiggum Status                           ║\n╚══════════════════════════════════════════════════════════════════╝\n\n🔄 ACTIVE LOOP\n   Iteration:    3 \u002F 10\n   Elapsed:      5m 23s\n   Promise:      COMPLETE\n   Prompt:       Build a REST API...\n\n📊 HISTORY (3 iterations)\n   Total time:   5m 23s\n\n   Recent iterations:\n   🔄 #1: 2m 10s | Bash:5 Write:3 Read:2\n   🔄 #2: 1m 45s | Edit:4 Bash:3 Read:2\n   🔄 #3: 1m 28s | Bash:2 Edit:1\n\n⚠️  STRUGGLE INDICATORS:\n   - No file changes in 3 iterations\n   💡 Consider using: ralph --add-context \"your hint here\"\n```\n\n### Mid-Loop Context Injection\n\nGuide a struggling agent without stopping the loop:\n\n```bash\n# In another terminal while loop is running\nralph --add-context \"The bug is in utils\u002Fparser.ts line 42\"\nralph --add-context \"Try using the singleton pattern for config\"\n```\n\nContext is automatically consumed after one iteration.\n\n## Troubleshooting\n\n### Plugin errors\n\nThis package is **CLI-only**. If OpenCode tries to load a `ralph-wiggum` or `open-ralph-wiggum` plugin,\nremove it from your OpenCode `plugin` list (opencode.json), or run:\n\n```bash\nralph \"Your task\" --no-plugins\n```\n\n### ProviderModelNotFoundError \u002F Model not configured\n\nIf you see `ProviderModelNotFoundError` or \"Provider returned error\", you need to configure a default model:\n\n**For OpenCode:**\n1. Edit `~\u002F.config\u002Fopencode\u002Fopencode.json`:\n   ```json\n   {\n     \"$schema\": \"https:\u002F\u002Fopencode.ai\u002Fconfig.json\",\n     \"model\": \"your-provider\u002Fmodel-name\"\n   }\n   ```\n2. Or use the `--model` flag: `ralph \"task\" --model provider\u002Fmodel`\n\n**For other agents:**\nUse the `--model` flag to specify the model explicitly.\n\n### \"command not found\" on Windows\n\nRalph automatically tries `.cmd` extensions on Windows. If you still have issues:\n1. Set the full path using environment variables:\n   ```powershell\n   $env:RALPH_OPENCODE_BINARY = \"C:\\path\\to\\opencode.cmd\"\n   ```\n2. Or add the CLI to your PATH\n\n### \"bun: command not found\"\n\nInstall Bun: https:\u002F\u002Fbun.sh\n\n## Writing Good Prompts\n\n### Include Clear Success Criteria\n\n❌ Bad:\n```\nBuild a todo API\n```\n\n✅ Good:\n```\nBuild a REST API for todos with:\n- CRUD endpoints (GET, POST, PUT, DELETE)\n- Input validation\n- Tests for each endpoint\n\nRun tests after changes. Output \u003Cpromise>COMPLETE\u003C\u002Fpromise> when all tests pass.\n```\n\n### Use Verifiable Conditions\n\n❌ Bad:\n```\nMake the code better\n```\n\n✅ Good:\n```\nRefactor auth.ts to:\n1. Extract validation into separate functions\n2. Add error handling for network failures\n3. Ensure all existing tests still pass\n\nOutput \u003Cpromise>DONE\u003C\u002Fpromise> when refactored and tests pass.\n```\n\n### Always Set Max Iterations\n\n```bash\n# Safety net for runaway loops\nralph \"Your task\" --max-iterations 20\n```\n\n## Recommended PRD Format\n\nRalph treats prompt files as plain text, so any format works. For best results, use a concise PRD with:\n\n- **Goal**: one sentence summary of the desired outcome\n- **Scope**: what is in\u002Fout\n- **Requirements**: numbered, testable items\n- **Constraints**: tech stack, performance, security, compatibility\n- **Acceptance criteria**: explicit success checks\n- **Completion promise**: include `\u003Cpromise>COMPLETE\u003C\u002Fpromise>` (or match your `--completion-promise`)\n\nExample (Markdown):\n\n```markdown\n# PRD: Add Export Button\n\n## Goal\nLet users export reports as CSV from the dashboard.\n\n## Scope\n- In: export current report view\n- Out: background exports, scheduling\n\n## Requirements\n1. Add \"Export CSV\" button to dashboard header.\n2. CSV includes columns: date, revenue, sessions.\n3. Works for reports up to 10k rows.\n\n## Constraints\n- Keep current UI styling.\n- Use existing CSV utility in utils\u002Fcsv.ts.\n\n## Acceptance Criteria\n- Clicking button downloads a valid CSV.\n- CSV opens cleanly in Excel\u002FSheets.\n- All existing tests pass.\n\n## Completion Promise\n\u003Cpromise>COMPLETE\u003C\u002Fpromise>\n```\n\n### JSON Feature List (Recommended for Complex Projects)\n\nFor larger projects, a structured JSON feature list works better than prose. Based on [Anthropic's research on effective agent harnesses](https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Feffective-harnesses-for-long-running-agents), JSON format reduces the chance of agents inappropriately modifying test definitions.\n\nCreate a `features.json` file:\n\n```json\n{\n  \"features\": [\n    {\n      \"category\": \"functional\",\n      \"description\": \"Export button downloads CSV with current report data\",\n      \"steps\": [\n        \"Navigate to dashboard\",\n        \"Click 'Export CSV' button\",\n        \"Verify CSV file downloads\",\n        \"Open CSV and verify columns: date, revenue, sessions\",\n        \"Verify data matches displayed report\"\n      ],\n      \"passes\": false\n    },\n    {\n      \"category\": \"functional\",\n      \"description\": \"Export handles large reports up to 10k rows\",\n      \"steps\": [\n        \"Load report with 10,000 rows\",\n        \"Click 'Export CSV' button\",\n        \"Verify export completes without timeout\",\n        \"Verify all rows present in CSV\"\n      ],\n      \"passes\": false\n    },\n    {\n      \"category\": \"ui\",\n      \"description\": \"Export button matches existing dashboard styling\",\n      \"steps\": [\n        \"Navigate to dashboard\",\n        \"Verify button uses existing button component\",\n        \"Verify button placement in header area\"\n      ],\n      \"passes\": false\n    }\n  ]\n}\n```\n\nThen reference it in your prompt:\n\n```\nRead features.json for the feature list. Work through each feature one at a time.\nAfter verifying a feature works end-to-end, update its \"passes\" field to true.\nDo NOT modify the description or steps - only change the passes boolean.\nOutput \u003Cpromise>COMPLETE\u003C\u002Fpromise> when all features pass.\n```\n\n**Why JSON?** Agents are less likely to inappropriately modify JSON test definitions compared to Markdown. The structured format keeps agents focused on implementation rather than redefining success criteria.\n\n## When to Use Ralph\n\n**Good for:**\n- Tasks with automatic verification (tests, linters, type checking)\n- Well-defined tasks with clear completion criteria\n- Greenfield projects where you can walk away\n- Iterative refinement (getting tests to pass)\n\n**Not good for:**\n- Tasks requiring human judgment\n- One-shot operations\n- Unclear success criteria\n- Production debugging\n\n## How It Works\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                                                             │\n│   ┌──────────┐    same prompt    ┌──────────┐              │\n│   │          │ ───────────────▶  │          │              │\n│   │  ralph   │                   │ AI Agent │              │\n│   │   CLI    │ ◀─────────────── │          │              │\n│   │          │   output + files  │          │              │\n│   └──────────┘                   └──────────┘              │\n│        │                              │                     │\n│        │ check for                    │ modify              │\n│        │ \u003Cpromise>                    │ files               │\n│        ▼                              ▼                     │\n│   ┌──────────┐                   ┌──────────┐              │\n│   │ Complete │                   │   Git    │              │\n│   │   or     │                   │  Repo    │              │\n│   │  Retry   │                   │ (state)  │              │\n│   └──────────┘                   └──────────┘              │\n│                                                             │\n└─────────────────────────────────────────────────────────────┘\n```\n\n1. Ralph sends your prompt to the selected agent\n2. The agent works on the task, modifies files\n3. Ralph checks output for completion promise\n4. If not found, repeat with same prompt\n5. AI sees previous work in files\n6. Loop until success or max iterations\n\n## Project Structure\n\n```\nralph-wiggum\u002F\n├── bin\u002Fralph.js                  # CLI entrypoint (npm wrapper)\n├── ralph.ts                      # Main loop implementation\n├── package.json                  # Package config\n├── install.sh \u002F install.ps1     # Installation scripts\n└── uninstall.sh \u002F uninstall.ps1 # Uninstallation scripts\n```\n\n### State Files (in .ralph\u002F)\n\nDuring operation, Ralph stores state in `.ralph\u002F`:\n- `ralph-loop.state.json` - Active loop state\n- `ralph-history.json` - Iteration history and metrics\n- `ralph-context.md` - Pending context for next iteration\n- `ralph-tasks.md` - Task list for Tasks Mode (created when `--tasks` is used)\n- `ralph-questions.json` - Pending user answers to agent questions\n\n## Uninstall\n\n```bash\nnpm uninstall -g @th0rgal\u002Fralph-wiggum\n```\n\n```powershell\nnpm uninstall -g @th0rgal\u002Fralph-wiggum\n```\n\n## Agent-Specific Notes\n\n### Claude Code\n\n[Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code) is Anthropic's official CLI for Claude. Use it with Open Ralph Wiggum for powerful autonomous coding:\n\n```bash\nralph \"Refactor the auth module and ensure tests pass\" \\\n  --agent claude-code \\\n  --model claude-sonnet-4 \\\n  --max-iterations 15\n```\n\n### OpenAI Codex\n\n[Codex](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex) is OpenAI's code-specialized agent. Perfect for code generation and refactoring tasks:\n\n```bash\nralph \"Generate unit tests for all utility functions\" \\\n  --agent codex \\\n  --model gpt-5-codex \\\n  --max-iterations 10\n```\n\n### OpenCode\n\n[OpenCode](https:\u002F\u002Fopencode.ai) is an open-source AI coding assistant. It's the default agent:\n\n```bash\nralph \"Fix all TypeScript errors\" --max-iterations 10\n```\n\n### Copilot CLI\n\n[Copilot CLI](https:\u002F\u002Fgithub.com\u002Fgithub\u002Fcopilot-cli) is GitHub's agentic coding tool (public preview). It requires a GitHub Copilot subscription and authentication via `GH_TOKEN`, `GITHUB_TOKEN`, or prior `copilot \u002Flogin`.\n\n**Install:**\n```bash\nnpm install -g @github\u002Fcopilot\n# or\nbrew install copilot-cli\n```\n\n**Usage:**\n```bash\nralph \"Refactor the auth module and add tests\" \\\n  --agent copilot \\\n  --max-iterations 15\n\n# With a specific model\nralph \"Build a REST API\" \\\n  --agent copilot \\\n  --model claude-opus-4.6 \\\n  --max-iterations 10\n```\n\n**Notes:**\n- Default model is Claude Sonnet 4.5; override with `--model`\n- `--allow-all` (default) maps to `--allow-all` + `--no-ask-user` in Copilot CLI\n- `--no-plugins` has no effect with Copilot CLI\n- Authentication: set `GH_TOKEN` \u002F `GITHUB_TOKEN` env var, or run `copilot \u002Flogin` first\n\n## Agent Rotation\n\nAgent rotation lets you cycle through different agent\u002Fmodel combinations across iterations. This is useful for leveraging the strengths of different models or comparing their performance on a task.\n\n### Format\n\nEach rotation entry uses the `agent:model` format:\n\n```\n--rotation \"agent1:model1,agent2:model2,agent3:model3\"\n```\n\n**Valid agents:** `opencode`, `claude-code`, `codex`, `copilot`\n\n### Example Usage\n\n```bash\n# Alternate between OpenCode and Claude Code\nralph \"Build a REST API\" \\\n  --rotation \"opencode:claude-sonnet-4,claude-code:claude-sonnet-4\" \\\n  --max-iterations 10\n\n# Cycle through three different configurations\nralph \"Refactor the auth module\" \\\n  --rotation \"opencode:claude-sonnet-4,claude-code:claude-sonnet-4,codex:gpt-5-codex\" \\\n  --max-iterations 15\n\n# Include Copilot in the rotation\nralph \"Build a REST API\" \\\n  --rotation \"opencode:claude-sonnet-4,copilot:claude-sonnet-4\" \\\n  --max-iterations 10\n```\n\n### Flag Interaction\n\nWhen `--rotation` is used, the `--agent` and `--model` flags are **ignored**. The rotation list takes precedence for agent\u002Fmodel selection.\n\n### Cycling Behavior\n\nThe rotation cycles back to the first entry after reaching the end:\n\n- Iteration 1 → Entry 1\n- Iteration 2 → Entry 2\n- Iteration 3 → Entry 1 (wraps around for a 2-entry rotation)\n- ...and so on\n\n### Error Messages\n\nInvalid rotation entries produce clear error messages:\n\n**Invalid agent name:**\n```\nError: Invalid agent 'invalid' in rotation entry 'invalid:model'. Valid agents: opencode, claude-code, codex, copilot\n```\n\n**Malformed entry (missing colon):**\n```\nError: Invalid rotation entry 'opencode-model'. Expected format: agent:model\n```\n\n**Empty values:**\n```\nError: Invalid rotation entry 'opencode:'. Both agent and model are required.\n```\n\n### Status Display\n\nWhen using `--status` with an active rotation, the output shows all rotation entries and marks the current one:\n\n```\n🔄 ACTIVE LOOP\n   Iteration:    3 \u002F 10\n   Prompt:       Build a REST API...\n\n   Rotation (position 1\u002F2):\n   1. opencode:claude-sonnet-4  **ACTIVE**\n   2. claude-code:claude-sonnet-4\n```\n\n### Iteration History\n\nThe `--status` command shows which agent and model was used for each iteration:\n\n```\n📊 HISTORY (3 iterations)\n   Total time:   5m 23s\n\n   Recent iterations:\n   #1  2m 10s  opencode \u002F claude-sonnet-4  Bash(5) Write(3) Read(2)\n   #2  1m 45s  claude-code \u002F claude-sonnet-4  Edit(4) Bash(3) Read(2)\n   #3  1m 28s  opencode \u002F claude-sonnet-4  Bash(2) Edit(1)\n```\n\n## Learn More\n\n- [Original Ralph Wiggum technique by Geoffrey Huntley](https:\u002F\u002Fghuntley.com\u002Fralph\u002F)\n- [Ralph Orchestrator](https:\u002F\u002Fgithub.com\u002Fmikeyobrien\u002Fralph-orchestrator)\n\n## See Also\n\nCheck out 🏝️ [sandboxed.sh](https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fsandboxed.sh) — a dashboard for orchestrating AI agents with workspace management, real-time monitoring, and multi-agent workflows.\n\n## License\n\nMIT\n","\u003Cp align=\"center\">\n  \u003Ch1 align=\"center\">开启拉尔夫·维格姆\u003C\u002Fh1>\n  \u003Ch3 align=\"center\">面向 Claude Code、Codex、Copilot CLI 以及 OpenCode 的自主代理循环\u003C\u002Fh3>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FTh0rgal_open-ralph-wiggum_readme_216e8c34bc6e.webp\" alt=\"Open Ralph Wiggum — 面向 Claude Code 和 Codex 的迭代式 AI 编码循环\" \u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cem>可与\u003Cb>Claude Code\u003C\u002Fb>、\u003Cb>OpenAI Codex\u003C\u002Fb>、\u003Cb>Copilot CLI\u003C\u002Fb> 以及 \u003Cb>OpenCode\u003C\u002Fb> 无缝协作——只需使用 \u003Ccode>--agent\u003C\u002Fcode> 即可切换代理。\u003C\u002Fem>\u003Cbr>\n  \u003Cem>基于 Geoffrey Huntley 提出的 \u003Ca href=\"https:\u002F\u002Fghuntley.com\u002Fralph\u002F\">Ralph Wiggum 技术\u003C\u002Fa>\u003C\u002Fem>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\u002Fblob\u002Fmaster\u002FLICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue.svg\" alt=\"MIT 许可证\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fbuilt%20with-Bun%20%2B%20TypeScript-f472b6.svg\" alt=\"使用 Bun + TypeScript 构建\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\u002Freleases\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002FTh0rgal\u002Fralph-wiggum?include_prereleases\" alt=\"版本发布\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#supported-agents\">支持的代理\u003C\u002Fa> •\n  \u003Ca href=\"#what-is-open-ralph-wiggum\">什么是 Ralph?\u003C\u002Fa> •\n  \u003Ca href=\"#installation\">安装\u003C\u002Fa> •\n  \u003Ca href=\"#quick-start\">快速入门\u003C\u002Fa> •\n  \u003Ca href=\"#commands\">命令\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>厌倦了代理破坏你的本地环境吗？\u003C\u002Fstrong>\u003Cbr>\n  🏝️ 使用 \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fsandboxed.sh\">sandboxed.sh\u003C\u002Fa>，为每个任务提供一个隔离的 Linux 工作区。完全自托管，且数据存储在 Git 中。\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  💬 \u003Cstrong>加入社区：\u003C\u002Fstrong> \u003Ca href=\"https:\u002F\u002Frelens.ai\u002Fcommunity\">relens.ai\u002Fcommunity\u003C\u002Fa>\n\u003C\u002Fp>\n\n---\n\n## 支持的代理\n\nOpen Ralph Wiggum 可以与多种 AI 编码代理协同工作。只需使用 `--agent` 标志即可在它们之间自由切换：\n\n| 代理 | 标志 | 说明 |\n|-------|------|-------------|\n| **Claude Code** | `--agent claude-code` | Anthropic 的 Claude Code CLI，用于实现自主编码 |\n| **Codex** | `--agent codex` | OpenAI 的 Codex CLI，专为 AI 驱动的开发而设计 |\n| **Copilot CLI** | `--agent copilot` | GitHub Copilot CLI，用于代理式编码 |\n| **OpenCode** | `--agent opencode` | 默认代理，开源的 AI 编码助手 |\n\n```bash\n# 使用 Claude Code\nralph \"构建一个 REST API\" --agent claude-code --max-iterations 10\n\n# 使用 OpenAI Codex\nralph \"创建一个 CLI 工具\" --agent codex --max-iterations 10\n\n# 使用 Copilot CLI\nralph \"重构身份验证模块\" --agent copilot --max-iterations 10\n\n# 使用 OpenCode（默认）\nralph \"修复失败的测试\" --max-iterations 10\n```\n\n---\n\n## 什么是 Open Ralph Wiggum？\n\nOpen Ralph Wiggum 实现了 **Ralph Wiggum 技术**——一种自主代理循环：AI 编码代理（如 Claude Code、Codex 或 OpenCode）会反复接收相同的提示，直到完成任务。每次迭代时，AI 都能查看自己之前的工作成果以及 Git 历史记录，从而实现自我修正和逐步推进。\n\n这是一款 **CLI 工具**，可将任何受支持的 AI 编码代理封装进一个持久化的开发循环中。无需插件——只需安装并运行即可。\n\n```bash\n# Ralph 循环的核心：\nwhile true; do\n  claude-code \"构建功能 X。完成后输出 \u003Cpromise>DONE\u003C\u002Fpromise>。\"  # 或 codex、opencode\ndone\n```\n\n**为什么这样有效？** AI 在每次迭代之间不会彼此对话。它每次都会看到相同的提示，但代码库却已从之前的迭代中发生了变化。这种机制形成了强大的反馈回路：代理会不断迭代优化自己的工作，直至所有测试全部通过。\n\n### 多代理灵活性\n\n在不改变工作流程的前提下，轻松在不同 AI 编码代理之间切换：\n\n- **Claude Code** (`--agent claude-code`) — Anthropic 强大的编码代理\n- **Codex** (`--agent codex`) — OpenAI 专为代码优化的模型\n- **Copilot CLI** (`--agent copilot`) — GitHub 的代理式编码工具\n- **OpenCode** (`--agent opencode`) — 开源的默认选项\n\n## 核心功能\n\n- **多代理支持** — 采用相同的工作流，同时使用 Claude Code、Codex 或 OpenCode\n- **自我修正循环** — 代理能够看到自己之前的工作，并及时纠正错误\n- **自主执行** — 设置好循环后，随时返回到已完成的代码\n- **任务追踪** — 内置任务管理功能，支持使用 `--tasks` 模式\n- **实时监控** — 通过 `--status` 命令，在另一个终端中查看进度\n- **循环中期提示** — 无需中断，只需使用 `--add-context` 注入指导信息\n\n## 为什么选择代理式循环？\n\n| 优势 | 工作原理 |\n|---------|--------------|\n| **自我修正** | AI 能够识别并修复先前运行中出现的测试失败问题 |\n| **持久性** | 离开后，再次回到已完成的工作中 |\n| **迭代式推进** | 将复杂任务分解为多个逐步推进的环节 |\n| **自动化** | 无需人工看管——循环会自动处理重试 |\n| **可观察性** | 通过 `--status` 监控进展，查看历史记录和困难指标 |\n| **循环中期指导** | 通过 `--add-context` 注入提示，而不中断循环 |\n\n## 安装\n\n**前提条件：**\n- [Bun](https:\u002F\u002Fbun.sh) 运行时\n- 至少一种 AI 编码代理 CLI：\n  - [Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code) — Anthropic 的 Claude Code CLI\n  - [Codex](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex) — OpenAI 的 Codex CLI\n  - [Copilot CLI](https:\u002F\u002Fgithub.com\u002Fgithub\u002Fcopilot-cli) — GitHub 的 Copilot CLI\n  - [OpenCode](https:\u002F\u002Fopencode.ai) — 开源的 AI 编码助手\n\n### npm（推荐）\n\n```bash\nnpm install -g @th0rgal\u002Fralph-wiggum\n```\n\n### Bun\n\n```bash\nbun add -g @th0rgal\u002Fralph-wiggum\n```\n\n### 从源代码获取\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\ncd open-ralph-wiggum\n.\u002Finstall.sh\n```\n\n```powershell\ngit clone https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\ncd open-ralph-wiggum\n.\\install.ps1\n```\n\n此操作会将 `ralph` CLI 命令全局安装。\n\n## 快速入门\n\n```bash\n# 简单任务，设置迭代上限\nralph \"创建一个名为 'Hello World' 的 hello.txt 文件。完成后输出 \u003Cpromise>DONE\u003C\u002Fpromise>。\" \\\n  --max-iterations 5\n\n# 构建实际项目\nralph \"构建一个用于 todo 的 REST API，支持 CRUD 操作及测试。每次修改后运行测试。当所有测试通过时，输出 \u003Cpromise>COMPLETE\u003C\u002Fpromise>。\" \\\n  --max-iterations 20\n\n# 用 Claude Code 替代 OpenCode\nralph \"创建一个小型 CLI 并记录使用方法。完成后输出 \u003Cpromise>COMPLETE\u003C\u002Fpromise>。\" \\\n  --agent claude-code --model claude-sonnet-4 --max-iterations 5\n\n# 用 Codex 替代 OpenCode\nralph \"创建一个小型 CLI 并记录使用方法。完成后输出 \u003Cpromise>COMPLETE\u003C\u002Fpromise>。\" \\\n  --agent codex --model gpt-5-codex --max-iterations 5\n\n# 用 Copilot CLI\nralph \"创建一个小型 CLI 并记录使用方法。完成后输出 \u003Cpromise>COMPLETE\u003C\u002Fpromise>。\" \\\n  --agent copilot --max-iterations 5\n\n# 复杂项目，采用任务模式\nralph \"构建一个全栈 Web 应用，包含用户认证和数据库功能\" \\\n  --tasks --max-iterations 50\n```\n\n## 环境变量\n\n通过以下环境变量来配置代理二进制文件：\n\n| 变量 | 说明 | 默认值 |\n|------|-------|-------|\n| `RALPH_OPENCODE_BINARY` | OpenCode CLI 的路径 | `\"opencode\"` |\n| `RALPH_CLAUDE_BINARY` | Claude Code CLI 的路径 | `\"claude\"` |\n| `RALPH_CODEX_BINARY` | Codex CLI 的路径 | `\"codex\"` |\n| `RALPH_COPILOT_BINARY` | Copilot CLI 的路径 | `\"copilot\"` |\n\n**Windows 用户请注意：** Ralph 会自动为 npm 安装的 CLI 解析 `.cmd` 扩展名。若遇到“命令未找到”的错误，您可以使用这些环境变量来指定可执行文件的完整路径。\n\n## 命令\n\n### 运行循环\n\n```bash\nralph \"\u003Cprompt>\" [选项]\n\n选项：\n  --agent AGENT            要使用的 AI 代理：opencode（默认）、claude-code、codex、copilot\n  --min-iterations N       允许完成前的最小迭代次数（默认：1）\n  --max-iterations N       在达到 N 次迭代后停止（默认：无限制）\n  --completion-promise T   表示完成的文本（默认：COMPLETE）\n  --abort-promise TEXT     表示提前终止的短语（例如：前置条件失败）\n  --tasks, -t              启用任务模式，用于结构化任务跟踪\n  --task-promise T         表示任务完成的文本（默认：READY_FOR_NEXT_TASK）\n  --model MODEL            要使用的模型（仅限代理特定的模型）\n  --rotation LIST          每次迭代时的代理\u002F模型旋转顺序（以逗号分隔）\n  --prompt-file, --file, -f  从文件中读取提示内容\n  --prompt-template PATH   使用自定义提示模板（请参阅自定义提示）\n  --no-stream              缓存代理输出，并在末尾打印\n  --verbose-tools          打印每一条工具行（禁用紧凑的工具摘要）\n  --questions              启用交互式问题处理（默认启用）\n  --no-questions           禁用交互式问题处理（代理将对问题进行循环处理）\n  --no-plugins             禁用本次运行中的非认证 OpenCode 插件（仅适用于 opencode）\n  --no-commit              不在迭代结束后自动提交\n  --allow-all              自动批准所有工具权限（默认开启）\n  --no-allow-all           需要交互式权限提示\n  --config PATH            使用自定义代理配置文件\n  --init-config [PATH]     将默认代理配置写入 PATH 并退出\n  --help                   显示帮助信息\n```\n\n### 任务模式\n\n任务模式允许您将复杂项目拆分为更小、更易于管理的任务。Ralph 一次专注于一项任务，并在 Markdown 文件中记录进度。\n\n```bash\n# 启用任务模式\nralph \"构建一个完整的 Web 应用程序\" --tasks --max-iterations 20\n\n# 自定义任务完成信号\nralph \"多功能项目\" --tasks --task-promise \"TASK_DONE\"\n```\n\n#### 任务管理命令\n\n```bash\n# 列出当前任务\nralph --list-tasks\n\n# 添加新任务\nralph --add-task \"实现用户身份验证\"\n\n# 根据索引移除任务\nralph --remove-task 3\n\n# 显示状态（当任务模式启用时，任务会自动显示）\nralph --status\n```\n\n#### 任务模式的工作原理\n\n1. **任务文件**：任务存储在 `.ralph\u002Fralph-tasks.md` 中。\n2. **每次迭代一个任务**：Ralph 专注于单一任务，以减少混淆。\n3. **自动推进进度**：当某项任务完成时（\u003Cpromise>READY_FOR_NEXT_TASK\u003C\u002Fpromise>），Ralph 会继续下一个任务。\n4. **持久化状态**：任务在循环重启后依然保留。\n5. **专注的上下文**：每次迭代中更小的上下文能够降低成本并提升可靠性。\n\n任务状态指示器：\n- `[ ]` - 未开始\n- `[\u002F]` - 正在进行中\n- `[x]` - 已完成\n\n示例任务文件：\n```markdown\n# Ralph 任务\n\n- [ ] 设置项目结构\n- [x] 初始化 Git 仓库\n- [\u002F] 实现用户身份验证\n  - [ ] 创建登录页面\n  - [ ] 添加 JWT 处理\n- [ ] 构建仪表盘界面\n```\n\n### 自定义提示模板\n\n您可以完全自定义发送给代理的提示，使用 `--prompt-template`。这在与自定义工作流或工具集成时非常有用。\n\n```bash\nralph \"构建一个 REST API\" --prompt-template .\u002Fmy-template.md\n```\n\n**可用变量：**\n\n| 变量 | 说明 |\n|------|-------|\n| `{{iteration}}` | 当前迭代编号 |\n| `{{max_iterations}}` | 最大迭代次数（或“无限制”） |\n| `{{min_iterations}}` | 最小迭代次数 |\n| `{{prompt}}` | 用户的任务提示 |\n| `{{completion_promise}}` | 完成承诺文本（例如：“COMPLETE”） |\n| `{{abort_promise}}` | 中止承诺文本（如已配置） |\n| `{{task_promise}}` | 任务承诺文本（适用于任务模式） |\n| `{{context}}` | 在循环过程中添加的额外上下文 |\n| `{{tasks}}` | 任务列表内容（适用于任务模式） |\n\n**示例模板 (`my-template.md`):**\n\n```markdown\n# 迭代 {{iteration}} \u002F {{max_iterations}}\n\n## 任务\n{{prompt}}\n\n## 指令\n1. 检查珠子的当前状态\n2. 决定下一步该做什么\n3. 当珠子上的整个任务完成时，输出：\n   \u003Cpromise>{{completion_promise}}\u003C\u002Fpromise>\n\n{{context}}\n```\n\n### 监控与控制\n\n```bash\n# 检查活跃循环的状态（从另一个终端运行）\nralph --status\n\n# 为下一次迭代添加上下文\u002F提示\nralph --add-context \"重点先修复身份验证模块\"\n\n# 清空待处理的上下文\nralph --clear-context\n```\n\n### 状态仪表板\n\n`--status` 命令会显示：\n- **活跃循环信息**：当前迭代、已耗时、提示内容\n- **待处理的上下文**：任何已排队等待下一次迭代的提示\n- **当前任务**：当任务模式启用时会自动显示（或使用 `--tasks`）\n- **迭代历史**：最近 5 次迭代的工具使用情况及持续时间\n- **困难指标**：如果代理陷入停滞（无进展、重复报错），则会显示警告\n\n```\n╔══════════════════════════════════════════════════════════════════╗\n║                    Ralph Wiggum 状态                           ║\n╚══════════════════════════════════════════════════════════════════╝\n\n🔄 ACTIVE LOOP\n   迭代：    3 \u002F 10\n   已耗时： 5 分 23 秒\n   提示：      COMPLETE\n   提示内容： 构建一个 REST API...\n\n📊 历史记录（3 次迭代）\n   总耗时：   5 分 23 秒\n\n   最近几次迭代：\n   🔄 #1：2 分 10 秒 | Bash:5 写入:3 阅读:2\n   🔄 #2：1 分 45 秒 | 编辑:4 Bash:3 阅读:2\n   🔄 #3：1 分 28 秒 | Bash:2 编辑:1\n\n⚠️ 困难指标：\n   - 3 次迭代中未发生文件变更\n   💡 可考虑使用：ralph --add-context \"你的提示在这里\"\n```\n\n### 循环中注入上下文\n\n在循环运行期间，引导陷入困境的代理，而无需中断循环：\n\n```bash\n# 在另一个终端中，循环仍在运行\nralph --add-context \"错误出现在 utils\u002Fparser.ts 第 42 行\"\nralph --add-context \"尝试使用单例模式来管理配置\"\n```\n\n上下文会在一次迭代后自动被消耗。\n\n## 故障排除\n\n### 插件错误\n\n本包仅支持 CLI 使用。若 OpenCode 尝试加载 `ralph-wiggum` 或 `open-ralph-wiggum` 插件，\n请将其从 OpenCode 的 `plugin` 列表中移除（opencode.json），或运行：\n\n```bash\nralph \"您的任务\" --no-plugins\n```\n\n### 提供商模型未找到 \u002F 模型未配置\n\n如果您看到 `ProviderModelNotFoundError` 或“提供商会返回错误”，则需要配置一个默认模型：\n\n**对于 OpenCode：**\n1. 编辑 `~\u002F.config\u002Fopencode\u002Fopencode.json`：\n   ```json\n   {\n     \"$schema\": \"https:\u002F\u002Fopencode.ai\u002Fconfig.json\",\n     \"model\": \"your-provider\u002Fmodel-name\"\n   }\n   ```\n2. 或者使用 `--model` 标志：`ralph \"task\" --model provider\u002Fmodel`\n\n**对于其他代理：**\n请使用 `--model` 标志明确指定模型。\n\n### Windows 上出现“命令未找到”错误\n\nRalph 会在 Windows 系统中自动尝试使用 `.cmd` 扩展名。如果仍然遇到问题：\n1. 使用环境变量设置完整路径：\n   ```powershell\n   $env:RALPH_OPENCODE_BINARY = \"C:\\path\\to\\opencode.cmd\"\n   ```\n2. 或者将 CLI 添加到您的 PATH 中\n\n### “bun: 命令未找到”\n\n请安装 Bun：https:\u002F\u002Fbun.sh\n\n## 如何撰写优质提示词\n\n### 包含清晰的成功标准\n\n❌ 不佳示例：\n```\n构建一个待办事项 API\n```\n\n✅ 良好示例：\n```\n构建一个用于待办事项的 REST API，具备以下功能：\n- CRUD 接口（GET、POST、PUT、DELETE）\n- 输入验证\n- 对每个接口进行测试\n在代码变更后运行测试。当所有测试通过时，输出 `\u003Cpromise>COMPLETE\u003C\u002Fpromise>`。\n```\n\n### 使用可验证的条件\n\n❌ 不佳示例：\n```\n让代码变得更好\n```\n\n✅ 良好示例：\n```\n重构 auth.ts，具体步骤如下：\n1. 将验证逻辑提取至独立函数中\n2. 添加网络失败的错误处理机制\n3. 确保所有现有测试依然通过\n\n当重构完成且测试通过时，输出 `\u003Cpromise>DONE\u003C\u002Fpromise>`。\n```\n\n### 始终设置最大迭代次数\n\n```bash\n# 安全网，防止循环失控\nralph \"您的任务\" --max-iterations 20\n```\n\n## 推荐的 PRD 格式\n\nRalph 将提示词文件视为纯文本格式，因此任何格式均可使用。为获得最佳效果，请使用简洁明了的 PRD 文件，其中包含以下内容：\n- **目标**：一句话概括期望达成的结果\n- **范围**：明确哪些内容在内，哪些内容在外\n- **需求**：按编号列出、可测试的项目\n- **约束条件**：技术栈、性能、安全性、兼容性\n- **验收标准**：明确的成功验证条件\n- **完成承诺**：务必添加 `\u003Cpromise>COMPLETE\u003C\u002Fpromise>`（或与您的 `--completion-promise` 相匹配）\n\n示例（Markdown）：\n```markdown\n# PRD：添加导出按钮\n\n## 目标\n让用户能够从仪表板导出报表为 CSV 格式。\n\n## 范围\n- 在：导出当前报表视图\n- 在：后台导出并进行调度\n\n## 需求\n1. 在仪表板页眉处添加“导出 CSV”按钮。\n2. CSV 报表应包含以下列：日期、收入、会话数。\n3. 支持最多 1 万行的报表。\n\n## 约束条件\n- 保持当前的 UI 样式。\n- 使用 utils\u002Fcsv.ts 中已有的 CSV 工具。\n\n## 验收标准\n- 点击按钮后，可下载有效的 CSV 文件。\n- CSV 文件能顺利打开并显示在 Excel\u002FExcel 表格中。\n- 所有现有测试均通过。\n\n## 完成承诺\n\u003Cpromise>COMPLETE\u003C\u002Fpromise>\n```\n\n### JSON 功能列表（适用于复杂项目）\n\n对于大型项目，采用结构化的 JSON 功能列表比使用散文形式更有效。根据 [Anthropic 关于高效代理架构的研究](https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Feffective-harnesses-for-long-running-agents) 的发现，JSON 格式能够降低代理不当修改测试定义的风险。\n\n创建一个 `features.json` 文件：\n\n```json\n{\n  \"features\": [\n    {\n      \"category\": \"功能性\",\n      \"description\": \"导出按钮可下载包含当前报表数据的 CSV 文件\",\n      \"steps\": [\n        \"导航至仪表板\",\n        \"点击‘导出 CSV’按钮\",\n        \"验证 CSV 文件已成功下载\",\n        \"打开 CSV 文件并确认列：日期、收入、会话数\",\n        \"确保数据与报表中的实际内容一致\"\n      ],\n      \"passes\": false\n    },\n    {\n      \"category\": \"功能性\",\n      \"description\": \"导出功能可处理高达 1 万行的大型报表\",\n      \"steps\": [\n        \"加载包含 1 万行数据的报表\",\n        \"点击‘导出 CSV’按钮\",\n        \"验证导出过程无超时问题\",\n        \"确认 CSV 文件中包含所有所需行\"\n      ],\n      \"passes\": false\n    },\n    {\n      \"category\": \"UI\",\n      \"description\": \"导出按钮与现有仪表板风格相匹配\",\n      \"steps\": [\n        \"导航至仪表板\",\n        \"验证按钮是否使用了现有的按钮组件\",\n        \"确认按钮位于仪表板页眉区域\"\n      ],\n      \"passes\": false\n    }\n  ]\n}\n```\n\n随后，在提示词中引用该文件：\n\n```\n阅读 `features.json` 文件以了解功能列表。逐一完成每个功能的测试。\n在确认某个功能能够实现端到端的完整流程后，将该功能的 `passes` 字段更新为 `true`。\n切勿修改描述或步骤——仅需更改 `passes` 布尔值。\n当所有功能均通过测试时，输出 `\u003Cpromise>COMPLETE\u003C\u002Fpromise>`。\n```\n\n**为什么选择 JSON？** 与 Markdown 相比，代理更不容易对 JSON 测试定义进行不当修改。结构化的格式有助于代理专注于实现工作，而非重新定义成功标准。\n\n## 何时使用 Ralph\n\n**适合场景：**\n- 需要自动验证的任务（测试、Linter、类型检查）\n- 任务定义清晰、成功标准明确\n- 绿色开发项目，您可以随时退出\n- 迭代式优化（确保测试不断通过）\n\n**不适用场景：**\n- 需要人工判断的任务\n- 一次性操作\n- 成功标准不明确\n- 生产环境调试\n\n## 工作原理\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                                                             │\n│   ┌──────────┐    同样的提示词    ┌──────────┐              │\n│   │          │ ───────────────▶  │          │              │\n│   │  ralph   │                   │ AI 代理 │              │\n│   │  CLI    │ ◀─────────────── │          │              │\n│   │          │  输出 + 文件  │          │              │\n│   └──────────┘                   └──────────┘              │\n│        │                              │                     │\n│        │ 检查                        │ 修改                │\n│        │ \u003Cpromise>                    │ 文件                │\n│        ▼                              ▼                     │\n│   ┌──────────┐                   ┌──────────┐              │\n│   │ 完成 │                   │   Git    │              │\n│   │  重试   │                   │  仓库    │              │\n│   └──────────┘                   └──────────┘              │\n│                                                             │\n└─────────────────────────────────────────────────────────────┘\n```\n\n1. Ralph 将您的提示词发送给选定的代理\n2. 代理开始执行任务，并修改相关文件\n3. Ralph 检查输出结果，以确认是否满足完成承诺\n4. 若未达到预期，重复使用相同的提示词\n5. AI 会查看文件中之前已完成的工作\n6. 循环直至成功或达到最大迭代次数\n\n## 项目结构\n\n```\nralph-wiggum\u002F\n├── bin\u002Fralph.js                  # CLI 入口点（npm 包装器）\n├── ralph.ts                      # 主循环实现\n├── package.json                  # 包配置\n├── install.sh \u002F install.ps1     # 安装脚本\n└── uninstall.sh \u002F uninstall.ps1 # 卸载脚本\n```\n\n### 状态文件（位于 `.ralph\u002F` 目录下）\n\n在运行过程中，Ralph 会将状态存储于 `.ralph\u002F` 目录中：\n- `ralph-loop.state.json` — 活跃循环状态\n- `ralph-history.json` — 迭代历史与指标\n- `ralph-context.md` — 下一次迭代的待处理上下文\n- `ralph-tasks.md` — 任务模式下的任务列表（在使用 `--tasks` 参数时生成）\n- `ralph-questions.json` — 用户对客服人员问题的待处理回答\n\n## 卸载\n\n```bash\nnpm uninstall -g @th0rgal\u002Fralph-wiggum\n```\n\n```powershell\nnpm uninstall -g @th0rgal\u002Fralph-wiggum\n```\n\n## 代理特定注意事项\n\n### Claude Code\n\n[Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code) 是 Anthropic 为 Claude 提供的官方命令行工具。将其与 Open Ralph Wiggum 结合使用，可实现强大的自主代码编写功能：\n\n```bash\nralph \"重构身份验证模块，并确保测试通过\" \\\n  --agent claude-code \\\n  --model claude-sonnet-4 \\\n  --max-iterations 15\n```\n\n### OpenAI Codex\n\n[Codex](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex) 是 OpenAI 专为代码开发设计的代理工具，非常适合用于代码生成与重构任务：\n\n```bash\nralph \"为所有实用函数生成单元测试\" \\\n  --agent codex \\\n  --model gpt-5-codex \\\n  --max-iterations 10\n```\n\n### OpenCode\n\n[OpenCode](https:\u002F\u002Fopencode.ai) 是一款开源的 AI 编码助手，也是默认的代理工具：\n\n```bash\nralph \"修复所有 TypeScript 错误\" --max-iterations 10\n```\n\n### Copilot CLI\n\n[Copilot CLI](https:\u002F\u002Fgithub.com\u002Fgithub\u002Fcopilot-cli) 是 GitHub 的代理式代码生成工具（公测版）。使用该工具需订阅 GitHub Copilot 并通过 `GH_TOKEN`、`GITHUB_TOKEN` 或先前的 `copilot \u002Flogin` 进行身份验证。\n\n**安装：**\n```bash\nnpm install -g @github\u002Fcopilot\n# 或\nbrew install copilot-cli\n```\n\n**使用方法：**\n```bash\nralph \"重构身份验证模块并添加测试\" \\\n  --agent copilot \\\n  --max-iterations 15\n\n# 使用特定模型\nralph \"构建 REST API\" \\\n  --agent copilot \\\n  --model claude-opus-4.6 \\\n  --max-iterations 10\n```\n\n**注意事项：**\n- 默认模型为 Claude Sonnet 4.5；可通过 `--model` 参数进行覆盖。\n- `--allow-all`（默认值）等同于 Copilot CLI 中的 `--allow-all` + `--no-ask-user`。\n- `--no-plugins` 在 Copilot CLI 中无任何效果。\n- 身份验证：需设置环境变量 `GH_TOKEN` 或 `GITHUB_TOKEN`，或先运行 `copilot \u002Flogin`。\n\n## 代理轮换\n\n代理轮换功能允许您在多次迭代中交替使用不同的代理\u002F模型组合。这一功能非常适用于充分利用不同模型的优势，或对比它们在某项任务中的表现。\n\n### 格式\n\n每次轮换条目均采用 `agent:model` 的格式：\n\n```\n--rotation \"agent1:model1,agent2:model2,agent3:model3\"\n```\n\n**有效代理：** opencode、claude-code、codex、copilot\n\n### 示例用法\n\n```bash\n# 在 OpenCode 和 Claude Code 之间切换\nralph \"构建 REST API\" \\\n  --rotation \"opencode:claude-sonnet-4,claude-code:claude-sonnet-4\" \\\n  --max-iterations 10\n\n# 在三种不同配置间循环切换\nralph \"重构身份验证模块\" \\\n  --rotation \"opencode:claude-sonnet-4,claude-code:claude-sonnet-4,codex:gpt-5-codex\" \\\n  --max-iterations 15\n\n# 在轮换中加入 Copilot\nralph \"构建 REST API\" \\\n  --rotation \"opencode:claude-sonnet-4,copilot:claude-sonnet-4\" \\\n  --max-iterations 10\n```\n\n### 标志交互\n\n当使用 `--rotation` 时，`--agent` 和 `--model` 标志会被 **忽略**。轮换列表将优先作为代理\u002F模型选择的依据。\n\n### 循环行为\n\n当轮换到达末尾后，循环会回到第一个条目：\n\n- 第 1 次迭代 → 第 1 个条目\n- 第 2 次迭代 → 第 2 个条目\n- 第 3 次迭代 → 第 1 个条目（循环往复，形成 2 个条目的轮换）\n- ……以此类推\n\n### 错误提示\n\n无效的轮换条目会显示清晰的错误信息：\n\n**无效的代理名称：**\n```\nError: 无效的代理 'invalid' 在轮换条目 'invalid:model' 中。有效代理：opencode、claude-code、codex、copilot\n```\n\n**格式不正确（缺少冒号）：**\n```\nError: 无效的轮换条目 'opencode-model'。应遵循以下格式：agent:model\n```\n\n**空值：**\n```\nError: 无效的轮换条目 'opencode:'。代理和模型都必须填写。\n```\n\n### 状态显示\n\n当使用 `--status` 启动活跃轮换时，输出会显示所有轮换条目，并标记当前的轮换条目：\n\n```\n🔄 ACTIVE LOOP\n   迭代：    3 \u002F 10\n   提示：       构建 REST API...\n\n   轮换（位置 1\u002F2）：\n   1. opencode:claude-sonnet-4  **ACTIVE**\n   2. claude-code:claude-sonnet-4\n```\n\n### 迭代历史\n\n`--status` 命令会显示每次迭代所使用的代理和模型：\n\n```\n📊 HISTORY (3 次迭代)\n   总耗时：   5 分 23 秒\n\n   最近的迭代：\n   #1  2 分 10 秒  opencode \u002F claude-sonnet-4  Bash(5) Write(3) Read(2)\n   #2  1 分 45 秒  claude-code \u002F claude-sonnet-4  Edit(4) Bash(3) Read(2)\n   #3  1 分 28 秒  opencode \u002F claude-sonnet-4  Bash(2) Edit(1)\n```\n\n## 了解更多\n\n- [Geoffrey Huntley 原创的 Ralph Wiggum 技术](https:\u002F\u002Fghuntley.com\u002Fralph\u002F)\n- [Ralph Orchestrator](https:\u002F\u002Fgithub.com\u002Fmikeyobrien\u002Fralph-orchestrator)\n\n## 参考链接\n\n欢迎查看 🏝️ [sandboxed.sh](https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fsandboxed.sh) — 一个用于协调 AI 代理、管理工作区、实时监控以及多代理工作流的仪表盘。\n\n## 许可证\n\nMIT","# Open Ralph Wiggum 快速上手指南\n\nOpen Ralph Wiggum 是一个基于\"Ralph Wiggum 技术”的自主代理循环工具。它通过让 AI 编程助手（如 Claude Code、Codex、Copilot CLI 或 OpenCode）反复接收相同的提示，直到任务完成。在每次迭代中，AI 能看到之前的代码变更和 Git 历史，从而实现自我修正和增量开发。\n\n## 环境准备\n\n在开始之前，请确保您的系统满足以下要求：\n\n### 1. 运行时环境\n必须安装 **Bun** 运行时：\n```bash\n# macOS\u002FLinux\ncurl -fsSL https:\u002F\u002Fbun.sh\u002Finstall | bash\n\n# Windows (PowerShell)\npowershell -c \"irm bun.sh\u002Finstall.ps1 | iex\"\n```\n\n### 2. AI 编程助手 CLI\n您至少需要安装以下任意一个 AI 编程助手的命令行工具，并确保它们已在系统路径中可用：\n\n*   **Claude Code**: Anthropic 的官方 CLI\n*   **Codex**: OpenAI 的 Codex CLI\n*   **Copilot CLI**: GitHub Copilot CLI\n*   **OpenCode**: 开源 AI 编程助手（默认选项）\n\n> **注意**：请根据您选择的 Agent 提前完成对应的账号认证和配置（例如 `claude login` 或 `copilot auth`）。\n\n## 安装步骤\n\n推荐使用 npm 或 Bun 进行全局安装：\n\n### 方式一：使用 npm（推荐）\n```bash\nnpm install -g @th0rgal\u002Fralph-wiggum\n```\n\n### 方式二：使用 Bun\n```bash\nbun add -g @th0rgal\u002Fralph-wiggum\n```\n\n### 方式三：从源码安装\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\ncd open-ralph-wiggum\n.\u002Finstall.sh\n# Windows 用户请使用: .\\install.ps1\n```\n\n安装完成后，您可以在终端直接使用 `ralph` 命令。\n\n## 基本使用\n\n### 1. 运行一个简单的任务\n最基本的用法是直接传入任务描述。默认情况下，它会使用 **OpenCode** 作为代理，并持续运行直到检测到完成信号（默认为 `\u003Cpromise>COMPLETE\u003C\u002Fpromise>`）。\n\n```bash\nralph \"Create a hello.txt file with 'Hello World'. Output \u003Cpromise>DONE\u003C\u002Fpromise> when complete.\" --max-iterations 5\n```\n\n### 2. 切换不同的 AI 代理\n使用 `--agent` 参数可以轻松切换底层使用的 AI 工具：\n\n**使用 Claude Code:**\n```bash\nralph \"Build a REST API for todos with CRUD operations and tests. Run tests after each change. Output \u003Cpromise>COMPLETE\u003C\u002Fpromise> when all tests pass.\" --agent claude-code --max-iterations 20\n```\n\n**使用 OpenAI Codex:**\n```bash\nralph \"Create a CLI tool\" --agent codex --max-iterations 10\n```\n\n**使用 GitHub Copilot CLI:**\n```bash\nralph \"Refactor the auth module\" --agent copilot --max-iterations 10\n```\n\n### 3. 启用任务模式 (Tasks Mode)\n对于复杂项目，可以使用 `--tasks` 模式将大目标拆解为小任务。Ralph 会自动管理 `.ralph\u002Fralph-tasks.md` 文件，逐个完成任务。\n\n```bash\nralph \"Build a full-stack web application with user auth and database\" --tasks --max-iterations 50\n```\n\n在此模式下，当 AI 输出 `\u003Cpromise>READY_FOR_NEXT_TASK\u003C\u002Fpromise>` 时，会自动进入下一个子任务。\n\n### 4. 监控与干预\n您可以在另一个终端窗口监控运行状态或注入新的上下文提示，而无需停止循环：\n\n**查看当前状态：**\n```bash\nralph --status\n```\n\n**在运行中注入提示（例如指导修复方向）：**\n```bash\nralph --add-context \"Focus on fixing the auth module first\"\n```\n\n### 常用参数速查\n*   `--agent [name]`: 指定代理 (opencode, claude-code, codex, copilot)\n*   `--max-iterations N`: 最大迭代次数\n*   `--completion-promise TEXT`: 自定义完成信号文本\n*   `--tasks`: 开启任务管理模式\n*   `--model MODEL`: 指定具体模型版本","某后端工程师需要在周五下班前紧急重构一个遗留的支付模块，该模块包含复杂的边界条件且缺乏文档，必须确保所有单元测试通过才能上线。\n\n### 没有 open-ralph-wiggum 时\n- **陷入“对话疲劳”**：开发者需手动将每次代码修改后的报错信息复制粘贴回 AI 对话框，反复解释上下文，导致注意力分散在维护对话状态而非解决逻辑问题上。\n- **迭代中断频繁**：当 AI 生成的代码未完全通过测试时，开发者必须人工介入分析失败原因并重新编写提示词，难以让 AI 自主进行连续的自我修正。\n- **多模型切换成本高**：若想尝试用 Claude Code 或 Codex 等不同模型解决同一难题，需要分别配置环境并重新输入冗长的任务背景，流程繁琐。\n- **进度难以量化**：缺乏自动化的循环机制，无法设定“直到测试全绿”的明确终止条件，往往在多次不成功的尝试后被迫放弃或降低代码质量。\n\n### 使用 open-ralph-wiggum 后\n- **实现全自动闭环**：只需执行 `ralph \"重构支付模块并通过所有测试\"`，open-ralph-wiggum 会自动将相同的指令循环发送给 AI，利用 Git 历史让 AI 基于最新代码状态自我纠错。\n- **持续增量优化**：AI 在每次迭代中都能“看到”上一次运行产生的文件变化和测试报错，无需人工转述，自动逐步修复 Bug 直至任务完成。\n- **灵活切换大脑**：若发现当前模型效果不佳，可立即通过 `--agent codex` 或 `--agent claude-code` 参数无缝切换底层驱动模型，复用同一套工作流验证不同策略。\n- **可控的交付标准**：通过设置 `--max-iterations` 参数控制最大尝试次数，确保任务在限定资源内朝着“测试全绿”的目标稳步推进，避免无限空转。\n\nopen-ralph-wiggum 通过将单次提示转化为具备记忆和自我修正能力的自动化开发循环，彻底解放了开发者在复杂重构任务中的重复劳动。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FTh0rgal_open-ralph-wiggum_216e8c34.webp","Th0rgal","Thomas Marchand","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FTh0rgal_98012dbd.png","23, french.","LFG Labs","Lisbon","thomas@lfglabs.dev","Th0rgal_","thomas.md","https:\u002F\u002Fgithub.com\u002FTh0rgal",[87,91,95,99],{"name":88,"color":89,"percentage":90},"TypeScript","#3178c6",94.8,{"name":92,"color":93,"percentage":94},"PowerShell","#012456",2.5,{"name":96,"color":97,"percentage":98},"Shell","#89e051",2.2,{"name":100,"color":101,"percentage":102},"JavaScript","#f1e05a",0.4,1416,112,"2026-04-05T06:16:08","MIT","Linux, macOS, Windows","未说明",{"notes":110,"python":111,"dependencies":112},"该工具是一个命令行包装器，本身不运行 AI 模型，而是调用外部的 AI 编码代理（如 Claude Code、Codex 等）。因此没有特定的 GPU 或内存需求，具体取决于所选用的外部代理的要求。主要运行环境要求是安装 Bun 运行时以及至少一种支持的 AI 代理 CLI。Windows 用户需注意该工具会自动解析 npm 安装 CLI 的 .cmd 扩展名。","不需要 (基于 Bun 运行时)",[113,114,115,116,117],"Bun","Claude Code CLI","OpenAI Codex CLI","GitHub Copilot CLI","OpenCode CLI",[26,15,53],[120,121,122,123,124],"claude-code","open-code","opencode","ralph","ralph-wiggum",null,"2026-03-27T02:49:30.150509","2026-04-06T05:44:33.926785",[129,134,139,144,149,154],{"id":130,"question_zh":131,"answer_zh":132,"source_url":133},6312,"Ralph 只创建了 README 文件而没有生成实际的代码文件（如 .tsx, .jsx），如何解决？","这通常是因为当前使用的 AI 模型能力不足或指令遵循能力较弱。建议切换到更强大的编码专用模型，例如从 `gpt-oss-20b` 切换到 `qwen3-coder-next`。更换模型后，Ralph 通常能正确执行创建代码文件的任务。","https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\u002Fissues\u002F27",{"id":135,"question_zh":136,"answer_zh":137,"source_url":138},6313,"运行 Ralph 时遇到 \"Unable to connect\" 错误怎么办？","该错误通常源于 OpenCode 配置而非 Ralph 本身。可能原因包括：API 密钥未配置、网络无法访问提供商端点、或模型已废弃。\n调试步骤：\n1. 直接运行 `opencode run \"hello world\"` 测试连接。\n2. 检查配置文件 `cat ~\u002F.config\u002Fopencode\u002Fopencode.json`。\n3. 尝试通过 `--model` 标志切换模型，例如：`ralph \"implement hello world\" --model anthropic\u002Fclaude-sonnet-4`。\n如果 `opencode run` 直接失败，请参照 OpenCode 文档修复配置。","https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\u002Fissues\u002F24",{"id":140,"question_zh":141,"answer_zh":142,"source_url":143},6314,"AI 经常在第一次迭代后就过早停止工作，如何强制它执行更多次迭代？","可以使用 `--min-iterations` 标志来设定最小迭代次数，防止 AI 因过早判断任务完成而退出。这对于需要多步推理或容易中途放弃的任务非常有用。你也可以结合 `--max-iterations` 使用，或者使用 `--iterations` 指定确切的迭代次数。","https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\u002Fissues\u002F10",{"id":145,"question_zh":146,"answer_zh":147,"source_url":148},6315,"如何在 Windows 上安装和运行 Ralph？","Windows 用户现在可以使用全局安装模式，无需手动运行 shell 脚本。只需确保已安装 Bun，然后运行以下命令：\n```powershell\nbun i -g @th0rgal\u002Fralph-wiggum@latest\n```\n安装完成后即可直接使用 `ralph` 命令。如果遇到特定错误，请检查日志文件（通常位于 `%USERPROFILE%\\.local\\share\\opencode\\log\\`）以获取详细信息。","https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\u002Fissues\u002F2",{"id":150,"question_zh":151,"answer_zh":152,"source_url":153},6316,"使用 Claude Code 时提示 \"Credit balance is too low\"，但实际我有订阅计划，如何解决？","这通常是因为 Ralph 默认调用了 API Token 计费模式，而未识别到你的订阅计划（Plan Token）。目前需要在运行命令时明确指定代理或检查环境变量配置，确保 Claude Code 优先使用账户内的订阅额度而非按量计费的 API Key。具体配置需检查 OpenCode 或 Claude Code 的认证设置，确保加载了正确的凭证类型。","https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\u002Fissues\u002F41",{"id":155,"question_zh":156,"answer_zh":157,"source_url":158},6317,"在哪里可以找到社区交流、讨论技巧或获取帮助？","项目维护者建议访问 [relens.ai\u002Fcommunity](https:\u002F\u002Frelens.ai\u002Fcommunity) 加入社区。此外，维护者也计划在 GitHub 仓库中开启 Discussions 板块，或建立 Telegram\u002FDiscord 群组以便用户交流工作流技巧和故障排除。","https:\u002F\u002Fgithub.com\u002FTh0rgal\u002Fopen-ralph-wiggum\u002Fissues\u002F31",[160,165,170,175,180],{"id":161,"version":162,"summary_zh":163,"released_at":164},105874,"v1.2.2","Deduplicated code, narrowed types, config validation","2026-02-22T12:42:07",{"id":166,"version":167,"summary_zh":168,"released_at":169},105875,"v1.2.1","- Version bump to 1.2.1 (sync package and runtime --version output)","2026-02-13T11:57:27",{"id":171,"version":172,"summary_zh":173,"released_at":174},105876,"v1.1.0","## What's New\n\n### Multi-Agent Support\n- Added support for **Claude Code** and **Codex** in addition to OpenCode\n- Use `--agent claude` or `--agent codex` to switch agents\n- Cross-platform agent detection using `Bun.which()` instead of Unix-only `which`\n- Install scripts now detect and report available agents\n\n### Tasks Mode\n- New structured task tracking with `--tasks` flag\n- Task file stored in `.ralph\u002Fralph-tasks.md` with markdown checkbox format\n- Commands: `--list-tasks`, `--add-task`, `--remove-task`, `--task-promise`\n- One-task-per-iteration workflow for reduced context and improved reliability\n- Task status: `[ ]` todo, `[\u002F]` in-progress, `[x]` complete\n- Automatic task progression on completion signal\n\n### New Flags\n- `--no-allow-all` - Disable auto-approve for interactive permission prompts\n- `--min-iterations` - Enforce minimum loop iterations before completion\n- `--task-promise` - Customize task completion signal (default: READY_FOR_NEXT_TASK)\n\n### Improvements\n- Permission flags now correctly positioned before positional arguments\n- `--status` automatically shows tasks when tasks mode is active\n- JSDoc documentation for internal APIs\n\n### Bug Fixes\n- Fixed cross-platform agent validation\n- Fixed Codex `--full-auto` flag ordering\n- Fixed task removal to include all indented content (notes, subtasks)\n\n## Contributors\nCo-authored-by: Cameron King (Tasks Mode implementation from PR #14)","2026-01-23T15:01:30",{"id":176,"version":177,"summary_zh":178,"released_at":179},105877,"v1.0.9","## What's New\n\n### Added\n- **Interactive permission approval**: When opencode prompts for tool permissions, you can now type to approve them directly. This provides a middle ground between fully autonomous (`--allow-all`) and the process hanging.\n\n### Changed\n- stdin is now passed through to opencode, enabling interactive responses when needed","2026-01-15T16:43:00",{"id":181,"version":182,"summary_zh":183,"released_at":184},105878,"v1.0.8","## What's New\n\n### Added\n- `--allow-all` flag for non-interactive permission auto-approval\n  - When running ralph in non-interactive environments (CI, automated workflows), opencode may prompt for tool permissions that cannot be approved because there's no stdin\n  - This flag creates a config that auto-approves all tool permissions, enabling fully autonomous operation\n  - Usage: `ralph \"your task\" --allow-all`","2026-01-15T16:40:08"]