live-artifact

Live Artifact スキル

OpenDesign のライブアーティファクトを作成します。これは、プロジェクト単位のプレビュー可能な HTML アーティファクトで、表示を再設計することなく、後からデータを更新できます。

リソースマップ

live-artifact/
├── SKILL.md
└── references/
    ├── artifact-schema.md      ← `references/artifact-schema.md`: artifact files, DTO shape, template binding rules
    ├── connector-policy.md     ← `references/connector-policy.md`: connector safety, redaction, credential boundaries
    └── refresh-contract.md     ← `references/refresh-contract.md`: source metadata, refresh execution, snapshots

現在の状況

ライブアーティファクトのファイル仕様については、このディレクトリにあるリファレンスを正としてください。ライブアーティファクトの登録や更新には、未加工の HTTP よりもデーモンラッパーコマンドを優先してください。

このスキルを使用する場面

初回の表示後も役立ち続ける、データに基づくビューをユーザーが求めている場合に、このスキルを使用します。たとえば、ライブダッシュボード、更新可能なレポート、同期されるステータスページ、監査可能なデータビュー、またはローカル／プロジェクトデータやコネクターから後で更新できるアーティファクトなどです。

ファイルを作成する前に、ユーザーが本当にライブアーティファクトを求めているのか、通常の静的アーティファクトを求めているのかを判断します。

• ユーザーが更新、同期、定期的な更新、コネクターに基づくデータ、ソース／来歴の追跡、ダッシュボード、レポート、再利用可能なデータに基づくビューについて言及している場合は、ライブアーティファクトを使用します。
• ユーザーが単発の HTML／モックアップ／画像／ファイルのみを求めており、更新、ソースメタデータ、データ／来歴パネルを必要としていない場合は、通常の静的アーティファクトを使用します。
• 意図が曖昧な場合は、短く質問します。「更新可能なライブアーティファクトにしますか、それとも静的なアーティファクトにしますか？」

ワークフロー

1. 接続済みのコネクターがなくても作業を止めず、スコープとデータソースを決定する

   • プレビューの目的、対象者、データの鮮度に関する要件、後から更新できる必要があるかどうかを確認します。
   • ユーザーが Notion、GitHub、Slack、Google Drive などのコネクター／ソースを明示した場合は、デーモンのコネクターツールを確認する前に「データはどこから取得しますか？」と尋ねないでください。
   • 利用可能な場合は、ローカル／プロジェクトのソースまたはデーモンのコネクターツールを優先します。
   • デーモンコネクター／ラッパーがある場合は、プロバイダー API を直接呼び出さないでください。
   • コネクターデータが必要な場合は、まず "$OD_NODE_BIN" "$OD_BIN" tools connectors list --format compact を使ってコネクターの一覧を取得します。指定されたコネクターが status: "connected" で存在する場合は、カタログから適切な読み取り専用の auto ツールを選び、コネクターラッパー経由で実行します。
   • Notion の場合は、接続済みの notion コネクターがあり、ユーザーの依頼内容で Notion が指定されていれば、依頼されたアーティファクト／トピックからクエリを作成し、notion.notion_search で検索を開始できます。notion.notion_fetch_database を使用するのは、ユーザーからデータベース ID が提供された場合、または検索結果からデータベースを明確に特定できる場合に限ります。
   • 該当する接続済みコネクターがない場合、接続済みの候補が複数あり、どれも同程度に適している場合、または作成するアーティファクトに検索可能なトピック／クエリがない場合に限り、ユーザーにデータソースについて質問します。質問が必要な場合は、具体的に、ページ／データベース／トピック、または広範囲に検索する許可を尋ねてください。「Notion のデータソースはどこですか？」とは尋ねないでください。

2. ソースファイルを作成する

   • 人が設計した HTML テンプレートとして template.html を作成します。デーモンは html_template_v1 バインディング契約を使用して data.json を読み込み、テンプレートにデータを反映します。契約の範囲内で作成してください。範囲外の場合はデータの反映に失敗し、{{…}} トークンが見える状態のまま、生のテンプレートが出力されます。
     • スカラー値：{{data.path.to.value}}。パスは data から始まり、ドットで区切ります。数値の配列インデックスも使用できます（{{data.kpis.0.value}}）。各バインディングの解決先は、オブジェクトや配列ではなく、単一の文字列または数値である必要があります。
     • リスト：data-od-repeat="item in data.items" を指定して要素を繰り返し、その要素内でループスコープのフィールドを {{item.label}}（またはスカラー配列の場合は {{item}}）としてバインドします。繰り返しは 1 階層のみです。繰り返しの中でも、グローバル値には引き続き data.* を使用できます。
     • <script> 内で手動のループ処理を行わないでください（プレビューではスクリプトが除去されます）。また、一致する data-od-repeat スコープがない状態で {{metric.value}} のようなループ変数を直接参照しないでください。このバインディングは解決できません。入れ子の繰り返し、条件分岐、フィルター、ヘルパー、raw／トリプルブレース補間はサポートされていません。
   • バインディングで使用するプレビュー用の正式なデータとして、data.json を作成します。プレースホルダーではなく、実際の値を使用してください。
   • ライブアーティファクトのメタデータ、プレビュー宣言、ドキュメント宣言、安全なソース記述子を含む artifact.json を作成します。
   • 簡潔なソースメモ、タイムスタンプ、機密情報を含まないコネクター参照、変換に関するメモを含む provenance.json を作成します。
   • ソースとして index.html を作成しないでください。デーモンが template.html と data.json から index.html を生成します。

