火花会 Sparkwave 新能力：接入本机「带本体的知识库」------让头脑风暴同时听得懂自有语料与企业知识
一文读懂「外部知识库组合检索」：能力项 + 实现过程。
引言
在人机混合的头脑风暴房间里，智能体发言的含金量，一半来自推理，一半来自它所检索到的知识。
火花会（Sparkwave）一直拥有自己的三维度知识库（业务领域／方法论／技术架构），管理员上传文档、系统切块嵌入，智能体绑定后按需检索。但很多组织在本机还有一套更重的知识资产------带本体（Ontology）、实体图谱与语义检索能力的中心知识库（my-center-knowledge-lib）：它从权威源目录同步 Markdown 文档，构建向量索引（Qdrant）、本体与实体图谱（Neo4j），并提供语义检索 API。
于是自然的问题出现了：能不能让 Sparkwave 既用自己的知识库，又实时借力这套带本体的中心知识库？
答案是：能。这就是本版新增的「外部知识库组合检索」能力。下面是它的能力清单与实现历程。
一、能力项
1. 一个连接，两个知识源兼有
管理后台新增「外部知识库连接」分区：填 API 地址、访问令牌、启用开关，即可连上本机中心知识库。内容不导入本系统------Sparkwave 不复制任何外部文档，只保存一条「连接配置」与若干「挂接关系」，检索时实时访问外部 API。
- 访问令牌受保护：掩码回显、仅管理令牌可读写、日志与导出不含；
- 「测试连通」用表单当前值即时验证------所见即所测，未保存也能测；
- 未启用时零外部调用，检索为纯本地，随时可退回。
2. 语料库挂接与别名
外部语料库以「挂接」方式归属到某个维度知识库：挂接即生效，解除即回到纯本地，没有复杂的启停开关。当外部语料库与本系统知识库、智能体重名时，可为其定义别名（全局唯一），管理界面以别名区分、消解混淆。语料库列表的按钮会实时表达挂接状态：未挂接显示「挂接」，已挂接显示「已挂接」，点击即可查看挂接信息。
3. 组合检索：发言同时检索两个知识源
智能体发言时，绑定知识库的检索自动升级为双源组合：
- 本程序知识库：本地 Chroma 向量检索（相似度分）；
- 外部挂接知识库：各挂接语料库的语义检索（RRF 融合分，可借力外部本体与图谱扩展）；
两个源的分数量纲不同，不能直接比较，因此采用「源内归一化 + 等权合并 」：各自归一到 0~1 后合并排序，按内容哈希跨源去重 （同一片段只留高分者），最后截断 Top-K------合并结果就是发言真正会引用的那几条证据。
4. 显式降级：外部掉线不打断头脑风暴
外部知识库不可达、超时或令牌失效时，该源按 0 条处理并显式标注 （日志与管理界面可见），讨论照常进行；全部外部源不可用即退化为纯本地检索。静默降级被视为缺陷------这是本系统一贯的工程原则。
5. 外部知识库连接层：随服务启动的后台快照
为了管理界面的即时体验，新增了随服务启动的「连接层」：一个每 15 秒刷新的后台任务，维护语料库清单、存在/归档/消失状态与健康状态快照。管理类读接口（语料库列表、挂接失效判定）走快照即时返回，不再逐条实时调外部；发言检索仍实时访问，实时性不受影响。外部语料库增删归档，最长 15 秒即反映到界面。
6. 知识检索测试验证：所见即发言所用
独立分区「知识检索测试验证」让管理员不用建房 就能验证检索效果：输入查询词、选范围（全部知识库或某知识库），一次执行、三组对照------本程序知识库命中／外部挂接知识库命中／合并结果 ，每条带文本片段、来源（知识库名／外部别名）与分数。合并组与智能体发言共用同一算法路径：你看到的 5 条，就是发言时真正进入上下文的那 5 条。测试是一次性内存态操作，不落库、不影响房间讨论。
7. 安全与边界
- 全部端点须管理令牌；外部令牌只存后端、不出浏览器；
- 只读外部、不写外部；不导入、不同步、不回写；
- 不管理外部本体/实体图谱（由中心知识库自身界面负责）------本体能力经其检索 API 间接借力。
二、实现过程
第 1 步：调研------摸清中心知识库的对外能力
先读通了 my-center-knowledge-lib 的代码与需求规格：FastAPI + 单一 Bearer 令牌，语料库 CRUD、同步/重建任务、资产与切块、语义检索（按 corpus 定向、支持标签/时间/类别过滤）、本体与实体管理、图谱与统计。也确认了两个关键事实：检索按 corpus_id 定向；外部不提供原文下载接口。
第 2 步：需求定案------三版方案的演化
最初的设计是「拉取导入 + 增量同步」------把外部内容复制进本系统知识库。但用户给出了更本质的取向：两者知识库兼有、组合使用，不导入、不同步，实时经 API 访问；重名用别名消解。于是方案重构为「运行时组合检索」：
- 挂接粒度：仅知识库（维度）级；
- 合并权重：默认等权；
- 不做同步触发与任务查询；不做抽验检索（后演化为独立的「知识检索测试验证」）；
- 别名仅管理界面呈现，发言界面来源标注口径不变。
第 3 步：设计------需求稿与详细设计稿
按文档链规范产出两份设计稿：需求与设计（req-connect-to-my-knowledge-lib.md）与详细设计（design-spec-connect-to-my-knowledge-lib.md），覆盖数据模型（ExternalCorpusLink 挂接表 + 三键系统设置）、API 契约、合并算法、线程边界、测试矩阵与验收标准，并经用户评审定稿。
第 4 步：实现------模型、客户端、端点与合并算法
- 数据模型 ：新实体
ExternalCorpusLink（别名全局唯一、同库不重复挂接），幂等迁移脚本； - 外部客户端：同步 httpx 封装，连接 3 秒/总 8 秒超时，五类错误分类（不可达/未授权/超时/坏响应/不存在）；
- 五个端点：连接配置读写、连通探测、语料库列表、挂接 CRUD（409/422/502 分类文案）；
- 组合检索 ：
RetrievalService双源并发、源内归一化、等权合并、sha1 去重、Top-K 截断，并重构出retrieve_debug供测试验证分组透出； - 前端：连接分区、挂接模态与信息模态、知识库视图挂接面板。
第 5 步：打磨------用户反馈驱动的迭代
上线后的真实使用反馈推动了一连串体验修正，值得记录：
- 「测试连通提示未配置」→ 改为用表单当前值即时测试；
- 挂接按钮无反馈导致重复提交 → 提交期间禁用并显示「挂接中...」；
- 「挂接中」状态残留下一次模态 → 请求一返回立即复原 + 打开模态兜底复原；
- 挂接成功后按钮未及时变「已挂接」→ 乐观更新 + 后台刷新带版本序号（过期快照丢弃，解决「解除要两次」）；
- 进入知识库分区要等一会儿才显示挂接 → 外部知识库连接层（随服务启动的后台快照）；
- 测试验证从分区内区块升级为独立功能分区（VW-A10），合并结果透明对照发言所用证据。
第 6 步：测试与文档------同轮同步、全量不回退
- 新增单元与集成测试 20+ 例（客户端错误分类、归一化/去重/合并、降级显式、挂接冲突矩阵、快照状态、检索验证分组一致性......）；
- 全量回归 458 例通过，发言、结论、语音输入等既有能力零回退；
- 文档链同轮同步：srs（FR-13/FR-14、A-23/A-24）、architecture、data-model、view-spec（VW-A9/VW-A10）、user-stories（US-G5/G6）、runbook、local-run-guide、AGENTS（不变量 21）、rules、README。
结语
「外部知识库组合检索」给火花会装上了一根可以随时插拔的知识脐带：本机那套带本体、带图谱的语义知识库，不必迁移、不必导入，就能实时流入每一轮头脑风暴------而每一次发言用到了哪几条证据，管理后台都能一眼验证。
接下来，本体与实体图谱在检索中的权重还可以进一步利用（如把实体关系路径透传到证据标注、支持外部检索的标签与类别过滤），这扇门已经打开。