开发工具#代码智能体#代码审查

Plannotator:给编码代理的计划与 diff 审阅台

Plannotator 是本地浏览器审阅台:Claude Code、Codex 等 11 个客户端的计划与 diff 在这里批注,反馈结构化回灌给会话。

项目资料

GitHub Ecosystem
仓库地址github.com/backnotprop/plannotator
许可证
Apache-2.0
主语言
TypeScript
星标
12,742
核查时间
2026-11-17

以上快照资料以核查当日为准,可能随版本或运营策略变化。

GitHub 为 backnotprop/plannotator 生成的仓库卡片:左侧是仓库名与简介,右侧是作者头像,底部是贡献者、issue、星标与分叉数

读代理写的计划,有时比读它写的代码更费劲。计划是一整段 Markdown,你想删掉第三条、把第五条换个说法,只能在聊天框里复述一遍,代理再猜你想改哪儿。Plannotator 把这一步搬到浏览器:代理要退出计划模式、或者跑完一轮改动时,它在本机起一个页面,你在正文上划词批注、在 diff 上按行留意见,点一下发送,反馈以结构化文本回到同一个会话。仓库 backnotprop/plannotator 建库于 2025-12-28,截至 2026-11-17 有 12,742 星。

GitHub 为 backnotprop/plannotator 生成的仓库卡片,显示仓库名、简介与 13k 星标

要点

  • 部署形态:一个 plannotator 二进制加本机 HTTP 服务,界面在浏览器里打开,靠各家代理的 hook、插件或命令触发。它没有云端账号体系,审阅数据默认写在 ~/.plannotator。
  • 覆盖面:README 的安装表列了 11 个客户端——Amp、Claude Code、Codex、Copilot CLI、DeepSeek Harness、Droid、Gemini CLI、Kiro CLI、OpenCode、Pi、T3 Code;其他代理可以走 plannotator inbox mcp 接进来。
  • 节奏:release 累计 229 个,最新 v0.28.66 发布于 2026-11-16;仓库 11 月 17 日仍有推送,未归档。
项目值(2026-11-17 核对)
星标 / 分叉12,742 / 1,256
许可Apache-2.0(README 写 Apache 或 MIT 双许可)
语言TypeScript
建库时间2025-12-28
最新 releasev0.28.66,2026-11-16

核心功能

Plannotator 的功能都围绕一件事:把你对一份文本的意见,变成代理下一条消息能直接执行的输入。

  • 计划拦截:Claude Code 上,代理调用 ExitPlanMode 时由 PermissionRequest hook 接管,本地服务从 hook 输入里读到计划,浏览器打开审阅界面;你批准,代理继续,你拒绝,就把批注作为结构化反馈发回去,代理改完再显示新旧计划的 diff。整个过程不需要额外命令。
  • diff 审阅:/plannotator-review 抓 git diff HEAD 打开 diff 视图,也能直接传 GitHub PR 或 GitLab MR 链接,或 plannotator review --gitbutler 看一个 GitButler 工作区。支持的版本控制不止 git:GitButler、Jujutsu(jj)、Perforce(p4)都在 README 里点名。
  • 批注即输入:审阅界面里可以选一段正文标记删除、写行内评论、给出替换文本;diff 里能按行留言、附建议代码、顺手 stage 或 unstage 文件。批准时发出去的是一句 LGTM,拒绝时发出去的是结构化意见(README 未说明具体格式)。
  • 引导式审阅:在 diff 视图里按 Guide(或 Cmd/Ctrl+Shift+G),代理会把改动拆成章节,最要紧的部分排在最前,每章左边一段概述、右边真实 diff。大改动先看骨架,比从第一行滚到最后一行省事。
  • HTML 与本地站点:/plannotator-annotate report.html --render-html 直接标注渲染后的 HTML;plannotator annotate http://localhost:5173 通过本地代理打开正在开发的前端,热更新照常工作。站内写过的 effective-html 那 6 个技能产出的自包含 HTML,正好是这里要标注的对象。

Plannotator 的批注界面:左侧是文档目录与章节,中间正文高亮了一段,右侧列出两条批注,旁边是触发它的 Claude Code 终端

它跑在哪

