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

ErisPulse 轉接器標準化回傳規範

Tip

什麼時候需要讀這篇:當你在轉接器中實作 call_api / Send / Request 的回傳值,需要確認回應結構與回傳碼是否符合 ErisPulse 標準,或排查某個 retcode 的含義時對照本文。不需要則跳過。

1. 說明

為什麼會有這個規範?

為了確保各平台發送介面回傳的統一性與 OneBot12 的相容性,ErisPulse 適配器在 API 回應格式上採用了 OneBot12 定義的消息發送回傳結構標準。

但 ErisPulse 的協定有一些特殊性定義:

    1. 基礎欄位中,message_id 是必須的,但 OneBot12 標準中沒有此欄位
    1. 回傳內容中需要添加 {platform_name}_raw 欄位,用於存放原始回應資料

2. 基礎返回結構

所有動作回應必須包含以下基礎欄位:

欄位名 資料類型 必選 說明
status string 是 執行狀態,必須是"ok"或"failed"
retcode int64 是 返回碼,遵循OneBot12返回碼規則
data any 是 回應資料,成功時包含請求結果,失敗時為null
message_id string 是 消息ID,用於標識消息,沒有則為空字串
message string 是 錯誤資訊,成功時為空字串
{platform_name}_raw any 否 原始回應資料

可選欄位:

欄位名 資料類型 必選 說明
echo string 否 當請求中包含echo欄位時,原樣返回

3. 完整欄位規範

3.1 通用欄位

成功回應範例

{
    "status": "ok",
    "retcode": 0,
    "data": {
        "message_id": "1234",
        "time": 1632847927.599013
    },
    "message_id": "1234",
    "message": "",
    "echo": "1234",
    "telegram_raw": {...}
}

失敗回應範例

{
    "status": "failed",
    "retcode": 10003,
    "data": null,
    "message_id": "",
    "message": "缺少必要參數: user_id",
    "echo": "1234",
    "telegram_raw": {...}
}

3.2 回傳碼規範

0 成功(OK)

  • 0: 成功(OK)

1xxxx 動作請求錯誤(Request Error)

錯誤碼 錯誤名 說明
10001 Bad Request 無效的動作請求
10002 Unsupported Action 不支援的動作請求
10003 Bad Param 無效的動作請求參數
10004 Unsupported Param 不支援的動作請求參數
10005 Unsupported Segment 不支援的訊息段類型
10006 Bad Segment Data 無效的訊息段參數
10007 Unsupported Segment Data 不支援的訊息段參數
10101 Who Am I 未指定機器人帳號
10102 Unknown Self 未知的機器人帳號

2xxxx 動作處理器錯誤(Handler Error)

錯誤碼 錯誤名 說明
20001 Bad Handler 動作處理器實作錯誤
20002 Internal Handler Error 動作處理器執行時拋出例外

3xxxx 動作執行錯誤(Execution Error)

錯誤碼範圍 錯誤類型 說明
31xxx Database Error 資料庫錯誤
32xxx Filesystem Error 檔案系統錯誤
33xxx Network Error 網路錯誤
34xxx Platform Error 機器人平台錯誤
35xxx Logic Error 動作邏輯錯誤
36xxx I Am Tired 實現決定罷工

保留錯誤段

  • 4xxxx、5xxxx: 保留段,不應使用
  • 6xxxx~9xxxx: 其他錯誤段,供實現自訂使用

4. 實作要求

  1. 所有回應必須包含status、retcode、data和message欄位
  2. 當請求中包含非空echo欄位時,回應必須包含相同值的echo欄位
  3. 回傳碼必須嚴格遵循OneBot12規範
  4. 錯誤訊息(message)應當是人類可讀的描述

4.1 回應建構助手:make_response / make_error

轉接器建構標準回應統一用 BaseAdapter 上的兩個助手,不必手寫 dict:

# 成功(send / call_api / _do_accept 等所有回傳標準回應的位置)
return self.make_response(
    data=result,                    # 回應資料
    message_id=result.get("message_id", ""),
    raw=result,                     # 平台原始回應 → 自動掛到 {platform}_raw 欄位
)

