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

12 KiB
Raw Permalink Blame History

复现知识库 · 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
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,并人工确认它覆盖对了 —— 这是整个自我纠错机制唯一的实战证据