appbuilder-action-scaffolder

App Builder アクションスキャフォルダー

Adobe Runtime アクションのライフサイクル全体をカバーするスキルです。スキャフォールドの作成、実装、デプロイ、デバッグを行います。アクションコードは src/<extension-dir>/actions/<action-name>/index.js に配置し、src/<extension-dir>/ext.config.yaml に登録してください。

Workfront 拡張機能を構築していますか？{ data, error } レスポンスコントラクト、SPA からの IMS トークンのパススルー、Workfront 独自の Public API v21 など、Workfront 固有のアクションレイヤーについては workfront-actions を参照してください。汎用的なアクションパターン、テンプレート、App Builder SDK にはこのスキルを使用してください。

パターンのクイックリファレンス

ユーザーの意図に合ったテンプレートを選んでください。汎用アクションには、デフォルトで assets/action-boilerplate.js を使用します。

ユーザーの要望	テンプレート
シンプルなアクション／汎用的な開始点	assets/action-boilerplate.js
最小限のプロトタイプ（基本構成のみ）	assets/action-scaffold-template.js
データベースの CRUD（永続レコード、インデックス）	assets/database-action-template.js
Webhook 受信（I/O Events）	assets/event-webhook-template.js
カスタムイベントプロバイダー	assets/event-provider-template.js
ジャーナリングコンシューマー（再生可能なイベント）	assets/journaling-consumer-template.js
大容量ペイロードのレスポンス（>1 MB）	assets/large-payload-template.js
アクションシーケンスパイプライン	assets/action-sequence-template.js
Asset Compute ワーカー（AEM レンディション）	assets/asset-compute-worker-template.js
Runtime アクションの問題をデバッグ	references/debugging.md

クイックパス（明確なリクエスト向け）

ユーザーのリクエストが上記の単一パターンに明確に当てはまる場合（特定のパターン名やテンプレートを挙げている場合、またはある項目に明確に合致するユースケースを説明している場合）は、スキャフォールドの作成に直接進みます。該当するテンプレートを使い、そのまま作業を進めてください。

クイックパスを適用する例：

• 「Webhook 受信アクションを追加して」→ assets/event-webhook-template.js を使って、直接スキャフォールドを作成
• 「Asset Compute ワーカーを作成して」→ assets/asset-compute-worker-template.js を使って、直接スキャフォールドを作成
• 「データベース CRUD アクションを追加して」→ assets/database-action-template.js を使って、直接スキャフォールドを作成
• 「process-order という名前のアクションを追加して」（シンプルで曖昧さがない場合）→ assets/action-boilerplate.js を使って、直接スキャフォールドを作成

曖昧な点がある場合（複数のパターンが当てはまる可能性がある、制約が不明確、または単一のアプローチを選ぶための情報が不足している場合）は、以下の全ワークフローに進んでください。

クイックリファレンス

• アクションのエントリーポイント： アクションコードは src/<extension-dir>/actions/<action-name>/index.js に配置してください。これにより、パスを生成された拡張機能のレイアウトに合わせられます。
• マニフェストの場所： アクションは src/<extension-dir>/ext.config.yaml に登録してください。app.config.yaml にルートレベルの runtimeManifest を置かないでください。CLI はこれを警告なく無視します。
• 拡張機能ディレクトリ名： 拡張機能ディレクトリ名はプロジェクトテンプレートによって異なります。
  • src/dx-excshell-1/ — Experience Cloud Shell SPA（デフォルト）
  • src/aem-cf-console-admin-1/ — AEM Content Fragment Console 拡張機能
  • src/dx-asset-compute-worker-1/ — Asset Compute ワーカー 実際のディレクトリ名は、プロジェクトの app.config.yaml の $include エントリーから確認してください。
• Web アクションのレスポンス形式： 標準的な Web アクションでは { statusCode, body } を返してください。headers は必要な場合のみ追加します。
• 主要な CLI ループ： ローカルでの反復開発には aio app dev を使用します（アクションで State SDK、Files SDK、またはシーケンスを使用する場合は aio app run を使用）。直接テストには aio rt action invoke を、公開には aio app deploy を使用します。
• State とデータベースの使い分け： 一時的なジョブの追跡には State を、永続レコード、インデックス付きクエリ、またはドキュメント形式の CRUD にはデータベースを使用します。
• イベント配信方式の選択： プッシュ配信には Webhook、ドメインイベントの公開にはカスタムイベントプロバイダー、再生可能性またはバックプレッシャーが必要な場合はジャーナリングコンシューマーを使用します。
• 大容量ペイロードとシーケンスのパターン： レスポンス上限が 1 MB を超える場合は、大容量ペイロードのリダイレクトを使用します。複数のアクションを直線的に実行するフローにはアクションシーケンスを使用します。
• Asset Compute ワーカーの適用範囲： AEM レンディションの処理には Asset Compute ワーカーを使用します。標準的な Runtime アクションとは SDK と拡張機能のレイアウトが異なります。

