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 --path ../apps

# 强制覆盖已有配置
epsdk init -f

# 在当前目录初始化
epsdk init --here -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

# 直接创建 Module 项目
epsdk create module -n MyModule

# 创建本地插件（放入项目 plugins/ 目录，启动时自动发现，支持热重载）
epsdk create module -n MyModule --local

# 直接创建 Adapter 项目
epsdk create adapter -n MyAdapter

# 完整参数
epsdk create module -n MyModule -d "模块描述" -a "作者" -e "[email protected]"

# 指定输出目录
epsdk create module -n MyModule -o ./projects

# 强制覆盖已有目录
epsdk create module -n MyModule -f

语言命令

i18n

查看当前 CLI 语言、列出支持的语言、切换显示语言。若不指定参数则进入交互式选择界面。

别名： language, lang

参数：

示例：

# 交互式选择语言
epsdk i18n

# 切换到英文
epsdk i18n en

# 切换到日文
epsdk i18n ja

# 列出所有支持的语言
epsdk i18n --list

类型存根命令

types

扫描已安装的 ErisPulse 模块和适配器，为它们生成 .pyi 类型存根文件，从而在 IDE 中获得准确的代码补全与类型检查支持。

别名： t, stub

参数：

注意： --adapters-only 与 --modules-only 互斥，同时指定时后者生效。

示例：

# 为所有已安装的模块和适配器生成类型存根
epsdk types

# 仅生成适配器存根
epsdk types --adapters-only

# 输出到指定目录
epsdk types -o ./typings

# 强制覆盖已有文件
epsdk types --force

全局参数

以下参数适用于所有命令：

环境诊断

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 adapters

# 只列出可升级的组件
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 --modules-only

初始化项目

# 交互式初始化
epsdk init

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

创建脚手架

# 交互式创建（引导选择类型和填写信息）
epsdk create

# 直接创建 Module 项目
epsdk create module -n MyModule

# 直接创建 Adapter 项目
epsdk create adapter -n MyAdapter

# 完整参数
epsdk create module -n MyModule -d "模块描述" -a "作者" -e "[email protected]"

# 强制覆盖已有目录
epsdk create module -n MyModule -f