# Investibook Regression / Evaluation 重设计关键决策题说明

**Date:** 2026-04-21
**Status:** Decision Notes

---

## 背景

Investibook 当前已经有两套和 “evaluation / regression” 相关的能力，但它们解决的问题并不相同：

- `tools/replayer/`
  更像 file-based case library + shell runner，擅长本地 replay、postmortem、人工验证和 `expected.md` 基线检查
- `/api/admin/evaluations*`
  更像 workspace / conversation 级别的质量分析，擅长会话评分、correction 统计、tool call 统计和趋势展示

当前这次重设计，目标不是简单增强其中某一个工具，而是回答下面这个更大的问题：

> 我们要不要把“偶发 replay + 人工复盘”升级成“可持续、可比较、可运营的 regression / evaluation system”？

如果答案是要，那么很多关键设计必须先达成团队共识，否则后面容易出现：

- 执行链路和后台模型双轨并存
- baseline 含义不一致
- judge 规则与语义评判混杂
- case 资产沉淀方式前后不一致
- daily run 做出来但长期难维护

因此，这份文档已经收敛为一个单文件版本，只保留最影响架构方向的 7 个关键决策题，并整理每道题背后的背景、主要取舍与当前默认建议，方便团队在同一份材料上对齐理解。

相关背景材料：

- `docs/plans/2026-04-20-evaluation-system/main-design.zh.md`
- `docs/plans/2026-04-20-evaluation-system/case-authoring.zh.md`
- `docs/plans/2026-04-20-evaluation-system/case-judging.zh.md`
- `docs/plans/2026-04-20-evaluation-system/daily-run-cost.zh.md`
- `docs/plans/2026-04-20-evaluation-system/technical-ops.zh.md`

---

## 快速决策表

| 问题 | 主题 | 推荐默认值 |
|------|------|------------|
| Q4 | 正式执行链路 | backend runner 主导，bash 保留为 debug helper |
| Q7 | 输入模式 | 默认冻结输入 / 稳定 replay context |
| Q9 | judge 哲学 | three-layer judge |
| Q14 | baseline 粒度 | suite 为主视角，case pointer 为底座 |
| Q17 | case 迁移范围 | 先迁 10-20 个 `core-daily` case |
| Q21 | daily 预算 | `core-daily` 10-20 个，`high-cost` case 默认 weekly |
| Q27 | 重构方式 | 桥接式重构 |

---

## Q4. 正式执行链路

### 问题

正式 regression 系统的执行权威，应该掌握在谁手里？

### 备选项

- A. 继续以 `tools/replayer/replay.sh` 为主执行入口
- B. backend runner 主导，bash 脚本降级为 debug / tooling
- C. 暂时双轨并行，后续再收敛

### 背景与考虑

- 这道题的本质不是“要不要保留脚本”，而是在问：正式 regression 系统的执行权威，到底掌握在 shell 工具手里，还是掌握在一个可编排、可观测、可持久化的 backend runner 手里。
- `backend runner` 更适合作为复杂系统的正式入口和长期维护载体，因为它更容易承载结构化状态、失败语义、重试、并发控制、预算控制、DB 落库、后台页面和 CronJob 调度。
- `bash script` 更适合作为开发辅助工具，例如本地调试、快速验证链路、thin wrapper。它不是不能做复杂流程，但当系统开始需要 `run / case_run / judgment / baseline / regression` 这些长期对象时，bash 的维护成本会明显上升。
- 如果目标只是“把现有 replay 再规范一点”，继续以脚本为主是可以的。
- 如果目标是“做成长期 daily 运营的 regression system”，更推荐 backend runner 主导。

### 主要取舍

- 偏脚本主导：
  - 起步快
  - 本地调试顺手
  - 改造成本低
  - 但长期维护、定时任务、UI 闭环、baseline 和回归运营能力偏弱
- 偏 backend runner 主导：
  - 初期工程量更高
  - 但更适合作为复杂系统正式入口
  - 更利于长期维护、定时任务和后台运营闭环

### 默认建议

- B. backend runner 主导，bash 保留为 debug helper 或 thin wrapper

---

## Q7. 输入模式

### 问题

每次 daily / scheduled regression run 的输入，应该更偏向哪种模式？

### 备选项

- A. 尽量使用冻结快照 / 稳定 replay context
- B. 每次实时重新从 Jira / Clinic / 外部数据源取数
- C. 分层混合：core suite 偏冻结，扩展 suite 可实时

### 背景与考虑

