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

外部知识库 UI 设计

文档信息

项目	内容
状态	Portal 与控件已修正，Dify 完整 App 真实问答及当前自动回归已通过
版本	0.2
日期	2026-09-13
产品需求	外部知识库接入 PRD
行为规则	外部知识库逻辑设计
全局规范	GoodBuddy UI 设计系统

当前实现与验收边界

KnowledgeWorkspace.tsx 已接入 ExternalKnowledge.tsx，不再处于只有界面草案的阶段。 当前操作与控件如下；后续编号章节保留目标布局、文案和验收要求，其中超出本节的内容 仍待核对，不能作为已实现或已通过桌面验收的描述。

区域	当前实现
页面入口与列表	标题区有“管理外部实例”和新建操作；本地和外部同一列表，按显示名、远端名、Provider、实例名搜索，原生 Select 筛选来源
实例管理	560px 紧凑 Modal 内切换实例列表、编辑表单和删除确认；标题随状态变化，行内提供测试、编辑、启停和移除，显示地址 origin、凭据、探测状态、绑定数与本地化测试时间
实例保存与测试	新建直接显示密码输入；编辑才提供 keep/replace/clear，清除需要确认。眼睛图标切换显隐并提供可访问名称和按下状态。保存后回列表测试目录，连接说明默认折叠；HTTP 地址下显示传输说明
创建类型	共享 SegmentedControl 选择本地、Dify、FastGPT、RAGFlow；本地继续使用现有创建向导，外部挂载独立绑定表单
来源选择	实例使用复用既有 picker 样式的富信息菜单，条目显示名称、地址 origin 与凭据状态；目录使用搜索框、目标按钮、刷新和分页，FastGPT 文件夹可进入与返回根目录；共享分段控件切换手工 ID
配置	常规窗口来源与参数两栏，宽度不超过 959px 时单栏；参数使用数字输入、原生 Select 与共享滑动 Switch 样式，没有 Slider 或自由 JSON 编辑器
测试与保存	用户填写查询，测试成功后可保存，零命中允许添加；保存会再次发出检索请求。查询、目标或参数改变会使测试失效，更换现有绑定目标要求确认
外部详情	共享 PageTabs 提供概览、检索配置和检索测试；概览显示远端 ID、推导状态和绑定验证时间，可刷新详情、用于对话、重新绑定、管理实例或移除
参数编辑	复用绑定表单，保存按钮为“保存检索参数”；恢复默认只重置表单。配置页签访问后保持挂载，切换详情页签保留草稿
检索结果	外部组件显示总耗时、返回数量、片段、定位、实际 ID 和原始评分，包括 FastGPT 评分数组；不显示本地全文、向量、图谱通道或本地上下文操作
聊天与引用	统一选择器显示 Provider、实例与状态；外部引用打开保存片段，显示实例 ID 和远端定位，不请求本地上下文或打开原始来源

创建类型分段控件复用全局不收缩规则，不能被目录和参数表单压扁；列表长名称的宽度约束见 知识库 UI 设计。新建时自动名称跟随目录选择，手动改名和已保存 名称不被覆盖，具体规则见逻辑设计。 实例 Modal 和其他浮层统一参与原生浏览器遮挡处理， 不再仅验证没有浏览器的独立 Portal。

原 knowledge-field 的控件样式依赖知识库工作区祖先，实例 Modal 经 createPortal 挂到 body 后丢失该作用域。当前 Field 使用全局 .field 和标签 span，密码也复用同一字段 结构，确保 Portal 内的字体、输入边框、背景和焦点样式与应用一致。弹窗宽度为 min(560px, 100%)，内容可滚动；操作区粘附底部，范围徽标靠左、按钮靠右，滚动留白 避免键盘焦点被底部操作区遮住。通用参数、Provider 参数和认证使用 fieldset/legend 分组。

Switch 按标签文字在左、滑动开关在右排列，保持 role="switch"。实例菜单支持方向键 打开与移动、Home/End、跳过禁用项、Enter 选择和 Escape 返回触发按钮；目录空状态使用 共享 EmptyState，无搜索结果可清空查询，无目录可切换手工 ID。已选目标悬停不覆盖 选中背景，保存和测试分别显示对应忙碌文案。

保存、删除等成功信息及实例管理中的异步错误使用应用通知；绑定测试、详情刷新和删除 中途失败保留就地恢复所需的错误。实例有绑定时，确认后依次移除本地绑定再删实例；中途 失败刷新已完成的移除，远端内容不变。

当前已实现过期响应丢弃、Modal 焦点管理、PageTabs、标记了 role="switch" 的开关和 窄窗口 CSS。2026-09-13 Dify 已在当前生产 BrowserWindow、Main、Preload、Renderer 和 IPC 上完成实例保存、目录选择、检索后绑定、参数更新、重启及历史引用检查，详见 脱敏验证摘要。验证程序仅在 Main 的实例 保存 Handler 边界替入已有密钥，未将真实密钥放入 Renderer。

