---

# Telegram Bot 智能通知与交互系统 PRD

**项目代号**: NaughtyMan
**文档版本**: v2.0
**最后更新**: 2025 年 10 月

# 一、产品概述

## 1.1 产品定位

构建一个企业级 Telegram Bot 系统,集成消息通知、智能提醒和 AI 助手功能,为 ProjectOctopus(服务器监控)和 ProjectTonyStack(金融监控)提供统一的实时通知中枢。

## 1.2 核心价值

- **智能分级推送**: 根据事件紧急程度自动调度通知时间和模板
- **安全可控**: 白名单 + 动态 Token 双重鉴权机制
- **高可用性**: 内置速率控制器保障稳定运行
- **AI 增强**: 多厂商 AI 集成提供智能上下文响应

## 1.3 技术栈

- **后端框架**: Gin (Go 语言)
- **Bot SDK**: 原生 Telegram Bot API
- **数据持久化**: SQLite
- **网络代理**: 支持 SOCKS5/HTTP

---

# 二、功能模块详细设计

## 2.1 核心模块:消息通知系统 [P0-高优先级]

### 2.1.1 接口设计

**API 端点结构**

```go
POST /api/v1/auth/handshake      # 握手获取临时Token
POST /api/v1/auth/token          # 换取正式Token
POST /api/v1/message/send        # 发送消息
GET  /api/v1/message/status      # 查询消息状态
```

**Token 安全机制**

1. **双阶段认证流程**:

    - 阶段一:客户端携带 API Key 请求握手,服务端返回 challenge 码(60 秒有效期)
    - 阶段二:客户端用 challenge+API Secret 生成签名,换取 Access Token(6 小时有效期)
2. **Token 刷新策略**:

    - Token 过期前 30 分钟允许静默续期
    - 每个 API Key 同时只允许一个有效 Token
    - Token 中包含加密的白名单用户 ID/群组 ID

**请求体示例**

```go
{
  "target_type": "user|group",
  "target_id": "123456789",
  "level": "info|warning|critical",
  "project": "octopus|tonystack",
  "content": {
    "title": "服务器CPU告警",
    "body": "服务器CPU使用率达85%",
    "metadata": {
      "server": "prod-web-01",
      "timestamp": "2025-10-21T10:23:00Z"
    }
  }
}
```

### 2.1.2 消息分级与模板

**等级定义**

| 等级     | 触发条件     | 推送时段    | 响应时效             | 模板标识      |
| ---------- | -------------- | ------------- | ---------------------- | --------------- |
| INFO     | 常规事件日志 | 08:00-23:00 | 批量推送(5 分钟汇总) | 📘 蓝色图标   |
| WARNING  | 异常但可运行 | 08:00-23:00 | 即时推送             | ⚠️ 黄色图标 |
| CRITICAL | 严重故障     | 全天候      | 即时推送 + 重试      | 🚨 红色图标   |

**模板配置**

*ProjectOctopus (服务器监控模板)*

```go
🖥️ [{{level}}] {{title}}

📍 服务器: {{metadata.server}}
📊 详情: {{body}}
⏰ 时间: {{timestamp}}

#服务器监控 #{{level}}
```

*ProjectTonyStack (金融监控模板)*

```go
💹 [{{level}}] {{title}}

💰 标的: {{metadata.symbol}}
📈 数值: {{body}}
⏰ 时间: {{timestamp}}

#金融监控 #{{level}}
```

### 2.1.3 速率限制器设计

**Telegram 官方限速规则**

- 不同聊天: 30 消息/秒
- 同一私聊: 1 消息/秒
- 同一群聊: 20 消息/分钟
- editMessageText: 共享发送额度

**限制器实现**

```go
// 单例模式令牌桶算法
type RateLimiter struct {
    globalBucket   *TokenBucket  // 全局30/s
    chatBuckets    sync.Map      // 每个chat独立限流
    editBucket     *TokenBucket  // 编辑消息单独限流
}

// 消息排队机制
type MessageQueue struct {
    priority       PriorityQueue  // CRITICAL优先
    retryQueue     []Message      // 失败重试队列(指数退避)
    deadLetterBox  []Message      // 3次失败转死信队列
}
```

---

## 2.2 机器人交互功能 [P1-中优先级]

### 2.2.1 定时提醒功能

**指令**: `/notify`

**交互流程**

利用 Telegram InlineKeyboard 实现多步交互:

