一、先说一个很多人默认跳过的环节
用 AI 写代码，大多数人卡在同一个地方：你其实没在认真 review 它写的东西。
不是不想，是成本太高。AI 一次给你改 8 个文件、300 行 diff，你扫一眼，觉得第 42 行的错误处理不对、第 70 行那个命名别扭、某个函数缺个边界判断——然后呢？你有三条路，每条都难受：
- 切回聊天框用自然语言描述：「你刚才那个导出函数，大概在中间位置，有个地方没处理空数组」。AI 经常找错位置，改到别的地方，你还得再描述一遍。你心里清楚问题在哪一行，可这个「哪一行」传不过去。
- 自己动手改：那 AI 帮你省的时间又还回去了，而且你改完 AI 下一轮可能又覆盖掉。
- 干脆不细看，直接提交：这是最常见的，也是 AI 代码事故的主要来源。
问题的本质是：「评审」和「让 AI 改」是两个断开的动作。 你看 diff 是在一个地方，给 AI 下指令是在另一个地方，中间靠你用自然语言当「人肉坐标系」把问题重新定位一遍。信息在这一步大量丢失。
有人会说「那走 GitHub PR 评论啊」。可以，但 PR 评论要先 push 才有 diff 可评，你是在已经推上去的代码上评审；而 AI 写代码是本地、高频、还没想提交的状态——你想在它还没 push、甚至还没 commit 的时候就逐行挑刺、让它立刻改。PR 流程太重，对不上这个节奏。
下面讲一套把这两个动作接起来的做法：在本地 diff 上逐行批注，让批注自己带着文件和行号，一键发回正在干活的 agent。
二、机制：让批注自己带坐标
先说原理，你换任何工具都能自己判断。
一条行级批注要有用，它必须携带三样东西：改哪个文件、哪一行（或哪个区间）、你想说什么。 只要这三样齐全，AI 就不需要你再用自然语言描述位置——坐标已经在批注里了。
DevAgent 里每条批注就是这么一个结构：
File: src/export.ts
Line: 42
User comment: "这里没处理空数组，rows 为空时会抛异常"
区间批注会变成 Lines: 42-50，整文件级的变成 Scope: file。多条批注攒在一起，就是一份确定格式、引号安全的提示词——这份格式是批注和 agent 之间的契约，发给任何 agent 都能稳定解析。
关键点有三个：
- 批注挂在改动的那一侧（modified side），不是原始代码。你评的是「AI 改成了什么」，不是「原来是什么」。
- 批注存在 worktree 上，会持久化。你今天挑了一半的刺，关掉应用明天接着挑，批注还在。
- 批注记得自己发没发过。发给 agent 之后它被标记为「已发送」；你一旦编辑它，这个标记就清掉——提醒你这条改过、需要重发。
有了带坐标的批注，剩下的就是把它递给谁。
三、实操：批注 → 发回 → 复查 → 提交
以 DevAgent 为例（它把这条链路做进了 GUI），每一步的原理通用。
第 1 步：打开改动的合并 diff
一个 worktree 的所有改动汇总在一个 diff 面板里：文件树 + 逐文件对比，支持并排 / 行内切换、按段落加载，改动大也不会一次糊满屏幕。你看到的就是 AI 这一轮到底动了什么。
第 2 步：在要改的行上批注
在改动侧选中一行、或拖选一个区间，写下你的意见。你不是在跟 AI 聊天，你是在代码的具体位置上留话。markdown 文件还能选中一段文字批注，连选的原文都一起带上。
第 3 步：攒一批，工具栏上看计数
批注不用一条一条发。挑刺的时候一路加，工具栏上那个「AI 笔记」计数在涨。点开能预览每一条（带文件和行号）、一键复制成提示词、或全部清空。一轮 review 挑完十几条，再一起处理。
第 4 步：一键把这批意见交给 agent
点「Send」，菜单让你选谁来处理这批意见：这个 worktree 里正在跑的 agent 会列在这里，你也可以新开一个 agent专门处理这批修改——不限于你当前盯着的那个终端。
所有批注会拼成一条提示词发过去，每条都带着 File / Line / User comment。agent 拿到的是精确坐标 + 你的原话，不用猜你指的是哪儿。
第 5 步：agent 改完，你复查，就地提交
agent 按批注改完，你在同一个窗口里再看一遍新的 diff——满意就在旁边的源码控制面板：暂存、让它生成 commit message、提交、发 PR。批注、diff、提交三样并排在一个窗口里。
这里要说实话：工具不会替你把 AI 的改动自动合并进去。 它做的是把「你的意见精确传给 AI」和「复查、提交」放进同一个窗口，让 review → 改 → 复查 → 提交形成闭环，而不是让你在聊天框、编辑器、终端 git 之间来回跳。判断始终在你这。
四、DevAgent 在这条链路上省掉了什么
同样的事你也能手动拼：看 diff，心里记下问题，切回终端或聊天框，用自然语言把每个问题的位置重新描述一遍，等 AI 改，再看。能做，就是信息在「描述位置」这一步反复丢失。这套闭环省的是：
- 定位不再靠人肉描述：批注自带文件 + 行号 + 原话，拼成确定格式的提示词，AI 不用猜位置。
- 不用 push 就能评审本地改动：PR 评论要先推上去；这里评的是本地、还没 commit 的 diff，节奏对得上 AI 高频改代码。
- 批注能发给任意在跑的 agent，或新开一个：不限于当前这个终端——你可以把意见甩给专门负责修改的那个 agent。
- 一批批注一次发：挑刺时一路加，攒够十几条一起发，而不是发现一个描述一个。
- review 和提交在同一个窗口闭环：看 diff、批注、发回、复查、生成 commit message、提交、发 PR，全程不离开，不用切终端敲
git。
一句话：行号是 git diff 本来就有的信息，DevAgent 省的是「把行号和你的意见一起、准确地交给 AI」这一步。
五、这套做法的边界（照例说清楚）
- 不自动改：发给 agent 的是提示词，不是结构化补丁。agent 自己理解、自己动手，改得对不对要你复查。工具负责把话带准，不负责替 AI 写对。
- Send 需要有 agent 可发：要么 worktree 里有在跑的 agent，要么你当场新开一个。没有 agent 就只能先复制批注、自己贴。
- 批注是 prompt，不是 patch：它优化的是「沟通精度」，不是「自动套用」。一条含糊的批注（「这里不好」）AI 照样会改歪。
- 提交在相邻面板：批注、发送在 diff 面板，暂存、提交、生成 message 在旁边的源码控制面板——同一个窗口，但不是同一个工具栏。
- 它不替代最终把关：逐行批注让 review 变轻，但「这版能不能合」仍然是你的判断。
六、什么场景最值
值得用的：
- AI 一次改动大（几个文件、上百行），你想精确挑几处让它返工，而不是整体重做；
- 命名、错误处理、边界条件这类「位置明确、说一句就懂」的小修，批注比重新描述快得多；
- 你在带新人 / 带 agent，想把「哪里该怎么改」沉淀成具体位置上的意见，而不是口头说；
- 本地高频迭代、还没到 PR 阶段，但已经想认真看每一轮改动。
不太值的：
- 改一两行的小 diff，直接说比批注快；
- 问题是「整体思路不对」，那不是逐行批注能解决的，该重开一轮对话讲清目标；
- 你本来就不打算 review——那什么工具都救不了。
七、试一下
如果你现在的习惯是「AI 写完扫一眼就提交」，那这套东西值得试一次。最快的验证方式：拿一段 AI 刚给你改的、你隐约觉得哪里不对的代码，打开它的 diff，在你最不放心的那两三行上各写一句批注，一键发回去，看它改得准不准。你会立刻感到「说一句就懂」和「描述半天还找错地方」的差别。
下载与安装（Windows / macOS / Linux，链接始终指向最新版本）：docs.devagent.clouditera.com/guide/insta…
