Tolaria 的 Vault 文件布局：扁平结构、递归扫描与特殊目录约定

Tolaria 的 Vault 文件布局：扁平结构、递归扫描与特殊目录约定

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

Tolaria 是一款以 Markdown 为源、以 Git 为同步介质的桌面知识库应用，它对 vault 的目录组织“不强加意见”：笔记可扁平铺在根目录，也可放进任意子文件夹，真正的组织结构来自 frontmatter 中的type字段与 wikilink 关系。本文基于 site/reference/file-layout.md 这份官方参考文档展开，结合 Rust 扫描器源码与设计决策记录（ADR），讲清楚 Tolaria vault 中每一类文件应该放在哪里、为什么这样放，以及扫描器在底层如何处理这些约定。

一、总览：一个典型的 Tolaria vault

官方文档给出的标准布局如下：

my-vault/ project-alpha.md weekly-review.md research/ source-notes.md attachments/ diagram.png source.pdf project.md person.md views/ active-projects.yml

仓库中的示例 vault demo-vault-v2 正是这个布局的完整实例：根目录散落着25q1.md、person-luca-rossi.md等笔记，demo-vault-v2/views/active-projects.yml 是一个保存的自定义视图，demo-vault-v2/attachments/ 存放图片附件，demo-vault-v2/type/ 下则是各类类型的定义文档（如 project.md、person.md）。

需要说明的演进背景：早期 Tolaria 曾要求按类型建文件夹（project/、person/、topic/），但后来在 docs/adr/0006-flat-vault-structure.md 中改为“所有用户笔记是扁平的根目录.md文件，类型只由type:frontmatter 决定”。随后 docs/adr/0033-subfolder-scanning-and-folder-tree.md 又放宽了扫描约束：扫描器开始索引所有可见子目录中的.md文件，并暴露折叠式文件夹树。因此今天的官方立场就是文档开头那句话——Tolaria 不关心你的文件夹结构，它在整个 vault 中递归发现笔记，新笔记默认存到根目录，类型和关系才是组织知识的真正手段。

二、根目录笔记：类型不来自文件夹，而来自 frontmatter

文档中 "Root Notes" 一节的核心结论有两条：

1. 文件夹是可选的。扁平 vault 体验最好；文件夹可以为了兼容其他工具（Obsidian、纯文件管理习惯）而存在，但对人物、项目、主题等任何笔记类别都不是必需的。
2. 类型绝不从文件夹位置推断。它来自 frontmatter 的type字段，关系（relationships）则通过字段中的 wikilink 表达。侧边栏、Properties 面板、搜索、自定义视图和邻域（neighborhood）导航都消费这一套元数据，而不是目录路径。

这意味着改一个笔记的类型只是一次 frontmatter 编辑，不涉及移动文件，也不会打断指向它的 wikilink——这正是 ADR-0006 相对“类型文件夹”方案的直接收益：wikilink 解析被简化为基于标题/文件名的多轮匹配，无需路径感知。

三、特殊文件夹约定

文档用一张表格列出了两个有特殊含义的目录：

3.1views/：自定义视图目录

自定义视图是.yml文件，每个文件定义一个命名的过滤笔记列表，包含过滤条件、可选的图标/颜色和排序偏好。docs/adr/0040-custom-views-yml-filter-engine.md 给出了标准格式：

name: Active Projects icon: rocket color: blue sort: "modified:desc" filters: all: - field: type op: equals value: Project - field: status op: not_equals value: done

过滤条件支持all/any组合的 AND/OR 树，可用操作符包括equals、not_equals、contains、not_contains、any_of、none_of、is_empty、is_not_empty、before、after。之所以选独立的.yml文件而非数据库表或“特殊笔记”，是因为它们能随 Git 同步、可手工编辑、且与笔记内容天然分离。

两个值得注意的实现细节：

• 目录已迁移。ADR-0040 最初把视图放在.laputa/views/（隐藏目录），但当前源码 src-tauri/src/vault/view_migration.rs 实现了从旧位置.laputa/views到新位置views/的自动迁移——legacy_views_dir与current_views_dir两个函数明确界定了新旧路径，迁移后删除空的旧目录。这与官方文档表格中views/位于 vault 根目录的约定一致。
• 视图目录会出现在文件夹树中。源码 src-tauri/src/vault/mod.rs 的scan_vault_folders测试 folder_and_file_kind.rs 断言根目录文件夹树会列出attachments、projects、views等目录，即这些“特殊目录”对用户是可见、可浏览的，只有真正的隐藏目录被剔除。

3.2attachments/与非 Markdown 文件

PDF、图片和其他非 Markdown 文件保持普通文件的身份：文件夹浏览会把它们就地显示，设置项控制 PDF、图片和不支持的文件是否出现在 All Notes 列表中。文档还给出两条易被忽略的归类规则：

• 白板（whiteboard）属于笔记，不属于附件。它们是携带持久化 tldraw 数据的 Markdown 文件，因此和笔记放在一起（参见 docs/adr/0107-markdown-durable-tldraw-whiteboards.md）。
• 电子表格（spreadsheet）也是 Markdown 文件。带_display: sheet的笔记由普通 frontmatter 加上 CSV 风格正文构成，在 sheet 编辑器中打开（参见 docs/adr/0134-sheet-nodes-with-plain-text-workbook-storage.md）。

