# Investibook Evaluation System 主设计文档 **Date:** 2026-04-20 **Status:** Draft for discussion --- ## Summary Investibook 已经具备基础的 agent 诊断能力，也有 `tools/replayer` 这样的回放工具，但还没有形成一套真正可长期运营的 evaluation 系统。 我们现在面对的问题，已经不是“能不能 replay”，而是： - case 沉淀成本高 - 成功标准不够稳定 - 缺少统一的 baseline 和回归比较 - 缺少 daily run 和结果运营闭环 这个 feature 的目标，是把 evaluation 升级成一个独立的产品能力，用来长期回答下面这些问题： - 一个经典故障 case，agent 现在还能不能稳定诊断出来 - 新的 prompt / skill / tool 变化，会不会让已有能力退化 - 哪些 case 回归了，回归集中在哪类问题 - 每天跑完之后，团队应该在哪里看结果、如何决定下一步动作 一句话概括： > 把“偶发的 replay 和人工复盘”升级成“可持续、可比较、可运营的质量保障系统”。 这份主文档只讲： - 我们想解决什么问题 - evaluation 系统的核心概念是什么 - 整体业务流程是什么 - 第一阶段要做什么，不做什么 具体怎么实现，放在各个子设计文档里展开。 --- ## End-to-End Business Flow 为了让读者先建立整体场景，evaluation 系统的业务流程可以先压缩成下面这张图： ```mermaid flowchart LR A[Ticket + 人工带跑一次] --> B[Golden Workspace] B --> C[生成 Case Draft] C --> D[人工 Review] D --> E[正式 Case / Suite] E --> F[Daily Run] F --> G[Judge 判分] G --> H[Baseline 对比] H --> I[Admin 展示结果] I --> J[修复、Rerun、Promote Baseline] ``` 这张图表达的是一条很清晰的闭环： - 现有 Investibook 系统先产出一个高质量 `golden workspace` - evaluation 系统从 `golden_workspace_id` 开始，把它沉淀成正式 case - case 进入 suite 之后，系统每天自动跑回归 - 跑完后自动判分，并与 baseline 比较 - 最终结果在后台页面中展示，驱动修复、重跑和基线更新 --- ## 为什么现在要做 ### 1. 当前 replay 更像工具，不是系统 现在的 `tools/replayer` 更像一组 operator 工具和案例文档： - 能帮助复盘 - 能帮助手工回放 - 能帮助整理 `expected.md` 但它还不能稳定回答“今天 agent 质量有没有回退”。 ### 2. 当前 evaluation 更像会话分析，不是 case regression 现有 `/api/admin/evaluations*` 更接近“泛化会话质量分析”： - 消息数 - correction 次数 - tool call 数 - conversation summary 这和“一个经典故障 case 有没有答对”是两回事。 ### 3. 真正的长期稳定性必须围绕 case 建立 对数据库故障诊断 agent 来说，最重要的不是平均表现，而是关键模式是否稳定： - known bug 是否还能识别 - hotspot / lock contention / GC 等模式是否还能诊断 - 关键 guardrail 是否还在 - recommendation 是否开始偏移 因此 evaluation 必须围绕 case、ground truth、baseline 和 regression 来设计。 --- ## 核心概念 这套系统里最重要的概念不多，但必须先讲清楚。因为后面的设计，基本都围绕这些概念展开。 ### Golden Workspace `golden workspace` 是 evaluation 系统的前置输入，不是 evaluation 系统自己生成的东西。 它来自现有 Investibook 系统中的一次人工带跑，作用是： - 提供高质量诊断样本 - 提供可追溯的首轮诊断过程 - 为 case 建档提供基线材料 evaluation 系统不负责“人工如何带跑第一轮”，它只接管 `golden_workspace_id` 之后的流程。这是这套方案最重要的边界之一。 ### Case `case` 是 evaluation 系统里的基本评测单元。 一个 case 表示： - 一个具体故障模式 - 一组明确的 ground truth - 一组判定是否成功的规则 - 一组后续 daily run 会反复回放的标准输入 case 不是 ticket 的简单拷贝，而是从 ticket 和 golden workspace 中提炼出来的长期资产。一个 case 一旦进入系统，就应该能被反复运行、反复比较、反复用于回归判断。 ### Rubric `rubric` 可以理解成某个 case 的“判定清单”或“评分标准”。 它不是一句模糊的“答案要正确”，而是一组可以逐项检查的要求，例如： - 必须识别正确 root cause - 必须检查某类 evidence - 必须指出关键 instance / digest / bug ID - 不能把某个干扰因素误判为主因 evaluation 系统不会只看最终回答“像不像对”，而是会按 rubric 逐项检查。 ### Suite `suite` 是一组 case 的集合。 它的作用是把 case 组织成可运行的评测包，例如： - 核心 daily suite - 扩展 weekly suite - 某一类故障主题的专项 suite suite 是 daily run 的直接输入。 ### Baseline `baseline` 是当前被认可的一条参考线。 它的作用不是证明系统“绝对正确”，而是作为后续所有 run 的比较对象，用来回答： - 今天和之前比，是进步了还是退步了 - 哪些 case 回归了 - 回归严重程度如何 ### Daily Run `daily run` 是 evaluation 系统的周期性自动运行。 它的作用是： - 按固定节奏回放 suite - 自动产生判分结果 - 自动与 baseline 比较 - 自动输出回归列表 ### Judge `judge` 是判定某个 case 本次是否成功的机制。 它负责把一次 run 的输出转换成： - pass / fail - score / coverage - failure codes - regression diff Judge 的目标，是把“这次到底算不算成功”从主观感受变成可重复、可解释、可对比的结果。 --- ## 这套系统最终要做到什么 如果把 evaluation 系统当成一个产品能力来看，第一阶段至少要做到下面几件事。 ### 1. 把 golden workspace 变成正式 case 系统要支持从 `golden_workspace_id` 自动生成 case draft，并经过人工 review 后进入正式 case registry。 ### 2. 把“是否成功”变成稳定标准 系统要定义一套统一 success contract，让不同 case 都能被稳定判断，而不是依赖人工看全文。 ### 3. 把 case 组织成可周期执行的 suite 系统要支持把 case 按不同目标组织起来，例如 daily / weekly / theme-based suites。 ### 4. 把 daily run 做成长期运行机制 系统要支持每天自动跑、自动判分、自动比较，而不是每次都靠手工发起 replay。 ### 5. 把结果变成可运营信息 系统要让团队可以稳定看到： - 今天跑了什么 - 哪些 case 失败了 - 哪些是新回归 - 失败主要集中在哪类问题 ### 6. 把后续动作闭环接回来 系统不是为了“存一堆分数”，而是为了支持下一步动作： - 修 prompt / skill / tool adapter - rerun failed cases - 复核争议 case - promote 新 baseline --- ## 范围与边界 第一阶段先明确一个边界： - **golden workspace 的产生不属于 evaluation 系统** - 它继续由现有 Investibook 产品流程产生 - evaluation 系统从 `golden_workspace_id` 作为输入开始接管 在这个边界内，第一阶段关注的是四块能力： - case 资产沉淀 - success / correctness 判定 - daily regression - 结果展示与运营 --- ## 第一阶段目标 第一阶段的目标是： 1. 建立可维护的 case 资产体系 2. 建立稳定、可解释的成功判定标准 3. 建立按天运行的 regression 机制 4. 建立 baseline 对比和回归发现能力 5. 建立后台可见的结果展示和运营闭环 --- ## 第一阶段不做 第一阶段不做： - per-commit CI gate - 任意真实 workspace 的全量纳入 - 训练数据导出、模型微调、自动 prompt 优化 - 面向普通终端用户的展示页面 --- ## 分阶段视图 从产品演进角度看，这件事可以拆成四个阶段。 ### Phase 1: Case 资产标准化 目标： - 把 golden workspace 变成正式 case - 把 case 沉淀流程标准化 ### Phase 2: Success Contract 建立 目标： - 定义 case 成功的统一判定方式 - 让 pass / fail 变得稳定、可解释 ### Phase 3: Daily Regression 运行起来 目标： - 能按 suite 自动跑 - 能自动产出结果 - 能自动做 baseline 对比 ### Phase 4: 结果展示与运营闭环 目标： - 在后台稳定展示 run、case、regression - 支持 rerun、review、promote baseline 等动作 --- ## 与子设计文档的关系 这份主文档不展开实现细节。具体设计拆到下面几个子文档： - [子设计 1：Case 沉淀机制](./case-authoring.zh.md) - [子设计 2：Case 正确性评判](./case-judging.zh.md) - [子设计 3：Daily Run 成本控制](./daily-run-cost.zh.md) - [子设计 4：自动运行部署与结果展示](./technical-ops.zh.md) 主文档的作用，是先讲清楚： - 为什么要做这件事 - 这套系统的核心对象是什么 - 整体业务流程是什么 - 第一阶段范围是什么 而不是直接进入实现细节。 --- ## Defaults - 第一阶段默认是 **offline-first** - 主目标是 **daily regression** - 基线比较对象是 **pinned baseline** - case 是长期维护资产，不是一次性 ticket 附件 - 主文档讲概念与范围，具体实现下沉到子设计