feat: 初始化多机器人服务端项目框架

基于Go语言构建多机器人服务端框架，包含配置管理、事件总线、依赖注入等核心模块添加项目基础结构、README、gitignore和初始代码实现
2026-01-04 21:19:17 +08:00
commit ac0dfb64c9
22 changed files with 2385 additions and 0 deletions
--- a/.codebuddy/plans/cellbot-multibot-server_ec830ef3.md
+++ b/.codebuddy/plans/cellbot-multibot-server_ec830ef3.md
@@ -0,0 +1,209 @@
+---
+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: 确认当前目录结构和代码风格，生成符合规范的代码