【免费下载链接】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点击查看免费下载在 Claude Code 等编码 Agent 中Plannotator 通过 SKILL.md 技能文件把“可视化审阅 Agent 最近一条回复”变成一条可直接触发的命令。本篇围绕 plannotator-last 技能定义 展开讲清其 frontmatter 配置allowed-tools、disable-model-invocation的约束语义、!前缀动态命令与$ARGUMENTS参数透传机制以及技能核心的“三种输出决策”任务协议——批准approved、关闭dismissed、带注释反馈annotated并结合 CLI 别名解析与标注服务源码说明plannotator last命令背后的真实调用链。读完后你能掌握如何在自己的 harness 中复刻这类技能并正确路由审阅结果。技能文件总览与 frontmatter 约束Claude Code 的技能本质是一个带 YAML frontmatter 的 Markdown 文件。plannotator-last/SKILL.md 的 frontmatter 定义了技能的身份与调用边界--- name: plannotator-last description: Open Plannotator on the latest rendered assistant message and use the returned annotations to revise that message or continue. allowed-tools: Bash(plannotator:*) disable-model-invocation: true ---各字段的作用name技能在 harness 中的唯一标识。斜杠命令/plannotator-last即由此派生用户在 Claude Code 中输入该命令即可触发本技能。description技能用途的一句话描述供 harness 展示给用户。allowed-tools: Bash(plannotator:*)声明该技能执行时只允许调用以plannotator开头的 Bash 命令。这是一个白名单约束——技能体内所有需要执行的操作都收敛到plannotator可执行文件不会触及其他 shell 能力。disable-model-invocation: true禁止模型自主隐式调用本技能只能由用户显式触发。这一策略在配套的 openai.yaml 中以policy.allow_implicit_invocation: false的形式镜像保证跨 harness 行为一致。之所以这样设计是因为“打开审阅界面并阻塞等待人工反馈”是一个高交互副作用动作绝不应该被模型在对话中自行决定发起。值得注意的是本技能与同目录下的 plannotator-annotate、plannotator-review 共享同一套结构模式frontmatter 白名单 动态命令执行 “Your task” 决策协议仅命令与反馈对象不同文件/URL/文件夹 vs 最新消息 vs 代码 diff/PR。动态命令!前缀与$ARGUMENTS透传技能正文的核心执行段只有一行## Message annotations !plannotator annotate-last $ARGUMENTS这里有两个关键机制!前缀表示“在技能注入前先执行这条 shell 命令并把其 stdout 作为上下文的一部分”。与普通的 bash 代码块只给用户/模型看不同!包裹的命令块由 harness 实际执行——命令运行时浏览器标注界面会打开命令阻塞直到标注会话结束退出时把审阅结果打印到 stdout再连同本技能其余内容一起交给模型。$ARGUMENTS透传用户在/plannotator-last后面追加的参数会原样展开到命令里。例如/plannotator-last --gate --json会展开为plannotator annotate-last --gate --json从而让审阅结果以结构化 JSON 而非纯文本返回。plannotator annotate-last与plannotator last是同一命令。从源码看CLI 的 别名表 中定义了last: annotate-last的映射SUBCOMMAND_HELP_ALIASES约第 322–324 行并且--help文案也同时列出两条形式plannotator last [--stdin] [--tailscale] [--gate] [--json] [--hook] plannotator annotate-last [--stdin] [--tailscale] [--gate] [--json] [--hook]支持的标志位annotate-last复用annotate的完整标志位矩阵最常用的是三个结构化输出开关详见官方文档 annotate-last 命令页 与 Annotate Gates and JSON Responses标志行为--gate在标注 UI 增加 Approve 按钮形成“批准 / 发送注释 / 关闭”三路决策--json每个决策以单行 JSON 输出到 stdout例如{decision:annotated,feedback:...}--hook输出 hook 原生 JSON{decision:block,reason:...}直接对接 Claude Code 的 Stop/PostToolUse hook 协议隐含--gate--gate --json组合下的 stdout 契约批准输出{decision:approved}附注时携带feedback字段关闭输出{decision:dismissed}发送注释输出{decision:annotated,feedback:markdown}。这正是技能“Your task”一节需要识别的输出形态。“Your task”三种输出结果的路由协议技能文档最重要的部分是命令输出之后的行为约束。原文档规定上方!命令的输出必然落入以下三种情况之一模型必须按对应方式处理情况 1用户批准输出为精确文本The user approved.或decision: approved的 JSON 对象。这意味着用户认可了模型上一条消息。若 JSON 对象还携带feedback字段说明用户是带注批准——这些注释是非阻塞性指导non-blocking guidance应被读入并带入后续工作但不是要求重写该消息。否则只用一句话确认Approved.并停止。无论哪种情况都不应开始任何新工作。情况 2会话关闭输出为空或decision: dismissed的 JSON 对象。用户没有要求任何变更就关闭了会话。用一句话确认Annotation session closed.并停止不开始任何工作。情况 3收到注释反馈输出为纯文本注释反馈或decision: annotated且带feedback字段的 JSON 对象。用户审阅了模型上一条消息并给出了具体的划词标注和评论模型需要针对反馈做出修改Address the feedback。对比同目录的 plannotator-annotate 技能plannotator-last 少了第四种情况——“参数无法解析为文件/URL/文件夹”的兜底分支因为annotate-last的目标天然确定就是最新一条助手消息不存在目标解析问题而plannotator annotate接受用户自然语言描述的目标需要模型自行推断并补跑命令。这套协议与 CLI 的 stdout 契约严格对应纯文本模式下批准输出The user approved.、关闭输出空、发送注释输出反馈 markdown加--json后三种决策全部 JSON 化。技能把两种形态都写进分支条件“The exact text X, OR a JSON object with …”使得同一技能文件在有无--json的情况下都能正确路由。底层实现消息从哪里来反馈到哪里去会话日志解析annotate-last的目标是“最新一条已渲染的助手消息”各 harness 的取法不同见 命令文档Harness来源方式Claude Code~/.claude/projects/{slug}/*.jsonl解析 JSONL 会话日志定位最后一条 assistant 文本块OpenCodeSDKclient.session.messages()APIPiSDKctx.sessionManager.getEntries()APICodex~/.codex/sessions/rollout 文件按CODEX_THREAD_ID环境变量解析 JSONL对 Claude Code解析器要处理流式分块多条 JSONL 行共享同一message.id的合并、过滤系统生成的用户消息与噪声条目若最近一次会话日志里没有 assistant 消息会按修改时间倒序回退到更早的日志。标注服务的 annotate-last 模式在服务端annotate.ts 的会话配置中mode字段区分annotate文件、annotate-last最新消息、annotate-folder等形态。其中recentMessages字段按“新消息在前”提供候选消息列表——当提供多条时编辑器会渲染一个选择器让用户挑选要注释的消息索引 0 为默认选中项与“最后一条消息”的旧行为兼容。会话结束后提交记录会按模式打上来源标记mode annotate-last ? annotate-last : ...写入反馈存档保证annotate-last的审阅与文件审阅一样留下持久记录。UI 层面annotate-last模式与plannotator annotate完全同构仅文案不同复制按钮显示 “Copy message” 而非 “Copy plan”完成页措辞为 “annotations on the message”反馈导出标题为 “Message Feedback”。跨 harness 变体与使用要点同一技能在 core 目录 下还有一份跨 harness 通用版本内容与 Claude Code 版几乎一致差异在于frontmatter 中没有allowed-tools该字段是 Claude Code 特有语法执行命令写作plannotator last短别名而非plannotator annotate-last额外强调执行命令前不要发送任何铺垫/状态消息因为命令注释的是“最新一条已渲染的助手回复”多出来的前言反而会变成被注释的对象明确要求模型自己执行命令而不是把 shell 语法告诉用户让其手动运行。这些约束点值得在自建技能时借鉴目标确定性annotate-last不需要用户给路径天然指向“上一条回复”所以技能体极简——一行命令加一段路由协议阻塞语义命令执行会挂起直到人工审阅结束技能协议必须覆盖“无输出/空输出”这一分支用户直接关窗口决策三态与语义区分approved 是“可以继续”dismissed 是“本轮结束、不注入任何信号”annotated 是“必须修改”带注的 approved 介于批准与修改请求之间——三者混淆都会导致 Agent 行为失控结构化输出的可移植性通过--json技能输出协议从纯文本匹配升级为稳定的 JSON 契约便于被 hook、插件或其他程序消费在 OpenCode 和 Pi 上--json/--hook会被静默接受这两个 harness 直接写回会话而非走 stdout保证了同一份技能文件在各 harness 上可移植。参考路径技能定义apps/skills/claude/plannotator-last/SKILL.md、apps/skills/core/plannotator-last/SKILL.md兄弟技能plannotator-annotate、plannotator-reviewCLI 别名与帮助文案apps/hook/server/cli.ts标注服务实现packages/server/annotate.ts命令与网关文档annotate-last 命令、Annotate Gates and JSON Responses赞分享【免费下载链接】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点击查看免费下载相关推荐如何用 but skill install 把 GitButler CLI Agent 技能安装到 Claude Code 等 AI 编码工具中并用 --detect 更新如何用 but skill install 把 GitButler CLI Agent 技能安装到 Claude Code 等 AI 编码工具中并用 detec开发工具版本控制CLIbook-to-skill把任何技术书籍转换成 Claude Code / Copilot CLI 可用的 Agent Skill 实战指南book to skill把任何技术书籍转换成 Claude Code / Copilot CLI 可用的 Agent Skill 实战指南 book toAI 技能多智能体如何并行协作Claude Code Ultimate Guide Agent Teams工作流与决策框架全解多智能体如何并行协作Claude Code Ultimate Guide Agent Teams工作流与决策框架全解 Claude Code Ultimate上一篇F3D终极指南如何快速掌握这个轻量级3D查看器的5大核心功能下一篇如何快速构建基于Fay的虚拟服务员订单管理系统完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
