QQ 机器人

这是 Nascraft26P 新增 的功能，上游 Nascraft 没有。它让玩家在 QQ 群里查价、设提醒、绑定账号，也能把成交直接播报到群里。

支持两种接入方式，按你的 QQ 形态二选一（也可以同时开，下文分别说明）：

方式	适合场景	需要的东西
OneBot v11（个人 QQ）	个人 QQ、自建机器人框架	一个 OneBot v11 实现（NapCat / LLOneBot / Lagrange / go-cqhttp 等）
QQ 官方机器人（官方 API v2）	官方渠道、需要长期稳定运行	QQ 开放平台的 AppID 与 AppSecret
QQ 官方机器人 + OneBot 适配器	已经在用 onebots 等框架，想复用同一个适配器	Node.js + @onebots/adapter-qq（官方 SDK 的 OneBot v11 封装）

两种方式共用同一套 QQ 命令和账号绑定，/linkqq 生成的绑定码在两边都有效。

它能做什么

功能	说明
查价	在群里或私聊发「行情煤炭」，返回当前价格、库存和今日涨跌
价格提醒	到价后私聊提醒你，每个 QQ 最多 8 条
交易播报	大额成交、指定玩家的成交实时推送到指定群
账号绑定	QQ ↔ 游戏账号一对一绑定，权限与游戏内一致

方式一：OneBot v11（个人 QQ）

支持的 OneBot 实现

协议是标准的 OneBot v11，原则上任何实现都能接：

个人 QQ：NapCat、LLOneBot、Lagrange、go-cqhttp
QQ 官方机器人渠道：gensokyo、@onebots/adapter-qq 等 OneBot v11 适配器

机器人本身不随插件分发，需要你自己部署一个，并开启它的 HTTP API 与 HTTP 上报。

配置

在 config.yml 末尾的 onebot 段：

onebot:
  enabled: false
  # OneBot v11 HTTP API 地址（不要带 /send_private_msg 后缀）
  api-url: 'http://127.0.0.1:3000'
  # 与 OneBot 实现约定的 access token；留空表示不校验
  access-token: ''

  # 把游戏内成交播报到 QQ 群
  log-trades:
    enabled: false
    # 接收交易日志的群号，可以填多个
    group-ids: []

  # QQ 价格提醒
  alerts:
    enabled: false
    # 检查提醒的间隔（秒）
    check-interval: 60

  # 接收 OneBot 事件上报的 Webhook 服务
  webhook:
    enabled: false
    host: '127.0.0.1'
    port: 8765
    path: '/onebot'
    # 校验上报请求的密钥；留空或 SECRET 表示不校验
    secret: ''

  # 允许在 QQ 里使用的命令
  commands:
    enabled: true
    # 允许使用命令的群号；留空 = 所有群都允许（私聊始终允许）
    group-whitelist: []

port 注意别和其他插件（例如网页地图、面板）冲突；这是插件自己监听的端口。

连接步骤

部署机器人（以 NapCat / LLOneBot 为例），登录你的 QQ 小号。
在机器人后台打开 HTTP 服务（HTTP API），记下地址和端口，建议设置 access token。
在机器人后台配置 HTTP 上报（HTTP POST），地址填：

http://<服务器内网或公网 IP>:8765/onebot

如果 webhook.secret 不是空的，还要在机器人侧填上相同的 token / secret。

回到 config.yml，把 onebot.enabled、webhook.enabled 打开，api-url 填机器人地址，重启服务器。
控制台出现 [OneBot] Webhook 监听 http://…:8765/onebot 就算通了。

绑定账号

玩家在游戏里执行 /linkqq（别名 /qq，权限 nascraft.qq.linkable）。
插件返回一串 6 位绑定码，10 分钟内有效。
玩家用 QQ 私聊机器人发送：绑定 123456。
绑定成功后，各种查询和提醒都会发到该 QQ。

解绑：

游戏内：/linkqq unlink
QQ 里：解绑

QQ 命令

私聊直接发；群里需要机器人能被叫到（或在白名单群里直接发）。

命令	说明
`帮助` / `help` / `菜单` / `?`	查看指令帮助
`行情 <物品>` / `价格 <物品>` / `price <物品>`	查询价格、库存、今日涨跌
`提醒 <物品> <价格>` / `alert <物品> <价格>`	设置到价提醒（负数表示跌破）
`提醒列表` / `alerts`	查看自己的提醒
`取消提醒 <物品>` / `unalert <物品>`	取消某条提醒
`绑定 <绑定码>` / `bind <绑定码>`	绑定游戏账号
`解绑` / `unlink`	解除绑定

示例：

行情 煤炭
提醒 钻石 120
提醒列表

交易播报

打开 onebot.log-trades.enabled 并填好 group-ids 后，每笔成交会按下面的格式发到群里：

[TIME] [PLAYER] [ACTION] [AMOUNT] x [ITEM] = [WORTH]

可以改 langs/zh_CN.yml 里的 onebot_trade_line 自定义文案，[ACTION] 等占位符会被替换。

排错

现象	排查方向
群里发命令没反应	`webhook.enabled` 是否打开；机器人上报地址是否指向 `http://IP:端口/onebot`
返回 403	`webhook.secret` 与机器人侧填的 token 不一致
返回 405	上报方式用了 GET，必须是 POST
能收消息但发不出去	`api-url` 填错，或机器人 HTTP API 未开启
群里能用、私聊不行	私聊也走同一个 Webhook，检查机器人是否把私聊消息也上报
提示"该 QQ 已经绑定"	一个 QQ 只能绑一个游戏账号，先在 QQ 里 `解绑`

服务器到机器人的网络必须是通的：如果机器人和服务器不在同一台机器，api-url 要填可达地址（或走内网穿透）。

