Oopz 平台特性文档

文档信息

基本信息

• 适配器类：OopzAdapter（entry-point oopz）
• 接入方式：WebSocket（wss://ws.oopz.cn）+ REST 网关（https://gateway.oopz.cn），RSA 签名请求头 + JWT
• 凭据：「账密二选一」——password（手机号+密码+客户端私钥，自动登录续期，推荐）或 token（uid/JWT/device_id/私钥四件套，仅密码登录被风控时的备用，JWT 过期需手动重新提取）
• 多账户：支持（[Oopz_Adapter.accounts.<name>]），事件 self.account_id 标记来源
• 框架软依赖：ErisPulse ≥ 2.7.1

会话模型

标准化对齐（0.1.0）

错误码规范

响应结构

所有响应含 status / retcode / data / message_id / message / oopz_raw；发送响应 message_id 取自平台返回的 messageId；data.self_info.user_id 在 get_self_info 中回填。

事件字段完备性

• 所有事件必备 id / time / type / detail_type / sub_type / platform / self，且 oopz_raw + oopz_raw_type 永远存在
• 消息事件顶层必带 message_id；时间戳微秒字符串统一归一为秒
• 事件 id 账户域去重（<account>:<类型>:<平台ID>）
• 未知事件转 type="unknown" + warning，不静默丢弃
• 协议内部帧（握手/认证/心跳/订阅）不产生平台事件

降级语义

• voice/audio/video/file 发送段 → retcode=10002（平台仅支持图片上传），不抛异常
• guild 发送目标 → retcode=10003（请指定频道）
• token 模式 JWT 失效 → retcode=34100 提示更新凭据；password 模式自动重登后重试一次

支持的消息发送类型

标准 API 动作（ApiDSL）

支持的标准动作

get_self_info、get_user_info、get_friend_list、get_group_info（频道+所属域合并信息）、get_group_list（已加入域的频道扁平表）、get_guild_info、get_guild_list、get_channel_list、get_guild_members、delete_message（需 channel_id 或 user_id 上下文）、get_file（附件 URL → base64）、leave_guild、get_status、get_version、get_supported_actions

不支持的标准动作（retcode=10002）

send_message（走 Send DSL）、upload_file、get_latest_events、set_group_name、set_group_admin、set_group_leave、set_group_card、leave_group、leave_channel

平台扩展动作（oopz.*）

好友申请处理

• 事件：request/friend，request_id 为无状态复合键 <target>:<friendRequestId>
• event.approve() / event.reject() → POST /client/v1/friendship/v1/response
• 单端点同构，无需请求类型上下文留存表

发送方法返回值

{
  "status": "ok",
  "retcode": 0,
  "data": {"message_id": "14283..."},
  "message_id": "14283...",
  "message": "",
  "oopz_raw": {"messageId": "14283...", "timestamp": "..."}
}

特有事件类型

• 消息事件扩展字段：oopz_area_id、guild_id（频道消息）；oopz_reference_message_id（回复）
• 通知扩展：oopz_edited_text、oopz_emoji、oopz_reaction_type、oopz_persons、oopz_from_channel、oopz_channel_name、oopz_channel_type、oopz_area_name、oopz_role_id、oopz_role_name、oopz_ban_until、oopz_login_state
• EventMixin 便捷方法：get_raw_event()、get_area_id()、get_edited_text()、get_emoji()、get_reaction_type()、get_voice_persons()