--- # 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 提升实时性