From 1a7111973bd654412fa6fafa49666b1f0ace1e88 Mon Sep 17 00:00:00 2001
From: snowy-yang <102860110+snowy-yang@users.noreply.github.com>
Date: Sun, 20 Sep 2026 22:16:05 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=20README=20=E6=9E=B6?=
 =?UTF-8?q?=E6=9E=84=E5=9B=BE=E4=B8=8E=20API=20=E6=A8=A1=E5=9D=97=E8=A1=A8?=
 =?UTF-8?q?=EF=BC=88=E5=8D=8F=E8=AE=AE=E5=88=86=E6=B5=81=E5=90=8E=E6=AE=8B?=
 =?UTF-8?q?=E7=95=99=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md   | 23 ++++++++++++-----------
 docs/API.md |  7 ++++---
 2 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index beff31a..127a69e 100644
--- a/README.md
+++ b/README.md
@@ -9,38 +9,39 @@ QQ 官方机器人 Python SDK（Python 3.13 / asyncio / aiohttp），支持 WebS
 ```mermaid
 flowchart TB
     subgraph 接入层
-        WS["WebsocketConnecter（ws 长连接 / 重连 / 看门狗）"]
+        WS["WebsocketConnecter（ws 长连接 / 重连 / 心跳看门狗）"]
         WH["WebhookConnecter（http 回调 / 验签 / 去重）"]
     end
-    subgraph 分发层
-        Q[("EventQueue")]
-        EE["EventEmitter（路由 / 参数注入 / 异常隔离）"]
-    end
     subgraph 协议层
-        WSP["WebsocketProtocol（鉴权 / 心跳 / 序列号）"]
+        WSP["WebsocketProtocol（握手 / 会话 / 序列号）"]
         WHP["WebhookProtocol（op=13 验证应答）"]
     end
+    subgraph 分发层
+        Q[("EventQueue<br/>业务事件 op=0")]
+        EE["EventEmitter（路由 / 参数注入 / 异常隔离）"]
+    end
     subgraph 业务层
         API["BotApi（REST + ApiError）"]
         USER["用户 handler @ee.on(...)"]
     end
     QQ["QQ 开放平台"]
 
-    WS --> Q
-    WH --> Q
+    WS -. "逐帧 on_frame" .-> WSP
+    WH -. "op=13 逐帧 on_frame" .-> WHP
+    WS -->|"业务事件"| Q
+    WH -->|"业务事件"| Q
     Q --> EE
-    EE <--> WSP
     EE --> USER
     USER --> API
     API --> 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 续传
 - Webhook 接入自带 Ed25519 验签、op=13 验证应答与 60s TTL 事件去重
 - 事件订阅由项目根目录的 `intents.toml` 控制，按大类（Intents 分组）开关，将对应分组改为 `true` 即可
diff --git a/docs/API.md b/docs/API.md
index 32532d6..64417db 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -233,9 +233,10 @@ DirectMessage     # 同 AtMessage
 
 | 模块 | 职责 |
 |---|---|
-| `connecter.py` | `WebsocketConnecter` / `WebhookConnecter`：接入归一为事件流入、reply 流出 |
-| `ws_protocol.py` | IDENTIFY/RESUME 鉴权、apscheduler 心跳、会话序列号 |
+| `connecter.py` | `WebsocketConnecter` / `WebhookConnecter`：接入归一为业务事件流入、出站帧流出 |
+| `protocol.py` | `BaseProtocol` 协议处理器接口（`on_frame`，由连接适配器逐帧调用） |
+| `ws_protocol.py` | IDENTIFY/RESUME 鉴权、会话语义与 `s` 序列号（心跳在 connecter 内） |
 | `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 位掩码 |
 | `__init__.py` | `main`/`run_loop` 入口与组件显式装配 |