# 子设计 1：Case 沉淀机制

**Date:** 2026-04-20
**Status:** Draft for discussion

---

## Summary

一个可长期运行的 evaluation 系统，前提不是“能 replay”，而是“能持续沉淀高质量 case”。如果 case 资产不稳定，后面的判分、baseline、daily run 都会失真。

本设计明确采用一个边界清晰的两阶段模式：

- **阶段 A：Golden Workspace 采集**
  由现有 Investibook 系统完成，人带着 AI 跑一次，得到一个高质量 `golden_workspace`
- **阶段 B：Evaluation Case 建档**
  由 evaluation 系统接管，从 `golden_workspace_id` 开始生成 case draft、评审并进入 suite

也就是说，evaluation 系统不负责“人工如何带跑第一轮”，这一步被视为前置 prerequisite。

本设计定义：

- case 从哪里来
- case 由谁来写
- case 需要包含哪些信息
- case 如何审核、分级和进入 suite

目标是把“写一个 `expected.md`”升级成“沉淀一个可执行、可判分、可复用的 eval case”。

---

## Case Source

case 仅允许来自以下三类来源：

### 1. 真实线上故障

例如：

- O11Y / TCOC / Jira issue
- Investibook workspace 诊断记录
- oncall handoff / postmortem

这是第一优先级，因为它最接近真实诊断需求。

### 2. 已知经典模式

例如：

- 热点
- pessimistic lock contention
- known bug
- GC pressure
- coprocessor worker OOM

适合补齐覆盖面，避免只围绕最近事故建 case。

### 3. 历史回归事故

即曾经修好、但容易反复退化的路径。它们通常应该进入 `core-daily` 或 `weekly-extended`。

---

## Boundary And Prerequisite

在第一阶段，case 建档的输入不是 ticket 本身，而是：

- `ticket / issue`
- 对应的 `golden_workspace_id`

其中：

- ticket 提供业务标识和背景
- golden workspace 提供首轮人工带跑后的高质量诊断素材

默认前置条件：

1. 人工已经在现有 Investibook 系统中完成一次带跑
2. 产出了一个可追溯的 golden workspace
3. `replay.sh <golden_workspace_id>` 或后续 runner 能从该 workspace 生成 case 草稿材料

因此，evaluation 系统里的 case 沉淀流程，应理解为：

`golden workspace -> case draft -> review -> active case`

而不是：

`ticket -> 人工带跑 -> case`

后者仍然存在，但属于 evaluation 系统之外的 prerequisite。

---

## Authoring Workflow

每个 case 的沉淀流程固定为 6 步，入口是 `golden_workspace_id`。

### Step 1: 输入 golden workspace

case 作者需要准备：

- issue ID
- `golden_workspace_id`
- cluster / version / environment 信息
- 故障时间窗
- 关键工具输出来源
- 已确认 root cause
- 推荐修复动作
- 常见误判点和负样本结论

最低要求：

- 必须能清楚回答“真实根因是什么”
- 必须能清楚回答“为什么是这个根因，而不是另一个候选结论”

### Step 2: 从 golden workspace 生成 case 草稿

系统应支持把 `golden_workspace_id` 作为输入，自动生成 case 草稿，至少自动填充：

- issue ID
- golden workspace 引用
- prompt
- cluster_type
- tidb_version
- time window
- 已触达工具列表
- 工具轨迹摘要
- 初版 `expected.md`

推荐产物：

- `case_draft.yaml`
- `expected_draft.md`
- `rubric_candidates.json`
- `negative_assertion_candidates.json`
- `intervention_trace.json`

作者主要补齐：

- ground truth
- rubric
- negative assertions
- case 分级和 cost tier

### Step 3: 填写结构化 `case.yaml`

`case.yaml` 是机器执行真值，建议字段包括：

