halo-plugin-dev

Halo プラグイン開発

対象のプラグインを基準に作業し、Halo 固有の仕様が必要な場合にのみ、最新の Halo ドキュメントを取得してください。スキルに埋め込まれた API の詳細や、学習データから思い出した情報に頼らないでください。

対象を確認する

• 編集する前に、既存の Gradle ファイル、src/main/resources/plugin.yaml、UI パッケージのマニフェストとビルド設定、および近隣の実装を確認してください。
• Halo プラットフォームの依存関係と、plugin.yaml の spec.requires の両方を確認してください。必要条件を黙って引き上げたり、UI のビルド形式を切り替えたりしないでください。
• 既存のプラグインでは、構造とツールを維持してください。新しいプラグインでは、ユーザーが別の開始方法を選んでいない限り、公式の pnpm create halo-plugin スキャフォールドを優先してください。

必要に応じてドキュメントを取得する

1. タスクに Halo プラグインの API、設定、ライフサイクル、UI、DevTools、セキュリティ、または統合仕様が関わる場合は、プラグインドキュメントのインデックスから確認してください。
2. 関連するドキュメントのセクションが不明な場合や、複数のセクションにまたがるタスクの場合に限り、Halo ドキュメント全体のインデックスを使用してください。
3. 現在のタスクに関連する Markdown ページのみを取得してください。デフォルトで llms-full.txt を読み込まないでください。
4. バージョンに依存する作業では、プラグイン API の変更履歴も確認し、対象の依存関係、ソース、または既存の呼び出し元と照らし合わせて、正確なシグネチャと動作を検証してください。現在のサイトのドキュメントより、対象のバージョンを優先してください。

オンラインのドキュメントを利用できない場合は、可能であれば対象のチェックアウトと依存関係のソースを使って作業を続け、推測せず、検証できなかった内容を明らかにしてください。

Halo 固有の制約

• リアクティブな WebFlux の処理経路でブロッキング処理を行わないでください。最新のリアクティブ開発ガイドに従ってください。
• 依存関係や独自の同等機能を追加する前に、Halo が提供する UI コンポーネント、FormKit の入力コンポーネント、共有ユーティリティ、およびプロジェクトにインストール済みのビルドツールを再利用してください。
• 通常のプラグイン設定には、設定用のルートを重複して作成するのではなく、Setting YAML を使用してください。ページとモーダルのフォームには FormKit を使用し、ネイティブの代替実装を用意する前に、Halo のリスト、検索、モーダル、フィードバック、権限に関するコンポーネントを再利用してください。最新のフォームとページコンポーネントのガイドに従ってください。
• プロジェクトの generateApiClient タスクを使って、カスタムモデルと、ドキュメント化された SpringdocRouteBuilder エンドポイントから TypeScript のモデルと API メソッドを生成してください。Halo の axiosInstance を再利用し、生成されるリソース型を手書きしたり、/api または /apis 用に別の Axios クライアントを作成したりしないでください。最新のAPI リクエストガイドに従ってください。
• 生成された API クライアントとビルド済みの UI アセットは生成ファイルとして扱ってください。出力を直接編集するのではなく、入力を変更し、プロジェクトのジェネレーターまたはビルドタスクを使用してください。
• パスワード、トークン、API キー、秘密鍵は Halo の Secret に保存し、ConfigMap やカスタムモデルの仕様には保存しないでください。認証情報を付与する前に、ユーザーが指定した送信先を SSRF やリダイレクトのリスクについて検証し、設定の読み込みに失敗した場合は、公開 API やセキュリティ切り替えを無効のままにしてください。最新の送信 HTTP ガイドに従ってください。
• RoleTemplate を追加するのは、スーパー管理者以外または匿名ユーザーのアクセスが必要な場合に限り、必要最小限の権限を付与してください。

検証

プロジェクトに既存の Gradle スクリプトと UI スクリプトを使用してください。関連するテストとチェックを必要最小限の範囲で実行し、マニフェスト、UI の出力、または生成リソースがプラグイン JAR に影響する場合は、パッケージングを検証してください。実行可能な Halo インスタンスが利用できる場合は、変更した Console、User Center、API、ライフサイクル、またはテーマの統合経路をスモークテストしてください。