docs: 修正 README 架构图与 API 模块表(协议分流后残留)

This commit is contained in:
snowy-yang committed 2026-09-20 22:16:05 +08:00
1 parent 4d19db24e1
commit 1a7111973b
2 files changed
+16 -14

No files matched your search

+12 -11
View File
@@ -9,38 +9,39 @@ QQ 官方机器人 Python SDK(Python 3.13 / asyncio / aiohttp),支持 WebS
```mermaid ```mermaid
flowchart TB flowchart TB
subgraph 接入层 subgraph 接入层
WS["WebsocketConnecter(ws 长连接 / 重连 / 看门狗)"] WS["WebsocketConnecter(ws 长连接 / 重连 / 心跳看门狗)"]
WH["WebhookConnecter(http 回调 / 验签 / 去重)"] WH["WebhookConnecter(http 回调 / 验签 / 去重)"]
end end
subgraph 分发层
Q[("EventQueue")]
EE["EventEmitter(路由 / 参数注入 / 异常隔离)"]
end
subgraph 协议层 subgraph 协议层
WSP["WebsocketProtocol(鉴权 / 心跳 / 序列号)"] WSP["WebsocketProtocol(握手 / 会话 / 序列号)"]
WHP["WebhookProtocol(op=13 验证应答)"] WHP["WebhookProtocol(op=13 验证应答)"]
end end
subgraph 分发层
Q[("EventQueue<br/>业务事件 op=0")]
EE["EventEmitter(路由 / 参数注入 / 异常隔离)"]
end
subgraph 业务层 subgraph 业务层
API["BotApi(REST + ApiError)"] API["BotApi(REST + ApiError)"]
USER["用户 handler @ee.on(...)"] USER["用户 handler @ee.on(...)"]
end end
QQ["QQ 开放平台"] QQ["QQ 开放平台"]
WS --> Q WS -. "逐帧 on_frame" .-> WSP
WH --> Q WH -. "op=13 逐帧 on_frame" .-> WHP
WS -->|"业务事件"| Q
WH -->|"业务事件"| Q
Q --> EE Q --> EE
EE <--> WSP
EE --> USER EE --> USER
USER --> API USER --> API
API --> QQ API --> QQ
WS --> QQ WS --> QQ
``` ```
组件在 `run_loop` 显式装配,并按类型登记到 `emitter.services` 供 handler 参数注入(无全局单例);依赖关系、数据流与设计决策详见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 组件在 `run_loop` 显式装配,并按类型登记到 `emitter.services` 供 handler 参数注入(无全局单例);协议帧由连接适配器交给各自的协议处理器就地处理,只有 op=0 的业务事件经队列进入分发——依赖关系与设计决策详见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 特性 ## 特性
- 内置协议处理器(`ws_protocol.py` / `webhook_protocol.py`):HELLO 鉴权(IDENTIFY/RESUME 自动切换)、apscheduler 定时心跳、READY 会话捕获、INVALID_SESSION 会话失效处理 - 内置协议处理器(`ws_protocol.py` / `webhook_protocol.py`):HELLO 鉴权(IDENTIFY/RESUME 自动切换)、READY 会话捕获、INVALID_SESSION 会话失效处理;心跳由连接器按连接生命周期驱动
- 断线自动重连(指数退避 + 心跳看门狗),重连时自动 RESUME 续传 - 断线自动重连(指数退避 + 心跳看门狗),重连时自动 RESUME 续传
- Webhook 接入自带 Ed25519 验签、op=13 验证应答与 60s TTL 事件去重 - Webhook 接入自带 Ed25519 验签、op=13 验证应答与 60s TTL 事件去重
- 事件订阅由项目根目录的 `intents.toml` 控制,按大类(Intents 分组)开关,将对应分组改为 `true` 即可 - 事件订阅由项目根目录的 `intents.toml` 控制,按大类(Intents 分组)开关,将对应分组改为 `true` 即可
+4 -3
View File
@@ -233,9 +233,10 @@ DirectMessage # 同 AtMessage
| 模块 | 职责 | | 模块 | 职责 |
|---|---| |---|---|
| `connecter.py` | `WebsocketConnecter` / `WebhookConnecter`:接入归一为事件流入、reply 流出 | | `connecter.py` | `WebsocketConnecter` / `WebhookConnecter`:接入归一为业务事件流入、出站帧流出 |
| `ws_protocol.py` | IDENTIFY/RESUME 鉴权、apscheduler 心跳、会话序列号 | | `protocol.py` | `BaseProtocol` 协议处理器接口(`on_frame`,由连接适配器逐帧调用) |
| `ws_protocol.py` | IDENTIFY/RESUME 鉴权、会话语义与 `s` 序列号(心跳在 connecter 内) |
| `webhook_protocol.py` | op=13 验证应答 | | `webhook_protocol.py` | op=13 验证应答 |
| `queue.py` / `session.py` / `token.py` / `crypto.py` | 队列、ws 会话状态、token 缓存、Ed25519 签名 | | `queue.py` / `session.py` / `token.py` / `crypto.py` | 业务事件通道、ws 会话状态、token 缓存、Ed25519 签名 |
| `model.py` | Opcode、payload 类型、Intent 位掩码 | | `model.py` | Opcode、payload 类型、Intent 位掩码 |
| `__init__.py` | `main`/`run_loop` 入口与组件显式装配 | | `__init__.py` | `main`/`run_loop` 入口与组件显式装配 |