Gensokyo NewQQ

Appearance

Gensokyo API 介绍 ​

标准 OneBot V11 API ​

以下 API 符合 OneBot V11 标准。

Action文件场景行为
send_msgsend_msg.go私聊 (C2C) / q群 (Group Chat)按 echo/msgType 缓存和 ID 映射分流到对应发送处理器。
send_msg_asyncsend_msg_async.go同 send_msg注册到 HandleSendMsg，处理逻辑同 send_msg。
send_group_msgsend_group_msg.goq群 (Group Chat)发送消息，支持 Gensokyo 的消息解析和 ID 转换。
send_group_msg_asyncsend_group_msg_async.goq群 (Group Chat)注册到 HandleSendGroupMsg，处理逻辑同 send_group_msg。
send_group_msg_rawsend_group_msg_raw.goq群 (Group Chat)发送消息，保留更多原始参数，少做预处理。
send_private_msgsend_private_msg.go私聊 (C2C)发送 C2C 私聊消息。
send_private_msg_asyncsend_private_msg_async.go私聊 (C2C)注册到 HandleSendPrivateMsg，处理逻辑同 send_private_msg。
delete_msgdelete_msg.go私聊 (C2C) / q群 (Group Chat)按消息所属场景调用对应撤回接口。
get_login_infoget_login_info.go-获取当前机器人登录信息。
get_friend_listget_friend_list.go私聊 (C2C)获取好友列表（含全部 C2C 私聊用户的虚拟 ID）。
get_group_listget_group_list.goq群 (Group Chat)获取群列表：逐群拉取真实群名/简介/成员数（get_g_list_delay 毫秒节流），group_create_time 诚实置 0。
get_group_infoget_group_info.goq群 (Group Chat)调用 QQ 官方 v2 群信息接口返回真实群名/简介/成员数。
get_group_member_infoget_group_member_info.goq群 (Group Chat)获取成员信息：真实调用 QQ v2 接口，失败时回退中性值。
get_group_member_listget_group_member_list.goq群 (Group Chat)获取成员列表：真实调用 QQ v2 接口，游标分页全量拉取（单页≤30、安全上限 100 页）；官方接口不可用回退 idmap-pro 缓存。
get_statusget_status.go-获取运行状态：包收发/断线/丢包统计诚实置 0，消息收发计数为 botstats 真实数据。
get_version_infoget_version_info.go-获取版本信息。
get_online_clientsget_online_clients.go-获取在线客户端。
send_group_forward_msgsend_group_forward_msg.goq群 (Group Chat)发送合并转发消息。
set_group_banset_group_ban.goq群 (Group Chat)单人禁言，duration 秒数（0=解除禁言）。与 [CQ:set_group,action=ban] 共享实现底层。
set_group_whole_banset_group_whole_ban.goq群 (Group Chat)⚠️ 固定失败：官方 POST /restrict_chat_setting 无全员禁言写入字段，返回 retcode 100。与 [CQ:set_group,action=whole_ban] 共享实现底层。
set_group_kickset_group_kick.goq群 (Group Chat)批量移出群成员（单批≤20，user_id/user_ids 二选一、可合并去重），可同步拉黑。与 [CQ:set_group,action=kick] 共享实现底层。
set_group_cardset_group_card.go-QQ 官方 API 未提供设置群名片接口，明确失败回执（retcode 100）。
.handle_quick_operationhandle_quick_operation.go-OneBot 快速操作。
.handle_quick_operation_asynchandle_quick_operation_async.go-OneBot 快速操作的 async action 名称。
mark_msg_as_readmark_msg_as_read.go-标记消息已读：官方无已读上报接口，空实现仅回执 ok。

delete_msg 差异说明：

参数类型说明
message_idint32消息 ID
user_idint64/string私聊 (C2C) 时需要
group_idint64/stringq群 (Group Chat) 时需要

Gensokyo 扩展 API ​

Action文件场景行为
get_avatarget_avatar.go-按虚拟用户 ID 反查 OpenID 并返回头像直链。
get_robot_share_linkget_robot_share_link.go-获取机器人资料页分享链接。
put_interactionput_interaction.goq群 (Group Chat)回复按钮交互结果。
send_private_msg_wakeupsend_private_msg_wakeup.go私聊 (C2C)发送 is_wakeup=true 的 C2C 召回消息。
send_private_msg_ssesend_private_msg_sse.go私聊 (C2C)SSE 私聊消息。
get_group_banset_group_ban.goq群 (Group Chat)兼容入口，处理逻辑等同 set_group_ban。
get_group_whole_banset_group_whole_ban.goq群 (Group Chat)兼容入口，处理逻辑等同 set_group_whole_ban（同样固定失败 retcode 100）。
set_group_add_requestset_group_add_request.goq群 (Group Chat)入群申请审批。与 [CQ:set_group,action=add_request] 共享实现底层。
send_to_groupsend_group_msg.goq群 (Group Chat)send_group_msg 别名。
delete_group_msgdelete_group_msg.goq群 (Group Chat)撤回群内指定用户或 Bot 自身的消息；支持自动查找最后一条消息。
get_group_join_request_listget_group_join_request_list.goq群 (Group Chat)拉取入群申请列表，cursor/limit 分页（旧 next_index 兼容回退）；返回的 group_id/user_id/flag 可直接回传 set_group_add_request 审批。
get_group_bot_stateget_group_bot_state.goq群 (Group Chat)获取机器人在群内状态（入群时间/可推送/角色）。
join_approval_strategy_createjoin_approval_strategy.go-创建入群自动审批策略（group_openids/group_ids 二选一）。
join_approval_strategy_listjoin_approval_strategy.go-查询策略列表（cursor/limit 分页）。
join_approval_strategy_updatejoin_approval_strategy.go-修改策略（strategy_id + is_enable/expire_at/remark/op+关联群）。
join_approval_strategy_executejoin_approval_strategy.go-执行策略全量扫描（异步约 10 分钟）。
join_approval_strategy_whitelistjoin_approval_strategy.go-修改策略白名单（strategy_id + op + whitelist_users）。
join_approval_strategy_deletejoin_approval_strategy.go-删除策略（strategy_id）。
get_group_member_blacklist / set_group_member_blacklistget_group_member_blacklist.go / set_group_member_blacklist.goq群 (Group Chat)群黑名单查询 / 增删（单批≤20）。
get_custom_menu / set_custom_menuget_custom_menu.go / set_custom_menu.go私聊 (C2C)C2C 自定义菜单读取 / 设置（覆盖式，仅 C2C 全局生效）。
get_panel_list / create_panel / get_panel / set_panel / delete_panel / set_panel_targetget_panel_list.go / create_panel.go / get_panel.go / set_panel.go / delete_panel.go / set_panel_target.go-指令面板管理：列表 / 创建 / 详情 / 更新元素与备注 / 删除 / 增删关联对象（支持 c2c/group/channel/dm）。

