17 KiB
知识库检索与分块增强 User Stories
文档信息
| 项目 | 内容 |
|---|---|
| 状态 | 实施中 |
| 版本 | 0.1 |
| 日期 | 2026-08-11 |
| 关联 PRD | 知识库检索与分块增强 PRD |
1. 角色
1.1 普通知识使用者
已经导入公司制度、产品手册或项目资料，希望直接提问并得到稳定、带来源的回答， 不需要理解向量、RRF 或分块算法。
1.2 知识库维护者
负责导入、同步和清理资料，需要知道哪些文档成功、哪些索引失败，以及如何修复 错误解析或错误分块。
1.3 RAG 调试者
需要用真实问题验证召回，比较不同参数和通道，定位“文档里有但没有命中”的 原因。
1.4 本地与内网用户
不能把资料上传到外部知识库服务，希望全文检索、分块、重排和诊断均在本机 完成，只在显式配置 Embeddings 后发送有界文本。
2. Epic A：明确控制是否检索
US-A1 模型按需检索
作为普通知识使用者，我希望保留由模型判断是否需要检索的模式，以便一般闲聊 不会产生不必要的知识搜索。
验收：
- Given 当前启用了至少一个知识库并选择“模型按需检索”
- When 用户发送问题
- Then Main 只向本次请求开放已选知识库的只读搜索能力
- And 模型没有调用知识搜索时，不显示虚假的“已检索”
- And 未选中的知识库不可被工具参数扩大范围
US-A2 每次先检索
作为普通知识使用者，我希望选择“每次先检索”，以便模型不能跳过已启用的 知识库。
验收：
- Given 当前启用了至少一个知识库并选择“每次先检索”
- When 用户发送文本问题
- Then Main 在 Runtime 启动前使用原始问题执行一次有界检索
- And 命中证据以不可信上下文进入 Runtime
- And 模型仍可通过只读工具执行后续改写检索
- And 页面明确显示“已预检索”“零结果”或“已降级”
- And 图片生成请求不执行知识预检索
US-A3 请求级范围
作为普通知识使用者，我希望每次请求只使用我勾选的知识库，以免不相关资料 干扰回答。
验收：
- 新建知识库后只新增该知识库到当前选择，不自动重新启用已取消的知识库
- 删除知识库后从当前范围中移除对应 ID
- 同一请求最多启用 20 个知识库
- 对话输入区持续显示已选数量和检索方式
- 范围为空时检索方式不产生误导状态
3. Epic B：检索可见、可诊断
US-B1 打开检索测试
作为 RAG 调试者，我希望在当前知识库直接输入问题并测试，以便不通过聊天模型 也能验证索引。
验收：
- 知识库标题区提供“测试检索”次操作
- 工作台打开后焦点进入查询输入框
- 查询最多 4,000 字符
- 测试不创建聊天消息、任务成果或模型调用
- 关闭工作台后焦点返回触发按钮
US-B2 查看通道诊断
作为 RAG 调试者，我希望看到每种检索通道的结果和降级原因，以便判断问题来自 全文、向量还是图谱。
验收：
- 结果显示请求通道和实际使用通道
- 结果显示 FTS/CJK、向量和图谱候选数
- 结果显示总耗时和有界通道耗时
- 向量未配置、请求失败或索引不兼容时显示明确原因
- 不在错误或诊断中显示 API Key、Authorization 或完整文档
US-B3 查看排名与上下文
作为 RAG 调试者，我希望看到候选排名、最终相关度和送入模型的上下文，以便 解释最终回答为什么使用这些资料。
验收：
- 每条结果显示文档、定位、片段和最终排名
- 可用时显示全文、向量、图谱独立排名和向量相似度
- 启用本地重排后显示重排前排名
- 展示相邻块或父块合并后的上下文
- 展示上下文字符数、预算和截断状态
US-B4 零结果诊断
作为普通知识使用者，我希望零结果时获得具体原因，而不是只有空列表。
验收：
- 区分“知识库为空”“索引不可用”“查询无命中”“被阈值过滤”
- 提供修改关键词、检查状态或调整阈值的下一步说明
- 零结果不显示为首次使用空状态
- 检索测试保留原查询和设置，方便再次执行
4. Epic C：中文与混合检索
US-C1 中文自然语言召回
作为中文用户，我希望不用输入原文中的连续短语，也能找到表达相同意思的内容。
验收：
- 中文索引生成连续二元词组
- 中文查询不会要求所有不同汉字同时出现
- 短查询具有有界单字回退
- 中英文、数字和产品标识混合查询仍能召回
- 相同查询和索引产生稳定排序
US-C2 向量服务降级
作为本地与内网用户，我希望向量服务断开时仍可使用全文搜索，同时清楚知道 语义召回不可用。
验收：
- 查询向量失败不阻止 FTS/CJK 和图谱检索
- 检索响应包含向量降级原因
- 文档状态不把向量失败显示成全部完成
- 同名模型切换端点后，Fingerprint 不匹配的旧向量不得参与召回
- 重建失败时，上一版已就绪向量继续服务
- 修复配置并重建后，降级状态消失
- 故障信息经过脱敏
US-C3 大知识库向量检索
作为知识库维护者，我希望超过 5,000 个分块后语义搜索仍然工作。
验收：
- 向量分批扫描没有固定 5,000 分块空结果
- 只保留所需最佳候选，内存不会随全库候选等比例增长
- 扫描支持取消和应用关闭
- 10,000 个以上分块的测试返回正确 Top K
- 诊断显示扫描数量与耗时
US-C4 大目录完整同步
作为知识库维护者，我希望包含 2,000 个文件的目录也能完整增量同步，以免后半 部分文档长期保留旧内容。
验收：
- 第 501 至 2,000 个文档参与校验和比较
- 未变化文档不会重复解析和向量化
- 已删除文件对应文档会被移除
- 页面分页上限不影响后台同步完整性
US-C5 调整召回参数
作为 RAG 调试者，我希望调整 Top K、最低相关度和通道权重，以便适配不同知识 类型。
验收：
- Top K、阈值、候选倍数和权重具有明确范围和默认值
- 至少一个召回通道权重大于 0
- 图谱关闭时图谱权重不可生效并说明原因
- 设置持久化到当前知识库，不影响其他知识库
- 非法输入不能跨 IPC
5. Epic D：真实索引状态
US-D1 查看分阶段状态
作为知识库维护者，我希望分别看到解析、全文、向量和图谱状态，以便准确判断 文档能否使用。
验收：
- 文档不再用单个“ready”代表所有索引完成
- 全文完成但向量失败时，明确显示“全文可用、向量失败”
- 向量未启用与向量失败是不同状态
- 图谱按需、未启用和失败是不同状态
- 汇总显示全文可用数、向量完成数和失败数
US-D2 修复失败文档
作为知识库维护者，我希望单独重建失败文档，而不是重新同步整个目录。
验收：
- 文档行提供“重建文档”
- 重建重新执行解析、分块、全文、向量和图谱
- 失败时保留上一版可用索引
- 完成后更新任务和状态
- 原文件不存在时保留可重试错误
US-D3 修改设置后重建
作为知识库维护者，我希望分块设置修改后明确提示需要重建，以免误以为旧文档 已经使用新设置。
验收：
- 保存关键分块设置后显示“等待重建”
- 设置保存本身不删除现有索引
- 用户可选择全库重建
- 全库重建可取消
- 已成功替换的文档继续可用
6. Epic E：高级分块
US-E1 固定分块
作为知识库维护者，我希望配置目标长度和重叠，以便处理日志、代码或简单文本。
验收：
- 目标长度为 400 至 8,000 字符
- 重叠不超过目标长度的 40%
- 优先在自然边界切分
- 每个块保留来源 section、定位和 ordinal
- 旧知识库迁移后不自动改变已有分块
US-E2 结构分块
作为知识库维护者，我希望分块尽量保持标题和段落结构，以便命中片段保留语义。
验收：
- 优先保持解析 section
- Markdown 标题能够成为分块 heading
- 标题随子段落进入索引元数据
- 超长 section 仍按有界规则继续切分
- 空标题和空段落不创建分块
US-E3 父子分块
作为 RAG 调试者，我希望小块负责准确召回、大块负责完整上下文，以便兼顾精度 和完整性。
验收：
- 父块和子块具有稳定关系
- 父块不直接进入 FTS/CJK/向量候选
- 子块命中后可返回父块上下文
- 引用突出实际命中的子块
- 父块输出仍受上下文预算和截断限制
7. Epic F：重排与上下文
US-F1 本地重排
作为本地与内网用户，我希望在不调用外部模型的情况下改善候选排序。
验收：
- 本地重排默认关闭并可按知识库开启
- 使用 RRF、词覆盖、短语、标题、路径、向量和重复惩罚等确定性特征
- 结果相关度归一化到 0 至 1
- 检索测试显示重排前后排名
- 关闭时保持原 RRF 行为
- UI 不把本地算法描述为 AI Rerank 模型
US-F1.1 学习型重排
作为需要更高排序质量的用户，我希望可选择兼容的学习型重排模型，并在服务 不可用时继续获得本地结果。
验收：
- 模式明确区分关闭、本地规则和学习型重排
- Main 最多发送 100 个候选，每个候选不超过 8,000 字符
- API Key 仅通过环境变量或 Main 加密存储使用，不进入 Renderer
- 超时、无效响应和服务错误回退本地重排，并显示脱敏诊断
- 用户取消和应用关闭必须终止请求，不得按普通降级吞掉
US-F2 相邻分块合并
作为普通知识使用者，我希望命中片段包含必要的上下文，而不是孤立半句话。
验收：
- 可配置向前、向后相邻 0 至 2 个块
- 只合并同文档且 ordinal 连续的启用分块
- 同一块不会重复输出
- 每个原命中仍保留引用定位
- 合并结果遵守上下文预算
US-F3 上下文预算
作为普通知识使用者，我希望低质量内容不会挤占模型上下文。
验收：
- 按最终相关度从高到低选择上下文
- 已选择的高排名证据不会被低排名证据替换
- 超预算时明确标记截断
- 预算范围为 2,000 至 48,000 字符
- IPC 和 Runtime 输入继续受总大小限制
US-F4 上下文索引
作为知识库维护者，我希望检索可以利用文档结构，而引用仍忠于原文。
验收：
- 可按知识库启用上下文索引，并在修改后提示显式重建
- 标题、标题层级、页码和块类型使用有界确定性前缀进入 FTS、CJK 和向量文本
- 原始分块、引用、模型上下文和图谱证据不显示生成前缀
- FTS、CJK、向量和内容校验使用同一规范索引文本
7.1 Epic F+：受控本体与检索评估
US-F5 每库受控本体
作为知识库维护者，我希望控制可用实体和关系类型，以便图谱保持一致。
验收：
- 每库保存实体类型、关系类型、双语名称、别名和可选端点约束
- 手工编辑使用受控选择器并拒绝未知类型或不兼容端点
- 图谱抽取按类型解析实体，保留人工锁定字段和跨类型边界
- 证据保存原文偏移、置信度、抽取来源和有界 provenance
- 本体或启用中的图谱策略变化标记需要重建
US-F6 离线检索评估
作为 RAG 维护者，我希望用固定双语样本检测召回回归，而不读取用户数据或调用 网络服务。
验收：
npm run eval:retrieval使用临时 SQLite 和确定性内存 Provider- 报告 Recall@5/10、MRR@10、nDCG@10、上下文精度/召回、无答案误报和延迟
- 提供词法、确定性向量、混合及本地重排消融
- 质量门槛按中英文分别检查，报告不包含原文、查询、端点、模型名或凭据
- 可选报告路径仅允许工作区内非符号链接文件
8. Epic G：分块维护
US-G1 查看分块
作为知识库维护者，我希望查看某篇文档实际生成的分块，以便确认解析和切分质量。
验收：
- 文档行提供“查看分块”
- 列表显示序号、角色、标题、定位、字符数和启用状态
- 支持有界分页和文档内搜索
- 可查看完整单块内容
- 父子块关系可辨认但不只靠颜色表达
US-G2 编辑分块
作为知识库维护者，我希望修正错误文本，以便问答使用正确内容。
验收：
- 编辑限制单块最大字符数
- 保存后同步更新全文和 CJK 索引
- 旧向量立即失效并触发当前文档重建
- 编辑块标记为人工修改
- UI 说明来源再次同步可能覆盖修改
- 保存失败保留用户草稿
US-G3 启停分块
作为知识库维护者，我希望暂时停用有害或无关片段，而不永久删除它。
验收：
- 使用共享 Switch 和
role="switch" - 停用块不参与任何召回通道
- 重新启用后恢复全文索引，并按需重建向量
- 状态更新失败时保留最后确认状态
- 引用已停用块时显示引用已失效
US-G4 删除分块
作为知识库维护者，我希望删除确定无用的分块，以便避免错误召回。
验收：
- 删除前说明来源同步可能重新创建该块
- 删除使用具体动作和对象文案
- 删除联动清理全文、CJK、向量和图谱证据
- 删除最后一个可检索块后文档显示“无可检索内容”
- 不删除原始文件
9. Epic H：引用和来源
US-H1 查看完整引用上下文
作为普通知识使用者，我希望从回答引用查看完整上下文，以便验证回答是否忠于 资料。
验收：
- 引用携带稳定
libraryId、documentId和chunkId - 点击引用由 Main 重新校验对象归属
- 展示命中分块、相邻块或父块
- 展示知识库、文档、来源和定位
- 对已删除对象显示明确失效状态
US-H2 打开原始来源
作为普通知识使用者，我希望从引用打开原文件或网页，以便继续阅读。
验收：
- 本地来源只通过数据库保存的普通文件路径打开
- 网页来源只允许数据库保存的 HTTP(S) URL
- Renderer 不能传入任意待打开路径或 URL
- 文件已移动时显示可恢复错误
- 不能跨平台精确跳页时仍显示原定位信息
US-H3 引用与回答一致
作为普通知识使用者，我希望引用列表只显示本次实际检索到的内容。
验收：
- Main 只收集本次 capability token 产生的引用
- 预检索和模型后续检索引用去重
- 引用顺序遵循最终相关度和首次使用顺序
- 单消息引用数和序列化大小有明确上限
- 不把未检索文档显示为来源
10. Epic I：迁移、安全和兼容
US-I1 无损迁移
作为现有用户，我希望升级后保留知识库、来源、分块、图谱和向量。
验收：
- SQLite 迁移在事务中执行
- 旧分块默认启用并视为 standalone
- 旧知识库获得兼容检索和分块设置
- CJK 索引回填失败时回滚迁移
- 升级不自动删除或重建原有内容
US-I2 安全边界
作为本地用户，我希望新增功能不扩大 Renderer 和子 Runtime 权限。
验收：
- 新增 IPC 全部校验可信 sender 和共享 Schema
- Main 重新检查知识库、文档、分块和来源归属
- Renderer 不访问 SQLite、文件系统、Electron shell 或凭据
- 知识内容标记为不可信证据
- Ask 不获得写工具
- 错误和日志不包含密钥、授权头和未限制正文
US-I3 取消和关闭
作为用户，我希望大库检索或重建可以停止，不留下损坏索引。
验收：
- 长向量扫描、单文档重建和全库重建响应 AbortSignal
- 应用关闭停止新批次并等待有界清理
- 文档级替换成功前继续使用上一版索引
- 取消状态区别于失败
- 取消不会删除原文件或用户维护的其他文档
11. 优先级映射
第一阶段
- US-A1、US-A2、US-A3
- US-B1、US-B2、US-B3、US-B4
- US-C1、US-C2、US-C3、US-C4、US-C5
- US-D1
- US-H1、US-H2、US-H3
- US-I1、US-I2
第二阶段
- US-D2、US-D3
- US-E1、US-E2、US-E3
- US-F1、US-F2、US-F3
- US-G1、US-G2、US-G3、US-G4
- US-I3
12. Definition of Done
每个 User Story 只有在以下条件全部满足时才完成：
- Main、Preload、Renderer 和共享契约保持明确边界。
- 行为有聚焦的单元、IPC 或组件回归测试。
- 中英文文案同时更新。
- 浅色、深色、键盘和窄窗口核心流程可用。
- 失败、取消、空结果和降级状态均有独立表现。
- 不覆盖用户现有未提交或未跟踪文件。
npm test、npm run typecheck、npm run lint和npm run build全部通过。