1 概览

• 一个让人类和 AI Agent 在同一份 Markdown 笔记上协作的轻量笔记系统
• 笔记写完即渲染成自定义样式的网页，任何人都能通过链接直接访问
• 内置类 Git 的版本控制，任何一次改动都可以回退，删除也有回收站兜底
• 面向 AI 的统一 API，Codex、Claude Code 可以直接读写你的笔记
• 支持多用户、权限隔离，可以自部署，本地和云端还能双向同步

2 前言

我换过不少笔记应用。Notion 太重，Obsidian 的双链图谱我用不上，最后在 Joplin 上停了一阵。Joplin 是好东西——开源、本地优先、Markdown 原生，按理说很对我胃口。但用着用着，我总觉得哪里别扭：它的交互逻辑始终停留在"一个给人用的编辑器"，而我这一年越来越多的写作，其实是我和 AI 一起完成的。

我会让 Codex 帮我整理一份调研笔记，让 Claude Code 把零散的想法拼成一篇文章，再自己润色发布。可这些 AI 写出来的 Markdown，要进 Joplin 还得我手动复制粘贴、手动建目录、手动管版本。笔记应用明明应该是 AI 最顺手的"工作台"，现实里却成了一个需要人去伺候的容器。

我想要的是一个 AI 原生（AI-native） 的笔记应用：它从设计的第一天起，就把"AI 会来读写"当作默认前提，而不是事后补一个插件。找了一阵没遇到完全合心意的，干脆自己做一个——这就是 bensz-notes。

3 我想要的，是一份能和 AI 一起长大的笔记

所谓 AI 原生，在我看来不是给编辑器塞一个"AI 续写"按钮那么简单。它意味着 AI 和人一样，是这个系统里的一等公民：人有账号、有空间、有权限，AI 也有自己的 token、自己的读写范围、自己的操作边界。人可以写，AI 也可以写；人改错了能撤回，AI 改错了同样能撤回。两者在同一份笔记上来来回回，系统都要记得清清楚楚、可审计、可回滚。

bensz-notes 就是按这个思路搭起来的。它的底子是 Markdown——源文件是核心资产，渲染出来的网页随时可以重建。在这个底子之上，它把"给人用的界面"和"给 AI 用的接口"做成同一套数据的两个出口：你在网页后台改一个字，和你让 Codex 通过 API 改同一个字，走的是同一条记录、同一套版本历史。谁也不比谁特殊。

4 写下来、发出去、还能改回来

从用户的视角看，bensz-notes 的日常其实很简单。

你写一篇 Markdown 笔记，它会被渲染成一份自定义样式的网页。样式是可以换模板的，所以最终呈现出来的不是干巴巴的纯文本，而是一篇排版体面的、任何人都能通过链接直接打开的文章。我自己把它挂在 note.hwb0307.com，写完一篇丢个链接出去就能读，访客看到的是一个干净的阅读页，而不是一堆管理后台的配置项。

笔记之间用文件夹、子文件夹和标签组织，配上全文搜索。访客首页我做成瀑布流的样子，右上角一个搜索框，敲一下 / 能调出快捷指令：输 /tag 可以按标签定位，输 /theme 可以在不同文件夹之间跳转。这些是我在用别的博客系统时养成的习惯，顺手搬了过来。

真正让我安心的，是它的版本控制。每一次保存都是一个版本，你可以对比两个版本的差异，也可以一键回退到任意一个历史版本。这对"人和 AI 一起改同一篇"的场景特别重要——AI 有时候会热心过头，把我不想要的内容也一起"优化"掉了，有了版本历史，我随时能把它拽回来。删除也不可怕，回收站会接住。

5 让 AI 成为你的合著者

如果说版本控制提供的是"安全感"，那 AI 协同才是 bensz-notes 真正的差异化。

它对外提供一套统一的 API，AI Agent 拿着一个 token，就能对笔记做读写、追加、移动、删除、恢复甚至批量编辑。你在本地用 Codex 干活，让它把今天的调研整理成一篇笔记，它可以直接调接口把内容写进你的空间，顺手打好标签、归到对应文件夹——全程不用你切窗口，更不用复制粘贴。

这里有个很现实的工程问题：当你和 AI 同时在改同一篇笔记怎么办？bensz-notes 用乐观锁和修订号来处理并发冲突，谁后改、改了什么，系统都能识别，不会出现"两个人互相覆盖"的惨剧。每一笔 AI 的操作也都会进审计日志，谁在什么时候改了什么，事后查得到。

文档的可见性同样是分层可控的：草稿、私有、隐藏、公开发布，状态清清楚楚。你想让 AI 帮你整理一份只给自己看的私密笔记，没问题；想发布出去给所有人读，也没问题。同一份内容，不同的命运，由你说了算。

6 一些没说出口的小坚持

做这个项目的过程中，我也攒了一些自己的小坚持，顺便聊聊。

一是本地优先。很多人和我一样，习惯在本地维护一套和云端同名的 Markdown 目录，手动改完想推到云端。bensz-notes 配了一个命令行工具，可以增量同步本地的 .md 文件到云端：默认只增不删，想删除要显式确认，远端被删的内容也是软删除进回收站。你的本地文件，始终是完整且属于你的一份。

二是自己部署。整个系统打包成一个 Docker 镜像，docker compose up 就能跑起来，数据库和缓存都内置。数据躺在你的服务器上，不依赖任何第三方云服务——这一点对我这种长期守着 NAS 的人很重要。

三是克制的设计。后台的配色和间距我反复调过很多遍，最近把大面积的浅绿收敛成中性的暖灰纸面，只在品牌色和当前操作上保留一点绿色点缀。访客页的悬浮导航做了 macOS 风格的弹性动效。这些都是很小的细节，但合在一起，决定了你每天打开它时舒不舒服。

7 小结

bensz-notes 不是要取代 Notion 或 Obsidian，它更像是我给自己和 AI 搭的一张共同工作台。它保留了 Markdown、本地优先、版本可控、可自部署这些"老派"的踏实感，又从第一天起就把 AI 当作一等公民——让 Codex 和 Claude Code 能直接读写我的笔记，而不是在应用外面隔靴搔痒。从 Joplin 出走，本质上是因为我不再满足于"一个只给人用的笔记应用"：当写作越来越多地变成人和 AI 的协作，工具也该跟着变。它还在迭代，但日常写作、发布、AI 协同这条主线已经跑通了。如果你也长期和 AI 一起写东西，欢迎来 note.hwb0307.com 看看，或者在评论区聊聊你对"AI 原生笔记"的期待。