wp-abilities-api

WP Abilities API

使用する場面

次のようなタスクでは、このスキルを使用してください。

• PHP でアビリティやアビリティカテゴリーを登録する
• REST（wp-abilities/v1）経由でクライアントにアビリティを公開する
• JS（特に @wordpress/abilities）でアビリティを使用する
• 「アビリティが表示されない」「クライアントからアビリティが見えない」「REST が空の結果を返す」といった問題を診断する

必要な入力

• リポジトリのルート（まだ実行していない場合は、先に wp-project-triage を実行してください）。
• 対象の WordPress バージョン、および WP コアかプラグイン／テーマか。
• 変更を適用する場所（プラグイン、テーマ、mu-plugin のいずれか）。

手順

何を登録するかを決める前に、references/domain-vs-projection.md を読んでください。アビリティはドメインの機能レイヤーに属し、MCP／コマンドパレット／REST への公開は投影です。登録の形と公開の形は別々に決める必要があります。この2つを混同すると、利用側の制約が変わるたびに再登録することになります。

1) 利用可能かどうかとバージョンの制約を確認する

• WP コアの作業の場合は、signals.isWpCoreCheckout と versions.wordpress.core を確認してください。
• プロジェクトの対象が WP < 6.9 の場合は、コアに依存せず、Abilities API プラグイン／パッケージが必要になることがあります。

2) 既存の Abilities の使用状況を確認する

リポジトリ内で次の文字列を検索してください。

• wp_register_ability(
• wp_register_ability_category(
• wp_abilities_api_init
• wp_abilities_api_categories_init
• wp-abilities/v1
• @wordpress/abilities

見つからない場合は、Abilities API を新たに導入する（新しい登録とクライアント側での利用）か、利用のみを行うかを判断してください。

3) カテゴリーを登録する（任意）

論理的なグループ分けが必要な場合は、アビリティカテゴリーを早い段階で登録してください（references/php-registration.md を参照）。

4) アビリティを登録する（PHP）

グループ分け（登録するアビリティの数、およびフィルターと新しいアビリティ名のどちらを使うか）を決める前に、まず references/grouping-heuristic.md を読んでください。これにより、REST 操作ごとに個別のアトミックなアビリティを用意してしまうのを防げます。

アビリティと既存の UI／REST コードパスの乖離を防ぐ方法については、references/shared-core-service.md を参照してください。アビリティ、REST ハンドラー、CLI コマンド、UI コントローラーは、共有サービスを呼び出す薄いアダプターにする必要があります。このリファレンスでは、メトリクスに関する落とし穴（使用状況のテレメトリーを送信する REST ハンドラー）と、基盤となるコードパスが変更された際に登録内容を同期させるための AGENTS.md のルールも説明しています。

複数の実行コールバックが既存の REST コントローラーに処理を委譲する場合の、共有ヘルパーのパターンについては、references/plugin-family-patterns.md（共有 API クライアント型か、引数なしコントローラー型かを判別）と references/delegate-helper-pattern.md（適用可能なヘルパーの形と、使用を避けるべき場合）を参照してください。

エージェントが再試行とエスカレーションを判断できるようにする、標準化された WP_Error コードについては、references/error-code-vocabulary.md を参照してください。

PHP でアビリティを登録する際は、次の項目を設定してください。

• 安定した id（名前空間付き）
• label／description
• category
• meta：
  • アビリティが情報提供のみの場合は readonly: true を追加する
  • クライアントに表示するアビリティには show_in_rest: true を設定する

Abilities API の登録には、適切なタイミングで読み込まれるよう、ドキュメントに記載された初期化フックを使用してください（references/php-registration.md を参照）。

5) REST への公開を確認する

• REST エンドポイントが存在し、期待どおりの結果を返すことを確認してください（references/rest-api.md を参照）。
• クライアントに引き続きアビリティが表示されない場合は、meta.show_in_rest が有効になっていることと、適切なエンドポイントにクエリしていることを確認してください。

6) JS から使用する（必要な場合）

• クライアント側でのアクセスとチェックには、@wordpress/abilities の API を優先してください。
• ビルドツールに依存関係が含まれ、プロジェクトのビルドパイプラインでバンドルされることを確認してください。

検証

• 変更後、該当する場合は wp-project-triage が signals.usesAbilitiesApi: true を示すこと。
• REST の確認（WP 環境内）：期待どおりに、wp-abilities/v1 配下のエンドポイントがアビリティとカテゴリーを返すこと。
• リポジトリにテストがある場合は、次の箇所のカバレッジを追加または更新してください。
  • PHP：アビリティの登録とメタデータの公開
  • JS：アビリティの利用と UI の表示制御

失敗パターン／デバッグ

• アビリティがまったく表示されない場合：
  • 登録コードが実行されていない（フックの誤り／ファイルが読み込まれていない）、
  • meta.show_in_rest が設定されていない、
  • カテゴリー／ID が一致していない。
• REST にはアビリティが表示されるが、JS には表示されない場合：
  • REST のベース／名前空間が誤っている、
  • JS の依存関係がバンドルされていない、
  • キャッシュ（オブジェクトキャッシュ／ページキャッシュ）によって変更が反映されていない。
• 実行コールバックが予期しないエラーを返す、または入力を無視する場合：
  • input_schema のデフォルト値が適用されていない、アビリティとバックエンドの間でページネーションのキーにずれがある、または empty() を使った ID 検証が原因です。references/input-schema-gotchas.md を参照してください。

エスカレーション

• バージョンのサポート状況が不明な場合は、対象となる WP コアのバージョンと、Abilities API がコアの機能として、またはプラグインとして提供される想定かどうかを確認してください。
• 正確な情報については、以下を参照してください。
  • references/rest-api.md
  • references/php-registration.md