herdr 实践指南：编码智能体驻留的终端运行时——安装、重连与源码原理

herdr 是一个运行在你终端里的"智能体复用器"（terminal workspace manager for AI coding agents），负责持有各编码智能体的终端（PTY），让多个 agent 始终处于可观测、可重连的状态。本文以仓库中文 README 为骨架，覆盖安装方式、分离/重连工作流、智能体状态检测、Socket API、插件与本地开发流程，并结合 Cargo.toml、src/server/autodetect.rs、src/detect/manifests/claude.toml 等源码实现，解释每个特性的底层原理。读完你应能完成安装、日常使用、配置查阅与从源码构建验证。

定位：一句话看懂 herdr 是什么

README.zh-CN.md 把 herdr 概括为"智能体复用器，住在你的终端里"，Cargo.toml 中的官方描述则是 terminal workspace manager for AI coding agents。它的核心卖点在 README 中逐条列出，每一条都能在仓库源码中找到对应实现：

• 每个智能体一目了然——每个窗格标记 working、blocked、idle。这不是猜测，而是基于屏幕内容的规则引擎：src/detect/manifests/ 下为每个受支持智能体提供 TOML 检测清单（claude、codex、cursor、opencode、grok、gemini、droid、copilot、kimi、kiro、amp、antigravity、cline、devin、github-copilot、hermes、kilo、maki、muse、pi、qodercli、qwen 等），用正则匹配终端屏幕特定区域（OSC 标题、底部 N 行、提示框正文等）来判定状态，详见下文"智能体状态检测"一节。
• 分离后智能体继续运行——从任意终端重连，或通过 ssh；会话在重启后保留。对应"always running"设计：herdr 是一个后台 server，终端活在 server 里（见 src/server/autodetect.rs 的注释说明）。
• 智能体也能使用 herdr——纯 socket API：智能体可以创建窗格、读取输出、互相等待。技能文件随二进制内置，见 skills/herdr/SKILL.md（src/main.rs 在编译期 include_str! 打包，herdr --skill 直接打印）。
• 键盘和鼠标都是一等公民——tmux 风格前缀键，以及点击、拖动、分割。
• 插件——扩展窗格和工作流；仓库内 workers/plugin-marketplace/ 是插件市场的 Cloudflare Worker 实现。
• 单个 Rust 二进制，没有 Electron——运行在你已经在用的任何终端里。

安装

README 给出的官方安装方式是：

curl -fsSL https://herdr.dev/install.sh | sh

该脚本的仓库源文件就是 website/install.sh（Windows 侧为 website/install.ps1）。除此之外还有多种等效途径：

• brew install herdr（Homebrew）
• mise use -g herdr（mise 版本管理器）
• Windows：powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
• 受端点保护（endpoint-protected）的 Windows 环境，对应文档位于 docs/next/website/src/content/docs/windows-beta.mdx，中文版本在 docs/next/website/src/content/docs/zh-cn/ 下
• 或直接取用 release 二进制

README 同时强调：Windows 预览构建默认处于 preview 更新通道（见 src/main.rs 中 DEFAULT_CONFIG 的 [update] 注释，stable 构建默认 stable 通道），可用 herdr channel set <stable|preview> 显式切换。

首次启动与分离/重连：源码级工作流

安装后，在工作目录直接运行：

herdr

运行你的智能体、分割窗格，然后安心离开：ctrl+b q 分离（detach），再次 herdr 重连。这一"输入一次 herdr 即可自动接回"的行为，在 src/server/autodetect.rs 的模块注释中写得很明确，其启动决策链路为：

1. 检查客户端 socket 上是否已有 server 在监听（is_server_listening，src/server/autodetect.rs#L47-L92）；
2. 若无 server，则拉起一个后台守护 server，并轮询等待 socket 就绪（最长 15 秒，SERVER_READY_TIMEOUT，轮询间隔 50ms）；
3. 以瘦客户端（thin client）身份 attach 到 server。

几个可验证的实现细节：

