键盘飞起、可 AI 深度集成的笔记工具ZenNotes,真实 Vim 内核 + 纯本地 .md 文件 + MCP 零拷贝集成 + Electron/Go 双运行时自托管架构

在笔记应用同质化严重的今天，大多数工具要么依赖云端数据库锁仓数据，要么提供“类 Vim”快捷键却无法真正保留肌肉记忆。ZenNotes（GitHub: ZenNotes/zennotes）选择了一条彻底本地优先、键盘驱动的道路：所有笔记都是普通 .md 文件，编辑器底层使用 CodeMirror 6 + codemirror-vim 实现真实 Vim 模式（支持完整 motions、operators、registers、marks、macros、folds、ex prompt），并内置 MCP 服务器让 Claude Code / Claude Desktop / Codex 等 AI 助手直接在磁盘上读写同一份文件，无需任何同步层或副本。

一、ZenNotes定位

●Plain files first：Vault 就是一个普通文件夹，笔记即 .md 文件。支持 Git、iCloud、Dropbox、Syncthing 等任何同步方式，无数据库、无专有格式、无迁移焦虑。完美兼容 Obsidian vault（支持 ![[embed]]、松散文件、磁盘布局）。

●Keyboard-first + Real Vim：默认 Vim 模式，leader key（Space）、which-key 提示、完整 ex 命令。不是“类似 Vim”，而是 codemirror-vim 驱动的真实模拟（支持 jk 退出插入模式等自定义映射）。

●Preview is workflow：Edit / Split / Preview 三模式无缝切换，支持实时渲染数学与图表。

●Shared vault, shared tooling：同一个 vault 可被桌面 App、浏览器、自托管 Web、CLI、MCP AI 同时操作，变更即时可见（live folder sync）。

●多运行时单核心：monorepo 结构，共享 packages/app-core（编辑器、领域逻辑、UI），分别打包为 Electron 桌面 + Go 后端自托管 Web。

键盘效率党 + 本地极客 + AI 协作用户的理想选择。

二、 功能详解

1. 笔记生命周期与组织

●创建/重命名/复制/移动/归档/取消归档/删除/恢复/在文件管理器中显示笔记与文件夹。

●实时监听 vault 外部变更（多客户端同步时文件夹创建/删除立即反映）。

●系统文件夹（Quick Notes、Inbox、Archive、Trash）可自定义 UI 标签。

●Primary Notes Location：可设为 inbox/ 或 vault 根目录（Obsidian 风格平铺）。

●Daily & Weekly Notes：可开启，标题与文件夹支持丰富 date pattern tokens（yyyy/MM-MMM、yyyy-MM-dd-EEE、yyyy-'W'ww 等），支持本地化月份/星期。v2.4+ 支持任务与日期笔记联动、日历面板拖拽或 Vim 调整到期日、未完成任务自动滚入今日。

●Templates：内置 ADR、RFC、Bug Report、Postmortem、Meeting Notes、1:1、Daily、Weekly Review 等；自定义模板放在 .zennotes/templates/ 目录，支持 :template 或 leader Space t 快速创建。

●Tasks：标准 - [ ] 语法，全 vault Tasks 视图（支持 Kanban 列移动、键盘 x 切换、过滤）。

●Tags：#tag 语法，Tags 视图支持多选过滤。

●Backlinks & Connections：自动解析 [[wikilinks]]，v2.3+ 重命名笔记时 wikilinks 自动跟随更新；Connections 面板显示相关笔记。

●Archive / Trash：独立主面板列表，Trash 支持永久删除或恢复；支持批量操作。

●Quick Notes：独立可折叠侧边栏区域或独立列表，支持日期标题或前缀，系统级快捷键快速捕获。

2. 编辑器与渲染

●底层：CodeMirror 6 + codemirror-vim（真实 Vim 模拟，支持 motions 如 ci", diw, gg/G, Ctrl+w v/s, registers, marks, macros, folds, ex prompt）。

