# 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