Lingchu Bot

English | 中文

Lingchu Bot is an application-side group management bot powered by NoneBot2. It currently focuses on QQ group management through the OneBot V11 adapter while keeping a plugin, platform registry, configuration, storage, permission, and documentation structure that can grow toward broader cross-platform workflows.

Project status

Lingchu Bot has published its first 0.0.1 formal release. The project is still early and may make breaking changes before 1.0.0, but the current release is intended to be installable, documented, and reproducible through the release workflow.

Useful entry points:

• Online documentation
• User guide overview
• Quick start
• QQ command reference
• Architecture guide
• Contributing guide

What is in this repository

• nonebot-plugin-lingchu-bot: the Python package declared in pyproject.toml.
• src/plugins/nonebot_plugin_lingchu_bot: the core NoneBot plugin, including metadata, startup hooks, platform registry, command handlers, permissions, i18n, repositories, and storage helpers.
• [tool.nonebot] in pyproject.toml: local plugin loading configuration, installed adapter declarations, and dependency plugin declarations.
• apps/docs: the Astro / Starlight documentation site, with Chinese and English content.
• Dockerfile / docker-compose.yml: container runtime flow. The image generates /tmp/bot.py during build through nb-cli; the repository root does not ship a committed local bot.py.
• scripts/setup.sh: cross-platform initialization script for local development.

Capabilities

Future cross-platform and non-group-management features depend on later implementation and tests.

Adapter support

The currently implemented platform profile is QQ, and the only active adapter is OneBot V11:

LINGCHUAdapter=~onebot.v11

When LINGCHUAdapter is unset, Lingchu selects ~onebot.v11 by default. The selected adapter must also be loaded and registered by NoneBot; otherwise startup fails with a clear adapter-not-loaded error.

Only OneBot V11 is implemented. Configuring any other adapter ID (such as ~milky, ~qq, or ~onebot.v12) fails startup with PlatformAdapterUnknownError. Configuring multiple known adapters for the same platform fails with PlatformAdapterConflictError.

OneBot V11 currently has default and NapCat implementation paths. Some features are implementation-gated: for example, group announcement and group avatar entries are shown only when the selected implementation supports them, and remote announcement requires NapCat.Onebot >= 4.18.0.

Quick start

Requirements

• Python 3.13 (pyproject.toml requires >=3.13, <4.0; targets 3.13)
• uv
• Git
• A usable NoneBot runtime and OneBot V11 connection / account setup
• Node.js 24+ and pnpm for the docs / frontend workspace and the full setup script

Option A — Install via NB-CLI (recommended)

nb plugin install nonebot-plugin-lingchu-bot

This installs the published package from PyPI and registers it with NoneBot. After installation, add nonebot_plugin_lingchu_bot to your NoneBot plugin list or let NB-CLI manage it automatically.

Option B — Use as a local plugin directory

Clone the repository and initialize:

git clone https://github.com/xinvxueyuan/lingchu-bot.git
cd lingchu-bot
chmod +x scripts/setup.sh
./scripts/setup.sh

The setup script checks the operating system and toolchain, installs Python and Node.js dependencies, creates environment files, configures Git hooks, and can optionally install Playwright browsers.

Manual alternative:

uv sync --frozen
pnpm install
pnpm exec husky
cp .env.example .env

To load Lingchu Bot from an existing NoneBot project, point plugin_dirs at the cloned src/plugins directory:

# In the target NoneBot project's pyproject.toml
[tool.nonebot]
plugin_dirs = ["path/to/lingchu-bot/src/plugins"]

Option C — Run in Docker

# docker-compose.yml reads .env.prod; create it from your deployment settings.
cp .env.example .env.prod
docker compose up --build

Before connecting to a real platform, prepare the account, network, reverse WebSocket / HTTP settings, and permissions required by NoneBot and the OneBot V11 implementation you use.

Configuration

Deployment fields are resolved by NoneBot from OS environment variables, its .env files or global configuration, then code defaults. Lingchu does not implement a second dotenv or TOML override layer. Startup does not create deployment configuration or install JSON Schema files.

Online-editable command, menu-trigger, and platform-permission overrides are stored separately in localstore-owned runtime-overrides.toml. Boolean values in NoneBot .env files must use JSON-style lowercase true / false, not Python-style True / False.

Example runtime-overrides.toml:

permission_platform_runtime_passthrough = true

[command_trigger_overrides.member_mute]
chinese = "禁言"
english = "mute"

