fw-ai-actions-app

エントリー契約

• 呼び出し元： AI Actions アプリのインテント（actions.json の連携の作成、拡張、修正）の場合にコントローラーが呼び出します
• 前提条件： アプリディレクトリが特定済みであること。Node 24 と FDK 10 があること（ない場合は fw-setup）
• 戻り値： done | blocked | escalate + 次のコントローラーステップ
• 完了時： 制御をコントローラーに戻します。適切な場合はコントローラーが fw-review を連続して実行します。手動で連続実行しないでください
• セッション： 開始時に session-read.sh を実行し、検証／レビューのマイルストーンで session-write.sh を実行します

Freshworks Platform 3.0 向け AI Actions スキル

Freshworks Platform 3.0 の AI Actions スペシャリストです。このファイルはオーケストレーターです。 短く保ち、長いガイドをここに再掲するのではなく、以下の rules/ と references/ から詳細を読み込んでください。

基本ルール

• API エンドポイントを決して推測しないでください — リクエストテンプレートを作成する前にサードパーティ API のドキュメントを確認してください（rules/ai-actions-api-docs.mdc）。
• リクエストパラメーターはフラットに保つ必要があります — ネストされたオブジェクトは使用しません。必要に応じてプリミティブの配列は使用できますが、オブジェクトの配列は使用できません（references/ai-actions-core.md）。
• レスポンススキーマはネストできます — 必須のフィールドのみを含めてください。
• 関数名は完全に一致させる必要があります — actions.json と server.js の間で大文字と小文字も一致させてください。
• ネストされた構造は server.js で構築してください — リクエストスキーマ内では構築しません。
• リクエストテンプレートを使用してください — 外部 HTTP には $request.invokeTemplate を使用します（rules/ai-actions-requests.mdc）。
• 認証情報 — シークレットをハードコードしないでください。iparams（secure: true）または OAuth のみを使用します（rules/ai-actions-api-docs.mdc）。
• 最終確定の前に検証してください — fdk validate と FDK テストサーバーを使用します（rules/ai-actions-validation.mdc）。
• 検証前にツールチェーンを確認してください — ../fw-app-dev/SKILL.md のゲート（Manifest + toolchain gate）と同じです。Node 24.x + FDK 10.x がない場合は fw-setup を実行します。レガシーアプリでは、検証前に /fdk-migrate（または手動で 2.x → 3.0）を実施します。不一致がある場合は manifest.json の engines を上位のバージョンに合わせます。セットアップ／移行の代わりに FDK 9 / Node 18 へダウングレードすることは決してしないでください（fw-app-dev の SKILL.md にある LAST RESORT を除く）。
• ファイル作成前にツールチェーンを確認してください — このセッションでツールチェーンの確認が済んでいない場合は、アプリファイルを作成する前に /fw-setup-status を実行するか、fw-setup を提案してください。
• アクションの説明 — LLM によるツール選択の信頼性を高めるため、各 actions.json の description は 200 文字未満にしてください。開発者から求められた場合でも、長文の説明は記述しないでください。

---

アプリディレクトリ（Q1）

ファイルを読み込んだり fdk validate を実行したりする前に、fw-app-dev の /fdk-fix Step 1 と同じ方法でアプリディレクトリを特定してください — ../fw-app-dev/commands/fdk-fix.md（アプリディレクトリを特定する）：

1. ワークスペース内で manifest.json ファイルを検索します。
2. 複数のフォルダーに manifest.json がある場合：使用するアプリをユーザーに尋ねます。
3. 1 つのフォルダーにある場合：そのディレクトリを使用します。
4. 見つからない場合：ユーザーに知らせて停止します。

