name: ralph-operations description: 用于管理Ralph编排循环、分析诊断数据、调试hat选择、调查backpressure或执行事后分析 tags: [loops, diagnostics, debugging, analysis]

Ralph操作

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

循环管理

快速参考

任务	命令
列出活跃循环	`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

循环状态

状态	颜色	含义
running	green	循环正在主动执行
queued	blue	已完成，等待合并
merging	yellow	合并进行中
needs-review	red	合并失败，需要干预
merged	dim	成功合并（使用`--all`时显示）
discarded	dim	已废弃（使用`--all`时显示）

启动与停止

循环通过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/events.jsonl`	事件流：hats、迭代、工具调用
`.ralph/agent/summary.md`	当前会话摘要
`.ralph/agent/handoff.md`	下一迭代的交接上下文
`.ralph/agent/scratchpad.md`	工作笔记
`.ralph/agent/tasks.jsonl`	运行时任务状态

主循环使用仓库根目录下.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"

文件参考

文件	包含内容	关键字段
`agent-output.jsonl`	代理文本、工具调用、结果	`type`, `iteration`, `hat`
`orchestration.jsonl`	Hat选择、事件、backpressure	`event.type`, `iteration`, `hat`
`performance.jsonl`	计时、延迟、令牌计数	`metric.type`, `iteration`, `hat`
`errors.jsonl`	解析错误、验证失败	`error_type`, `message`, `context`
`trace.jsonl`	所有带元数据的跟踪日志	`level`, `target`, `message`

诊断工作流

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 "
--- 错误 ---"
wc -l < "$SESSION/errors.jsonl" 2>/dev/null || echo "0"
echo -e "
--- 迭代 ---"
jq -s 'map(select(.event.type == "iteration_started")) | length' "$SESSION/orchestration.jsonl"
echo -e "
--- 使用的Hats ---"
jq -s '[.[] | select(.event.type == "hat_selected") | .event.hat] | unique' "$SESSION/orchestration.jsonl"
echo -e "
--- Backpressure计数 ---"
jq -s 'map(select(.event.type == "backpressure_triggered")) | length' "$SESSION/orchestration.jsonl"
echo -e "
--- 终止 ---"
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：

ralph loops diff <id> — 查看冲突变更
ralph loops attach <id> — 手动解决、提交、重试
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":"合并进程死亡"}}' >> .ralph/merge-queue.jsonl
ralph loops discard <loop-id>

工作树损坏

git worktree repair
ralph loops prune

清理

ralph clean --diagnostics              # 删除所有会话
ralph clean --diagnostics --dry-run    # 预览删除