# gaofeiyang360-create/python-qq-chatbot architecture

> Architecture diagram of the GitHub repository gaofeiyang360-create/python-qq-chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gaofeiyang360-create/python-qq-chatbot
- Repository: https://github.com/gaofeiyang360-create/python-qq-chatbot

## Overview

This is a multi-bot QQ AI assistant. Its main workflow receives QQ events over WebSocket, parses and batches messages, decides whether to reply, uses AI and optional tools, then sends a response through QQ. Separate branches provide an authenticated HTTP API, scheduled pushes and wakeups, group events, media handling, and scoped conversation memory. The graph follows documented architecture and indexed imports; some implementation details are unsampled, so uncertain relationships are omitted.

Main entry points: [`client.py`](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/client.py) (QQ Client), [`msg.py`](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/msg.py) (Message Handling), [`wakeup_scheduler.py`](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/wakeup_scheduler.py) (Wakeup Scheduler), [`core.py`](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/core.py) (Bot Orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_bot_entry["Bot Entry<br/>[bot.py]"]
  node_bot_runtime["Bot Orchestration<br/>[core.py]"]
  node_qq_client["QQ Client<br/>[client.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_logging["Logging<br/>[log.py]"]
end

subgraph group_conversation["Conversation Processing"]
  node_message_handler["Message Handling<br/>[msg.py]"]
  node_media_web["Media And Web Processing<br/>[ai.py]"]
end

subgraph group_intelligence["AI And Tools"]
  node_chat_ai["AI Conversation<br/>[ai.py]"]
  node_tool_runtime["Tool Execution<br/>[tool.py]"]
end

subgraph group_state["Memory And State"]
  node_conversation_store[("Conversation Memory<br/>[memory.py]")]
end

subgraph group_operations["API And Scheduling"]
  node_shared_tasks["Task Rules<br/>[task_core.py]"]
  node_http_api["HTTP API<br/>[api_server.py]"]
  node_push_scheduler["Push Scheduler<br/>[scheduler.py]"]
  node_wakeup_scheduler["Wakeup Scheduler"]
end

node_operator(("QQ Users"))
node_qq{{"QQ Platform"}}
node_model_api{{"AI Model APIs"}}

node_operator -->|"sends messages"| node_qq
node_qq -->|"delivers events"| node_qq_client
node_qq_client -->|"routes messages"| node_message_handler
node_message_handler -->|"processes media"| node_media_web
node_message_handler -->|"records history"| node_conversation_store
node_message_handler -->|"requests replies"| node_chat_ai
node_chat_ai -->|"calls models"| node_model_api
node_chat_ai -->|"uses memory"| node_conversation_store
node_chat_ai -->|"dispatches tools"| node_tool_runtime
node_tool_runtime -->|"sends actions"| node_qq_client
node_qq_client -->|"sends replies"| node_qq
node_bot_entry -->|"starts bots"| node_bot_runtime
node_bot_runtime -->|"runs clients"| node_qq_client
node_bot_runtime -->|"starts scheduler"| node_push_scheduler
node_bot_runtime -->|"starts scheduler"| node_wakeup_scheduler
node_bot_runtime -->|"starts API"| node_http_api
node_bot_runtime -->|"reads settings"| node_config
node_message_handler -->|"sends replies"| node_qq_client
node_message_handler -->|"updates memories"| node_conversation_store
node_media_web -->|"requests recognition"| node_model_api
node_http_api -->|"reads histories"| node_conversation_store
node_http_api -->|"sends messages"| node_qq_client
node_http_api -->|"normalizes tasks"| node_shared_tasks
node_http_api -->|"manages pushes"| node_push_scheduler
node_http_api -->|"manages wakeups"| node_wakeup_scheduler
node_push_scheduler -->|"validates tasks"| node_shared_tasks
node_push_scheduler -->|"sends pushes"| node_qq_client
node_wakeup_scheduler -->|"validates tasks"| node_shared_tasks
node_wakeup_scheduler -->|"generates replies"| node_chat_ai
node_wakeup_scheduler -->|"records wakeups"| node_conversation_store
node_wakeup_scheduler -->|"sends wakeups"| node_qq_client
node_config -->|"configures logs"| node_logging
node_message_handler -->|"reports events"| node_logging
node_tool_runtime -->|"manages pushes"| node_push_scheduler
node_tool_runtime -->|"manages wakeups"| node_wakeup_scheduler

click node_bot_entry "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/bot.py"
click node_bot_runtime "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/core.py"
click node_qq_client "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/client.py"
click node_config "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/config.py"
click node_message_handler "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/msg.py"
click node_media_web "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/ai.py"
click node_chat_ai "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/ai.py"
click node_tool_runtime "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/tool.py"
click node_conversation_store "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/memory.py"
click node_shared_tasks "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/task_core.py"
click node_http_api "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/api_server.py"
click node_push_scheduler "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/scheduler.py"
click node_wakeup_scheduler "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/wakeup_scheduler.py"
click node_logging "https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/log.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bot_entry,node_bot_runtime,node_qq_client,node_config,node_logging,node_operator toneBlue
class node_message_handler,node_media_web toneAmber
class node_chat_ai,node_tool_runtime,node_model_api toneMint
class node_conversation_store toneRose
class node_shared_tasks,node_http_api,node_push_scheduler,node_wakeup_scheduler,node_qq toneIndigo
```

## Components

### Bot Runtime

- [Bot Entry](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/bot.py): `bot.py`
- [Bot Orchestration](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/core.py): `core.py`
- [QQ Client](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/client.py): `client.py`
- [Configuration](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/config.py): `config.py`
- [Logging](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/log.py): `log.py`

### Conversation Processing

- [Message Handling](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/msg.py): `msg.py`
- [Media And Web Processing](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/ai.py): `ai.py`

### AI And Tools

- [AI Conversation](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/ai.py): `ai.py`
- [Tool Execution](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/tool.py): `tool.py`

### Memory And State

- [Conversation Memory](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/memory.py): `memory.py`

### API And Scheduling

- [Task Rules](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/task_core.py): `task_core.py`
- [HTTP API](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/api_server.py): `api_server.py`
- [Push Scheduler](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/scheduler.py): `scheduler.py`
- [Wakeup Scheduler](https://github.com/gaofeiyang360-create/python-qq-chatbot/blob/main/wakeup_scheduler.py): `wakeup_scheduler.py`

### Other components

- **QQ Users**
- **QQ Platform**
- **AI Model APIs**

## Connections

- QQ Users → QQ Platform: sends messages (evidence: `README.md`)
- QQ Platform → QQ Client: delivers events (evidence: `README.md`)
- QQ Client → Message Handling: routes messages (evidence: `README.md`)
- Message Handling → Media And Web Processing: processes media (evidence: `README.md`)
- Message Handling → Conversation Memory: records history (evidence: `msg.py`)
- Message Handling → AI Conversation: requests replies (evidence: `README.md`)
- AI Conversation → AI Model APIs: calls models (evidence: `ai.py`)
- AI Conversation → Conversation Memory: uses memory (evidence: `ai.py`)
- AI Conversation → Tool Execution: dispatches tools (evidence: `README.md`)
- Tool Execution → QQ Client: sends actions (evidence: `tool.py`)
- QQ Client → QQ Platform: sends replies (evidence: `README.md`)
- Bot Entry → Bot Orchestration: starts bots (evidence: `bot.py`)
- Bot Orchestration → QQ Client: runs clients (evidence: `core.py`)
- Bot Orchestration → Push Scheduler: starts scheduler (evidence: `core.py`)
- Bot Orchestration → Wakeup Scheduler: starts scheduler (evidence: `core.py`)
- Bot Orchestration → HTTP API: starts API (evidence: `core.py`)
- Bot Orchestration → Configuration: reads settings (evidence: `core.py`)
- Message Handling → QQ Client: sends replies (evidence: `README.md`)
- Message Handling → Conversation Memory: updates memories (evidence: `msg.py`)
- Media And Web Processing → AI Model APIs: requests recognition (evidence: `README.md`)
- HTTP API → Conversation Memory: reads histories (evidence: `api_server.py`)
- HTTP API → QQ Client: sends messages (evidence: `api_server.py`)
- HTTP API → Task Rules: normalizes tasks (evidence: `api_server.py`)
- HTTP API → Push Scheduler: manages pushes (evidence: `api_server.py`)
- HTTP API → Wakeup Scheduler: manages wakeups (evidence: `api_server.py`)
- Push Scheduler → Task Rules: validates tasks (evidence: `scheduler.py`)
- Push Scheduler → QQ Client: sends pushes (evidence: `scheduler.py`)
- Wakeup Scheduler → Task Rules: validates tasks (evidence: `wakeup_scheduler.py`)
- Wakeup Scheduler → AI Conversation: generates replies (evidence: `wakeup_scheduler.py`)
- Wakeup Scheduler → Conversation Memory: records wakeups (evidence: `wakeup_scheduler.py`)
- Wakeup Scheduler → QQ Client: sends wakeups (evidence: `wakeup_scheduler.py`)
- Configuration → Logging: configures logs (evidence: `log.py`)
- Message Handling → Logging: reports events (evidence: `msg.py`)
- Tool Execution → Push Scheduler: manages pushes (evidence: `tool.py`)
- Tool Execution → Wakeup Scheduler: manages wakeups (evidence: `tool.py`)
