会话知识库

本章介绍「会话知识库」「整理记录」和「已归档会话」。本地 Markdown 文件的管理、编辑和导入见本地知识库。

会话知识库保存知识、决策、约束和经验教训，按“项目 → 会话 → 条目”的层级组织。生成的条目单独存储：来源会话发生变化时，这些条目不会随之改变，你也可以手动编辑它们。会话知识库属于你所连接的 VelaTerm 后端，由该后端上的所有项目和会话共用；连接到另一台服务器时，看到的是那台服务器的知识库。

会话知识库与会话内容搜索相互独立。会话搜索查找的是原始对话中的文本，而知识库只搜索已保存的条目。VelaTerm 只在你要求时整理、保存和显示条目，不会自动将条目加入新会话。

整理会话

在左栏中右键点击会话或其标签页，选择「整理到会话知识库」。已归档的会话也提供同样的操作。
选择「智能体」：Claude、Codex、Grok Build、OpenCode、Pi 或 OMP。VelaTerm 会使用「设置 ▸ 智能体」中设定的可执行文件路径，或在 PATH 中查找该程序。找不到的智能体会标为「未安装或未配置」，无法选择。
可以选择「模型（可选）」和「思考程度」。「默认模型」和「使用智能体默认设置」表示由智能体自身的配置决定。模型列表与新建会话时使用的列表相同，只有提供思考程度档位的模型才会显示这些档位。VelaTerm 会记住你上次使用的智能体、模型和思考程度。智能体必须已登录，并有权使用所选模型。
点击「整理并保存」。所选智能体会收到该会话的文本，并按其自身的模型配置进行处理。
在「整理记录」中跟踪任务进度。关闭对话框不会停止任务。

如果有智能体的对话记录，VelaTerm 会读取该记录；否则，它会使用会话的终端录制（见终端使用），并去除其中的终端控制码。两者都无法读取时，会提示「此会话暂无可读取的对话内容。」终端录制包含屏幕上可见的文本，其中可能有重绘的内容，因此负责整理的智能体不应将这类输出视为已核实的事实。

来源快照保存整理时读取的文本。项目和会话名称在会话首次加入时保存；之后如果在其他地方重命名、移动、归档或删除该项目或会话，这些名称不会随之更新。

再次整理某个会话时，会重新读取该会话，并替换之前从中生成的条目，包括你手动所做的修改；即使文本和模型设置都没有变化，也是如此。如果该会话已有未完成的任务，新任务会取代它。如果旧任务已在运行，新任务会在旧进程停止后自动开始（「等待本会话的上一项整理停止后，将自动开始。」）；旧任务仍保留在记录中。

整理过程

整理分为三个阶段，并作为任务进度显示：

提取主题：分段读取会话，并提取可复用的知识。主题只在本次任务内合并，不会使用其他会话的条目或之前的手动修改。
合并知识：将每个主题下的各部分内容合并，并保留其中的知识、约束和不确定之处。智能体会被要求考虑后续的更正和相互矛盾之处，不得编造结论。
保存条目：VelaTerm 检查字段、来源、链接和版本，并在单个数据库事务中替换该会话的生成条目。标题相同的条目保留原有身份，并新增一个修订版本。不再生成的条目会连同其修订历史一起删除，指向它们的链接也会被移除。如果整理成功但没有找到可复用的内容，该会话原有的生成条目会被清空（「本次未提取到可复用知识，该会话已有的生成条目已清空。」）。检查未通过、任务被取消或出现版本冲突时，原有条目保持不变，也不会保存任何部分结果。

智能体返回结构化内容，所有数据库修改都由 VelaTerm 执行。条目之间可以相互链接，「反向引用」列表会自动计算。即使原始会话已被删除，来源快照和修订历史仍然可用。

整理出的知识质量如何，仍需你自行判断。如果内容有误，可以编辑条目或恢复到较早的修订版本；恢复操作会创建一个新的修订版本，并保留被替换的版本。

整理记录

「整理记录」列出整理任务，每页 40 条。每个任务都会显示智能体、模型（未选择时显示「默认模型」）、思考程度和时间；正在运行的任务还会显示当前阶段（「提取主题」「合并知识」或「保存条目」）。任务状态为「等待开始」「进行中」「正在取消」「已完成」「失败」或「已取消」，可以从列表中打开其「来源快照」和生成的条目。

「取消」会停止正在等待或运行的任务。正在运行的任务会一直显示「正在取消」，直到智能体进程停止。取消不会删除来源快照。
「重试」会使用相同的来源快照、模型和思考程度，重新启动失败或已取消的任务。记录中显示的是任务创建时的设置；显示为默认选项，表示由智能体自行决定，而不是 VelaTerm 解析出了某个具体模型。

不同的会话可以并行整理。每个会话同一时间只运行一个任务；再次提交时只保留最新的等待任务，不会形成队列。等待中的任务保存在数据库中，应用重启后会继续执行。正在运行的任务如果两分钟未报告进度，会被标记为已中断（「整理任务已中断，可重试处理已保存的来源快照。」）。等待所花的时间不计入任务的时间上限。

