轨迹与用量
TIP
本节介绍一次回复的执行过程（轨迹）和产生的开销（用量）。遇到问题先看轨迹，核算开销先看用量。
ChatLuna 把每一次模型调用、工具执行和提示词装配都记录为轨迹。轨迹是一棵结构化的树：一个回合包含多个步骤，每个步骤包含模型或工具调用，工具内部还可以嵌套子代理。用量统计基于轨迹汇总，按模型、用途、插件和平台等维度折算成 token 数和预估成本。
轨迹页
点击「观测 → 轨迹」。页面顶部是三泳道时间轴，自上而下分别是回合、步骤和模型/工具调用，直观呈现每一步的耗时。
记录表
时间轴下方是按回合和步骤排列的调用记录。点击任意一条，右侧检查器显示：
- 提供商与模型。
- 速度：首 token 时间（TTFT）、总耗时和解码速度。
- token 消耗：输入、输出和缓存命中的 token 数。
- 提示词归属：系统提示片段和挂载的工具，以及它们来自哪个插件。
- 工具调用：参数、原始返回、耗时和权限判定结果。
- 错误信息：失败原因和错误码。
时间线回放
切换到「时间线回放」视图，可以按时间顺序查看一个回合内的所有事件：消息何时进入队列、模型何时开始和结束生成、工具何时触发和返回，以及压缩、审批、子代理等动作的时机。回放只展示已保存的事件，不会重新发起请求，适合定位阻塞环节。
作为草稿重新调用
在记录表中选中一步模型调用，点击右上角的「作为草稿重新调用」，当时的上下文、提示词和参数会复制到草稿抽屉中。你可以修改提示词、切换模型或调整温度等参数，然后点击「重新调用」。
重新调用直接请求模型，脱离原来的 Agent 循环，结果只保存在抽屉中，不会写回会话。适合对比不同提示词或模型的效果，以及复现偶发的异常回复。
WARNING
重新调用会向提供商发起真实请求并产生费用；如果允许执行工具，也会产生实际副作用。测试前请确认权限模式，或在面板中禁用相关工具。
进程视图
切换到「进程」标签，可以查看会话之外的后台调用：
- 后台维护：历史压缩、标题生成、记忆提取、向量化和实例启动设置等。
- 系统生命周期：插件注册和配置热重载。
- 审批流：审批请求的发起、处理和结果。
这些调用同样消耗 token。费用超出预期或空闲时仍有负载，可以在这里查明细。
用量页
点击「观测 → 用量」查看实例的统计报表。
核心指标
顶部的指标卡片包括请求数、输入/输出 token、预估成本、平均首 token 时间、P95 耗时和成功率，可以用右上角的时间范围筛选。仪表盘上的「今日用量」卡片是当天的精简版。
分组
可以按以下维度汇总：
- 模型 / 提供商。
- 用途：对话、压缩、记忆提取、意图判定、标题生成、向量化等。
- 插件来源。
- 平台渠道。
- 会话或用户。
调用明细
页面下方按时间倒序列出每次调用的时间、模型、用途、token、成本、耗时和状态。失败的调用也会记录，并附带错误描述——它们同样可能产生费用或占用并发配额。点击「导出 CSV」可以导出明细，点击任意一行会跳转到轨迹页中的对应步骤。
成本怎么算
成本 = 各项 token 消耗 × 单价。单价可以使用模型目录中的默认价格，也可以在用量插件中按提供商和模型分别配置普通输入、缓存读取和输出的单价。未单独配置缓存价格时按统一规则估算。
TIP
用量页的成本是预估值，不是服务商账单。实际费用请以提供商控制台为准，用量页主要用于观察趋势和各插件的消耗分布。
插件怎么标注用量
插件发起模型调用时可以标注用途标签（例如「记忆提取」「标题生成」「判定」），用量页据此分类。插件可以在配置中声明默认标签，也可以为单次调用单独指定；不经过统一入口的调用可以通过标准接口手动上报。没有标签的调用归入「未分类」。
缓存看板
仪表盘的「KV 缓存看板」卡片显示各会话的 epoch 代数和前缀复用情况。正常的会话回合数平稳增长，epoch 维持在较低水平，前缀作废次数接近 0。
如果 epoch 增长速度接近回合数，说明提示词前缀几乎每轮都在重建。常见原因：
- 把精确到秒的时间或实时状态放进了系统提示。
- 每轮都在增删工具。
- 同一会话在不同模型间来回切换。
- 频繁切换预设。
排查时，在轨迹页中查看提示词片段来源，结合看板上 epoch 突变的时间点，定位破坏缓存的插件。
命令行诊断
WebUI 无法访问或服务无法启动时，可以使用命令行诊断：
chatluna doctor config：检查配置、插件清单和认证状态。chatluna doctor session <id>：校验会话日志的完整性。chatluna doctor cache <id>：检查会话的前缀缓存和 epoch 变化。chatluna doctor providers：检测各提供商的连通性（需要服务正在运行）。chatluna export <id>：把会话的轨迹和上下文导出为 JSONL，便于反馈问题。
日志页
侧边栏的「日志」页面按时间输出系统运行日志，包括启动和关闭、插件加载与热重载、网络超时和限流、权限拒绝与审批超时等。
日志按时间记录系统流水，轨迹按结构呈现一次交互的完整因果。排查单次回复用轨迹，排查系统报错或网络问题用日志。
常见排查
回复变慢
在轨迹时间轴上判断是模型慢、工具慢还是排队。打开模型调用的检查器：首 token 时间过长通常是网络或提供商排队；首 token 正常但解码慢，多为输出较长或模型本身较慢。
费用突然上涨
在用量页按「模型」和「用途」查看分布，再按「插件」排查新增或更新的插件，最后在调用明细中检查超长输入或失败重试。
缓存不命中
在缓存看板找到 epoch 异常升高的会话，到轨迹页比对各次请求的提示词来源，检查是否有插件把动态内容拼进了系统提示，或工具列表频繁变化。
模型没调用工具
在轨迹页打开该步骤的模型调用，检查「可见工具列表」。工具不在列表中，检查工具策略、场景规则和可见性过滤；在列表中却没被调用，通常是工具描述不够清楚或参数太复杂。
常见问题
轨迹页没有记录：确认轨迹插件已开启，并且至少启用了一个输出（会话存储、JSONL 文件或 OpenTelemetry）。没有持久化输出时，数据不会写入磁盘。
用量和账单对不上：检查用量插件中的单价和缓存计价是否与提供商一致；失败的调用和后台任务也会产生费用，可以在「进程」视图中核对。
看不到提示词全文：可能触发了长度截断或脱敏规则，检查轨迹与隐私相关设置。多用户实例的管理员可能有意隐藏了完整提示词。
导出文件很大：JSONL 包含完整的会话日志和工具原始返回。可以先用 chatluna doctor session <id> 校验，或只导出有问题的会话。
