Sidenote：在浏览器里给博客加注释，由 LLM 生成 git diff

Sidenote 是一个面向独立博客和文档站作者的开源工具，作为 Show HN 项目由开发者本人发布。它通过浏览器中的覆盖层，让作者像在 Google Docs 一样，对本地 dev server 上渲染好的 Markdown 站点做段落级批注，并由本地运行的 Claude 或 Codex 等 LLM 代理把注释解析成可逐处接受或拒绝的 git diff。整条工作流无需离开浏览器。

核心思路：让 LLM 替你改 Markdown

日常博客或文档写作中，作者常需要在浏览器（查看渲染效果）和终端（让 AI 代理改源码）之间反复切换。Sidenote 希望把这个循环留到浏览器内完成：站点源码仍然作为单一事实来源（source of truth），工具本身并不充当编辑器；作者只需标注「想要怎样改」，代理负责真正写入。

四步使用流程

选段批注：在渲染好的页面上选中任意段落，写下修改意图，沿用 Google Docs / Word 的肌肉记忆。
进入侧栏：批注会固定到右侧栏，可在「提问」与「解析为编辑」之间切换。
选 Ask：代理只在线程内回答，不会动源文件，相当于一段对话。
选 Resolve：代理把回答转为对源码的修改，作者在内联的 git diff 里逐处 Accept 或 Reject。

补充能力包括：

在原线程上继续 Reply，等准备好再转为编辑。
实时查看代理的工作流（活动状态与流式输出），不必盯转圈。
单条 Reject 只回滚该批注的修改，不会牵连其他变更。
一个名为「drift guard」的机制：当源文件自批注起已经被改动时，拒绝打补丁，以避免覆盖未察觉的变更。

运行要求与默认配置

环境：Node.js 18 及以上；PATH 中需要可用的 claude 或 codex（项目内置一个零 LLM 的 mock agent，专供测试使用）。
站点：需要通过 remark 渲染 Markdown，例如基于 Next.js 的个人博客。
三步上手：npm install --save-dev remark-sidenote、npx sidenote-cli init --agent claude、npx sidenote-cli dev 启动守护进程。

init 会写入一份默认的 .sidenote/config.json：

agent: claude
contentDir: content
port: 4517
askModel: haiku
resolveModel: opus

其中 askModel 与 resolveModel 为可选字段。Ask/Reply 默认使用较快的模型，Resolve 则沿用代理的默认模型（默认是 opus）。项目内的 TESTING.md 描述了如何有 LLM 或无 LLM 地跑完整个循环。

项目结构与测试

仓库划分为四个部分：

packages/remark-plugin：在 Markdown 渲染流水线里给 HTML 块打上源码偏移（offset stamping）。
packages/daemon：本地 4517 端口上的注释存储与解析循环，支持 claude、codex 或 mock agent。
packages/overlay：注入到浏览器的覆盖层，负责选段批注、侧栏与实时 diff。
bin/sidenote.js：提供 init 与 dev 两条 CLI 命令。

测试方面，npm test 跑 remark 插件与守护进程的单元套件（不依赖浏览器）；npm run test:e2e 跑需要 Playwright 的完整浏览器流程。项目以 MIT 协议开源，作者在 GitHub 上接受 Issue 与 PR，并附带 CONTRIBUTING.md 与行为准则。