# 外部知识库接入 PRD

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 设计稿 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 适用产品 | GoodBuddy 桌面端 |
| 关联逻辑 | [外部知识库逻辑设计](./external-knowledge-logic-design.md) |
| 关联界面 | [外部知识库 UI 设计](./external-knowledge-ui-design.md) |
| 技术设计 | [外部知识库技术设计](./external-knowledge-technical-design.md) |

## 1. 背景

不少企业已经在内网部署 Dify、FastGPT 或 RAGFlow，并在其中维护制度、产品、研发
和客服知识。继续要求用户把相同资料导入 GoodBuddy，会产生重复存储、版本分叉和
额外维护成本。

GoodBuddy 需要把这些已有知识库加入当前知识库列表和聊天检索范围。外部系统只
承担知识存储与检索，问题理解、上下文组织、模型回答、Agent 和工具执行仍由
GoodBuddy 负责。

## 2. 产品决策

1. 外部知识库属于现有“知识库”功能，不新增一级页面，也不放入全局设置中心。
2. 知识库页面标题区增加“管理外部实例”；现有“新建知识库”向导增加知识库类型。
3. 一个外部实例代表一个 Provider 服务地址和一组凭据，可绑定多个远端知识库。
4. 一个外部知识库绑定在 GoodBuddy 中仍是一个 `KnowledgeBase`，可以进入现有聊天
   范围、每次先检索、模型按需检索和检索测试流程。
5. 外部知识库保持远端检索，不批量同步或本地索引远端文档、分块、向量和图谱，也不
   显示“已同步”。实际进入回答的有界片段和引用随会话保存在本机，并遵循会话删除规则。
6. Dify、FastGPT 和 RAGFlow 只使用知识库列表、详情和检索接口。App、Chat、
   Assistant、Workflow 和 Agent API 均不接入。
7. 用户点击“添加”只创建本地绑定，不在外部实例中创建知识库；移除绑定也不删除
   远端知识库。
8. 通用配置只包含跨 Provider 语义一致的选项。检索算法、阈值、重排和图谱开关
   由 Provider 配置承担。
9. Provider 专属字段由 GoodBuddy 内置适配器定义。外部服务器不能下发任意表单、
   脚本或字段 Schema。
10. API Key 在用户输入表单和受限 IPC 中短暂存在，由 Main 进程加密保存并用于请求；
    保存后不回传 Renderer，也不进入 Runtime、日志、普通元数据和检索引用。

## 3. 目标

### 3.1 用户目标

- 在知识库页面配置企业现有的 Dify、FastGPT 或 RAGFlow 实例。
- 新建知识库时选择 Provider、实例和远端知识库，不手工复制资料。
- 在同一知识库列表和聊天选择器中使用本地与外部知识库。
- 按 Provider 能力调整检索参数，例如 RAGFlow 图谱检索。
- 明确看到查询发送到哪个实例、检索是否成功以及引用来自哪里。
- 连接失效后能更新凭据、重试或更换远端知识库，不丢失其他知识库配置。

### 3.2 产品目标

- 保持现有知识库 ID 作为聊天和 Runtime 的统一授权单位。
- 让三种 Provider 的结果进入同一有界证据与引用契约。
- 保留每种 Provider 的有效检索能力，不用最低公共字段覆盖全部差异。
- 将实例认证与知识库绑定分离，使一个实例可以服务多个绑定。
- 对 Provider 版本差异、列表权限关闭和部分检索失败提供可诊断状态。

## 4. 非目标

本功能不包含：

- 调用 Dify App、FastGPT 应用、RAGFlow Chat 或任何外部 Agent。
- 使用外部系统生成最终回答或维护外部会话。
- 在外部实例中创建、编辑、删除知识库、文档或分块。
- 向外部实例上传文件、网页、剪贴板、完整会话或本地知识库内容。
- 批量同步或本地索引外部文档、分块、Embedding、图谱或模型配置。回答实际引用的
  有界片段仍会随会话保存在本机。
- 跨实例复制、迁移或统一管理外部知识内容。
- 企业 SSO、组织级凭据下发、文档级 ACL 映射或 ShareServer 管理策略。
- 自定义脚本适配器和任意 HTTP 请求模板。兼容检索 API 需要独立设计。
- 把不同 Provider 的原始分数解释成可直接比较的统一质量分数。

## 5. 核心对象

| 对象 | 定义 | 用户可执行操作 |
| --- | --- | --- |
| 外部实例 | Provider、服务地址、凭据和已探测能力 | 添加、测试、编辑、停用、删除 |
| 外部知识库目录项 | 实例列表接口返回的远端知识库摘要 | 刷新、选择 |
| 外部知识库绑定 | GoodBuddy 知识库与远端知识库的只读关联 | 添加、改名、配置、测试、移除 |
| Provider 配置 | 适配器支持的检索参数 | 查看、修改、恢复默认 |
| 标准化检索结果 | Provider 结果转换后的片段、来源和诊断 | 查看、引用、提供给 Runtime |

