# 📢 多渠道通知配置完整指南

## 概述

Tavily MCP 支持将使用统计和告警通过 **8 种渠道**发送通知，每种渠道都有专门优化的消息格式。系统会**自动识别**通知类型，无需手动配置。

## 🎯 支持的通知渠道

1. **Slack** - 企业协作（国际）
2. **Discord** - 社区/团队沟通
3. **Telegram** - 即时通讯
4. **企业微信（Weixin Work）** - 企业协作（中国）
5. **钉钉（DingTalk）** - 企业协作（中国）
6. **飞书（Feishu/Lark）** - 企业协作（中国）
7. **邮件（Email）** - 传统邮件通知
8. **通用 Webhook** - 自定义服务

---

## 📋 快速配置对照表

| 渠道 | 自动识别 | 额外配置 | 消息格式 |
|------|---------|---------|---------|
| Slack | ✅ | 无 | Attachments（彩色卡片）|
| Discord | ✅ | 无 | Embeds（富文本卡片）|
| Telegram | ✅ | 需要 | Markdown |
| 企业微信 | ✅ | 无 | 文本 |
| 钉钉 | ✅ | 无 | Markdown |
| 飞书 | ✅ | 无 | Interactive Card |
| Webhook | ✅ | 无 | JSON |

---

## 1️⃣ Slack 配置

### 获取 Webhook URL

1. 访问 https://api.slack.com/apps
2. 创建新应用或选择现有应用
3. 进入 "Incoming Webhooks"
4. 启用 Incoming Webhooks
5. 点击 "Add New Webhook to Workspace"
6. 选择频道并授权
7. 复制 Webhook URL

### 配置示例

```json
{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "your-api-key",
        "USAGE_TRACKING_ENABLED": "true",
        "USAGE_CALLBACK_URL": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX",
        "USAGE_REPORT_INTERVAL": "3600"
      }
    }
  }
}
```

### 消息示例

```
📊 Tavily MCP Usage Report
┌────────────────────────────┐
│ 📊 Total Requests    │ 150 │
│ ✅ Successful        │ 145 │
│ ❌ Failed            │ 5   │
│ 🔍 Search            │ 100 │
│ 📄 Extract           │ 30  │
│ 🕷️ Crawl             │ 15  │
└────────────────────────────┘
```

**特点：**
- 彩色侧边栏（绿色=正常，橙色=警告，红色=错误）
- 紧凑的字段布局
- 时间戳自动格式化

---

## 2️⃣ Discord 配置

### 获取 Webhook URL

1. 打开 Discord 服务器设置
2. 选择"整合" → "Webhook"
3. 点击"新建 Webhook"
4. 设置名称和频道
5. 复制 Webhook URL

### 配置示例

```json
{
  "env": {
    "TAVILY_API_KEY": "your-api-key",
    "USAGE_TRACKING_ENABLED": "true",
    "USAGE_CALLBACK_URL": "https://discord.com/api/webhooks/1234567890/abcdefghijklmnopqrstuvwxyz",
    "USAGE_REPORT_INTERVAL": "3600"
  }
}
```

### 消息示例

```
📊 Usage Report
Total: 150 | Success: 96.67%
━━━━━━━━━━━━━━━━━━
✅ Successful  │ 145
❌ Failed      │ 5
🔍 Search      │ 100
📄 Extract     │ 30
🕷️ Crawl       │ 15
🗺️ Map         │ 5
```

**特点：**
- Rich Embed 格式
- 彩色边框
- Inline 字段排列
- Markdown 支持

---

## 3️⃣ Telegram 配置

### 获取配置信息

1. 与 @BotFather 对话创建 Bot
2. 获取 Bot Token
3. 将 Bot 添加到群组或获取个人 Chat ID
4. 使用 https://api.telegram.org/bot<TOKEN>/getUpdates 获取 Chat ID

### 配置示例

```json
{
  "env": {
    "TAVILY_API_KEY": "your-api-key",
    "USAGE_TRACKING_ENABLED": "true",
    "USAGE_CALLBACK_URL": "https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage",
    "TELEGRAM_CHAT_ID": "123456789",
    "TELEGRAM_BOT_TOKEN": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
    "USAGE_REPORT_INTERVAL": "3600"
  }
}
```

### 消息示例

```
📊 *Usage Report*
⏰ 2025-12-17 11:20:00

📊 *Usage Summary*
Total: `150`
✅ Success: `145` (96.67%)
❌ Failed: `5`

*By Type:*
🔍 Search: `100`
📄 Extract: `30`
🕷️ Crawl: `15`
🗺️ Map: `5`
```

**特点：**
- Markdown 格式
- 代码块高亮数字
- 清晰的分组结构

---

## 4️⃣ 企业微信（Weixin Work）配置

### 获取 Webhook URL

