ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

CLI コマンドリファレンス

Tip

いつこのドキュメントを読むべきか:epsdk コマンドの引数を忘れたとき、コンポーネント管理をスクリプトに組み込みたいとき、run / stop / restart の挙動を制御したいときに参照してください。日常的に init / install / run しか使わないなら、これだけ覚えておけば十分です:epsdk <コマンド> --help でいつでも引数の説明を確認できるため、本文全体を読み通す必要はありません。

epsdk は ErisPulse のコマンドラインツールです。プロジェクトの初期化、モジュールとアダプターのインストール / アップグレード、コンポーネントの対話式設定、ボットの実行と停止、環境の診断が、この一つのコマンドで行えます。

ヒント:epsdk(コマンドなし)のメインヘルプはカテゴリ別にグループ化して表示されます:プロジェクト(init / create / run)、コンポーネント管理(install / uninstall / upgrade / list / list-remote / types)、設定と診断(config / doctor / i18n)、その他(self-update / version)。


パッケージ管理コマンド

コマンド エイリアス パラメータ 説明
install i, add [package]... [--upgrade/-U] [--pre] [-e PATH] [--user] [--no-deps] [-t DIR] [--index-url URL] [--extra-index-url URL] [--no-cache-dir] [-r FILE] [-c FILE] [--force-reinstall] [--ignore-installed] [--compile/--no-compile] [--prefix DIR] [--src DIR] [--config-settings SETTINGS] [--no-binary FORMAT] [--only-binary FORMAT] [--prefer-binary] [--build-isolation/--no-build-isolation] [--upgrade-strategy {eager,only-if-needed,to-satisfy-only}] [--break-system-packages] [--no-uv] モジュール/アダプターのインストール
uninstall rm, remove <package>... [--no-uv] モジュール/アダプターのアンインストール
upgrade up [package]... [--force/-f] [--pre] [--no-uv] 指定モジュールまたはすべてをアップグレード
self-update su, update [version] [--pre] [--force/-f] [--no-uv] SDK 自体を更新

診断コマンド

コマンド エイリアス パラメータ 説明
doctor diag [--verbose] [--fix] 環境を診断してヘルスレポートを出力。--fix で自動修復を試みる

install

ErisPulse モジュールまたはアダプターパッケージをインストールします。パッケージ名を指定しない場合は対話式インストール画面に入ります。

エイリアス: i, add

uv プロジェクト連携(2.11.1+):uv が管理するプロジェクト内(uv.lock または [tool.uv] が存在する場合)では、 install / upgrade / uninstall は自動的に uv add / uv remove に切り替わります——依存関係は pyproject.toml と uv.lock に同時に書き込まれ、uv sync で epsdk がインストールしたコンポーネントが消えることはなくなります。失敗した場合は自動的に uv pip / pip 経路へフォールバックします。--user など uv が対応していない引数は直接 pip を使用します。ターゲット環境の解決順序: ERISPULSE_PYTHON → UV_PROJECT_ENVIRONMENT → プロジェクトの .venv → UV_PYTHON → VIRTUAL_ENV → 現在のインタープリター(完全な判断チェーンは epsdk doctor で確認できます)。

パラメータ:

パラメータ 短縮形 説明
[package]... インストールするパッケージ名、複数指定可
--upgrade -U インストール時に最新バージョンへアップグレード
--pre プレリリース版のインストールを許可
--editable -e 編集可能モードでインストール(パス指定が必要)
--user ユーザーの site-packages ディレクトリにインストール
--no-deps 依存関係をインストールしない
--target -t 指定ディレクトリにインストール
--index-url PyPI ミラーソースのアドレスを指定
--extra-index-url 追加の PyPI ミラーソースアドレス(複数回指定可)
--no-cache-dir キャッシュを無効化
--requirement -r requirements ファイルからインストール
--constraint -c 制約ファイルからインストール
--force-reinstall 強制的に再インストール
--ignore-installed インストール済みパッケージを無視
--compile インストール後に .pyc ファイルをコンパイル
--no-compile インストール後に .pyc ファイルをコンパイルしない
--prefix 指定プレフィックスディレクトリにインストール
--src 編集可能インストール時に使用するソースディレクトリ
--config-settings ビルドバックエンドに渡す設定(複数回指定可)
--no-binary バイナリパッケージを使用しないよう制限(形式例 :all:)
--only-binary バイナリパッケージのみ使用に制限(形式例 :all:)
--prefer-binary バイナリパッケージを優先
--build-isolation ビルド分離を有効化
--no-build-isolation ビルド分離を無効化
--upgrade-strategy アップグレード戦略:eager、only-if-needed、to-satisfy-only
--break-system-packages システムパッケージマネージャーが管理する Python パッケージの変更を許可
--no-uv uv の代わりに pip を使用

