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 会议管道