●模式：Edit（带 live preview 行为的所见即所得）、Split（左右/上下）、Preview。Mod+4/5/6 切换；支持 pinned reference panes、桌面 floating windows。

●Markdown 增强：

○GitHub Flavored Markdown

○KaTeX 数学（行内与块级）

○Mermaid 流程图/时序图等

○TikZ、JSXGraph（交互式）、function-plot

○Callouts、footnotes、wiki links、local embeds、tables

●其他编辑体验：标题折叠、outline 跳转、行号（绝对/相对）、可配置行高/字体/阅读宽度、语法高亮、自动闭合 Markdown 分隔符、选择工具栏（Mod+/）、评论（高亮文字后侧边栏添加，标记随编辑锚定）。

●Zen Mode：Mod+. 一键隐藏所有 UI，仅保留编辑器或预览。

●Word Wrap、缩放、主题（Apple、Gruvbox、Catppuccin 等多 family + Light/Dark/Auto）。

3. 导航与效率工具

●Fuzzy Finders：笔记搜索（标题/路径）、Vault 全文搜索（内置引擎或自动检测 ripgrep / fzf，支持自定义二进制路径）。

●Command Palette (Shift+Mod+P) 与本地 ex 命令（: 提示，tab 补全）。

●Leader Key (Space) + which-key 提示：Space f 搜笔记、Space o buffers、Space s t 全文搜索、Space p outline、Space d/w daily/weekly 等。

●Pane/Tab 导航：Ctrl+w h/j/k/l、Alt+h/j/k/l、gt/gT、Ctrl+o/i 历史。

●Sidebar / Outline / Connections / Comments 面板切换（Mod+1/2/3/Shift+C）。

●Database Grid（Notion-style Table + Board）：v2.3+ 针对 .csv 文件的键盘驱动表格视图（h/j/k/l 单元格移动、i/Enter 编辑、a 新增、dd 删除、Kanban 列/卡片移动），完美适合轻量数据库需求。

4. 搜索、导出与其他

●PDF 导出（桌面原生，浏览器 print-to-PDF）。

●Inline Comments 面板。

●内置帮助手册（:h 或侧边栏打开，与网站 docs 同步）。

●Obsidian 互操作：直接打开 vault、支持 embeds 与松散文件。

5. CLI (zen) 与 MCP 集成（AI 协作核心）

桌面 App Settings → CLI 可安装 zen 命令（macOS 还可一键安装 Raycast 扩展）。

典型用法：

●●●bash
zen capture "Meeting takeaways" --tag work          # 创建 inbox/日期-标题.mdpbpaste | zen append inbox/Daily.md --body -       # 从剪贴板追加zen search "deadline" --json | jq '.[].path'       # JSON 输出便于脚本zen task list --unchecked --tag work               # 任务过滤zen mcp ...                                        # 运行 MCP server

MCP Server：内置，支持一键与 Claude Code / Desktop / Codex 连接。AI 可调用工具如 zennotes.search_by_tag "graphics" 直接操作磁盘文件，实现“AI 直接编辑你的笔记”而非复制粘贴。示例场景：让 AI 总结所有 #graphics 标签笔记中的 SDF 与隐式几何讨论。

三、高效使用工作流

日常捕获 → 组织 → 深度写作 → AI 协作 全键盘闭环：

1.快速捕获：Shift+Mod+Space（系统级）打开 floating capture 窗口 → Mod+Enter 保存并隐藏；或 Space q / zen capture。

2.组织：Space f 模糊搜笔记移动（:mv archive/ref）、Space t 从模板创建、:tag work 打开标签视图、任务用 x 切换。

3.写作：进入 Split 模式实时看渲染效果；用 Vim zc/zo 折叠大纲；Space p 跳标题；写到一半 Mod+Alt+M 加评论。

4.导航：Space o 所有 buffers、Ctrl+w 系列分屏、Mod+. Zen Mode 专注。

