【TypeScript】QQ机qi人Api v2 快速二次开发框架

荼泱

bunqq-core

QQ 官方机qi人（API v2）TypeScript 框架——基于 Bun.js，登录、消息收发、命令系统、管理员、回复预算。

纯框架骨架，不含任何业务逻辑。开箱即跑，自行挂载业务模块即可。

运行时：Bun.js —— 原生 TypeScript、零运行时依赖、单文件部署。

为什么选 Bun

本项目所有代码在 Bun 上开发与运行，不混用 npm / yarn / pnpm，依赖锁定在 bun.lockb。选型理由：

维度	Bun 的优势	对本项目的实际收益
原生 TS	内置 TypeScript 转译器，bun src/index.ts 直接运行 .ts	无需 tsc 预编译、无需 ts-node，开发与生产同一套入口；typecheck 只作类型校验不产出
零运行时依赖	标准库自带 WebSocket、fetch、crypto.subtle、setInterval.unref 等	QQ 网关的 WS 长连接、Webhook 的 Ed25519 验签、REST 调用全用内置 API，package.json 无任何 dependencies
启动速度	原生编译执行，冷启动毫秒级	适配 docker restart: unless-stopped 崩溃自愈策略，重启几乎无感
热重载	bun --hot 文件变更自动重启进程	框架内置热重载守卫（globalThis.__qqbot），重载时优雅停掉旧 Bot 实例避免双 WS 连接
单二进制部署	bun build --compile 可产出独立可执行文件	容器镜像可进一步压缩为 COPY 单文件，无需 bun install 阶段
API 兼容 Node	大部分 Node API（process、Buffer、stream）可用	未来若引入生态包无需大改

一句话：Bun 让这个框架在「零依赖 + 原生 TS + WS 长连接」组合下做到最小最纯净，省掉 babel/tsc/ts-node/ws 等一堆开发期依赖。

---

能力一览

类别	说明
登录接入	WS / Webhook 双模式，AccessToken 自动刷新，断线退避重连 + 假死检测
消息接收	群 AT/全量消息、单聊、群管理事件（进退群/消息设置）、按钮回调（INTERACTION_CREATE）
消息发送	被动回复（预算+分段）、主动群消息、Markdown、ark 卡片、event_id 被动、广播
命令系统	前缀触发、全角容错（！ ／）、管理员隐身、场景限制（群/单聊）
管理员	/bind <口令> 私聊绑定 openid，严重故障主动私聊告警
健壮性	消息去重（AT/全量双事件）、沙箱群隔离、@机qi人任意位置识别、mention id 自动学习、热重载守卫、进程级兜底

---

项目仓库

https://github.com/tuyangJs/bunqq-core

二次开发文档

https://github.com/tuyangJs/bunqq-core/blob/main/DEVELOPMENT.md

cmkjw

论坛有你更精彩

曦月

论坛有你更精彩

yxl2008

感谢分享！！！

huxian

可以可以哦

huxian

可以直接使用吗

瞎JB搞

学习一下

尹老师

学习一下

算法艺术家

学习一下

shinbudar

感谢分享