配置Gensokyo（官方机器人转换器）
重要
本文教程必须使用 SparkBridge 官方Fork版 Gensokyo，官方原版长时间未更新，无法满足群服互通需求。 魔改版新增了：群全量消息接收、主动消息发送、官方昵称回填 等能力。
Gensokyo For Spark:
蓝奏云 密码:spark
视频版教学：
https://www.bilibili.com/video/BV18GbU68Eio/
前置准备
- 一个 QQ 官方机器人（在 QQ开放平台 创建，需要应用ID、应用令牌、客户端密钥）
- 魔改版 Gensokyo（上方获取）
- SparkBridge3（已安装）
什么是 Gensokyo？
Gensokyo 是一个把"QQ官方机器人API"转换成"OneBot协议"的转换器。 SparkBridge 无法直接连接官方机器人，需要通过 Gensokyo 中转。 简而言之：QQ官方机器人 → Gensokyo → SparkBridge → 游戏。
第一步：用辅助工具生成 Gensokyo 配置
打开 SparkBridge 网页控制台，在侧边栏找到 Gensokyo配置生成 页面：
也可以直接在线打开生成器（无需 SparkBridge 控制台）：
填写机器人账号（必填）
| 字段 | 说明 | 在哪获取 |
|---|---|---|
| 应用ID (app_id) | 机器人的应用ID | QQ开放平台 → 开发设置 |
| 应用令牌 (token) | 机器人的令牌 | QQ开放平台 → 开发设置 |
| 客户端密钥 (client_secret) | 机器人的密钥 | QQ开放平台 → 开发设置 |
| 机器人QQ号 (uin) | 机器人的QQ号码 | 点击机器人资料卡查看 |
TIP
如果找不到客户端密匙，可以开放平台右上角返回旧版平台，然后选择开发配置。
填写服务器连接（必填）
| 字段 | 说明 | 建议 |
|---|---|---|
| 监听端口 (port) | Gensokyo 的监听端口 | 默认 15630，可改 |
| 正向WS令牌 (ws_server_token) | 连接密码，记下来，下一步要用 | 随意设置一个复杂的字符串 |
消息行为（推荐配置）
| 选项 | 推荐 | 说明 |
|---|---|---|
| 事件订阅 | 全部勾选 | 群@消息 + 群全量消息 + 私聊 |
| 响应模式 | 全量响应 | 所有消息都处理，群服互通必需 |
| 主动消息 | 允许主动发送 | 游戏消息能主动推送到群 |
| 日志级别 | info | 报障时再调 debug |
填完后点击 生成 config.yml → 下载文件。
替换配置文件
- 把下载的
config.yml复制到 Gensokyo 所在的文件夹 - 覆盖原有的
config.yml - 重启 Gensokyo
为什么不用手动改 Gensokyo 配置？
Gensokyo 原版配置有 140+ 项，手动配置容易出错，且太多无关内容。 辅助工具会自动写入推荐默认值，您只需要填写必要字段即可。
第二步：配置 SparkBridge 连接
打开 SparkBridge 网页控制台，选择 插件中心，点击 base 模块：
| 字段 | 填写内容 |
|---|---|
| 连接地址 (target) | ws://你的服务器IP:端口（端口 = 第一步填的监听端口） |
| 机器人QQ号码 (qid) | 第一步填的应用ID |
| 鉴权密码 (pwd) | 第一步填的正向WS令牌（必须一致） |
| Websocket连接类型 (ws_type) | 选择 正向WS |
保存修改，并重启服务器。
第三步：确认连接成功
重启后，观察 SparkBridge 控制台日志：
- 出现
WebSocket连接成功相关日志 → Gensokyo 和 SparkBridge 已连通 ✅ - 如果连接失败 → 检查：端口是否一致、令牌是否一致、Gensokyo 是否在运行
第四步：打开QQ客户端，允许机器人接受所有的信息
作为群主，把bot拉进你的群，点开bot信息，许可bot获取信息范围为所有
允许机器人在群内主动发言（如果看不见请更新qq）
第五步：查看实时群聊，识别群成员
首次使用官方机器人，您不知道群里谁是谁（官方身份是一串乱码ID）。
打开实时消息开关
SparkBridge 网页控制台 → 插件配置 → sb3_gskconfig → 打开 "实时打印群聊信息"：
观察控制台
让群成员随便发几条消息，SparkBridge 控制台会实时打印：
[群消息] 群=683060421 | 用户=354421934 (openid=5D06DB71...) | 昵称=Daniel_户山兔兔 | 内容: 你好通过这个日志，您可以：
- 认出群号：
群=后面的数字就是您的群号 - 认出管理员：
用户=后面的数字，对照群成员昵称，找出管理员的数字ID
数字ID是什么？
Gensokyo 会把官方的一串乱码ID（openid）转换成一串数字ID，方便识别。 您在日志里看到的 用户=354421934 就是群成员的"数字身份"，之后配置都用它。
第五步：配置超管和主群，完成
回到 SparkBridge 网页控制台 → 插件中心 → base 模块，把第四步看到的数字填进去：
| 字段 | 填写内容 |
|---|---|
| 超级管理员QQ号码 (admin_qq) | 管理员的 用户= 数字ID |
| 机器人主群号 (main_group) | 目标群的 群= 数字ID |
保存修改，重启服务器。
完成后，可关闭 sb3_gskconfig 的实时消息开关（避免刷屏）。
常见问题
Q: 连接不上，日志显示鉴权失败
检查两边的令牌是否一致：Gensokyo 的 ws_server_token 和 SparkBridge 的 pwd。
Q: 日志显示"主动消息失败, 无权限"
您的官方机器人没有开通主动消息权限。需要在QQ客户端上允许机器人发送主动信息，或暂时关闭 allow_proactive_msg。
Q: 群里收不到消息
确认 Gensokyo 的事件订阅里勾选了 群全量消息，且在QQ客户端上允许机器人开通"接收所有消息"权限（在群主的QQ客户端里操作）。