ffcpe-custom-node-sdk

App Builder 上の FFCPE カスタムアクション（@adobe/ffcpe-custom-node-core、@adobe/ffcpe-custom-node-app-builder）

対象読者

Workflow Builder から custom-action（非同期の送信＋ステータスのポーリング）として呼び出される App Builder アプリケーションを提供するチームなど、NPM パッケージを利用する方を支援する際に、このスキルを使用してください。

SDK のソースリポジトリ（モノレポ、Turbo、リリース）への貢献については、SDK のソースと同じ場所にある README.md（「Monorepo (contributors)」）と CONTRIBUTING.md（内部ミラーまたは公開リポジトリのチェックアウト）を参照してください。

ウェブ／ワーカーのファイル、webpack、ext.config.yaml のスキャフォールディングには、ffcpe-app-builder-actions を使用してください。

catalog-entry.json の作成と aio ffcpe catalog（検証、登録、一覧表示、更新）については、adobe/aio-cli-plugin-ffcpe からスキルをインストールしてください：ffcpe-catalog-entry-json と aio-ffcpe-cli。

npx skills add adobe/aio-cli-plugin-ffcpe --all -y

エンドツーエンドのチェックリスト

0. Console プロジェクトをブートストラップする（新規プロジェクトのみ）— aio console でプロジェクトとワークスペースを作成し、aio app init --standalone-app を実行して、ワークスペース設定をダウンロードし、aio app use <config>.json --overwrite --no-input で接続します。web-src/、スキャフォールディングされた汎用アクション、および app.config.yaml の web: web-src を削除します。webpack-config.js を esbuild-loader と commonjs2 の構成に置き換えます。Console プロジェクト名：英数字のみ、20 文字以下（ハイフン不可）。YAML 内の OpenWhisk パッケージ名と異なっていてもかまいません。正確な手順については、ffcpe-app-builder-actions →「Starting from scratch with init-bare」を参照してください。

1. SDK パッケージをインストールする（npm または pnpm）し、ウェブアクションとワーカーアクションを実装します。ベストプラクティス：カタログエントリーを <action-name>.web.* および <action-name>.worker.* と同じ場所に <action-name>.entry.json として配置します（ffcpe-app-builder-actions を参照）。

2. App Builder アプリケーションをデプロイし、デプロイ出力からウェブアクションのベース URL をコピーして、カタログの submitEndpoint／statusEndpoint を {base}/submit と {base}/status に設定します。

3. <action-name>.entry.json を作成します — ポートはワーカーの入力／出力名と一致させ、エンドポイントにはデプロイ先を設定します。デフォルトの mountFfcpeNodeRoutes 認証を使用する場合は authentication: { "type": "ims_service_token" } を指定します（ルートで authenticate: null を設定しない限り、none は指定しないでください）。

4. CLI で検証して登録します — curl を直接実行しないでください。

   aio ffcpe catalog validate --file ./actions/my-action/my-action.entry.json
   aio ffcpe catalog register --file ./actions/my-action/my-action.entry.json
   

パッケージのインストール

npm の場合：

npm install @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder

または pnpm の場合 — アプリの .npmrc で auto-install-peers=true を設定し、次を実行します。

pnpm add @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder

ピア依存関係を明示する場合 — すべてのピアを package.json に記載したい場合や、使用するツールがピア依存関係を自動インストールしない場合（例：Yarn Classic）：

npm install @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder hono hono-openwhisk-adapter

pnpm add @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder hono hono-openwhisk-adapter

一般的なピア依存関係（テンプレートと Adobe のドキュメントでバージョンを確認してください）：

• @adobe/aio-lib-core-logging、@adobe/aio-lib-state、@adobe/aio-lib-ims、openwhisk、hono、hono-openwhisk-adapter

ローカルの SDK チェックアウトをリンクする

コンシューマーアプリで、レジストリではなく近くにある SDK モノレポのクローンから @adobe/ffcpe-custom-node-core ／ @adobe/ffcpe-custom-node-app-builder を読み込む場合に使用します。

1. SDK モノレポで、両方のパッケージの dist/ をインストールしてビルドします。

   pnpm install && pnpm run build
   # or: npm install && npm run build
   

   変更をすぐに反映させるには、SDK のルートから pnpm run dev（または npm run dev）を実行し、変更のたびに dist/ を再ビルドします。

