CLI 命令參考

ErisPulse 命令行工具（epsdk）提供專案管理和套件管理功能。

提示：所有命令均可透過 epsdk <命令> --help 查看詳細的參數說明。

套件管理命令

臨床診斷命令

install

安裝 ErisPulse 模組或適配器套件。若不指定套件名則進入互動式安裝介面。

別名： i, add

參數：

示例：

# 安裝單個模組
epsdk install Weather

# 安裝多個模組
epsdk install Yunhu Weather

# 從鏡像來源安裝並升級
epsdk install Weather -U --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 可編輯模式安裝（開發模式）
epsdk install -e ./my-adapter

uninstall

卸載已安裝的 ErisPulse 模組或適配器套件。若不指定套件名則進入互動式卸載介面。

別名： rm, remove

參數：

示例：

# 卸載單個模組
epsdk uninstall Weather

# 卸載多個模組
epsdk uninstall Yunhu Weather

upgrade

升級已安裝的 ErisPulse 組件。不指定套件名則互動式升級全部。

別名： up

參數：

示例：

# 升級所有套件
epsdk upgrade

# 升級指定套件
epsdk upgrade Weather

# 強制升級（跳過確認）
epsdk upgrade -f

self-update

更新 ErisPulse SDK 本身到最新版本。

別名： su, update

參數：

示例：

# 更新到最新穩定版
epsdk self-update

# 更新到指定版本
epsdk self-update 1.2.3

# 允許預發布版本
epsdk self-update --pre

# 強制更新
epsdk self-update -f

資訊查詢命令

list

列出已安裝的 ErisPulse 模組和適配器。

別名： l, ls

參數：

示例：

# 列出所有已安裝的組件
epsdk list

# 只列出模組
epsdk list -t modules

# 只列出適配器
epsdk list -t adapters

# 只顯示可升級的套件
epsdk list -o

list-remote

列出遠端倉庫中可用的 ErisPulse 模組和適配器。

別名： lsr

參數：

示例：

# 列出所有遠端可用組件
epsdk list-remote

# 只列出遠端模組
epsdk list-remote -t modules

# 強制刷新快取後列出
epsdk list-remote -r

配置命令

config

互動式填寫適配器/模組的宣告式配置項。向導由適配器/模組宣告的配置類（ConfigClass / AccountConfigClass）驅動，自動產生表單並驗證，無需手寫 config.toml。

適配器額外支援多帳戶（bot 帳戶）管理：新增/編輯/刪除帳戶，以及啟用/停用開關。

別名： cfg, conf

參數：

示例：

# 查看所有適配器/模組的配置狀態
epsdk config --list

# 互動選擇目標進行配置
epsdk config

# 直接配置指定適配器
epsdk config yunhu

# 直接配置指定模組
epsdk config MyModule

說明：

• 配置狀態分為四檔：已就緒（驗證通過）、待完善（必填項缺失或驗證失敗）、未配置（從未生成）、無配置（目標未宣告配置類）
• 字段值帶來源標註：已有配置顯示 （目前:值），未配置時顯示 schema 預設值 （預設:值）；直接回車即保留該值
• 密鑰類字段（宣告 secret）輸入時不回顯，回車保留已設定的值
• 互動選擇模式下，單個向導結束後會回到選擇選單（狀態已刷新），可連續配置多個目標，留空退出
• 全局表單驗證失敗且放棄重新填寫時，本次向導中止且不寫入任何配置（避免產生"已啟用但配置不完整"的半成品狀態）
• 保存後立即寫入 config/config.toml，Dashboard 與運行中的 SDK 均可見；運行中的適配器如需應用新帳戶配置，重啟進程即可
• epsdk install（互動式安裝）與 epsdk init 安裝適配器成功後，若檢測到配置宣告會自動引導進入本向導；命令列直接指定套件名安裝時僅列印配置提示

運行控制命令

run

運行 ErisPulse 專案腳本或直接啟動 SDK。支援熱重載模式。

別名： r

參數：

示例：

# 直接運行 SDK
epsdk run

# 運行指定腳本檔案
epsdk run main.py

# 熱重載模式運行（檔案變更自動重啟）
epsdk run main.py --reload

# SDK 熱重載模式
epsdk run --reload

專案管理命令

init

初始化一個新的 ErisPulse 專案。支援互動式與快速模式，2.8.4 起生成 pyproject.toml（相依性清單）、可選建立專案 .venv 虛擬環境並安裝框架與適配器，並支援指定任意目錄。

參數：

示例：

# 互動式初始化
epsdk init

# 快速初始化（目前目錄下建立 my_bot/，含 pyproject.toml + .venv）
epsdk init -q -n my_bot

# 指定任意目錄初始化（../apps/mybot）
epsdk init ../apps/mybot