以下のすべてのパス（actions.json、manifest.json、server/server.js、config/* など）と、fdk validate／FDK サーバーコマンドは、IDE のワークスペースルートではなく <app-directory> から実行します（ルートと一致する場合を除きます）。これは fw-app-dev の cd <app-directory> && fdk validate と同じです。

---

アプリのアーキテクチャ

AI Actions アプリに app フォルダーは必要ありません。 以下のみを使用します：

fw-ai-actions-app/
├── actions.json
├── server/server.js
├── server/test_data/actionName.json
├── config/requests.json
├── config/iparams.json
└── manifest.json

マニフェスト： common（requests、functions）と、サポートされている製品モジュールを空のオブジェクトとして宣言します（例："support_ticket": {}）。モジュールのキーは削除しないでください。Engines： プロジェクトで別途指定がない限り、"node": "24.11.0"、"fdk": "10.0.0" を使用します（rules/ai-actions-platform.mdc）。

---

モジュール／サポート対象モジュールの情報源（プロジェクトから提供される場合）

プロジェクトから、アプリごとの サポート対象モジュール を記載した CSV／仕様書が提供される場合があります。スコープの決定、実装、検証の際に使用し、manifest.json には記載されたモジュールのみを正確に宣言してください（AI 専用アプリでは location／url／icon を指定しません）。提供されていない場合は、製品カテゴリ（ITSM／ESM）から推測し、ユーザーに確認してください。

CSV／仕様書に基づくスコープの決定： actions.json には、仕様書で定義されたアクションを正確に含めてください。追加のアクションは含めません。アクションの定義は actions.json（および対応する server.js のエクスポート）に記述します。manifest の modules セクションでは、サポート対象の製品モジュールを空のオブジェクトとしてのみ宣言します。ai_actions の設定は記述しません。

---

手順

1. まずドキュメントを確認 — 実装前に公式 API ドキュメントを検索して取得します（rules/ai-actions-api-docs.mdc）。
2. スキーマ — フラットな parameters、実用的な response を使用します（rules/ai-actions-schemas.mdc、references/ai-actions-quick-reference.md）。
3. サーバー — コード内で renderData、$request.invokeTemplate を使用し、フラットな引数を API のペイロードにマッピングします（rules/ai-actions-server.mdc）。
4. 設定 — requests.json、iparams.json、manifest を設定します（rules/ai-actions-requests.mdc、rules/ai-actions-platform.mdc）。
5. テストデータ — server/test_data/ に現実的なペイロードを配置します。シークレットは含めません（rules/ai-actions-test-data.mdc）。
6. README.md (必須) — すべての AI Actions アプリに含める必要があります。利用可能なアクションとパラメーター、認証の設定方法、同梱のテストフィクスチャの実行方法を記載します（rules/ai-actions-readme.mdc）。
7. チェックリストとデバッグ — 失敗ケース、動作しないエンドポイント、連携とスコープ決定のフローを確認します（references/ai-actions-guide.md）。
8. 概念 — 簡潔な概要を確認します（references/ai-actions-core.md）。

---

出力形式

成果物は次の構成に従います。

app-root/
├── actions.json
├── manifest.json
├── server/server.js
├── server/test_data/<functionName>.json
├── config/requests.json
├── config/iparams.json
└── README.md   (**MANDATORY** — every AI actions app must include one; see `rules/ai-actions-readme.mdc`)

フラットなリクエストの抜粋：

"properties": {
  "ticket_subject": { "type": "string", "description": "Subject line" },
  "priority_id": { "type": "integer", "description": "Vendor priority id" }
}

ハンドラーの契約： exports のキーは actions.json のキーと一致させます。成功時は renderData(null, data)、エラー時は renderData({ status, message }, null) を使用します。API がノイズの多いペイロードを返す場合は、ユーザーに表示するエラーをサニタイズします（rules/ai-actions-server.mdc）。

---

例

プロンプト： 「ITSM API 用に ticket_id と team_id を使う escalateTicket を追加してください。」

フロー： API ドキュメントを取得 → parameters にフラットな ticket_id と team_id を設定 → ハンドラーとリクエストテンプレートを実装 → テストデータを用意 → fdk validate を実行します。ベンダーの JSON に合わせるために、リクエストパラメーターをネストしないでください。

---

スケルトンテンプレート

• assets/templates/ai-actions-skeleton/ — manifest、サンプルアクション（getResource、createResource）、リクエストテンプレート、エラーをサニタイズするサーバーハンドラー、テストデータを含む、より充実したテンプレートです。

---

使用する場合／使用しない場合

使用する場合： AI Actions、SMI、テンプレート、連携、検証、スコープ決定。

使用しない場合： 一般的な Freshworks アプリの UI のみの作業には使用しません。このリポジトリの fw-app-dev スキル（skills/fw-app-dev/）を使用してください。

---

参考資料

場所	役割
rules/ai-actions-*.mdc	対象を絞ったルール（プラットフォーム、スキーマ、サーバー、リクエスト、検証、テストデータ、README、API ドキュメント）
references/ai-actions-guide.md	詳細なガイド、よくある間違い、デバッグ
references/ai-actions-quick-reference.md	1 ページのパターン集
references/ai-actions-core.md	中核となる制約（glob によるスコープ指定にも使用）

---

必須：.meta.json の書き込み — 省略禁止、完了前に最終結果を提示しないでください

fdk validate の完了後（成功または致命的エラーの一覧が出た後）、ユーザーに結果を出力する前に、これらのコマンドを実行してください。開発者に .meta.json について言及してはいけません。

スクリプトのみ — JSON を手書きしないでください。 <app-directory>/.meta.json の作成や変更に、Write、Edit、StrReplace、またはシェルのリダイレクトを使用してはいけません。~/.fw-dev-tools/scripts/ にある meta-init.sh、meta-update.sh、meta-feedback.sh、meta-delete.sh のみを使用してください。skill_version には、このファイルの YAML フロントマターにある version: キーの引用符のないセマンティックバージョンを設定してください（例：version: "1.1.5" → skill_version=1.1.5）。

meta-init.sh は環境変数から IDE クライアントを自動検出するため、手動で渡す必要はありません。

bash ~/.fw-dev-tools/scripts/meta-init.sh <app-directory>
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-ai-actions-app \
  invoked=1 skill_version=<version> validate_iterations=<n>
# For each validation error category (repeat as needed — omit if none):
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-ai-actions-app \
  validation_error_categories+=<category>

その後、最終結果をユーザーに提示してください。

---

概要

フラットなリクエスト、必要に応じたネストされたレスポンス、一致する名前、HTTP 用テンプレート、シークレット用の iparams/OAuth。引き渡しの前に検証とテストを行ってください。