rock-agent-debug

Rock エージェントデバッグスキル

rockcli を使用して、ROCK サンドボックスで実行される Agent Job（Harbor Job／Bash Job）を調査・トラブルシューティングし、最終的に詳細なレポートをファイルに保存します。

背景

ROCK サンドボックスは、次の 2 種類の Job に対応しています。

種類	Config クラス	Trial クラス	識別方法
Harbor Job	HarborJobConfig	HarborTrial	orchestrator、datasets、agents、jobs_dir、experiment_id フィールドがある
Bash Job	BashJobConfig	BashTrial	script または script_path フィールドがあり、harbor 関連のフィールドがない

Job の種類は YAML 設定から自動的に検出されます。まず HarborJobConfig で解析を試み、失敗した場合は BashJobConfig にフォールバックします。

2 種類のトラブルシューティング経路

情報源に応じて、トラブルシューティングの経路は 2 種類に分かれます。

経路	適用シナリオ	主なコマンド
リモート照会（推奨）	ユーザーから実験 ID と Job ID（または job 名のみ）が提供されている。サンドボックスが停止しており、exec できない	rc agent view + rc agent fs
サンドボックス内照会	ユーザーからサンドボックス ID が提供され、サンドボックスが稼働している。より柔軟な調査が必要	rc sandbox <id> exec

リモート照会を優先してください。agent view と agent fs はサンドボックスの稼働状態に依存せず、job／trial のメタデータとファイルを直接確認できるため、より効率的です。

リモート照会のクイックフロー

# 1. 查看 job 状态和 trial 列表
rockcli agent view -e <exp_id> -j <job_name>

# 2. 列出 trial 文件
rockcli agent fs ls -e <exp_id> -j <job_name> -t <task_name>

# 3. 读取关键文件
rockcli agent fs cat result.json -e <exp_id> -j <job_name> -t <task_name>
rockcli agent fs cat agent/log.txt -e <exp_id> -j <job_name> -t <task_name>

# 4. 查看执行轨迹
rockcli agent view -e <exp_id> -j <job_name> --trajectory

# 5. 查看 artifacts
rockcli agent fs artifacts -e <exp_id> -j <job_name> -t <task_name>

重要な原則

必要な情報が得られたら、照会を終了してください。 ファイルが想定した場所にないからといって、ディスク全体を検索し続けないでください。判断基準：

• Harbor Job（/data/logs/user-defined/）：.out ファイルに実行ログ全体が含まれており、reward を確認できれば十分です
• Harbor Job（/tmp/harbor/jobs/）：result.json + trial.log + exception.txt があれば十分です
• Bash Job：.out ログ + スクリプトの終了コード + artifact（ある場合）があれば十分です
• 重要なファイルから状況を把握できる場合は、それ以上探す必要はありません。手元の情報を使って、そのままレポートを作成してください

---

Step 1：調査の開始点と Job の種類を確認する

ユーザーから提供された情報に基づいて、調査経路を選択します。

ケース A：ユーザーから実験 ID と Job ID が提供されている（リモート照会、推奨の開始点）

最も一般的な開始点は、実験 ID + Job ID の組み合わせです。agent view と agent fs はどちらも -e <experiment_id> で job を指定します。2 つのパラメーターを組み合わせて、順に詳細を確認します。

# 0. （可选）只有实验 ID、不知道 job 名时，先列出实验下的 jobs
rockcli agent view -e <experiment_id>

# 1. 查看 job 详情（实验 ID + Job ID）
rockcli agent view -e <experiment_id> -j <job_name>

# 2. 列出 job 文件（从文件结构判断类型）
rockcli agent fs ls -e <experiment_id> -j <job_name>

job 名のみがあり、実験 ID がない場合は、まず rockcli agent view -E ですべての実験を一覧表示し、該当する experiment_id を見つけてから続行します。

ケース B：ユーザーからサンドボックス ID が提供されている（サンドボックス内照会）

# 查看沙箱存活状态
rockcli sandbox <id> status

