日期:2026-11-17 GitHub Trending 排名:第 2 位;榜单采集时间:16:00:53(北京时间)
Agent 写了一份重试方案,你在第三段标出“这里不能自动重放支付请求”。下一步最容易出问题的,往往不是批注界面,而是这句话怎样回到正确的会话:原来的工具调用还在等吗?会话重启后,答复还在不在?两个终端同时恢复同一个 Agent,会不会把同一句“继续执行”送进去两次?
Plannotator 从浏览器里的计划批注工具长出了一个 Inbox。它把人的意见存成消息,再交给具体的 Agent 会话连接投递。值得细读的部分就在这个变化里:从“函数等一个返回值”,走向“消息先留下,答复稍后到达”。
📋 项目概览
| 项目 | 内容 |
|---|---|
| 主仓库 | backnotprop/plannotator |
| 定位 | 面向编码 Agent 的本地浏览器审阅界面与异步 Inbox |
| 主要语言 | TypeScript |
| 主要技术 | Bun 服务端、React 界面、宿主插件与 MCP 接口 |
| Stars | 12,804,来自当日采集快照 |
| Forks | 1,272,来自当日采集快照 |
| 许可证 | MIT 或 Apache-2.0,使用者可二选一 |
| 本文上手版本 | v0.28.67 |
| 重点 | 消息持久化、会话路由、投递去重和崩溃后的恢复边界 |
仓库名里的 plan 很容易让人以为它只管计划。现在它还包含 Markdown 和 HTML 批注、代码差异审阅、引导式审阅,以及让多个 Agent 留言的 Inbox。各个宿主的接入方式并不一样,不能把“有 MCP 接口”直接理解成“所有宿主都能自动收到下一轮消息”。
🔥 为什么值得关注
常见的人机审阅流程把人放在一条同步调用链上:Agent 提交计划,工具等待,人读完并点按钮,工具才返回。小任务很直观,等待时间一长,工具生命周期就开始替业务状态背锅。终端关闭、连接中断、插件重载,都可能影响这次交互。
Inbox 换了一种组织方式。Agent 的发信工具先把消息存下来,返回消息 ID、线程 ID 和界面入口;人的答复是之后产生的另一条消息。接入了唤醒连接的宿主,可以在适当时机把答复作为下一轮输入送回 Agent。没有这条连接的普通 MCP 客户端,需要按它实际支持的读取方式继续交互。
这对并行开发很实用。一个 Agent 正在调整缓存,另一个正在做界面,它们的问题可以进入同一个审阅窗口,但回复仍然有各自的会话目标。人不用守着两个一直挂起的工具调用,线程也不会因为某次工具请求结束就消失。
代价同样明确:同步返回值变成了持久消息,就必须处理地址、幂等键、投递确认和故障恢复。Plannotator 没把这些问题藏在“自动发回”四个字后面,源码里能看到相当具体的取舍。
🏗️ 核心特性
批注对象不只是一段聊天文字
计划、文档、代码差异、HTML 原型都能成为审阅对象。代码审阅保留真实 diff,人的意见可以对应文件和代码行;文档批注则围绕被审阅内容形成反馈。引导式审阅允许 Agent 把较大的变更分成章节,降低一次读完整份差异的负担。
这些功能解决的是“人在哪里给意见”。它们不证明意见一定正确,也不会替代编译、测试或业务验收。让 Agent 讲解自己的修改,适合帮助导航,不适合当作独立的正确性证明。
Inbox 把问题、答案和会话分开保存
消息正文中的结构化问题会形成独立问题记录。人可以先选择答案,再统一 Send;一条回复还可以带上文字和批注。这样的模型比直接覆盖一大段 Markdown 更容易表达“已经选了,但还没发回”。
线程用于组织上下文,session 用于决定送到哪里。线程不是终端连接,也不是一次 MCP 请求。同一个讨论可以包含多条消息,连接进程则可以在其生命周期里反复上线。
同步计划审阅与异步模式并存
经典 Claude Code 接入使用 PermissionRequest 钩子匹配 ExitPlanMode,通过本地界面处理计划决定。仓库同时提供 hooks module;README 说明,Claude Code 2.1.287 及以上的相应接入可以让审阅不再阻塞原来的等待流程,并用后续消息送回决定。
因此,“Plannotator 一定会阻塞 Agent”与“一定完全不阻塞”都不准确。实际行为取决于宿主版本、插件和配置。项目保留 PLANNOTATOR_CLAUDE_MOD=0 作为回到经典流程的开关,但它并不是所有宿主通用的异步开关。
本地界面不等于所有功能都没有网络边界
本地审阅是产品的重要使用方式,但安装器需要下载发行文件,分享、URL 读取和 AI 功能也各有外部服务边界。希望只装命令行二进制时,可以选择 minimal 安装,避免顺手配置各种 Agent 集成。
README 特别提醒:经典远程审阅模式会监听 0.0.0.0,没有登录保护;端口转发不意味着服务器端口已经对其他网络不可达。这个警告对应远程审阅模式,不能用它替代对 Inbox 自身接入配置的检查。内部文档是否可以分享、哪些 AI 功能可以启用,应分别决定。
🔬 技术架构深度解析
一条消息有四种不同的身份
理解 Inbox,先别从界面组件开始。它最关键的对象关系在消息模型和存储里:
| 标识 | 回答的问题 | 不能替代什么 |
|---|---|---|
| MCP/JSON-RPC 请求 ID | 这次工具结果属于哪次请求? | 不能代替业务发信去重键 |
message_id | 这条持久消息是哪一条? | 不能表示整段讨论 |
thread_id | 消息属于哪个讨论线程? | 不能直接当作 Agent 会话地址 |
idempotency_key | 这次发信是否是之前那次操作的重试? | 不能保证 Agent 执行副作用恰好一次 |
Agent 消息还有作者的 host、session 等信息。回复通过 reply_to 指向目标消息,并保留所属线程。发送端传入 reply_to 时,存储从父消息继承项目和线程,而不是另开一条讨论。
不带 reply_to 时,线程名可以把消息路由到同项目尚未关闭的同名讨论;没有线程名,则新开线程。新线程第一条消息的 ID 也就是线程 ID。这说明 session 和 thread 的关系不适合简化成一张“一会话一线程”的表。
从工具调用到后续输入,数据要经过这些位置
Agent / 宿主插件 / MCP 客户端
|
| send_message:正文、项目路径、线程/回复目标、幂等键
v
Inbox MCP 处理器
|
v
InboxStore -----------> 本地 JSONL 记录日志
| |
| +-- 重启时按 seq 重建内存视图
v
浏览器 Inbox:阅读、选择答案、批注
|
| Send:生成 person 回复消息
v
InboxStore 中的待投递回复
|
| session bridge 长轮询
v
宿主连接 InboxWake(共享实现)
|
+-- lease:本会话当前由哪个进程处理
+-- claim:本回复向本会话的投递由谁取得
|
v
宿主 deliver / steer:作为新一轮输入或支持的中途输入
|
| delivered 确认
v
InboxStore 记录投递结果
图里的 InboxWake 是共享连接路径,Pi、OpenCode 等接入会用到它;Claude Code mod 还有自己的连接与 claim 协议。整体概念相通,具体目录和补偿分支不能混写成一个实现。
MCP 的 send_message 在存储接收消息后组装 message_id、thread_id、cursor、url 等结果,并不留着这个工具调用等待人回答。对应实现在 inbox-mcp.ts。这是异步流程的起点,不是一个把旧式等待简单挪到后台的包装。
JSONL 存的是记录快照,内存里维护当前视图
默认存储使用本地追加式 JSONL。每次变化追加一行,行里是该记录的完整快照;启动后,InboxStore 读取记录、按 seq 排序并应用,用“记录类型加 ID”维护最新状态。这里的日志不等于外部消息队列,也不是一个分布式数据库。
写入顺序是先追加日志,再应用内存更新、通知订阅者。读取器跳过不能解析的坏行;如果文件尾部是不完整的一行,下次追加先补一个换行,避免新记录和残片粘在一起。具体文件实现见 jsonl-log.ts。
这个方案便于查看本地数据,运行时也不需要额外数据库服务。成本则包括启动时的日志读取、排序和投影,以及记录快照反复追加形成的存储量。appendFileSync 也不能自动推出“所有记录跨文件原子提交”或“掉电不丢”的结论。
人的 Send 就有一个能说明问题的分支:问题记录已经标成 sent,但回复消息还没写进去,进程就失败了。加载时,repairUnsentAnswers 检查 sent_reply_id 是否真的指向存在的回复;不存在,就在内存里恢复为尚未送出的答案和批注,让人可以再次 Send。
它做的是补偿恢复,不是把一组 JSONL 追加变成数据库事务。store.test.ts 还通过让消息文件只读模拟回复写入失败,断言重启后答案仍可发送。这样的测试表达了维护者希望保住的语义,不能替代对所有磁盘故障的保证。
幂等键保护发信,但两端的规则不完全一样
Agent 发信时,idempotency_key 可以省略。提供 key 后,存储在相同或组合项目范围内查找已有 Agent 消息;命中后比较正文、回复目标、线程名等相关内容。相同操作返回原消息,关键内容发生变化则报 idempotency_key_reused。
这带来一个实际约束:同一个逻辑操作重试要复用 key,真正修改内容后重新发信要换 key。也不要让多个 Agent 随手使用 retry-1 这种过于宽泛的键,因为这个查找没有再以 Agent session 做隔离。
人的 Send 规则不同。它强制要求非空 key,按目标消息、person 作者和 key 查找已有回复;命中就返回原回复,发生在重新检查新正文之前。于是,“同 key 改了内容一定报错”并不是双方通用规则。前端重试原操作与用户新写一条回复,需要区分清楚。
这两套分支都在 store.ts 里。对接时只读工具的自然语言说明不够,还要弄清实际去重作用域,以及重放返回的是新结果还是第一次的结果。
长轮询拿到回复,还没有完成投递
服务端按 session 查询待投递回复。有待办立即返回;没有则订阅存储变化,等待人的新消息、超时或取消。共享连接使用长轮询取得待办,并在真正交给宿主前,再以 waitMs: 0 读取一次新状态,避免直接投递旧缓存。
正常共享唤醒路径会观察宿主是否忙碌,通常连续两个 tick 空闲才投递;Send now 和宿主支持的 steer 是另外的分支。这里没有一个适用于所有宿主的固定“回复几秒后必达”承诺。
特别重要的是:poll 返回了一条回复,不会因此自动把它当作已消费。直到会话接收并上报 delivered,待办仍可能再次出现在 poll 结果里。网络读取成功只是传输链路中的一段,不是工作完成。
lease 与 claim 解决的是不同的重复问题
同一 Agent session 可能同时被两个终端恢复。共享连接先用 lease 决定哪个进程处理当前会话的投递,最近在某进程里发生的交互会影响这个归属。
取得 lease 之后,每条回复仍要抢 claim。实现通过非递归 mkdirSync 创建 claim 目录,让“目录已经存在”成为另一个进程已经取得该投递的信号。共享实现按回复 ID 和 session 组成目录键,因此同一回复可以分别送到 owner 和被标记的其他会话,而不是全局只能送一次。
lease 偏向会话级的处理者选择,claim 才是每次投递的跨进程互斥。把 lease 描述成一个足以保证强一致的分布式锁,会夸大它的能力;这里依赖的是同机共享数据目录和具体文件系统操作。关键调用顺序见 agent-link.ts。
下面是便于理解的伪代码,不是可以直接调用的项目 API:
刷新待投递回复
若宿主忙碌且不能 steer:稍后处理
复查本进程是否持有会话 lease
创建 reply + session 对应的 claim
若 claim 已存在:不再投递
调用宿主 deliver / steer
写 delivered 标记
向 Inbox 补交 delivered 确认
delivered 只说明进入会话,不说明任务做完
共享连接在宿主接收后写 delivered 标记,再上报确认;服务端把对应 session 的投递状态写进存储。它确认的是“回复进入了会话”,不是“Agent 完成修改”,更不是“测试已经通过”。
投递给被标记会话的回复,还需要更新那位收件人的状态,不能顺手吞掉 owner 本来应收到的输入。对多 Agent UI 而言,这是很容易遗漏的细节:界面上同一条回复,不代表底下只有一个消费进度。
如果要用 Inbox 承接部署审批,后面的部署任务仍要有自己的任务 ID、结果回执和幂等控制。把聊天层的 delivered 当成业务完成状态,会把问题推迟到下一次故障才暴露。
为什么它宁愿显示卡住,也不盲目重发
最难的一段在 claim 和宿主调用之间。进程可能刚创建 claim 就退出,也可能已经让宿主接收了回复,却没来得及写标记。两种情况从外部看很像,补发正文却有不同风险。
共享连接将失败分开处理:
| 失败位置 | 实现采取的处理 |
|---|---|
| Inbox 不可达、poll 没有有效结果 | 退避重连,成功后重置退避 |
| 宿主已接收,但确认暂未成功 | 在进程内保留未确认集合,后续补交确认 |
| steer 失败,或明确可以稍后投递 | 释放 claim,退回等待路径 |
| 普通 deliver 抛出其他异常 | 保留保守状态,提示人在 Inbox 查看,不自动重放正文 |
| claim 遗留且持有进程已消失 | 识别为 stuck/undelivered,允许人介入处理 |
确认重试也不是“任何错误都无限重试”。共享实现把 200,以及除 401 外的 4xx,当作这次确认不必再补交;无响应、401 和服务端错误则继续保留待确认状态。
卡住投递的检测实现 会看 delivered、reported、pid 等信息;有 pid 时,借助进程是否仍存在判断持有者有没有消失。测试覆盖了旧 claim 在会话重启后仍被视为未送达,以及人工转交另一 session 后才继续投递的场景。
因此,合适的评价是:它抑制了同机并发重复投递,并为指定操作提供幂等处理,但不保证端到端 exactly-once。claim、宿主接收、写标记、确认落盘之间没有贯穿全程的原子事务;遇到不确定结果时,项目选择保守地交给人恢复。对于可能触发写代码、运行命令的输入,这个选择有实际理由。
📖 README 核心内容摘要
README 最有用的部分是不同入口的使用边界。
单纯审阅文件,可以直接使用 plannotator annotate;查看代码差异使用 plannotator review;集中处理异步问题则使用 plannotator inbox。它们不是同一个服务模式换几个菜单,尤其不能把一次性文件审阅的返回值当作 Inbox 的持久消息协议。
Claude Code、Pi、OpenCode 有各自的插件接入,通用 Agent 可以通过 plannotator inbox mcp 使用 MCP。自动把人的答复送回会话,还取决于宿主连接;普通 MCP 的工具返回并不等于系统已经拥有唤醒任意外部会话的能力。
安装器默认会检测和配置多种 Agent。--minimal 只装二进制到 ~/.local/bin,跳过技能、钩子、斜杠命令和各宿主配置,适合先确认界面是否符合自己的审阅习惯。后续再按宿主说明增加集成,不必一开始接管所有终端工具。
本地数据默认在 ~/.plannotator,同时有 XDG 和 PLANNOTATOR_DATA_DIR 相关规则。想知道当前究竟使用哪个目录,运行 plannotator data-dir,比直接假设路径稳妥。这个命令用于查询,不需要手动移动旧数据来试探。
项目提供链接分享和可选 AI 能力。涉及内部代码与设计文档时,先决定分享、模型服务、URL 读取的允许范围,再选择功能;“界面在 localhost”不能当成数据永不离开机器的证明。
🚀 快速上手
先只安装二进制,减少环境改动
下面以 macOS、Linux 或 WSL 的 v0.28.67 为例。下载固定版本的安装脚本,先阅读,再执行;脚本仍需联网下载对应平台的发行二进制。minimal 不会替你完成 Agent 插件配置。
curl -fsSL \
https://raw.githubusercontent.com/backnotprop/plannotator/v0.28.67/scripts/install.sh \
-o plannotator-install.sh
less plannotator-install.sh
bash plannotator-install.sh --minimal --version v0.28.67
export PATH="$HOME/.local/bin:$PATH"
plannotator --help
plannotator data-dir
如果环境里已经有其他版本,先用它的帮助检查入口,不要把滚动更新的命令参数和固定版本混着使用。正式使用前也可以按仓库的发行校验说明检查二进制摘要与构建证明。
用一个小文件体验批注
这组命令创建独立练习目录和文件,不需要已有项目 checkout:
mkdir -p plannotator-demo
cd plannotator-demo
printf '%s\n' \
'# 请求重试方案' \
'' \
'- 读取请求遇到临时网络错误时允许重试。' \
'- 支付请求不能在结果不明时直接重放。' \
> plan.md
plannotator annotate plan.md
在浏览器中给第二条留下“请补充幂等键和结果查询路径”的批注,再发送反馈。这个例子先让你观察文档与反馈如何对应;从自己的终端直接运行,不会凭空把结果注入某个没有建立连接的 Agent。
再接入 Inbox
plannotator inbox --help
plannotator inbox
第二条命令打开 Inbox。需要通用 MCP 接入时,在宿主的 MCP 配置中设置命令为 plannotator、参数为 ["inbox", "mcp"];对应启动命令是:
plannotator inbox mcp
它是 stdio MCP 入口,通常由 Agent 宿主启动,不是另一个需要人手动交互的聊天窗口。不同宿主配置文件格式不同,不宜复制一份假装通用的配置覆盖已有设置。
例如,在支持工具调用的客户端中,下面是 send_message 的参数示意,不是 Shell 或 TypeScript 程序。把 project_path 换成真实存在的项目绝对路径;会话身份按已接入宿主提供的信息填写,不能编一个字符串指望它自动收到回复。
{
"project_path": "/absolute/path/to/your-project",
"thread": "request-retry-design",
"subject": "请确认请求重试的边界",
"body": "读取请求可以有限重试;支付请求先查询结果,再决定是否使用原幂等键继续。请批注这份方案。",
"idempotency_key": "request-retry-design-v1"
}
若只是因为连接断开而重试同一次发送,保留相同参数与 key;修改方案再次请求审阅时,换一个新 key。收到工具结果中的消息与线程 ID 后,沿已有线程继续交流,不要把“再调用一次工具”当作“另起一个讨论”。
📊 增长速度与社区热度
当日采集记录中,Plannotator 位列 Trending 第 2,Stars 为 12,804,Forks 为 1,272。这些数值是一个时点的累计量,不能从中算出单日新增 Stars 或增长率。
它的关注点有比较清楚的工程背景:Agent 可以很快产出方案和代码,人仍需要一个能定位内容、保存意见并回到原会话的入口。多个 Agent 并行时,审阅变成了独立工作,而不再只是聊天里偶尔点一次批准。
但榜单排名衡量不了自动投递是否稳定,也衡量不了审阅质量。评估这个项目,更适合观察目标宿主的接入是否完整、回复状态是否能解释、失败后有没有可恢复的路径,而不是把热度当成生产保证。
下表为当日采集的完整榜单:
🎯 适用场景
如果你经常让 Agent 先出方案,再逐段指出修改意见,文档批注比在聊天里写“上面第三段”可靠。需要审阅 HTML 原型或较大的代码 diff 时,保留内容位置和文件上下文也能减少来回解释。
多个 Agent 分别处理不同模块、但都需要同一个人做决定时,Inbox 的线程和会话路由更有价值。它把人的待办聚在一起,同时保留答复地址;前提是你选用的宿主确实接好了对应连接。
它也适合做可控的人机反馈实验:先从普通 Markdown 文件开始,再接一类 Agent,观察重启、回复延迟和重复发送的行为。不要同时开启所有集成,否则很难分辨问题来自宿主、插件还是投递流程。
不适合直接把它当作组织级审批系统。聊天中的“批准”没有自动获得企业身份校验、细粒度权限、不可篡改审计和业务补偿能力。支付、部署、删除资源这类操作,仍应由业务系统验证权限与幂等,再接受 Agent 的请求。
如果需求只有偶尔看一次小 diff,现有编辑器和聊天反馈可能已经够用。增加一个常驻 Inbox 也意味着管理本地数据、连接版本和未送达消息;这些成本要和减少的上下文切换一起考虑。
💡 总结
Plannotator 把审阅做成了一个有地址、有持久记录、能送回 Agent 会话的工作过程。它的技术价值既在可视化批注,也在 Inbox 对消息、线程、宿主连接和投递状态的拆分。
我更看重它对不确定结果的态度:能重连的继续重连,能补确认的补确认,无法证明是否进入会话时就把问题交还给人。它没有解决所有执行可靠性问题,但没有用一个“自动回传”按钮掩盖这些边界。需要人持续参与 Agent 开发的人,可以从这个边界清楚的小入口开始。