一天一个开源项目

一天一个开源项目（第260篇）：Plannotator —— 给 AI 编码 Agent 配一块「可批注的审阅台」，计划和代码改动都能在浏览器里逐条批示

Plannotator 是一个运行在本地的浏览器审阅界面，适配 Claude Code、Codex、Copilot CLI、Gemini CLI、OpenCode、Kiro、Droid、Amp、DeepSeek Harness、Pi 等十个 Agent。Agent 提出计划或完成改动时，浏览器自动弹出，你可以逐段批注、批准或打回，反馈一键回传给 Agent。支持计划审阅、Markdown/网页批注、本地与 PR 代码审阅、Inbox 收件箱和加密分享。双协议 Apache-2.0 或 MIT，约 1 万 Stars。

·约 11 分钟阅读·AI 工程
开源项目PlannotatorAI AgentClaude Code代码审阅Human-in-the-loop计划审阅

引言

「Stay in the loop and on top of agents.」

这是「一天一个开源项目」系列的第 260 篇。今天的项目是 backnotprop 的 Plannotator。

和 AI 编码 Agent 协作，最常见的尴尬是这样的：Agent 在终端里吐出一大段计划，你想改其中第三步，却只能在聊天框里打字「第三步不对，换成……」；Agent 改完代码，你想对某几行提意见，也只能口头描述「就是那个函数里的那一行」。信息在对话里来回传，既慢又容易丢。

Plannotator 的做法是给这个环节配一块专用的审阅台：Agent 一提出计划，浏览器就弹出一个界面，你像在文档里批注一样逐段标记，点一下就把结构化的反馈发回给 Agent。它不替你决策，只是让「人在回路里」这件事变得顺手。

本文基于 README 和仓库目录整理，我没有安装并实际跑过。

你将学到什么

  • Plannotator 解决什么问题，和直接在聊天框里反馈有什么差别
  • 它如何通过各个 Agent 的 Hook 自动弹出审阅界面
  • 计划审阅、批注、代码审阅、Inbox 几个主要功能
  • 分享功能的隐私模型：哪些内容会离开你的机器
  • 怎么安装到不同的 Agent，以及已知的限制

前置知识

  • 用过 Claude Code、Codex 或类似的 AI 编码 Agent，了解「计划模式」
  • 对 Hook、Git diff 有基本认识
  • 可选：了解 Bun 与 Monorepo

项目背景

项目简介

README 对它的定位是：一个本地的、基于浏览器的、面向 AI 编码 Agent 的审阅界面。Agent 提出计划或完成工作后，浏览器界面弹出，你做标注，再把反馈直接送回 Agent。仓库描述的原话是，这是一个让你「保持在回路中、掌控 Agent」的工作台：塑形、决策、计划、批注、审代码、与团队分享，并一键把所有反馈发给 Agent。

README 列出的支持对象是：Claude Code、Codex、Copilot CLI、Gemini CLI、OpenCode、Kiro、Droid、Amp、DeepSeek Harness 和 Pi。仓库的 apps/ 目录下还能看到 Cline、Qwen Code、OpenClaw、Hermes 等对应的插件目录，但 README 的支持列表里没有写它们，成熟度我没有核实。

项目数据

  • ⭐ GitHub Stars：约 10,237
  • 🍴 Forks：约 776
  • 💻 语言：TypeScript（Bun Monorepo）
  • 📅 创建时间：2025-12-28，最近一次推送为 2026-11-13，最新发布版本 v0.28.62（2026-11-12）
  • 📄 许可证：Apache-2.0 或 MIT，二选一（双协议）
  • 👤 作者：backnotprop，版权 2025-2026
  • 🌐 官网：plannotator.ai

主要功能

它解决的问题

只用聊天反馈时：
  Agent 输出长计划 → 你在聊天框里文字描述要改哪里
  ↑ 定位靠口述，批注无法结构化，改完也不容易对比
 
用 Plannotator：
  Agent 提出计划 → 浏览器弹出审阅界面 → 逐段批注 → 批准或打回
  ↓ 结构化反馈回到同一个 Agent 会话
  ↑ Agent 修改后，界面还会显示计划前后的差异

主要能力

