它管的是"改完"到"合入"中间那一段
官方文档里的定义是这一句:
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 与行号,还有originrecords/<时间戳>-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 里是我三条批注的原文,加上那段"逐条核、没讨论完不许改代码"的收尾。
三条我踩到的坑
- 装完当前终端找不到命令 。安装脚本把目录写进 PATH 了,但已经在跑的终端读不到,
plannotator --version直接报找不到。要么重开终端,要么走完整路径& "$env:LOCALAPPDATA\plannotator\plannotator.exe" --version。 sessions查不到刚做完的评审 。它会报No active Plannotator sessions,因为只列正在跑的会话。历史在~/.plannotator/feedback/下按项目分目录,回头要看就开文件,别敲sessions。- 首次打开要连点五个引导层。Guided Reviews、plans look、Edit code to suggest、Hover cards、TUI 宣传,一层层点 Got it / Done / Continue 才落到 diff 上。换浏览器配置或者换机器,这套还会再来一遍。
意见贴在行上,比贴在对话里更容易被兑现。
那个演示仓库里三条批注,我写的全是"这行会怎么出错",没有一条是"这段写得不好"。行级位置本身就逼着人说到具体那一行,agent 也只能回到那一行去核。
什么情况下它值得留在工具链里:经常让 agent 一次改好几个文件,又习惯在提交前自己过一遍,那它省下的就是"把 diff 复制进聊天框、再一句句解释哪里不对"的那段时间。什么情况下不必装:一次只改一个函数、看完就提交,终端里扫一眼就够了;要在公司里推开还得先问一句 Artifact Server 那条商业许可。
它省的不是读代码的时间,是把"哪里不对"翻译成 agent 能照着核的话的那段时间。
装一次,跑一次,就知道它该不该留在你的工具链里。
本文为原创内容,首发发布于本平台;未经授权请勿转载。