我所理解的 Markdown 最佳实践（4）：给 AI 写的 Markdown 做批注：CriticMarkup、MarkMark 和 Windows 工作流

我所理解的 Markdown 最佳实践

1. 中文加粗为什么会露出星号
2. 给 Markdown 文档接入 textlint
3. Markdown 里的代码也要检查
4. 给 AI 写的 Markdown 做批注（当前）
5. Markdown 怎样交付到网页和富文本编辑器
6. 善用 Markdown 扩展语法

最近用 Codex 写文档、方案和博客草稿时，有一个反馈动作越来越别扭：我明明是在改一篇 Markdown，却经常要回到聊天框里写「第 37 行那句话删掉」「第 52 行改成另一种说法」。

这套反馈方式把文章当成代码补丁来处理。文章里的问题常常落在段落、证据、标题和例子上：一段表达方向不对，一个概念需要补证据，一个标题该收紧，一个例子该换掉。只用行号描述，反馈者要费力定位，Agent 也要重新理解上下文。行号成了中间损耗。

MarkMark 给我的启发，是把「批注」变成 Markdown 文件里的可读文本协议。人直接在文章上标，AI 直接读这些标记，再把文章改回干净版本。反馈不需要旁边另写一套说明，修改意图已经嵌在原文里。

让模型读到批注

很多写作工具已经能批注。AI 协作更看重另一件事：标完以后，模型能不能完整读懂这些批注。

Google Docs、Word、飞书文档这类工具的批注体验很好，但批注通常存在文档模型或云端协作层里。要把它交给 Codex，就需要导出、复制、截图，或者让模型读一个带格式的中间文件。这个过程一复杂，日常反馈又会退回到聊天框里的行号和口述。

Markdown 的优势在这里反而很朴素：它本来就是纯文本。只要批注也是纯文本，文件本身就能成为沟通介质。

CriticMarkup 做的正是这件事。它把常见审阅动作写成几种内联标记：

{++新增文字++}
{--删除文字--}
{~~旧文字~>新文字~~}
{==需要注意的文字==}{>>这里补一句为什么<<}
{>>单独评论<<}

这些标记对人来说还能读，对 Git 来说还是普通 diff，对 AI 来说也很容易解释。你不需要额外数据库、隐藏元数据或截图 OCR。文件里已经同时包含原文、修改建议和评论。

MarkMark 的关键设计

MarkMark README 将它定位为 macOS Markdown 阅读器，并在阅读器上加了 CriticMarkup 审阅流程。你在渲染后的页面里选中文字，可以做删除、替换、评论、高亮，然后一键复制「引导提示词 + 带 CriticMarkup 标注的全文」交给 AI。

我读源码时更在意它的中间链路。用户不必在源码 Markdown 里手写 {~~ ~> ~~}，批注入口放在渲染视图里：

• Markdown 先被渲染到 WKWebView。
• 前端脚本捕获选区，并把选中文本、行号或附近上下文传回 Swift 层。
• Swift 的文档模型把这次动作转换成 CriticMarkup。
• 源 Markdown 被写入批注标记。
• 导出时把说明 prompt 和完整标注文档一起放进剪贴板。

这条链路把应用状态压到最低。MarkMark 负责选区、浮层和预览，文件里留下 CriticMarkup 文本；换一个编辑器或模型，批注仍然能被读到。

MarkMark 的 README 要求 macOS 14.0 或更高版本。在 Windows 上，我用同样的文件格式接起了阅读和批注。

在 Windows 上边读边批注

我先在 Windows 上试了 VS Code 的批注流程。Markdown 源码和预览分在两边，读到一句需要改的话，要回到源码找到它，再触发批注命令。批注写进去后，我还得在预览和标记之间来回确认。这套流程能把意见留在文件里，但在长文里逐段审阅时，每条批注都要多做一次定位。

我给这个流程做了一个 Windows 桌面工具 sheng-markdown-marker。打开项目目录后，可以直接在渲染后的 Markdown 上选中文字，添加评论、高亮、删除建议或替换建议。保存时，工具把 CriticMarkup 写回正在看的 .md，阅读位置留在原处。长文可以用「大纲」或「查找」定位，也可以从顶栏的「批注」列表跳回某条意见对应的原文。

比如样稿里写「上传失败后，程序会自动重试。」我想让作者补上重试条件和次数，就选中这句话，点「添加批注」并保存。阅读页保留这句话，用高亮和编号指向右侧的评论。打开同一个 Markdown 文件，可以看到选中的句子和评论连在一起。

{==上传失败后，程序会自动重试。==}{>>说明哪些错误会重试，以及重试次数的上限。<<}

审完一轮，点顶栏的复制图标，把文件路径交给能读取当前工作区的 Codex。它读的是刚刚写回的那份稿件，原句和批注都在同一个文件里。这个阅读器目前是我本地使用的版本。想在已有编辑器里直接试这套流程，可以用下面的插件。

编辑器里的 CriticMarkup 插件

• 在 VS Code 里，MarkReview 支持选中文字写入评论、从侧栏跳回原文，也能导出给 AI 的提示词。
• 需要从工作区里找出多个文件的批注时，Review Markup Sidebar 会按文件分组展示标记，可以跳回源码并处理增删改建议。
• 稿件已经放在 Obsidian 时，Review Critic 可以在阅读视图和实时预览中显示审阅标记，并从变更面板定位和处理它们。

