1.4w e2e-inc

unbox-ai Skill

分析 AI 代理的追踪文件(*.trace.json——gateway 或 opencode 导出,或 .devtools/generations.json AI SDK devtools 数据库,甚至应用仍在写入时也可分析),无需读取原始 JSON。适用于检查代理运行记录、查找缓慢或昂贵的原因、检查缓存效率、调试工具调用,或总结代理做了什么。所有命令均为只读且输出有上限,可放心随意运行。

安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。

查看源码

技能指令原文(SKILL.md)

unbox-ai: explore AI traces from the CLI

Traces are too big to read raw (megabytes of duplicated context). unbox-ai
normalizes them and answers questions with bounded output. Never cat or Read
a trace file - always go through the CLI.

Run via npx unbox-ai (or node dist/cli/index.js in the unbox-ai repo).

Workflow

Always start wide, then drill:

unbox-ai runs <trace>           # multi-run sources only: one line per independent run
unbox-ai summary <trace>        # who/what/cost + one line per generation
unbox-ai tools <trace>          # per-tool usage: calls, failures, time, output size
unbox-ai events <trace>         # table: tokens, latency, cost per generation
unbox-ai event <trace> <idx>    # one generation: metrics + only its NEW messages
unbox-ai messages <trace> --grep <q> [--role r] [--event n] [--limit n]
unbox-ai get <trace> '<path>'   # exact raw value, e.g. events[3].messages[2].content
unbox-ai compare <a> <b>        # A/B: metric deltas + system prompt / tool-set diff
  • --json on summary/events/event/tools/messages for machine-readable output

(unbounded - prefer the plain forms first).

  • --run scopes any text command to one run of a multi-run source

(AI SDK devtools databases hold many). Without it they see the whole file
merged. Keep passing the same --run when following printed pointers -
generation indexes are run-local.

  • Truncated output always prints the exact get invocation that returns the

rest. Follow those pointers instead of guessing paths.

  • --grep accepts regex; invalid regex silently falls back to literal search.
  • tools --all lists every individual call with args.
  • compare answers "what changed between these two runs": token/cost/time

deltas, a task diff (differing tasks make deltas misleading), per-tool
usage deltas, then a line diff of the system prompt and the tool-set
changes - added/removed names plus, per changed tool, what changed
(description or schema). Two runs of one file: compare --run 0 --run 1 (first --run
scopes A, second B). Diff output is bounded; --json has the full diff.
--trajectory adds a content-aligned action table (* = differing step,

  • = no counterpart; alignment is LCS over tool sequences, so an extra step

in one run offsets nothing) - the fastest way to see where two runs
actually diverged.

  • unbox-ai view starts a localhost visualization - only offer this

to the human; as an agent, stay on the read commands.

Reading the numbers

  • generation = one model request/response. segment = one conversation

thread (resets and interleaved agents split threads).

  • caching NN% = input tokens that were a repeated, cache-eligible prefix

(real cache reads when the trace reports them, else inferred from repeats).

  • cost - = the source reports no dollar amounts (AI SDK devtools traces);

reason about tokens instead.

  • latency NN% prompt wait = share of model time spent re-reading input

(TTFT). High = the run is prompt-bound; shrinking resent context cuts both
cost and wall-clock.

  • re-paid ~N tokens = identical system prompt/tools re-processed because

fresh conversations start from zero - a prompt-caching or one-conversation
opportunity.

  • event shows only messages NEW in that generation; earlier context is in

prior events of the same segment.

Analysis recipes

Cost hotspots (which segment/agent burns the money):

unbox-ai events <trace> --json | jq 'group_by(.segment) | map({seg: .[0].segment, model: .[0].model, cost: ([.[].cost] | add), in: ([.[].inputTokens] | add)}) | sort_by(-.cost)'

Retry loops (same tool + same args repeating = a stuck agent):

unbox-ai tools <trace> --json | jq 'group_by(.name + (.args|tostring)) | map(select(length > 2) | {call: .[0].name, args: .[0].args, times: length})'

Latency outliers: unbox-ai events and scan the latency column;
drill into the outlier with event, and check its tool durations in
tools --all (wait-style tools show their requested duration).

Failures: unbox-ai tools failed column, then
messages --grep "error|failed" for the evidence trail.

Supported formats

Gateway exports ({events[]} with cumulative message snapshots), opencode
session exports ({info, messages[{info, parts}]}), and AI SDK devtools
databases ({runs[], steps[]}, usually .devtools/generations.json) are
auto-detected - summary prints which. Unknown files fail with a readable
error; do not retry with other commands.

Live AI SDK apps (devtools databases)

A project instrumented with @ai-sdk/devtools writes every AI SDK call to
.devtools/generations.json in the app's cwd - analyze it with the commands
above WHILE the app runs. Each command reads a fresh snapshot, so this is the
way to debug an agent mid-flight:

unbox-ai runs .devtools/generations.json            # what ran / is running ([live])
unbox-ai summary .devtools/generations.json --run 2 # drill into one run
unbox-ai tools .devtools/generations.json --run 2   # its tool behavior
  • Always start with runs on these files and scope with --run; the

unscoped view merges every run and its indexes shift as the app appends.

  • A run marked [live] (or a generation with latency 0.00s and no output)

is still executing - re-run the command for updated state.

  • unbox-ai devtools serves a live browser viewer of the same file; only

offer it to the human, as an agent stay on the read commands.

配合站内内容