Herdr 多 Agent 终端工作台使用指南

基于本机实测(0.6.8 → 0.9.0 升级实战)+ 官方 v0.9.0 文档(llms.txt 全套 mdx 原文)整理。 本机环境: Ubuntu 22.04 桌面 / 42 个 workspace 并行跑 Claude Code / stable 频道。

1. 工具定位

Herdr 是专为 AI 编码 agent 设计的终端工作台(terminal workspace manager),Rust 编写,Apache-2.0(0.8.0 起,之前是 AGPL)。

和同类工具的区别:

工具	核心差异
tmux/zellij	通用终端复用,不认识”agent”,没有状态概念
ClaudeSquad	多 agent + worktree 隔离,但 TUI 以任务卡片为中心,终端能力弱
Herdr	pane 是真实终端 + agent 状态感知(working/blocked/done/idle)+ 侧栏注意力路由 + socket API 可编程

一句话: Herdr 回答的核心问题是”哪个 agent 现在需要我”——42 个窗口并行时,不用挨个巡检,侧栏直接告诉你哪个 blocked(等你点确认)、哪个 done(等你验收)。

官方资源:

• 文档索引: https://herdr.dev/llms.txt(agent 可读,分 stable/preview 快照)
• 完整文档打包: https://herdr.dev/llms-full.txt
• 插件市场: https://herdr.dev/plugins
• 仓库: https://github.com/herdrdev/herdr(有简体中文 README)

2. 概念模型

Session(持久 server 命名空间)
└── Workspace(项目容器,侧栏一行,状态自卷积)
    └── Tab(布局页)
        └── Pane(真实终端) ← Agent(被识别出的前台进程)

• Workspace: 一项目/一任务/一调查一个。状态从内部 agent 向上卷积(blocked 传染到 tab 和 workspace 行)
• Client/Server 分离: server 持有 pane 和进程,client 只是 UI。detach(prefix+q)后一切照跑
• 三种模式: terminal 模式(键入直达 pane)/ prefix 模式(一次动作)/ navigate 模式(workspace 导航)
• 鼠标原生: 点选/拖拽分栏边框/右键菜单/划选即复制,不靠键盘也能全操作

3. 键位速查(prefix = ctrl+b)

日常五个就够:

动作	键
新建 tab	prefix+c
左右/上下分屏	prefix+v / prefix+-
pane 间跳转	prefix+h/j/k/l
workspace 导航	prefix+w
detach(全部保留)	prefix+q

进阶:

