# 知识管理

管理当前应用空间的知识库与文档，供智能体运行时加载

## 创建与管理知识库

**功能说明**

「知识管理」页管理当前应用空间的知识库与文档。知识库创建后，还需要在[智能体详情](/docs/tenant-portal/agents.md#agent-detail)的「知识库」卡片中启用，智能体运行时才会加载对应知识。

页面顶部有三张统计卡：

| 卡片 | 内容 |
| --- | --- |
| 应用知识库总数 | 当前空间内可管理的知识库数量 |
| 应用文档总数 | 文档总数，以及生成中 / 等待中 / 失败数量 |
| 创建来源构成 | 按用户、API Key、应用等来源统计知识库 |

列表提供「搜索知识库名称 / 描述」和来源筛选（全部 / 用户 / API Key / 应用），表头为：**知识库 / 创建来源 / 文档数 / 启用的智能体 / 最近更新 / 操作**。

**知识管理列表**

![知识管理列表](/docs/images/tenant-portal/04-knowledge-list.png)

**前置条件**

- 已进入目标应用空间。

**操作步骤（新建知识库）**

1. 点击侧边栏「知识管理」，再点击右上角「新建知识库」。
2. 填写「知识库名称」（必填，最多 100 个字符）和「描述」（可选，最多 500 个字符）。
3. 点击「保存」。

**预期结果**：系统提示「知识库创建成功」，新知识库出现在列表中。在控制台创建的知识库归属当前应用空间，创建来源记为「应用」。

**操作步骤（管理知识库）**

在知识库行尾打开操作菜单：

| 操作 | 说明 |
| --- | --- |
| 编辑 | 修改知识库名称和描述 |
| 管理文档 | 进入知识库详情页，上传和管理文档 |
| 重建 | 重新生成知识库中的可用文档 |
| 删除 | 删除知识库，确认文案说明「删除后无法恢复」 |

**注意事项 / 异常处理**

- 删除知识库不可恢复，删除前请确认智能体已解除引用，并完成必要的数据备份。

## 导入与管理文档

**功能说明**

点击知识库名称或「管理文档」进入详情页。顶部显示知识库描述、文档数和启用它的智能体数量，右上角有「导入文档」；存在上传任务时按钮变为「查看上传任务」。也可以把文件拖拽到页面任意位置导入。

文档视图有以下状态筛选：**全部 / 可用 / 生成中 / 失败 / 智能体删除的文档**，并提供「搜索文件名」和「批量重建」。列表表头为：**文件名 / 描述 / 体积 / 上传时间 / 操作**。

**支持的文件**

| 类型 | 扩展名 | 导入规则 |
| --- | --- | --- |
| 普通文档 | pdf / doc / docx / txt / md / markdown / jpg / jpeg / png | 单个文件不超过 100MB；一次最多选择 20 个 |
| 表格文档 | xls / xlsx / csv | 单个文件不超过 100MB；必须逐个导入并配置列映射 |

空文件、超过 100MB、不支持的类型会在选择后直接提示原因。

### 导入普通文档

1. 点击「导入文档」，选择一个或多个普通文档。
2. 系统打开「批量文档上传」任务面板。上传最多 5 个文件并发执行，上传完成后按顺序逐个受理；进度显示「已处理 x/n · 已受理 n · 失败 n」。
3. 上传期间可以点击「最小化」，或在站内切换页面继续工作；失败项可单独重试，也可以点击「重试全部失败」。全部处理结束后点击「完成并清除」。

**预期结果**：文件受理后出现在文档列表中，状态从「等待中 / 生成中」变为「可用」或「失败」。

> 「已受理」不代表生成完成，请回到文档列表查看最终结果；已受理文档不会因其他文件失败而回滚。刷新或关闭浏览器页签会停止未完成的上传任务。遇到「受理结果未确认」时，请先检查文档列表：上次请求可能已经受理，直接重试可能重复导入。

### 导入表格文档

1. 点击「导入文档」，只选择一个 Excel 或 CSV 文件。
2. 在「导入表格」弹窗设置「表头行」和「数据起始行」，需要时点击「重新解析」。
3. 为每一列选择映射类型：一级标题 / 二级标题 / 三级标题 / 正文 / 不导入。至少保留一列。
4. 确认后提交。QA 类表格建议把问题列设为标题、答案列设为正文。

**预期结果**：系统提示「表格文档已开始导入」，生成完成后文档状态变为「可用」。

### 管理文档

文档行尾提供以下操作：

| 操作 | 说明 |
| --- | --- |
| 查看摘要树 | 查看解析后的文档层级和摘要 |
| 下载 | 获取文档下载地址并下载 |
| 重建 | 重新解析和生成单个文档 |
| 删除 | 手动删除文档，删除后无法恢复 |
| Agent 变更记录 | 有 Agent 修改记录时出现，查看版本差异和回滚，详见[查看 Agent 变更记录](#agent-change-history) |
| 恢复文档 | 仅「智能体删除的文档」视图出现 |

「智能体删除的文档」只展示由智能体删除的文档，可以查看变更记录并恢复；不包含手动删除的文档。

## 为智能体启用知识库

**操作步骤**

1. 进入智能体详情的「Agent」Tab，找到「知识库（已启用 n / 共 m）」卡片。
2. 点击「管理」，打开「管理知识库」。
3. 开启需要引用的知识库；开关会立即启用或解除引用，失败时只回滚当前项。
4. 点击「完成」。

**预期结果**：知识库出现在卡片的「已启用知识库」中，智能体之后的运行会加载该知识库。

## 配置 Agent 更新设置

**功能说明**

如果希望智能体在运行中维护知识库，可以为已启用的知识库配置「Agent 更新设置」。运行时，系统提示词最初只加载候选可写知识库的名称和描述；Agent 选定知识库后，才按需加载更新规范、允许更新的文档范围及新增 / 删除能力。

**操作步骤**

1. 在智能体详情的「知识库」卡片中，对已启用知识库打开「Agent 更新设置」。
2. 填写「知识库更新规范」（可选，Markdown，最多 2000 字），描述更新时机、维护原则和内容结构。此规范不能扩大下面配置的权限范围。
3. 配置「允许更新文档范围」：只允许修改或删除勾选的文档；未选择时不允许修改或删除已有文档。
4. 配置「允许修改用户主体范围」：只有勾选的用户可以触发本库更新；未选择时不允许任何用户触发。
5. 两个范围均支持搜索、分页（每页 100 条）、「全选当前页」和跨页保留勾选。
6. 按需开启：
  - 「允许新增文档」：允许 Agent 把当前会话工作区中的新文件导入本库；
  - 「允许删除文档」：只允许删除上方已选文档，并保留可回滚的 Agent 变更记录。
7. 点击「保存」。

**预期结果**：系统提示「Agent 更新设置已保存」。

## 查看 Agent 变更记录

**功能说明**

「Agent 变更记录」抽屉用来审计智能体对知识文档的修改。左侧按时间列出「新增 / 修改 / Agent 删除 / 回滚」记录，标注版本变化（如 v2 → v3）和变更摘要；右侧对比「变更前 / 变更后」。表格类变更还会显示位置和公式变化。

**操作步骤**

1. 在文档行尾点击「Agent 变更记录」。
2. 在左侧选择一条记录，在右侧查看内容差异。
3. 点击「恢复变更前 vN」或「回滚到此版本」，在确认弹窗中提交。

**预期结果**：系统提交文档恢复或版本回滚，完成编译后自动生效。回滚会生成一个新版本，不会覆盖既有历史。

**注意事项 / 异常处理**

- 节点级修改不会改写原文件；重新编译或重新解析原文件后，节点修改会被覆盖并重建，但历史记录仍会保留。