58 lines
6.0 KiB
Markdown
58 lines
6.0 KiB
Markdown
# herdr
|
||
|
||
个人 herdr 配置与迁移笔记。配置由 `tmux/.tmux.conf` 映射而来。
|
||
|
||
- `config.toml` — 真实配置，经 `script/herdr-init.sh` 软链到 `~/.config/herdr/config.toml`
|
||
- 校验：`herdr config check`
|
||
- 热重载：`prefix+shift+r`（本配置改为 `prefix+r`）或 `herdr server reload-config`
|
||
- 默认值参考：`herdr --default-config`
|
||
- 官方速查：https://herdr.dev/docs/concepts/ ，给 agent 看的：`herdr --skill`
|
||
|
||
## 概念对照
|
||
|
||
| tmux | herdr | 说明 |
|
||
|---|---|---|
|
||
| session | workspace | herdr 的 workspace 对应“一个项目/任务”，侧栏按 workspace 汇总 agent 状态 |
|
||
| （无对应） | session | herdr 的 named session 是**独立的 server 命名空间**（`herdr session attach work`），跟 tmux 的 session 不是一回事 |
|
||
| window | tab | |
|
||
| pane | pane | 只能向右（right）或向下（down）切 |
|
||
| prefix mode | prefix mode (`ctrl+b`) | 相同；另有 terminal mode / navigate mode |
|
||
| status bar + 脚本 | sidebar | 鼠标可点、可拖分隔条、右键菜单 |
|
||
| （无对应） | agent | herdr 识别 pane 里的 coding agent，状态 `working`/`blocked`/`done`/`idle`/`unknown` |
|
||
| tmux-resurrect | session.json + `[experimental] pane_history` | 布局自动持久化，agent 原生会话恢复需要装 integration |
|
||
| tpm 插件 | 无插件系统 | fzf 类能力内建（`prefix+w` workspace picker、`prefix+g` goto）；自定义动作用 `[[keys.command]]` |
|
||
| tmux over ssh | `herdr --remote <ssh-target>` | 远端跑 server，本地 attach |
|
||
|
||
## 和 tmux 的主要差异
|
||
|
||
1. **鼠标优先**。所有交互都能用鼠标完成；键位是可选层。`prefix+?` 可实时列出当前所有有效绑定。
|
||
2. **agent 感知**。侧栏能看到每个 pane 里的 agent 状态，`blocked`（等你审批/回答）会被顶到前面。tmux 只能靠 pane 标题自己写。
|
||
3. **CLI + 本地 socket API**。`herdr pane split/run/read/wait-output`、`herdr agent prompt/wait` 这类命令可以从脚本或 agent 内部驱动布局和读输出，tmux 的 `send-keys` 做不到等待与状态判定。
|
||
4. **配置是单个 TOML**，没有插件系统，也没有 `run-shell` 状态栏脚本；但支持
|
||
`[[keys.command]]` 自定义命令（`type = "shell"` / `"pane"` / `"popup"`，可指定宽高百分比），基本能覆盖原来用插件/脚本做的事。
|
||
5. **直接快捷键**。除 `prefix+...` 外还支持 `ctrl+alt+...` 这类直通键位（适合想摆脱 prefix 的用法）。反过来，被 OS 或外层终端占用的组合 herdr 收不到，表现为“绑了没反应”。
|
||
6. **没有 `escape-time` / `terminal-overrides` / 真彩色开关**。那些是 tmux 作为终端适配层才需要的，herdr 自己处理能力协商。通知走 `[ui.toast] delivery`，剪贴板走 `[ui] copy_on_select`。
|
||
7. **不支持嵌套启动**（`experimental.allow_nested = false`）：herdr pane 里再跑 `herdr` 会被拒绝。tmux 里 `tmux` 是能套的。
|
||
8. `[remote] manage_ssh_config` 默认开启：`herdr --remote` 会生成一份私有 ssh config，**先 include 你的 `~/.ssh/config`**，再补 `ServerAliveInterval`/`ServerAliveCountMax` 兜底，并用私有 control socket 复用连接。所以 `~/.ssh/config` 里已有的 keepalive 仍然优先，我们的 `Include ~/.ssh/config.d/*` 也照常生效。
|
||
|
||
## 切换时的注意事项
|
||
|
||
- **分屏按分隔线的形状记**：`|` 是竖线 → 切成左右；`-` 是横线 → 切成上下。herdr 就是按形状命名的（`split_vertical` = 竖线 = 向右切，`split_horizontal` = 横线 = 向下切），而 tmux 的 `splitw -v/-h` 按“排列方向”命名，两者相反：tmux `splitw -v`（上下堆叠）对应 herdr `split_horizontal`，tmux `splitw -h`（左右并排）对应 `split_vertical`。本配置按形状对齐（`-` 上下、`|` 左右）。
|
||
- **`herdr` 裸跑会 attach；`herdr server` 是前台 headless server**。别为了“看看帮助”敲 `herdr server`——它不返回，会把调用它的地方永久挂住（踩过一次：pi 的 bash 工具卡了 46 分钟）。要看帮助用 `herdr --help`、`herdr <group>`（如 `herdr pane`）；停 server 用 `herdr server stop`。
|
||
- **prefix 都是 `ctrl+b`**，两套配置不冲突，但同时开难免按错。切过去之前建议先退掉 tmux，避免双层状态栏/双层 prefix。
|
||
- **没有 `-c '#{pane_current_path}'` 这个开关**：新建 pane/tab 的目录策略在 `[terminal] new_cwd`（`follow` / `home` / `current` / 固定路径），本配置是 `follow`。
|
||
- **resize 步长不可配**。tmux 那边是固定 10 格；herdr 直接绑定（本配置 `prefix+shift+hjkl`）用默认步长，或 `prefix+r` 进 resize mode 再动。
|
||
- **`mouse on/off` 没有运行时快捷键**：由 `[ui] mouse_capture` 决定，运行时去 `prefix+s` 设置面板改。用 `copy_on_select = false` 可以在拖选后保留选区，等 `Ctrl+C` 再复制。
|
||
- **复制模式**：`mode-keys vi` 在 herdr 没有等价配置。本配置给 `copy_mode` 绑了 `prefix+[`（herdr 0.8.2 支持该校验通过，但未写进 `--default-config`），复制模式的内部键位不可配；平时直接鼠标拖选即可。想把 scrollback 丢进 `$EDITOR` 用 `prefix+e`。
|
||
- **中文/IME**：如果你在 pane 里用 pi/claude/codex 这类自绘光标的 TUI 遇到输入法候选框错位，可试开
|
||
`[experimental] reveal_hidden_cursor_for_cjk_ime = true`（可用 `cjk_ime_agents` 限定只对某些 agent 生效）。默认关闭。
|
||
- **别再跑 tpm**：`script/tmux-init.sh` 会克隆 tpm 并装插件，那是 tmux 的；herdr 不需要。两套可以并存，但别指望插件搬到 herdr。
|
||
- **升级**：`herdr update`（stable 通道）；0.8.2 → 0.9.0 已经可用。用包管理器装的则走包管理器。
|
||
|
||
## 迁移状态
|
||
|
||
- [x] `herdr/config.toml`（tmux 键位/UI 行为映射，`herdr config check` 通过）
|
||
- [x] `script/herdr-init.sh`（软链 + 备份 + 幂等 + 校验）
|
||
- [ ] 装 agent integration（`herdr integration install claude` 等），才有原生会话恢复与状态上报
|
||
- [ ] 需要时启用 `reveal_hidden_cursor_for_cjk_ime`
|