349 lines
8.1 KiB
Markdown
349 lines
8.1 KiB
Markdown
# Funstat BOT MCP 封装架构流程图
|
||
|
||
## 1. 整体系统架构图
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "用户层"
|
||
U1[普通用户 1]
|
||
U2[普通用户 2]
|
||
U3[普通用户 N]
|
||
end
|
||
|
||
subgraph "Claude Code 层"
|
||
C1[Claude Code 实例 1]
|
||
C2[Claude Code 实例 2]
|
||
C3[Claude Code 实例 N]
|
||
end
|
||
|
||
subgraph "MCP 服务器层"
|
||
MCP[MCP Server]
|
||
Queue[请求队列]
|
||
Cache[结果缓存]
|
||
RateLimit[速率限制器]
|
||
end
|
||
|
||
subgraph "Telegram 客户端层"
|
||
T1[Telethon Client 1]
|
||
T2[Telethon Client 2]
|
||
T3[Telethon Client N]
|
||
end
|
||
|
||
subgraph "目标 BOT"
|
||
BOT[@openaiw_bot]
|
||
end
|
||
|
||
U1 --> C1
|
||
U2 --> C2
|
||
U3 --> C3
|
||
|
||
C1 --> MCP
|
||
C2 --> MCP
|
||
C3 --> MCP
|
||
|
||
MCP --> Queue
|
||
Queue --> RateLimit
|
||
RateLimit --> Cache
|
||
Cache --> T1
|
||
Cache --> T2
|
||
Cache --> T3
|
||
|
||
T1 --> BOT
|
||
T2 --> BOT
|
||
T3 --> BOT
|
||
|
||
BOT -.响应.-> T1
|
||
BOT -.响应.-> T2
|
||
BOT -.响应.-> T3
|
||
|
||
T1 -.结果.-> Cache
|
||
T2 -.结果.-> Cache
|
||
T3 -.结果.-> Cache
|
||
|
||
Cache -.返回.-> MCP
|
||
MCP -.返回.-> C1
|
||
MCP -.返回.-> C2
|
||
MCP -.返回.-> C3
|
||
```
|
||
|
||
## 2. 单次请求流程图
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 普通用户
|
||
participant Claude as Claude Code
|
||
participant MCP as MCP Server
|
||
participant Queue as 请求队列
|
||
participant Rate as 速率限制
|
||
participant Cache as 缓存层
|
||
participant Tele as Telethon Client
|
||
participant Bot as @openaiw_bot
|
||
|
||
User->>Claude: "搜索 Python 相关群组"
|
||
Claude->>MCP: funstat_search(query="python")
|
||
|
||
MCP->>Cache: 检查缓存
|
||
alt 缓存命中
|
||
Cache-->>MCP: 返回缓存结果
|
||
MCP-->>Claude: 返回结果
|
||
Claude-->>User: 展示搜索结果
|
||
else 缓存未命中
|
||
MCP->>Queue: 加入请求队列
|
||
Queue->>Rate: 检查速率限制
|
||
|
||
alt 速率允许
|
||
Rate->>Tele: 发送消息到 BOT
|
||
Tele->>Bot: /search python
|
||
Bot-->>Tele: 返回搜索结果
|
||
Tele->>Cache: 保存到缓存
|
||
Cache-->>MCP: 返回结果
|
||
MCP-->>Claude: 返回结果
|
||
Claude-->>User: 展示搜索结果
|
||
else 超过限制
|
||
Rate->>Queue: 延迟执行
|
||
Queue-->>Rate: 等待后重试
|
||
Rate->>Tele: 发送消息到 BOT
|
||
Tele->>Bot: /search python
|
||
Bot-->>Tele: 返回搜索结果
|
||
Tele->>Cache: 保存到缓存
|
||
Cache-->>MCP: 返回结果
|
||
MCP-->>Claude: 返回结果
|
||
Claude-->>User: 展示搜索结果
|
||
end
|
||
end
|
||
```
|
||
|
||
## 3. 批量请求处理流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start[收到多个请求] --> Queue{请求队列}
|
||
Queue --> Check[检查当前速率]
|
||
|
||
Check --> |速率<18/s| Exec[立即执行]
|
||
Check --> |速率≥18/s| Wait[加入等待队列]
|
||
|
||
Exec --> Cache1{检查缓存}
|
||
Cache1 --> |命中| Return1[返回缓存结果]
|
||
Cache1 --> |未命中| Send1[发送到 BOT]
|
||
|
||
Send1 --> Receive1[接收 BOT 响应]
|
||
Receive1 --> Save1[保存到缓存]
|
||
Save1 --> Return2[返回结果]
|
||
|
||
Wait --> Timer[定时器触发]
|
||
Timer --> Check
|
||
|
||
Return1 --> End[完成]
|
||
Return2 --> End
|
||
```
|
||
|
||
## 4. 多账号负载均衡流程
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
Request[新请求] --> Balancer{负载均衡器}
|
||
|
||
Balancer --> Check1{账号1状态}
|
||
Balancer --> Check2{账号2状态}
|
||
Balancer --> Check3{账号N状态}
|
||
|
||
Check1 --> |可用且速率低| Select1[选择账号1]
|
||
Check1 --> |不可用或速率高| Next1[检查下一个]
|
||
|
||
Check2 --> |可用且速率低| Select2[选择账号2]
|
||
Check2 --> |不可用或速率高| Next2[检查下一个]
|
||
|
||
Check3 --> |可用且速率低| Select3[选择账号N]
|
||
Check3 --> |不可用或速率高| Retry[重新均衡]
|
||
|
||
Next1 --> Check2
|
||
Next2 --> Check3
|
||
Next3 --> Retry
|
||
Retry --> Balancer
|
||
|
||
Select1 --> Execute1[通过账号1发送]
|
||
Select2 --> Execute2[通过账号2发送]
|
||
Select3 --> Execute3[通过账号N发送]
|
||
|
||
Execute1 --> BOT[@openaiw_bot]
|
||
Execute2 --> BOT
|
||
Execute3 --> BOT
|
||
|
||
BOT --> Response[返回结果]
|
||
```
|
||
|
||
## 5. 限流与重试机制
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> Idle: 服务启动
|
||
|
||
Idle --> Receiving: 收到请求
|
||
Receiving --> RateCheck: 检查速率
|
||
|
||
RateCheck --> Available: 速率OK
|
||
RateCheck --> Limited: 超过限制
|
||
|
||
Available --> Sending: 发送请求
|
||
Limited --> Waiting: 加入等待队列
|
||
|
||
Sending --> Success: BOT响应成功
|
||
Sending --> Error: 请求失败
|
||
|
||
Success --> Caching: 缓存结果
|
||
Caching --> Idle: 返回结果
|
||
|
||
Error --> Retry: 重试计数<3
|
||
Error --> Failed: 重试计数≥3
|
||
|
||
Retry --> Backoff: 指数退避
|
||
Backoff --> Sending: 延迟后重试
|
||
|
||
Failed --> Idle: 返回错误
|
||
|
||
Waiting --> Timer: 定时器触发
|
||
Timer --> RateCheck: 重新检查
|
||
```
|
||
|
||
## 6. Telegram 请求限制详解
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph "个人账号限制"
|
||
P1[用户 → BOT<br/>18-20 msg/s]
|
||
P2[用户 → 群组<br/>20-30 msg/s]
|
||
P3[用户 → 私聊<br/>30 msg/s]
|
||
end
|
||
|
||
subgraph "BOT 账号限制"
|
||
B1[BOT → 用户<br/>30 msg/s]
|
||
B2[BOT → 群组<br/>20 msg/s]
|
||
B3[BOT API<br/>限流严格]
|
||
end
|
||
|
||
subgraph "解决方案"
|
||
S1[多账号池<br/>N×18 msg/s]
|
||
S2[请求缓存<br/>+30-40%]
|
||
S3[智能调度<br/>+20-30%]
|
||
end
|
||
|
||
P1 --> S1
|
||
P2 --> S2
|
||
P3 --> S3
|
||
```
|
||
|
||
## 7. MCP 工具调用示例
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as 用户
|
||
participant C as Claude
|
||
participant M as MCP funstat_search
|
||
participant T as Telethon
|
||
participant B as @openaiw_bot
|
||
|
||
U->>C: "帮我找 Python 学习群组"
|
||
|
||
Note over C: 理解用户意图
|
||
C->>M: funstat_search(query="python", type="group")
|
||
|
||
M->>T: 发送 /search python
|
||
T->>B: /search python
|
||
|
||
Note over B: 查询数据库
|
||
B-->>T: 返回群组列表（JSON）
|
||
T-->>M: 解析响应
|
||
|
||
Note over M: 格式化结果
|
||
M-->>C: 返回群组数据
|
||
|
||
Note over C: 生成友好回复
|
||
C-->>U: "我找到了以下 Python 学习群组：<br/>1. Python 编程学习...<br/>2. Python 数据科学..."
|
||
```
|
||
|
||
## 8. 推荐架构：单账号 + 队列
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "前端"
|
||
Users[多个普通用户]
|
||
end
|
||
|
||
subgraph "MCP 服务层"
|
||
MCP[MCP Server]
|
||
|
||
subgraph "核心组件"
|
||
Queue[FIFO 队列]
|
||
Rate[速率限制<br/>18 req/s]
|
||
Cache[Redis 缓存<br/>TTL: 1h]
|
||
end
|
||
end
|
||
|
||
subgraph "Telegram 层"
|
||
Tele[Telethon Client<br/>1个账号]
|
||
end
|
||
|
||
subgraph "目标"
|
||
Bot[@openaiw_bot<br/>funstat数据库]
|
||
end
|
||
|
||
Users -->|并发请求| MCP
|
||
MCP --> Queue
|
||
Queue -->|FIFO| Rate
|
||
|
||
Rate -->|检查缓存| Cache
|
||
Cache -->|未命中| Tele
|
||
Cache -->|命中| MCP
|
||
|
||
Tele -->|MTProto| Bot
|
||
Bot -.响应.-> Tele
|
||
Tele -.保存.-> Cache
|
||
Tele -.返回.-> MCP
|
||
|
||
MCP -.结果.-> Users
|
||
|
||
style Rate fill:#f9f,stroke:#333,stroke-width:2px
|
||
style Cache fill:#bbf,stroke:#333,stroke-width:2px
|
||
style Tele fill:#bfb,stroke:#333,stroke-width:2px
|
||
```
|
||
|
||
---
|
||
|
||
## 性能指标总结
|
||
|
||
| 架构方案 | 吞吐量 | 响应时间 | 成本 | 复杂度 |
|
||
|---------|--------|---------|------|--------|
|
||
| 单账号 + 队列 | 15-18 req/s | 1-2s | $5/月 | 低 |
|
||
| 多账号池 (3个) | 45-54 req/s | 1-2s | $15/月 | 中 |
|
||
| 智能调度 (10个) | 150-180 req/s | 0.5-1s | $50/月 | 高 |
|
||
|
||
## 使用示例
|
||
|
||
### 用户视角
|
||
```
|
||
用户: "帮我搜索区块链相关群组"
|
||
Claude: [自动调用 MCP 工具]
|
||
"我找到了以下区块链群组：
|
||
1. 区块链技术交流 (50万成员)
|
||
2. 加密货币投资 (30万成员)
|
||
..."
|
||
```
|
||
|
||
### MCP 工具定义
|
||
```json
|
||
{
|
||
"name": "funstat_search",
|
||
"description": "搜索 Telegram 群组、用户、消息",
|
||
"parameters": {
|
||
"query": "搜索关键词",
|
||
"type": "group/user/message",
|
||
"limit": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
**这些流程图完整展示了整个系统的架构设计！** 你可以把这个文档保存下来，或者我可以把它上传到 MrDoc。
|