H繁中版
文件Flows社群 Repos開始使用
文件入門指南updating
<!-- Source: https://hermesbible.com/docs/getting-started/updating -->

更新

Git 安裝

使用單一指令更新到最新版本：

hermes update

這會從 main 拉取最新程式碼、更新相依性，並提示你設定自上次更新以來新增的任何新選項。

pip 安裝

PyPI 發布追蹤標記版本（主要和次要發版），而不是 main 上的每個提交。檢查更新並升級：

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

或手動：

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

提示

hermes update 會自動偵測新的設定選項並提示你新增它們。如果你跳過了該提示，可以手動執行 hermes config check 查看缺少的選項，然後執行 hermes config migrate 互動式新增它們。

更新時發生了什麼（Git 安裝）

當你執行 hermes update 時，會發生以下步驟：

  1. 配對資料快照——儲存輕量級的更新前狀態快照（涵蓋 ~/.hermes/pairing/、Feishu 留言規則和其他在運行時修改的狀態檔案）。可透過 快照與回滾 中描述的快照復原流程恢復，或從 Hermes 寫在 ~/.hermes/ 目錄旁的最近快速快照 zip 檔案中提取。
  2. Git pull——從 main 分支拉取最新程式碼並更新子模組
  3. 拉取後語法驗證 + 自動回滾——拉取後，Hermes 會編譯每次 hermes 呫用在啟動時匯入的八個關鍵檔案。如果任何檔案無法解析（例如孤立的合併衝突標記、意外截斷的檔案），Hermes 會執行 git reset --hard <pre-pull-sha> 將安裝回滾，使你的 shell 保持可啟動。等上游修復到位後重新執行 hermes update。
  4. 相依性安裝——執行 uv pip install -e ".[all]" 以取得新的或變更的相依性
  5. 設定遷移——偵測自你的版本以來新增的設定選項並提示你設定它們
  6. 閘道自動重啟——更新完成後刷新正在運行的閘道，使新程式碼立即生效。服務管理的閘道（Linux 上的 systemd、macOS 上的 launchd）透過服務管理器重啟。手動閘道在 Hermes 能將正在運行的 PID 映射回配置檔時自動重新啟動。

針對非預設分支更新：--branch

預設情況下 hermes update 追蹤 origin/main。傳入 --branch <name> 針對不同的分支更新——適用於 QA 頻道、功能分支或發行候選測試：

hermes update --branch release-candidate
hermes update --check --branch experimental   # 僅預覽落後程度

如果你的本地簽出在不同的分支上，Hermes 會自動儲存任何未提交的工作、切換 HEAD 到目標分支，然後拉取。不存在於本地的分支會從 origin/<name> 自動追蹤（git checkout -B <name> origin/<name>）。在任何地方都不存在的分支會乾淨地失敗——你的儲存變更會在退出前恢復，所以你永遠不會被困在奇怪的狀態。main 專用的 fork-upstream 同步邏輯在非 main 分支上會自動跳過。

非互動式更新時的本地變更

當你在終端機中執行 hermes update 時，Hermes 會儲存任何未提交的原始碼樹變更、拉取，然後詢問是否恢復它們——一如既往。互動式更新沒有變化。

當更新沒有終端機執行時——來自桌面/聊天應用程式的「更新」按鈕或閘道觸發的更新——沒有提示需要回答。updates.non_interactive_local_changes 設定決定你的儲存變更會發生什麼：

# ~/.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 安裝，它會 fetch 並比較提交與 origin/main；對於 pip 安裝，它會查詢 PyPI 的最新發版。不會修改任何檔案，不會重啟閘道。在腳本和定時任務中很有用，用於判斷「是否有更新」。

完整的更新前備份：--backup

對於高價值的配置檔（生產閘道、共享團隊安裝），你可以選擇在拉取前完整備份 HERMES_HOME（設定、驗證、工作階段、技能、配對）：

hermes update --backup

或將其設為每次執行的預設值：

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

--backup 在早期版本中是預設行為，但它會在大型主目錄上為每次更新增加數分鐘，所以現在是選擇加入。上面的輕量級配對資料快照仍然會無條件運行。

Windows：另一個 hermes.exe 正在運行

在 Windows 上，如果偵測到另一個 hermes.exe 正在持有虛擬環境的進入點可執行檔，hermes update 會拒絕執行——最常見的是 Hermes Desktop 應用程式衍生的後端、另一個終端機中開啟的 hermes REPL，或正在運行的閘道：

