chore: initial commit
This commit is contained in:
你的用户名
322
scripts/generate_mermaid_diagrams.py
Normal file
322
scripts/generate_mermaid_diagrams.py
Normal file
@@ -0,0 +1,322 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
生成 Mermaid 流程图并保存为 Markdown 文件
|
||||
可以在支持 Mermaid 的编辑器中查看，或访问 https://mermaid.live/
|
||||
"""
|
||||
|
||||
# 图表 1: 整体架构
|
||||
architecture_diagram = """
|
||||
# funstat BOT MCP 封装 - 系统架构图
|
||||
|
||||
## 1. 整体架构流程
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph Users[用户层]
|
||||
U1[普通用户1]
|
||||
U2[普通用户2]
|
||||
U3[普通用户N]
|
||||
end
|
||||
|
||||
subgraph Claude[Claude Code层]
|
||||
C1[Claude实例1]
|
||||
C2[Claude实例2]
|
||||
C3[Claude实例N]
|
||||
end
|
||||
|
||||
subgraph MCP[MCP服务器]
|
||||
M1[MCP工具接口]
|
||||
M2[请求队列]
|
||||
M3[速率限制器]
|
||||
M4[结果缓存]
|
||||
end
|
||||
|
||||
subgraph Telegram[Telegram客户端]
|
||||
T1[Telethon账号1]
|
||||
T2[Telethon账号2]
|
||||
T3[Telethon账号3]
|
||||
end
|
||||
|
||||
subgraph Bot[目标BOT]
|
||||
B1[@openaiw_bot]
|
||||
end
|
||||
|
||||
U1 --> C1
|
||||
U2 --> C2
|
||||
U3 --> C3
|
||||
|
||||
C1 --> M1
|
||||
C2 --> M1
|
||||
C3 --> M1
|
||||
|
||||
M1 --> M2
|
||||
M2 --> M3
|
||||
M3 --> M4
|
||||
|
||||
M4 --> T1
|
||||
M4 --> T2
|
||||
M4 --> T3
|
||||
|
||||
T1 --> B1
|
||||
T2 --> B1
|
||||
T3 --> B1
|
||||
|
||||
B1 --> T1
|
||||
B1 --> T2
|
||||
B1 --> T3
|
||||
|
||||
T1 --> M4
|
||||
T2 --> M4
|
||||
T3 --> M4
|
||||
|
||||
M4 --> M1
|
||||
M1 --> C1
|
||||
M1 --> C2
|
||||
M1 --> C3
|
||||
|
||||
C1 --> U1
|
||||
C2 --> U2
|
||||
C3 --> U3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 单次请求完整流程（时序图）
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
actor User as 普通用户
|
||||
participant Claude as Claude Code
|
||||
participant MCP as MCP Server
|
||||
participant Queue as 请求队列
|
||||
participant Limiter as 速率限制
|
||||
participant Cache as 缓存
|
||||
participant Client as Telethon Client
|
||||
participant Bot as @openaiw_bot
|
||||
|
||||
User->>Claude: 发起请求：搜索python群组
|
||||
Claude->>MCP: 调用MCP工具
|
||||
Note over Claude,MCP: openaiw_search_groups(query="python")
|
||||
|
||||
MCP->>Cache: 检查缓存
|
||||
alt 缓存命中
|
||||
Cache-->>MCP: 返回缓存结果
|
||||
MCP-->>Claude: 返回结果
|
||||
Claude-->>User: 展示结果
|
||||
else 缓存未命中
|
||||
MCP->>Queue: 加入请求队列
|
||||
Queue->>Limiter: 请求令牌
|
||||
|
||||
alt 有可用令牌
|
||||
Limiter-->>Queue: 授予令牌
|
||||
Queue->>Client: 发送命令
|
||||
Client->>Bot: /search python
|
||||
Note over Client,Bot: Telegram消息
|
||||
Bot->>Bot: 处理查询
|
||||
Bot-->>Client: 返回搜索结果
|
||||
Client-->>Queue: 解析响应
|
||||
Queue->>Cache: 存储结果
|
||||
Cache-->>MCP: 返回结果
|
||||
MCP-->>Claude: 返回格式化结果
|
||||
Claude-->>User: 展示结果
|
||||
else 需要等待
|
||||
Limiter->>Limiter: 等待50-100ms
|
||||
Note over Limiter: 令牌桶补充
|
||||
Limiter-->>Queue: 授予令牌
|
||||
Queue->>Client: 发送命令
|
||||
Client->>Bot: /search python
|
||||
Bot-->>Client: 返回结果
|
||||
Client-->>Cache: 缓存结果
|
||||
Cache-->>MCP: 返回结果
|
||||
MCP-->>Claude: 返回结果
|
||||
Claude-->>User: 展示结果
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 批量并发请求处理
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([多个并发请求]) --> Queue[请求队列FIFO]
|
||||
Queue --> Check{检查队列长度}
|
||||
|
||||
Check -->|队列未满| Add[加入队列]
|
||||
Check -->|队列已满| Wait[等待队列有空位]
|
||||
|
||||
Wait --> Check
|
||||
Add --> Limiter{获取令牌}
|
||||
|
||||
Limiter -->|有令牌| Select[选择账号]
|
||||
Limiter -->|无令牌| WaitToken[等待令牌补充]
|
||||
|
||||
WaitToken --> Limiter
|
||||
|
||||
Select --> Balance{负载均衡}
|
||||
Balance -->|轮询| Account1[账号1]
|
||||
Balance -->|最少使用| Account2[账号2]
|
||||
Balance -->|加权| Account3[账号3]
|
||||
|
||||
Account1 --> Send[发送请求]
|
||||
Account2 --> Send
|
||||
Account3 --> Send
|
||||
|
||||
Send --> Response{响应状态}
|
||||
|
||||
Response -->|成功| Parse[解析结果]
|
||||
Response -->|FloodWait| Retry{重试?}
|
||||
Response -->|超时| Timeout[返回超时]
|
||||
Response -->|错误| Error[返回错误]
|
||||
|
||||
Retry -->|是| WaitFlood[等待FloodWait]
|
||||
Retry -->|否| Error
|
||||
|
||||
WaitFlood --> Send
|
||||
|
||||
Parse --> Cache[存入缓存]
|
||||
Cache --> Return[返回结果]
|
||||
|
||||
Timeout --> Return
|
||||
Error --> Return
|
||||
Return --> End([处理完成])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 请求限制和性能指标
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph Single[单账号模式]
|
||||
S1[18请求/秒]
|
||||
S2[100队列容量]
|
||||
S3[1-2秒延迟]
|
||||
end
|
||||
|
||||
subgraph Multi[多账号模式3账号]
|
||||
M1[54请求/秒]
|
||||
M2[500队列容量]
|
||||
M3[1-3秒延迟]
|
||||
end
|
||||
|
||||
subgraph Large[大规模10账号]
|
||||
L1[180请求/秒]
|
||||
L2[2000队列容量]
|
||||
L3[1-2秒延迟]
|
||||
end
|
||||
|
||||
Single --> Cost1[$5/月]
|
||||
Multi --> Cost2[$15/月]
|
||||
Large --> Cost3[$50/月]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 负载均衡策略
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 收到请求
|
||||
收到请求 --> 选择策略
|
||||
|
||||
选择策略 --> 轮询策略: Round Robin
|
||||
选择策略 --> 最少使用策略: Least Used
|
||||
选择策略 --> 加权策略: Weighted
|
||||
|
||||
轮询策略 --> 账号1
|
||||
轮询策略 --> 账号2
|
||||
轮询策略 --> 账号3
|
||||
|
||||
最少使用策略 --> 检查使用率
|
||||
检查使用率 --> 选择最空闲账号
|
||||
选择最空闲账号 --> 发送请求
|
||||
|
||||
加权策略 --> 按权重分配
|
||||
按权重分配 --> 发送请求
|
||||
|
||||
账号1 --> 发送请求
|
||||
账号2 --> 发送请求
|
||||
账号3 --> 发送请求
|
||||
|
||||
发送请求 --> 等待响应
|
||||
等待响应 --> 检查结果
|
||||
|
||||
检查结果 --> 成功: 正常响应
|
||||
检查结果 --> FloodWait: 被限流
|
||||
检查结果 --> 失败: 其他错误
|
||||
|
||||
成功 --> 更新统计
|
||||
FloodWait --> 标记账号繁忙
|
||||
失败 --> 故障转移
|
||||
|
||||
标记账号繁忙 --> 选择其他账号
|
||||
故障转移 --> 选择其他账号
|
||||
选择其他账号 --> 发送请求
|
||||
|
||||
更新统计 --> [*]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 使用说明
|
||||
|
||||
### 查看这些图表：
|
||||
|
||||
1. **在线查看**:
|
||||
- 访问 https://mermaid.live/
|
||||
- 复制任意一个 ```mermaid 代码块
|
||||
- 粘贴到编辑器中即可看到图表
|
||||
|
||||
2. **在 VS Code 中查看**:
|
||||
- 安装 "Markdown Preview Mermaid Support" 插件
|
||||
- 打开此文件并预览
|
||||
|
||||
3. **在 GitHub/GitLab 中查看**:
|
||||
- 直接上传此文件，Mermaid 会自动渲染
|
||||
|
||||
4. **导出为图片**:
|
||||
- 在 mermaid.live 中可以导出为 PNG/SVG
|
||||
|
||||
---
|
||||
|
||||
## 核心要点总结
|
||||
|
||||
### 请求限制
|
||||
- **单账号**: ~18 请求/秒
|
||||
- **多账号**: N × 18 请求/秒
|
||||
- **Flood Wait**: 自动处理和重试
|
||||
|
||||
### 普通用户使用
|
||||
```
|
||||
用户: "帮我搜索 python 群组"
|
||||
↓
|
||||
Claude 自动调用 MCP 工具
|
||||
↓
|
||||
后台处理（队列、限流、缓存）
|
||||
↓
|
||||
返回结果给用户
|
||||
```
|
||||
|
||||
**用户完全不需要了解技术细节！**
|
||||
|
||||
### 性能指标
|
||||
| 配置 | 吞吐量 | 成本 |
|
||||
|-----|-------|------|
|
||||
| 小规模(1账号) | 15-18 req/s | $5/月 |
|
||||
| 中等(3账号) | 45-54 req/s | $15/月 |
|
||||
| 大规模(10账号) | 150-180 req/s | $50/月 |
|
||||
|
||||
"""
|
||||
|
||||
# 保存文件
|
||||
with open('mermaid_diagrams.md', 'w', encoding='utf-8') as f:
|
||||
f.write(architecture_diagram)
|
||||
|
||||
print("✅ Mermaid 图表已生成！")
|
||||
print("\n查看方式：")
|
||||
print("1. 在线查看: https://mermaid.live/")
|
||||
print("2. VS Code: 安装 Markdown Preview Mermaid Support 插件")
|
||||
print("3. 文件位置: mermaid_diagrams.md")
|
||||
print("\n在线编辑器中粘贴 ```mermaid 代码块即可看到图表！")
|
||||
Reference in New Issue
Block a user