Hunk Live Session Control 实战指南：通过本地 Session Broker 检查、导航与重载 TUI 窗口

开发工具代码评审CLIAI 应用【免费下载链接】hunkReview-first terminal diff viewer for agentic coders项目地址https://gitcode.com/gh_mirrors/hu/hunk点击查看免费下载本指南面向在终端中运行 HunkReview-first terminal diff viewer并以 Agent 身份通过 CLI 驱动其会话的开发者完整讲解hunk session系列命令如何定位已注册的 Hunk 窗口、在不撑爆上下文的前提下读取 review 结构、把用户视角导航到指定文件与 hunk、以及如何安全地重载会话内容并处理 daemon 构建不匹配等故障场景。读完本文你将掌握一套可脚本化、可被 Agent 可靠调用的活会话控制工作流并理解其背后的 loopback daemon 机制与错误契约。架构基础TUI、Daemon 与 CLI 三方如何协作Hunk 的 TUI 界面属于用户Agent 不应直接运行hunk diff、hunk show等交互式命令。取而代之的是每个正常启动的 Hunk TUI 都会向一个loopback daemon注册自身随后hunk session ...系列命令通过该 daemon 找到已注册的窗口并发送 review 动作。这条链路在 会话 Agent 命令实现 中被完整落地每个 CLI 动作都会先探测 daemon 可用性resolveDaemonAvailability再通过REQUIRED_ACTION_BY_COMMAND把list、get、context、review、navigate、reload等命令映射为对应的 daemon 动作comment-add、highlight-add等也在同一张表中HTTP 客户端基于hunk/session-broker的签名调用器经HUNK_SESSION_API_PATH/session-apiPOST 请求并对list之外的动作启用targetSpecific定向投递实现方式见 cliClient.tsdaemon 同时维护独立于 HTTP 动作面的HUNK_SESSION_DAEMON_VERSION构建修订号用于跨构建兼容性判断细节见 protocol.ts。因此本文的所有命令都以Hunk 已在终端中打开并注册到本地 daemon为前提若没有任何活动会话非list类命令会抛出No active Hunk sessions are registered with the daemon. Open Hunk and wait for it to connect.消息定义见 errors.ts。第一步找到目标会话hunk session list hunk session get --repo . hunk session context --repo .list列出当前注册到 daemon 的全部会话即使 daemon 未运行list也不会报错而是返回空列表这一行为由真实探测路径下的测试锁定见 commands.daemon.test.ts。get返回单个会话的Path、Repo、Source字段是判断该用--repo还是--session-path的依据。context返回当前选中的上下文当前聚焦的文件 / hunk是导航前校准用户视野的依据。会话选择遵循以下优先级与 hunk-review skill 的会话选择说明一致--repo path按会话当前加载的仓库根目录匹配普通工作树场景最常用session-id按精确 ID 匹配当多个窗口共享同一仓库时必须显式指定仅存在一个会话时自动解析无需任何选择参数。轻量检查不撑爆上下文的 review 读取hunk session review --repo . --jsonreview默认只返回文件与 hunk 结构不携带原始 diff 文本专为先看结构、按需取内容的 Agent 工作流设计。按需追加标志hunk session review --repo . --include-notes --json hunk session review --repo . --include-patch --json--include-notes在文件与 hunk 结构之外附带当前 review 的活评论摘要--include-patch返回原始 unified diff 文本。注意patch 正文以 review 资源形式从会话读取而非来自注册信息若读取期间会话恰好重载或关闭会得到Could not read the raw diff for file from the live session.errors.ts此时重跑review即可若只需要结构则直接去掉--include-patch。这条命令在 skill 的推荐流程 中被列为引导 review 的第一步先用review --json摸清结构再只对真正需要读原文的文件启用--include-patch。导航可见窗口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 . --next-comment规则与语义hunk 编号从 1 开始--hunk n为 1-based绝对导航必须同时提供--file和恰好一个定位目标--hunk n、--old-line n或--new-line n三者不可混用违反时抛出Specify exactly one navigation target约束消息生成逻辑见 errors.ts行号在各自 diff 侧为 1-based行目标会把用户视口落在该精确行上若行位于折叠区域则回退到所属 hunk--hunk目标则直接落在 hunk 上相对评论导航--next-comment/--prev-comment在带注释的 hunk 之间跳转二者不可同时使用且不需要--file还可以按评论 ID 精确导航hunk session navigate --repo . --comment comment-1commentId来自hunk session comment list --json。导航目标被映射为 daemon 的navigate动作其中--file、--hunk、--old-line/--new-line会被序列化进请求体见 cliClient.ts。重载 review 内容重载用于换掉活会话当前展示的内容。必须在嵌套的 Hunk 命令之前放--分隔符hunk session reload --repo . -- diff hunk session reload --repo . -- show HEAD~1 -- README.mdreload接受嵌套的diff或show子命令并透传其参数[ref]与-- pathspec...例如hunk session reload --repo . -- diff main...feature -- src/ui hunk session reload --repo . -- show HEAD~1 hunk session reload --repo /path/to/worktree -- diff忘记--时抛出Pass the replacement Hunk command after --, for example hunk session reload session-id -- diff.errors.ts。高级重载场景支持把窗口定位与内容来源分离hunk session reload --session-path /path/to/live-window --source /path/to/other-checkout -- diff--session-path path按活窗口的当前工作目录即get返回的Path选中会话--source path只改变替换命令diff/show的执行目录不参与会话选择。当活会话要展示的目标工作树与其自身目录一致时直接用--repo即可只有当要控制的窗口与下次要加载的检出确实不是同一处时才需要拆开--session-path与--source。若传入的--session-path没有匹配会话错误No active session matches session path ...会提示先用hunk session get/list核对窗口的Path。另外针对工作树 review 中是否包含未跟踪文件的取舍hunk diff默认包含未跟踪文件只想看已跟踪变更时可重载为hunk session reload --repo . -- diff --exclude-untracked。诊断本地访问故障如果用户屏幕上明明有 Hunk 窗口session list里却看不到它最常见的原因是Agent 沙箱阻断了 loopback127.0.0.1访问。Hunk 的 daemon 刻意只监听本地回环loopback-only不会暴露到远程若list返回空、而 Hunk 正在运行先带着 Agent 的网络/沙箱权限重试而不是想方设法把 daemon 暴露到外部hunk daemon serve可用于手动启动 daemon 或调试 daemon 自身行为若端口被其他进程占用例如另一个 busy daemonCLI 会报告健康探测失败并提示重试、停止冲突进程或通过环境变量HUNK_MCP_PORT换用其他回环端口——这是 commands.ts 中端口冲突诊断 给出的明确建议。对应的错误速查No active Hunk sessions—— 若 Hunk 可见运行多半是 localhost 被沙箱阻断需授权后重试否则请用户先打开 Hunkskill 的 Common errors 段落 汇总了全部常见错误与对策。处理 daemon 构建不匹配升级 Hunk 后可能出现构建错位旧构建的 daemon 仍在运行且被任何一个旧窗口持有新构建的窗口会在状态栏提示两个构建的版本号同时每个hunk session命令都会以daemon-build-mismatch失败。该错误的--json形态携带结构化事实errors.ts 定义了完整字段daemon运行中 daemon 的构建daemonVersionappVersion若 daemon 早于 admin 作用域则可能为nullcli当前 CLI 的构建attachedSessions附着的窗口数量与明细sessionId、title、cwd、pid重启会断开这些窗口recommendedActionrestart-daemon或use-newer-hunk——当 CLI 比 daemon 旧时建议使用新构建的 Hunk否则建议重启 daemon。诊断与处置命令hunk daemon status # 查看 daemon 的构建与附着窗口 hunk daemon restart [--yes] # 确认后用本构建的 daemon 替换旧 daemonrestart的具体成本在 daemonMessages.ts 中被精确描述重启会断开若干附着窗口Restarting disconnects N attached windows重启后未能注册的新构建窗口会自动重新注册无需重跑任何东西直接再执行hunk session list验证即可而旧构建的窗口必须由用户重新启动must be relaunched, losing their notes若直接关闭旧窗口daemon 会在约一分钟后自行退出。Agent 的正确姿势是报告不匹配并把哪个构建更新、多少窗口受影响讲清楚然后征得用户同意后再执行hunk daemon restart --yes——从不未经询问就重启errors.ts 中 AGENT_ERROR_DOCS 对此有显式约束。当recommendedAction为use-newer-hunk时则说明 daemon 反而是新构建应当改用与之匹配的 Hunk 版本。给 Agent 的推荐会话工作流把上面的命令串成一次可复用的活会话控制循环对应 skill 的 Workflowhunk session list—— 找到活会话hunk session get --repo .—— 确认Path/Repo/Sourcehunk session review --repo . --json—— 先读文件/hunk 结构仅在确需原文时加--include-patchhunk session context --repo .—— 需要时核对当前聚焦位置hunk session navigate ...—— 把用户视口带到正确的文件/hunk/行hunk session reload -- command—— 内容不对时替换会话内容。遵循先导航、后评论结构先行、原文按需的顺序可以让 Agent 在几乎不消耗自身上下文的情况下精确驱动一个人类用户正在观看的 Hunk 窗口这也是 Hunk 面向 agentic coding 工作流的核心交互模型。赞分享开发工具代码评审CLIAI 应用【免费下载链接】hunkReview-first terminal diff viewer for agentic coders项目地址https://gitcode.com/gh_mirrors/hu/hunk点击查看免费下载相关推荐Hunk Session Broker 架构解析本地会话代理如何支撑 AI Agent 远程实时控制Hunk Session Broker 架构解析本地会话代理如何支撑 AI Agent 远程实时控制 Hunk 是一个面向 AI 编码 Agent 的 终端开发工具代码评审CLIAI 应用Reconmap CLI工具完全手册命令行下的渗透测试管理技巧Reconmap CLI工具完全手册命令行下的渗透测试管理技巧 Reconmap CLI是一款专为渗透测试团队设计的命令行工具它能够无缝集成Reconmap使用 hunk session 命令驱动交互式 Diff 审阅Hunk Review Agent Skill 完整实战指南使用 hunk session 命令驱动交互式 Diff 审阅Hunk Review Agent Skill 完整实战指南 在 AI 编码时代把 diffCLI后端数据库上一篇PocketBase项目中go.mod版本号格式的兼容性问题解析下一篇Komorebi配置文件详解手动定制壁纸行为的完整教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考