例:

# 単一モジュールをインストール
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

パラメータ:

パラメータ 説明
<package>... アンインストールするパッケージ名、複数指定可
--no-uv uv の代わりに pip を使用

例:

# 単一モジュールをアンインストール
epsdk uninstall Weather

# 複数モジュールをアンインストール
epsdk uninstall Yunhu Weather

upgrade

インストール済みの ErisPulse コンポーネントをアップグレードします。パッケージ名を指定しない場合は対話式ですべてをアップグレードします。

エイリアス: up

パラメータ:

パラメータ 短縮形 説明
[package]... アップグレードするパッケージ名、複数指定可
--force -f 確認をスキップして強制アップグレード
--pre プレリリース版へのアップグレードを許可
--no-uv uv の代わりに pip を使用

例:

# すべてのパッケージをアップグレード
epsdk upgrade

# 指定したパッケージをアップグレード
epsdk upgrade Weather

# 強制アップグレード(確認をスキップ)
epsdk upgrade -f

self-update

ErisPulse SDK 自体を最新バージョンに更新します。

エイリアス: su, update

パラメータ:

パラメータ 短縮形 説明
[version] 更新先のターゲットバージョン番号を指定
--pre プレリリース版への更新を許可
--force -f 確認をスキップして強制更新
--no-uv uv の代わりに pip を使用

例:

# 最新安定版に更新
epsdk self-update

# 指定したバージョンに更新
epsdk self-update 1.2.3

# プレリリース版を許可
epsdk self-update --pre

# 強制更新
epsdk self-update -f

Note

uv tool install ErisPulse でインストールした場合、このコマンドは自動的に uv tool upgrade ErisPulse に切り替わります(バージョン指定時は uv tool install ErisPulse==<バージョン> --force)。pip で直接ツール環境をアップグレードすると、uv のマニフェスト復元によって消されてしまいます。 Windows での更新は新しいコンソールウィンドウで行われます:現在の CLI はツール環境ファイルの占有を解除するため先に終了する必要があり、ウィンドウに完了の表示が出たらターミナルを開き直してください。


情報照会コマンド

コマンド エイリアス パラメータ 説明
list l, ls [--type/-t {modules,adapters,all}] [--outdated/-o] インストール済みコンポーネントの一覧表示
list-remote lsr [--type/-t {modules,adapters,all}] [--refresh/-r] リモートで利用可能なコンポーネントの一覧表示
version ver SDK と Python のバージョン情報を表示(-V と同等)

list

インストール済みの ErisPulse モジュールとアダプターを一覧表示します。

エイリアス: l, ls

パラメータ:

パラメータ 短縮形 説明
--type -t タイプを指定:modules、adapters、all(デフォルト)
--outdated -o アップグレード可能なパッケージのみ表示

例:

# インストール済みのすべてのコンポーネントを一覧表示
epsdk list

# モジュールのみ一覧表示
epsdk list -t modules

# アダプターのみ一覧表示
epsdk list -t adapters

# アップグレード可能なパッケージのみ表示
epsdk list -o

list-remote

リモートリポジトリで利用可能な ErisPulse モジュールとアダプターを一覧表示します。

エイリアス: lsr

パラメータ:

パラメータ 短縮形 説明
--type -t タイプを指定:modules、adapters、all(デフォルト)
--refresh -r リモートパッケージリストのキャッシュを強制更新

例:

# リモートで利用可能なすべてのコンポーネントを一覧表示
epsdk list-remote

# リモートモジュールのみ一覧表示
epsdk list-remote -t modules

# キャッシュを強制更新してから一覧表示
epsdk list-remote -r

設定コマンド

コマンド エイリアス パラメータ 説明
config cfg, conf [name] [--list/-l] [--json] アダプター/モジュールの宣言的設定項目を対話式で設定

config

アダプター/モジュールの宣言的設定項目を対話式で入力します。ウィザードはアダプター/モジュールが宣言する設定クラス(ConfigClass / AccountConfigClass)によって駆動され、フォームを自動生成して検証するため、config.toml を手書きする必要はありません。

