笔记留在本地，AI可以换：Tolaria的知识库设计

准备一轮订单回归，需求说明在一个文件夹，历史缺陷散在复盘里，用例又有单独的表格。材料都在，AI也能读，生成的清单却可能引用了已经过期的取消规则。

接着换个Agent，还要重新说明一遍：哪份文档生效、哪些记录只是历史、哪些文件允许修改。

这样的知识库，文件数量增加得很快，重新交代背景的工作也跟着增加。

Tolaria提供了一种组织方式：用桌面应用管理本地Markdown文件，给笔记加类型、属性和关系；需要AI时，再接入本机的编程Agent或模型服务。这里的Agent，是能调用工具执行任务的AI助手。笔记可以换编辑器，AI也可以换，文件继续留在原来的知识库里。

它使用Tauri、React和TypeScript构建，桌面端面向macOS、Windows和Linux，iPhone、iPad版本仍处于TestFlight测试阶段。仓库采用AGPL-3.0-or-later许可。

本文依据2026年11月14日仓库main分支的文档与源码展开，未安装运行应用。后面的订单回归案例是模拟设计，具体界面和功能以所用发行版为准。

文件继续是文件，组织方式可以多一层

Tolaria把存放笔记的文件夹称为vault，也就是知识库。Markdown正文、图片和PDF附件，都保存在普通文件里。笔记属性写在文件开头的YAML区域，也就是由---包住的一组键和值。应用的缓存和界面状态由这些文件派生。

这意味着，关闭Tolaria以后，笔记仍然能被其他编辑器打开。AI修改笔记会落到具体文件上，改了哪些内容，可以逐处检查。

当前使用文档明确支持直接打开普通Markdown文件夹。Git版本管理是可选能力：启用后可以查看差异、保留历史、提交修改，再按需要连接远程仓库。**保存笔记、本地提交和推送远程，是三件不同的事。**没有配置远程仓库，也能保留本地版本记录。

组织笔记时，Tolaria更偏向类型与关系。

例如，一份文档可以在开头写上type: Project，成为项目笔记；另一份写type: Procedure，成为操作流程。文件放在哪个目录，不决定它的类型，移动文件也不会自动改变类型。

类型定义本身也是Markdown：写上type: Type，就能定义侧栏显示、图标、颜色和新笔记模板。需要常用筛选时，可以把视图保存为views/下的文件，组合类型、状态、日期等条件。

关系通过双向链接表达。例如，一份故障复盘可以用belongs_to关联项目，再用related_to连接需求和修复记录。Tolaria会展示这些关联，也能为默认关系计算反向连接，减少手工维护两份链接的工作。

不过，类型只是组织和导航的约定。type: TestCase不会让一篇文字自动变成合格用例，更不会验证前置条件、步骤和断言是否完整。需要强校验时，仍要接专门的规则或检查工具。

依据：知识库与Git、类型、关系。

接入AI，要分清谁负责聊天，谁能够改文件

Tolaria当前有几种接入方式，能力差别会直接影响使用流程。MCP是一种让AI客户端调用外部工具的协议，这里通过它提供搜索和读写笔记等功能。CLI则是可从终端启动的命令行程序。

接入方式	能做什么	使用前提
应用内的编程Agent	通过工具查找、读取和编辑知识库，界面展示执行过程	本机已有相应CLI及认证，具体工具受适配器和权限配置影响
直接连接模型	根据当前笔记、关联上下文和对话记录回答问题	配好本地模型服务或远程模型接口；该模式不提供知识库写入工具和Shell权限
外部工具通过MCP连接	从外部助手调用笔记搜索、读取、创建、更新等能力	显式完成MCP配置，由客户端决定怎样调用和审批

当前文档列出的编程Agent包括Claude Code、Codex、GitHub Copilot、OpenCode、Pi、Antigravity CLI、Kiro和Hermes Agent。各个Agent仍负责自己的认证、工具和运行行为，Tolaria负责接入与展示。

直接模型则可以连接Ollama、LM Studio，也可以使用OpenAI、Anthropic等提供方或兼容接口。因此，本地保存笔记不等于调用远程模型时内容绝不离开设备，仍要看实际选择的服务与提交的上下文。

