7.7 KiB
7.7 KiB
外部知识库 User Stories
文档信息
| 项目 | 内容 |
|---|---|
| 状态 | 设计稿 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 关联 PRD | 外部知识库接入 PRD |
1. 角色
- 知识库使用者：在聊天中选择已经添加的本地或外部知识库并查看引用。
- 实例维护者：持有外部知识库 API Key，负责配置实例、选择远端知识库和处理失效连接。
- RAG 调试者：需要调整 Provider 参数并直接验证检索结果。
2. 实例管理
EK-US-A1 添加外部实例
作为实例维护者，我希望在知识库页面保存一个外部实例，以便后续绑定其中的多个知识库。
验收：
- Given 用户打开“管理外部实例”并选择 Dify、FastGPT 或 RAGFlow
- When 用户填写名称、服务地址和 API Key，并执行连接测试
- Then 页面分别显示服务、认证、目录和检索检查结果
- And 保存后只显示“凭据已配置”，不回显 API Key
- And 新实例可被同 Provider 的新建知识库向导选择
- And 使用 HTTP 或放宽证书校验时，保存前明确提示 API Key 的传输风险
EK-US-A2 修复失效凭据
作为实例维护者，我希望替换认证失效的 API Key，同时保留已有知识库绑定。
验收：
- Given 实例因认证失败处于“认证失效”状态
- When 用户选择“替换凭据”、测试并保存
- Then 所有绑定继续引用同一实例 ID
- And 旧密钥不再使用
- And 用户没有输入新密钥时可以取消且不清除旧密钥
EK-US-A3 删除仍被使用的实例
作为实例维护者，我希望删除实例前看到受影响的知识库，以免留下无法解释的绑定。
验收：
- Given 实例仍被一个或多个外部知识库绑定引用
- When 用户点击“删除实例”
- Then 确认界面列出受影响数量和名称
- And 用户可以取消，或明确同时移除本地绑定
- And 确认后不向外部实例发送删除请求
3. 添加知识库
EK-US-B1 从远端列表添加
作为实例维护者，我希望选择 Provider 和实例后自动看到远端知识库，以便避免手工复制 ID。
验收：
- Given 至少存在一个可用的对应 Provider 实例
- When 用户在“新建知识库”中选择外部类型和实例
- Then GoodBuddy 自动读取有界知识库列表
- And 下拉框支持按名称搜索与刷新
- And 目录只显示当前凭据可见的知识库，不推断隐藏对象
- And 切换实例后旧实例的异步响应不会覆盖新列表
EK-US-B2 手工填写远端 ID
作为实例维护者，我希望列表接口受限时仍可通过远端 ID 添加已有知识库。
验收：
- Given 连接测试表明认证和检索可用，但目录读取无权限或不受支持
- When 用户进入手工模式并填写远端知识库 ID
- Then GoodBuddy 使用详情或测试检索验证该目标
- And 验证失败时保留输入并显示原因
- And 未经真实验证不能完成添加
EK-US-B3 配置 RAGFlow 图谱检索
作为 RAG 调试者，我希望在添加 RAGFlow 知识库时设置图谱检索，以便使用远端已经构建的图谱内容。
验收：
- Given 适配器确认实例检索接口支持
use_kg - When 用户选择一个具备相关能力的 RAGFlow 知识库
- Then 右侧显示“图谱检索”开关并说明它只影响检索
- And 开启后测试请求携带该选项
- And 只有远端知识库存在已构建图谱的证据时才允许开启
- And 页面不把该开关描述为构建或更新远端图谱
- And 能力不明确时该开关禁用并说明原因
EK-US-B4 保持本地创建流程
作为本地知识库用户，我希望新增外部类型后仍能按原流程创建本地知识库。
验收：
- Given 用户在新建向导中选择“本地”
- When 用户填写名称、存储模式和图谱设置
- Then 表单字段、默认值和创建结果与现有行为一致
- And 外部实例、远端 ID 和 Provider 配置不出现
4. 检索和引用
EK-US-C1 在聊天中选择外部知识库
作为知识库使用者，我希望外部知识库出现在现有知识范围选择器中，以便与本地知识库一起使用。
验收：
- Given 外部知识库绑定处于可检索状态
- When 用户打开聊天知识范围
- Then 它与本地知识库出现在同一选择器中
- And 条目持续显示 Provider 和实例名称
- And 选择结果仍保存 GoodBuddy 知识库 ID
- And 新添加的绑定进入当前聊天选择，但不重新启用其他已取消知识库
EK-US-C2 只发送检索查询
作为知识库使用者，我希望清楚知道哪些数据会发送到企业知识库。
验收：
- Given 本次请求选择了外部知识库
- When GoodBuddy 执行检索
- Then 只发送本次检索查询、远端知识库 ID 和已保存检索参数
- And 不发送完整会话、本地附件、其他知识库内容、系统提示或模型凭据
- And 活动状态显示目标 Provider 和实例
EK-US-C3 查看外部引用
作为知识库使用者，我希望回答中的引用标明外部来源，以便回到企业知识系统核验。
验收：
- Given Provider 返回文档名、片段 ID、内容和分数
- When GoodBuddy 展示引用
- Then 引用显示 Provider、实例、知识库和文档名称
- And 详情只显示 Provider 实际返回且通过校验的定位信息
- And 缺失页码、链接或分数时不生成替代值
EK-US-C4 多知识库部分失败
作为知识库使用者，我希望一个外部实例暂时失败时仍能使用其他成功结果。
验收：
- Given 本次选择了本地知识库和两个外部知识库
- When 一个外部请求超时，其他请求成功
- Then 成功证据继续进入回答
- And 页面显示一个知识库检索失败及其原因
- And 超时不显示为“未找到相关内容”
- And GoodBuddy 不自动改用同 Provider 的其他实例
5. 配置与诊断
EK-US-D1 调整 Provider 配置
作为 RAG 调试者，我希望只看到当前 Provider 支持的参数，以便理解设置会怎样影响远端检索。
验收：
- Given 用户编辑一个外部知识库绑定
- When 页面读取实例能力和已保存配置
- Then 通用配置与 Provider 专属配置分区显示
- And 每个字段显示范围、默认值和作用
- And 不受支持的字段不会被静默发送
- And 恢复默认只恢复当前绑定的 Provider 配置
EK-US-D2 运行检索测试
作为 RAG 调试者，我希望在知识库页面直接测试外部检索，不经过聊天模型。
验收：
- Given 当前选中一个外部知识库
- When 用户输入查询并点击“测试检索”
- Then 页面显示 Provider 耗时、返回数量、片段、来源和截断状态
- And 测试不创建聊天消息、不调用 GoodBuddy LLM、不修改远端内容
- And 远端原始响应和凭据不进入界面或日志
- And FastGPT 测试明确提示远端可能记录 API 使用并产生检索或重排用量
EK-US-D3 Provider 版本变化
作为实例维护者，我希望升级外部系统后看到配置是否仍受支持。
验收：
- Given 最近一次能力探测与已保存快照不同
- When 用户测试实例或打开绑定设置
- Then 页面指出新增、失效或行为变化的配置
- And 失效配置不会静默删除或继续发送
- And 用户确认有效配置后才更新绑定
EK-US-D4 远端知识库被删除
作为实例维护者，我希望远端目标不存在时看到准确状态并重新绑定。
验收：
- Given Provider 返回目标不存在
- When 用户打开知识库或执行检索
- Then 绑定状态显示“远端知识库不存在”
- And 聊天选择器不把它显示为可用
- And 用户可以刷新目录并选择新的远端知识库
- And 保存新目标前必须重新测试