Ralphy

加入我们的 Discord - 有问题吗？想要贡献代码？欢迎加入我们的社区！

自动化的 AI 编码循环工具。它会驱动 AI Agent 持续执行任务，直到所有工作完成。

安装

选项 A：npm（推荐）

npm install -g ralphy-cli

# 安装后可在任何地方使用
ralphy "add login button"
ralphy --prd PRD.md

选项 B：克隆仓库

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

./ralphy.sh "add login button"
./ralphy.sh --prd PRD.md

两种版本的功能完全相同。以下示例均使用 ralphy (npm) 命令，如果使用 bash 脚本，请将其替换为 ./ralphy.sh。

两种工作模式

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

ralphy "add dark mode"
ralphy "fix the auth bug"

任务列表模式 - 根据 PRD（产品需求文档）逐步完成工作：

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

项目配置

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

ralphy --init              # 自动检测项目设置
ralphy --config            # 查看配置
ralphy --add-rule "use TypeScript strict mode"

这会创建 .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:
  - "use server actions not API routes"
  - "follow error pattern in 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 "add feature"                    # 在 Claude 中使用 sonnet 模型
ralphy --sonnet "add feature"                          # 上述命令的快捷方式
ralphy --opencode --model opencode/glm-4.7-free "task" # 自定义 OpenCode 模型
ralphy --qwen --model qwen-max "build 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 "add feature" -- --no-permissions-prompt

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

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

任务来源

Markdown 文件（默认）：

ralphy --prd PRD.md

## Tasks
- [ ] create auth
- [ ] add dashboard
- [x] done task (skipped)

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

ralphy --prd ./prd/

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

prd/
  backend.md      # - [ ] create user API
  frontend.md     # - [ ] add login page
  infra.md        # - [ ] setup CI/CD

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

YAML 文件:

ralphy --yaml tasks.yaml

tasks:
  - title: create auth
    completed: false
  - title: add dashboard
    completed: false

JSON 文件:

ralphy --json PRD.json

{
  "tasks": [
    {
      "title": "create auth",
      "completed": false,
      "parallel_group": 1,
      "description": "Optional details"
    }
  ]
}

任务标题必须唯一。

GitHub Issues:

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

并行执行

ralphy --parallel                  # 默认启动 3 个 Agent
ralphy --parallel --max-parallel 5 # 启动 5 个 Agent

每个 Agent 都有隔离的工作树（worktree）和分支：

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

• 不使用 --create-pr：自动合并回基础分支，AI 处理冲突。
• 使用 --create-pr：保留分支并创建 PR。
• 使用 --no-merge：保留分支，不进行合并或创建 PR。

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

tasks:
  - title: Create User model
    parallel_group: 1
  - title: Create Post model
    parallel_group: 1  # 组号相同 = 同时运行
  - title: Add relationships
    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/