NapCatQQ：基于 NTQQ 的 OneBot 协议端，本地跑通 QQ 机器人的最短路径

NapCatQQ：基于 NTQQ 的 OneBot 协议端，本地跑通 QQ 机器人的最短路径

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

NapCatQQ 是一个基于 NTQQ 的机器人协议端框架：它把 NTQQ 的协议能力封装成标准 OneBot API 和 Web 管理界面，适合需要在 Windows 上以低内存占用跑长期在线 QQ 机器人的开发者。如果你要对接现有 OneBot 框架（如 AstrBot、MaiBot），或者想读懂协议端内部实现，这个项目都能直接用。

3 分钟看懂仓库结构

一句话定位：NapCatQQ 是协议端，不是应用框架——它负责登录、收发、暴露 API，业务逻辑由你接入的 Bot 框架处理。

仓库是 pnpm monorepo（见 pnpm-workspace.yaml），所有子包都在 packages/ 下：

新手先关注两块：napcat-onebot定义了你能调用的全部 API，napcat-onebot/action/下按 user、group、msg、file 等目录分门别类，翻一遍就知道能做什么。

最短路径跑起来

前置条件：Node.js ≥ 18.0.0（各包engines字段均要求）、pnpm，以及一台装有 NTQQ 客户端的 Windows 机器——开发模式启动脚本 packages/napcat-develop/nodeTest.ps1 会读取注册表里的 QQ 安装路径。

git clone https://gitcode.com/gh_mirrors/na/NapCatQQ cd NapCatQQ pnpm install

装完后packages/下各子包应都有node_modules链接，说明 workspace 解析正常。

pnpm run build:shell

成功后会在packages/napcat-shell/dist/生成napcat.mjs，无报错即通过。

pnpm run dev:shell

这个命令实际执行pnpm --filter napcat-develop run dev，流程是：脚本打印QQPath: ...定位到本机 QQ 目录，把wrapper.node、QQNT.dll等运行时文件复制到packages/napcat-develop/dist/，然后以--inspect调试模式加载 shell。看到文件复制完成、进程未退出即启动成功，此时可用浏览器访问本地 WebUI（默认 6099 端口，凭据见下文配置节）。

各核心组件的分工

• napcat-core：整个项目的地基。listeners/下是 QQ 事件的监听入口，services/是一一对应 NodeI 接口的服务实现，packet/处理网络包收发。排查协议层问题从这里入手。
• napcat-onebot：把 core 的能力翻译成 OneBot 动作与事件。你对接 Bot 框架时实际消费的 API 全在action/与event/两个目录，网络接入方式（HTTP、WebSocket、SSE、客户端模式）在network/下实现。
• napcat-webui-backend / frontend：管理界面。日志、配置编辑、多账号管理走这条链路，改界面行为看 frontend，改接口看 backend 的router/。
• napcat-shell 与 napcat-framework：前者是本地 shell 形态，后者构建面向 GUI 集成的框架产物，日常开发碰 shell 即可。
• napcat-protobuf / napcat-database：protobuf 消息定义与本地数据库读取的底层工具包，一般不需要动。

两处必改的配置

OneBot 网络配置在 packages/napcat-develop/config/onebot11.json：开发模式下build:shell:config会把它复制到 shell 产物目录。默认启用 HTTP（127.0.0.1:3000）和 WebSocket（127.0.0.1:3001）两个 server，messagePostFormat决定消息体是array还是string格式——对接框架时若收不到消息，先核对这两项和框架端的约定是否一致。token字段用于接入鉴权，生产环境务必填。

WebUI 配置在 packages/napcat-webui-backend/webui.json：host/port控制访问地址（默认 0.0.0.0:6099），token是登录令牌，开发模式固定为napcatqq。accessControlMode与黑白名单控制远程访问，仅内网自用时保持none即可。

按症状自查

现象：pnpm install 失败→ 常见原因是无法访问 npm registry 或网络抖动。确认网络能连通仓库源，必要时换国内镜像源；仍失败可执行pnpm store prune清理缓存后重装。

现象：build:shell 或 typecheck 报错→ 多为 TypeScript 配置或子包依赖版本问题。根目录 tsconfig.base.json 是全仓编译基准（target ES2021、bundler 解析、strict），子包各自有独立 tsconfig。看第一个报错的文件定位是哪个子包，必要时单独跑pnpm --filter <包名> run typecheck缩小范围。

现象：dev:shell 报找不到 QQ 路径→nodeTest.ps1依赖 Windows 注册表中的 QQ 卸载信息定位安装目录，QQ 未安装或安装在非常规位置都会失败。手动确认versions目录存在且包含resources/app子目录，否则以仓库文档为准。

现象：服务起来了但框架收不到消息→ 依次核对 onebot11.json 的端口与messagePostFormat、token 是否两端一致、对应 server 的enable是否为 true。

接下来做什么

1. 读 packages/napcat-onebot/action/ 下的动作实现，挑msg/SendMsg.ts、group/GetGroupList.ts两个典型文件看参数与返回结构。
2. 跑 packages/napcat-test/ 里的用例（pnpm run test），其中 packages/napcat-test/Readme.md 说明了测试用途。
3. 需要 WebUI 侧细节时看 packages/napcat-webui-backend/Readme.md。
4. 对接具体 Bot 框架时，在仓库 Issues 区搜同类项目（README 提到 AstrBot、MaiBot 均为适配对象），以仓库文档为准。

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