docs: organize product documentation by domain
Replace the flat features directory with document-type and functional-domain navigation, update repository-wide links, and add a top-level documentation index. Define Task, Conversation, Job, Subjob, Run, Scheduled Task, Goal Task, and Task Center in one canonical document set. Keep Smart Heartbeat ownership separate and leave future partitioned memory explicitly undesigned.
This commit is contained in:
mesalogo
@@ -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