goodbuddy/docs/features/knowledge-base/external-knowledge-ui-design.md

外部知识库 UI 设计

文档信息

项目	内容
状态	设计稿
版本	0.1
日期	2026-09-03
产品需求	外部知识库接入 PRD
行为规则	外部知识库逻辑设计
全局规范	GoodBuddy UI 设计系统

1. 信息架构

外部知识库不增加左侧主导航和知识库一级页签。现有知识库页面结构保持：

知识库
├─ 页面标题区
│  ├─ 管理外部实例
│  └─ 新建知识库
├─ 知识库列表
└─ 当前知识库详情

“管理外部实例”管理可复用连接；“新建知识库”负责创建本地知识库或添加一个远端绑定。

2. 页面标题区

常规宽度：

知识库                              [管理外部实例] [新建知识库]
导入、检索并维护本地和企业现有知识
范围：全局

• “新建知识库”保持主按钮。
• “管理外部实例”是带服务器图标的次按钮。
• 沿用知识库页面的全局 ScopeBadge，创建和管理外部连接时持续可见。
• 按钮使用文字和图标，不增加只含缩写的厂商快捷入口。
• 窄窗口下两个按钮换到标题下方，保持同一行；空间不足时各占一半宽度。

对应：EK-FR-01。

3. 知识库列表

本地和外部知识库保留在同一主列表。条目采用现有列表密度，不增加卡片墙。

研发规范
RAGFlow · 研发知识平台 · 远端可检索

产品资料
本地 · 12 个来源 · 全文与向量可用

3.1 外部条目字段

• GoodBuddy 显示名称。
• Provider 图标或文字徽标。
• 外部实例名称。
• “远端可检索”、认证失效、目标不存在等准确状态。
• 最近一次成功检索时间；从未检索时显示“尚未检索”。

外部条目不显示来源数量、同步进度、向量覆盖率、本地图谱或导入失败数。

3.2 列表筛选

现有搜索同时匹配 GoodBuddy 名称、远端名称、Provider 和实例名称。来源筛选使用菜单：

全部来源
本地
Dify
FastGPT
RAGFlow

筛选不是新的页面页签。

4. 管理外部实例

点击“管理外部实例”打开大尺寸 Modal。Modal 使用标题、可滚动内容和固定操作区，遵循 全局焦点陷阱、Escape、背景隔离和焦点恢复规则。

┌──────────────────────────────────────────────────────────────┐
│ 外部实例                                      [添加实例] [×] │
│ 管理 Dify、FastGPT 和 RAGFlow 的连接                         │
├──────────────────────────────────────────────────────────────┤
│ 名称            Provider   服务地址             状态    操作 │
│ 研发知识平台    RAGFlow    ragflow.example      正常     ⋯   │
│ 客服知识平台    FastGPT    fastgpt.example      认证失效 ⋯   │
└──────────────────────────────────────────────────────────────┘

4.1 实例行

显示：

• 名称、Provider、脱敏后的主机名、状态。
• 已绑定知识库数量。
• 最近测试时间。
• 行尾菜单：测试连接、编辑、停用或启用、删除。

服务地址可以显示 scheme、host 和非默认端口，不显示路径中的敏感信息、查询或凭据。

4.2 空状态

尚未配置外部实例
添加企业现有的 Dify、FastGPT 或 RAGFlow 服务。
[添加实例]

筛选无结果和加载失败使用不同 EmptyState 变体。

5. 添加和编辑实例

实例表单在管理 Modal 内切换为编辑面板，不叠加第二层 Modal。

添加外部实例