[menu_page_trigger_overrides.member-management]
chinese = "成员管理"
english = "member-management"

Runtime settings are read from the localstore-owned runtime-overrides.toml file. Deployment settings remain in NoneBot environment configuration; there is no project-specific configuration CLI or generated schema step.

Commands at a glance

Main menu:

菜单
menu

Default submenu pages:

• 成员管理 / member-management
• 发言管理 / speech-management
• 群聊管理 / group-chat-management
• 远程管理 / remote-management
• 系统管理 / system-management

Examples:

禁言 @用户 [时长秒数] [原因]
mute @user [duration seconds] [reason]

撤回 [@用户] [数量]
recall [@user] [count]

远程禁言 <群号或群名称> @用户 [时长秒数] [原因]
remote-mute <group_id_or_group_name> @user [duration seconds] [reason]

闭嘴 / 说话
silence / speak

开机 / 关机
boot / shutdown

Command trigger language is locale-exclusive. Chinese locales enable Chinese triggers; English locales enable short hyphenated English triggers. They are not enabled at the same time. Full command behavior, permission pre-checks, implementation filters, and remote management details are documented in QQ Commands.

Development and verification

CI checks Ruff, Markdown, Pyright, ty, pytest on multiple database backends, and docs site lint / test. Run the checks relevant to your change before committing.

Ruff:

uv run -m ruff check . --output-format=github
uv run -m ruff format --check .

Type checking:

uv run -m pyright
uv run -m ty check --output-format github

Python tests:

uv run -m pytest

# Optional multi-database testing:
# SQLALCHEMY_DATABASE_URL="postgresql+psycopg://postgres:postgres@localhost:5432/postgres" uv run -m pytest
# SQLALCHEMY_DATABASE_URL="mysql+aiomysql://mysql:mysql@localhost:3306/mymysql" uv run -m pytest

Documentation site:

pnpm --filter docs lint
pnpm --filter docs test
pnpm --filter docs check-types
pnpm --filter docs build

Runtime i18n catalogs:

task i18n

Markdown:

pnpm exec markdownlint-cli2 README.md README-zh.md

Contributing

Issues, tests, documentation, and code improvements are welcome. Please read CONTRIBUTING.md before starting; it describes the current collaboration workflow, GitNexus impact analysis requirements, version validation system, and PR checklist.

When participating in discussions and reviews, please follow CODE_OF_CONDUCT.md. For security-related issues, please refer to SECURITY.md.

License

This project uses a phased open-source license stack (see Repository-Policy.md for the transition rules and trigger date):

• Current phase — Software: LGPL-3.0-or-later (LICENSE-code). Documentation: GFDL-1.3-or-later (LICENSE-docs). Visual elements: CC0-1.0 (LICENSE-cc0).
• Future phase (triggered automatically on the earlier of one year after the first public release or the first major version bump) — Software: MIT OR Apache-2.0 (dual, user-elected; see LICENSE-mit and LICENSE-apache). Documentation and visual elements: CC-BY-SA-4.0-or-later (LICENSE-cc-by-sa).

By submitting a contribution, you accept the terms of CLA.md, which grants the Project the rights it needs to execute the transition described above. The transition only applies to contributions submitted on or after the trigger date; contributions made before the trigger date remain under the license that was in effect at the time of submission.

For media file handling, sanitization requirements, REUSE compliance, and the official license texts, see Repository-Policy.md and the LICENSE-* files in the repository root.

Acknowledgments

Lingchu Bot stands on a lot of good open-source shoulders. Thanks especially to these upstream projects and communities:

• Bot runtime and adapter ecosystem: NoneBot2, nonebot-adapter-onebot, nonebot-plugin-alconna, nonebot-plugin-localstore, nonebot-plugin-orm, nonebot-plugin-apscheduler, nonebot-plugin-htmlkit, and nonebot-plugin-docs.
• Python configuration, storage, and service utilities: aiofiles, rtoml, Babel, Jinja, and packaging.
• Documentation and frontend stack: Astro, Starlight, React, Mermaid, Twoslash, and Tailwind CSS.
• Engineering, testing, and repository workflow: uv, pnpm, Turborepo, Ruff, Pyright, ty, pytest, Vitest, Playwright, markdownlint-cli2, Prettier, ESLint, Husky, Gitmoji, gitnexus, and FOSSA.

For complete dependency lists, please refer to pyproject.toml, package.json, apps/docs/package.json, and uv.lock.

License compliance