• 陈旧 socket 处理：server 崩溃后留下的 socket 文件会被识别——连接返回 ConnectionRefused 即判定"无人在监听"，从而走重新拉起路径（见 src/server/autodetect.rs#L65-L90）。
• 启动目录继承：新拉起的 server 通过环境变量 HERDR_STARTUP_CWD 记录你运行 herdr 的目录（src/server/autodetect.rs#L31-L33），保证工作空间落在预期位置。
• 逃生舱口 --no-session：完全绕过 server/client 架构，跑成单进程单体模式（src/main.rs#L827-L842），这是为测试与排障保留的"pre-mission 单进程行为"。
• 嵌套保护：默认禁止在 herdr 管理的窗格里再启动 herdr——启动时检查环境变量 HERDR=1（HERDR_ENV_VAR，src/main.rs#L11-L12），若已在 herdr 内部则拒绝启动并打印一条随机"彩蛋"提示；确有需要时可用 [experimental] allow_nested = true 打开。

命名会话（named sessions）

除默认会话外，herdr 支持命名持久会话：herdr --session <name>、herdr session attach <name>。会话名上限 64 字符、默认名 default、环境变量 HERDR_SESSION 可在 shell 间传递当前会话（src/session.rs#L9-L14），解析入口 configure_from_args 会在最前端预处理 --session / --session= 两种写法（src/session.rs#L29-L94）。会话状态文档见 docs/next/website/src/content/docs/session-state.mdx（中文版 session-state.mdx）。

常用 CLI 一览

herdr --help 输出的完整用法（来自 src/main.rs#L625-L739）：

herdr [options]
herdr --session <name> [options]
herdr --remote <ssh-target> [--session <name>]
herdr session attach <name>
herdr completion <shell>
herdr update [--handoff]
herdr channel set <stable|preview>
herdr server stop
herdr server reload-config
herdr api <subcommand> ...
herdr config <subcommand> ...
herdr workspace <subcommand> ...
herdr worktree <subcommand> ...
herdr tab <subcommand> ...
herdr notification <subcommand> ...
herdr agent <subcommand> ...
herdr pane <subcommand> ...
herdr integration <subcommand> ...

常用命令速查（README 之外的补充，全部可在 --help 中查到）：

命令	作用
herdr	启动或 attach 到持久会话
herdr status [server|client]	显示本地 client 与运行中 server 的状态
herdr update	下载并安装最新版本
herdr server stop	经 API socket 停止运行中的 server
herdr server reload-config	让运行中的 server 重新加载 config.toml
herdr config reset-keys	备份 config.toml 并移除自定义键位
herdr completion zsh	生成 shell 补全
herdr --default-config	打印默认配置（src/main.rs#L747-L751）
herdr --skill	打印 agent skill 文件

其中 workspace / worktree / tab / agent / pane / notification / api 等子命令都是"socket API 之上的助手"（socket API helpers），这正是 README 所说"智能体也能使用 herdr"的入口——智能体通过 CLI 与 socket API 驱动 herdr：创建窗格、提示（prompt）其他 agent、等待另一个 agent 真正进入 blocked 状态。

智能体状态检测：working / blocked / idle 是怎么判定的

README 第一条卖点"每个智能体一目了然"依赖的检测系统，源码在 src/detect/。每个智能体一份 TOML 清单，以 src/detect/manifests/claude.toml 为例，每条规则（[[rules]]）声明四要素：

• state：判定结果（working / blocked / idle / unknown）；
• priority：优先级数值，高优先级规则先命中（如 osc_title_working 为 1100，live_blocked_form 为 980）；
• region：屏幕区域，如 osc_title（OSC 转义上报的标题）、bottom_non_empty_lines(12)（底部 12 个非空行）、prompt_box_body、after_last_horizontal_rule 等；
• 匹配条件：regex / line_regex / contains / any / all / not（负向排除）。

举两个直观规则：osc_title_working 通过 OSC 标题以 braille 字符或半圆字符开头识别"忙碌中"（注释说明 braille 覆盖 <= 2.1.227 版本，半圆是 2.1.228 起的 busy spinner）；bash_permission_prompt 则用 "do you want to proceed?" + "bash command" 组合加 yes/no 选项行正则，判定 agent 卡在权限确认上，即 blocked（src/detect/manifests/claude.toml#L159-L175）。

这些清单并非静态：[update] manifest_check = true（默认开启）会让 herdr 在后台检查 herdr.dev 上的远程清单更新；skip_state_update、visible_blocker 等字段区分"仅展示标签"与"真正改变会话状态"的规则。受支持智能体列表与图标在 website/agent-detection/（如 website/agent-detection/claude.toml、website/agent-detection/index.toml），文档页为 docs/next/website/src/content/docs/agents.mdx（中文版 agents.mdx）。

