kuroco-external-integration-design
Installation
SKILL.md
Kuroco 外部システム連携設計
位置づけ
3パターン（直接呼び出し／プロキシ／取り込み）の選定基準は /kuroco-app-builder の0-4と共通。本スキルはその先——選んだ後に何を確認し、何に気をつけるかを深掘りする。Smartyプラグインの正確な構文は /kuroco-server-processing が正であり、本スキルはそれを設計判断の材料として引用する。
相手がREST APIであれば、{api}プラグインはメソッド・ヘッダー・ボディ・ファイル送信・mTLSまで一通り揃っており、「繋がるかどうか」自体で詰まることはまず無い。 プロキシパターンを検討する際の設計の重心は「REST的に呼べるか」ではなく、(1) 定数・シークレットの置き場所（後述）と**(2) トークンのライフサイクル管理**（後述）に置く。この2つを詰め切らずに実装へ進むと、動くものはできても運用開始後にトークン切れ・鍵の誤配置で止まる。
3パターンのおさらい
| パターン | 構成 | 向くケース |
|---|---|---|
| 直接呼び出し | フロントエンドが外部APIを直接呼ぶ。Kurocoは関与しない | 外部API側がCORS許可済み・鍵をフロントに置いてよい・リアルタイム性最優先 |
| プロキシ（Kuroco経由） | カスタムエンドポイントのSmartyテンプレートから {api} プラグインで外部APIを呼び、結果を返す |
鍵を隠したい、認証/CORS/レート制限をKuroco側に一本化したい、レスポンスを加工したい |
| 取り込み | 事前に外部データをTopics/CSVテーブルへ取り込み、標準のTopics APIで提供する | 更新頻度が低い、Kurocoの標準機能（検索・キャッシュ・多言語）に外部データも乗せたい |
プロキシパターンの実装制約
プラグイン名は{api}。api_requestという名前のプラグインは存在しない（{api_internal}はKuroco自身のAPIを呼ぶ別物）。主なパラメータ: