02. 架构设计 (Architecture Design - Framework Aligned)

1. 总体架构图 (Pragmatic Architecture)

本架构旨在最大限度复用 AstrBot 框架能力，通过职责拆分（而非分层解耦）来降低 AutoScheduler 的复杂度。

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 的一次性延时任务中，复用框架能力。

4.2 KiB Raw Blame History