企业官网建设流程全解析

把 NapCatQQ 当协议桥：无头 QQ 机器人接入 OneBot 11 的实操路径

【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ

先说结论：NapCatQQ 是封装在 NTQQ 之上的协议端实现，它不替你写业务逻辑，而是把 NTQQ 的消息能力翻译成 OneBot 11 标准接口，让任何理解 OneBot 11 的 bot 框架（AstrBot、MaiBot 这类）直接接上。需要管理 QQ 号、又要复用 OneBot 生态的开发者，选它成本最低；如果你的目标平台不是 QQ，或者你指望它内置定时器和数据库，那它给不了。

事件进、动作出：一条消息在 NapCatQQ 里怎么走

整条链路分两侧。事件侧：NTQQ 的监听器模块把群消息、好友请求、登录状态这些原始事件，经 OneBot 事件封装 转成标准事件对象，再由网络层按你配置的方式推给外部。动作侧：你发来的 OneBot 11 action（比如 set_group_ban），由 OneBot 协议适配模块 路由到具体处理器，落到 NTQQ 原生协议上执行，再按_async或同步约定返回结果。

传输方式四种都能开：http-server（默认 3000 端口）、websocket-server（默认 3001）、http-client、websocket-client，配置都在 OneBot 11 网络配置 里。你的 bot 框架作为 client 连进来就行。

群管机器人：从收到消息到封禁回包

以最常见的场景为例：群里有广告消息，bot 需要禁言并回一条提示。

第一步，框架连接 WebSocket Server 端口订阅事件，收到的是标准 OB11 消息事件，message 字段是 array 格式的消息段：

{ "post_type": "message", "message_type": "group", "group_id": 123456, "user_id": 654321 }

第二步，命中你的规则后调用动作。每个 action 都带_async变体，长耗时操作（下载文件、群文件读写）建议用异步版拿回包：

{ "action": "set_group_ban_async", "params": { "group_id": 123456, "user_id": 654321, "duration": 1800 }, "echo": "ban-001" }

回包通过 echo 关联请求。最后再调 send_group_msg 回提示消息。整个过程你的框架不碰任何 NTQQ 细节，只面对 OneBot 11 的契约。

超出基础协议的几个扩展点

NapCatQQ 在标准 OB11 之外注册了上百个扩展 action，全部在 action 目录可见：OCRImage、SetGroupTodo、群相册的 UploadImagesToQunAlbum、闪传的 SendFlashMsg、在线文件的 SendOnlineFile、流式上传下载等。想确认某个能力是否存在，直接翻 action 目录 比看文档快。两个容易被忽略的点：一是call层做了返回类型推导，扩展 action 有 TypeScript 类型支持；二是网络层除了四种标准模式，还内置了插件机制，可以为特定场景单独挂适配器。

下一步：起一个支持 OneBot 11 的 bot 框架，把 WebSocket Server 地址指过去，用 get_login_info 验证链路通了，再按上面的群管例子把第一个业务写出来。

【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