1. 登录企业微信管理后台
2. 应用管理 → 选择群机器人
3. 添加机器人
4. 复制 Webhook 地址

### 配置示例

```json
{
  "env": {
    "TAVILY_API_KEY": "your-api-key",
    "USAGE_TRACKING_ENABLED": "true",
    "USAGE_CALLBACK_URL": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "USAGE_REPORT_INTERVAL": "3600"
  }
}
```

### 消息示例

```
【Tavily MCP】Usage Report
时间：2025-12-17 11:20:00

总请求数：150
成功：145（96.67%）
失败：5

请求类型分布：
- 搜索：100
- 提取：30
- 爬取：15
- 地图：5
```

**特点：**
- 纯文本格式
- 中文界面
- 清晰的层级结构

---

## 5️⃣ 钉钉（DingTalk）配置

### 获取 Webhook URL

1. 打开钉钉群设置
2. 智能群助手 → 添加机器人
3. 选择"自定义"机器人
4. 设置机器人名称和安全设置
5. 复制 Webhook 地址

### 配置示例

```json
{
  "env": {
    "TAVILY_API_KEY": "your-api-key",
    "USAGE_TRACKING_ENABLED": "true",
    "USAGE_CALLBACK_URL": "https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "USAGE_REPORT_INTERVAL": "3600"
  }
}
```

### 消息示例

```markdown
## Usage Report

**时间：** 2025-12-17 11:20:00

### 📊 使用统计

- **总请求数：** 150
- **成功：** 145（96.67%）
- **失败：** 5

### 请求类型

- 🔍 搜索：100
- 📄 提取：30
- 🕷️ 爬取：15
- 🗺️ 地图：5
```

**特点：**
- Markdown 格式
- 支持标题层级
- Emoji 图标

---

## 6️⃣ 飞书（Feishu/Lark）配置

### 获取 Webhook URL

1. 打开飞书群设置
2. 群机器人 → 添加机器人
3. 选择"自定义机器人"
4. 配置机器人
5. 复制 Webhook 地址

### 配置示例

```json
{
  "env": {
    "TAVILY_API_KEY": "your-api-key",
    "USAGE_TRACKING_ENABLED": "true",
    "USAGE_CALLBACK_URL": "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "USAGE_REPORT_INTERVAL": "3600"
  }
}
```

### 消息示例

```
╔════════════════════════╗
║ Usage Report          ║
╠════════════════════════╣
║ 🕐 2025-12-17 11:20   ║
╠════════════════════════╣
║ 总请求    │ 150      ║
║ 成功率    │ 96.67%   ║
║ 搜索      │ 100      ║
║ 提取      │ 30       ║
╚════════════════════════╝
```

**特点：**
- Interactive Card 格式
- 卡片式布局
- 字段分栏显示

---

## 7️⃣ 通用 Webhook 配置

### 适用场景

- 自定义后端服务
- webhook.site 等测试工具
- 其他未明确支持的服务

### 配置示例

```json
{
  "env": {
    "TAVILY_API_KEY": "your-api-key",
    "USAGE_TRACKING_ENABLED": "true",
    "USAGE_CALLBACK_URL": "https://your-custom-service.com/webhook",
    "NOTIFICATION_TYPE": "webhook",
    "USAGE_REPORT_INTERVAL": "3600"
  }
}
```

### 接收到的 JSON

```json
{
  "timestamp": "2025-12-17T03:20:00Z",
  "event": "periodic_report",
  "stats": {
    "totalRequests": 150,
    "successfulRequests": 145,
    "failedRequests": 5,
    "requestsByType": {
      "search": 100,
      "extract": 30,
      "crawl": 15,
      "map": 5
    },
    "dailyStats": [...],
    "monthlyStats": [...]
  }
}
```

**特点：**
- 原始 JSON 格式
- 完整数据结构
- 可自定义处理

---

## 🔧 高级配置

### 强制指定通知类型

如果自动识别失败，可以手动指定：

```json
{
  "env": {
    "USAGE_CALLBACK_URL": "https://your-url.com/webhook",
    "NOTIFICATION_TYPE": "slack"
  }
}
```

可选值：`slack` | `discord` | `telegram` | `weixin` | `dingtalk` | `feishu` | `webhook`

### Telegram 额外配置

```json
{
  "env": {
    "TELEGRAM_CHAT_ID": "你的聊天ID",
    "TELEGRAM_BOT_TOKEN": "你的Bot Token"
  }
}
```

### 自定义 Headers（仅 webhook 类型）

在代码中可以扩展：

```typescript
{
  type: 'webhook',
  url: 'https://your-api.com/webhook',
  extras: {
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'X-Custom-Header': 'value'
    }
  }
}
```

---

## 📨 通知事件类型

所有渠道都支持以下三种事件：

### 1. 定期报告（periodic_report）