```yaml
id: TCOC-5019
title: TiDB known bug with GC pressure
owner: huyibin
status: active
tags:
  - gc-pressure
  - heap-profile
  - known-bug
source:
  type: jira
  issue_id: TCOC-5019
golden_run:
  workspace_id: ws-xxx
  source: investibook-manual-run
environment:
  profile: stable-premium
  cluster_type: premium
  tidb_version: v8.5.4
time_window:
  start: 2026-03-31T10:00:00Z
  end: 2026-03-31T12:11:00Z
prompt:
  text: Use tidb-clinic-diagnosis to analyze...
ground_truth:
  root_cause: TiDB v8.5.4 known bug #66096 ...
required_data_sources:
  - metrics
  - slow_query
  - topsql
  - profiling
negative_assertions:
  - stale_stats_as_primary_root_cause
rubric:
  critical:
    - identify_gc_abnormality
    - identify_known_bug_66096
  major:
    - include_incident_window
    - recommend_upgrade
case_tier: P0
cost_tier: high
judge:
  llm_semantic_enabled: true
  max_followups: 2
```

### Step 4: 保留 `expected.md`

`expected.md` 面向人类阅读，建议固定结构：

- Root Cause
- Evidence Chain
- Causality
- Recommendations
- Scoring Rubric

要求：

- 表达 ground truth，而不是复述 agent 输出
- 内容简洁，但足够解释 critical rubric 的由来

### Step 5: Case 分层

每个 case 必须声明两种层级。

#### 业务重要性层级

- `P0`
  核心模式，daily 必跑
- `P1`
  重要模式，daily 可跑
- `P2`
  扩展模式，weekly 跑
- `P3`
  调试模式，不进入 daily

#### 成本层级

- `low`
  metrics / TopSQL / SlowQuery 为主
- `medium`
  含 logs / events / 少量 follow-up
- `high`
  含 profiling / heap / 多轮 follow-up / 复杂外部查询

### Step 6: Review 准入

新 case 进入正式 suite 前必须通过 review，检查：

- ground truth 是否稳定
- rubric 是否可执行
- golden workspace 是否足以支撑这些结论
- 是否与已有 case 重复
- 是否依赖不可复现的环境状态
- cost tier 是否合理

默认拒绝条件：

- 根因本身仍存在争议
- 只有人工主观阅读才能判断是否正确
- 太依赖瞬时线上状态，难以稳定复现
- 与已有 case 几乎重复，没有新增覆盖价值

---

## Authoring Contract

case 作者需要保证四件事：

1. `ground truth` 明确
2. `critical rubric` 明确
3. `negative assertions` 明确
4. `cost tier` 明确
5. `golden_workspace_id` 明确

如果上述任一核心项缺失，case 不应进入正式 suite。

---

## Suggested File Layout

每个 case 目录建议如下：

```text
<case-id>/
  case.yaml
  expected.md
  postmortem.md
  intervention-log.md
  attachments/
    notes.md
```

其中：

- `case.yaml` 是执行真值
- `expected.md` 是人工标准答案
- `postmortem.md` 是可选扩展背景
- `intervention-log.md` 记录首轮人工带跑过程中高价值的纠偏信息
- `attachments/` 存放辅助材料，不参与主判分

---

## Review Roles

建议引入两个角色：

- `Author`
  提交 case 草稿的人
- `Reviewer`
  对 root cause 和 rubric 负责的人

Reviewer 的关注点：

- 这个 case 是否值得长期维护
- critical rubric 是否真正能挡住错误诊断
- 是否存在容易误伤正确答案的规则
- golden workspace 是否已经足够“收敛”，可以作为后续 replay 的基线来源

---

## Entry Criteria For Daily Suite

一个 case 进入 `core-daily` 至少需要满足：

- 已完成 review
- ground truth 无争议
- cost 可控
- golden workspace 可追溯且可复用
- critical rubric 可自动判定
- 至少能覆盖一个明确的 failure mode

进入 `weekly-extended` 的 case 可以放宽：

- 允许成本更高
- 允许更多语义判断
- 允许需要更多 follow-up

---

## Tooling Expectations

为了让开发愿意沉淀 case，系统应提供半自动支持：