动作	键
pane 全屏缩放	prefix+z
关闭 pane / tab / workspace	prefix+x / prefix+shift+x / prefix+shift+d
tab 切换 / 直跳	prefix+n/p / prefix+1..9
复制模式(vim 移动+/搜索)	prefix+[
键位帮助(带 / 过滤)	prefix+?
收起/展开侧栏	prefix+b
resize 模式	prefix+r

免 prefix 直按: 官方勘测过 Ghostty/iTerm2/kitty/WezTerm/GNOME/Konsole 等默认键位,ctrl+alt 家族几乎处处空闲,可叠加绑定:

[keys]
focus_pane_left  = ["prefix+h", "ctrl+alt+h"]
next_tab         = ["prefix+n", "ctrl+alt+]"]

避开 ctrl+alt+方向键(GNOME 切工作区)、ctrl+alt+t(Ubuntu 开终端)、ctrl+alt+l(KDE 锁屏)。

4. Agent 状态检测体系

五种状态: blocked(等你输入/审批) / working / done(完成未查看) / idle(完成已查看) / unknown。

检测权威分两层(0.9.0 实测逻辑):

1. lifecycle hooks(装了 integration 的 Pi/OMP/Kimi/OpenCode/Kilo/MastraCode): hook 直报,是唯一权威,不再跑屏幕兜底
2. screen manifest(Claude Code/Codex 等): 读 pane 底部 live buffer 快照,用 TOML 规则匹配 idle/working/blocked。回滚.scrollback 不影响检测(始终看底部)

关键运维点:

• manifest 会在线热更新(herdr.dev 远端下发,无需重启);本地可放 ~/.config/herdr/agent-detection/<agent>.toml 覆盖,优先级最高
• 状态不对时先跑 herdr agent explain <target> —— 会输出命中了哪条规则、manifest 来源/版本、fallback 原因
• 沙箱/VM 里跑 agent 时,用 HERDR_AGENT=claude fence -- claude 显式告知用哪个 manifest
• blocked 检测故意做得保守: 认不出的新提示样式会先显示 idle 而不是误报 blocked
• herdr pane 里再套 tmux 时,detection 只能看到 tmux 进程本身,看不到里面的 agent

给 agent 起名字方便引用: herdr agent rename w1:p1 reviewer。

5. 会话持久化: 四级恢复机制(重点)

这是升级/崩溃后”会话还在不在”的权威结论,0.9.0 文档原表:

场景	进程存活	布局恢复	屏幕内容	agent 对话恢复
detach/reattach	✅	✅	✅(活终端)	✅(进程没死)
server 重启	❌	✅	仅开了 pane_history	仅原生会话恢复
update(不带 handoff)	兼容的 server 不动	✅	同上	同上
update --handoff	✅(尽力而为)	✅	✅	✅

四个机制叠加:

1. Live persistence: detach 默认路径,进程从不停
2. Snapshot restore: server 重启后恢复 workspace/tab/pane/cwd/布局/焦点,但 pane 回来的是新 shell
3. Pane screen history: [experimental] pane_history = true 后,server 重启能回放 pane 最近的屏幕内容(默认关,因为可能含 token/密钥,落 session-history.json)
4. Native agent session restore(默认开): server 重启后,用 integration 上报的 session id 自动拉起 agent 对话——Claude Code 对应 claude --resume <id>,要求 integration 版本 ≥6(herdr integration status 查)。关掉: [session] resume_agents_on_restore = false

本机实战(2026-09-16,0.6.8 → 0.9.0): 跨 endpoint generation 1 的一次性升级必须换 server,用 herdr update --handoff 热交接,42 个 workspace 的 pane 进程全部存活,包含正在跑的 claude 会话。注意 herdr update 会拒绝在 herdr pane 内直接跑(防自杀),需剥离 HERDR_PANE_ID/HERDR_ENV/HERDR_SOCKET_PATH 环境变量并 setsid 脱离进程组后执行。

本机补充机制: server 级 handoff 管不到”pane 里 claude 进程自己 OOM/崩了”的场景,已在 ~/.bashrc 把 claude-unsafe 从 alias 升级为函数: 异常退出(rc≠0 且 ≠130)2s 后自动 --continue 接回,3 次秒崩熔断。与 herdr 的 native session restore 是互补关系(一个管进程崩溃,一个管 server 重启)。

坑: 原生恢复丢 agent 启动参数(2026-09-18 实证)。重启电脑后 herdr 用固定的 claude --resume <id> 拉起各 pane,不带 --dangerously-skip-permissions,42 个 pane 全部退回普通权限模式逐条确认(ps 实证)。herdr 无配置项自定义恢复命令(仅 session.resume_agents_on_restore 开关),上游功能缺口见 issue #3302(preserve agent options across session restore)。本机解法: ~/.claude/settings.json 设 "permissions": {"defaultMode": "bypassPermissions"}(配合已有的 skipDangerousModePermissionPrompt),让任何途径启动的 claude 默认就是 bypass,herdr 恢复路径自动继承。注意该设置只影响之后启动的进程,已在跑的 pane 不追溯。重启实证(2026-09-18): 42 个恢复 pane 中 40 个底栏确认 bypass;例外 2 个是车机JIRA项目 pane——项目级 .claude/settings.json 故意设了 acceptEdits(优先级: 项目 > 用户),属预期行为。验证手法: herdr agent list + 逐 pane agent read --source detection 扫底栏标识,全自动无需人工逐窗检查。

6. 多机管理(0.9.0 头条特性)

一个窗口同时管本地 + 多台 SSH 机器,侧栏合并显示所有 agent,断线互不影响:

herdr machine add workbox --label "构建机"           # 加机器(交互式,会装好远端 server)
herdr machine add tx2 --label "tx2" --remote-session agents   # 挂到远端指定 session
herdr machine list / rename / disable / remove       # 管理

要点:

• 每台机器独立 server/独立 session,断线那台只是变暗(显示缓存状态),不拖垮其他机器;重连不会抢走你正在用的机器焦点
• 认证完全走 OpenSSH(~/.ssh/config 的 Host 直接可用),herdr 不存密码/密钥;带 passphrase 的 key 先 ssh-add
• client/server 版本不必一致(协商兼容);machine add 需要交互终端(安装/替换要审批,默认 No)
• 多机时 agent 行自动多出 machine 标签列
• 暂不支持 Windows 作 client;远端不支持 Windows server

轻量替代: herdr --remote workbox 一次性远端挂载(本地 UI + 远端 pane,剪贴板图片粘贴可桥接);手机上随便一个 SSH 客户端 + 远端跑 herdr 就是移动端方案(iOS 推荐 moshi)。

7. Agent 自动化(脚本/Agent 遥控 Agent)

三类原语: layout(建 workspace/tab/pane 布局)、pane(裸终端: run/send-text/send-keys/read/wait-output)、agent(按生命周期控制: start/prompt/wait/send-keys)。

7.0 让 pane 里的 agent 学会遥控: herdr skill(两件套,别搞混)

组件	安装方式	职责	本机状态(2026-09-17)
integration hook	herdr integration install claude	SessionStart 时把 claude 的 session_id/transcript 路径上报 herdr server(pane.report_agent_session),支撑 §5 的原生会话恢复	✅ 已装(v9, ~/.claude/hooks/herdr-agent-state.sh)
herdr skill	herdr --skill > ~/.claude/skills/herdr/SKILL.md(或 npx skills add herdrdev/herdr --skill herdr -g)	教 agent 全套 herdr CLI 遥控玩法+安全规则	✅ 已补装(0.9.0 随二进制自带副本)

⚠️ 只装 hook 不装 skill 时,agent 只能”碰巧知道”herdr CLI 而存在,行为不可靠;skill 才是遥控器说明书。skill 第一条护栏: HERDR_ENV=1 不成立时直接停手不碰会话。

skill 里的关键安全规则(摘录):

• 后台动作用 --no-focus,不抢用户焦点;目标用 --current/显式 pane id/唯一 agent 名,不依赖别的 client 的焦点
• ID 从 JSON 响应里解析,不从侧栏顺序/示例里猜
• 不关非自己创建的 workspace/tab/pane;workspace close --group 永不作为绕过手段
• 永不 herdr server stop、永不杀主进程;实验用 named session 隔离
• agent prompt 遇 agent_blocked 先读现场问用户,不擅自回答审批框
• 超时/stall ≠ 没发出去,重试前先 agent read 防重复提交

本机实测(pane p_42 内): pane current --current 精确回传本 pane 身份(含 hook 上报的 session id);agent list 40 个 agent 状态分布 39 idle + 1 working;跨 workspace agent read 直接读到隔壁 pane 现场;agent explain 打出判定依据(manifest=remote 热更新版 2026.09.11.1, 规则 live_prompt_box 命中 ❯ 提示符)。

7.1 经典配方

# 1. 建 workspace 起 agent 派活并等结果
created=$(herdr workspace create --cwd ~/project --label api --no-focus)
pane_id=$(jq -r '.result.root_pane.pane_id' <<<"$created")
herdr agent start reviewer --kind codex --pane "$pane_id" -- -m gpt-5.4
herdr agent prompt reviewer "Review the current diff" --wait --timeout 120000
herdr agent read reviewer --source recent-unwrapped --lines 120
 
# 2. 等 agent 卡住要审批,看现场,按键回应
herdr agent wait reviewer --until blocked --timeout 120000
herdr agent read reviewer --source recent-unwrapped --lines 80
herdr agent send-keys reviewer esc
 
# 3. 普通进程等输出(不当 agent 管)
herdr pane run w1:p3 "just test --watch"
herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000

易踩的坑:

• agent prompt 对已 blocked 的 agent 直接返回 agent_blocked 不发输入——先看现场再用 send-keys 回应
• 超时 ≠ 没发出去。重试前先 agent read,避免同一 prompt 发两遍
• Claude Code 这类全屏 agent 的历史在 alternate screen,agent read --lines N 超出一屏时会自动模拟鼠标滚轮翻页收集(仅 idle 态;working 时返回 agent_not_idle)
• 创建类命令都返回 JSON,ID 从响应里 jq,不要猜
• pane move 后 pane_id 会变(取 .result.move_result.pane.pane_id),但旧 id 仍作别名,--current 安全
• agent 名规则 [a-z][a-z0-9_-]{0,31},live 唯一;agent 退出即失效

直挂单个 agent(不进完整 UI): herdr agent attach reviewer,手机上看某个 agent 很方便。第三方桥接用 herdr terminal session observe/control <pane>(NDJSON 帧流)。

8. 插件系统

本地插件 = 一个目录 + herdr-plugin.toml manifest + 任意语言的可执行:

id = "example.workspace-tools"
name = "Workspace Tools"
version = "0.1.0"
min_herdr_version = "0.7.0"
 
[[actions]]
id = "list-workspaces"
title = "List workspaces"
contexts = ["workspace"]
command = ["node", "index.js"]        # argv 不过 shell,要 shell 自己起

能力面: actions(命令) / startup 钩子 / events(如 worktree.created) / 插件 pane(overlay 浮层) / link_handlers(正则匹配 URL 交给插件,如 GitHub issue 链接) / 键位绑定。插件里用 $HERDR_BIN_PATH 回调 herdr CLI。

herdr plugin link ./my-plugin          # 本地开发
herdr plugin install owner/repo[/subdir]   # 从 GitHub 装(marketplace 收录的)
herdr plugin list / action invoke / log list

市场逛法: 浏览器开 https://herdr.dev/plugins(Trending / New arrivals 货架)。

9. 配置精要(~/.config/herdr/config.toml)

本机当前生效配置(2026-09-16 调优后):

onboarding = false
 
[ui.sound]
enabled = false
 
# 侧栏条目间距: 0.9.0 默认去掉了空行,恢复旧版排版
[ui.sidebar.agents]
row_gap = 1
 
[ui.sidebar.spaces]
row_gap = 1

改完 herdr server reload-config 热加载(大部分 UI 项免重启)。

精选可用项:

[ui]
sidebar_width = 26            # 侧栏宽度(18~36 之间自动缩放,此为基准)
sidebar_collapsed_mode = "hidden"   # 收起时零宽(默认 compact 窄条)
agent_panel_sort = "priority"       # agent 面板按注意力排序(默认 spaces 分组)
window_title = "..."           # 外层终端标题同步会话
pane_borders = "always"        # pane 边框: always/auto/off
mouse_capture = false          # 不想被抢鼠标时
 
[ui.toast]                     # agent 完成/求输入弹通知
delivery = "herdr"             # herdr 内 toast / terminal(SSH 也能收) / system / off
 
[[keys.command]]               # 自定义键位命令: popup 浮窗/pane/shell/plugin_action
key = "prefix+alt+g"
type = "popup"
command = "lazygit"
width = "80%"
 
[worktrees]
directory = "~/.herdr/worktrees"   # 侧栏建 worktree 的根目录
 
[server]
headless_cols = 160            # 无 client 时的虚拟终端尺寸(默认 120x40)
headless_rows = 50
 
[update]
version_check = true           # 可关后台版本检查
manifest_check = true          # 可关 agent 检测规则热更新

侧栏行还可自定义令牌布局(两行/单行)与按值变色:

[ui.sidebar.agents]
rows = [["state_icon", "workspace", "agent"]]    # 压成单行,列表矮一半

10. 版本更新机制

herdr status          # 先看 server/client 版本、协议代际、restart_needed
herdr update          # 稳定频道原地升级;兼容 server 不动
herdr update --handoff   # 需要换 server 时热交接 pane 进程(实验性,opt-in)
herdr channel set preview  # 换 preview 频道追新

注意:

• Homebrew/mise/Nix 装的禁用 herdr update,走各自包管理器
• 升级后 integration 要同步: herdr integration install claude(session 恢复能力依赖它,版本要求见 §5 表)
• 跨 endpoint generation 的一次性升级无法无痛,--handoff 是唯一保进程路径(本机已验证)

11. 故障排查

• 三件套日志: ~/.config/herdr/herdr{,-client,-server}.log;加详细: HERDR_LOG=herdr=debug
• agent 状态不对: herdr agent explain <target>
• resize/split 后屏幕文字变形(幽灵行/错位): 已知未修 bug #3672(0.9.1 仍未修)。本质是 client 绘制层残留,retained grid 是干净的(herdr pane read --source visible 可验证)。恢复: 鼠标点击别的窗口再点回来(触发 focus-gained 全量重绘,ui.redraw_on_focus_gained 默认开),或 prefix+q detach 后重跑 herdr。pane_scrollbars=false 无效(那是 #3329 的 workaround,不同的 bug)。多显示器竖屏↔横屏拖动是高发触发路径(GNOME Terminal/Wayland 实测)
• 升级后会话还是旧的: 二进制升级不替换兼容的运行中 server,herdr server stop 后重开(会杀 pane,慎用)或 --handoff
• Enter/Tab/Backspace 连击两次: 外层终端太旧(kitty≥0.33.0 / foot≥1.20.0 / Alacritty≥0.15.0 修复),LTS 发行版仓库版高发
• 远端认证失败: 先裸 ssh <host> 验证;passphrase key 先 ssh-add
• Kitty 图形异常: terminal.kitty_graphics = false(0.9.0 起默认开)

12. 参考链接

• 文档索引(agent 可读): https://herdr.dev/llms.txt
• 配置全量 JSON reference: 见 llms.txt 中 config-reference.json
• Socket API 详表: socket-api.mdx(本指南未展开,45K 原文,脚本化深水区自取)
• 本机相关记忆: claude-unsafe 自动恢复机制见 ~/.bashrc 注释