funstat BOT MCP 封装 - 完整架构流程图 (Mermaid)

# funstat BOT MCP 封装 - 架构流程图

## 1. 整体系统架构

```mermaid
graph TB
    subgraph "用户层"
        U1[用户 1]
        U2[用户 2]
        U3[用户 N...]
    end

subgraph "Claude Code"
        C1[Claude Instance 1]
        C2[Claude Instance 2]
        C3[Claude Instance N]
    end

subgraph "MCP Server"
 MCP[MCP 工具接口]
 Q[请求队列 Rate Limiter]
 S[智能调度器]
 Cache[结果缓存 Redis/内存]
 end

subgraph "Telegram 客户端层"
        TC1[Telethon Client 1]
        TC2[Telethon Client 2]
        TC3[Telethon Client N]
    end

subgraph "Telegram 生态"
 Bot[@openaiw_bot funstat/infostat]
 end

U1 --> C1
    U2 --> C2
    U3 --> C3

C1 --> MCP
    C2 --> MCP
    C3 --> MCP

MCP --> Q
    Q --> S
    S --> Cache

S --> TC1
    S --> TC2
    S --> TC3

TC1 --> Bot
    TC2 --> Bot
    TC3 --> Bot

Bot --> TC1
    Bot --> TC2
    Bot --> TC3

TC1 --> S
    TC2 --> S
    TC3 --> S

S --> Cache
    Cache --> MCP
    MCP --> C1
    MCP --> C2
    MCP --> C3

style MCP fill:#e1f5ff
    style Q fill:#fff9c4
    style S fill:#c8e6c9
    style Cache fill:#ffccbc
    style Bot fill:#f3e5f5
```

---

## 2. 单次请求完整流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant C as Claude Code
    participant M as MCP Server
    participant RL as Rate Limiter
    participant Cache as 缓存
    participant TC as Telethon Client
    participant Bot as @openaiw_bot

U->>C: 发起查询 "搜索 python 群组"
 C->>M: openaiw_search_groups(query="python")

M->>Cache: 检查缓存
    alt 缓存命中
        Cache-->>M: 返回缓存结果
        M-->>C: 返回结果
        C-->>U: 展示结果
    else 缓存未命中
        M->>RL: 请求令牌
        RL->>RL: 检查速率限制

alt 未达到限制
            RL-->>M: 授予令牌
            M->>TC: send_message("/search python")
            TC->>Bot: 发送消息
            Bot->>Bot: 处理查询
            Bot-->>TC: 返回搜索结果
            TC-->>M: 解析响应
            M->>Cache: 存储结果
            M-->>C: 返回结果
            C-->>U: 展示结果
        else 达到限制
            RL->>RL: 等待令牌补充
            Note over RL: 等待 50-100ms
            RL-->>M: 授予令牌
            M->>TC: send_message("/search python")
            TC->>Bot: 发送消息
            Bot-->>TC: 返回结果
            TC-->>M: 解析响应
            M-->>C: 返回结果
            C-->>U: 展示结果
        end
    end
```

---

## 3. 批量并发请求处理流程

```mermaid
graph TB
 subgraph "并发请求"
 R1[请求 1 搜索群组]
 R2[请求 2 查询用户]
 R3[请求 3 热门群组]
 R4[请求 N...]
 end

subgraph "请求队列"
 Q[FIFO Queue 最大 1000]
 end

subgraph "速率限制器"
 RL[Token Bucket 18 令牌/秒]
 T1[令牌 1]
 T2[令牌 2]
 T3[令牌 3]
 end

subgraph "账号池"
 A1[账号 1 空闲]
 A2[账号 2 使用中]
 A3[账号 3 空闲]
 end

subgraph "负载均衡"
 LB{负载均衡器 最少使用策略}
 end

R1 --> Q
    R2 --> Q
    R3 --> Q
    R4 --> Q

Q --> RL

RL --> T1
    RL --> T2
    RL --> T3

T1 --> LB
    T2 --> LB
    T3 --> LB

LB --> A1
    LB --> A2
    LB --> A3

A1 --> Bot1[@openaiw_bot]
    A2 --> Bot2[@openaiw_bot]
    A3 --> Bot3[@openaiw_bot]

style Q fill:#fff9c4
    style RL fill:#c8e6c9
    style LB fill:#e1f5ff
    style Bot1 fill:#f3e5f5
    style Bot2 fill:#f3e5f5
    style Bot3 fill:#f3e5f5
