Tracing

QitOS 会为每次运行写出结构化追踪记录产物，从而支持回放、差异比较、导出与审计。

追踪记录（tracing）是 QitOS 可观测性的持久化层。每次启用追踪记录的运行都会写出一个自包含目录：

<trace_logdir>/<run_id>/
  manifest.json
  events.jsonl
  steps.jsonl

​

三个文件分别表示什么

文件	作用
manifest.json	运行摘要、复现元信息、基准测试元信息与官方运行字段
events.jsonl	运行时阶段的事件流
steps.jsonl	每个已完成步骤的结构化记录

原始文件是事实来源，qita 是建立在这些产物之上的人工检查层。

​

为什么追踪记录是一等特性

QitOS 面向的是智能体研究，而不仅是一次性演示。

这意味着框架必须能回答下列问题：

• 运行是怎么停下来的
• 它用的是什么提示词/解析器契约
• 它看到了哪些工具
• 上下文在长时运行中如何变化
• 哪些配置字段决定了回放和比较的意义

因此 AgentModule.run(...) 默认开启追踪记录。

​

v0.3 中的重要追踪记录元信息

v0.3 补强了清单中的复现字段，包括：

• git_sha
• package_version
• benchmark_name
• benchmark_split
• model_family
• prompt_protocol
• parser_name
• tool_manifest
• run_spec
• experiment_spec
• official_run
• replay_mode
• 令牌/延迟/成本汇总

这些字段让 qita compare 与基准测试结果归一化真正有了稳定语义。

​

尽力回放

QitOS 的追踪记录支持的是研究级尽力回放。

也就是说，它会尽量完整记录复盘需要的信息，但不会承诺远程模型服务提供商或外部环境能被严格确定性重放。

这套追踪记录适合：

• 调试长轨迹智能体
• 比较提示词/解析器/工具变化
• 导出审阅产物
• 回放基准测试失败

但不应被理解为远程模型永远返回完全相同的令牌。

​

用 qita 检查追踪记录

qita board --logdir ./runs
qita replay --run ./runs/<run_id>
qita export --run ./runs/<run_id> --html ./report.html

qita 还支持运行比较，你可以直接回答两次运行为什么不同，不需要手工读 JSON。

​

继续阅读

• 官方运行
• 可观测性
• CLI 参考
• 回放并检查失败运行