```go
用户输入 /notify
↓
Bot返回主界面:
┌─────────────────────────┐
│  📅 日期  🕐 时间  🔁 重复 │ 
├─────────────────────────┤
│ 📝 提醒内容:             │
│ [在此输入...]            │
├─────────────────────────┤
│      ✅ 创建提醒         │
└─────────────────────────┘
```

**回调数据结构**

```json
{
  "action": "notify_date|notify_time|notify_repeat|notify_submit",
  "state": {
    "date": "2025-10-25",
    "time": "09:00",
    "repeat": "daily|weekly|biweekly|monthly|custom:[1,3,5]",
    "content": "团队站会"
  }
}
```

**日期选择器实现**

使用 editMessageText 动态更新消息:

- 日历视图: 显示当前月份,支持上/下月翻页
- 时间选择: 时/分滚动选择器(步长 15 分钟)
- 重复规则: 预设 + 自定义(RRULE 格式)

### 2.2.2 提醒管理功能

**指令**: `/notify_list`

**列表展示**

```go
📋 您的提醒事项 (3)

🔁 每日 | 09:00 | 团队站会
   [🗑️ 删除]

📅 10-25 | 14:30 | 客户电话会议
   [🗑️ 删除]

📅 10-30 | 全天 | 项目交付DDL
   [🗑️ 删除]
```

**删除确认机制**

点击删除后 editMessageText 更新为确认界面:

```go
⚠️ 确认删除提醒?

🔁 每日 | 09:00 | 团队站会

[❌ 取消]  [✅ 确认删除]
```

### 2.2.3 数据持久化

**SQLite 表结构**

```sql
CREATE TABLE reminders (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id BIGINT NOT NULL,
    chat_id BIGINT NOT NULL,
    content TEXT NOT NULL,
    trigger_time DATETIME NOT NULL,
    repeat_rule TEXT,  -- RRULE格式
    next_trigger DATETIME,
    status INTEGER DEFAULT 1,  -- 1:活动 0:已删除
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_next_trigger (next_trigger, status)
);
```

---

## 2.3 AI 智能体功能 [P1-中优先级]

### 2.3.1 触发机制

- 私聊: 直接回复所有消息
- 群聊: 仅响应 @ 机器人的消息

### 2.3.2 上下文管理

**消息引用策略**

```tex
触发消息(被@的消息)
↓ 引用
前3条历史消息
↓ 拼接
发送给AI API
```

**上下文窗口**

```json
{
  "messages": [
    {"role": "system", "content": "你是Telegram群助手..."},
    {"role": "user", "content": "历史消息1", "name": "user123"},
    {"role": "user", "content": "历史消息2", "name": "user456"},
    {"role": "user", "content": "历史消息3", "name": "user123"},
    {"role": "user", "content": "当前@消息", "name": "user789"}
  ]
}
```

### 2.3.3 多厂商 AI 集成

**支持的 AI 提供商**

| 提供商     | 模型推荐       | 流式支持 | 思考链         |
| ------------ | ---------------- | ---------- | ---------------- |
| OpenAI     | gpt-4-turbo    | ✅       | ✅ (reasoning) |
| Google     | gemini-1.5-pro | ✅       | ✅ (思考步骤)  |
| xAI        | grok-2         | ✅       | ✅ (推理过程)  |
| OpenRouter | 多模型聚合     | ✅       | 视模型而定     |

**流式响应处理**

```text
1. 发送初始消息"正在思考..."
2. 累积AI响应分片(每500字符或5秒)
3. 使用editMessageText更新消息
4. 遵守编辑速率限制(复用全局限流器)
5. 完成后添加"✅ 回答完成"标识
```

**思考过程展示**

```txt
🤔 思考中...

【推理步骤1】分析问题...
【推理步骤2】检索知识...

💡 回答:
[AI生成的完整答复]

✅ 回答完成 | 用时3.2s
```

---

# 三、基础架构设计

## 3.1 安全控制

**白名单机制**

```sql
CREATE TABLE whitelist (
    id INTEGER PRIMARY KEY,
    type TEXT CHECK(type IN ('user', 'group')),
    entity_id BIGINT UNIQUE NOT NULL,
    alias TEXT,
    added_by BIGINT,
    added_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    status INTEGER DEFAULT 1
);
```

**中间件验证逻辑**

```go
func WhitelistMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        update := c.MustGet("telegram_update")
        
        // 提取user_id和chat_id
        if !IsInWhitelist(userID, chatID) {
            bot.SendMessage(chatID, "⚠️ 未授权访问")
            c.Abort()
            return
        }
        c.Next()
    }
}
```

