Day 29 - Final Project Implementation and Eval

今日目标

能完成可演示版本，用评估集跑出成功与失败案例。

学习安排

核心概念

阅读重点

• 对应章节：全计划回顾，重点是第 4 章工具、第 6 章评估与第 25 天的轨迹记录思路。
• 关注点：
• 六个模块的职责与输入输出边界：task_parser、context_builder、retriever、tool_router、report_writer、evaluator。
• 评估驱动的改进：先跑基线，再改，再重跑，用数据说话。
• 轨迹调试：失败时回放轨迹，区分模型问题、工具问题、上下文问题。
• 伪实现与真实实现的边界：Demo 阶段什么可以简化，什么不能省略。
• 补充材料：
• OpenAI Evals 文档中关于 eval set 组织与指标计算的部分。
• LangSmith 或类似工具的轨迹追踪文档，参考如何记录与回放轨迹。

理解检查

• 哪个模块最难实现？你判断的依据是什么？
• 哪些失败是模型问题？哪些失败是工具或上下文问题？怎么区分？
• 评估结果是否支持你的改动？什么算「支持」？
• 六个模块之间的边界怎么定？改一个模块会不会影响其他模块？

实践任务

背景：昨天定义了 MVP，今天把它变成可演示版本。用 Day 28 的 10 条评估用例跑一遍，输出成功与失败案例。

• 第 1 步：按实现顺序（task_parser -> context_builder -> retriever -> tool_router -> report_writer -> evaluator）逐个完成六个模块，先用伪实现跑通链路，再替换关键模块。
• 第 2 步：跑通一条完整链路：输入「开启 WAF 后 Nginx CPU 升高」到输出 Markdown 报告，并保存运行日志。
• 第 3 步：用 10 条评估用例跑一遍，记录每条的成功或失败。
• 第 4 步：对每个失败用例回放轨迹，把失败原因归到模型、工具、上下文三类。
• 第 5 步：写改进计划，每条改动都要注明依据来自哪个失败案例。

输出模板

模块 1：task_parser
- 职责：[把用户问题解析成结构化任务]
- 输入 -> 输出：[用户原始问题 -> 任务对象：问题类型、实体、时间范围、约束]
- 状态与备注：[已实现 / 伪实现 / 待做]，[实现要点]
模块 2：context_builder
- 职责：[组装 system prompt 与任务上下文]
- 输入 -> 输出：[任务对象与约束 -> 组装好的上下文]
- 状态与备注：[已实现 / 伪实现 / 待做]
模块 3：retriever
- 职责：[从知识库检索相关资料]
- 输入 -> 输出：[查询关键词 -> Top-K 资料片段，附来源]
- 状态与备注：[已实现 / 伪实现 / 待做]
模块 4：tool_router
- 职责：[决定调用哪个工具并处理返回]
- 输入 -> 输出：[数据需求与参数 -> 工具返回结果或失败标记]
- 状态与备注：[已实现 / 伪实现 / 待做]
模块 5：report_writer
- 职责：[生成 Markdown 报告，标注证据与假设]
- 输入 -> 输出：[上下文与检索结果 -> Markdown 报告]
- 状态与备注：[已实现 / 伪实现 / 待做]
模块 6：evaluator
- 职责：[跑评估集并输出统计]
- 输入 -> 输出：[用例与 Agent 输出 -> 成功数、失败数、失败原因归类]
- 状态与备注：[已实现 / 伪实现 / 待做]

运行日志示例
- task_parser 解析问题并输出任务对象
- tool_router 调用 query_metrics 返回 CPU 数据
- report_writer 生成报告，evaluator 判定通过

成功案例与失败案例
- 成功案例 1：[输入] -> [输出] -> [通过原因]
- 失败案例 1：[输入] -> [输出] -> [失败原因归类：模型 / 工具 / 上下文]

改进计划
- v0.2 改动：[...]，依据：[来自哪个失败案例]

示范输出

