给生产 Agent 做质量评估，最常见的现实约束是：拿不到内部链路日志。要么 Agent 是第三方系统，trace、检索命中、工具调用都不在自己手里；要么日志体系虽在，但字段混乱、接入成本高，评估永远排在”之后再说”。结果是评估长期退化为人工抽检，覆盖率上不去，badcase 靠用户投诉被动收集，PM 拿到的反馈是”感觉回复不够准”，无法变成可排期的优化事项。
我们针对这个现实做了一条端到端的黑盒诊断流水线：只要求上传 query 和 answer 两列对话文本，经过数据质检、规则诊断、风险筛选之后，用 LLM 对筛选出的对话做结构化逐条诊断，再聚类成问题簇，最终生成 PM 能直接使用的优化事项和报告。整套方案不依赖被测 Agent 的任何内部实现，换一个 Agent 只需要换一份数据。
这个系列共六篇，本篇讲整体工作流和数据流。后五篇分别展开数据质检与风险筛选、严格 JSON Schema 结构化输出、LLM 输出坏损的防御、基于数据库的任务编排，以及报告的产品化。贯穿全程的设计哲学只有一句话：
模型负责语义判断，应用负责协议边界。
一、背景：为什么需要”黑盒”诊断
先看没有黑盒诊断时，团队通常处在什么状态。
1. 内部链路日志拿不到，或者不好拿
理想中的评估是白盒的：能看到 Agent 实际检索了哪些知识、调用了哪些工具、每一步的推理轨迹。但生产环境里，白盒评估的前提条件经常不成立：
- Agent 由外部团队或供应商交付，内部实现是黑盒；
- 日志分散在多个系统，字段口径不统一，关联一条完整对话的成本很高；
- 日志里混有敏感信息，评估侧拿数据要走审批。
当白盒不可得，唯一稳定存在的数据就是对话本身：用户问了什么，Agent 答了什么。这份数据每个团队都有，只是从来没人系统地用它做评估。
2. 人工抽检覆盖率低
人工抽检的问题不是不认真，而是不规模。每天数万条对话，人工能看的只有百分之一都不到，而且抽检员的标准会漂移：同一个”答非所问”，有人标严重、有人标正常。抽检结论无法按周对比，也就无法回答”这版 Agent 比上一版好了多少”。
3. badcase 收集是被动的
大多数团队的 badcase 流入路径是：用户投诉 → 客服转述 → 群里贴一段截图。等投诉到达时，问题往往已经发酵；没有投诉的部分，则完全不知道是否存在问题。这是一种漏斗极窄、延迟极高的采样方式。
4. PM 缺可执行的优化依据
即使收集到了问题，PM 拿到的通常是一堆零散截图。要回答”下一版优先修什么”，需要知道：问题分几类、每类影响多少对话、严重程度如何、有哪些具体案例可以做验收。零散 badcase 支撑不了这个决策。
黑盒诊断的目标就是把这条链路补全：从全量对话出发，产出分类、定量、带证据的问题清单和优化建议。
二、核心约束与数据模板
黑盒方案的第一条纪律是：对数据的要求必须压到最低。
必填列只有两个：
query 用户输入
answer Agent 回复只要能导出这两列，任何 Agent 的数据都能进入流水线。这是”通用黑盒”的底线——如果模板要求一堆内部字段，方案就退化成了特定系统的专属工具。
在此之上，可选列用于增强诊断上下文：
| 字段 | 作用 | 典型用法 |
|---|---|---|
session_id | 会话 ID | 把同一会话的多轮对话拼成上下文，判断指代和承接 |
user_id | 用户 ID | 识别同一用户的重复求助，是问题严重性的信号 |
request_time | 请求时间 | 按时间切片，观察版本切换前后的质量变化 |
first_token_response_time | 首 token 响应耗时 | 区分”答得慢”和”答得差”两类体验问题 |
vote / advice | 用户反馈 | 点踩和文字反馈是高价值的风险信号 |
agent_id / agent_version | Agent 标识与版本 | 多 Agent 对比、版本回归评估 |
channel / business_line | 渠道与业务线 | 拆分维度，定位问题集中在哪个业务 |
这些列全部可选、缺一不可用。比如没有 vote，风险筛选就退化为纯规则判断；没有 session_id，多轮对话按单轮处理，诊断粒度变粗但依然可用。
模板上传支持 Excel 和 CSV，字段名大小写和空格做归一化处理，让业务同学从各种系统里导出的原始数据能直接用。
三、整体方案与数据流
流水线由八个阶段组成，每个阶段职责单一、输入输出明确。任务上传后持久化到数据库，由 Worker 依次执行：
模板上传
↓ 数据质检
↓ 规则诊断
↓ 风险筛选
↓ 批量 LLM 逐条诊断
↓ 问题聚类
↓ 优化事项生成
↓ 报告生成各阶段职责如下：
| 阶段 | 输入 | 输出 | 职责 |
|---|---|---|---|
| 模板上传 | Excel / CSV | 解析后的对话行 | 列校验、字段归一化、落库 |
| 数据质检 | 对话行 | 干净数据集 + 质检报告 | 拦截空值、超长、乱码、重复行 |
| 规则诊断 | 干净数据集 | 规则标记 | 零成本的确定性检查，不调 LLM |
| 风险筛选 | 规则标记 + 可选反馈列 | 高风险子集 | 点赞点踩、重复求助、超时等信号 |
| 批量 LLM 诊断 | 候选对话（高风险优先） | 结构化诊断结果 | 判断问题类型、严重级别、依据 |
| 问题聚类 | 逐条诊断结果 | 问题簇 | 相似问题归并，统计规模和分布 |
| 优化事项生成 | 问题簇 | 优化建议 | 每簇给出可排期的改进动作 |
| 报告生成 | 全部上游结果 | 最终报告 | 汇总为 PM 视角的可视化页面和导出 |
有两个设计点值得强调。
第一，规则诊断在 LLM 之前。像”answer 为拒答话术""query 与 answer 语言不一致""响应超时”这类判断，规则就能做，成本为零、结果确定。规则先行既能省下 LLM 调用，也为 LLM 诊断提供先验信号。
第二，风险筛选决定 LLM 的优先级。逐条诊断是整条流水线里最贵的环节，当预算或时间有限时，高风险对话（用户点过踩、同一 user_id 反复追问、响应超慢）应当先被处理。覆盖率成为一等公民指标：诊断完成的对话比例决定这份报告的可信程度，覆盖率太低的任务会被明确标记为”数据不足”，而不是静默输出一份看似完整的报告。
举一个贯穿后续各篇的虚构例子：某电商客服 Agent，用户问”我买的包裹三天没更新物流了，是不是丢了”，Agent 回复了一段通用的物流查询口径，没有回应”是否丢失”的担忧，也没有给出补发或赔付路径。逐条诊断会把它标记为”未解决用户核心诉求 / 严重级别中等”，聚类后它和”退换货只重复政策不处理诉求”等对话归入同一个问题簇，最终生成一条类似”回复模板化，缺少针对用户具体诉求的行动指引”的优化事项，并附上可下钻的会话证据。
四、五个专题预告
整体方案讲完，真正的工程难点在细节里。后续五篇各解决一个绕不开的问题。
1. 为什么不给每条对话都跑 LLM？
听起来最简单的方案是：全量对话逐条发给 LLM 判断好坏。但全量跑成本高、周期长，而数据本身质量参差——空行、测试数据、乱码、重复导出都会污染结果。第二篇讲数据质检与风险筛选：如何定义”进入诊断的人口”，如何用规则和反馈信号在 LLM 之前完成第一轮分诊。
2. 如何让 LLM 稳定输出结构化结果？
诊断结论要进数据库、要聚类、要出报告，就必须是严格的结构化数据，不能是一段自由文本。让 LLM 按指定 schema 输出——枚举值合法、必填字段齐全、类型正确——是一切后续处理的前提。第三篇讲严格 JSON Schema Structured Outputs 的实践，以及 Zod 在服务端的第二道防线。
3. LLM 输出坏了怎么办？
即使有严格 schema，批量调用仍会出现无效行、重复行、缺失行。全部重试代价太大，全部丢弃覆盖率受损。第四篇讲输出防御策略：先保存校验通过的行，只对坏行做一次定向修复，单行失败不拖垮整批。核心是把 LLM 当作不可靠的外部系统来设计协议边界。
4. 长任务如何编排？
一次全量诊断是典型的长任务：数千次 LLM 调用、中途可能失败、需要断点续跑。引入消息队列对很多团队是重负担。第五篇讲不依赖消息队列的方案：用数据库做任务状态机，Worker 通过原子领取任务保证多实例不重复消费，失败任务可单独重试。
5. 报告怎么让 PM 用起来？
诊断明细对工程师有用，但 PM 需要的是”问题分布、严重程度、优化优先级、验收案例”。第六篇讲报告的产品化：如何把成千上万条诊断结果收敛成一页 PM 能看懂、能据此排期的报告，以及如何用可下钻的会话证据建立信任。
五、技术选型
选型一段带过，因为它不是这个系列的重点。整体是 Next.js 全栈单体：前端和 API 在同一个应用里，PostgreSQL 承担任务队列和全部状态存储，LLM 走 OpenAI 兼容接口（诊断用的是 DeepSeek），Worker 以进程内嵌方式随应用启动，pnpm dev 一条命令跑起完整流水线，不需要单独部署队列或 Worker 服务。
这套选型的出发点是运维成本最低化。诊断工具是低频内部应用，值得把复杂度花在诊断质量和数据流设计上，而不是基础设施上。换任何同等技术栈，本系列的方法论同样成立。
六、总结
这个系列反复出现的分工是：语义层面的判断——这条对话有没有解决问题、问题属于哪一类、有多严重——交给 LLM；协议层面的保证——schema 校验、坏行修复、任务原子领取、覆盖率兜底——由应用代码硬性承担。
不把 LLM 当成可信组件，也不把结构化约束写成松散的 prompt 恳求，这条边界划清楚之后，“用 LLM 做生产级评估”就从碰运气变成了可工程化、可回滚、可验收的系统。下一篇从流水线的第一站讲起：数据质检与风险筛选。