# 組合父目錄與專案名
epsdk init -n my_bot --路徑 ../apps

# 強制覆蓋已有配置
epsdk init -f

# 在目前目錄初始化
epsdk init --在這裡 -n my_bot

# 只生成專案結構，不建立虛擬環境
epsdk init --no-venv -n my_bot

init 產物：main.py、pyproject.toml（相依性清單）、config/config.toml + config.full.example、config/ssl/、logs/、.gitignore、README.md；選擇建立虛擬環境時額外生成 .venv 並將 erispulse 與所選適配器安裝其中。

create

建立 ErisPulse 模組或適配器的腳手架專案。

參數：

示例：

# 互動式建立（引導選擇類型和填寫資訊）
epsdk create

# 直接建立模組專案
epsdk create 模組 -n MyModule

# 建立本地插件（放入專案 plugins/ 目錄，啟動時自動發現，支援熱重載）
epsdk create 模組 -n MyModule --本地

# 直接建立適配器專案
epsdk create 適配器 -n MyAdapter

# 完整參數
epsdk create 模組 -n MyModule -d "模組描述" -a "作者" -e "[email protected]"

# 指定輸出目錄
epsdk create 模組 -n MyModule -o ./projects

# 強制覆蓋已有目錄
epsdk create 模組 -n MyModule -f

語言命令

i18n

查看目前 CLI 語言、列出支援的語言、切換顯示語言。若不指定參數則進入互動式選擇介面。

別名： language, lang

參數：

示例：

# 互動式選擇語言
epsdk i18n

# 切換到英文
epsdk i18n en

# 切換到日文
epsdk i18n ja

# 列出所有支援的語言
epsdk i18n --list

類型存根命令

types

掃描已安裝的 ErisPulse 模組和適配器，為它們生成 .pyi 類型存根檔案，從而在 IDE 中獲得準確的程式碼補全與類型檢查支援。

別名： t, stub

參數：

注意： --僅適配器 與 --僅模組 互斥，同時指定時後者生效。

示例：

# 為所有已安裝的模組和適配器生成類型存根
epsdk types

# 僅生成適配器存根
epsdk types --僅適配器

# 輸出到指定目錄
epsdk types -o ./typings

# 強制覆蓋已有檔案
epsdk types --強制

全局參數

以下參數適用於所有命令：

環境診斷

doctor

診斷目前 CLI 運行環境，輸出健康報告。用於排查"為什麼裝不上 / 連不上"類問題。

檢查項目：

• Python：解釋器版本與路徑
• 安裝後端：使用 uv 還是 pip
• 目標解釋器：套件實際安裝到的目標 Python 環境
• 配置檔案：config/config.toml 是否存在
• PyPI 連通性：能否存取 PyPI（並顯示發現的組件數）
• 系統代理：是否檢測到代理

# 運行環境診斷
epsdk doctor

# 使用別名
epsdk diag

互動式安裝

執行 epsdk install 不指定套件名時進入互動式安裝：

epsdk install

互動介面提供：

1. 適配器選擇
2. 模組選擇
3. 自訂安裝

常見用法

安裝模組

# 安裝單個模組
epsdk install Weather

# 安裝多個模組
epsdk install Yunhu Weather

# 升級模組
epsdk install Weather -U

列出組件

# 列出所有組件
epsdk list

# 只列出適配器
epsdk list -t 適配器

# 只列出可升級的組件
epsdk list -o

# 查看遠端可用組件
epsdk list-remote

卸載組件

# 卸載單個組件
epsdk uninstall Weather

# 卸載多個組件
epsdk uninstall Yunhu Weather

配置組件

# 查看配置狀態
epsdk config --list

# 互動選擇目標配置
epsdk config

# 配置指定適配器
epsdk config yunhu

升級組件

# 升級所有組件
epsdk upgrade

# 升級指定組件
epsdk upgrade Weather

# 強制升級
epsdk upgrade -f

運行專案

# 普通運行
epsdk run main.py

# 熱重載模式
epsdk run main.py --reload

切換語言

# 互動式選擇語言
epsdk i18n

# 直接切換到英文
epsdk i18n en

# 列出支援的語言
epsdk i18n --list

生成類型存根

# 生成所有類型存根
epsdk types

# 僅生成模組類型存根
epsdk types --僅模組

初始化專案

# 互動式初始化
epsdk init

# 快速初始化
epsdk init -q -n my_bot

建立腳手架

# 互動式建立（引導選擇類型和填寫資訊）
epsdk create

# 直接建立模組專案
epsdk create 模組 -n MyModule

# 直接建立適配器專案
epsdk create 適配器 -n MyAdapter

# 完整參數
epsdk create 模組 -n MyModule -d "模組描述" -a "作者" -e "[email protected]"

# 強制覆蓋已有目錄
epsdk create 模組 -n MyModule -f