用途:在 CLI 中探索和排查 AI 智能体 trace,避免直接 cat/Read 兆字节级的原始文件。支持 gateway 导出({events[]} 累积消息快照)、opencode 会话导出({info, messages[{info, parts}]})以及 AI SDK devtools 数据库({runs[], steps[]},通常为 .devtools/generations.json),格式自动识别。
主要能力:runs 列出多运行来源的独立运行;summary 输出主体、成本与每次 generation 概览;tools 统计每个工具的调用、失败、耗时与输出大小;events/event 查看 token、延迟、成本及单次 generation 的新增消息;messages 支持按关键词、角色、事件、数量过滤;get 按路径取原始值;compare 对比两次运行的指标增量、系统提示与工具集差异,并可用 --trajectory 显示内容对齐的动作表;view 启动本地可视化(仅面向人类)。summary/events/event/tools/messages 支持 --json。
使用方式:通过 npx unbox-ai 运行,或在 unbox-ai 仓库用 node dist/cli/index.js。建议先宽后深,先 runs/summary 再 drill。多运行来源需用 --run <n|id> 限定;跟踪打印出的指针时要沿用同一 --run。截断输出会打印获取其余内容的准确 get 调用。--grep 支持正则,无效正则回退为字面搜索。
实时调试:被 @ai-sdk/devtools 插桩的应用会把每次调用写入 cwd 下 .devtools/generations.json,可在应用运行中分析;每条命令读取新快照。标记 [live] 或延迟 0.00s 且无输出的 generation 仍在执行,可重跑命令。建议先用 runs 再用 --run 限定;不限定时会合并所有运行且索引会随追加而变动。
限制:未提供收费或价格信息。cost 显示 - 表示来源未报告金额(AI SDK devtools trace),此时应基于 token 分析。未知文件会给出可读错误,不要换命令重试。