NekoBot

Overview

NekoBot 是一个面向角色扮演与长期互动场景的 AI 系统。项目采用统一 AI 内核与频道适配层分离的架构，提供完整的 Web 管理后台、角色运行时、记忆系统、工具调用与工作区能力。

它的核心目标不是单纯提供“聊天接口”，而是提供一套可持续运行、可配置、可观测、可扩展的角色型智能体基础设施。

Core Capabilities

• 多渠道接入：支持 QQ、Web、CLI、Telegram、Feishu，共用统一的 ChatRequest / ChatResponse 处理链路。
• 角色运行时：内置实时情感引擎、六维关系模型、动态 PromptStack、自动状态评估与角色记忆。
• Web 控制台：提供会话管理、角色管理、模型配置、工作流、知识库、记忆、日志与调试界面。
• 工具与工作区：支持工具调用、文件读写、共享/私有工作区、文件变更预览与任务执行。
• 模型适配：兼容 OpenAI Chat Completions/Responses , Anthropic , Gemini接口，可接入 Deepseek、GLM、Kimi、Mimo及其他兼容服务。
• 插件与技能：支持通过插件与技能系统扩展能力，而不破坏核心处理流程。
• MCP 接口：通过 Model Context Protocol 暴露 Gateway 能力，支持 Claude Code、Cursor、ChatGPT Agent 等 AI 智能体直接调用。
• 语音能力：内置可插拔 TTS/STT 适配器架构，TTS 支持 OpenAI 兼容、小米 MiMo、豆包（火山引擎）等提供商，STT 支持 OpenAI 兼容、小米 MiMo 及本地 faster-whisper 离线识别。

Architecture

项目围绕“统一 AI 内核 + 多渠道适配”的原则组织：

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

请求流如下：

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/ 提供角色运行时，用于把“角色设定”转化为持续一致的对话行为：

• PromptStack：按优先级动态拼装提示词，而不是把所有状态污染进历史消息。
• StateMachine：控制情绪惯性与关系平滑变化，避免单轮输入导致剧烈失真。
• AutoState：定期总结近期互动，自动调整情绪强度、精力与六维关系值。
• Memory：支持按角色、按用户隔离的长期与短期记忆。
• ReactionPlan：在每轮回复前生成风格与行为策略，约束角色输出。

Workspace and Tools

系统支持私有工作区与共享工作区：

• 私有工作区绑定当前会话。
• 共享工作区可被多个会话访问。
• 文件创建、修改、删除、传输与差异预览可通过 Web 界面管理。
• 工具系统支持在对话中触发文件、搜索、执行等能力。

Web Dashboard

Web 后台覆盖日常运维与调试需求：

• 会话与聊天管理
• 角色卡创建、编辑、导入、导出
• AI 模型配置与切换
• 记忆、知识库、技能、工具管理
• 工作流与定时任务
• Token 统计、日志、调试与运行状态查看

Requirements

• Python 3.10+
• NapCatQQ
• ncatbot 3.8.5
• 可用的 OpenAI-compatible API 服务

说明：

• .env 是首选配置来源。
• config.ini 仍作为 QQ 连接参数的兼容回退。
• 项目默认使用 Flask + Flask-SocketIO + Eventlet 提供 Web 服务。

Installation

git clone https://github.com/asukaneko/nekobot.git
cd nekobot

#配置虚拟环境（可选）
python -m venv venv
source venv/bin/activate
# windows: venv\Scripts\activate.bat
python -m pip install -r requirements.txt

复制环境变量模板并填写必要配置：

cp .env.example .env

至少建议先配置：

WEB_PASSWORD=your_web_password

如需启用 QQ Bot，还需要补充：

BOT_UIN=your_qq_number
ROOT=your_admin_qq_number
WS_URI=ws://your_napcat_host:port
TOKEN=your_napcat_token

AI 服务的最小示例：

API_KEY=your_api_key
BASE_URL=https://your-openai-compatible-endpoint/v1
MODEL=your_model_name

但你仍然可以通过web界面来配置你的模型

Running

# 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

默认情况下：

• 若检测到 QQ 相关配置，启动 QQ + Web。
• 若未检测到 QQ 配置，项目可仅以 Web 模式运行。

Development Notes

• 目标 Python 版本为 3.10。
• 代码风格使用 Ruff，行宽 100，双引号，空格缩进。
• nbot/core/ 不应依赖频道层模块。
• 所有新频道都应通过 BaseChannelAdapter 接入，而不是直接调用模型。
• 角色逻辑应通过 before_turn() / after_turn() 挂入统一流水线。

常用检查命令：

ruff check .
python -m compileall -q bot.py nbot tools
python -m pytest -q

CI 主要执行：

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

更详细的使用与开发文档位于 docs/：

• 快速开始：docs/docs/guide/quick-start.md
• 命令说明：docs/docs/guide/commands.md
• 频道接入：docs/docs/guide/channels.md
• 语音合成 (TTS)：docs/docs/guide/nbot/services/tts.md
• 语音识别 (STT)：docs/docs/guide/nbot/services/stt.md
• 贡献指南：docs/CONTRIBUTING.md
• 更新记录：docs/CHANGELOG.md

MCP (Model Context Protocol)

NekoBot 内置 MCP Server，可以将 Gateway 的消息、事件、队列、节点等能力以标准 MCP 协议暴露给 AI 智能体。

支持的能力

快速开始

# 启动 Bot + MCP
python bot.py --mcp

Claude Code 配置

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "nekobot": {
      "command": "python",
      "args": ["bot.py", "--mcp-only"],
      "env": {
        "PYTHONPATH": "."
      }
    }
  }
}

提示：bot.py 是相对路径，会从当前工作目录查找。如果 Claude Code 不在项目根目录启动，需要通过 cwd 指定项目路径，或将 args 改为绝对路径。

Cursor 配置

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "nekobot": {
      "command": "python",
      "args": ["bot.py", "--mcp-only"],
      "env": {
        "PYTHONPATH": "."
      }
    }
  }
}

MCP 配置项

在 config.ini 中配置 MCP 行为：

[mcp]
; 是否允许 MCP 发送真实消息（高危，默认关闭）
send_message_enabled = false
; 重试死信是否需要确认
retry_require_confirmation = true
; 审计日志
audit_enabled = true
; 授予 MCP 全部权限（本地使用建议开启）
admin = true
; 传输模式: stdio (本地) | streamable-http (远程)
transport = stdio
; 服务端配置（streamable-http 模式）
host = 127.0.0.1
port = 5001
; 远程连接 URL（--mcp-connect 使用）
connect_url = http://127.0.0.1:5001/mcp

[gateway]
; Gateway 持久化存储（启用后可查询历史事件）
storage_enabled = true
data_dir = data/web

远程连接

MCP Server 支持 streamable-http 远程访问：

# 服务端：config.ini 设置 transport = streamable-http，然后启动
python bot.py --mcp-only

# 客户端：连接远程 MCP Server
python bot.py --mcp-connect http://192.168.1.100:5001/mcp

Claude Code 远程连接配置（.mcp.json）：

{
  "mcpServers": {
    "nekobot": {
      "url": "http://192.168.1.100:5001/mcp"
    }
  }
}

可用 Tools

查看详细文档：docs/MCP

Security Notes

• 不要将 Web 后台直接暴露到公网且不做额外防护。
• 请为 WEB_PASSWORD、API Key、NapCat Token 设置有效且独立的密钥。
• 不要提交 .env、真实凭据或运行时敏感数据到仓库。
• 机器人运行期间，不要手动修改 data/character/ 下的持久化文件。

License

本项目基于 MIT License 发布，详见 LICENSE。