开发工具代码评审CLIAI 应用【免费下载链接】hunkReview-first terminal diff viewer for agentic coders项目地址https://gitcode.com/gh_mirrors/hu/hunk点击查看免费下载导读HunkReview-first terminal diff viewer for agentic coders为 Agent 驱动的代码审查提供了两条注入审查推理的通道一条是实时会话评论live session commentsAgent 边看边写另一条是JSON 侧车文件agent-context sidecar注解随 diff/patch 一起提交或预先存在。本文以 Hunk 官方文档website/src/content/docs/docs/agents/agent-context-and-stml.md为主体结合仓库源码packages/hunk/src/core/changeset/sidecar.ts、packages/hunk/src/ui/lib/stml/等与真实示例examples/3-agent-review-demo/agent-context.json完整讲解侧车文件的字段规范、加载命令、叙述性文件排序以及实验性 STML 终端富文本标记的启用、预览与词汇表帮助你为 Agent 与 Hunk 的协作设计出既紧凑又信息密度高的审查输入。为什么需要 sidecar与实时评论的工作流分工Hunk 将实时会话评论视为推荐工作流会话进行中Agent 可以针对正在浏览的 hunk 直接追加注释形成边看边审的交互体验。但有两种场景下实时评论并不适用这正是侧车文件的用武之地注解在 Hunk 启动前就已存在——例如上一个 Agent 会话或其他审查工具已经产出了完整结论需要原样灌入本次审查注解需要随 patch 一起旅行——你拿到一份change.patch和配套的agent-context.json希望在任何环境、任何时间复现同样的审查上下文。从源码结构看侧车加载是可选增强而非强制输入packages/hunk/src/core/changeset/sidecar.ts中的loadSidecarContext在未提供路径时直接返回null整个加载管线对此完全容错packages/hunk/src/core/changeset/loaders.ts中loadChangesetInput只有在input.options.agentContext存在时才调用加载器。也就是说带不带侧车都能正常审查带上侧车则是加分项。加载 JSON 侧车两条入口命令原文档给出的核心命令如下两条路径覆盖了最常见的两种审查输入形态hunk diff --agent-context notes.json hunk patch change.patch --agent-context notes.jsonhunk diff --agent-context notes.json对工作区/指定范围生成 diff 审查同时把notes.json的注解挂载到对应文件与 hunk 上hunk patch change.patch --agent-context notes.json直接审查一份 patch 文件侧车注解随之带入。除了文件路径--agent-context还支持从标准输入读取在loadSidecarContext中pathOrDash -时会将 stdin 整体读入再JSON.parse因此你可以用hunk diff --agent-context -配合管道把 Agent 生成的 JSON 直接喂给 Hunk而无需落地临时文件。此外该标志的定义位于packages/hunk/src/session/agent/surface.ts的AUXILIARY_AGENT_OPTIONS.agentContext--agent-context path描述为 JSON sidecar with agent rationale由packages/hunk/src/app/cli.ts注册到实际 CLI 解析器属于 Agent 会话命令面与 CLI 共享的稳定标志。一份真实可用的完整示例仓库中的examples/3-agent-review-demo/agent-context.json是一份经过校验的紧凑示例配套的examples/3-agent-review-demo/change.patch是对应的代码变更完整内容如下{ version: 1, summary: Improves command-palette matching by normalizing query text and ranking stronger matches ahead of loose substring hits., files: [ { path: src/normalize.ts, summary: Centralizes query cleanup before any matching happens., annotations: [ { newRange: [1, 3], summary: Adds one normalization helper for whitespace, case, and dashed shortcut terms., rationale: This lets the search layer reason about one normalized token shape instead of repeating slightly different cleanup logic in multiple places., author: sonnet } ] }, { path: src/search.ts, summary: Scores and sorts matches instead of returning the first loose substring list., annotations: [ { newRange: [15, 35], summary: Prefix and exact keyword matches now outrank weaker substring hits before the result list is sorted., rationale: The old behavior made every match look equally good, which was fine for filtering but weak for command-palette ranking where the top result should usually be the most obvious intent., author: sonnet }, { newRange: [20, 27], summary: Worth checking the score floor — could mask edge cases., rationale: The scoring thresholds (4, 3, 2, 1) look good but validate that zero-score items are properly filtered out., author: prism } ] }, { path: src/index.ts, summary: Keeps the preview intentionally short., annotations: [ { newRange: [1, 8], summary: The preview now shows only the top three ranked commands., rationale: Once ranking is reliable, the preview can stay compact and let the best results carry the review without flooding the UI., author: prism } ] }, { path: test/search.demo.ts, summary: Locks in normalized query handling and result ordering., annotations: [ { newRange: [1, 8], summary: The test covers a dashed query form so the new normalization helper has a visible behavioral contract., rationale: Without a test that exercises short-cuts specifically, it would be easy to regress the helper and still pass on simpler substring-only cases., author: sonnet } ] } ] }注意该示例刻意保持紧凑一个 changeset 级summary、每个文件一行summary、每条注解只保留提升审查价值的rationale不堆砌无关说明。这正是官方文档强调的原则——Keep it concise: one changeset summary, short file summaries, and only rationale that improves the review。sidecar 的结构与字段规范侧车是单个 JSON 对象由SidecarContextpackages/hunk/src/core/changeset/model.ts与公开扩展契约AgentFileContext/AgentAnnotationpackages/hunk/src/extension-api/types.ts共同定义interface SidecarContext { version: number; // 顶层版本号缺省按 1 处理 summary?: string; // 一个 changeset 级总结 files: AgentFileContext[]; } interface AgentFileContext { path: string; // 必填非空仓库根相对路径 summary?: string; // 该文件的短总结 annotations: AgentAnnotation[]; // 挂在该文件上的注解列表 } interface AgentAnnotation { id?: string; oldRange?: [number, number]; // 旧文件侧行号区间1-based newRange?: [number, number]; // 新文件侧行号区间1-based summary: string; // 必填注解标题/摘要 rationale?: string; // 审查推理说明为什么这么改 markup?: string; // 可选 STML 富文本正文实验特性 tags?: string[]; confidence?: low | medium | high; source?: string; title?: string; author?: string; createdAt?: string; updatedAt?: string; editable?: boolean; }加载时的校验与归一化源码级sidecar.ts的normalizeAnnotation与normalizeAnnotationFile承担了严格的输入校验理解这些规则有助于你写出不会触发错误的侧车summary必填每条注解必须带非空summary否则抛出Each agent annotation requires a summary.每个文件条目必须带非空path否则抛出Agent context file entries require a non-empty path.行号区间校验normalizeRangenewRange/oldRange必须是长度为 2 的整数元组行号必须是正的 1-based整数start 1或end 1即报错且必须有序end start报错confidence白名单只接受low | medium | high三个值之一其余值被丢弃为undefined不会把不可信输入放行可选字段宽容处理id、rationale、author、createdAt等任意类型值都会被规约为字符串或undefinedtags只保留其中的字符串元素顶层必须是对象非对象 JSON 会抛出Agent context must be a JSON object.version宽松顶层version只要数值类型就保留否则按 1 处理。文件匹配与重命名处理findSidecarFileContext(sidecar, currentPath, previousPath)决定了侧车注解如何落到 diff 文件上先按当前路径匹配重命名文件再回退到previousPath。也就是说针对 rename 变更你可以在侧车里只写新的path加载器会自动在旧路径上找到它。叙述性文件顺序packages/hunk/src/core/changeset/loaders.ts中的orderDiffFiles实现了叙述性文件顺序当侧车提供了files列表时审查流的文件顺序会跟随侧车中的排列次序而非 VCS 默认输出顺序。实现细节是为侧车中每个path建立 rank首次出现位置diff 文件按min(自身 rank, previousPath 的 rank)升序排序未在侧车中出现的文件排在最后并保持原有相对次序。这让 Agent 可以设计先看核心改动、再看配套测试的叙述节奏。变更集级 summary 的传递buildChangesetFromDiffFiles等构造点会把sidecar.summary写入changeset.agentSummary区别于 VCS 生成的summary供审查界面在变更集层面展示 Agent 视角的总结。可见 UI 的优先级hunk 注解优先于通用解释卡片原文档明确指出The visible UI prioritizes hunk notes rather than generic explainer cards. 侧车注解在渲染时被定位为挂在具体 hunk/行区间上的注释与 Agent 在会话中写的评论走同一套 note 渲染管线packages/hunk/src/ui/lib/agentNoteGeometry.ts负责注解与 diff 行的几何映射。这意味着带newRange/oldRange的注解会锚定到具体代码行跟随 hunk 滚动与展开通用性解释泛泛的这段代码做了 X卡片优先级低Hunk 界面优先展示锚定到代码的 hunk 注解因此编写侧车时应尽量让每条注解落在一个精确的行区间上而非仅提供文件级或变更集级的泛泛说明。实验性 STML终端原生富文本注解STMLterminal markup是 Hunk 实验性的终端富文本标记语言用于渲染 Agent 注解正文——boxes、rows、badges、gauges、lists、code blocks 等真正的终端 UI而不是纯文本。其定位是HTML-like markup rendered as real terminal UI inside agent notes见packages/hunk/src/ui/lib/stml/guide.ts的STML_GUIDE。默认关闭启动标志是权威STML默认关闭。启用方式是在启动审查时携带实验标志hunk --experimental diff --agent-context notes.json关键语义务必理解否则容易踩坑启动标志是一次性权威--experimental属于 launch-scoped会话启动范围开关一次 reload 无法事后把该能力打开。原文档原话The launch flag is the authority for that session; a reload cannot turn the capability on later. 从源码看packages/hunk/src/core/run/experimental.ts的resolveExperimentalFeatures只在options.experimental为真时返回[stml]且该标志在packages/hunk/src/app/cli.ts中被描述为 enable experimental review features (currently STML)——能力集合在启动时就被锁定纯文本summary仍是必需回退即使启用 STML每条注解的summary字段依然必须存在。当会话未启用 STML 时resolveExperimentalDiffFiles会逐条删除注解的markup字段保留summary/rationale文本作为渲染回退见packages/hunk/src/core/run/experimental.ts。换句话说markup是可选增强summary是永不失效的底线未启用 STML 的会话还会拒绝实时 markup 评论guide 中写道 otherwise Hunk uses the required plain-text summary fallback and rejects live markup comments。发送标记前的三步检查原文档给出了 Agent 在发送任何--markup之前必须执行的三步探测流程hunk session context --repo . --json hunk markup guide hunk markup render - --width reported-noteMarkupWidthhunk session context --repo . --json查询当前仓库的活动会话以 JSON 返回上下文。你需要检查其中的experimentalFeatures是否包含stml——只有包含时才允许发送--markup。该命令在packages/hunk/src/session/agent/surface.ts中定义为 show the selected file and hunk for one live Hunk session支持--repo path选择器与--json输出hunk markup guide打印 STML 创作指南即STML_GUIDE常量这是 Agent 编写标记时的权威教学材料。packages/hunk/src/app/cli.ts将其注册为markup-guide命令synopsis:hunk markup guidehunk markup render - --width reported-noteMarkupWidth用会话报告的实际宽度对标记做离线渲染预览。--width取自session context报告的noteMarkupWidth与实时评论响应的markupWidth一致。guide 强调统一布局unified≈ 全屏宽分屏布局split≈ 半宽所以预览宽度必须跟随当前会话布局。hunk markup render的完整形态来自packages/hunk/src/app/cli.tshunk markup render (file | -) [--width n] [--color auto|always|never] [--theme id] [--json]输入为文件路径或-stdin--width默认 56 列参考宽度支持positiveInt解析Design for ~56 cols — it holds up wider--color控制 ANSI 颜色输出策略--theme指定主题--json输出结构化结果。渲染器的两条实现路径packages/hunk/src/ui/lib/stml/render.ts分别是renderStmlToAnsi彩色终端渲染与renderStmlToText纯文本渲染用于无颜色环境。坏标记会优雅降级而不是崩溃并在评论响应和markup render的 stderr 上给出 render notes按提示修复即可。STML 词汇表标签、属性与颜色下面完整列出hunk markup guide所定义的 STML 词汇与packages/hunk/src/core/review/stml.ts的角色映射一一对应块级标签Blockbox card section col row·text p·h1 h2 h3·list ul ol item·hr·spacer·code pre行内标签Inlineb i u s dim·c/color·kbd·badge·a·br常用属性标签属性box/cardborder、border-stylesingle/rounded/double/heavy、border-color、title、title-color、bg、padding/padding-x/padding-y、width单元格数或百分比rowgaplistmarkerspacersizecodetitle颜色取值优先使用主题令牌theme tokens——accent success warning danger info muted subtle heading——它们跟随用户当前主题自动适配是符号化、与主题无关的推荐写法此外支持 ANSI 颜色名与#hex十六进制。官方反复强调 Keep colors symbolic不要把具体颜色写死否则换主题后注解会失去可读性。实体Entitiesrarr;→→、check;→✓、amp;→。关于角色而非标签名的设计stml.ts将标签解析为角色role例如b/strong都归一为strongbox/col/column/stack/section都归一为containerhr/rule/divider都归一为divider。渲染器只 switch 角色而非标签名这样新标签在注册一次后即可被所有渲染面终端、浏览器等理解未知标签则在所有地方都被视为未知杜绝一个渲染器认识、另一个不认识的漂移设计背景见docs/browser-review-seam-audit.md。语法示例直接可用的 STML 片段以下片段均来自hunk markup guidepackages/hunk/src/ui/lib/stml/guide.tsguide.test.ts会逐个验证这些 stml 代码块在参考宽度下可被渲染器接受因此它们永远不会与渲染器能力脱节行内样式组合textbadge colorsuccesslabel/badge bbold/b iitalic/i dimdim/dim/text带边框的分组box border border-coloraccent padding-x1 titlegroup grouped detail /box响应式并列区域row gap2 box border titleleftfirst region/box box border titlerightsecond region/box /row彩色字形进度条没有专门的 chart 标签用块字符加颜色 span 实现textc fgsuccess████████████/cc fgsubtle░░░░░░░░/c 60%/text带连接符的流程行br/让箭头在垂直方向居中row gap1 box borderfirstbr/dimdetail/dim/box text width3br/ rarr;/text box bordersecondbr/dimdetail/dim/box /row列表结构list itemfirst item/item itemsecond item/item /list固定宽度列row gap1 box width12dimlabel/dimbr/dimstatus/dim/box boxvaluebr/ready/box /row等宽代码块verbatim裁剪不换行code titleoutput const value compute(); /code键盘键帽textkbd key /kbd/textSTML 正文的三个注入来源除 sidecar 的annotations[].markup外同一套标记词汇还用于另外两个入口guide 中并列列出hunk session comment add ... --markup textformatted note body/text实时会话评论直接携带标记正文评论应用项中的{ markup: ..., ... }字段。三个来源共享同一渲染管线保证注解正文在不同入口下表现一致。编写高质量侧车与标记的实践准则综合原文档与源码可归纳出以下可操作的准则保持紧凑一个 changesetsummary、每个文件一条短summary、每条注解只保留能改进审查的 rationale。信息密度优先不要堆砌。让注解落点精确优先提供newRange/oldRange行区间使注解锚定到具体 hunk 而非泛化卡片。顺序即叙事利用files数组顺序控制审查流叙述节奏核心实现 - 配套测试。summary 永远在场即便写 STML 标记summary纯文本也必须保留——它是未启用实验特性会话的唯一回退。先探测再发送session context --json确认experimentalFeatures含stml用报告的noteMarkupWidth预览后再发--markup。颜色符号化、布局紧凑用主题令牌而非硬编码颜色STML 负责让注解比纯文本更清晰的内部层次Hunk 已提供外层框架、作者与来源位置不要在正文里重复包裹整体外框。为 ~56 列设计统一/分屏布局宽度不同按参考宽度排版可在更宽时依然成立用户随时可能调整布局。相关阅读与验证路径官方文档原稿docs/agents/agent-context-and-stml.md侧车加载与校验实现packages/hunk/src/core/changeset/sidecar.ts侧车匹配与文件排序packages/hunk/src/core/changeset/loaders.ts公开类型契约AgentAnnotation/AgentFileContextpackages/hunk/src/extension-api/types.ts实验特性解析与回退逻辑packages/hunk/src/core/run/experimental.tsSTML 角色词汇与解析packages/hunk/src/core/review/stml.tsSTML 创作指南hunk markup guide输出源packages/hunk/src/ui/lib/stml/guide.tsmarkup render/markup guideCLI 定义packages/hunk/src/app/cli.ts完整侧车示例examples/3-agent-review-demo/agent-context.json 与配套补丁 examples/3-agent-review-demo/change.patch对照这些路径阅读可以进一步验证本文涉及的所有命令、字段与回退行为并基于examples/3-agent-review-demo的完整示例搭建你自己的第一个 Agent 侧车工作流。赞分享开发工具代码评审CLIAI 应用【免费下载链接】hunkReview-first terminal diff viewer for agentic coders项目地址https://gitcode.com/gh_mirrors/hu/hunk点击查看免费下载相关推荐Hunk Agent 笔记标记语言 STML在终端内渲染结构化工单评注的完整实践指南Hunk Agent 笔记标记语言 STML在终端内渲染结构化工单评注的完整实践指南 Hunk 是一个面向 agentic 编程场景的 Review fir开发工具代码评审CLIAI 应用knowledge-work-pluginsZoom Video SDK Flutter 自定义视频会话的六阶段生命周期工作流knowledge work pluginsZoom Video SDK Flutter 自定义视频会话的六阶段生命周期工作流 本文基于 knowledge开发工具代码评审CLIAI 应用Hunk Review Triage 扩展实战为 Agent 代码审查构建会话级 Hunk 分诊面板Hunk Review Triage 扩展实战为 Agent 代码审查构建会话级 Hunk 分诊面板 导读 review triage 是 Hunk 官方示例开发工具代码评审CLIAI 应用上一篇猫抓 Cat-Catch 浏览器资源嗅探扩展完整指南三步安装捕获网页视频并解析 M3U8 流下一篇fp-ts Jest函数式代码测试的匹配器与最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hunk Agent Context 指南：用 JSON 侧车注解与实验性 STML 终端标记为代码审查注入结构化 Agent 推理
开发工具代码评审CLIAI 应用【免费下载链接】hunkReview-first terminal diff viewer for agentic coders项目地址https://gitcode.com/gh_mirrors/hu/hunk点击查看免费下载导读HunkReview-first terminal diff viewer for agentic coders为 Agent 驱动的代码审查提供了两条注入审查推理的通道一条是实时会话评论live session commentsAgent 边看边写另一条是JSON 侧车文件agent-context sidecar注解随 diff/patch 一起提交或预先存在。本文以 Hunk 官方文档website/src/content/docs/docs/agents/agent-context-and-stml.md为主体结合仓库源码packages/hunk/src/core/changeset/sidecar.ts、packages/hunk/src/ui/lib/stml/等与真实示例examples/3-agent-review-demo/agent-context.json完整讲解侧车文件的字段规范、加载命令、叙述性文件排序以及实验性 STML 终端富文本标记的启用、预览与词汇表帮助你为 Agent 与 Hunk 的协作设计出既紧凑又信息密度高的审查输入。为什么需要 sidecar与实时评论的工作流分工Hunk 将实时会话评论视为推荐工作流会话进行中Agent 可以针对正在浏览的 hunk 直接追加注释形成边看边审的交互体验。但有两种场景下实时评论并不适用这正是侧车文件的用武之地注解在 Hunk 启动前就已存在——例如上一个 Agent 会话或其他审查工具已经产出了完整结论需要原样灌入本次审查注解需要随 patch 一起旅行——你拿到一份change.patch和配套的agent-context.json希望在任何环境、任何时间复现同样的审查上下文。从源码结构看侧车加载是可选增强而非强制输入packages/hunk/src/core/changeset/sidecar.ts中的loadSidecarContext在未提供路径时直接返回null整个加载管线对此完全容错packages/hunk/src/core/changeset/loaders.ts中loadChangesetInput只有在input.options.agentContext存在时才调用加载器。也就是说带不带侧车都能正常审查带上侧车则是加分项。加载 JSON 侧车两条入口命令原文档给出的核心命令如下两条路径覆盖了最常见的两种审查输入形态hunk diff --agent-context notes.json hunk patch change.patch --agent-context notes.jsonhunk diff --agent-context notes.json对工作区/指定范围生成 diff 审查同时把notes.json的注解挂载到对应文件与 hunk 上hunk patch change.patch --agent-context notes.json直接审查一份 patch 文件侧车注解随之带入。除了文件路径--agent-context还支持从标准输入读取在loadSidecarContext中pathOrDash -时会将 stdin 整体读入再JSON.parse因此你可以用hunk diff --agent-context -配合管道把 Agent 生成的 JSON 直接喂给 Hunk而无需落地临时文件。此外该标志的定义位于packages/hunk/src/session/agent/surface.ts的AUXILIARY_AGENT_OPTIONS.agentContext--agent-context path描述为 JSON sidecar with agent rationale由packages/hunk/src/app/cli.ts注册到实际 CLI 解析器属于 Agent 会话命令面与 CLI 共享的稳定标志。一份真实可用的完整示例仓库中的examples/3-agent-review-demo/agent-context.json是一份经过校验的紧凑示例配套的examples/3-agent-review-demo/change.patch是对应的代码变更完整内容如下{ version: 1, summary: Improves command-palette matching by normalizing query text and ranking stronger matches ahead of loose substring hits., files: [ { path: src/normalize.ts, summary: Centralizes query cleanup before any matching happens., annotations: [ { newRange: [1, 3], summary: Adds one normalization helper for whitespace, case, and dashed shortcut terms., rationale: This lets the search layer reason about one normalized token shape instead of repeating slightly different cleanup logic in multiple places., author: sonnet } ] }, { path: src/search.ts, summary: Scores and sorts matches instead of returning the first loose substring list., annotations: [ { newRange: [15, 35], summary: Prefix and exact keyword matches now outrank weaker substring hits before the result list is sorted., rationale: The old behavior made every match look equally good, which was fine for filtering but weak for command-palette ranking where the top result should usually be the most obvious intent., author: sonnet }, { newRange: [20, 27], summary: Worth checking the score floor — could mask edge cases., rationale: The scoring thresholds (4, 3, 2, 1) look good but validate that zero-score items are properly filtered out., author: prism } ] }, { path: src/index.ts, summary: Keeps the preview intentionally short., annotations: [ { newRange: [1, 8], summary: The preview now shows only the top three ranked commands., rationale: Once ranking is reliable, the preview can stay compact and let the best results carry the review without flooding the UI., author: prism } ] }, { path: test/search.demo.ts, summary: Locks in normalized query handling and result ordering., annotations: [ { newRange: [1, 8], summary: The test covers a dashed query form so the new normalization helper has a visible behavioral contract., rationale: Without a test that exercises short-cuts specifically, it would be easy to regress the helper and still pass on simpler substring-only cases., author: sonnet } ] } ] }注意该示例刻意保持紧凑一个 changeset 级summary、每个文件一行summary、每条注解只保留提升审查价值的rationale不堆砌无关说明。这正是官方文档强调的原则——Keep it concise: one changeset summary, short file summaries, and only rationale that improves the review。sidecar 的结构与字段规范侧车是单个 JSON 对象由SidecarContextpackages/hunk/src/core/changeset/model.ts与公开扩展契约AgentFileContext/AgentAnnotationpackages/hunk/src/extension-api/types.ts共同定义interface SidecarContext { version: number; // 顶层版本号缺省按 1 处理 summary?: string; // 一个 changeset 级总结 files: AgentFileContext[]; } interface AgentFileContext { path: string; // 必填非空仓库根相对路径 summary?: string; // 该文件的短总结 annotations: AgentAnnotation[]; // 挂在该文件上的注解列表 } interface AgentAnnotation { id?: string; oldRange?: [number, number]; // 旧文件侧行号区间1-based newRange?: [number, number]; // 新文件侧行号区间1-based summary: string; // 必填注解标题/摘要 rationale?: string; // 审查推理说明为什么这么改 markup?: string; // 可选 STML 富文本正文实验特性 tags?: string[]; confidence?: low | medium | high; source?: string; title?: string; author?: string; createdAt?: string; updatedAt?: string; editable?: boolean; }加载时的校验与归一化源码级sidecar.ts的normalizeAnnotation与normalizeAnnotationFile承担了严格的输入校验理解这些规则有助于你写出不会触发错误的侧车summary必填每条注解必须带非空summary否则抛出Each agent annotation requires a summary.每个文件条目必须带非空path否则抛出Agent context file entries require a non-empty path.行号区间校验normalizeRangenewRange/oldRange必须是长度为 2 的整数元组行号必须是正的 1-based整数start 1或end 1即报错且必须有序end start报错confidence白名单只接受low | medium | high三个值之一其余值被丢弃为undefined不会把不可信输入放行可选字段宽容处理id、rationale、author、createdAt等任意类型值都会被规约为字符串或undefinedtags只保留其中的字符串元素顶层必须是对象非对象 JSON 会抛出Agent context must be a JSON object.version宽松顶层version只要数值类型就保留否则按 1 处理。文件匹配与重命名处理findSidecarFileContext(sidecar, currentPath, previousPath)决定了侧车注解如何落到 diff 文件上先按当前路径匹配重命名文件再回退到previousPath。也就是说针对 rename 变更你可以在侧车里只写新的path加载器会自动在旧路径上找到它。叙述性文件顺序packages/hunk/src/core/changeset/loaders.ts中的orderDiffFiles实现了叙述性文件顺序当侧车提供了files列表时审查流的文件顺序会跟随侧车中的排列次序而非 VCS 默认输出顺序。实现细节是为侧车中每个path建立 rank首次出现位置diff 文件按min(自身 rank, previousPath 的 rank)升序排序未在侧车中出现的文件排在最后并保持原有相对次序。这让 Agent 可以设计先看核心改动、再看配套测试的叙述节奏。变更集级 summary 的传递buildChangesetFromDiffFiles等构造点会把sidecar.summary写入changeset.agentSummary区别于 VCS 生成的summary供审查界面在变更集层面展示 Agent 视角的总结。可见 UI 的优先级hunk 注解优先于通用解释卡片原文档明确指出The visible UI prioritizes hunk notes rather than generic explainer cards. 侧车注解在渲染时被定位为挂在具体 hunk/行区间上的注释与 Agent 在会话中写的评论走同一套 note 渲染管线packages/hunk/src/ui/lib/agentNoteGeometry.ts负责注解与 diff 行的几何映射。这意味着带newRange/oldRange的注解会锚定到具体代码行跟随 hunk 滚动与展开通用性解释泛泛的这段代码做了 X卡片优先级低Hunk 界面优先展示锚定到代码的 hunk 注解因此编写侧车时应尽量让每条注解落在一个精确的行区间上而非仅提供文件级或变更集级的泛泛说明。实验性 STML终端原生富文本注解STMLterminal markup是 Hunk 实验性的终端富文本标记语言用于渲染 Agent 注解正文——boxes、rows、badges、gauges、lists、code blocks 等真正的终端 UI而不是纯文本。其定位是HTML-like markup rendered as real terminal UI inside agent notes见packages/hunk/src/ui/lib/stml/guide.ts的STML_GUIDE。默认关闭启动标志是权威STML默认关闭。启用方式是在启动审查时携带实验标志hunk --experimental diff --agent-context notes.json关键语义务必理解否则容易踩坑启动标志是一次性权威--experimental属于 launch-scoped会话启动范围开关一次 reload 无法事后把该能力打开。原文档原话The launch flag is the authority for that session; a reload cannot turn the capability on later. 从源码看packages/hunk/src/core/run/experimental.ts的resolveExperimentalFeatures只在options.experimental为真时返回[stml]且该标志在packages/hunk/src/app/cli.ts中被描述为 enable experimental review features (currently STML)——能力集合在启动时就被锁定纯文本summary仍是必需回退即使启用 STML每条注解的summary字段依然必须存在。当会话未启用 STML 时resolveExperimentalDiffFiles会逐条删除注解的markup字段保留summary/rationale文本作为渲染回退见packages/hunk/src/core/run/experimental.ts。换句话说markup是可选增强summary是永不失效的底线未启用 STML 的会话还会拒绝实时 markup 评论guide 中写道 otherwise Hunk uses the required plain-text summary fallback and rejects live markup comments。发送标记前的三步检查原文档给出了 Agent 在发送任何--markup之前必须执行的三步探测流程hunk session context --repo . --json hunk markup guide hunk markup render - --width reported-noteMarkupWidthhunk session context --repo . --json查询当前仓库的活动会话以 JSON 返回上下文。你需要检查其中的experimentalFeatures是否包含stml——只有包含时才允许发送--markup。该命令在packages/hunk/src/session/agent/surface.ts中定义为 show the selected file and hunk for one live Hunk session支持--repo path选择器与--json输出hunk markup guide打印 STML 创作指南即STML_GUIDE常量这是 Agent 编写标记时的权威教学材料。packages/hunk/src/app/cli.ts将其注册为markup-guide命令synopsis:hunk markup guidehunk markup render - --width reported-noteMarkupWidth用会话报告的实际宽度对标记做离线渲染预览。--width取自session context报告的noteMarkupWidth与实时评论响应的markupWidth一致。guide 强调统一布局unified≈ 全屏宽分屏布局split≈ 半宽所以预览宽度必须跟随当前会话布局。hunk markup render的完整形态来自packages/hunk/src/app/cli.tshunk markup render (file | -) [--width n] [--color auto|always|never] [--theme id] [--json]输入为文件路径或-stdin--width默认 56 列参考宽度支持positiveInt解析Design for ~56 cols — it holds up wider--color控制 ANSI 颜色输出策略--theme指定主题--json输出结构化结果。渲染器的两条实现路径packages/hunk/src/ui/lib/stml/render.ts分别是renderStmlToAnsi彩色终端渲染与renderStmlToText纯文本渲染用于无颜色环境。坏标记会优雅降级而不是崩溃并在评论响应和markup render的 stderr 上给出 render notes按提示修复即可。STML 词汇表标签、属性与颜色下面完整列出hunk markup guide所定义的 STML 词汇与packages/hunk/src/core/review/stml.ts的角色映射一一对应块级标签Blockbox card section col row·text p·h1 h2 h3·list ul ol item·hr·spacer·code pre行内标签Inlineb i u s dim·c/color·kbd·badge·a·br常用属性标签属性box/cardborder、border-stylesingle/rounded/double/heavy、border-color、title、title-color、bg、padding/padding-x/padding-y、width单元格数或百分比rowgaplistmarkerspacersizecodetitle颜色取值优先使用主题令牌theme tokens——accent success warning danger info muted subtle heading——它们跟随用户当前主题自动适配是符号化、与主题无关的推荐写法此外支持 ANSI 颜色名与#hex十六进制。官方反复强调 Keep colors symbolic不要把具体颜色写死否则换主题后注解会失去可读性。实体Entitiesrarr;→→、check;→✓、amp;→。关于角色而非标签名的设计stml.ts将标签解析为角色role例如b/strong都归一为strongbox/col/column/stack/section都归一为containerhr/rule/divider都归一为divider。渲染器只 switch 角色而非标签名这样新标签在注册一次后即可被所有渲染面终端、浏览器等理解未知标签则在所有地方都被视为未知杜绝一个渲染器认识、另一个不认识的漂移设计背景见docs/browser-review-seam-audit.md。语法示例直接可用的 STML 片段以下片段均来自hunk markup guidepackages/hunk/src/ui/lib/stml/guide.tsguide.test.ts会逐个验证这些 stml 代码块在参考宽度下可被渲染器接受因此它们永远不会与渲染器能力脱节行内样式组合textbadge colorsuccesslabel/badge bbold/b iitalic/i dimdim/dim/text带边框的分组box border border-coloraccent padding-x1 titlegroup grouped detail /box响应式并列区域row gap2 box border titleleftfirst region/box box border titlerightsecond region/box /row彩色字形进度条没有专门的 chart 标签用块字符加颜色 span 实现textc fgsuccess████████████/cc fgsubtle░░░░░░░░/c 60%/text带连接符的流程行br/让箭头在垂直方向居中row gap1 box borderfirstbr/dimdetail/dim/box text width3br/ rarr;/text box bordersecondbr/dimdetail/dim/box /row列表结构list itemfirst item/item itemsecond item/item /list固定宽度列row gap1 box width12dimlabel/dimbr/dimstatus/dim/box boxvaluebr/ready/box /row等宽代码块verbatim裁剪不换行code titleoutput const value compute(); /code键盘键帽textkbd key /kbd/textSTML 正文的三个注入来源除 sidecar 的annotations[].markup外同一套标记词汇还用于另外两个入口guide 中并列列出hunk session comment add ... --markup textformatted note body/text实时会话评论直接携带标记正文评论应用项中的{ markup: ..., ... }字段。三个来源共享同一渲染管线保证注解正文在不同入口下表现一致。编写高质量侧车与标记的实践准则综合原文档与源码可归纳出以下可操作的准则保持紧凑一个 changesetsummary、每个文件一条短summary、每条注解只保留能改进审查的 rationale。信息密度优先不要堆砌。让注解落点精确优先提供newRange/oldRange行区间使注解锚定到具体 hunk 而非泛化卡片。顺序即叙事利用files数组顺序控制审查流叙述节奏核心实现 - 配套测试。summary 永远在场即便写 STML 标记summary纯文本也必须保留——它是未启用实验特性会话的唯一回退。先探测再发送session context --json确认experimentalFeatures含stml用报告的noteMarkupWidth预览后再发--markup。颜色符号化、布局紧凑用主题令牌而非硬编码颜色STML 负责让注解比纯文本更清晰的内部层次Hunk 已提供外层框架、作者与来源位置不要在正文里重复包裹整体外框。为 ~56 列设计统一/分屏布局宽度不同按参考宽度排版可在更宽时依然成立用户随时可能调整布局。相关阅读与验证路径官方文档原稿docs/agents/agent-context-and-stml.md侧车加载与校验实现packages/hunk/src/core/changeset/sidecar.ts侧车匹配与文件排序packages/hunk/src/core/changeset/loaders.ts公开类型契约AgentAnnotation/AgentFileContextpackages/hunk/src/extension-api/types.ts实验特性解析与回退逻辑packages/hunk/src/core/run/experimental.tsSTML 角色词汇与解析packages/hunk/src/core/review/stml.tsSTML 创作指南hunk markup guide输出源packages/hunk/src/ui/lib/stml/guide.tsmarkup render/markup guideCLI 定义packages/hunk/src/app/cli.ts完整侧车示例examples/3-agent-review-demo/agent-context.json 与配套补丁 examples/3-agent-review-demo/change.patch对照这些路径阅读可以进一步验证本文涉及的所有命令、字段与回退行为并基于examples/3-agent-review-demo的完整示例搭建你自己的第一个 Agent 侧车工作流。赞分享开发工具代码评审CLIAI 应用【免费下载链接】hunkReview-first terminal diff viewer for agentic coders项目地址https://gitcode.com/gh_mirrors/hu/hunk点击查看免费下载相关推荐Hunk Agent 笔记标记语言 STML在终端内渲染结构化工单评注的完整实践指南Hunk Agent 笔记标记语言 STML在终端内渲染结构化工单评注的完整实践指南 Hunk 是一个面向 agentic 编程场景的 Review fir开发工具代码评审CLIAI 应用knowledge-work-pluginsZoom Video SDK Flutter 自定义视频会话的六阶段生命周期工作流knowledge work pluginsZoom Video SDK Flutter 自定义视频会话的六阶段生命周期工作流 本文基于 knowledge开发工具代码评审CLIAI 应用Hunk Review Triage 扩展实战为 Agent 代码审查构建会话级 Hunk 分诊面板Hunk Review Triage 扩展实战为 Agent 代码审查构建会话级 Hunk 分诊面板 导读 review triage 是 Hunk 官方示例开发工具代码评审CLIAI 应用上一篇猫抓 Cat-Catch 浏览器资源嗅探扩展完整指南三步安装捕获网页视频并解析 M3U8 流下一篇fp-ts Jest函数式代码测试的匹配器与最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考