配置：路径、默认值与热加载

配置文件位于 ~/.config/herdr/config.toml，HERDR_CONFIG_PATH 环境变量可覆盖路径（herdr --help 尾部即打印实际路径）。用 herdr --default-config 或 justfile 的 just default-config 可打印完整默认配置，其内容编译期固化在 src/main.rs 的 DEFAULT_CONFIG 中，涵盖以下主要区块：

• [theme]：内置主题（catppuccin、tokyo-night、dracula、nord、gruvbox、one-dark、solarized、kanagawa、rose-pine、vesper、terminal 等），auto_switch 跟随宿主终端明暗，[theme.custom] 可覆盖单个颜色 token；
• [terminal]：新交互窗格使用的 shell（default_shell，空则 $SHELL 回退 /bin/sh）、shell_mode（auto/login/non_login）、新窗格 CWD 策略 new_cwd（follow/home/current 或固定路径）；
• [update]：channel（stable/preview）、version_check、manifest_check；
• [keys]：前缀键（默认 ctrl+b）与全部前缀动作绑定，支持 prefix+n 前缀语法与 ctrl+alt+n 直连语法；[[keys.command]] 可把任意命令绑定为 shell（后台执行）、pane（临时窗格）或 popup（会话模态终端）三种类型；
• [server]：无客户端连接时虚拟终端尺寸（headless_cols/headless_rows，默认 120x40）；
• [ui]：侧边栏宽度、移动端单栏阈值（mobile_width_threshold，默认 64 列）、鼠标捕获、选中即复制、窗格边框/滚动条/间隙、tab 栏位置与右侧状态项（tab_bar_right，支持 zoom/hostname/datetime/text/command）、window_title 模板（{hostname}、{workspace}、{tab} 等 token）、agent 面板排序（spaces 或 priority 注意力队列）、[ui.toast] 通知投递方式（off/herdr/terminal/system）、[ui.sound] 背景工作区声音提示（支持 done_path/request_path 自定义 mp3，仓库自带 assets/sounds/done.mp3 与 assets/sounds/request.mp3）；
• [session]：resume_agents_on_restore（默认 true）——server 重启后把受支持 agent 窗格恢复到其原生会话，需要官方集成上报 session ref；
• [remote]：manage_ssh_config（默认 true）——herdr 为 herdr --remote 生成私有 ssh 配置，优先保留你 ~/.ssh/config 中的设置，追加 ServerAliveInterval/ServerAliveCountMax 兜底防 NAT 超时，并用每 attach 一个的私有 OpenSSH control socket 复用已认证连接；
• [experimental]：allow_nested、kitty_graphics、pane_history，以及面向 CJK 输入法的 switch_ascii_input_source_in_prefix、reveal_hidden_cursor_for_cjk_ime（含 cjk_ime_agents 白名单与光标形状）；
• [advanced]：scrollback_limit_bytes（默认 10000000，对齐 Ghostty 的 scrollback-limit 行为）。

运行中改完配置无需重启：herdr server reload-config 让 server 热加载，或按 prefix+shift+r（reload_config 默认绑定）。配置参考的完整版见 docs/next/website/src/content/docs/config-reference.mdx 与机器可读的 website/src/data/config-reference.json。

远程访问与持久化

README 将"远程访问"单列为文档入口（persistence-remote.mdx）。启动参数层面：

• herdr --remote <ssh-target>：经 SSH attach 远端 herdr server；--remote-keybindings <local|server> 控制远端 app attach 时键位由本地还是 server 解释（默认 local）；--handoff 为更新或远端 attach 启用 live handoff；
• 隐藏入口 herdr remote-client-bridge 与 herdr server（headless server）见 src/main.rs#L584-L590。

"关闭笔记本、断网甚至重启机器后 agent 继续工作、会话回归"的前提是：终端运行在后台 server 进程内而非你的 shell 里，detach 只是断开 UI 连接。

键盘与鼠标

默认键位遵循 tmux 风格前缀键模型（ctrl+b 进入前缀模式）：q 分离、c 新 tab、v 垂直分割、minus 水平分割、x 关窗格、h/j/k/l 焦点移动、z 全屏、r 进入 resize 模式、w 工作空间选择器等，完整清单即上文 [keys] 默认配置。鼠标侧由 [ui] mouse_capture、copy_on_select、right_click_passthrough_modifier 等控制；prefix + 数字 直切 tab（switch_tab = "prefix+1..9"）。按键矩阵与验证脚本见 scripts/capture_key_matrix.py、scripts/verify_suspicious_keys.py，键盘文档见 keyboard.mdx。

