docs: specify knowledge retrieval enhancements
This commit is contained in:
lofyer
@@ -0,0 +1,523 @@
|
||||
# 知识库检索与分块增强 User Stories
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 实施中 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 关联 PRD | [知识库检索与分块增强 PRD](knowledge-rag-enhancement-prd.md) |
|
||||
|
||||
## 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 只有在以下条件全部满足时才完成：
|
||||
|
||||
1. Main、Preload、Renderer 和共享契约保持明确边界。
|
||||
2. 行为有聚焦的单元、IPC 或组件回归测试。
|
||||
3. 中英文文案同时更新。
|
||||
4. 浅色、深色、键盘和窄窗口核心流程可用。
|
||||
5. 失败、取消、空结果和降级状态均有独立表现。
|
||||
6. 不覆盖用户现有未提交或未跟踪文件。
|
||||
7. `npm test`、`npm run typecheck`、`npm run lint` 和 `npm run build`
|
||||
全部通过。
|
||||
Reference in New Issue
Block a user