2. コンシューマーの App Builder プロジェクトで、まず core を、次に app-builder をリンクします。

   pnpm:

   pnpm link /path/to/ffcpe-custom-node-sdk/packages/core
   pnpm link /path/to/ffcpe-custom-node-sdk/packages/app-builder
   

   npm:

   npm link /path/to/ffcpe-custom-node-sdk/packages/core
   npm link /path/to/ffcpe-custom-node-sdk/packages/app-builder
   

3. レジストリのパッケージに戻すには、次を実行します。

   pnpm unlink @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder && pnpm install
   # or: npm unlink @adobe/ffcpe-custom-node-core @adobe/ffcpe-custom-node-app-builder && npm install
   

グローバルリンク（pnpm、任意）： packages/core と packages/app-builder からそれぞれ pnpm link --global を実行してパッケージを登録します。次に、コンシューマー側で pnpm link --global @adobe/ffcpe-custom-node-core と pnpm link --global @adobe/ffcpe-custom-node-app-builder を実行します。app-builder で workspace:* を解決できない場合は、ディレクトリリンクを使い続けるか、@adobe/ffcpe-custom-node-core を packages/core のパスに固定するコンシューマー側の pnpm.overrides を追加してください。

詳しい説明は SDK の README.md（「Use a local SDK checkout」）を参照してください。

エージェントスキルをインストールする

スキルは SDK リポジトリの skills/ にあり、open agent skills CLI を使ってインストールします。各エージェント（Claude Code、Cursor など）には、正規のコピーをシンボリックリンクで配置し、ガイダンスが常に同じになるようにしています。

GitHub から（コンシューマーリポジトリ）

# List available skills
npx skills add adobe/ffcpe-custom-node-sdk --list

# Install all FFCPE skills (project-local)
npx skills add adobe/ffcpe-custom-node-sdk --all -y

# Install only this skill
npx skills add adobe/ffcpe-custom-node-sdk --skill ffcpe-custom-node-sdk -y

# Claude Code + Cursor
npx skills add adobe/ffcpe-custom-node-sdk --all -a claude-code -a cursor -y

# Global (all projects on this machine)
npx skills add adobe/ffcpe-custom-node-sdk --all -g -y

ローカルの SDK チェックアウトから

npx skills add /path/to/ffcpe-custom-node-sdk/skills --all -y

更新／削除コマンドとスキルの構成については、このリポジトリの skills/README.md を参照してください。

CLI プラグインのスキル（別リポジトリ）：

npx skills add adobe/aio-cli-plugin-ffcpe --all -y

各 SKILL.md のフロントマターで name を使ってスキルを参照します：ffcpe-custom-node-sdk、ffcpe-app-builder-actions、aio-ffcpe-cli、ffcpe-catalog-entry-json。

カタログ CLI（@adobe/aio-cli-plugin-ffcpe）

デプロイ後のカタログ操作には、Adobe I/O CLI プラグインをインストールします。

npm install -g @adobe/aio-cli
aio plugins:install @adobe/aio-cli-plugin-ffcpe
aio login
aio console org select

コマンド	用途
aio ffcpe catalog validate -f ./actions/<action-name>/<action-name>.entry.json	ローカルでの JSON 検証（API 呼び出しなし）
aio ffcpe catalog register -f ./actions/<action-name>/<action-name>.entry.json	新しいカスタムアクションを登録
aio ffcpe catalog inspect ACTIONTYPE	エントリーを 1 件取得
aio ffcpe catalog list	カスタムアクションを一覧表示（Adobe の組み込みアクションを含めるには --include-core を追加）
aio ffcpe catalog update ACTIONTYPE -f …	全体を PUT で置換
aio ffcpe catalog disable ／ enable ／ delete	ライフサイクル操作

検証の警告がある場合に失敗させるには、register／update で --strict を使用します。API ホストは AIO_FFCPE_CATALOG_BASE_URL または --base-url で上書きできます。認証には aio login と同じ IMS セッションを使用するため、手書きの HTTP よりも aio ffcpe catalog を優先してください。

カタログ JSON の customActionConfig.submitEndpoint ／ statusEndpoint を、デプロイ済みの Web アクション URL と mountFfcpeNodeRoutes のルートパスに合わせてください。カタログの inputs ／ outputs にある name の値は、ワーカーが getTextInput、getImageInput などを通じて読み取る値と一致させる必要があります。

2 つの OpenWhisk アクション（推奨構成）

