|
| 1 | +# v0.19.3:读路径 B——检索建议(发现路径,建议制·默认关) |
| 2 | + |
| 3 | +> 状态:**已实施**(2026-09-03;真机验收待执行) |
| 4 | +> 依据:[v0.19 检索与发现层设计([ ] 已归档)](../archive/2026-09-03/2026-09-03-v0.19-rag-retrieval-discovery-design.md) §八 · ADR-029(决策 5/治理)· REQ-261 · REQ-262(发现开关余项) |
| 5 | +> 排期注:v0.19.2 采集体验小版本用户实测插队后,检索建议本批落地为 v0.19.3(原排期 v0.19.2 顺延一档) |
| 6 | +
|
| 7 | +## 一句话 |
| 8 | + |
| 9 | +体系概念详情出现「📎 相关素材建议」:以概念名+essence 全库检索 top-K(≤10,**排除已链接**)→ 逐条勾选 → 确认后仅经既有 `link_knowledge_target` 落库(白名单 note/fragment 零迁移,幂等,**建议零双写**);跨体系相似概念只提示不合并(人工处置)。feature flag `kb_discovery` 默认关——设置 → 学习库可开启(后端 command 同步把关)。 |
| 10 | + |
| 11 | +## 本批已交付 |
| 12 | + |
| 13 | +| 层 | 内容 | |
| 14 | +|---|---| |
| 15 | +| 开关 | FeatureFlags.kb_discovery(默认 false——保守默认纪律;旧 JSON 缺失字段零迁移回退默认;roundtrip/legacy 单测)· set/get 白名单扩展 | |
| 16 | +| 数据层 | kb_discovery.rs:kb_discovery_suggest(概念取回 → 排除集=该概念 knowledge_links 已链 note/fragment → name+essence 混合检索 → 过滤截顶 → 跨体系相似提示);纯函数 normalize_name(空白/全角/大小写折叠)与 concept_name_overlap(双向包含,短边 ≥2 字防单字误报);SimilarHint/DiscoveryResult serde camelCase | |
| 17 | +| 命令层 | kb_discovery_suggest(flag 关 → 明确报错引导设置——后端不信前端隐藏;concept_id ≤0 拒绝;None→"概念不存在")· lib.rs 注册 | |
| 18 | +| 前端 | DiscoverySuggestSection(概念详情建议区:开关关零渲染;候选勾选/确认/重建议;确认逐条 link 后 onChanged + 自动刷新(已链者随即消失);相似提示黄条展示型)· KnowledgeDetailPanel 概念分支嵌入 · LearningLibraryPanel「📎 相关素材建议」开关(feature_flags 持久化) | |
| 19 | +| 契约 | types/kb.ts:KbDiscoveryResult/SimilarHint;KbHit 复用(证据候选与引用卡片同字段口径) | |
| 20 | + |
| 21 | +## 测试与验证 |
| 22 | + |
| 23 | +- Rust:kb_discovery 6 用例(overlap 双向/单字拒绝/全角归一化、证据排除已链 note 与 fragment、跨体系相似仅跨体系、概念不存在 None)+ feature_flags kb_discovery roundtrip/legacy——`kb_discovery feature_flags` 过滤全绿 |
| 24 | +- 前端:DiscoverySuggestSection 3 用例(开关关不渲染零噪音 / 开启候选逐条确认仅走 link_knowledge_target(note+fragment 两路断言)+ onChanged + 刷新 / 空候选诚实文案)——vitest 71 文件 528 用例全绿;tsc 零错误 |
| 25 | +- Rust 全量:**2052 通过 / 2 失败(note_filter 预存 TD-30-B)**;clippy 零告警 |
| 26 | + |
| 27 | +## 治理落地 |
| 28 | + |
| 29 | +- 默认关:kb_discovery=false(UI 零渲染 + command 报错双保险);命中检索恒可用不受开关约束 |
| 30 | +- 铁律:建议不落库、零双写——确认路径唯一 = link_knowledge_target(幂等语义既有);相似概念为提示型(不自动合并——无合并命令且语义归人,YAGNI) |
| 31 | +- 性能:按实体现算(个人量级 <100ms),无后台批处理/无自动聚类任务(设计 §八 一致) |
| 32 | + |
| 33 | +## 验收(用户真机,待执行) |
| 34 | + |
| 35 | +- [ ] 设置 → 学习库开启「相关素材建议」→ 概念详情出现建议区;勾选确认 → 体系页引用即现;未确认不落库 |
| 36 | +- [ ] 已链接素材不再重复建议(确认后自动从候选消失);跨体系相似概念黄条提示可人工处置 |
| 37 | +- [ ] 开关关闭时概念详情无建议区且直接调用 command 被拒(错误文案引导设置) |
| 38 | +- [ ] 回归:v0.19.0~2 全部既有路径(学习库问答/窗口选择/索引)零回归 |
| 39 | + |
| 40 | +## 关联与后续 |
| 41 | + |
| 42 | +- 设计/ADR:设计 §八/§9 · ADR-029 · REQ-261/REQ-262(发现开关余项随本批) |
| 43 | +- 后续:v0.19.4(REQ-259 语义增强:EmbeddingEngine spike 选型后实施——RRF 函数已就绪待合流;不阻塞本批)· `/ask` 命令别名(设计 §7.1 下批接线评估)· 真机验收批 |
| 44 | + |
| 45 | +## 待办 |
| 46 | + |
| 47 | +- [ ] 真机验收(上述 4 项) |
| 48 | +- [ ] v0.19.4 embedding 选型裁决(内嵌 ONNX vs Ollama 端点——依赖环境与分发策略) |
0 commit comments