hermes教程-更新与卸载

更新

Git 安装

使用一条命令更新到最新版本：

bash

hermes update

这会从 main 分支拉取最新代码，更新依赖，并提示你配置自上次更新以来新增的任何选项。

pip 安装

PyPI 发布版本跟踪标记版本（主版本和次版本），而不是 main 上的每次提交。检查更新并升级：

bash

hermes update --check    # 查看 PyPI 上是否有新版本
hermes update            # 运行 pip install --upgrade hermes-agent

或手动操作：

bash

pip install --upgrade hermes-agent    # 或：uv pip install --upgrade hermes-agent

提示

hermes update 会自动检测新的配置选项并提示你添加。如果你跳过了该提示，可以手动运行 hermes config check 查看缺失的选项，然后运行 hermes config migrate 以交互方式添加它们。

更新期间发生的情况（Git 安装）

当你运行 hermes update 时，会执行以下步骤：

配对数据快照 — 保存一个轻量级的更新前状态快照（涵盖 ~/.hermes/pairing/、飞书评论规则以及其他在运行时被修改的状态文件）。可通过快照与回滚中描述的快照恢复流程，或解压 Hermes 在 ~/.hermes/ 目录旁写入的最新快速快照 zip 文件来恢复。
Git 拉取 — 从 main 分支拉取最新代码并更新子模块
拉取后语法验证 + 自动回滚 — 拉取后，Hermes 会编译每次 hermes 调用启动时导入的八个关键文件。如果任何文件解析失败（例如孤立的合并冲突标记、意外截断的文件），Hermes 会运行 git reset --hard <pre-pull-sha> 将安装回滚，以确保你的 shell 保持可启动状态。待上游修复后重新运行 hermes update。
依赖安装 — 运行 uv pip install -e ".[all]" 以获取新的或更改的依赖
配置迁移 — 检测自你的版本以来新增的配置选项，并提示你设置它们
网关自动重启 — 更新完成后刷新正在运行的网关，使新代码立即生效。服务管理的网关（Linux 上的 systemd，macOS 上的 launchd）通过服务管理器重启。当 Hermes 能够将运行中的 PID 映射回配置文件时，手动网关会自动重新启动。

针对非默认分支更新：`--branch`

默认情况下，hermes update 跟踪 origin/main。使用 --branch <name> 针对不同分支进行更新——适用于 QA 渠道、功能分支或候选版本测试：

bash

hermes update --branch release-candidate
hermes update --check --branch experimental   # 仅预览落后程度

如果你的本地检出位于不同分支，Hermes 会自动暂存任何未提交的工作，将 HEAD 切换到目标分支，然后拉取。本地不存在的分支会自动从 origin/<name> 跟踪（git checkout -B <name> origin/<name>）。任何地方都不存在的分支会干净地失败——退出前会恢复你暂存的更改，这样你就不会陷入奇怪的状态。在非 main 分支上，仅针对 main 的分支上游同步逻辑会自动跳过。

非交互式更新中的本地更改

当你在终端中运行 hermes update 时，Hermes 会暂存任何未提交的源代码树更改，拉取，然后询问是否恢复它们——与以往完全一样。交互式更新没有任何变化。

当更新没有终端运行时——从桌面/聊天应用的“更新”按钮或网关触发的更新——没有提示可以回答。updates.non_interactive_local_changes 设置决定如何处理你暂存的更改：

yaml

## ~/.hermes/config.yaml
updates:
  non_interactive_local_changes: stash   # 默认：保留 + 自动恢复
## non_interactive_local_changes: discard  # 丢弃本地源代码编辑

stash（默认）— 自动暂存，拉取，然后在更新后的代码之上自动恢复你的更改。不会丢失任何内容；如果恢复时遇到冲突，它们会保存在 git stash 中供手动恢复。
discard — 自动暂存并在拉取后丢弃 stash，这样更新始终落在干净的树上。仅在你从不打算保留 Hermes 源代码的本地编辑的机器上使用此选项。它使用 stash-drop（而不是 git reset --hard + git clean -fd），因此像 node_modules、venv 和构建输出这样的忽略路径永远不会被触及。

在桌面应用中，这是设置 → 高级 → 应用内更新本地更改。

仅预览：`hermes update --check`

想知道在拉取之前是否有可用更新？运行 hermes update --check——对于 Git 安装，它会获取并比较 origin/main 上的提交；对于 pip 安装，它会查询 PyPI 上的最新版本。不会修改任何文件，也不会重启任何网关。适用于脚本和 cron 作业中基于“是否有更新”进行判断的场景。

更新前完整备份：`--backup`

对于高价值配置文件（生产网关、共享团队安装），你可以选择在拉取前对 HERMES_HOME（配置、认证、会话、技能、配对）进行完整备份：

bash

hermes update --backup

或者将其设为每次运行的默认行为：

yaml

## ~/.hermes/config.yaml
updates:
  pre_update_backup: true

--backup 在早期版本中是始终开启的行为，但在大型 home 目录上每次更新会增加几分钟时间，因此现在改为可选。上述轻量级配对数据快照仍然无条件运行。

Windows：另一个 `hermes.exe` 正在运行

在 Windows 上，如果 hermes update 检测到另一个持有 venv 入口点可执行文件的 hermes.exe 进程正在运行，它将拒绝执行——最常见的是 Hermes 桌面应用生成的后端、另一个终端中打开的 hermes REPL，或正在运行的网关：

text