1. Web アクション — FFCPE の HTTP エントリーポイント：POST /submit、GET /status。Hono アプリを構築し、mountFfcpeNodeRoutes を呼び出して、hono-openwhisk-adapter の ToOpenWhiskAction で main をエクスポートします。
2. Worker アクション — 長時間実行ジョブ：createFfcpeNodeWorker(handler, options) から main をエクスポートします。

ext.config.yaml（または同等の設定）を使用して、web アクションで web: "raw" と annotations.require-adobe-auth: false が使われるようにします（README.md のマニフェスト例を参照）。worker／web のパッケージ名とアクション名は、mountFfcpeNodeRoutes に渡す名前と一致させてください。

Web ルートの配線（mountFfcpeNodeRoutes）

• worker: { package, name } を渡します。submit 後に非同期で OpenWhisk を呼び出す際のターゲットです。
• web: { package, name } を渡します。必須です。Workflow Builder に返す statusUrl の生成に使われます。省略するか空文字列を指定すると、マウント時にエラーになります。
• routes は任意です。デフォルトは /submit と /status です。カタログの submitEndpoint／statusEndpoint のパスに合わせてください。
• authenticate は任意です。デフォルトでは createImsInboundAuth による IMS bearer と x-api-key を使用します。これらのルートで認証を無効にするには null を渡します（製品／セキュリティ上許可される場合に限ります）。
• jobStore、loggerName、jobMetadata(submit) は任意です。上級者向けの設定です。デフォルトのストアは aio-lib-state を使用します。

Worker ハンドラー（createFfcpeNodeWorker）

• FfcpeNodeWorkerHandler を実装します。非同期の ({ jobId, inputs, params, logger, authContext, args }) です。inputs は検証済みの FFCPE input[]、params は run-workflow からのワークフローパラメーター（submit の parameters）、args は Worker の呼び出しオブジェクト全体（OpenWhisk main(args)）です。
• { status: "completed", outputs?: ActionOutput[] } または { status: "failed", error: string } を返します。
• submit ペイロードに名前付き入力が含まれていない場合に即時失敗させるには、オプションで requiredInputNames を使用します。
• 失敗を SDK の failed-job 動作に意図的にマッピングする場合に限り、FfcpeJobFailedError をスローします（アダプターはハンドラーの failed 結果をすでにマッピングします）。

@adobe/ffcpe-custom-node-core の findInputByName、getTextInput などを優先して使用し、TextInput、ImageInput、VideoInput、JsonInput で型を絞り込んでください。createTextOutput、createImageOutput、createVideoOutput、createJsonOutput（および関連ヘルパー）を使用して出力を構築します。

HTTP コントラクト（Workflow Builder が想定する内容）

Workflow Builder は { inputs, parameters } を submitEndpoint に POST し、ステータスが completed または failed になるまでポーリングします。submit のレスポンスには jobId、status、およびポーリング用の statusUrl を含めるのが理想的です。

ヘッダーのルール、レスポンスのフィールド、ポーリングの仕様については、SDK ドキュメントバンドルまたはソースツリー内の docs/custom-action-requests.md を参照してください（メンテナー向けに、同じ資料がリポジトリの README の隣にもあります）。

セキュリティと堅牢性（カスタムアクションの作成者向け）

• inputs と parameters は信頼できない入力として扱います。アセットを取得または処理する前に、型、サイズ、URL を検証してください。
• トークン、API キー、生の Authorization ヘッダーは決してログに記録しないでください。Logger の出力は最小限にしてください。
• 可能な場合は HTTPS のアセット URL を使用してください。SDK の外で独自の fetch ロジックを実装する場合は、不審なスキームやリダイレクトを拒否してください。
• authenticate: null を渡す明示的かつレビュー済みの理由がない限り、submit/status の認証を有効にしてください。

上級者向け／回避手段

• HTTP のみを Core で処理 — Hono を使用しない場合は handleFfcpeSubmit、handleFfcpeStatus、または runWorkerJob を使用します（それでも JobStore、JobOrchestrator、InboundAuth、ステータス URL ビルダーが必要です）。
• カスタムのオーケストレーションまたはストレージ — Core のポート（JobStore、JobOrchestrator）を実装し、上流 README の「別の Cloud Functions プロバイダー向けの実装」セクションにあるチェックリストに沿ってください（アダプターの動作をフォークする場合も同じ考え方が適用されます）。

クイックリファレンス

インポート用のチートシート、pnpm link、トラブルシューティング（ステータス URL、ウェブマニフェスト）については、references/quick-reference.mdを参照してください。