轨迹与用量记录
TIP
轨迹回答「这一轮对话中究竟发生了什么」，用量回答「总共消耗了多少资源与成本」。两者共享同一个数据来源：span。轨迹把每次调用拆成可观测的片段，包括一轮对话、单个步骤、一次工具调用和一次子代理运行，用来解释为什么这样回答、为什么这么慢、为什么 Token 超出预期。
Span
一条轨迹是一棵 span 树：
| 类型 | 代表什么 |
|---|---|
turn | 一轮完整对话 |
step | 一次模型请求及其工具执行 |
model | 一次模型调用 |
tool | 一次工具调用 |
subagent | 一次子代理执行 |
chat | 一次对话请求 |
每个 span 记录开始与结束时间、状态、属性、用量和子 span。属性是键值对，通常是模型、提供商、工具名、参数摘要和报错信息。
- 广播：开始时广播一次，结束时再广播一次并附带完整快照。载荷经过深拷贝，订阅者拿不到内部可变引用，异步持久化或界面渲染不会影响写入流程。
- 用量累计：输入、输出、缓存读写与推理 Token 在
span树上逐级向上累计，而不是由各个下游自行计算，所以所有视图看到的数字一致。
消费者
span 事件可以被多个相互独立的消费者订阅，单个消费者异常或阻塞不影响其他消费者：
- 会话存储：写入数据库，供控制台查询。
- 文件输出：追加写入 JSONL，适合离线归档与分析。
- 计费：提取用量并按单价折算费用。
- 自定义：扩展插件自建监控与统计面板。
轨迹页
控制台的「轨迹」页基于持久化数据：按会话列出最近的交互，下钻到某一轮的 span 树，展开节点查看属性、输入输出摘要和报错堆栈。
- 回放：按时间轴单步复现这一轮的全过程。
- 草稿重调：用当时的请求快照重新调用模型，对比提示词改动。
- 进程视图：把并发的步骤与工具调用并排铺在时间线上，找出耗时瓶颈。
TIP
排查「答非所问」时，最有价值的是请求发出时实际装配的上下文，而不是最终回复。轨迹详情里可以看到当时的提示词摘要、可用工具和推理参数。
用量
用量是轨迹数据的聚合视图。每次模型调用结束时记录：
- 提供商与模型
- 用途（对话、判定、提取、摘要等）
- 输入、缓存读取、缓存写入、输出与推理 Token
- 是否流式、总耗时、折算费用
失败的调用同样记录流水，但只有能识别出提供商和模型时才生成计费行。
单价来源：优先使用计费插件或全局配置中填写的价格，其次是模型目录自带的价格。两处都没有时成本记为 0，价格来源标为「无」。价格通常按每百万 Token 计，输入、缓存读取和输出分别定价。
WARNING
成本是估算值，不等于实际账单。中转计费、阶梯折扣、促销和缓存策略都会造成偏差，对账以服务商后台为准。
聚合与导出：明细默认保留 90 天，每日汇总永久保留。汇总可以按日期、模型、用途和会话切分，可以导出为 CSV。
看板：概览卡片（今日花费、请求数、缓存命中率）、趋势图、按模型/会话/用途的分组表，以及单次调用明细。控制台首页也有一张今日用量卡片。
与其他子系统的关系
- 缓存：命中前缀缓存的部分按缓存价计费，而不是全额输入单价。
- 压缩：缩短历史，直接降低后续轮次的 Token 消耗。
- 子代理：用量单独统计，但汇总到同一账户。
- 判定模型：意图识别、唤醒判定等也会产生用量，建议用小模型。
采样与开销
收集轨迹和用量本身也有序列化、写库和广播的开销。调用频率极高时可以只持久化关键类型的 span、降低属性记录粒度，或缩短明细保留期。
常见问题
轨迹页是空的：确认轨迹插件已启用、数据库连接正常，以及该轮确实发起了模型请求。
用量对不上：核对单价配置，检查适配器是否正确提取了缓存 Token，以及是否有调用来自未接入用量收集的实例。
成本一直是 0：配置和模型目录里都没有该模型的单价，在计费配置中补上即可。
某次调用没有记录：检查请求是否在进入执行管线前就抛出了异常，以及轨迹消费者是否有未捕获的报错。
数据太多，查询很慢：缩短明细保留期，或只查预聚合的汇总视图。轨迹用于实时排查，不适合替代长期冷归档。
