【免费下载链接】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 为 Kiro CLI 提供的plannotator-annotate技能包说明如何在 Kiro 会话中通过一条命令把 Markdown/纯文本配置、文件夹、HTML 或 URL 送入 Plannotator 的浏览器批注界面并在批注结果返回后闭环处理。读完本文你将掌握 Kiro 下 annotate 命令的标准写法、PLANNOTATOR_ORIGINkiro-cli环境变量的作用、目标解析与参数容错机制、stdout 输出契约以及--gate --json严格审批门的使用方式并理解技能包在仓库中的安装与组织结构。一、技能定位Kiro 专属的 annotate 技能包在仓库中Kiro CLI 的集成源码位于 apps/kiro-cli 目录其中skills/plannotator-annotate/SKILL.md就是本文的关联文档。它是一个极简的技能启动器frontmatter 声明了技能名plannotator-annotate、disable-model-invocation: true禁止模型凭空自调用必须由用户显式触发以及描述信息 Open Plannotators annotation UI for a file, folder, or URL, then address the returned annotations.。与同目录的 plannotator-review/SKILL.md 相比两者分工明确review面向当前代码变更git/jj diff或 PRannotate面向文档型目标文件、文件夹、URL。Kiro 专属副本刻意把PLANNOTATOR_ORIGINkiro-cli写死在命令里与 apps/skills/core 下的核心技能保持独立——apps/kiro-cli/README.md 明确说明这些 Kiro 副本是故意独立的They hardcode PLANNOTATOR_ORIGINkiro-cli and are exempt from single-sourcing不要用核心副本替换它们。二、标准调用方式关联文档给出了唯一一条核心命令PLANNOTATOR_ORIGINkiro-cli plannotator annotate $ARGUMENTS其中$ARGUMENTS可以是Markdown 或纯文本配置文件路径.md、.txt、.yaml、.json、.toml、.ini、.csv、.log等文件夹路径打开该文件夹内受支持文件的文件浏览器HTML 文件路径URL。PLANNOTATOR_ORIGINkiro-cli是这条命令的关键前缀。根据核心技能文档 apps/skills/core/plannotator/SKILL.md 的环境变量说明PLANNOTATOR_ORIGIN用于覆盖 Agent 来源检测可取claude-code、codex、opencode、pi、oh-my-pi、amp、droid、copilot-cli、gemini-cli、kiro-cli等。当 Plannotator 从 Kiro 这样的包装环境被启动、自带的来源检测无法看穿时就必须显式设置该变量以便 UI 呈现正确的宿主上下文。Kiro 技能包直接把这一设置烘焙进命令用户无需手动记忆。配合 Kiro 自定义 Agent 使用安装后Kiro 用户可以通过示例 Agent 一键接入。仓库中的 agents/plannotator.json 定义了一个名为plannotator的 Kiro 自定义 Agent通过resources字段以skill://~/.kiro/skills/plannotator-*/SKILL.md挂载全部 Plannotator 技能在 prompt 中说明每个技能的适用场景review / annotate / setup-goal / visual-explainer并注明plannotator-review与plannotator-annotate会设置PLANNOTATOR_ORIGINkiro-cli通过toolsSettings.shell.allowedCommands: [plannotator .*]将 shell 工具限制为仅允许执行plannotator命令。启动方式为kiro-cli chat --agent plannotator三、目标解析与参数容错关联文档最后一段写明了 Agent 面对解析失败时的行为契约如果命令报告参数无法解析为文件、URL 或文件夹就自己判断用户指的是哪个目标然后用那个具体路径或 URL 重新运行命令。这与核心技能 apps/skills/core/plannotator-annotate/SKILL.md 中的第 6 条行为完全一致用户用自然语言描述要批注什么时Agent 应自行推断目标并代为执行plannotator annotate path-or-url保留命令回显中的 flags再按输出契约处理结果——不要要求用户把 shell 命令粘贴进聊天框自己运行命令。从 CLI 参考文档apps/skills/core/plannotator/SKILL.md可以进一步了解到 annotate 的参数容错设计多余词语是允许的例如plannotator annotate look at notes.md please会正确打开notes.md两个可解析目标会报错同时命名两个可解析目标属于错误会同时列出两者无法识别的短横线 token 会禁用容错flag 拼写错误会大声失败避免静默误解析多词调用且一无所获时CLI 会在 stdout 打印一段面向 Agent 的交接说明并以退出码 0 结束——Agent 应阅读该说明、确定具体目标再用精确路径或 URL 重跑。支持的目标类型全览依据 CLI 参考文档plannotator annotate支持的目标可归纳为六类目标类型说明示例Markdown / 文本文件.md、.mdx、.txtplannotator annotate plan.md纯文本配置与数据文件.yaml、.yml、.json、.jsonc、.json5、.toml、.ini、.cfg、.conf、.properties、.csv、.tsv、.log、.xml、.env.example以文本渲染plannotator annotate config.yaml图表源文件.mmd/.mermaidMermaid、.dot/.gvGraphviz以完整图表查看器打开缩放、平移、弹窗、点击节点/边/簇评论plannotator annotate flow.mmdHTML 文件.html/.htm默认按原始页面渲染--markdown改为转成 Markdown--render-html仅为兼容保留原始渲染本就是默认plannotator annotate report.htmlURLhttps://...默认经 Jina Reader 抓取并转换--no-jina改为普通 fetch Turndownplannotator annotate https://example.com/docs文件夹打开该文件夹受支持文件的文件浏览器plannotator annotate docs/此外还有两种特殊场景运行中的本地应用回环http://localhost:PORT/探测返回 HTML 时进入 live-app 模式批注真实运行页面--app强制 live 模式无法应用时大声失败--static强制经典转换管线非回环 URL 一律走转换管线边界与限制单个文件上限 2MB文件从磁盘上的稳定项目路径读取不要移动被批注的源文件.env本身被刻意拒绝常含密钥且 annotate 历史会复制文件内容源代码文件不属于 annotate应走plannotator review。四、stdout 输出契约批注如何回到对话会话模型核心技能文档规定每次 annotate 命令都会启动本地 Web 服务器、打开浏览器并阻塞直到人做出决定——这可能耗时数分钟。因此 Agent 应使用长或不设命令超时或在后台启动进程待其退出后读取 stdout不要为了结束批注而杀掉进程无决策结束的会话等同于没有反馈。对于 annotate 及其 last-message 变体stdout 契约如下纯文本默认关闭时输出为空批准时输出The user approved.其余情况输出反馈文本。Agent 应在同一会话中处理返回的反馈--json输出一条 JSON 记录含decisionapproved、dismissed或annotated与可选的原始feedback。注意approved结果仍可能携带feedback备注这类备注是指导性意见而非变更请求应带入后续工作但不要据此修改文档--hook仅用于真实的 PostToolUse/Stop hook 上下文批准/关闭不输出hook 通过批注输出{decision:block,reason:...}。--hook隐含 gate UI绝不能用于普通交互调用。Kiro 技能包的关联文档本身只要求处理返回的批注上述契约在 apps/skills/core/plannotator/SKILL.md 中有完整定义提供了处理三种输出形态的精确依据。五、审批门Gate--gate --json的使用边界普通annotate是纯反馈模式界面只显示Close没有Approve按钮。当用户要求评审、批准、接受或门禁gate某个生成的文件plan/spec/文档时必须使用PLANNOTATOR_ORIGINkiro-cli plannotator annotate path-or-url --gate --json两条纪律核心 annotate 技能强调不要承诺普通 annotate 会话可以批准——只有--gate存在时才有审批动作--json只改变输出格式本身不启用审批——它必须与--gate搭配。Kiro 场景下的典型示例来自 plannotator-setup-goal/SKILL.mdplannotator annotate goals/slug/plan.md --gate若被拒绝则根据反馈修订后重新 gate 直到批准。严格审批门与退出码若需要机器可校验的审批结果可在--gate --json基础上加严格 flagPLANNOTATOR_ORIGINkiro-cli plannotator annotate report.md --gate --json --require-approval --result-file /tmp/decision.json--require-approval退出码直接报告人的审批结果--result-file path把 stdout 的决策 JSON 以原子方式写入指定路径父目录必须存在、目标文件必须不存在结果路径从调用 cwd 解析。严格 flag 下的退出码约定grep 惯例退出码含义0已批准唯一成功1评审人未批准annotated 或 dismissed决策记录仍已发布2门本身失败flag 组合错误、启动失败文件缺失、URL 不可达、文件超限或结果文件无法发布——绝不可当作评审人结果128n被信号 n 杀死无严格 flag 时启动失败退出码为 1退出码不携带任何决策应解析输出而非依赖退出码。两个严格 flag 都要求--gate --json且拒绝--hook。六、安装与组织结构Kiro 技能如何进入~/.kiroKiro 集成没有独立安装器由主安装脚本 scripts/install.sh 统一处理一行安装命令由 README 给出此处说明机制而非重复外部 URL。安装逻辑要点自动检测若~/.kiro存在或kiro-cli在 PATH 上即判定为 Kiro 环境与 Codex、Gemini 采用同一约定并安装集成安装内容2 个 Kiro 专属技能plannotator-review、plannotator-annotate→~/.kiro/skills2 个共享技能plannotator-setup-goal、plannotator-visual-explainer取自 apps/skills/extra不在 Kiro 目录重复→~/.kiro/skills示例 Agentagents/plannotator.json→~/.kiro/agents/plannotator.json已存在则绝不覆盖退出开关install.sh 提供--skip-kiro标志优先级为 flag 环境变量PLANNOTATOR_SKIP_KIRO_INSTALL 配置文件~/.plannotator/config.json中的skipInstall.kiro。七、Agent 实战 Checklist综合关联文档与核心技能Kiro 下使用 annotate 的完整动作序列如下识别场景用户要批注文档/文件夹/URL而非评审代码 diff时选用本技能执行命令PLANNOTATOR_ORIGINkiro-cli plannotator annotate target审批场景追加--gate --json等待会话阻塞直到评审人提交反馈、批准或关闭标签页处理反馈有批注则直接处理会话无反馈关闭则简短说明并继续解析失败兜底命令报告无法解析时自行推断目标并用具体路径/URL 重跑保持命令回显的 flags批准带备注--gate --json下decision:approved且带feedback时把备注带入后续工作但不要据此修订文档——它们是指导不是变更请求。这套流程把 Plannotator 的人在浏览器中标注、结构化反馈回到 stdout机制与 Kiro Agent 的自主执行能力结合起来Agent 负责定位目标、启动会话、消费反馈人负责在批注 UI 中给出精准意见从而形成文档评审的闭环。延伸阅读Kiro CLI 集成说明目录结构、安装约定、Agent 启动方式Kiro 批注技能原文Kiro 评审技能同一 Agent 下的代码/PR 评审入口Kiro 示例 Agent 配置核心 annotate 技能跨宿主的行为契约与纪律Plannotator CLI 参考全部子命令、环境变量与退出码的权威定义Claude 版 annotate 技能另一种宿主下的同主题实现赞分享【免费下载链接】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 OpenCode 插件 /plannotator-annotate 命令解析:从 Markdown 存根到注释反馈闭环plannotator OpenCode 插件 /plannotator annotate 命令解析:从 Markdown 存根到注释反馈闭环 本篇以 planPlannotator 接入 Kiro CLI 实战Skills 自动安装与 plannotator 自定义 AgentPlannotator 接入 Kiro CLI 实战Skills 自动安装与 plannotator 自定义 Agent 本篇指南基于 PlannotatorGitHub Copilot CLI 集成指南读懂 plannotator-annotate 命令协议与注解决策流转GitHub Copilot CLI 集成指南读懂 plannotator annotate 命令协议与注解决策流转 导读 plannotator annot上一篇Apache MXNet在娱乐产业中的应用内容生成与个性化推荐下一篇终极指南如何在Windows Vista/Server 2008上安装Python 3.8最新版本创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