插件与 Socket API

插件系统用于扩展窗格与工作流，清单格式示例见 tests/fixtures/plugin-smoke/herdr-plugin.toml，插件应用 API 实现集中在 src/app/api/plugins/（manifest、context、runtime、panes），市场后端为 workers/plugin-marketplace/src/index.ts。Socket API 的完整方法面有 JSON Schema 定义：docs/next/api/herdr-api.schema.json，对应 Rust 侧 schema 模块在 src/api/schema/（agents、panes、tabs、workspaces、worktrees、events、session 等按域拆分），API 客户端封装在 src/api/client.rs。面向智能体的用法指南（agent skill）即 skills/herdr/SKILL.md，文档见 socket-api.mdx 与 agent-skill.mdx。

单一 Rust 二进制的技术构成

"单个 rust 二进制，没有 electron"在 Cargo.toml（当前版本 0.8.2）中体现为一条紧凑的依赖链：

• 渲染：ratatui 0.30（TUI 框架）+ crossterm 0.29（终端事件与能力协商）；
• PTY：portable-pty（以 [patch.crates-io] 指向仓库内 vendor/portable-pty 的 vendor 副本，保证跨平台一致性），Windows 侧额外依赖 ConPTY 相关组件，打包脚本见 scripts/package_windows_conpty.py 与 packaging/windows/conpty.json；
• 异步运行时：tokio（rt-multi-thread、process、io-util）；
• CLI：clap + clap_complete（shell 补全生成）；
• IPC/协议：interprocess（本地 socket）、bincode + serde（二进制线协议，src/protocol/wire.rs）、serde_json（JSON API）。

工具链由 rust-toolchain.toml 锁定为 Rust 1.96.1（含 clippy、rustfmt 组件）。

从源码构建与开发验证

README 给出的开发流程（配合 justfile 理解每一步实际做什么）：

git clone https://github.com/herdrdev/herdr
cd herdr
cargo build --release

just test        # 单元测试
just check       # 格式检查、测试和维护性检查

源码可确认的更多细节：

• just test 实际执行 cargo nextest run --locked（单元与集成测试）+ 一批 Python 维护脚本测试（清单检查、changelog、配置参考校验、文档翻译一致性等）+ UI 热路径架构边界测试 + 集成资产测试（bun 跑 src/integration/assets/ 下的状态上报脚本）+ 插件市场 Worker 测试（justfile#L3-L9）；
• just check 在 unix 上等价于 CI 全套：cargo fmt --check、cargo clippy --all-targets -- -D warnings、nextest、Windows 目标交叉 lint（在 unix/macOS 上对 x86_64-pc-windows-msvc 跑 clippy，提前拦截 cfg(windows) 编译错误），见 justfile#L31-L53；
• just ci 是 PR 级检查，just bench-render-scale / just bench-release-smoke 是发版前的渲染扩展性与端到端 CPU 冒烟；
• 仓库自带 Nix 包（nix/package.nix、flake.nix），可作为无 Rust 工具链环境的构建路径。

集成测试覆盖 server/client 生命周期，如 tests/detach_reattach.rs、tests/multi_client.rs、tests/live_handoff.rs、tests/server_headless.rs，与上文"分离/重连"卖点一一对应。

文档索引、智能体须知与许可证

完整文档按语言分目录维护于 docs/next/website/src/content/docs/（英文）与 zh-cn/、ja/，README 的链接索引对应到仓库路径如下：

README 链接	仓库文档
快速开始	quick-start.mdx
核心概念	concepts.mdx
受支持的智能体	agents.mdx
键盘	keyboard.mdx
配置	configuration.mdx
会话状态	session-state.mdx
远程访问	persistence-remote.mdx
集成	integrations.mdx
插件	plugins.mdx
Socket API	socket-api.mdx

README.zh-CN.md 还包含两条面向仓库协作者的约定：协助本仓库的 AI 智能体在改动代码前阅读 AGENTS.md，在创建 issue 或 PR 前阅读 CONTRIBUTING.md；致谢与支持者列表见 SPONSORS.md。herdr 基于 Apache License 2.0 发布。