OneBot v12 适配¶

v12还未启用

v12目前的实现还未经验证, 代码中暂时未启用

OneBot v12¶

Action	状态	说明
`get_supported_actions`	✅	获取支持的 action。
`get_latest_events`	✅	获取 adapter 内最近缓存的事件。
`get_status`	✅	返回在线状态。
`get_version`	✅	返回 app / 协议版本信息。
`send_message`	✅	发送私聊或频道消息。
`delete_message`	✅	撤回消息。
`recall_message`	✅	`delete_message` 别名。
`delete_msg`	✅	`delete_message` 兼容别名。
`get_self_info`	✅	获取当前 bot 信息。
`get_user_info`	✅	获取用户信息。
`get_friend_list`	✅	获取好友/私聊相关列表。
`get_guild_info`	✅	获取 Oopz area 信息。
`get_guild_list`	✅	获取 Oopz area 列表。
`set_guild_name`	✅	设置 area 名称。
`get_guild_member_info`	✅	获取 area 成员信息。
`get_channel_info`	✅	获取频道信息。
`get_channel_list`	✅	获取频道列表。
`set_channel_name`	✅	设置频道名称。
`get_channel_member_info`	✅	获取频道成员信息。
`get_channel_member_list`	✅	获取频道成员列表。
`cleanup_message_mapping`	✅	清理旧 message mapping。

主要文件¶

文件	职责
`adapter.py`	v12 action 注册、调用 Oopz service、保存消息映射、事件广播。
`event.py`	Oopz Event 转 OneBot v12 Event。
`message.py`	Oopz 消息段与 v12 消息段互转。
`types.py`	v12 response、消息映射、时间解析、参数校验。
`server.py`	v12 server 兼容导出。

self 信息¶

v12 使用 self 对象标识当前机器人：

{
  "platform": "oopz",
  "user_id": "OOPZ_SELF_UID"
}

对应配置：

from oopz_sdk import OneBotV12Config

onebot_v12 = OneBotV12Config(
    enabled=True,
    platform="oopz",
    self_id="OOPZ_SELF_UID",
)

如果 self_id 为空，会使用 OopzConfig.person_uid。

消息事件¶

频道消息：

{
  "type": "message",
  "detail_type": "channel",
  "message_id": "oopz:xxxxxxxxxxxxxxxxxxxxxxxx",
  "guild_id": "OOPZ_AREA_ID",
  "channel_id": "OOPZ_CHANNEL_ID",
  "user_id": "OOPZ_USER_UID",
  "message": [
    {"type": "text", "data": {"text": "hello"}}
  ],
  "alt_message": "hello"
}

私聊消息：

{
  "type": "message",
  "detail_type": "private",
  "message_id": "oopz:xxxxxxxxxxxxxxxxxxxxxxxx",
  "user_id": "OOPZ_USER_UID",
  "message": [
    {"type": "text", "data": {"text": "hello"}}
  ],
  "alt_message": "hello"
}

发送频道消息¶

{
  "action": "send_message",
  "params": {
    "detail_type": "channel",
    "guild_id": "OOPZ_AREA_ID",
    "channel_id": "OOPZ_CHANNEL_ID",
    "message": [
      {"type": "text", "data": {"text": "hello"}}
    ]
  }
}

返回：

{
  "status": "ok",
  "retcode": 0,
  "data": {
    "message_id": "oopz:xxxxxxxxxxxxxxxxxxxxxxxx",
    "time": 1777629501.0,
    "original_message_id": "OOPZ_ORIGINAL_MESSAGE_ID"
  }
}

发送私聊消息¶

{
  "action": "send_message",
  "params": {
    "detail_type": "private",
    "user_id": "OOPZ_USER_UID",
    "message": "hello"
  }
}

回复消息¶

v12 reply 消息段里的 message_id 应传 OneBot adapter 返回或事件上报的内部 message_id：

{
  "action": "send_message",
  "params": {
    "detail_type": "channel",
    "guild_id": "OOPZ_AREA_ID",
    "channel_id": "OOPZ_CHANNEL_ID",
    "message": [
      {"type": "reply", "data": {"message_id": "oopz:xxxxxxxxxxxxxxxxxxxxxxxx"}},
      {"type": "text", "data": {"text": "收到"}}
    ]
  }
}

adapter 会通过 SQLite 映射找回 Oopz 原始 messageId，再作为 reference_message_id 发送。

撤回消息¶

{
  "action": "delete_message",
  "params": {
    "message_id": "oopz:xxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

如果映射存在，adapter 会自动选择：

私聊：recall_private_message；
频道：recall_message。

如果映射不存在，也可以传 Oopz 原始 message ID 和频道上下文作为 fallback：

{
  "action": "delete_message",
  "params": {
    "message_id": "OOPZ_ORIGINAL_MESSAGE_ID",
    "guild_id": "OOPZ_AREA_ID",
    "channel_id": "OOPZ_CHANNEL_ID"
  }
}

消息段支持¶

v12 segment	发送到 Oopz 时的处理
`text`	纯文本。
`mention` / `at`	转为 Oopz mention 文本与 `mention_list`。
`mention_all` / `at_all`	转为全体提及。
`reply`	读取 `message_id`，作为 `reference_message_id`。
`image`	支持本地文件、Oopz `file_key`、带 URL 的图片资源。
其他类型	降级为文本占位，避免静默丢消息。

图片示例：

[
  {"type": "text", "data": {"text": "图片："}},
  {"type": "image", "data": {"file_id": "file:///tmp/a.png"}}
]

也可以直接使用 Oopz 上传后的 file_key：

[
  {"type": "image", "data": {"file_id": "OOPZ_FILE_KEY", "url": "https://..."}}
]