YunzaiBot

定义

YunzaiBot是一个基于Node.js运行的开源QQ聊天机器人项目，社区通常称其为「云崽」^[1][5]。它本身不是单一功能的成品机器人，而是一套把机器人登录、消息接收与解析、命令分发和插件加载组织在一起的应用端框架，具体功能由加载的插件决定^[1]。项目文档说明其源码采用GPL-3.0许可证发布^[6]。

项目早期定位是原神QQ群助手，通过对接米游社接口获取游戏信息并以图片形式返回查询结果^[7]。仓库说明中写明该项目仅供学习交流，不允许用于商业用途或违法行为^[7]。

原理

框架的运行依赖两套外部组件：一是Node.js运行时，二是以Redis（或其兼容实现Valkey）承担的数据存储^[5]。部分需要渲染图片的功能还要借助Chrome或Chromium等浏览器内核完成页面截图^[8]。硬件门槛不高，Linux环境下推荐配置为2核CPU、2GB内存与20GB硬盘^[5]。

在结构上，核心模块负责机器人登录、消息接收解析，并通过统一的命令调度把消息分发给对应插件；配置文件集中存放于专用目录，用于设定登录信息、命令与插件参数^[1]。登录侧早期采用oicq库，后续分支改用icqq以规避客户端版本过低导致的登录失败^[4]。

插件机制是框架可扩展性的关键。框架启动时扫描plugins目录下所有.js文件并把符合规则的模块载入，插件因此分为单个js文件的「单js插件」和以文件夹形式发布的插件包两类^[2]。新增单js插件可被自动检测并重载，无需重启进程，即通常所说的热更新^[2][1]。

多协议分支进一步把消息收发与协议端解耦。TRSS-Yunzai通过适配器接入OneBotv11、ComWeChat、GSUIDCore、ICQQ、QQBot、QQ频道、微信、KOOK、Telegram、Discord、OPQBot、Lagrange等多种协议端，一个应用端可同时管理多个账号^[9]。这种设计让框架能脱离单一即时通讯平台运行^[9]。

发展历程

原版Yunzai-Bot由Le-niao创作。项目仓库的README在2022年8月由作者提交，其中将该版本标注为v3，定位是原神QQ群机器人^[7]。2022年间的多篇部署教程记录了这一时期的安装方式：准备Windows或Linux系统、Node.js与Redis，克隆仓库后安装依赖并以node app启动，首次运行按提示完成账号登录^[8][10]。同一时期，2.x版本已不再由作者维护^[11]。

此后项目出现分支化发展。喵喵（yoimiya-kokomi）在乐神版v3.0基础上改造出Miao-Yunzai，重整项目结构，以icqq替换停止更新的oicq，移除原版签到功能，并要求同时安装miao-plugin才能完整使用^[4][12]。喵喵同时维护了一份保持原版功能形态的Yunzai-Bot版本，两种分支各有侧重。

时雨（TimeRainStarSky）的TRSS-Yunzai则以Miao-Yunzai为基础，重点增加多账号与多协议端支持，并针对底层代码做了性能优化^[9][13]。社区还整理出插件索引库，汇总各版本框架与常用插件；索引中列出TRSS-Yunzai、Miao-Yunzai、Le-niao原版以及不含原神功能的精简版等多个条目^[3]。

应用

最常见的使用场景是游戏社群。框架通过对接米游社等第三方接口查询角色详情、抽卡记录与体力数据，并将结果渲染成图片回传群聊；配合面板类插件还可展示角色装备与伤害计算^[1]。

群组管理是另一类用途，包括自动欢迎新成员、定时发布公告、关键词回复以及禁言、违禁词、自助头衔等指令，用于协助群主和管理员维持秩序^[1]。

在娱乐与信息服务方面，插件可提供趣味对话、斗图、小游戏，以及接入大语言模型接口的对话能力；也有插件将在线报纸阅读、游戏数据查询等功能封装为命令^[1][3]。锅巴等插件还为部署者提供网页端后台，用于管理配置、更新插件与查看运行状态^[14]。

部署方式包括本地安装与容器化两种。本地部署需预先准备Node.js、Redis与Git，克隆仓库后安装依赖并首次登录；Docker镜像分精简版与扩展版，后者额外集成ffmpeg与Python环境，便于加载语音、图像处理及Python插件^[1][11]。

局限

框架本身不提供聊天平台账号，机器人接入QQ等平台依赖非官方协议实现，因此稳定性受平台策略制约。仓库与文档均注明严禁用于商业用途和非法行为，项目定位限于学习交流^[7]。

实际运行中常见的障碍是登录与发信受限。原版基于oicq的实现会遇到提示客户端版本过低的登录错误，这也是Miao-Yunzai改用icqq的原因之一^[15][4]。文档提到Miao-Yunzai采用ICQQ登录时需自行配置签名服务，缺少可用签名会直接影响登录与群消息发送^[13]。

对环境的要求也构成门槛。Redis强依赖POSIX/Linux特性，官方明确不支持Windows，Windows用户只能借助社区编译版本间接运行^[5]。文档另建议Node.js版本不低于v24.x，并提示v22.x可能导致部分插件加载超时，版本选择需要自行比对^[5]。

生态层面存在维护不均衡的问题。Miao-Yunzai的原作者因工作原因更新频率有限，追求新特性的使用者被引向TRSS-Yunzai^[13]。社区插件索引库也声明仅作索引查询，不对收录内容及其质量做完整验证，使用第三方代码需自行评估风险^[3]。

许可方面，框架采用GPL-3.0，以模块形式在框架进程内加载的插件通常被视为衍生作品，需以GPL-3.0或兼容协议开源；只有通过独立进程或OneBot等网络协议通信的插件才可另选协议^[6]。这一约束会限制部分开发者的发布方式^[6]。

参见

• Miao-Yunzai —— 由喵喵基于云崽v3.0改造的衍生框架，改用icqq登录。

• TRSS-Yunzai —— 以Miao-Yunzai为基础、支持多账号与多协议端的应用端分支。

• miao-plugin —— 为云崽提供角色面板查询等增强功能的常用插件。

• Node.js —— 云崽运行所依赖的服务端JavaScript运行时。

• Redis —— 云崽用于数据存储的键值数据库，亦可用兼容实现Valkey替代。

• GPL-3.0 —— 云崽项目使用的开源许可证。