- 如果每天都从外部系统实时取数，baseline 很容易被数据漂移污染
- 如果全部冻结输入，回归信号会更稳定，但对真实环境变化的覆盖会弱一些
- 这个问题会直接影响 baseline 稳定性、daily run 可重复性、故障定位难度，以及后续 case 的长期可信度

### 默认建议

- A. 尽量使用冻结快照 / 稳定 replay context

默认理解：

- 默认 regression，尤其是 daily / scheduled run，应尽量基于冻结输入或高度稳定的 replay context
- 这样可以最大限度降低外部数据漂移对 baseline 的污染
- 如果后续需要实时取数验证，更适合作为独立验证路径，而不是默认 regression 输入模式

---

## Q9. Judge 哲学

### 问题

你是否认可三层 judge 作为默认判分架构？

### 备选项

- A. `rule-first-only`
- B. `semantic-first`
- C. `three-layer judge`

### 背景与考虑

- 这道题本质上决定的是整个 evaluation 系统的“判分哲学”：你到底想把它做成一个 rule-first 的回归系统、一个 semantic-first 的语义评审系统，还是一个分层组合系统。
- 如果没有 judge 分层，系统最后很容易滑向两种坏结果之一：
  - 全部靠字符串 / 规则匹配。实现简单，但对复杂 case、表达变体、主次因判断、recommendation 合理性很脆。
  - 全部靠 LLM 判分。更灵活，但 pass/fail 会抖动，成本高，而且很难解释为什么这次 fail。
- 三层 judge 的目的，就是把“是否可评”“哪些硬性要求必须满足”“哪些语义问题需要弹性判断”拆开处理，避免把所有判断都挤进一层里。

### 三层分别负责什么

1. `execution checks`

- 先判断这次 run 是否真正可评
- 例如 workspace 是否创建成功、source prepare 是否成功、是否超时、是否 tool fail、最终输出是否为空
- 这一层回答的是：这次结果到底是“答错了”，还是“根本没成功跑完”

2. `deterministic rubric`

- 处理最重要、最稳定、最应该可解释的要求
- 例如是否识别了正确 root cause、是否检查了特定数据源、是否命中关键 instance / digest / bug ID、是否踩了 negative assertion
- 这一层应该成为 v1 的主 gate，因为它最稳定、最便于复查、最适合做 baseline diff

3. `LLM semantic judge`

- 只处理规则不容易稳定覆盖的部分
- 例如 primary / secondary root cause 排序是否合理、因果链是否完整、recommendation 是否对症、是否有明显幻觉
- 这一层更适合补边界和解释，而不适合承担所有 hard gate

### 三种哲学的取舍

#### `rule-first-only`

优点：

- 最稳定
- 最便宜
- 最容易解释和复查
- 最适合做 hard gate

缺点：

- 对复杂 case 的表达变体适应性弱
- 很难稳定判断主次因排序、因果链完整性、recommendation 是否真正对症
- 规则可能不断膨胀

#### `semantic-first`

优点：

- 对复杂表述更灵活
- 新 case 扩展速度可能更快

缺点：

- pass / fail 更容易抖动
- token 成本更高
- 很难做强 hard gate
- 不利于结构化 diff 和运营

#### `three-layer judge`

优点：

- 能同时兼顾稳定性、解释性和复杂语义覆盖
- 更适合 daily regression、baseline diff、回归发现和后续运营
- semantic judge 可以按需触发

缺点：

- 工程复杂度更高
- 需要清楚定义三层边界

### 默认建议

- C. `three-layer judge`

默认理解：

- `execution` 解决“这次是否可评”
- `deterministic` 解决“这次是否触犯硬性错误”
- `semantic` 解决“这次是否在复杂语义上发生质量退化”

---

## Q14. Baseline 粒度

### 问题

baseline 的默认主视角应该落在哪个层级？

### 备选项

- A. `per-case baseline` 为主
- B. `per-suite baseline` 为主
- C. suite 为主视角，但底层保留 case pointer

### 背景与考虑

- 这道题的背景是在问：系统将来拿什么作为“参考线”来判断 regression。也就是，今天这次 run 结束后，到底跟谁比，才算退化了或进步了。
- 常见粒度有三种：
  - `per-case baseline`：每个 case 自己有一条参考结果
  - `per-suite baseline`：一个 suite 绑定一套基线结果
  - `variant baseline`：按 model / prompt / skill / tool 组合维护多条 baseline
- 这题不是最前置的问题，但在设计持久化对象、promote baseline 动作和 admin 结果页之前，最好定下来。

