Microsoft Teams 會議

當您希望 Hermes 攝取 Microsoft Graph 會議事件、優先獲取轉錄文本、在需要時回退到錄音加語音轉文本（STT），並將結構化摘要交付給下游接收器時，請使用 Teams 會議管道。

前提條件：請參閱 Microsoft Teams 瞭解底層機器人/憑據設置。

運行 hermes gateway setup 並選擇 Teams Meetings 以獲取引導式演練。

本頁重點介紹設置和啟用：

• Graph 憑據
• Webhook 監聽器配置
• Teams 交付模式
• 管道配置結構

有關日常運營、上線檢查和操作員工作表，請使用專用指南：操作 Teams 會議管道。

此功能的作用

該管道：

1. 接收 Microsoft Graph webhook 事件
2. 解析會議並優先使用轉錄工件
3. 當沒有可用的轉錄文本時，回退到下載錄音加 STT
4. 在本地存儲持久的作業狀態和接收器記錄
5. 可以將摘要寫入 Notion、Linear 和 Microsoft Teams

操作員操作保留在 CLI 中（teams-pipeline 子命令由 teams_pipeline 插件註冊 — 通過 hermes plugins enable teams_pipeline 啟用它，或在 config.yaml 中設置 plugins.enabled: [teams_pipeline]）：

hermes teams-pipeline validate
hermes teams-pipeline list
hermes teams-pipeline maintain-subscriptions

前提條件

在啟用會議管道之前，請確保您具備：

• 正常運行的 Hermes 安裝
• 如果希望 Teams 出站交付，需具備現有的 Microsoft Teams 機器人設置
• 具有訂閱計劃使用的會議資源所需權限的 Microsoft Graph 應用程序憑據
• Microsoft Graph 可用於 webhook 交付的公共 HTTPS URL
• 如果希望使用錄音加 STT 回退，需安裝 ffmpeg

步驟 1：添加 Microsoft Graph 憑據

將 Graph 應用專屬憑據添加到 ~/.hermes/.env：

MSGRAPH_TENANT_ID=<tenant-id>
MSGRAPH_CLIENT_ID=<client-id>
MSGRAPH_CLIENT_SECRET=<client-secret>

這些憑據用於：

• Graph 客戶端基礎
• 訂閱維護命令
• 會議解析和工件獲取
• 當您不提供專用的 Teams 訪問令牌時，基於 Graph 的 Teams 出站交付

步驟 2：啟用 Graph Webhook 監聽器

Webhook 監聽器是一個名為 msgraph_webhook 的網關平臺。至少需要啟用它並設置一個客戶端狀態值：

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_HOST=127.0.0.1
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=<random-shared-secret>
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

監聽器暴露：

• /msgraph/webhook 用於 Graph 通知
• /health 用於簡單的健康檢查

您需要將公共 HTTPS 端點路由到該監聽器。例如，如果您的公共域是 https://ops.example.com，您的 Graph 通知 URL 通常為：

https://ops.example.com/msgraph/webhook

步驟 3：配置 Teams 交付和管道行為

會議管道從現有的 teams 平臺條目讀取其運行時配置。特定於管道的調節參數位於 teams.extra.meeting_pipeline 下。Teams 出站交付保持在正常的 Teams 平臺配置界面上。

~/.hermes/config.yaml 示例：

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "replace-me"
      accepted_resources:
        - "communications/onlineMeetings"

  teams:
    enabled: true
    extra:
      client_id: "your-teams-client-id"
      client_secret: "your-teams-client-secret"
      tenant_id: "your-teams-tenant-id"

      # outbound summary delivery
      delivery_mode: "graph" # or incoming_webhook
      team_id: "team-id"
      channel_id: "channel-id"
      # incoming_webhook_url: "https://..."

      meeting_pipeline:
        transcript_min_chars: 80
        transcript_required: false
        transcription_fallback: true
        ffmpeg_extract_audio: true
        notion:
          enabled: false
        linear:
          enabled: false

如果您將監聽器綁定到非環回主機（如 0.0.0.0），還必須將 allowed_source_cidrs 設置為 Microsoft 的 webhook 出口範圍。環回綁定（127.0.0.1 / ::1）是預期的開發隧道和本地反向代理設置。

Teams 交付模式

該管道支持現有 Teams 插件中的兩種 Teams 摘要交付模式。

incoming_webhook

當您希望通過簡單的 webhook 將帖子發送到 Teams，而不通過 Graph 創建頻道消息時，請使用此模式。

必需配置：

platforms:
  teams:
    enabled: true
    extra:
      delivery_mode: "incoming_webhook"
      incoming_webhook_url: "https://..."

graph

當您希望 Hermes 通過 Microsoft Graph 將摘要發佈到 Teams 聊天或頻道時，請使用此模式。

支持的目標：

• chat_id
• team_id + channel_id
• team_id + home_channel 作為現有 Teams 平臺的回退

示例：

platforms:
  teams:
    enabled: true
    extra:
      delivery_mode: "graph"
      team_id: "team-id"
      channel_id: "channel-id"

步驟 4：啟動網關

更新配置後，正常啟動 Hermes：

hermes gateway run

或者，如果您在 Docker 中運行 Hermes，請以與部署相同的方式啟動網關。

檢查監聽器：

curl http://localhost:8646/health

步驟 5：創建 Graph 訂閱

使用插件 CLI 創建和檢查訂閱。

示例：

hermes teams-pipeline subscribe \
  --resource communications/onlineMeetings/getAllTranscripts \
  --notification-url https://ops.example.com/msgraph/webhook \
  --client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"

hermes teams-pipeline subscribe \
  --resource communications/onlineMeetings/getAllRecordings \
  --notification-url https://ops.example.com/msgraph/webhook \
  --client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"

Graph 訂閱在 72 小時後過期

Microsoft Graph 將 webhook 訂閱限制為 72 小時，且不會自動續訂。您必須在上線前安排 hermes teams-pipeline maintain-subscriptions，否則在手動創建訂閱三天後，通知將靜默停止。請參閱操作員運行手冊中的 自動化訂閱續訂 — 三種選項（Hermes cron、systemd timer、普通 crontab）。

有關訂閱維護和日常操作員流程，請繼續閱讀指南：操作 Teams 會議管道。

驗證

運行內置的驗證快照：

hermes teams-pipeline validate

有用的配套檢查：

hermes teams-pipeline token-health
hermes teams-pipeline subscriptions

故障排除

問題	檢查事項
Graph webhook 驗證失敗	確認公共 URL 正確且可訪問，並且 Graph 正在調用確切的 /msgraph/webhook 路徑
hermes teams-pipeline list 中未顯示作業	確認已啟用 msgraph_webhook，並且訂閱指向正確的通知 URL
Transcript-first 始終無法成功	檢查 Graph 對轉錄資源的權限，以及該會議是否存在轉錄工件
錄製回退失敗	確認已安裝 ffmpeg，並且 Graph 應用可以訪問錄製工件
Teams 摘要交付失敗	重新檢查 delivery_mode、目標 ID 和 Teams 身份驗證配置

相關文檔

• Microsoft Teams 機器人設置
• 操作 Teams 會議管道