Update README for tmux isolation, CLI entries and version notes

Document that the Hub server does not read ~/.tmux.conf and how to opt
into a custom file, list the control and keys subcommands, describe the
background local-session query and corrupt-aliases behaviour, and
rephrase the "Herdr 0.8.2" statements as design-time notes so they no
longer contradict the 0.9+ requirement.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
2026-10-03 03:09:28 +00:00
co-authored by Claude Fable 5.1
parent ac6bb30f47
commit 1a4cb1f2ca
+16 -9
View File
@@ -4,7 +4,7 @@
把每个本地或 `herdr --remote` attach 放进独立 tmux window,并在 Herdr 画面顶部
显示可点击的 Sessions 条。
它不是 Herdr 插件,也不会修改 Herdr core。Herdr 0.8.2 的插件 API 不能向原生
它不是 Herdr 插件,也不会修改 Herdr core。设计本工具时的 Herdr(0.8.2)插件 API 不能向原生
sidebar 插入 UI,也不能让 thin client 从一个 server 原地改连另一个 server;
所以顶部状态栏横跨整个终端,而不是只嵌在 Spaces 上方。
@@ -20,7 +20,7 @@ sidebar 插入 UI,也不能让 thin client 从一个 server 原地改连另一
- 可隐藏不再需要的 Tab,而不停止底层本地或远端 Herdr Session。
- 可在 Sessions 管理弹窗中为 Tab 设置持久化显示名称,或恢复默认名称。
- dead window 留在顶栏,可原地重连。
- 不修改 `~/.tmux.conf`,不保存 SSH 凭据或远端 Session 缓存。
- 不读取也不修改 `~/.tmux.conf`:Hub 的 tmux server 以 `-f /dev/null` 启动,用户主题和按键绑定不会渗入;不保存 SSH 凭据或远端 Session 缓存。
## 依赖
@@ -88,7 +88,10 @@ herdr-hub open --session work
## 日常操作
Hub 使用独立 tmux socket `herdr-hub`,不会接管普通 tmux server。外层前缀固定为
`Ctrl+A`,Herdr 原来的 `Ctrl+B` 可以直接使用。
`Ctrl+A`,Herdr 原来的 `Ctrl+B` 可以直接使用。Hub server 不读取 `~/.tmux.conf`,
因此主题的 `status-format` 和 root 表按键不会覆盖顶栏或抢占 Herdr 的按键;如需附加
自定义配置,设置 `HERDR_HUB_TMUX_CONFIG=/path/to/file` 后重新启动 Hub(`herdr-hub stop`
再执行 `herdr-hub`)。
| 操作 | 快捷键 / 命令 |
| --- | --- |
@@ -186,7 +189,8 @@ Windows 普通更新会补读远端用户和系统的代理环境变量。
## 远端 Session 弹窗
弹窗由 tmux `display-popup` 和 Hub 内置选择器组成,不依赖 fzf。它会立即显示已打开的
window,同时在后台并行查询所有已登记远端;每台机器的结果就绪后原地更新。
window,同时在后台查询本机 Session 列表,并并行查询所有已登记远端;每项结果就绪后
原地更新。
主页面只显示 Session 和两个全局入口。大多数主机只有 `default` Session,因此默认只显示
主机名;有命名 Session 时显示为 `主机 / Session`。本机同样显示为“本机”或
@@ -222,7 +226,7 @@ Tab,也不停止远端 Herdr server。
也会一并关闭。运行中的 Session 需先“关闭并停止”,Herdr 永久保留的 `default` Session
不能删除。
Herdr 0.8.2 不支持 Windows 作为原生 `herdr --remote` 的目标主机。Hub 查询到 Windows
设计本工具时的 Herdr(0.8.2)不支持 Windows 作为原生 `herdr --remote` 的目标主机。Hub 查询到 Windows
Session 后会标记为“Windows · SSH 模式”,并自动改为 `ssh -tt target herdr`;命名
Session 会在远端运行 `herdr --session NAME`。这种模式仍支持 Tab 切换、detach、断线
重连和远端工作现场持久化,但使用远端 Herdr 的 keybindings,也没有原生 thin client
@@ -257,12 +261,13 @@ herdr-hub remote remove orangepi
## Session 显示名称
Herdr 0.8.2 没有底层 Session rename 命令,因此 Hub 的“重命名”是安全的显示名称:
设计本工具时的 Herdr(0.8.2)没有底层 Session rename 命令,因此 Hub 的“重命名”是安全的显示名称:
顶部 Tab 和 Sessions 弹窗显示新名称,attach、重连和工作现场仍绑定原来的 Session ID。
名称会跨终端断线、Hub detach 和 `herdr-hub stop` 保留,并在重新打开 endpoint 时自动
应用。配置保存在 `~/.config/herdr-hub/aliases.json`(遵循 `$XDG_CONFIG_HOME`),
权限为 `0600`;留空保存会删除该 endpoint 的显示名称并恢复 `local/work`、
`host/work` 等默认格式。
`host/work` 等默认格式。名称可以是任意不含控制字符的文本。若该文件损坏,Hub 会给出
警告并暂时使用默认名称,`herdr-hub doctor` 会报告具体错误。
## 复制与剪贴板
@@ -325,6 +330,8 @@ herdr-hub open [--session NAME]
herdr-hub open --remote TARGET [--session NAME]
[--remote-keybindings local|server] [--transport native|ssh]
herdr-hub choose
herdr-hub control [--window ID]
herdr-hub keys
herdr-hub remote list
herdr-hub remote add TARGET [--remote-keybindings local|server]
[--transport native|ssh]
@@ -357,8 +364,8 @@ herdr-hub stop
- 可执行文件不叫 `herdr`。
这些场景可在弹窗中选择“添加远端”,或使用 `herdr-hub open --remote …`。为了避免嵌套 tmux 与前缀冲突,
`herdr-hub` 应从普通终端启动;若当前已经在另一个 tmux server 中,它会拒绝再次
attach。
`herdr-hub` 应从普通终端启动;若当前已经在另一个 tmux server 中,它会在扫描或创建
Hub 之前直接拒绝。
## 开发与测试