アダプターはさらにマルチアカウント(bot アカウント)管理に対応します:アカウントの追加/編集/削除、および有効/無効の切り替え。

エイリアス: cfg, conf

パラメータ:

パラメータ 短縮形 説明
[name] 対象名(アダプターのプラットフォーム名またはモジュール名)。空欄で対話選択へ
--list -l すべての対象の設定状態のみ一覧表示し、ウィザードには入りません
--json すべての対象とその設定状態を JSON で出力(CI / スクリプトで利用)。ウィザードには入りません

例:

# すべてのアダプター/モジュールの設定状態を確認
epsdk config --list

# 設定状態を JSON で出力(CI / スクリプトで利用)
epsdk config --json

# 対話式で対象を選択して設定
epsdk config

# 指定したアダプターを直接設定
epsdk config yunhu

# 指定したモジュールを直接設定
epsdk config MyModule

説明:

  • 設定状態は 4 段階に分かれます:準備完了(検証通過)、要改善(必須項目の欠落または検証失敗)、未設定(一度も生成されていない)、設定なし(対象が設定クラスを宣言していない)
  • フィールド値には出所ラベルが付きます:既存の設定がある場合は (現在:値) と表示され、未設定の場合は schema のデフォルト値 (デフォルト:値) が表示されます。そのまま Enter を押せばその値が保持されます
  • シークレット系フィールド(secret 宣言)は入力時にエコー表示されず、Enter で設定済みの値が保持されます
  • 対話選択モードでは、1 つのウィザード終了後に選択メニューへ戻ります(状態は更新済み)。複数の対象を連続して設定でき、空欄入力で終了します
  • グローバルフォームの検証に失敗して再入力を中止した場合、そのウィザードは中断され、いかなる設定も書き込まれません(「有効化されているが設定が不完全」な中途半端な状態の発生を回避)
  • 保存後、直ちに config/config.toml に書き込まれ、Dashboard と実行中の SDK のどちらからでも参照できます。実行中のアダプターが新しいアカウント設定を適用する必要がある場合は、プロセスを再起動するだけで反映されます
  • epsdk install(対話式インストール)と epsdk init でアダプターのインストールに成功した後、設定宣言が検出された場合は自動的に本ウィザードへ誘導します。コマンドラインでパッケージ名を直接指定してインストールした場合は、設定ヒントの表示のみ行われます

実行制御コマンド

Tip

epsdk run はプロジェクトディレクトリ下の .venv 仮想環境を自動検出してボットを実行します (ERISPULSE_PYTHON 環境変数でインタープリターを明示的に指定することも可能)。epsdk install / uninstall / upgrade / list も同様にプロジェクトの仮想環境に対して作用します。

コマンド エイリアス パラメータ 説明
run r [script] [--reload] [--strict/--no-strict] 指定スクリプトまたは SDK を実行
stop — [--force] [--pid PID] 実行中のインスタンスを停止(epsdk run で起動されたもの)
restart — [--force] [--pid PID] 実行中のインスタンスを再起動(停止後、元の引数で再起動)

run

ErisPulse プロジェクトのスクリプトを実行、または SDK を直接起動します。ホットリロードモードをサポートします。

エイリアス: r

パラメータ:

パラメータ 説明
[script] 実行するスクリプトファイル。未指定の場合は SDK を実行
--reload ホットリロードモードを有効化:ファイル変更を監視し、自動的にコンポーネントレベルのコードホットリロードをトリガー(プロセス全体の再起動は不要)。デフォルトでは .venv/.git などのディレクトリを無視(ErisPulse.framework.watch_ignore_dirs で設定可能)。プラグインディレクトリはプラグイン用ホットリロード watcher が正確に処理
--strict / --no-strict 厳格モードを一時的にオン / オフ(今回のみ有効、設定には書き込まない)。デフォルトは ErisPulse.framework.strict_mode に従う

例:

# SDK を直接実行
epsdk run

# 指定したスクリプトファイルを実行
epsdk run main.py

# ホットリロードモードで実行(ファイル変更で自動的にコードレベルのホットリロードをトリガー)
epsdk run main.py --reload

# SDK のホットリロードモード
epsdk run --reload

# 一時的な厳格モード:起動前セルフチェックに失敗したら即終了、フレームワークの厳格レベルは今回少なくとも 1 に引き上げられる
epsdk run main.py --strict

# 一時的な寛容モード(設定で strict_mode が有効だが、今回はとりあえず動かしたい場合)
epsdk run main.py --no-strict

