本地知识库

本地知识库是一个存放 Markdown 文件的普通文件夹，你可以在 VelaTerm 中编写和整理其中的内容。笔记和附件都保存在该文件夹中，因此也可以继续用其他编辑器编辑。英文界面的部分菜单项将本地知识库称为“notebook”，两种叫法指的是同一个文件夹。

内置的「会话知识库」与你的本地知识库并列显示。它保存智能体从你的会话中整理出的知识，并单独维护自己的条目、来源和修订历史，详见会话知识库。

打开知识库

点击右栏中的知识库图标（提示文字为「知识库」），中栏会打开一个「知识库」标签页，并显示主页：

搜索框（「搜索会话知识与本地笔记…」，见下文的“搜索”一节）；
「会话知识库」；
你的「本地知识库」；
「打开知识库」和「新建知识库」按钮。

右栏显示一棵包含三个根节点的树：「会话知识库」「已归档会话」和「本地知识库」。点击箭头可以就地展开文件夹，并且可以同时展开多个知识库。点击文件夹名称可以显示其内容，点击笔记即可打开。树顶部的「知识库」链接可返回主页；页面标题栏中的「返回上一级」按钮会转到上一级页面，而不会离开知识库。

笔记在普通的文档标签页中打开，编辑、保存、搜索和导出 PDF 的方式与其他 Markdown 文件相同（见文档与浏览器标签页）。「知识库」标签页会保留在标签栏中，方便你回到之前的位置。

打开或新建本地知识库

打开：点击「打开知识库」并选择一个文件夹。桌面版会显示系统的文件夹选择器；浏览器客户端则显示所连接计算机上的文件夹浏览器。现有的 Obsidian 仓库可以直接打开：文件保留在原位置，.obsidian 等隐藏文件夹既不会被索引，也不会被修改。
新建：点击「新建知识库」，输入「名称」，选择「文件夹」（或点击「浏览」；建议位置为 ~/Notes），然后确认。VelaTerm 会创建并打开该文件夹。父文件夹必须已存在，且其中不能已有同名文件夹，否则 VelaTerm 会提示「目标已存在，请更换名称或文件夹。」如需使用现有文件夹，请改用「打开知识库」。
重命名：在树中右键点击知识库并选择「重命名」。这会重命名磁盘上的文件夹。
关闭：点击知识库工具栏中的「关闭知识库」，或在树中右键点击该知识库进行关闭。关闭只会将文件夹从列表中移除，其中的文件仍保留在磁盘上。再次打开同一文件夹时，它的回收站和导入记录依然存在。

这里的“本地”是指运行你所连接的 VelaTerm 后端的那台计算机。在浏览器客户端中，「打开知识库」浏览的是那台计算机上的文件夹，导入时会将你在浏览器中选择的文件上传到那台计算机。

导入文件和文件夹

打开目标知识库，点击其工具栏中的「导入」。
选择目标「文件夹」，然后点击「选择文件」或「选择文件夹」，也可以将文件和文件夹拖入导入区域。
检查列表并确认。

导入在后台运行，复制期间可以切换页面或打开笔记。导入进度显示在知识库工具栏和主页上，可以在导入对话框或「导入记录」中取消。导入结束后，横幅会显示已导入和已跳过的文件数；如果窗口不在前台，还会弹出系统通知（「导入完成」或「导入失败」）。同一个知识库同一时间只能运行一个导入任务。

导入会按原样复制文件，包括非 ASCII 文件名、相对目录结构和附件，并且从不修改原文件。导入文件夹时会连同该文件夹本身一起导入。只要有任何文件会覆盖已有文件，整批导入都会被拒绝。隐藏文件和隐藏的配置文件夹会被跳过。浏览器的文件选择器不提供空文件夹，因此空文件夹不会被导入。

单次导入最多包含 5,000 个文件（被跳过的隐藏文件也计入此上限），总大小不超过 1 GiB，单个文件不超过 100 MiB。文件会先暂存，整批全部到达后才会出现在目标位置，因此中断的上传不会留下写了一半的笔记。

「导入记录」列出每次导入的时间、目标位置（顶层文件夹显示为「知识库根目录」）、状态（「正在导入」「已完成」「失败」「已取消」或「已中断」）、已导入和已跳过的文件数、大小以及耗时。点击「文件清单（N）」可以查看每个文件及其被跳过的原因。「删除记录」会将该条目从记录中移除，但不会删除已导入的文件。如果某次导入的进度停止超过两分钟（例如应用意外退出），该导入会被标记为「已中断」；删除它的记录时，也会删除为其暂存的文件。

编写和整理笔记

知识库页面包含「最近笔记」「回收站」和「导入记录」三个视图、一个「新建笔记」按钮，以及工具栏中的「新建文件夹」「导入」和「关闭知识库」按钮。笔记列表可以按标签筛选（「全部标签」），排序方式可选「最近更新」或「按标题排序」。

显示知识库页面时，⌘N / Ctrl+N 会执行「新建笔记」，⌘O / Ctrl+O 会打开「快速打开」（按路径查找笔记），⌘⇧F / Ctrl+Shift+F 会将焦点移到「搜索笔记…」输入框。
要重命名笔记，请在树中右键点击它并选择「重命名」。要移动笔记，请将它拖到同一知识库中的另一个文件夹上。「删除」会将它移到该知识库的回收站。
打开某个文件夹时，「重命名或移动」会将该文件夹移到相对于知识库根目录的指定路径，目标的父文件夹必须已经存在。移动笔记或文件夹时，同一知识库中其他笔记里的链接会随之更新，链接文字保持不变，代码内容也不会被改动。
删除的项目会移到知识库内的 .vkb-trash 文件夹。打开「回收站」并点击「恢复」即可将其还原；恢复时绝不会覆盖已有的同名文件。
标签来自正文中的 #tag，以及 YAML 中的 tags 列表或数组。
粘贴到笔记中的图片会保存在该笔记旁边的 assets 文件夹中。