$ hermes update
✗ Another hermes.exe is running:
    PID 12345  hermes.exe

  Updating now would fail to overwrite ...\venv\Scripts\hermes.exe because
  Windows blocks REPLACE on a running executable.

  Close Hermes Desktop, exit any open `hermes` REPLs, and
  stop the gateway (`hermes gateway stop`) before retrying.
  Override with `hermes update --force` if you've already
  confirmed those processes will not write to the venv.

關閉列出的程序並重新執行。如果你確定並行程序不會干擾（很少見——通常只在防毒軟體 shim 被錯誤歸因時有用），傳入 --force 跳過檢查。在這種情況下，更新程式仍會以指數退避重試 .exe 重新命名，對於頑固的鎖，會透過 MoveFileEx(MOVEFILE_DELAY_UNTIL_REBOOT) 將替換排程到下次重啟時執行，使更新可以完成。

預期輸出如下：

$ hermes update
Updating Hermes Agent...
📥 Pulling latest code...
Already up to date.  (或：Updating abc1234..def5678)
📦 Updating dependencies...
✅ Dependencies updated
🔍 Checking for new config options...
✅ Config is up to date  (或：Found 2 new options — running migration...)
🔄 Restarting gateways...
✅ Gateway restarted
✅ Hermes Agent updated successfully!

建議的更新後驗證

hermes update 處理主要的更新路徑，但快速驗證可以確認所有內容都乾淨地到位：

  1. git status --short——如果樹意外地不乾淨，繼續之前先檢查
  2. hermes doctor——檢查設定、相依性和服務健康狀態
  3. hermes --version——確認版本如預期般提升
  4. 如果你使用閘道：hermes gateway status
  5. 如果 doctor 報告 npm audit 問題：在標記的目錄中執行 npm audit fix

警告——更新後工作樹不乾淨

如果 git status --short 在 hermes update 後顯示意外的變更，停止並在繼續之前檢查它們。這通常意味著本地修改在更新的程式碼之上被重新應用，或相依性步驟刷新了鎖定檔案。

如果你的終端機在更新中斷線

hermes update 會保護自己免受意外終端機丟失：

  • 更新忽略 SIGHUP，所以關閉你的 SSH 會話或終端機視窗不再會在安裝中途終止它。pip 和 git 子程序繼承這個保護，所以 Python 環境不會因為連線丟失而處於半安裝狀態。
  • 更新執行時，所有輸出都會鏡像到 ~/.hermes/logs/update.log。如果你的終端機消失，重新連線並檢查日誌以查看更新是否完成以及閘道重啟是否成功：
tail -f ~/.hermes/logs/update.log
  • Ctrl-C（SIGINT）和系統關機（SIGTERM）仍然會被遵守——這些是刻意的取消，不是意外。

你不再需要將 hermes update 包裹在 screen 或 tmux 中以避免終端機丟失。

檢查你目前的版本

hermes version

與 GitHub 發布頁面上的最新版本比較。

從訊息平台更新

你也可以直接從 Telegram、Discord、Slack、WhatsApp 或 Teams 更新，發送：

/update

這會拉取最新程式碼、更新相依性並重啟正在運行的閘道。機器人會在重啟期間短暫離線（通常 5-15 秒），然後恢復。

手動更新

如果你是手動安裝的（不是透過快速安裝器）：

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   # 互動式新增任何缺少的選項

回滾說明

如果更新引入了問題，你可以回滾到之前的版本：

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 的更早標籤）：

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

警告

如果新增了新選項，回滾可能會導致設定不相容。回滾後執行 hermes config check，如果遇到錯誤，從 config.yaml 中移除任何無法識別的選項。

Nix 使用者注意事項

如果你是透過 Nix flake 安裝的，更新透過 Nix 套件管理器管理：

# 更新 flake 輸入
nix flake update hermes-agent

# 或使用最新的重新建置
nix profile upgrade hermes-agent

Nix 安裝是不可變的——回滾透過 Nix 的世代系統處理：

nix profile rollback

參閱 Nix 設定了解更多詳情。

解除安裝

Git 安裝

hermes uninstall

解除安裝器會提供保留你的設定檔案（~/.hermes/）以供未來重新安裝的選項。

pip 安裝

pip uninstall hermes-agent
rm -rf ~/.hermes            # 可選——如果你計畫重新安裝則保留

手動解除安裝

rm -f ~/.local/bin/hermes
rm -rf /path/to/hermes-agent
rm -rf ~/.hermes            # 可選——如果你計畫重新安裝則保留

資訊

如果你將閘道安裝為系統服務，請先停止並停用它：

hermes gateway stop
# Linux: systemctl --user disable hermes-gateway
# macOS: launchctl remove ai.hermes.gateway

Android / Termux

termuxautomate with cron