技術標準
總綱：適配器標準化指南 —— 標準化原則、標準地圖、命名規則、差異處理模式與開發者 CheckList。新適配器/新能力請先閱讀它。
本文檔包含 ErisPulse 的技術標準規範，確保各組件間的一致性和兼容性。
標準文件列表
- 會話類型標準 - ErisPulse 會話類型定義和映射規範
- 事件轉換標準 - 平台事件轉換規範、擴展命名規範、訊息段標準
- API 回應標準 - 適配器 API 回應格式標準及擴展要求
- 發送方法規範 - Send 類方法命名、參數規範及反向轉換要求
- 請求操作規範 - 請求事件欄位要求、HandleRequest DSL 及適配器實現要求
- 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 - 形態判定順序符合規範（bytes → URL →
file://→ 路徑） -
File的檔案名稱按推導順序生成（顯式filename> URL basename > 路徑 basename > 平台預設） - 平台媒體限制已在適配器文件中聲明
- 不支援的媒體類型按降級階梯處理（近緣類型降級或
retcode=10002，不拋出異常、不靜默丟棄）
詳細協定見 發送方法規範 §2.1
請求操作
- HandleRequest 類已實作 _do_accept / _do_reject
- 操作回傳標準 API 回應格式
- 不支援的操作回傳 retcode=10002