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()