整理进行期间仍可编辑条目。如果在任务进行期间有人编辑或删除了该会话的生成条目，任务会报告版本冲突，你所做的修改会被保留，之后可以重试。不同会话中的条目可以使用相同的标题，但同一会话内的标题必须唯一。

浏览和维护条目

从右栏打开知识库（见本地知识库），然后按项目、会话和条目逐级展开「会话知识库」。点击项目或会话可列出其中的条目，点击条目即可阅读。「返回上一级」按钮会返回上一级页面。

列表页提供搜索（「搜索条目标题与正文…」）、标签筛选（「全部标签」）、排序（「最近更新」或「按标题排序」）以及刷新。搜索范围包括标题、摘要、正文和标签，支持多个词（必须全部匹配），标题匹配的结果排在前面；每条结果还会列出与其直接关联的条目。没有精确匹配时，会像本地知识库搜索一样显示近似匹配。
会话的条目每页显示 40 条；项目和会话列表不受此限制，树中较长的列表会提供「加载更多」。
条目页面显示 Markdown 正文、「关联条目」「反向引用」「来源」和「修订历史」。你可以直接编辑正文并用 ⌘S / Ctrl+S 保存，也可以通过「编辑」修改标题、摘要和标签，或者选择「导出 Markdown」「复制到本地知识库」或「删除」。删除条目会同时删除其修订历史，但会保留来源会话及其快照。
「新建条目」用于手动创建条目，这类条目显示在「手动创建」分组中。

树中还支持以下管理操作：

右键点击条目可以重命名或删除它；将条目拖到另一个会话上，可以将其改归该会话。
右键点击项目分组或会话分组，可以重命名该分组或删除其中的条目。重命名分组时，对应的实际项目或会话也会一并重命名。删除分组只会删除其中的知识条目：「删除该组内的全部 N 条知识条目？项目或会话本身保留。」
将会话拖到另一个项目上，会把实际的会话移到该项目中。
「手动创建」「历史合并条目」和「来源项目未知」这几个分组无法重命名。

条目页面、编辑表单、来源快照、修订版本、整理对话框和整理记录都有各自的 URL，所选的项目、会话、搜索、筛选、排序和页码也都包含在 URL 中。

已归档会话

已归档的会话在知识库中管理。「已归档会话」显示在知识库树中「会话知识库」的旁边，按来源项目对已归档的会话分组；左栏顶部的「已归档会话」按钮也会打开同一位置。

主区域按项目列出所有已归档的会话。打开某个会话后，会显示两个标签页：「对话」显示完整对话，「知识条目」显示从该会话生成的条目。
「搜索归档内容…」只搜索已归档会话的全文，并按会话对匹配结果分组。
打开已归档的会话后，可以选择「恢复为正常会话」「整理到会话知识库」「导出完整上下文为 Markdown」（适用于 Claude 和 Codex 会话）以及「彻底删除（连带录制）」。彻底删除会立即生效，没有确认步骤。
归档、恢复和删除会话都不会改变已有的知识条目，因为条目和来源快照是单独存储的。恢复后的会话可以继续原来的对话。

早期版本的数据

VelaTerm 升级旧数据时，只有一个来源会话的条目被归入该会话。已经合并了多个会话的条目完整保留在「历史合并条目」分组中；这些条目不会被拆分，再次整理其中任何一个会话也不会替换它们。没有来源的条目归入「手动创建」。仍然存在的项目信息已在升级时一次性补全；无法确定所属项目的来源列在「来源项目未知」下，并保留其原始会话名称和快照。

数据与限制

会话知识库存储在应用的 SQLite 数据库中（memory_* 表），与会话搜索索引相互独立。界面只保存当前显示的内容和尚未保存的表单输入；校验、版本检查、重复检测以及所有写入操作都在后端完成。

一个来源最多包含 2,000,000 个字符，每个提取分段最多 24,000 个字符，单次模型输入最多 350,000 个字符，单个条目正文最多 200,000 个字符。
每次调用智能体最多运行 10 分钟，其每个输出流最多产生 8 MiB 数据。
对于 OpenCode、Pi 和 OMP，单次调用传入的文本不超过 128 KiB。
如果智能体返回的输出不符合预期结构，VelaTerm 会要求它重新输出，最多三次。

超出上述限制时，任务会明确报错（「来源、上下文或输出超出支持的大小，未截断内容，也未保存条目。」），不会截断后再保存。

整理过程记录在应用数据目录下的 logs/runtime-*.log 中。未设置 VLX_LOG_DIR 时，由 VLX_MEMORY_LOG_DIR 指定日志目录。VLX_MEMORY_LOG_LEVEL=error 只记录错误，设为 off 则关闭此模块的日志。日志记录任务与阶段、输入和输出数量、耗时、字符数、SHA-256 摘要以及 token 用量，但从不记录完整的提示词、来源文本、模型回复、凭据或错误输出；原始材料保存在来源快照中。

与代码图谱的关联

知识条目可以关联到代码符号，条目页面上的「代码引用」可以跳转到代码图谱。关联的文件发生变化后，条目会显示需要复核；确认复核不会改变条目的正文。会话中的智能体可以用 vkb 查询代码和条目。详见代码图谱与知识库。