名称： ralph-operations
描述： 用于管理 Ralph 编排循环、分析诊断数据、调试帽子选择、调查背压或进行事后分析
标签： [loops, diagnostics, debugging, analysis]

Ralph 运维指南

管理、监控和诊断 Ralph 编排循环。

循环管理

快速参考

循环 ID 格式： 支持部分匹配 - a3f2 可匹配 loop-20250124-143052-a3f2

循环状态

启动与停止

循环通过 ralph run 自动启动：
- 主循环：在主工作区运行，持有 .ralph/loop.lock 文件
- 工作树循环：当主循环运行时创建，隔离在 .worktrees/<loop-id>/ 目录中

ralph loops                       # 有任何循环在运行吗？
cat .ralph/loop.lock 2>/dev/null  # 查看主循环详情
ralph loops stop <id>             # 优雅停止
ralph loops stop <id> --force     # 立即停止
ralph loops discard <id>          # 放弃并清理工作树

检查循环

ralph loops diff <id>             # 查看变更内容
ralph loops logs <id> -f          # 实时查看事件日志
ralph loops history <id>          # 查看状态变更历史
ralph loops attach <id>           # 进入工作树 shell

工作树上下文文件（位于 .worktrees/<loop-id>/）：

主循环使用仓库根目录下 .ralph/agent/ 中的相同文件。

合并队列

流程：Queued → Merging → Merged 或 → NeedsReview → Merging (retry) 或 → Discarded

ralph loops merge <id>            # 加入合并队列
ralph loops process               # 立即处理待合并项
ralph loops retry <id>            # 重试失败的合并

读取状态：

jq -r '.prompt' .ralph/loop.lock 2>/dev/null
tail -20 .ralph/merge-queue.jsonl | jq .

诊断

启用诊断

RALPH_DIAGNOSTICS=1 ralph run -p "你的提示词"

禁用时零开销。输出目录：.ralph/diagnostics/<YYYY-MM-DDTHH-MM-SS>/

会话发现

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

文件参考

诊断工作流

1. 先看错误：

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. 编排流程：

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. 代理活动：

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. 性能：

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. 追踪日志：

jq 'select(.level == "ERROR" or .level == "WARN")' "$SESSION/trace.jsonl"

快速健康检查

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--- 使用的帽子 ---"
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"

故障排除

陈旧进程

ralph loops 显示未运行的循环 → 使用 ralph loops prune

孤立工作树

.worktrees/ 目录存在但 ralph loops 未列出 → 使用 ralph loops prune 或 git worktree remove .worktrees/<id> --force

合并冲突

循环卡在 needs-review 状态：
1. ralph loops diff <id> — 查看冲突变更
2. ralph loops attach <id> — 手动解决，提交，重试
3. ralph loops discard <id> — 如果不值得修复则放弃

锁死

提示“循环已在运行”但实际没有 → rm .ralph/loop.lock（如果进程已死，此操作安全）

代理卡在循环中

jq -s '[.[] | select(.type == "tool_call")] | group_by(.name) | map({tool: .[0].name, count: length}) | sort_by(-.count)' "$SESSION/agent-output.jsonl"

危险信号：许多迭代但事件很少 = 代理未取得进展。

合并卡在 "merging" 状态

合并过程中进程死亡。解除阻塞：

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>

工作树损坏

git worktree repair
ralph loops prune

清理

ralph clean --diagnostics              # 删除所有诊断会话
ralph clean --diagnostics --dry-run    # 预览待删除项