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

類型存根生成(IDE 補全)

Tip

何時需要閱讀本文:當 IDE 補全無法顯示適配器的平台特定方法(如雲湖的 Board)或模組的自訂方法時,只需執行一條 epsdk types 命令生成類型存根即可解決;若不需要則可跳過。

ErisPulse 透過 entry-points 動態發現模組/適配器,入口點無法在靜態層面得知使用者類別的具體類型。
epsdk types 命令透過掃描已安裝的模組/適配器,生成一個類型存根檔案,讓使用者可以將這些類型作為變數標註,進而獲得 IDE 補全功能。

核心設計原則

存根檔案只導出類型,不提供任何執行時實例:

  • 所有匯入都在 TYPE_CHECKING 下,零執行時開銷、零行為改變
  • 類型名採用 entry-point 名的 PascalCase 形式(如 yunhu → Yunhu),與傳入 sdk.adapter.get() / sdk.module.get() 的名稱對應
  • 使用者在程式碼中照常用 sdk.module.get(...) / sdk.adapter.get(...) 取得實例,只是用匯入的類型做變數標註

基本用法

在專案根目錄執行:

epsdk types

會在當前目錄產生 _ep_types.py,包含所有已安裝模組/適配器的類型。

在程式碼中使用

from _ep_types import MyModule, Yunhu
from ErisPulse import sdk

# 使用導入的類型作為變數標註,即可讓 IDE 自動補全該類的方法
my_mod: MyModule = sdk.module.get("MyModule")
my_mod.hello()                  # ← IDE 自動補全 hello

my_adapter: Yunhu = sdk.adapter.get("yunhu")
await my_adapter.Send.To("group", "123").Board(...)   # ← 自動補全平台特有方法

工作原理

  1. 掃描 erispulse.adapter / erispulse.module entry-points
  2. 透過子進程在目標 Python 環境中內省,收集每個適配器/模組的實際類資訊(包含模組路徑與限定名)
  3. 產生 .py 檔,其中:
    • 所有 from xxx import Yyy as Zzz 都在 TYPE_CHECKING 下
    • Zzz 是 entry-point 名的 PascalCase 形式
  4. IDE 讀取 TYPE_CHECKING 部分提供補全;執行時不執行任何程式碼

產生的存根範例:

# _ep_types.py(自動產生)
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    # 適配器
    from MyAdapter.Core import MyAdapter as MyAdapter
    from YunhuAdapter.Core import YunhuAdapter as Yunhu

    # 模組
    from MyModule.Core import Main as MyModule

    __all__ = ['MyAdapter', 'Yunhu', 'MyModule']

命令選項

選項 說明
-o, --output PATH 指定輸出檔案路徑(預設 ./_ep_types.py)
--force 覆蓋已存在的存根檔案
--adapters-only 僅掃描適配器
--modules-only 僅掃描模組

何時重新產生

  • 安裝/解除安裝新的模組或適配器後
  • 模組/適配器更新了公開 API 後
  • IDE 自動完成失效或類型過期時

與 SendDSL 標準方法的關係

SendDSL 基類已內建標準發送方法(Text/Image/Voice/Video/File),無論以何種方式取得的 SendDSL 實例都能補全這些方法。
types 命令主要用於補全平台特有方法(如雲湖的 Board、沙盒的 Dice)以及模組特有方法。

下一步

  • 想知道哪些發送方法所有平台通用:請參閱 SendDSL 詳解,獲取 Text / Image / Voice 等標準方法的權威說明
  • 正在開發自己的適配器:請從 適配器開發入門 開始建立適配器項目