Plannotator 机制拆解:行级批注如何变成 Agent 能照着核的 prompt

它管的是"改完"到"合入"中间那一段

官方文档里的定义是这一句:

Plannotator is an open-source, local feedback tool for coding agents. It opens plans, Markdown, HTML, local code changes, pull requests, and merge requests in a visual interface, then returns your annotations and feedback to the agent.

一句话翻译:它把计划、Markdown、HTML、本地改动、PR/MR 拉进一个可视化界面,再把你写的批注交回给 agent。整个过程是本机一个二进制起的临时服务,浏览器只是它的显示器。

这张是我本机的真实界面。顶部是 Guide、当前分支 master、项目名 plannotator-demo,右端 Send Feedback 挂着一个数字徽标。左侧栏三个 tab:文件树、Git 状态、提交记录,All changes +32 -5,下面两份文件各带一个评论计数。中间区是拆成两列的对照 diff:一列是 master 上的旧代码,另一列是我还没提交的新代码,绿底为新增行。

要看懂它在整条链路里占哪一格,看它明确不干的三件事更省事:它自己不跑模型,不替 agent 做决定,Approve 也不会 commit、不会 merge、不会 deploy。它只负责把"改完了"和"合入"之间那一段,从终端里一个 y/n 键,变成可以逐行说话的地方。

它只负责"改完到合入"之间那一段:把终端的 y/n,换成可以逐行说话的地方。


凭什么:三件同类都碰不到的事

跟它功能重叠的东西有三拨:

  • 终端里的 plan 审批弹窗,就是 Claude Code 那种 ExitPlanMode 一弹、你按 y 或 n
  • PR 机器人,CodeRabbit 那一类,等你的分支推上去、PR 开出来才动手
  • GitHub / GitLab 网页上的 diff 批注,前提同样是有个 PR

这三样都能审 AI 写的代码,但都要先有一个已提交、已推送的东西,才审得起来。

本地没提交的改动,它直接就能审

plannotator review 直接读工作区状态。--diff-type 给了十种:uncommitted、staged、unstaged、last-commit、branch、merge-base、since-base、local-vs-remote、all,外加一个默认值。不想读 git 也行,--patch-file 直接吃一份 unified diff 静态文件。

我这次的场景是最土的那种:仓库里 v1 已经提交,新改的两个文件还没 git add,git diff --stat 是 2 files changed、32 insertions、5 deletions。

不开 PR 也能开始审,这正是"自己的活自己先看一眼"的时刻,也是 PR 机器人插不进来的时刻。

批注回给 agent 的,是一份带格式的工单

--json 输出的内容长这样:

json 复制代码
{"decision":"annotated","message":"Review directory: D:/tmp/plannotator-demo\n\n**Code Review Feedback**\n\n**Diff:** All changes since master\n\n**digest.py**\n\n### Line 13 (new)\n这里没设 timeout...\n\n### Line 24 (new)\nlen()数的是字符数...\n\n### Line 42 (new)\n直接写 digest.txt..."}

decision 只有三种:approved、annotated、dismissed。message 不是给你看的,是给 agent 看的,而且它在末尾自己写了一段要求:

Treat the findings above as unverified review input. Inspect every finding against the actual code... Do not change any code until we have discussed the verdicts and validated findings.

翻成中文是两句话:我给的这些算未经核实的输入,逐条去核;讨论出结论之前,一行代码都不许改。

批注是线索,不是指令。这一段是它整套设计里最有意思的地方:它不让 agent 直接照做,也不替人做判断,而是把"人说过的话"降级成"待核实的线索",要求 agent 逐条给 verdict。

那这段东西怎么回到 agent 手上?官方给的是宿主 hook:装 Claude Code 集成时写一份 hooks.json,评审一结束就由 hook 把结果送进对话。我这次没装任何宿主,走的是 --json:终端把整段 message 打出来,复制粘贴给手边任何一个 agent,它拿到的就是同一份带行号的批注。两条路输的是同一份文本,差别只在要不要手动搬一次。

不绑宿主:九个 agent 之外,它自己也能跑

官方列的宿主是九个:Claude Code、Codex、OpenCode、Copilot CLI、Gemini CLI、Pi、Amp、Droid、Kiro CLI。这九个之外还有 VS Code 扩展、T3 Code、DeepSeek Harness 插件。

