技術標準
Tip
什麼時候需要讀這篇:當你在開發或修改適配器,需要確認事件轉換、API 回應、傳送方法等是否符合 ErisPulse 跨平台標準時,從本目錄找對應規範對照。不確定從哪篇開始時,先讀下方總綱。
總綱:適配器標準化指南 —— 標準化原則、標準地圖、命名規則、差異處理模式與開發者 Checklist。新適配器/新能力請先讀它。
本文件包含 ErisPulse 的技術標準規範,確保各元件間的一致性和相容性。
標準文件列表
- 會話類型標準 - ErisPulse 會話類型定義和映射規範
- 事件轉換標準 - 平台事件轉換規範、擴展命名規範、訊息段標準
- API 回應標準 - 適配器 API 回應格式標準及擴展要求
- 發送方法規範 - Send 類方法命名、參數規範及反向轉換要求
- 請求操作規範 - 請求事件欄位要求、Request DSL(approve/reject)、異構端點的請求類型上下文留存及適配器實現要求
- API 動作標準 - OneBot12 標準 API 動作統一介面(使用者/群組/頻道/訊息管理/檔案含分片/元動作)
- 適配器標準化指南(總綱) - 標準化原則/工作流程/命名規則 + 互動元件標準(按鈕鍵盤/互動回調事件)與各平台映射
標準概述
ErisPulse 採用 OneBot12 作為核心事件標準,並在此基礎上進行了擴充和細化。
核心原則
- 相容性:所有標準都必須與 OneBot12 標準保持相容
- 擴充性:平台特有功能透過前綴方式擴充,避免衝突
- 一致性:時間戳、ID 格式等關鍵欄位需要統一處理
- 可追溯性:保留原始資料以便偵錯和問題排查
為什麼需要標準?
1. 確保跨平台相容
不同平台的事件格式各不相同,標準化的轉換確保:
- 模組程式碼只需撰寫一次,即可在所有平台執行
- 事件處理邏輯保持一致
- 降低開發和維護成本
2. 規範 API 介面
統一的 API 回應格式確保:
- 模組可以一致地處理 API 錯誤
- 錯誤資訊統一且易於理解
- 回傳資料結構一致
3. 提升程式碼品質
標準規範幫助:
- 保持程式碼風格一致
- 減少命名衝突
- 提升程式碼可讀性
遵循標準的好處
對適配器開發者
- 清晰的轉換規則
- 統一的回應格式
- 易於偵錯和測試
對模組開發者
- 一致的事件介面
- 可預測的 API 行為
- 簡化的跨平台開發
對最終使用者
- 穩定的系統行為
- 統一的訊息格式
- 良好的相容性
標準遵循檢查清單
事件轉換
- 所有標準字段已正確映射
- 平台特有字段已添加前綴
- 時間戳已轉換為10位秒級
- 原始數據保存在 {platform}_raw
- 原始事件類型保存在 {platform}_raw_type
- 消息段的 alt_message 已生成
- 請求事件包含 request_id 字段
API 响應
- 包含 status 字段
- 包含 retcode 字段
- 包含 data 字段
- 包含 message_id 字段
- 包含 message 字段
- 返回碼遵循 OneBot12 規範
發送方法命名
- 使用大駝峰命名法(PascalCase)
- 返回 Task 對象
- 修飾方法返回 self
- 參數命名符合規範
媒體發送(Image / Voice / Video / File)
-
file參數必須形態全部支援:HTTP(S) URL / 本地路徑 /bytes -
file參數應當形態盡量支援:file://URI / Base64 / Data URI(無法支援時按降級階梯返回retcode=10002) - 形態判定順序符合規範(bytes → URL →
file://→ 路徑) -
File的檔案名按推導順序生成(顯式filename> URL basename > 路徑 basename > 平台預設) - 平台媒體限制已在適配器文件中聲明
- 不支援的媒體類型按降級階梯處理(近緣類型降級或
retcode=10002,不拋異常、不靜默丟棄)
詳細協議見 發送方法規範 §2.1
請求操作
- Request 內部類已重寫 _do_accept / _do_reject(公開入口 accept()/reject() 勿重寫)
- 操作返回標準 API 响應格式
- 不支援的操作返回 retcode=10002