Files
streamline/docs/kb-retrieval-injection.md
2026-11-16 17:26:44 -08:00

202 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 复现知识库 · Phase C:检索与注入
> 状态:**已上线;2026-08-21 重做过一版检索策略,2026-09-02 又补了「拉」和「归因」两条腿**。
> 下面按时间倒序:先是 2026-09-02 这次的依据与改动,再是 08-21 那次,最后是最初的设计,
> 都保留原样 —— 它们哪里判断错了,对下一次改动比它们哪里对了更有用。
## 2026-09-02:上线 12 天的实测,以及照着它改的四件事
08-21 那版的效果是真的(条目级引用率 3.6% → 40.9%),但同一批数据也把三个新问题
摆了出来。三条都不是调参能解决的,所以这次改的是结构。
### 实测(strategyAt = 2026-08-21 17:14,至今 12 天;分母是「回报过 KB_USED 的注入」)
| | 注入次数 | 每次条数 | 条目级引用率 |
|---|---|---|---|
| eval · 改版前 | 646 | 9.7 | **5.0%**(97 / 1958) |
| eval · 改版后 | 321 | 6.6 | **47.7%**(751 / 1575) |
| fix · 改版后(新开的) | 614 | 6.0 | **37.5%**(1263 / 3366) |
按 kind(改版后):env **43.2%**(1947/4508)· account 31.3% · pitfall 22.3% ·
entry_path **8.9%**(7/79)· experiment **0/89** · tricky 0/6。
fix 阶段 614 次注入里 561 次回报了 `KB_USED`,338 次(60%)至少用上一条。
### 三个问题,以及它们各自的证据
**① 归因回环仍然是开的。** 全部 1634 次注入:inconclusive 731 · contradicted 5 ·
confirmed 3 · 待判 895。改版后已评分的 350 次里只有 8 次不是 inconclusive。
不是缺证据 —— fix 注入覆盖 265 个 target,其中 **248 个有 verified 的 `run_conditions`**,
这些 target 上光 `env` 类就有 520 条真机确证条件,而 fix 注入的又几乎全是 env。
卡在 `matchStrength` 的主题相似度门槛上:把精确 key 相等换成分级匹配只把命中率从
0/381 抬到 8/350。**跨月、跨节点、各自随手写的 subject 和 statement,事后是配不回去的。**
**② 待判队列在结构上排不空。** 404 个待判 target 里 **214 个永远不可能被评分**
(一条 verified 条件都没有,`attributeTarget` 返回空、`outcome` 留 NULL),
而 sweep 每天只扫 100 个、**无排序无水位** —— 于是每天的预算被这批不可评分的吃掉,
真的能判的排在后面永远轮不到。
**③ 产品面知识在「推」这条路上不可能命中。** entry_path 展示 79 次引用 7 次、
experiment 展示 89 次引用 0 次。工单标题是在**任何人看到那个页面之前**写下的,
拿它去匹配入口路径,匹配到的是对的**模块**、错的**事实**。
### 改了什么
| # | 改动 | 落点 |
|---|---|---|
| ① | **让 agent 直接写下配对**:`conditions record --kb K1`,归因优先用显式关联,模糊匹配退为兜底 | `bin/conditions.ts`、`run_conditions.kb_labels`、`kb_outcome.ts::explicitLinks` |
| ② | **待判队列加水位和退出**:超过 7 天仍无任何真机确证条件的注入判为 `unscoreable`;sweep 按最早注入时间排序 | `kb_outcome.ts::sweepPendingAttribution` |
| ③ | **执行期可以反过来拉**:`kb recall --target bug:<id> "<问题>"`,命中项接着现有 K 编号往下排、并入同一份注入清单 | `bin/kb.ts`、`kb_retrieval.ts::recallClaims`、`POST /api/internal/kb/recall` |
| ④ | **产品面知识不再硬推**(`KB_INJECT_SPECIFIC_K` 默认 0),改由 recall 按真实问题检索 | `kb_retrieval.ts::SPECIFIC_K` |
四条是一件事的两半:**派发时推「不管什么单子都成立」的常驻知识,执行期拉「只有当下才知道要什么」的产品面知识**;
而两边用的是同一套 K 编号、同一行 `KB_USED:`、同一条归因路径,所以效果仍然是一个数能说清的。
### 三条必须守住的边界
1. **`--kb` 记录的是关联,不是判定。** agent 说「这条条件讲的是 K1」,
对不对由控制面拿 `--statement` 去比 —— 否则就是让模型给模型的知识投票,
`docs/rsi.md` 那条底线(真值只认执行结果)当场破掉。
2. **编号只在执行阶段解析。** eval 的 K1 和 agent 看到的 K1 不是同一条知识,
越界编号一律丢弃、同编号先写者胜(否则 ingest 顺序能翻转判定)。
3. **`unscoreable` 不是判定,是退出。** 它跟 `inconclusive` 分开计:
「看过了没配上」和「压根没东西可看」要修的是完全不同的两处
(前者是匹配规则,后者是记录纪律)。
---
## 2026-08-21 那次:上线后的实测
三周生产数据(688 次注入、200 次带引用回报):
| 观察 | 数值 |
|---|---|
| 条目级引用率 | **3.6%**(106 / 2973) |
| 撞满 K=10 上限的注入 | **649 / 688** |
| 按 kind 的引用率 | env 11.6% · account 6.0% · pitfall 4.4% · experiment 1.1% · tricky 0.9% · **entry_path 0.5%** |
| 跨任务复用过的 claim | **7 / 3748** |
| 已核实条件里 subject 在第二个任务再出现过的 | **9 / 3595** |
| 归因回环闭合过几次 | **0**(49,483 对比对,精确配对命中 0) |
两个结论,都跟原设计的假设相反:
1. **这个库当时几乎是一次性的。** 每条知识只在它诞生的那个任务里成立过一次。
对这样的语料做检索不是检索,是抽样 —— 起草者用 3.6% 的引用率把这件事说清楚了。
2. **文本相关性预测不了采纳。** 被引用与被忽略的知识,相关性均值 0.149 / 0.147,
每一类都如此。照相关性排反而比原来的按置信度排更差(MRR 0.275 vs 0.410)。
原因在读一眼被引用的内容就清楚了:"airb 远端是共享池"、"这个 inhouse 包首启会卡在
Feishu 验证" —— 它们跟工单写了什么无关,是关于**这台机器**的常驻知识,
而这正是唯一会复用的那部分。
## 重做后的四条策略
| # | 策略 | 落点 |
|---|---|---|
| ① | **分层**:episodic(只当证据)/ semantic(可检索)。凭出身(env/account、人工录入)或凭本事(被第二个任务见证、被起草者引用)晋升 | `kb_claims.tier`、`kb_db.ts::earnsSemanticTier` |
| ② | **两个检索池**:常驻知识按平台 + 历史表现选,不要求命中工单词;产品面知识(entry_path/experiment)才做文本匹配并设相关性下限,允许一条都不注 | `kb_retrieval.ts::STANDING_KINDS / retrieveClaims` |
| ③ | **有用度回流**:`injected_count` / `cited_count` 直接进排序权重 | `kb_retrieval.ts::usefulnessFactor` |
| ④ | **执行阶段也注入**(只 env/tricky/pitfall)+ 归因配对规则重写 | `routes.ts::FIX_STAGE_KINDS`、`kb_outcome.ts::matchStrength` |
## 效果(同一批历史注入回放,`bun scripts/kb_rank_replay.ts`)
- 每次注入 **9.9 → 3.3 条**(−67%),而被起草者引用过的知识 **99% 仍在注入里**;
- 排序 MRR **0.410 → 0.548**,被引用知识平均名次 3.41 → 3.24,前 3 条命中 57% → 59%;
- 可检索知识 3748 → 约三分之一,其余留库作证据。
回放是**前序式**的:给第 N 次注入打分时,有用度先验只看第 1..N-1 次的引用 ——
否则就是拿正在被预测的那次引用去预测它自己。面板「知识库蒸馏 › 效果」用的是同一段代码
(`kb_effectiveness.ts::replayRanking`),命令行和面板算出两套数字是这类度量最常见的烂尾方式。
---
## 1. 检索
### 第一版:不上向量库
`kb_claims` 已有 `embedding` 列但**先别用**。第一版走关键词 + 结构化字段的混合检索:
- Postgres `pg_trgm` 扩展,对 `statement` / `scope_label` / `subject_key` 建 GIN 索引
- 查询词从 task 的 `title` + `description` + `reproSteps` 抽取
- 硬过滤:`platform` 匹配(或 NULL)、`status = 'active'`
- 排序:`confidence × trgm 相似度`,取 Top-K
```sql
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE INDEX kb_claims_statement_trgm ON kb_claims USING gin (statement gin_trgm_ops);
CREATE INDEX kb_claims_scope_trgm ON kb_claims USING gin (scope_label gin_trgm_ops);
```
**K ≈ 8-12,渲染后正文 ≤ 2000 字。** 注入长度必须有硬上限:prompt 里每多一段"参考资料",模型对「铁律」和 NEEDS_INPUT 哨兵纪律的遵守度就掉一点,这个 tradeoff 是真实的。
### 第二版:语义检索
trgm 对「Story 相机」vs「故事拍摄页」这类同义表述无能为力(`normalizeKey` 也不行,见 `kb_arbitration.ts` 的注释)。届时:写入时算 embedding 存进 `kb_claims.embedding`,检索改成 `向量相似度 × confidence`,trgm 保留为召回补充。
---
## 2. 注入点(三处)
| 位置 | 文件 | 注入什么 |
|---|---|---|
| 评估器首轮 | `satellite/src/evaluator.ts` · `buildEvalPrompt` | 全部 kind —— 这是核心诉求,让首版 TestSpec 就带上正确的复现条件 |
| 评估器重生成 | `satellite/src/evaluator.ts` · `buildRegenPrompt` | 同上 |
| 修复执行器 | `satellite/src/runner.ts` · `buildSinglePrompt` | 只注 `tricky` / `env` / `pitfall` —— 构建命令、mock、必须冷启动之类,减少执行期踩坑 |
知识由**控制面**在派发时查好并随 Task 下发(控制面拥有 DB;卫星不该反向查库)。渲染格式:
```
## 已验证的历史复现知识(参考,非权威)
- [置信 0.87 · 最近验证 2026-07-10 · 源自 meego 7328764565] Story 相机:进入特效面板的路径是 我的 → 右上角三点 → 设置 → 隐私 → 故事
- [置信 0.62 · 最近验证 2026-05-02 · 源自 meego 7301120088] Story 相机:需开启 abid 7712334 才能看到特效入口
```
### 注入即 hint,不是 fact
prompt 里必须写死两条,否则这套东西会从"提高准确率"变成"系统化地传播错误":
1. **与代码调研冲突时以代码为准。** 知识库记录的是过去某次执行时的事实,代码是现在的事实。
2. **引用了哪条就在该位置标注来源。** 这不是为了好看 —— 它是下面命中率统计的唯一数据来源。
现有的「铁律」和 NEEDS_INPUT 哨兵机制**完全不变**:知识库里有,不等于可以不验证。评估器仍然必须对拿不准的内容打哨兵。
---
## 3. 注入 → 验证回环(`kb_injections`)
这是让知识库自我纠错的第二条腿(第一条是蒸馏时的仲裁,见 `kb_db.ts` 的 `arbitrate`)。
1. 评估/派发时,把注入的 `claimIds` 写一行 `kb_injections`(`stage` = eval / regen / fix);
2. 该 task 执行结束后回看:
- 产生了**针对某条注入 claim 的 SpecDelta** → 说明注进去的知识是错的 → 给该 claim 记一条 `refute` 证据;
- 没有相关 delta 且执行成功 → 记一条 `support` 证据;
3. 回填 `kb_injections.outcome` / `evaluated_at`。
匹配「SpecDelta 是否针对某条 claim」用与仲裁同一套 `(scopeKey, subjectKey, kind)` 对齐 + `claimsEquivalent`,不要另造一套 —— 两套判等规则一旦不一致,回环就会开始随机地奖惩知识。
**效果**:知识不只在蒸馏时更新,**每次被用到都在被执行器重新验证一遍**。这正是"执行器是验证器"这条原则的完整形态。
---
## 4. 效果度量
上线注入的同时必须能回答"它到底有没有用"。按**有无注入**分组对比(同期任务随机分流,或先按 scope 灰度):
| 指标 | 取数位置 | 预期方向 |
|---|---|---|
| 首版 TestSpec 的 NEEDS_INPUT 哨兵数 | 解析 `tasks.executionPlan` | ↓ |
| `pending_confirmation` 人工批注轮次 | `tasks.regenContext` 的重生成次数 | ↓ |
| 首轮复现成功率 | `unreproducible` 占比 | ↑ |
| 每任务 SpecDelta 条数 | `spec_delta_events` | ↓(spec 一开始就更准) |
| 注入命中率 | 生成文本里的来源标注 ÷ 注入条数 | 观测项,判断 K 值和检索质量 |
**注入条数 ↓ 而 SpecDelta 条数不降**,说明检索召回不行;**SpecDelta 降但 unreproducible 不降**,说明知识被采纳了但采纳的是错的 —— 这两种情况都要回到仲裁规则去查。
---
## 5. 上线前的前置条件
- [ ] `spec_delta_events` 里累计 ≥ 数十个任务的真实数据
- [ ] 「未声明率」(见看板 `undeclaredRate`)稳定在低位 —— 高说明采集在漏,注入会把漏掉的错误固化下来
- [ ] 人工抽查过一批 `kb_claims`,确认 scope / subject 的归一化没有把不同的事混成一桶(或把同一件事拆成多桶)
- [ ] 至少出现过一次**真实的自动 supersede**,并人工确认它覆盖对了 —— 这是整个自我纠错机制唯一的实战证据