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

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

```mermaid
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处理 -> 协议适配器解析 -> 事件总线分发 -> 订阅者处理 -> 结果返回。

```mermaid
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: 确认当前目录结构和代码风格，生成符合规范的代码