docs: update documentation and project structure

2026-09-22 13:38:43 +00:00 · 2026-02-07 23:50:13 +08:00
parent 58c27f9136
commit 5ebe211791
9 changed files with 1187 additions and 0 deletions
@@ -0,0 +1,96 @@
+# 02. 架构设计 (Architecture Design - Framework Aligned)
+
+## 1. 总体架构图 (Pragmatic Architecture)
+
+本架构旨在最大限度复用 AstrBot 框架能力，通过职责拆分（而非分层解耦）来降低 `AutoScheduler` 的复杂度。
+
+```mermaid
+graph TD
+    subgraph "AstrBot Framework (宿主环境)"
+        TaskScheduler["Context.task_scheduler\n(APScheduler)"]
+        Context["Context\n(Session/Event/PlatformManager)"]
+        StarTools["StarTools\n(Message/Image)"]
+    end
+
+    subgraph "Plugin Core (核心逻辑)"
+        Bootstrap["Plugin Bootstrap\n(main.py)"]
+        SchedulerJob["Scheduler Job\n(定时任务回调)"]
+        
+        AnalysisOrchestrator["Analysis Orchestrator\n(原有逻辑拆分)"]
+        
+        subgraph "Extracted Modules (提取模块)"
+            MessageSender["Message Sender\n(统一发送+降级)"]
+            ReportDispatcher["Report Dispatcher\n(报告生成+分发)"]
+            BotManagerEnh["Bot Manager\n(Session管理+群发现)"]
+        end
+    end
+
+    subgraph "Infrastructure Enhancements (基建增强)"
+        TraceContext["Trace Context\n(contextvars)"]
+        LLMClient["LLM Client\n(CircuitBreaker + RateLimit)"]
+    end
+
+    %% Flow
+    Bootstrap -->|Register Job| TaskScheduler
+    TaskScheduler -->|Trigger| SchedulerJob
+    
+    SchedulerJob -->|Set TraceID| TraceContext
+    SchedulerJob -->|Invoke| AnalysisOrchestrator
+    
+    AnalysisOrchestrator -->|Get Groups| BotManagerEnh
+    BotManagerEnh -->|Query| Context
+    
+    AnalysisOrchestrator -->|Analyze| LLMClient
+    
+    AnalysisOrchestrator -->|Generate Report| ReportDispatcher
+    ReportDispatcher -->|Send Report| MessageSender
+    
+    MessageSender -->|Use| StarTools
+    MessageSender -->|Fallback| Context
+```
+
+## 2. 核心组件详解
+
+### 2.1 任务调度 (Scheduler)
+**不再自建循环**。直接使用 AstrBot 提供的 `Context.task_scheduler` (APScheduler 实例)。
+- **注册**: 在 `__init__` 或 `OnPlatformLoaded` 中注册 cron job。
+- **优势**: 自动处理时区、任务持久化（如果配置）、优雅关闭。
+
+### 2.2 消息发送 (MessageSender)
+**统一发送入口**。将散落在各处的发送逻辑收敛到 `src/core/message_sender.py`。
+- **职责**:
+    1.  **协议适配**: 优先构建 `AstrMessageEvent` (即使是主动发送，也可构造虚拟 Event)，调用 `Context.send_message`。
+    2.  **降级策略**: URL发送失败 -> 下载转Base64发送 -> 纯文本回退。
+    3.  **合并转发**: 封装 OneBot v11 的 Forward Message 构建细节。
+- **依赖**: 依赖 `Context` 和 `StarTools`，而非直接依赖 `bot.api`。
+
+### 2.3 分析编排 (AnalysisOrchestrator / ReportDispatcher)
+**逻辑拆分**。
+- `ReportDispatcher`: 接收 `AnalysisResult`，决定调用哪个渲染器（HTML/Text/PDF），并调用 `MessageSender` 发送。
+- `AnalysisOrchestrator`: 负责并发控制（Semaphore）和错误处理（Partial Failure）。
+
+### 2.4 可观测性 (TraceContext)
+**零侵入追踪**。
+- 使用 `contextvars.ContextVar` 存储 `trace_id`。
+- 实现 `TraceLogFilter` 自动注入 logging record。
+- 效果：在 `SchedulerJob` 入口设置一次 ID，后续深层调用的所有 `logger.info` 自动带上 `[trace_id: xxx]`。
+
+### 2.5 LLM 客户端增强
+**原地增强**。不重写 `LLMAnalyzer`，而是在 `call_provider_with_retry` 层面增加：
+- **CircuitBreaker**: 简单的失败计数器 (Windowed Counter)。
+- **RateLimiter**: `asyncio.Semaphore` 全局控制并发数。
+
+## 3. 发送流程演进
+
+### 旧流程 (Current)
+`AutoScheduler` -> `_send_image_message` -> `bot.api.call_action("send_group_msg")` -> (失败) -> `RetryManager` queue -> `RetryManager` worker -> `bot.api`
+
+### 新流程 (Proposed)
+`SchedulerJob` -> `ReportDispatcher` -> `MessageSender.send_image(url)`
+-> **Attempt 1**: `Context.send_message(image(url))`
+-> **Fail**: Catch generic exception
+-> **Attempt 2**: Download -> `Context.send_message(image(base64))`
+-> **Fail**: Catch exception
+-> **Fallback**: `MessageSender.send_text(report.text)` (Instant Fallback, no complex queue)
+
+> **注**: 如果确实需要异步低优先级的重试队列，可以将 `MessageSender` 的失败任务推送到 `Context.task_scheduler` 的一次性延时任务中，复用框架能力。