权限名称也需要按实际能力理解。**Vault Safe允许文件、搜索和编辑操作，不能当成只读模式。**Power User可为支持的Agent开放Shell操作；不同CLI的权限开关并不完全一样，不能仅凭统一界面上的名称推断相同的隔离效果。

外部MCP接入有单独的显式配置流程。设置对话框可以写入受支持客户端的配置，也可以复制JSON供手工配置；关闭对话框不会改动第三方配置文件。

围绕资料讨论，可以用直接模型；需要整理和维护笔记，就选择具备写入工具的Agent或MCP客户端，并安排修改后的检查。

依据：AI能力说明、不同适配器的权限语义。

写笔记之前，先确认读到的版本还有效

界面、原生后端与AI工具服务，在仓库里分开实现。

位置	对应职责
`src/`	React界面、笔记编辑和用户交互
`src-tauri/src/`	Rust原生后端，承担文件、Git和本地运行等能力
`mcp-server/`	向AI工具开放知识库操作，使用Node.js实现
`site/`	面向使用者的概念与操作说明
`docs/adr/`	记录架构选择、替代方案和代价

以外部MCP工具为例，调用先在mcp-server/index.js中按工具定义进入，再交给tool-service.js选择知识库、组织操作；vault.js负责具体的文件读取与写入。更新完成后，服务层发送vault_changed通知，让应用刷新。

其中一项设计与维护知识库很有关系：读取笔记时，get_note会返回修改时间mtimeMs。更新已有笔记的update_note可以携带expectedMtime，也就是读取时记住的那个修改时间。

假设Agent读完一份回归清单，还在生成补充内容，测试负责人已经手动改了同一份文件。Agent如果带着旧修改时间写回，当前实现会检查时间是否匹配；检测到变化，就拒绝这次更新，让调用方重新读取。

这个参数是可选的。调用方没有传入，就没有启用这项检查。

update_note替换的是完整笔记，包括属性与正文。它会先在旁边写临时文件，再替换目标文件，以减少中途写入失败留下半截正文的风险。它没有提供字段级合并策略，保留哪些属性、怎样整合两次修改，仍由调用方处理。

还有两个不同用途的工具：create_note用于创建新文件，拒绝覆盖已有文件；append_to_note用于向已有笔记追加内容。追加适合记录过程，完整更新适合维护当前状态，不能不看任务就互相替换。

修改时间检查和临时文件替换分别处理不同问题，也不能合起来视为完整的多Agent并发事务。涉及共享资料时，先生成候选、再审核写回，仍然更容易控制。

依据：工具服务实现、文件操作实现。

模拟：把订单取消资料整理成回归候选

设定一个测试团队的使用场景：发布前，需要从需求和历史缺陷中整理订单取消的回归范围。目的只是准备待审核的候选用例，不连接业务系统，不执行退款，也不修改真实订单。

本节的文件、规则、缺陷和预期结果均为模拟示例，不代表Tolaria自带业务知识或已经完成测试。

先放进能互相找到的资料

模拟知识库先准备三份Markdown：

模拟文件	内容与作用
`订单服务.md`	项目范围与资料入口
`取消订单规则.md`	未支付订单可直接取消；已支付订单进入退款确认；重复请求应保持幂等
`取消订单缺陷复盘.md`	历史问题设为重复点击后产生两条退款记录，用于提醒补充回归

幂等在这里指：同一订单重复提交相同请求，不应多产生一次退款等业务副作用。这是模拟业务规则，需要用实际系统要求替换。

为一份既有用例增加类型和关系，可以写成下面的形式。它展示的是文件格式，不是运行输出：

---
type: TestCase
status: Active
belongs_to:
  - "订单服务"
related_to:
  - "取消订单规则"
  - "取消订单缺陷复盘"
---

这样，项目、规则、复盘和用例之间就有了可跟随的连接。类型字段负责分组，具体业务正确性仍要看正文。已有文件夹也可以保留，不必为了接入Tolaria先做一次全库搬家。

让Agent先找资料，再生成候选

可以在知识库根目录的AGENTS.md里写清本团队的处理规则。以下是模拟任务说明：