# 同时检查所有可能的路径
rockcli sandbox <id> exec 'echo "=== /tmp/harbor/jobs/ ==="; ls -lt /tmp/harbor/jobs/ 2>/dev/null | head -10; echo "=== /data/logs/user-defined/ ==="; ls -lt /data/logs/user-defined/ 2>/dev/null | head -10; echo "=== /data/logs/ ==="; ls -lt /data/logs/*.out /data/logs/*.log 2>/dev/null | head -10'

Job の種類を判定する：

1. YAML 設定を読み取ります（優先）：rockcli sandbox <id> exec 'cat /data/logs/user-defined/<job_name>.yaml'
2. 設定に orchestrator、datasets、agents が含まれている場合 → Harbor Job
3. 設定に script または script_path が含まれている場合 → Bash Job
4. YAML がなく、/tmp/harbor/jobs/ 内にファイルしかない場合 → Harbor Job（ローカルの harbor run）

ユーザーからサンドボックス ID も実験 ID も提供されていない場合は、そのまま尋ねてください。

---

Step 2：対象の Job を特定する

ユーザーが job を指定していない場合は、内容がある最新のものを選びます（空のディレクトリはスキップします）。

# Harbor 路径（本地 harbor run）：找最新非空的 job
rockcli sandbox <id> exec 'for d in $(ls -t /tmp/harbor/jobs/); do if [ "$(ls /tmp/harbor/jobs/$d 2>/dev/null)" ]; then echo $d; break; fi; done'

# ROCK 平台路径：列出 .yaml 配置和 .out 日志
rockcli sandbox <id> exec 'ls -lt /data/logs/user-defined/*.yaml /data/logs/user-defined/*.out 2>/dev/null | head -10'

---

Step 3：Job の情報を読み取る

リモート照会方式（agent view / agent fs）

実験 ID + Job ID がある場合に適用します。サンドボックスの稼働状態に依存しません。

# 查看 job 整体状态（含 tasks 列表、进度）
rockcli agent view -e <exp_id> -j <job_name>

# 列出 job 目录结构
rockcli agent fs ls -e <exp_id> -j <job_name>

# 读取 result.json
rockcli agent fs cat result.json -e <exp_id> -j <job_name> -t <task_name>

# 读取日志文件
rockcli agent fs cat agent/log.txt -e <exp_id> -j <job_name> -t <task_name>

# 查看完整执行轨迹
rockcli agent view -e <exp_id> -j <job_name> --trajectory

# 查看 trial artifacts
rockcli agent fs artifacts -e <exp_id> -j <job_name> -t <task_name>

サンドボックス内照会方式

Harbor Job

/tmp/harbor/jobs/ パス（ローカルの harbor run）

rockcli sandbox <id> exec 'cat /tmp/harbor/jobs/<job_name>/config.json'
rockcli sandbox <id> exec 'cat /tmp/harbor/jobs/<job_name>/result.json 2>/dev/null || echo "no result yet"'
rockcli sandbox <id> exec 'cat /tmp/harbor/jobs/<job_name>/job.log 2>/dev/null'

/data/logs/user-defined/ パス（ROCK プラットフォーム）

# 配置（agent、model、dataset）
rockcli sandbox <id> exec 'cat /data/logs/user-defined/<job_name>.yaml'

# 完整运行日志（含进度、reward、时间线）
rockcli sandbox <id> exec 'cat /data/logs/user-defined/<job_name>.out'

# result.json（可能不存在，不要为此继续搜索）
rockcli sandbox <id> exec 'cat /data/logs/user-defined/jobs/<job_name>/result.json 2>/dev/null || echo "no result.json"'

タスクが完了したかどうかは .out ファイルだけで判断できます（reward の行、完了時刻、trial 名が含まれます）。result.json がないからといって、ディスク全体を検索しないでください。

Bash Job

# 配置（script / script_path）
rockcli sandbox <id> exec 'cat /data/logs/user-defined/<job_name>.yaml'

# 完整运行日志
rockcli sandbox <id> exec 'cat /data/logs/user-defined/<job_name>.out'

# 检查是否有 artifact 输出
rockcli sandbox <id> exec 'ls -lt /data/logs/artifacts/ 2>/dev/null | head -10'

Bash Job の特徴：

• スクリプトを 1 回実行し、trial の概念はありません
• 成功／失敗を判断するうえで、終了コード（exit code）が重要です
• OSS artifact が artifacts/{namespace}/{experiment_id}/{job_name}/ に出力される場合があります
• ログは .out ファイルに直接出力されます

---

Step 4：結果を分析する

Harbor Job：Trial ごとの分析

Trial のファイル構造（/tmp/harbor/jobs/ パス）：

<trial_name>/
├── result.json          # 完整结果（阶段时间、reward、异常）
├── trial.log            # 简短摘要（失败时有错误原因）
├── exception.txt        # 完整异常栈
├── agent/setup/stdout.txt   # Agent 安装日志
├── agent/setup/return-code.txt
├── verifier/reward.txt
├── verifier/test-stdout.txt
├── verifier/test-stderr.txt
└── agent/trajectory.json    # Agent 执行轨迹（ATIF 格式，若有）

# 列出 trials
rockcli sandbox <id> exec 'ls /tmp/harbor/jobs/<job_name>/ 2>/dev/null || ls /data/logs/user-defined/jobs/<job_name>/ 2>/dev/null'

# 批量查看所有 trial 状态（快速）
rockcli sandbox <id> exec 'for t in /tmp/harbor/jobs/<job_name>/*/; do echo "=== $(basename $t) ==="; cat "$t/result.json" 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print(\"reward:\", d.get(\"verifier_result\"), \"exception:\", bool(d.get(\"exception_info\")))" 2>/dev/null || cat "$t/trial.log" 2>/dev/null | head -3; done'

result.json の主なフィールドの説明：

フィールド	意味	異常の兆候
exception_info	例外の種類とメッセージ	null 以外の場合、捕捉されていない例外が発生しています
verifier_result.rewards	各項目の評価スコア	すべて 0 または null の場合、verifier が実行されていません
agent_result	Agent の実行結果	null の場合、Agent が正常に完了していません
agent_execution.duration_sec	Agent の実行時間	極端に短い（<5s）場合、早期に終了しています
environment_setup	環境の起動時間	極端に長い場合、イメージのビルドまたは起動に問題があります
started_at / finished_at	開始／終了時刻	finished_at が null の場合、未完了です

result.json から Trial の現在の段階を判定する：

• environment_setup に値があり、agent_setup が null → 環境の起動中
• agent_setup に値があり、agent_execution が null → Agent のインストール中
• agent_execution に値があり、verifier が null → Agent の実行中
• verifier に値があり、finished_at が null → Verifier の実行中
• finished_at に値がある → 完了

Bash Job：単回実行の分析

Bash Job には trial の概念がなく、スクリプトを 1 回実行します。

# 查看退出码（.out 末尾通常有 exit code）
rockcli sandbox <id> exec 'tail -20 /data/logs/user-defined/<job_name>.out'

# 搜索错误
rockcli sandbox <id> exec 'grep -i "error\|exception\|failed\|traceback" /data/logs/user-defined/<job_name>.out | tail -30'

# 如果有 artifact，检查输出
rockcli sandbox <id> exec 'ls -R /data/logs/artifacts/<namespace>/<experiment_id>/<job_name>/ 2>/dev/null'

---

Step 5：詳細なデバッグ（問題が見つかった場合）

Harbor Job のデバッグ

詳細なログを読み取る

# 1. 如果有 exception.txt，先读它
rockcli sandbox <id> exec 'cat /tmp/harbor/jobs/<job_name>/<trial_name>/exception.txt'

# 2. Verifier 输出（测试脚本的实际运行结果）
rockcli sandbox <id> exec 'cat /tmp/harbor/jobs/<job_name>/<trial_name>/verifier/test-stdout.txt'
rockcli sandbox <id> exec 'cat /tmp/harbor/jobs/<job_name>/<trial_name>/verifier/test-stderr.txt'

# 3. Trial 主日志（先搜关键词）
rockcli sandbox <id> exec 'grep -i "error\|exception\|failed\|traceback" /tmp/harbor/jobs/<job_name>/<trial_name>/trial.log | tail -50'

Docker Container の状態を確認する

Harbor Docker container の命名規則：hb__<environment_name>（小文字）

