research-ledger-debug

name

research-ledger-debug

description

Debugs Research verification flows via Research Ledger read-only HTTP API (/api/ops/*): list/filter verification tasks, fetch task detail with scores and price path, fetch raw research records. Use when investigating wrong verdicts, missing tasks, roundId/pmId/agentUrl traces, or LLM analyses. Not a generic admin console skill. Requires RESEARCH_LEDGER_BASE_URL and HUBBLE_ADMIN_KEY; never print the key.

Research Ledger 排障（Ops 只读 API）

通过 Ledger 暴露的 /api/ops/* 做 Research 验证链 调试：任务列表、单任务评分详情、原始 record（含 analyses）。不是运营后台、积分、Market 那类「admin 控制台」能力。

接口规范见 docs/ops-api.md（参数、响应、错误码）。此处只固定 环境与三条路由。

When to use

用户在查 Research 验证任务、评分/价格路径、raw research record / LLM analyses，或按 roundId / pmId / agentUrl 追踪时使用本 skill。

Requirements

从环境变量读取（勿让用户粘贴密钥到聊天）：

• RESEARCH_LEDGER_BASE_URL — Ledger Worker 根 URL，无尾斜杠
• HUBBLE_ADMIN_KEY — 当前环境密钥（请求头名仍为 X-Hubble-Admin-Key）

Safety rules

• Never print HUBBLE_ADMIN_KEY in any response or tool output.
• Use the Bash tool with curl only.
• Always pass --fail-with-body; surface non-2xx bodies to the user verbatim.

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（见 docs/ops-api.md §1）。

三条接口

1. 验证任务列表

GET /api/ops/verification/tasks — 查询参数见 docs/ops-api.md §3.1。

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

2. 单条验证任务详情

GET /api/ops/verification/tasks/:id — id 形如 vt_<roundId>_<endpointId>_<symbol>（§3.2）。

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

3. 原始 research record

GET /api/ops/research-records/:id — id 形如 rc_<roundId>_<endpointId>（§3.3）。

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。