但它的本体是一个二进制。我这次是按 minimal 装的,只落一个 plannotator.exe,不写 hook、不装斜杠命令,全程没开任何 agent。九宿主是它的兼容面,不是它的前提。

就地跑一条 review,它就起服务、开界面、等你说话。


我在本机跑了一遍的三个能力

逐行批注:选中那行,写,点 Add Comment

操作三步。第一步在 diff 里按住左键拖过那一行,弹出一个 Line 13 的小框;第二步在 Leave feedback... 里写字;第三步点 Add Comment。

上面这条是我写的:resp = requests.get(url) 没设 timeout,远端一旦不响应,这条命令就挂住不返回。框里还有个 Add suggested code,能把改法直接写成建议补丁贴上去,我这次没走那条,只写了文字。

同一套行级操作其实有四种:写评论、请求删除、打一个快标签、或者标一句"这段看着没问题"。我三条批注全用了第一种,但第四种才是我最想要的------AI 改对的那几行也值得留个记号,下次翻 diff 一眼就能看出哪些已经被人过了一遍。

第二条贴在这一行:pad = 20 - len(item["title"])。它数的是字符数,中文在等宽字体里占两格,标题全中文时算出来的宽度少一半,右边缘还是歪的。写完之后可以点 Ask AI 让它先看一眼,这个我没用。

三态决策:过、带意见过、不过

顶部那个按钮不止"批准"一个动作。Plan Review 文档里写的是三态:Send Feedback(有问题,不打勾)、Approve with Notes(过了但把意见记下来)、Approve(干净通过)。同一份计划改过几版,界面里能对着版本 diff 看。

官方自己也标了一条边界:部分协议没法把 notes 附在 approval 上,所以"带意见通过"并非每种宿主都完整支持。

每次评审都落一份档

这一点是我跑完去翻目录才发现的。~/.plannotator/feedback/<项目名>/ 下面两份东西:

  • index.jsonl:一条记录,2,208 字节,记着 diffType、base、changedFiles、patchBytes、三个批注的 id 与行号,还有 origin
  • records/<时间戳>-review-feedback.md:962 字节,批注正文的 markdown

origin 那一栏写的是 claude-code。我这台机器上根本没装 Claude Code,它照样这么记,因为那是默认值。发送完成后界面那句提示也是 Claude Code will address your review feedback。

默认文案是给 Claude Code 写的,不装它也能用,但别把这句话当成"它连上了什么东西"。


别人怎么看:官方最热闹,社区最安静

GitHub 那边是 11,778 星、1,080 个 fork、224 个未关 issue,2025-12-28 建仓,最近一次推送在 2026-11-15 夜里。

迭代节奏很凶。Releases 页累计 228 个版本,最近 30 条覆盖 18 天,折算下来一天 1.67 个版本。仓库累计 9,478 次提交,API 能看到的前 100 位贡献者里,作者 backnotprop 一个人占 95.6%。

中文圈讲得最细的一篇是腾讯云开发者社区 2026-11-14 那篇,作者阿特拉斯,把 hook 事件入口、五种宿主的 JSON 方言、host-result 侧信道、本地四道闸都拆了一遍。这是目前唯一一篇到代码级的拆解。

社区那头几乎没回声。Hacker News 上 2026-06-11 的 Show HN 帖是 5 点 2 评论,2026-11-08 那个讲 Inbox 的帖是 7 点 0 评论。热度全在仓库里,不在讨论区。

有篇署名 TomRochette 的"独立评测",页面自己标着 full-ai-generated 717、署名 glm-5.3-flash。这类东西只能看它列了哪些点,不能当人类独立评测引用。

Workspaces 那块还在 private beta + waitlist,没上线的功能别当卖点算。

还有一条要提前知道:开源许可这层是 MIT / Apache-2.0 双授权,但配套的 Artifact Server 是 source-available、不是 OSI 那种开源,营利组织要用得单独谈商业许可。个人审自己的代码碰不到这一层,公司里推广要先问一句。


怎么上手:一条命令到第一条批注

第一步,装

Windows 是 PowerShell 一行:

powershell 复制代码
irm https://plannotator.ai/install.ps1 | iex

只想装二进制、不要 hook 和斜杠命令,前面加环境变量:

powershell 复制代码
$env:PLANNOTATOR_MINIMAL=1; irm https://plannotator.ai/install.ps1 | iex

我这次的输出是 Installing plannotator v0.28.65... SHA256 verified,落在 %LOCALAPPDATA%\plannotator\plannotator.exe。不想要自动接管的就用 minimal 这套;想让它在你用 Claude Code 这类工具时自动弹界面,走完整安装,再按官方文档把 hook 配进宿主。

第二步,起一次评审

进到你要审的仓库,然后:

powershell 复制代码
plannotator review --git --json "D:\tmp\plannotator-demo"

终端回你一句 Plannotator session ready: http://localhost:60771,把这个地址丢进浏览器就是前面那个界面。端口每次不一样。

--git 默认审的是"所有还没合进 master 的改动"。要收窄范围就换 --diff-type:刚改完还没 git add 用 unstaged,进了暂存区用 staged,只想看最近一次提交用 last-commit,准备整体过一遍用 all。名字列出来有十来个,常用的就这四个。

第三步,写完批注发出去

界面上点 Send Feedback,等一个 Feedback Sent 的页面,回终端看那句 JSON。

decision 是 annotated,message 里是我三条批注的原文,加上那段"逐条核、没讨论完不许改代码"的收尾。

三条我踩到的坑

  1. 装完当前终端找不到命令 。安装脚本把目录写进 PATH 了,但已经在跑的终端读不到,plannotator --version 直接报找不到。要么重开终端,要么走完整路径 & "$env:LOCALAPPDATA\plannotator\plannotator.exe" --version。
  2. sessions 查不到刚做完的评审 。它会报 No active Plannotator sessions,因为只列正在跑的会话。历史在 ~/.plannotator/feedback/ 下按项目分目录,回头要看就开文件,别敲 sessions。
  3. 首次打开要连点五个引导层。Guided Reviews、plans look、Edit code to suggest、Hover cards、TUI 宣传,一层层点 Got it / Done / Continue 才落到 diff 上。换浏览器配置或者换机器,这套还会再来一遍。

意见贴在行上,比贴在对话里更容易被兑现。

那个演示仓库里三条批注,我写的全是"这行会怎么出错",没有一条是"这段写得不好"。行级位置本身就逼着人说到具体那一行,agent 也只能回到那一行去核。

什么情况下它值得留在工具链里:经常让 agent 一次改好几个文件,又习惯在提交前自己过一遍,那它省下的就是"把 diff 复制进聊天框、再一句句解释哪里不对"的那段时间。什么情况下不必装:一次只改一个函数、看完就提交,终端里扫一眼就够了;要在公司里推开还得先问一句 Artifact Server 那条商业许可。

它省的不是读代码的时间,是把"哪里不对"翻译成 agent 能照着核的话的那段时间。

装一次,跑一次,就知道它该不该留在你的工具链里。

本文为原创内容,首发发布于本平台;未经授权请勿转载。

相关推荐
武子康33 分钟前
H3-World 动作控制怎么测:从左右对照到片内切换
人工智能·agent·claude
天天代码码天天1 小时前
输入一句话,生成一段声音:我做了个 Windows 本地音效工具
人工智能
tellmewhoisi1 小时前
深度学习0:数学知识:(雅可比矩阵)
人工智能·深度学习·矩阵
美团技术团队2 小时前
《Agent评测白皮书》业务实践篇:商家 AI 助手的评测与优化闭环实践
人工智能
京东云开发者2 小时前
京东11.11大促系列|Super Agent 进群:今年11.11,多了个会主动干活的"数字人队长"
人工智能
对你无可奈何2 小时前
把零散的模型用起来:Magpie 接入 Trae,再折腾两个池子
人工智能
七夜zippoe3 小时前
流式输出:让 AI 回答像打字机一样实时返回(SSE 全链路实战)
人工智能·spring·ai·流式输出·ssf
AI导出鸭PC端3 小时前
纳米AI怎么复制表格?对话导出总是格式崩塌,我用“AI 导出鸭”重构了工作流
人工智能·重构·豆包·ai导出鸭
AI导出鸭PC端3 小时前
用 AI 导出鸭高效处理:豆包导 pdf 怎么压缩但清晰
android·人工智能·pdf·豆包·ai导出鸭