运行 Teams 会议 Pipeline

hermes agent 运行 Teams 会议 Pipeline

请在你已经从 Teams Meetings 启用该功能之后，再使用本指南。

本页面涵盖：

operator CLI 流程
常规 subscription 维护
故障分诊
上线检查
rollout worksheet

核心 Operator 命令

验证配置快照

hermes teams-pipeline validate

每次配置变更后，请先使用这个命令。

检查 token 健康状态

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

当你怀疑 auth state 过期时，使用 --force-refresh。

检查 subscriptions

hermes teams-pipeline subscriptions

续订即将过期的 subscriptions

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

自动化 subscription 续订（生产环境必需）

Microsoft Graph subscriptions 最多 72 小时后过期。如果没有任何东西续订它们，会议通知会在 3 天后静默停止，pipeline 看起来就像“坏了”。这是任何 Graph-backed integration 的 #1 运维故障模式。

你必须按计划运行 maintain-subscriptions。从以下三个选项中选择一个：

选项 1：Hermes cron（如果你已经运行 Hermes gateway，推荐）

Hermes 随附内置 cron scheduler。--no-agent 模式会将脚本作为 job 运行（而不是使用 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 小时运行一次的 script-only cron job（相对于 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        # scheduler status

选项 2：systemd timer（推荐用于 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_* credentials。最简单的修复方式：在 crontab 调用的 wrapper script 顶部 source ~/.hermes/.env。

验证续订是否正常工作

设置好 schedule 后，在第一次计划运行后检查续订活动：

hermes teams-pipeline subscriptions   # should show expirationDateTime advanced
hermes teams-pipeline maintain-subscriptions --dry-run   # should show "0 expiring soon" most of the time

如果你发现 Graph webhook 在大约 72 小时后神秘地“停止工作”，这是首先要检查的事情：续订 job 是否真的运行了？

检查最近 jobs

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

重放已存储的 job

hermes teams-pipeline run <job-id>

Dry-run 会议 artifact 获取

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

常规 Runbook

首次设置后

按顺序运行这些命令：

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 delivery target 仍然是正确的 chat 或 channel

在更改 webhook URLs 或 delivery targets 之前

更新 public notification URL 或 Teams target config
运行 hermes teams-pipeline validate
续订或重新创建受影响的 subscriptions
确认新事件进入预期的 sink

故障分诊

没有创建 jobs

检查：

msgraph_webhook 是否已启用
public notification URL 是否指向 /msgraph/webhook
subscription 中的 client state 是否与 MSGRAPH_WEBHOOK_CLIENT_STATE 匹配
subscriptions 是否仍然远程存在并且没有过期

Jobs 保持 retry 状态，或在 summarization 前失败

检查：

transcript permissions 和可用性
recording permissions 和 artifact 可用性
如果启用了 recording fallback，检查 ffmpeg 可用性
Graph token health

Summaries 已生成但没有投递到 Teams

检查：

platforms.teams.enabled: true
delivery_mode
webhook mode 下的 incoming_webhook_url
Graph mode 下的 chat_id 或 team_id 加 channel_id
如果使用 Graph posting，检查 Teams auth config

重复或意外 replays

检查：

你是否手动使用 hermes teams-pipeline run 重放了 job
该 meeting 的 sink record 是否已经存在
你是否在本地配置中有意启用了 resend path

上线检查清单

[] Graph credentials 存在且正确
[] msgraph_webhook 已启用，并且可从公网访问
[] MSGRAPH_WEBHOOK_CLIENT_STATE 已设置，并且与 subscriptions 匹配
[] transcript subscription 已创建
[] 如果需要 STT fallback，recording subscription 已创建
[] 如果启用了 recording fallback，ffmpeg 已安装
[] Teams outbound delivery target 已配置并验证
[] Notion 和 Linear sinks 仅在实际需要时配置
[] hermes teams-pipeline validate 返回 OK snapshot
[] hermes teams-pipeline token-health --force-refresh 成功
[] maintain-subscriptions 已调度（Hermes cron、systemd timer 或 crontab —— 参见 Automating subscription renewal）。如果没有这一步，Graph subscriptions 会在 72 小时内静默过期。
[] 一个真实的端到端 meeting event 已生成 stored job
[] 至少一个 summary 已到达预期 delivery sink

Delivery-Mode 决策指南

Mode	使用场景	取舍
`incoming_webhook`	你只需要简单地发布到 Teams	设置最简单，控制较少
`graph`	你需要通过 Graph 发布到 channel 或 chat	控制更多，但需要更多 auth 和 target config

Operator Worksheet

上线前填写：

Item	Value
Public notification URL
Graph tenant ID
Graph client ID
Webhook client state
Transcript resource subscription
Recording resource subscription
Teams delivery mode
Teams chat ID or team/channel
Notion database ID
Linear team ID
Store path override, if any
Owner for daily checks

Change Review Worksheet

在更改部署前使用：

Question	Answer
Are we changing the public webhook URL?
Are we rotating Graph credentials?
Are we changing Teams delivery mode?
Are we moving to a new Teams chat or channel?
Do subscriptions need to be recreated or renewed?
Do we need a fresh end-to-end verification run?