Hermes Agent 0.22.0 版本迎来重要更新，不仅新增功能，更对默认行为和安装方式进行了底层重构。本文旨在指导用户如何安全升级、理解变更影响及应对潜在问题。
一、升级前准备：检查与备份
在执行升级前，建议先确认是否存在可用更新，该操作仅进行比较，不修改文件或重启服务：
对于生产网关或团队共用环境，强烈建议执行备份：
备份策略分为三档，可在配置文件中设定长期生效：
quick：默认模式。保存配对数据、定时任务、config.yaml、.env及auth.json等状态文件（单文件超过 1 GiB 将被跳过）。full：额外生成 zip 归档，大型数据目录耗时较长。off：不执行更新前备份（也可使用--no-backup单次关闭）。
二、升级流程解析
执行以下命令即可启动升级：
该命令内部依次执行五个步骤：更新前快照 → 拉取代码 → 安装依赖 → 配置迁移 → 重启网关。
其中，依赖安装采用新的包管理器（python -m pm.cli install）；配置迁移环节会检测新增配置项并提示补充。若跳过提示，后续可手动运行 hermes config check 检查缺失项，并通过 hermes config migrate 进行修补。最后一步将刷新正在运行的网关或由系统服务管理器重启托管服务。
注意：升级后请立即检查 Git 工作树状态。若 git status --short 显示非预期改动，通常意味着本地修改被重新应用或依赖锁文件被刷新，需暂停并排查。
三、版本通道管理与回滚机制
自 0.22 版本起，源码安装默认跟随正式版（vX.Y.Z），不再自动跟随主干提交。可通过以下命令切换通道：
若当前安装版本高于最新正式版（如曾跟随主干），系统将原地等待下一个正式版发布，不会强制降级。降级操作被明确标记为「回滚」，需手动执行且不默认开启。
手动回滚步骤如下：
警告：若新版本引入了新配置项，回滚可能导致配置不兼容。回滚后请运行 hermes config check，若有报错，需手动删除 config.yaml 中无法识别的选项。
四、常见注意事项
Windows 系统进程占用
Windows 不允许替换正在运行的可执行文件。若升级时检测到 hermes.exe 被占用（如桌面端后端、REPL 或运行中的网关），系统将拒绝升级并列出占用进程的 PID。解决方法：
- 按提示关闭相关进程后重试。
- 确认无风险后可添加
--force参数，系统将尝试指数退避重试重命名；若仍被锁定，则安排在下一次系统重启时执行替换。
终端断线保护
升级过程现已忽略 SIGHUP 信号，关闭 SSH 或终端窗口不会中断升级。pip 和 git 子进程同样受到保护，避免留下损坏的 Python 环境。所有输出日志镜像至 ~/.hermes/logs/update.log，断线重连后可通过 tail -f 查看进度。Ctrl+C 和系统关机信号依然有效。
五、升级后验证清单
建议花费两分钟完成以下四项检查：
git status --short：确认工作树干净无意外改动。hermes doctor：检查配置、依赖及服务健康状态。hermes --version：确认版本号已更新。hermes gateway status：确认网关正常启动。
六、日常使用行为的六大变更
- 会话重置机制取消：原有的闲置或每日自动重置模式已废弃。如需开启新会话，请使用
/new或/reset命令。 - 旧会话自动清理：已结束且 90 天未活动的会话将在启动时被删除。固定会话及未结束会话不受影响，该功能可关闭。
- 单实例架构：每台机器仅运行一个网关和一个桌面后端，服务于所有 Profile。升级时将自动合并原有多个进程结构。新建 Profile 无需重启即可上线，各 Profile 的凭据、白名单、任务及会话保持独立。
- 记忆插件迁移：Honcho、Supermemory、Hindsight、Mem0、OpenViking、Holographic 等记忆类插件，以及 Home Assistant、Spotify、Langfuse 集成，均已迁移至插件目录。升级或首次启动时自动迁移数据。
- 客户端平台限制：Windows 桌面端仅提供 MSIX 包，要求 Windows 11 22H2 或更高版本，旧安装器已移除；macOS 默认构建仅支持 Apple Silicon 芯片。
- Python 3.14 运行时：托管安装默认使用 Python 3.14（包管理器自动安装）。部分依赖尚未适配，如 KittenTTS 在 Python 3.14 上暂不可用。
七、环境管理优化
依赖环境现按「代」进行管理：新环境先构建并自检通过后才切换，确保升级失败或中断不会遗留半成品。可使用 hermes pm gc 回收旧环境（实测可从 92 GB 降至 18 GB）。
提供一套完整的诊断与修复命令：
可选能力改为按需安装（如特定 SDK），支持在不重启的情况下于会话中途加载，该行为可配置关闭。插件现在可声明自身的 Python 依赖，与核心依赖共同求解，冲突将直接导致拒绝安装，不兼容的插件会被自动停用。
会话数据库经过优化：锁超时将指明占用进程，繁忙状态不再打断当前操作；自动压缩仅在可回收空间超过四分之一时触发；提供专门的修复命令以处理日志模式重建、Profile 交叉及提示词修复等问题。
八、插件开发者注意事项
以下内容为破坏性变更，插件作者需在升级前适配：
- 移除旧的插件兼容导入层。
- 移除
hermes sync（技能同步）。 - 移除内置的 tirith 扫描器。
- 部分工具改名：
todo→todo_list、cronjob→cronjob_manage、process→process_manage。旧名称暂时保留兼容，但建议尽快更新。
九、快速升级指南
hermes update --check：确认有可用更新。hermes update --backup：执行备份（生产环境必需）。- 关闭桌面端、其他终端中的 REPL 及网关（Windows 用户必做）。
hermes update：执行升级。- 执行三项验证：
git status --short、hermes doctor、hermes --version。 - 重点检查第六节所述的会话重置与自动清理逻辑是否符合预期。
此外，支持在 Telegram、Discord、Slack、WhatsApp 或 Teams 中发送 /update 命令进行升级，机器人将短暂下线 5–15 秒后恢复。
十、总结
这是一个必须重视的版本更新。虽然升级过程仅需一条命令和几分钟时间，但默认行为的改变需要用户主动确认：会话不再自动重置、旧会话开始自动清理、单机单网关架构生效。理清这三点变化，才能充分获得更稳定的环境、更小的安装包体积以及更可靠的升级体验。