本附录提供 Herdr 的快速参考，涵盖安装、快捷键、CLI 命令、Agent 状态和配置等常用内容。
安装速查
# macOS — Homebrew brew install herdr# macOS/Linux — 官方脚本 curl -fsSL https://herdr.dev/install.sh | bash # mise mise install herdr@latest# Nix nix-env -iA nixpkgs.herdr# 验证安装 herdr --version herdr doctor
常用键盘快捷键
全局快捷键（随时生效）
Ctrl+a进入前缀模式
Ctrl+a Ctrl+a快速切换到上一个活跃窗格
Ctrl+a z最大化/还原当前窗格
Ctrl+a sSession 列表选择器
导航模式（无前缀，直接按键）
h左移窗格
←
j下移窗格
↓
k上移窗格
↑
l右移窗格
→
Tab下一个窗格
—
Shift+Tab上一个窗格
—
n下一个 Tab
next
p上一个 Tab
prev
1-9跳转到第 N 个 Tab
—
前缀模式（先按 Ctrl+a，再按功能键）
窗格操作
h水平分割新窗格
v垂直分割新窗格
x关闭当前窗格
z最大化/还原窗格
{与前一窗格交换位置
}与后一窗格交换位置
+增大窗格
-缩小窗格
=均匀分配窗格大小
Tab 操作
t新建 Tab
w关闭当前 Tab
,重命名当前 Tab
n下一个 Tab
p上一个 Tab
Session 操作
dDetach session
sSession 列表
$重命名 session
r重新加载配置
Agent 操作
a启动 Agent
q停止当前窗格的 Agent
i显示 Agent 详情
CLI 命令速查
Server 管理
herdr server start # 启动 server herdr server stop # 停止 server herdr server restart # 重启 server herdr server status # 查看 server 状态 herdr server reload-config # 热重载配置 herdr server update-agent-manifests # 更新 Agent 检测清单
Session 管理
herdr init # 在当前目录初始化 workspace herdr attach [ name ] # 连接到 session herdr detach # 分离当前 session herdr session list # 列出所有 session herdr session switch < name> # 切换到指定 session herdr session kill < name> # 终止指定 session
Agent 管理
herdr agent start < name> # 启动 Agent herdr agent start < name> --cwd < path> # 指定工作目录 herdr agent start < name> --worktree < name> # 在 worktree 中启动 herdr agent stop < name> # 停止 Agent herdr agent list # 列出所有 Agent herdr agent status < name> # 查看 Agent 状态 herdr agent explain < name> # 诊断 Agent 状态 herdr agent wait --all # 等待所有 Agent 完成 herdr agent chain --step 1:a --step 2:b # 编排 Agent 链
窗格操作
herdr pane list # 列出所有窗格 herdr pane info < pane-id> # 查看窗格信息 herdr pane split < pane-id> --direction horizontal # 水平分割 herdr pane split < pane-id> --direction vertical # 垂直分割 herdr pane close < pane-id> # 关闭窗格
远程操作
herdr remote attach < host> < session> # 连接远程 session herdr remote detach < host> < session> # 分离远程 session herdr remote list # 列出远程 session herdr remote ping < host> # 测试远程连通性
配置与诊断
herdr config show # 显示生效配置 herdr config validate # 验证配置语法 herdr --default-config # 打印默认配置 herdr doctor # 全面健康检查 herdr logs # 查看日志 herdr logs --follow # 实时跟踪日志 herdr logs --level debug # 查看 debug 日志 herdr stats # 查看资源占用
插件管理
herdr plugin list # 列出已安装插件 herdr plugin install < name> # 安装插件 herdr plugin enable < name> # 启用插件 herdr plugin disable < name> # 禁用插件 herdr plugin uninstall < name> # 卸载插件
更新
herdr update # 检查并安装更新 herdr update --check # 仅检查不安装 herdr update --handoff # 平滑升级（处理版本兼容）
Agent 状态速查
Idle ○灰色
空闲待命
初始状态或任务完成后
分配新任务
Running ◐蓝色
正在执行任务
Agent 收到任务指令
等待完成
Done ●绿色
任务成功完成
检测到完成标记/退出码 0
检查结果，分配新任务
Blocked ■黄色
需要人工介入
检测到阻塞模式/等待输入
查看窗格，做出决策
Unknown ?红色
状态无法确定
检测清单不匹配
运行 herdr agent explain
状态转换图
stateDiagram-v2
[*] --> Idle: Agent 启动
Idle --> Running: 收到任务
Running --> Done: 任务完成
Running --> Blocked: 需要输入
Done --> Idle: 结果确认
Blocked --> Running: 输入提供
Running --> Unknown: 检测失败
Unknown --> Running: 重新检测
Unknown --> Done: 手动标记
Done --> [*]: Agent 停止
配置速查
最常用配置项
# ~/.config/herdr/config.toml [terminal] default_shell = "zsh" # Shell 选择 [keys] prefix = "Ctrl+a" # 前缀键 [theme] name = "tokyonight" # 主题 [ui] sidebar_width = 30 # 侧边栏宽度 pane_borders = true # 窗格边框 [session] resume_agents_on_restore = true # 恢复时重启 Agent [remote] manage_ssh_config = true # 自动管理 SSH 配置
配置分区总览
[terminal]终端设置
default_shell, shell_mode, new_cwd
[worktrees]Worktree
directory
[remote]远程连接
manage_ssh_config
[keys]键绑定
prefix, navigate, prefix_mode, custom
[theme]主题外观
name, auto_switch, custom
[ui]界面
sidebar_width, pane_borders, mouse_capture
[ui.toast]通知
enabled, duration, position
[sound]声音
enabled, volume
[session]Session
resume_agents_on_restore
[experimental]实验功能
pane_history, kitty_graphics
[update]更新
manifest_check, auto_update
多 Agent 编排速查模板
模板一：前端 + 后端并行
# 同时启动前端和后端 Agent herdr agent start frontend --cwd src/frontendherdr agent start backend --cwd src/backend# 启动测试 Agent，等待前两者完成 herdr agent start tester \ --watch-panes frontend,backend \ --trigger done \ --task "运行完整测试套件"
模板二：编码 → 审查自动化
# Agent 完成编码后自动触发审查 herdr agent start coder --task "实现用户认证模块" # Reviewer 监控 coder 的完成事件 herdr agent start reviewer \ --watch-panes coder \ --trigger done \ --task "审查代码变更"
模板三：完整流水线
herdr agent chain \ --step 1:backend --task "实现 API 接口" \ --step 2:frontend --task "实现前端页面" --after 1 \ --step 3:tester --task "编写测试" --after 1,2 \ --step 4:reviewer --task "代码审查" --after 2 \ --step 5:docs --task "更新文档" --after 4
flowchart LR
S1["1. Backend<br/>实现 API"] --> S2["2. Frontend<br/>实现页面"]
S1 --> S3["3. Tester<br/>编写测试"]
S2 --> S3
S2 --> S4["4. Reviewer<br/>代码审查"]
S4 --> S5["5. Docs<br/>更新文档"]
模板四：并行 Worktree 开发
# 在独立 worktree 中并行开发多个模块 herdr agent start feature-a --worktree feat-a --base-branch developherdr agent start feature-b --worktree feat-b --base-branch developherdr agent start feature-c --worktree feat-c --base-branch develop# 完成后合并 herdr worktree merge feat-a --to developherdr worktree merge feat-b --to developherdr worktree merge feat-c --to develop
常见操作快速参考
创建新项目 workspace
cd project && herdr init
连接到 workspace
herdr attach <name>
启动一个 Agent
herdr agent start <name>
查看 Agent 在做什么
herdr agent explain <name>
最大化当前窗格
Ctrl+a z
新建水平窗格
Ctrl+a h（前缀模式）
切换 Tab
导航模式下按 n / p
分离 session
Ctrl+a d
查看日志
herdr logs --follow
检查健康状态
herdr doctor
更新 Agent 清单
herdr server update-agent-manifests
重载配置
herdr server reload-config
连接远程 workspace
herdr remote attach <host> <name>
停止所有 Agent
herdr agent stop --all
查看资源占用
herdr stats