[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-michaelshimeles--ralphy":3,"tool-michaelshimeles--ralphy":62},[4,18,28,37,45,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":24,"last_commit_at":25,"category_tags":26,"status":17},9989,"n8n","n8n-io\u002Fn8n","n8n 是一款面向技术团队的公平代码（fair-code）工作流自动化平台，旨在让用户在享受低代码快速构建便利的同时，保留编写自定义代码的灵活性。它主要解决了传统自动化工具要么过于封闭难以扩展、要么完全依赖手写代码效率低下的痛点，帮助用户轻松连接 400 多种应用与服务，实现复杂业务流程的自动化。\n\nn8n 特别适合开发者、工程师以及具备一定技术背景的业务人员使用。其核心亮点在于“按需编码”：既可以通过直观的可视化界面拖拽节点搭建流程，也能随时插入 JavaScript 或 Python 代码、调用 npm 包来处理复杂逻辑。此外，n8n 原生集成了基于 LangChain 的 AI 能力，支持用户利用自有数据和模型构建智能体工作流。在部署方面，n8n 提供极高的自由度，支持完全自托管以保障数据隐私和控制权，也提供云端服务选项。凭借活跃的社区生态和数百个现成模板，n8n 让构建强大且可控的自动化系统变得简单高效。",184740,2,"2026-04-19T23:22:26",[16,14,13,15,27],"插件",{"id":29,"name":30,"github_repo":31,"description_zh":32,"stars":33,"difficulty_score":10,"last_commit_at":34,"category_tags":35,"status":17},10095,"AutoGPT","Significant-Gravitas\u002FAutoGPT","AutoGPT 是一个旨在让每个人都能轻松使用和构建 AI 的强大平台，核心功能是帮助用户创建、部署和管理能够自动执行复杂任务的连续型 AI 智能体。它解决了传统 AI 应用中需要频繁人工干预、难以自动化长流程工作的痛点，让用户只需设定目标，AI 即可自主规划步骤、调用工具并持续运行直至完成任务。\n\n无论是开发者、研究人员，还是希望提升工作效率的普通用户，都能从 AutoGPT 中受益。开发者可利用其低代码界面快速定制专属智能体；研究人员能基于开源架构探索多智能体协作机制；而非技术背景用户也可直接选用预置的智能体模板，立即投入实际工作场景。\n\nAutoGPT 的技术亮点在于其模块化“积木式”工作流设计——用户通过连接功能块即可构建复杂逻辑，每个块负责单一动作，灵活且易于调试。同时，平台支持本地自托管与云端部署两种模式，兼顾数据隐私与使用便捷性。配合完善的文档和一键安装脚本，即使是初次接触的用户也能在几分钟内启动自己的第一个 AI 智能体。AutoGPT 正致力于降低 AI 应用门槛，让人人都能成为 AI 的创造者与受益者。",183572,"2026-04-20T04:47:55",[13,36,27,14,15],"语言模型",{"id":38,"name":39,"github_repo":40,"description_zh":41,"stars":42,"difficulty_score":10,"last_commit_at":43,"category_tags":44,"status":17},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,"2026-04-05T11:01:52",[14,15,13],{"id":46,"name":47,"github_repo":48,"description_zh":49,"stars":50,"difficulty_score":24,"last_commit_at":51,"category_tags":52,"status":17},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 真正成长为懂上",161147,"2026-04-19T23:31:47",[14,13,36],{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":59,"last_commit_at":60,"category_tags":61,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,27],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":68,"readme_en":69,"readme_zh":70,"quickstart_zh":71,"use_case_zh":72,"hero_image_url":73,"owner_login":74,"owner_name":75,"owner_avatar_url":76,"owner_bio":77,"owner_company":78,"owner_location":79,"owner_email":78,"owner_twitter":80,"owner_website":81,"owner_url":82,"languages":83,"stars":100,"forks":101,"last_commit_at":102,"license":78,"difficulty_score":24,"env_os":103,"env_gpu":104,"env_ram":104,"env_deps":105,"category_tags":115,"github_topics":116,"view_count":24,"oss_zip_url":78,"oss_zip_packed_at":78,"status":17,"created_at":120,"updated_at":121,"faqs":122,"releases":153},10121,"michaelshimeles\u002Fralphy","ralphy","My Ralph Wiggum setup, an autonomous bash script that runs Claude Code, Codex, OpenCode, Cursor agent, Qwen & Droid in a loop until your PRD is complete.","Ralphy 是一款自主 AI 编码循环工具，旨在帮助开发者自动化完成软件开发任务。它通过运行一个 Bash 脚本，将 Claude Code、Cursor、Qwen 等多种主流 AI 编程助手串联起来，形成闭环工作流。用户只需输入自然语言指令或提供产品需求文档（PRD），Ralphy 就能自动调度不同的 AI 代理持续执行任务，直到所有功能开发完毕或需求列表清空。\n\n这款工具主要解决了单一 AI 模型在处理复杂、多步骤开发任务时可能出现的上下文丢失、中途停滞或需要人工反复干预的问题。它特别适合全栈开发者、技术负责人以及希望提升原型开发效率的工程师使用。无论是修复单个 Bug、添加深色模式，还是依据详细的 PRD 文档构建完整功能模块，Ralphy 都能胜任。\n\n其技术亮点在于强大的灵活性与兼容性：支持多种任务输入格式（Markdown、YAML、JSON 甚至 GitHub Issues），允许用户自定义项目规则与代码边界以保障安全，并能并行启动多个 AI 代理协同工作。此外，它还提供了丰富的引擎切换与参数透传功能，让开发者可以自由选择底层大模型或传递特定 CLI 参数，真正实现“一","Ralphy 是一款自主 AI 编码循环工具，旨在帮助开发者自动化完成软件开发任务。它通过运行一个 Bash 脚本，将 Claude Code、Cursor、Qwen 等多种主流 AI 编程助手串联起来，形成闭环工作流。用户只需输入自然语言指令或提供产品需求文档（PRD），Ralphy 就能自动调度不同的 AI 代理持续执行任务，直到所有功能开发完毕或需求列表清空。\n\n这款工具主要解决了单一 AI 模型在处理复杂、多步骤开发任务时可能出现的上下文丢失、中途停滞或需要人工反复干预的问题。它特别适合全栈开发者、技术负责人以及希望提升原型开发效率的工程师使用。无论是修复单个 Bug、添加深色模式，还是依据详细的 PRD 文档构建完整功能模块，Ralphy 都能胜任。\n\n其技术亮点在于强大的灵活性与兼容性：支持多种任务输入格式（Markdown、YAML、JSON 甚至 GitHub Issues），允许用户自定义项目规则与代码边界以保障安全，并能并行启动多个 AI 代理协同工作。此外，它还提供了丰富的引擎切换与参数透传功能，让开发者可以自由选择底层大模型或传递特定 CLI 参数，真正实现“一次配置，全自动交付”的高效开发体验。","# Ralphy\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fralphy-cli.svg)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fralphy-cli)\n\n**[Join our Discord](https:\u002F\u002Fdiscord.gg\u002FSZZV74mCuV)** - Questions? Want to contribute? Join the community!\n\n![Ralphy](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmichaelshimeles_ralphy_readme_48d7811dc326.jpeg)\n\nAutonomous AI coding loop. Runs AI agents on tasks until done.\n\n## Install\n\n**Option A: [npm](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fralphy-cli)** (recommended)\n```bash\nnpm install -g ralphy-cli\n\n# Then use anywhere\nralphy \"add login button\"\nralphy --prd PRD.md\n```\n\n**Option B: Clone**\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fmichaelshimeles\u002Fralphy.git\ncd ralphy && chmod +x ralphy.sh\n\n.\u002Fralphy.sh \"add login button\"\n.\u002Fralphy.sh --prd PRD.md\n```\n\nBoth versions have identical features. Examples below use `ralphy` (npm) - substitute `.\u002Fralphy.sh` if using the bash script.\n\n## Two Modes\n\n**Single task** - just tell it what to do:\n```bash\nralphy \"add dark mode\"\nralphy \"fix the auth bug\"\n```\n\n**Task list** - work through a PRD:\n```bash\nralphy              # uses PRD.md\nralphy --prd tasks.md\n```\n\n## Project Config\n\nOptional. Stores rules the AI must follow.\n\n```bash\nralphy --init              # auto-detects project settings\nralphy --config            # view config\nralphy --add-rule \"use TypeScript strict mode\"\n```\n\nCreates `.ralphy\u002Fconfig.yaml`:\n```yaml\nproject:\n  name: \"my-app\"\n  language: \"TypeScript\"\n  framework: \"Next.js\"\n\ncommands:\n  test: \"npm test\"\n  lint: \"npm run lint\"\n  build: \"npm run build\"\n\nrules:\n  - \"use server actions not API routes\"\n  - \"follow error pattern in src\u002Futils\u002Ferrors.ts\"\n\nboundaries:\n  never_touch:\n    - \"src\u002Flegacy\u002F**\"\n    - \"*.lock\"\n```\n\nRules apply to all tasks (single or PRD).\n\n## AI Engines\n\n```bash\nralphy              # Claude Code (default)\nralphy --opencode   # OpenCode\nralphy --cursor     # Cursor\nralphy --codex      # Codex\nralphy --qwen       # Qwen-Code\nralphy --droid      # Factory Droid\nralphy --copilot    # GitHub Copilot\nralphy --gemini     # Gemini CLI\n```\n\n### Model Override\n\nOverride the default model for any engine:\n\n```bash\nralphy --model sonnet \"add feature\"                    # use sonnet with Claude\nralphy --sonnet \"add feature\"                          # shortcut for above\nralphy --opencode --model opencode\u002Fglm-4.7-free \"task\" # custom OpenCode model\nralphy --qwen --model qwen-max \"build api\"             # custom Qwen model\n```\n\n### Engine-Specific Arguments\n\nPass additional arguments to the underlying engine CLI using `--` separator:\n\n```bash\n# Pass copilot-specific arguments\nralphy --copilot --model \"claude-opus-4.5\" --prd PRD.md -- --allow-all-tools --allow-all-urls --stream on\n\n# Pass claude-specific arguments  \nralphy --claude \"add feature\" -- --no-permissions-prompt\n\n# Works with any engine\nralphy --cursor \"fix bug\" -- --custom-arg value\n```\n\nEverything after `--` is passed directly to the engine CLI without interpretation.\n\n## Task Sources\n\n**Markdown file** (default):\n```bash\nralphy --prd PRD.md\n```\n```markdown\n## Tasks\n- [ ] create auth\n- [ ] add dashboard\n- [x] done task (skipped)\n```\n\n**Markdown folder** (for large projects):\n```bash\nralphy --prd .\u002Fprd\u002F\n```\nWhen pointing to a folder, Ralphy reads all `.md` files and aggregates tasks:\n```\nprd\u002F\n  backend.md      # - [ ] create user API\n  frontend.md     # - [ ] add login page\n  infra.md        # - [ ] setup CI\u002FCD\n```\nTasks are tracked per-file so completion updates the correct file.\n\n**YAML**:\n```bash\nralphy --yaml tasks.yaml\n```\n```yaml\ntasks:\n  - title: create auth\n    completed: false\n  - title: add dashboard\n    completed: false\n```\n\n**JSON**:\n```bash\nralphy --json PRD.json\n```\n```json\n{\n  \"tasks\": [\n    {\n      \"title\": \"create auth\",\n      \"completed\": false,\n      \"parallel_group\": 1,\n      \"description\": \"Optional details\"\n    }\n  ]\n}\n```\nTitles must be unique.\n\n**GitHub Issues**:\n```bash\nralphy --github owner\u002Frepo\nralphy --github owner\u002Frepo --github-label \"ready\"\n```\n\n## Parallel Execution\n\n```bash\nralphy --parallel                  # 3 agents default\nralphy --parallel --max-parallel 5 # 5 agents\n```\n\nEach agent gets isolated worktree + branch:\n```\nAgent 1 → \u002Ftmp\u002Fxxx\u002Fagent-1 → ralphy\u002Fagent-1-create-auth\nAgent 2 → \u002Ftmp\u002Fxxx\u002Fagent-2 → ralphy\u002Fagent-2-add-dashboard\nAgent 3 → \u002Ftmp\u002Fxxx\u002Fagent-3 → ralphy\u002Fagent-3-build-api\n```\n\nWithout `--create-pr`: auto-merges back to base branch, AI resolves conflicts.\nWith `--create-pr`: keeps branches, creates PRs.\nWith `--no-merge`: keeps branches without merging or creating PRs.\n\n**YAML parallel groups** - control execution order:\n```yaml\ntasks:\n  - title: Create User model\n    parallel_group: 1\n  - title: Create Post model\n    parallel_group: 1  # same group = runs together\n  - title: Add relationships\n    parallel_group: 2  # runs after group 1\n```\n\n## Branch Workflow\n\n```bash\nralphy --branch-per-task                # branch per task\nralphy --branch-per-task --create-pr    # + create PRs\nralphy --branch-per-task --draft-pr     # + draft PRs\nralphy --base-branch main               # branch from main\n```\n\nBranch naming: `ralphy\u002F\u003Ctask-slug>`\n\n## Browser Automation\n\nRalphy can use [agent-browser](https:\u002F\u002Fagent-browser.dev) to automate browser interactions during tasks.\n\n```bash\nralphy \"test the login flow\" --browser    # force enable\nralphy \"add checkout\" --no-browser        # force disable\nralphy \"build feature\"                    # auto-detect (default)\n```\n\nWhen enabled, the AI gets browser commands:\n- `agent-browser open \u003Curl>` - navigate to URL\n- `agent-browser snapshot` - get element refs (@e1, @e2)\n- `agent-browser click @e1` - click element\n- `agent-browser type @e1 \"text\"` - type into input\n- `agent-browser screenshot \u003Cfile>` - capture screenshot\n\n**Use cases:**\n- Testing UI after implementing features\n- Verifying deployments\n- Form filling and workflow testing\n\n**Config** (`.ralphy\u002Fconfig.yaml`):\n```yaml\ncapabilities:\n  browser: \"auto\"  # \"auto\", \"true\", or \"false\"\n```\n\n## Webhook Notifications\n\nGet notified when sessions complete via Discord, Slack, or custom webhooks.\n\n**Config** (`.ralphy\u002Fconfig.yaml`):\n```yaml\nnotifications:\n  discord_webhook: \"https:\u002F\u002Fdiscord.com\u002Fapi\u002Fwebhooks\u002F...\"\n  slack_webhook: \"https:\u002F\u002Fhooks.slack.com\u002Fservices\u002F...\"\n  custom_webhook: \"https:\u002F\u002Fyour-api.com\u002Fwebhook\"\n```\n\nNotifications include task completion counts and status (completed\u002Ffailed).\n\n## Sandbox Mode\n\nFor large repos with big dependency directories, sandbox mode is faster than git worktrees:\n\n```bash\nralphy --parallel --sandbox\n```\n\n**How it works:**\n- **Symlinks** read-only dependencies (`node_modules`, `.git`, `vendor`, `.venv`, `.pnpm-store`, `.yarn`, `.cache`)\n- **Copies** source files that agents might modify (`src\u002F`, `app\u002F`, `lib\u002F`, config files, etc.)\n\n**Why use it:**\n- Avoids duplicating gigabytes of `node_modules` across worktrees\n- Much faster sandbox creation for large monorepos\n- Changes sync back to original directory after each task\n\n**When to use worktrees instead (default):**\n- Need full git history access in each sandbox\n- Running `git` commands that require a real repo\n- Smaller repos where worktree overhead is minimal\n\n**Parallel execution reliability:**\n- If worktree operations fail (e.g., nested worktree repos), ralphy falls back to sandbox mode automatically\n- Retryable rate-limit or quota errors are detected and deferred for later retry\n- Local changes are stashed before the merge phase and restored after\n- Agents should not modify PRD files, `.ralphy\u002Fprogress.txt`, `.ralphy-worktrees`, or `.ralphy-sandboxes`\n\n## Options\n\n| Flag | What it does |\n|------|--------------|\n| `--prd PATH` | task file or folder (auto-detected, default: PRD.md) |\n| `--yaml FILE` | YAML task file |\n| `--json FILE` | JSON task file |\n| `--github REPO` | use GitHub issues |\n| `--github-label TAG` | filter issues by label |\n| `--sync-issue N` | sync PRD progress to GitHub issue #N |\n| `--model NAME` | override model for any engine |\n| `--sonnet` | shortcut for `--claude --model sonnet` |\n| `--parallel` | run parallel |\n| `--max-parallel N` | max agents (default: 3) |\n| `--sandbox` | use lightweight sandboxes instead of git worktrees |\n| `--no-merge` | skip auto-merge in parallel mode |\n| `--branch-per-task` | branch per task |\n| `--base-branch NAME` | base branch |\n| `--create-pr` | create PRs |\n| `--draft-pr` | draft PRs |\n| `--no-tests` | skip tests |\n| `--no-lint` | skip lint |\n| `--fast` | skip tests + lint |\n| `--no-commit` | don't auto-commit |\n| `--max-iterations N` | stop after N tasks |\n| `--max-retries N` | retries per task (default: 3) |\n| `--retry-delay N` | seconds between retries |\n| `--dry-run` | preview only |\n| `--browser` | enable browser automation |\n| `--no-browser` | disable browser automation |\n| `-v, --verbose` | debug output |\n| `--init` | setup .ralphy\u002F config |\n| `--config` | show config |\n| `--add-rule \"rule\"` | add rule to config |\n\n## Requirements\n\n**Required:**\n- AI CLI: [Claude Code](https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-code), [OpenCode](https:\u002F\u002Fopencode.ai\u002Fdocs\u002F), [Cursor](https:\u002F\u002Fcursor.com), Codex, Qwen-Code, [Factory Droid](https:\u002F\u002Fdocs.factory.ai\u002Fcli\u002Fgetting-started\u002Fquickstart), [GitHub Copilot](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Fhow-tos\u002Fuse-copilot-agents\u002Fuse-copilot-cli), or [Gemini CLI](https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli)\n\n**npm version (`ralphy-cli`):**\n- Node.js 18+ or Bun\n\n**Bash version (`ralphy.sh`):**\n- `jq`\n- `yq` (optional, for YAML tasks)\n- `bc` (optional, for cost calc)\n\n**Both versions:**\n- `gh` (optional, for GitHub issues \u002F `--create-pr`)\n- [agent-browser](https:\u002F\u002Fagent-browser.dev) (optional, for `--browser`)\n\n## Engine Details\n\n| Engine | CLI | Permissions | Output |\n|--------|-----|-------------|--------|\n| Claude | `claude` | `--dangerously-skip-permissions` | tokens + cost |\n| OpenCode | `opencode` | `full-auto` | tokens + cost |\n| Codex | `codex` | N\u002FA | tokens |\n| Cursor | `agent` | `--force` | duration |\n| Qwen | `qwen` | `--approval-mode yolo` | tokens |\n| Droid | `droid exec` | `--auto medium` | duration |\n| Copilot | `copilot` | `--yolo` | tokens |\n| Gemini | `gemini` | `--yolo` | tokens + cost |\n\nWhen an engine exits non-zero, ralphy includes the last lines of CLI output in the error message to make debugging easier.\n\n---\n\n## Changelog\n\n### v4.7.2\n- **Improved auth error detection**: simplified `extractAuthenticationError` function with better edge case handling (e.g., JSON dumps during login)\n- **Added project standards**: `CLAUDE.md`, `.cursorrules`, `CONTRIBUTING.md` for consistent AI-assisted development\n- **Enhanced default prompts**: enforce concise, focused code changes\n\n### v4.7.1\n- **Copilot engine improvements**: non-interactive mode (`--yolo`), proper error detection for auth\u002Frate-limit\u002Fnetwork errors, token usage parsing, temp file-based prompts for markdown preservation\n- **Fixed infinite retry loop**: tasks now properly abort on fatal configuration\u002Fauthentication errors\n- **Project standards**: added `.editorconfig` and `.gitattributes` for consistent coding styles\n\n### v4.7.0\n- **JSON PRD support**: new `--json` flag to use JSON files as task sources with support for parallel groups and task descriptions\n\n### v4.6.0\n- **Gemini CLI support**: new `--gemini` engine option for Google Gemini CLI\n- **GitHub issue sync**: `--sync-issue \u003Cnumber>` syncs PRD progress to a GitHub issue after each task\n- **performance improvements**: reduced redundant file reads, exponential backoff for retries, non-blocking logging, operation timing visibility\n- **version fix**: CLI version now reads dynamically from package.json\n\n### v4.5.3\n- parallel reliability: fallback to sandbox mode on worktree errors\n- error output: include CLI output snippet for failed engine commands\n- retry handling: detect rate-limit\u002Fquota errors and stop early\n- merge safety: stash local changes before merge phase and restore after\n- prompts: explicitly avoid PRD and `.ralphy` progress\u002Fsandbox\u002Fworktree edits\n\n### v4.5.0\n- **sandbox mode**: lightweight isolation using symlinks for dependencies (faster than worktrees)\n- **performance improvements**: task caching, parallel merge analysis, smart branch ordering\n- **webhook notifications**: Discord, Slack, and custom webhooks for session completion (configure in `.ralphy\u002Fconfig.yaml`)\n- **engine-specific arguments**: pass arguments to underlying CLI via `--` separator\n- **Windows improvements**: better error handling for .cmd wrappers\n\n### v4.4.1\n- Windows line ending handling fixes\n- Windows Bun command resolution fixes\n\n### v4.4.0\n- GitHub Copilot CLI support (`--copilot`)\n\n### v4.3.0\n- model override: `--model \u003Cname>` flag to override model for any engine\n- `--sonnet` shortcut for `--claude --model sonnet`\n- `--no-merge` flag to skip auto-merge in parallel mode\n- AI-assisted merge conflict resolution during parallel auto-merge\n- root user detection: error for Claude\u002FCursor, warning for other engines\n- improved OpenCode error handling and model override support\n\n### v4.2.0\n- browser automation: `--browser` \u002F `--no-browser` with [agent-browser](https:\u002F\u002Fagent-browser.dev)\n- auto-detects agent-browser when available\n- config option: `capabilities.browser` in `.ralphy\u002Fconfig.yaml`\n\n### v4.1.0\n- TypeScript CLI: `npm install -g ralphy-cli`\n- cross-platform binaries (macOS, Linux, Windows)\n- no dependencies on jq\u002Fyq\u002Fbc for npm version\n\n### v4.0.0\n- single-task mode: `ralphy \"task\"` without PRD\n- project config: `--init` creates `.ralphy\u002F` with rules + auto-detection\n- new: `--config`, `--add-rule`, `--no-commit`\n\n### v3.3.0\n- Factory Droid support (`--droid`)\n\n### v3.2.0\n- Qwen-Code support (`--qwen`)\n\n### v3.1.0\n- Cursor support (`--cursor`)\n- better task verification\n\n### v3.0.0\n- parallel execution with worktrees\n- branch-per-task + auto-PR\n- YAML + GitHub Issues sources\n- parallel groups\n\n### v2.0.0\n- OpenCode support\n- retry logic\n- `--max-iterations`, `--dry-run`\n\n### v1.0.0\n- initial release\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.\n\n**Key principles:**\n- Keep changes small and focused - one logical change per commit\n- Break large tasks into micro-tasks\n- Quality over speed\n- Don't leave dead code\n- Fight entropy - leave the codebase better than you found it\n\nAI coding assistants can reference:\n- [CLAUDE.md](CLAUDE.md) - Claude Code instructions\n- [.cursorrules](.cursorrules) - Cursor IDE rules\n\n## Community\n\n- [Discord](https:\u002F\u002Frasmic.link\u002Fdiscord)\n\n## License\n\nMIT\n","# Ralphy\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fralphy-cli.svg)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fralphy-cli)\n\n**[加入我们的 Discord](https:\u002F\u002Fdiscord.gg\u002FSZZV74mCuV)** - 有问题？想贡献代码？快来加入社区吧！\n\n![Ralphy](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmichaelshimeles_ralphy_readme_48d7811dc326.jpeg)\n\n自主 AI 编码循环。持续运行 AI 代理处理任务，直到完成。\n\n## 安装\n\n**选项 A：[npm](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fralphy-cli)**（推荐）\n```bash\nnpm install -g ralphy-cli\n\n# 然后在任何地方使用\nralphy \"添加登录按钮\"\nralphy --prd PRD.md\n```\n\n**选项 B：克隆**\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fmichaelshimeles\u002Fralphy.git\ncd ralphy && chmod +x ralphy.sh\n\n.\u002Fralphy.sh \"添加登录按钮\"\n.\u002Fralphy.sh --prd PRD.md\n```\n\n两种方式功能完全相同。以下示例使用 `ralphy`（npm），如果使用 bash 脚本，请替换为 `.\u002Fralphy.sh`。\n\n## 两种模式\n\n**单任务** - 只需告诉它要做什么：\n```bash\nralphy \"添加暗黑模式\"\nralphy \"修复认证 bug\"\n```\n\n**任务列表** - 按照产品需求文档逐步执行：\n```bash\nralphy              # 使用 PRD.md\nralphy --prd tasks.md\n```\n\n## 项目配置\n\n可选。用于存储 AI 必须遵循的规则。\n\n```bash\nralphy --init              # 自动检测项目设置\nralphy --config            # 查看配置\nralphy --add-rule \"使用 TypeScript 严格模式\"\n```\n\n会创建 `.ralphy\u002Fconfig.yaml` 文件：\n```yaml\nproject:\n  name: \"my-app\"\n  language: \"TypeScript\"\n  framework: \"Next.js\"\n\ncommands:\n  test: \"npm test\"\n  lint: \"npm run lint\"\n  build: \"npm run build\"\n\nrules:\n  - \"使用服务器动作而非 API 路由\"\n  - \"遵循 src\u002Futils\u002Ferrors.ts 中的错误模式\"\n\nboundaries:\n  never_touch:\n    - \"src\u002Flegacy\u002F**\"\n    - \"*.lock\"\n```\n\n这些规则适用于所有任务（无论是单个任务还是 PRD）。\n\n## AI 引擎\n\n```bash\nralphy              # Claude Code（默认）\nralphy --opencode   # OpenCode\nralphy --cursor     # Cursor\nralphy --codex      # Codex\nralphy --qwen       # Qwen-Code\nralphy --droid      # Factory Droid\nralphy --copilot    # GitHub Copilot\nralphy --gemini     # Gemini CLI\n```\n\n### 模型覆盖\n\n可以为任何引擎覆盖默认模型：\n\n```bash\nralphy --model sonnet \"添加功能\"                    # 使用 Claude 的 Sonnet 模型\nralphy --sonnet \"添加功能\"                          # 上面的快捷方式\nralphy --opencode --model opencode\u002Fglm-4.7-free \"任务\" # 自定义 OpenCode 模型\nralphy --qwen --model qwen-max \"构建 API\"             # 自定义 Qwen 模型\n```\n\n### 引擎特定参数\n\n使用 `--` 分隔符传递底层引擎 CLI 的额外参数：\n\n```bash\n# 传递 Copilot 特定参数\nralphy --copilot --model \"claude-opus-4.5\" --prd PRD.md -- --allow-all-tools --allow-all-urls --stream on\n\n# 传递 Claude 特定参数  \nralphy --claude \"添加功能\" -- --no-permissions-prompt\n\n# 适用于任何引擎\nralphy --cursor \"修复 bug\" -- --custom-arg value\n```\n\n`--` 之后的所有内容都会直接传递给引擎 CLI，而不会被解析。\n\n## 任务来源\n\n**Markdown 文件**（默认）：\n```bash\nralphy --prd PRD.md\n```\n```markdown\n## 任务\n- [ ] 创建认证\n- [ ] 添加仪表盘\n- [x] 已完成任务（已跳过）\n```\n\n**Markdown 文件夹**（适用于大型项目）：\n```bash\nralphy --prd .\u002Fprd\u002F\n```\n当指向一个文件夹时，Ralphy 会读取所有 `.md` 文件并汇总任务：\n```\nprd\u002F\n  backend.md      # - [ ] 创建用户 API\n  frontend.md     # - [ ] 添加登录页面\n  infra.md        # - [ ] 设置 CI\u002FCD\n```\n任务按文件跟踪，因此完成状态会更新到正确的文件中。\n\n**YAML**：\n```bash\nralphy --yaml tasks.yaml\n```\n```yaml\ntasks:\n  - title: 创建认证\n    completed: false\n  - title: 添加仪表盘\n    completed: false\n```\n\n**JSON**：\n```bash\nralphy --json PRD.json\n```\n```json\n{\n  \"tasks\": [\n    {\n      \"title\": \"创建认证\",\n      \"completed\": false,\n      \"parallel_group\": 1,\n      \"description\": \"可选详情\"\n    }\n  ]\n}\n```\n标题必须唯一。\n\n**GitHub Issues**：\n```bash\nralphy --github owner\u002Frepo\nralphy --github owner\u002Frepo --github-label \"ready\"\n```\n\n## 并行执行\n\n```bash\nralphy --parallel                  # 默认 3 个代理\nralphy --parallel --max-parallel 5 # 5 个代理\n```\n\n每个代理都有独立的工作树和分支：\n```\n代理 1 → \u002Ftmp\u002Fxxx\u002Fagent-1 → ralphy\u002Fagent-1-create-auth\n代理 2 → \u002Ftmp\u002Fxxx\u002Fagent-2 → ralphy\u002Fagent-2-add-dashboard\n代理 3 → \u002Ftmp\u002Fxxx\u002Fagent-3 → ralphy\u002Fagent-3-build-api\n```\n\n如果没有 `--create-pr`：自动合并回主分支，AI 会解决冲突。  \n如果有 `--create-pr`：保留分支并创建 PR。  \n如果有 `--no-merge`：保留分支，不合并也不创建 PR。\n\n**YAML 并行组** - 控制执行顺序：\n```yaml\ntasks:\n  - title: 创建用户模型\n    parallel_group: 1\n  - title: 创建帖子模型\n    parallel_group: 1  # 同一组会同时执行\n  - title: 添加关系\n    parallel_group: 2  # 在第 1 组之后执行\n```\n\n## 分支工作流\n\n```bash\nralphy --branch-per-task                # 每个任务一个分支\nralphy --branch-per-task --create-pr    # 同时创建 PR\nralphy --branch-per-task --draft-pr     # 同时创建草稿 PR\nralphy --base-branch main               # 从 main 分支开始\n```\n\n分支命名格式：`ralphy\u002F\u003Ctask-slug>`\n\n## 浏览器自动化\n\nRalphy 可以使用 [agent-browser](https:\u002F\u002Fagent-browser.dev) 自动化浏览器交互。\n\n```bash\nralphy \"测试登录流程\" --browser    # 强制启用\nralphy \"添加结账功能\" --no-browser  # 强制禁用\nralphy \"构建功能\"                    # 自动检测（默认）\n```\n\n启用后，AI 会获得以下浏览器命令：\n- `agent-browser open \u003Curl>` - 导航到指定 URL\n- `agent-browser snapshot` - 获取元素引用（@e1, @e2）\n- `agent-browser click @e1` - 点击元素\n- `agent-browser type @e1 \"text\"` - 在输入框中输入文本\n- `agent-browser screenshot \u003Cfile>` - 截取屏幕截图\n\n**应用场景**：\n- 实现功能后测试 UI\n- 验证部署\n- 填写表单和测试工作流\n\n**配置**（`.ralphy\u002Fconfig.yaml`）：\n```yaml\ncapabilities:\n  browser: \"auto\"  # \"auto\", \"true\" 或 \"false\"\n```\n\n## Webhook 通知\n\n通过 Discord、Slack 或自定义 webhook，在会话完成时接收通知。\n\n**配置**（`.ralphy\u002Fconfig.yaml`）：\n```yaml\nnotifications:\n  discord_webhook: \"https:\u002F\u002Fdiscord.com\u002Fapi\u002Fwebhooks\u002F...\"\n  slack_webhook: \"https:\u002F\u002Fhooks.slack.com\u002Fservices\u002F...\"\n  custom_webhook: \"https:\u002F\u002Fyour-api.com\u002Fwebhook\"\n```\n\n通知内容包括任务完成数量和状态（已完成\u002F失败）。\n\n## 沙盒模式\n\n对于包含大型依赖目录的大规模代码库，沙盒模式比 Git 工作树更快：\n\n```bash\nralphy --parallel --sandbox\n```\n\n**工作原理：**\n- **符号链接** 用于只读依赖项（`node_modules`、`.git`、`vendor`、`.venv`、`.pnpm-store`、`.yarn`、`.cache`）\n- **复制** 代理可能修改的源文件（`src\u002F`、`app\u002F`、`lib\u002F`、配置文件等）\n\n**为何使用：**\n- 避免在多个工作树中重复存储数 GB 的 `node_modules`\n- 对于大型 monorepo，沙盒创建速度显著提升\n- 每个任务完成后，更改会同步回原始目录\n\n**何时改用工作树（默认）：**\n- 需要在每个沙盒中访问完整的 Git 历史记录\n- 需要执行需要真实仓库的 `git` 命令\n- 对于工作树开销较小的小型仓库\n\n**并行执行的可靠性：**\n- 如果工作树操作失败（例如嵌套的工作树仓库），ralphy 会自动回退到沙盒模式\n- 可重试的速率限制或配额错误会被检测并推迟到后续重试\n- 在合并阶段之前，本地更改会被暂存，并在合并后恢复\n- 代理不应修改 PRD 文件、`.ralphy\u002Fprogress.txt`、`.ralphy-worktrees` 或 `.ralphy-sandboxes`\n\n## 选项\n\n| 标志 | 功能 |\n|------|------|\n| `--prd PATH` | 任务文件或文件夹（自动检测，默认：PRD.md） |\n| `--yaml FILE` | YAML 任务文件 |\n| `--json FILE` | JSON 任务文件 |\n| `--github REPO` | 使用 GitHub 问题 |\n| `--github-label TAG` | 按标签筛选问题 |\n| `--sync-issue N` | 将 PRD 进度同步到 GitHub 问题 #N |\n| `--model NAME` | 覆盖任何引擎的模型 |\n| `--sonnet` | `--claude --model sonnet` 的快捷方式 |\n| `--parallel` | 并行执行 |\n| `--max-parallel N` | 最大代理数量（默认：3） |\n| `--sandbox` | 使用轻量级沙盒代替 Git 工作树 |\n| `--no-merge` | 跳过并行模式下的自动合并 |\n| `--branch-per-task` | 每个任务一个分支 |\n| `--base-branch NAME` | 基础分支 |\n| `--create-pr` | 创建 PR |\n| `--draft-pr` | 草稿 PR |\n| `--no-tests` | 跳过测试 |\n| `--no-lint` | 跳过代码检查 |\n| `--fast` | 跳过测试和代码检查 |\n| `--no-commit` | 不自动提交 |\n| `--max-iterations N` | 执行 N 个任务后停止 |\n| `--max-retries N` | 每个任务的重试次数（默认：3） |\n| `--retry-delay N` | 重试间隔秒数 |\n| `--dry-run` | 仅预览 |\n| `--browser` | 启用浏览器自动化 |\n| `--no-browser` | 禁用浏览器自动化 |\n| `-v, --verbose` | 调试输出 |\n| `--init` | 设置 .ralphy\u002F 配置 |\n| `--config` | 显示配置 |\n| `--add-rule \"rule\"` | 向配置添加规则 |\n\n## 要求\n\n**必需：**\n- AI CLI：[Claude Code](https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-code)、[OpenCode](https:\u002F\u002Fopencode.ai\u002Fdocs\u002F)、[Cursor](https:\u002F\u002Fcursor.com)、Codex、Qwen-Code、[Factory Droid](https:\u002F\u002Fdocs.factory.ai\u002Fcli\u002Fgetting-started\u002Fquickstart)、[GitHub Copilot](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Fhow-tos\u002Fuse-copilot-agents\u002Fuse-copilot-cli) 或 [Gemini CLI](https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli)\n\n**npm 版本 (`ralphy-cli`)：**\n- Node.js 18+ 或 Bun\n\n**Bash 版本 (`ralphy.sh`)：**\n- `jq`\n- `yq`（可选，用于 YAML 任务）\n- `bc`（可选，用于成本计算）\n\n**两个版本共有的要求：**\n- `gh`（可选，用于 GitHub 问题 \u002F `--create-pr`）\n- [agent-browser](https:\u002F\u002Fagent-browser.dev)（可选，用于 `--browser`）\n\n## 引擎详情\n\n| 引擎 | CLI | 权限 | 输出 |\n|--------|-----|-------------|--------|\n| Claude | `claude` | `--dangerously-skip-permissions` | 令牌 + 成本 |\n| OpenCode | `opencode` | `full-auto` | 令牌 + 成本 |\n| Codex | `codex` | 无 | 令牌 |\n| Cursor | `agent` | `--force` | 时长 |\n| Qwen | `qwen` | `--approval-mode yolo` | 令牌 |\n| Droid | `droid exec` | `--auto medium` | 时长 |\n| Copilot | `copilot` | `--yolo` | 令牌 |\n| Gemini | `gemini` | `--yolo` | 令牌 + 成本 |\n\n当引擎以非零状态退出时，ralphy 会在错误信息中包含 CLI 输出的最后一行，以便于调试。\n\n---\n\n## 更改日志\n\n### v4.7.2\n- **改进了身份验证错误检测**：简化了 `extractAuthenticationError` 函数，更好地处理边缘情况（例如登录时的 JSON 输出）\n- **新增项目标准**：`CLAUDE.md`、`.cursorrules`、`CONTRIBUTING.md`，用于实现一致的 AI 辅助开发\n- **增强默认提示**：强制执行简洁、专注的代码更改\n\n### v4.7.1\n- **Copilot 引擎改进**：非交互模式（`--yolo`）、正确的身份验证\u002F速率限制\u002F网络错误检测、令牌使用解析、基于临时文件的提示以保留 Markdown 格式\n- **修复了无限重试循环**：任务现在会在致命的配置或身份验证错误时正确中止\n- **项目标准**：添加了 `.editorconfig` 和 `.gitattributes` 以保持一致的编码风格\n\n### v4.7.0\n- **JSON PRD 支持**：新增 `--json` 标志，允许使用 JSON 文件作为任务来源，并支持并行组和任务描述\n\n### v4.6.0\n- **Gemini CLI 支持**：新增 `--gemini` 引擎选项，用于 Google Gemini CLI\n- **GitHub 问题同步**：`--sync-issue \u003Cnumber>` 会在每个任务后将 PRD 进度同步到 GitHub 问题\n- **性能改进**：减少冗余文件读取、指数退避重试策略、非阻塞日志记录、操作时间可见性\n- **版本修复**：CLI 版本现在动态从 package.json 中读取\n\n### v4.5.3\n- 并行可靠性：在工作树错误时回退到沙盒模式\n- 错误输出：包含失败引擎命令的 CLI 输出片段\n- 重试处理：检测速率限制\u002F配额错误并提前停止\n- 合并安全：在合并阶段前暂存本地更改，并在合并后恢复\n- 提示：明确避免编辑 PRD 和 `.ralphy` 进度\u002F沙盒\u002F工作树相关文件\n\n### v4.5.0\n- **沙盒模式**：使用符号链接对依赖项进行轻量级隔离（比工作树更快）\n- **性能改进**：任务缓存、并行合并分析、智能分支排序\n- **Webhook 通知**：Discord、Slack 以及自定义 Webhook，用于会话完成通知（可在 `.ralphy\u002Fconfig.yaml` 中配置）\n- **引擎特定参数**：通过 `--` 分隔符将参数传递给底层 CLI\n- **Windows 改进**：改善了 .cmd 包装器的错误处理\n\n### v4.4.1\n- 修复了 Windows 行尾处理问题\n- 修复了 Windows Bun 命令解析问题\n\n### v4.4.0\n- GitHub Copilot CLI 支持（`--copilot`）\n\n### v4.3.0\n- 模型覆盖：新增 `--model \u003Cname>` 标志，用于覆盖任何引擎的模型\n- `--sonnet` 是 `--claude --model sonnet` 的快捷方式\n- `--no-merge` 标志用于跳过并行模式下的自动合并\n- 并行自动合并期间进行 AI 辅助的冲突解决\n- 根用户检测：Claude\u002FCursor 报错，其他引擎警告\n- 改进了 OpenCode 的错误处理和模型覆盖支持\n\n### v4.2.0\n- 浏览器自动化：`--browser` \u002F `--no-browser`，配合 [agent-browser](https:\u002F\u002Fagent-browser.dev)\n- 自动检测 agent-browser 是否可用\n- 配置选项：`.ralphy\u002Fconfig.yaml` 中的 `capabilities.browser`\n\n### v4.1.0\n- TypeScript CLI：`npm install -g ralphy-cli`\n- 跨平台二进制文件（macOS、Linux、Windows）\n- npm 版本不再依赖 jq\u002Fyq\u002Fbc\n\n### v4.0.0\n- 单任务模式：`ralphy \"task\"`，无需 PRD\n- 项目配置：`--init` 会创建包含规则和自动检测功能的 `.ralphy\u002F` 目录\n- 新增：`--config`、`--add-rule`、`--no-commit`\n\n### v3.3.0\n- 支持 Factory Droid (`--droid`)\n\n### v3.2.0\n- 支持 Qwen-Code (`--qwen`)\n\n### v3.1.0\n- 支持 Cursor (`--cursor`)\n- 更好的任务验证\n\n### v3.0.0\n- 使用 worktree 实现并行执行\n- 每个任务一个分支 + 自动创建 PR\n- 支持 YAML 和 GitHub Issues 数据源\n- 并行分组\n\n### v2.0.0\n- 支持 OpenCode\n- 增加重试逻辑\n- `--max-iterations`、`--dry-run`\n\n### v1.0.0\n- 初始发布\n\n## 贡献指南\n\n开发指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。\n\n**核心原则：**\n- 保持每次更改小而集中——每个提交只包含一个逻辑变更\n- 将大型任务拆分为微任务\n- 质量优先于速度\n- 不要留下未使用的代码\n- 抵抗熵增——让代码库比你接手时更好\n\nAI 编码助手可参考：\n- [CLAUDE.md](CLAUDE.md) —— Claude Code 使用说明\n- [.cursorrules](.cursorrules) —— Cursor IDE 规则\n\n## 社区\n\n- [Discord](https:\u002F\u002Frasmic.link\u002Fdiscord)\n\n## 许可证\n\nMIT","# Ralphy 快速上手指南\n\nRalphy 是一个自主 AI 编码循环工具，能够运行 AI 代理自动执行开发任务，直到完成为止。它支持多种主流 AI 引擎（如 Claude Code、Cursor、GitHub Copilot 等），并具备并行执行、浏览器自动化和任务追踪功能。\n\n## 环境准备\n\n### 系统要求\n- **Node.js 版本**：18+ 或 Bun（推荐使用 npm 安装方式）\n- **操作系统**：Linux \u002F macOS \u002F Windows (WSL)\n\n### 前置依赖\n在使用 Ralphy 前，你必须至少安装以下**任意一个** AI CLI 工具作为底层引擎：\n- [Claude Code](https:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-code) (默认推荐)\n- [Cursor](https:\u002F\u002Fcursor.com)\n- [GitHub Copilot CLI](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot)\n- [OpenCode](https:\u002F\u002Fopencode.ai\u002Fdocs\u002F)\n- [Qwen-Code](https:\u002F\u002Fgithub.com\u002FQwenLM\u002FQwen-Coder)\n- [Gemini CLI](https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli)\n- Factory Droid 或 Codex\n\n### 可选依赖\n- `gh` (GitHub CLI)：用于同步 GitHub Issues 或自动创建 PR。\n- `agent-browser`：用于启用浏览器自动化测试功能。\n- `jq`, `yq`, `bc`：仅在使用 Bash 脚本版本 (`ralphy.sh`) 时需要。\n\n> **国内开发者提示**：如果访问 npm 或 GitHub 较慢，建议配置国内镜像源（如淘宝 npmmirror）或使用加速工具进行依赖安装。\n\n## 安装步骤\n\n推荐通过 npm 全局安装，使用最便捷。\n\n### 方式 A：npm 安装（推荐）\n\n```bash\n# 全局安装 ralphy-cli\nnpm install -g ralphy-cli\n\n# 验证安装\nralphy --version\n```\n\n### 方式 B：源码克隆\n\n如果你更喜欢直接使用脚本或需要修改源码：\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fmichaelshimeles\u002Fralphy.git\ncd ralphy\nchmod +x ralphy.sh\n\n# 后续使用 .\u002Fralphy.sh 代替 ralphy 命令\n```\n\n## 基本使用\n\n### 1. 初始化项目配置（可选）\n在项目根目录运行初始化，自动检测项目类型（如 TypeScript, Next.js 等）并生成 `.ralphy\u002Fconfig.yaml` 配置文件。你可以在此定义 AI 需遵守的规则和禁止修改的文件边界。\n\n```bash\nralphy --init\n```\n\n### 2. 执行单个任务\n直接告诉 AI 你需要做什么，它将自动编写代码、运行测试并修复错误。\n\n```bash\n# 示例：添加一个登录按钮\nralphy \"add login button\"\n\n# 示例：修复认证 bug\nralphy \"fix the auth bug\"\n```\n\n### 3. 执行任务列表 (PRD 模式)\n创建一个包含任务列表的 Markdown 文件（默认为 `PRD.md`），让 AI 按顺序逐个完成。\n\n**创建 `PRD.md`：**\n```markdown\n## Tasks\n- [ ] create auth system\n- [ ] add user dashboard\n- [ ] setup CI\u002FCD pipeline\n```\n\n**运行任务：**\n```bash\n# 自动读取 PRD.md\nralphy\n\n# 或指定其他文件\nralphy --prd tasks.md\n```\n\n### 4. 切换 AI 引擎\nRalphy 默认使用 Claude Code，你可以通过参数轻松切换其他引擎：\n\n```bash\n# 使用 Cursor\nralphy --cursor \"add dark mode\"\n\n# 使用 GitHub Copilot\nralphy --copilot \"refactor utils\"\n\n# 使用 Qwen-Code\nralphy --qwen \"build api endpoint\"\n```\n\n### 5. 并行加速（高级）\n对于大型任务列表，可以启动多个 AI 代理并行工作：\n\n```bash\n# 启动并行模式（默认 3 个代理）\nralphy --parallel\n\n# 自定义最大代理数量\nralphy --parallel --max-parallel 5\n```","某初创团队需要在三天内基于 Next.js 完成一个包含用户认证、数据仪表盘及后台管理的 MVP 版本，时间紧任务重。\n\n### 没有 ralphy 时\n- **上下文切换频繁**：开发者需手动在 Claude Code、Cursor 和 GitHub Copilot 之间切换，反复复制粘贴代码片段，注意力被严重分散。\n- **任务进度难追踪**：面对几十项待办功能，依靠人工标记 PRD 文档中的复选框，极易遗漏或重复开发，导致状态不同步。\n- **规范执行不一致**：不同 AI 助手对代码风格理解不一，有人写 API 路由，有人写 Server Actions，后期重构耗费大量时间。\n- **串行效率低下**：只能逐个任务执行，前端页面与后端接口开发必须排队进行，无法利用多模型并行加速。\n\n### 使用 ralphy 后\n- **全自动闭环执行**：只需运行 `ralphy --prd PRD.md`，工具自动调用 Claude Code 等引擎循环执行，直到所有任务标记为完成，无需人工干预。\n- **智能进度同步**：ralphy 实时读取并更新 Markdown 或 YAML 格式的任务列表，自动跳过已完成项，确保文档与代码状态严格一致。\n- **统一规则约束**：通过 `.ralphy\u002Fconfig.yaml` 预设\"强制使用 TypeScript 严格模式”等规则，所有引擎输出均符合团队规范，代码风格高度统一。\n- **并行加速交付**：启用 `--parallel` 模式后，ralphy 同时调度多个 Agent 分别处理前端与后端任务，将原本串行的开发流程压缩至几小时内完成。\n\nralphy 通过将分散的 AI 能力整合为自主运行的开发流水线，让团队从繁琐的提示词工程中解放出来，专注于核心架构设计。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmichaelshimeles_ralphy_73f2dcc1.png","michaelshimeles","Michael Shimeles","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fmichaelshimeles_9ba30dec.png","Full Stack Engineer",null,"Toronto","rasmic","www.rasmic.xyz","https:\u002F\u002Fgithub.com\u002Fmichaelshimeles",[84,88,92,96],{"name":85,"color":86,"percentage":87},"TypeScript","#3178c6",75.8,{"name":89,"color":90,"percentage":91},"Shell","#89e051",23.2,{"name":93,"color":94,"percentage":95},"JavaScript","#f1e05a",0.9,{"name":97,"color":98,"percentage":99},"CSS","#663399",0.1,2777,347,"2026-04-20T02:25:21","Linux, macOS, Windows","未说明",{"notes":106,"python":104,"dependencies":107},"该工具是一个自主 AI 编码循环管理器，本身不运行大模型，而是调用外部 AI CLI 工具（如 Claude Code、Cursor 等）执行任务。因此硬件需求取决于所选用的具体 AI 引擎。支持通过 npm 全局安装或使用 Bash 脚本运行。并行执行模式下，每个代理会创建隔离的工作树或沙箱环境。",[108,109,110,111,112,113,114],"Node.js 18+ 或 Bun","AI CLI (Claude Code, OpenCode, Cursor, Codex, Qwen-Code, Factory Droid, GitHub Copilot, 或 Gemini CLI)","jq","yq (可选，用于 YAML 任务)","bc (可选，用于成本计算)","gh (可选，用于 GitHub 集成)","agent-browser (可选，用于浏览器自动化)",[13,27],[117,55,118,119,65],"claude-code","ralph-loop","ralph-wiggum","2026-03-27T02:49:30.150509","2026-04-20T19:32:36.852447",[123,128,133,138,143,148],{"id":124,"question_zh":125,"answer_zh":126,"source_url":127},45436,"运行 Ralphy 时立即显示\"[OK] No tasks remaining. All done!\"，没有任何任务执行，如何解决？","这是一个已知问题，通常与 `--opencode` 标志或 PRD 文件解析有关。维护者表示该问题已在后续版本中修复，请尝试更新到最新版本。如果问题依旧，请检查你的 `PRD.md` 文件格式是否正确（包含明确的 Tasks 列表），并尝试移除 `--opencode` 标志或指定具体的模型参数重试。","https:\u002F\u002Fgithub.com\u002Fmichaelshimeles\u002Fralphy\u002Fissues\u002F78",{"id":129,"question_zh":130,"answer_zh":131,"source_url":132},45437,"在 Linux 系统上运行 Ralphy 或使用 OpenCode 时遇到问题怎么办？","Linux 用户在使用 OpenCode 集成时可能会遇到兼容性问题。该问题已通过 Pull Request #24 修复。请确保你安装了最新版本的 Ralphy 和 OpenCode。如果仍然报错，请参考相关的修复补丁或检查 OpenCode 的配置是否正确。","https:\u002F\u002Fgithub.com\u002Fmichaelshimeles\u002Fralphy\u002Fissues\u002F7",{"id":134,"question_zh":135,"answer_zh":136,"source_url":137},45438,"如何配置 Ralphy 以使用 Z.AI (GLM-4.7) 作为 OpenCode 的默认模型？","需要在项目根目录创建 `opencode.json` 配置文件，并确保已安装且认证了 OpenCode。配置文件内容如下：\n{\n  \"$schema\": \"https:\u002F\u002Fopencode.ai\u002Fconfig.json\",\n  \"model\": \"zai-coding-plan\u002Fglm-4.7\",\n  \"permission\": \"allow\"\n}\n注意：必须包含 `\"permission\": \"allow\"` 字段，否则可能无法正常运行。你也可以通过修改 OpenCode 的默认模型设置来指定 provider-id 和 model-id。","https:\u002F\u002Fgithub.com\u002Fmichaelshimeles\u002Fralphy\u002Fissues\u002F44",{"id":139,"question_zh":140,"answer_zh":141,"source_url":142},45439,"Ralphy 每一步都运行完整的测试套件导致速度极慢，如何跳过测试和 lint？","可以通过添加以下命令行标志来跳过耗时的验证步骤：\n- `--no-tests`：跳过测试\n- `--no-lint`：跳过 lint 检查\n- `--fast`：同时跳过测试和 lint（推荐用于快速迭代）\n例如：`ralphy --prd PRD.md --fast`","https:\u002F\u002Fgithub.com\u002Fmichaelshimeles\u002Fralphy\u002Fissues\u002F174",{"id":144,"question_zh":145,"answer_zh":146,"source_url":147},45440,"Ralphy 是否有内置功能可以辅助生成高质量的 PRD（产品需求文档）？","目前 Ralphy 正在规划原生支持更好的 PRD 生成功能。暂时你可以使用关联工具 `ralph-tui` 中的 `create-prd` 命令来辅助生成。维护者建议关注官方 Discord 频道以获取即将发布的轻量级 GUI 规范，届时将提供更可视化的项目管理功能。","https:\u002F\u002Fgithub.com\u002Fmichaelshimeles\u002Fralphy\u002Fissues\u002F99",{"id":149,"question_zh":150,"answer_zh":151,"source_url":152},45441,"是否有计划为 Ralphy 开发图形界面（GUI）？","是的，维护者正在规划一个轻量级的 GUI 方案，旨在提供可视化的任务管理、实时监控和多 Agent 编排功能，而不是构建另一个重型 IDE。社区建议使用 Tauri 而非 Electron 以减少资源占用。具体规格将在官方 Discord 中公布，用户可以加入社区参与讨论。","https:\u002F\u002Fgithub.com\u002Fmichaelshimeles\u002Fralphy\u002Fissues\u002F85",[]]