怎么跑起来
升级之前要备份的东西
升级不是换二进制,而是迁移状态。值得存四样:config.yaml(新版本会按自己的 schema 版本重写它)、记忆库、会话库、auth.json;其余都能再生。我们这份归档 122 MB、5279 个条目、耗时 35 秒,而它是否可用只有一种证明方式——解出三个文件,和原文件比 sha256。
升级看起来像一次下载。它其实是把 agent 关于自己的一切迁到新形状——而出事的那部分,从来不是下载。
升级会动到什么
两类,只有一类是明显的:
- 二进制。 被替换。错了就回滚二进制。
- 你的状态,在原地被重写。
config.yaml被迁移到新的_config_version;会话库可能加列;记忆库可能被一次合并流程重写。这一类出错时,回滚二进制并不会把它恢复成旧形状。
第二类就是备份存在的理由。
体积,以及风险究竟在哪
本机实测:
| 路径 | 体积 | 能再生吗 |
|---|---|---|
state.db(会话) |
146 MB | 不能,它就是历史 |
skills/(822 个 SKILL.md) |
几十 MB | 不能,这是最贵的那部分 |
local-memory.json |
652 KB | 不能 |
memories/MEMORY.md |
5,878 字节(3,382 字符) | 不能 |
auth.json |
3 KB | 不能,而且根本重建不出来 |
config.yaml |
9 KB | 不能——22 个段都是手调出来的 |
cron/ |
21 个文件 | 能手搓,很痛苦 |
cache/、bin/、logs/、bootstrap-cache/ |
几百 MB | 能,下次运行就有 |
这组对比很不舒服:决定你能不能登进去的文件是 3 KB,占满归档的文件是 146 MB。只备小的丢历史,只备大的丢钥匙。
归档命令
L="$LOCALAPPDATA"
tar -czf "$L/Temp/hermes-backup.tar.gz" -C "$L" \
hermes/config.yaml hermes/auth.json hermes/local-memory.json hermes/state.db \
hermes/memories hermes/skills hermes/cron hermes/profiles hermes/scripts
真跑结果,2026-11-18:
elapsed=35s
archive: 122M
entries=5279
hermes/config.yaml present
hermes/auth.json present
hermes/state.db present
hermes/cron present
三点值得注意:35 秒,便宜到每次升级前都该做;122 MB,小到能留三份;条目数 5279,是恢复后要拿来对比的那个数。
写这篇时真踩到的一个坑
Windows 的 git-bash 里,-C "C:\Users\..." 会报 tar (child): Cannot connect to C: resolve failed——MSYS 把盘符当成了远程主机。要么用 POSIX 路径(/c/Users/...),要么先 cd 再传相对路径。同一类坑在平台差异那篇里有完整推导。
校验归档,别相信 tar
tar 退出 0 只说明归档写完了,不说明它可读。解出三个文件比哈希:
R="$LOCALAPPDATA/Temp/restore-drill"
mkdir -p "$R"
tar -xzf "$LOCALAPPDATA/Temp/hermes-backup.tar.gz" -C "$R" \
hermes/config.yaml hermes/memories/MEMORY.md hermes/auth.json
for f in hermes/config.yaml hermes/memories/MEMORY.md hermes/auth.json; do
a=$(sha256sum "$LOCALAPPDATA/$f" | cut -c1-16)
b=$(sha256sum "$R/$f" | cut -c1-16)
printf '%-28s orig=%s restored=%s %s\n' "$f" "$a" "$b" "$([ "$a" = "$b" ] && echo MATCH || echo DIFF)"
done
hermes/config.yaml orig=9380b09296f29604 restored=9380b09296f29604 MATCH
hermes/memories/MEMORY.md orig=d89f7b0685e59738 restored=d89f7b0685e59738 MATCH
hermes/auth.json orig=32974e6ed5e5d6a5 restored=32974e6ed5e5d6a5 MATCH
三个 MATCH 证明三件事:归档可读、路径就是你以为的、字节在往返中没有变形。再顺手数一遍条目(tar -tzf … | wc -l)——被截断的归档也能干净地解出前几个文件。
怎么知道恢复真的成功
备份由恢复证明,恢复由行为证明,不是由文件证明:
- 二进制起得来,版本是你预期的那个。
grep -cE '^[a-z_]+:' config.yaml仍是 22。 段数是最便宜的结构性检查:迁移有没有把配置改残。- 记忆块字符数不变:
wc -m memories/MEMORY.md→ 3,382。升级后变短,说明合并流程吃掉条目了。 cron/里还是 21 个文件,并且调度器能看到它们。skills/仍有 66 个顶层目录(822 个SKILL.md)。这个数字告诉你「幂等复制」那一步到底有没有真的复制。auth.json权限仍是 600。 跨文件系统的cp/tar会丢权限,别人可读的凭据文件是另一起事故。
怎么回滚
- 回滚二进制,也要回滚配置。 如果升级把
_config_version往前迁了,旧二进制可能拒读新文件。要成对恢复:二进制 + 同一份归档里的config.yaml。 - 留三份,带日期。 你真正需要的那一份,往往来自「当时看着没问题、一周后才炸」的那次升级之前。
- 先恢复到副本。 解到临时目录,用另一个 profile / home 起一遍(你的版本支持的话),确认能跑再覆盖。拿未经验证的归档直接覆盖在跑的状态,是把备份变成事故的标准姿势。
- 绝不在进程运行时覆盖
state.db。 停掉、拷贝、再启动。写了一半的 SQLite 文件就是损坏的 SQLite 文件。
我们没验的三件事
- 146 MB 会话库整体恢复后再跨版本升级。 我们只对三个小文件做了哈希级验证,没把数据库恢复到更旧或更新的版本里跑过。
auth.json换机器后是否还能用(盘符相同、主机名不同)。很可能令牌与安装 id 绑定,我们没测。- 历史量 10 倍时的归档体积。 122 MB 是一台机器、14 个会话;等备份不再是 35 秒的事,这条曲线就要重新算。
一句话版:把四样再生不出来的东西存起来,35 秒能做一次,然后用「解包 + 哈希」证明它可用——因为「我有备份」和「我恢复过这份备份」是两个不同的 Claim。
相关档案
常见问题
升级到底会改什么?
二进制,以及你状态文件的形状:config.yaml 会被迁移到新的 _config_version,会话库可能加列。真正疼的是迁移,不是下载。
什么可以跳过?
cache/、bootstrap-cache/、bin/、logs/、node/ —— 下次运行都会再生。跳过它们,归档是 122 MB 而不是几百 MB。
会话库有多大?
本机 146 MB,占归档的绝大部分。正是这个文件让备份变成「拷文件」的问题,而不是「tar 一下配置」的问题。
怎么知道备份是可用的?
从归档里解出三个文件,与在用的那份比 sha256。对得上,说明归档可读且完整。从来没恢复过的备份不是备份,只是一个文件。
来源
本文最后一次核验:2026-11-18 · 下面这份归档于 2026-11-18 在本机创建并校验:122 MB、35 秒、5279 个条目、822 个 SKILL.md,以及一次三文件解包,sha256 前缀与原件完全一致。