Tolaria 文件与媒体处理指南：Markdown 可持久化的图表、附件、预览、HTML 与白板-开发者社区

Tolaria 文件与媒体处理指南：Markdown 可持久化的图表、附件、预览、HTML 与白板

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

Tolaria 是一个以 Markdown 笔记为核心的桌面知识库管理应用，但一个 Vault（笔记库）绝不止于.md文件——它还可以承载图片、PDF、音视频、独立 HTML 文件、白板以及其他本地文件。本篇指南围绕 Tolaria 的文件与媒体子系统展开：你将掌握 Mermaid 图如何以纯文本形式持久化在笔记中、粘贴的远程图片如何被安全导入本地、图片/PDF/媒体的应用内预览与回退策略、独立 HTML 文件的沙箱化预览边界、tldraw 白板的 Markdown 存储格式，以及被 Git 忽略的内容如何在 Vault 中按边界过滤。文中所有机制均有仓库源码与 ADR 决策记录作为依据，可直接用于日常使用与二次开发排查。

从笔记到文件：Tolaria 的 Vault 文件模型

Tolaria 的核心文件模型以「文件系统为事实来源」为第一原则（参见 ADR-0002）：笔记是普通的 Markdown 文件，图片、PDF、音视频、白板与 HTML 同样是 Vault 中真实存在的文件。Vault 扫描器会为每个文件标记fileKind（如markdown、text、binary，见 ADR-0041），而文件的预览能力不是持久化的 schema 字段，而是由渲染层根据文件扩展名推断出来的——这一约束在多个 ADR 中被反复强调，保证了新增媒体类型时无需迁移缓存结构。

在这个模型下：

Markdown 笔记内可以引用或嵌入其他文件；
二进制文件保持「普通 Vault 条目」的身份，不引入专有文档类型；
所有资源路径遵循便携的attachments/...相对路径约定（由 src/utils/vaultAttachments.ts 统一解析）。

Mermaid 图：Markdown 可持久化的图表

当笔记需要一张「应当保持纯文本、可被 Git 版本化」的示意图时，Tolaria 使用 Mermaid 代码块。在笔记中写入如下 Markdown 即可：