起動前セルフチェック: run は起動前に、config/config.toml の解析可能性とインストール済みコンポーネントの必須設定の完全性を素早くチェックします。厳格さはデフォルトで ErisPulse.framework.strict_mode に従います(0 以外の場合はチェック失敗時に即終了、0 の場合は警告のみで続行)。設定ファイルの欠落は正常な初回起動とみなされ、通知のみで失敗とは判定されません。--strict で一時的に有効化:事前チェックに失敗すると即終了し、同時にフレームワークの厳格レベルは今回のみ少なくとも 1 に引き上げられます(非準拠コンポーネントをスキップ、ERISPULSE_FRAMEWORK_STRICT_MODE 環境変数を介して実行プロセスに伝達され、設定ファイルには書き込まれません);--no-strict はその逆で、一時的に寛容レベルへ下げます。セルフチェック自体に異常が発生した場合は自動的にスキップされ、ネットワーク検出は含まれないため、起動をブロックしません。

--reload の監督構造(2.11.1 以降):epsdk run --reload は「監督プロセス + リロード worker 子プロセス」として実行されます。.py ファイルの保存によってトリガーされるホットリロードはすべて worker 内で完了します(排他直列実行、ストーム統合);モジュール側の構文エラーは全体事前チェックで拒否され、旧インスタンスがサービスを継続します。sdk.hard_restart() が実行されると worker は終了コード 42 で終了し、監督プロセスが理由を表示した後、自動的にまったく新しい worker を再起動します——フレームワーク本体をアップグレードした後、新しいコードが即座に有効になります。

stop

実行中の ErisPulse インスタンス(epsdk run で起動され、同じプロジェクトディレクトリで実行されているもの)を停止します。 run は起動時に、監督プロセスの PID、現在のフレームワーク子プロセスの PID、元の起動コマンドを .erispulse/runtime.json に書き込み、stop はこれに基づいてインスタンスを特定します。

停止順序: POSIX ではまず監督プロセスに SIGINT を送信します(Ctrl+C と同じ優雅な終了パス—— finally チェーンが自動的にフレームワーク子プロセスを終了)。タイムアウト時は段階的に SIGTERM / SIGKILL へエスカレートします。Windows には プロセスシグナルのセマンティクスがないため、まずフレームワーク子プロセスを終了させてから監督プロセスを終了します(監督者が強制終了をクラッシュと誤判定して 再起動することを避けるため)。

パラメータ:

パラメータ 説明
--force 優雅な停止をスキップし、直接強制終了
--pid PID 対象プロセスの PID を直接指定(実行状態ファイルを上書き。非標準の起動方法用)

例:

# 現在のプロジェクトの実行インスタンスを停止
epsdk stop

# 強制終了
epsdk stop --force

restart

実行中の ErisPulse インスタンスを再起動します:stop のセマンティクスに従って停止した後、状態ファイルに記録された 元の起動コマンドで再起動します(フォアグラウンドで現在のターミナルを引き継ぎ、新しいインスタンスは新しい実行状態ファイルを書き込みます)。

パラメータ: stop と同じ(--force / --pid PID)。

例:

# 優雅な再起動(pip でアダプター/モジュールをアップグレードした後にコードを反映;実行中のモジュールは
# sdk.reload_module / sdk.adapter.reload によるコードレベルのホットリロードも可能で、再起動は不要)
epsdk restart

Note

python main.py など epsdk run をバイパスする起動方法では実行状態ファイルは書き込まれません——この種の プロセスはシステムツールで管理するか、epsdk stop --pid <PID> で PID を指定してください。


プロジェクト管理コマンド

コマンド エイリアス パラメータ 説明
init — [path] [--project-name/-n <name>] [--path <dir>] [--adapter/-a <name>] [--quick/-q] [--force/-f] [--here] [--no-uv] [--no-venv] ErisPulse プロジェクトの初期化
create — {module,adapter,pack} [--name/-n <name>] [--description/-d <desc>] [--author/-a <name>] [--email/-e <mail>] [--homepage <url>] [--output/-o <dir>] [--force/-f] [--local] モジュール/アダプターのスキャフォールドを作成;pack はローカルプラグインを公開可能なプロジェクトに変換

init

新しい ErisPulse プロジェクトを初期化します。対話式モードとクイックモードに対応し、2.8.4 以降は pyproject.toml(依存マニフェスト)を生成、オプションでプロジェクトの .venv 仮想環境を作成してフレームワークとアダプターをインストールし、任意のディレクトリ指定にも対応します。

