# sj244/dsh-qq-bridge architecture

> Architecture diagram of the GitHub repository sj244/dsh-qq-bridge, 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/sj244/dsh-qq-bridge
- Repository: https://github.com/sj244/dsh-qq-bridge

## Overview

dsh-qq-bridge connects one existing DSH session to QQ through a OneBot WebSocket client. Its main workflow receives and normalizes QQ events, applies whitelist and wake rules, then delivers eligible messages to the explicitly selected session; responses can pass a QQ-specific outbound gate and return to the originating destination. Separate capabilities include image caching and description, live settings, a browser settings card, and explicitly invoked NapCat setup. The README documents several behaviors whose internal call paths were not sampled, so those links cite the README rather than implying source inspection.

Main entry points: [`index.js`](https://github.com/sj244/dsh-qq-bridge/blob/main/index.js) (Target DSH session), [`onebot.js`](https://github.com/sj244/dsh-qq-bridge/blob/main/onebot.js) (WebSocket transport), [`napcat.js`](https://github.com/sj244/dsh-qq-bridge/blob/main/napcat.js) (OneBot configuration), [`client/client.js`](https://github.com/sj244/dsh-qq-bridge/blob/main/client/client.js) (Settings card)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bridge["Message bridge"]
  node_event_handling["Event normalization<br/>[index.js]"]
  node_wake_policy["Wake policy<br/>[index.js]"]
  node_chat_buffer["Recent chat buffer<br/>[index.js]"]
  node_image_handling["Image cache and vision<br/>[index.js]"]
  node_transport["WebSocket transport<br/>[onebot.js]"]
end

subgraph group_session["Session interaction"]
  node_fixed_session["Target DSH session<br/>[index.js]"]
  node_followup["Follow-up window tool<br/>[index.js]"]
  node_outbound_gate["Outbound source gate<br/>[index.js]"]
  node_reply_format["Reply formatting<br/>[index.js]"]
end

subgraph group_config["Settings interface"]
  node_settings_api["Settings API and storage<br/>[index.js]"]
  node_settings_card["Settings card<br/>[client.js]"]
end

subgraph group_napcat["NapCat management"]
  node_napcat_actions["NapCat actions<br/>[index.js]"]
  node_release_download["Release download and verify<br/>[napcat.js]"]
  node_zip_extract["Safe ZIP extraction<br/>[napcat.js]"]
  node_onebot_config["OneBot configuration<br/>[napcat.js]"]
end

node_qq_user(("QQ participants"))
node_onebot_service(("OneBot server"))
node_napcat_process(("NapCat process"))
node_vision_model(("Vision model"))

node_qq_user -->|"sends events"| node_onebot_service
node_onebot_service -->|"delivers events"| node_transport
node_transport -->|"dispatches events"| node_event_handling
node_event_handling -->|"normalizes for"| node_wake_policy
node_wake_policy -->|"delivers eligible messages"| node_fixed_session
node_wake_policy -->|"records unwoken chat"| node_chat_buffer
node_chat_buffer -->|"adds recent context"| node_fixed_session
node_event_handling -->|"caches images"| node_image_handling
node_image_handling -->|"requests descriptions"| node_vision_model
node_image_handling -->|"adds image descriptions"| node_fixed_session
node_fixed_session -->|"invokes listening tool"| node_followup
node_fixed_session -->|"emits session events"| node_outbound_gate
node_outbound_gate -->|"permits QQ replies"| node_reply_format
node_reply_format -->|"sends formatted replies"| node_transport
node_transport -->|"calls actions"| node_onebot_service
node_settings_card -->|"reads and saves"| node_settings_api
node_settings_api -->|"reconfigures connection"| node_transport
node_fixed_session -->|"invokes management tool"| node_napcat_actions
node_napcat_actions -->|"downloads and verifies"| node_release_download
node_napcat_actions -->|"extracts release"| node_zip_extract
node_napcat_actions -->|"writes connection config"| node_onebot_config
node_napcat_actions -->|"launches process"| node_napcat_process
node_onebot_config -->|"configures service"| node_napcat_process

click node_event_handling "https://github.com/sj244/dsh-qq-bridge/blob/main/index.js"
click node_wake_policy "https://github.com/sj244/dsh-qq-bridge/blob/main/index.js"
click node_chat_buffer "https://github.com/sj244/dsh-qq-bridge/blob/main/index.js"
click node_image_handling "https://github.com/sj244/dsh-qq-bridge/blob/main/index.js"
click node_transport "https://github.com/sj244/dsh-qq-bridge/blob/main/onebot.js"
click node_fixed_session "https://github.com/sj244/dsh-qq-bridge/blob/main/index.js"
click node_followup "https://github.com/sj244/dsh-qq-bridge/blob/main/index.js"
click node_outbound_gate "https://github.com/sj244/dsh-qq-bridge/blob/main/index.js"
click node_reply_format "https://github.com/sj244/dsh-qq-bridge/blob/main/index.js"
click node_settings_api "https://github.com/sj244/dsh-qq-bridge/blob/main/index.js"
click node_settings_card "https://github.com/sj244/dsh-qq-bridge/blob/main/client/client.js"
click node_napcat_actions "https://github.com/sj244/dsh-qq-bridge/blob/main/index.js"
click node_release_download "https://github.com/sj244/dsh-qq-bridge/blob/main/napcat.js"
click node_zip_extract "https://github.com/sj244/dsh-qq-bridge/blob/main/napcat.js"
click node_onebot_config "https://github.com/sj244/dsh-qq-bridge/blob/main/napcat.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_event_handling,node_wake_policy,node_chat_buffer,node_image_handling,node_transport toneBlue
class node_fixed_session,node_followup,node_outbound_gate,node_reply_format toneAmber
class node_settings_api,node_settings_card,node_onebot_service toneMint
class node_napcat_actions,node_release_download,node_zip_extract,node_onebot_config toneRose
class node_qq_user,node_napcat_process,node_vision_model toneIndigo
```

## Components

### Message bridge

- [Event normalization](https://github.com/sj244/dsh-qq-bridge/blob/main/index.js): `index.js`
- [Wake policy](https://github.com/sj244/dsh-qq-bridge/blob/main/index.js): `index.js`
- [Recent chat buffer](https://github.com/sj244/dsh-qq-bridge/blob/main/index.js): `index.js`
- [Image cache and vision](https://github.com/sj244/dsh-qq-bridge/blob/main/index.js): `index.js`
- [WebSocket transport](https://github.com/sj244/dsh-qq-bridge/blob/main/onebot.js): `onebot.js`

### Session interaction

- [Target DSH session](https://github.com/sj244/dsh-qq-bridge/blob/main/index.js): `index.js`
- [Follow-up window tool](https://github.com/sj244/dsh-qq-bridge/blob/main/index.js): `index.js`
- [Outbound source gate](https://github.com/sj244/dsh-qq-bridge/blob/main/index.js): `index.js`
- [Reply formatting](https://github.com/sj244/dsh-qq-bridge/blob/main/index.js): `index.js`

### Settings interface

- [Settings API and storage](https://github.com/sj244/dsh-qq-bridge/blob/main/index.js): `index.js`
- [Settings card](https://github.com/sj244/dsh-qq-bridge/blob/main/client/client.js): `client/client.js`

### NapCat management

- [NapCat actions](https://github.com/sj244/dsh-qq-bridge/blob/main/index.js): `index.js`
- [Release download and verify](https://github.com/sj244/dsh-qq-bridge/blob/main/napcat.js): `napcat.js`
- [Safe ZIP extraction](https://github.com/sj244/dsh-qq-bridge/blob/main/napcat.js): `napcat.js`
- [OneBot configuration](https://github.com/sj244/dsh-qq-bridge/blob/main/napcat.js): `napcat.js`

### Other components

- **QQ participants**
- **OneBot server**
- **NapCat process**
- **Vision model**

## Connections

- QQ participants → OneBot server: sends events (evidence: `README.md`)
- OneBot server → WebSocket transport: delivers events (evidence: `README.md`)
- WebSocket transport → Event normalization: dispatches events (evidence: `README.md`)
- Event normalization → Wake policy: normalizes for (evidence: `README.md`)
- Wake policy → Target DSH session: delivers eligible messages (evidence: `README.md`)
- Wake policy → Recent chat buffer: records unwoken chat (evidence: `README.md`)
- Recent chat buffer → Target DSH session: adds recent context (evidence: `README.md`)
- Event normalization → Image cache and vision: caches images (evidence: `README.md`)
- Image cache and vision → Vision model: requests descriptions (evidence: `README.md`)
- Image cache and vision → Target DSH session: adds image descriptions (evidence: `README.md`)
- Target DSH session → Follow-up window tool: invokes listening tool (evidence: `README.md`)
- Target DSH session → Outbound source gate: emits session events (evidence: `README.md`)
- Outbound source gate → Reply formatting: permits QQ replies (evidence: `README.md`)
- Reply formatting → WebSocket transport: sends formatted replies (evidence: `README.md`)
- WebSocket transport → OneBot server: calls actions (evidence: `README.md`)
- Settings card → Settings API and storage: reads and saves (evidence: `client/client.js`)
- Settings API and storage → WebSocket transport: reconfigures connection (evidence: `index.js`)
- Target DSH session → NapCat actions: invokes management tool (evidence: `README.md`)
- NapCat actions → Release download and verify: downloads and verifies (evidence: `index.js`)
- NapCat actions → Safe ZIP extraction: extracts release (evidence: `index.js`)
- NapCat actions → OneBot configuration: writes connection config (evidence: `index.js`)
- NapCat actions → NapCat process: launches process (evidence: `README.md`)
- OneBot configuration → NapCat process: configures service (evidence: `README.md`)