3.3 类型定义文档

类型定义是带type: Typefrontmatter 的 Markdown 笔记。按 docs/adr/0096-root-created-type-documents.md 的决策，新建的类型文档是普通笔记；而旧 vault 中位于type/文件夹的类型定义文档仍然可用。源码中有一个配套的排除逻辑：src-tauri/src/vault/mod.rs 定义了FOLDER_TREE_EXCLUDED_DIRS: &[&str] = &["type"]，注释写明“让类型定义留在它们专属的侧边栏区块，而不是通用的文件夹树里”——也就是说type/目录在扫描索引时是可见的，但在侧边栏 FOLDERS 树中被隐藏，避免与 TYPES 区块重复出现。

四、扫描器如何落地这些约定：源码级解析

官方文档描述的是约定，而约定的执行者是 Rust 侧的 vault 扫描器 src-tauri/src/vault/mod.rs。关键行为可以逐条对应：

1. 全 vault 递归扫描，隐藏目录被排除。scan_all_files（L418-L449）用walkdir从 vault 根递归遍历，filter_entry跳过隐藏目录，同时跳过以.开头的隐藏文件：

/// Directories hidden from user-facing vault scans. const HIDDEN_DIRS: &[&str] = &[".git", ".laputa", ".DS_Store"]; fn is_hidden_dir(name: &str) -> bool { name.starts_with('.') || HIDDEN_DIRS.contains(&name) }

因此.git/、.laputa/、.DS_Store以及一切点开头目录都不会进入笔记列表，这解释了文档中“Git 文件”一节的说法：如果 vault 是 Git 仓库，.git/属于 Git 本身，Tolaria 会读取 Git 状态（用于创建/修改时间等），但绝不把.git/当作笔记处理。

2. 文件分类决定展示位置。classify_file_kind（L350-L386）按扩展名把文件分为三类：md/markdown→markdown；一个较大的可编辑文本扩展名清单（yml、json、txt、ts、rs、html等 60 余种）→text；其余 →binary。无扩展名文件还会按名称匹配makefile、dockerfile、.gitignore等特例。这套分类正是“设置项控制 All Notes 是否显示 PDF/图片/不支持文件”背后的数据结构：UI 按file_kind过滤，而文件本身仍完整保留在磁盘和文件夹视图中。

3. Git 日期优先于文件系统日期。扫描时每个文件会先在git_dates映射（lookup_git_dates，L391-L398）中查找 Git 记录的创建/修改时间，查不到才回退到文件系统时间。回归测试 modified_dates_tests.rs 验证了“取 Git 与文件系统修改时间中较新者”的排序行为——这是 vault 通过 Git 同步后列表顺序仍然稳定的原因。

4. 扫描前恢复未完成的重命名事务。scan_vault入口（L453-L483）在解析任何文件之前会调用rename::recover_pending_rename_transactions，确保崩溃安全重命名（见 docs/adr/0075-crash-safe-note-rename-transactions.md 的机制）在每次扫描时得到补齐，避免遗留的临时文件污染 vault 内容。

5. 文件夹树独立于条目缓存。侧边栏的 FOLDERS 区块由独立的scan_vault_folders生成（ADR-0033 选择该方案而非给条目加folder字段，就是为了避免文件夹增删时的缓存失效问题）：它只收集目录、剔除隐藏目录与type/、按名称排序，返回FolderNode树。

五、实战建议：如何组织你的 Tolaria vault

把以上机制串起来，官方文档隐含的组织策略可以总结为：

• 日常笔记直接放根目录，命名清晰即可；type、status等 frontmatter 字段负责分类，wikilink 负责建立关系。侧边栏、搜索、自定义视图全部基于这套元数据工作，文件夹不参与判断。
• 需要子目录时随意使用（PARA、项目子目录均可），只要不放隐藏目录即可被完整索引；但如果依赖文件夹做过滤，从源码结构看当前版本仅在选择文件夹时展示其直接子项，递归文件夹过滤仍是 ADR-0033 留下的待评估项。
• 附件放attachments/，白板与电子表格笔记放正文区，视图配置放views/，类型定义文档可放type/或按新版惯例作为普通笔记管理。
• 保持 vault 是干净的 Git 仓库：.git/会被读取但不会被展示，视图文件的冲突可以按普通 YAML 文本用 Git 合并解决。

这套“文件即数据、文件夹仅为人眼服务、元数据为机器服务”的布局，是 Tolaria 在多端 Git 同步和 AI Agent 直接操作 vault 场景下保持低摩擦的基础。

参考文件

• site/reference/file-layout.md —— 本文主体参考文档
• src-tauri/src/vault/mod.rs —— 扫描、隐藏目录、文件分类与文件夹树实现
• src-tauri/src/vault/view_migration.rs —— 视图目录迁移逻辑
• docs/adr/0006-flat-vault-structure.md、docs/adr/0033-subfolder-scanning-and-folder-tree.md、docs/adr/0040-custom-views-yml-filter-engine.md —— 布局演进决策
• demo-vault-v2/ —— 符合上述布局的完整示例 vault

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