Back to Details

ralph-operations

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ralph Operations

Ralph 运维操作

Manage, monitor, and diagnose Ralph orchestration loops.
管理、监控并诊断Ralph编排循环。

Loop Management

循环管理

Quick Reference

快速参考

TaskCommand
List active loops
ralph loops
List all (including merged)
ralph loops --all
View loop changes
ralph loops diff <id>
View loop logs
ralph loops logs <id>
Follow logs live
ralph loops logs <id> -f
Stop running loop
ralph loops stop <id>
Merge completed loop
ralph loops merge <id>
Retry failed merge
ralph loops retry <id>
Abandon loop
ralph loops discard <id>
Clean stale processes
ralph loops prune
Loop ID format: Partial matching works - 
a3f2
matches 
loop-20250124-143052-a3f2
任务命令
列出活跃循环
ralph loops
列出所有循环（含已合并）
ralph loops --all
查看循环变更
ralph loops diff <id>
查看循环日志
ralph loops logs <id>
实时跟踪日志
ralph loops logs <id> -f
停止运行中的循环
ralph loops stop <id>
合并已完成的循环
ralph loops merge <id>
重试失败的合并
ralph loops retry <id>
废弃循环
ralph loops discard <id>
清理僵死进程
ralph loops prune
循环ID格式： 支持部分匹配 - 
a3f2
可匹配 
loop-20250124-143052-a3f2

Loop Status

循环状态

StatusColorMeaning
runninggreenLoop is actively executing
queuedblueCompleted, waiting for merge
mergingyellowMerge in progress
needs-reviewredMerge failed, requires intervention
mergeddimSuccessfully merged (with 
--all
)
discardeddimAbandoned (with 
--all
)
状态颜色含义
running绿色循环正在执行
queued蓝色已完成，等待合并
merging黄色合并中
needs-review红色合并失败，需要人工干预
merged灰色合并成功（需加
--all
参数显示）
discarded灰色已废弃（需加
--all
参数显示）

Starting & Stopping

启动与停止

Loops start automatically via 
ralph run
:
  • Primary loop: Runs in main workspace, holds 
    .ralph/loop.lock
  • Worktree loop: Created when primary is running, isolated in 
    .worktrees/<loop-id>/
bash
ralph loops                       # Any loops running?
cat .ralph/loop.lock 2>/dev/null  # Primary loop details
ralph loops stop <id>             # Graceful stop
ralph loops stop <id> --force     # Immediate stop
ralph loops discard <id>          # Abandon + clean worktree
循环通过
ralph run
自动启动：
  • 主循环：在主工作区运行，持有
    .ralph/loop.lock
    文件
  • 工作树循环：主循环运行时创建，隔离在
    .worktrees/<loop-id>/
    目录中
bash
ralph loops                       # 查看是否有运行中的循环？
cat .ralph/loop.lock 2>/dev/null  # 查看主循环详情
ralph loops stop <id>             # 优雅停止
ralph loops stop <id> --force     # 强制立即停止
ralph loops discard <id>          # 废弃并清理工作树

Inspecting Loops

检查循环

bash
ralph loops diff <id>             # What changed
ralph loops logs <id> -f          # Live event log
ralph loops history <id>          # State changes
ralph loops attach <id>           # Shell into worktree
Worktree context files (
.worktrees/<loop-id>/
):
FileContents
.ralph/events.jsonl
Event stream: hats, iterations, tool calls
.ralph/agent/summary.md
Current session summary
.ralph/agent/handoff.md
Handoff context for next iteration
.ralph/agent/scratchpad.md
Working notes
.ralph/agent/tasks.jsonl
Runtime task state
Primary loop uses the same files at 
.ralph/agent/
in repo root.
bash
ralph loops diff <id>             # 查看变更内容
ralph loops logs <id> -f          # 实时事件日志
ralph loops history <id>          # 查看状态变更历史
ralph loops attach <id>           # 进入工作树的Shell环境
工作树上下文文件（位于
.worktrees/<loop-id>/
）：
文件内容
.ralph/events.jsonl
事件流：Hat、迭代、工具调用
.ralph/agent/summary.md
当前会话摘要
.ralph/agent/handoff.md
供下一次迭代使用的交接上下文
.ralph/agent/scratchpad.md
工作笔记
.ralph/agent/tasks.jsonl
运行时任务状态
主循环在仓库根目录的
.ralph/agent/
目录中使用相同的文件。

Merge Queue

合并队列

Flow: 
Queued → Merging → Merged
or 
→ NeedsReview → Merging (retry)
or 
→ Discarded
bash
ralph loops merge <id>            # Queue for merge
ralph loops process               # Process pending merges now
ralph loops retry <id>            # Retry failed merge
Reading state:
bash
jq -r '.prompt' .ralph/loop.lock 2>/dev/null
tail -20 .ralph/merge-queue.jsonl | jq .
流程：
已排队 → 合并中 → 已合并
或 
→ 需要审核 → 合并中（重试）
或 
→ 已废弃
bash
ralph loops merge <id>            # 加入合并队列
ralph loops process               # 立即处理待合并任务
ralph loops retry <id>            # 重试失败的合并
读取状态：
bash
jq -r '.prompt' .ralph/loop.lock 2>/dev/null
tail -20 .ralph/merge-queue.jsonl | jq .