パラメータ:

パラメータ 短縮形 説明
[path] ターゲットパス(親ディレクトリを含められます、例 ../apps/mybot。名前のみの場合は --project-name と同等)
--project-name -n プロジェクト名
--path プロジェクトの親ディレクトリ(-n と組み合わせて作成場所を指定)
--adapter -a プリインストールするアダプターを事前選択(繰り返し指定またはカンマ区切り可)。指定時はアダプターの問い合わせと選択をスキップ
--quick -q クイックモード、対話式ウィザードをスキップ(デフォルトで .venv を作成し依存関係をインストール)
--force -f 既存の設定ファイルを強制上書き
--here 現在のディレクトリで初期化し、サブディレクトリを作成しない
--no-uv uv の代わりに pip を使用
--no-venv 仮想環境の作成と依存関係のインストールをスキップ

例:

# 対話式で初期化
epsdk init

# クイック初期化(現在のディレクトリに my_bot/ を作成、pyproject.toml + .venv を含む)
epsdk init -q -n my_bot

# クイック初期化とアダプターのプリインストール(非対話、スクリプト / CI シナリオ向け)
epsdk init -q -n my_bot --adapter yunhu,telegram

# 任意のディレクトリを指定して初期化(../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 と選択したアダプターがその中にインストールされます。

Note

.gitignore はグループ化されたテンプレート:Python バイトコードとビルド成果物、仮想環境と .env、ツールキャッシュ、エディターとシステムファイルが含まれ、**config/ と logs/ のランタイムディレクトリを丸ごと除外**します——config.toml にはアダプターのトークンなどの機密情報が含まれるため、リポジトリへの登録は推奨されません。設定の雛形を共有する場合は config.full.example を使用してください。

Warning

uv run epsdk run でボットを実行しないでください。uv run は pyproject.toml が存在しないディレクトリで実行されると使い捨ての分離環境を作成します——そこで epsdk install によってインストールしたアダプターは永続化されません。プロジェクトディレクトリ内で epsdk run を使用するか(プロジェクトの .venv を自動使用)、先に仮想環境をアクティブ化してから実行してください。

create

ErisPulse モジュールまたはアダプターのスキャフォールドプロジェクトを作成します;pack サブコマンドはローカルプラグイン(plugins/ ディレクトリ)を公開可能な標準プロジェクトに変換します。

パラメータ:

パラメータ 短縮形 説明
{module,adapter,pack} 作成するタイプ:module / adapter / pack(プラグインをプロジェクトへ変換)
--name -n プロジェクト名(PascalCase)
--description -d プロジェクトの説明
--author -a 作者名
--email -e 作者のメールアドレス
--homepage プロジェクトのホームページ URL
--output -o 出力ディレクトリ(デフォルトは現在のディレクトリ)
--force -f 既存のディレクトリを強制上書き
--local ローカルプラグインを作成(module / adapter で使用可能):plugins/<name>/ パッケージ構造を生成、パッケージング不要のインストール

例:

# 対話式で作成(タイプの選択と情報入力をガイド)
epsdk create

# Module プロジェクトを直接作成
epsdk create module -n MyModule

# ローカルプラグインを作成(プロジェクトの plugins/ ディレクトリに配置され、起動時に自動検出)
epsdk create module -n MyModule --local

# ローカルアダプタープラグインを作成(同上、パッケージング不要の開発)
epsdk create adapter -n MyAdapter --local

# Adapter プロジェクトを直接作成
epsdk create adapter -n MyAdapter

# ローカルプラグインを公開可能なプロジェクトに変換(対話でプラグインを選択 → メタ情報を補完 → 標準プロジェクトを生成)
epsdk create pack

# 完全なパラメータ
epsdk create module -n MyModule -d "モジュールの説明" -a "作者" -e "[email protected]"

# 出力ディレクトリを指定
epsdk create module -n MyModule -o ./projects

# 既存のディレクトリを強制上書き
epsdk create module -n MyModule -f

言語コマンド

コマンド エイリアス パラメータ 説明
i18n language, lang [lang] [--list/-l] CLI の表示言語の確認または切り替え

i18n

現在の CLI 言語の確認、サポートされている言語の一覧表示、表示言語の切り替えを行います。引数を指定しない場合は対話式選択画面に入ります。

エイリアス: language, lang

パラメータ:

パラメータ 短縮形 説明
[lang] 切り替え先の言語コード(例:zh-CN、en、ja、ru)
--list -l サポートされているすべての言語を一覧表示