5.AI 增强：在 Claude 中通过 MCP 工具搜索特定 tag 笔记，让 AI 直接追加内容或生成新章节，保存后 ZenNotes 立即看到变更。

6.自动化：用 zen + jq + shell 脚本批量处理；Raycast 扩展（macOS）实现 launcher 级快速打开/搜索。

Power User 技巧：

●自定义 Vim 映射（Settings → Vim → Exit insert mode with jk）。

●ex 命令补全与 wildmenu。

●大 vault 性能：项目提供 perf 基准脚本，CodeMirror + 虚拟滚动表现优秀。

●多 remote workspace：桌面可保存多个自托管服务器连接，轻松切换本地/远程。

四、安装方法

1. 桌面 App

●macOS（Homebrew 最佳）：brew install --cask zennotes/tap/zennotes

●直接下载 DMG（Apple Silicon / Intel），拖入 Applications（已签名公证）。

●Windows：下载 exe 安装包，自动更新。

●Linux：

○Arch/CachyOS：yay -S zennotes-bin（推荐，无 FUSE 问题）

○Debian/Ubuntu：sudo apt install ./ZenNotes-*.deb

○通用 AppImage：chmod +x *.AppImage && ./ZenNotes-*.AppImage --appimage-extract-and-run（FUSE 3 系统需此参数或安装 fuse2）

●安装后 Settings → CLI 安装 zen 命令 + Raycast 扩展（macOS）。

2. 自托管 Web App

官方推荐镜像 adibhanna/zennotes:latest（多架构）或源码构建。

快速启动（生成 token）：

●●●bash
TOKEN=$(openssl rand -hex 32)mkdir -p "$HOME/Documents/MyVault""$HOME/zennotes-data"docker run -d --user "$(id -u):$(id -g)" --name zennotes \  -p 127.0.0.1:7878:7878 \  -e ZENNOTES_AUTH_TOKEN="$TOKEN" \  -v "$HOME/Documents/MyVault:/workspace" \  -v "$HOME/zennotes-data:/data" \  --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \  adibhanna/zennotes:latestecho $TOKEN# 浏览器打开 http://localhost:7878

进阶安全：设置 ZENNOTES_BEHIND_TLS=1 + 反向代理（Nginx/Caddy），ZENNOTES_TRUSTED_PROXIES，使用 ZENNOTES_AUTH_TOKEN_FILE，调整 ZENNOTES_VAULT_FILE_MODE=0600ZENNOTES_VAULT_DIR_MODE=0700 等。笔记默认 0600 权限，body 限制（note 10MiB，asset 50MiB）防磁盘耗尽。Symlink 全部 canonicalize 防逃逸。

Docker Compose / Makefile 一键（推荐源码或自定义）：

●●●bash
CONTENT_ROOT="$HOME/Documents/MyVault" make upcat data/auth-token   # 首次登录用make down / logs / rebuild

3. 从源码安装

项目为 Turborepo monorepo（v2.5.0）：

●●●bash
git clone https://github.com/ZenNotes/zennotes.gitcd zennotesnpm ci                    # 安装所有 workspace 依赖

桌面开发：

●●●bash
make desktop          # 或 npm run dev:desktop# 对应 apps/desktop (Electron)

自托管 Web 开发：

●●●bash
make web-stack        # 同时启动 Go server + Vite web# 或分开：npm run dev:server + npm run dev:web

生产构建：

●●●bash
npm run build:prod    # typecheck + test + buildmake desktop-build    # Electron 打包make server-build     # 先 web-build 再 server-build（Go 嵌入 web/dist 静态资源，单二进制）

Docker 从源码：

●●●bash
make up               # 使用本地构建镜像make nuke             # 清理

Nix：packaging/nix/README.md 有 flake 说明。

环境变量（Makefile / Docker 传递）：ZENNOTES_* 系列控制端口、内容根、认证、TLS、文件权限、body limit、trusted proxies 等，详见文档。

