mdpreview 是一个 Markdown 预览与批注工具，采用 Catppuccin Mocha（深色）/ Latte（浅色）主题，提供实时重载、多标签页和类似 Google Docs 的边距批注功能。
用途
该工具用于在本地预览 Markdown 文件，并在阅读过程中添加、管理和持久化批注。适合需要边看文档边做注释、或让 AI 代理以编程方式写入批注的场景。
主要能力
- 实时重载：500ms 轮询，文件保存后自动刷新。
- 多标签页：可同时打开多个 .md 文件，切换标签页，并在运行时添加或关闭标签页；服务器运行期间启动新文件会作为新标签页加入。
- 批注系统：右侧边距评论气泡，带作者徽章（人类为蓝色，AI 为淡紫色并带机器人图标）；支持线程化回复、解决（切换删除线）和删除（悬停显示垃圾桶图标）。
- 批注持久化：保存在源文件旁的 file.md.annotations.json 边栏 JSON 中，查看器刷新或文件轮询时自动加载。
- 命令行批注：使用 --annotate 参数可直接写入边栏 JSON，无需运行服务器。
- 书签：全局持久化到 ~/.claude/bookmarks/，并生成 INDEX.md。
- 文件标签：7 个预定义标签及自定义标签，通过命令面板的 # 前缀使用。
- 命令面板：Cmd+K / Ctrl+K 快速访问命令、标签页和最近文件。
- 主题与排版：完整的 Catppuccin Mocha/Latte 主题，含 26 个 CSS 变量；标题使用 Cormorant Garamond，正文使用 DM Sans，代码使用 Victor Mono。
- 侧边栏目录：可调整大小的目录，带滚动监听。
- 代码高亮：highlight.js 配合 Catppuccin 语法主题。
- Chrome --app 模式：在无边框 Chrome 窗口中打开，接近原生应用体验。
- 跨文件链接：本地 .md 链接在新标签页中打开，而非跳转离开。
使用方式
快速开始：
预览一个或多个文件
python3 -m md_preview_and_annotate file.md [file2.md ...] --port 3031
若未全局安装，从克隆的仓库运行：
python3 ~/Desktop/Programming/md-preview-and-annotate/md_preview_and_annotate/main.py file.md
向运行中的服务器添加文件：
python3 -m md_preview_and_annotate --add another.md --port 3031
从命令行添加批注（无需服务器）：
python3 -m md_preview_and_annotate --annotate file.md
--text "RPL §235-b" --author "Claude" --comment "Cite the specific subsection"
交互式创建批注：在查看器中选中文本，会出现浮动按钮，然后在右侧边距填写评论表单。
规范仓库：github.com/tdimino/dabarat。可克隆该仓库，或确保 md_preview_and_annotate 位于 PYTHONPATH 中。
边栏 JSON 结构
{ "version": 1, "tags": ["draft", "research"], "annotations": [ { "id": "a1b2c3", "anchor": { "text": "selected phrase", "heading": "", "offset": 0 }, "author": { "name": "Claude", "type": "ai" }, "created": "2026-02-12T15:30:00+00:00", "body": "Comment text here", "resolved": false, "replies": [] } ] }
API 端点
- GET /api/content?tab=<id>：获取某个标签页的 Markdown 内容。
- GET /api/tabs：列出打开的标签页。
- GET /api/annotations?tab=<id>：获取某个标签页的批注。
- GET /api/tags?tab=<id>：获取某个标签页的标签。
- POST /api/add：打开新文件标签页。
- POST /api/close：关闭标签页。
- POST /api/annotate：创建批注。
- POST /api/resolve：切换批注的解决状态。
- POST /api/reply：添加线程化回复。
- POST /api/delete-annotation：删除批注。
- POST /api/tags：添加或移除标签。
适用场景
适合本地 Markdown 文档的阅读与批注、多人或人机协作审阅、以及需要以编程方式向文档写入批注的工作流。
限制
资料未提供关于收费、价格、平台兼容性、性能上限或具体效果的信息，暂未提供。