Plannotator 不是又一个网页服务,理解它的部署方式比记功能列表更有用。

  • 本机进程加浏览器:每次 hook 调用都会在随机端口起一个本地服务,界面是一个单文件 HTML,跑完即走。也正因为端口每次都变,界面设置存在 cookie 里而不是 localStorage。
  • 远程与容器:SSH 会话会自动切到固定端口 19432;devcontainer 或 Docker 里设 PLANNOTATOR_REMOTE=1 和 PLANNOTATOR_PORT,再把端口转发出去。
  • 数据的去处:计划、批注、草稿、配置都在 ~/.plannotator,可用 PLANNOTATOR_DATA_DIR 搬家。反馈归档默认开启,记录审阅文本与被引用的片段(不含 diff 本身),隐私页写明「Nothing prunes the directory」——不手动删就一直留着,不想要就得设 PLANNOTATOR_FEEDBACK_HISTORY=0。
  • 网络边界:默认每天每个用到的工具发一次匿名 ping 到 ping.plannotator.ai,只带工具名、版本、使用周数之类,没有身份标识,NO_ANON_PING=1 可关。首页写的是「no usage telemetry」,隐私页写的是一天一次匿名 ping,两处口径不一致,按隐私页理解更准。
  • 分享是可选项:小份计划直接压进链接片段(压缩,不是加密,拿到完整链接就能读);大份用 AES-256-GCM 加密后上传,托管服务 7 天后删除密文,密钥留在 URL 片段里。不想用就设 PLANNOTATOR_SHARE=disabled。

典型使用场景

  • 让代理先交计划再动手:把需求丢给 Claude Code,计划在你的批注里过一遍再放行,比等它改完 20 个文件再回滚便宜。作者在 2026-01-03 的博客里写,起点是计划管理这块一直缺工具——代理会写计划,但读计划、改计划的界面一直缺。
  • 一天开好几个会话:并行跑代理时,每个会话都会在某个点等你决策。plannotator inbox 把这些请求收进一个本地收件箱,代理不占着会话空转,你有空再点;Claude Code、Pi、OpenCode 通过插件接入,其他代理走 MCP。
  • 审别人的大 PR:用 /plannotator-review <PR 链接> 打开完整 diff 视图,开引导式审阅先看章节概述,批注完把意见发给自己会话里的代理去处理,或者导回给作者。
  • 非技术同事看原型:把计划或 HTML 原型发成链接,对方在浏览器里批注,你再把反馈导入给代理。这一步是 Plannotator 少见的协作面,团队版的 Workspaces 还在等待名单里。

Plannotator 的代码审阅界面:左侧文件树与改动统计,中间并排 diff,某一行上挂着批注框,右上角是 Approve 按钮

快速上手

安装脚本会装二进制、探测本机已有的代理,并给每个代理配好 hook、技能和斜杠命令:

curl -fsSL https://plannotator.ai/install.sh | bash

只想先要二进制,加 --minimal,它只往 ~/.local/bin 放一个 plannotator,其他一概不动。装完在代理里试三条命令,就知道它长什么样:

/plannotator-last                  # 批注代理的上一条回复
/plannotator-review                # 按 PR 的方式审当前改动
/plannotator-annotate report.html  # 批注文件、目录或 URL

计划审阅不用命令:下一次代理提出计划时,浏览器会自己弹出来。各家客户端装完的收尾不一样,README 的表格是准的,这里挑几个差异大的:

客户端装完还要做什么
Codex什么都不用做,靠实验性的 Stop hook 生效;命令换成 $plannotator-* 技能
Claude Code跑完安装脚本还要 /plugin marketplace add backnotprop/plannotator、/plugin install plannotator@plannotator,再重启
Pi跳过安装脚本,pi install npm:@plannotator/pi-extension,用 --plan 启动
Droid只有命令,没有计划拦截
Gemini CLI自动配置,要求 Gemini CLI 0.36.0 及以上

小结

Plannotator 适合每天都在用编码代理、并且真的会读计划的人:它把「在聊天框里描述我想改哪儿」换成「在原文上划出来」,反馈的形状对了,代理的返工就少。它也适合要审别人 PR、又不想把代码推到远端仓库的人。不适合的是很少看计划、直接让代理跑完看结果的用法——多一个窗口只是多一步。

许可是 Apache-2.0,README 同时给了 MIT 选项,按任一使用;TypeScript 编写,2026-11-17 为 12,742 星。它和站内写过的 OpenCodeReview 是两条路:后者让 AI 生成审查意见,人只看结果;Plannotator 反过来,人出意见,AI 执行。选哪个取决于你信谁的眼睛。

要留意的短板有三个。远程模式监听 0.0.0.0 且没有登录,任何能连到这个端口的人都能用,README 自己提醒要把端口关在可信网络里。客户端能力也不齐:Droid 还没有计划拦截,其余全靠各家代理的 hook,代理升级后可能要重配。发布侧做得比多数同类项目认真——每个 release 带 SHA256 校验文件,v0.17.2 起有 SLSA provenance,还附 CycloneDX SBOM 并用 Grype 过一遍——但这套验证要手动加 --verify-attestation 才跑,普通安装不校验。