页面可见时，树和列表大约每五秒刷新一次；窗口重新获得焦点时也会刷新。已打开的文档标签页能检测到其他程序所做的修改，并提示重新加载。

知识库页面、对话框、导入记录、搜索、搜索范围、标签、排序和快速打开都有各自的 URL，因此可以刷新页面，也可以使用浏览器的后退和前进按钮。未保存的文本和表单输入不包含在 URL 中。

搜索

主页：同时搜索会话知识库和所有本地知识库，并按来源对结果分组。不包括已归档的会话。
右栏：树上方的「搜索笔记…」会搜索所有本地知识库。
知识库页面：「搜索笔记…」会搜索笔记名称、路径和正文。「搜索范围」可在「当前知识库」和「全部知识库」之间切换。

输入多个词时，必须全部匹配。每条结果会显示其所属的知识库或会话分组、一段摘录、行号、匹配次数，以及该笔记链接到的「相关笔记」；点击其中任意一项即可打开。使用上下方向键选择结果，按 Enter 打开，按 Esc 清除搜索。结果首先按名称或路径是否匹配排序，其次按匹配次数，最后按最近更新时间。最多列出 100 条结果；超出时，列表末尾会显示「只列出前面的结果，缩小关键词可看到其余命中。」

VelaTerm 会先查找精确匹配，只有在没有精确匹配时才改用近似匹配，并显示「没有精确匹配，以下为近似结果。」近似匹配适用于由拉丁字母和数字组成的词：按顺序出现的字母（knwl 可以找到 knowledge）、首字母（kb 可以找到 knowledge base），以及轻微的拼写错误（四个或以上字符的词允许一处错误，八个或以上字符的词允许两处错误；knoledge 可以找到 knowledge）。中文及其他非拉丁文字按精确方式匹配。

链接与现有文件的兼容性

VelaTerm 能识别常见的 [[note]]、[[folder/note|label]] 和 [[note#heading]] 形式、标准的 Markdown 相对链接，以及 ![[image.png]]。这些链接用于在笔记移动时更新链接、在搜索结果中列出「相关笔记」，以及供下文的 vkb 命令使用。在编辑器中，[[…]] 链接显示为纯文本。多个文件同名时，只有目标唯一，短链接才能解析；否则请写出文件夹路径。

文件始终是纯 Markdown，YAML 前置元数据（front matter）也保留在文件中；编辑器的源码模式会原样显示这些内容。非 UTF-8 编码或大于 5 MiB 的 Markdown 文件不会作为笔记列出，而是计入「已跳过」。一个知识库最多可包含 50,000 个文件和文件夹；超出此数量的文件夹无法打开，并会显示「文件或所选内容超出知识库限制。」VelaTerm 不会跟随符号链接。

上述功能涵盖了处理本地文件、文件夹、Markdown、链接和搜索的日常工作。Obsidian 的插件、主题、Canvas、块引用、嵌入笔记和 YAML 别名均不受支持，相应的文件保持不变。关于文件模型和链接语法，请参阅 Obsidian 文档中关于仓库、内部链接和附件的说明。

从会话知识库复制与智能体查询

在会话知识库中打开一个条目，选择「复制到本地知识库」，然后选择目标知识库和文件名。副本是一篇独立的 Markdown 笔记；原条目及其来源快照和修订历史都保持原样。

在 VelaTerm 会话中，你或智能体可以使用 vkb 读取已登记的本地知识库：

vkb notes "reading notes"
vkb note <knowledge-base-ID> "reading/how-to-take-notes.md"
vkb search "architecture decision"

notes 搜索当前后端上登记的所有本地知识库。每条结果包含 vaultId、vaultName、path、absolutePath、line、matches、score、matched（实际匹配到的文本）、related（该笔记链接到的笔记）和 summary（匹配处前后的文本）。响应中还包含 total、hasMore、unavailable（无法读取的知识库）和 fuzzy（结果是否为近似匹配）。最多返回 100 条结果。
note 返回笔记的正文、大纲、链接、反向链接和标签。
search 返回会话知识库和本地笔记中的匹配结果；如果存在代码索引，还会返回代码图谱中的结果（见代码图谱与知识库）。

这些命令都是只读的，从不修改笔记；VelaTerm 也不会自动将知识库内容加入会话。

存储与日志

磁盘上的文件是笔记和附件的权威副本。应用数据库（kb_* 表）只保存已登记的知识库列表、回收站记录、导入记录，以及可以重建的搜索缓存。会话知识库使用自己的 memory_* 表。

打开、写入、移动、删除、恢复和导入操作会记录在运行日志中，内容包括操作 ID、数量和耗时，但从不记录笔记内容。这些日志行使用 knowledge 事件；未设置 VLX_LOG_DIR 时，由 VLX_KNOWLEDGE_LOG_DIR 指定其目录。导入记录保存在数据库中，并显示在「导入记录」页面上。要完整备份一个知识库，需要同时保留其文件夹和应用数据，后者保存着该知识库的回收站和导入记录。