ralph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph - Autonomous Agent

Ralph - 自主Agent

Ralph breaks big projects into user stories and executes them autonomously. The workflow:

Create a PRD - Define user stories with acceptance criteria

Run it -

ralph.mjs create --prd path/to/prd.json --start

Monitor -
```
ralph.mjs logs <session-id> --follow
```

Ralph 可将大型项目拆解为用户故事并自主执行。工作流程如下：

创建PRD - 定义带有验收标准的用户故事

运行项目 -

ralph.mjs create --prd path/to/prd.json --start

监控会话 -
```
ralph.mjs logs <session-id> --follow
```

Creating a PRD

创建PRD

Create a project folder and prd.json:

.claude/skills/ralph/projects/<project-name>/prd.json

创建项目文件夹及prd.json文件：

.claude/skills/ralph/projects/<project-name>/prd.json

PRD Structure

PRD结构

json

{
  "description": "Brief description of the feature",
  "branchName": "feature/my-feature",
  "userStories": [
    {
      "id": "US001",
      "title": "Short descriptive title",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Specific testable criterion",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false
    }
  ]
}

json

{
  "description": "Brief description of the feature",
  "branchName": "feature/my-feature",
  "userStories": [
    {
      "id": "US001",
      "title": "Short descriptive title",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Specific testable criterion",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false
    }
  ]
}

Story Guidelines

故事编写指南

Priority 1: Foundation - migrations, types, base components
Priority 2-3: Core functionality
Priority 4+: Secondary features, polish
Each story should touch 1-3 files, not 10-file refactors
Include "Typecheck passes" in acceptance criteria

优先级1：基础内容 - 迁移脚本、类型定义、基础组件
优先级2-3：核心功能
优先级4及以上：次要功能、优化打磨
每个故事应仅涉及1-3个文件，避免一次性重构10个文件
验收标准中需包含"Typecheck passes"

CLI Commands

CLI命令

The daemon starts automatically when you run any command.

运行任意命令时，守护进程会自动启动。

Running Sessions

运行会话

bash

undefined

bash

undefined

Create and start a session

创建并启动会话

ralph.mjs create --prd path/to/prd.json --start

List all sessions

列出所有会话

ralph.mjs list

Check session status

查看会话状态

ralph.mjs status <session-id>

Follow logs in real-time

实时跟踪日志

ralph.mjs logs <session-id> --follow

undefined

ralph.mjs logs <session-id> --follow

undefined

Session Control

会话控制

bash

undefined

bash

undefined

Pause a session

暂停会话

ralph.mjs pause <session-id> --reason "Waiting for API"

Resume with guidance

附带指导信息恢复会话

ralph.mjs resume <session-id> --guidance "API is ready on port 3000"

Inject guidance into running session

向运行中的会话注入指导信息

ralph.mjs inject <session-id> --message "Try using the helper in utils.ts"

Abort a session

终止会话

ralph.mjs abort <session-id>

undefined

ralph.mjs abort <session-id>

undefined

Orchestration (Multi-Level)

编排（多层级）

For orchestrator PRDs that spawn child sessions:

bash

undefined

针对可生成子会话的编排器PRD：

bash

undefined

Spawn a child session

生成子会话

ralph.mjs spawn <parent-id> --prd child/prd.json --start

List children of a session

列出会话的所有子会话

ralph.mjs children <session-id>

Wait for all children to complete

等待所有子会话完成

ralph.mjs wait <session-id>

View session tree

查看会话树

ralph.mjs tree <session-id>

Abort parent and all children

终止父会话及所有子会话

ralph.mjs abort <session-id> --cascade

undefined

ralph.mjs abort <session-id> --cascade

undefined

PRD Types

PRD类型

Type	Use Case
`code` (default)	Implement features, commit code
`orchestrator`	Coordinate multiple sub-Ralphs
`testing`	Browser automation testing

Set via

"type": "orchestrator"

in prd.json.

类型	使用场景
`code` （默认）	实现功能、提交代码
`orchestrator`	协调多个子Ralph实例
`testing`	浏览器自动化测试

可通过在prd.json中设置

"type": "orchestrator"

来指定类型。

Full CLI Reference

完整CLI参考

Run

ralph.mjs --help

for complete documentation.

运行

ralph.mjs --help

获取完整文档。