**触发条件：** 按 `USAGE_REPORT_INTERVAL` 配置的间隔发送

**包含信息：**
- 总请求数
- 成功/失败统计
- 请求类型分布
- 每日/月度统计

### 2. 错误激增告警（error_spike）

**触发条件：** 错误率超过 `USAGE_ALERT_THRESHOLD` 设定的阈值

**包含信息：**
- 错误消息
- 严重程度（warning/critical）
- 当前错误率
- 阈值设定

### 3. 配额告警（quota_alert）

**触发条件：** API 配额使用接近限制

**包含信息：**
- API Key 信息
- 当前使用量
- 配额限制
- 剩余额度
- 计费周期

---

## ✅ 测试配置

### 方法 1：使用测试脚本

```bash
# 编辑 test-webhook.js 中的 WEBHOOK_URL
node test-webhook.js
```

### 方法 2：手动发送测试

```bash
curl -X POST YOUR_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2025-12-17T03:20:00Z",
    "event": "periodic_report",
    "stats": {
      "totalRequests": 100,
      "successfulRequests": 95,
      "failedRequests": 5,
      "requestsByType": {
        "search": 60,
        "extract": 25,
        "crawl": 10,
        "map": 5
      }
    }
  }'
```

---

## 🎨 消息格式对比

| 渠道 | 颜色 | Emoji | Markdown | 字段 | 卡片 |
|------|------|-------|----------|------|------|
| Slack | ✅ | ✅ | ✅ | ✅ | ✅ |
| Discord | ✅ | ✅ | ✅ | ✅ | ✅ |
| Telegram | ❌ | ✅ | ✅ | ❌ | ❌ |
| 企业微信 | ❌ | ✅ | ❌ | ❌ | ❌ |
| 钉钉 | ❌ | ✅ | ✅ | ❌ | ❌ |
| 飞书 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Webhook | ❌ | ❌ | ❌ | ❌ | ❌ |

---

## 🔍 故障排查

### 问题：通知没有发送

**检查清单：**
1. ✅ `USAGE_TRACKING_ENABLED=true`
2. ✅ `USAGE_CALLBACK_URL` 配置正确
3. ✅ Webhook URL 可访问
4. ✅ 防火墙没有阻止
5. ✅ Telegram 额外配置已设置（如果使用）

**查看日志：**
```
Initialized notification adapter: slack
Notification sent via adapter: periodic_report
```

### 问题：消息格式错误

**可能原因：**
- 通知类型自动识别错误
- 解决方法：手动设置 `NOTIFICATION_TYPE`

### 问题：Telegram 不工作

**检查：**
- `TELEGRAM_CHAT_ID` 是否正确
- `TELEGRAM_BOT_TOKEN` 是否有效
- Bot 是否已添加到对应群组

---

## 💡 最佳实践

### 开发环境
- 使用 **webhook.site** 或**本地接收器**快速测试
- 设置较短的报告间隔（60秒）

### 生产环境
- 使用企业通讯工具（Slack/企业微信/钉钉）
- 设置合理的报告间隔（3600秒）
- 配置告警阈值避免噪音

### 多渠道通知
暂不支持同时发送到多个渠道，如需实现：
1. 使用 webhook 类型
2. 创建中转服务接收并分发到多个渠道

---

## 📚 完整配置示例

### Slack + 定期报告 + 告警

```json
{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "tvly-your-api-key",
        "USAGE_TRACKING_ENABLED": "true",
        "USAGE_STATS_FILE": "./tavily-stats.json",
        "USAGE_CALLBACK_URL": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
        "USAGE_REPORT_INTERVAL": "3600",
        "USAGE_ALERT_THRESHOLD": "80"
      }
    }
  }
}
```

### Discord + 仅告警

```json
{
  "env": {
    "TAVILY_API_KEY": "tvly-your-api-key",
    "USAGE_TRACKING_ENABLED": "true",
    "USAGE_CALLBACK_URL": "https://discord.com/api/webhooks/YOUR/WEBHOOK",
    "USAGE_ALERT_THRESHOLD": "70"
  }
}
```

### 钉钉 + 中文环境

```json
{
  "env": {
    "TAVILY_API_KEY": "tvly-your-api-key",
    "USAGE_TRACKING_ENABLED": "true",
    "USAGE_CALLBACK_URL": "https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN",
    "USAGE_REPORT_INTERVAL": "7200",
    "USAGE_ALERT_THRESHOLD": "85"
  }
}
```

---

## 🎉 总结

- ✅ **8 种渠道**全部支持
- ✅ **自动识别**通知类型
- ✅ **专门优化**每种渠道的消息格式
- ✅ **零配置**开始使用（除 Telegram）
- ✅ **完整的**错误处理和日志

选择适合你的渠道，复制配置，即刻开始接收通知！🚀