## 6. 主要流程

### 6.1 管理外部实例

1. 用户在知识库页面点击“管理外部实例”。
2. 页面列出实例名称、Provider、服务地址、状态和已绑定知识库数量。
3. 用户添加实例，填写名称、Provider、服务地址和 API Key。
4. “测试连接”分别验证服务可达、认证、知识库列表和检索能力。
5. 用户保存后，API Key 被加密保存，列表只显示凭据已配置。

列表接口不可用但已知远端知识库 ID 可检索时，实例可以保存为“需手工指定知识库”。
服务不可达或认证失败时不得保存为可用实例；用户可以保留表单并修正。

### 6.2 添加外部知识库

1. 用户点击现有“新建知识库”。
2. 在“知识库类型”中选择“本地”、Dify、FastGPT 或 RAGFlow。
3. 选择外部类型后，左侧选择同 Provider 的外部实例。
4. GoodBuddy 自动读取远端知识库列表，并填入可搜索下拉框。
5. 列表权限不可用时，用户可以手工填写远端知识库 ID。
6. 用户选择一个远端知识库，填写 GoodBuddy 显示名称。
7. 右侧展示通用配置和当前 Provider 的专属配置。
8. 用户填写测试查询并执行一次有界检索；请求成功后创建本地绑定，零结果不算失败。

添加完成后沿用现有知识库规则，把新绑定加入当前聊天选择，但不会重新启用用户此前
取消的其他知识库。

### 6.3 使用外部知识库

外部绑定出现在现有知识库列表和聊天知识范围中，持续显示 Provider 与实例名称。
检索请求只发送本次查询文本和该绑定已保存的检索配置。返回片段经过 Main 校验、
截断和标准化后，才作为不可信证据提供给 Runtime。

一次请求选择多个知识库时，本地与外部检索可以并行。单个外部知识库失败不扩大
检索范围，也不切换其他实例；其他知识库成功时可继续回答，并显示部分失败。

### 6.4 编辑和移除

- 修改显示名称只影响 GoodBuddy 本地名称。
- 修改 Provider 配置只影响后续检索，不写回远端知识库。
- 更换远端知识库属于重新绑定，保存前必须重新测试。
- 删除外部实例前必须处理其所有绑定：取消，或明确移除这些本地绑定。
- 移除绑定只删除 GoodBuddy 中的绑定和检索配置，不调用远端删除接口。已经保存在历史
  会话中的引用继续可读，但不再提供依赖当前实例的刷新操作。

## 7. 功能需求

### EK-FR-01 知识库页面入口

知识库页面必须同时提供“管理外部实例”和“新建知识库”。外部实例管理不得迁移到
全局设置中心或创建新的一级导航。

### EK-FR-02 实例配置

实例必须包含唯一 ID、显示名称、Provider、规范化服务地址、凭据状态、启停状态、
最近测试结果和适配器能力快照。用户可以使用 `keep`、`replace`、`clear` 语义更新凭据。

### EK-FR-03 分项连接测试

连接测试必须区分服务可达、认证、列表读取和测试检索。新增实例尚未选择知识库时，
测试检索显示“绑定知识库时验证”，不能伪装成已通过。测试错误应包含可处理原因，
不得返回凭据、Authorization、完整响应正文或内部堆栈。

### EK-FR-04 远端目录读取

选择实例后自动读取有界、可分页的远端知识库列表。列表支持加载、刷新、搜索、空结果、
权限不足和失败状态，且异步旧响应不得覆盖当前实例结果。

### EK-FR-05 手工指定远端 ID

列表接口不受支持或没有权限时，允许手工填写远端知识库 ID 和显示名称。保存前必须通过
该 ID 的详情或检索验证；不能只验证字符串非空。

### EK-FR-06 知识库类型

新建向导必须提供“本地”、Dify、FastGPT、RAGFlow 四种类型。本地类型保持现有创建、
存储模式、图谱和导入行为；外部类型不得显示本地分块、导入或索引设置。

### EK-FR-07 两栏配置

外部类型的创建向导在常规宽度使用左右两栏。左侧负责 Provider、实例、远端知识库和
显示名称；右侧负责通用配置与 Provider 专属配置。窄窗口按来源、通用配置、专属配置
顺序堆叠。

### EK-FR-08 通用配置

通用配置至少包含最终返回片段数、请求超时和单片段最大字符数。数值必须有固定范围，
由 Main 再次校验。Provider 的 Top K、Token 预算或 Page Size 不得冒充同一字段。

### EK-FR-09 Provider 专属配置

Provider 配置使用受版本控制的判别联合。界面只展示当前适配器和已确认实例版本支持的字段；
不支持的已保存字段必须明确显示为失效配置并阻止静默提交。

### EK-FR-10 统一知识库列表

外部绑定与本地知识库出现在同一列表，但必须显示 Provider、实例和“远端检索”状态。
外部绑定不得显示本地文档数、同步、分块、向量覆盖率或本地图谱状态。

### EK-FR-11 统一检索范围

现有聊天知识范围、多选上限、`auto` 和 `always` 模式继续以 GoodBuddy 知识库 ID 工作。
Runtime 只能获得标准化后的有界证据，不能获得实例地址、API Key 或 Provider 原始响应。

### EK-FR-12 引用来源

每条外部结果必须保留 Provider、实例 ID、远端知识库 ID、文档名称和片段。远端文档 ID、
远端片段 ID、页码、URL、分数及其他定位只在 Provider 实际返回时保存，不得补造。

### EK-FR-13 检索测试

现有检索测试入口支持外部绑定。页面显示生效配置、总耗时、Provider 耗时、返回数量、
截断状态和脱敏错误。外部测试不创建聊天、调用 GoodBuddy LLM 或修改远端内容。

### EK-FR-14 故障隔离

认证失败、超时、限流、目标删除、版本不兼容和响应无效必须分别报告。多知识库检索中，
单项失败不得改写为零结果，也不得阻止已成功证据进入回答。

### EK-FR-15 生命周期边界

删除实例、移除绑定、清除凭据和更换远端目标必须经过明确确认。任何操作都不得调用
Provider 的远端创建、更新、上传或删除接口。

### EK-FR-16 网络与数据说明

界面必须说明查询会发送到所选实例，并列出不会发送的内容。请求遵循用户配置的服务地址
和当前内网兼容模式，不自动切换地址、Provider 或公共云端点。HTTP 或放宽证书校验会
传输 API Key，测试和保存实例前必须显示风险并取得针对当前地址的明确确认。

## 8. Provider 初始范围

| Provider | 目录能力 | 检索能力 | 首批专属配置 |
| --- | --- | --- | --- |
| Dify | 知识库列表与详情 | Dataset Retrieve | 使用知识库默认配置，或完整覆盖检索方式、Top K、Score 阈值及 Rerank 模式 |
| FastGPT | 知识库层级列表与详情 | Dataset Search Test | 搜索模式、Token 上限、相似度、Rerank |
| RAGFlow | Dataset 列表与详情 | Retrieval | 相似度、向量权重、KNN Top K、Rerank、图谱检索、Knowledge Compilation |

“首批专属配置”表示适配器允许表达的字段，不保证每个实例版本都支持。具体显隐由能力
探测和[逻辑设计](./external-knowledge-logic-design.md)共同决定。

## 9. 产品验收

1. 用户可以在知识库页面完成三种 Provider 的实例添加、连接测试、编辑和删除。
2. 每种 Provider 至少通过一个真实自部署实例完成列表读取、绑定和检索。
3. 列表权限关闭时，可以通过手工 ID 添加并验证一个可检索知识库。
4. 本地与外部知识库可以同时进入一次聊天检索，引用来源可区分。
5. RAGFlow 支持时可以开启图谱检索；不支持时不发送该字段。
6. 外部知识库详情不出现本地导入、同步、分块和索引操作。
7. 删除绑定或实例不会改变远端知识库和文档。
8. 保存完成后的 Renderer 状态、Runtime、SQLite 普通元数据、日志和错误中均找不到明文
   API Key。
9. 超时、401/403、404、429、5xx 和响应格式错误都有独立测试并显示准确状态。
10. 中断、切换实例或关闭向导后，过期列表与测试响应不会写入当前表单。
11. FastGPT 页面说明检索会记录远端 API 使用情况，并可能产生 Embedding 或 Rerank 用量。
12. HTTP 或放宽证书校验的实例未经明确确认不能保存或发送 API Key。

## 10. 外部资料

以下链接用于核对初始适配范围，实施时仍须用受支持版本的真实实例和响应 fixture 验证：

- [Dify Knowledge API](https://docs.dify.ai/en/guides/knowledge-base/knowledge-and-documents-maintenance/maintain-dataset-via-api)
- [Dify Retrieve Chunks](https://docs.dify.ai/en/api-reference/knowledge-bases/retrieve-chunks-from-a-knowledge-base-test-retrieval)
- [FastGPT 知识库接口](https://doc.fastgpt.io/zh-CN/openapi/dataset)
- [RAGFlow HTTP API](https://ragflow.io/docs/dev/http_api_reference)
- [RAGFlow Release Notes](https://ragflow.io/docs/dev/release_notes)