MaiBot Docs

English

简体中文

English

简体中文

Appearance

Development Guide ​

Updated: 07/22/2026Word count: 0 wordsReading time: 1 min

This section is aimed at deployment operators and advanced users — keeping MaiBot running smoothly, troubleshooting issues, extending integrations, and handling data archiving and automation.

Tech Stack

MaiBot uses Python 3.12+ / FastAPI / SQLModel / structlog / Pydantic + TOML hot reload, with dependency management via uv. For the full project structure and technology choices, see Configuration System.

Document Index ​

  • Database — SQLite + SQLModel 22 tables: connections and sessions, PRAGMA tuning, data archiving and troubleshooting. (Operations)
  • Configuration System — version chains, hot reload mechanisms, upgrade hooks, and legacy migration for the two TOML files (bot_config + model_config). (Operations / Advanced Users)
  • Message Server and Adapter Integration — how the WebSocket message server lets external adapters (NapCat, GoCQ, Discord, Telegram, etc.) connect to MaiBot: authentication, message flow, and deployment notes. (Operations)
  • LLM Model Integration — the LLM integration pipeline driven by the three concepts of APIProvider / ModelInfo / ModelTaskConfig; configure to connect. (Advanced Users)
  • MCP Integration and External Tool Access — MCP client integration: three transport options, tool registration, naming conflict handling, and debugging. (Advanced Users)
  • WebUI HTTP API Entry — 6 sub-articles: FastAPI backend HTTP / WebSocket API overview, covering authentication, route groups, and scene navigation. (Operations / Advanced Users)
  • Logging and Observability — structlog's three parallel output channels (file / console / WebUI): log tuning, third-party noise reduction, LLM request snapshot capture, and online troubleshooting. (Operations)
  • Statistics and Data Import/Export — hourly granularity aggregation tables, real-time dashboard queries, and async zip export: three data consumption pathways. (Operations / Advanced Users)
  • Event Pipeline and Hooks — the cooperative mechanism of the EventBus and named Hook dual event systems: intercepting / non-intercepting handlers, plugin bridging, and troubleshooting perspective. (Advanced Users / Plugin Internals)
  • Plugin Runtime Internal Architecture — the internal mechanics of the Host / Runner dual-process IPC architecture: msgpack encoding/decoding, hot reload, and fault isolation. For operations troubleshooting, not plugin development. (Plugin Internals)

Roadmaps ​

Extensions and Contributions ​

  • If you need to write plugins, head to the Plugin Development Documentation, which covers Manifest, lifecycle, component registration, and other developer-facing content.
  • If you want to contribute code to the MaiBot source, see the GitHub repository contribution guide. The contributing.md in this repository is no longer maintained; the GitHub repository is the canonical source.