使用 hunk session 命令驱动交互式 Diff 审阅Hunk Review Agent Skill 完整实战指南【免费下载链接】atuin✨ Making your shell magical项目地址: https://gitcode.com/gh_mirrors/at/atuin在 AI 编码时代把 diff 审阅变成可编程流程 是 Agent 与开发者协作的关键一环。本仓库随附的 Claude 技能文件 .claude/skills/hunk/SKILL.md 定义了一套完整的「Hunk Review」技能它让 AI Agent 通过hunk session *本地守护进程命令与用户终端里正在运行的 Hunk 交互式 Diff 审阅会话进行通信——检查审阅焦点、浏览文件与 hunks、重载会话内容、批量写入内联评论。读完本文你将掌握该技能的全部命令用法、会话选择机制、JSON 批量评论协议以及如何像资深 Reviewer 一样叙述式引导一场代码审阅。技能定位一份面向 Agent 的 Hunk 审阅操作手册该技能文件位于仓库的.claude/skills/hunk/SKILL.mdfrontmatter 声明如下name: hunk-review description: Interacts with live Hunk diff review sessions via CLI. Inspects review focus, navigates files and hunks, reloads session contents, and adds inline review comments. Use when the user has a Hunk session running or wants to review diffs interactively.技能名为hunk-review其描述明确了适用场景当用户正在运行 Hunk 会话、或想要以交互方式审阅 diff 时Agent 应当通过 CLI 与活动中的 Hunk 会话交互——检查审阅焦点、在文件和 hunks 之间导航、重载会话内容、添加内联审阅评论。第一条铁律TUI 属于用户Agent 只用 CLI技能文档在开头即强调一条核心分工原则Hunk is an interactive terminal diff viewer. The TUI is for the user -- do NOT runhunk diff,hunk show, or other interactive commands directly. Usehunk session *CLI commands to inspect and control live sessions through the local daemon.也就是说Hunk 的 TUI 是给用户看的交互界面Agent绝不能直接替用户执行hunk diff、hunk show这类交互式命令——那会抢走用户的终端控制权。Agent 的正确做法是通过hunk session *系列命令经由本地守护进程local daemon去检视和控制已经存在的活动会话。如果当前没有活动的 Hunk 会话Agent 应当先请用户在终端中自行启动 Hunk而不是擅自代劳。工作流程全景一次标准审阅的九个步骤技能文档给出了 Agent 介入审阅的标准工作流九个步骤环环相扣1. hunk session list # find live sessions 2. hunk session get --repo . # inspect path / repo / source 3. hunk session review --repo . --json # inspect file/hunk structure first 4. hunk session review --repo . --include-patch --json # opt into raw diff text only when needed 5. hunk session context --repo . # check current focus when needed 6. hunk session navigate ... # move to the right place 7. hunk session reload -- command # swap contents if needed 8. hunk session comment add ... # leave one review note 9. hunk session comment apply ... # apply many agent notes in one stdin batch这条链路的设计意图非常清晰先探测list/get→ 再结构预览review --json→ 按需看补丁原文--include-patch→ 确认焦点context→ 导航navigate→ 必要时换内容reload→ 最后留评comment add/apply。其中第 3、4 步特别强调默认只取文件与 hunk 的结构只有当调用方确实需要原始 unified diff 文本时才加--include-patch——这是为了控制 Agent 的上下文开销避免把整份 diff 灌进上下文窗口。会话选择机制--repo、session-id 与自动解析多数会话命令都接受以下几种选择会话的方式方式说明适用场景--repo path按会话当前加载的仓库根目录匹配最常见普通 worktree 会话首选session-id按确切 ID 匹配多个会话共用同一仓库时缺省只有一个会话时自动解析无歧义时最省事reload命令额外支持两个参数--session-path path按 Hunk 窗口当前的工作目录匹配活动会话--source path从另一个目录加载要替换的diff/show命令。文档特别强调--source的边界它是高级用法只改变替换审阅命令的运行位置并不负责选择会话。只有在想控制的会话并未关联到你下一步要加载的 checkout这种场景下才需要它对普通 worktree 会话直接--repo /path/to/worktree选择即可不要混用。Inspect 命令先看清再动手hunk session list [--json] hunk session get (--repo . | id) [--json] hunk session context (--repo . | id) [--json] hunk session review (--repo . | id) [--json] [--include-patch]get输出会话的Path、Repo、Source三个字段——这正是判断该用--repo还是--session-path的依据Repo是--repo的匹配对象Path是--session-path的匹配对象review --json默认返回文件与 hunk 的结构信息只有当调用方确实需要原始 unified diff 文本时才追加--include-patch。技能文档的建议是先用review --json拿到结构再对真正需要精读的文件单独启用补丁原文从而把 Agent 的上下文消耗降到最低。这套结构优先、原文按需的策略与仓库中 Agent 集成普遍采用的上下文节流思路一脉相承——例如 contrib/opencode/atuin.ts 中 opencode 插件通过history start/history end记录命令并附带--intent同样是轻量记录、按需取用的设计哲学。Navigate 命令绝对定位与相对跳转绝对导航需要--file并且--hunk、--new-line、--old-line三选一必须恰好一个hunk session navigate --repo . --file src/App.tsx --hunk 2 hunk session navigate --repo . --file src/App.tsx --new-line 372 hunk session navigate --repo . --file src/App.tsx --old-line 355相对评论导航在已标注评论的 hunks 之间跳跃不需要--filehunk session navigate --repo . --next-comment hunk session navigate --repo . --prev-comment要点--hunk n从1开始计数1-based--new-line/--old-line分别是 diff 新侧、旧侧的1-based行号--next-comment与--prev-comment只能二选一不可同时使用。Reload 命令替换活动会话的内容当活动会话加载的不是你想要审阅的内容时用reload换掉它。格式为在--之后跟一条 Hunk 审阅命令hunk session reload --repo . -- diff hunk session reload --repo . -- diff main...feature -- src/ui hunk session reload --repo . -- show HEAD~1 hunk session reload --repo . -- show HEAD~1 -- README.md hunk session reload --repo /path/to/worktree -- diff hunk session reload --session-path /path/to/live-window --source /path/to/other-checkout -- diff规则与注意点--之前是reload自身的选项之后才是要嵌套执行的 Hunk 命令--分隔符必须保留通常用--repo或session-id选择目标会话--source是高级选项它不选择会话只改变替换命令的运行目录如果活动会话已经在显示目标 worktree优先hunk session reload --repo /path/to/worktree -- diff需要在会话选择与重载来源分离的场景下用--session-path锁定活动窗口。Comments 命令从单条评论到 JSON 批量写入hunk session comment add --repo . --file README.md --new-line 103 --summary Tighten this wording [--rationale ...] [--author agent] [--focus] printf %s\n {comments:[{filePath:README.md,newLine:103,summary:Tighten this wording}]} | hunk session comment apply --repo . --stdin [--focus] hunk session comment list --repo . [--file README.md] hunk session comment rm --repo . comment-id hunk session comment clear --repo . --yes [--file README.md]选择策略与约束comment add适合单条评论当 Agent 已准备好多条笔记时用一次comment apply批量提交比多次调用 shell 更优comment add必须提供--file、--summary并且--old-line/--new-line二选一comment apply的载荷项payload item需要filePath、summary以及恰好一个定位字段hunk、hunkNumber、oldLine或newLinecomment apply从stdin读取 JSON 批次并且在修改活动会话之前先校验整个批次validate the full batch before mutating——这意味着一次坏数据不会产生半途而废的写入希望跳到新评论或批次的第一个评论时传--focus--focus要克制使用只在评论本身应当主动引导审阅方向时使用comment list与comment clear都接受可选的--file过滤--summary与--rationale在 shell 中要防御性地加引号防止空格与特殊字符被拆词。新文件与 working-tree 审阅hunk diff默认会包含 untracked 文件。如果用户只关心已跟踪文件的变更可以通过 reload 排除未跟踪文件hunk session reload --repo . -- diff --exclude-untracked引导一次审阅Agent 的叙述者角色技能文档明确指出 Agent 在审阅中的角色定位Your role is to narrate: steer the users view to what matters and leave comments that explain what theyre looking at.Agent 不是替用户做决定的机器而是叙述者——把用户的视线引向关键位置用评论解释正在看的是什么、为什么重要。典型流程加载正确内容必要时先reload导航到第一个值得看的文件 / hunk添加评论说明发生了什么以及为什么若已备好多条笔记优先一次comment apply批量提交而不是多次单独 shell 调用结束时总结。文档给出的审阅准则同样值得记牢按最能讲清故事的顺序工作而不是机械地按文件顺序先导航再评论确保用户亲眼看到你正在讨论的代码Agent 生成的批量笔记用comment apply零散的单条笔记用comment add--focus要克制使用——只有当评论本身需要主动牵引审阅方向时才用评论要聚焦意图、结构、风险或后续行动intent, structure, risks, or follow-ups不要每个 hunk 都评——只指出用户自己发现不了的问题。启动一次审阅时正确的起点是hunk session review --json拿到文件/hunk 结构而不膨胀 Agent 上下文只有对真正需要原文精读的文件才启用--include-patch再用context和navigate对齐用户当前视图最后才落评论。常见错误速查表技能文档贴心整理了六类高频报错及处置方法实战中可直接对照排障报错信息含义与处置No visible diff file matches ...该文件不在当前加载的审阅内容中。先查context必要时reloadNo active Hunk sessions当前没有活动会话。请用户先在终端里打开 HunkMultiple active sessions match匹配到多个会话。显式传入session-idNo active Hunk session matches session path ...高级 split-path reload 场景下路径匹配失败。先用hunk session get或list确认活动窗口的Path再用--session-pathPass the replacement Hunk command after \--| 嵌套的diff/show命令必须放在-- 之后Pass --stdin to read batch comments from stdin JSON.comment apply只从 stdin 读取批次载荷必须传--stdinSpecify exactly one navigation target--hunk、--old-line、--new-line必须恰好选一个Specify either --next-comment or --prev-comment, not both.评论导航方向二选一在 Atuin 仓库中的生态位置Agent 技能与 Agent Hooks这份技能文件并非孤立存在它是本仓库Agent 友好化体系中的一环与仓库内其他 Agent 基础设施相互呼应Agent HooksAI 代理钩子docs/docs/guide/agent-hooks.md 详细记录了 Atuin 如何捕获 Claude Code、Codex、opencode、pi 等 AI 编码代理执行的命令并打上claude-code、codex、opencode、pi等作者标签写入历史支持atuin search --author $all-agent之类的按作者过滤——与 Hunk 技能Agent 与工具会话协作的思路同源Agent 插件实现contrib/opencode/atuin.ts 与 contrib/pi/atuin.ts 展示了仓库如何为 opencode、pi 这类扩展型 Agent 提供钩子插件通过atuin history start --author agent --author-kind agent [--intent ...]与atuin history end id --exit code在命令执行前后记录历史技能Skills机制本仓库不仅随附.claude/skills/hunk/SKILL.md这类 Claude 技能Atuin AI 自身也支持技能目录机制docs/docs/ai/skills.md 中给出的示例正是code-review技能——它声明Conducts a structured code review. Use when the user asks to review code, a PR, or a diff与本文的 Hunk 审阅技能互为补充一个负责审阅内容与策略一个负责与交互式 diff 查看器的会话打通。对于想在自己的 Agent 配置中复用该技能的开发者可将其放入 Claude Code 的 skills 目录例如本仓库的.claude/skills/hunk/SKILL.md路径结构并确保本地已安装 Hunk、且存在活动的 Hunk 会话。结语Hunk Review 技能把终端里的交互式 diff 审阅变成了一套清晰、可编程的 Agent 协议用list/get/context/review探测会话状态用navigate精确定位文件、hunk 与行用reload随时切换审阅对象用comment add/apply以单条或 JSON 批次的方式落评论并配齐了会话选择、错误排障与叙述式引导准则。掌握这套命令后Agent 可以全程旁观不打扰地伴随用户完成一场高质量的代码审阅——这正是现代 AI 编码工作流里工具、Agent 与开发者三方协作的正确姿势。【免费下载链接】atuin✨ Making your shell magical项目地址: https://gitcode.com/gh_mirrors/at/atuin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考