AI 编码 Agent 可以生成计划、修改代码、读取仓库,但当开发者想指出“第三步不合适”或“某一函数里的某一行要改”时,很多时候仍要在聊天框里用文字描述位置。开源项目 Plannotator 试图补上这个环节:它为 AI 编码 Agent 提供一个本地、基于浏览器的审阅界面,让计划、代码改动和反馈回流都能被逐条查看、批注和确认。
该项目来自 backnotprop。按照 README 的定位,Plannotator 是一个让开发者“保持在回路中、掌控 Agent”的工作台,可用于塑形、决策、计划、批注、审代码、与团队分享,并把所有反馈一键发回 Agent。
把聊天框里的反馈,变成结构化批注
在纯聊天反馈模式下,Agent 输出一段长计划后,开发者通常只能继续用文字说明哪里要改。这种方式依赖口头定位,批注难以结构化,修改前后也不容易对比。Plannotator 的做法是:Agent 提出计划后,浏览器打开审阅界面,开发者像在文档里做批注一样逐段标记,再把结构化反馈发回给同一个 Agent 会话。
README 列出的支持对象包括:
- Claude Code、Codex、Copilot CLI、Gemini CLI、OpenCode、Kiro、Droid、Amp、DeepSeek Harness 和 Pi。
仓库的 apps/ 目录下还能看到 Cline、Qwen Code、OpenClaw、Hermes 等对应插件目录,但 README 的支持列表没有写入这些项目,其成熟度未得到核实。
在项目流程上,Plannotator 不代替开发者做决定。Agent 提出计划后,界面可以批准,也可以带结构化反馈打回;Agent 修改后,界面还会显示计划前后的差异。代码审阅部分支持本地改动,以及 GitHub、GitLab 的 PR/MR;版本控制方面支持 Git、GitButler、Jujutsu、Perforce。开发者可以评论 diff、建议代码、暂存文件,也能用 –patch-file 审阅静态补丁。批准时发送的是“LGTM”。
围绕 Hook 接入计划、文件、PR 与收件箱
Plannotator 的核心接入方式是 Hook。以 Claude Code 为例,README 描述手动配置 Hook 时,匹配器为 ExitPlanMode,超时设为 345600 秒,也就是 4 天。这意味着开发者可以离开一段时间后再回来审阅。README 还提到,在 Claude Code 2.1.287 及以上版本,Agent 会先结束当前一轮,用户的决定稍后以一条消息的形式送达;如果希望回到经典流程,可以设置 PLANNOTATOR_CLAUDE_MOD=0。
代码审阅的流程类似。执行 /plannotator-review 后,工具会获取 git diff 或拉取 PR,并打开 diff 查看器,开发者逐行评论,反馈再回到 Agent 会话。除代码外,它也支持批注 Markdown 文件、文件夹、网址和 HTML;/plannotator-last 可用于批注 Agent 的上一条消息。
项目还提供了一组配套能力:
- /plannotator-annotate README.md:批注指定文件。
- /plannotator-review <github-pr-url>:审阅某个 PR。
- plannotator sessions:查看会话。
- plannotator archive:归档。
- plannotator inbox:Agent 可以在继续工作的同时,把问题、文件和审阅请求留在收件箱中。
终端审阅可通过 Herdr Annotate / Plannotator TUI 完成,安装命令为 brew install plannotator/tap/plannotator-tui。Vim 键位默认关闭,支持 j / k 导航、v / V 选择。集成方面,README 提到 VS Code、Obsidian、Bear、Notion(需 NOTION_TOKEN)以及 GitHub/GitLab。Codex 的使用方式略有不同,采用 !plannotator … 或 $plannotator-* 这样的 Skill。
安装、远程模式与需要留意的安全边界
安装脚本覆盖 macOS、Linux、WSL 和 Windows。通用安装器会自动检测本机已安装的 Agent。只安装二进制可加 –minimal,或设置 PLANNOTATOR_MINIMAL=1;固定版本可用 –version vX.Y.Z。更新方式是重跑安装器;卸载命令为 plannotator uninstall,–purge 会清除全部数据,–dry-run 可以先预览。
远程机器使用时,SSH 会被自动识别并使用端口 19432。开发者需要在本地 ~/.ssh/config 中加入一行转发:LocalForward 19432 localhost:19432。README 对远程模式的风险表述直接:服务监听 0.0.0.0,没有登录认证,因此不要把这个端口暴露给不可信网络。
分享功能也有边界。持有完整分享链接的人可以读到内容;链接分享正在转向“已弃用但仍支持”,团队方向是托管工作区(Hosted Workspaces),但没有给出移除日期。设置可放在 Cookie、环境变量或 ~/.plannotator/config.json 中。
在发布和供应链层面,Plannotator 的公开二进制带有 SHA256 校验文件;自 v0.17.2 起提供 SLSA 来源证明,并通过 Sigstore 证明了一份 CycloneDX 软件物料清单。该清单对应整个发布版本,而不是每个二进制各一份。安装时如需校验,可加 –verify-attestation,该步骤需要 gh;也可在配置中写入 { “verifyAttestation”: true }。项目本身是一个 Bun Monorepo,开发构建时需要先构建 apps/review,再构建 hook。
human-in-the-loop 正在进入 Agent 编程工具链
从设计上看,Plannotator 没有另起一套独立工作流,而是挂在 Agent 本来就有的关卡上:退出计划模式、完成改动、提交审阅。它把“在聊天里读和回”换成了“在专门界面里读和批注”,降低人在回路中的操作摩擦。
这类工具的价值,并不在于替 Agent 多写几行代码,而在于让开发者更容易定位到具体步骤、具体文件和具体 diff。当 AI 编码 Agent 开始承担更长链路的工作时,审阅、批注、打回和确认会变成工具链中不可省略的一层。
对于准备尝试的开发者,较稳妥的方式是先在自己熟悉的 Agent 上安装,例如步骤描述较完整的 Claude Code,然后故意让 Agent 生成一个有明显问题的计划,测试批注、打回和反馈回流是否能准确对应。若在远程服务器上使用,则应先读完远程与 SSH 相关说明,再决定是否转发端口。
原创文章,作者:点点,如若转载,请注明出处:https://www.dian8dian.com/cong-kou-shu-xiu-gai-dao-zhu-tiao-pi-shi-plannotator-gei-ai