Plannotator：给编程 Agent 的计划与代码加可视化审阅层

编程 Agent 在终端里抛出一长串计划、直接改出一屏 diff，人要在窄终端里精确指出”这段删掉、这句改写、这里加评论”非常别扭。Plannotator 把人类熟悉的文档批注与 Code Review 流程搬到 Agent 协作中：Agent 提计划时拦截审批环节，你在浏览器里划选文字、标记删除、写替换或评论，批注作为结构化反馈直接发回 Agent；也能用 PR 风格 diff 视图审阅未提交改动或 GitHub/GitLab PR。本文基于官网、GitHub 仓库与官方 README 一手核对。

一、背景动机：人管规格，Agent 写代码

在 plan mode 工作流里，Agent 先出计划、等人批准再动手。问题在于批准发生在终端纯文本里：计划动辄上千字，人只能口头转述修改意见，Agent 拿到的是二手描述，容易漏改或误解。Plannotator 的定位是在”人批准”这一步插入一个正式的审阅面（review surface），让人像评论文档一样精确地标出要改哪里，而不是重新打字描述。

它是一个本地运行、免费开源的浏览器端审阅工具，通过各 Agent 的 hook 与斜杠命令接入，不替换 Agent，也不替代版本控制。GitHub 仓库为 backnotprop/plannotator，双协议 Apache-2.0 / MIT；抓取时仓库约 9.5k stars、711 forks、92 个开放 issue、1,600 次提交（官网实时计数器另显示 8,911 stars，随时间波动）。

二、两种审阅模式

2.1 计划审阅（Plan Review）

无需手动触发：Agent 进入 plan mode 提出计划时，hook 自动拦截审批步骤，Markdown 计划在浏览器审阅面打开。可做的操作：

• Inline comments：在任意段落加评论；
• Mark deletions：划选文字标记为待删除，直接收窄范围；
• Write a replacement：为选中段落写替换文本；
• Approve / Send Feedback：批准，或把批注作为结构化反馈发回 Agent 修订；
• Version history：每次计划修订都保存，可用 diff 视图对比两个版本改了哪里，不必重读全文。

2.2 代码审阅（Code Review）

执行 /plannotator-review 打开当前未提交改动的 PR 风格 diff：

• Side-by-side（分栏）或 unified（统一）两种 diff 视图；
• 文件树导航，逐文件审阅；
• 行级批注与代码建议（上图弹窗 “Are you sure this is the right approach?”）；
• 提交前可 stage / unstage 文件；
• 支持直接审阅 GitHub PR URL 与 GitLab MR URL。

版本控制后端除 Git 外，官方 README 声明还支持 GitButler、Jujutsu（jj）、Perforce（p4）。

三、命令与集成

核心命令（不同宿主写法略有差异）：

/plannotator-annotate <file|dir|url>   # 批注任意 markdown、目录、URL、HTML
/plannotator-review [PR_URL]          # 审阅本地 diff 或远程 PR/MR
/plannotator-last                      # 批注 Agent 的上一条消息

Codex 下斜杠命令换成 !plannotator review 形式。计划审阅在各宿主里通过 hook 自动接线，无需命令。

官方支持的 Agent 与接入方式（README 安装表）：

官网另称”works with any agent that supports plan mode”。配套的 Herdr Annotate 把同款批注带到 Herdr 终端内；独立 TUI 版本可通过 brew install plannotator/tap/plannotator-tui 单独安装。

四、隐私与网络行为（官方 README 明确口径）

这是官方写得最细的一节，也是最容易被营销语掩盖的部分：