Diagnostics

诊断功能

Enabling

启用诊断

bash
RALPH_DIAGNOSTICS=1 ralph run -p "your prompt"
Zero overhead when disabled. Output: 
.ralph/diagnostics/<YYYY-MM-DDTHH-MM-SS>/
bash
RALPH_DIAGNOSTICS=1 ralph run -p "your prompt"
禁用时无额外性能开销。输出目录：
.ralph/diagnostics/<YYYY-MM-DDTHH-MM-SS>/

Session Discovery

会话查找

bash
LATEST=$(ls -t .ralph/diagnostics/ | head -1)
SESSION=".ralph/diagnostics/$LATEST"
bash
LATEST=$(ls -t .ralph/diagnostics/ | head -1)
SESSION=".ralph/diagnostics/$LATEST"

File Reference

文件参考

FileContainsKey Fields
agent-output.jsonl
Agent text, tool calls, results
type
, 
iteration
, 
hat
orchestration.jsonl
Hat selection, events, backpressure
event.type
, 
iteration
, 
hat
performance.jsonl
Timing, latency, token counts
metric.type
, 
iteration
, 
hat
errors.jsonl
Parse errors, validation failures
error_type
, 
message
, 
context
trace.jsonl
All tracing logs with metadata
level
, 
target
, 
message
文件包含内容关键字段
agent-output.jsonl
Agent文本、工具调用、结果
type
, 
iteration
, 
hat
orchestration.jsonl
Hat选择、事件、背压
event.type
, 
iteration
, 
hat
performance.jsonl
计时、延迟、Token计数
metric.type
, 
iteration
, 
hat
errors.jsonl
解析错误、验证失败
error_type
, 
message
, 
context
trace.jsonl
所有带元数据的跟踪日志
level
, 
target
, 
message

Diagnostic Workflow

诊断工作流

1. Errors first:
bash
wc -l "$SESSION/errors.jsonl"
jq '.' "$SESSION/errors.jsonl"
jq -s 'group_by(.error_type) | map({type: .[0].error_type, count: length})' "$SESSION/errors.jsonl"
2. Orchestration flow:
bash
jq '{iter: .iteration, hat: .hat, event: .event.type}' "$SESSION/orchestration.jsonl"
jq 'select(.event.type == "hat_selected") | {iter: .iteration, hat: .event.hat, reason: .event.reason}' "$SESSION/orchestration.jsonl"
jq 'select(.event.type == "backpressure_triggered") | {iter: .iteration, reason: .event.reason}' "$SESSION/orchestration.jsonl"
3. Agent activity:
bash
jq 'select(.type == "tool_call") | {iter: .iteration, tool: .name}' "$SESSION/agent-output.jsonl"
jq -s '[.[] | select(.type == "tool_call")] | group_by(.iteration) | map({iter: .[0].iteration, tools: [.[].name]})' "$SESSION/agent-output.jsonl"
4. Performance:
bash
jq 'select(.metric.type == "iteration_duration") | {iter: .iteration, ms: .metric.duration_ms}' "$SESSION/performance.jsonl"
jq -s '[.[] | select(.metric.type == "token_count")] | {total_in: (map(.metric.input) | add), total_out: (map(.metric.output) | add)}' "$SESSION/performance.jsonl"
5. Trace logs:
bash
jq 'select(.level == "ERROR" or .level == "WARN")' "$SESSION/trace.jsonl"
1. 优先检查错误：
bash
wc -l "$SESSION/errors.jsonl"
jq '.' "$SESSION/errors.jsonl"
jq -s 'group_by(.error_type) | map({type: .[0].error_type, count: length})' "$SESSION/errors.jsonl"
2. 编排流程：
bash
jq '{iter: .iteration, hat: .hat, event: .event.type}' "$SESSION/orchestration.jsonl"
jq 'select(.event.type == "hat_selected") | {iter: .iteration, hat: .event.hat, reason: .event.reason}' "$SESSION/orchestration.jsonl"
jq 'select(.event.type == "backpressure_triggered") | {iter: .iteration, reason: .event.reason}' "$SESSION/orchestration.jsonl"
3. Agent活动：
bash
jq 'select(.type == "tool_call") | {iter: .iteration, tool: .name}' "$SESSION/agent-output.jsonl"
jq -s '[.[] | select(.type == "tool_call")] | group_by(.iteration) | map({iter: .[0].iteration, tools: [.[].name]})' "$SESSION/agent-output.jsonl"
4. 性能分析：
bash
jq 'select(.metric.type == "iteration_duration") | {iter: .iteration, ms: .metric.duration_ms}' "$SESSION/performance.jsonl"
jq -s '[.[] | select(.metric.type == "token_count")] | {total_in: (map(.metric.input) | add), total_out: (map(.metric.output) | add)}' "$SESSION/performance.jsonl"
5. 跟踪日志：
bash
jq 'select(.level == "ERROR" or .level == "WARN")' "$SESSION/trace.jsonl"