![mermaid](https://web-api.gitcode.com/mermaid/svg/eNpLy8kvT85ILCpR8AniUlDwTElNVNDVtVNwKUpMKwGzglLLMlPLwcyA0qSczOIMAKphEAg)

Tolaria 会在富文本编辑器中渲染 Mermaid 图表，同时让源码始终以 Markdown 形式存在——复制、关闭重开、进入 raw 模式都不会丢失原始围栏源码。

实现原理：Markdown 占位符往返（round-trip）

根据 ADR-0088，Tolaria 采用「编辑器管线自有的 Markdown 占位符往返」方案，与 wikilink、数学公式共享同一套架构。其核心链路为：

在 BlockNote 解析 Markdown 之前，先将围栏mermaid块转换为临时占位符（token 前缀为@@TOLARIA_MERMAID_BLOCK:）；
占位符被替换为mermaidBlock架构块，其中同时保存原始围栏源码（source）与图表正文（diagram）；
富文本编辑器通过mermaid包渲染该块；
保存、进入 raw 模式、以及编辑器位置快照前，mermaidBlock节点被序列化回其存储的围栏 Markdown；
当 Mermaid 无法渲染某段非法图表源码时，直接以内联形式显示原始源码，而不是破坏编辑器表面。

这段解析/序列化桥接逻辑集中在 src/utils/mermaidMarkdown.ts，它导出一个mermaidMarkdownCodec（DurableBlockCodec实现）。源码还揭示了一个细节：looksLikeMermaidDiagram会识别常见的 Mermaid 图表类型关键词，因此未标注mermaid语言、或语言为text/plain/plaintext的代码块，只要首条有效语句匹配，也会被自动注入为 Mermaid 块。识别到的图表类型包括flowchart、graph、sequenceDiagram、classDiagram、stateDiagram/stateDiagram-v2、erDiagram、journey、gantt、pie、mindmap、timeline、quadrantChart、requirementDiagram、gitGraph、C4Context、C4Container、C4Component、C4Dynamic、sankey-beta、xychart-beta。

渲染组件位于 src/components/MermaidDiagram.tsx，并有对应测试 MermaidDiagram.test.tsx 覆盖渲染与回退行为。

附件：粘贴即本地化，远程图片后台导入

Tolaria 的附件模型遵循「粘贴即落盘」的设计：粘贴到编辑器中的图片会作为普通文件保存进 Vault，保持可移植性，任何其他工具都能直接打开。

粘贴网页内容时的远程图片导入

当粘贴的网页内容包含符合资格的远程图片时，Tolaria 会在后台将这些图片导入attachments/目录，并把粘贴引用改写为本地路径——文本内容立即呈现，如果某张图片无法安全导入，其原始远程引用保持可编辑状态，而不是阻塞整个粘贴操作。这是 ADR-0162 确立的「先粘贴、后导入」模型：富文本模式与 raw 模式共用同一套远程图片提取/导入逻辑，但各自保留原生粘贴行为。

从 ADR 可以了解到 Rust 边界上的安全校验非常严格：

将每个下载目标解析为公网地址，并将 HTTP 客户端固定到该地址；
拒绝本地/私有/链路本地目标地址、URL 凭据、不支持的协议、不安全的跳转、非图片或不支持的 MIME 类型；
拒绝超过15 MiB的响应，以及超出有界连接/总超时的请求；
跳转（redirect）会重复同样的校验；字节在附件文件创建前先缓冲；
文件名取自最终 URL 的文件名主干加上校验后的 MIME 扩展名。

同时，私有网络图片与 SVG 明确不会被网页粘贴路径导入。成功保存的引用使用可移植的attachments/...表示，并复用现有的唯一附件路径所有权逻辑。下载失败时只会产生一条本地化的非阻塞消息，正文与已成功的图片不受影响。

便携附件路径解析

src/utils/vaultAttachments.ts 是附件路径解析的核心，它定义了三种可识别的便携路径前缀：

attachments/（相对前缀）
./attachments/（带点相对前缀）
/attachments/（根相对前缀）

vaultAttachmentPath根据 Vault 所在平台选择/或\分隔符；resolveVaultAttachmentPath依次尝试相对附件路径、Tauri 资源 URL 与原始路径，最终必须验证目标路径位于活动 Vault 之内才返回结果，并拒绝含..不安全段落的路径。attachmentAssetUrlFromPath通过 Tauri 的convertFileSrc生成资源访问 URL。相关测试见 vaultAttachments.test.ts 与 remoteImagePaste.test.ts。

预览：图片、PDF 与媒体文件

Tolaria 可以在应用内预览常见的图片文件、PDF 与受支持的媒体文件；没有应用内预览的文件仍然可以通过系统默认应用打开。

预览体系的关键设计（源自 ADR-0086 与 ADR-0110）：

单一渲染面：FilePreview（src/components/FilePreview.tsx）是唯一负责二进制文件预览的渲染层组件；
扩展名推断：预览能力由 src/utils/filePreview.ts 依据安全的扩展名白名单推断，而不是持久化的 schema 字段；
作用域资源访问：图片通过<img>、PDF 通过 webview 的 PDF 渲染器、音视频通过原生 HTML 媒体控件展示，全部经由 Tauri 作用域资源协议（convertFileSrc生成的asset://类 URL），不开放宽泛的文件系统读取；
外部打开走命令边界：委托操作系统打开文件前，必须先重新进入活动 Vault 的命令边界校验。

一个值得注意的平台差异来自 ADR-0121：由于 Linux AppImage 构建下的 WebKitGTK 音频/视频播放运行时不够稳定，AppImage 版本对音频/视频默认回退为「外部打开」控件，而图片与 PDF 预览在所有平台保持应用内。预览策略是运行时拥有的——渲染层先询问原生运行时是否需要外部媒体回退，再决定是否渲染音视频元素，因此编辑器内嵌的音视频块与文件预览遵循同一运行时门控，行为保持一致。

设置控制列表可见性

设置项控制 PDF、图片以及不受支持的文件是否出现在「所有笔记」（All Notes）列表中；文件夹浏览（Folder）视图始终按文件夹展示实际存在的文件。这意味着 All Notes 可以聚焦于笔记类内容，而文件夹视图保留文件系统的真实全貌。

HTML 文件：沙箱化的应用内预览

独立的.html与.htm文件可以在应用内以净化后的预览形式打开。本地图片、样式、字体与媒体文件，只要其路径保持在 Vault 内部即可正常工作。

预览模式会移除脚本、表单、嵌套 frame 与远程资源；如果需要编辑源码，切换到 raw 模式；当文件需要交互式浏览器行为时，则在默认浏览器中打开。这一设计来自 ADR-0168：

HTML 文件在编辑器窗格中通过净化过的、不透明源（opaque-origin）的 iframe 预览渲染，iframe 以srcdoc方式注入内容；
渲染器在设置srcdoc前移除脚本、事件处理器、表单、嵌套 frame、嵌入对象等活跃控件；
添加限制性的 Content Security Policy，禁用脚本、网络连接、workers、表单、嵌套 frame、对象与 base URL 变更；
iframe不授予allow-scripts与allow-same-origin，因此预览内容无法接触 Tolaria 的文档、存储或 Tauri IPC；
本地被动资源（图片、样式表）相对于 HTML 文件解析，仅当其归一化路径仍在活动 Vault 内时才接受，并转换为既有的作用域 Tauri 资源 URL；远程被动加载会被移除；
链接可在独立的带noopener/noreferrer的外部浏览上下文打开，既有的「默认应用打开」命令仍然可用。

预览占据与富文本编辑器相同的表面：面包屑的源码按钮或Cmd/Ctrl+\可将 HTML 文件切换到既有的 CodeMirror raw 编辑器（RawEditorView.tsx），正常保存行为适用；再次切换则基于当前标签页内容重建预览。渲染实现位于 src/components/HtmlFilePreview.tsx。

此外，如果你想在笔记内部嵌入一段静态 HTML，而不是打开整个 HTML 文件，Tolaria 的围栏html块走的是同一套沙箱思路：Markdown 可持久化的htmlBlock节点在净化后的沙箱 iframe 中渲染，可携带可选的height元数据（见 ADR-0154 与 HtmlBlock.tsx）。

白板：tldraw 画布，Markdown 存储

白板使用 tldraw 作为编辑器中的交互画布，但其持久化表示始终保持在 Markdown 中——这保证了白板与其余笔记一起留在 Vault 内、被 Git 版本化。

根据 ADR-0107，其实现路径为：

在 BlockNote 解析 Markdown 前，将围栏tldraw块转换为临时占位符；
占位符被替换为tldrawBlock架构块，存储稳定的白板 id与tldraw 文档快照 JSON；
富文本编辑器中用tldraw包渲染每个块；
tldraw 文档变更被防抖（debounce）写入 BlockNote 块属性，从而由 Tolaria 常规的自动保存机制把快照写回.md文件；
保存、raw 模式与编辑器位置快照前，tldrawBlock节点序列化回围栏 Markdown；
提供/whiteboard斜杠命令插入同样的块格式。

会话状态（如相机位置、选中形状、选中工具）不会被持久化进笔记；预览图在初始设计中也被有意排除。解析/序列化桥接位于 src/utils/tldrawMarkdown.ts，tldraw 运行时集成位于 src/components/TldrawWhiteboard.tsx，测试见 TldrawWhiteboard.test.tsx。raw 模式仍然是对围栏 JSON 的直接源码编辑器。

Git 边界：被 Git 忽略内容的可见性过滤

如果某些生成文件或仅本地文件被 Git 忽略，Tolaria 可以把它们从笔记、搜索、快速打开与文件夹中隐藏——适用于构建产物或私有本地文件不应表现得像 Vault 内容时的场景。

该功能由 ADR-0094 定义，关键设计是「扫描与缓存保持完整，过滤发生在命令边界」：

hide_gitignored_files是一个安装本地的应用设置，默认值为true（见 src/lib/gitignoredVisibility.ts 中的DEFAULT_HIDE_GITIGNORED_FILES，以及 src/types.ts 中的设置类型定义）；
可见性检查使用批量git check-ignore --no-index --stdin，尽可能贴近 Git 常规的忽略与否定（negation）语义；
list_vault、reload_vault、list_vault_folders与关键词搜索在设置开启时应用同一过滤；
切换该设置会重载当前 Vault 的各个表面，而不是重建另一种缓存格式；
如果 Vault 没有.gitignore，或该设置被关闭，Tolaria 显示完整扫描结果。

这种「完整扫描 + 边界过滤」的取舍在于：把 Gitignored 可见性做成每台安装的舒适偏好而非 Vault 共享元数据，搜索、文件夹列表与笔记重载始终一致地咨询同一过滤边界，缓存也能在不做数据迁移的情况下支持未来的可见性变化——用户关闭设置即可立即重新看到被忽略的内容。设置界面见 SettingsPanel.tsx，相关测试见 gitignoredVisibility 相关的 lib 与 hooks 测试。