1440、900、700 窗口宽度对应报告 viewport 1439、899、699，均无 body 横向溢出。 宽屏配置两栏、窄屏单栏，窄屏列表可见；原生 ArrowRight 可以激活检索页签。已保存并 重开的参数为返回 2 条、超时 15 秒、单片段 200 字符。生产搜索返回两条引用，验证程序 保存带测试标记的会话后重载，引用弹窗显示 Provider、片段和快照说明，焦点在弹窗内， 没有本地上下文或打开来源操作。此检查没有生成模型答案。

上述早期检查没有生成答案。后续完整 App 已从实际输入区选择 Dify 知识库并点击发送， 得到已保存的真实模型短答案，再点击引用核对片段及远端文档/片段 ID；没有伪造消息或 引用。浅深主题均检查了真实 Portal 编辑器的共享字体、背景、560px 宽度与无横向溢出。

另有真实 Electron 视觉 fixture 覆盖浅深主题、四档尺寸及原生键盘操作；其 IPC 是假数据， 只用于界面、焦点和布局检查。三家生成的生产 IPC 验证中，引用展示使用隔离 DOM；只有 Dify 完成了完整 App 的发送与点击引用。计数与方法边界见 实施进度和 后续摘要。当前 UI 修正后的聚焦测试、 全量回归、类型检查、lint 与工作区/暂存区 diff 检查均已通过。App 测试已按实际可访问 富信息菜单交互替换旧 Select 操作，精确计数由实施进度维护。FastGPT/RAGFlow 完整桌面专属操作和 广泛问答质量仍待验收。

与下文目标设计相比，当前还存在以下边界：

• 没有保存前按地址传输风险确认，也没有接入独立证书例外设置；只有传输说明。
• 没有目录或检索的 IPC 取消入口；丢弃旧响应不等于中止网络请求。测试期间绑定表单整体 禁用，不能把其“取消”按钮描述为正在进行的请求可随时取消。
• Dify 版本、Metadata、摘要、多模态和 Pipeline 状态没有进入当前界面；RAGFlow 只接收 图谱完成与知识编译可用布尔证据，没有三态构建展示或版本支持矩阵。
• 列表和概览没有持久化的最近成功检索时间；概览显示 lastVerifiedAt。当前也没有自动 remote-missing/config-invalid 状态、完整裁剪诊断或历史引用“连接已移除”标签。
• 没有覆盖所有关闭、类型切换和手工模式切换的未保存草稿离开确认；实例列表使用可换行 列表而非表格，未单设 720px 表格转换规则。

目标设计与待验收要求

以下保留既有产品布局和交互目标。当前事实以上节为准；历史 Provider 探测用于解释能力 边界，不作为下述界面已经呈现或已通过产品验证的证据。

1. 信息架构

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

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

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

2. 页面标题区

常规宽度：

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

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

对应：EK-FR-01。

3. 知识库列表

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

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

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

3.1 外部条目字段

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

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

3.2 列表筛选

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

全部来源
本地
Dify
FastGPT
RAGFlow

筛选不是新的页面页签。

4. 管理外部实例

点击“管理外部实例”打开最大 560px 的紧凑 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 图谱检索保持直接可见。

第一版遵循 PRD 产品决策的只读范围。面板固定说明： 参数仅保存在 GoodBuddy，用于此绑定的后续检索，不会修改远端知识库设置。 编辑页保存按钮使用“保存检索参数”；恢复默认仅重置当前表单，保存后作用于当前绑定。 远端索引、模型、图谱构建和 Pipeline 配置只展示状态，不提供编辑或执行操作。

Dify 的“使用知识库默认配置”开启时说明：每次检索沿用远端当前设置，远端设置变化会影响结果。 关闭后，客户端显式检索参数随请求发送，不写回远端默认配置。

控件选择：

• 开关：图谱检索、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 当前实例	基础检索；具备完成证据时启用图谱检索	没有独立配置证据时禁用 Knowledge Compilation；Metadata 条件仍隐藏	相似度、向量权重和候选数请求已被接受，但未单独验证参数效果；候选数参数需按部署版本适配，详见技术设计；graphrag_task_finish_at 有效才启用图谱；compilation_template_group_id 有效才启用 Knowledge Compilation

RAGFlow 列表项应区分三个图谱状态：“未配置”“构建中或未完成”“可用于图谱检索”。不能 仅因 parser_config.graphrag.use_graphrag = true 就显示为可用。实测数量见 实施进度，界面按当前远端知识库的配置和完成状态判断。

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