方式二：QQ 官方机器人（官方 API v2）

v26.4.5.2 新增：不依赖 NapCat 之类的第三方客户端，插件直接用 HttpClient + WebSocket 连腾讯官方网关。

和 OneBot 的区别

	OneBot v11	QQ 官方机器人
需要额外部署客户端	是（NapCat / LLOneBot…）	否，插件直连官方
使用门槛	任何 QQ 号都行	需要在 q.qq.com 注册开发者、创建机器人并通过审核
身份标识	QQ 号	`openid`（不是 QQ 号，不同机器人下不同）
主动消息	基本不受限	受官方频控（被动回复 5 分钟内有效、每条消息最多回 5 次）
群号	QQ 群号	群 `openid`

两种方式可以同时开启：/linkqq 生成的绑定码在两边都能用，账号绑定分别保存在 onebot.yml 与 qqofficial.yml。

配置

qq-official:
  enabled: false
  # 机器人 AppID / AppSecret（开放平台「开发设置」里）
  app-id: ''
  client-secret: ''
  # 审核/开发阶段填 true 使用沙箱环境
  sandbox: false
  # 自定义 API 基地址；留空按 sandbox 自动选择
  api-base: ''
  # 自定义取 token 地址；留空使用官方地址（失败会自动尝试备用域名）
  token-url: ''
  # 订阅事件位掩码；33554432 = 1<<25（群 @ 消息 + 私聊消息）
  intents: 33554432
  log-trades:
    enabled: false
    # 群 openid（不是群号）
    group-openids: []
  alerts:
    enabled: false
    check-interval: 60
  commands:
    enabled: true
    # 允许使用命令的群 openid；留空 = 全部允许
    group-whitelist: []

接入步骤

打开 QQ 开放平台，创建机器人，拿到 AppID 与 AppSecret。
在「开发设置」里勾选需要的权限，并确保申请了 群聊 @ 消息 与 私聊消息 事件（对应 intents 1<<25）。
把机器人拉进目标 QQ 群（机器人需要是群成员才能被动回复）。
填写 config.yml 的 qq-official 段，enabled: true，重启服务器。
控制台出现 [QQ Official] 已连接 QQ 网关 即接入成功（首次连接会打印 鉴权成功 (session=…)）。
若在沙箱阶段，把 sandbox 改成 true。

获取群 openid

群 openid 与群号不同。把机器人拉进群后，在群里 @ 机器人发一条 帮助，控制台/插件的告警里会带出收到的 group_openid；也可以先用私聊完成绑定与查价。

命令

与 OneBot 完全一致：帮助、行情 <物品>、提醒 <物品> <价格>、提醒列表、取消提醒 <物品>、绑定 <绑定码>、解绑。群里需要 @ 机器人 才会收到命令。

排错

现象	排查方向
控制台一直重连	`app-id` / `client-secret` 是否正确；该机器人是否已通过审核
网关报 intents 错误并断开	`intents` 与开放平台后台申请的事件不一致
私聊能回、群里不回	机器人不是群成员，或没有申请群聊事件
发送失败 40054005	同一 `msg_id` + `msg_seq` 重复发送（插件已自增，正常不会触发）
主动播报失败 40034128	超过被动回复 5 分钟窗口 / 主动消息频控
绑定提示失败	绑定码过期（10 分钟）或已在其他账号使用

方式三：QQ 官方机器人 + OneBot v11 适配器（官方适配器）

如果你已经在用 onebots / @onebots/adapter-qq 这类「QQ 官方机器人适配器」，就不必再让插件自己连 QQ 网关：适配器基于腾讯官方 SDK（@tencent-connect/qqbot-nodejs）把官方机器人的消息投影成 OneBot v11，插件仍然走上面「方式一」的 OneBot 桥接即可。

	方式二（插件直连）	方式三（官方适配器）
需要额外进程	不需要	需要一个 Node.js 进程
适合	只想装一个插件	已经有 onebots 等框架，或要同时接多个平台
配置位置	`qq-official` 段	`onebot` 段

步骤

安装 Node.js 18 或更高版本。
启动官方适配器（以 onebots 为例）：npx onebots -r qq，按提示填入 QQ 开放平台的 AppID / AppSecret。
打开适配器的 OneBot v11 HTTP API（onebots 配置里 onebot.v11: use_http: true），记下地址，一般是 http://127.0.0.1:6727。
在 Nascraft 的 config.yml 里启用 OneBot：

onebot:
  enabled: true
  # 指向官方适配器的 OneBot v11 HTTP API
  api-url: 'http://127.0.0.1:6727'
  # 与适配器里配置的 access token 保持一致；留空表示不校验
  access-token: ''
  commands:
    enabled: true
    group-whitelist: []
  webhook:
    # 若要被动回复/收群消息，需要适配器把上报地址指向插件
    enabled: true
    host: '0.0.0.0'
    port: 8765
    path: '/onebot'
    secret: ''

重启服务器，控制台出现 [OneBot] 已启用，API: http://127.0.0.1:6727 即接通。

需要注意

id 是字符串：官方适配器上报的 user_id / group_id 是 openid（例如 0A1B2C3D4E5F...），不是数字 QQ 号。Nascraft 的 OneBot 桥接同时接受数字与字符串 id，所以 group-ids、group-whitelist 里直接填 openid 即可，老的数字群号也照旧可用。
频道消息不处理：插件只处理群聊 @ 与私聊，QQ 频道（guild）的消息会被忽略。
被动回复有窗口：官方机器人对同一条消息的被动回复有效期 5 分钟、最多 5 次；交易播报和价格提醒属于主动消息，受官方频控（认证 60 条/分钟）。