```

---

## 4. 多账号负载均衡策略

```mermaid
stateDiagram-v2
    [*] --> 收到请求

收到请求 --> 检查账号池

检查账号池 --> 选择策略

选择策略 --> 轮询: Round Robin
    选择策略 --> 最少使用: Least Used
    选择策略 --> 加权: Weighted

轮询 --> 选择账号1
    最少使用 --> 检查使用率
    加权 --> 根据权重选择

检查使用率 --> 选择最空闲账号

选择账号1 --> 发送请求
    选择最空闲账号 --> 发送请求
    根据权重选择 --> 发送请求

发送请求 --> 检查结果

检查结果 --> 成功: 正常响应
    检查结果 --> FloodWait: Flood Wait 错误
    检查结果 --> 失败: 其他错误

成功 --> 更新统计
    FloodWait --> 标记账号: 等待中
    失败 --> 故障转移

故障转移 --> 选择下一个账号
    选择下一个账号 --> 发送请求

标记账号 --> 选择其他账号
    选择其他账号 --> 发送请求

更新统计 --> [*]
```

---

## 5. 限流与重试机制

```mermaid
flowchart TD
    Start[开始请求] --> CheckCache{检查缓存?}

CheckCache -->|命中| ReturnCache[返回缓存结果]
    CheckCache -->|未命中| GetToken[获取令牌]

GetToken --> HasToken{有令牌?}

HasToken -->|是| SelectAccount[选择账号]
 HasToken -->|否| WaitToken[等待令牌 50ms]

WaitToken --> GetToken

SelectAccount --> SendRequest[发送请求]

SendRequest --> CheckResponse{检查响应}

CheckResponse -->|成功| ParseResponse[解析响应]
 CheckResponse -->|FloodWait| HandleFlood{重试次数<3?}
 CheckResponse -->|网络错误| HandleError{重试次数<3?}
 CheckResponse -->|超时| HandleTimeout[返回超时提示]

HandleFlood -->|是| WaitFlood[等待 Flood 时间]
    HandleFlood -->|否| ReturnError[返回错误]

HandleError -->|是| RetryRequest[重试请求]
    HandleError -->|否| ReturnError

WaitFlood --> RetryRequest
    RetryRequest --> SendRequest

ParseResponse --> CacheResult[缓存结果]
    CacheResult --> ReturnResult[返回结果]

ReturnCache --> End[结束]
    ReturnResult --> End
    ReturnError --> End
    HandleTimeout --> End

style Start fill:#e1f5ff
    style End fill:#c8e6c9
    style CheckCache fill:#fff9c4
    style CacheResult fill:#ffccbc
```

---

## 6. 请求限制说明

### 单账号限制
- **速率**: ~18-20 请求/秒
- **队列**: 最多 100 个待处理请求
- **超时**: 20 秒无响应则超时

### 多账号限制（3 个账号）
- **总速率**: ~54-60 请求/秒
- **队列**: 最多 500 个待处理请求
- **故障转移**: 自动切换到其他账号

### 缓存机制
- **热门查询**: 缓存 1 小时
- **用户信息**: 缓存 24 小时
- **命中率**: 预计 30-40%

---

## 7. 普通用户调用方式

### 方式 1: 通过 Claude Code (推荐)

```
用户: 帮我搜索 "python" 相关的 Telegram 群组

Claude: [自动调用 openaiw_search_groups]
        查询中...

找到以下群组：
        1. Python 学习交流群
        2. Python 开发者社区
        ...
```

### 方式 2: 通过 API 调用

```bash
curl -X POST http://localhost:8080/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python"}'
```

### 方式 3: 通过 Web 界面

```
访问: http://localhost:8080/web
输入查询 → 点击搜索 → 查看结果
```

---

## 8. 性能指标

| 配置 | 账号数 | 吞吐量 | 延迟 | 成本 |
|-----|-------|--------|------|------|
| 小规模 | 1 | 15-18 req/s | 1-2s | $5/月 |
| 中等 | 3 | 45-54 req/s | 1-3s | $15/月 |
| 大规模 | 10 | 150-180 req/s | 1-2s | $50/月 |

---

**文档说明**: 以上 Mermaid 图表可以在支持 Mermaid 的 Markdown 编辑器中查看，包括：
- GitHub
- GitLab
- Typora
- VS Code (with Mermaid extension)
- 在线工具: https://mermaid.live/