完全なワークフロー（曖昧または複雑なリクエストの場合）

1. 目標とする成果、制約、受け入れ基準を確認します。
2. コード、環境、Adobe の設定から、現在の実装状況を収集します。
3. この機能に関する詳細な手順は、references/playbook.md に従います。
4. 実装成果物と検証の証拠を作成します。
5. 最終引き継ぎの前に、references/checklist.md を確認します。
6. 決定事項、リスク、直近の対応事項をまとめます。

ユーザープロンプトの例

• 「AEM Assets API を呼び出す新しいアクションを App Builder プロジェクトに追加してください。」
• 「ランタイムアクションが 60 秒後にタイムアウトします。アプリを壊さずに制限を増やす方法を教えてください。」
• 「外部 API とデータを同期するため、5 分ごとに実行する cron アクションを設定してください。」
• 「ファイルのアップロードを受け付け、Files SDK を使って保存する Web アクションを作成してください。」
• 「App Builder Database に顧客の設定を保存してください。」
• 「アセットの変更に関する I/O Events を受信する Webhook を設定してください。」
• 「アクションの応答が大きすぎます。1MB を超えるペイロードを処理する方法を教えてください。」

依頼する入力情報

• 現在のリポジトリのパスとモジュールの境界
• 対象となる Adobe 組織、プロジェクト、ワークスペース
• 非機能要件：レイテンシ、コスト、コンプライアンス、サポートモデル
• 完了の定義と、測定可能な受け入れ基準

成果物

• 依頼された機能の実装更新
• 検証の証拠：テスト、チェック、または再現可能な検証手順
• 明示的なトレードオフとフォローアップ対応を含む引き継ぎの概要

品質基準

• 決定事項を明確にし、プロジェクトの制約との関連を追跡できるようにします。
• 繰り返し実行できる手順には、決定論的な自動化を優先します。
• 実行可能な診断情報を提示し、安全に失敗するようにします。
• 引き継ぎメモにトレードオフと次の段階でのリスクを記録します。

参考資料

• 詳細な実行ガイダンスについては、references/playbook.md を使用します。
• 引き継ぎ前の検証については、references/checklist.md を使用します。
• すぐに使える実行プロンプトについては、references/prompt-pack.md を使用します。
• アクションの構造、パラメーター、応答形式、SDK の使用方法、CLI の操作については、references/runtime-reference.md を使用します。
• AEM Content Fragment API のインターフェイス（判断表、Delivery OpenAPI、Management OpenAPI、GraphQL 永続クエリ、非推奨の Assets HTTP API）、認証パターン、各 API のアクションコードについては、references/aem-apis.md を使用します。
• CRUD API、cron、複数ステップの処理、データベース CRUD、Webhook の受信、カスタムイベントプロバイダー、ジャーナリングコンシューマー、大規模ペイロードのリダイレクト、アクションシーケンスの構成、Asset Compute ワーカーなど、一般的なアクションパターンについては、references/action-patterns.md を使用します。
• ユーザーのリクエストが新しいボイラープレートパターンのいずれかに直接対応する場合は、assets/database-action-template.js、assets/event-webhook-template.js、assets/event-provider-template.js、assets/journaling-consumer-template.js、assets/large-payload-template.js、assets/action-sequence-template.js、assets/asset-compute-worker-template.js を使用します。
• Adobe サービス固有のガイダンスについては、../_shared/categories/architecture-runtime.md を使用します。

共通マニフェストのガードレール

• App Builder アクションの定義は、app.config.yaml の application.runtimeManifest に記述します。
• ルートレベルの runtimeManifest は使用しないでください。App Builder CLI はアクション設定としてこれを無視します。
• デプロイ前にマニフェスト構造を検証します：python3 ../_shared/scripts/validate_manifest_structure.py <path-to-app.config.yaml>。
• 有効な例と無効な例については、../_shared/references/appbuilder-manifest-guardrail.md を使用します。

よくある問題

