文档 / beta
页边批注beta
像评论拉取请求一样评论任何本地 Markdown 文档——只不过评论住在文件本身里，是不会出现在渲染页面上的普通 HTML 注释。它专为一个闭环而造：智能体给你写了一份文档，你在 PullMark 里 边读边留批注，然后把文件递回去，说一句“处理这些批注，做完就删”。 智能体页面连截图带流程走完了整个 闭环。
在 PullMark 中使用
正在装有 PullMark（0.28.1+）的 Mac 上读这页？ 直接跳到 页边批注的开关。
- 默认开启——页边批注是一个 beta 级实验性功能，出厂即启用 （0.35 起）。你第一次伸手用它——悬停气泡、⌥⌘M，或对 别人留给你的批注点“编辑”/“删除”——PullMark 会做一次介绍：批注是 什么、一枚教你的智能体的复制按钮，以及一枚“关闭”按钮（如果它 不合你意）。开关住在 设置 → 实验性功能，只管住撰写 工具；已经含有批注的文档无论如何都会显示气泡（只读），所以队友 或智能体批注过的文件绝不会悄无声息地渲染成空白。
- 添加批注——悬停本地文档的任意区块，点击页边的 气泡（和在 PR 上评论是同一个手势）。在列表里，气泡指向你所指的 那一项；在表格里指向那一行——一层淡淡的底色标明批注将附着的确切 范围。先选中文字，批注就带着所选引文打开——这就是指着一句话而 不是一整段的方式。⌥⌘M 批注你正在读的区块； 编辑 → 整篇文档的页边批注… 在文档顶部留下 一条关于整份文档的批注。
- 写 Markdown——粗体、代码、围栏代码块、链接、 列表；⌘↩ 保存。每次保存是文件里的一次编辑（用“文件 → 还原上次编辑”撤销）。
- 编辑 / 删除——悬停批注气泡见 操作。删除批注就是解决它：没有状态，没有归档——处理完的批注就是 不存在的批注。
- 计数标签——文档还带着批注时，“打开的文件”行上 会显示一枚评论计数标签。它是活的：智能体一边处理一边删批注， 计数就在你眼前下降，气泡逐个消失。
- 其他地方——批注在浏览的 GitHub 文件中只读 渲染，绝不出现在打印、PDF/HTML 导出或 Quick Look 中； 显示 → 隐藏页边批注 想清净阅读时 一键清屏。
- 你的署名——批注默认署名
@your-github-login；到“设置 → 实验性功能”里该功能自己的开关下修改。
格式
一条页边批注就是一条带 note 关键字和作者标记的 HTML
注释，独占一行，放在它所评论的区块之后：
Requests retry three times with exponential backoff.
<!-- note @josh: Section 2 says five times. Which is it? -->关于某个列表项的批注住在该项内部——缩进到该项的内容，贴紧排布， 让列表保持完整：
- First point
<!-- note @josh: too vague — name the metric -->
- Second point较长的批注把结束标记放到单独一行；正文是完整的 Markdown，空行和 围栏代码都可以：
<!-- note @josh:
This contradicts the design doc. Either reconcile them or
drop this section.
```suggestion
Requests retry five times with exponential backoff.
```
-->完整语法：
| 规则 | 说明 |
|---|---|
| 标记 | <!-- note @ 开始一条批注；普通的
HTML 注释（lint 指令、TODO）不受影响。 |
| 作者 | @ 与第一个冒号之间的
一切。允许空格；短一点的名字读起来最好。 |
| 正文 | Markdown，从冒号到 -->——短批注
写在同一行，长批注写在后续行。 |
| 转义 | 正文里字面的 --> 写作
--\>（唯一的保留序列；PullMark 替你转义和
还原）。 |
| 位置 | 独占一行，前后各留空行，紧跟它所批注的区块。 位于第一个标题之上 = 关于整份文档的批注。 |
| 列表项 | 关于某个列表项的批注位于该项内部： 紧跟该项的最后一行，缩进到该项的内容（至多 3 个空格——更深会 被当成代码），前后没有空行。缩进正是它与该项之间的 纽带。 |
| 会话 | 同一区块下相邻的批注读作一场对话——在下方再 加一条即是回复。 |
| 预留 | @name (attrs):——括号槽位为将来
预留，原样保存；今天没有任何东西读写它。 |
| 代码块 | 围栏代码块里长得像批注的注释是代码，不是 批注。 |
因为 Markdown 渲染器会跳过 HTML 注释，带批注的文件在 GitHub 上、 在编辑器里、在其他任何工具中都渲染得干干净净——批注随源码同行， 不惊扰页面。PullMark 只是这个到处能用的格式的漂亮客户端。
给智能体
交接是零协议的：智能体读文件，而批注就在文件里，物理上紧挨着
它们谈论的文字。把下面这段粘进你的 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.收敛循环从格式里自然长出来：剩下的气泡就是剩下的活儿，文件空了，
审查就完了。如果批注绝不能进入拉取请求，CI 检查只要一行——
grep -rn '<!-- note @' docs/ && exit 1。
为什么是 beta
机制已经证明了自己——这个格式自发布以来从未需要不兼容的修改， 这正是它从 alpha 毕业的原因。按照 beta 契约，我们现在切实努力在 版本之间保持语法和行为兼容，功能也很可能完全毕业。仍在打磨的是它 周围的表层：命名、交互方式，以及这套工作流在它诞生于其中的智能体 审查闭环之外能走多远。若真有任何变化，发行说明会写得明明白白。 欢迎 反馈。