跳转到主要内容
Tracing 是 QitOS observability 的持久化层。 每次启用 trace 的 run 都会写出一个自包含目录： 
<trace_logdir>/<run_id>/
  manifest.json
  events.jsonl
  steps.jsonl

​
三个文件分别表示什么

文件作用
manifest.jsonrun 摘要、复现元信息、benchmark 元信息与 official-run 字段
events.jsonlruntime phases 的事件流
steps.jsonl每个已完成 step 的结构化记录
原始文件是事实来源，qita 是建立在这些 artifacts 之上的人工检查层。

​
为什么 tracing 是一等特性

QitOS 面向的是 agent 研究，而不仅是一次性 demo。 这意味着框架必须保留下列问题的答案：
  • run 是怎么停下来的
  • 它用的是什么 prompt / parser 契约
  • 它看到了哪些 tools
  • 上下文在长时运行中如何变化
  • 哪些配置字段决定了 replay 和 compare 的意义
因此 AgentModule.run(...) 默认开启 tracing。

​
v0.3 中的重要 trace 元信息

v0.3 补强了 manifest 中的复现字段，包括：
  • git_sha
  • package_version
  • benchmark_name
  • benchmark_split
  • model_family
  • prompt_protocol
  • parser_name
  • tool_manifest
  • run_spec
  • experiment_spec
  • official_run
  • replay_mode
  • token / latency / cost 汇总
这些字段让 qita compare 与 benchmark result normalization 真正有了稳定语义。

​
Best-effort replay

QitOS 的 tracing 支持的是 best-effort research replay。 也就是说，它会尽量完整记录复盘需要的信息，但不会承诺远程模型 provider 或外部环境能被严格确定性重放。 这套 trace 适合：
  • 调试长轨迹 agent
  • 比较 prompt / parser / tool 变化
  • 导出审阅 artifact
  • replay benchmark failure
但不应被理解为“远程模型永远返回完全相同的 tokens”。

​
用 qita 检查 traces

qita board --logdir ./runs
qita replay --run ./runs/<run_id>
qita export --run ./runs/<run_id> --html ./report.html
qita 还支持 run compare，所以你可以直接回答“两次 run 为什么不同”，而不是手工读 JSON。

​
继续阅读