• 默认本地：计划、diff、批注、草稿、历史与配置默认留在本机，不收集使用遥测或分析；
• 发布检查无开关：每个应用面加载时都会向 GitHub 查询最新版本，不发送计划内容、也不产生使用分析，但目前没有 opt-out 设置；
• git 远端检查：本地代码审阅打开时会用已配置的 origin 跑 git ls-remote 检测默认分支与过期基线，不上传本地 diff；可用 --no-git-remote-check、环境变量或配置彻底关闭；
• URL 批注：公开页面默认经 Jina Reader 抓取；
• Ask AI / AI 审阅：把选中的问题与相关计划、文档、仓库或 diff 上下文发给你配置的模型提供方，并非本地推理；
• 分享：小体积 Markdown 分享压缩进 URL fragment，fragment 不加密，持有完整链接即可读；大体积 Markdown 与 HTML 分享用 AES-256-GCM 加密后上传短链服务，服务器只存密文、密钥留在 fragment，托管粘贴 7 天过期，粘贴服务可自托管；
• Workspaces：面向团队的托管层（共享计划、审阅历史、验证标准）目前在 waitlist，开源本地版的本地存储模型不适用于托管内容；异步链接分享保留兼容但已转向 deprecated。

五、关键数据（抓取时快照）

六、评测方法与口径偏差：官方自己承认的边界

1. “本地/私密”不等于全程不联网：发布检查每次加载必连 GitHub 且无开关；ls-remote、Jina Reader、Ask AI、加密短链上传都会按场景出网，只是默认不上传审阅内容。
2. 小分享链接不加密：官网强调隐私，但小 Markdown 分享走未加密 URL fragment，任何拿到完整链接的人或中转服务都能读，与大分享的加密模型不同。
3. 计划拦截能力各宿主不均：Droid 只有命令、没有 plan 拦截；Codex 原生 Windows hook 仍实验性；Gemini 有版本下限（0.36.0+）。“自动拦截审批”并非对所有 Agent 等价成立。
4. 团队协作在托管层：开源版的异步链接分享已 deprecated，正式团队共享要等 Workspaces 托管产品（waitlist），开源本身不含多人实时协作。
5. AI 审阅依赖外部提供方：内建 Ask AI 与 AI review 把上下文送出本机，隐私边界由你配置的模型服务决定。
6. 官网与 README 未提供独立的对照评测（如批注反馈是否提升 Agent 一次通过率），效果论述以场景演示为主。

七、适用与不适用场景

适合：

• 在 Claude Code / Codex / OpenCode 等 plan mode 下工作，希望精确改计划而非口头转述的个人开发者；
• 需要在提交前对 Agent 产出做行级批注、统一走 PR 式 diff 的小团队；
• 对本地留痕、版本历史、草稿自动保存有要求，又想避免遥测的用户；
• 使用 GitButler / Jujutsu / Perforce 等非主流 VCS 的用户（官方有适配）。

不适合：

• 期待开箱即用的多人实时协作审阅（需 Workspaces 托管）；
• 在 Droid 或原生 Windows Codex 上依赖自动计划拦截的用户（能力未齐）；
• 要求全程零外联、连发布检查都不能有的隔离环境；
• 把 AI 审阅当本地隐私功能使用的团队（上下文会发给模型提供方）。

八、客观分析：优势与局限

优势：

1. 切中审批摩擦点：把”口头说改哪里”变成”划选即批注”，结构化反馈减少 Agent 理解偏差；
2. 两种模式覆盖计划与代码：plan diff 历史 + PR 风格 diff，闭环完整；
3. 本地优先、双协议开源：批注数据默认不出本机，Apache-2.0/MIT 可商用改造；
4. 宿主覆盖广：10 个以上 Agent 与编辑器接入，并照顾 GitButler/jj/p4 等非主流后端。

局限：

1. 小分享链接不加密、发布检查无开关，隐私叙事需打折扣；
2. 自动拦截能力随宿主成熟度不一；
3. 团队协作依赖未发布的托管 Workspaces；
4. 缺独立效果评测，价值主要靠工作流体感验证。

九、它意味着什么 / 谁该关注

Plannotator 代表 Agent 协作工具的一个细分方向：不改进模型本身，而是优化”人在环中”的审批与审阅界面。对重度使用 plan mode 的开发者，它把规格制定权牢牢留在人手里；对团队管理者，可先在个人侧试用批注精度，再评估 Workspaces 落地。关注其后续在 Droid/Windows 宿主上的拦截补齐与开源团队协作能力即可。

参考来源

• Plannotator 官网
• GitHub: backnotprop/plannotator
• 官方文档：Open Source
• 官方文档：安全与网络边界
• Koala 项目库条目：Plannotator