docs: design external knowledge providers
This commit is contained in:
mesalogo
@@ -0,0 +1,401 @@
|
||||
# 外部知识库 UI 设计
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 设计稿 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-09-03 |
|
||||
| 产品需求 | [外部知识库接入 PRD](./external-knowledge-prd.md) |
|
||||
| 行为规则 | [外部知识库逻辑设计](./external-knowledge-logic-design.md) |
|
||||
| 全局规范 | [GoodBuddy UI 设计系统](../../../UI-DESIGN.md) |
|
||||
|
||||
## 1. 信息架构
|
||||
|
||||
外部知识库不增加左侧主导航和知识库一级页签。现有知识库页面结构保持：
|
||||
|
||||
```text
|
||||
知识库
|
||||
├─ 页面标题区
|
||||
│ ├─ 管理外部实例
|
||||
│ └─ 新建知识库
|
||||
├─ 知识库列表
|
||||
└─ 当前知识库详情
|
||||
```
|
||||
|
||||
“管理外部实例”管理可复用连接；“新建知识库”负责创建本地知识库或添加一个远端绑定。
|
||||
|
||||
## 2. 页面标题区
|
||||
|
||||
常规宽度：
|
||||
|
||||
```text
|
||||
知识库 [管理外部实例] [新建知识库]
|
||||
导入、检索并维护本地和企业现有知识
|
||||
范围：全局
|
||||
```
|
||||
|
||||
- “新建知识库”保持主按钮。
|
||||
- “管理外部实例”是带服务器图标的次按钮。
|
||||
- 沿用知识库页面的全局 `ScopeBadge`，创建和管理外部连接时持续可见。
|
||||
- 按钮使用文字和图标，不增加只含缩写的厂商快捷入口。
|
||||
- 窄窗口下两个按钮换到标题下方，保持同一行；空间不足时各占一半宽度。
|
||||
|
||||
对应：`EK-FR-01`。
|
||||
|
||||
## 3. 知识库列表
|
||||
|
||||
本地和外部知识库保留在同一主列表。条目采用现有列表密度，不增加卡片墙。
|
||||
|
||||
```text
|
||||
研发规范
|
||||
RAGFlow · 研发知识平台 · 远端可检索
|
||||
|
||||
产品资料
|
||||
本地 · 12 个来源 · 全文与向量可用
|
||||
```
|
||||
|
||||
### 3.1 外部条目字段
|
||||
|
||||
- GoodBuddy 显示名称。
|
||||
- Provider 图标或文字徽标。
|
||||
- 外部实例名称。
|
||||
- “远端可检索”、认证失效、目标不存在等准确状态。
|
||||
- 最近一次成功检索时间；从未检索时显示“尚未检索”。
|
||||
|
||||
外部条目不显示来源数量、同步进度、向量覆盖率、本地图谱或导入失败数。
|
||||
|
||||
### 3.2 列表筛选
|
||||
|
||||
现有搜索同时匹配 GoodBuddy 名称、远端名称、Provider 和实例名称。来源筛选使用菜单：
|
||||
|
||||
```text
|
||||
全部来源
|
||||
本地
|
||||
Dify
|
||||
FastGPT
|
||||
RAGFlow
|
||||
```
|
||||
|
||||
筛选不是新的页面页签。
|
||||
|
||||
## 4. 管理外部实例
|
||||
|
||||
点击“管理外部实例”打开大尺寸 Modal。Modal 使用标题、可滚动内容和固定操作区，遵循
|
||||
全局焦点陷阱、Escape、背景隔离和焦点恢复规则。
|
||||
|
||||
```text
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 外部实例 [添加实例] [×] │
|
||||
│ 管理 Dify、FastGPT 和 RAGFlow 的连接 │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ 名称 Provider 服务地址 状态 操作 │
|
||||
│ 研发知识平台 RAGFlow ragflow.example 正常 ⋯ │
|
||||
│ 客服知识平台 FastGPT fastgpt.example 认证失效 ⋯ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 4.1 实例行
|
||||
|
||||
显示：
|
||||
|
||||
- 名称、Provider、脱敏后的主机名、状态。
|
||||
- 已绑定知识库数量。
|
||||
- 最近测试时间。
|
||||
- 行尾菜单：测试连接、编辑、停用或启用、删除。
|
||||
|
||||
服务地址可以显示 scheme、host 和非默认端口，不显示路径中的敏感信息、查询或凭据。
|
||||
|
||||
### 4.2 空状态
|
||||
|
||||
```text
|
||||
尚未配置外部实例
|
||||
添加企业现有的 Dify、FastGPT 或 RAGFlow 服务。
|
||||
[添加实例]
|
||||
```
|
||||
|
||||
筛选无结果和加载失败使用不同 `EmptyState` 变体。
|
||||
|
||||
## 5. 添加和编辑实例
|
||||
|
||||
实例表单在管理 Modal 内切换为编辑面板，不叠加第二层 Modal。
|
||||
|
||||
```text
|
||||
添加外部实例
|
||||
|
||||
实例名称 [研发知识平台 ]
|
||||
Provider [RAGFlow ▾]
|
||||
服务地址 [https://ragflow.example ]
|
||||
认证方式 API Key
|
||||
API Key [•••••••••••••••• ]
|
||||
凭据状态 尚未保存
|
||||
|
||||
连接测试
|
||||
服务连接 未测试
|
||||
身份认证 未测试
|
||||
知识库列表 未测试
|
||||
检索接口 绑定知识库时验证
|
||||
|
||||
[取消] [测试连接] [保存实例]
|
||||
```
|
||||
|
||||
### 5.1 字段行为
|
||||
|
||||
- Provider 使用原生 Select；编辑已被绑定的实例时不可切换 Provider。
|
||||
- 服务地址只接受完整 HTTP(S) 地址。字段下方说明其受全局内网兼容模式影响。
|
||||
- API Key 使用密码输入和显示/隐藏图标。明文会在当前表单和保存 IPC 中短暂存在；编辑时
|
||||
留空表示保留，不使用占位假密钥。
|
||||
- 已保存凭据旁提供“替换凭据”和“清除凭据”，清除属于需要确认的操作。
|
||||
- 地址使用 HTTP，或连接测试依赖放宽证书校验时，在测试和保存操作旁持续显示传输风险。
|
||||
用户必须针对当前地址确认后才能保存；地址变化会清除该确认。
|
||||
- “测试连接”不保存草稿；测试期间按钮显示进度并提供取消。
|
||||
- 保存成功进入应用通知，Modal 返回实例列表并聚焦对应行。
|
||||
|
||||
### 5.2 测试结果
|
||||
|
||||
分项状态使用图标、文字和说明，不只依靠颜色：
|
||||
|
||||
```text
|
||||
服务连接 通过 183 ms
|
||||
身份认证 通过
|
||||
知识库列表 受限 当前凭据不能读取列表，可手工填写知识库 ID
|
||||
检索接口 待验证 添加知识库时执行
|
||||
```
|
||||
|
||||
长错误折叠显示，正文经过脱敏。失败后保留全部草稿和 API Key 输入。
|
||||
|
||||
FastGPT 实例额外显示：`检索会计入该实例的 API 使用记录，并可能产生 Embedding 或
|
||||
Rerank 用量。`
|
||||
|
||||
## 6. 新建知识库向导
|
||||
|
||||
扩展现有页面内 `CreateLibraryWizard`，不改为新的全屏页面或 Modal。
|
||||
|
||||
### 6.1 类型选择
|
||||
|
||||
表单第一项使用单选卡片或共享 SegmentedControl：
|
||||
|
||||
```text
|
||||
知识库类型
|
||||
[本地] [Dify] [FastGPT] [RAGFlow]
|
||||
```
|
||||
|
||||
只有选择本地时显示现有存储模式、图谱和本地说明。外部类型选中后显示两栏配置。
|
||||
|
||||
### 6.2 外部类型两栏布局
|
||||
|
||||
```text
|
||||
┌──────────────────────────────┬──────────────────────────────┐
|
||||
│ 知识库来源 │ 检索配置 │
|
||||
│ │ │
|
||||
│ 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 手工模式
|
||||
|
||||
```text
|
||||
远端知识库 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 合成同一开关。
|
||||
|
||||
## 8. 外部知识库详情
|
||||
|
||||
选中外部绑定后，现有详情区按来源类型裁剪：
|
||||
|
||||
```text
|
||||
研发规范 RAGFlow · 远端检索
|
||||
研发知识平台 / 远端知识库 7f31…c902
|
||||
|
||||
[概览] [检索配置] [检索测试]
|
||||
```
|
||||
|
||||
### 8.1 概览
|
||||
|
||||
显示 Provider、实例、远端名称、远端 ID、连接状态、最近成功检索和数据位置。操作包括：
|
||||
|
||||
- 刷新远端信息。
|
||||
- 更换远端知识库。
|
||||
- 编辑 GoodBuddy 显示名称。
|
||||
- 从 GoodBuddy 移除。
|
||||
|
||||
不显示导入文件、添加目录、添加网页、同步、分块、重建索引和本地图谱入口。
|
||||
|
||||
### 8.2 检索配置
|
||||
|
||||
复用创建向导右侧配置面板。存在失效字段时，页头显示“配置需要确认”，字段附近说明
|
||||
Provider 版本变化，保存按钮保持禁用直到用户处理。
|
||||
|
||||
### 8.3 检索测试
|
||||
|
||||
复用现有检索测试工作台的查询、结果和焦点行为，但外部结果采用 Provider 诊断：
|
||||
|
||||
```text
|
||||
RAGFlow · 研发知识平台
|
||||
总耗时 642 ms · 返回 6 条 · 保留 6 条
|
||||
|
||||
1 部署规范.pdf
|
||||
第四章 网络要求…
|
||||
Provider 分数 0.82 · 文档 ID 98ab…
|
||||
```
|
||||
|
||||
外部测试不显示 FTS/CJK/本地向量扫描等本地通道，也不提供依赖本地分块的“查看上下文”。
|
||||
|
||||
## 9. 聊天知识范围
|
||||
|
||||
现有多选列表保留一个选择面，只在每行增加来源：
|
||||
|
||||
```text
|
||||
[✓] 产品资料 本地
|
||||
[✓] 研发规范 RAGFlow · 研发知识平台
|
||||
[ ] 客服知识 FastGPT · 客服平台
|
||||
```
|
||||
|
||||
- 不按 Provider 创建多套选择器。
|
||||
- 不可用绑定保留显示但禁用勾选，并给出认证失效或目标不存在原因。
|
||||
- 当前会话已选绑定变为不可用时，不静默移除 ID；发送前提示该知识库本次无法检索。
|
||||
|
||||
## 10. 执行状态和引用
|
||||
|
||||
活动状态：
|
||||
|
||||
```text
|
||||
正在检索“研发规范”
|
||||
RAGFlow · 研发知识平台 · 已发送当前检索词
|
||||
```
|
||||
|
||||
部分失败：
|
||||
|
||||
```text
|
||||
已检索 3 个知识库，2 个成功，1 个超时
|
||||
[查看详情]
|
||||
```
|
||||
|
||||
引用：
|
||||
|
||||
```text
|
||||
部署规范.pdf / 网络要求
|
||||
研发规范 · RAGFlow · 研发知识平台
|
||||
```
|
||||
|
||||
引用详情显示远端文档名、ID、片段、Provider 分数和实际返回的定位。未完成 URL 安全设计前，
|
||||
不显示“打开远端来源”。
|
||||
|
||||
## 11. 删除确认
|
||||
|
||||
移除绑定：
|
||||
|
||||
```text
|
||||
从 GoodBuddy 移除“研发规范”？
|
||||
这会删除本机绑定和检索配置，不会删除 RAGFlow 中的知识库或文档。
|
||||
|
||||
[取消] [移除]
|
||||
```
|
||||
|
||||
删除有绑定的实例：
|
||||
|
||||
```text
|
||||
“研发知识平台”仍被 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` |
|
||||
Reference in New Issue
Block a user