Skillget

nekobot

mcp
Security Audit
Pass
Health Pass
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 15 GitHub stars
Code Pass
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

一个面向Web的多频道 AI 角色扮演项目，集成角色卡系统、聊天、工作区、工具调用、知识库、记忆、工作流与可视化管理后台。

README.md

NekoBot

cover

Python
License
Web
QQ
MCP

面向 Web 的多渠道 AI 角色扮演系统，包含Web、QQ、CLI、Telegram、Feishu等频道。

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/：

MCP (Model Context Protocol)

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

支持的能力

类型 说明
Tools 查询状态、查询事件链路、查询队列、模拟消息、触发任务、重试死信、节点管理
Resources Gateway 状态、统计数据、能力清单、队列状态、节点列表
Prompts 故障诊断、频道测试、节点健康检查

快速开始

# 启动 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

Tool 说明 风险
gateway_get_status Gateway 健康状态 只读
gateway_get_stats 事件/投递/去重统计 只读
gateway_query_trace 查询 trace 完整链路 只读
gateway_query_events 按条件查询事件 只读
gateway_query_deliveries 查询投递记录 只读
gateway_get_queue_stats 队列状态 只读
gateway_list_nodes 节点列表 只读
gateway_get_node 节点详情 只读
gateway_receive_message 模拟频道消息 操作
gateway_send_message 发送真实消息 高危
gateway_submit_internal_task 触发内部任务 操作
gateway_retry_dead_letter 重试死信 高危
gateway_register_node 注册节点 操作

查看详细文档：docs/MCP

Security Notes

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

License

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

Reviews (0)

No results found