konabot/QWEN.md

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:

   git clone https://gitea.service.jazzwhom.top/Passthem/konabot.git
   cd konabot
   

2. Install dependencies:

   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:

  poetry run just watch
  

• Manual start:

  poetry run python bot.py
  

Production

• Docker container build and run:

  docker build -t konabot .
  docker run konabot
  

Testing

Run the test suite with:

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:

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