例:

# 対話式で言語を選択
epsdk i18n

# 英語に切り替え
epsdk i18n en

# 日本語に切り替え
epsdk i18n ja

# サポートされているすべての言語を一覧表示
epsdk i18n --list

型スタブコマンド

コマンド エイリアス パラメータ 説明
types t, stub [--output/-o <path>] [--force] [--adapters-only] [--modules-only] IDE 補完を有効にするための型スタブファイルを生成

types

インストール済みの ErisPulse モジュールとアダプターをスキャンし、それらに対して .pyi 型スタブファイルを生成することで、IDE で正確なコード補完と型チェックのサポートを受けられます。

エイリアス: t, stub

パラメータ:

パラメータ 短縮形 説明
--output -o 出力パス(デフォルトは現在のディレクトリの ep-stubs/)
--force 既存のスタブファイルを強制上書き
--adapters-only アダプターの型スタブのみ生成
--modules-only モジュールの型スタブのみ生成

注意: --adapters-only と --modules-only は相互に排他的で、同時に指定した場合は後者が有効になります。

例:

# インストール済みのすべてのモジュールとアダプターの型スタブを生成
epsdk types

# アダプターのスタブのみ生成
epsdk types --adapters-only

# 指定したディレクトリに出力
epsdk types -o ./typings

# 既存のファイルを強制上書き
epsdk types --force

グローバルパラメータ

以下のパラメータはすべてのコマンドに適用されます:

パラメータ 短縮形 説明
--help -h ヘルプ情報を表示
--version -V バージョン情報を表示
--verbose -v 詳細出力を表示(-vv/-vvv のように重ね掛け可能)
--no-color カラー出力を無効化(CI / ログ収集に適する)
--no-banner 起動 Banner をスキップ(スクリプトからの呼び出し / CI シナリオ向け。非対話ターミナルと ERISPULSE_NO_BANNER=1 の場合は自動的にサイレント化)
--yes -y すべての対話プロンプトを自動確認(非対話実行)

環境診断

doctor

Note

このコマンドには ErisPulse 2.7.0+ が必要です。

現在の CLI 実行環境を診断し、ヘルスレポートを出力します。「なぜインストールできない / 接続できない」類の問題の切り分けに使用します。

パラメータ 説明
--verbose 詳細な診断情報を表示
--fix 診断後に修復可能な問題の自動修復を試みる

チェック項目:

  • Python:インタープリターのバージョンとパス
  • インストールバックエンド:uv と pip のどちらを使用しているか
  • ターゲットインタープリター:パッケージが実際にインストールされるターゲットの Python 環境
  • 設定ファイル:config/config.toml が存在するか
  • コンポーネント設定:インストール済みコンポーネントの宣言的設定の完全性(「インストールしたのに動かない」の多くは必須項目の欠落が原因)
  • 設定汚染(2.11.1+):過去のアップグレードで残った残留キーをスキャン(旧バージョンのランタイムがバインドしていたシャドウ状態キー、遊離した設定セクション)。検出時は通知を表示
  • PyPI 接続性:PyPI にアクセスできるか(発見されたコンポーネント数も表示)
  • システムプロキシ:プロキシが検出されたかどうか

自動修復(--fix):

  • config.toml の欠落 → 現在の言語に基づいて初期設定ファイルを生成(init によるプロジェクト作成と同源)
  • コンポーネント設定が「要改善」 → 順番に対話式設定ウィザードを起動して必須項目を補完(非対話環境では epsdk config <名前> の使用を促すメッセージを表示)
  • 設定汚染の残留キー → 出所を明示した上で確認後に削除(tomlclass の可逆経路、コメントと順序は保持)
  • Python バージョンが低すぎる、PyPI にアクセスできないなど人手による介入が必要な問題 → 対処提案のみ出力
# 環境診断を実行
epsdk doctor

# エイリアスを使用
epsdk diag

# 診断して自動修復を試みる
epsdk doctor --fix

対話式インストール

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

次のステップ

  • コンポーネントをインストールしたら設定の入力が必要:epsdk config の対話式ウィザードを使用するか、設定ファイルの説明 で手動編集
  • コードを書いたら IDE 補完が欲しい:epsdk types を実行。詳細は 型スタブ生成 を参照
  • ボットが動かない:まず epsdk doctor で環境を診断し(環境診断 を参照)、長期的なデプロイの場合は デプロイガイド を参照