## 3.2 网络代理配置

**环境变量**

```shell
TELEGRAM_PROXY_TYPE=socks5|http
TELEGRAM_PROXY_HOST=127.0.0.1
TELEGRAM_PROXY_PORT=1080
TELEGRAM_PROXY_USER=optional_username
TELEGRAM_PROXY_PASS=optional_password
```

**代理客户端初始化**

```go
proxyURL, _ := url.Parse(
    fmt.Sprintf("%s://%s:%s@%s:%d",
        proxyType, user, pass, host, port))

httpClient := &http.Client{
    Transport: &http.Transport{
        Proxy: http.ProxyURL(proxyURL),
    },
}

bot, _ := tgbotapi.NewBotAPIWithClient(token, httpClient)
```

## 3.3 数据持久化

**存储路径规范**

- Windows: `%USERPROFILE%\naughty_man\bot.db`
- Linux: `/usr/local/etc/naughty_man/bot.db`

**核心表设计**

```sql
-- Token管理
CREATE TABLE api_tokens (
    id INTEGER PRIMARY KEY,
    api_key TEXT NOT NULL,
    access_token TEXT UNIQUE,
    challenge TEXT,
    challenge_expire DATETIME,
    token_expire DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 消息日志
CREATE TABLE message_log (
    id INTEGER PRIMARY KEY,
    message_id TEXT,
    chat_id BIGINT,
    level TEXT,
    project TEXT,
    content TEXT,
    status TEXT,  -- pending|sent|failed
    retry_count INTEGER DEFAULT 0,
    sent_at DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

## 3.4 配置文件

所有可变参数都通过**统一的配置文件**（如`config.yaml`）加载，便于部署和维护

- 数据库路径
- 代理设置
- AI API Keys
- Token 密钥
- 正常时段定义

---

# 四、非功能性需求

## 4.1 性能指标

- API 响应延迟: P95 \< 200ms
- 消息发送成功率: \> 99.5%
- 定时提醒误差: ±30 秒
- AI 响应首字延迟: \< 3 秒

## 4.2 可靠性

- 消息队列持久化避免丢失
- 失败消息自动重试(指数退避,最多 3 次)
- 死信队列人工介入机制
- 定时任务崩溃恢复(启动时扫描 pending 任务)

## 4.3 可观测性

**日志分级**

- ERROR: 消息发送失败、数据库错误
- WARN: 触及速率限制、Token 即将过期
- INFO: API 调用、定时任务触发
- DEBUG: 消息队列状态、AI 流式分片

**监控指标**

- 消息发送 QPS
- 令牌桶剩余容量
- 数据库连接池状态
- AI API 调用耗时分布

---

# 五、实施计划

## 阶段一:基础设施 (2 周)

- 速率限制器实现与测试
- 数据库表结构设计
- 白名单 +Token 认证系统
- 代理支持与连接测试

## 阶段二:核心功能 (3 周)

- 消息通知 API 开发
- 分级模板渲染引擎
- 消息队列与重试机制
- 定时提醒 CRUD 功能

## 阶段三:高级功能 (3 周)

- InlineKeyboard 交互流程
- AI 多厂商适配层
- 流式响应处理
- 性能优化与压测

## 阶段四:上线准备 (1 周)

- 集成测试与修复
- 文档编写
- 监控告警配置
- 灰度发布

---

# 六、风险与对策

| 风险项            | 影响          | 对策                            |
| ------------------- | --------------- | --------------------------------- |
| Telegram API 限流 | 消息延迟/丢失 | 令牌桶 + 优先级队列 + 重试机制 [byteplus+1](https://www.byteplus.com/en/topic/450604) |
| AI 厂商服务中断   | 智能体不可用  | 自动降级到下一厂商/返回友好提示 |
| SQLite 并发写入   | 数据竞争      | 使用 WAL 模式 + 写操作串行化    |
| 网络代理不稳定    | Bot 离线      | 心跳检测 + 自动重连 + 备用代理  |

---

# 七、后续演进方向

1. **多 Bot 实例**: 分布式部署 + 消息路由中心
2. **富媒体支持**: 图片、文件、语音消息通知
3. **自定义指令**: 用户自定义快捷命令
4. **数据看板**: 消息统计、AI 使用分析
5. **Webhook 模式**: 替代 Long Polling 提升实时性