187 lines
5.8 KiB
Markdown
187 lines
5.8 KiB
Markdown
# Konabot Project Context
|
|
|
|
## Project Overview
|
|
|
|
Konabot is a multi-platform chatbot built using the NoneBot2 framework, primarily used within MTTU (likely an organization or community). The bot supports multiple adapters including Discord, QQ (via Onebot), Minecraft, and Console interfaces.
|
|
|
|
### Key Features
|
|
- Multi-platform support (Discord, QQ, Minecraft, Console)
|
|
- Rich plugin ecosystem with over 20 built-in plugins
|
|
- Asynchronous database system with connection pooling (SQLite-based)
|
|
- Advanced image processing capabilities
|
|
- Integration with external services like Bilibili analysis
|
|
- Support for Large Language Models (LLM)
|
|
- Web rendering capabilities for advanced image generation
|
|
|
|
## Technology Stack
|
|
|
|
- **Framework**: NoneBot2
|
|
- **Language**: Python 3.12+
|
|
- **Dependency Management**: Poetry
|
|
- **Database**: SQLite with aiosqlite for async operations
|
|
- **Build System**: Just (task runner)
|
|
- **Containerization**: Docker
|
|
- **CI/CD**: Drone CI
|
|
- **Testing**: Pytest
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
konabot/
|
|
├── bot.py # Main entry point
|
|
├── pyproject.toml # Project dependencies and metadata
|
|
├── justfile # Task definitions
|
|
├── Dockerfile # Container build definition
|
|
├── .drone.yml # CI/CD pipeline configuration
|
|
├── konabot/ # Main source code
|
|
│ ├── common/ # Shared utilities and modules
|
|
│ │ ├── database/ # Async database manager with connection pooling
|
|
│ │ ├── llm/ # Large Language Model integration
|
|
│ │ ├── web_render/ # Web-based image rendering
|
|
│ │ └── ... # Other utilities
|
|
│ ├── plugins/ # Plugin modules (core functionality)
|
|
│ │ ├── air_conditioner/
|
|
│ │ ├── bilibili_fetch/
|
|
│ │ ├── gen_qrcode/
|
|
│ │ ├── hanzi/
|
|
│ │ ├── idiomgame/
|
|
│ │ ├── image_process/
|
|
│ │ ├── roll_dice/
|
|
│ │ ├── weather/
|
|
│ │ └── ... (20+ plugins)
|
|
│ └── test/
|
|
├── tests/ # Test suite
|
|
├── scripts/ # Utility scripts
|
|
├── docs/ # Documentation
|
|
├── assets/ # Static assets
|
|
└── data/ # Runtime data storage
|
|
```
|
|
|
|
## Development Environment Setup
|
|
|
|
### Prerequisites
|
|
- Python 3.12+
|
|
- Git
|
|
- Poetry (installed via pipx)
|
|
|
|
### Installation Steps
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone https://gitea.service.jazzwhom.top/Passthem/konabot.git
|
|
cd konabot
|
|
```
|
|
2. Install dependencies:
|
|
```bash
|
|
poetry install
|
|
```
|
|
3. Configure environment:
|
|
- Copy `.env.example` to `.env`
|
|
- Modify settings as needed for your platform adapters
|
|
|
|
### Platform Adapters Configuration
|
|
- **Discord**: Set `ENABLE_DISCORD=true` and configure bot token
|
|
- **QQ (Onebot)**: Set `ENABLE_QQ=true` and configure connection
|
|
- **Console**: Enabled by default, disable with `ENABLE_CONSOLE=false`
|
|
- **Minecraft**: Set `ENABLE_MINECRAFT=true`
|
|
|
|
## Building and Running
|
|
|
|
### Development
|
|
- Auto-reload development mode:
|
|
```bash
|
|
poetry run just watch
|
|
```
|
|
- Manual start:
|
|
```bash
|
|
poetry run python bot.py
|
|
```
|
|
|
|
### Production
|
|
- Docker container build and run:
|
|
```bash
|
|
docker build -t konabot .
|
|
docker run konabot
|
|
```
|
|
|
|
## Testing
|
|
|
|
Run the test suite with:
|
|
```bash
|
|
poetry run pytest
|
|
```
|
|
|
|
Tests are located in the `tests/` directory and focus primarily on core functionality like the database manager.
|
|
|
|
## Database System
|
|
|
|
The project implements a custom asynchronous database manager (`konabot/common/database/__init__.py`) with these features:
|
|
- Connection pooling for performance
|
|
- Parameterized queries for security
|
|
- SQL file execution support
|
|
- Support for both string and Path objects for file paths
|
|
- Automatic resource management
|
|
|
|
Example usage:
|
|
```python
|
|
from konabot.common.database import DatabaseManager
|
|
|
|
db = DatabaseManager()
|
|
results = await db.query("SELECT * FROM users WHERE age > ?", (18,))
|
|
await db.execute("INSERT INTO users (name, email) VALUES (?, ?)", ("John", "john@example.com"))
|
|
```
|
|
|
|
## Plugin Architecture
|
|
|
|
Plugins are organized in `konabot/plugins/` and follow the NoneBot2 plugin structure. Each plugin typically consists of:
|
|
- `__init__.py`: Main plugin logic using Alconna command parser
|
|
- Supporting modules for specific functionality
|
|
|
|
Popular plugins include:
|
|
- `roll_dice`: Dice rolling with image generation
|
|
- `weather`: Weather radar image fetching
|
|
- `bilibili_fetch`: Bilibili video analysis
|
|
- `image_process`: Image manipulation tools
|
|
- `markdown`: Markdown rendering
|
|
|
|
## CI/CD Pipeline
|
|
|
|
Drone CI is configured with two pipelines:
|
|
1. **Nightly builds**: Triggered on pushes to master branch
|
|
2. **Release builds**: Triggered on git tags
|
|
|
|
Both pipelines:
|
|
- Build Docker images
|
|
- Test plugin loading
|
|
- Verify Playwright functionality
|
|
- Send notifications via ntfy
|
|
|
|
## Development Conventions
|
|
|
|
- Use Poetry for dependency management
|
|
- Follow NoneBot2 plugin development patterns
|
|
- Write async code for database operations
|
|
- Use Alconna for command parsing
|
|
- Organize SQL queries in separate files when complex
|
|
- Write tests for core functionality
|
|
- Document features in the `docs/` directory
|
|
|
|
## Common Development Tasks
|
|
|
|
1. **Add a new plugin**:
|
|
- Create a new directory in `konabot/plugins/`
|
|
- Implement functionality in `__init__.py`
|
|
- Use Alconna for command definition
|
|
|
|
2. **Database operations**:
|
|
- Use the `DatabaseManager` class
|
|
- Always parameterize queries
|
|
- Store complex SQL in separate `.sql` files
|
|
|
|
3. **Image processing**:
|
|
- Leverage existing utilities in `image_process` plugin
|
|
- Use Pillow and Skia-Python for advanced graphics
|
|
|
|
4. **Testing**:
|
|
- Add tests to the `tests/` directory
|
|
- Use pytest with async support
|
|
- Mock external services when needed |