YuKiKo Bot

基于 NoneBot2 + OneBot V11 的智能 QQ 机器人

一个功能丰富的 AI 驱动 QQ 群聊/私聊机器人，支持多模型接入、Agent 工具调用、 音乐点播、图片生成、视频解析、Web 管理面板等。

快速开始 · 功能特性 · 配置说明 · 文档 · English

---

✨ 功能特性

类别	功能
AI 对话	多模型（OpenAI / Claude / DeepSeek / Gemini / 通义千问 / Moonshot 等），上下文记忆，知识库自动学习
Agent 系统	50+ 内置工具，自动推理与多步工具调用，置信度路由
音乐点播	多平台搜索播放，VIP 歌曲解锁，歌手一致性保护，B站音频回退
搜索引擎	联网搜索，网页智能摘要，结构化信息提取
视频解析	B站 / 抖音 / 快手 / AcFun 视频下载与内容分析
图片生成	DALL-E 等多模型，自动 NSFW 过滤
Web 管理面板	React 前端，配置热更新，日志实时查看，数据库管理，在线聊天测试
插件系统	热插拔，独立配置文件，WebUI 可视化管理
安全机制	内容过滤，权限三级分层，密钥加密存储，Self-check 防误回复

📋 环境要求

依赖	版本	说明
Python	3.10+	推荐 3.11 / 3.12
Node.js	18+	构建 WebUI 用
ffmpeg	最新	音视频处理（Linux 安装脚本自动安装）
OneBot V11 服务	—	推荐 NapCat

Windows 用户如果没有 Python / Node.js，请先安装：

• Python: https://www.python.org/downloads/ （安装时勾选 "Add to PATH"）
• Node.js: https://nodejs.org/ （LTS 版本即可）
• ffmpeg: https://www.gyan.dev/ffmpeg/builds/ （下载后加入系统 PATH）

🚀 快速开始

方式一：Linux 一键部署（推荐）

无需手动 clone，一条命令搞定：

