herdr 使用指南
了解 herdr 的安装, 界面布局与常用快捷键, 在同一个终端工作区中组织项目, Coding Agent 和程序运行窗口.
herdr 介绍
herdr 是一个面向 Coding Agent 的终端工作区管理器. 它把多个项目, 终端和 Agent 组织到同一个界面中, 方便你同时使用 pi, Claude Code, Codex 等编程工具, 并查看它们的运行状态.
本文先介绍四部分: herdr 介绍, 下载安装, 界面布局介绍, 常用快捷键.
它解决什么问题
假设你正在学习 LyrjAgent, 经常需要同时打开几个终端:
- 一个运行 pi, 用来阅读代码, 讨论实现或修改文件.
- 一个运行 Python 程序, 查看执行结果和报错.
- 一个执行 Git 命令, 或启动服务, 查看日志.
如果这些终端散落在不同窗口里, 你需要反复寻找和切换. herdr 可以把它们放进同一个工作区, 再通过标签页和分屏组织起来. 你可以一边看 Agent 的回答, 一边看程序运行结果.
它的主要能力包括:
| 能力 | 用途 |
|---|---|
| 工作区管理 | 按项目组织终端 |
| 标签页和分屏 | 同时处理多个任务 |
| Agent 状态展示 | 找到需要你回应的 Agent |
| 后台会话 | 分离界面后继续运行任务 |
| 远程机器管理 | 在同一界面管理远程工作 |
| CLI, API 和插件 | 扩展与自动化工作流程 |
本文先掌握本地使用. 远程连接, 插件和自动化只需知道有这些能力, 后续需要时再查官方文档.
它和 pi 是什么关系
herdr 负责管理终端, pi 负责在终端中完成编程任务. 两者可以配合使用:
Windows Terminal
└── herdr
├── 窗格 A: pi, 阅读和修改代码
└── 窗格 B: PowerShell, 运行程序和查看结果
Windows Terminal 是外层终端应用. herdr 在里面提供工作区, 标签页和窗格, 每个窗格又可以运行 shell 或 Agent.
在窗格中启动 pi 后, 模型选择, 对话和工具调用仍由 pi 负责. 例如 /model 是 pi 的命令, 应输入到 pi 的对话输入框中. herdr 的分屏和标签页操作则使用后文的前缀快捷键.
📌 herdr 不会替你安装 pi, 也不会自动配置模型或 API Key. 想在窗格中运行某个 Agent, 需要先让该 Agent 在对应环境中可用.
后台运行的含义
herdr 采用客户端和后台服务器分离的方式. 你看到的界面是客户端, 后台服务器负责维持窗格和其中的进程.
按快捷键分离客户端后, 后台服务器仍在运行, Agent 和程序可以继续执行. 再次运行 herdr 就能重新连接默认会话.
这适合长时间运行的任务: 先让 Agent 工作, 暂时离开界面, 之后回来查看结果.
📌 后台运行的前提是机器和服务器仍在运行. 机器或服务器重启后, 原来的进程不会保留. herdr 可以恢复已保存的布局, 并在支持的情况下恢复 Agent 会话, 这与原进程一直运行是两回事.
项目使用 Rust 编写, 提供 Linux, macOS 和 Windows 版本, 在现有终端中运行. 官方入口: GitHub 仓库, 中文文档.
下载安装
一条命令安装
按当前使用的 Windows 环境, 打开 PowerShell, 执行官方安装命令:
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
安装器会下载对应的发布版本并配置 PATH. 安装完成后重新打开终端, 让新终端读取更新后的环境变量.
本文采用 Windows 原生安装方式. Windows 与 WSL 是不同的运行环境, 下面的命令在 PowerShell 中执行.
在项目中启动
先进入 LyrjAgent 目录, 再启动 herdr:
cd "D:\itheima\real-itheima\backend-learning-workspace\backend-learning\18-模型接入与最小Agent\LyrjAgent"
herdr
herdr 会启动或连接默认后台会话. 首次进入且没有工作区时, 它会自动创建工作区. 如果已有会话, 会重新连接已有内容, 不应把它理解成每次都新建一个项目.
进入 herdr 后, 当前窗格就是可以执行命令的终端. 如果 pi 已在该环境中安装并配置好, 输入:
pi
之后就可以像平时一样使用 pi. 想同时运行程序, 可以先按 Ctrl+B, 松开, 再按 v 向右分屏, 然后在新窗格里执行命令.
如果提示找不到 herdr, 先完全关闭并重新打开终端再试; 如果提示找不到 pi, 则需要检查当前 Windows 环境中的 pi 安装和 PATH.
安装依据: 官方安装说明.
界面布局介绍
先认识整体界面
下图来自 herdr 官方仓库, 是官方界面示例, 不是当前电脑的实际运行截图. 本地版本, 主题, 终端尺寸和已有工作区可能让界面细节有所不同.
图片来源: 官方 screenshot.png. 博客版直接引用官方仓库的原图.
看这张图时, 先辨认三个区域:
- 左上方的工作区列表. 图中的
herdr和pi-extensions是两个工作区, 下方还能看到分支信息. 这里用于在项目之间切换. - 左下方的 Agent 列表. 图中有
pi和claude, 旁边分别显示idle,working. 这里方便你查看 Agent 是否正在工作或需要关注. - 右侧的终端区域. 图中有两个并排窗格, 每个窗格运行自己的程序. 右侧窗格的高亮边框表示它当前获得焦点, 键盘输入会发送给它.
窗格内部的模型名, 对话, 命令输出和提示符, 属于该窗格内运行的程序. 例如右侧的 Claude Code 欢迎信息属于 Claude Code 的界面.
工作区, 标签页和窗格
这三个概念按层级组织:
herdr 默认会话
├── 工作区: LyrjAgent
│ ├── 标签页: 开发
│ │ ├── 窗格: pi
│ │ └── 窗格: 运行 Python
│ └── 标签页: 日志
│ └── 窗格: 查看程序输出
└── 工作区: 另一个项目
└── 标签页
└── 窗格
这是组织方式示意, 不是官方截图中的具体内容.
| 层级 | 含义 | 使用建议 |
|---|---|---|
| 工作区 | 项目级容器 | 一个项目一个工作区 |
| 标签页 | 工作区内的一套布局 | 按开发, 日志等用途划分 |
| 窗格 | 一个真实的终端 | 运行 shell 或 Agent |
工作区用于区分项目. 例如 LyrjAgent 与其他项目分别放到不同工作区, 避免终端和任务混在一起.
标签页用于区分视图. 同一个项目中, 可以用一个标签页写代码, 用另一个看日志. 新建标签页属于当前工作区.
窗格用于同时看多个终端. 左边运行 pi, 右边执行 Python 程序, 两边可以同时显示. 分屏创建的是新终端, 不是复制当前 Agent 的对话. 想在新窗格中使用另一个 pi, 需要在新窗格里再次运行 pi.
侧边栏里的 Agent 状态
herdr 会识别支持的 Agent, 并根据检测结果或集成上报展示状态.
| 状态 | 含义 |
|---|---|
working | 正在执行任务 |
blocked | 需要输入, 审批或决策 |
done | 已完成, 尚未查看 |
idle | 空闲或已查看完成状态 |
unknown | 无法可靠判断状态 |
例如让 pi 修改代码后, 可以切到另一个窗格运行程序. 如果 Agent 显示 blocked, 再回到对应窗格查看它的问题或确认请求.
done 和 idle 都可能表示 Agent 已经可以接受下一次输入. done 额外提示你还有完成结果未查看. 状态准确度取决于 Agent 和集成情况, 具体问题及结果仍应以窗格内的实际内容为准.
鼠标也能完成常用操作
- 点击窗格, 将键盘焦点切换过去.
- 点击工作区, 标签页或 Agent, 切换到对应位置.
- 拖动分隔边框, 调整窗格大小.
- 右键打开上下文菜单, 进行分屏等操作.
- 拖选窗格里的文本, 松开后复制; 不需要使用
Ctrl+C复制.
Windows Terminal 中可使用 Ctrl+Shift+V 粘贴文本. 复制文本和中断程序是不同操作, shell 中的 Ctrl+C 通常用于中断当前程序.
布局与状态依据: 核心概念, 快速开始, Windows 支持.
常用快捷键
Prefix 是哪个键
Prefix 表示前缀键. herdr 默认的前缀键是 Ctrl+B. 它不是键盘上印着 Prefix 的某个键.
文档写 Prefix → c 时, 实际操作是:
- 按住
Ctrl, 按一下B. - 松开
Ctrl和B. - 再按一下
c.
它是两步按键, 不是同时按住 Ctrl+B+C.
前缀键让 herdr 能区分终端输入和自身操作. 普通输入通常交给当前窗格内的程序, 前缀后的动作键则用于控制 herdr.
下表统一使用 Prefix → 动作键 表示这种顺序. 每次执行新操作, 都需要重新按一次前缀键. 如果修改过配置, 以 Prefix → ? 显示的实际绑定为准.
先记住这些
| 功能 | 快捷键 |
|---|---|
| 查看快捷键帮助 | Prefix → ? |
| 新建标签页 | Prefix → c |
| 向右分屏 | Prefix → v |
| 向下分屏 | Prefix → - |
| 切换到左 / 下 / 上 / 右窗格 | Prefix → h / j / k / l |
| 当前窗格放大 / 恢复 | Prefix → z |
| 下一个 / 上一个标签页 | Prefix → n / p |
| 打开工作区导航 | Prefix → w |
| 分离客户端 | Prefix → q |
h / j / k / l 表示选择其中一个方向键: h 向左, j 向下, k 向上, l 向右. - 是减号键, 官方绑定中也写作 minus.
在常见键盘布局中, 输入 ? 需要 Shift+/. 查看帮助的完整按法就是先按 Ctrl+B, 松开, 再输入 ?. 帮助界面中按 / 可以搜索操作和快捷键.
窗格与标签页操作
| 功能 | 快捷键 |
|---|---|
| 关闭当前窗格 | Prefix → x |
| 调整窗格大小模式 | Prefix → r |
| 向左 / 下 / 上 / 右交换窗格 | Prefix → Shift+H / J / K / L |
| 跳转到第 1 至 9 个标签页 | Prefix → 1 至 Prefix → 9 |
| 重命名标签页 | Prefix → Shift+T |
| 关闭当前标签页 | Prefix → Shift+X |
Prefix → Shift+T 表示先按前缀键并松开, 再按 Shift+T. 方向交换同理, 例如向左交换为 Prefix → Shift+H.
⚠️ 关闭窗格或标签页会结束相应终端中的运行任务. 如果只是暂时离开并保留任务, 使用
Prefix → q分离客户端.
工作区与导航
| 功能 | 快捷键 |
|---|---|
| 新建工作区 | Prefix → Shift+N |
| 重命名工作区 | Prefix → Shift+W |
| 关闭工作区 | Prefix → Shift+D |
| 打开 Go To 选择器 | Prefix → g |
| 显示 / 隐藏侧边栏 | Prefix → b |
Go To 选择器适合终端较多时使用. 打开后按 / 搜索名称, Agent 类型, 工作区或路径, 选择结果并按回车即可跳转到对应窗格.
Prefix → b 的完整按法是 Ctrl+B, 松开, 再按一次 b, 用来切换侧边栏显示.
复制与查看历史输出
先按 Prefix → [ 进入当前窗格的复制模式. 进入之后, 下表中的按键直接使用, 无须再按前缀键.
| 功能 | 复制模式内按键 |
|---|---|
| 向左 / 下 / 上 / 右移动 | h / j / k / l |
| 向前 / 向后搜索 | / / ? |
| 重复搜索 / 反向重复搜索 | n / Shift+N |
| 开始选择文本 | v 或空格 |
| 复制所选文本 | y 或回车 |
| 不复制直接退出 | q |
| 清除选择, 搜索或退出 | Esc |
Esc 会先清除当前选择或搜索, 再退出复制模式. 复制模式不会暂停程序, 查看历史输出时后台任务仍然继续运行.
这里的 q 与 Prefix → q 不同: 复制模式中的 q 退出复制模式, Prefix → q 分离 herdr 客户端.
用一遍就能记住的流程
以一个窗格运行 pi, 另一个窗格执行命令为例:
- 在项目目录运行
herdr, 然后在当前窗格运行pi. - 按
Prefix → v, 向右创建一个新终端窗格. - 点击右侧窗格, 确认提示符所在目录, 再执行程序或 Git 命令.
- 按
Prefix → h, 回到左侧的 pi; 按Prefix → l, 切回右侧终端. - 需要专心阅读一个窗格时, 按
Prefix → z放大, 再按一次恢复. - 暂时离开时, 按
Prefix → q分离. 之后在终端执行herdr重新连接.
以上说明依据官方 0.9.5 版本文档整理, 图片来自官方仓库. 本文未在当前电脑启动 herdr 实测, 具体界面和快捷键以本机版本及配置为准.