# 外部知识库 User Stories

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 设计稿 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 关联 PRD | [外部知识库接入 PRD](./external-knowledge-prd.md) |

## 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 保存新目标前必须重新测试