$ hermes update
✗ 另一个 hermes.exe 正在运行：
    PID 12345  hermes.exe

  现在更新将无法覆盖 ...\venv\Scripts\hermes.exe，因为
  Windows 阻止替换正在运行的可执行文件。

  请关闭 Hermes 桌面应用，退出所有打开的 `hermes` REPL，并
  停止网关（`hermes gateway stop`），然后重试。
  如果你已确认这些进程不会写入 venv，可以使用 `hermes update --force` 覆盖。

关闭列出的进程并重新运行。如果你确定并发进程不会造成干扰（很少见——通常仅在防病毒软件垫片被错误归因时有用），请传递 --force 跳过检查。在这种情况下，更新程序仍会以指数退避重试 .exe 重命名，并且在锁顽固的情况下，通过 MoveFileEx(MOVEFILE_DELAY_UNTIL_REBOOT) 将替换计划到下次重启，以便更新能够完成。

预期输出如下：

text

$ hermes update
正在更新 Hermes Agent...
📥 拉取最新代码...
已经是最新。  （或：正在更新 abc1234..def5678）
📦 更新依赖...
✅ 依赖已更新
🔍 检查新配置选项...
✅ 配置已是最新  （或：发现 2 个新选项 — 正在运行迁移...）
🔄 重启网关...
✅ 网关已重启
✅ Hermes Agent 更新成功！

如果终端在更新中断开连接

hermes update 会保护自身免受意外终端丢失的影响：

更新忽略 SIGHUP，因此关闭 SSH 会话或终端窗口不再会在安装过程中杀死它。pip 和 git 子进程继承此保护，因此 Python 环境不会因连接断开而半安装。
更新运行时，所有输出都会镜像到 ~/.hermes/logs/update.log。如果终端消失，请重新连接并检查日志以查看更新是否完成以及网关重启是否成功：

bash

tail -f ~/.hermes/logs/update.log

Ctrl-C（SIGINT）和系统关机（SIGTERM）仍然被处理——这些是故意的取消操作，而非意外。

你不再需要将 hermes update 包装在 screen 或 tmux 中来应对终端断开。

检查当前版本

bash

hermes version

与 GitHub 发布页面上的最新版本进行比较。

从消息平台更新

你也可以直接从 Telegram、Discord、Slack、WhatsApp 或 Teams 发送以下内容进行更新：

/update

这会拉取最新代码，更新依赖，并重启正在运行的网关。机器人会在重启期间短暂离线（通常 5–15 秒），然后恢复。

手动更新

如果你是通过手动方式安装的（而非快速安装程序）：

bash

cd /path/to/hermes-agent
export VIRTUAL_ENV="$(pwd)/venv"
## 拉取最新代码
git pull origin main
## 重新安装（获取新依赖）
uv pip install -e ".[all]"
## 检查新配置选项
hermes config check
hermes config migrate   # 交互式添加任何缺失的选项

回滚说明

如果更新引入了问题，你可以回滚到之前的版本：

bash

cd /path/to/hermes-agent
## 列出最近版本
git log --oneline -10
## 回滚到特定提交
git checkout <commit-hash>
uv pip install -e ".[all]"
## 如果网关正在运行，重启它
hermes gateway restart

要回滚到特定的发布标签（替换为你之前的标签——例如最近的发布版本如 v2026.5.16，或通过 git tag --sort=-version:refname 找到的任何更早标签）：

bash

git checkout vX.Y.Z
uv pip install -e ".[all]"

警告

如果添加了新选项，回滚可能导致配置不兼容。回滚后运行 hermes config check，如果遇到错误，请从 config.yaml 中删除任何无法识别的选项。

Nix 用户注意事项

如果你通过 Nix flake 安装，更新通过 Nix 包管理器管理：

bash

## 更新 flake 输入
nix flake update hermes-agent
## 或使用最新版本重建
nix profile upgrade hermes-agent

Nix 安装是不可变的——回滚由 Nix 的生成系统处理：

bash

nix profile rollback

更多详情请参见 Nix 设置。

卸载

Git 安装

bash

hermes uninstall

卸载程序会提供选项，让你保留配置文件（~/.hermes/）以便将来重新安装。

pip 安装

bash

pip uninstall hermes-agent
rm -rf ~/.hermes            # 可选——如果计划重新安装则保留

手动卸载

bash

rm -f ~/.local/bin/hermes
rm -rf /path/to/hermes-agent
rm -rf ~/.hermes            # 可选——如果计划重新安装则保留

信息

如果你将网关安装为系统服务，请先停止并禁用它：
bash
hermes gateway stop
# Linux: systemctl --user disable hermes-gateway
# macOS: launchctl remove ai.hermes.gateway

字节笔记本

hermes教程-更新与卸载

更新

Git 安装

pip 安装

更新期间发生的情况（Git 安装）

针对非默认分支更新：`--branch`

非交互式更新中的本地更改

仅预览：`hermes update --check`

更新前完整备份：`--backup`

Windows：另一个 `hermes.exe` 正在运行

推荐的更新后验证

如果终端在更新中断开连接

检查当前版本

从消息平台更新

手动更新

回滚说明

Nix 用户注意事项

卸载

Git 安装

pip 安装

手动卸载

字节笔记本

hermes教程-更新与卸载

更新

Git 安装

pip 安装

更新期间发生的情况（Git 安装）

针对非默认分支更新：--branch

非交互式更新中的本地更改

仅预览：hermes update --check

更新前完整备份：--backup

Windows：另一个 hermes.exe 正在运行

推荐的更新后验证

如果终端在更新中断开连接

检查当前版本

从消息平台更新

手动更新

回滚说明

Nix 用户注意事项

卸载

Git 安装

pip 安装

手动卸载

针对非默认分支更新：`--branch`

仅预览：`hermes update --check`

更新前完整备份：`--backup`

Windows：另一个 `hermes.exe` 正在运行