开发工具代码评审CLIAI 应用【免费下载链接】hunkReview-first terminal diff viewer for agentic coders项目地址https://gitcode.com/gh_mirrors/hu/hunk点击查看免费下载导读Watch mode--watch是 Hunk 面向 Agent 化编码场景提供的一项核心工作流能力它把一次性的 diff review 会话升级为对不断变化的源码输入持续跟踪、自动刷新的连续视图。本指南将围绕 watch-mode.md 的官方用法展开并结合 Hunk 仓库中packages/hunk/src/core/watch/的控制器、观察器、签名检测与 VCS 集成源码讲清哪些输入可以被监听、底层如何以事件提示 签名校验 周期轮询兜底三层机制保持同步以及r键与hunk session reload两种手动刷新方式的使用边界。读完你可以在自己的仓库里正确使用 watch mode并理解它为什么会这样工作。什么是 Watch ModeHunk 的定位是 review-first 的终端 diff 查看器见 README.md 项目描述 Review-first terminal diff viewer for agentic coderswatch mode 则是把评审一次快照升级为评审一条不断变化的流。它的核心语义可以用文档原句概括Watch mode turns a review into a continuous view of a changing source.也就是说当你用--watch启动一个 review 后Hunk 会持续观察输入的来源文件、补丁文件、仓库工作区或历史版本一旦底层内容发生变化就自动重新加载并刷新评审视图无需你手动退出重进。这在Agent 正在持续修改代码、评审者需要盯着最新差异的场景下尤其有用——工作区里的文件一边被改写diff 视图一边跟着更新。启动一个被监听的评审官方文档给出的最简启动方式是对工作区 diff 开启 watchhunk diff --watch该命令会同时观察直接文件输入与Git-backed 输入用于在内容变化时触发刷新同时保留周期轮询periodic polling作为兜底。而对 Jujutsujj与 Sapling 输入则直接使用轮询方式详见下文轮询兜底一节。除了工作区 diff所有**可重新打开reopenable**的输入都能进入 watch mode官方示例包括hunk show HEAD~1 --watch hunk diff --files before.ts after.ts --watch hunk patch changes.patch --watch这些命令的共性在于它们的输入在磁盘上有一个稳定、可重新读取的落点——一个 ref、两个具体文件路径、或一个补丁文件。在 CLI 参考实现 中--watch被定义为export const WATCH_OPTION { flag: --watch, description: auto-reload when the current diff input changes, } as const satisfies CliReferenceOption;并且diff、show、stash show、patch、difftool等 review 命令在命令规格上都声明了watch: true见 cli.ts意味着它们都共享同一个--watch标志并具备自动重载能力。哪些输入可以被监听watch mode 有一个硬性前提输入的来源必须能被 Hunk 再次打开。换句话说只有可重开的输入才谈得上持续观察一次性、流式的输入则不行。官方文档明确排除了一种典型场景——stdin 输入# Snapshot only; --watch would fail some-command | hunk patch -从源码看这条规则在 resolveWatchPlan 中实现当输入的 kind 为patch且文件参数缺失或为-stdin时直接返回null即无法构建 watch 计划case patch: if (!input.file || input.file -) { return null; } fileTargets.push({ path: input.file, source: content }); break;同理agentContext若来自 stdin-也无法被监听if (input.options.agentContext -) { return null; }为什么 stdin 不能 watch因为 Hunk 的 watch 机制需要反复读取同一输入来计算内容是否变化的签名stdin 是一次性管道读完即尽无法二次打开。文档给出的替代方案非常明确把正在变化的输出落盘到文件或者改用仓库-backed 命令如hunk diff、hunk show再对文件路径开启--watch。底层同步机制三层架构watch mode 之所以能既灵敏又省资源是因为它的同步不是单一的纯事件或纯轮询而是三层配合。对应的核心实现在 packages/hunk/src/core/watch/ 目录由controller.ts状态机控制器、observer.ts事件观察器、signature.ts签名检测三个模块构成。第一层事件提示Event HintscreateWatchController见 controller.ts维护一个明确的状态机starting → idle → debouncing → checking → refreshing → closed当观察器observer报告底层文件发生变化时控制器进入debouncing阶段——事件只被当作提示不会立即触发刷新而是先进入防抖窗口等安静下来再校验签名。控制器提供了一组可调参数源码中的默认值参数默认值作用quietDelayMs200ms防抖窗口事件安静这么久后才做一次检查maximumDelayMs1000ms事件洪泛时的最大延迟上限保证检查不会无限推迟healthyCheckMs10000ms健康状态下的兜底轮询间隔degradedCheckMs2000ms降级状态下的快速轮询间隔duplicateErrorIntervalMs10000ms同一错误在窗口内的去重上报间隔startupTimeoutMs2000ms事件源启动超时见下第二层签名校验Signature Check防抖到期后控制器调用getSignature计算当前输入的签名与上一次应用过的签名比对一致则什么都不做不一致才触发 refresh见 controller.ts。这层校验过滤了大量事件发生了但其实内容没变的噪声例如编辑器 touch 文件、无关元数据写入。签名由 computeWatchSignature 生成不同输入类型采用不同签名策略diff/difftool左右两个文件对左右文件分别取path:size:mtimeMs:ino的 stat 签名patch补丁文件对补丁文件取同样的 stat 签名vcs/show/stash-show委托给 VCS adapter 的watchSignature生成仓库态签名若带有--agent-context还会把该 sidecar 文件的 stat 签名拼进签名串。第三层周期轮询兜底Polling Fallback事件监听并不是所有输入都能提供的。在 createVcsWatchPlan 中可以看到return handler.watchPlan?.(operation.input, context) ?? { coverage: poll-only, targets: [] };即如果所选 VCS 操作的 adapter 没有实现watchPlan就回退到poll-only轮询计划。这正是文档所说的它轮询 Jujutsu 和 Sapling 输入——这两类 VCS 适配器不提供文件系统事件计划Hunk 便以轮询签名的方式来感知仓库变化。此外当事件源因资源耗尽ENOSPC、EMFILE或启动超时而降级时控制器也会把健康轮询间隔从 10s 收紧为 2s 的降级轮询保证事件不可用同步仍不中断见 controller.ts 与L311-L325。观察器原生递归与可移植树两种后端事件从哪来createWatchObserver 会按 watch 计划为每个目标构建底层 watcher并根据平台选择后端见 observer.tsmacOSdarwin与 Windows使用 Bun/Node 的原生递归 watcherfs.watchrecursive: true注册完成后即视为 readyLinux 等可移植平台使用 Chokidar 的分块树监听器createChunkedTreeWatcher见 portableTree.ts。分块树监听器的设计很讲究它按PORTABLE_TREE_BATCH_SIZE 32个目录一批地注册深度为零的 Chokidar watcher批与批之间让出 macrotask从而在遍历超大工作区时避免一次性扫完整个目录树导致的卡顿每批 watcher 会暴露独立的 ready 边界全部就绪后才向控制器报告整体 ready。目录的新增addDir会被动态登记删除unlinkDir会先注销旧批次再重新收编存活的兄弟目录。在事件进入控制器前观察器还会做一层忽略根ignored roots过滤VCS adapter 可以在 watch 计划中声明忽略的目录例如.git观察器通过createIgnoredRootMatcherobserver.ts做带缓存的祖先链判断把无关目录的写事件直接丢弃避免无谓刷新。运行前提Bun 版本要求watch mode 依赖运行时Bun的文件系统 watcher而这里有一个真实的历史坑Bun 1.3.14 之前存在 watcher 关闭时的锁反转deadlock问题。因此 runtime.ts 定义了export const MINIMUM_RELIABLE_WATCH_BUN_VERSION 1.3.14;assertReliableWatchRuntime会在旧版本上直接抛出用户可读错误提示升级 Bun 或去掉--watch。这意味着使用 watch mode 请确保 Bun ≥ 1.3.14bun upgrade可升级。手动刷新r键与hunk session reload不是所有场景都需要常驻 watch。文档给了两种按需刷新的途径1. 终端内按r键当 review 输入可重载reloadable时直接按r立即刷新无需开启持续的--watch。从测试用例看r触发的是软重载soft reloadresetApp: false保留当前选区及其稳定 id仅替换底层 review 文件对象见 AppHost.extensions.test.tsx所以刷新后你的阅读位置不会被打回原点。2. 活体 Agent 用hunk session reload如果评审会话运行在 Agent 会话场景中Agent 可以通过hunk session reload命令替换会话的整个输入。其语法要求嵌套的 Hunk review 命令放在--之后见 cli.ts 的解析实现hunk session reload session-1 -- show HEAD~1若--后缺失 review 命令CLI 会报错Pass the replacement Hunk command after--见 cli.test.tssession reload也不允许再嵌套另一个 session 命令或非 review 命令见 cli.ts。reload 在桥接层对应reloadSession处理器可携带新的输入并保留或重置应用状态见 bridge.test.ts。相比r键只重载当前输入session reload是整个会话换血适合 Agent 需要切换到完全不同的评审目标例如从 diff 切到某个历史提交的场景。总结选择哪种同步方式场景推荐方式说明Agent 持续改工作区文件hunk diff --watch事件提示 签名校验变化即刷新盯住某个历史提交/补丁hunk show HEAD~1 --watch/hunk patch changes.patch --watch输入可重开即可监听输入来自 stdin 管道先落盘再用--watchstdin 输入无法二次打开watch 会失败只想偶尔手动刷新按r软重载保留阅读位置Agent 要整体替换会话输入hunk session reload id -- review-command换整个输入需--分隔符jj / sapling 仓库hunk diff --watch轮询兜底事件计划缺省靠签名轮询感知变化更深一层的机制——状态机防抖参数、忽略根过滤、原生/可移植双后端、Bun 版本门禁——都可以在 packages/hunk/src/core/watch/ 的源码与controller.test.ts、observer.test.ts、plan.test.ts等测试中继续深入研读作为把 watch mode 集成进自己工具链时的可靠参考。赞分享开发工具代码评审CLIAI 应用【免费下载链接】hunkReview-first terminal diff viewer for agentic coders项目地址https://gitcode.com/gh_mirrors/hu/hunk点击查看免费下载相关推荐Hunk hunk-review Skill 完全指南让编码 Agent 安全驱动实时终端 Diff 评审Hunk hunk review Skill 完全指南让编码 Agent 安全驱动实时终端 Diff 评审 导读 Hunk 是一个面向终端用户的交互式 dif开发工具代码评审CLIAI 应用visual-explainer /diff-review 视觉化 Diff 审查指南把 git 变更渲染成自包含 HTML 审查报告visual explainer /diff review 视觉化 Diff 审查指南把 git 变更渲染成自包含 HTML 审查报告 /diff revieUnderstand Anything /understand-diff 实战指南把 Git Diff 变成知识图谱上的结构化影响分析Understand Anything /understand diff 实战指南把 Git Diff 变成知识图谱上的结构化影响分析 本篇指南围绕 UndeAI 技能AI 插件开发工具知识图谱上一篇开源项目推荐me_cleaner —— 为您的系统安全与隐私护航下一篇【亲测免费】 数据清洗利器DataCleaner——打造高质量数据集的捷径创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考