【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载Plannotator 的 External Annotations API 让 Linter、AI 工具、安全扫描器和自定义脚本能通过本地 HTTP 接口把标注实时推送到一个正在运行的 Plannotator 会话中。读完本文你将掌握完整的端点用法POST 单条/批量、PATCH 更新、DELETE 清理、plan 与 review 两种标注形状的字段规则以及 SSE 实时广播与轮询降级的工作机制并可直接把这条管道接进自己的工具链。工作原理整条链路非常短外部工具向本地服务器发一个 HTTP 请求标注随即出现在浏览器里。External tool (eslint, AI agent, etc.) ↓ POST /api/external-annotations Local Plannotator server (in-memory store) ↓ SSE broadcast Browser UI - annotation appears in real-time关键行为与 服务端实现 对应内存存储会话级生命周期标注存放在本地 Plannotator 服务器的内存 store 中共享 store 实现 的createAnnotationStore不落盘会话结束后消失。SSE 实时广播每次 store 变更add / remove / update / clear都会通过 Server-Sent Events 广播给所有已连接的浏览器。轮询降级若 SSE 不可用例如代理环境客户端会自动降级为带版本门的轮询功能不中断。反馈导出当用户提交反馈approve、deny 或 send时外部标注会随用户创建的标注一起被包含在导出的反馈中——也就是说你的工具产出的标注可以直接成为回传给 agent 的 feedback 的一部分。快速开始Plannotator 启动时终端会打印服务地址例如Server running on http://localhost:54321端口号从该输出中获取本地会话使用随机端口远程模式下默认固定为19432见 API Endpoints。Plan review标注一段文本curl -X POST http://localhost:PORT/api/external-annotations \ -H Content-Type: application/json \ -d { source: my-tool, type: COMMENT, originalText: the selected text in the plan, text: This needs attention }Code review标注一个代码位置curl -X POST http://localhost:PORT/api/external-annotations \ -H Content-Type: application/json \ -d { source: eslint, type: concern, filePath: src/utils.ts, lineStart: 10, lineEnd: 12, text: Possible null reference }source字段标识工具名称会在 UI 中显示为徽标badge同时是 DELETE 按来源清理的过滤键。成功时服务器返回201与{ ids: [uuid] }。端点总览MethodEndpoint作用GET/api/external-annotations/streamSSE 流实时更新GET/api/external-annotationsJSON 快照轮询降级用支持?sinceN版本门控POST/api/external-annotations添加一条或多条标注PATCH/api/external-annotations?id更新某条标注的字段DELETE/api/external-annotations?id/?source按 id 删除、按工具清理、或清空全部完整的请求/响应细节可参考 API Endpoints。GET/streamSSE 实时流服务器为该端点返回Content-Type: text/event-stream响应。从 Bun 处理器源码 可以看到两个值得注意的细节连接即快照新连接建立时服务器先推送当前全部标注作为snapshot事件客户端无需再单独拉一次全量。30 秒心跳每 30 秒发送一个 SSE 注释心跳HEARTBEAT_INTERVAL_MS 30_000见 packages/core/external-annotation.ts保活处理器还会调用disableIdleTimeout防止服务器侧空闲超时切断长连接该行为有专门测试验证。事件体统一为data: json\n\n格式事件类型有五种snapshot、add、remove、clear、update定义于 ExternalAnnotationEvent。GET 快照?sinceN版本门控轮询客户端带上已知的version查询该端点若版本未变服务器直接返回304空响应否则返回{ annotations: [...], version: N }见 处理器实现。每次 store 变更都会递增一个单调版本号使轮询在无变化时几乎零成本。POST单条或批量两种请求体形态由同一个解析器处理unwrapBody单条顶层即标注对象必须带字符串source批量包裹在annotations数组中见下一节。任一字段校验失败即整体返回400与{ error: ... }错误信息会指明数组下标和字段名例如annotations[1] invalid type xxx。PATCH按白名单更新字段PATCH /api/external-annotations?iduuid用于修改已存在的标注规则比直觉更严格validateAnnotationPatch字段白名单只有 plan/review 各自的已知字段可被修改如text、type、severity、inReplyTo、diagramAnchor等未知键被静默丢弃而非报错——线上格式是增量演进的新写入方的新字段不构成拒绝理由。身份字段不可变id与source在 store 层被钉死update 实现。源码注释解释了原因source是反馈导出器判断是否逐字注入 SKILL.md 指令的安全标记若允许{source: }通过合并任何本地进程都能剥掉外部标记重新武装注入路径。测试用例端到端复现并验证了这一守卫patch{source: }、{source: innocent}、{source: null}均不生效。结构化字段走 fail-closed 解析器如diagramAnchor必须通过同一个锚点解析器畸形值直接400绝不会被存成渲染器读属性时会崩的空值。回复线程校验inReplyTo必须指向另一条存在的标注且不能形成自引用或环validateReplyTarget非法状态在入口处即被拒绝。未找到目标 id 时返回404成功返回{ annotation: updated }。DELETE三种粒度的清理从 处理器源码 可见# 删除单条 curl -X DELETE http://localhost:PORT/api/external-annotations?iduuid # 清理某个工具的全部标注返回被移除数量 curl -X DELETE http://localhost:PORT/api/external-annotations?sourceeslint # 清空全部 curl -X DELETE http://localhost:PORT/api/external-annotations返回{ ok: true }或{ ok: true, removed: count }。批量标注一次发送多条时把标注包裹在annotations数组里curl -X POST http://localhost:PORT/api/external-annotations \ -H Content-Type: application/json \ -d { annotations: [ { source: eslint, type: concern, filePath: src/a.ts, lineStart: 5, lineEnd: 5, text: Unused variable }, { source: eslint, type: concern, filePath: src/b.ts, lineStart: 12, lineEnd: 14, text: Missing error handling } ] }返回{ ids: [uuid1, uuid2] }。空数组会被拒绝annotations array must not be empty。plan 与 review 两种标注形状端点面在 plan review、code review、annotate 三种模式下完全一致唯一区别是标注形状服务器按模式选择不同的输入转换器见 transformPlanInput 与 transformReviewInputPlan / annotate 模式字段必填说明source是工具标识UI 中显示为徽标text是标注内容type否DELETION/COMMENT/GLOBAL_COMMENT默认GLOBAL_COMMENToriginalTextCOMMENT与DELETION必填锚定的原文片段COMMENT缺它会渲染成空引用气泡想只做侧边栏反馈应使用GLOBAL_COMMENTauthor否展示用的作者名diagramAnchor否指向渲染图表中某部分的锚点{ v: 1, family, kind, id \| from to, label, sourceLine }必须通过严格解析器服务器会把这些标注固定为blockId: external与用户手工标注的块级锚定区分开。Review 模式字段必填说明source是工具标识type否comment/suggestion/concern默认commentscope否line/file/general默认lineline要求filePathlineStartlineEndfile只要求filePathgeneral不需要任何定位定位分类逻辑side否old/new默认newtext或suggestedCode至少其一标注正文或建议代码originalCode否配合suggestedCode显示替换前severity否important/nit/pre_existing运行内置沙箱演示仓库自带一个手动测试脚本它会启动一个带示例 diff 的沙箱 review 服务器然后按时间波次推送标注让你直观看到它们实时出现、更新和消失bun run tests/manual/test-external-annotations.ts脚本tests/manual/test-external-annotations.ts会打开浏览器并发送 6 波标注、历时约 17 秒Wave 1单条 eslint concern2 秒后Wave 2批量 3 条eslint 重复导入 typescript 隐式 any 一条带suggestedCode/originalCode的 suggestionWave 3coverage 覆盖度 commentWave 4depcheck 对package.json的 concernWave 5按 id 删除第一条标注Wave 6按sourceeslint清空该工具的全部标注。观察标注面板应看到标注陆续出现最后剩余 coverage、depcheck、typescript 三条。提交反馈后脚本还会打印服务器收到的最终决定。注意该脚本直接读取apps/review/dist/index.html即它假定 review 前端已构建请在完成构建的检出中运行。三种模式全部可用客户端如何收事件External annotations API 在 plan review、code review 和 annotate 模式下均可用。从源码接线可以确认三个服务器各自创建了处理器Plan 服务器packages/server/index.ts 中以plan模式创建archive 只读模式下禁用Review 服务器packages/server/review.ts 中以review模式创建Annotate 服务器packages/server/annotate.ts 中以plan模式创建因此 annotate 模式同样使用originalText/blockId形状的 plan 标注。另外Pi 扩展有一个基于node:http的镜像处理器apps/pi-extension/server/external-annotations.ts与 Bun 处理器共用同一套运行时无关的 store 与校验逻辑。浏览器侧的事件消费由 useExternalAnnotations hook 完成其状态机与文档描述的降级行为一一对应首选 SSEEventSource连接/api/external-annotations/stream解析snapshot/add/remove/clear/update五类事件并归约进本地状态一次性降级轮询若从未收到过快照就出错典型如代理环境吞掉 SSEhook 关闭 EventSource 并切换为每 500ms 一次的快照轮询携带?sinceversion收到304即跳过乐观更新UI 内删除/清空/更新操作先改本地状态再发 DELETE/PATCH 请求失败时等待下一轮 SSE 事件对账。安全边界小结这个 API 是本地回环、无鉴权的表面localhost源码里因此有多处防御性设计接工具前值得了解source不可经 PATCH 清除或改写防止伪造用户创建标注以触发 SKILL.md 逐字注入PATCH 字段白名单 结构化字段 fail-closed 解析防止把diagramAnchor打成null后让渲染器读取.family时白屏inReplyTo入口拒绝自引用与环POST 批量校验任一失败即整批 400错误信息带下标便于调试。把 lint 结果、AI 审查发现或安全扫描输出按上述形状 POST 到这个端点就能让它们在 Plannotator 界面中与人工标注同屏出现并随一次反馈提交原路送回 agent。赞分享【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载相关推荐ARIS 外部节奏External Cadence实战指南调度驱动何时合法、评审裁决何时不可外包ARIS 外部节奏External Cadence实战指南调度驱动何时合法、评审裁决何时不可外包 导读 本文是 ARISAuto Research InAI 技能/插件AI 评测科研人工智能MCP 服务dsh-pluginPlannotator Hook 集成用 --hook 把人工评审闸门嵌入 Agent 生命周期Plannotator Hook 集成用 hook 把人工评审闸门嵌入 Agent 生命周期 本篇基于 Plannotator 仓库中的官方指南 hook i3 分钟配好自定义指令让 GitHub Copilot for Xcode 写出有团队味的代码3 分钟配好自定义指令让 GitHub Copilot for Xcode 写出有团队味的代码 刚让 Xcode 里的 AI 写代码产出总差一口气命名开发工具AI 应用AI Agent上一篇Chrome画中画扩展解锁多任务视频观看新姿势下一篇Steam挂刀行情追踪终极指南从零搭建全天候市场监控系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Plannotator External Annotations API:把外部工具的标注实时推送到活动评审会话
【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载Plannotator 的 External Annotations API 让 Linter、AI 工具、安全扫描器和自定义脚本能通过本地 HTTP 接口把标注实时推送到一个正在运行的 Plannotator 会话中。读完本文你将掌握完整的端点用法POST 单条/批量、PATCH 更新、DELETE 清理、plan 与 review 两种标注形状的字段规则以及 SSE 实时广播与轮询降级的工作机制并可直接把这条管道接进自己的工具链。工作原理整条链路非常短外部工具向本地服务器发一个 HTTP 请求标注随即出现在浏览器里。External tool (eslint, AI agent, etc.) ↓ POST /api/external-annotations Local Plannotator server (in-memory store) ↓ SSE broadcast Browser UI - annotation appears in real-time关键行为与 服务端实现 对应内存存储会话级生命周期标注存放在本地 Plannotator 服务器的内存 store 中共享 store 实现 的createAnnotationStore不落盘会话结束后消失。SSE 实时广播每次 store 变更add / remove / update / clear都会通过 Server-Sent Events 广播给所有已连接的浏览器。轮询降级若 SSE 不可用例如代理环境客户端会自动降级为带版本门的轮询功能不中断。反馈导出当用户提交反馈approve、deny 或 send时外部标注会随用户创建的标注一起被包含在导出的反馈中——也就是说你的工具产出的标注可以直接成为回传给 agent 的 feedback 的一部分。快速开始Plannotator 启动时终端会打印服务地址例如Server running on http://localhost:54321端口号从该输出中获取本地会话使用随机端口远程模式下默认固定为19432见 API Endpoints。Plan review标注一段文本curl -X POST http://localhost:PORT/api/external-annotations \ -H Content-Type: application/json \ -d { source: my-tool, type: COMMENT, originalText: the selected text in the plan, text: This needs attention }Code review标注一个代码位置curl -X POST http://localhost:PORT/api/external-annotations \ -H Content-Type: application/json \ -d { source: eslint, type: concern, filePath: src/utils.ts, lineStart: 10, lineEnd: 12, text: Possible null reference }source字段标识工具名称会在 UI 中显示为徽标badge同时是 DELETE 按来源清理的过滤键。成功时服务器返回201与{ ids: [uuid] }。端点总览MethodEndpoint作用GET/api/external-annotations/streamSSE 流实时更新GET/api/external-annotationsJSON 快照轮询降级用支持?sinceN版本门控POST/api/external-annotations添加一条或多条标注PATCH/api/external-annotations?id更新某条标注的字段DELETE/api/external-annotations?id/?source按 id 删除、按工具清理、或清空全部完整的请求/响应细节可参考 API Endpoints。GET/streamSSE 实时流服务器为该端点返回Content-Type: text/event-stream响应。从 Bun 处理器源码 可以看到两个值得注意的细节连接即快照新连接建立时服务器先推送当前全部标注作为snapshot事件客户端无需再单独拉一次全量。30 秒心跳每 30 秒发送一个 SSE 注释心跳HEARTBEAT_INTERVAL_MS 30_000见 packages/core/external-annotation.ts保活处理器还会调用disableIdleTimeout防止服务器侧空闲超时切断长连接该行为有专门测试验证。事件体统一为data: json\n\n格式事件类型有五种snapshot、add、remove、clear、update定义于 ExternalAnnotationEvent。GET 快照?sinceN版本门控轮询客户端带上已知的version查询该端点若版本未变服务器直接返回304空响应否则返回{ annotations: [...], version: N }见 处理器实现。每次 store 变更都会递增一个单调版本号使轮询在无变化时几乎零成本。POST单条或批量两种请求体形态由同一个解析器处理unwrapBody单条顶层即标注对象必须带字符串source批量包裹在annotations数组中见下一节。任一字段校验失败即整体返回400与{ error: ... }错误信息会指明数组下标和字段名例如annotations[1] invalid type xxx。PATCH按白名单更新字段PATCH /api/external-annotations?iduuid用于修改已存在的标注规则比直觉更严格validateAnnotationPatch字段白名单只有 plan/review 各自的已知字段可被修改如text、type、severity、inReplyTo、diagramAnchor等未知键被静默丢弃而非报错——线上格式是增量演进的新写入方的新字段不构成拒绝理由。身份字段不可变id与source在 store 层被钉死update 实现。源码注释解释了原因source是反馈导出器判断是否逐字注入 SKILL.md 指令的安全标记若允许{source: }通过合并任何本地进程都能剥掉外部标记重新武装注入路径。测试用例端到端复现并验证了这一守卫patch{source: }、{source: innocent}、{source: null}均不生效。结构化字段走 fail-closed 解析器如diagramAnchor必须通过同一个锚点解析器畸形值直接400绝不会被存成渲染器读属性时会崩的空值。回复线程校验inReplyTo必须指向另一条存在的标注且不能形成自引用或环validateReplyTarget非法状态在入口处即被拒绝。未找到目标 id 时返回404成功返回{ annotation: updated }。DELETE三种粒度的清理从 处理器源码 可见# 删除单条 curl -X DELETE http://localhost:PORT/api/external-annotations?iduuid # 清理某个工具的全部标注返回被移除数量 curl -X DELETE http://localhost:PORT/api/external-annotations?sourceeslint # 清空全部 curl -X DELETE http://localhost:PORT/api/external-annotations返回{ ok: true }或{ ok: true, removed: count }。批量标注一次发送多条时把标注包裹在annotations数组里curl -X POST http://localhost:PORT/api/external-annotations \ -H Content-Type: application/json \ -d { annotations: [ { source: eslint, type: concern, filePath: src/a.ts, lineStart: 5, lineEnd: 5, text: Unused variable }, { source: eslint, type: concern, filePath: src/b.ts, lineStart: 12, lineEnd: 14, text: Missing error handling } ] }返回{ ids: [uuid1, uuid2] }。空数组会被拒绝annotations array must not be empty。plan 与 review 两种标注形状端点面在 plan review、code review、annotate 三种模式下完全一致唯一区别是标注形状服务器按模式选择不同的输入转换器见 transformPlanInput 与 transformReviewInputPlan / annotate 模式字段必填说明source是工具标识UI 中显示为徽标text是标注内容type否DELETION/COMMENT/GLOBAL_COMMENT默认GLOBAL_COMMENToriginalTextCOMMENT与DELETION必填锚定的原文片段COMMENT缺它会渲染成空引用气泡想只做侧边栏反馈应使用GLOBAL_COMMENTauthor否展示用的作者名diagramAnchor否指向渲染图表中某部分的锚点{ v: 1, family, kind, id \| from to, label, sourceLine }必须通过严格解析器服务器会把这些标注固定为blockId: external与用户手工标注的块级锚定区分开。Review 模式字段必填说明source是工具标识type否comment/suggestion/concern默认commentscope否line/file/general默认lineline要求filePathlineStartlineEndfile只要求filePathgeneral不需要任何定位定位分类逻辑side否old/new默认newtext或suggestedCode至少其一标注正文或建议代码originalCode否配合suggestedCode显示替换前severity否important/nit/pre_existing运行内置沙箱演示仓库自带一个手动测试脚本它会启动一个带示例 diff 的沙箱 review 服务器然后按时间波次推送标注让你直观看到它们实时出现、更新和消失bun run tests/manual/test-external-annotations.ts脚本tests/manual/test-external-annotations.ts会打开浏览器并发送 6 波标注、历时约 17 秒Wave 1单条 eslint concern2 秒后Wave 2批量 3 条eslint 重复导入 typescript 隐式 any 一条带suggestedCode/originalCode的 suggestionWave 3coverage 覆盖度 commentWave 4depcheck 对package.json的 concernWave 5按 id 删除第一条标注Wave 6按sourceeslint清空该工具的全部标注。观察标注面板应看到标注陆续出现最后剩余 coverage、depcheck、typescript 三条。提交反馈后脚本还会打印服务器收到的最终决定。注意该脚本直接读取apps/review/dist/index.html即它假定 review 前端已构建请在完成构建的检出中运行。三种模式全部可用客户端如何收事件External annotations API 在 plan review、code review 和 annotate 模式下均可用。从源码接线可以确认三个服务器各自创建了处理器Plan 服务器packages/server/index.ts 中以plan模式创建archive 只读模式下禁用Review 服务器packages/server/review.ts 中以review模式创建Annotate 服务器packages/server/annotate.ts 中以plan模式创建因此 annotate 模式同样使用originalText/blockId形状的 plan 标注。另外Pi 扩展有一个基于node:http的镜像处理器apps/pi-extension/server/external-annotations.ts与 Bun 处理器共用同一套运行时无关的 store 与校验逻辑。浏览器侧的事件消费由 useExternalAnnotations hook 完成其状态机与文档描述的降级行为一一对应首选 SSEEventSource连接/api/external-annotations/stream解析snapshot/add/remove/clear/update五类事件并归约进本地状态一次性降级轮询若从未收到过快照就出错典型如代理环境吞掉 SSEhook 关闭 EventSource 并切换为每 500ms 一次的快照轮询携带?sinceversion收到304即跳过乐观更新UI 内删除/清空/更新操作先改本地状态再发 DELETE/PATCH 请求失败时等待下一轮 SSE 事件对账。安全边界小结这个 API 是本地回环、无鉴权的表面localhost源码里因此有多处防御性设计接工具前值得了解source不可经 PATCH 清除或改写防止伪造用户创建标注以触发 SKILL.md 逐字注入PATCH 字段白名单 结构化字段 fail-closed 解析防止把diagramAnchor打成null后让渲染器读取.family时白屏inReplyTo入口拒绝自引用与环POST 批量校验任一失败即整批 400错误信息带下标便于调试。把 lint 结果、AI 审查发现或安全扫描输出按上述形状 POST 到这个端点就能让它们在 Plannotator 界面中与人工标注同屏出现并随一次反馈提交原路送回 agent。赞分享【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载相关推荐ARIS 外部节奏External Cadence实战指南调度驱动何时合法、评审裁决何时不可外包ARIS 外部节奏External Cadence实战指南调度驱动何时合法、评审裁决何时不可外包 导读 本文是 ARISAuto Research InAI 技能/插件AI 评测科研人工智能MCP 服务dsh-pluginPlannotator Hook 集成用 --hook 把人工评审闸门嵌入 Agent 生命周期Plannotator Hook 集成用 hook 把人工评审闸门嵌入 Agent 生命周期 本篇基于 Plannotator 仓库中的官方指南 hook i3 分钟配好自定义指令让 GitHub Copilot for Xcode 写出有团队味的代码3 分钟配好自定义指令让 GitHub Copilot for Xcode 写出有团队味的代码 刚让 Xcode 里的 AI 写代码产出总差一口气命名开发工具AI 应用AI Agent上一篇Chrome画中画扩展解锁多任务视频观看新姿势下一篇Steam挂刀行情追踪终极指南从零搭建全天候市场监控系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考