このドキュメントでは、Telegraph公開プラグインの作成を例に、ゼロからのDifyプラグイン開発に関する詳細なチュートリアルを提供します。環境準備、プロジェクト初期化、仮想環境設定、プラグインコアロジック開発、ローカル実行デバッグ、プラグインメタ情報整備、パッケージ化と公開といった手順が含まれます。
LLM 向けの説明: ここで私たちが作成したプロンプトを使用して、プラグイン開発を支援することもできます:Dify プラグイン開発:プロンプト始める前に、いつでも私たちが提供する 開発者向けチートシート (Cheatsheet) でよく使われるコマンドや情報を確認したり、より複雑な問題に遭遇した場合には完全な開発者ドキュメントを参照したりすることができます。
dify-plugin-daemon
または「プラグイン開発SDK」とも呼ばれます。より詳細な開発環境準備ガイドについては、開発ツールの初期化 を参照してください。
dify-plugin-darwin-arm64
と仮定します。ターミナルで、ファイルが存在するディレクトリに移動し、以下のコマンドを実行して実行権限を付与します:
chmod +x <downloaded_filename>
コマンドを実行してください。
.exe
ファイルをダウンロードした後、通常は直接実行できます。
./dify-plugin-darwin-arm64
をダウンロードした実際のファイル名またはパスに置き換えてください):
v0.0.1-beta.15
)が正常に出力されれば、インストールは成功です。
ヒント (Tips):便宜上、このドキュメントでは以降、Dify プラグイン開発 CLI コマンドの例として
- macOS のセキュリティ警告: macOS で初めて実行する際に「Apple は検証できません」または「開けません」と表示された場合は、「システム設定」→「プライバシーとセキュリティ」→「セキュリティ」セクションに移動し、関連するメッセージを見つけて「それでも開く」または「許可」をクリックしてください。
- コマンドの簡略化: ダウンロードしたバイナリファイル名を短い名前(例:
dify
やdify-plugin
)に変更すると、後の使用が便利になります。例:mv dify-plugin-darwin-arm64 dify
、その後は./dify version
で使用できます。- グローバルインストール(オプション): システムのどのパスからでも直接コマンドを実行できるようにしたい場合(例:
./dify
ではなく直接dify
と入力する)、名前変更後のファイルをシステムのPATH
環境変数に含まれるディレクトリ(例:/usr/local/bin
(macOS/Linux))に移動するか、Windows の環境変数に追加します。
- 例 (macOS/Linux):
sudo mv dify /usr/local/bin/
- 設定完了後、ターミナルで直接
dify version
と入力すると、バージョン番号が正常に出力されるはずです。
./dify
を使用します。ご自身の実際の状況に合わせてコマンドを置き換えてください。
telegraph
your-name
A Telegraph plugin that allows you to publish your content easily
Select language
と表示されたら、python
を選択してください。
Select plugin type
と表示されたら、このチュートリアルでは tool
を選択してください。
telegraph
(または指定したプラグイン名)という名前の新しいフォルダが表示され、これがプラグインプロジェクトになります。
venv
にすることを推奨します)
(venv)
と表示されます。
requirements.txt
ファイルには、プラグイン開発に必要な基本ライブラリ dify_plugin
が含まれています。仮想環境をアクティベートした後、以下のコマンドを実行してインストールします:
telegraph
フォルダを VSCode で開きます。Cmd+Shift+P
, Windows/Linux: Ctrl+Shift+P
)。Python: Select Interpreter
と入力して選択します。.venv/bin/python
または venv\Scripts\python.exe
が含まれます)。リストに自動的に表示されない場合は、Enter interpreter path...
を選択して手動で検索できます。requirements.txt
ファイルを検出し、その中の依存関係をインストールするよう促すことがあります。プロンプトが表示されたら、インストールを確認してください。
pip install
コマンドと python -m main
の実行操作は、アクティベートされた仮想環境で実行してください。
your-telegraph
your-telegraph
という名前の Python ライブラリを使用して Telegraph API とやり取りします。(これは仮のライブラリ名です。実際に使用するライブラリが有効であることを確認してください)。
your-telegraph
は、Telegraph API の操作を簡略化する Python ラッパーで、数行のコードで簡単にコンテンツを公開できます。
その基本的な使い方は以下のようになるかもしれません:
requirements.txt
の更新: プロジェクトルートディレクトリにある telegraph/requirements.txt
ファイルを開き、dify_plugin
の下に、先ほどインストールしたライブラリ名を一行追加します:
telegraph_access_token
が必要です。プロバイダー設定でこの認証情報を定義し、ユーザーがプラグインを使用する際に入力できるようにする必要があります。プロバイダー設定の詳細については、一般仕様定義 を参照してください。
telegraph/provider/telegraph.yaml
ファイルを開きます。
credentials_for_provider
の追加: ファイルの末尾(または適切な場所)に以下の内容を追加します:
telegraph_access_token
: 認証情報の一意の識別子。コード内では self.runtime.credentials["telegraph_access_token"]
を介してユーザーが入力した値にアクセスします。type: secret-input
: Dify UI 上でパスワード入力フィールドとして表示されます。required: true
: ユーザーがこのプラグイン提供のツールを使用するには、この認証情報を入力する必要があります。label
, placeholder
, help
: 多言語対応の UI テキストを提供します。url
: (オプション) 認証情報取得のためのヘルプリンクを提供します。telegraph/tools/telegraph.py
を開きます。
_invoke
メソッドの実装: ファイルの内容を以下のコードに置き換えます:
self.runtime.credentials
から認証情報を取得します。tool_parameters
からツールの入力パラメータを取得します(パラメータ名は次のステップの YAML で定義します)。.get()
を使用する方が堅牢な方法です。ytelegraph
ライブラリを呼び出して実際の操作を実行します。try...except
を使用して起こりうるエラーをキャッチし、例外をスローします。yield self.create_link_message(url)
を使用して URL を含む結果を Dify に返します。telegraph/tools/telegraph.yaml
を開きます。
identity
: ツールの基本情報、name
は一意の識別子です。description
: human
(ユーザー向け) と llm
(Agent 向け) に分かれます。llm
の説明は、Agent がツールを正しく理解して使用できるかどうかにおいて非常に重要です。parameters
: 各入力パラメータを定義します。
name
: 内部名、Python コードの tool_parameters.get("...")
のキーと一致する必要があります。type
: データ型 (例: string
, number
, boolean
など)。required
: 提供が必須かどうか。label
, human_description
, llm_description
: identity
の説明と同様ですが、特定のパラメータに対するものです。llm_description
は、LLM がそのパラメータの値をどのように生成または取得するか(ここでの Markdown のようなフォーマット要件を含む)を明確に指示する必要があります。form
: パラメータが Dify でどのように表示され、入力されるかを定義します。llm
は、そのパラメータ値をユーザーが入力したり、変数を介して渡したり、Agent モードで LLM が自律的に決定したりできることを示します。form
は通常、ユーザーが UI 上で固定的に入力する必要がある設定項目を示します。ツール入力の場合、llm
の方が一般的です。extra.python.source
: このツールのロジックを実装する Python ファイルのパス(プロジェクトルートディレクトリからの相対パス)を示します。telegraph/provider/telegraph.py
を開きます。
_validate_credentials
メソッドの実装: ファイルの内容を以下に置き換えます:
credentials
辞書から認証情報を取得します。ToolProviderCredentialValidationError
をスローし、元のエラーメッセージを含めます。.env
ファイルの準備:
telegraph
プロジェクトディレクトリにいることを確認してください。
.env
ファイルの編集: 作成したばかりの .env
ファイルを開き、Dify 環境情報を入力します:
telegraph
ディレクトリで、メインプログラムを実行します:
https://your-dify-host.com/plugins
) を更新します。label
) という名前のプラグインが表示され、「デバッグ中」のマークが付いている場合があります。provider/telegraph.yaml
で定義した “Telegraph Access Token” の入力を求められます。有効なトークンを入力して保存します。検証ロジック (_validate_credentials
) が正しく実装されていれば、ここで検証が行われます。 (ローカルの対応するスクリーンショットを参照してください。プラグインがリストに表示され、認証を要求する画面が表示されています)python -m main
プロセスに転送されて処理されます。ローカルターミナルで関連するログ出力を確認し、デバッグできます。Ctrl + C
を押すと、ローカルプラグインサービスを停止できます。
telegraph/_assets
ディレクトリに、プラグインを表すアイコンファイル(例:icon.png
, icon.svg
)を配置します。正方形で鮮明な画像を推奨します。provider/telegraph.yaml
):
identity
セクションの label
(表示名)、description
(機能説明)、icon
(アイコンファイル名、例:icon.png
を記入) が入力され、多言語対応していることを確認します。この情報は主に Dify アプリケーションオーケストレーションインターフェースでプラグインを_使用する_ユーザーに表示されます。manifest.yaml
):
telegraph/manifest.yaml
ファイルを編集します。これはプラグイン全体の「身分証明書」のようなもので、その情報は Dify のプラグイン管理ページやプラグインマーケットプレイス (Marketplace) に表示されます。label
: プラグインの主要な表示名 (多言語対応)。description
: プラグイン機能の全体的な概要 (多言語対応)。その核心的な価値を明確に要約する必要があります。マーケットプレイスでの表示には文字数制限があることに注意してください。icon
: プラグインのメインアイコン (_assets
ディレクトリ内のアイコンファイル名を直接記入、例:icon.png
)。tags
: プラグインに分類タグを追加し、ユーザーがマーケットプレイスでフィルタリングするのに役立ちます。選択可能な値は、Dify が提供する列挙型またはドキュメントの説明を参照してください (例: media
, tools
, data-processing
など)。ToolLabelEnum 定義 を参照してください。README.md
: プロジェクトルートディレクトリの README.md
ファイルを編集します。これはプラグインの Marketplace 上の詳細な紹介ページとなり、機能詳細、使用例、設定ガイド、よくある質問など、より豊富な情報を含めるべきです。AWS プラグインマーケットプレイスページ のスタイルを参考にしてください。PRIVACY.md
: プラグインを公式 Marketplace に公開する予定がある場合は、プラグインがデータをどのように処理するかを説明するプライバシーポリシー説明ファイル PRIVACY.md
を提供する必要があります。.difypkg
ファイルにパッケージ化できます。プラグインのパッケージ化と公開の詳細については、公開概要 を参照してください。
telegraph
フォルダの一つ上であることを確認してください。
./telegraph
をプラグインプロジェクトの実際のパスに置き換えてください)
telegraph.difypkg
(または あなたのプラグイン名.difypkg
) という名前のファイルが生成されます。
.difypkg
ファイルは完全なプラグインパッケージです。これを以下のことができます: