Ralphy

加入我们的 Discord - 有问题？想贡献代码？快来加入社区吧！

自主 AI 编码循环。持续运行 AI 代理处理任务，直到完成。

安装

选项 A：npm（推荐）

npm install -g ralphy-cli

# 然后在任何地方使用
ralphy "添加登录按钮"
ralphy --prd PRD.md

选项 B：克隆

git clone https://github.com/michaelshimeles/ralphy.git
cd ralphy && chmod +x ralphy.sh

./ralphy.sh "添加登录按钮"
./ralphy.sh --prd PRD.md

两种方式功能完全相同。以下示例使用 ralphy（npm），如果使用 bash 脚本，请替换为 ./ralphy.sh。

两种模式

单任务 - 只需告诉它要做什么：

ralphy "添加暗黑模式"
ralphy "修复认证 bug"

任务列表 - 按照产品需求文档逐步执行：

ralphy              # 使用 PRD.md
ralphy --prd tasks.md

项目配置

可选。用于存储 AI 必须遵循的规则。

ralphy --init              # 自动检测项目设置
ralphy --config            # 查看配置
ralphy --add-rule "使用 TypeScript 严格模式"

会创建 .ralphy/config.yaml 文件：

project:
  name: "my-app"
  language: "TypeScript"
  framework: "Next.js"

commands:
  test: "npm test"
  lint: "npm run lint"
  build: "npm run build"

rules:
  - "使用服务器动作而非 API 路由"
  - "遵循 src/utils/errors.ts 中的错误模式"

boundaries:
  never_touch:
    - "src/legacy/**"
    - "*.lock"

这些规则适用于所有任务（无论是单个任务还是 PRD）。

AI 引擎

ralphy              # Claude Code（默认）
ralphy --opencode   # OpenCode
ralphy --cursor     # Cursor
ralphy --codex      # Codex
ralphy --qwen       # Qwen-Code
ralphy --droid      # Factory Droid
ralphy --copilot    # GitHub Copilot
ralphy --gemini     # Gemini CLI

模型覆盖

可以为任何引擎覆盖默认模型：

ralphy --model sonnet "添加功能"                    # 使用 Claude 的 Sonnet 模型
ralphy --sonnet "添加功能"                          # 上面的快捷方式
ralphy --opencode --model opencode/glm-4.7-free "任务" # 自定义 OpenCode 模型
ralphy --qwen --model qwen-max "构建 API"             # 自定义 Qwen 模型

引擎特定参数

使用 -- 分隔符传递底层引擎 CLI 的额外参数：

# 传递 Copilot 特定参数
ralphy --copilot --model "claude-opus-4.5" --prd PRD.md -- --allow-all-tools --allow-all-urls --stream on

# 传递 Claude 特定参数  
ralphy --claude "添加功能" -- --no-permissions-prompt

# 适用于任何引擎
ralphy --cursor "修复 bug" -- --custom-arg value

-- 之后的所有内容都会直接传递给引擎 CLI，而不会被解析。

任务来源

Markdown 文件（默认）：

ralphy --prd PRD.md

## 任务
- [ ] 创建认证
- [ ] 添加仪表盘
- [x] 已完成任务（已跳过）

Markdown 文件夹（适用于大型项目）：

ralphy --prd ./prd/

当指向一个文件夹时，Ralphy 会读取所有 .md 文件并汇总任务：

prd/
  backend.md      # - [ ] 创建用户 API
  frontend.md     # - [ ] 添加登录页面
  infra.md        # - [ ] 设置 CI/CD

任务按文件跟踪，因此完成状态会更新到正确的文件中。

YAML：

ralphy --yaml tasks.yaml

tasks:
  - title: 创建认证
    completed: false
  - title: 添加仪表盘
    completed: false

JSON：

ralphy --json PRD.json

{
  "tasks": [
    {
      "title": "创建认证",
      "completed": false,
      "parallel_group": 1,
      "description": "可选详情"
    }
  ]
}

标题必须唯一。

GitHub Issues：

ralphy --github owner/repo
ralphy --github owner/repo --github-label "ready"

并行执行

ralphy --parallel                  # 默认 3 个代理
ralphy --parallel --max-parallel 5 # 5 个代理

每个代理都有独立的工作树和分支：

代理 1 → /tmp/xxx/agent-1 → ralphy/agent-1-create-auth
代理 2 → /tmp/xxx/agent-2 → ralphy/agent-2-add-dashboard
代理 3 → /tmp/xxx/agent-3 → ralphy/agent-3-build-api

如果没有 --create-pr：自动合并回主分支，AI 会解决冲突。
如果有 --create-pr：保留分支并创建 PR。
如果有 --no-merge：保留分支，不合并也不创建 PR。

YAML 并行组 - 控制执行顺序：

tasks:
  - title: 创建用户模型
    parallel_group: 1
  - title: 创建帖子模型
    parallel_group: 1  # 同一组会同时执行
  - title: 添加关系
    parallel_group: 2  # 在第 1 组之后执行

分支工作流

ralphy --branch-per-task                # 每个任务一个分支
ralphy --branch-per-task --create-pr    # 同时创建 PR
ralphy --branch-per-task --draft-pr     # 同时创建草稿 PR
ralphy --base-branch main               # 从 main 分支开始

分支命名格式：ralphy/<task-slug>

浏览器自动化

Ralphy 可以使用 agent-browser 自动化浏览器交互。

ralphy "测试登录流程" --browser    # 强制启用
ralphy "添加结账功能" --no-browser  # 强制禁用
ralphy "构建功能"                    # 自动检测（默认）

启用后，AI 会获得以下浏览器命令：

• agent-browser open <url> - 导航到指定 URL
• agent-browser snapshot - 获取元素引用（@e1, @e2）
• agent-browser click @e1 - 点击元素
• agent-browser type @e1 "text" - 在输入框中输入文本
• agent-browser screenshot <file> - 截取屏幕截图

应用场景：

• 实现功能后测试 UI
• 验证部署
• 填写表单和测试工作流

配置（.ralphy/config.yaml）：

capabilities:
  browser: "auto"  # "auto", "true" 或 "false"

Webhook 通知

通过 Discord、Slack 或自定义 webhook，在会话完成时接收通知。

配置（.ralphy/config.yaml）：

notifications:
  discord_webhook: "https://discord.com/api/webhooks/..."
  slack_webhook: "https://hooks.slack.com/services/..."
  custom_webhook: "https://your-api.com/webhook"

通知内容包括任务完成数量和状态（已完成/失败）。

沙盒模式

对于包含大型依赖目录的大规模代码库，沙盒模式比 Git 工作树更快：

ralphy --parallel --sandbox

工作原理：

• 符号链接 用于只读依赖项（node_modules、.git、vendor、.venv、.pnpm-store、.yarn、.cache）
• 复制 代理可能修改的源文件（src/、app/、lib/、配置文件等）

为何使用：

• 避免在多个工作树中重复存储数 GB 的 node_modules
• 对于大型 monorepo，沙盒创建速度显著提升
• 每个任务完成后，更改会同步回原始目录

何时改用工作树（默认）：

• 需要在每个沙盒中访问完整的 Git 历史记录
• 需要执行需要真实仓库的 git 命令
• 对于工作树开销较小的小型仓库

并行执行的可靠性：

• 如果工作树操作失败（例如嵌套的工作树仓库），ralphy 会自动回退到沙盒模式
• 可重试的速率限制或配额错误会被检测并推迟到后续重试
• 在合并阶段之前，本地更改会被暂存，并在合并后恢复
• 代理不应修改 PRD 文件、.ralphy/progress.txt、.ralphy-worktrees 或 .ralphy-sandboxes

选项

标志	功能
--prd PATH	任务文件或文件夹（自动检测，默认：PRD.md）
--yaml FILE	YAML 任务文件
--json FILE	JSON 任务文件
--github REPO	使用 GitHub 问题
--github-label TAG	按标签筛选问题
--sync-issue N	将 PRD 进度同步到 GitHub 问题 #N
--model NAME	覆盖任何引擎的模型
--sonnet	--claude --model sonnet 的快捷方式
--parallel	并行执行
--max-parallel N	最大代理数量（默认：3）
--sandbox	使用轻量级沙盒代替 Git 工作树
--no-merge	跳过并行模式下的自动合并
--branch-per-task	每个任务一个分支
--base-branch NAME	基础分支
--create-pr	创建 PR
--draft-pr	草稿 PR
--no-tests	跳过测试
--no-lint	跳过代码检查
--fast	跳过测试和代码检查
--no-commit	不自动提交
--max-iterations N	执行 N 个任务后停止
--max-retries N	每个任务的重试次数（默认：3）
--retry-delay N	重试间隔秒数
--dry-run	仅预览
--browser	启用浏览器自动化
--no-browser	禁用浏览器自动化
-v, --verbose	调试输出
--init	设置 .ralphy/ 配置
--config	显示配置
--add-rule "rule"	向配置添加规则

要求

必需：

• AI CLI：Claude Code、OpenCode、Cursor、Codex、Qwen-Code、Factory Droid、GitHub Copilot 或 Gemini CLI

npm 版本 (ralphy-cli)：

• Node.js 18+ 或 Bun

Bash 版本 (ralphy.sh)：

• jq
• yq（可选，用于 YAML 任务）
• bc（可选，用于成本计算）

两个版本共有的要求：

• gh（可选，用于 GitHub 问题 / --create-pr）
• agent-browser（可选，用于 --browser）

引擎详情

引擎	CLI	权限	输出
Claude	claude	--dangerously-skip-permissions	令牌 + 成本
OpenCode	opencode	full-auto	令牌 + 成本
Codex	codex	无	令牌
Cursor	agent	--force	时长
Qwen	qwen	--approval-mode yolo	令牌
Droid	droid exec	--auto medium	时长
Copilot	copilot	--yolo	令牌
Gemini	gemini	--yolo	令牌 + 成本

当引擎以非零状态退出时，ralphy 会在错误信息中包含 CLI 输出的最后一行，以便于调试。

---

更改日志

v4.7.2

• 改进了身份验证错误检测：简化了 extractAuthenticationError 函数，更好地处理边缘情况（例如登录时的 JSON 输出）
• 新增项目标准：CLAUDE.md、.cursorrules、CONTRIBUTING.md，用于实现一致的 AI 辅助开发
• 增强默认提示：强制执行简洁、专注的代码更改

v4.7.1

• Copilot 引擎改进：非交互模式（--yolo）、正确的身份验证/速率限制/网络错误检测、令牌使用解析、基于临时文件的提示以保留 Markdown 格式
• 修复了无限重试循环：任务现在会在致命的配置或身份验证错误时正确中止
• 项目标准：添加了 .editorconfig 和 .gitattributes 以保持一致的编码风格

v4.7.0

• JSON PRD 支持：新增 --json 标志，允许使用 JSON 文件作为任务来源，并支持并行组和任务描述

v4.6.0

• Gemini CLI 支持：新增 --gemini 引擎选项，用于 Google Gemini CLI
• GitHub 问题同步：--sync-issue <number> 会在每个任务后将 PRD 进度同步到 GitHub 问题
• 性能改进：减少冗余文件读取、指数退避重试策略、非阻塞日志记录、操作时间可见性
• 版本修复：CLI 版本现在动态从 package.json 中读取

v4.5.3

• 并行可靠性：在工作树错误时回退到沙盒模式
• 错误输出：包含失败引擎命令的 CLI 输出片段
• 重试处理：检测速率限制/配额错误并提前停止
• 合并安全：在合并阶段前暂存本地更改，并在合并后恢复
• 提示：明确避免编辑 PRD 和 .ralphy 进度/沙盒/工作树相关文件

v4.5.0

• 沙盒模式：使用符号链接对依赖项进行轻量级隔离（比工作树更快）
• 性能改进：任务缓存、并行合并分析、智能分支排序
• Webhook 通知：Discord、Slack 以及自定义 Webhook，用于会话完成通知（可在 .ralphy/config.yaml 中配置）
• 引擎特定参数：通过 -- 分隔符将参数传递给底层 CLI
• Windows 改进：改善了 .cmd 包装器的错误处理

v4.4.1

• 修复了 Windows 行尾处理问题
• 修复了 Windows Bun 命令解析问题

v4.4.0

• GitHub Copilot CLI 支持（--copilot）

v4.3.0

• 模型覆盖：新增 --model <name> 标志，用于覆盖任何引擎的模型
• --sonnet 是 --claude --model sonnet 的快捷方式
• --no-merge 标志用于跳过并行模式下的自动合并
• 并行自动合并期间进行 AI 辅助的冲突解决
• 根用户检测：Claude/Cursor 报错，其他引擎警告
• 改进了 OpenCode 的错误处理和模型覆盖支持

v4.2.0

• 浏览器自动化：--browser / --no-browser，配合 agent-browser
• 自动检测 agent-browser 是否可用
• 配置选项：.ralphy/config.yaml 中的 capabilities.browser

v4.1.0

• TypeScript CLI：npm install -g ralphy-cli
• 跨平台二进制文件（macOS、Linux、Windows）
• npm 版本不再依赖 jq/yq/bc

v4.0.0

• 单任务模式：ralphy "task"，无需 PRD
• 项目配置：--init 会创建包含规则和自动检测功能的 .ralphy/ 目录
• 新增：--config、--add-rule、--no-commit

v3.3.0

• 支持 Factory Droid (--droid)

v3.2.0

• 支持 Qwen-Code (--qwen)

v3.1.0

• 支持 Cursor (--cursor)
• 更好的任务验证

v3.0.0

• 使用 worktree 实现并行执行
• 每个任务一个分支 + 自动创建 PR
• 支持 YAML 和 GitHub Issues 数据源
• 并行分组

v2.0.0

• 支持 OpenCode
• 增加重试逻辑
• --max-iterations、--dry-run

v1.0.0

• 初始发布

贡献指南

开发指南请参阅 CONTRIBUTING.md。

核心原则：

• 保持每次更改小而集中——每个提交只包含一个逻辑变更
• 将大型任务拆分为微任务
• 质量优先于速度
• 不要留下未使用的代码
• 抵抗熵增——让代码库比你接手时更好

AI 编码助手可参考：

• CLAUDE.md —— Claude Code 使用说明
• .cursorrules —— Cursor IDE 规则

社区

• Discord

许可证

MIT

Ralphy 快速上手指南

Ralphy 是一个自主 AI 编码循环工具，能够运行 AI 代理自动执行开发任务，直到完成为止。它支持多种主流 AI 引擎（如 Claude Code、Cursor、GitHub Copilot 等），并具备并行执行、浏览器自动化和任务追踪功能。

环境准备

系统要求

• Node.js 版本：18+ 或 Bun（推荐使用 npm 安装方式）
• 操作系统：Linux / macOS / Windows (WSL)

前置依赖

在使用 Ralphy 前，你必须至少安装以下任意一个 AI CLI 工具作为底层引擎：

• Claude Code (默认推荐)
• Cursor
• GitHub Copilot CLI
• OpenCode
• Qwen-Code
• Gemini CLI
• Factory Droid 或 Codex

可选依赖

• gh (GitHub CLI)：用于同步 GitHub Issues 或自动创建 PR。
• agent-browser：用于启用浏览器自动化测试功能。
• jq, yq, bc：仅在使用 Bash 脚本版本 (ralphy.sh) 时需要。

国内开发者提示：如果访问 npm 或 GitHub 较慢，建议配置国内镜像源（如淘宝 npmmirror）或使用加速工具进行依赖安装。

安装步骤

推荐通过 npm 全局安装，使用最便捷。

方式 A：npm 安装（推荐）

# 全局安装 ralphy-cli
npm install -g ralphy-cli

# 验证安装
ralphy --version

方式 B：源码克隆

如果你更喜欢直接使用脚本或需要修改源码：

git clone https://github.com/michaelshimeles/ralphy.git
cd ralphy
chmod +x ralphy.sh

# 后续使用 ./ralphy.sh 代替 ralphy 命令

基本使用

1. 初始化项目配置（可选）

在项目根目录运行初始化，自动检测项目类型（如 TypeScript, Next.js 等）并生成 .ralphy/config.yaml 配置文件。你可以在此定义 AI 需遵守的规则和禁止修改的文件边界。

ralphy --init

2. 执行单个任务

直接告诉 AI 你需要做什么，它将自动编写代码、运行测试并修复错误。

# 示例：添加一个登录按钮
ralphy "add login button"

# 示例：修复认证 bug
ralphy "fix the auth bug"

3. 执行任务列表 (PRD 模式)

创建一个包含任务列表的 Markdown 文件（默认为 PRD.md），让 AI 按顺序逐个完成。

创建 PRD.md：

## Tasks
- [ ] create auth system
- [ ] add user dashboard
- [ ] setup CI/CD pipeline

运行任务：

# 自动读取 PRD.md
ralphy

# 或指定其他文件
ralphy --prd tasks.md

4. 切换 AI 引擎

Ralphy 默认使用 Claude Code，你可以通过参数轻松切换其他引擎：

# 使用 Cursor
ralphy --cursor "add dark mode"

# 使用 GitHub Copilot
ralphy --copilot "refactor utils"

# 使用 Qwen-Code
ralphy --qwen "build api endpoint"

5. 并行加速（高级）

对于大型任务列表，可以启动多个 AI 代理并行工作：

# 启动并行模式（默认 3 个代理）
ralphy --parallel

# 自定义最大代理数量
ralphy --parallel --max-parallel 5