Herdr 智能复用器完整实战指南:dotfiles 中 agent-first 终端复用器的键位设计与扩展脚本
Herdr 智能复用器完整实战指南:dotfiles 中 agent-first 终端复用器的键位设计与扩展脚本
Herdr 是一款 agent-first 的终端复用器,专为高频使用 AI 编码代理(coding agent)的工作流设计。在这套 dotfiles 仓库中,它是作者的日常主力,tmux 则作为备用方案,两者共享同一套肌肉记忆,切换零成本。本文带你完整拆解 herdr/ 目录下的键位设计、agent 面板机制,以及 nav.sh、move-tab.sh 两个扩展脚本的实现思路。
为什么选择 agent-first 的终端复用器?
传统复用器的使用场景是"一个人管理多个终端会话";而 agent-first 的思路是:你的同事不再是人,而是一堆并行跑着的 AI 编码代理——它们各自占一个窗格(pane),你只需要在需要时把焦点跳转到"需要关注"的那个 agent 上。
作者对选型理由的原话(见 README.md):
Herdr is my daily driver since it is agent-first and a lot of my work these days runs through coding agents.
核心差异可以概括为三点:
| 设计点 | 传统复用器(tmux) | Herdr 智能复用器 |
|---|---|---|
| 面板管理 | 手动逐个切换窗口 | agent_panel_sort = "priority" 按优先级自动排序 agent |
| 焦点跳转 | 方向键逐格移动 | prefix+a 一键跳到"需要关注"的 agent 面板 |
| 配置方式 | 纯文本指令 | config.toml 结构化管理,还支持绑定 shell 命令 |
安装:一条 symlink 完成接入
整个 dotfiles 仓库通过 symlinks.conf 统一管理符号链接,Herdr 的配置映射写在其中(symlinks.conf):
$(pwd)/herdr/config.toml:$HOME/.config/herdr/config.toml
也就是说,clone 仓库后运行 ./install.sh,herdr/config.toml 就会被自动链接到 ~/.config/herdr/config.toml。软件本体由 Homebrew 安装,homebrew/Brewfile 中同时装好了 herdr 和它脚本依赖的 jq。
键位设计哲学:把 tmux 肌肉记忆平移到 Herdr
打开 herdr/config.toml 你会发现一个刻意的设计:几乎所有键位都和 tmux 保持一致,让你从 tmux 切换过来不用重新学。
基础键位一览
| 操作 | 键位 | 对应 tmux 习惯 |
|---|---|---|
| 前缀键 | Ctrl+Space |
同 tmux.conf 的 prefix C-Space |
| 垂直/水平分屏 | prefix+\ / prefix+- |
同 tmux 自定义分屏键 |
| 重命名 tab / 断开会话 | prefix+, / prefix+d |
与 tmux 完全一致 |
| 面板切换 | prefix+; 或 prefix+Shift+l |
tmux 的 last-pane 双绑定 |
| 放大窗格 | prefix+m |
与 tmux 的 bind -r m resize-pane -Z 对齐 |
| 工作区跳转 | prefix+Shift+1..9 |
tmux 的 numbered-window |
值得注意的细节:
- 透明背景:
panel_bg = "reset"让终端背景透出(config.toml),和 tmux 的bg=default行为一致,Nord 主题下视觉完全统一; j/k滚动会话、Ctrl+h/j/k/l移动面板:进入导航模式后的键位沿用 vim 方向键习惯(config.toml);- 滚动缓冲拉满:
scrollback_limit_bytes = 100000000,agent 输出再长也能翻。
agent 专属键位:复用器为 AI 工作流留出的快捷键
这是 agent-first 设计的精华所在(config.toml):
prefix+a→ 跳到下一个 agent 面板,当前面板需要关注时直接跳过去;prefix+Shift+a→ 反向循环,方便快速回头检查;prefix+Alt+1..9→ 直接聚焦第 N 个 agent 面板。
配合 <a href="https://link.gitcode.com/i/12eac6eaec4ac8847e7ebb968c249096" target="_blank">ui] 段的 agent_panel_sort = "priority"([config.toml),面板会按"需要关注程度"排序,形成一条完整的动线:按优先级看到谁在等你 → 一键循环 → 精确直达。跑多 agent 并行任务时,这套键位比逐个方向键翻面板要高效得多。
扩展脚本一:nav.sh 实现 vim 与面板间的无感穿梭
多窗格 + Neovim 分屏的嵌套布局里,最让人头大的问题是:Ctrl+h/j/k/l 到底该移动 vim 的分屏,还是复用器的面板?
dotfiles 用"两端协作"的思路解决了它:
- 终端侧:herdr/nav.sh 先用
herdr pane process-info查询当前面板的前台进程,用正则^g?(view|l?n?vim?x?)(diff)?$判断"vim 是否在控制这个面板"——是,就把按键转发给面板;不是,就调用herdr pane focus --direction移动面板焦点; - 编辑器侧:nvim/lua/tools/multiplexer-nav.lua 在 Neovim 里先尝试
wincmd,若窗格没变(说明已经顶到分屏边缘),再调用herdr pane focus穿越出去到外层面板。
两侧拼起来的效果:从一个分屏按 Ctrl+h,会一路向左穿过所有 vim 分屏,最后直接落到 Herdr 的相邻面板,全程零中断。这也是 tmux 用户熟悉的 vim-tmux-navigator 插件在 Herdr 上的等价实现(tmux.conf 中保留了原版插件)。
扩展脚本二:move-tab.sh 补齐官方缺失的 tab 排序
Herdr 没有原生的 move_tab 键位动作——重排 tab 只能通过 tab.move socket 方法完成。作者于是写了一个 34 行的小脚本补上这块(herdr/move-tab.sh):
- 通过
herdr tab list+jq算出当前 tab 在列表中的位置; - 用
nc向~/.config/herdr/herdr.sock发送{"method":"tab.move", ...}完成移动; - 一个易踩的坑被注释明确点出:
insert_index指向"移动前列表中的插槽",所以向右移动要取pos+2而不是pos+1。
然后在 config.toml 中把 prefix+Shift+Left/Right 绑定到该脚本,行为就和 tmux 的 swap-window(tmux.conf)一模一样了。
[[keys.command]] 把任意 shell 命令绑成快捷键,是 Herdr 这类扩展能力的通用出口:凡是 CLI 能做的事,都能变成你的快捷键。
上手建议:如何借鉴这套设计
- 先平迁肌肉记忆,再谈新特性:如果你从 tmux 转过来,优先照抄 config.toml 里"tmux muscle memory"注释块下的键位,熟悉度立得八成;
- 把 agent 键位当成一等公民:哪怕不跑 AI 代理,
prefix+a循环 + 优先级排序对任何多任务场景(编译、日志、测试)都有用; - CLI 驱动一切:
herdr pane focus、herdr pane send-keys、herdr tab list等子命令配合jq,足以支撑大部分自定义脚本,nav.sh和move-tab.sh就是两个可直接抄走的模板。
这套 dotfiles 用三个文件讲清了 agent-first 复用器的完整玩法:一个 config.toml 定义键位与 agent 面板行为,两个 shell 脚本分别打通"面板穿梭"和"tab 排序"两个官方未覆盖的断点。对于想让终端真正跟上 AI 编码节奏的开发者,这是一个非常值得参考的起点。
