research-ledger-debug

name	research-ledger-debug
description	Debug Research verification via Ledger read-only /api/ops/* (list tasks, task detail with scores, raw research records). Use for wrong verdicts, missing tasks, roundId/pmId/agentUrl traces, LLM analyses. Needs RESEARCH_LEDGER_BASE_URL and HUBBLE_ADMIN_KEY; never print the key.

Research Ledger 排障（Ops 只读 API）

通过 Ledger /api/ops/* 调试 Research 验证链：任务列表、单任务评分详情、原始 record（含 analyses）。不是运营后台类能力。

完整参数与响应见 docs/ops-api.md。

When to use

验证任务、评分曲线、research record / analyses，或按 roundId、pmId、agentUrl 追踪时启用。

Requirements

• RESEARCH_LEDGER_BASE_URL（无尾斜杠）
• HUBBLE_ADMIN_KEY（header：X-Hubble-Admin-Key）

Safety rules

• Never print HUBBLE_ADMIN_KEY.
• Use curl via the bash tool only.
• Use --fail-with-body; show non-2xx bodies to the user.

Tools

Use the bash tool to run the curl commands below.

Setup

: "${RESEARCH_LEDGER_BASE_URL:?set RESEARCH_LEDGER_BASE_URL}"
: "${HUBBLE_ADMIN_KEY:?set HUBBLE_ADMIN_KEY}"
BASE="${RESEARCH_LEDGER_BASE_URL%/}"
HDR=(-H "X-Hubble-Admin-Key: $HUBBLE_ADMIN_KEY")

未带 header 可能 404（隐身）；错 key 401（见文档 §1）。

Endpoints

List verification tasks

GET /api/ops/verification/tasks — 参数 §3.1。

curl -sS --fail-with-body -G "$BASE/api/ops/verification/tasks" "${HDR[@]}" \
  --data-urlencode "roundId=round_xxx" \
  --data-urlencode "pageSize=20"

Task detail

GET /api/ops/verification/tasks/:id

TASK_ID="vt_round_xxx_ep_yyy_BTCUSDT"
curl -sS --fail-with-body "$BASE/api/ops/verification/tasks/$TASK_ID" "${HDR[@]}"

Raw research record

GET /api/ops/research-records/:id

RECORD_ID="rc_round_xxx_ep_yyy"
curl -sS --fail-with-body "$BASE/api/ops/research-records/$RECORD_ID" "${HDR[@]}"

性能注意见 docs/ops-api.md §6。