Plannotator 让 Agent 的计划与代码可批注

AI 编码 Agent 在终端里生成一份分步骤计划后,协作常会卡在计划审阅上:计划第三步方向不对,但聊天框里只能先回一句“第三步不对,换成……”。代码落地后,开发者还要在聊天记录和代码 Diff 之间来回切换,才能把“那个函数里的那一行”准确定位给 Agent。

Plannotator 由 backnotprop 开发,采用 TypeScript 与 Bun Monorepo,以 Apache-2.0 或 MIT 双协议开源;它不是新的编码 Agent,而是在 Agent 与人之间插入一层本地浏览器审阅界面。

Agent 提出计划、生成 HTML 或完成代码工作后,Plannotator 会通过 Hook 或命令打开审阅界面。人可以在计划段落、Diff 行或文档内容上留下批注,再把审批结论和结构化反馈送回原来的 Agent 会话。与聊天框里的临时描述相比,这种方式多了明确的内容锚点,也更容易追踪一次审阅经过了哪些修改。

Plannotator 出现在 GitHub 趋势和中文开源项目讨论中。它尝试把 Agent 计划与代码产出中的隐含内容显式呈现出来,包括需要确认的步骤、暂不接受的判断以及尚未落实的修改意见。 本文主要依据 README、仓库目录及公开资料展开,不把功能描述当作实测结论,也不为项目背书。

为什么一份 Agent 计划值得单独审阅

聊天框可以承载修改意见,但意见会随着对话继续向下滚动。对一份十几步的计划而言,“第三步不对”还可能对应多个相似步骤;Agent 修订后,开发者也很难快速确认它究竟改了哪些内容。Plannotator 将计划改造成类似文档批注的对象,让每条意见附着在具体段落上。

计划审阅通常由 Agent 生命周期中的 Hook 触发。以 Claude Code 的计划模式为例,ExitPlanMode 钩子可以触发浏览器审阅;其他接入则可以利用 PermissionRequest、Stop 等钩子拦截计划或 Agent 产出,随后启动本地服务器并打开界面。

在计划界面中,开发者可以逐段删除、替换或评论某一步,并选择批准或打回。批准后,Agent 继续执行;打回时,批注内容会作为结构化反馈返回原会话,而不是再由开发者手工复制一遍。 Agent 修订计划后,Plan Diff 还能以新增、修改和删除的方式展示前后差异,呈现“上一版与这一版究竟变了什么”。

这套审阅流程对长计划尤其有用。它不替开发者判断技术方案是否正确,只把原本容易散落在聊天记录中的人类判断固定下来。反过来,如果改动只有一行,单独打开审阅台可能显得笨重;Plannotator 的收益主要出现在计划复杂、影响范围较大,或者需要多轮修订的场景。

代码改完以后,Diff 里的意见怎样回到 Agent

代码审阅是 Plannotator 与传统 PR Review 最接近的部分。运行 /plannotator-review 后,浏览器可以打开本地未提交改动的 Diff 视图,区分暂存与未暂存文件,并允许在两种状态之间切换。 除了本地 Git 改动,它还支持静态 unified diff,以及 GitHub PR、GitLab MR;资料列出的版本控制场景还包括 Git、GitButler、Jujutsu 和 Perforce。

在这个界面里,评论可以附着到具体代码行,开发者也可以给出建议代码和审批结论,再将这些内容整体返回 Agent 会话。 因此它并不是在 Agent 结束后额外生成一份互不关联的评审报告,而是把“发现问题—交给 Agent 修改—再次查看 Diff”连接成了一条工作流。

Plannotator 能批注的对象也不限于 Diff。/plannotator-annotate 可以处理本地 Markdown、文件夹、URL 和渲染后的 HTML,/plannotator-last 则用于标注 Agent 的上一条回复。 这使它能够覆盖 Agent 生成的 HTML 报告、文档页面以及一般说明材料,而不只是代码文件。

会话管理提供了补充入口。资料把 Inbox 列为主要功能之一,plannotator sessions 可以列出并重新打开活动会话,plannotator archive 提供归档入口,已保存的计划决策还可以只读回看。 这些功能解决的是审阅内容散落、反馈难以重新定位的问题,与 Git 的提交历史形成互补。

接入方式、分享机制与本地数据边界

Plannotator README 明确列出的支持对象包括 Claude Code、Codex、Copilot CLI、Gemini CLI、OpenCode、Kiro、Droid、Amp、DeepSeek Harness 和 Pi。 仓库的 apps/ 目录中还能看到 Cline、Qwen Code、OpenClaw、Hermes 等插件目录,但这些目录没有全部进入 README 支持列表,目录存在本身不足以证明接入已经成熟,实际兼容性仍需结合最新版仓库核验。 此外,项目还提供 VS Code 扩展、Obsidian 计划归档和 Bear 笔记导出等集成。

资料给出的 macOS、Linux 和 WSL 安装入口如下,Windows 另有 PowerShell 安装方式。

curl -fsSL https://plannotator.ai/install.sh | bash

这类远程安装脚本会直接执行安装逻辑,团队环境更适合先检查脚本或按 README 固定版本。使用环境需要 Shell、本地文件系统和安装阶段的网络访问;如果参与项目开发,还需要 Bun。

安装完成后,主要入口包括 Agent 会话中的斜杠命令,以及用于管理会话与归档的 CLI 子命令。

/plannotator-annotate README.md
/plannotator-review
/plannotator-last
plannotator sessions
plannotator archive

资料还列出了 PLANNOTATOR_PORT 环境变量,以及 opencode.json、~/.plannotator/config.json 等配置位置;不同 Agent 对应的配置方式和参数,应以当前 README 为准。 Droid 用户需要注意一项现有限制:目前主要通过命令接入,不能像其他支持计划拦截的 Agent 那样自动截获计划。

Plannotator 的计划、Diff、批注和历史默认保存在本地,并且不收集遥测。 但“本地运行”并不等于“使用过程中绝不会有数据离开本机”。团队分享至少存在三种路径:无加密分享链接、加密分享链接和托管的 Workspaces;前两者会把链接内容或密文送出本机,后者则把协作数据交给托管服务处理。

一份较早的 v0.19.3 分析快照显示,小型计划可以完全编码在 URL 哈希中而无需服务器存储,大型计划采用 AES-256-GCM 加密,服务器只保存密文,分享链接则在七天后自动删除。 这些属于特定版本下的实现记录,加密格式、链接有效期和服务端行为都可能调整,涉及时应以最新 README 为准。

不同资料中的 Star 数、版本号和最近提交时间也存在明显差异,快照横跨 v0.19.3 至 v0.28.x。因此,本文只把 Plannotator 视为 GitHub 趋势中的活跃项目;旧快照中的 Star 数、版本号和最近提交时间不作为实时状态。

就本文讨论的协作环节而言,Plannotator 的核心价值在审阅:原本埋在聊天记录里、容易丢失的人类判断,可以变成可定位、可回传、可协作的审阅对象。加快 Agent 运行或代码生成速度不是它的重点。

© 版权声明
THE END
喜欢就支持一下吧
点赞0 分享
评论 抢沙发

请登录后发表评论

    暂无评论内容