# 知识库挂载 > Cube Agent 2.2.0 正式版（构建 2002007）使用说明。 > 分类：模型与 AI 能力。内容基准：2026-11-07。 > 网页：https://cubeagent.app/docs/knowledge_base/ ## 知识库是什么 知识库是一个可包含多个文件的资料容器,可挂载给助手。适合放项目文档、产品手册、术语表、固定参考资料等内容,避免每次对话都手动粘贴。一个知识库内可以导入多份不同格式的文件,统一管理。 ## 保存与备份 知识库保存在本机，连接 Cube Agent 在线服务不会自动备份。可从知识库首页的 **备份与恢复** 进入数据备份页，选择华为云盘、WebDAV 或 SMB 保存备份。SMB 需要先配置可访问的共享目录。卸载或换机前请确认备份成功；重装后先检查已有备份，再选择恢复。 ## 多级文件夹与搜索 进入某个知识库后可新建文件夹，逐级进入目录，通过路径导航返回上级或祖先。文件夹菜单支持重命名、移动和删除空文件夹；非空文件夹需先处理其中内容，不能移入自身或子目录。 文档菜单可以移动文件，多选后可以批量移动到目标目录。新建文本和导入资料默认进入当前目录。未搜索时，全选作用于当前目录；在标题栏搜索文件名或来源文件名时会跨文件夹查找，全选只作用于搜索结果，切换目录或关键词会清空原选择。 系统文件夹和普通文档 ZIP 导入保留有效资料的相对层级；多文档导出为带目录的 ZIP。合并知识库时，以来源库名创建子目录并保留层级。仅导出文档不等于整库备份，未选中文档所在的空目录不会随文档包导出。 ## 跨知识库移动文件 多选文件（或单个文件菜单）选择移动时，目的地弹窗会显示当前知识库。点 **切换知识库** 选择另一个文档知识库，再选择库内的文件夹；库根目录是该库最外层，不是系统文件夹。世界书不能作为目的地，文件夹本身只能在库内移动。 - 文件的正文、原件、草稿和历史版本会一起移走，目标库有同名文件时自动加序号，不会覆盖。 - 跨库移动后关键词检索可直接使用，向量索引需要到目标库重新建立。 - 文件正在索引、识别、优化或导出时不能移动，请等待完成后再试。 - 移动过程中可点 **停止后续移动**，已完成的保留在目标库，其余仍在来源库。 移动目录或文档不会改写正文、文档身份或已有索引。检索结果带目录路径以区分同名资料；助手仍按整库挂载，全部索引与覆盖率也仍按整库计算。目录最多 16 层、每库最多 2000 个；旧版可能丢弃目录字段，请使用支持目录功能的版本恢复和维护新目录。 ## 复制知识库文件到工作区 在普通会话中让助手“把知识库里的这份文件复制到工作区”，即可本地复制到当前会话的 outputs 目录，并显示文件卡片。需要当前助手启用“管理知识库”和来源知识库。默认复制保留的 PDF 或图片原件，其他文档复制为 Markdown；也可以明确要求复制当前 Markdown 正文。同名自动加序号，原件及索引保留，无需 AI 读取或重写全文。 未保留的 Office / EPUB 原件不能由导出恢复；无痕会话不保存工作区文件。知识库之间的复制与复制到工作区是两个独立操作，分别遵循设置中的确认策略。 ## 怎么导入 打开 **设置 → 知识库**,点击 **导入** 或进入某个知识库详情点 **导入文件**。支持文本(`.md`/`.txt`)与文档(`.pdf`/`.docx`/`.xlsx`/`.ofd`/`.ppt`/`.pptx`/`.epub`,自动抽取正文;EPUB 电子书整本转为 Markdown),文件选择器只显示支持的格式。文本文件导入时会自动识别编码(UTF-8 / UTF-16 / GB18030,覆盖 GBK 老文件),无需手动转码。已有知识库时会先询问 **导入到哪个库**(新建或追加到已有库);也可以在标题栏点 **新建** 先建一个空知识库,再进详情页慢慢添加内容。 ## 批量导入 文件选择器支持一次多选(最多 100 个)。选中多个文件会进入批量导入页:逐个解析、实时展示每个文件的状态与字数,解析失败的文件可移除后继续,底部一次确认全部入库,完成后直达知识库详情页。文字版 PDF 会自动提取文本；扫描件可保留原 PDF 并标记「待 OCR」，先导入知识库，再从文档中继续识别。 单文件导入会先预览解析结果,你可以选择: - **直接导入**:原样落库(标记为「原始」)。 - **后台优化为 Markdown（可选）**:选择一个已配置的对话模型，确认后先保存原文，再后台清理段落、标题、列表和表格。可以离开页面，在知识库的文档任务中查看进度；优化完成后先预览审核稿，确认采用才替换正文。任务失败时原文仍保留，可重试。 导入时跳过优化也可以稍后处理：在知识库详情通过文件菜单进行单篇优化，或进入多选、选择所需文件后点 **LLM 优化**。每批最多 100 篇，选择一次模型即可排队，全局同时处理最多 2 篇。可离开页面，在任务记录中查看逐篇进度、取消或仅重试未完成项。后台运行仍受系统限制；进程结束后保留中断记录，不自动重复收费请求。 优化不设字数上限。长文档可能耗时较久，也可能超出所选模型的上下文或最大输出长度，导致请求失败或结果不完整，请在采用前核对完整性。 优化先生成待审核稿，不直接覆盖正文。确认采用后才替换当前内容，并保留原文恢复入口；采用导致旧语义索引失效，需要重新建立索引。未选择的文件不受影响。 ## 直接导入 ZIP 在知识库页选择 **导入知识库（压缩包）**，选择本应用导出的文档 ZIP，再选择新建知识库或追加目标。也可以从某个知识库详情的同名入口直接追加。预览文件列表后确认导入，无需先手动解压。 支持文档 ZIP 和可识别的普通文档压缩包；本应用导出的清单会校验正文与完整性信息。压缩包最多 256 MiB、展开后最多 256 MiB、每次最多 100 篇文档。整应用备份包请使用 **设置 → 数据与同步 → 数据导入**，不要从知识库文档入口恢复。 ## 多选删除 进入知识库详情的多选模式，勾选文档后点 **删除所选**，确认数量后删除。取消确认会保留选择；删除只处理所选文档及其索引，保留知识库和未选文档。删除后不能从该知识库直接撤销，请先导出需要保留的正文。 ## 重命名与导出 知识库与库内文件均可重命名；只修改显示名称，不改变正文、索引或挂载关系。已授权的助手也可通过 **管理知识库** 提交改名操作，默认确认面板显示原名与新名；按已设置的该助手重命名授权策略执行，仍核对原名称。 从文件菜单或多选操作栏可以导出：单篇保存为 Markdown，多篇打包为 ZIP，并附来源及完整性清单。准备完成后再选择保存位置，取消保存仍可稍后继续。导出的是当前已保存的正文，不含原始 PDF/Office 附件、未采用的优化稿、语义索引或本地解析图片。知识库检索使用解析正文，图片本身不会自动成为视觉检索内容。 ## 手写新建文本 在知识库详情点 **新建文本**,可直接填写文件名与正文落库,适合笔记、设定、规则等不必先从外部导入的内容。已有文本文件也可进入编辑页修改。 ## 在对话里直接入库 和助手讨论出一个结论后,不必先生成 Markdown 文件再下载、再回来导入。为助手开启 **助手 → 编辑助手 → 工具 → 管理知识库**，并在 **助手 → 编辑助手 → 知识** 中启用目标知识库后，可以直接在对话里说「把刚才这段存进 XX 库」，或者只说「存进知识库」，让助手按需列出已启用的库后选择。关闭或未挂载的库不能被列出、读取或写入，开启管理工具也不会扩大权限。助手能做的操作有: - **新增笔记**:把讨论结论整理成一篇新笔记写入某个库;目标库不存在时可顺带新建。 - **追加**:把补充内容接到已有笔记末尾,避免同一主题散成很多篇。 - **局部修改与中间插入**:只替换指定的一句话或一段内容，也可以删除片段、在指定标题或段落前后插入新内容。助手定位原文后只提交相关片段和新增文字，减少读取和重写全文带来的 token 消耗。 - **复制文件**:在同一个知识库或两个已启用的知识库之间复制文件，可指定目标目录和副本名称。正文、原始附件与修订文件在本地复制，保留源文件，同名自动加序号，无需 AI 手抄。复制默认不建立语义索引，可在确认卡开启，使用目标库的向量模型配置。 - **覆盖**:整篇重写一篇已有笔记。 - **删除**:删掉某一篇笔记(不支持删除整个知识库,那仍需去知识库中心操作)。 - **查阅**:列出知识库与文件、按关键词定位原文或分段读取笔记。查阅是只读操作,不会打断你。 例如，可以说「把售后知识库《服务说明》里的服务期从 7 天改成 15 天，其他内容保持原样」，或「在这篇笔记的『退款流程』标题前插入以下说明……」。复制时可以说「把售后库的《服务说明》复制到培训库的新人目录，命名为《服务说明副本》」。描述清楚来源和目标即可，无需自己复制整篇原文。只需在末尾补充时，可以直接说「在这篇笔记末尾追加……」。 默认每次写入都会在对话里弹出 **入库草稿卡**，确认后才落库；点取消则不写入。可在 **工具服务 → 授权 → 知识库管理** 按新建笔记、导入文件、复制文件、导入并追加、追加内容、修改正文、重命名文档／知识库、新建文件夹、移动文档和删除文档分别设置。选择全局默认，或选择助手设为 **跟随 / 询问 / 允许**；助手的单项设置优先于全局。可点击 **确认策略** 右侧的 **批量允许**，勾选操作并一次确认；删除默认不勾选，未选操作保持原设置，助手的批量授权仅影响当前选中的助手。同一行的 **重置** 可将当前对象全部改为询问；助手还可全部跟随全局，清除单独设置（全局已允许的操作仍会直接执行）。草稿卡的 **此助手始终允许此操作** 只保存当前助手当前操作的授权。授权仅保存在本设备，不随备份或分享迁移，可在授权页撤销；新建知识库并挂载仍每次确认。始终允许不会开启管理工具或扩大助手可访问的知识库范围，覆盖与删除仍检查内容版本。新增或整篇覆盖时可以检查正文；局部修改时会展示 **修改对比**，列出原文和替换后的文字。可以编辑替换文字，留空表示删除该片段。默认只替换唯一匹配的原文；要修改所有相同内容时，请明确说明「全部替换」，并检查卡片上的提示。原文找不到、匹配不唯一或编辑期间内容已变化时，助手需要重新定位或读取后再提交。 新增、导入或修改成功后，默认只为这一条新内容建立语义索引(需要已配置知识库向量模型)，未配置时会跳过并提示；复制文件默认不自动建立索引，减少单纯复制的向量化消耗。可在确认卡调整索引开关，或稍后到详情页手动整理。副本不继承原文件的向量索引；关键词检索与全量灌入不受影响。 技能中心内置了一个 **知识入库** 技能,挂给助手后会约束入库前的归纳格式(标题、结论、要点、来源与日期),避免把整段对话原样塞进知识库。 ## 标签整理 可在知识库详情为资料添加多个标签,例如“项目 A”“产品资料”或“待整理”。标签会显示在知识库列表中,方便快速筛选和辨认同类资料。 ## 语义索引与后台保活 需要语义检索时,可在详情页摘要卡点 **为全部文档建立索引**，也可以在单个文件卡上手动触发。未配置向量模型时会直接弹出选择器,选完自动继续。索引进行中可切到后台继续(continuous task 保活),不必一直停在页面;建立失败会显示具体数量,可点重试。导入时的正文优化同样支持后台继续。 ## 怎么挂载给助手 进入 **助手 → 编辑助手 → 知识**,打开需要的知识库开关。除了逐个选择,也可以按标签一次选择或卸载一组知识库。挂载以整个知识库为单位(库内全部文件一起生效),可选择装载方式: - **全量灌入**:把知识库全部文件正文聚合后注入请求上下文。适合短资料、规则手册。 - **按需检索**:不主动塞进上下文,模型需要时通过 `search_knowledge_base` 检索相关片段。适合长资料、多文档合集。 ## 混合检索(关键词 + 语义) 按需检索模式下,系统会同时执行关键词检索与语义向量检索,融合后返回最相关的片段(仅在配置了 Embedding 模型时启用语义路)。未配置 Embedding 模型时自动降级为纯关键词检索,不中断对话。 在 **设置 → 模型与用量 → 默认模型 → 知识库向量化** 配置全局 Embedding 模型,或在单个知识库详情里覆盖使用不同的 Embedding 模型。在详情页切换某个库的向量模型后,旧索引会失效,需手动点 **为全部文档建立索引** 重新建立,不会自动全量重跑。 ## System 与 @Depth 全量灌入时可以选择注入位置: - **System 设定**:并入系统提示词,更稳定,也更适合长期规则。 - **@Depth 深度**:把资料插到靠近最近消息的位置。深度越靠近末尾,模型越容易关注;适合临时性更强、需要提高注意力的资料。 ## 和技能的区别 技能更像"做事方法 + 可按需读取的多文件资料",适合工作流、规范和工具使用说明。知识库更像"可检索/可注入的资料正文",适合把文档内容挂给助手长期参考。 ## 注意事项 全量灌入会增加上下文长度和 token 消耗。同一次对话中所有全量灌入的知识库合计最多 100 万字符,且不超过当前模型上下文窗口的一半(按估算 token 计,模型未填写窗口时只按字符上限),超出部分按挂载顺序和文件顺序截断,模型会看到截断提示和未灌入的文件数;超过 20 万字符的大文本建议优先使用按需检索并建立向量索引,检索不受长度限制且更细致。知识库正文与向量索引保存在本机文件目录中;删除知识库会自动解除所有助手挂载。使用备份/恢复可完整携带知识库的多文件内容与向量索引,恢复后可直接复用向量无需重新计算。旧版本(单文件知识库)在升级后会自动迁移为含单文件的新模型,挂载关系完整保留。 ## 合并知识库 在知识库列表可以把多个知识库合并为一个，常用于整理重复或同类资料。合并会把所选知识库的文件汇聚到目标库，原知识库的挂载关系也随之转移到目标库。若个别文件迁移失败，涉及的源库会整库保留以防内容丢失，完成时会展示迁移/失败/保留的具体计数。 ## 最佳实践 - 合并前确认目标知识库命名清晰，便于合并后分辨来源。 - 合并不会自动建立索引；完成后可点 **去建立索引** 直达新库，用摘要卡的 **为全部文档建立索引** 一键完成。 - 合并是文件汇聚、原库会被整合，重要资料建议先备份再操作。