nekobot

# NekoBot  <div align="center">      A web-oriented multi-channel AI role-playing system, including Web, QQ, CLI, Telegram, Feishu and other channels. </div> ## Overview NekoBot is an AI system for role-playing and long-term interaction scenarios. The project adopts a unified AI kernel and a separate architecture of channel adaptation layer, providing a complete web management backend, role runtime, memory system, tool calling and workspace capabilities. Its core goal is not simply to provide a "chat interface", but to provide a sustainable, configurable, observable, scalable role-based intelligent body infrastructure. ## Core Capabilities - Multi-channel access: Support QQ, Web, CLI, Telegram, Feishu, sharing a unified `ChatRequest / ChatResponse` processing link. - Role runtime: Built-in real-time emotional engine, six-dimensional relationship model, dynamic PromptStack, automatic state assessment and role memory. - Web console: Provide session management, role management, model configuration, workflow, knowledge base, memory, log and debugging interface. - Tools and workspace: Support tool calling, file reading and writing, shared/private workspace, file change preview and task execution. - Model adaptation: Compatible with OpenAI Chat Completions/Responses, Anthropic, Gemini interface, can access Deepseek, GLM, Kimi, Mimo and other compatible services. - Plug-in and skill: Support expanding capabilities through plug-in and skill system without damaging the core processing flow. - MCP interface: Expose Gateway capabilities through Model Context Protocol, support Claude Code, Cursor, ChatGPT Agent and other AI intelligent bodies to call directly. - Voice capability: Built-in pluggable TTS/STT adapter architecture, TTS support OpenAI compatible, Xiaomi MiMo, Douyu (Volcano Engine) and other providers, STT support OpenAI compatible, Xiaomi MiMo and local faster-whisper offline recognition. ## Architecture The project is organized around the principle of "unified AI kernel + multi-channel adaptation": ```text bot.py └── nbot/ ├── commands.py # QQ command handlers, BotClient init ├── core/ # Unified AI pipeline │ ├── chat_models.py # ChatRequest / ChatResponse │ ├── agent_service.py # Main AI entry │ ├── ai_pipeline.py # Pre-process -> chat -> post-process │ ├── session_store.py # Unified session state │ ├── model_adapter.py # Cross-provider model adapter │ ├── workspace.py # Per-session file workspace │ ├── auto_memory.py # Automatic memory extraction │ └── workflow.py # Workflow executor ├── character/ # Affective runtime and relationship model ├── channels/ # QQ, Web, Telegram, Feishu adapters ├── services/ # AI client, chat service, tools, TTS/STT ├── plugins/ # Plugin and skill system ├── hooks/ # Hook Runtime (event-driven conversation hooks) ├── gateway/ # Message bus, routing, delivery, dedupe │ └── facade.py # Gateway service facade for MCP ├── web/ # Flask blueprints, Socket.IO events, dashboard ├── mcp/ # MCP Server (AI Agent interface) │ ├── server.py # FastMCP entry point │ ├── tools/ # MCP Tools │ ├── resources/ # MCP Resources │ └── prompts/ # MCP Prompts └── cli/ # Terminal UI ``` The request flow is as follows: ```text Channel Adapter -> ChatRequest -> Agent Service / AI Pipeline -> Character Runtime (before_turn / after_turn) -> Model Adapter / AI Client -> ChatResponse -> Channel Adapter ``` ## Runtime Features ### Character Runtime `nbot/character/` provides role runtime, used to convert "role setting" into continuous and consistent dialogue behavior: - `PromptStack`: Dynamically assemble prompt words according to priority, rather than polluting all states into historical messages. - `StateMachine`: Control emotional inertia and relationship smooth changes, avoid drastic distortion caused by single-wheel input. - `AutoState`: Regularly summarize recent interactions, automatically adjust emotional intensity, energy and six-dimensional relationship values. - `Memory`: Support long-term and short-term memory isolated by role and user. - `ReactionPlan`: Generate style and behavior strategy before each reply, constrain role output. ### Workspace and Tools The system supports private and shared workspaces: - Private workspace binds to the current session. - Shared workspace can be accessed by multiple sessions. - File creation, modification, deletion, transmission and difference preview can be managed through the web interface. - Tool system supports triggering file, search, execution and other capabilities in dialogue. ### Web Dashboard The web backend covers daily operation and maintenance needs: - Session and chat management - Role card creation, editing, import and export - AI model configuration and switching - Memory, knowledge base, skill, tool management - Workflow and timing task - Token statistics, log, debugging and running status viewing ## Requirements - Python 3.10+ - NapCatQQ - ncatbot 3.8.5 - Available OpenAI-compatible API service ## Installation ```bash git clone https://github.com/asukaneko/nekobot.git cd nekobot ``` ```bash # Configure virtual environment (optional) python -m venv venv source venv/bin/activate # windows: venv\Scripts\activate.bat python -m pip install -r requirements.txt ``` Copy environment variable template and fill in necessary configuration: ```bash cp .env.example .env ``` At least suggest configuring: ```env WEB_PASSWORD=your_web_password ``` If you need to enable QQ Bot, you also need to supplement: ```env BOT_UIN=your_qq_number ROOT=your_admin_qq_number WS_URI=ws://your_napcat_host:port TOKEN=your_napcat_token ``` Minimum example of AI service: ```env API_KEY=your_api_key BASE_URL=https://your-openai-compatible-endpoint/v1 MODEL=your_model_name ``` But you can still configure your model through the web interface. ## Running ```bash # QQ + Web python bot.py # Web only python bot.py --only-web # Web only on custom host/port python bot.py --only-web --web-host 0.0.0.0 --web-port 5000 # CLI only python bot.py --cli # CLI + Web python bot.py --cli-and-web # QQ only python bot.py --no-web ``` By default: - If QQ-related configuration is detected, start `QQ + Web`. - If no QQ configuration is detected, the project can run only in Web mode. ## Development Notes - Target Python version is `3.10`. - Code style uses Ruff, line width 100, double quotes, space indentation. - `nbot/core/` should not depend on channel layer modules. - All new channels should be accessed through `BaseChannelAdapter`, not directly calling the model. - Role logic should be hooked into the unified pipeline through `before_turn()` / `after_turn()`. Common inspection commands: ```bash ruff check . python -m compileall -q bot.py nbot tools python -m pytest -q ``` CI mainly executes: 1. `ruff check . --select E9,F63,F7,F82` 2. `python -m compileall -q bot.py nbot tools` 3. `python -m pip install -r requirements.txt` 4. `python -m pytest -q` ## Documentation More detailed usage and development documents are located in `docs/`: - Quick start: [docs/docs/guide/quick-start.md](docs/docs/guide/quick-start.md) - Command description: [docs/docs/guide/commands.md](docs/docs/guide/commands.md) - Channel access: [docs/docs/guide/channels.md](docs/docs/guide/channels.md) - Voice synthesis (TTS): [docs/docs/guide/nbot/services/tts.md](docs/docs/guide/nbot/services/tts.md) - Voice recognition (STT): [docs/docs/guide/nbot/services/stt.md](docs/docs/guide/nbot/services/stt.md) - Contribution guide: [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) - Update record: [docs/CHANGELOG.md](docs/CHANGELOG.md) ## MCP (Model Context Protocol) NekoBot has a built-in MCP Server, which can expose the Gateway's message, event, queue, node and other capabilities to AI intelligent bodies in a standard MCP protocol. ### Supported capabilities | Type | Description | |------|------| | Tools | Query status, query event link, query queue, simulate message, trigger task, retry dead letter, node management | | Resources | Gateway status, statistical data, capability list, queue status, node list | | Prompts | Fault diagnosis, channel test, node health check | ### Quick start ```bash # Start Bot + MCP python bot.py --mcp ``` ### Claude Code configuration Create `.mcp.json` in the project root directory: ```json { "mcpServers": { "nekobot": { "command": "python", "args": ["bot.py", "--mcp-only"], "env": { "PYTHONPATH": "." } } } } ``` > **Tip**: `bot.py` is a relative path and will be found from the current working directory. If Claude Code is not started in the project root directory, you need to specify the project path through `cwd`, or change `args` to an absolute path. ### Cursor configuration Create `.cursor/mcp.json` in the project root directory: ```json { "mcpServers": { "nekobot": { "command": "python", "args": ["bot.py", "--mcp-only"], "env": { "PYTHONPATH": "." } } } } ``` ### MCP configuration items Configure MCP behavior in `config.ini`: ```ini [mcp] ; Whether to allow MCP to send real messages (high risk, default off) send_message_enabled = false ; Whether retry dead letter requires confirmation retry_require_confirmation = true ; Audit log audit_enabled = true ; Grant MCP all permissions (local use suggests opening) admin = true ; Transmission mode: stdio (local) | streamable-http (remote) transport = stdio ; Server configuration (streamable-http mode) host = 127.0.0.1 port = 5001 ; Remote connection URL (--mcp-connect use) connect_url = http://127.0.0.1:5001/mcp [gateway] ; Gateway persistent storage (enable can query historical events) storage_enabled = true data_dir = data/web ``` ### Remote connection MCP Server supports `streamable-http` remote access: ```bash # Server: configure transport = streamable-http in config.ini, then start python bot.py --mcp-only # Client: connect to remote MCP Server python bot.py --mcp-connect http://192.168.1.100:5001/mcp ``` Claude Code remote connection configuration (`.mcp.json`): ```json { "mcpServers": { "nekobot": { "url": "http://192.168.1.100:5001/mcp" } } } ``` ### Available Tools | Tool | Description | Risk | |------|------|------| | `gateway_get_status` | Gateway health status | Read-only | | `gateway_get_stats` | Event/delivery/deduplication statistics | Read-only | | `gateway_query_trace` | Query trace complete link | Read-only | | `gateway_query_events` | Query events by condition | Read-only | | `gateway_query_deliveries` | Query delivery records | Read-only | | `gateway_get_queue_stats` | Queue status | Read-only | | `gateway_list_nodes` | Node list | Read-only | | `gateway_get_node` | Node details | Read-only | | `gateway_receive_message` | Simulate channel message | Operation | | `gateway_send_message` | Send real message | High risk | | `gateway_submit_internal_task` | Trigger internal task | Operation | | `gateway_retry_dead_letter` | Retry dead letter | High risk | | `gateway_register_node` | Register node | Operation | View detailed documentation: [docs/MCP](./docs/docs/guide/nbot/mcp/index.md) ## Security Notes - Do not expose the web backend directly to the public network without additional protection. - Please set valid and independent keys for `WEB_PASSWORD`, API Key, and NapCat Token. - Do not submit `.env`, real credentials or runtime sensitive data to the warehouse. - Do not manually modify persistent files under `data/character/` during robot operation. ## License This project is released under the MIT License, see [LICENSE](LICENSE).