zeaslity/ProjectAGiPrompt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
ProjectAGiPrompt/4-ProjectNaughtyMan/0-需求规格书/2-优化产品需求文档PRD.md
zeaslity fc72a7312e 大量的更新
2025-11-20 16:18:35 +08:00

12 KiB
Raw Permalink Blame History

# 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 端点结构

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

请求体示例

{
  "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 (服务器监控模板)

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

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

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

ProjectTonyStack (金融监控模板)

💹 [{{level}}] {{title}}

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

#金融监控 #{{level}}

2.1.3 速率限制器设计

Telegram 官方限速规则

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

限制器实现

// 单例模式令牌桶算法
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 实现多步交互:

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

回调数据结构

{
  "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

列表展示

📋 您的提醒事项 (3)

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

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

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

删除确认机制

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

⚠️ 确认删除提醒?

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

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

2.2.3 数据持久化

SQLite 表结构

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 上下文管理

消息引用策略

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

上下文窗口

{
  "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 多模型聚合 ✅ 视模型而定

流式响应处理

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

思考过程展示

🤔 思考中...

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

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

✅ 回答完成 | 用时3.2s

三、基础架构设计

3.1 安全控制

白名单机制

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
);

中间件验证逻辑

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 网络代理配置

环境变量

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

代理客户端初始化

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

核心表设计

-- 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
AI 厂商服务中断 智能体不可用 自动降级到下一厂商/返回友好提示
SQLite 并发写入 数据竞争 使用 WAL 模式 + 写操作串行化
网络代理不稳定 Bot 离线 心跳检测 + 自动重连 + 备用代理

七、后续演进方向

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