Gensokyo-Koishi教程
=============================================
本篇教程将带您使用 koishi 的adapter-onebot 插件 ，
完成在 Windows 平台上，基于 Gensokyo 的连接方法完成 bot 部署
（现阶段QQ频道可用）
编纂者是小学我啦，有什么不足之处要及时指出哦，我会积极核实考虑并改正的！~
Gensokyo 简介
摘要
gensokyo兼容 OneBot-v11 ，并在其基础上做了一些扩展
可将官方的websocket和api转换至onebotv11标准,和koishi,nonebot2,trss等项目的onebot适配器相连接使用。
实现插件开发和用户开发者无需重新开发,复用过往生态的插件和使用体验.
目前还处于早期阶段…（现阶段仅QQ频道开放可用）
语雀教程：Gensokyo教程 · 语雀
Gensokyo项目地址：GitHub - Hoshinonyaruko/Gensokyo: 基于qq官方api开发的符合onebot标准的golang实现，轻量、原生跨平台.
QQ交流群:196173384
欢迎测试,询问任何有关使用的问题,有问必答,有难必帮~
在此感谢小狐狸的辛勤付出！
·
Gensokyo教程
面向曾经有机器人部署经验的开拓者
初次使用的用户 请期待 即将到来的 gensokyo一键脚本&小白教程
第一步
获得最新的gensokyo可执行文件
· Windows系统 下载releases获得gensokyo可执行文件
建议下载到一个新建的文件夹哦~
点击右侧 前往下载： Hoshinonyaruko/Gensokyo: 基于qq官方api开发的符合onebot标准的golang实现，轻量、原生跨平台. (github.com)
非Windows系统的可执行文件 请在action中获取
或者通过actions下载获得gensokyo可执行文件
· 或者通过actions下载获得gensokyo可执行文件
前往项目获取最新actions内容
链接：Workflow runs · Hoshinonyaruko/Gensokyo · GitHub
登录github后，按图示 点击【Test4】按钮
进入【Test4】后，出现下方图片所示的界面，翻到最底下
根据系统选择对应的版本即可哦~（注；登录github才可点击下载哦，不然点不了）
下载到一个文件夹即可。
下载得到一个压缩包。请解压到一个单独的文件夹里。
解压后 得到的文件如下所示：
可以注意到，这个文件缺少了【.exe】的后缀
在Windows平台下，我们需要重命名该文件，在文件名称结尾加上【 .exe 】
（此处注意【.exe】不是【。Exe】哦）
下载得到gensokyo-windows-amd64.exe
双击运行‘ gensokyo-windows-amd64.exe ’
会（如下图）提示配置文件不存在, 关掉这个页面
发现 .exe在所在目录生成了三个文件
第二步
打开同目录的config.yml文件，（此处建议使用VScode等工具打开，以便明确缩进）
我们需要在config.yml文件中配置机器人参数
参数需要前往q.qq.com注册并获取机器人【 appid, token 】
下面是【第三步】关于如何获取QQ机器人appid,token参数的教程：
第三步
第三步-注册QQ官方机器人--如果已经有了就可以跳过本步骤啦~
打开浏览器，地址栏输入【q.qq.com】并访问。
注册/登录你的账号。此步骤具体操作请参考QQ机器人文档
【 QQ 机器人 | QQ机器人文档 】
登录 QQ开放平台 之后，点击页面左上角的logo返回主页面
（即访问【 QQ 开放平台 】）
在此页面向下翻 可以找到【 创建机器人 】的蓝色按钮
需要注意的是，注册机器人时，所需要选择填写的【沙箱频道ID】是上方登录QQ开放平台账号所创建的频道。所以需要先建一个频道哦 ~
没有频道？如何新建？
没有频道？
你可以先进入一个频道，就可以找到频道在哪啦~这里给出QQ官方频道
建议手机QQ打开
点击链接加入QQ频道【QQ频道桃源岛】： https://pd.qq.com/s/6192hpo4x
*
如何新建？
在手机QQ的频道页面上方可以新建哦
完成机器人的创建后，不要忘记将机器人 添加到 沙盒频道哦~
（频道添加机器人 在QQ机器人文档中有说明 —— QQ 机器人 | QQ机器人文档 ）
最终完成机器人的创建，可以在QQ开放平台的 开发设置 页面看到机器人的相关信息：
注意这三项即为我们所需的内容
第四步
回到【打开config.yml文件，】
此处以公域机器人为例：（下文有私域的例子）
首先配置你的 【应用ID 、 应用令牌 、 客户端密钥】
填入配置项,保持类型正确,将值填入引号之间,appid是数字,不需要括号
并且选择对应的intent（私域机器人,需要解开频道不at信息的intent）
（把需要的选项的前面的
删掉，保持如图对齐就是【选中】状态）
然后在下方的图床端口，请填入对应内容
（不填入会闪退捏~填一个就好，哪怕不能用，详情可以看下面的【yml文件具体内容】）
yml文件具体内容
version: 1
settings:
ws_address: [“ws://127.0.0.1:5140/onebot”] # WebSocket服务的地址 支持多个[“”,“”,“”]
app_id: 10*****59 # 你的应用ID
token: “0Q**************************** x” # 你的应用令牌
client_secret: “4q*************tY” # 你的客户端密钥
text_intent: # 请根据公域 私域来选择intent,错误的intent将连接失败
- “ATMessageEventHandler” # 频道at信息
# “DirectMessageHandler” # 私域频道私信(dms)
# - “ReadyHandler” # 连接成功
# - “ErrorNotifyHandler” # 连接关闭
# - “GuildEventHandler” # 频道事件
# - “MemberEventHandler” # 频道成员新增
# - “ChannelEventHandler” # 频道事件
# “CreateMessageHandler” # 频道不at信息 私域机器人需要开启 公域机器人开启会连接失败
# - “InteractionHandler” # 添加频道互动回应
- “GroupATMessageEventHandler” # 群at信息 仅频道机器人时候需要注释
# - “C2CMessageEventHandler” # 群私聊 仅频道机器人时候需要注释
# - “ThreadEventHandler” # 发帖事件 (当前版本已禁用)
global_channel_to_group: true # 是否将频道转换成群 默认true
global_private_to_channel: false # 是否将私聊转换成频道 如果是群场景 会将私聊转为群(方便提审\测试)
array: false
server_dir: “127.0.0.1” # 提供图片上传服务的服务器(图床)需要带端口号. 如果需要发base64图,需为公网ip,且开放对应端口
port: “11451” # idmaps和图床对外开放的端口号
lotus: false # lotus特性默认为false,当为true时,将会连接到另一个lotus为false的gensokyo。
# 使用它提供的图床和idmaps服务(场景:同一个机器人在不同服务器运行,或内网需要发送base64图)。
# 如果需要发送base64图片,需要设置正确的公网server_dir和开放对应的port
ws_token: [“”,“”,“”] #连接wss地址时服务器所需的token,如果是ws,可留空,按顺序一一对应
master_id : [“1”,“2”] #群场景尚未开放获取管理员和列表能力,手动从日志中获取需要设置为管理,的user_id并填入(适用插件有权限判断场景)
enable_ws_server: true #是否启用正向ws服务器 监听server_dir:port/ws
ws_server_token : “” #正向ws的token 不启动正向ws可忽略
identify_file: false #自动生成域名校验文件,在q.qq.com配置信息URL,在server_dir填入自己已备案域名,正确解析到机器人所在服务器ip地址,机器人即可发送链接
crt: “” #证书路径 从你的域名服务商或云服务商申请签发SSL证书(qq要求SSL)
key: “” #密钥路径 Apache（crt文件、key文件）示例: “C:\123.key” \需要双写成\
image_sizelimit : 0 #代表kb 腾讯api要求图片1500ms完成传输 如果图片发不出 请提升上行或设置此值 默认为0 不压缩
backup_port : “5200” #当totus为ture时,port值不再是本地webui的端口,使用lotus_Port来访问webui
developer_log : false #开启开发者日志 默认关闭
server_user_password : “admin” #默认网页面板密码
remove_prefix : false #是否忽略公域机器人指令前第一个/
server_user_name : “useradmin” #默认网页面板用户名
white_prefixs : [“”] #可设置多个 比如设置 机器人 测试 则只有信息以机器人 测试开头会相应 remove_prefix remove_at 需为true时生效
title : “Gensokyo © 2023 - Hoshinonyaruko” #程序的标题 如果多个机器人 可根据标题区分
develop_bot_id : “1234” #开发者环境需自行获取botid 填入 用户请不要设置这两行…开发者调试用
forward_msg_limit : 3 #发送折叠转发信息时的最大限制条数 若要发转发信息 请设置lazy_message_id为true
lazy_message_id : false #false=message_id 条条准确对应 true=message_id 按时间范围随机对应(适合主动推送bot)前提,有足够多的活跃信息刷新id池
hash_id : false # 使用hash来进行idmaps转换,可以让user_id不是123开始的递增值
black_prefix_mode : false #公私域 过审用 指令黑名单模式开关 过滤被审核打回的指令不响应 无需改机器人后端
sandbox_mode : false #默认false 如果你只希望沙箱频道使用,请改为true
dev_message_id : false #在沙盒和测试环境使用无限制msg_id 仅沙盒有效,正式环境请关闭,内测结束后,tx侧未来会移除
save_logs : false #自动储存日志
twoway_echo : false #是否采用双向echo,根据机器人选择,獭獭\早苗 true 红色问答\椛椛 或者其他 请使用 false
white_prefix_mode : false #公域 过审用 指令白名单模式开关 如果审核严格 请开启并设置白名单指令 以白名单开头的指令会被通过,反之被拦截
visible_ip : false #转换url时,如果server_dir是ip true将以ip形式发出url 默认隐藏url 将server_dir配置为自己域名可以转换url
remove_at : false #是否忽略公域机器人指令前第一个[CQ:aq,qq=机器人] 场景(公域机器人,但插件未适配at开头)
black_prefixs : [“”] #可设置多个 比如设置 查询 则查询开头的信息均被拦截 防止审核失败
develop_access_token_dir : “” #开发者测试环境access_token自定义获取地址 默认留空 请留空忽略
bind_prefix : “/bind” #需设置 #增强配置项 master_id 可触发
log_level : 1 # 0=debug 1=info 2=warning 3=error 默认1
me_prefix : “/me” #需设置 #增强配置项 master_id 可触发
visual_prefixs : [“”] #虚拟前缀 与white_prefixs配合使用 处理流程自动忽略该前缀 remove_prefix remove_at 需为true时生效
frp_port : “0” #不使用请保持为0,frp的端口,frp有内外端口,请在frp软件设置gensokyo的port,并将frp显示的对外端口填入这里
image_limit : 100 #每分钟上传的最大图片数量,可自行增加
remove_bot_at_group : true #因为群聊机器人不支持发at,开启本开关会自动隐藏群机器人发出的at(不影响频道场景)
send_error : true #将报错用文本发出,避免机器人被审核报无响应
record_sampleRate : 24000 #语音文件的采样率 最高48000 默认24000 单位Khz
record_bitRate : 24000 #语音文件的比特率 默认25000 代表 25 kbps 最高无限 请根据带宽 您发送的实际码率调整
No_White_Response : “” #默认不兜底,强烈建议设置一个友善的兜底回复,告知审核机器人已无隐藏指令,如:你输入的指令不对哦,@机器人来获取可用指令
此处以私域机器人为例
首先配置你的 【应用ID 、 应用令牌 、 客户端密钥】
填入配置项,保持类型正确,将值填入引号之间,appid是数字,不需要括号
并且选择对应的intent（私域机器人,需要解开频道不at信息的intent）
（把需要的选项的前面的
删掉，保持如图对齐就好）
然后在下方的图床端口，请填入对应内容
（不填入会闪退捏~填一个就好，哪怕不能用）
第五步
打开koishi，在adapter-onebot界面如图配置
· 关闭gocq子进程
· 机器人账号填入你的机器人app_id（即应用ID）
· 协议选择ws-reverse
· 开启adapter-onebot插件（此时koishi右下角为黄灯）
然后在第四步中填好的config.yml内，ws_address处填入当前实例的onebot地址。
ws_address处填入【 ws://127.0.0.1:5140/onebot 】
填入【 ws://127.0.0.1:5140/onebot 】后的图例
/
**怎么看当前koishi的端口呢**
（当前实例的地址可以在鼠标放到左侧活动栏的图标上，在左下角看到
ws_address填入【
ws://127.0.0.1:5140/onebot
】
最后，按下Ctrl+S保存该文件
第六步
在此前运行的‘ gensokyo-windows-amd64.exe ’程序生成了gensokyo.bat
我们运行gensokyo.bat。
运行框内出现如下字样即代表 对接成功啦~
不出意外的话，在koishi右下角的灯是绿灯哦~
如果出现了黄灯，那代表没连上哦？根据gensokyo.bat内的code提示，检查comfig.yml文件是否有误！
这样就是登陆成功了
Gensokyo目前处于内测阶段
欢迎有机器人部署经验的开拓者们 测试、反馈！
遇到错误或者反馈问题,可以到 QQ群聊 196173384 交流哦~
有任何bug和问题欢迎反馈！
