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

知识库 UI 设计

1. 设计目标

知识库优先帮助普通用户完成“添加资料并可靠提问”，高级 RAG 调试和图谱维护不得阻塞 首次使用。全局视觉、页面壳层、通知、焦点和危险操作遵循 UI-DESIGN.md。

2. 信息架构

当前列表同时容纳本地库与外部绑定，页面增加“管理外部实例”和来源筛选。以下详情结构、 资料导入和索引状态适用于本地库；外部创建、配置、检索测试及引用的当前实现与待验收项见 外部知识库 UI 设计。

知识库
├─ 知识库列表
└─ 当前知识库
   ├─ 文档与来源
   ├─ 知识图谱（启用后显示）
   ├─ 任务中心
   └─ 高级设置

标题区提供“用于当前对话”“检索测试”、编辑和删除。新建知识库是页面主操作。 “高级设置”承载问答效果入口、向量索引、分块与图谱配置，不把工程参数放在首次路径。

本地与外部库共用的列表以 minmax(0, 1fr) 限制条目宽度，再对名称单行省略；选中卡片 的边框必须完整留在列表内，Provider/实例等辅助文字允许换行。不得用列表外层裁切 掩盖被长名称撑宽的卡片，库图标不能随名称一起收缩。外部详情的长名称和远端名称允许 换行，不能撑出横向滚动条。创建类型分段控件与详情页签保持固定内容高度，不随长表单收缩。

3. 首次使用

没有知识库时，页面空状态显示“新建知识库”主操作。创建时先选择类型；本地类型默认 展示名称和描述，存储方式与知识图谱放入折叠的“高级设置”。本地库创建完成后进入 “文档与来源”，用户可以导入文件、文件夹或 URL。

文档处理完成后，标题区“用于当前对话”可用。该操作把当前知识库加入当前 Conversation 的检索范围，返回对话并聚焦输入框。

4. 状态

知识库列表显示“可用”和“需处理”文档数。详情标题持续显示可检索、处理中、需处理和 总文档数，即使用户填写了知识库描述也不隐藏状态。

文档行显示：

• 总体处理状态。
• 全文状态。
• 向量状态。
• 启用图谱时的图谱状态。

失败文档保留错误信息和“重新处理”，入口位置见第 6 节。只要仍有可用分块，就允许 打开分块管理，避免隐藏上一版可用索引。

5. 问答效果与高级参数

“检索测试”默认只突出真实问题、测试按钮和结果。高级参数使用折叠区，包含候选倍数、 通道权重、最低相似度、重排、结果数和上下文预算。“高级设置 → 问答效果”打开同一 工作台。

向量模型未配置时显示“前往设置”，直接进入模型连接，不使用只有说明文字的死路状态。

6. 来源操作

“文档与来源”使用一张按来源组织的表格。单文件、单 URL 来源只有一篇关联文档时， 来源与文档合成一行，以文档名为主标题，同步状态、同步时间和索引状态就近显示。 不再单独展示同名来源行，也不重复任务入口。目录及其他一对多来源保留来源组标题， 文档紧随其后；零文档和失败来源仍保留同步、暂停、重试及移除入口。 没有 sourceId 或找不到对应来源的文档独立显示。

搜索同时匹配来源名称、来源位置、文档名称和路径。来源命中时显示该组全部文档； 仅文档命中时保留组标题和命中文档。一对多关系按完整数据判断，搜索不能将其临时合成 单文档行。移除确认使用来源的完整文档数量，不使用搜索结果数。

导入文件、目录、URL 及拖放入口保持可用，拖放区使用紧凑的图标与文字提示。 合并行继续显示 URL，包含路径、查询参数和片段，使同标题的不同页面可以区分； 长地址允许换行。本地文件沿用文件名摘要。来源组中的 URL 同样可见。

每行只直接显示一个主要动作及一个“更多操作”按钮。有解析结果时主要动作是 “查看解析结果”；没有结果时，失败文档显示“重新处理”，其余文档有任务时显示 “查看任务”，否则显示“打开来源”。来源组优先提供失败重试或查看任务，没有任务时 提供同步或暂停。状态与错误始终在行内可见。

