附录：常用命令速查

基本命令

初始化

# 在当前目录初始化 Ralph（使用 Claude 后端）
ralph init --backend claude

# 使用 Kiro 后端
ralph init --backend kiro

# 使用内置预设（通过 run 命令指定）
ralph run --hats builtin:code-assist -p "任务描述"

运行循环

# 直接用提示词运行
ralph run -p "你的任务描述"

# 使用内置预设（推荐）
ralph run -H builtin:code-assist -p "任务描述"

# 或使用本地下载的预设文件
ralph run -H presets/code-assist.yml -p "任务描述"

# 从文件读取提示词
ralph run --prompt-file PROMPT.md

# 限制最大迭代次数
ralph run -p "任务" --max-iterations 20

# 指定 AI 后端（覆盖配置文件）
ralph run -p "任务" --backend kiro

# 记录会话（用于调试或创建测试 fixture）
ralph run -p "任务" --record-session session.jsonl

规划（PDD）

# 通过问答方式把想法变成设计文档
ralph plan "你的想法描述"

# 查看生成的设计文档
cat .agents/scratchpad/implementation/*/design.md

循环管理

# 查看所有活跃循环
ralph loops list

# 查看所有循环（含已完成）
ralph loops list --all

# 停止特定循环
ralph loops stop loop-abc

# 查看某个循环的事件历史
ralph loops history loop-abc

# 查看某个循环的实时输出
ralph loops logs loop-abc --follow

# 废弃循环并清理 worktree
ralph loops discard loop-abc

任务管理

# 列出所有任务
ralph tools task list

# 列出待处理的任务
ralph tools task ready

# 查看任务详情（task-id 示例：task-1776737176-532e，由 Ralph 生成）
ralph tools task show task-1776737176-532e

# 手动确保任务存在（create or update；签名：--key <KEY> <TITLE> [--description <DESC>]）
ralph tools task ensure --key "my-key" "任务标题" --description "任务描述"

# 手动关闭/重开任务
ralph tools task close task-1776737176-532e
ralph tools task reopen task-1776737176-532e

记忆管理

# 列出所有记忆
ralph tools memory list

# 添加记忆
ralph tools memory add "重要说明：这个项目不允许使用 X 库"

# 查看记忆文件
cat .ralph/agent/memories.md

# 手动编辑记忆
vim .ralph/agent/memories.md

事件系统

# 查看所有事件历史
ralph events

# 查看最近 20 个事件
ralph events --last 20

# 按话题过滤
ralph events --topic review

# 手动注入事件（向正在运行的循环发送指引）
ralph emit human.guidance "请用中文写注释"

# 触发波浪（并行处理多个工作单元）
ralph wave emit review.file \
  --payloads "src/a.py" "src/b.py" "src/c.py"

帽子管理

# 列出配置的帽子
ralph hats

# 查看某个帽子的详细配置
ralph hats show builder

Web 仪表盘

# 启动 Web 仪表盘（自动打开浏览器）
ralph web

# 不自动打开浏览器
ralph web --no-open

# 指定端口
ralph web --backend-port 4000

# 指定工作区
ralph web --workspace /path/to/project

Telegram 机器人

# 引导式配置（Ralph 的 bot 目前就是 Telegram，无需额外 flag）
ralph bot onboard

# 查看连接状态
ralph bot status

# 发送测试消息
ralph bot test

清理

# 预览会删除什么（不实际删除）
ralph clean --dry-run

# 清理诊断日志
ralph clean --diagnostics

# 手动编辑记忆（直接编辑文件，删除不再相关的条目）
vim .ralph/agent/memories.md

# 废弃并清理某个并行循环的 worktree
ralph loops discard loop-abc

诊断和调试

# 开启诊断模式（保存详细日志）
RALPH_DIAGNOSTICS=1 ralph run -p "任务"

# 查看诊断日志
ls .ralph/diagnostics/

# 查看工具调用记录
jq 'select(.type == "tool_call")' \
  .ralph/diagnostics/*/agent-output.jsonl

# 查看帽子激活记录
jq 'select(.type == "hat_activation")' \
  .ralph/diagnostics/*/orchestration.jsonl

# 运行 E2E 测试（模拟模式）
ralph run -p "任务" --dry-run

MCP 服务器（IDE 集成）

# 在当前目录启动 MCP 服务器
ralph mcp serve

# 指定工作区
ralph mcp serve --workspace-root /path/to/project

# 使用环境变量指定工作区
RALPH_API_WORKSPACE_ROOT=/path/to/project ralph mcp serve

常用工作流命令

完整功能开发流程

# 1. 规划（可选，适合复杂功能）
ralph plan "功能描述"

# 2. 实现
ralph run -H builtin:pdd-to-code-assist -p "功能描述"
# 或
ralph run -H builtin:code-assist \
  --prompt ".agents/scratchpad/implementation/feature-name/"

# 3. 监控进度
ralph loops

# 4. 查看结果
ralph events --last 20
ralph tools task list

快速 bug 修复

ralph run -p "修复：[具体描述 bug 的现象和位置]" \
  --max-iterations 10

代码审查

ralph run -H builtin:review \
  --prompt "审查最近的修改，检查安全性和代码质量"

并行任务

# 终端 1
ralph run -p "任务 A"

# 终端 2（同时）
ralph run -p "任务 B"

# 监控
ralph loops

配置文件速查模板

最简配置

event_loop:
  max_iterations: 50

cli:
  backend: claude

标准配置（Python 项目）

event_loop:
  max_iterations: 150
  max_runtime_seconds: 7200

cli:
  backend: claude

core:
  guardrails:
    - "代码注释用中文"

hats:
  builder:
    name: "⚙️ Builder"
    triggers: ["tasks.ready"]
    publishes: ["review.ready"]
    instructions: |
      实现任务。发出 review.ready 前必须通过：
      - python -m pytest（全部通过）
      - black --check .（0 个格式错误）
      把实际输出附在载荷里。

标准配置（Node.js 项目）

event_loop:
  max_iterations: 150

cli:
  backend: claude

hats:
  builder:
    name: "⚙️ Builder"
    triggers: ["tasks.ready"]
    publishes: ["review.ready"]
    instructions: |
      实现任务。发出 review.ready 前必须通过：
      - npm test
      - npm run lint
      - tsc --noEmit
      把实际输出附在载荷里。

标准配置（Rust 项目）

event_loop:
  max_iterations: 200

cli:
  backend: claude

hats:
  builder:
    name: "⚙️ Builder"
    triggers: ["tasks.ready"]
    publishes: ["review.ready"]
    instructions: |
      实现任务。发出 review.ready 前必须通过：
      - cargo fmt --all -- --check
      - cargo clippy --all-targets --all-features -- -D warnings
      - cargo test --all
      把实际输出附在载荷里。

.ralph/ 目录结构说明

.ralph/
├── agent/
│   ├── memories.md          ← AI 的跨会话记忆（可手动编辑）
│   ├── tasks.jsonl          ← 运行时任务状态
│   └── decisions.md         ← AI 的决策记录（置信度 < 80 时）
├── diagnostics/             ← 诊断日志（每次运行一个目录）
│   └── 2024-01-15T10-30-00/
│       ├── agent-output.jsonl
│       ├── orchestration.jsonl
│       └── errors.jsonl
├── loops.json               ← 所有循环的注册表
├── loop.lock                ← 主循环的 PID 和提示词
├── tasks/                   ← 代码任务文件（.code-task.md）
└── specs/                   ← 规格文档（设计文档等）

环境变量