# Herdr 快速参考

*workspace、pane、agent 状态、CLI 自动化（v0.9.x）*

> Source: Herdr documentation (herdr.dev, v0.9.3) and herdr CLI help output · MIT

## 心智模型

### 层级

| Command | Description |
|---------|-------------|
| `session` | 后台服务器命名空间（会话），拥有所有进程 |
| `workspace` | 每个仓库或任务一个（工作区），侧栏汇总 agent 状态 |
| `tab` | workspace 内的一个布局（agent、日志、服务） |
| `pane` | 真实终端（面板），可向右或向下分割，断开后仍运行 |
| `agent` | Herdr 在 pane 中识别出的编码 agent（智能体） |

*断开客户端后，服务器及所有 pane 继续运行*

### Agent 状态

| Command | Description |
|---------|-------------|
| `working` | agent 正在处理一轮任务 |
| `blocked` | 等待审批提示或提问的回复 |
| `done` | 已完成，但你尚未查看 |
| `idle` | 已完成或在等待，且已查看 |
| `unknown` | 存在 agent 但状态不明；不代表已完成 |

*idle 和 done 都表示 agent 可以接收新提示*

### 输入模式

| Command | Description |
|---------|-------------|
| `terminal` | 按键直接发送到当前 pane |
| `prefix` | 按 Ctrl-b 后，下一个键触发 Herdr 操作 |
| `navigate` | 常驻的 workspace 导航界面 |
| `copy` | 键盘回滚、搜索与选择（Prefix [） |

## 快速上手

### 安装与启动

```
curl -fsSL https://herdr.dev/install.sh | sh
cd ~/projects/app
herdr           # launch or attach
claude          # any agent, auto-detected
herdr update    # self-update
herdr status    # client vs server version
```

### Agent 集成

```
herdr integration install claude
herdr integration install codex
herdr integration status --outdated-only
```

*集成可上报精确状态，并让 agent 在服务器重启后恢复*

### 鼠标优先

> 一切皆可点击：pane、tab、workspace、agent 行。拖动边框调整大小，右键打开分割和 tab 菜单，拖选即可复制。快捷键只是叠加的可选层。

## 快捷键

### 优先掌握

| Command | Description |
|---------|-------------|
| `Prefix ?` | 显示所有生效的绑定（/ 过滤） |
| `Prefix c` | 新建 tab |
| `Prefix v` | 分割：在右侧新建 pane |
| `Prefix -` | 分割：在下方新建 pane |
| `Prefix h/j/k/l` | 聚焦左 / 下 / 上 / 右侧 pane |
| `Prefix w` | workspace 导航 |
| `Prefix q` | 断开；所有内容继续运行 |

*默认前缀键为 Ctrl-b。断开是 q，而非 tmux 的 d*

### Pane

| Command | Description |
|---------|-------------|
| `Prefix z` | 放大（全屏）当前 pane |
| `Prefix x` | 关闭 pane |
| `Prefix Shift-h/j/k/l` | 与相邻 pane 交换 |
| `Prefix r` | 调整大小模式 |
| `Prefix Tab` | 切换到下一个 pane |
| `Prefix Shift-p` | 重命名 pane |
| `Prefix e` | 在编辑器中打开回滚内容 |

### Tab 与 Workspace

| Command | Description |
|---------|-------------|
| `Prefix n / p` | 下一个 / 上一个 tab |
| `Prefix 1..9` | 按编号跳转到 tab |
| `Prefix Shift-t / Shift-x` | 重命名 / 关闭 tab |
| `Prefix Shift-n` | 新建 workspace |
| `Prefix Shift-g` | 基于 git worktree 新建 workspace |
| `Prefix Shift-w / Shift-d` | 重命名 / 关闭 workspace |
| `Prefix g` | Goto 选择器：所有 agent 和终端 |
| `Prefix o` | 跳转到最新通知所在 pane |
| `Prefix b` | 切换侧栏 |
| `Prefix s` | 设置 |

*在 Goto 选择器中，b/w/i/d 过滤 blocked/working/idle/done；/ 搜索*

### 复制模式（Prefix [）

| Command | Description |
|---------|-------------|
| `h/j/k/l  w/b/e` | 按字符或单词移动 |
| `Ctrl-u / Ctrl-d` | 向上 / 向下翻半页 |
| `/  ?  n  N` | 向前 / 向后搜索，重复 |
| `v or Space` | 开始选择 |
| `y or Enter` | 复制选区并退出 |
| `q or Esc` | 不复制直接退出 |

*回滚查看时 pane 仍在运行*

## Session 与远程

### 持久化

```
herdr                      # reattach
herdr session list
herdr session attach work  # isolated server
herdr session stop work
herdr server stop          # kills ALL panes
```

### 通过 SSH

```
herdr --remote workbox  # local UI, remote panes
herdr --remote workbox --session agents
herdr machine add workbox --label box
herdr --machine box agent list
```

### 以 Worktree 作为 Workspace

```
herdr worktree create --branch fix/login --base main
herdr worktree list
herdr worktree remove --workspace w3
```

## 脚本化 Pane

### ID 与上下文

> ID 形如 w1（workspace）、w1:t1（tab）、w1:p1（pane）。在 Herdr pane 内会设置 HERDR_ENV=1 和 HERDR_PANE_ID。命令返回 JSON：从响应中读取新 ID，切勿根据侧栏顺序猜测。

### 查询

```
herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr pane layout --current
```

### 在旁边运行命令

```
id=$(herdr pane split --current \
       --direction right --no-focus \
     | jq -r .result.pane.pane_id)
herdr pane run "$id" "npm test"
herdr pane wait-output "$id" \
  --match "passed" --timeout 120000
herdr pane read "$id" --lines 80 \
  --source recent-unwrapped
```

### Pane 命令

| Command | Description |
|---------|-------------|
| `pane run ID CMD` | 一步输入命令并按 Enter |
| `pane send-text ID TEXT` | 输入原样文本，不按 Enter |
| `pane send-keys ID ctrl+c` | 发送具名按键 |
| `pane wait-output --regex RE` | 阻塞直到输出匹配（Rust 正则） |
| `pane zoom ID --toggle` | 通过脚本放大 pane |
| `pane move ID --new-tab` | 移动 pane；会获得新 ID |
| `notification show TITLE` | 弹出通知，可加 --sound done |

## 编排 Agent

### 启动、提示、收集

```
herdr agent start reviewer --kind codex --pane "$id"
herdr agent prompt reviewer "Review the diff" \
  --wait --timeout 300000
herdr agent read reviewer --lines 120
herdr agent wait reviewer --until blocked
herdr agent send-keys reviewer esc
```

### Agent 命令

| Command | Description |
|---------|-------------|
| `agent list` | 所有存活 agent 及其状态 |
| `agent get NAME` | 单个 agent 的 pane、类型和状态 |
| `agent focus NAME` | 将界面跳转到该 agent（标记为已查看） |
| `agent attach NAME` | 只打开该终端，不带 Herdr 界面 |
| `agent explain NAME` | 解释检测为何判定此状态 |

*目标为唯一的 agent 名称或其所在 pane 的 ID*

### Pane 与 Agent 命令对比

| Choice | Use when | Watch for |
|--------|----------|-----------|
| `pane` | shell、测试、服务 | 无法感知 agent 状态 |
| `agent` | 已检测到的编码 agent | 拒绝操作 blocked 的 agent |

### 经验法则

> agent start 需要一个已停在 shell 提示符的现有 pane；它从不创建布局。后台任务请用 --no-focus。超时后，先 read 该 agent 再重发：提示可能已经送达。

## 配置

### ~/.config/herdr/config.toml

```
[keys]
prefix = "ctrl+a"
focus_pane_left = ["prefix+h", "ctrl+alt+h"]
[theme]
name = "tokyo-night"
[ui.toast]
delivery = "system"  # or herdr / terminal
```

### 自定义弹窗命令

```
[[keys.command]]
key = "prefix+alt+g"
type = "popup"       # or "pane" / "shell"
command = "lazygit"
width = "80%"
height = "80%"
```

### 配置命令

| Command | Description |
|---------|-------------|
| `herdr --default-config` | 打印所有选项及注释 |
| `herdr config check` | 校验 config.toml |
| `Prefix Shift-r` | 在运行中的服务器重载配置 |
| `herdr config reset-keys` | 备份配置并清除自定义绑定 |

*ctrl+alt 组合键是跨终端最稳妥的免前缀绑定*