bash <(curl -fsSL https://raw.githubusercontent.com/dwgx/YuKiKo/main/bootstrap.sh)

脚本自动完成：系统依赖 → Python 虚拟环境 → WebUI 构建 → systemd 服务注册。

非交互模式（适合自动化 / CI）

bash <(curl -fsSL https://raw.githubusercontent.com/dwgx/YuKiKo/main/bootstrap.sh) \
  -- --non-interactive --host 0.0.0.0 --port 8081 --service-name yukiko --open-firewall

已 clone 仓库？用本地安装脚本

git clone https://github.com/dwgx/YuKiKo.git && cd YuKiKo
bash install.sh

网络慢？使用国内镜像 / 本地缓存加速

bash install.sh \
  --pip-index-url https://pypi.tuna.tsinghua.edu.cn/simple \
  --npm-registry https://registry.npmmirror.com \
  --pip-cache-dir ~/.cache/yukiko/pip \
  --npm-cache-dir ~/.cache/yukiko/npm \
  --use-uv

也可以直接设置环境变量：YUKIKO_PIP_INDEX_URL、YUKIKO_NPM_REGISTRY、YUKIKO_PIP_CACHE_DIR、YUKIKO_NPM_CACHE_DIR、YUKIKO_USE_UV。

方式二：Windows 手动部署

# 1. 克隆项目
git clone https://github.com/dwgx/YuKiKo.git
cd YuKiKo

# 2. 复制环境变量文件
Copy-Item .env.example .env

# 3. 编辑 .env，至少填写：
#    ONEBOT_ACCESS_TOKEN=你的NapCat令牌
#    WEBUI_TOKEN=随机字符串

# 4. 一键启动（自动创建虚拟环境 + 安装依赖）
.\start.bat

首次启动后访问 http://127.0.0.1:8081/webui/setup 完成初始配置。

方式三：macOS / Linux 手动部署

# 1. 克隆项目
git clone https://github.com/dwgx/YuKiKo.git && cd YuKiKo

# 2. 复制环境变量文件并编辑
cp .env.example .env
# 编辑 .env，填写 ONEBOT_ACCESS_TOKEN 和 WEBUI_TOKEN

# 3. 一键启动
bash start.sh

方式四：手动完全控制

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

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

# 构建 WebUI（可选但推荐）
cd webui && npm install && npm run build && cd ..

# 启动
python main.py

🔗 连接 NapCat（QQ 适配器）

YuKiKo 通过 NapCat 的 OneBot V11 协议接入 QQ。

NapCat 侧配置：

1. 连接模式选择 反向 WebSocket (Reverse WS)
2. WS 上报地址填写：ws://<YuKiKo地址>:<端口>/onebot/v11/ws
3. Access Token 与 .env 中的 ONEBOT_ACCESS_TOKEN 保持一致

# 同机部署示例
ws://127.0.0.1:8081/onebot/v11/ws

# 跨机器示例（填 YuKiKo 所在机器的 IP）
ws://192.168.1.50:8081/onebot/v11/ws

Linux 安装脚本会自动检测并提示安装 NapCat。手动安装：

curl -o napcat.sh https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh && bash napcat.sh

进阶运维与本次更新说明：docs/zh-TW/NAPCAT_LINUX_WEBUI_UPDATE.md

⚙️ 配置说明

YuKiKo 采用三层配置体系：

层级	文件	用途
环境变量	.env	端口、密钥、API Key 等敏感信息
全局配置	config/config.yml	机器人行为、模型参数、路由策略等
插件配置	plugins/config/*.yml	每个插件独立一份配置文件

.env 关键字段

HOST=0.0.0.0                              # 监听地址
PORT=8081                                  # 监听端口
ONEBOT_ACCESS_TOKEN=your_napcat_token      # NapCat 鉴权令牌
WEBUI_TOKEN=your_random_string             # WebUI 管理面板令牌
SKIAPI_KEY=                                # 默认 AI 模型 API Key
OPENAI_API_KEY=                            # OpenAI（按需）
DEEPSEEK_API_KEY=                          # DeepSeek（按需）
ANTHROPIC_API_KEY=                         # Claude（按需）

完整字段参考 .env.example。

config.yml 主要分组

首次启动时会从模板自动生成，也可通过 WebUI 在线编辑。

分组	说明
bot	机器人名称、昵称、回复形式、分段策略
api	模型供应商、模型名、base_url、温度、token 上限
agent	Agent 步数上限、超时、工具调用策略
routing	路由置信度阈值、路由模式
queue	并发控制、智能中断、消息队列策略
music	音源配置、解锁源、歌手保护
search	网页抓取、视频解析、视觉分析
safety	内容安全等级

🖥️ WebUI 管理面板

启动后访问 http://<HOST>:<PORT>/webui/login，使用 .env 中的 WEBUI_TOKEN 登录。

页面	功能
Dashboard	系统状态、版本检查、一键更新、并发监控
Config	YAML 在线编辑器，支持热更新
Plugins	插件列表、启用/禁用、独立配置编辑
Prompts	系统提示词编辑
Chat	在线聊天测试
Memory	记忆管理与搜索
Database	数据库导出/导入/浏览
Logs	实时日志查看

🔌 插件系统

插件放在 plugins/ 目录下，配置文件在 plugins/config/ 中。

内置插件：

• NewAPI — 支付/充值集成
• Wayback — Internet Archive 网页快照查询
• ConnectCLI — 外部 CLI 工具接入

开发自定义插件请参考 plugins/example_plugin.py 和 插件开发指南。

🛠️ 运维命令

安装脚本会注册 yukiko CLI 工具（仅 Linux）：

yukiko status              # 查看服务状态
yukiko logs --lines 200    # 查看最近日志
yukiko doctor              # 部署健康自检
yukiko doctor --strict     # 严格验收（有 warning 也返回失败）
yukiko napcat-status       # NapCat 安装检测
yukiko backup              # 备份 env/config/storage
yukiko restore --file <backup.tar.gz> --yes
yukiko update --fast       # 快速更新（按变更决定是否装依赖/构建）
yukiko restart             # 重启服务
yukiko stop                # 停止服务
yukiko start               # 启动服务
yukiko update --check-only # 检查更新
yukiko update --restart    # 更新并重启
yukiko uninstall           # 卸载

Linux 安装后默认会执行严格部署后检查（服务活性 + WebUI 健康 + doctor --strict）。 如需跳过可用：bash install.sh --skip-post-check，也可用 --post-check-timeout 30 调整超时。

一键卸载 / 完整清理

# Linux（默认完整清理 + 卸载服务/NapCat + 卸载前自动备份）
bash uninstall.sh --yes

# Linux：只卸载服务和 CLI，保留数据
yukiko uninstall --keep-napcat --keep-cli --yes

# Windows（默认完整清理 + 卸载前自动备份）
.\uninstall.bat --yes

# macOS（默认完整清理 + 卸载前自动备份）
bash uninstall.sh --yes

如需更细粒度控制，可组合使用：--purge-runtime、--purge-state、--purge-env、--purge-data、--backup-dir、--backup-name、--no-backup。

项目接管自检（推荐）

当你准备大改 Prompt / 路由 / Agent / API 策略时，先跑一遍：

python scripts/project_takeover_selfcheck.py

该脚本会执行：

• scripts/agent_deep_selfcheck.py
• 关键回归测试（本地关键词回归、群聊上下文回归、记忆集成回归、模型降级回归）

接管改造说明见：docs/zh-CN/TAKEOVER_IMPROVEMENT_PLAN.md

🔍 常见问题

报 ModuleNotFoundError

虚拟环境依赖不完整，运行：

python scripts/deploy.py

WebUI 打不开 / 503

前端未构建。运行：

cd webui && npm install && npm run build

或使用脚本：bash build-webui.sh（Linux）/ build-webui.bat（Windows）

NapCat 连不上

1. 确认 .env 中 ONEBOT_ACCESS_TOKEN 与 NapCat 侧完全一致
2. 确认 NapCat 连接模式为"反向 WebSocket"
3. 确认 WS 地址格式：ws://<IP>:<PORT>/onebot/v11/ws
4. 跨机器部署时确认防火墙已放行端口

Windows 下 ffmpeg 找不到

1. 从 https://www.gyan.dev/ffmpeg/builds/ 下载 ffmpeg
2. 解压后将 bin 目录加入系统 PATH
3. 重启终端，运行 ffmpeg -version 验证

插件配置不生效

YuKiKo 支持两种插件配置位置：

• plugins/config/<plugin>.yml（推荐，独立管理）
• config/plugins.yml（统一管理）

在 WebUI 插件页保存后会自动写回正确位置。如果手动编辑，请确认文件路径正确。

📁 项目结构

YuKiKo/
├── main.py              # 入口
├── app.py               # OneBot 事件处理
├── core/                # 核心引擎（消息处理、路由、Agent、队列、WebUI 后端）
├── plugins/             # 插件 + 插件配置模板
│   └── config/          # 插件独立配置文件
├── config/              # 全局配置
│   └── templates/       # 配置模板（master.template.yml）
├── services/            # 模型客户端 / 外部服务封装
├── webui/               # React + Vite 管理面板前端
├── scripts/             # 部署 / 构建脚本
├── utils/               # 工具函数（文本处理、媒体、过滤器）
├── storage/             # 运行时数据（缓存、数据库）
├── deploy/              # systemd 服务模板
├── tests/               # 测试
├── install.sh           # Linux 交互式安装脚本
├── bootstrap.sh         # 远程一键部署脚本
├── start.sh / start.bat # 一键启动脚本
├── uninstall.sh / uninstall.bat # 一键卸载脚本
└── .env.example         # 环境变量模板

📖 文档

文档	说明
简体中文部署指南	完整部署、配置、运行方式
简体中文架构说明	内部设计原理
English Guide	Deployment & configuration
English Architecture	Internal design notes
繁體中文指南	部署與設定
NapCat/Linux/WebUI 更新說明	NapCat 深度整合、運維命令、部署加速
插件开发指南	插件配置与开发

📄 License

MIT