NekoBot

Appearance

NekoBot多频道 AI 角色扮演

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

🚀 快速开始
📖 命令文档
💻 开发指南
NekoBot
🎭

实时情感引擎

独立角色运行时，支持情绪惯性、六维关系系统、动态提示词栈、ReactionPlan反应计划

🌐

多频道支持

支持 QQ、Web、Telegram 等多频道接入，统一 AI 内核，频道适配层分离

💬

AI 聊天

基于大模型的智能对话，支持工具调用、多轮对话、上下文管理、流式回复

🧠

记忆系统

用户个性化记忆，知识库 RAG 智能问答，支持私有和共享工作区

🪝

Hook 事件驱动

对话生命周期事件系统，27 种事件类型，条件触发自动注入提示词、修改状态、写入记忆

🎬

剧情模式

分支剧情图系统，AI 自动生成选择项，支持回溯、Mermaid 可视化、记忆与世界书桥接

👥

群聊会话

多角色群聊，5 种发言策略，角色间四维关系系统，第三人称旁白叙述

🎛️

Web 后台

完整的 Web 管理界面，支持会话管理、AI 配置、模型管理、日志监控

项目简介 ​

NekoBot是一个多频道 AI 角色扮演系统，采用"统一 AI 内核 + 频道适配层"的架构设计：

  • 实时情感引擎 - 独立角色运行时，支持情绪惯性、6 回合 AI 状态评估、关系系统、动态提示词栈、ReactionPlan
  • 拥有AI管道，支持多频道接入 - 通过统一的 ChatRequest / ChatResponse 处理链路
  • 支持会话级与共享工作区 - 文件创建、修改、删除、发送，支持 diff 预览
  • 支持工具调用与多轮对话 - 可继续执行中断的工具调用任务
  • 提供 Web 仪表盘 - AI 配置中心、工作流、日志与调试界面
  • 支持多模型配置 - 保存多个模型配置，运行时切换

架构概览 ​

Ncatbot-comic-QQbot/
├── bot.py                 # 入口文件，启动 QQ 服务与 Web 服务
├── nbot/                  # 核心模块包
│   ├── channels/          # 频道适配层（QQ / Web / Telegram）
│   ├── core/              # 统一 AI 核心
│   │   ├── agent_service.py   # AI 处理入口
│   │   ├── chat_models.py     # ChatRequest / ChatResponse
│   │   ├── session_store.py   # 会话读写
│   │   └── model_adapter.py   # 模型适配层
│   ├── character/         # 实时情感引擎（新增）
│   │   ├── models.py          # 数据模型
│   │   ├── runtime.py         # 运行时引擎
│   │   ├── prompt_stack.py    # 动态提示词栈
│   │   ├── planner.py         # 反应计划生成器
│   │   └── state_machine.py   # 状态机
│   ├── plugins/           # 插件系统
│   ├── services/          # AI、工具、聊天服务
│   └── web/               # Web 后台与前端
├── data/                  # 运行数据
│   ├── qq/               # QQ 相关数据
│   ├── character/        # 角色运行时数据
│   ├── web/              # Web 会话、模型配置
│   └── workspaces/       # 私有 / 共享工作区
└── resources/            # 静态资源

快速启动 ​

bash
# 克隆项目
git clone https://github.com/asukaneko/nekobot.git
cd nekobot

# 安装依赖
pip install -r requirements.txt

# 配置环境变量（复制 .env.example 为 .env 并编辑）
cp .env.example .env

# 启动（QQ + Web）
python bot.py

# 仅启动 Web
python bot.py --only-web

# 仅启动 QQ
python bot.py --no-web

# CLI + Web 模式
python bot.py --cli-and-web

核心特性 ​

实时情感引擎 ​

NekoBot 提供独立的角色运行时引擎，让角色具备"活人感"：

  • 动态提示词栈（PromptStack） - 支持多模块动态注册提示词注入项，按优先级合成，不污染历史消息
  • 角色运行时状态 - 每个会话/用户独立的角色状态（心情、情绪强度、精力、场景）
  • 关系系统 - 六维关系模型：好感、信任、熟悉、依赖、安全感、嫉妒
  • 信号分析器 - 分析用户输入中的情绪信号（夸奖、拒绝、亲密、敌意、关心等）
  • 反应计划（ReactionPlan） - 每轮动态生成回复策略，控制情绪表达和回复风格
  • 状态机 - 情绪惯性更新，关系值平滑变化，避免暴涨暴跌
  • 自动状态评估 - 每 6 回合调用当前 AI 汇总近期互动，调整情绪强度、精力和六维关系

角色扮演系统 ​

  • 可视化角色卡编辑器
  • 角色立绘支持本地上传或 AI 生成
  • 角色卡导入/导出功能
  • AI 辅助创建角色
  • 多角色切换，每个会话可指定不同角色

记忆系统 ​

  • 每个角色拥有独立的记忆空间
  • 支持长期记忆和短期记忆
  • 知识库 RAG 智能问答
  • 工具调用自动关联当前角色

技术栈 ​

  • Python 3.11+ - 主要开发语言
  • NapCat + ncatbot - QQ 协议接入
  • Flask + Socket.IO - Web 服务
  • Vue.js - 前端界面
  • RAG - 知识库检索