Plannotator:在编程智能体写代码之前,先审阅并批注它的计划

Plannotator 会在浏览器中打开编程智能体的计划,让你在代码写出来之前先做标注、发反馈。本文介绍安装方法、常用命令以及隐私方面的细节。

Graphic of a browser window with a marked-up plan and comment bubbles, illustrating the Plannotator tool for reviewing coding agent plans.

你的编程智能体刚刚提出了一个十二步的计划,想在开始重写你的项目之前得到你的点头。你在终端里扫了一眼,敲下“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 描述的流程如下:

  1. 智能体完成计划并请求退出计划模式(README 把这一步称为 ExitPlanMode)。
  2. 一个 hook 被触发,本地服务器在你的浏览器中打开计划。
  3. 你写好批注,然后批准或拒绝。
  4. 如果你拒绝,结构化的反馈会发回给智能体,由它修改计划。计划 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 日。

作者:Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

关于 Mindloop Experience

评论

写评论

更多来自 Mindloop Experience

查看 Mindloop Experience 的全部文章

最多可以鼓掌 50 次。