Notula：让 AI Agent 可读写 Git 仓库中的 Markdown 文档

Notula 是一款在 Hacker News 上以「Show HN」形式发布的桌面端 Markdown 文档编辑器，定位是「让人类编辑 AI Agent 读取的 Markdown」。它面向同时使用 Git 仓库管理文档、且希望 AI Agent（如 Claude Code）参与文档协作的工程团队。

产品定位与核心使用场景

Notula 的设计假设是：团队的规格说明、PRD、RFC、运维手册等文档已经迁移到 Git 仓库中以 .md 文件存放，AI Agent 能够原生读写这些纯 Markdown 文件。但随之而来的问题是，非工程师无法用普通编辑器审阅、批注、讨论这些文档，而工程导向的代码编辑器对内容贡献者并不友好。Notula 试图在保留「文档即代码」工作流的前提下，提供接近 Google Docs 的编辑体验。

关键功能

• WYSIWYG Markdown 编辑：屏幕上不显示任何 Markdown 语法字符（井号、星号、表格竖线等），落盘的内容仍是普通 Markdown，可直接通过 Pull Request 评审。
• 仓库内协作与评论：支持对段落添加批注、回复、解决；评论以追加日志形式提交到仓库中，遵循 W3C Web Annotation 模型，使用 union merge 驱动，避免并发冲突。
• Git 集成：通过 git ls-files 读取仓库，自动忽略 .gitignore 中的文件，仅展示包含文档的目录。支持 GitHub、GitLab、Bitbucket、Gitea 等托管平台，也支持纯 SSH 仓库或无远程仓库。
• 双向链接与历史导航：类浏览器方式打开文档内链接，后退/前进保留滚动位置；每次本地编辑只产生最小的字符级 diff。

AI Agent 协作机制

Notula 与 AI Agent 的集成是其差异化卖点，主要体现在四点：

• 自动生成 notula-agents.md，描述仓库中的文档类型、字段、布局和命令，并向 CLAUDE.md 中插入三行注释让 Agent 加载该文件；
• 通过命令行暴露文档、类型、字段、状态等操作（支持 --json 输出），Agent 可直接调用而非猜测文件结构；
• 文档重命名使用 notula docs move 命令，避免直接 mv 导致评论线程孤立；
• 当 Agent 改写用户正在编辑的文档时，改动会出现在用户面前而非被静默覆盖。

现状与局限

Notula 在官方介绍中自称仍处于早期阶段，提供 macOS 与 Windows 客户端，免费、无需账号或服务器、可离线工作。关于 AI Agent 的功能目前主要针对 Claude Code，其他 Agent 需要自行适配命令行接口。产品在 6,000 个真实文档的测试中，96.4% 的 Markdown 块在编辑后保持未变，编辑回写颗粒度较细。