LLM 向けの説明: ここで私たちが作成したプロンプトを使用して、プラグイン開発を支援することもできます:Dify プラグイン開発:プロンプト始める前に、いつでも私たちが提供する 開発者向けチートシート (Cheatsheet) でよく使われるコマンドや情報を確認したり、より複雑な問題に遭遇した場合には完全な開発者ドキュメントを参照したりすることができます。
1. 開発環境の準備
Dify プラグインの開発を始める前に、お使いの環境に以下のツールが準備されていることを確認してください:- Dify プラグイン開発 CLI (CLI): これはプラグインの開発、デバッグ、パッケージ化を行うための中核となるツールで、
dify-plugin-daemonまたは「プラグイン開発SDK」とも呼ばれます。 - Python 環境: Python 3.12 以降が必要です。
1.1 Dify プラグイン開発 CLI のインストール
より詳細な開発環境準備ガイドについては、開発ツールの初期化 を参照してください。
- ダウンロード: Dify Plugin CLI Releases ページにアクセスします。お使いのオペレーティングシステム(Windows, macOS Intel/ARM, Linux)に対応する最新バージョンのバイナリファイルをダウンロードします。
- 実行権限の設定 (macOS / Linux):
-
以下の手順は macOS (Apple Silicon / M シリーズチップ) を例としています。ダウンロードしたファイル名を
dify-plugin-darwin-arm64と仮定します。ターミナルで、ファイルが存在するディレクトリに移動し、以下のコマンドを実行して実行権限を付与します: -
Linux ユーザーの場合は、対応する Linux バージョンのファイルをダウンロードし、同様の
chmod +x <downloaded_filename>コマンドを実行してください。 -
Windows ユーザーの場合は、
.exeファイルをダウンロードした後、通常は直接実行できます。
-
以下の手順は macOS (Apple Silicon / M シリーズチップ) を例としています。ダウンロードしたファイル名を
- インストールの確認:
-
ターミナルで、以下のコマンドを実行してツールが正常に動作するか確認します(
./dify-plugin-darwin-arm64をダウンロードした実際のファイル名またはパスに置き換えてください): -
ターミナルにバージョン情報(例:
v0.0.1-beta.15)が正常に出力されれば、インストールは成功です。
-
ターミナルで、以下のコマンドを実行してツールが正常に動作するか確認します(
ヒント (Tips):
- 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 プラグイン開発 CLI コマンドの例として ./dify を使用します。ご自身の実際の状況に合わせてコマンドを置き換えてください。
2. プラグインプロジェクトの初期化
それでは、CLI ツールを使用して新しいプラグインプロジェクトを作成しましょう。-
ターミナルを開き、初期化コマンドを実行します:
-
プロンプトに従って、プラグインの基本情報を順に入力します:
- Plugin name: プラグインの一意の識別子。例:
telegraph- 制約: 長さ 1~128 文字、小文字の英数字、ハイフン(-)、アンダースコア()のみ使用可能。_
- Author: プラグイン作者の識別子。例:
your-name- 制約: 長さ 1~64 文字、小文字の英数字、ハイフン(-)、アンダースコア()のみ使用可能。_
- Description: プラグイン機能の簡単な説明。例:
A Telegraph plugin that allows you to publish your content easily - Enable multilingual README: このオプションを有効にすると、プラグインの多言語READMEファイルを生成できます。チェックを入れると、下の
Languages to generateセクションで、事前にREADMEファイルを生成したい言語を選択できます。
- Plugin name: プラグインの一意の識別子。例:
-
開発言語の選択:
Select languageと表示されたら、pythonを選択してください。 -
プラグインタイプの選択:
Select plugin typeと表示されたら、このチュートリアルではtoolを選択してください。 - 追加機能の選択: 次に、プロバイダー認証、永続ストレージなどの追加機能が必要かどうか尋ねられます。この簡単な Hello World プラグインでは、これらは一時的に不要なので、成功メッセージが表示されるまで Enter キー を押してすべてのオプションをスキップできます。
-
作成成功の確認: ターミナルに以下のような情報が出力されたら、プラグインプロジェクトは正常に作成されています:
telegraph(または指定したプラグイン名)という名前の新しいフォルダが表示され、これがプラグインプロジェクトになります。
3. Python 仮想環境と依存関係の設定
プロジェクトの依存関係を分離するために、Python 仮想環境の使用を推奨します。3.1 仮想環境の作成とアクティベート(コマンドライン方式)
これは推奨される一般的な方法で、特定の IDE に依存しません:-
プロジェクトディレクトリへの移動:
-
仮想環境の作成: (名前を
venvにすることを推奨します) -
仮想環境のアクティベート:
-
macOS / Linux:
-
Windows (cmd.exe):
-
Windows (PowerShell):
-
アクティベートに成功すると、通常、ターミナルのプロンプトの前に
(venv)と表示されます。
-
macOS / Linux:
3.2 基本的な依存関係のインストール
プロジェクト初期化時に生成されたrequirements.txt ファイルには、プラグイン開発に必要な基本ライブラリ dify_plugin が含まれています。仮想環境をアクティベートした後、以下のコマンドを実行してインストールします:
3.3 (オプション) VSCode 統合環境設定
VSCode をコードエディタとして使用している場合、その統合機能を利用して Python 環境を管理できます:- プロジェクトフォルダを開く: 作成した
telegraphフォルダを VSCode で開きます。 - Python インタープリタの選択:
- コマンドパレットを開きます (macOS:
Cmd+Shift+P, Windows/Linux:Ctrl+Shift+P)。 Python: Select Interpreterと入力して選択します。- 表示されたリストから、先ほど作成した仮想環境内の Python インタープリタを選択します(通常、パスには
.venv/bin/pythonまたはvenv\Scripts\python.exeが含まれます)。リストに自動的に表示されない場合は、Enter interpreter path...を選択して手動で検索できます。 - (ローカルの対応するスクリーンショットを参照してください。インタープリタ選択画面が表示されています)
- コマンドパレットを開きます (macOS:
- 依存関係のインストール (VSCode が提示した場合): VSCode が
requirements.txtファイルを検出し、その中の依存関係をインストールするよう促すことがあります。プロンプトが表示されたら、インストールを確認してください。- (ローカルの対応するスクリーンショットを参照してください。依存関係のインストール確認画面が表示されています)
以降のすべての pip install コマンドと python -m main の実行操作は、アクティベートされた仮想環境で実行してください。
4. プラグインコアロジックの開発
それでは、プラグインのコードを記述していきましょう。この例では、指定されたコンテンツを Telegraph に公開するための簡単なツールを実装します。4.1 サンプル依存ライブラリ: your-telegraph
your-telegraph という名前の Python ライブラリを使用して Telegraph API とやり取りします。(これは仮のライブラリ名です。実際に使用するライブラリが有効であることを確認してください)。
your-telegraph は、Telegraph API の操作を簡略化する Python ラッパーで、数行のコードで簡単にコンテンツを公開できます。
その基本的な使い方は以下のようになるかもしれません:
4.2 プロジェクト依存関係の追加と設定
-
依存ライブラリのインストール: 仮想環境がアクティベートされていることを確認し、ターミナルで以下を実行します:
-
requirements.txt の更新:プロジェクトルートディレクトリにあるtelegraph/requirements.txtファイルを開き、dify_pluginの下に、先ほどインストールしたライブラリ名を一行追加します:これにより、他の開発者やデプロイ環境がすべての必要な依存関係を簡単にインストールできるようになります。
4.3 プロバイダー認証情報の設定
この例ではtelegraph_access_token が必要です。プロバイダー設定でこの認証情報を定義し、ユーザーがプラグインを使用する際に入力できるようにする必要があります。プロバイダー設定の詳細については、一般仕様定義 を参照してください。
-
プロバイダー YAML の編集:
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: (オプション) 認証情報取得のためのヘルプリンクを提供します。
- フィールドの説明:
4.4 ツール (Tool) ロジックの実装
それでは、実際に公開操作を実行するツールのコードを記述しましょう。-
ツール Python ファイルの編集:
telegraph/tools/telegraph.pyを開きます。 -
_invoke メソッドの実装:ファイルの内容を以下のコードに置き換えます:- 重要なポイント:
self.runtime.credentialsから認証情報を取得します。tool_parametersからツールの入力パラメータを取得します(パラメータ名は次のステップの YAML で定義します)。.get()を使用する方が堅牢な方法です。ytelegraphライブラリを呼び出して実際の操作を実行します。try...exceptを使用して起こりうるエラーをキャッチし、例外をスローします。yield self.create_link_message(url)を使用して URL を含む結果を Dify に返します。
- 重要なポイント:
4.5 ツール (Tool) パラメータの設定
このツールがどの入力パラメータを受け取るかを Dify に伝える必要があります。-
ツール YAML ファイルの編集:
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 ファイルのパス(プロジェクトルートディレクトリからの相対パス)を示します。
- フィールドの説明:
4.6 プロバイダー認証情報の検証実装(オプションだが推奨)
ユーザーが提供した認証情報が有効であることを保証するために、検証ロジックを実装すべきです。-
プロバイダー Python ファイルの編集:
telegraph/provider/telegraph.pyを開きます。 -
_validate_credentials メソッドの実装:ファイルの内容を以下に置き換えます:- 重要なポイント:
credentials辞書から認証情報を取得します。- その認証情報が必要な API 呼び出しを実行します(アカウント情報の取得など、読み取り専用操作が望ましいです。もしなければ、無害なテストページを作成することもできますが、副作用の可能性に注意してください)。
- API 呼び出しが成功した場合、例外はスローされず、検証が通過したことを示します。
- API 呼び出しが失敗した場合、例外をキャッチして
ToolProviderCredentialValidationErrorをスローし、元のエラーメッセージを含めます。
- 重要なポイント:
5. ローカルでの実行とデバッグ
これでプラグインをローカルで実行し、Dify でデバッグできます。.env ファイルの準備:-
telegraphプロジェクトディレクトリにいることを確認してください。 -
環境変数テンプレートファイルをコピーします:
-
.env ファイルの編集:作成したばかりの.envファイルを開き、Dify 環境情報を入力します:- ホストとキーの取得: Dify 環境にログインし、右上の「プラグイン」アイコンをクリックし、次にデバッグアイコン(または虫のような形)をクリックします。ポップアップウィンドウで、「API キー (Key)」と「ホストアドレス (Host)」をコピーします。 (ローカルの対応するスクリーンショットを参照してください。キーとホストアドレスの取得画面が表示されています)
-
- ローカルプラグインサービスの起動:
- Python 仮想環境がアクティベートされていることを確認してください。
-
telegraphディレクトリで、メインプログラムを実行します: -
ターミナル出力の確認: すべてが正常であれば、以下のようなログ情報が表示され、プラグインツールが正常にロードされ、Dify に接続されたことを示します:
- Dify での確認とテスト:
- Dify ページを更新: Dify 環境(ブラウザ)に戻り、プラグイン管理ページ (通常は
https://your-dify-host.com/plugins) を更新します。 - プラグインを検索: リストに “Telegraph” (またはプロバイダー YAML で定義した
label) という名前のプラグインが表示され、「デバッグ中」のマークが付いている場合があります。 - 認証情報を追加: そのプラグインをクリックすると、以前
provider/telegraph.yamlで定義した “Telegraph Access Token” の入力を求められます。有効なトークンを入力して保存します。検証ロジック (_validate_credentials) が正しく実装されていれば、ここで検証が行われます。 (ローカルの対応するスクリーンショットを参照してください。プラグインがリストに表示され、認証を要求する画面が表示されています) - アプリケーションで使用: これで、Dify のアプリケーション(Chatbot や Workflow など)にこのツールノードを追加し、呼び出すことができます!アプリケーションで実行してツールをトリガーすると、リクエストはローカルで実行されている
python -m mainプロセスに転送されて処理されます。ローカルターミナルで関連するログ出力を確認し、デバッグできます。
- Dify ページを更新: Dify 環境(ブラウザ)に戻り、プラグイン管理ページ (通常は
- ローカルサービスの停止: ターミナルで
Ctrl + Cを押すと、ローカルプラグインサービスを停止できます。
6. プラグインメタ情報の整備
プラグインをより専門的に、発見・理解しやすくするために、いくつかの表示情報を整備する必要があります。-
アイコン (Icon):
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 とプライバシーポリシー:
-
README.md: プロジェクトルートディレクトリのREADME.mdファイルを編集します。これはプラグインの Marketplace 上の詳細な紹介ページとなり、機能詳細、使用例、設定ガイド、よくある質問など、より豊富な情報を含めるべきです。AWS プラグインマーケットプレイスページ のスタイルを参考にしてください。多言語でREADMEを提供することができます。詳細については、多言語 README をご覧ください。 -
PRIVACY.md: プラグインを公式 Marketplace に公開する予定がある場合は、プラグインがデータをどのように処理するかを説明するプライバシーポリシー説明ファイルPRIVACY.mdを提供する必要があります。
-
7. プラグインのパッケージ化
プラグイン開発が完了し、ローカルテストに合格したら、配布またはインストール用に.difypkg ファイルにパッケージ化できます。プラグインのパッケージ化と公開の詳細については、公開概要 を参照してください。
-
親ディレクトリに戻る: ターミナルの現在のパスが
telegraphフォルダの一つ上であることを確認してください。 -
パッケージ化コマンドの実行:
(
./telegraphをプラグインプロジェクトの実際のパスに置き換えてください) -
パッケージファイルの取得: コマンドが正常に実行されると、現在のディレクトリに
telegraph.difypkg(またはあなたのプラグイン名.difypkg) という名前のファイルが生成されます。
.difypkg ファイルは完全なプラグインパッケージです。これを以下のことができます:
- Dify のプラグイン管理ページで手動でアップロードしてインストールする。
- 他の人に共有してインストールしてもらう。
- Dify の規範と手順に従って、公式プラグインマーケットプレイス (Marketplace) に公開し、すべての Dify ユーザーがあなたのプラグインを発見して使用できるようにする。具体的な公開手順については、Dify マーケットプレイスへの公開 を参照してください。
次の学習ステップ
- リモートでプラグインをデバッグする - より高度なプラグインデバッグテクニックを学ぶ
- 永続ストレージ - プラグインでデータストレージを使用する方法を学ぶ
- Slack ボットプラグイン開発例 - より複雑なプラグイン開発事例を見る
- ツールプラグイン - ツールプラグインの高度な機能を探る
このページを編集する | 問題を報告する