# 列出所有 Harbor 相关 container
rockcli sandbox <id> exec 'docker ps -a | grep "hb__"'

# 查看 container 详情
rockcli sandbox <id> exec 'docker inspect <container_name> | python3 -c "
import json, sys
data = json.load(sys.stdin)[0]
state = data[\"State\"]
print(f\"Status: {state[chr(39)]Status{chr(39)}}\")
print(f\"ExitCode: {state[chr(39)]ExitCode{chr(39)}}\")
print(f\"OOMKilled: {state[chr(39)]OOMKilled{chr(39)}}\")
"'

# 查看 container 最近日志
rockcli sandbox <id> exec 'docker logs <container_name> --tail 100'

Agent の実行トレースを確認する（必要に応じて）

ユーザーが agent の動作内容を知りたい場合にのみ確認します。

rockcli sandbox <id> exec 'cat /path/to/trial/agent/trajectory.json | python3 -c "
import json, sys
d = json.load(sys.stdin)
steps = d.get(\"steps\", [])
print(f\"共 {len(steps)} 步\")
for i, s in enumerate(steps[:20]):
    tool = s.get(\"tool\", \"\") or s.get(\"action\", \"\")
    summary = s.get(\"observation\", \"\") or s.get(\"result\", \"\")
    print(f\"  [{i+1}] {tool}: {str(summary)[:100]}\")
"'

Bash Job のデバッグ

# 1. 查看完整日志
rockcli sandbox <id> exec 'cat /data/logs/user-defined/<job_name>.out'

# 2. 检查沙箱内执行环境
rockcli sandbox <id> exec 'echo "=== Python ==="; python3 --version 2>/dev/null; echo "=== Node ==="; node --version 2>/dev/null; echo "=== Disk ==="; df -h / 2>/dev/null'

# 3. 如果有 artifact，查看内容
rockcli sandbox <id> exec 'cat /data/logs/artifacts/<namespace>/<experiment_id>/<job_name>/* 2>/dev/null | head -100'

---

Step 6：レポートを作成する（必ず出力し、ローカルファイルに保存する）

分析のたびに、必ず以下を実施してください：

1. 会話内に構造化されたレポートを出力する
2. レポートをローカルファイルに保存する：/tmp/rock-agent-report-<sandbox_id_短>-<timestamp>.md

Harbor Job のレポート形式

## Harbor Job 报告

**沙箱**: <sandbox_id>
**Job**: <job_name>
**类型**: Harbor Job
**时间**: <started_at> → <finished_at 或 "运行中">
**耗时**: <duration>

### 配置
- Agent: <agent_name> (<model_name>)
- Bench: <dataset_name> v<version>（或 Task: <task_path>）
- 并发数: <n_concurrent_trials>
- Verifier 模式: <harbor/native>

### 整体结果
- 总 Trials: <n>，成功: <n>，失败: <n>
- 平均 Reward: <mean>

### Trial 明细
| Trial | 状态 | Reward | 耗时 | 问题 |
|-------|------|--------|------|------|
| <name> | ✅/❌/🔄/⚠️ | <reward> | <duration> | <issue 或 -> |

### 执行时间线
- `<HH:MM>` 环境启动完成（耗时 Xs）
- `<HH:MM>` Agent 安装完成（耗时 Xs）
- `<HH:MM>` Agent 开始执行
- `<HH:MM>` Verifier 完成，reward=<N>

### 问题分析（如有）

**[CRITICAL] 问题标题**
- 影响 trial：`<trial_name>`
- 根本原因：...
- 证据：`exception.txt` 关键日志
- 建议：...

### 行动建议
1. **立即修复**：...
2. **下次运行前**：...

Bash Job のレポート形式

## Bash Job 报告

**沙箱**: <sandbox_id>
**Job**: <job_name>
**类型**: Bash Job
**时间**: <started_at> → <finished_at>
**耗时**: <duration>
**退出码**: <exit_code>

### 配置
- Script: <script 内容或 script_path>
- Environment: <environment 配置>
- Timeout: <timeout>

### 执行结果
- 状态: ✅ 成功 / ❌ 失败
- 退出码: <0 或非零>
- 关键输出: <摘要>

### 日志摘要
<关键日志片段，特别是错误信息>

### 问题分析（如有）
- 根本原因：...
- 证据：日志关键行
- 建议：...

### 行动建议
1. ...

状態アイコン： ✅ 成功 | ❌ 失敗 | 🔄 実行中 | ⚠️ 完了したが異常あり

---

よくある障害のクイックリファレンス

Harbor Job

現象	失敗段階	典型的な原因
"Docker compose command failed" / "no such host"	env_setup	イメージのプル時に DNS エラーが発生
agent/setup/return-code.txt = 100	agent_setup	Agent のインストールスクリプトが失敗
AgentTimeoutError	agent_execution	Agent がタイムアウト
reward=0、例外なし	verifier	Agent は完了したものの、問題を解決できなかった
RewardFileNotFoundError	verifier	reward.txt が存在しない
no running event loop	cleanup	Agent のタイムアウト後、クリーンアップ段階でクラッシュ（主な失敗原因ではありません）
reward.txt が空、または存在しない	verifier	verifier が reward を書き込む手順まで実行されなかった
agent_result が null、実行時間が極端に短い	agent_setup	agent のインストールスクリプトでエラーが発生
すべての trial が同じ exception で失敗	環境レベル	イメージ／依存関係／ネットワークの問題

Bash Job

現象	典型的な原因
終了コードがゼロ以外	スクリプトの実行に失敗
タイムアウトによる終了	timeout の設定が短すぎる、またはスクリプトが停止している
ログが途中で切れている	サンドボックスのリソース不足（OOM／ディスク容量不足）
artifact が出力されない	スクリプトが想定されたパスに書き込んでいない、またはパスの権限に問題がある

Agent の種類に関する参考情報

Agent 名	説明
claude-code	Claude Code CLI
terminus / terminus-2	Terminus 内部の agent
swe-agent-internal	内部 SWE-Agent 実装
openhands	OpenHands agent
mini-swe-agent	軽量な SWE-Agent
aider	Aider コーディングエージェント
opencode	OpenCode agent
oracle	参照用 agent（既知の解答）
nop	何もしない（テスト用）

Harbor Job の一括スキャンスクリプト

#!/usr/bin/env python3
# 用法：python3 scan_job.py ./jobs/<job_name>
import json, sys
from pathlib import Path

job_dir = Path(sys.argv[1])
trials = sorted([d for d in job_dir.iterdir() if d.is_dir()])

print(f"Job: {job_dir.name}")
print(f"{'Trial':<40} {'Reward':<8} {'Status':<12} {'Duration':<10} {'Issue'}")
print("-" * 90)

for trial_dir in trials:
    result_path = trial_dir / "result.json"
    if not result_path.exists():
        print(f"{trial_dir.name:<40} {'N/A':<8} {'NO RESULT':<12} {'-':<10}")
        continue

    try:
        r = json.loads(result_path.read_text())
    except Exception as e:
        print(f"{trial_dir.name:<40} {'ERR':<8} {'JSON ERR':<12} {'-':<10} {e}")
        continue

    reward = "N/A"
    if r.get("verifier_result") and r["verifier_result"].get("rewards"):
        rewards = r["verifier_result"]["rewards"]
        if isinstance(rewards, dict):
            reward = str(list(rewards.values())[0])
        elif isinstance(rewards, list) and rewards:
            reward = str(rewards[0])
    elif (trial_dir / "verifier" / "reward.txt").exists():
        reward = (trial_dir / "verifier" / "reward.txt").read_text().strip()

    exc = r.get("exception_info")
    status = "EXCEPTION" if exc else ("OK" if reward != "N/A" else "NO REWARD")

    duration = "-"
    if r.get("agent_execution") and r["agent_execution"].get("duration_sec"):
        duration = f"{r['agent_execution']['duration_sec']:.1f}s"

    issue = ""
    if exc:
        issue = f"{exc.get('exception_type','?')}: {str(exc.get('exception_message',''))[:50]}"

    print(f"{trial_dir.name:<40} {reward:<8} {status:<12} {duration:<10} {issue}")