Raycast 扩展：macOS 上通过 zen CLI 一键安装，或手动从 integrations/raycast/。

五、技术原理与架构实现深度剖析

Monorepo 结构：

●packages/app-core：共享心脏（编辑器逻辑、Markdown 渲染 pipeline、domain models、Vim 状态机、picker 系统）。

●packages/shared-ui / shared-domain / bridge-contract：UI 组件、类型、IPC 契约。

●apps/desktop：Electron 主进程 + 渲染进程，native dialog、updater、PDF export、系统快捷键、CLI bundling。

●apps/web：Vite + PWA 前端（几乎与桌面共享 UI 行为）。

●apps/server：Go 后端（HTTP API、文件 CRUD 安全层、FS watcher + 实时同步、认证 session cookie、可能嵌入 MCP 网关或 stdio 桥接）。

●tooling/：perf 脚本、dev web-stack 脚本。

●packaging/：Nix、electron-builder 配置等。

编辑器实现：CodeMirror 6 作为基础，集成 codemirror-vim 提供 motions/operators/ex 命令；自定义 Markdown 扩展处理 live preview、KaTeX（remark/rehype + katex）、Mermaid（mermaid.js）、其他图表库（JSXGraph、function-plot）；heading folding、outline extraction 均在核心实现。

渲染 pipeline：编辑模式下 CodeMirror 本身做部分 WYSIWYG 渲染；Preview/Split 模式走完整 Markdown AST → 各渲染器（KaTeX、Mermaid 等 client-side 执行）。

自托管后端安全模型：

●启动时生成 256-bit bootstrap token（持久化 0600）。

●登录后切换 HttpOnly session cookie（支持 rotate-token 端点使旧会话失效）。

●所有文件操作先 realpath + canonicalize symlink，拒绝指向 vault 外的路径。

●Exponential backoff 防暴力破解 + 文件权限默认收紧。

●反向代理场景强制 ZENNOTES_BEHIND_TLS=1 启用 Secure cookie + HSTS。

●体积极限 + 非 root 运行 + read-only rootfs + cap-drop。

实时同步：Go 层 FS watch + WebSocket 推送变更到所有连接客户端（桌面远程模式 + 浏览器），实现多端“文件夹操作立即可见”。

MCP 集成：独立或与 server 协同的 stdio MCP server，暴露结构化工具（search_by_tag、read_note、append 等），让 AI 像本地工具一样操作 vault，实现“AI 直接写你的笔记”。

性能与扩展：提供多个 perf 基准脚本；大 vault 下虚拟滚动 + 增量渲染；未来计划 hosted 多用户模式（当前单用户自托管）。

与 Obsidian 对比亮点：更强的真实 Vim + ex 命令、更轻量的自托管方案（Go 单二进制）、原生 MCP AI 集成、无插件生态但核心更聚焦键盘与文件所有权。

ZenNotes 是一个极其务实、本地至上、键盘效率极高的开源笔记项目它用 CodeMirror 6 + codemirror-vim 实现了许多“类 Vim”应用做不到的真实操作感；用纯文件 + 安全 Go 服务器实现了真正可自托管、可 Git 版本控制、可 AI 零拷贝协作的体验；monorepo + Turborepo 让桌面与 Web 保持高度一致。

适合人群：

●Vim / Neovim 重度用户

●追求数据完全本地控制、不想锁在任何云或专有格式的人

●希望 AI 助手直接操作笔记文件而非聊天式复制的开发者

●需要自托管或团队内部部署笔记环境的用户

●喜欢 Notion 数据库但更爱纯文本的用户

如果正在寻找一个真正属于自己、键盘飞起、未来可 AI 深度集成的#笔记工具，ZenNotes 值得立即尝试。安装二进制版 5 分钟就能上手，喜欢折腾的可以 make up 一键自托管或完整源码构建。