实例名称        [研发知识平台                    ]
Provider        [RAGFlow                       ▾]
服务地址        [https://ragflow.example        ]
认证方式        API Key
API Key         [••••••••••••••••               ]
凭据状态        尚未保存

连接测试
服务连接        未测试
身份认证        未测试
知识库列表      未测试
检索接口        绑定知识库时验证

                              [取消] [测试连接] [保存实例]

5.1 字段行为

• Provider 使用原生 Select；编辑已被绑定的实例时不可切换 Provider。
• 服务地址只接受完整 HTTP(S) 地址。字段下方说明其受全局内网兼容模式影响。
• API Key 使用密码输入和显示/隐藏图标。明文会在当前表单和保存 IPC 中短暂存在；编辑时 留空表示保留，不使用占位假密钥。
• 已保存凭据旁提供“替换凭据”和“清除凭据”，清除属于需要确认的操作。
• 地址使用 HTTP，或连接测试依赖放宽证书校验时，在测试和保存操作旁持续显示传输风险。 用户必须针对当前地址确认后才能保存；地址变化会清除该确认。
• “测试连接”不保存草稿；测试期间按钮显示进度并提供取消。
• 保存成功进入应用通知，Modal 返回实例列表并聚焦对应行。

5.2 测试结果

分项状态使用图标、文字和说明，不只依靠颜色：

服务连接       通过       183 ms
身份认证       通过
知识库列表     受限       当前凭据不能读取列表，可手工填写知识库 ID
检索接口       待验证     添加知识库时执行

长错误折叠显示，正文经过脱敏。失败后保留全部草稿和 API Key 输入。

FastGPT 实例额外显示：检索会计入该实例的 API 使用记录，并可能产生 Embedding 或 Rerank 用量。

6. 新建知识库向导

扩展现有页面内 CreateLibraryWizard，不改为新的全屏页面或 Modal。

6.1 类型选择

表单第一项使用单选卡片或共享 SegmentedControl：

知识库类型
[本地] [Dify] [FastGPT] [RAGFlow]

只有选择本地时显示现有存储模式、图谱和本地说明。外部类型选中后显示两栏配置。

6.2 外部类型两栏布局

┌──────────────────────────────┬──────────────────────────────┐
│ 知识库来源                   │ 检索配置                     │
│                              │                              │
│ Provider     RAGFlow         │ 通用配置                     │
│ 外部实例     [研发平台    ▾] │ 返回片段数          [ 6 ]   │
│ 远端知识库   [研发规范    ▾] │ 请求超时            [15 秒] │
│                         [↻]  │ 单片段上限          [4000]  │
│ [手工填写知识库 ID]          │                              │
│                              │ RAGFlow 配置                 │
│ 显示名称     [研发规范      ]│ 相似度阈值          [0.20]  │
│ 远端名称     研发规范        │ 向量相似度权重      [0.30]  │
│ 远端 ID      7f31…c902       │ KNN Top K           [1024]  │
│ 测试查询     [部署网络要求  ]│ 图谱检索             [开关] │
│                              │ Knowledge Compilation [开关]│
├──────────────────────────────┴──────────────────────────────┤
│ 将向研发知识平台发送测试查询。不会上传文件或完整会话。       │
│                              [取消] [测试检索] [添加知识库]   │
└─────────────────────────────────────────────────────────────┘

测试查询由用户填写，不自动生成，也不取用当前会话内容。“添加知识库”在真实检索请求 成功前禁用；成功返回零条结果仍可添加，但界面显示“检索成功，未找到匹配片段”。验证结果 在底部说明区展示，不用成功 Alert 撑高表单。 添加成功后沿用本地知识库行为，把新绑定加入当前聊天选择，不重新启用其他已取消知识库。

6.3 目录下拉框

• 选择实例后自动打开加载状态，不要求再点击“读取”。
• 使用可搜索 Select，选项显示名称、远端短 ID 和可用状态。
• 右侧刷新使用刷新图标按钮，Tooltip 为“刷新知识库列表”。
• 加载时保持控件稳定尺寸，显示“正在读取知识库…”。
• 目录为空显示“当前实例没有可访问的知识库”。
• 403 或不支持列表时显示原因和“手工填写知识库 ID”。
• 列表失败后显示“重试”，不自动切换到手工模式。

6.4 手工模式

远端知识库 ID  [                              ]
显示名称        [                              ]
[验证知识库]

验证成功后显示远端名称和 Provider 返回的摘要。返回自动列表不会丢弃已输入 ID，切换前 如有未保存输入须确认。

7. 配置面板

右侧配置固定分为“通用配置”和“{Provider} 配置”，不创建嵌套卡片。高级字段可以使用 一个折叠区，但核心检索方式、阈值和 RAGFlow 图谱检索保持直接可见。

控件选择：

• 开关：图谱检索、Score 阈值启用、Rerank、使用 Dify 知识库默认配置。
• Select 或 SegmentedControl：少量固定检索方式。
• 数字输入或 Stepper：结果数、Token、Top K、超时。
• Slider 加数字输入：0 至 1 的阈值和权重，二者保持同步。
• Metadata 条件：初始版本不提供自由 JSON 编辑器。

字段显隐由 GoodBuddy 内置 Provider 描述和 Main 返回的能力状态共同决定。服务端返回的 任意字符串不得变成 HTML、控件标签或帮助链接。

7.1 RAGFlow 图谱文案

开关名称：图谱检索

说明：检索远端知识库已经生成的图谱内容，不会创建或更新图谱。

只有远端详情或受控探测表明图谱已经构建时，该开关才可用。证据缺失时显示“未确认远端 图谱状态”并禁用。Knowledge Compilation 单独显示为 包含 Knowledge Compilation，默认 关闭，不把它和旧 GraphRAG 合成同一开关。

7.2 实测能力驱动的界面适配

界面不能只按 Provider 名称展示全部开关，必须按实例和当前远端知识库的能力证据处理：

Provider	已实测可启用	保持隐藏或禁用	界面依据
Dify 0.15.8	使用知识库默认配置；展示 retrieval_model_dict 中已出现的检索方式、Top K、阈值和 Rerank 配置	Metadata、多模态、摘要和 Pipeline 状态	目录项能力；该版本详情 GET 返回 405，不能把详情失败显示成实例不可用
Dify 1.17.0	默认配置、当前完整配置；详情中的文档统计、摘要索引、多模态、Metadata 和 Pipeline 只读状态	当前库没有字段定义时禁用 Metadata 条件；远端 Pipeline 和摘要配置不可编辑	详情 GET 和 3 条非空检索结果已实测；child_chunks/files/summary 仅按结果实际存在显示
FastGPT 当前实例	embedding、全文召回、混合召回；Rerank	查询扩展、扩展模型和背景文本	三种模式和 Rerank 均有 200 非空实测；查询扩展会调用模型，初始版本不启用
RAGFlow 当前实例	相似度、向量权重、KNN Top K；具备完成证据时启用图谱检索	没有独立配置证据时禁用 Knowledge Compilation；Metadata 条件仍隐藏	graphrag_task_finish_at 有效才启用图谱；compilation_template_group_id 有效才启用 Knowledge Compilation

RAGFlow 列表项应区分三个图谱状态：“未配置”“构建中或未完成”“可用于图谱检索”。不能 仅因 parser_config.graphrag.use_graphrag = true 就显示为可用。当前实测中 17 个库配置了 GraphRAG，只有 15 个存在完成证据。

Knowledge Compilation 的请求被服务器接受但当前没有库提供配置证据，因此开关显示为禁用， 说明为“当前知识库未配置 Knowledge Compilation”。返回 200 或零结果都不能改变此状态。

Dify 实例行持续显示探测版本。0.15.8 的详情请求返回 405 时显示“此版本从目录读取配置”， 不显示错误状态；1.17.0 详情页增加只读能力行：文档可用数、Metadata 字段数、多模态、 摘要索引和 Knowledge Pipeline。没有配置的能力显示“未配置”，不隐藏成未知，也不提供会 写回 Dify 的编辑操作。

Dify 1.x 的 Metadata 条件使用受控字段编辑器：先从 doc_metadata 选择字段，再按字段类型 提供比较操作和值输入。当前库字段数为 0 时控件禁用并显示“当前知识库没有 Metadata 字段”。 不得允许自由 JSON，也不得把 attachment_ids、Pipeline 或摘要 Prompt 暴露为检索输入。

8. 外部知识库详情

选中外部绑定后，现有详情区按来源类型裁剪：

研发规范                                      RAGFlow · 远端检索
研发知识平台 / 远端知识库 7f31…c902

[概览] [检索配置] [检索测试]

8.1 概览

显示 Provider、实例、远端名称、远端 ID、连接状态、最近成功检索和数据位置。操作包括：

• 刷新远端信息。
• 更换远端知识库。
• 编辑 GoodBuddy 显示名称。
• 从 GoodBuddy 移除。

不显示导入文件、添加目录、添加网页、同步、分块、重建索引和本地图谱入口。

8.2 检索配置

复用创建向导右侧配置面板。存在失效字段时，页头显示“配置需要确认”，字段附近说明 Provider 版本变化，保存按钮保持禁用直到用户处理。

8.3 检索测试

复用现有检索测试工作台的查询、结果和焦点行为，但外部结果采用 Provider 诊断：

RAGFlow · 研发知识平台
总耗时 642 ms · 返回 6 条 · 保留 6 条

1  部署规范.pdf
   第四章 网络要求…
   Provider 分数 0.82 · 文档 ID 98ab…

外部测试不显示 FTS/CJK/本地向量扫描等本地通道，也不提供依赖本地分块的“查看上下文”。

9. 聊天知识范围

现有多选列表保留一个选择面，只在每行增加来源：

[✓] 产品资料                         本地
[✓] 研发规范                         RAGFlow · 研发知识平台
[ ] 客服知识                         FastGPT · 客服平台

• 不按 Provider 创建多套选择器。
• 不可用绑定保留显示但禁用勾选，并给出认证失效或目标不存在原因。
• 当前会话已选绑定变为不可用时，不静默移除 ID；发送前提示该知识库本次无法检索。

10. 执行状态和引用

活动状态：

正在检索“研发规范”
RAGFlow · 研发知识平台 · 已发送当前检索词

部分失败：

已检索 3 个知识库，2 个成功，1 个超时
[查看详情]

引用：

部署规范.pdf / 网络要求
研发规范 · RAGFlow · 研发知识平台

引用详情显示远端文档名、ID、片段、Provider 分数和实际返回的定位。未完成 URL 安全设计前， 不显示“打开远端来源”。

11. 删除确认

移除绑定：

从 GoodBuddy 移除“研发规范”？
这会删除本机绑定和检索配置，不会删除 RAGFlow 中的知识库或文档。

[取消] [移除]

删除有绑定的实例：

“研发知识平台”仍被 3 个知识库使用
删除实例会同时从 GoodBuddy 移除这些绑定。远端数据不会改变。

[取消] [查看知识库] [删除实例和本地绑定]

破坏性主操作使用 danger-solid，默认焦点放在“取消”。

12. 可访问性与响应式

• 常规宽度两栏使用稳定 Grid；小于 960px 时改为单栏，顺序为来源、通用配置、Provider 配置。
• 小于 720px 时外部实例表格转为单列列表，行操作保留菜单按钮和完整可访问名称。
• Modal、创建向导、下拉框和折叠区支持完整键盘操作。
• 异步列表和测试状态使用 aria-live="polite"；错误使用与字段关联的 role="alert"。
• 图标按钮必须提供 Tooltip 和 aria-label。
• 状态不只靠颜色；加载、成功、受限和失败均包含文字。
• 长实例名、地址、远端名称和 ID 使用单行省略，完整值可通过 Tooltip 或详情查看。
• 切换类型、实例或退出时存在有效草稿，应按全局离开保护规则确认。

13. 文案表

场景	文案
页面操作	管理外部实例
创建类型	本地 / Dify / FastGPT / RAGFlow
创建主操作	添加知识库
列表加载	正在读取知识库…
列表受限	当前凭据不能读取知识库列表，可手工填写知识库 ID。
远端状态	远端可检索
移除操作	从 GoodBuddy 移除
图谱开关	图谱检索
测试说明	测试只发送当前查询，不会调用 GoodBuddy 模型或修改远端内容。

产品文案不使用“同步外部知识库”“导入 Dify 知识库”或“创建远端知识库”，因为这些动作 都不是本功能的实际行为。

14. 需求追踪

UI 区域	需求	场景
页面标题与统一列表	EK-FR-01、EK-FR-10	EK-US-C1
外部实例管理与表单	EK-FR-02、EK-FR-03、EK-FR-15、EK-FR-16	EK-US-A1 至 EK-US-A3
新建知识库向导	EK-FR-04 至 EK-FR-09	EK-US-B1 至 EK-US-B4
外部详情与检索测试	EK-FR-12、EK-FR-13	EK-US-C3、EK-US-D1 至 EK-US-D4
聊天范围、状态和引用	EK-FR-11、EK-FR-12、EK-FR-14	EK-US-C1 至 EK-US-C4