dwgx@blog:~$dwgx
> cd ../posts

YuKiKo:自托管的 AI QQ bot

// created

YuKiKo 是个自托管的 AI QQ bot,能聊天、点歌、解析视频链接。底子是 NoneBot2 + OneBot V11,QQ 那头挂 NapCat 走反向 WS 接进来。

QQ 协议不碰,交给 NapCat 啃,YuKiKo 只认 OneBot V11。NapCat 配成反向 WS 上报到 ws://<地址>:<端口>/onebot/v11/ws,两边 access token 对上就通。协议层和逻辑层彻底解耦,NapCat 换实现或哪天挂了,这边一行不改。

模型没绑死一家,OpenAI、Claude、DeepSeek、Gemini、通义、Moonshot 都能接,谁便宜在线走谁。花心思的是路由,消息进来先判断该不该接、用哪个模型答,靠置信度阈值卡,省得群里随便一句就触发一次贵的推理。

Agent 系统是核心,内置几十个工具,模型自己多步推理连续调工具,不是问一句答一句。音乐点播踩坑最多,多平台搜索、VIP 解锁、防串歌手,实在搜不到回退 B站音频。视频解析支持 B站/抖音/快手/AcFun,下下来还能顺带分析内容。

配置拆三层,.env 放端口密钥这类敏感的,config/config.yml 管机器人行为和模型参数,插件各自一份 yml。密钥加密存,权限分三级,还加了个 self-check 防 bot 把自己的话当用户输入反复自答,这坑排了很久。

管理面板用 React 写,配置在线热更新、日志实时看、数据库导入导出,网页里直接跟 bot 对话测试。插件热插拔,丢进 plugins/ 配好独立 yml 就能用,面板可视化开关,内置 NewAPI、Wayback、ConnectCLI 几个。部署有 bootstrap 脚本,一条命令搞定:

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

系统依赖、Python 虚拟环境、WebUI 构建、systemd 注册一条龙,装完给个 yukiko CLI,status/logs/doctor/backup/update 这些运维命令都在里面,我自己天天敲。