会话状态与恢复
Herdr 有多条状态路径,它们解决的是不同的问题。
什么能保留下来
Section titled “什么能保留下来”| 场景 | 进程继续运行 | 布局恢复 | 最近的屏幕内容恢复 | 智能体对话恢复 |
|---|---|---|---|---|
| 分离并重新连接 | 是 | 是 | 是,来自实时终端 | 是,因为进程从未停止 |
| 服务器重启 | 否 | 是 | 仅在开启窗格屏幕历史时 | 仅在有智能体原生会话恢复时 |
不带 --handoff 的更新 | 兼容的服务器继续运行;需要重启的服务器可能要停止/重启 | 重启后恢复 | 仅在开启窗格屏幕历史时 | 仅在有智能体原生会话恢复时 |
带 --handoff 的更新 | 对受支持的运行中服务器尽力而为 | 是 | 是,交接成功时来自实时终端 | 是,交接成功时进程保持运行 |
下面的小节逐一解释这些路径。
普通分离会让 Herdr 服务器继续运行。窗格、shell、智能体、服务器、测试和命令进程都在该服务器中继续运行。
用 ctrl+b q 分离客户端。之后重新连接:
herdr这是最强的持久化路径,因为原始进程从未停止。
如果 Herdr 服务器停止后再启动,原来的窗格进程已经不在了。Herdr 会恢复保存的会话形态: 工作区、标签页、窗格、cwd、布局和焦点。
快照恢复不会保留运行中的 shell、服务器、测试或任意进程。无法使用更强恢复路径的窗格,会在各自保存的目录中作为新 shell 回来。
如果保存的目录不可用或 shell 无法启动,窗格会留在布局中并显示错误,而不是消失或切换到主目录。保存的目录和智能体会话引用仍会保留。修复目录或 shell 配置后,重启服务器即可重试;也可以明确关闭窗格将其移除。
保存时,如果操作系统支持查询,Herdr 会优先使用正在运行的 shell 的目录,并在 shell 退出后保留最后确认的目录。在其他平台上,则使用 shell 报告的目录。
如果无法读取或解析 session.json，或该文件需要更新的 Herdr 版本，Herdr 会记录加载失败的原因。在保存或清除新会话之前，Herdr 会将原始文件逐字节保存到 session.json 旁的 session-backups/ 中，并通过 persist.backup 记录恢复副本的路径。即使启动时文件不存在，也会在首次保存或清除前再次检查。这些加载失败时的恢复副本与常规快照历史分开管理。
Herdr 保留最新的三个恢复副本，只有在新副本安全写入后才删除旧副本。如果无法保存副本，自动保存和退出保存都不会修改原始文件，并会记录错误，在下一次保存请求时重试。副本不会自动恢复。如需恢复，请停止对应的服务器，将恢复文件复制到该服务器的 session.json，然后重启。恢复副本不包含窗格屏幕历史。
关机与快照恢复
Section titled “关机与快照恢复”在使用 systemd-logind 的 Linux 系统上，Herdr 会监听主机关机预告，并请求短暂延迟，以便保存并停止服务器，随后 logind 才继续关机。延迟由操作系统限制，不会无限阻止关机。此保护不适用于没有 logind 的系统、强制关机、断电，或进程在预告到达前已被终止的情况。
在所有平台上，Herdr 还会在 session.json 旁的 session-snapshots/ 中保留最多 48 个布局快照。首次保存的布局会立即复制。之后的保存或清除操作会复制之前保存的布局，最多每 15 分钟一次，不重复保存相同内容。此间隔在服务器重启后仍然有效，因此连续的窗格退出或重启不会挤掉所有旧快照。最近的更改可能尚未包含在快照中。
正常关闭窗格仍会更新 session.json，不会出现恢复提示，也不会自动恢复旧布局。如需手动恢复：
- 用
herdr session list --json找到对应的会话目录。 - 停止对应的服务器：默认会话用
herdr server stop，命名会话用herdr session stop <name>。 - 先另存当前的
session.json，再将session-snapshots/中选定的文件复制到session.json。文件修改时间表示快照的保存时间。 - 重新启动该会话。
快照包含布局和代理会话引用，不包含运行中的进程或窗格屏幕历史。请将其视为私密会话数据。快照写入失败会记录到日志，但不会阻止主会话文件的正常保存。
窗格屏幕历史回放
Section titled “窗格屏幕历史回放”窗格屏幕历史在服务器完全重启后恢复最近的终端内容。它恢复的是 Herdr 能展示的内容,而不是原来的进程。
它默认关闭,因为窗格输出可能包含密钥、令牌、提示词和命令输出。可以在配置文件中开启:
[experimental]pane_history = true开启后,Herdr 把保存的窗格历史存放在 session.json 旁边的 session-history.json 中。请像对待终端历史一样对待 Herdr 的配置/会话目录。
只有与保存的布局完全匹配的历史才会回放。来自其他布局的历史,包括手动恢复快照后不再匹配的历史,都会被忽略。无法验证布局的旧版历史文件也会被忽略;新保存的历史可在下次重启时回放。
智能体原生会话恢复
Section titled “智能体原生会话恢复”一些智能体可以恢复它们自己的对话会话。Herdr 可以使用官方集成上报的会话引用,在 Herdr 服务器重启后重新启动受支持的智能体窗格。
这默认开启。关闭方法:
[session]resume_agents_on_restore = falseHerdr 会恢复通过当前官方 Herdr 集成上报了原生会话引用的窗格,以及智能体自己上报了恢复命令的窗格。参阅为你的智能体添加 Herdr 支持。
当客户端连接并提供终端尺寸和主题上下文后,Herdr 会跨工作区和标签页恢复符合条件的智能体窗格,不需要等每个窗格被聚焦。
智能体原生会话恢复需要以下版本或更新的 Herdr 集成:
| 智能体 | 最低 Herdr 集成版本 | 恢复命令 |
|---|---|---|
| Pi | 2 | pi --session <path-or-id> |
| OMP | 3 | omp --resume=<path-or-id> |
| Claude Code | 6 | claude --resume <id> |
| Codex | 5 | codex resume <id> |
| Cursor Agent CLI | 1 | cursor-agent --resume <id> |
| Grok CLI | 2 | grok --resume <id> |
| GitHub Copilot CLI | 2 | copilot --resume=<id> |
| Devin CLI | 2 | devin --resume <id> |
| Droid | 2 | droid --resume <id> |
| Kimi Code CLI | 3 | kimi --session <id> |
| Qoder CLI | 2 | qodercli --resume <id> |
| Qwen Code | 1 | qwen --resume <id> |
| Letta Code | 1 | letta --conversation <id>,或对 default:<agent-id> 使用 letta --conversation default --agent <agent-id> |
| OpenCode | 5 | opencode --session <id> |
| Kilo Code CLI | 1 | kilo --session <id> |
| Hermes Agent | 2 | hermes --resume <id> |
| MastraCode | 1 | mastracode --thread <id> |
运行 herdr integration status 查看已安装的集成版本。用 herdr integration install <agent> 重新安装过期的集成。
不受支持、缺失、无效、重复或过期的会话引用,会在保存的窗格目录中作为普通 shell 恢复。
如果某个窗格适用智能体原生会话恢复,Herdr 会对该窗格恢复智能体会话,而不是回放保存的窗格历史。
实时交接用于需要替换运行中 Herdr 服务器的更新和远程连接流程。它请求旧服务器把实时窗格转移给新服务器,让窗格进程跨服务器替换继续运行。
这与快照恢复、窗格历史回放和智能体原生会话恢复不同。交接尝试让当前进程活下去,其他路径则是在旧服务器已经停止之后重建状态。
交接保护的是由服务器拥有的长期会话状态:窗格 PTY 和进程、智能体身份与持久元数据,以及替换服务器所需的插件/会话状态。它不会跨替换边界保留临时协调状态。进行中的 CLI 或 API 请求、等待、订阅流、客户端套接字和窗格间消息可能会中断;客户端应重新连接并重试。
更新后的 Unix 服务器可以分批传输，在一次交接中发送超过 64 个窗格。发送方服务器必须已经支持此功能；从旧服务器进行第一次升级时，仍受其原有的 64 窗格限制。此时可能需要正常重启服务器，这会结束窗格进程。分批传输不会改变更新的安装顺序，也不会取消其他交接兼容性要求。
实时交接是实验性功能,需要主动开启:
herdr update --handoffherdr --remote workbox --handoff普通的 herdr update 会安装新客户端,并让端点第 1 代服务器继续运行。普通的 herdr --remote workbox 也会在版本不同时保留兼容的远程服务器。只有从早于第 1 代的服务器做一次性升级时才需要停止;如果要在不结束窗格进程的情况下明确替换受支持的运行中服务器,请使用 --handoff。
herdr update --handoff 只适用于由 Herdr 自带更新器管理的安装。Homebrew、mise 和 Nix 安装通过各自的包管理器更新,因此那些安装中 herdr update 被禁用,无法执行实时交接。