Hunk 快速上手：用 `hunk diff --files` 对比两个 TypeScript 文件并完成首次 Review

开发工具代码评审CLIAI 应用【免费下载链接】hunkReview-first terminal diff viewer for agentic coders项目地址https://gitcode.com/gh_mirrors/hu/hunk点击查看免费下载本篇技术指南围绕 Hunk 仓库中最小可运行的入门示例examples/1-hello-diff展开完整讲解 HunkReview-first 终端 diff 查看器最直接的用法——hunk diff --files left right命令如何脱离 Git 工作区、直接对比两个具体文件并手把手带你读懂示例中重命名、助手函数提取与行内文案变化三类典型 diff 特征。读完本文你将掌握 Hunk 直接文件对比模式的命令语义、参数边界、键盘导航与可验证的源码依据并能在自己的项目里立刻复现同样的 Review 流程。示例概览一个干净的 TypeScript diffexamples/1-hello-diff是整个 examples 目录中最小、最快的首次运行演示它在 README.md 中对自己的定位是A tiny first-run demo with one clean TypeScript diff.它的全部输入只有两个文件不涉及 Git 提交、补丁文件或 agent 上下文非常适合用来验证 Hunk 安装是否成功、终端渲染是否符合预期以及快速熟悉 diff 查看器的交互节奏。示例目录结构为before.ts修改前的版本定义了WelcomeUser类型与两个导出函数after.ts修改后的版本重命名了类型与参数、抽取了助手函数并改写文案README.md运行说明与观察要点examples/README.md的示例快速索引表也将它标注为 fastest first run最快首次运行是整个示例集中最适合作为第一个体验入口的演示。运行命令直接对比两个具体文件在仓库根目录执行hunk diff --files examples/1-hello-diff/before.ts examples/1-hello-diff/after.ts该命令会打开 Hunk 的终端 Review 界面将before.ts视为左侧旧版本、after.ts视为右侧新版本进行渲染。由于不涉及任何版本控制后端这是 Hunk 中最轻量、零依赖的 diff 输入方式。--files的精确语义源码依据--files并非一个普通的路径参数而是 Hunk CLI 中专门为对比恰好两个具体文件设计的模式。在 packages/hunk/src/app/cli.ts 中DIFF_OPTIONS对它的定义是flag: --files paths... description: compare exactly two concrete files: --files left right同时在hunk diff命令的 synopsispackages/hunk/src/app/cli.ts中--files left right与hunk diff [target]、hunk diff from to、hunk diff --staged并列构成四种输入形态之一。CLI 参考说明还特意强调了一个容易踩坑的细节Two positional arguments always name revision endpoints, even when matching files exist on disk. Use--files left rightfor concrete-file comparison; this replaces the former filesystem-existence disambiguation.即不带--files时两个位置参数永远被解释为 revision 端点即使磁盘上存在同名文件只有显式传入--files才会进入直接文件对比分支。这一点在 packages/hunk/src/app/cli.test.ts 中有专门测试验证hunk diff left right会被解析为rangeEndpoints: { from, to }revision 语义而带--files时才会解析为kind: diff加left/right字段。参数边界与报错行为--files对参数数量有严格约束。在 packages/hunk/src/app/cli.test.ts 中以下畸形组合都会被拒绝并抛出 exactly two file paths 错误hunk diff --files one # 只传一个文件 hunk diff --files one two three # 传了三个文件 hunk diff --files one two --staged # 混入 --staged文件对比模式下无意义 hunk diff target --files one two # 同时给了 target 位置参数这说明--files必须独占地接收恰好两个路径不能与其他 diff 输入形态混用。与之配套packages/hunk/src/app/cli.ts 也给出了完整的使用提示Usehunk diff [target] ...,hunk diff from to, orhunk diff --files left rightfor file comparison.在仓库内外的行为差异--files模式同样支持--watch自动刷新见下文。从 packages/hunk/src/app/session/reloadBounds.ts 的注释可以确认它的刷新边界语义在仓库内执行hunk diff --files fileA fileB刷新范围以仓库根为界仓库外的文件变化不会触发重载在仓库外执行刷新范围就是初始的两个文件本身其他文件以及所有仓库型重载都不会参与。逐行读懂示例 diff三类典型变化示例刻意设计成一眼能看出的典型重构模式。对照两个文件可以完整还原这次变更的动机与内容。1. 类型与函数参数的重命名修改前核心类型名为WelcomeUser参数沿用了类型名type WelcomeUser { name: string; visits: number; plan?: free | pro; }; export function renderWelcome(user: WelcomeUser) { ... }修改后类型被更名为Viewer字段name同步改为displayName参数也随之重命名语义更聚焦于查看者而非欢迎对象type Viewer { displayName: string; visits: number; plan?: free | pro; }; export function renderWelcome(viewer: Viewer) { ... }这是 Hunk 中最常见的 diff 类型之一符号重命名。Review 时你关注的重点是改名是否在全部引用点保持一致例如user.name.trim()必须同步变为viewer.displayName.trim()以及是否遗漏了未重命名的残留。2. 小助手函数的提取修改前pro 徽标的生成逻辑内联在renderWelcome里const badge user.plan pro ? ⭐ : ;修改后它被提取为独立的私有函数welcomeBadge并顺带调整了文案与样式从 ⭐变为 · Profunction welcomeBadge(viewer: Viewer) { return viewer.plan pro ? · Pro : ; }这是第二种典型变化助手函数提取helper extraction。Review 时你需要确认提取后函数职责单一、无副作用且所有调用点此处为renderWelcome内的welcomeBadge(viewer)传参正确。3. 字符串与文案中的行内变化renderWelcome与renderFooter的返回文案均有明显改写// before Welcome back, ${displayName}${badge}. You have visited ${user.visits} times. // after Welcome back, ${name}${welcomeBadge(viewer)}. Session ${viewer.visits}.以及renderFooter中// before return user.visits 10 ? Thanks for sticking with us. : Tell us what youd like to build next.; // after return viewer.visits 10 ? Thanks for sticking with Hunk. : Tip: press ] to jump to the next hunk.;这里同时埋了第三个观察点行内intra-line字符串变化——同一行内只有局部片段被改动如 ⭐→ · Pro、visited ... times→Session ...、 10→ 10。Hunk 基于 pierre/diffs 解析补丁与文件差异这类行内细粒度变化会在高亮渲染中与整行替换明显区分是检验终端 diff 渲染质量最直观的用例。原 README.md 的 What to look for 清单恰好对应上述三类a renamed type and function parameter重命名的类型与函数参数a small helper extraction小助手函数提取obvious intra-line changes in strings and copy字符串与文案中明显的行内变化一个自指彩蛋after.ts的renderFooter在新用户提示文案中写入了 Hunk 的真实快捷键]——jump to the next hunk。这个设计让示例在视觉上既展示文案变化又隐性地预告了下一步的交互操作是理解 HunkReview-first定位的一个趣味注脚。在 Review 界面中的导航与交互打开示例 diff 后你可以在终端界面中验证以下交互均为 Hunk 内置命令移动光标浏览改动区块观察整行替换与行内局部变化在渲染上的差异按]跳转到下一个 hunk。这个键位并非硬编码的魔法数字而是注册在命令目录中的具名命令hunk.review.nextHunk默认键即]见 packages/hunk/src/core/run/commandCatalog.ts具名命令意味着它可以通过[keybindings]配置重映射例如在配置中追加hunk.review.nextHunk [], ctrln]即可让CtrlN也成为下一个 hunk 快捷键相关解析逻辑见 packages/hunk/src/core/run/config.ts 与对应测试 packages/hunk/src/core/run/config.test.ts按Esc/q退出 Review 界面回到终端。延伸一为文件对比开启--watch直接文件对比同样支持自动刷新。在 packages/hunk/src/app/cli.ts 中--watch被定义为auto-reload when the current diff input changes并作为 diff 类命令的通用选项commonReviewOptions: true, watch: true挂载。对示例而言hunk diff --files examples/1-hello-diff/before.ts examples/1-hello-diff/after.ts --watch之后任意编辑before.ts或after.ts并保存Review 界面都会自动重载为最新差异——非常适合边改边审的工作流。如前所述刷新边界由 packages/hunk/src/app/session/reloadBounds.ts 管理仓库内以仓库根为界仓库外仅监听这两个文件本身。延伸二与其他 Review 模式的组合与对比--files可以与常规 Review 选项自由组合。测试用例 packages/hunk/src/app/cli.test.ts 演示了--mode unified与--files的搭配强制使用 unified 布局hunk diff --files left right --mode unified--mode支持auto响应式自动切换 split/unified、split、unified。此外还有--no-sidebar隐藏文件面板、--agent-notes默认显示 agent 笔记等选项可供探索选项清单见 packages/hunk/src/app/cli.ts。作为参照examples 中的其他示例展示了 Hunk 输入形态的完整谱系示例输入形态命令示例1-hello-diff两个具体文件hunk diff --files ...before.ts ...after.ts2-mini-app-refactor补丁文件hunk patch examples/2-mini-app-refactor/change.patch3-agent-review-demo补丁 agent 上下文hunk patch ... --agent-context .../agent-context.json4-ui-polishTSX 文件对比hunk diff --files ...before.tsx ...after.tsx5-pager-tour文件对比 分页hunk diff --files ... --pager1-hello-diff的价值正在于它是这条谱系中最简单的一端无补丁、无仓库、无 agent 上下文一条命令即可完成首次 Review。前置条件与安装运行示例前需要先安装 Hunk。本仓库根目录提供了 install.shmacOS/Linux 安装脚本将独立二进制安装到~/.hunk同时支持npm i -g hunkdiffmacOS/Linux/Windows需 Node.js 22、Homebrewbrew install hunk与 mise 等途径详见 packages/hunk/README.md。安装完成后在仓库根目录执行文章开头的命令即可启动 Review。需要注意示例中的相对路径examples/1-hello-diff/before.ts必须以仓库根目录为当前工作目录才能正确解析你也可以换成任意两个文件的绝对路径。小结examples/1-hello-diff用最少的代码量演示了 Hunk 三条核心能力--files直接文件对比的命令语义与 revision 对比严格区分、基于具名命令的键盘导航]→hunk.review.nextHunk以及面向 agent 生成变更的 Review 观察方法论重命名、提取、行内文案三类变化。以此示例为入口配合 examples 目录中从补丁到 agent 上下文的递进示例你可以快速建立对 Hunk 完整 Review 工作流的体感。赞分享开发工具代码评审CLIAI 应用【免费下载链接】hunkReview-first terminal diff viewer for agentic coders项目地址https://gitcode.com/gh_mirrors/hu/hunk点击查看免费下载相关推荐Habitat-Lab完整指南如何快速构建你的第一个具身AI训练环境Habitat Lab完整指南如何快速构建你的第一个具身AI训练环境 Habitat Lab是Meta AI开发的 模块化高级库 专门用于 具身AI代理训练开发工具代码评审CLIAI 应用Hunk 快速上手从 hunk diff 到多文件审查流10 分钟掌握核心心智模型Hunk 快速上手从 hunk diff 到多文件审查流10 分钟掌握核心心智模型 Hunk 是一款面向 AI 智能体Agent时代打造的 review开发工具代码评审CLIAI 应用使用 hunk session 命令驱动交互式 Diff 审阅Hunk Review Agent Skill 完整实战指南使用 hunk session 命令驱动交互式 Diff 审阅Hunk Review Agent Skill 完整实战指南 在 AI 编码时代把 diffCLI后端数据库上一篇GemPy API完全手册掌握地质建模的关键函数与参数配置下一篇MAA智能升级终极指南5步实现全自动更新体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考