flowchart TD
A[📦 安装 Herdr] --> B[⚙️ 首次引导配置]
B --> C[📂 进入项目目录]
C --> D[🚀 运行 herdr 启动工作区]
D --> E[🖥️ 界面出现：侧边栏 + 空白窗格]
E --> F[🤖 在窗格中启动 Agent]
F --> G[📊 侧边栏显示 Agent 状态]
G --> H{需要分屏？}
H -- 是 --> I["➡️ prefix+v / prefix+- 分屏"]
H -- 否 --> J[继续工作]
I --> K[在新窗格中启动更多 Agent 或服务]
J --> L[prefix+q 分离工作区]
K --> L
L --> M[Agent 在后台继续运行]
M --> N[herdr 重连回工作区]
N --> O[🎉 享受高效的 Agent 工作流]
style A fill:#e1f5fe
style O fill:#c8e6c9
5 第 3 章 · 快速上手
5.1 从安装到上手：完整流程概览
在开始具体操作之前，先看一下从安装到日常使用的完整流程：
如果你已经按照第 2 章完成了安装和配置，可以直接跳到「启动第一个 Session」。
5.2 启动第一个 Session
5.2.1 进入项目目录
Herdr 的设计哲学是项目优先——它默认你在某个项目目录中工作：
# 进入你的项目目录
cd ~/projects/my-awesome-project
# 确认这是一个 Git 仓库（推荐但非必须）
git status
Note为什么要进入项目目录？
Herdr 启动时会以当前目录作为工作区的根目录。这意味着： 1. 所有在这个工作区中启动的 Agent 和命令都默认使用这个目录 2. Herdr 会读取项目级别的配置（./herdr.toml） 3. 会话数据会与项目路径关联，下次 herdr 可以快速恢复
5.2.2 启动 Herdr
# 在项目目录中直接运行
herdr如果你是第一次运行，会看到首次引导界面（详见第 2 章）。完成引导后，你会看到 Herdr 的主界面。
5.2.3 给 Session 命名
默认情况下，Herdr 会使用项目目录名作为 session 名称。你也可以手动指定：
# 指定 session 名称
herdr --name "my-project"
# 在 session 内部重命名（命令模式）
# 按 prefix + : 进入命令模式，输入：
# rename-session my-project5.3 界面导览
Herdr 启动后，你会看到如下界面：
┌─────────────────────────────────────────────────────────────────────┐
│ 📦 my-project [main] [+] │ ← 标签栏
├──────────────┬──────────────────────────────────────────────────────┤
│ │ │
│ 📦 Workspace│ $ claude │ ← 主窗格
│ ├─ 🤖 claude│ Welcome to Claude Code! │
│ │ working │ │
│ │ 重构中… │ I'll help you with your codebase. What would │
│ ├─ 🖥️ server│ you like to work on today? │
│ │ running │ │
│ │ :3000 │ claude> _ │
│ └─ ➕ New │ │
│ │ │
│──────────────│ │
│ Ctrl+a 前缀 │ │
│ ? 帮助 │ │
└──────────────┴──────────────────────────────────────────────────────┘
↑ ↑
侧边栏 工作区（窗格区域）5.3.1 界面组成
| 区域 | 名称 | 说明 |
|---|---|---|
| 顶部标签栏 | Tab Bar | 显示所有打开的标签页，点击切换，[+] 新建 |
| 左侧边栏 | Sidebar | 显示工作区中所有窗格的 Agent 状态和概要 |
| 主区域 | Workspace | 窗格区域，每个窗格是一个独立的终端 |
| 底部状态栏 | Status Bar | 显示前缀键提示、帮助快捷键、系统信息 |
5.3.2 侧边栏详解
侧边栏是 Herdr 最有价值的 UI 元素。它实时反映工作区中每个窗格的状态：
📦 Workspace: my-project ← 工作区名称
├─ 🤖 claude ← 窗格类型（Agent）
│ ● working ← 状态指示器
│ "重构 auth.ts" ← 当前任务摘要
│ 00:03:24 ← 已运行时间
├─ 🖥️ server ← 窗格类型（普通进程）
│ ● running ← 状态：正常运行中
│ vite :3000 ← 进程信息
├─ 🤖 codex ← 另一个 Agent
│ ○ idle ← 状态：空闲
│ 等待指令... ← 状态描述
└─ ➕ New Pane ← 点击创建新窗格5.3.2.1 Agent 状态说明
| 状态 | 颜色 | 图标 | 含义 |
|---|---|---|---|
| idle | 灰色 | ○ | Agent 已启动，等待输入 |
| working | 蓝色 | ● | Agent 正在处理任务 |
| blocked | 黄色 | ⚠️ | Agent 需要用户确认/输入 |
| done | 绿色 | ✓ | Agent 已完成任务 |
| error | 红色 | ✗ | Agent 发生错误 |
| running | 青色 | ▶ | 非 Agent 进程正在运行（如服务器） |
Tip状态颜色与通知
当 Agent 状态变化时（特别是变为 blocked 或 done），Herdr 可以发送系统通知。确保在配置中启用了通知：
[agent]
notify_on_status_change = true
notify_statuses = ["blocked", "done"]这样你就可以切换到其他工作，Agent 完成或需要你时会自动通知你。
5.4 鼠标操作
Herdr 提供了完善的鼠标支持，让你可以像使用图形应用一样操作终端。
5.4.1 基本鼠标操作
| 操作 | 动作 | 效果 |
|---|---|---|
| 点击窗格 | 鼠标左键单击窗格内任意位置 | 切换到该窗格（获取焦点） |
| 点击侧边栏 | 左键点击侧边栏项目 | 切换到对应窗格 |
| 点击标签 | 左键点击标签栏标签 | 切换到该标签页 |
| 拖拽边框 | 左键按住窗格边框拖动 | 调整窗格大小 |
| 右键窗格 | 右键单击窗格 | 弹出上下文菜单 |
| 右键侧边栏 | 右键点击 Agent 项 | 弹出 Agent 操作菜单 |
| 拖选文字 | 左键拖选文字 | 选中文本（自动复制到剪贴板） |
| 滚轮 | 上下滚动 | 滚动当前窗格的输出历史 |
| 双击 | 左键双击 | 选中一个单词 |
5.4.2 右键上下文菜单
在窗格上右键会弹出上下文菜单：
┌─────────────────────────────┐
│ 📋 复制 │
│ 📋 粘贴 │
│ ───────────────────── │
│ ➡️ 右分屏 │
│ ⬇️ 下分屏 │
│ ───────────────────── │
│ 🔄 重启 Agent │
│ ⏹️ 停止 Agent │
│ ───────────────────── │
│ 📝 重命名窗格 │
│ ❌ 关闭窗格 │
└─────────────────────────────┘
Tip鼠标 vs. 键盘
Herdr 的设计原则是鼠标和键盘各有所长： - 鼠标适合：浏览、切换、选择文字、调整窗格大小 - 键盘适合：快速操作、连续命令、高频使用场景
熟练用户通常在日常使用中混搭：高频操作用键盘，低频操作用鼠标。
5.5 启动第一个 Agent
5.5.1 启动 Claude Code
在 Herdr 的主窗格中，直接输入 Agent 命令：
# 启动 Claude Code
claude启动后，你会看到 Claude Code 的欢迎界面。同时，侧边栏会自动识别这是一个 Agent 并更新状态：
侧边栏变化：
➕ New Pane → 🤖 claude
○ idle
"等待输入..."5.5.2 启动其他 Agent 或服务
你可以在同一个窗格中切换不同的 Agent，也可以在分屏后的新窗格中启动：
# 启动 Codex
codex
# 启动 Gemini CLI
gemini
# 启动一个开发服务器
npm run dev
# 启动 Python REPL
python3每个进程启动后，侧边栏都会自动识别并更新。
5.6 分屏操作
分屏是终端工作空间的核心操作。Herdr 的分屏快捷键使用前缀键 + 字符的模式。
5.6.1 前缀键
在开始之前，确认你的前缀键。默认情况下：
| 引导选择 | 前缀键 | 适合人群 |
|---|---|---|
| tmux 风格 | Ctrl+b |
tmux 老用户 |
| Herdr 默认 | Ctrl+a |
新用户（推荐） |
Warning前缀键冲突
如果你使用了 Ctrl+a，注意这在 Bash 中默认是「跳到行首」的快捷键。Herdr 在运行时会拦截这个快捷键。如果你偶尔需要在 shell 中使用原始功能，可以按两次 Ctrl+a（在 Herdr 默认配置中，第二次会透传给 shell）。
以下所有快捷键示例都使用 prefix 来代表前缀键。如果你的前缀键是 Ctrl+a，那么 prefix+v 就是先按 Ctrl+a 松开，再按 v。
5.6.2 分屏快捷键
| 快捷键 | 功能 | 说明 |
|---|---|---|
prefix + v |
右分屏（垂直分割） | 将当前窗格左右分成两个 |
prefix + - |
下分屏（水平分割） | 将当前窗格上下分成两个 |
prefix + h |
切换到左侧窗格 | 焦点移动 |
prefix + j |
切换到下方窗格 | 焦点移动 |
prefix + k |
切换到上方窗格 | 焦点移动 |
prefix + l |
切换到右侧窗格 | 焦点移动 |
prefix + H |
向左调整边框 | 大写 = 移动边框 |
prefix + J |
向下调整边框 | 每次移动 2 个字符 |
prefix + K |
向上调整边框 | |
prefix + L |
向右调整边框 | |
prefix + z |
当前后格全屏/还原 | 切换「聚焦模式」 |
prefix + x |
关闭当前窗格 | 会询问确认 |
5.6.3 分屏布局示例
假设你启动了 Herdr 并做了以下操作：
- 在主窗格中启动
claude - 按
prefix+v右分屏，在新窗格中启动npm run dev - 切换回左侧（
prefix+h），按prefix+-下分屏，启动codex
最终布局如下：
┌──────────────┬──────────────────┬──────────────────┐
│ 侧边栏 │ │ │
│ │ Claude Code │ Dev Server │
│ 🤖 claude │ (重构 auth.ts) │ vite :3000 ✓ │
│ working │ │ │
│ ├──────────────────┤ │
│ 🖥️ server │ │ │
│ running │ │ │
│ │ Codex │ │
│ 🤖 codex │ (查阅 API) │ │
│ working │ │ │
│ │ │ │
└──────────────┴──────────────────┴──────────────────┘5.6.4 使用预设布局
如果你每次都创建相同的布局，可以使用预设布局（preset layouts）：
# 在命令模式中（prefix + :）输入：
layout dev # 开发布局：左大右小（Agent + 服务器）
layout pair # 结对布局：左右各半
layout grid # 网格布局：四宫格
layout stack # 堆叠布局：全屏，通过侧边栏切换5.7 标签页管理
当你的工作区中有太多窗格时，可以使用标签页（Tab）来组织。
5.7.1 标签页快捷键
| 快捷键 | 功能 |
|---|---|
prefix + c |
新建标签页 |
prefix + n |
切换到下一个标签页 |
prefix + p |
切换到上一个标签页 |
prefix + 1~9 |
切换到第 1~9 个标签页 |
prefix + , |
重命名当前标签页 |
prefix + & |
关闭当前标签页 |
5.7.2 标签页组织建议
标签页 1: [开发] ← 主要的 Agent 和代码编辑
标签页 2: [测试] ← 测试服务器、测试 Agent
标签页 3: [文档] ← 文档 Agent、预览服务器
标签页 4: [日志] ← 日志监控、数据库查询5.8 工作区切换
当需要同时处理多个项目时，可以为每个项目创建独立的工作区：
# 创建新工作区
prefix + : → new-workspace backend
# 切换工作区
prefix + w # 打开工作区切换器（显示所有工作区列表）
# 或直接切换
prefix + 1 # 切换到工作区 1
prefix + 2 # 切换到工作区 2
Tip工作区 vs. 标签页
- 工作区（Workspace）：完全独立的环境，每个工作区有自己的窗格布局和 Agent 集合
- 标签页（Tab）：同一个工作区内的窗分组
类比：工作区就像虚拟桌面（macOS Space），标签页就像浏览器标签。
5.9 分离与重连
这是 Herdr（继承自终端复用器传统）最强大的功能之一：会话持久化。
5.9.1 分离（Detach）
当你需要离开终端时，可以分离工作区。分离后，所有 Agent 和进程继续在后台运行：
# 方式 1：快捷键分离
prefix + q # 分离当前工作区
# 方式 2：命令行分离
herdr detach
# 方式 3：关闭终端窗口也能自动分离
# （前提是 server 模式已启用，默认启用）分离后，你会回到普通的终端：
$ herdr
[detached from workspace: my-project]
$5.9.2 重连（Reconnect）
当你回来时，重新连接到工作区：
# 直接运行 herdr，会自动连接到最近的活跃工作区
herdr
# 列出所有活跃的工作区
herdr list
# 输出：
# my-project (2 agents, 3 panes) created 2h ago
# backend-api (1 agent, 2 panes) created 30m ago
# 连接到指定工作区
herdr attach my-project5.9.3 分离的场景应用
flowchart LR
A[办公室 Mac Studio] -->|SSH 到服务器| B[云服务器]
B --> C[herdr 启动工作区]
C --> D[启动 Claude Code 重构]
D --> E{需要离开？}
E -->|SSH 断开| F["prefix+q 分离<br/>或自动分离"]
F --> G[Agent 继续运行 ✅]
G --> H[回家]
H --> I[笔记本 SSH 重连]
I --> J[herdr attach]
J --> K[🎉 回到之前的状态]
E -->|继续工作| L[正常工作]
5.10 停止 Session
当你完全结束工作时：
# 停止当前工作区的 server（所有窗格中的进程会被终止）
herdr server stop
# 停止指定工作区
herdr server stop my-project
# 停止所有工作区
herdr server stop --all
Warning停止前的确认
herdr server stop 会终止工作区中的所有进程，包括正在运行的 Agent。如果有 Agent 正在执行重要任务，请先确认： 1. 检查侧边栏中是否有 working 状态的 Agent 2. 如果有，等待其完成或手动保存进度 3. 确认后再停止
5.11 快捷键速查表
以下是本章涉及的所有快捷键，建议打印出来放在手边：
5.11.1 基础操作
| 快捷键 | 功能 | 说明 |
|---|---|---|
prefix + ? |
查看所有快捷键 | 随时查看完整列表 |
prefix + : |
进入命令模式 | 输入命令 |
prefix + q |
分离工作区 | 后台继续运行 |
prefix + d |
分离工作区 | 同上（tmux 风格） |
5.11.2 窗格操作
| 快捷键 | 功能 |
|---|---|
prefix + v |
右分屏 |
prefix + - |
下分屏 |
prefix + h/j/k/l |
切换窗格（左/下/上/右） |
prefix + H/J/K/L |
调整窗格大小 |
prefix + z |
窗格全屏/还原 |
prefix + x |
关闭窗格 |
prefix + o |
轮换窗格位置 |
5.11.3 标签页操作
| 快捷键 | 功能 |
|---|---|
prefix + c |
新建标签页 |
prefix + n / p |
下一个/上一个标签页 |
prefix + 1~9 |
切换到指定标签页 |
prefix + , |
重命名标签页 |
prefix + & |
关闭标签页 |
5.11.4 工作区操作
| 快捷键 | 功能 |
|---|---|
prefix + w |
工作区切换器 |
prefix + ( |
上一个工作区 |
prefix + ) |
下一个工作区 |
5.12 实战练习：Claude Code + 测试服务器
让我们用一个完整的实战练习来巩固本章学到的内容。
5.12.1 目标
创建一个 Herdr 工作区，同时运行： 1. Claude Code——重构一个 React 组件 2. Vite 开发服务器——实时预览修改效果 3. Jest 测试——在 Claude 完成后运行测试验证
5.12.2 步骤 1：创建项目并启动 Herdr
# 创建一个练习项目（如果你已有项目可跳过）
mkdir -p ~/projects/herdr-practice && cd ~/projects/herdr-practice
# 初始化一个简单的 React 项目
npm create vite@latest . -- --template react-ts
npm install
# 启动 Herdr
herdr --name "practice"5.12.3 步骤 2：启动 Claude Code
在 Herdr 的主窗格中：
# 启动 Claude Code
claude
# 给 Claude 一个任务
# 输入：请重构 src/App.tsx，将计数器逻辑提取到 useCounter 自定义 Hook 中此时侧边栏应该显示：
📦 practice
└─ 🤖 claude
● working
"重构 App.tsx"
00:00:155.12.4 步骤 3：右分屏并启动开发服务器
按下 prefix + v 右分屏，然后在新窗格中：
# 启动 Vite 开发服务器
npm run dev侧边栏现在显示：
📦 practice
├─ 🤖 claude
│ ● working
│ "重构 App.tsx"
│ 00:01:30
└─ 🖥️ vite
● running
:5173 ✓5.12.5 步骤 4：观察状态变化
切换回 Claude 窗格（prefix + h），观察 Claude 的工作过程。当 Claude 完成重构时：
- 侧边栏中 claude 的状态从
● working变为✓ done - 你会收到一个系统通知（如果已启用通知）
5.12.6 步骤 5：下分屏并运行测试
在左侧窗格按 prefix + -（下分屏），在新窗格中：
# 运行测试
npm test5.12.7 步骤 6：分离并重连
现在所有工作都在进行中。尝试分离：
- 按
prefix + q分离 - 你回到了普通终端
- Agent 和服务器在后台继续运行
重新连接：
herdr attach practice你应该看到一切都还在原来的状态，Agent 继续工作。
5.12.8 最终布局
┌──────────┬─────────────────────────┬──────────────────────┐
│ 侧边栏 │ │ │
│ │ Claude Code │ Vite Dev Server │
│ 🤖 claude│ (重构 App.tsx) │ │
│ ✓ done │ │ VITE v6.0.0 │
│ │ ✨ Done! │ ➜ Local: :5173 │
│ 🖥️ vite ├─────────────────────────┤ │
│ running │ │ │
│ │ Jest Tests │ │
│ 🧪 jest │ PASS src/App.test.tsx │ │
│ ✓ done │ ✓ renders correctly │ │
│ │ ✓ counter works │ │
│ │ Tests: 2 passed │ │
└──────────┴─────────────────────────┴──────────────────────┘
Tip恭喜！
你已经完成了第一个 Herdr 实战练习。你体验了： - ✅ 启动工作区 - ✅ 启动多个 Agent 和服务 - ✅ 实时观察 Agent 状态 - ✅ 分屏操作 - ✅ 分离与重连 - ✅ 多 Agent 协同工作
这就是 Herdr 的日常使用方式。随着你越来越熟悉，这些操作会变成肌肉记忆。
5.13 本章小结
Tip快速上手要点速查
- 启动：在项目目录运行
herdr - 界面：侧边栏（Agent 状态） + 主区域（窗格）
- Agent 状态：idle → working → blocked/done → error
- 鼠标：点击切换、拖拽调整、右键菜单
- 分屏：
prefix+v右分屏，prefix+-下分屏 - 标签页：
prefix+c新建，prefix+1~9切换 - 工作区：
prefix+w切换器 - 分离：
prefix+q分离（后台继续运行） - 重连：
herdr或herdr attach <name> - 停止：
herdr server stop
5.14 延伸阅读
- 快捷键完整参考：https://herdr.dev/docs/keybindings
- 预设布局配置：https://herdr.dev/docs/layouts
- 命令模式命令列表：https://herdr.dev/docs/commands
- 高级用法教程：从 tmux 迁移的最佳实践
- 社区布局分享：https://herdr.dev/community/layouts
入门篇到此结束！你已经掌握了 Herdr 的基本使用方法。在接下来的进阶篇中，我们将深入探索 Herdr 的高级功能：自定义配置、多 Agent 编排、自动化工作流等。