和 Codex 添加到对话的关系

Codex 自己也有「添加到对话」一类入口。它适合把选区、打开文件或已有聊天材料放进当前请求，让模型立刻拿到上下文。ChatGPT 的项目文档也提到，编辑器里的当前选区和打开文件会为当前 turn 提供上下文；项目里的 Sources 则负责跨聊天复用文件和来源。

这个功能解决的是材料进入模型的问题。选中一段文字让 Codex 改短、解释一个段落、临时带入某个文件，直接添加到对话就很好。它的成本低，动作短，不需要额外协议。

CriticMarkup 更像审稿层。正式审稿时，一篇 Markdown 里可能同时出现删除、替换、补句子、评论语气和补证据提醒。只靠添加到对话，这些意见往往会挤在一次 prompt 里；文档一长，人和模型都要重新定位。

把它们写成 CriticMarkup 后，意见留在文件里。隔几天再打开，批注仍然跟着原句走；换一个编辑器或 Agent，文本标记也还能读。

所以这两套机制适合合用：

• 轻量反馈用「添加到对话」：选中一段，让 Codex 解释、缩短、润色或顺手改一处。
• 正式改稿用 CriticMarkup：把一篇文档当成审稿对象，逐段标删除、替换、补充和评论。
• 长文返工可以叠加使用：先在编辑器里标好 CriticMarkup，再把文件或小节添加到对话，让 Codex 按批注输出 clean 版。

我会怎样放进 Codex 工作流

这套机制落到 Codex，不需要复杂集成。先按反馈重量选入口，再固定文件和口径。

轻量反馈直接走 Codex 的添加到对话。选中文本后，让 Codex 处理当前段落即可；这种场景不需要把所有意见写进文件。

一旦进入正式审稿，就让 Codex 把草稿写成一个真实 Markdown 文件。文件可以是博客草稿、方案文档、README 或临时审阅稿。

在阅读器或编辑器里把 CriticMarkup 写进原文件。已经想好具体改法时，可以标记新增、删除或替换。还需要核实事实或斟酌写法时，就给原句加评论，把待判断的问题说明白。

把同一个文件交回 Codex 时，可以说明哪些标记表示直接改动，哪些还需要判断。

请读取这个 Markdown 文件，按 CriticMarkup 批注修改正文。
按新增、删除、替换标记处理明确的改动，高亮和评论结合上下文判断。
移除已处理的标记，保留并列出尚需核实的批注。

如果文件就在当前工作区，Codex 可以直接读文件；如果文件不在当前工作区，可以把带批注的小节添加到对话。长文不必整篇复制，每次给一个小节更稳。片段前面带上标题，模型就能定位语境。

最后让 Codex 输出 clean 版，并保留必要 diff。对博客这种内容，我更愿意让它直接改文件，然后跑一次 Markdown 风格扫描和站点生成；对方案文档，可以先输出一版 clean Markdown，再决定是否覆盖。

这比行号反馈舒服很多。你不需要描述「第三段第二句」，也不需要担心换行后行号变了。批注本身跟着文字走。

边界要提前接受

CriticMarkup 把审阅意见留在纯文本里，使用时要注意标记范围、定位上下文和清理方式。

第一，不要把大段跨多小节内容塞进同一个标记。多行、跨表格、跨代码块的批注会增加解析和渲染风险。更稳的做法是拆成几处小批注。

第二，代码块里要谨慎使用。Markdown fenced code 里的 {++ ++} 可能本来就是示例代码，AI 也可能误判它是批注。给代码示例提意见时，我更倾向于在代码块外加 comment。

第三，重复文本需要上下文。同一句话在文章里出现多次时，只复制一句批注回来，模型未必知道改哪里。保留所在标题和前后两三句，命中率会高很多。

第四，接受和拒绝最好由工具或脚本做，不要靠肉眼全局替换。尤其是 substitution 和 comment 混在一起时，手工清理很容易漏掉半个标记。

第五，它不解决「谁说了算」。批注只是把意见带回模型，最终仍然要有人看 clean 版。AI 可以执行改稿，但不能替你判断文章是否真的变好了。

批注也不是天然获得授权的指令。自己写的改稿意见，可以连同明确任务一起交给 Agent；来自外部文档、他人批注或示例代码的标记，仍只是待审阅材料。意见与事实、权限或当前任务冲突时，应先核对，不能因为它写在 comment 里就执行命令或删掉其他文件。未解决的批注也不应在「清理标记」时悄悄消失。

总结

CriticMarkup 把新增、删除、替换和评论保存在 Markdown 纯文本里，让审阅意见与原文一起交给 Agent。MarkMark 展示了怎么从渲染后的选区发起批注。在 Windows 上，桌面阅读器和编辑器插件都能把审阅意见写回原文件。文件因此保留了可供编辑器、Git 和模型共同读取的审阅信息，减少反复用行号定位的成本。

只改当前选区，直接添加到对话；正式审阅长稿，用 CriticMarkup 把意见留在文件里。两种入口不冲突，也不需要等所有编辑器都具备完整批注界面后再使用。

交还稿件时，一并检查干净正文和 diff，确认修改确实回应了批注，未解决的意见仍有记录。文本协议让意见容易传递，最终改得怎样，仍要回到成稿判断。