你的编程智能体刚刚提出了一个十二步的计划,想在开始重写你的项目之前得到你的点头。你在终端里扫了一眼,敲下“looks good”(看起来不错),然后祈祷第九步别删掉你喜欢的东西。
Plannotator 是一款开源工具,它把这种走马观花换成了一次像样的审阅:计划在浏览器中打开,你逐行写批注,批注直接回传给智能体。下面介绍如何在任何代码写出来之前完成设置并用上它。
准备工作
- 一个受支持的编程智能体。README 列出了 Claude Code、Codex、Copilot CLI、Gemini CLI、OpenCode、Kiro、Droid、Amp 和 Pi。
- 一个终端和一个浏览器。用 README 的原话说,Plannotator 是“a local, browser-based review surface”(一个在本地运行、基于浏览器的审阅界面)。
- Git。根据 Plannotator 的安装文档,安装程序需要它来安装 skills。
Plannotator 免费,采用 Apache 2.0 或 MIT 双许可证。截至 2026 年 11 月 15 日,其 GitHub 仓库(backnotprop/plannotator)约有 11,400 颗星。仓库创建于 2025 年 12 月 28 日,最新版本 v0.28.65 也在当天发布。下面的命令均摘自截至 2026 年 11 月 15 日的 README 和文档,并已与这些页面核对;这些 shell 命令通过了语法检查,但我们没有为撰写本文实际安装 Plannotator。
第 1 步:安装程序
在 macOS、Linux 或 WSL 上:
curl -fsSL https://plannotator.ai/install.sh | bash
在 Windows PowerShell 中:
irm https://plannotator.ai/install.ps1 | iex
根据文档,安装程序会添加 plannotator 命令,用 SHA-256 校验和核验下载文件,并为它找到的智能体安装 hooks 和核心 skills。首次运行时,它会询问是否添加额外的 skills,默认答案是否。检查一下是否安装成功:
plannotator --version
如果你对把脚本直接通过管道交给 shell 执行心存顾虑,文档还提供了只安装二进制文件的方式(--minimal),以及锁定版本并验证其来源的方法。
第 2 步:连接你的智能体
Claude Code 需要多做一步。在 Claude Code 中运行:
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator
然后重启 Claude Code。根据 README,Codex 和 Gemini CLI 无需额外操作(Gemini 需要 0.36.0 或更高版本),OpenCode 需要在 opencode.json 中加入 "plugin": ["@plannotator/opencode@latest"],Pi 则使用 pi install npm:@plannotator/pi-extension。如果你刚接触 hooks 和 skills,我们的 Claude Code 智能体 skills 指南会讲清楚其中的各个环节。
第 3 步:让智能体写出计划
这一步不用输入任何命令。README 说明,计划模式通过各智能体的 hooks 接入,所以下次你的智能体完成计划时,审阅界面会自动打开。
在幕后,README 描述的流程如下:
- 智能体完成计划并请求退出计划模式(README 把这一步称为
ExitPlanMode)。 - 一个 hook 被触发,本地服务器在你的浏览器中打开计划。
- 你写好批注,然后批准或拒绝。
- 如果你拒绝,结构化的反馈会发回给智能体,由它修改计划。计划 diff 会显示改动了哪些内容。
Plannotator 官网称,你可以对各个部分发表评论、标记要删除的文字或写下替换内容,然后附上这些反馈批准或拒绝。
预期结果:浏览器中打开一个显示你计划的标签页,可以开始批注。
第 4 步:批注已有的内容
Plannotator 不只用于计划。以下命令来自 README:
/plannotator-last
/plannotator-annotate README.md
/plannotator-annotate src/
/plannotator-review
第一条用来批注智能体的最后一条消息。第二条和第三条用来标注某个文件或文件夹。最后一条会为你尚未提交的改动打开一个类似 pull request 的 diff 查看器,你也可以改为传入 GitHub PR 或 GitLab merge request 的 URL。在 Codex 中,把斜杠命令换成 $plannotator-* skills。
它如何处理你的数据
README 表示,Plannotator“does not collect usage telemetry or analytics”(不收集使用遥测或分析数据),计划、diff 和批注默认都保存在本地。它也列出了几项值得了解的例外:
- 每个审阅界面在加载时都会向 GitHub 查询最新版本。README 称,目前无法关闭这项检查。
- “Ask AI”会把问题和相关上下文发送给你配置的服务提供商。
- 分享计划会生成一个链接。根据 README,小型分享内容会未经加密直接打包进链接本身,因此任何拿到链接的人都能读取。大型分享内容会在上传前加密,托管的粘贴内容 7 天后过期。
常见错误及解决方法
plannotator: command not found。打开一个新终端。文档说你的PATH可能已经改变。- 通过 SSH 或在容器中无法加载审阅页面。README 称,通过 SSH 时 Plannotator 会改用固定端口 19432,对应
~/.ssh/config的配置行是LocalForward 19432 localhost:19432。在容器中或想用其他端口时,设置PLANNOTATOR_REMOTE=1和PLANNOTATOR_PORT=9999,然后转发该端口。刚接触 SSH?请看我们的 SSH 密钥指南。 - 远程模式完全敞开。README 警告,在远程模式下服务器监听
0.0.0.0且无需登录,任何能访问该端口的人都能使用它。不要让你不信任的网络访问这个端口。 - 根本没有窗口弹出。
PLANNOTATOR_BROWSER=none不会打开浏览器,而会话 URL 总会打印出来。 - Claude 不再等你了。README 称,在 Claude Code 2.1.287 或更高版本中,Claude 会结束当前轮次,你的决定稍后以消息形式送达。设置
PLANNOTATOR_CLAUDE_MOD=0即可恢复经典流程。 - 插件无法更新。先运行
claude plugin marketplace update plannotator,再运行claude plugin update plannotator@plannotator,然后重启。 - 想彻底卸载。先用
plannotator uninstall --dry-run预览,再运行plannotator uninstall。默认情况下,它会保留你的计划和历史记录。
总结
认真读一遍计划,比事后去拆解一份 diff 划算得多。如果你还让智能体操控浏览器,可以看看我们的 Chrome DevTools MCP 设置指南。
资料来源
链接最后检查于 2026 年 11 月 15 日。





写评论