3. データを簡潔に保ち、プレビュー向けにする

   • プレビューに必要な、正規化済みの値のみを保存します。
   • 大きなリスト、プロバイダーの応答、ログは要約してから data.json に書き込みます。
   • references/artifact-schema.md に記載されている、上限のある JSON に関するルールを守ってください。

4. 登録前に安全ルールを適用する

   • 認証情報、OAuth トークン、API キー、Cookie、認証ヘッダー、生のプロバイダー応答、HTTP エンベロープ、完全なペイロード、シークレットと思われるフィールドを、artifact.json、data.json、provenance.json、またはソースメタデータに保存しないでください。
   • raw、rawResponse、payload、body、headers、cookie、authorization、token、secret、credential、password など、禁止されたキー名は、永続化する JSON のどこにも使用しないでください。
   • エスケープされた html_template_v1 補間のみを使用してください。raw／エスケープされていない HTML 補間は許可されていません。

5. デーモンのラッパーを使用して登録または更新する

   • 生の curl、単独の node、単独の od ではなく、OpenDesign デーモンのラッパーコマンドを "$OD_NODE_BIN" "$OD_BIN" 経由で使用します。

     "$OD_NODE_BIN" "$OD_BIN" tools live-artifacts create --input artifact.json
     "$OD_NODE_BIN" "$OD_BIN" tools live-artifacts list --format compact
     "$OD_NODE_BIN" "$OD_BIN" tools live-artifacts update --artifact-id "$ARTIFACT_ID" --input artifact.json
     

   • ラッパーは、注入された OD_NODE_BIN、OD_BIN、OD_DAEMON_URL、OD_TOOL_TOKEN を読み取ります。トークンの値を表示、永続化、または上書きしないでください。

   • projectId を含めたり、作成したりしないでください。デーモンはトークンからプロジェクト／実行スコープを判定します。

   • 生の HTTP を使用できるのは、明示的に求められたデーモンの開発／デバッグ時のみです。

6. コネクタのデータにはコネクターのラッパーを使用する

   • 利用可能なコネクターとツールを確認します。

     "$OD_NODE_BIN" "$OD_BIN" tools connectors list --format compact
     

   • JSON オブジェクトの入力ファイルを使用して、読み取り専用のコネクターツールを実行します。

     "$OD_NODE_BIN" "$OD_BIN" tools connectors execute --connector "$CONNECTOR_ID" --tool "$TOOL_NAME" --input input.json
     

   • プレビューに必要なコンパクトな正規化フィールドと、機密性のないコネクター参照（connectorId、toolName、accountLabel）のみを永続化します。コネクターの認証情報、トランスポートメタデータ、プロバイダーの生出力は決して永続化しないでください。

   • コネクターのシークレットを要求したり、セットアップを重複させたりしないでください。status が connected の場合は、一覧表示されたツールを使用します。接続されていない場合は、UI で接続するようユーザーに伝えてください。

   • 一覧表示／実行と認証情報の境界については references/connector-policy.md を、読み取り専用リフレッシュのソースメタデータについては references/refresh-contract.md を参照してください。

7. 簡潔な結果を報告する

   • 成功した場合は、アーティファクトの ID／タイトルを返し、index.html がデーモン生成であることを明記します。
   • 検証に失敗した場合は、ソースファイルを修正し、ラッパー経由で再試行します。検証をバイパスしないでください。

必須ファイル

すべてのライブアーティファクト作成フローは、登録前にこれらのソースファイルを生成する必要があります。

• template.html — 宣言されたスキル出力であり、プレビュー用のソーステンプレートです。
• data.json — コンパクトで正規のプレビューデータ。
• artifact.json — デーモン検証用の作成／更新入力。
• provenance.json — 安全なソースと変換の概要。

index.html は frontmatter で宣言された主要なプレビューエントリですが、エージェントが作成したソースではなく、デーモンが生成する派生出力です。