业务系统和 AI Agent 都适用同一套方法论：埋点 → 指标 → 看板 → 告警 → 复盘。差别只在观测对象——业务流程看漏斗，Agent 看链路与质量。这一页把 Agent 观测的概念体系补全。
跨行业通用 · 不属于外贸资料库 · 与 /define、/skills 互通
看完你能判断：自己现在有没有真的观测，还是只有一堆漂亮的图。
业务观测和 Agent 观测用的是同一套骨架，只是观测对象不同。
先定义事件字典：哪些动作值得记。不要只记页面浏览——要记关键动作（CTA 点击、表单提交、Agent 调用）。
把事件换成可比的口子：转化率、成功率、P95 延迟、单次成本。**口径必须先写死**，否则每周的数都对不上。
一屏看健康度。看板只放你每天真会看的 5–8 个数，多了就没人看。
只在异常时打扰人。告警必须有阈值和负责人，否则告警疲劳 = 等于没有告警。
周期回看并把结论反哺：更新事件字典、补评测集、改护栏。**不复盘的观测只是仪表盘装饰。**
铁律：没有数据就不许改。改完无法证明有效还是无效，等于白改。
同一套骨架，两种对象。先看差别，再进入 Agent 部分。
对象：用户行为与业务流程
看什么：漏斗、转化、流失点
典型指标：UV / CTA 点击率 / 提交率 / 收到率
判断标准：数值可比对、可归因
对象：一次调用的全链路与输出质量
看什么：每一步 tool call、prompt 版本、成本、延迟、错在哪
典型指标：任务成功率 / 幻觉率 / P95 延迟 / 单次成本 / 评测集得分
判断标准：不只是「通不通」，而是「好不好」
传统监控看「通不通」，Agent 还要看「好不好」——这是本质差别。
同一个输入两次可能给不同结果。所以不能只测「有没有返回」，必须测「质量稳不稳定」。
一次请求往往是一棵树：检索 → 工具调用 → 重试 → 模型 → 汇总。只看见最终输出，你永远不知道错在哪一步。
多一轮重试、多一次检索，成本和耗时就翻倍。必须把 token / cost / latency 记进链路。
改一句 prompt，可能修好一类问题又坏掉三类。所以必须有回归门禁，不能凭感觉上线。
查术语用。11 个概念覆盖从一次调用到一套评测。
从一次调用到一套评测，把术语和它们解决什么问题一次讲清。
Trace
一次完整调用的全链路（含每一步的输入输出、耗时、成本、错误）。
Span
链路中的一步：一次检索、一次工具调用、一次分支判断。
Generation
一次模型调用的完整记录：prompt、输出、模型、token、成本、耗时。
Session / Thread
多轮会话的容器，把同一用户的多次调用串起来。
Score
对一次输出的质量打分：人工评、规则评、模型评、或用户反馈（点踩）。
Dataset（评测集）
一组固定用例，每条带期望输出或评分标准。
Evaluation（评测）
在评测集上跑一遍，产出成功率、幻觉率等聚合指标。
Badcase
失败或低分的真实样例，是评测集最重要的原料。
Regression（回归）
改动后重跑同一评测集，与基线对比。
Prompt 版本
每次改 prompt 都打版本号，和 trace 绑定。
在线指标 vs 离线评测
在线看真实分布（用户实际怎么问），离线看可复现对比（同一批用例）。
照着做就能跑起来：先建 20 条评测集，再让每条 badcase 变成永久用例。
没有评测集，你对 Agent 的所有判断都是 anecdote（轶事），不是证据。
① 真实日志抽样（最重要，代表真实分布）② 边界/极端输入（超长、空、乱码、多语言）③ 已知 badcase ④ 对抗/注入（诱导越权、套取 prompt）。
20 条就能发现大部分明显退化；100 条左右才有统计意义。**别一上来追求 1000 条**——维护不动的评测集等于没有。
优先标「有标准答案」的（可做准确率）；没标准答案就标**评分维度**（相关性/完整性/语气/是否幻觉），每条写清「什么叫通过」。
先自己标一批建立标准，再考虑外包/众包。**标注指南必须写下来**，否则多人标注标准会漂移，评测集就废了。
Agent 项目的进步速度，取决于 badcase 变成用例的速度。
触发来源：用户点踩 / 低分 / 异常（报错、超时、超预算）/ 人工巡检抽样。
分到问题类型：检索不准 / 工具用错 / 格式不符 / 幻觉 / 该拒答没拒。分类才能看出系统性问题。
把这条 badcase 固化成一条永久用例（这是最关键的一步）。
打开 trace，找出是哪一步出的问题——别靠猜，看链路。
对应手段：改 prompt / 换或补工具 / 改检索 / 加兜底。改完打 prompt 版本号。
重跑全量评测集，对比基线：整体得分、新增失败项、成本与延迟变化。
更新标注指南、补护栏（如「必须拒答 X」）、把结论写进反模式清单。
铁律：每个 badcase 必须沉淀成一条评测用例。不沉淀 = 同一个坑你会反复踩。
先会分类，才能看出系统性问题而不是零散救火。
把这两段贴进你的仓库，从第一条开始填。
## 评测集用例模板 - id: E-001 - 来源: 真实日志 / 边界 / 对抗 / badcase - 输入: <买家原话> - 类型: 可判定 / 评分维度 / 硬约束 - 期望: <期望输出或行为> - 判定标准: <什么叫通过，写死，不留解释空间> - 关联 badcase: B-014（若来自 badcase） - 备注: <为什么收录这条> ## badcase 档案模板 - id: B-014 - 日期: 2026-10-15 - 触发: 用户点踩 / 低分 / 异常 / 人工巡检 - 输入: <原始输入> - Agent 输出: <实际输出> - 期望: <应该是什么> - trace 定位: <错在第几步> - 归类: 检索 / 工具 / 生成 / 拒答 / 工程 - 严重度: 高 / 中 / 低 - 用例化: E-021（必须关联一条评测用例，否则这条白记了）
改 prompt / 换模型 / 改工具之后，必须重跑评测集再上线。
记录当前评测集得分、P95 延迟、单次成本。没有基线就无法判断变化。
同一批用例、同一套评分标准。改了评分标准就等于换了一把尺子，不可比。
① 整体得分是否提升 ② **是否新增失败项**（修好一个坏三个是常态）③ 成本与延迟变化。
任一关键指标下降超过阈值 → 不许上线。阈值先粗后细（例如：成功率降 >5% 即拦）。
选型、避坑、以及一个下午能做完的起步动作。
选型的四个维度：能否自托管（数据合规）、有没有评测集与评分、能否接现有栈、成本。
业务侧零配置统计，托管在 Vercel 时直接可用。只覆盖基础流量，不含自定义漏斗事件。
隐私友好、可自托管的轻量统计。适合要自有数据或合规要求高的场景。
产品分析向，漏斗/留存/会话回放能力强，可自托管。业务观测要做得深时选它。
Agent 侧：trace + span + generation + score + 评测集，开源可自托管。是「一套走完方法论」最贴近的选择。
Agent 侧托管方案，评测与调试体验成熟；数据出境与成本需评估。
最朴素但可控：把 trace 写进表，用现成 BI 出图。适合数据不能出境、或要深度定制。
出现这些情况，说明你的观测是假的。
别一上来做中台。先做到能回答三个问题：从哪来？卡在哪？错了几次？
目标：任何一次调用，你都能看到它走了哪几步、花了多少钱、错在哪。
从真实日志抽样，覆盖你最常遇到的 3–5 类问题。先小，先能用。
哪怕一天只收 1 条，每条都变成永久用例。坚持两周就有 10+ 条真实护栏。
形成习惯：任何 prompt/模型/工具改动，都必须有改前基线和改后对比。
先把问题定义清楚
交付循环与能力地图