524 lines
17 KiB
Markdown
524 lines
17 KiB
Markdown
# 知识库检索与分块增强 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`
|
|
全部通过。
|