任务：根据订单取消规则和缺陷复盘，整理回归候选。
先读取项目入口，再查找并读取相关规则、历史缺陷和已有用例。
候选必须注明来源文件、适用状态、前置条件和预期结果。
来源冲突时保留冲突说明，不自行决定哪份规则生效。
只新增“取消订单回归候选.md”，不覆盖既有规则与用例。
不连接订单环境，不执行退款，不提交或推送Git。

Tolaria的MCP上下文工具能够返回知识库根目录的AGENTS.md内容。不过，这份文件表达的是团队约定，不能单靠提示词证明权限已经被技术强制限制；可用工具与客户端配置仍需对应检查。

在这个组合使用方案中，演示期间先关闭自动提交、自动同步等后台Git动作。Agent可以先用search_notes找相关笔记，再用get_note读取正文和属性，沿链接核对来源，最后用create_note生成候选文件。

**搜索命中只说明找到相关文字，不说明已经找到全部规则。**Tolaria的搜索采用关键词路线；面对取消、关单、撤销等不同说法，任务里应安排别名检索和关系追踪，不能默认有一套向量检索替代这些步骤。

输出要能审，不能只看起来完整

按前面的模拟规则，预期候选至少应覆盖未支付取消、已支付后的退款处理、重复取消或退款请求。每条都要能追到对应的需求或历史缺陷，缺少订单状态、权限或异常分支资料时，就把缺口写在候选里。

审核可以围绕四个问题进行：

已支付订单是否仍被错误归入直接取消？
重复操作是否检查了业务副作用，而非只检查界面提示？
每条预期结果是否有可定位的资料依据？
本次是否只新增候选文件，保留了原有资料？

审核通过后，才进入正式用例维护。需要更新已有文件时，可以采用下面的调用顺序。

// 模拟伪代码：说明MCP工具的使用顺序，不是可直接运行的SDK。
const note = await get_note({
  path: "取消订单回归清单.md"
});

// 根据读到的frontmatter和正文，保留原属性并生成完整Markdown。
const fullMarkdown = composeReviewedMarkdown(note);

await update_note({
  path: "取消订单回归清单.md",
  content: fullMarkdown,
  expectedMtime: note.mtimeMs
});

如果检测到文件已变化，应重新读取、重新核对，不要去掉expectedMtime后强行覆盖。多知识库中有同名文件时，还应显式传入目标vaultPath，避免把写入位置交给猜测。

预期收益是减少找资料和重新组织内容的工作，并留下可以检查的候选与修改记录。是否真的减少遗漏、节省时间，要在同一批材料上比较准备耗时、来源错误和审核返工，当前模拟没有提供收益数字。

这个流程也能迁移到事故复盘整理、客服规则维护和发布检查表。迁移时改变的是业务规则，查来源、生成候选、审核写回的顺序可以保留。

从一小份知识库开始使用

macOS可以使用官方文档给出的安装命令：

brew install --cask tolaria

Windows、Linux可以从项目发布页选择对应安装包。首次打开时，可以选Getting Started示例库，也可以打开一份已有Markdown文件夹。

尝试已有知识库时，先选一份小范围副本：确认笔记能正常打开，属性能识别，链接能跳转。Cmd+K或Ctrl+K打开命令面板；需要历史记录时，再显式启用Git。

随后在设置中选择AI目标。编程Agent需要先在本机安装并完成自己的认证；只需要围绕笔记讨论，也可以配置本地或远程模型。进入AI面板后，从查找关联资料、总结当前笔记这样的小任务开始，涉及写入就检查文件差异。

安装命令来自官方说明，这里没有执行。首次尝试也不必把所有资料、所有Agent和所有自动化一次接齐。先完成一份候选清单，再核对来源与改动，比同时接入所有助手更容易判断是否适合。

留得住的，是文件和修改的来路

Tolaria的组织方式适合经常更换AI工具、又希望长期保留资料的团队。Markdown提供可读的内容，类型与关系帮助寻找上下文，Git在启用后记录改动，Agent负责执行具体任务。

知识库里的文件以后可能越来越多，但一份规则什么时候改过、根据什么改、是否经过审核，依旧需要留下来。

模型可以换得很勤。几个月后重新接手项目的人，通常还是会先找那份解释清楚的文档。

项目地址：https://github.com/refactoringhq/tolaria #Tolaria #Markdown知识库 #AIAgent #测试开发