Tolaria Vault 完全指南：打开现有文件夹、创建新 Vault 与多 Vault 并行使用的 Git 可选边界

Tolaria Vault 完全指南：打开现有文件夹、创建新 Vault 与多 Vault 并行使用的 Git 可选边界

【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria

Tolaria 是一个以“本地文件夹即数据库”为核心的 Markdown 知识库桌面应用，它的 vault（知识库）就是一个普通的磁盘文件夹。本文基于仓库中的 open-or-create-vault.md 展开，覆盖三条创建路径（打开现有文件夹、新建空 vault、使用 Getting Started 样例 vault）、多 vault 统一图的使用方式，以及“Git 推荐但非必需”这一设计决策背后的实现依据，帮助你在任何起点——纯 Markdown 目录、Obsidian 风格 vault 或 Git 仓库——都能正确接入 Tolaria。

Vault 是什么：磁盘上的一个文件夹

Tolaria 中 vault 的定义非常直接：它是磁盘上的一个文件夹，可以包含 Markdown 笔记、附件（attachments）、类型定义（type definitions）、保存的视图（saved views）以及 Git 元数据。文件系统是唯一事实来源，应用状态和缓存都由文件派生（参见 vaults.md 与 ADR-0002：文件系统作为事实来源）。

从仓库内置的示例 vault demo-vault-v2 可以看到一个典型 vault 的实际构成：

• 根目录下的扁平.md笔记文件（如 24q4-laputa-start.md），这是 ADR-0006 确立的扁平 vault 结构；
• type/子目录存放类型定义（如 type/note.md）；
• views/子目录存放保存视图（如 views/active-projects.yml）；
• attachments/子目录存放普通文件附件。

本地文件的关键意义在于：笔记始终可以用其他编辑器打开、用命令行工具搜索、用你自己的系统备份，Tolaria 不应成为读取数据的唯一途径。

打开一个现有文件夹

如果你已有 Markdown 笔记，直接选择“打开一个现有文件夹”即可。Tolaria 会扫描目录中的.md文件，并在存在 frontmatter 时解析它作为结构信息。适合直接打开的起点包括：

• 一个纯 Markdown 文件组成的文件夹；
• 一个 Obsidian 风格的 vault；
• 一个包含笔记的 Git 仓库；
• 一份 Getting Started 样例 vault 的本地副本。

在源码层面，欢迎界面的三个操作按钮分别对应模板克隆、新建空 vault 和打开文件夹：WelcomeScreen.tsx 中data-testid分别为welcome-create-vault、welcome-create-new与welcome-open-folder。当已注册的路径失效时，StartupScreen.tsx 会把 onboarding 状态置为vault-missing并回到同一个欢迎界面，携带缺失路径供重新选择。

值得注意的是，打开的文件夹不要求是 Git 仓库。从 ADR-0085 可以确认，非 Git 文件夹是一个受支持状态而非错误状态：打开时 Tolaria 会询问是否初始化 Git；如果用户忽略该提示，应用照常工作，但状态栏会常驻一个Git disabled警告。点击该警告，或从命令面板运行Initialize Git for Current Vault，可以重新打开初始化入口。

新建一个空 Vault

如果想要从零开始就遵循 Tolaria 的约定，可以新建 vault：Tolaria 会在你选择的空文件夹中创建新笔记，类型定义则为可选。新笔记和类型定义都是以 Markdown 文件形式落盘，与打开已有文件夹没有任何结构差异。

实现上，前端通过 Tauri 命令完成建库：useOnboarding.ts 中调用create_empty_vault并传入targetPath，由 Rust 后端在指定路径创建文件夹并写入初始内容。这条路径与打开文件夹的路径一样完全离线可用——从 ADR-0046 的 Consequences 部分可以确认，“空 vault 和打开文件夹路径保持完全离线”。

可选起点：Getting Started 样例 Vault

欢迎界面的第一个选项是克隆 Getting Started 样例 vault。它在运行时从公共仓库克隆到用户选择的文件夹（ADR-0046），而不是随应用打包，因此样例内容可以独立于应用版本更新。

这条路径有两个值得注意的实现细节：

1. 本地优先，克隆后断开远端：克隆完成后 Tolaria 会移除所有已配置的 Git remote，使样例 vault 默认成为 local-only 仓库——你可以随意编辑、本地提交、随时删除，而不会误推送到公共模板仓库（见 ADR-0070）。样例 vault 的具体内容构成（类型、wikilinks、表格、HTML 报告等）详见 getting-started-vault.md。
2. 失败可重试，离线时禁用：克隆失败会显示带“Retry download”按钮的错误（对应 WelcomeScreen.tsx 中的welcome-retry-template按钮，且 useOnboarding 会缓存lastTemplatePath以重试到同一文件夹）；在离线状态下该选项被直接禁用，避免误导用户等待一个不可能成功的下载。

同时使用多个 Vault

不需要把所有内容合并进一个文件夹。可以把每个本地文件夹注册为独立的 vault，然后在Settings->Vaults中开启Use multiple vaults at the same time。

开启后的行为边界（与 concepts/vaults.md 的描述一致）：

• 左下角的 vault 菜单可以控制哪些 vault 加入统一图（unified graph）；
• 搜索、快速打开（quick open）、wikilinks 和笔记列表可以横跨所有被包含的 vault；需要区分来源时，笔记会显示紧凑的 vault 徽标；
• 跨 vault 的 wikilink 使用目标 vault 的稳定别名，例如[[team/projects/alpha]]；同一 vault 内部的链接保持普通的 vault 相对链接；
• Git 状态、提交、同步、文件夹导航、保存视图和 vault 修复操作仍然只作用于当前选中的 vault 及其仓库——统一图是读侧能力，不改变写侧的仓库边界；
• 新笔记写入Manage vaults中设定的默认 vault，该入口还可以重命名 vault、选择颜色和设置默认落点。

Git 推荐，但绝不强制

原文档的核心立场是：Tolaria 对纯 Markdown 文件夹工作得很好——打开、编辑、整理、搜索都不需要 Git 仓库。Git 的价值在于本地历史、diff 视图、恢复、pull/push 以及不依赖专有后端的远端同步。

从仓库中的决策记录可以看到这条边界的完整实现：

• 显式初始化：init_git_repo是后来启用 Git 的唯一后端命令（ADR-0085）。它创建仓库、写入 Tolaria 默认的.gitignore、暂存整个 vault 并创建一个无签名的初始化提交。
• 能力按 vault 动态启用：非 Git vault 中，Git 历史、变更、提交、同步、冲突与远端操作全部隐藏或禁用，后台 AutoGit 检查点与自动同步也不会运行；而 Markdown 扫描、笔记浏览编辑、搜索照常工作。
• local-only 是合法状态：没有远端不代表异常（ADR-0059，被 ADR-0070 引用）。后续需要远端时，通过状态栏No remote芯片或命令面板的Add Remote走git_add_remote后端：它添加origin、fetch 远端，拒绝不兼容或领先的远端历史，确认安全后才开始跟踪（ADR-0070）。

小结

Tolaria 的 vault 接入模型可以归纳为三点：任何包含 Markdown 的文件夹都是一个合法的 vault，打开、新建、克隆样例三条路径中只有样例克隆依赖网络；多 vault 并行时，统一图负责跨 vault 的检索与链接，而 Git 操作严格保持单仓库作用域；Git 是一个可以随时显式开启的能力，而非打开 vault 的前置条件。理解了这些边界，你就可以在保留自己既有笔记目录结构的前提下，安全地迁移到 Tolaria 的工作流中。

【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria