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