审查 AI 智能体写的计划与文档

那一刻

四百行的计划刚刚落地。然后呢？

这套流程你熟悉：智能体写完一份计划，接下来轮到你出手。在编辑器里读原始 Markdown，读者会看到的样子就被藏了起来——表格、结构、论证的形状。把片段贴回聊天窗口，每条评论都与它所指的位置断了联系，智能体只能猜你那句“这段不对”究竟指着哪里。而唯一为“给文档写评论”而造的工具——拉取请求——要求你先把草稿提交、推送，再到浏览器里审查。

并不是每份文档都该被提交，也不是文档的每一个工作版本都该被推上去。

一份还在改的草稿，需要的是你在白板前给同事的那种反馈：指着那一段，说出哪里不对，然后把它递回去。页边批注就是这件事。

这个闭环

渲染着读。就地批注。把它递回去。

1 · 渲染着读

在 PullMark 里打开草稿——或者就在智能体所在的那个终端里敲一句 pullmark plan.md。表格还是表格，图表还是图表，文件每变一次，页面就重新渲染一次。

2 · 就地批注

悬停在不对劲的区块上，点开批注气泡，把你会对同事说的话写下来。批注署着你的 @name，锚在确切的那段文字上——写在标题之上的批注，管的是整份文档。

3 · 把它递回去

对智能体说一句：“把 plan.md 里的批注都处理掉。”批注以普通 HTML 注释的形式住在文件里，智能体就在你留下它们的确切位置逐条读到——照做、回答，然后删掉。

PullMark 渲染一份由智能体撰写、标题为 Wind Gust Alerts 的设计规格，三条页边批注以审查者的署名卡片呈现——一条文件级批注要求重写一版干净的第二稿，一条质疑规格里的采样率假设，还有一条对某个功能喊了 YAGNI——侧边栏则显示这份规格位于某个 git 仓库 main 分支下的 docs/superpowers/specs 文件夹中 — 智能体的一份规格，第一遍审查过后：署名批注锚在确切的区块上——不用提交，不用粘贴，不用开拉取请求。

从构造上就不锁定你。一条页边批注就是 Markdown 里的 ——一条不会出现在渲染页面上的注释。你的文件仍是纯文本，你的批注随文档同行，任何读得了这个文件的东西都读得了这些反馈。页边批注文档讲清了它的机制；该功能目前是 beta，且默认开启。

给智能体一段上下文，它就能把这套约定守得更好。下面这段文字，和 “设置 → 实验性功能”里的“拷贝”按钮复制出来的是同一段——把它粘进智能体的指令文件（CLAUDE.md、AGENTS.md）或者对话里：

给你的智能体

## Margin notes

Markdown files may contain review notes as HTML comments:
`<!-- note @name: comment -->` (possibly multi-line, closing
with `-->` on its own line). Each note sits directly after the
passage it's about; a note above the first heading is about the
whole document. `--\>` inside a note means a literal `-->`.

When asked to address notes: work through each one, apply or
answer it, and DELETE the note (with its surrounding blank line)
once addressed. To reply or ask instead, leave your own note in
the same format below the original, signed with your own @name.
Don't add notes to code examples inside fenced blocks.

A note about one list item sits inside that item — directly after
the item's last line, indented to the item's content, with no
blank lines around it. Keep (or delete) the whole indented
comment; its indentation is what ties it to the item.

长文档

批注会等你。

认真审一份长文档——一篇调研报告、一份复杂的设计文档——可能要花上一个钟头。页边批注就是为这一个钟头而造的。你工作时，文档一动不动：念头在哪里冒出来就写在哪里，然后继续读下去。等第三十页让你改了对第三页那条批注的看法，回去把它写得更准一点—— 或者干脆删掉。在这一遍读完、你的批注彼此自洽之前，什么都不会传到智能体那里，于是反馈是作为一整套连贯的意见落地的，而不是一串边走边改的更正。

即便是最终要提交的文档，它也值回票价。在第一次提交之前，先用页边批注做完粗糙的第一遍，拉取请求开出来就是干净的——审查者看到的是真正要紧的讨论，而不是走到那一步所用的脚手架。

修订

看着改动落地。

智能体逐条处理你的批注时，PullMark 跟得上。每保存一次，页面就重新渲染一次；比较把这次修订显示为渲染后的差异——智能体的改动逐词高亮，落一处亮一处。一键就能把工作中的文件与最近的任意一次提交或任意分支比较； pullmark --diff plan.md 在终端里做同一件事。要回答“智能体刚刚把我的文档改成什么样了？”，这是最快的方式——而批注一旦被处理，它们就从文件里干干净净地消失了。

当它确实是个 PR

而当文档真要交上去审查时……

有些文档确实该被提交——重度使用智能体的仓库，会让拉取请求里装满 Markdown：计划、 ADR、智能体定义、运行手册。PullMark 把这类 PR 显示为渲染后的差异，只高亮改动的词，让你在确切的区块上评论和提建议，再把你的审查提交到 GitHub。总览页知道这个 PR 的处境：审查结论、每位审查者的裁定、CI 检查，以及作为可读时间线呈现的会话。

PullMark 的拉取请求总览：PR 标题旁挂着“开启”标签，一枚“已请求更改”胶囊，一枚“检查已通过”胶囊，审查者头像佩戴着裁定徽章，一枚 docs-guild 团队标签，渲染好的 PR 描述，以及会话时间线——其中第一条审查评论里的表格是渲染过的 — 同一套审查的本能，对准一个拉取请求——首页讲了完整的审查故事。

和你的智能体，把这个环闭上。

免费，开源，已签名并公证。macOS 13+。

Homebrew

$ brew tap jedijashwa/tap
$ brew trust jedijashwa/tap
$ brew install --cask pullmark

直接下载

下载 PullMark

最新的 DMG——打开它，拖进 Applications（收尾的事交给 PullMark）。全部版本发布 →

无论走哪条路，PullMark 都会自己检查更新，一键装好。