# Hermes 群聊健康檢查（Hermes Group Route Monitor）v1.1.1

新版 Hermes Desktop 已會在群聊的 Activity 摘要顯示成員失敗原因；但它不會告訴你這位 Bot「實際用了哪個模型」、
「是不是換成了備援模型」、「對話紀錄是不是快塞滿了」。這個小工具會讀取你電腦上的 Hermes 紀錄，
在瀏覽器裡用白話補上這幾件事，並告訴你下一步該做什麼。

- **只讀**：不會修改 Hermes 設定、資料庫、對話或群聊。
- **只在你的電腦上跑**：儀表板只開在 `127.0.0.1`，別台電腦連不進來；不會上傳任何資料。
- **不顯示金鑰**：報告裡不會出現 API key、OAuth token 或密碼。

## 你需要先有

1. 已經在用 Hermes Desktop 的 Bot Mode 群聊，且群聊裡至少送過一則訊息。
2. 電腦上有 Python 3.10 以上。沒有的話到 https://www.python.org/downloads/ 下載安裝；
   **Windows 安裝時記得勾選「Add python.exe to PATH」**。

## 三步驟開始

1. 下載 ZIP，**先解壓縮**（不要直接在壓縮檔裡點開）。
2. 雙擊啟動檔：
   - Windows：`start-windows.cmd`
   - macOS：`start-mac-linux.command`（第一次若被系統擋下，請按右鍵 →「打開」）
   - Linux：在終端機執行 `sh start-mac-linux.command`
3. 瀏覽器會自動打開儀表板（`http://127.0.0.1:8765/dashboard.html`）。

第一次執行會自動安裝需要的套件 PyYAML，約需幾十秒。
**黑色視窗要保持開著**，儀表板才會每 5 秒更新；看完直接關掉視窗即可停止。

## 狀態怎麼看

| 顏色 | 意思 | 你要做什麼 |
|---|---|---|
| 綠色 正常 | 用設定的主要模型，有成功回覆 | 不用做事 |
| 黃色 改用備援模型 | 主要模型這次沒接上，系統自動換手完成 | 偶爾出現不用管；整天都黃色再考慮換主要模型 |
| 紫色 待確認／被限流 | 證據還不夠，或模型暫時太擠（429） | 等一下，或在群聊 @ 這位 Bot 說一句話再看 |
| 紅色 需要處理 | 金鑰錯誤（401）、模型名稱錯誤（404）、對話太長塞不下 | 照卡片上的「下一步」做；不確定時先不要刪任何東西 |
| 灰色 沒有動靜 | 這位 Bot 沒收到訊息 | 沒被 @ 的 Bot 本來就可能不回答；點名它一次再看 |

每張卡片下方的「技術細節」是給進階使用者對照 log 用的，新手可以不看。

## 常見問題

- **視窗一閃就關／顯示找不到 Python**：Python 沒裝或沒加進 PATH。重新安裝並勾選 Add to PATH。
- **顯示「找不到 Hermes 資料夾」**：你的 Hermes 裝在非預設位置。用終端機在工具資料夾執行：
  `python hermes_group_route_monitor.py --serve --hermes-home "你的 Hermes 資料夾路徑"`
- **顯示「還沒有找到任何群聊紀錄」**：先到 Hermes Desktop 的群聊送出一則訊息。
- **顯示 port 被占用**：加上 `--port 8766` 再執行。
- **儀表板寫「讀不到監測資料」**：請用啟動檔開，不要直接雙擊 `dashboard.html`。
- **監測的不是我要的群聊**：工具預設挑最近有活動的群聊。可加上 `--room-id 群聊ID` 指定。

## 進階參數

```text
--serve              啟動本機儀表板並自動開瀏覽器（啟動檔預設使用）
--port 8765          儀表板 port
--no-browser         不自動開瀏覽器
--hermes-home PATH   指定 Hermes 資料夾；預設自動偵測
--room-id ID         指定群聊；預設選最近活動的群聊
--profiles a,b,c     只看這些 Bot
--exclude a,b        排除這些 Bot
--once               只產生一次 JSON 就結束（不開儀表板）
--interval 5         更新秒數
--offline            不連線查詢 OpenRouter 模型目錄
--output FILE        JSON 輸出位置，預設 group-route-status.json
```

技術上，工具把三種證據分開比對：`config.yaml` 的預期路由、`state.db` 的 session 資料，
以及 `agent.log` / `errors.log` 裡真正打到哪個 provider 的主請求紀錄。「Bot 自己說用哪個模型」不算證據。

## 分享前請注意

輸出的 `group-route-status.json` 已把 Hermes 路徑換成 `<HERMES_HOME>`，並遮蔽常見金鑰格式，
但要公開分享前仍請自己看過一遍。**不要上傳** `.env`、`auth.json`、`state.db` 或完整 log。

## 限制

- 已對照 Hermes v0.21.6（2026-10-08）原始碼確認：工具讀取的 log 字串（主請求、失敗、context 超限、prompt accepted、turn finished）與 log 位置都沒有改變。
- Hermes 版本更新可能改變 log 格式；看到「紀錄不足」時，可能是版本差異，不代表 Bot 壞了。
- v1.1.1 起支援新版的群聊對話標題（`Group: 房間 · 討論串`，以及壓縮後自動產生的 `#2`、`#3` 接續段），會把它們視為同一個群聊。
- 對話太長時，新版 Hermes 可在「群組設定 → 成員 → Compress history」直接壓縮，不需要用工具處理。
- 工具只負責「看」，不負責「修」。對話太長或群聊綁錯 session 的處理方式，請見教學文章。

## 參考

- 教學文章：https://heraizone.com/insights/hermes-bot-mode-group-chat-guide/
- Hermes 官方文件：Bot Mode https://hermes-agent.nousresearch.com/docs/user-guide/bot-mode
- Sessions https://hermes-agent.nousresearch.com/docs/user-guide/sessions
- Configuration https://hermes-agent.nousresearch.com/docs/user-guide/configuration

MIT License