Xingyue Bot

在 QQ 开放平台创建应用

前往 https://q.qq.com/#/apps，使用 QQ 号登录，点击"创建应用" → "机器人"。填写机器人名称、头像、简介等信息，创建完成后进入机器人管理页面。

获取 AppID / Token / AppSecret

在机器人管理页面左侧"开发" → "基本配置"中：

• AppID — 机器人的唯一标识（纯数字字符串）
• Token — 身份验证密钥
• AppSecret — 用于获取 access_token 的密钥

开启事件订阅（重要）

在"开发" → "事件订阅"中，开启以下事件：

• 群聊消息（AT_MESSAGE_CREATE、MESSAGE_CREATE）— 接收群消息
• 群成员增加（GUILD_MEMBER_ADD）— 新人入群通知
• 群成员减少（GUILD_MEMBER_REMOVE）— 成员退群通知

订阅方式选择"HTTP"，回调地址保持默认即可（本模组使用 WebSocket 连接，不需要 HTTP 回调）。

权限设置

在"开发" → "权限设置"中，确保已开启：

• 获取群聊信息
• 获取群成员信息
• 发送群聊消息

添加机器人到 QQ 群

在机器人管理页面"部署" → "群聊管理"中，搜索目标群号并添加机器人。也可以让群管理员在群设置中搜索机器人并邀请入群。

机器人入群后，群成员即可通过配置好的指令与机器人互动。

登录 Web 面板

启动服务器后，在浏览器访问 http://服务器IP:端口。默认端口为 8080（可在 config/xingyuebot/config.json 中修改 webPort 字段）。

默认管理员账号：admin，密码：admin。首次登录后请立即在"网页管理员"标签中修改密码。

填写机器人凭证

在"控制台" → "QQ Bot 连接"卡片中，依次填入：

• AppID — 从开放平台获取
• Token — 从开放平台获取
• AppSecret — 从开放平台获取

点击"连接"按钮，状态指示灯变为绿色即表示连接成功。

绑定 QQ 群

连接成功后，在"QQ 群管理"卡片中：

• 检测群聊 — 自动扫描机器人已加入的群
• 手动添加 — 输入群 OpenID 添加

添加成功后，该群的消息会自动转发到游戏内，游戏内消息也会自动转发到群中。

保存配置

所有配置修改后，点击页面底部的"保存配置"按钮持久化到文件。使用"重新加载"按钮可重新读取配置文件。

端口修改需要重启服务器才能生效，其他配置可以热重载。

方案一：硅基流动（SiliconFlow）

硅基流动提供多种开源模型的托管 API，注册即送免费额度。

• 官网：https://cloud.siliconflow.cn
• 注册登录后，在"API 密钥"页面创建密钥

面板填写：

• API 地址：https://api.siliconflow.cn/v1/chat/completions
• API Key：粘贴创建的密钥
• 模型名称：如 Pro/deepseek-ai/DeepSeek-V3.2-Exp（可在平台查看最新模型列表）

方案二：DeepSeek 官方 API

DeepSeek 官方提供高性价比的 API 服务，注册即送额度。

• 官网：https://platform.deepseek.com
• 注册后在"API Keys"页面创建密钥

面板填写：

• API 地址：https://api.deepseek.com/v1/chat/completions
• API Key：粘贴创建的密钥
• 模型名称：deepseek-chat

方案三：幻城网安

幻城网安提供多家大模型的一站式 API 聚合服务。

• 官网：https://ai.hcnetwork.cn
• 注册后获取 API Key

面板填写：

• API 地址：https://ai.hcnetwork.cn/v1/chat/completions
• API Key：粘贴获取的 Key
• 模型名称：咨询平台客服获取可用模型列表

方案四：自定义接口

任何兼容 OpenAI API 格式的接口均可使用，包括：

• 本地部署模型（Ollama、vLLM、llama.cpp 等）
• 其他云服务商（通义千问、智谱清言等）
• API 代理或中转服务

面板填写：

• API 地址：填写对应的 API 地址（以 /v1/chat/completions 结尾）
• API Key：粘贴对应的密钥
• 模型名称：填写服务商支持的模型名

系统提示词（System Prompt）

System Prompt 定义 AI 的人设和行为规则。示例：

提示词越具体，AI 表现越稳定。建议明确：回复长度、语气风格、行为边界。

触发方式

• QQ 群 @机器人 — 在群里 @机器人 并发送消息，AI 会自动回复
• 触发前缀 — 在 AI 设置中可配置前缀（如 #ai），输入 #ai 消息 也可触发
• 游戏中聊天气泡 — 开启后，游戏内输入消息也会触发 AI 回复（需在 AI 设置中开启）

联网搜索（可选）

在 AI 设置中开启"启用联网搜索"后，AI 会自动搜索网络获取最新信息来回答问题。自动多后备搜索：

