# 外部知识库 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` |