消息事件扩展字段 ​

to_me 字段 ​

Gensokyo 在 q群 消息事件中增加了 to_me 字段，标识消息是否 @ 了机器人。

json
{
    "group_id": 123456,
    "message": [...],
    "to_me": true,   // 本版新增
    "user_id": 789012,
    ...
}

取值逻辑：

  • GROUP_AT_MESSAGE_CREATE（@消息事件）→ to_me: true 始终为 true
  • GROUP_MESSAGE_CREATE（普通 q群 消息事件）→ 检测 Mentions 中是否有 IsYou=true，有为 true，否则为 false

nonebot2 获取方式：

python
from nonebot import on_message
from nonebot.adapters.onebot.v11 import GroupMessageEvent

@on_message().handle()
async def handler(event: GroupMessageEvent):
    # 直接通过 event.to_me 获取
    if event.to_me:
        await event.finish("你@我了")

或者通过 raw event 获取：

python
event.json()  # 查看完整字段

非自身 @ 处理 ​

在 GROUP_MESSAGE_CREATE（普通 q群 消息）中，若内容包含对其他用户/机器人的 @，Gensokyo 会自动将原始 <@OpenID> 替换为标准的 [CQ:at,qq=虚拟ID] 格式，并建立 OpenID 与虚拟 ID 的映射。

这是一种 双向转换：

入站（QQ API → 后端）：
  QQ API:   <@B1FE88...> 贴贴
  后端收到: [CQ:at,qq=713011248] 贴贴

出站（后端 → QQ API）：
  后端发送 [CQ:at,qq=713011248] 贴贴
  QQ API:   <@!B1FE88...> 贴贴

规则：

  • 入站 @bot 从 content 中剥离（to_me = true）
  • 入站 @其他人 转为 [CQ:at,qq=虚拟ID]
  • 出站 [CQ:at,qq=数字]：纯文本消息转为 @用户名 （带空格），Markdown 消息转为 <qqbot-at-user id="OpenID" />
  • 纯文本出站时 @ 转为 @用户名 格式，用户名来自内存缓存（入站时自动缓存，10 分钟 TTL）

Markdown 中的 @ 能力 ​

在 Markdown 卡片（msg_type=2）内容中嵌入 [CQ:at,qq=数字]，Gensokyo 会自动将其转换为 QQ API 的 <qqbot-at-user> 标签，并且整个 messageText（含 <qqbot-at-user> 标签和文本内容）会合并到 Markdown 内容头部，确保文本不丢失。

nonebot2 示例：

python
from nonebot import on_command
from nonebot.adapters.onebot.v11 import Bot, Event, Message

@on_command("md_at").handle()
async def _(bot: Bot, event: Event):
    md_content = f"你好 [CQ:at,qq={event.user_id}]，欢迎使用！"
    md_seg = {"type":"markdown","data":{"data":md_content}}
    await bot.send(event, Message(md_seg))

Sender.Nickname 自动填充 ​

Gensokyo 在群消息和私聊消息中，当 card_nick 配置为空时，会自动从 QQ API 返回的 data.Author.Username 中提取用户名填充到 event.sender.nickname。

json
{
    "sender": {
        "nickname": "NIKO",   // 自动从 Author.Username 获取
        "user_id": 123456789,
        ...
    }
}

优先顺序：card_nick 配置 > Author.Username > 空

Sender.Role 身份标识 ​

群消息中 sender.role 字段会优先使用 QQ API 返回的 member_role，不再仅依赖 master_id 配置。

json
{
    "sender": {
        "user_id": 10000001,
        "role": "owner",
        "nickname": "群主"
    }
}

取值：

  • owner → 群主
  • admin → 管理员
  • member → 普通群员

API 未返回时回退到 master_id 配置判断，保持兼容。详见本版新增功能。

Gensokyo-NewQQ 配套 Web 文档站

Copyright © 2026-present Gensokyo Project