更多操作复用 AnchoredMenu，依次放置打开来源、打开解析时原件、文档分块、查看任务， 再用分隔线区分重新处理、来源同步和移除来源。仅在有对应资源时显示原件或任务入口； 没有分块时禁用分块入口。来源组的菜单提供任务及来源维护。菜单支持方向键、Home、End、 Escape 和焦点返回，展开不改变行高；空间不足时翻转方向或在菜单内滚动。 大小与分块数保持单行，窄窗口在表格内部横向滚动。 操作文案使用“打开来源 / 重新解析 / 同步 / 暂停 / 重试 / 移除来源”，不附带对象名称；更多操作按钮的可访问名称和移除确认框仍保留对象名称。 列表和预览的操作菜单宽度为 220px，小视口下收窄并保留左右各 16px 边距。

解析预览头部按返回、文档标题与库名及全局范围、维护菜单排列，地址仍可辨认。 正文、图片和详情使用共享结果组件；知识库的会话选择及添加图片工具仅在图片页显示， 切换页签保留选择。返回列表恢复搜索、原触发按钮焦点及页面滚动位置。重新解析继续 调用文档重建，使用当前设置并保留上次结果，失败时显示可恢复错误。维护菜单同时保留 当前来源与解析时原件的打开操作，两者分别读取知识来源和已保存的解析资产。

在飞操作只禁用对应的操作入口。同步或重解析 A 期间，其他来源 B 的暂停仍可用； 并发操作分别恢复可用状态，A 结束不能提前解除仍在执行的 B。

文档行提供“打开来源”，Main 根据知识库和文档归属重新读取保存的文件路径或 URL。 移除来源使用确认对话框，说明文档数、索引、图谱证据和托管副本影响。初始焦点位于 取消，提交期间禁止重复操作，失败时保留对话框和错误。

7. 对话范围

知识库多选属于 Conversation。新对话默认空范围；切换对话恢复各自选择。创建新知识库 只加入当前 Conversation，不重新启用其他已取消项。发送请求时冻结当前选择和检索方式。

输入区的知识库选择弹层使用整行原生 Checkbox 标签，点击名称、文档数量或行内空白 均切换一次选择；选中背景和整行焦点环保持可见。Tab 聚焦、Space 切换，Escape 关闭并 返回触发按钮。点击行内非焦点元素时产生的空目标失焦不关闭弹层；点击外部或焦点明确 移到外部时才关闭，避免原生标签完成勾选前被卸载。

8. 任务批次与历史

任务中心按服务返回的 parentTaskId 组织一次操作及其文档、阶段子任务。顶层操作按 创建时间倒序排列，一个操作计为一个批次；缺失父记录的旧任务仍独立显示。重试产生的 新操作保留真实历史，使用已有 attempt 显示尝试次数，不按标题猜测合并关系。

文档或来源进入任务中心后，列表与计数使用同一对象范围，并保留命中任务的父级上下文。 合并文档行同时匹配来源 ID 和文档 ID，包括没有来源 ID 的文档任务。“清除对象筛选” 恢复当前库的任务集合。

列表与解析预览使用相同的文档任务范围。目录及一对多来源下的文档只按文档 ID 筛选， 即使搜索后只剩一篇也不扩大到整个来源；只有真正的单文档合并行同时包含来源 ID。 预览菜单中的来源同步、暂停和移除仍作用于所属来源，来源维护范围独立于任务筛选。

• 进行中：批次内有排队或运行记录。
• 失败：批次内有失败或中断记录；运行批次也可能同时存在失败子任务。
• 历史：批次内没有排队或运行记录，包含完成、失败、中断、取消和跳过。

计数均按批次计算，失败与历史可以重叠。标题旁的共享帮助解释口径。运行批次中已成功的 阶段不会单独进入历史。切换到进行中或失败时展开相关批次；全部和历史默认收起子任务， 用户仍可逐项展开。批次状态保留服务原值，子任务失败以额外文字提示，不改写父状态。

只有进行中的记录显示进度条；失败和中断保留停止阶段、错误及处理建议。已结束记录 不再显示“当前阶段”、百分比或默认“等待处理”。摘要保留时间、服务消息、子任务数及 重试次数。取消和重试严格使用服务返回的 canCancel、canRetry，提交期间禁用重复 操作，失败后保留筛选、任务内容及就地错误。