• アクションのデプロイに失敗する： デプロイ失敗の大半は、マニフェストの構造が無効であるか、依存関係が不足していることが原因です。アクションが application.runtimeManifest の下にネストされていること（または拡張機能の ext.config.yaml パターン）を確認し、マニフェスト検証ツールを実行してから npm install を実行し、aio app deploy を再試行してください。
• アクションのタイムアウト： ランタイムの実行時間はデフォルトで 60 秒です。Web アクション以外は 300 秒まで延長できます。呼び出しごとの処理量を減らし、長時間実行されるタスクは非同期またはバックグラウンドのフローに移すか、アクションの種類が対応している場合はマニフェストの制限値でタイムアウトを引き上げてください。
• ペイロードが大きすぎる： Web アクションでは、リクエストとレスポンスの両方のペイロードが 1 MB に制限されています。リクエスト本文を小さくし、大きなデータをインラインで返さないようにして、代わりに外部ストレージを利用するか、URL を渡してください。
• IMS トークンを利用できない／認証に失敗する： アクションが Adobe のユーザーコンテキストを必要とする場合は、annotations.require-adobe-auth: true を設定し、シェルまたは呼び出し元が実際にトークンを提供していることを確認してください。また、対象 API へのアクセスに必要な aio auth login と Adobe プロジェクト／ワークスペースのアクセス権を確認してください。
• 2 層の認証による混乱： アクションでは、互いに独立した 2 つの層で認証を強制できます。1 つは require-adobe-auth: true マニフェストアノテーション（ゲートウェイレベルでの拒否）、もう 1 つはアクション内のコードレベルでの Authorization ヘッダーチェックです。一方の層を無効にしても、もう一方は無効になりません。ローカル開発時は、require-adobe-auth: false に設定し、コードレベルのチェックもスタブ化してください。そうしないと、再デプロイを繰り返しても 401 エラーが解消されません。詳しいデバッグ手順については、references/runtime-reference.md § 「よくある認証の問題」を参照してください。

第 1 波アクセラレーターキット

• この高頻度機能の成果物を構成するには、references/implementation-template.md を使用してください。
• scripts/accelerator.py を実行して、リクエストのコンテキストから実行チェックリストを生成してください。

アセットテンプレート

• assets/action-scaffold-template.js — 迅速なプロトタイピング向けの最小限のスキャフォールドです。ゼロから始める場合、必要最低限のアクション構成を求める場合、または本番環境向けの考慮事項を追加する前に、基本的なパラメーター入力／レスポンス出力のフローを検証する場合に使用してください。
• assets/action-boilerplate.js — ロギング、入力検証、エラー処理、レスポンスのフォーマットを備えた、本番環境対応のテンプレートです。本番環境での利用を想定したアクション、チーム内で共有して引き継ぐアクション、または可観測性と防御的なデフォルト設定をあらかじめ備えた状態で実装を開始する場合に使用してください。
• assets/database-action-template.js — コレクションの初期化、インデックス、ドキュメント形式の操作を備えた、永続的なデータベース CRUD のスターターです。
• assets/event-webhook-template.js — チャレンジ処理、署名検証、べき等なイベント処理を備えた Adobe I/O Events Webhook レシーバーです。
• assets/event-provider-template.js — プロバイダーのメタデータ設定とドメインイベントの公開を開始するための、カスタムイベントプロバイダーのスターターです。
• assets/journaling-consumer-template.js — ジャーナルをポーリングし、カーソルを保存して、再生可能なイベントバッチを処理する、スケジュール実行されるジャーナリングコンシューマーです。
• assets/large-payload-template.js — Files ストレージにサイズ超過のレスポンスを書き込み、リダイレクト URL を返す、大きなペイロードを扱うレスポンスのスターターです。
• assets/action-sequence-template.js — 直線的なアクションシーケンスパイプライン向けの、スターターマニフェストとアクションレイアウトです。
• assets/asset-compute-worker-template.js — Asset Compute SDK を使用した AEM レンディション処理向けの、Asset Compute ワーカースキャフォールドです。

エージェント統合

• agents/ ディレクトリには、標準のスキルディレクトリを補完する、エージェントプラットフォーム統合のメタデータが格納されています。
• agents/openai.yaml は OpenAI 向けのスキル設定を定義します。この設定には、表示名、短い説明、OpenAI 互換のエージェント環境でこのスキルを呼び出すために使用するデフォルトのプロンプトが含まれます。
• コアとなるスキルの指示は SKILL.md に記述し、agents/ はプラットフォーム固有の統合の詳細にのみ使用してください。