跳转到主要内容
默认情况下，每次 agent.run() 都会把 trace 写到 ./runs/<run_id>/。qita CLI 会读取这些 traces，并通过本地 web board 提供 run inspection、step-by-step replay 与独立 HTML 导出。

​
Trace artifacts

每个 run 目录都包含三个文件：
文件内容
manifest.json运行元数据：run_id、model_id、status、stop_reason、step_count、event_count、schema_version、prompt_hash、run_config_hash、seed、summary
events.jsonl每行一个 RuntimeEvent，包含 step_id、phase、ts、ok、error 与 payload
steps.jsonl每行一个 StepRecord，包含 step_id、decision、actions、action_results、observation 与 critic_outputs
manifest.json 会在初始化时写出，并在 Engine 退出时 finalize。events.jsonl 与 steps.jsonl 都是 append-only。

​
qita board

qita board 会启动一个本地 HTTP server，发现 log root 下所有 run 目录并渲染成卡片网格。
1

启动 board

qita board --logdir ./runs
默认地址为 http://127.0.0.1:8765。常用参数：
参数默认值说明
--logdir./runs包含各个 run 子目录的根路径
--host127.0.0.1绑定地址
--port8765监听端口
qita board --logdir ./runs --host 0.0.0.0 --port 9000
2

浏览 runs

board 每 2.5 秒自动刷新一次。每个 run 会以卡片形式展示：
  • Run ID
  • Status badge
  • Step count 与 event count
  • Stop reason
  • 更新时间
  • Manifest metadata，如 model ID、schema version、seed、prompt hash
你可以通过工具栏：
  • Search：按 run ID、stop reason、final result 搜索
  • Status filter：按状态筛选
  • Sort：按更新时间、event count 或 step count 排序
  • Auto refresh：开关自动刷新
页面顶部还会展示摘要指标，如 success rate、平均 steps、平均 events 和主要失败 stop reasons。这是最常用的总览界面：qita board 总览
3

打开一个 run

点击任意 run 卡片的 view 即可进入详情页。详情页通常有两个 tab：Traj tab轨迹视图会把每一步显示成一张卡片，通常包含这些折叠区块：
  • State：当前 observation 中的关键状态字段
  • Thought：模型推理文本
  • Action：本步调用的工具
  • Direct Observation：action results；搜索结果会表格化，错误会高亮
  • Critic：critic 输出
  • Trace Events：该 step 的原始 RuntimeEvent
左侧 Step Navigator 支持：
  • 全文过滤
  • 按 event phase 过滤
  • 升序或降序排序
  • 开关 observation / critic 区块
  • 全部折叠或展开
  • 调整字号
顶部还有一个 gantt 风格的 phase timeline，用颜色表示各 phase 时长。Manifest tab直接展示格式化后的 manifest.json。这是逐步检查 agent 行为时最重要的界面：qita trajectory 视图

​
qita replay

qita replay 用于把单次 run 以时间序方式回放出来。 
qita replay --run ./runs/my_agent_20260407_120000_000001
参数默认值说明
--run必填run 目录路径
--host127.0.0.1绑定地址
--port8765监听端口
replay 页支持调整播放速度，URL 上可使用 ?speed=300 指定毫秒级间隔。

​
qita export

qita export 会生成一个自包含的 HTML 文件，便于分享而不必运行本地 server。 
qita export --run ./runs/my_agent_20260407_120000_000001 --html out.html
参数说明
--runrun 目录路径，必填
--html输出 HTML 文件路径，必填
导出文件会内联全部 CSS、JavaScript 与 run 数据，因此可以直接作为审阅 artifact 发送给同事或审稿人。

​
配置 trace 输出

默认情况下，agent.run() 会把 traces 写到 ./runs/，run ID 由 agent 类名与 UTC 时间戳组成。你也可以自定义目录和前缀： 
result = agent.run(
    task="...",
    max_steps=10,
    trace_logdir="./my_experiments",
    trace_prefix="react_v2",
    return_state=True,
)
如果完全不想写 trace，可以传： 
result = agent.run(task="...", trace=False, return_state=True)
也可以传入一个预配置 TraceWriter： 
from qitos.trace import TraceWriter

writer = TraceWriter(
    output_dir="./runs",
    run_id="my_custom_run_id",
    strict_validate=True,
    metadata={"model_id": "Qwen3-8B"},
)

result = agent.run(task="...", trace=writer, return_state=True)
qita 发现 run 至少需要三个文件：manifest.json、events.jsonl 和 steps.jsonl。缺少 manifest.json 的目录会被 qita board 静默跳过。