<!-- Source: https://hermesbible.com/docs/guides/operate-teams-meeting-pipeline -->

在你已經從 Teams 會議 啟用功能後使用本指南。

本頁涵蓋：

• 操作員 CLI 流程
• 例行訂閱維護
• 故障分類
• 上線檢查
• 推廣工作表

核心操作員指令

驗證設定快照

hermes teams-pipeline validate

在任何設定變更後首先使用此指令。

檢視代碼健康狀態

hermes teams-pipeline token-health
hermes teams-pipeline token-health --force-refresh

當你懷疑認證狀態過時時使用 --force-refresh。

檢視訂閱

hermes teams-pipeline subscriptions

重新整理即將到期的訂閱

hermes teams-pipeline maintain-subscriptions
hermes teams-pipeline maintain-subscriptions --dry-run

自動化訂閱重新整理（生產環境必需）

Microsoft Graph 訂閱最多在 72 小時後到期。 如果沒有任何東西重新整理它們，會議通知會在 3 天後靜默停止，管線看起來像「壞了」。這是任何 Graph 支援整合的 #1 運營失敗模式。

你必須按排程執行 maintain-subscriptions。選擇以下三個選項之一：

選項 1：Hermes cron（如果你已經運行 Hermes 閘道，建議使用）

Hermes 附帶內建的 cron 排程器。--no-agent 模式將腳本作為工作運行（而非使用 LLM），--script 必須指向 ~/.hermes/scripts/ 下的檔案。首先建立腳本：

mkdir -p ~/.hermes/scripts
cat > ~/.hermes/scripts/maintain-teams-subscriptions.sh <<'EOF'
#!/usr/bin/env bash
exec hermes teams-pipeline maintain-subscriptions
EOF
chmod +x ~/.hermes/scripts/maintain-teams-subscriptions.sh

然後註冊一個每 12 小時執行一次的純腳本定時任務（相對於 72 小時到期窗口提供 6 倍緩衝）：

hermes cron create "0 */12 * * *" \
  --name "teams-pipeline-maintain-subscriptions" \
  --no-agent \
  --script maintain-teams-subscriptions.sh \
  --deliver local

驗證它已註冊並檢查下次執行時間：

hermes cron list
hermes cron status        # 排程器狀態

選項 2：systemd 計時器（Linux 生產部署建議使用）

建立 /etc/systemd/system/hermes-teams-pipeline-maintain.service：

[Unit]
Description=Hermes Teams pipeline subscription maintenance
After=network-online.target

[Service]
Type=oneshot
User=hermes
EnvironmentFile=/etc/hermes/env
ExecStart=/usr/local/bin/hermes teams-pipeline maintain-subscriptions

以及 /etc/systemd/system/hermes-teams-pipeline-maintain.timer：

[Unit]
Description=Run Hermes Teams pipeline subscription maintenance every 12 hours

[Timer]
OnBootSec=5min
OnUnitActiveSec=12h
Persistent=true

[Install]
WantedBy=timers.target

啟用：

sudo systemctl daemon-reload
sudo systemctl enable --now hermes-teams-pipeline-maintain.timer
systemctl list-timers hermes-teams-pipeline-maintain.timer

選項 3：純 crontab

0 */12 * * * /usr/local/bin/hermes teams-pipeline maintain-subscriptions >> /var/log/hermes/teams-pipeline-maintain.log 2>&1

確保 cron 環境具有 MSGRAPH_* 憑證。最簡單的修正：在 crontab 呼叫的包裝腳本頂部 source ~/.hermes/.env。

驗證重新整理運作正常

設定排程後，在第一次排程執行後檢查重新整理活動：

hermes teams-pipeline subscriptions   # 應顯示 expirationDateTime 已提前
hermes teams-pipeline maintain-subscriptions --dry-run   # 大多數時候應顯示「0 expiring soon」

如果你的 Graph webhook 神秘地在大約 72 小時後「停止運作」，這是第一個要檢查的：重新整理工作是否真的執行了？

檢視最近的工作

hermes teams-pipeline list
hermes teams-pipeline list --status failed
hermes teams-pipeline show <job-id>

重播儲存的工作

hermes teams-pipeline run <job-id>

乾跑會議產品獲取

hermes teams-pipeline fetch --meeting-id <meeting-id>
hermes teams-pipeline fetch --join-web-url "<join-url>"

例行操作手冊

首次設定後

依序執行這些：

hermes teams-pipeline validate
hermes teams-pipeline token-health --force-refresh
hermes teams-pipeline subscriptions

然後觸發或等待真實的會議事件並確認：

hermes teams-pipeline list
hermes teams-pipeline show <job-id>

每日或定期檢查

• 執行 hermes teams-pipeline maintain-subscriptions --dry-run
• 檢視 hermes teams-pipeline list --status failed
• 驗證 Teams 傳遞目標仍是正確的聊天室或頻道

在更改 webhook URL 或傳遞目標之前

• 更新公開通知 URL 或 Teams 目標設定
• 執行 hermes teams-pipeline validate
• 重新整理或重新建立受影響的訂閱
• 確認新事件落入預期的接收器

故障分類

沒有建立任何工作

檢查：

• msgraph_webhook 已啟用
• 公開通知 URL 指向 /msgraph/webhook
• 訂閱中的用戶端狀態與 MSGRAPH_WEBHOOK_CLIENT_STATE 匹配
• 訂閱仍然存在於遠端且未過期

工作停留在重試狀態或在摘要化之前失敗

檢查：

• 逐字稿權限和可用性
• 錄音權限和產品可用性
• 如果啟用了錄音備用，檢查 ffmpeg 可用性
• Graph 代碼健康狀態

已產生摘要但未傳遞到 Teams

檢查：

• platforms.teams.enabled: true
• delivery_mode
• Webhook 模式的 incoming_webhook_url
• Graph 模式的 chat_id 或 team_id 加 channel_id
• 如果使用 Graph 發佈，檢查 Teams 認證設定

重複或意外的重播

檢查：

• 你是否使用 hermes teams-pipeline run 手動重播了工作
• 該會議的接收器記錄是否已存在
• 你是否在本機設定中啟用了重發路徑

上線檢查清單

• Graph 憑證存在且正確
• msgraph_webhook 已啟用且可從公共網際網路到達
• MSGRAPH_WEBHOOK_CLIENT_STATE 已設定且與訂閱匹配
• 逐字稿訂閱已建立
• 如果需要 STT 備用，錄音訂閱已建立
• 如果啟用了錄音備用，ffmpeg 已安裝
• Teams 出站傳遞目標已設定並驗證
• 僅在實際需要時設定 Notion 和 Linear 接收器
• hermes teams-pipeline validate 傳回 OK 快照
• hermes teams-pipeline token-health --force-refresh 成功
• maintain-subscriptions 已排程（Hermes cron、systemd 計時器或 crontab — 見自動化訂閱重新整理）。沒有此項，Graph 訂閱會在 72 小時內靜默到期。
• 一個真實的端到端會議事件已產生儲存的工作
• 至少有一個摘要已到達預期的傳遞接收器

傳遞模式決策指南

操作員工作表

在推廣前填寫：

變更審查工作表

在變更部署前使用此表：

相關文件

• Teams 會議設定
• Microsoft Teams 機器人設定

---

---

將腳本輸出導入訊息平台