Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 32 additions & 10 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,10 +121,32 @@ eval/ · eval/cases/ · observability/ · 飞轮/ # 评估门 / **失
app/ .claude/skills/ .github/(CI-CD) tests/ # 实现层
```

## 当前指针(随推进更新 — 上次更新 **2026-10-18** 会话:`DEC-019/020 均已实施并合(#81/#79)· 只剩 live 回归未跑 · 锚点已按实况更正`)
## 当前指针(随推进更新 — 上次更新 **2026-10-18** 会话:`DEC-019` 完整 live 回归已跑完(47/48、exit 0)· 待签核 = 0 · 余项只剩环境待办)

> **🔜 新会话从这里接**:读本段 + `ROADMAP.md`「📌 交接」即可,不必翻历史。
> **B 的 12 个节点:已签核闭环 12 / 待终裁 0 / 技术欠账 0** —— 签核号到 **D-26**。
> **🔜 新会话从这里接**:读本段 + `ROADMAP.md`「📌 交接(**2026-10-18**)」即可,不必翻历史。
> **B 的 12 个节点:已签核闭环 12 / 待终裁 0 / 技术欠账 0** —— 签核号到 **D-29**。
>
> ✅ **2026-10-18 会话完成** —— **`DEC-019` 的完整 live 回归**(此前唯一未完成项):
> - run **`20261018-182724-e6212c1d`**:被测 `fastapi-rag-agent@150a963` + 隔离语料库(125 行)
> → **47/48 · 达标率 0.9792 · exit 0** · judge 39,697 token · **0 重试 / 0 解析失败**;
> - **对「判分器变严会不会误伤」的回答**:`rule_hit_judge_fail = 0`、`soft_miss_judge_pass = 0`
> ⇒ **本轮未观测到误伤**;唯一失败 `id=20` 是**真实被测失败**(召回 `[55,64,8]`,
> 未召回含「两者结果互补」的 doc 60)。⚠️ **边界**:单轮、n=48,不能外推;
> - **落点**:报告 `docs/reports/DEC-019-live回归-2026-10-18.md` · 失败回灌
> `eval/cases/fastapi-rag-2026-10-18.json` · 过程错误
> `docs/复盘/2026-10-18-语料筛选漏掉seed金标语料.md` · `DEC-019 §7`;
> - ⚠️ **成本如实**:有效轮之前有两轮无效(judge key 401 · 我方语料筛选漏 seed),
> **judge 合计 ≈83,000 token**(43,303 无效 + 39,697 有效)。
>
> ⚠️ **最新环境事实(与旧文档冲突,以本条为准)**:
> - 生产 `rag_db` 已有 **345 行 `documents`**,评测语料只占 **125 行** ⇒ **不能直接拿生产库跑评测**;
> 本轮用副本库 `rag_eval_20261018`(原库一行未动);
> - 被测仓结构已从 `api/` 改为 **`app/`**,官方镜像是 **`fastapi-rag-agent:latest`**;
> - ✅ **`tools/sut-harness/run_sut.sh` 已在同一任务内修好**(`DEC-023 §6`):
> 适配 `app/` + 官方镜像,支持 `EVAL_SUT_DB` / `EVAL_SUT_SESSION_TOKEN_LIMIT`,
> 单测 11 passed + 真机端到端 exit 0;**关键坑**:不能把源码只读直接挂 `/app`
> (应用要写 `.mem0/qdrant/.lock`)⇒ 只读挂 `/src` 再复制到可写 `/app`;
> - `EVAL_JUDGE_API_KEY` 曾失效(401),**已由业务方更新**(尾号 `fd3e`)。
>
> ✅ **2026-09-21 会话完成**(按业务方"建议顺序"逐条执行):
> - **B4 完成** —— 业务方 10 条盲标 → 回填参照集(**16 → 26 条**)→ `calibrate` **实测 0.88**(22/25),
Expand Down Expand Up @@ -181,16 +203,16 @@ app/ .claude/skills/ .github/(CI-CD) tests/ # 实现层
> - **`DEC-019`**(判分器放行了「非拒答的答非所问」)—— 签核 **D-28**(α + β)· **✅ 已实施并合(#81)**
> - **`DEC-020`**(门 2 判据取了「会话累计」)—— 签核 **D-29**(α)· **✅ 已实施并合(#79)**
>
> **🔜 当前唯一未完成:`DEC-019` 的<u>完整 live 回归</u>**(⚠️ **≈3.5 万 token ⇒ 须另批**)
> - **已跑的(judge 侧两件,30,266 token)**:`canary` **0/8**(改前 **3/8 被放过**,id=3/13/19)·
> **✅ `DEC-019` 的完整 live 回归:已于 2026-10-18 跑完**(本段原写"当前唯一未完成")
> - **judge 侧两件(2026-09-24,30,266 token)**:`canary` **0/8**(改前 **3/8 被放过**,id=3/13/19)·
> `calibrate` **1.00**(阈值 0.80;⚠️ 只能写「**本参照集已耗尽信息**」,不得写"已校准");
> - **未跑的**:SUT + judge 的**完整一轮** —— 被测容器已被删,**要重起**
> (`tools/sut-harness/run_sut.sh`;首次等 pip **30–60s**;判据是**能力探针**,不是 `/health`);
> - ⚠️ **为什么不能省**:改 Prompt 的完整回归是本仓既有纪律 ——
> **离线 `calibrate` 测不到「判分器变严后在真实链路里会不会误伤」**。
> - **完整一轮(2026-10-18)**:`20261018-182724-e6212c1d` → **47/48 · 0.9792 · exit 0**;
> `rule_hit_judge_fail = 0` ⇒ **未观测到误伤**;唯一失败 `id=20` 是真实被测失败(见上方交接);
> - ⚠️ **边界**:单轮、n=48;被测版本已变(`f2dad78` → `150a963`),**不能与历史 48/48 直接比较**。
>
> **其余未完成(不阻塞可用)**:① 轮间 2× 延迟悬案(16 轮内 1 次,成因未指名)
> ② 母体 Kit 缺陷观察(证据 1/2)③ 被测知识库有无文档(R1 探针)。
> ② 母体 Kit 缺陷观察(证据 1/2)③ **环境待办:修 `run_sut.sh`**(见上方"最新环境事实")
> ④ `id=20` 的检索问题(未改被测,仅回灌)。
>
---
> ### 📜 **分界:以下全部是「历史」**(2026-09-10 ~ 2026-09-21 的过程记录)
Expand Down
72 changes: 57 additions & 15 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,23 +19,65 @@
⇒ **收窄为 `A-safe`**:只改报告面(`hits`→`issues`),**判分器入参的键一字不动**,并入方案 B(待报备 ≈3 万)。
新增 2 条守卫钉住该边界(**已突变验证**)。详见 `DEC-015 §7`。
- **定调**:阶段1/2 已由业务方逐条签核(D-1..D-9,2026-09-10);**P3 收口顺序已由 D-10a..D-10h 签核**(2026-09-10,grilling 定调压测门通过后,见 `docs/decisions/定调复核-签核记录.md`)。
- **🟢 收尾批次(裁定 D-23/24/25)—— ✅ P0+P1 已完成;⛔ P2 被环境卡住**
- **🟢 收尾批次(裁定 D-23/24/25)—— ✅ P0–P8 全部完成并合入 main**(2026-09-21 收口)
实施计划 = **`docs/plans/2026-09-15-收尾批次-实施计划.md`**(含逐项"认下的代价"与防伪清单)。
**✅ 已合**:计划与裁决(#59)· **PR-1 逐轮取证落盘 + `ab_pool`**(#60)· **PR-2 工具卫生三修**(#61);
**已合**:计划与裁决(#59)· **PR-1 逐轮取证落盘 + `ab_pool`**(#60)· **PR-2 工具卫生三修**(#61)
· **#64–#67** · **#69** · **#70–#72** · **#75**;**12 个遗留分支已清,仓库只剩 `main`**。
途中修掉真 bug:`_run_id` **同秒撞名** ⇒ 同一秒内两次运行的产物**静默互相覆盖**。
**⛔ 卡点**:**Docker Desktop 的 Linux VM 未运行**(虚拟化进程匹配数 0)⇒ `docker start` 挂死
⇒ `postgres-rag`/`redis-rag` 起不来 ⇒ 被测起不来 ⇒ **`chunk 1` 未开始**。业务方将自行重启 Docker。
**下一步**:预检 `run_sut.sh`(退出码 0)→ chunk 1(≈23 万 / ≈23 min)→ chunk-1 门禁(不过不开 chunk 2)。
**做**:A1 `T4` live A/B(≈116 万,分 5 块 + **已批准早停**)· A2 `DEC-015 B1`(≈3 万,**排在批次报告之后**)·
A3(并入 A1 的 40 轮)· B4 judge 校准(前置 **`DEC-017` 已签核 D-25**)· B5 T5 重审(须单独 DEC)。
**不做**:B7 接入他人 PR 流程 · C1 M3 抽取(维持现状)。
**定性**:C2 `T3` → 正式判**不适用**+触发条件 · C3 MTTR → 设**覆盖目标**(守卫**尚未写**)· C4 飞轮 → **已裁决**。
⚠️ **C2/C3 零 token、不依赖 Docker ⇒ 可在等 Docker 期间并行做。**
- **⛔ 授权口径已更正(D-23)**:PR 合并**逐次批** —— 开好先问「可以合吗」,**自开 PR 不许自合**(取代 D-14 的 auto-merge 条款)。
- **下一步(节点侧)**:**B 的 12 个节点全部闭环(已签核 12 · 待终裁 0 · 技术欠账 0)**,签核号到 **D-24**。
节点表已无待办;剩余全部集中在上面那个批次里。

### 📌 交接(**2026-09-21** 会话末 · 新会话从这里接)
**`DEC-021`**:测试基数复算 **499 → 554**(由 #69 承载)。
- **✅ `DEC-019` / `DEC-020`:均已签核、实施并合**(`#81` / `#79`);
**`DEC-019` 的完整 live 回归已于 2026-10-18 跑完** —— **47/48、exit 0**,
**未观测到判分器误伤**(`rule_hit_judge_fail=0`)⇒ 见下方「📌 交接(2026-10-18)」。
- **⛔ 授权口径(D-23)**:PR 合并**逐次批** —— 开好先问「可以合吗」,**自开 PR 不许自合**(取代 D-14 的 auto-merge 条款)。
- **下一步(节点侧)**:**B 的 12 个节点全部闭环;待签核 = 0;收尾批次已收口**。
剩余 = **环境待办**(修 `run_sut.sh`)+ 非阻塞观察项,见下方「📌 交接(2026-10-18)」。

### 📌 交接(**2026-10-18** 会话末 · 新会话从这里接)

> **🔜 一句话**:`DEC-019` 的**完整 live 回归已跑完** —— **47/48、exit 0**;
> **未观测到 α 造成的误伤**(`rule_hit_judge_fail = 0`)。
> ⇒ **B 的 12 节点 + 收尾批次 P0–P8 + `DEC-019`/`DEC-020` 全部收口;待签核 = 0。**

#### ✅ 2026-10-18 完成了什么

| 序 | 事 | 落点 |
|---|---|---|
| 1 | **`DEC-019` 完整 live 回归** | ✅ run `20261018-182724-e6212c1d` · **47/48 · 0.9792 · exit 0** · judge 39,697 token |
| 2 | 报告(环境/语料/证据/复跑命令) | `docs/reports/DEC-019-live回归-2026-10-18.md` |
| 3 | 唯一失败 `id=20` 回灌 | `eval/cases/fastapi-rag-2026-10-18.json`(`status=open`) |
| 4 | 过程错误复盘(两轮无效,83,000 judge token) | `docs/复盘/2026-10-18-语料筛选漏掉seed金标语料.md` |
| 5 | `DEC-019` 补记 §7 | `docs/decisions/DEC-019-判分器放行口径.md` |
| 6 | **修好 `run_sut.sh`**(适配 `app/` + 官方镜像;env 覆盖隔离库/会话预算) | `tools/sut-harness/run_sut.sh` · `DEC-023 §6` · 单测 11 passed + 真机 exit 0 |

**对「α 会不会误伤」的回答**:`rule_hit_judge_fail = 0`、`soft_miss_judge_pass = 0`;
唯一失败 `id=20` 是**真实被测失败**(召回 `[55,64,8]`,未召回含「两者结果互补」的 doc 60),
判分器判 fail 正确。⚠️ **边界**:单轮、n=48;被测已从 `f2dad78` 前进到 `150a963`,
**不能与历史 48/48 基线直接比较**。

**环境关键事实(本轮实测)**:

- 生产 `rag_db` 已有 **345 行**,评测语料只占 **125 行**(其它项目/测试灌入 220 行)
⇒ **不能直接拿生产库跑评测**;本轮用副本库 `rag_eval_20261018`(原库一行未动);
- 被测仓已从 `api/` 改为 **`app/`**,官方镜像是 **`fastapi-rag-agent:latest`**;
- **`tools/sut-harness/run_sut.sh` 已在同一任务内修好**并真机验证(exit 0 + 能力探针通过):
自动识别 `app/`,默认官方镜像/网络,支持 `EVAL_SUT_DB` / `EVAL_SUT_SESSION_TOKEN_LIMIT`;
⚠️ 关键坑:**不能把源码只读直接挂 `/app`**(应用要写 `.mem0/qdrant/.lock`)⇒ 只读挂 `/src` 再复制到可写 `/app`;
- `EVAL_JUDGE_API_KEY` 曾失效(401),**已由业务方更新**(尾号 `fd3e`)。

#### ⚠️ 下一会话开工要盯的

1. **待签核 = 0**;没有未完成的评测节点。
2. **✅ 环境待办已清**:`tools/sut-harness/run_sut.sh` 已适配 `app/` + 官方镜像,
单测 11 passed + 真机端到端 exit 0(见 `DEC-023 §6`)。
3. **非阻塞余项**:① 轮间 2× 延迟悬案(16 轮内 1 次,成因未指名)
② 母体 Kit 缺陷观察(证据 1/2)③ R1 探针(生产库有无文档 —— 本轮已间接回答:**有 345 行**)。
4. **`id=20` 的检索问题未修**(被测未改),只回灌不结论。

### 📜 历史交接(**2026-09-21** 会话末,**已被上文 2026-10-18 取代**)

> ⚠️ **本段当时的「当前唯一未完成 = `DEC-019` 完整 live 回归」已于 2026-10-18 跑完**
> (47/48、exit 0、未观测到误伤)⇒ 以**上方「📌 交接(2026-10-18)」为准**;
> 本段保留作过程记录,下面所有「未跑 / 待做 / 下一步」均按**过去时**读。

> **🔜 一句话**:收尾批次 **P0→P8 全部完成并已合入 main** —— **整个批次收口**。
> `main` **不写死 sha**(它每次合并都会过期 ⇒ 现取:`git log -1 --oneline main`)。
Expand Down
40 changes: 40 additions & 0 deletions docs/decisions/DEC-019-判分器放行口径.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,3 +143,43 @@ assert "答非所问" not in sysp.replace("答非所问时", "")
- ⚠️ **α ≈ 4.9 万 token**(回归 ≈3.5 万/轮 + `calibrate` ≈1.4 万);
- ⚠️ **α 会让判分器更严** ⇒ `judge_human_agreement` **可能下降** —— **那是仪器变准,不是回归**;
- ⚠️ **β 眼下就是红的**(洞未修)⇒ **实施时必须二选一**:先修 α 让它转绿,或**显式标"已知未修"**。

## 7. 完整 live 回归(**2026-10-18 已跑**)

> **本节补上 §6.3 之后唯一欠着的验证** —— 离线 `calibrate` 测不到
> 「判分器变严后在真实链路里会不会误伤」。

- **run**:`20261018-182724-e6212c1d`(eval-gate `5375542`)· 被测 `fastapi-rag-agent@150a963`
- **环境**:官方镜像 `fastapi-rag-agent:latest` + **隔离语料库 `rag_eval_20261018`(125 行)**
—— 生产 `rag_db` 已有 345 行(混入其它项目语料),不能直接跑
- **结果**:**47/48 通过(0.9792)· 1 失败 · 0 存疑 · 红队突破 0 · exit 0**
- **judge**:39,697 token · 45 次调用 / 45 条用例 · **0 重试 / 0 解析失败 / 0 截断**

### 7.1 对「α 会不会误伤」的回答

| 判据 | 值 | 结论 |
|---|---:|---|
| `rule_hit_judge_fail` | **0** | **没有**「字面命中却被判 fail」的条目 —— 最直接的误伤形态未出现 |
| `soft_miss_judge_pass` | **0** | 也没有反向的「软层没命中、judge 放过」 |
| 唯一失败 `id=20` | 真实失败 | 召回 `[55,64,8]`,未召回含「两者结果互补」的 doc 60;被测如实拒答 ⇒ judge 判 fail 正确 |

⇒ **本轮没有观测到 α 造成的误伤。**
⚠️ **边界(不得省略)**:单轮、n=48;本轮没有出现「字面命中 + 答非所问」同时成立的样本;
被测版本已从 `f2dad78` 前进到 `150a963`,**不能与历史 48/48 基线直接比较**。

### 7.2 过程与成本(如实)

- 有效轮之前有**两轮无效**:
① judge key 失效(HTTP 401,judge 0 token,SUT 侧约 5 万);
② **我方语料筛选漏掉 `eval_dataset.json#10–#25` 的 16 篇 seed**(43,303 judge token 白花)——
过程错误见 `docs/复盘/2026-10-18-语料筛选漏掉seed金标语料.md`;
- 本轮 judge 合计 **≈83,000 token**(43,303 无效 + 39,697 有效);
- 完整证据、隔离语料构成与复跑命令:
**`docs/reports/DEC-019-live回归-2026-10-18.md`**;
- 失败回灌:**`eval/cases/fastapi-rag-2026-10-18.json`**(id=20,`status=open`)。

### 7.3 同时发现的环境问题(与 DEC-019 无关,单独跟踪)

`tools/sut-harness/run_sut.sh` 已与当前被测结构不匹配(被测从 `api/` 改为 `app/`,
默认镜像 `my-fixed-name-api` 也已过期)⇒ **旧命令会直接跑不起来**;
本轮按 harness README 的退出条件改走官方镜像。修复列入待办。
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# DEC-023 · live 回归的环境选择:隔离语料库 + 官方镜像

- 状态:**已实施**(2026-10-18,`DEC-019` 完整 live 回归)
- 类型:工程方法决策(非业务口径,无需业务方签核)
- 关联:`DEC-019`(判分器放行口径)· `DEC-018`(证据覆盖)· `DEC-014`(归档按需)

## 1. 背景(实测,不是推断)

跑 `DEC-019` 的完整 live 回归时,环境已经和旧文档不一致:

| 事实 | 实测 |
|---|---|
| 生产库 `rag_db` 的 `documents` | **345 行**;评测语料只占约 **125 行**,其余是其它项目/测试灌入(`a.md` 91、`test` 48、`isolation-seed` 16、demo/probe 等) |
| 被测仓结构 | 已从 `api/` 改为 **`app/`**(HEAD `150a963`,2026-10-18) |
| 官方镜像 | **`fastapi-rag-agent:latest`**(2 天前构建);旧 `my-fixed-name-api` 停留在 2026-07-01 |
| 旧 harness | `tools/sut-harness/run_sut.sh` 仍要求 `api/` + 旧镜像 ⇒ **直接跑会 `die`** |
| judge key | `EVAL_JUDGE_API_KEY` 曾失效(HTTP 401),业务方已更新 |

## 2. 备选方案与评估

| 方案 | 做法 | 优点 | 代价 / 为什么没选 |
|---|---|---|---|
| **A. 直接跑生产库** | 不隔离,`top_k=3` 面对 345 行 | 零准备成本;最接近"生产真实" | **失败无法归因**:无关语料挤占召回,分不清是被测退化、判分器变严还是语料污染 |
| **B. 清理生产库** | 删掉非评测语料 | 库变干净 | **破坏性**:生产库是共享数据,别的项目正在用;**否决** |
| **C. 隔离副本(选定)** | `CREATE DATABASE rag_eval_20261018 TEMPLATE rag_db` → 过滤 + 去重 → 125 行 | **原库一行不动**;失败可归因;可重复 | 需要准确识别评测语料;结果**不能直接代表生产库** |
| **D. 修旧 harness 后照旧跑** | 把 `run_sut.sh` 改到 `app/` | 保留旧路径 | 官方镜像已可用(harness README 的**退出条件**已满足);临时改 harness 会把"环境修复"混进本次回归;**推到单独待办** |
| **E. 回退被测到 `f2dad78`** | worktree checkout 旧版本 | 与历史 48/48 可比 | 业务方明确告知数据已变;目标是**当前链路**里验证判分器,不是复现旧基线;**否决** |

## 3. 决策

1. **语料**:用副本库 `rag_eval_20261018`,生产 `rag_db` 不写、不删;
2. **被测运行方式**:走官方镜像 `fastapi-rag-agent:latest`(按 `tools/sut-harness/README.md` 的退出条件);
3. **会话预算**:本轮容器临时设 `SESSION_TOKEN_LIMIT=200000`(新版被测默认 5 万,单轮会触顶);
4. **judge key**:使用业务方更新后的 `EVAL_JUDGE_API_KEY`;
5. **旧 harness**:本决策做出时先不改(不把环境修复混进回归);
**同一任务内已补修** —— 见 §6。

## 4. 认下的代价与边界(不得省略)

- ⚠️ **结果不能与历史 48/48 直接比较**:被测版本(`f2dad78` → `150a963`)与语料(70 篇 → 125 行)都变了;
- ⚠️ **隔离语料的正确性依赖"评测事实反查"** —— 本次第一版过滤漏掉了
`eval_dataset.json#10–#25` 的 16 篇 seed,导致一轮 **37/48 的无效结果**;
补救与防错见 `docs/复盘/2026-10-18-语料筛选漏掉seed金标语料.md`;
- ⚠️ **隔离库 ≠ 生产库**:它回答"判分器在真实链路里是否误伤",不回答"生产库当前质量如何";
- ~~⚠️ **旧 harness 仍是坏的**:下轮若照旧命令跑会直接失败~~ ⇒ **已于同一任务内修复(§6)**。

## 6. 补记:harness 已修(2026-10-18,同一任务内)

`tools/sut-harness/run_sut.sh` 已按本 DEC 的官方路径重写:

- 源码目录自动识别:`app/` 优先,兼容旧 `api/`;
- 默认镜像改为 `fastapi-rag-agent:latest`、网络改为 `fastapi-rag-agent_app-net`;
- 去掉旧 `/deps` 卷与启动时 `pip install`;
- 新增两个评测必需的可选覆盖:`EVAL_SUT_DB`(隔离库)与 `EVAL_SUT_SESSION_TOKEN_LIMIT`(会话预算);
- **源码只读挂到 `/src`,容器内复制到可写 `/app` 再启动**
—— ⚠️ 实测:**直接只读挂 `/app` 会失败**(应用要写 `/app/.mem0/qdrant/.lock`,
`OSError [Errno 30] Read-only file system`);
- 保留能力探针与 DEC-016 被测自证。

**验证**:
- 单测 `tests/test_sut_harness.py` **11 passed**(含用 stub `docker`/`curl` 的 `docker run` 参数契约);
- 真机端到端:**exit 0**,`/health` 200 + **能力探针通过**,
`eval/runs/.sut-harness.env` 记 `EVAL_SUT_VERSION=150a963` / `EVAL_SUT_PROBE=ok`。

## 5. 实施结果

- run `20261018-182724-e6212c1d`:**47/48 · 0.9792 · exit 0**;
- `rule_hit_judge_fail = 0`、`soft_miss_judge_pass = 0` ⇒ 未观测到判分器误伤;
- 完整记录:`docs/reports/DEC-019-live回归-2026-10-18.md`。

## 变更记录

- 2026-10-18 建立(随 `DEC-019` 完整 live 回归落盘)。
Loading
Loading