better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/messaging/sms.md

@@ -0,0 +1,203 @@
+---
+sidebar_position: 8
+sidebar_label: "SMS (Twilio)"
+title: "SMS (Twilio)"
+description: "通过 Twilio 将 Hermes Agent 设置为 SMS 聊天机器人"
+---
+
+# SMS 设置（Twilio）
+
+Hermes 通过 [Twilio](https://www.twilio.com/) API 接入 SMS。用户向你的 Twilio 电话号码发送短信，即可获得 AI 回复——与 Telegram 或 Discord 的对话体验相同，但通过标准短信进行。
+
+:::info 共享凭据
+SMS gateway（网关）与可选的 [telephony skill](/reference/skills-catalog) 共享凭据。如果你已为语音通话或单次 SMS 配置了 Twilio，该 gateway 可直接使用相同的 `TWILIO_ACCOUNT_SID`、`TWILIO_AUTH_TOKEN` 和 `TWILIO_PHONE_NUMBER`。
+:::
+
+---
+
+## 前提条件
+
+- **Twilio 账户** — [在 twilio.com 注册](https://www.twilio.com/try-twilio)（提供免费试用）
+- **具备 SMS 功能的 Twilio 电话号码**
+- **可公开访问的服务器** — Twilio 在收到 SMS 时会向你的服务器发送 webhook
+- **aiohttp** — `cd ~/.hermes/hermes-agent && uv pip install -e ".[sms]"`
+
+---
+
+## 第一步：获取 Twilio 凭据
+
+1. 前往 [Twilio 控制台](https://console.twilio.com/)
+2. 从仪表板复制你的 **Account SID** 和 **Auth Token**
+3. 前往 **Phone Numbers → Manage → Active Numbers**，记录 E.164 格式的电话号码（例如 `+15551234567`）
+
+---
+
+## 第二步：配置 Hermes
+
+### 交互式设置（推荐）
+
+```bash
+hermes gateway setup
+```
+
+从平台列表中选择 **SMS (Twilio)**，向导将提示你输入凭据。
+
+### 手动设置
+
+在 `~/.hermes/.env` 中添加：
+
+```bash
+TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+TWILIO_AUTH_TOKEN=your_auth_token_here
+TWILIO_PHONE_NUMBER=+15551234567
+
+# 安全：限制特定电话号码（推荐）
+SMS_ALLOWED_USERS=+15559876543,+15551112222
+
+# 可选：为 cron 任务投递设置主频道
+SMS_HOME_CHANNEL=+15559876543
+```
+
+---
+
+## 第三步：配置 Twilio Webhook
+
+Twilio 需要知道将传入消息发送到哪里。在 [Twilio 控制台](https://console.twilio.com/) 中：
+
+1. 前往 **Phone Numbers → Manage → Active Numbers**
+2. 点击你的电话号码
+3. 在 **Messaging → A MESSAGE COMES IN** 下，设置：
+   - **Webhook**：`https://your-server:8080/webhooks/twilio`
+   - **HTTP Method**：`POST`
+
+:::tip 暴露你的 Webhook
+如果你在本地运行 Hermes，请使用隧道工具暴露 webhook：
+
+```bash
+# 使用 cloudflared
+cloudflared tunnel --url http://localhost:8080
+
+# 使用 ngrok
+ngrok http 8080
+```
+
+将生成的公网 URL 设置为你的 Twilio webhook。
+:::
+
+**将 `SMS_WEBHOOK_URL` 设置为你在 Twilio 中配置的相同 URL。** 这是 Twilio 签名验证所必需的——如果未设置，适配器将拒绝启动：
+
+```bash
+# 必须与 Twilio 控制台中的 webhook URL 一致
+SMS_WEBHOOK_URL=https://your-server:8080/webhooks/twilio
+```
+
+webhook 端口默认为 `8080`，可通过以下方式覆盖：
+
+```bash
+SMS_WEBHOOK_PORT=3000
+```
+
+---
+
+## 第四步：启动 Gateway
+
+```bash
+hermes gateway
+```
+
+你应该看到：
+
+```
+[sms] Twilio webhook server listening on 127.0.0.1:8080, from: +1555***4567
+```
+
+如果看到 `Refusing to start: SMS_WEBHOOK_URL is required`，请将 `SMS_WEBHOOK_URL` 设置为你在 Twilio 控制台中配置的公网 URL（参见第三步）。
+
+向你的 Twilio 号码发送短信——Hermes 将通过 SMS 回复。
+
+---
+
+## 环境变量
+
+| 变量 | 是否必填 | 说明 |
+|----------|----------|-------------|
+| `TWILIO_ACCOUNT_SID` | 是 | Twilio Account SID（以 `AC` 开头） |
+| `TWILIO_AUTH_TOKEN` | 是 | Twilio Auth Token（同时用于 webhook 签名验证） |
+| `TWILIO_PHONE_NUMBER` | 是 | 你的 Twilio 电话号码（E.164 格式） |
+| `SMS_WEBHOOK_URL` | 是 | 用于 Twilio 签名验证的公网 URL——必须与 Twilio 控制台中的 webhook URL 一致 |
+| `SMS_WEBHOOK_PORT` | 否 | Webhook 监听端口（默认：`8080`） |
+| `SMS_WEBHOOK_HOST` | 否 | Webhook 绑定地址（默认：`127.0.0.1`） |
+| `SMS_INSECURE_NO_SIGNATURE` | 否 | 设为 `true` 可禁用签名验证（仅限本地开发——**不适用于生产环境**） |
+| `SMS_ALLOWED_USERS` | 否 | 允许聊天的 E.164 格式电话号码，逗号分隔 |
+| `SMS_ALLOW_ALL_USERS` | 否 | 设为 `true` 允许所有人（不推荐） |
+| `SMS_HOME_CHANNEL` | 否 | 用于 cron 任务／通知投递的电话号码 |
+| `SMS_HOME_CHANNEL_NAME` | 否 | 主频道的显示名称（默认：`Home`） |
+
+---
+
+## SMS 特有行为
+
+- **纯文本** — Markdown 会被自动剥离，因为 SMS 会将其渲染为字面字符
+- **1600 字符限制** — 较长的回复会在自然边界处（换行符，其次是空格）拆分为多条消息
+- **防回声** — 来自你自己 Twilio 号码的消息将被忽略，以防止循环
+- **电话号码脱敏** — 日志中的电话号码会被脱敏处理以保护隐私
+
+---
+
+## 安全
+
+### Webhook 签名验证
+
+Hermes 通过验证 `X-Twilio-Signature` 头（HMAC-SHA1）来确认入站 webhook 确实来自 Twilio，防止攻击者注入伪造消息。
+
+**`SMS_WEBHOOK_URL` 为必填项。** 将其设置为你在 Twilio 控制台中配置的公网 URL，否则适配器将拒绝启动。
+
+如需在本地开发时不使用公网 URL，可禁用验证：
+
+```bash
+# 仅限本地开发——不适用于生产环境
+SMS_INSECURE_NO_SIGNATURE=true
+```
+
+### 用户白名单
+
+**Gateway 默认拒绝所有用户。** 请配置白名单：
+
+```bash
+# 推荐：限制特定电话号码
+SMS_ALLOWED_USERS=+15559876543,+15551112222
+
+# 或允许所有人（对于具有终端访问权限的机器人，不推荐）
+SMS_ALLOW_ALL_USERS=true
+```
+
+:::warning
+SMS 没有内置加密。除非你了解相关安全风险，否则不要通过 SMS 进行敏感操作。对于敏感场景，请优先使用 Signal 或 Telegram。
+:::
+
+---
+
+## 故障排查
+
+### 消息未到达
+
+1. 检查 Twilio webhook URL 是否正确且可公开访问
+2. 验证 `TWILIO_ACCOUNT_SID` 和 `TWILIO_AUTH_TOKEN` 是否正确
+3. 在 Twilio 控制台 → **Monitor → Logs → Messaging** 中查看投递错误
+4. 确保你的电话号码在 `SMS_ALLOWED_USERS` 中（或设置 `SMS_ALLOW_ALL_USERS=true`）
+
+### 回复未发送
+
+1. 检查 `TWILIO_PHONE_NUMBER` 是否正确设置（E.164 格式，带 `+`）
+2. 验证你的 Twilio 账户是否有支持 SMS 的号码
+3. 查看 Hermes gateway 日志中的 Twilio API 错误
+
+### Webhook 端口冲突
+
+如果 8080 端口已被占用，请更改端口：
+
+```bash
+SMS_WEBHOOK_PORT=3001
+```
+
+并在 Twilio 控制台中更新 webhook URL 以匹配新端口。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/messaging/teams-meetings.md

@@ -0,0 +1,233 @@
+---
+sidebar_position: 6
+title: "Teams 会议"
+description: "使用 Microsoft Graph webhook 配置 Microsoft Teams 会议摘要流水线"
+---
+
+# Microsoft Teams 会议
+
+当你希望 Hermes 接收 Microsoft Graph 会议事件、优先获取转录文本、在无可用转录时回退到录音加 STT（语音转文字），并将结构化摘要输出到下游 sink 时，请使用 Teams 会议流水线。
+
+本页重点介绍配置与启用：
+- Graph 凭据
+- webhook 监听器配置
+- Teams 投递模式
+- 流水线配置结构
+
+关于上线后的日常运维、上线检查及运维工作表，请参阅专项指南：[运维 Teams 会议流水线](/guides/operate-teams-meeting-pipeline)。
+
+## 功能说明
+
+该流水线：
+1. 接收 Microsoft Graph webhook 事件
+2. 解析会议并优先使用转录文件
+3. 在无可用转录时回退到录音下载加 STT
+4. 在本地存储持久化任务状态和 sink 记录
+5. 可将摘要写入 Notion、Linear 和 Microsoft Teams
+
+运维操作通过 CLI 完成（`teams-pipeline` 子命令由 `teams_pipeline` 插件注册——通过 `hermes plugins enable teams_pipeline` 启用，或在 `config.yaml` 中设置 `plugins.enabled: [teams_pipeline]`）：
+
+```bash
+hermes teams-pipeline validate
+hermes teams-pipeline list
+hermes teams-pipeline maintain-subscriptions
+```
+
+## 前提条件
+
+启用会议流水线前，请确保已具备：
+
+- 可正常运行的 Hermes 安装
+- 若需要 Teams 出站投递，需完成现有的 [Microsoft Teams bot 配置](/user-guide/messaging/teams)
+- 具备订阅所需会议资源权限的 Microsoft Graph 应用凭据
+- Microsoft Graph 可调用的公网 HTTPS URL，用于 webhook 投递
+- 若需要录音加 STT 回退，需安装 `ffmpeg`
+
+## 第一步：添加 Microsoft Graph 凭据
+
+将 Graph 应用凭据添加到 `~/.hermes/.env`：
+
+```bash
+MSGRAPH_TENANT_ID=<tenant-id>
+MSGRAPH_CLIENT_ID=<client-id>
+MSGRAPH_CLIENT_SECRET=<client-secret>
+```
+
+这些凭据用于：
+- Graph 客户端基础层
+- 订阅维护命令
+- 会议解析和文件获取
+- 未提供专用 Teams 访问令牌时，通过 Graph 进行 Teams 出站投递
+
+## 第二步：启用 Graph Webhook 监听器
+
+webhook 监听器是一个名为 `msgraph_webhook` 的 gateway 平台。至少需要启用它并设置一个 client state 值：
+
+```bash
+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 通常为：
+
+```text
+https://ops.example.com/msgraph/webhook
+```
+
+## 第三步：配置 Teams 投递与流水线行为
+
+会议流水线从现有的 `teams` 平台条目读取运行时配置。流水线专属参数位于 `teams.extra.meeting_pipeline` 下。Teams 出站投递仍使用常规 Teams 平台配置。
+
+`~/.hermes/config.yaml` 示例：
+
+```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"
+
+      # 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
+```
+
+## Teams 投递模式
+
+流水线在现有 Teams 插件内支持两种 Teams 摘要投递模式。
+
+### `incoming_webhook`
+
+当你希望通过简单的 webhook 将消息发送到 Teams，而无需通过 Graph 创建频道消息时，使用此模式。
+
+所需配置：
+
+```yaml
+platforms:
+  teams:
+    enabled: true
+    extra:
+      delivery_mode: "incoming_webhook"
+      incoming_webhook_url: "https://..."
+```
+
+### `graph`
+
+当你希望 Hermes 通过 Microsoft Graph 将摘要发送到 Teams 聊天或频道时，使用此模式。
+
+支持的目标：
+- `chat_id`
+- `team_id` + `channel_id`
+- 现有 Teams 平台的 `team_id` + `home_channel` 回退
+
+示例：
+
+```yaml
+platforms:
+  teams:
+    enabled: true
+    extra:
+      delivery_mode: "graph"
+      team_id: "team-id"
+      channel_id: "channel-id"
+```
+
+## 第四步：启动 Gateway
+
+更新配置后正常启动 Hermes：
+
+```bash
+hermes gateway run
+```
+
+若你在 Docker 中运行 Hermes，按现有部署方式启动 gateway 即可。
+
+检查监听器：
+
+```bash
+curl http://localhost:8646/health
+```
+
+## 第五步：创建 Graph 订阅
+
+使用插件 CLI 创建和查看订阅。
+
+示例：
+
+```bash
+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"
+```
+
+:::warning Graph 订阅在 72 小时后过期
+
+Microsoft Graph 将 webhook 订阅上限设为 72 小时，且不会自动续期。你**必须**在上线前调度 `hermes teams-pipeline maintain-subscriptions`，否则通知将在手动创建订阅三天后静默停止。请参阅运维手册中的[自动化订阅续期](/guides/operate-teams-meeting-pipeline#automating-subscription-renewal-required-for-production)——提供三种方案（Hermes cron、systemd timer、普通 crontab）。
+
+:::
+
+关于订阅维护和上线后的运维流程，请继续阅读指南：[运维 Teams 会议流水线](/guides/operate-teams-meeting-pipeline)。
+
+## 验证
+
+运行内置验证快照：
+
+```bash
+hermes teams-pipeline validate
+```
+
+常用辅助检查：
+
+```bash
+hermes teams-pipeline token-health
+hermes teams-pipeline subscriptions
+```
+
+## 故障排查
+
+| 问题 | 检查项 |
+|---------|---------------|
+| Graph webhook 验证失败 | 确认公网 URL 正确且可访问，并确认 Graph 调用的路径为 `/msgraph/webhook` |
+| `hermes teams-pipeline list` 中未出现任务 | 确认 `msgraph_webhook` 已启用，且订阅指向正确的通知 URL |
+| 转录优先从未成功 | 检查转录资源的 Graph 权限，以及该会议是否存在转录文件 |
+| 录音回退失败 | 确认已安装 `ffmpeg`，且 Graph 应用可访问录音文件 |
+| Teams 摘要投递失败 | 重新检查 `delivery_mode`、目标 ID 及 Teams 认证配置 |
+
+## 相关文档
+
+- [Microsoft Teams bot 配置](/user-guide/messaging/teams)
+- [运维 Teams 会议流水线](/guides/operate-teams-meeting-pipeline)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/messaging/teams.md

@@ -0,0 +1,255 @@
+---
+sidebar_position: 5
+title: "Microsoft Teams"
+description: "将 Hermes Agent 设置为 Microsoft Teams 机器人"
+---
+
+# Microsoft Teams 设置
+
+将 Hermes Agent 作为机器人接入 Microsoft Teams。与 Slack 的 Socket Mode 不同，Teams 通过调用**公开 HTTPS webhook**（钩子）来投递消息，因此你的实例需要一个可公开访问的端点——本地开发时使用开发隧道，生产环境使用真实域名。
+
+如果你需要的是来自 Microsoft Graph 事件的会议摘要，而非普通的机器人对话，请使用专用设置页面：[Teams 会议](/user-guide/messaging/teams-meetings)。
+
+## 机器人的响应方式
+
+| 场景 | 行为 |
+|------|------|
+| **个人聊天（私信）** | 机器人响应每一条消息，无需 @提及。 |
+| **群聊** | 机器人仅在被 @提及时响应。 |
+| **频道** | 机器人仅在被 @提及时响应。 |
+
+Teams 将 @提及作为普通消息投递，其中包含 `<at>BotName</at>` 标签，Hermes 在处理前会自动去除这些标签。
+
+---
+
+## 第一步：安装 Teams CLI
+
+`@microsoft/teams.cli` 可自动完成机器人注册，无需进入 Azure 门户。
+
+```bash
+npm install -g @microsoft/teams.cli@preview
+teams login
+```
+
+验证登录状态并查找你自己的 AAD 对象 ID（`TEAMS_ALLOWED_USERS` 需要用到）：
+
+```bash
+teams status --verbose
+```
+
+---
+
+## 第二步：暴露 Webhook 端口
+
+Teams 无法向 `localhost` 投递消息。本地开发时，使用任意隧道工具获取一个公开的 HTTPS URL。默认端口为 `3978`，如需更改可通过 `TEAMS_PORT` 设置。
+
+```bash
+# devtunnel（Microsoft 官方）
+devtunnel create hermes-bot --allow-anonymous
+devtunnel port create hermes-bot -p 3978 --protocol http  # 如已修改 TEAMS_PORT，请替换 3978
+devtunnel host hermes-bot
+
+# ngrok
+ngrok http 3978  # 如已修改 TEAMS_PORT，请替换 3978
+
+# cloudflared
+cloudflared tunnel --url http://localhost:3978  # 如已修改 TEAMS_PORT，请替换 3978
+```
+
+从输出中复制 `https://` URL——下一步会用到。开发期间保持隧道运行。
+
+公开隧道 URL 使用 HTTPS，但 Hermes 的本地 webhook 监听器使用纯 HTTP。隧道会终止 TLS，并将 HTTP 转发到 `3978` 端口；不要将本地隧道端口配置为 HTTPS。
+
+生产环境请将机器人端点指向服务器的公开域名（参见[生产部署](#production-deployment)）。
+
+---
+
+## 第三步：创建机器人
+
+```bash
+teams app create \
+  --name "Hermes" \
+  --endpoint "https://<your-tunnel-url>/api/messages"
+```
+
+CLI 会输出你的 `CLIENT_ID`、`CLIENT_SECRET` 和 `TENANT_ID`，以及第六步所需的安装链接。请保存客户端密钥——它不会再次显示。
+
+---
+
+## 第四步：配置环境变量
+
+添加到 `~/.hermes/.env`：
+
+```bash
+# 必填
+TEAMS_CLIENT_ID=<your-client-id>
+TEAMS_CLIENT_SECRET=<your-client-secret>
+TEAMS_TENANT_ID=<your-tenant-id>
+
+# 限制特定用户访问（推荐）
+# 使用 `teams status --verbose` 获取 AAD 对象 ID
+TEAMS_ALLOWED_USERS=<your-aad-object-id>
+```
+
+---
+
+## 第五步：启动 Gateway
+
+```bash
+HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d gateway
+```
+
+此命令启动 gateway。默认 webhook 端口为 `3978`（可通过 `TEAMS_PORT` 覆盖）。检查运行状态：
+
+```bash
+curl http://localhost:3978/health   # 应返回：ok
+docker logs -f hermes
+```
+
+查找以下日志：
+```
+[teams] Webhook server listening on 0.0.0.0:3978/api/messages
+```
+
+---
+
+## 第六步：在 Teams 中安装应用
+
+```bash
+teams app get <teamsAppId> --install-link
+```
+
+在浏览器中打开输出的链接——它会直接在 Teams 客户端中打开。安装完成后，向机器人发送一条私信，即可开始使用。
+
+---
+
+## 配置参考
+
+### 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `TEAMS_CLIENT_ID` | Azure AD 应用（客户端）ID |
+| `TEAMS_CLIENT_SECRET` | Azure AD 客户端密钥 |
+| `TEAMS_TENANT_ID` | Azure AD 租户 ID |
+| `TEAMS_ALLOWED_USERS` | 允许使用机器人的 AAD 对象 ID，逗号分隔 |
+| `TEAMS_ALLOW_ALL_USERS` | 设为 `true` 可跳过白名单，允许所有人使用 |
+| `TEAMS_HOME_CHANNEL` | 用于 cron/主动消息投递的会话 ID |
+| `TEAMS_HOME_CHANNEL_NAME` | 主频道的显示名称 |
+| `TEAMS_PORT` | Webhook 端口（默认：`3978`） |
+
+### config.yaml
+
+也可通过 `~/.hermes/config.yaml` 进行配置：
+
+```yaml
+platforms:
+  teams:
+    enabled: true
+    extra:
+      client_id: "your-client-id"
+      client_secret: "your-secret"
+      tenant_id: "your-tenant-id"
+      port: 3978
+```
+
+---
+
+## 功能特性
+
+### 交互式审批卡片
+
+当 Agent 需要执行可能存在风险的命令时，它会发送一张带有四个按钮的 Adaptive Card，而不是要求你输入 `/approve`：
+
+- **Allow Once**——仅批准此次特定命令
+- **Allow Session**——在本次会话期间批准此模式
+- **Always Allow**——永久批准此模式
+- **Deny**——拒绝该命令
+
+点击按钮即可内联完成审批，卡片会被替换为决策结果。
+
+### 会议摘要投递（Teams 会议 Pipeline）
+
+当 [Teams 会议 pipeline 插件](/user-guide/messaging/msgraph-webhook)启用后，此适配器同时负责会议摘要的出站投递——一个 Teams 集成面，而非两个。会议转录摘要生成后，写入器会将摘要发布到你指定的 Teams 目标。
+
+Pipeline 摘要投递在 `teams` 平台条目下与机器人配置并列配置：
+
+```yaml
+platforms:
+  teams:
+    enabled: true
+    extra:
+      # 现有机器人配置（client_id、client_secret、tenant_id、port）...
+
+      # 会议摘要投递（仅在 teams_pipeline 插件启用时生效）
+      delivery_mode: "graph"       # 或 "incoming_webhook"
+      # 对于 delivery_mode: graph — 选择其中一项：
+      chat_id: "19:meeting_..."    # 发布到 Teams 聊天
+      # team_id: "..."             # 或发布到频道
+      # channel_id: "..."
+      # access_token: "..."        # 可选；回退到 MSGRAPH_* 应用凭据
+      # 对于 delivery_mode: incoming_webhook：
+      # incoming_webhook_url: "https://outlook.office.com/webhook/..."
+```
+
+| 模式 | 适用场景 | 权衡 |
+|------|----------|------|
+| `incoming_webhook` | 使用 Teams 生成的静态 URL，简单地将摘要发布到某个频道。 | 不支持回复线程和表情回应，显示为 webhook 配置的身份。 |
+| `graph` | 通过 Microsoft Graph 以机器人身份发布带线程的频道帖子或 1:1/群聊消息。 | 需要完成 [Graph 应用注册](/guides/microsoft-graph-app-registration)，并具备 `ChannelMessage.Send`（频道）或 `Chat.ReadWrite.All`（聊天）应用权限。 |
+
+如果 `teams_pipeline` 插件**未启用**，这些设置不会生效——它们仅在 pipeline 运行时绑定到 Graph webhook 入口时才会激活。
+
+---
+
+## 生产部署
+
+对于永久服务器，请在反向代理处终止 TLS，并将请求转发到 Hermes 的纯 HTTP 监听器，通常为 `http://127.0.0.1:3978`。使用该代理的公开 HTTPS 端点注册机器人：
+
+```bash
+teams app create \
+  --name "Hermes" \
+  --endpoint "https://your-domain.com/api/messages"
+```
+
+如果机器人已创建，只需更新端点：
+
+```bash
+teams app update --id <teamsAppId> --endpoint "https://your-domain.com/api/messages"
+```
+
+确保公开 HTTPS 端点可从互联网访问并使用有效的 TLS 证书。Teams 会拒绝自签名证书。请将 Hermes 监听器置于代理后方；`3978` 端口本身不提供 HTTPS。
+
+---
+
+## 故障排查
+
+| 问题 | 解决方案 |
+|------|----------|
+| `health` 端点正常但机器人不响应 | 检查隧道是否仍在运行，以及机器人的消息端点是否与隧道 URL 匹配 |
+| Teams 发送消息时日志显示 `"UNKNOWN / HTTP/1.0" 400` | 隧道或反向代理正在将 HTTPS 转发到 Hermes 的纯 HTTP 监听器。请在代理处终止 TLS，并将 HTTP 转发到 `3978` 端口 |
+| 日志中出现 `KeyError: 'teams'` | 重启容器——此问题已在当前版本中修复 |
+| 机器人响应时出现认证错误 | 验证 `TEAMS_CLIENT_ID`、`TEAMS_CLIENT_SECRET` 和 `TEAMS_TENANT_ID` 是否均已正确设置 |
+| `No inference provider configured` | 检查 `~/.hermes/.env` 中是否设置了 `ANTHROPIC_API_KEY`（或其他提供商密钥） |
+| 机器人收到消息但忽略它们 | 你的 AAD 对象 ID 可能不在 `TEAMS_ALLOWED_USERS` 中。运行 `teams status --verbose` 查找 |
+| 隧道 URL 在重启后变更 | 使用命名隧道（`devtunnel create hermes-bot`）时，devtunnel URL 是持久的。ngrok 和 cloudflared 每次运行都会生成新 URL（除非你有付费计划）——URL 变更时请用 `teams app update` 更新机器人端点 |
+| Teams 显示"此机器人未响应" | Webhook 返回了错误。检查 `docker logs hermes` 中的错误堆栈 |
+| 日志中出现 `[teams] Failed to connect` | SDK 认证失败。仔细检查凭据，并确认租户 ID 与 `teams login` 时使用的账户匹配 |
+
+---
+
+## 安全性
+
+:::warning
+**务必设置 `TEAMS_ALLOWED_USERS`**，填入授权用户的 AAD 对象 ID。否则，任何能找到或安装你的机器人的人都可以与其交互。
+
+将 `TEAMS_CLIENT_SECRET` 视同密码对待——定期通过 Azure 门户或 Teams CLI 进行轮换。
+:::
+
+- 将凭据存储在权限为 `600` 的 `~/.hermes/.env` 中（`chmod 600 ~/.hermes/.env`）
+- 机器人仅接受 `TEAMS_ALLOWED_USERS` 中用户的消息；未授权的消息会被静默丢弃
+- 你的公开端点（`/api/messages`）由 Teams Bot Framework 进行认证——不含有效 JWT 的请求会被拒绝
+
+## 相关文档
+
+- [Teams 会议](/user-guide/messaging/teams-meetings)
+- [运营 Teams 会议 Pipeline](/guides/operate-teams-meeting-pipeline)