### 重要说明

- `per-suite` 和 `per-case` 并不冲突，它们更像是两个层级，而不是二选一互斥。
- `per-case baseline` 解决的是“单个 case 的参考结果是什么”。
- `per-suite baseline` 解决的是“这次 suite run 应该整体拿哪一组 case baseline 来比较”。
- 一个自然的设计是：
  - suite baseline 是一个“基线集合”
  - 集合里实际关联的是每个 case 的 baseline pointer 或 baseline judgment

### 两种主视角的差异

- 如果以 `per-suite` 为主视角：
  - 更适合 daily run
  - 更适合 admin 看一次 run 的整体状态
  - promote baseline 更像“promote 一套 suite 结果”
  - 更适合先做运营闭环
- 如果以 `per-case` 为主视角：
  - 更适合精细分析单个 case 的历史演化
  - 更适合 case 级 review、特殊基线管理和个别 rerun
  - 但 v1 的 schema 和 UI 往往会更碎

### 默认建议

- C. suite 为主视角，但底层保留 case pointer

默认理解：

- 运营和调度层面：以 `per-suite baseline` 为主
- 存储和判分层面：以 `per-case baseline pointer` 为底座
- `promote baseline` 默认发生在 suite 层
- `judgment / diff` 默认落在 case 层

---

## Q17. Case 迁移范围

### 问题

现有 `tools/replayer/cases/*` 应该如何进入新系统？

### 备选项

- A. 一次性全部迁移
- B. 先迁 `core-daily` 小集合
- C. 只迁新 case，旧 case 暂不迁

### 背景与考虑

- 现有 case 资产已经很有价值，但成熟度、稳定性、成本层级并不完全一致
- 一次性全迁会放大 authoring、judge、baseline 和 daily 成本问题
- 完全不迁又会丢掉已有真实 incident 资产

### 默认建议

- B. 先迁 10-20 个最稳定、最能代表 guardrail 的 `core-daily` case

---

## Q21. Daily 预算

### 问题

你认可什么量级的 daily regression 预算？

### 备选项

- A. 小而精：`core-daily` 10-20 个，`high-cost` 默认 weekly
- B. 中等覆盖：30-50 个，允许少量高成本 case 进入 daily
- C. 激进覆盖：尽可能多地 daily 跑

### 背景与考虑

- 当前长期成本的主要压力很可能不是 collection，而是：
  - LLM token
  - semantic judge
  - 高成本 case 的 profiling / follow-up / 外部依赖
- 这题会直接影响 suite 分层、judge 策略、scheduled run 时长和预算控制逻辑

### 默认建议

- A. 小而精

默认理解：

- `core-daily`: 10-20 个最关键 case
- `daily-lite`: 范围更广，但默认只做 execution + deterministic
- `high-cost` case 默认 weekly

---

## Q27. 重构方式

### 问题

这次重设计，你更偏向哪种工程路径？

### 备选项

- A. 桥接式重构
- B. 平台式重构
- C. 暂时维持现状，只做增量修补

### 背景与考虑

#### 桥接式重构

- 先复用 replayer case 和现有 repo 资产
- 补 backend runner、DB schema、judge 和 admin 结果页
- 更强调“先接住已有资产，再逐步平台化”

#### 平台式重构

- 直接新建完整 evaluation domain model
- 把旧系统和旧 case 当迁移输入
- 架构更干净，但起步成本和切换成本更高

#### 维持现状 / 增量修补

- 继续在现有工具和页面上做局部增强
- 起步最轻，但后续容易继续累积历史包袱

### 默认建议

- A. 桥接式重构

原因：

- repo 已经有不少真实 case 资产
- 先把资产接住，比一开始追求“平台绝对纯净”更务实
- 更适合先完成 Phase 1 和 Phase 2

---
---

## 当前建议总结

如果当前没有更强共识，建议先按下面这组默认值推进 v1 方案：

- Q4: backend runner 主导，bash 保留为 debug helper
- Q7: 默认冻结输入 / 稳定 replay context
- Q9: three-layer judge
- Q14: suite 为主视角，case pointer 为底座
- Q17: 先迁 `core-daily` 小集合
- Q21: `core-daily` 10-20 个，`high-cost` 默认 weekly
- Q27: 桥接式重构

这组默认值的核心倾向是：

- 先接住已有 case 资产
- 先把正式执行链路和 judge 模型立住
- 先把 daily regression 做成稳定、可运营、可演进的系统
- 不在 v1 过早追求全覆盖、全自动、或平台绝对纯净