Tolaria 的 Vault 文件布局扁平结构、递归扫描与特殊目录约定【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolariaTolaria 是一款以 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 一节的核心结论有两条文件夹是可选的。扁平 vault 体验最好文件夹可以为了兼容其他工具Obsidian、纯文件管理习惯而存在但对人物、项目、主题等任何笔记类别都不是必需的。类型绝不从文件夹位置推断。它来自 frontmatter 的type字段关系relationships则通过字段中的 wikilink 表达。侧边栏、Properties 面板、搜索、自定义视图和邻域neighborhood导航都消费这一套元数据而不是目录路径。这意味着改一个笔记的类型只是一次 frontmatter 编辑不涉及移动文件也不会打断指向它的 wikilink——这正是 ADR-0006 相对“类型文件夹”方案的直接收益wikilink 解析被简化为基于标题/文件名的多轮匹配无需路径感知。三、特殊文件夹约定文档用一张表格列出了两个有特殊含义的目录文件夹用途views/保存的自定义视图YAML 文件attachments/图片与其他附件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_filesL418-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_kindL350-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_datesL391-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考