# 失敗(status 固定 "failed")
return self.make_error(
    retcode=34100,                  # 預設 34600(SDK Failure);平台錯誤應傳自訂的 34xxx
    message="平台風控拒絕",
    raw=response,
)
助手 簽名 語意
make_response (*, status="ok", retcode=0, data=None, message_id="", message="", raw=None) 依標準結構組裝;raw 非 None 時自動掛 {platform}_raw 鍵(平台名取 self._platform)
make_error (retcode=34600, message="", raw=None) make_response(status="failed", ...) 的快捷方式

手寫等價 dict 亦合法(結構一致即可);助手的價值是 {platform}_raw 的平台名串接與欄位完整性不遺漏。

5. 擴充規範

ErisPulse 在 OneBot12 標準回傳結構之上做了以下擴充:

5.1 message_id 必選欄位

OneBot12 標準中 message_id 位於 data 物件內部且非強制。ErisPulse 將其提升為頂層必選欄位:

  • 無法取得 message_id 時應設為空字串 ""
  • 確保 message_id 始終存在,模組無需做 null 檢查

注意區分兩側:本節的頂層提升僅針對動作回應(出站)。入站 message 事件的 message_id 是 OneBot12 基線頂層必選欄位,見事件轉換標準。

5.2 {platform}_raw 原始回應欄位

回傳值中應包含 {platform}_raw 欄位,存放平台原始回應資料的完整副本:

{
    "status": "ok",
    "retcode": 0,
    "data": {"message_id": "1234", "time": 1632847927},
    "message_id": "1234",
    "message": "",
    "telegram_raw": {
        "ok": true,
        "result": {"message_id": 1234, "date": 1632847927, ...}
    }
}

要求:

  • {platform}_raw 必須是原始回應的深層複製,而非參考
  • platform 必須與轉接器註冊時的平台名稱完全一致(區分大小寫)
  • 原始回應中的錯誤訊息也應保留,便於偵錯

5.3 框架擴充回傳碼(34xxx 平台錯誤段的低三位自訂)

OneBot12 規範允許實作自訂 3xxxx 的低三位。34xxx 語意為 Platform Error (機器人平台錯誤,如平台限制導致失敗)。34xxx 內部按職責分層使用:

低三位段 歸屬 用途
340xx 轉接器實作 請求操作族(Request Not Found / Already Handled / Not Supported / Permission Denied,見 request-action-spec §7)
341xx~345xx 轉接器實作 平台側權限 / 風控 / 帳號限制等錯誤(實作自訂低三位,原始錯誤放 {platform}_raw)
346xx ErisPulse 框架(保留) 框架自身攔截與通用失敗,轉接器/模組請勿佔用
347xx~349xx 轉接器實作 其它平台執行錯誤

ErisPulse 框架目前使用的 346xx 碼:

錯誤碼 錯誤名 說明
34600 SDK Failure 框架通用失敗(make_error() 預設回傳碼)
34601 Action Denied 出站動作被作用域停用(scope.actions),呼叫未發起,直接回傳該回應

職責區分:34601 是框架在呼叫前攔截(模組根本沒資格發起動作); 34004 / 34xxx 平台碼是動作已發出但平台拒絕(如 Bot 無權限、被風控)。 模組判斷權限問題時同時檢查這兩種:先看 34601(自己模組被 scope 禁), 再看 34xxx(平台側限制)。

回傳結構為 §2 標準失敗回應:

{
    "status": "failed",
    "retcode": 34601,
    "data": null,
    "message_id": "",
    "message": "action 'send' denied by scope.actions"
}

5.4 轉接器實作檢查清單

  • 包含 status, retcode, data, message_id, message 欄位
  • 回傳碼遵循 OneBot12 規範(詳見 §3.2)
  • message_id 始終存在(無法取得時為空字串)
  • {platform}_raw 包含平台原始回應資料

6. 注意事項

  • 對於 3xxxx 錯誤碼,低三位可由實作自行定義
  • 避免使用保留錯誤段(4xxxx、5xxxx)
  • 34600 / 34601 為 ErisPulse 框架保留碼(見 §5.3),適配器/模組避免使用
  • 錯誤訊息應當簡潔明瞭,便於除錯

下一步

  • 實作各 DSL 回傳值時的配套對照:API 動作標準(標準動作的 data 欄位)、請求操作規範(請求操作的 34001-34004 擴充)、傳送方法規範(傳送失敗的降級語義)
  • 排查權限類失敗:先看 34601(模組被 scope 停用,框架在呼叫前攔截,見 §5.3),再看 34xxx(動作已發出但平台端拒絕)