- 从 workspace / issue 自动初始化 case 草稿
- 自动生成初版 `expected.md`
- 自动提取候选 rubric 实体
  例如 digest、instance、metric、bug ID
- 自动检查是否和已有 case 相似
- 自动提示建议的 `case_tier` 和 `cost_tier`

目标是让作者主要做“审核与修正”，而不是从零手写全部文档。

---

## Flow Optimizations

在当前边界下，首轮人工带跑已经被隔离在 evaluation 系统之外，因此真正值得优化的是：

- `golden_workspace_id -> case draft`
- 人工纠偏信息的复用
- review 成本
- case 数量膨胀

### 1. 标准化 `golden workspace -> case draft`

当前最需要收紧的是：不要让不同作者从同一个 golden workspace 出发，最后写出风格差异很大的 case。

建议把这一步固定成标准流水线：

1. 读取 `golden_workspace_id`
2. 抽取 transcript、tool trace、final diagnosis、人工 follow-up
3. 自动生成 `case_draft.yaml`
4. 自动生成 `expected_draft.md`
5. 自动生成 `rubric_candidates.json`
6. 自动生成 `negative_assertion_candidates.json`

这样作者面对的不是原始 workspace，而是一组已经结构化的草稿材料。

核心收益：

- 降低 case authoring 的随机性
- 减少作者从头整理材料的成本
- 便于后续批量迁移历史 golden workspace

### 2. 把人工纠偏过程沉淀成结构化资产

golden workspace 最有价值的部分，不只是最终结论，还包括“人工如何把 AI 从错误路径拉回来”。

这部分如果只保留在消息流里，后续价值会快速流失。建议额外抽取并保留：

- AI 首轮遗漏了什么
- 人工发出的关键 follow-up
- 哪些 follow-up 改变了诊断方向
- 哪些误判路径是高频模式

建议形成以下派生产物：

- `intervention_trace.json`
- `followup_patterns.json`
- `common_mistakes.json`

这些产物后续可直接用于：

- follow-up policy 设计
- negative assertions 生成
- regression 失败归因

### 3. 把人工 review 分层

如果 reviewer 每次都要完整重读整个 golden workspace 和完整 draft，case 收集规模很难上去。

建议把 review 拆成三层：

- `结构 review`
  检查字段完整性、case tier、cost tier、文件产物是否齐全
- `真值 review`
  检查 root cause、critical evidence、negative assertions 是否成立
- `全文 review`
  只用于复杂 case、高成本 case 或存在争议的 case

默认要求：

- 普通 case 必须过 `结构 review + 真值 review`
- 只有复杂 case 才要求 `全文 review`

这样能明显降低 reviewer 成本，同时不牺牲核心质量控制。

### 4. 提前做 case 去重与 variant 收敛

如果一个 ticket 对应一个永久 case，case 数会膨胀得很快，daily run 成本也会同步上升。

建议在 `golden workspace -> draft` 阶段就做相似度判断，区分：

- `new_case`
- `case_variant`
- `duplicate_case`

建议比较的维度包括：

- root cause pattern 是否相同
- required evidence pattern 是否相同
- negative assertions 是否相同
- 只是实例值不同，还是机制真正不同

推荐策略：

- 机制相同、实体不同的，优先作为 variant 挂到已有 case
- 只有在 failure pattern 明显新增时，才新建长期维护的 case

这样可以让 suite 长期保持可控，而不是无限膨胀。

### Recommended priority

建议优先顺序如下：

1. 标准化 `golden_workspace -> draft`
2. 结构化保留 intervention 信息
3. review 分层
4. case 去重 / variant 收敛

原因是前两项最直接决定：

- case authoring 的轻量程度
- 后续自动 replay 和 regression 的可解释性

---

## Defaults

- 新 case 默认先进入 `draft` 状态
- 必须有 `case.yaml`
- 必须有 `expected.md`
- 必须声明 `owner`、`case_tier`、`cost_tier`
- 未经过 review 的 case 不进入 daily suite