• Bing（必应） → 首选
• 百度 → Bing 不可用时自动切换
• 自定义 API → 可选填其他搜索接口

默认只需勾选"启用联网搜索"即可，无需任何额外配置。

方式一：QQ 群发起绑定（推荐）

玩家在 QQ 群中发送：

机器人回复一条验证码和验证指令。玩家在游戏内执行：

验证码有效期为 5 分钟，超时需重新发起。

方式二：游戏内绑定

玩家在游戏内发送：

其中 123456 是机器人在QQ私聊中发送给玩家的验证码。此方式不需要在群里操作，适合不想公开游戏ID的玩家。

查询绑定

QQ 群中发送：

可查询该游戏 ID 是否已绑定以及绑定的 QQ 号。

发送 #me 或 #我的 可查询自己的绑定信息。

解除绑定

QQ 群中发送：

可解除自己的 QQ 与游戏 ID 的绑定关系。

管理员可在控制台的"QQ-MC 绑定管理"中强制解绑任意玩家。

消息格式

在控制台"消息格式"卡片中，可配置消息的显示模板：

• 游戏→QQ：游戏内消息发到 QQ 群的格式。变量：{player}（玩家名）、{message}（消息内容）
• QQ→游戏：QQ 群消息发到游戏内的格式。变量：{sender}（发送者昵称）、{message}（消息内容）

示例：[QQ] {sender}: {message} 会显示为 [QQ] 小明: 大家好

通知设置

在控制台"通知设置"卡片中，可开关以下通知到 QQ 群：

• 玩家加入 — 有玩家进入服务器时通知
• 玩家退出 — 有玩家离开服务器时通知
• 玩家死亡 — 有玩家死亡时通知（含死亡原因）

QQ 管理员

在控制台"QQ 管理员"卡片中，可以添加或移除具有管理权限的群成员。

管理员可以在 QQ 群中使用 #givecoins 和 #takecoins 指令管理玩家金币。

点击"检测群成员"可查看群内所有成员及其 OpenID，方便添加管理员。

签到设置

在"签到设置"标签页中，可配置：

• 启用签到 — 开关签到功能
• 每日金币范围 — 每日签到随机给予的金币数量（最小/最大）
• 连续签到奖励 — 连续签到达到一定天数时的额外金币
• 周期天数 — 连续签到奖励的循环周期

签到功能需要安装并加载 SellBox 插件，通过其经济系统发放金币。

Web 面板无法访问

可能的原因和解决方法：

• 确认服务器已成功启动（检查控制台日志是否有报错）
• 确认端口未被防火墙拦截（默认 8080）
• 面板服请在 config/xingyuebot/config.json 中修改 webPort 为可用端口
• 检查服务器是否绑定在 0.0.0.0 而非 127.0.0.1

机器人连接失败

• 检查 AppID、Token、AppSecret 是否填写正确（注意大小写）
• 确认已开启必要的事件订阅和权限（参见第一章）
• 网络环境是否能正常访问 api.sgroup.qq.com
• 查看服务器日志中的错误信息，根据具体错误排查

QQ 群收不到消息

• 确认机器人已加入群聊并在群管理中配置了"获取群内全部消息"
• 确认群 OpenID 已添加到控制台的群列表中
• 确认事件订阅中的 AT_MESSAGE_CREATE 和 MESSAGE_CREATE 已开启
• 检查机器人是否被群管理员设置了禁言

AI 不回复

• 确认 AI 功能已开启（AI 设置 → 启用 AI 对话）
• 检查 API 地址、Key、模型名是否正确
• 使用"AI 对话预览"功能测试是否能正常调用
• 确认触发方式正确（@机器人 或配置的前缀）
• 查看服务器日志中 AI 相关错误信息

验证码无效

• 验证码有效期为 5 分钟，超时需重新发起绑定
• 每个验证码只能使用一次，使用后即失效
• 确认在游戏内输入的验证码与机器人回复的完全一致
• 如在游戏中绑定，确认私聊收到的验证码与输入的一致

签到功能不可用

• 确认已安装 SellBox 插件且版本兼容
• 检查服务器日志是否有 SellBox 相关报错
• 确认签名设置中的"启用签到"已开启
• 检查 config.json 中 signInEnabled 是否为 true

联网搜索无结果或超时

• 默认使用 Bing → 百度的多后备搜索，国内可用
• 如果搜索失败，检查服务器网络是否能访问 www.bing.com 和 www.baidu.com
• 可在 AI 设置中自定义其他搜索 API 地址作为补充

配置修改后不生效

• Web 面板中点击"保存配置"按钮写入文件
• 点击"重新加载"按钮使配置生效
• 部分配置（端口、AI 提供商等）需要重启服务器
• 也可以直接修改 config.json 后重启服务器