cellbot/.codebuddy/plans/cellbot-multibot-server_ec830ef3.md

name, overview, todos

name	overview	todos
cellbot-multibot-server	基于Go语言的多机器人服务端,参考OneBot12协议设计通用框架,采用分层架构和依赖注入设计模式。	id content status setup-project 初始化Go模块项目结构，创建基础目录和go.mod completed id content status dependencies implement-config 实现配置模块，支持TOML解析和fsnotify热重载 completed setup-project id content status dependencies define-protocol 定义通用协议接口，提取OneBot12核心设计理念 completed setup-project id content status dependencies build-eventbus 实现基于channel的高性能事件总线 completed define-protocol id content status dependencies create-di-container 集成Uber Fx依赖注入容器，管理应用生命周期 completed implement-config build-eventbus id content status dependencies implement-fasthttp 封装fasthttp网络层，处理连接和通信 completed create-di-container id content status dependencies unit-tests 编写核心模块的单元测试和并发基准测试 completed build-eventbus implement-config

Product Overview

基于Go语言构建的高性能、可扩展的多机器人服务端，参考OneBot12协议的设计理念，旨在提供统一的机器人管理与消息分发框架。

Core Features

• 协议适配层：提取OneBot12核心设计，支持通用接口定义与扩展
• 多机器人管理：支持同时连接和管理多个不同实现的机器人实例
• 事件总线：基于channel的高性能发布订阅机制，实现模块间解耦通信
• 依赖注入容器：管理组件生命周期，降低耦合度
• 配置管理：支持TOML格式配置，具备热重载能力
• 反向WebSocket：支持高性能反向WebSocket通信连接

Tech Stack

• 语言: Go 1.21+
• 网络库: fasthttp (valyala/fasthttp)
• 配置: BurntSushi/toml + fsnotify (热重载)
• 依赖注入: Uber-go/fx 或 uber-go/dig
• 测试: 标准库 testing + testify
• 日志: uber-go/zap

Tech Architecture

System Architecture

采用分层架构结合依赖注入模式。

• 协议层: 定义OneBot12通用接口规范。
• 适配层: 实现不同平台的具体协议适配。
• 核心层: 事件总线、生命周期管理、依赖注入容器。
• 网络层: 基于fasthttp的高并发连接处理。

graph TD
    A[Client/Bot] -->|WebSocket/TCP| B[Network Layer: fasthttp]
    B --> C[Adapter Layer: Protocol Implementation]
    C -->|Event Message| D[Event Bus: Channel Pub/Sub]
    D --> E[Core Layer: Business Logic]
    F[Config Manager: TOML + Hot Reload] --> E
    G[DI Container: fx/dig] --> B
    G --> C
    G --> D
    G --> E

Module Division

• internal/protocol: 定义OneBot12核心接口（Event, Action, API）。
• internal/adapter: 协议适配器实现（如OneBot11适配器）。
• internal/engine: 核心引擎，包含事件总线与Bot管理。
• internal/config: 配置加载与热重载逻辑。
• internal/di: 依赖注入容器封装。
• pkg/fasthttp: fasthttp网络服务封装。

Data Flow

外部连接 -> fasthttp处理 -> 协议适配器解析 -> 事件总线分发 -> 订阅者处理 -> 结果返回。

flowchart LR
    A[Incoming Message] --> B[fasthttp Handler]
    B --> C[Adapter Parse]
    C --> D{Event Bus Channel}
    D -->|Subscribe| E[Handler 1]
    D -->|Subscribe| F[Handler 2]
    E --> G[Response]
    F --> G

Implementation Details

Core Directory Structure

cellbot-multibot-server/
├── cmd/
│   └── server/
│       └── main.go           # 程序入口，注入fx应用
├── internal/
│   ├── config/               # 配置模块
│   │   ├── config.go         # 配置结构体定义
│   │   └── loader.go         # TOML加载与fsnotify热重载
│   ├── protocol/             # 通用协议层
│   │   └── onebot12.go       # 核心接口定义
│   ├── adapter/              # 适配器层
│   │   ├── base.go           # 适配器基类
│   │   └── onebot11.go       # OneBot11实现示例
│   ├── engine/               # 核心引擎
│   │   ├── eventbus.go       # Channel发布订阅
│   │   └── bot.go            # 机器人实例管理
│   └── di/                   # 依赖注入
│       └── wire.go           # Provider定义
├── pkg/
│   └── net/                  # 网络封装
│       └── server.go         # fasthttp服务器封装
├── configs/
│   └── config.toml           # 默认配置文件
└── go.mod

Key Code Structures

Event Bus (Channel-based): 使用类型安全的channel进行事件分发，支持并发订阅与取消订阅。

type EventBus struct {
    subscribers map[string][]chan Event
    mu         sync.RWMutex
}

func (eb *EventBus) Publish(eventType string, event Event) {
    // 发布逻辑
}

func (eb *EventBus) Subscribe(eventType string) chan Event {
    // 订阅逻辑
}

Dependency Injection (Fx): 使用Uber Fx管理应用生命周期，提供优雅的启动与关闭。

// 提供Config实例
func ProvideConfig() *Config {
    return LoadConfig("config.toml")
}

// 提供EventBus实例
func ProvideEventBus() *EventBus {
    return NewEventBus()
}

Technical Implementation Plan

1. 配置与热重载

• 定义Config结构体，支持TOML映射。
• 使用fsnotify监听文件变化，实现平滑热重载。

2. 通用协议框架

• 抽象OneBot12核心概念：Action, Event, API。
• 定义统一的接口契约。

3. 事件总线设计

• 基于buffered channel实现高吞吐量。
• 实现带类型检查的订阅机制。

4. fasthttp集成

• 封装fasthttp Server，处理WebSocket升级。
• 实现连接池管理以优化性能。

5. 测试策略

• 单元测试覆盖核心逻辑（EventBus, Config）。
• 基准测试验证并发性能。

Agent Extensions

SubAgent

• code-explorer
• Purpose: 搜索和分析现有项目结构，确保新代码与现有模式一致
• Expected outcome: 确认当前目录结构和代码风格，生成符合规范的代码