功能说明
计划审阅通过各 Agent 的 Hook 自动打开；可批准，或带结构化反馈打回；Agent 改完后显示计划 diff
批注支持 Markdown 文件、文件夹、网址和 HTML；/plannotator-last 可批注 Agent 上一条消息
代码审阅本地改动，以及 GitHub、GitLab 的 PR/MR；支持 Git、GitButler、Jujutsu、Perforce；可评论 diff、建议代码、暂存文件，也能用 --patch-file 审阅静态补丁
内置 AI可向 AI 提问，也有审阅 Agent 直接在 diff 上发评论
Inbox 收件箱plannotator inbox：Agent 在继续工作的同时，把问题、文件和审阅请求留在这里
终端审阅Herdr Annotate / Plannotator TUI，可用 brew install plannotator/tap/plannotator-tui 安装
Vim 键位默认关闭，支持 j/k 导航、v/V 选择
集成VS Code、Obsidian、Bear、Notion（需 NOTION_TOKEN）、GitHub/GitLab

常用命令：

/plannotator-annotate README.md       批注某个文件
/plannotator-review                   审阅本地改动
/plannotator-review <github-pr-url>   审阅某个 PR
/plannotator-last                     批注 Agent 的上一条消息
plannotator sessions                  查看会话
plannotator archive                   归档

在 Codex 里使用方式略有不同：用 !plannotator … 或 $plannotator-* 这样的 Skill。

快速安装

通用安装器会自动检测你装了哪些 Agent：

# macOS / Linux / WSL
curl -fsSL https://plannotator.ai/install.sh | bash
 
# Windows
irm https://plannotator.ai/install.ps1 | iex

只装二进制可加 --minimal（或设置 PLANNOTATOR_MINIMAL=1），固定版本用 --version vX.Y.Z。

装好后，按 Agent 补一步：

Agent额外步骤
Claude Code/plugin marketplace add backnotprop/plannotator，再 /plugin install plannotator@plannotator，然后重启
Codex无需额外步骤，计划审阅用的是实验性的 Stop Hook
Copilot CLI/plugin marketplace add backnotprop/plannotator，再 /plugin install plannotator-copilot@plannotator；在计划模式（Shift+Tab）下生效
Gemini CLI无需额外步骤，要求 0.36.0 及以上
OpenCode在 opencode.json 里加 "plugin": ["@plannotator/opencode@latest"]
Pipi install npm:@plannotator/pi-extension，用 --plan 启动
DeepSeek Harnessdsh plugin --profile <profile> add @plannotator/dsh
Droiddroid plugin marketplace add https://github.com/backnotprop/plannotator，再 droid plugin install plannotator@plannotator，目前只有命令，没有计划拦截

Kiro、Amp、T3 Code 的步骤在 README 里另有说明。更新就是重跑安装器；卸载用 plannotator uninstall，加 --purge 会清除全部数据，--dry-run 可以先预览。

项目详细剖析

计划审阅是怎么「弹出来」的

核心是 Hook。以 Claude Code 为例，README 描述的流程是：

  1. Agent 在计划模式下准备好计划，调用 ExitPlanMode
  2. 这会触发 PermissionRequest Hook
  3. 本地服务读取计划内容，浏览器随之打开审阅界面
  4. 你批准，Agent 继续执行；你打回，结构化的反馈回到 Agent

手动配置 Hook 时，匹配器是 ExitPlanMode，超时设为 345600 秒（4 天），也就是说你可以离开很久再回来审。README 还提到，在 Claude Code 2.1.287 及以上版本，Agent 会先结束当前一轮，你的决定稍后以一条消息的形式送达；想回到经典流程，设置 PLANNOTATOR_CLAUDE_MOD=0。

代码审阅的流程类似：/plannotator-review 取到 git diff（或拉取 PR），打开 diff 查看器，你逐行评论，反馈回到 Agent 会话。批准时发送的是「LGTM」。

这个设计的巧妙之处在于，它没有另起一个「新工作流」，而是挂在 Agent 本来就有的关卡上（退出计划模式、完成改动），只是把「在聊天里读和回」换成了「在专门界面里读和批注」。

分享与隐私：哪些内容会离开你的机器

这部分 README 写得很细，值得单独看：

  • 默认不做遥测和分析，计划、diff、批注都留在本地
  • 每个界面加载时会向 GitHub 检查最新版本，这一项没有关闭选项
  • Git 审阅可能对 origin 执行 git ls-remote，可用 --no-git-remote-check、PLANNOTATOR_GIT_REMOTE_CHECK=0 或配置 { "gitRemoteCheck": false } 关闭
  • 只有网络类功能才会让内容离开本机：抓取网址（默认使用 Jina Reader）、GitHub/GitLab 数据、AI 服务商，以及分享
  • 小体量分享：压缩进链接的 URL 片段（# 后面的部分）。片段不会发给分享门户，但没有加密
  • 大体量的 Markdown 和原始 HTML 分享：上传前用 AES-256-GCM 加密，服务端只保存密文，密钥留在 URL 片段里，内容 7 天后过期。README 说它的模型和 PrivateBin 类似
  • 用 PLANNOTATOR_SHARE=disabled 可以完全关闭分享
  • 分享服务可以自托管：PLANNOTATOR_SHARE_URL 指向自定义门户，PLANNOTATOR_PASTE_URL 指向自定义存储 API

