ErisPulse ErisPulse
在互動式文檔中心打開 →
本頁章節
本文為靜態鏡像,內容以互動版為準 在互動式文檔中心打開 →

技術標準

Tip

什麼時候需要讀這篇:當你在開發或修改適配器,需要確認事件轉換、API 回應、傳送方法等是否符合 ErisPulse 跨平台標準時,從本目錄找對應規範對照。不確定從哪篇開始時,先讀下方總綱。

總綱:適配器標準化指南 —— 標準化原則、標準地圖、命名規則、差異處理模式與開發者 Checklist。新適配器/新能力請先讀它。

本文件包含 ErisPulse 的技術標準規範,確保各元件間的一致性和相容性。

標準文件列表

  1. 會話類型標準 - ErisPulse 會話類型定義和映射規範
  2. 事件轉換標準 - 平台事件轉換規範、擴展命名規範、訊息段標準
  3. API 回應標準 - 適配器 API 回應格式標準及擴展要求
  4. 發送方法規範 - Send 類方法命名、參數規範及反向轉換要求
  5. 請求操作規範 - 請求事件欄位要求、Request DSL(approve/reject)、異構端點的請求類型上下文留存及適配器實現要求
  6. API 動作標準 - OneBot12 標準 API 動作統一介面(使用者/群組/頻道/訊息管理/檔案含分片/元動作)
  7. 適配器標準化指南(總綱) - 標準化原則/工作流程/命名規則 + 互動元件標準(按鈕鍵盤/互動回調事件)與各平台映射

標準概述

ErisPulse 採用 OneBot12 作為核心事件標準,並在此基礎上進行了擴充和細化。

核心原則

  1. 相容性:所有標準都必須與 OneBot12 標準保持相容
  2. 擴充性:平台特有功能透過前綴方式擴充,避免衝突
  3. 一致性:時間戳、ID 格式等關鍵欄位需要統一處理
  4. 可追溯性:保留原始資料以便偵錯和問題排查

為什麼需要標準?

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

相關文件