Hermes Agent v0.18.0 升级实战：1953 个 commit 带来的性能提升与一个致命坑

Hermes Agent v0.18.0 升级实战：1953 个 commit 带来的性能提升与一个致命坑

摘要：6 月 19 日刚升完 v0.17.0，7 月 1 日 v0.18.0 又来了——1953 个 commit、998 个 merged PR、P0/P1 清零。本文记录从 v0.17.0 到 v0.18.0 的完整升级过程，包括：安全网备份、git tag 纯净切版、gateway drain 机制与 systemd TimeoutStopSec 冲突导致的反复崩溃修复、三层 skill 保护机制拆解、以及后台自学习降本实测。文末附回滚命令，全程可复现。

一、为什么要升？

7 月 1 日，Nous Research 发布了 Hermes Agent v0.18.0（v2026.7.1）——"The Judgment Release"。这次更新不追求新功能，而是干了一件疯狂的事：12 天内把仓库里所有 P0 和 P1 级别的 issue/PR 全部清零。

数字说话：

核心文件变动分布：

二、升级前的安全网

跨大版本升级（>1000 commits），不备份就是赌命。标准三步：

# 1. 全量备份 config + state + skills + webui 配置
BACKUP_DIR=~/backup-hermes-pre-v0.18.0-$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"
cp -a ~/.hermes/config.yaml ~/.hermes/.env ~/.hermes/state.db \
      ~/.hermes/auth.json ~/.hermes/cron/ ~/.hermes/skills/ "$BACKUP_DIR/"
cp -a ~/.hermes-web-ui/ "$BACKUP_DIR/hermes-web-ui/"
tar czf "${BACKUP_DIR}.tar.gz" -C "$(dirname "$BACKUP_DIR")" "$(basename "$BACKUP_DIR")"

# 2. Git stash 当前修改
cd ~/.hermes/hermes-agent
git stash push -m "pre-v0.18.0-upgrade"

# 3. 拉取最新 tag
git config http.proxy http://127.0.0.1:7890   # 国内需要代理
git fetch --tags

⚠️ 铁律：只切 release tag，不拉 master。 hermes update 命令实际行为是 git checkout main，会拉到 tag 之后 N 个未测试的 commit。正确做法是直接 git checkout v2026.7.1。

三、升级执行 + 验证

cd ~/.hermes/hermes-agent

# 切换 tag
git checkout v2026.7.1

# 验证：必须是纯 tag，无后缀偏移
git describe --tags
# 期望：v2026.7.1
# ❌ 异常：v2026.7.1-919-gd712a7fd7 → 919 commits past tag = 在 main 上！

# 重新安装
venv/bin/pip install -e .

# 验证版本
hermes --version
# Hermes Agent v0.18.0 (2026.7.1)

# 重启 gateway
systemctl --user restart hermes-gateway

四、致命坑：gateway drain 与 systemd TimeoutStopSec 冲突

升级完成后，gateway 开始反复崩溃。journalctl 显示：

7月 02 09:52:52 hermes-gateway.service: Failed with result 'exit-code'.
7月 02 12:17:11 hermes-gateway.service: Failed with result 'exit-code'.
7月 02 12:52:39 hermes-gateway.service: State 'stop-sigterm' timed out. Killing.
# 3 小时内重启了 4 次！

日志中的关键警告：

WARNING: Stale systemd unit detected: hermes-gateway.service has
TimeoutStopSec=5s but drain_timeout=0s (expected >=30s).
systemd may SIGKILL the gateway mid-drain.

根因

v0.18.0 引入了 gateway drain（优雅排空）机制——收到 SIGTERM 后，gateway 需要时间排空正在处理的会话，然后安全退出。但旧的 systemd unit 文件里 TimeoutStopSec=5s，只给 5 秒：

v0.18.0 gateway:   "给我 30 秒排空当前会话"
systemd unit:      "5 秒后直接 SIGKILL"
                    ↓
              每次重启必被强杀 → 循环崩溃

修复：重新生成 systemd unit

hermes gateway install --force

新生成的 unit 文件对比：

新 unit 还会以 hermes-gateway-friday.service 命名（profile 感知），需要停用旧的：