README 还提醒：持有完整分享链接的人就能读到内容；并且链接分享正在转向「已弃用但仍支持」，团队方向是托管工作区（Hosted Workspaces），没有给出移除日期。

远程与 SSH

在远程机器上用，SSH 会被自动识别并使用端口 19432。需要在本地的 ~/.ssh/config 里加一行转发：

LocalForward 19432 localhost:19432

README 对这里的安全风险讲得很直白：远程模式下服务监听 0.0.0.0，没有登录认证，所以不要把这个端口暴露给不可信的网络。

配置

设置可以放在 Cookie、环境变量或 ~/.plannotator/config.json 中。常用的环境变量有：

变量作用
PLANNOTATOR_PORT端口，本地默认随机，远程默认 19432
PLANNOTATOR_BROWSER设为 none 则不自动打开浏览器
PLANNOTATOR_AI设为 disabled 关闭内置 AI
PLANNOTATOR_DATA_DIR数据目录，默认 ~/.plannotator
PLANNOTATOR_SHARE设为 disabled 关闭分享

供应链与发布

发布的二进制带有 SHA256 校验文件，v0.17.2 起提供 SLSA 来源证明，并通过 Sigstore 证明了一份 CycloneDX 软件物料清单（注意它是整个发布版本的清单，不是每个二进制各一份）。安装时想校验，可以加 --verify-attestation（需要 gh），或配置 { "verifyAttestation": true }。

仓库结构

这是一个 Bun Monorepo：

  • apps/：各 Agent 的接入层与服务，包括 hook、review、inbox、opencode-plugin、pi-extension、paste-service、portal、vscode-extension 等
  • packages/：共享代码，包括 ui、editor、review-editor、server、core、ai、t3-code 等

开发命令是 bun install、bun run dev:hook、bun run build，注意构建顺序：要先构建 apps/review，再构建 hook。

局限与注意事项

README 自己列出的限制：

  1. Codex 的 Hook 仍是实验性的，原生 Windows 需要手动配置
  2. Droid 还不能拦截计划
  3. GitHub 版本检查无法关闭
  4. 远程模式没有认证
  5. 分享链接对持有完整链接的人可读

我补充两点判断：

  • 覆盖的 Agent 很多，但深度不一：有的是完整的计划拦截，有的只有命令，用之前先对照 README 里自己所用 Agent 的那一行
  • 「无遥测」我没有核实：README 这样声明，但 apps/ 下有一个名为 telemetry 的目录。我没有去读它的内容，所以不能断言两者的关系。对隐私敏感的话，建议自己看一下

项目地址与资源

总结与展望

核心要点回顾

  1. 解决的是「反馈效率」：把「聊天里口述」换成「界面里批注」，反馈结构化，定位精确
  2. 挂在 Agent 已有的关卡上：用 Hook 在退出计划模式、完成改动时自动弹出，不改变你的工作流
  3. 覆盖面广：十个 Agent，计划审阅之外还有批注、代码审阅和 Inbox
  4. 隐私模型清楚：默认本地；分享分「URL 片段」和「加密上传」两档，并可自托管、可关闭
  5. 有明确的限制：Codex Hook 实验性、远程模式无认证、版本检查无法关闭

适用人群

  • 经常让 Agent 先出计划再动手、想精确批注计划的开发者
  • 需要审阅 Agent 改动、PR 的人，尤其是想把意见一次性回传给 Agent 的人
  • 团队里想统一「如何给 Agent 反馈」流程的人

学习建议

先装在一个你熟悉的 Agent 上（Claude Code 的步骤最完整），故意让它出一个有明显问题的计划，试一次批注和打回，看反馈回到 Agent 后它的修改是否对得上。如果你在远程服务器上用，先读完「远程与 SSH」那一节再开端口。想了解它怎么接入不同 Agent，可以对照 apps/hook 和 apps/opencode-plugin 两个目录。

欢迎访问 PrimeSkills —— 一个精心策划的 AI Agent 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。

更多实用知识和有趣产品，欢迎访问我的个人主页

← 返回博客列表