Microsoft Teams 会议

当你希望 Hermes 接收 Microsoft Graph 会议事件、优先获取会议记录（transcript）、在无可用记录时回退到录音加语音转文本（STT），并将结构化摘要发送到下游接收端时，使用 Teams 会议流水线。

本页面重点介绍设置和启用：

Graph 凭据
webhook 监听器配置
Teams 发送模式
流水线配置结构

有关日常运维、上线检查和运维工作表，请使用专用指南：运维 Teams 会议流水线。

此功能的作用

流水线：

接收 Microsoft Graph webhook 事件
解析会议并优先使用会议记录（transcript）产物
当没有可用会议记录时，回退到录音下载加 STT
在本地存储持久的作业状态和接收端记录
可以将摘要写入 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 安装
现有的 Microsoft Teams 机器人设置（如果你需要 Teams 出站发送）
具有你计划订阅的会议资源所需权限的 Microsoft Graph 应用程序凭据
Microsoft Graph 可以调用的用于 webhook 发送的公共 HTTPS URL
如果需要录音加 STT 回退，需要安装 ffmpeg

步骤 1：添加 Microsoft Graph 凭据

将 Graph 仅应用程序（app-only）凭据添加到 ~/.hermes/.env：

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

这些凭据用于：

Graph 客户端基础
订阅维护命令
会议解析和产物获取
当你不提供专用 Teams 访问令牌时，基于 Graph 的 Teams 出站发送

步骤 2：启用 Graph Webhook 监听器

webhook 监听器是一个名为 msgraph_webhook 的网关平台。至少，启用它并设置一个客户端状态值：

MSGRAPH_WEBHOOK_ENABLED=true
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:
      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"

      # 出站摘要发送
      delivery_mode: "graph" # 或 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

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、plain 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 身份验证配置

此功能的作用​

先决条件​

步骤 1：添加 Microsoft Graph 凭据​

步骤 2：启用 Graph Webhook 监听器​

步骤 3：配置 Teams 发送和流水线行为​

Teams 发送模式​

incoming_webhook​

graph​

步骤 4：启动网关​

步骤 5：创建 Graph 订阅​

验证​

故障排查​

相关文档​