Tolaria 是近期在 GitHub 开源的 macOS 桌面应用，专门用于管理 Markdown 知识库。该项目在发布后迅速获得 1700 余颗星标，由 Refactoring 创始人 Luca Rossi 开发，其核心理念是构建一个「AI 时代第二大脑」，支持本地优先、文件优先的知识管理范式。与传统的笔记应用不同，Tolaria 从设计之初就将 AI 代理交互纳入核心架构，通过 MCP（Model Context Protocol）协议实现与 Claude Code、Cursor 等 AI 工具的无缝衔接。本文将聚焦于 Tolaria 的多窗口管理、四面板布局、实时预览机制以及与 Obsidian、Heptabase 等现有生态的互操作设计，为开发者提供可复用的工程参数与架构参考。
四面板布局与响应式窗口约束
Tolaria 采用经典的四面板 UI 设计，灵感来源于 Bear Notes 的界面范式。从左至右依次为：侧边栏（Sidebar）、笔记列表（Note List）、编辑器（Editor）和检查器（Inspector）或 AI 面板。这一布局通过可调整大小的 ResizeHandle 组件实现，用户可以根据工作需求动态分配各面板宽度。侧边栏默认宽度为 150 至 400 像素，笔记列表为 200 至 500 像素，检查器为 200 至 500 像素或收起至 40 像素，编辑器占据剩余空间。
值得注意的技术细节是主窗口的最小宽度计算逻辑。useMainWindowSizeConstraints 钩子并非使用固定数值作为最小宽度阈值，而是基于当前可见面板组合动态计算。当用户仅打开编辑器时（对应 editor-only 模式），基准宽度为 480 像素；每增加一个可见侧边栏、检查器等面板，最小宽度相应累加。该逻辑通过 Tauri 原生命令 update_current_window_min_size 实时更新窗口约束，当用户切换视图模式或展开 / 收起检查器时，窗口会自动调整至合适的最小尺寸。值得注意的是，笔记独立窗口采用固定的 800×700 尺寸初始化，跳过了这一动态约束计算路径。
四面板的具体功能划分如下：侧边栏承载顶级过滤器（All Notes、Changes、Pulse）、基于类型的可折叠分组、文件夹树结构以及置顶笔记入口。笔记列表显示当前侧边栏筛选条件匹配的笔记，支持按任意属性排序、定制可见列配置，并提供 Neighborhood 模式展示当前笔记的关系网络。编辑器支持两种模式切换：WYSIWYG 模式基于 BlockNote 库实现富文本编辑体验，Raw 模式则使用 CodeMirror 6 显示纯 Markdown 源码。检查器与 AI 面板共享同一区域，通过面包屑栏的 Sparkle 图标切换 —— 前者展示元数据、关系、后向链接和 Git 历史，后者承载 AI 代理对话界面。
多窗口笔记编辑的实现机制
Tolaria 在 Tauri v2 框架基础上实现了多窗口支持，允许用户将笔记在独立窗口中打开以便专注编辑。触发新窗口打开的方式包括：命令 palette（Cmd+K 搜索 "Open in New Window"）、键盘快捷键 Cmd+Shift+O、菜单栏操作以及按住 Cmd+Shift 点击笔记列表中的任意笔记。
多窗口的技术实现依赖 src/utils/openNoteInNewWindow.ts 中的 openNoteInNewWindow() 函数。该函数调用 Tauri v2 的 WebviewWindow API 创建新窗口，URL 参数中携带窗口类型标识（?window=note）、笔记路径、保险库路径和窗口标题。main.tsx 在应用启动时通过 isNoteWindow() 检查判断窗口类型，从而路由至主窗口组件 App 或独立笔记窗口组件 NoteWindow。
NoteWindow 是一个精简的 shell，仅加载笔记条目、获取笔记内容、应用主题并渲染单个编辑器实例。每个独立窗口运行相同的自动保存逻辑（500 毫秒防抖，通过 Rust 的 save_note_content 命令写入磁盘）。Raw 编辑器在输入时同步在前端渲染派生自 frontmatter 的 VaultEntry 状态，使检查器和笔记列表能够即时响应，无需等待完整重载。窗口标签采用 note-* 模式命名（如 note-1738846825），与主窗口标签 main 一并在 src-tauri/capabilities/default.json 中配置权限。
这一架构的关键设计决策在于：无标签页模式（No Tabs）。Tolaria 通过 Cmd+[和 Cmd+] 实现导航历史替代传统标签页功能，这一设计在 ADR-0003 中有详细记录，核心理念是减少认知负担，让用户专注于当前笔记而非标签页管理。
实时预览与双模式编辑架构
Tolaria 编辑器的核心特色是双模式支持：WYSIWYG 模式与 Raw 模式。两种模式共享相同的箭头连字符解析逻辑（src/utils/arrowLigatures.ts），确保在模式切换时 ->、<-、<-> 等箭头的渲染表现一致，同时转义的 ASCII 序列保持字面意义不变。
WYSIWYG 模式基于 BlockNote 库（版本 0.46.2）实现，这是一个专为块级编辑设计的 React 组件库，支持富文本格式、嵌入内容以及最重要的 wikilinks 功能。用户在编辑器中输入 [[ 可触发自动补全，从整个保险库中搜索匹配的笔记标题并创建链接。这种双向链接能力是构建知识图谱的基础，而 wikilinks 在目标笔记重命名时会自动更新所有引用。BlockNote 同时通过 @blocknote/code-block 插件提供语法高亮的代码块支持。
Raw 模式切换通过面包屑栏的代码按钮或 Cmd+/ 快捷键触发，显示纯 Markdown 源码。该模式使用 CodeMirror 6 构建，适合需要精确控制 Markdown 语法的场景。两种模式的数据流向统一：编辑器内容变更经 500 毫秒防抖后，通过 blocksToMarkdownLossy() 转换为 Markdown 字符串，再经 postProcessWikilinks() 处理还原 [[target]] 语法，最后通过 Tauri IPC 调用 save_note_content 命令写入磁盘。
实时预览的另一层含义体现在关系网络的即时反馈。当笔记的 frontmatter 属性（特别是 belongs_to、related_to、has 等关系字段）发生变化时，检查器面板会立即更新显示新建立或解除的链接关系，无需手动刷新。这一行为得益于前端状态管理中严格遵循的「磁盘优先写入」原则：所有修改先通过 Rust 后端写入文件系统，确认成功后更新 React 状态，确保内存状态与磁盘状态一致。
与 Obsidian、Heptabase 的互操作设计
Tolaria 在设计层面充分考虑了与现有 Markdown 知识库生态的兼容性，这主要体现在以下几个维度。
文件格式层面，Tolaria 使用标准的 Markdown 文件加 YAML frontmatter 存储笔记，不引入任何专有格式。Frontmatter 中的标准字段如 type、status、url、belongs_to、related_to、has、start_date、end_date 等具有约定俗成的语义，会触发特定的 UI 行为。用户可以通过 config/relations.md 和 config/semantic-properties.md 覆盖默认约定。这一设计使得任何支持 Markdown 的工具（包括 Obsidian、Heptabase、VS Code 等）都可以直接读写 Tolaria 保险库中的文件。
Git 层面，每个 Tolaria 保险库即是一个 Git 仓库，内置一级 Git 支持。应用提供手动提交、推送、拉动功能，同时也提供可选的 AutoGit 模式 —— 在应用空闲或失去焦点时自动创建提交并推送。Git 元数据（提交信息、文件状态、分支信息）在笔记列表中清晰可见，用户可以从状态栏直接查看同步状态。Git 的引入不仅解决了版本控制问题，还天然支持与 GitHub、GitLab 等远程仓库的同步，且不依赖 Tolaria 自身的云服务。
关系模型层面，Tolaria 采用类型系统（Types）作为笔记的组织单位，而非传统的文件夹层级。类型存储为 type/ 目录下的 Markdown 文件（如 Project.md、Person.md），每个类型可配置独立的图标、颜色和排序规则。笔记通过 frontmatter 中的 type: 字段与类型关联。这一模型与 Obsidian 的文件属性（Properties）机制高度兼容，Obsidian 的 YAML frontmatter 可以直接被 Tolaria 读取，反之亦然。
MCP 集成层面，Tolaria 内置 MCP 服务器，提供 14 个工具供 AI 代理调用，包括 open_note、search_notes、create_note、edit_note_frontmatter、ui_open_note 等。服务器通过 stdio 传输（适用于 Claude Code、Cursor）和 WebSocket 传输（端口 9710 为工具桥、端口 9711 为 UI 桥）双通道运行。用户可以通过状态栏或命令 palette 将 Tolaria 注册为 Claude Code 或 Cursor 的 MCP 服务器，从而在 AI 助手环境中直接操作笔记库。这意味着用户可以在 Obsidian 或 Heptabase 中积累的笔记资产，无缝迁移至 Tolaria 的 AI 增强工作流中。
性能优化：缓存策略与增量更新
面对 10,000+ 笔记规模的大型保险库，Tolaria 实现了三层数据表示与单一权威源的设计。数据以三种形式同时存在：文件系统上的 .md 文件（唯一权威源）、缓存文件 ~/.laputa/cache/<vault-hash>.json（加速启动的索引）以及 React 状态中的 VaultEntry[]（会话期间内存表示）。三者不应永久分离，若发生分歧，文件系统获胜，缓存和状态重建。
缓存系统采用基于 Git 的增量更新策略。应用启动时首先检查缓存是否存在且有效；若缓存的 Git HEAD 提交哈希与当前仓库一致，则仅通过 git status --porcelain 获取未提交变更，解析变化文件后增量更新缓存；若提交哈希不同，则执行 git diff old..new --name-only 获取变更文件列表，选择性重解析受影响文件；只有在缓存不存在或损坏时才执行完整的文件系统扫描（walkdir 遍历所有 .md 文件）。
缓存写入采用最佳努力策略：写入临时文件、fsync 落盘、短生命周期写锁加磁盘指纹校验确认无并发冲突后，方 Rename 重命名到位。写入失败时记录日志并回退到从文件系统重建。这一策略在保证性能的同时确保数据一致性不会因缓存故障而损坏。
工程参数与可落地清单
对于计划基于 Tauri 构建类似多窗口 Markdown 编辑器的团队，以下是关键工程参数。
窗口管理：主窗口最小宽度动态计算（480px 基准 + 侧边栏 / 笔记列表 / 检查器宽度增量），独立笔记窗口固定 800×700，窗口标签需在 capabilities 配置中声明权限。窗口间通过 URL 查询参数传递上下文，路由逻辑在 main.tsx 启动时执行。
编辑器：BlockNote 版本 0.46.2 配合 CodeMirror 6 实现双模式，自动保存防抖 500 毫秒，箭头连字符逻辑统一处理。Wikilinks 触发字符为 [[，自动补全索引整个保险库标题。
状态管理：无 Redux 或全局 Context，状态由根组件 App.tsx 持有并通过 props 向下传递，子组件通过自定义 Hook 与后端通信。写入遵循「磁盘优先」原则 —— 所有数据修改先通过 Tauri IPC 写入磁盘，成功后更新内存状态。
Git 集成：AutoGit 支持可配置空闲 / 失焦触发阈值，冲突检测通过 get_conflict_files 命令，远程状态通过 git_remote_status 获取。Git 操作使用系统 git CLI，认证完全依赖用户已有的 SSH 密钥或 Git Credential Manager 配置。
MCP 服务器：工具桥端口 9710，UI 桥端口 9711，均绑定回环地址，浏览器来源仅允许访问 UI 桥。14 个工具覆盖笔记的增删改查、关系链接、UI 操作和上下文获取。
缓存策略：缓存路径 ~/.laputa/cache/<vault-hash>.json（哈希值通过 DefaultHasher 生成），缓存版本号 v13（随 VaultEntry 字段变更递增），增量更新依赖 Git 提交历史。
资料来源：Tolaria GitHub 仓库（refactoringhq/tolaria）、Refactoring 官方博客 Introducing Tolaria、Tolaria 架构文档（docs/ARCHITECTURE.md）。