Plannotator:给编码代理的计划与 diff 审阅台
Plannotator 是本地浏览器审阅台:Claude Code、Codex 等 11 个客户端的计划与 diff 在这里批注,反馈结构化回灌给会话。
项目资料
GitHub Ecosystem- 许可证
- Apache-2.0
- 主语言
- TypeScript
- 星标
- 12,742
- 核查时间
- 2026-11-17
以上快照资料以核查当日为准,可能随版本或运营策略变化。

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

要点
- 部署形态:一个
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 |
| 最新 release | v0.28.66,2026-11-16 |
核心功能
Plannotator 的功能都围绕一件事:把你对一份文本的意见,变成代理下一条消息能直接执行的输入。
- 计划拦截:Claude Code 上,代理调用
ExitPlanMode时由PermissionRequesthook 接管,本地服务从 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 不是又一个网页服务,理解它的部署方式比记功能列表更有用。
- 本机进程加浏览器:每次 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 还在等待名单里。

快速上手
安装脚本会装二进制、探测本机已有的代理,并给每个代理配好 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 才跑,普通安装不校验。