NQBot

第十代新版机器人 · 基于 .NET 9 / WPF / OneBot 11 的 QQ 机器人框架。

作者：Muo · 版本：v1.0.0

NQBot 由 WPF 外壳、ASP.NET Core 宿主和独立插件 SDK 组成，通过 NapCat 的 OneBot 11 HTTP/WebSocket 接口收发消息。插件只依赖 NQBot.Sdk，可独立开发、编译和热加载。

功能

• WPF 五页签界面：好友、群、机器人设置、插件、日志
• NapCat 登录窗：HTTP/WebSocket 地址、Token、连接测试
• 插件 SDK：事件、动作、配置、群级参数、JSON 存储、定时任务、权限
• 插件管理：启用/停用、热重载、添加/删除、旧版插件拖拽排序
• 出站文本过滤 / 消息转换（敏感词、文字转图等）
• 自动更新检测（updateUrl）
• 可选的 32 位旧版 .plugin 兼容运行时（不包含在原版二进制中）

环境

• Windows 10/11
• .NET 9 SDK
• NapCat（OneBot 11）

构建

dotnet build NQBot.sln -c Release
dotnet test tests/NQBot.Tests/NQBot.Tests.csproj -c Release

运行

1. 复制配置样例：

cp runtime/appsettings.example.json runtime/appsettings.json
cp runtime/settings.example.json runtime/settings.json

2. 启动 NapCat 并登录 QQ。
3. 启动宿主：

dotnet run --project src/NQBot.Host -c Release

4. 启动 WPF 外壳：

dotnet run --project src/NQBot.App -c Release

5. 在登录窗填写 NapCat 地址，测试连接成功后进入主界面。

宿主首次启动会在 runtime/appsettings.json 生成 apiToken，WPF 外壳会自动读取并通过 X-NQBot-Token 访问本地 API。不要提交这个文件。

发布便携版时，把宿主发布到 runtime/，把 WPF 外壳发布到根目录即可。

插件开发

• 规范：docs/plugin-sdk.md
• 示例：samples/NQBot.Plugin.Hello
• 插件 DLL 放到 runtime/plugins/，在插件页重新加载。

自动更新

在 runtime/appsettings.json 配置：

{
  "updateUrl": "https://example.com/nqbot/update.json"
}

支持通用 update.json 和 GitHub/GitCode Releases API，详见 docs/update.md。

目录

src/NQBot.Sdk       插件契约
src/NQBot.Core      网关、事件、插件运行时、更新检测
src/NQBot.Host      宿主、本地 API、快照
src/NQBot.App       WPF 外壳
plugins/            内置插件
samples/            插件示例
tests/              单元测试
docs/               架构 / SDK / 更新文档
runtime/            配置样例（数据/日志/插件目录已忽略）

旧版插件兼容

旧版 .plugin 需要单独提供 32 位兼容运行时（NapCatCompat）和原软件框架文件；本仓库不包含这些二进制。相关代码位于 src/NQBot.Host/Legacy/，默认关闭，可在机器人设置中启用。

安全

• 不要提交 runtime/appsettings.json、runtime/settings.json、日志和插件数据。
• Token、管理员 QQ 等敏感信息只保存在本机。
• 第三方插件拥有与宿主相同的进程权限，请只安装可信插件。

免责声明

本项目与腾讯、QQ、NapCat 官方无关。使用机器人可能违反平台规则，请自行评估风险并遵守当地法律法规。

已知问题

见 KNOWN_ISSUES.md。

License

MIT © 2026 Muo