Quick Health Check

快速健康检查

bash
SESSION=".ralph/diagnostics/$(ls -t .ralph/diagnostics/ | head -1)"
echo "=== Session: $SESSION ==="
echo -e "\n--- Errors ---"
wc -l < "$SESSION/errors.jsonl" 2>/dev/null || echo "0"
echo -e "\n--- Iterations ---"
jq -s 'map(select(.event.type == "iteration_started")) | length' "$SESSION/orchestration.jsonl"
echo -e "\n--- Hats Used ---"
jq -s '[.[] | select(.event.type == "hat_selected") | .event.hat] | unique' "$SESSION/orchestration.jsonl"
echo -e "\n--- Backpressure Count ---"
jq -s 'map(select(.event.type == "backpressure_triggered")) | length' "$SESSION/orchestration.jsonl"
echo -e "\n--- Termination ---"
jq 'select(.event.type == "loop_terminated")' "$SESSION/orchestration.jsonl"
bash
SESSION=".ralph/diagnostics/$(ls -t .ralph/diagnostics/ | head -1)"
echo "=== 会话: $SESSION ==="
echo -e "\n--- 错误统计 ---"
wc -l < "$SESSION/errors.jsonl" 2>/dev/null || echo "0"
echo -e "\n--- 迭代次数 ---"
jq -s 'map(select(.event.type == "iteration_started")) | length' "$SESSION/orchestration.jsonl"
echo -e "\n--- 使用的Hat ---"
jq -s '[.[] | select(.event.type == "hat_selected") | .event.hat] | unique' "$SESSION/orchestration.jsonl"
echo -e "\n--- 背压触发次数 ---"
jq -s 'map(select(.event.type == "backpressure_triggered")) | length' "$SESSION/orchestration.jsonl"
echo -e "\n--- 终止原因 ---"
jq 'select(.event.type == "loop_terminated")' "$SESSION/orchestration.jsonl"

Troubleshooting

故障排查

Stale Processes

僵死进程

ralph loops
shows loops that aren't running → 
ralph loops prune
ralph loops
显示的循环实际并未运行 → 使用
ralph loops prune
清理

Orphan Worktrees

孤立工作树

.worktrees/
has directories not in 
ralph loops
→ 
ralph loops prune
or 
git worktree remove .worktrees/<id> --force
.worktrees/
目录中存在
ralph loops
未列出的目录 → 使用
ralph loops prune
或
git worktree remove .worktrees/<id> --force
删除

Merge Conflicts

合并冲突

Loop stuck in 
needs-review
:
  1. ralph loops diff <id>
    — see conflicting changes
  2. ralph loops attach <id>
    — resolve manually, commit, retry
  3. ralph loops discard <id>
    — abandon if not worth fixing
循环卡在
needs-review
状态：
  1. ralph loops diff <id>
    — 查看冲突变更
  2. ralph loops attach <id>
    — 手动解决冲突，提交后重试
  3. ralph loops discard <id>
    — 若不值得修复则废弃

Lock Stuck

锁卡住

"Loop already running" but nothing is → 
rm .ralph/loop.lock
(safe if process is dead)
提示“Loop already running”但实际无运行中的循环 → 删除
.ralph/loop.lock
（确认进程已终止时操作安全）

Agent Stuck in Loop

Agent陷入循环

bash
jq -s '[.[] | select(.type == "tool_call")] | group_by(.name) | map({tool: .[0].name, count: length}) | sort_by(-.count)' "$SESSION/agent-output.jsonl"
Red flag: Many iterations with few events = agent not making progress.
bash
jq -s '[.[] | select(.type == "tool_call")] | group_by(.name) | map({tool: .[0].name, count: length}) | sort_by(-.count)' "$SESSION/agent-output.jsonl"
危险信号：多次迭代但事件极少 → Agent未取得进展。

Merge Stuck in "merging"

合并卡在“merging”状态

Process died mid-merge. Unblock:
bash
echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%S.000000Z)'","loop_id":"<loop-id>","event":{"type":"needs_review","reason":"Merge process died"}}' >> .ralph/merge-queue.jsonl
ralph loops discard <loop-id>
合并过程中途崩溃。解决方法：
bash
echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%S.000000Z)'","loop_id":"<loop-id>","event":{"type":"needs_review","reason":"Merge process died"}}' >> .ralph/merge-queue.jsonl
ralph loops discard <loop-id>

Worktree Corruption

工作树损坏

bash
git worktree repair
ralph loops prune
bash
git worktree repair
ralph loops prune

Cleanup

清理

bash
ralph clean --diagnostics              # Delete all sessions
ralph clean --diagnostics --dry-run    # Preview deletions
bash
ralph clean --diagnostics              # 删除所有诊断会话
ralph clean --diagnostics --dry-run    # 预览要删除的内容