systemctl --user stop hermes-gateway.service
systemctl --user disable hermes-gateway.service
systemctl --user restart hermes-gateway-friday.service

五、三个实打实的性能提升

5.1 推理模型不再被误杀

v0.17.0 中，Hermes 每 90-180 秒检测 stream 是否存活。DeepSeek R1 / o1 / Grok 等推理模型思考阶段可能超过这个时间 → 被当成"死连接"杀掉。

v0.18.0 新增 reasoning_timeouts.py（216 行），按模型名匹配推理模型白名单，自动设置 floor 超时：

5.2 后台自学习 token 消耗降级

每次对话结束后，Hermes 会用 background review fork 回顾本轮生成内容，判断是否要保存 skill/memory。

v0.17.0：用主模型重放整段对话 → 全额 token 费用。

v0.18.0：切到 auxiliary 模型。如果 auxiliary 和主模型相同 → 利用 prompt cache（热读便宜）；如果不同 → 只传最近几轮摘要（cold-write 大幅减少）。长对话场景下 post-turn review 的 token 消耗可降低 50-80%。

5.3 上下文压缩更智能

v0.17.0 的压缩用字符数估算尾部保护预算（不准），导致保护过度 → 压缩无效 → 反复浪费 token。

v0.18.0 修复了三个问题：

• Token 级尾部预算估算：保护更精确，压缩更有效
• 摘要分隔符修复：END MARKER 放在摘要最后，旧摘要不会泄露到新轮次
• 无效压缩抑制：压缩效果追踪，无效时自动抑制重试

六、skill 不会被后台乱改了——三层保护

这是此次升级在"可用性"上最重要的改进。

v0.17.0 有一个已知 bug：后台 review fork 会把 curator 指令注入用户的 session DB，下次对话 agent 会"变成 curator 人格"拒绝执行任务。

v0.18.0 上了三重锁：

第一层：类型隔离

后台 review fork 只能改 agent 自己创建的本地 skill。内置 skill、hub skill、外部目录 skill 全部拒绝：

"Refusing background curator patch for skill 'xxx': the skill lives
in skills.external_dirs, which are externally owned and read-only."

第二层：先读后写

即使第一层放行，fork 也必须先 skill_view() 读过 skill 的当前内容才允许写。不读原文就别想改：

"Refusing background curator patch for skill 'my-skill':
the current SKILL.md content has not been loaded in this review turn."

第三层：会话隔离

Review fork 完全隔离于用户主会话：

review_agent._persist_disabled = True   # 禁止写 session DB
review_agent._session_db = None         # 无 DB 连接
review_agent._end_session_on_close = False  # 不关闭主会话

七、WebUI 版本对齐

hermes-agent 和 hermes-webui 是两个独立项目，版本必须对齐，否则会报 ModuleNotFoundError。

关键修复：webui v0.51.791+ 适配了 agent v0.18.0 的 verification-stop nudge 过滤机制——否则 agent 的自验证回合会以裸 system 消息显示在聊天中。v0.51.815 包含了这个修复，同时比最新的 v0.51.816 少一个 Claude Code 侧边栏开关（无影响）。

cd ~/hermes-webui
git checkout v0.51.815

八、回滚预案

如果升级后出现不可接受的问题，一键回滚到 v0.17.0：

cd ~/.hermes/hermes-agent
git checkout v2026.6.19
venv/bin/pip install -e .
systemctl --user restart hermes-gateway-friday

# webui 同步回滚
cd ~/hermes-webui
git checkout v0.51.692

配置备份在 ~/backup-hermes-pre-v0.18.0-*.tar.gz（276MB），包含 config.yaml、.env、state.db、auth.json、cron、skills 的完整快照。

总结

v0.18.0 是一次稳定性驱动的升级——不炫技、不加功能，12 天修完 692 个 P0/P1。升级后最直观的感受：

1. Gateway 稳定了——不再被 systemd TimeoutStopSec 误杀
2. Token 省了——后台 review 切辅助模型
3. Skill 安全了——三层锁防后台乱改
4. 推理模型不被杀了——有白名单 floor 超时

唯一的坑是 gateway drain 与 systemd unit 的兼容性问题，修复只需一行命令。整体值得升级。