# prolet1966/qq-agent-for-linux architecture

> Architecture diagram of the GitHub repository prolet1966/qq-agent-for-linux, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prolet1966/qq-agent-for-linux
- Repository: https://github.com/prolet1966/qq-agent-for-linux

## Overview

QQ-Agent is a Linux desktop QQ group AI bot: QQ messages arrive through the OneBot v11/SnowLuma connection, are handled by the agent, and replies or scheduled messages are sent back to chats. Its central workflow combines conversation orchestration, OpenAI-compatible model access, and registered skills/plugins; the desktop console provides configuration and session controls. The map also preserves the documented knowledge, memory, media, search, and scheduling capabilities. README and sampled excerpts support the broad boundaries, but most runtime wiring was not sampled, so uncertain internal call edges are omitted.

Main entry points: [`src/orchestrator.js`](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/orchestrator.js) (Conversation Orchestrator), [`src/store.js`](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/store.js) (Agent Data), [`src/server.js`](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/server.js) (HTTP API), [`src/onebot.js`](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/onebot.js) (OneBot Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop and API"]
  node_electron["Electron Shell<br/>[main.js]"]
  node_console["Web Console<br/>[app.js]"]
  node_http["HTTP API<br/>[server.js]"]
  node_routes["API Routes<br/>[routes.js]"]
end

subgraph group_agent["Agent Runtime"]
  node_onebot["OneBot Adapter<br/>[onebot.js]"]
  node_orchestrator["Conversation Orchestrator<br/>[orchestrator.js]"]
  node_llm["Model Access<br/>[llm.js]"]
  node_prompt["Prompt Assembly<br/>[prompt.js]"]
  node_sender["Message Sender<br/>[sender.js]"]
  node_state[("Agent Data<br/>[store.js]")]
end

subgraph group_extensions["Skills and Plugins"]
  node_skills["Skill Manager<br/>[manager.js]"]
  node_loader["Plugin Loader<br/>[plugin-loader.js]"]
  node_skillset["Skills"]
  node_pluginset["Plugins"]
end

subgraph group_capabilities["Conversation Capabilities"]
  node_schedule["Schedules<br/>[index.js]"]
  node_timed["Timed Messages<br/>[index.js]"]
  node_kb["Knowledge Growth<br/>[index.js]"]
  node_memory["Conversation Memory<br/>[index.js]"]
  node_search["Search Aggregation<br/>[index.js]"]
  node_media["Media Download<br/>[index.js]"]
end

node_operator(("Operator"))
node_qq["Linux QQ"]
node_snowluma["SnowLuma"]

node_operator -->|"sends message"| node_qq
node_qq -->|"provides client"| node_snowluma
node_snowluma -->|"OneBot events"| node_onebot
node_onebot -->|"delivers events"| node_orchestrator
node_orchestrator -->|"builds context"| node_prompt
node_orchestrator -->|"requests response"| node_llm
node_llm -->|"returns response"| node_orchestrator
node_orchestrator -->|"dispatches reply"| node_sender
node_sender -->|"sends messages"| node_onebot
node_electron -->|"starts core"| node_http
node_operator -->|"configures"| node_console
node_console -->|"API requests"| node_http
node_http -->|"dispatches"| node_routes
node_routes -->|"reads or updates"| node_state
node_loader -->|"registers"| node_skills
node_loader -->|"loads"| node_pluginset
node_skills -->|"manages"| node_skillset
node_schedule -->|"stores schedules"| node_state
node_schedule -->|"adds reminders"| node_orchestrator
node_timed -->|"stores messages"| node_state
node_kb -->|"persists knowledge"| node_state
node_memory -->|"persists memory"| node_state
node_search -->|"provides search"| node_orchestrator
node_media -->|"provides downloads"| node_orchestrator

click node_electron "https://github.com/prolet1966/qq-agent-for-linux/blob/main/electron/main.js"
click node_console "https://github.com/prolet1966/qq-agent-for-linux/blob/main/ui/app.js"
click node_http "https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/server.js"
click node_routes "https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/routes.js"
click node_onebot "https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/onebot.js"
click node_orchestrator "https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/orchestrator.js"
click node_llm "https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/llm.js"
click node_prompt "https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/prompt.js"
click node_sender "https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/sender.js"
click node_skills "https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/skills/manager.js"
click node_loader "https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/plugin-loader.js"
click node_skillset "https://github.com/prolet1966/qq-agent-for-linux/tree/main/skills"
click node_pluginset "https://github.com/prolet1966/qq-agent-for-linux/tree/main/plugins"
click node_schedule "https://github.com/prolet1966/qq-agent-for-linux/blob/main/skills/schedule/index.js"
click node_timed "https://github.com/prolet1966/qq-agent-for-linux/blob/main/skills/timed-message/index.js"
click node_kb "https://github.com/prolet1966/qq-agent-for-linux/blob/main/plugins/kb-growth/index.js"
click node_memory "https://github.com/prolet1966/qq-agent-for-linux/blob/main/plugins/conversation-memory/index.js"
click node_search "https://github.com/prolet1966/qq-agent-for-linux/blob/main/plugins/search-aggregator/index.js"
click node_media "https://github.com/prolet1966/qq-agent-for-linux/blob/main/plugins/media-download/index.js"
click node_state "https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/store.js"

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_electron,node_console,node_http,node_routes toneBlue
class node_onebot,node_orchestrator,node_llm,node_prompt,node_sender,node_state toneAmber
class node_skills,node_loader,node_skillset,node_pluginset toneMint
class node_schedule,node_timed,node_kb,node_memory,node_search,node_media toneRose
class node_operator,node_qq,node_snowluma toneIndigo
```

## Components

### Desktop and API

- [Electron Shell](https://github.com/prolet1966/qq-agent-for-linux/blob/main/electron/main.js): `electron/main.js`
- [Web Console](https://github.com/prolet1966/qq-agent-for-linux/blob/main/ui/app.js): `ui/app.js`
- [HTTP API](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/server.js): `src/server.js`
- [API Routes](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/routes.js): `src/routes.js`

### Agent Runtime

- [OneBot Adapter](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/onebot.js): `src/onebot.js`
- [Conversation Orchestrator](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/orchestrator.js): `src/orchestrator.js`
- [Model Access](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/llm.js): `src/llm.js`
- [Prompt Assembly](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/prompt.js): `src/prompt.js`
- [Message Sender](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/sender.js): `src/sender.js`
- [Agent Data](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/store.js): `src/store.js`

### Skills and Plugins

- [Skill Manager](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/skills/manager.js): `src/skills/manager.js`
- [Plugin Loader](https://github.com/prolet1966/qq-agent-for-linux/blob/main/src/plugin-loader.js): `src/plugin-loader.js`
- [Skills](https://github.com/prolet1966/qq-agent-for-linux/tree/main/skills): `skills`
- [Plugins](https://github.com/prolet1966/qq-agent-for-linux/tree/main/plugins): `plugins`

### Conversation Capabilities

- [Schedules](https://github.com/prolet1966/qq-agent-for-linux/blob/main/skills/schedule/index.js): `skills/schedule/index.js`
- [Timed Messages](https://github.com/prolet1966/qq-agent-for-linux/blob/main/skills/timed-message/index.js): `skills/timed-message/index.js`
- [Knowledge Growth](https://github.com/prolet1966/qq-agent-for-linux/blob/main/plugins/kb-growth/index.js): `plugins/kb-growth/index.js`
- [Conversation Memory](https://github.com/prolet1966/qq-agent-for-linux/blob/main/plugins/conversation-memory/index.js): `plugins/conversation-memory/index.js`
- [Search Aggregation](https://github.com/prolet1966/qq-agent-for-linux/blob/main/plugins/search-aggregator/index.js): `plugins/search-aggregator/index.js`
- [Media Download](https://github.com/prolet1966/qq-agent-for-linux/blob/main/plugins/media-download/index.js): `plugins/media-download/index.js`

### Other components

- **Operator**
- **Linux QQ**
- **SnowLuma**

## Connections

- Operator → Linux QQ: sends message
- Linux QQ → SnowLuma: provides client
- SnowLuma → OneBot Adapter: OneBot events
- OneBot Adapter → Conversation Orchestrator: delivers events
- Conversation Orchestrator → Prompt Assembly: builds context
- Conversation Orchestrator → Model Access: requests response
- Model Access → Conversation Orchestrator: returns response
- Conversation Orchestrator → Message Sender: dispatches reply
- Message Sender → OneBot Adapter: sends messages
- Electron Shell → HTTP API: starts core
- Operator → Web Console: configures
- Web Console → HTTP API: API requests
- HTTP API → API Routes: dispatches
- API Routes → Agent Data: reads or updates
- Plugin Loader → Skill Manager: registers
- Plugin Loader → Plugins: loads
- Skill Manager → Skills: manages
- Schedules → Agent Data: stores schedules
- Schedules → Conversation Orchestrator: adds reminders
- Timed Messages → Agent Data: stores messages
- Knowledge Growth → Agent Data: persists knowledge
- Conversation Memory → Agent Data: persists memory
- Search Aggregation → Conversation Orchestrator: provides search
- Media Download → Conversation Orchestrator: provides downloads