模块 1：task_parser
- 职责：把用户问题解析成结构化任务
- 输入 -> 输出：开启 WAF 后 Nginx CPU 升高 -> {问题类型: 性能分析, 实体: [WAF, Nginx], 约束: [需要验证步骤]}
- 状态与备注：已实现
模块 2：context_builder
- 职责：组装 system prompt、任务对象与工具描述
- 输入 -> 输出：任务对象与 mock 工具清单 -> 含证据标注要求的上下文
- 状态与备注：已实现
模块 3：retriever
- 职责：从知识库检索 WAF 与 Nginx CPU 相关文档
- 输入 -> 输出：WAF 开启、Nginx、CPU 升高 -> 5 条片段，附来源文档名
- 状态与备注：伪实现，用预置文档列表
模块 4：tool_router
- 职责：根据数据需求调用 query_metrics 或 query_logs
- 输入 -> 输出：{指标: cpu_usage, 时间: 10:00-11:00} -> CPU 均值 78%
- 状态与备注：伪实现，读取本地 mock 数据
模块 5：report_writer
- 职责：生成 Markdown 报告，证据标注为已验证或待验证
- 输入 -> 输出：上下文与检索结果 -> 含 4 条假设、2 条待验证、验证步骤的报告
- 状态与备注：已实现
模块 6：evaluator
- 职责：跑 10 条用例并输出统计
- 输入 -> 输出：用例文件与 Agent 输出 -> 成功 7 条、失败 3 条（模型 1、工具 1、上下文 1）
- 状态与备注：已实现

运行日志示例
- task_parser 解析出问题类型 performance，实体 [WAF, Nginx]
- tool_router 调用 query_metrics 成功，CPU 均值 78%
- evaluator 判定通过，报告含 2 条待验证标注

成功案例与失败案例
- 成功案例 1：[分析接口 P95 升高] -> [含时间窗口、关联日志、假设与验证步骤] -> 证据完整可执行
- 成功案例 2：[生成测试日报] -> [格式正确、无编造数据] -> 数据忠实度高
- 成功案例 3：[知识库问答] -> [引用来源片段并给出结论] -> 引用完整
- 失败案例 1：[输入数据缺失] -> [报告未标注缺口直接下结论] -> 归类：上下文，缺缺失信息规则
- 失败案例 2：[指标工具返回为空] -> [Agent 卡住未降级] -> 归类：工具，缺空结果处理

改进计划
- v0.2 改动：context_builder 增加缺失信息标注规则，tool_router 增加空结果降级，依据：失败案例 1 与失败案例 2

追问练习

• 哪些失败是工具或上下文问题？如何从轨迹里区分这两种失败？
• 评估结果是否支持你的改动？你怎么判断改动真的变好了？
• 下一版最应该优化什么？依据是什么？
• 如果评估集只有 10 条用例，你敢不敢下「系统已经可用」的结论？

常见误区

• 模块之间互相改对方的数据，边界不清，一个改动引发连锁错误。
• 只展示成功案例，把失败案例藏起来，失去改进依据。
• 失败分析只写「模型不行」，没有回放轨迹定位到具体步骤。
• 伪实现被当成真实实现，Demo 能跑就以为生产也能跑。

进阶扩展

• 离线评估流水线：每次改动先跑全部用例，与基线对比后再上线。
• 轨迹回放工具：把运行日志可视化，快速定位失败发生在哪个模块。
• CI 集成：把评估集挂进持续集成，prompt 或代码变更自动触发回归评估。

今日作业

• 实现或伪实现六个模块，跑通一条完整链路。
• 跑评估集，记录 3 个成功案例与 2 个失败案例，附运行日志。
• 对每个失败案例写失败原因归类：模型、工具还是上下文。
• 写改进计划，至少 3 条改动，每条注明依据的失败案例。

自检清单

• 我能说清六个模块各自的输入输出边界。
• 我能跑通从问题输入到报告输出的完整链路。
• 我能用评估集跑出成功与失败案例。
• 我能从轨迹里定位失败发生在哪个环节。
• 我能写出有依据的改进计划。