dingtalk-aicard

DingTalk AI Cards V0.8

ユーザーのコンテンツや画像から A2UI ファイルを作成または編集し、必要なコントラクトだけを参照して、ローカル検証、配信、クライアントでのレンダリングを区別します。この Skill では、A2UI 1.0 をベースとする DingTalk V0.8 パッケージを使用します。メッセージの version は "v1.0"、送信 API の protocolVersion は "1.0" です。

ユーザーが依頼した参照、ファイルの作成、送信、更新をそのまま実行してください。参照の順序に従う必要はありません。コマンドとプロトコルの要件を守ってください。結果に影響する情報、操作の意味、対象が不明な場合に限り、質問してください。

意図に応じた参照先

関連する参照だけを読みます。プロトコル全体、すべてのパターン、ガイド全体を先に読み込まないでください。

意図	最初に読む参照	必要に応じて追加する参照
参照と検証の準備	実行環境	インストール済みコマンドのヘルプ
コンテンツや画像からの作成・再設計	ビジュアルの焦点とレイアウト	関連するパターンまたは例を1つ
既知の名前を検索	名前を指定したコントラクトの検索	検索結果のソースポインター
不明な名前を検索	コンポーネント、関数、またはトークンのインデックス	選択した名前だけを検索
カードの構築・修復	構築と検証	診断ポインターと名前を指定したコントラクト
送信、プレビュー、更新	配信の境界	インストール済みコマンドのヘルプ

パターンは構成のガイダンスに、リンク先の JSON はメッセージの形式に使用します。名前が分かっている例は直接参照し、例のインデックスは選択にのみ使用してください。

構成パターン

コンテンツ	参照先
通知とリマインダー	通知
オブジェクトの事実と判断	詳細
イラスト付きコンテンツと添付ファイル	コンテンツ
指標とレポート	レポート
編集可能な入力と送信	フォーム
生成と実行の更新	進捗

編集可能な入力の場合は、別のパターンでカードが説明されている場合も、バインディングと送信についてフォームパターンも参照してください。 実行例を再生する場合は、JSONを直接選択した場合も、バッチの境界について例と再生を読んでください。

実行環境

このエディションでは Python ではなく、ネイティブの DWS コマンドを使用します。dws aicard --help に explain、lint、preview が表示されることを確認してください。Skill をコピーしても、コマンドはインストールされません。参照と lint はオフラインで実行でき、Profile は不要です。各コマンドの最新のヘルプと構造化されたエンベロープ（ok、outcome、data、または error.details）を確認してください。利用できない場合、参照をドラフト作成の参考にはできますが、DWS による検証を行ったと主張しないでください。

名前を指定したコントラクトの検索

dws aicard explain Tabs --format json
dws aicard explain Text Row Column --compact --format json

必要な名前だけを検索してください。簡潔な $contractRef と definitions は検索メタデータであり、A2UI フィールドではありません。展開されたフィールドを取得するには --compact を付けずに検索してください。省略された詳細の場所は source で確認できます。

構築と検証

契約として references/protocol/ を使用します。順序付きの JSON メッセージ配列を作成します。 1 つのカード内では同じ surfaceId を維持し、カードの作成時にはそのカードに適した ID を選択します。 新しいカードを完成させるには、Surface の作成、ルートデータの初期化（静的コンテンツの場合も {}）、および ID が root のコンポーネントが必要です。 推奨される明示的な形式は次のとおりです。

[
  {"version":"v1.0","createSurface":{"surfaceId":"example-surface","catalogId":"https://dingtalk.com/card/a2ui/catalogs/public/catalog.json"}},
  {"version":"v1.0","updateDataModel":{"surfaceId":"example-surface","path":"/","value":{}}},
  {"version":"v1.0","updateComponents":{"surfaceId":"example-surface","components":[{"id":"root","component":"Text","text":"Example"}]}}
]

これは構造を示す例であり、送信するビジネスカードではありません。createSurface.dataModel と createSurface.components での、プロトコルに準拠したインライン初期化も受け付けられます。3 つの個別メッセージだけが有効な形式ではありません。

シナリオ	メッセージとチェック
新しいカードを完成させる	上記のとおり作成して初期化し、--preflight new-card を使用します
ホストが作成した空の Surface	createSurface を使わず、既存の ID を初期化します。Schema とリソースのチェックを使用します
既存カードの更新	ID を維持して、意図した変更のみを送信します。Schema とリソースのチェックを使用し、既知の現在の状態と照合します

完成したファイルから createSurface を削除しても、安全な差分にはなりません。 フォームのデフォルト値や無関係な初期データを再送信しないでください。ユーザー入力が上書きされる可能性があります。リソースのチェックだけでは、更新によって状態や参照が維持されることを証明できません。

編集時は、無関係なスタイルを維持してください。通常の新しいカードでは、背景フィールドを持たないルート Column を推奨します。ルートに Card が必要な場合は、背景トークンを使わず backgroundColor: "#00FFFFFF" を使用してください。明示された Surface のデザインに従い、デザインガイダンスを参照してください。

リッチテキストや静的テーブルには Markdown を、短いタイトルやラベルには Text を推奨します。通常のカードではルートの padding を省略してください。デフォルトで CardHeader を使用しないでください。指定されている場合は維持し、インセットを確認してください。

提示された事実と要求されたインタラクションを維持し、デモデータにはその旨を明記してください。納品前に REPLACE_* プレースホルダーを置き換えてください。未検証のリソース、接続されていないアクション、またはシミュレーション状態を、実際に動作するものとして提示しないでください。

フィールドの仕様に応じて、リテラルまたはバインディングを選択してください。バインディングされたデータは必須の型で初期化し、updateDataModel を通じて更新します。コンポーネントのリテラルは updateComponents で変更します。sendDataModel は、A2A メッセージにデータモデル全体を含めるかどうかを制御するものであり、バインディングの動作を制御するものではありません。

dws aicard lint --file card.a2ui.json --format json

選択したシナリオに応じて --preflight new-card または --preflight resources を選択します。シリアライズされたメッセージ文字列が必要な場合にのみ --emit を使用してください。--emit は --fragment と併用できません。終了ステータスと、選択した場合は data.valid および data.preflight.valid を確認してください。dws aicard lint --self-check --format json でパッケージ全体を検証できます。

検証範囲

Lint は構文と Schema フィールドをチェックします。新規カードの事前検証では、初期化、ルート、メッセージ内の重複 ID、最終コンポーネントスナップショット内の静的参照と循環をチェックしますが、中間のストリーミングフレームはすべてチェックしません。到達不能なコンポーネントは警告されます。リソースの事前検証ではインラインエンコーディングをチェックします。どちらのモードもバインディングを評価せず、画像の読み込みを証明するものではありません。--fragment はコンポーネント／メッセージのフラグメントをチェックするものであり、新規カードの初期化を回避する方法ではありません。チェックに合格させるために、ユーザーデータを書き換えたり、要求されたコンポーネントを削除したり、インタラクションを格下げしたりしないでください。

名前付きルックアップが成功しても、パッケージ全体のチェックにはなりません。選択した実行環境がサポートするセルフチェックを使用してください。ローカルチェックだけでは、クライアントの動作は確認できません。

配信の境界

ネイティブの --emit を使う場合は、data.a2uiMessages を読み取ります。

要求された場合にのみ送信します。送信プロファイルの下で、会話の場合は --conversation-id、人物の場合は --open-dingtalk-id を使い、対象を正確に1つ解決します。名前は対象 ID ではありません。インストール済みコマンドのヘルプを確認し、出力されたメッセージ文字列の配列を1つの --content 引数として JSON エンコードして、dws chat message send-a2ui-card を呼び出します。要求、対象、プロファイル、返された bizId を保持します。結果が不確かな場合は、別の作成を行う前に確認してください。自動で再送信してはいけません。

作成時の状態は PROCESSING です。元のプロファイルの下で dws chat message update-a2ui-card --biz-id <bizId> --content <message-strings> --flow-status <state> を使って更新します。同じ surfaceId とコンポーネント ID を維持し、別の createSurface や無関係なデフォルトではなく、意図した updateDataModel または updateComponents の変更のみを送信します。静的カードには、空でない有効な差分とともに --flow-status FINISH が必要です。送信前に用意し、ビジネスデータを保持してください。JSON トークンではなく、完全なメッセージをストリーミングします。リソースの事前チェックでは差分のみを確認します。現在の状態がわかっている場合は、差分と合わせて検証してください。スキーマが有効でも、ビジネス上の安全性が証明されるわけではありません。

dws aicard preview --file card.a2ui.json は PROCESSING 状態でセルフプレビューを送信します。--dry-run は送信しません。静的プレビューを完了するには、同じプロファイルの下で dws chat message update-a2ui-card --biz-id <data.bizId> --content <message-strings> --flow-status FINISH を使い、同じ Surface に対する、状態を保持する空でない差分を指定します。フォームのデフォルトを再生してはいけません。リクエスト側の bizCardId ではなく、サーバーが発行した data.bizId を使用します。これがない場合は updateWarning とレシートを確認し、自動で再作成してはいけません。openTaskId は query-send-status では使用できません。

送信後は、利用可能な読み戻し機能を同じプロファイルと対象の下で使用し、返されたインスタンス ID／メッセージ ID から、このカードそのものを特定します。一般的なカードのテキストと近接するタイムスタンプだけでは不十分です。要求の受理、同一対象での読み戻し、クライアントでのレンダリング、操作をそれぞれ分けて報告します。読み戻しが利用できない、または結論が出ない場合は、未検証としてください。API に受理されたというだけで、ユーザーにカードが届いた、または正しくレンダリングされたと主張してはいけません。

要求された場合は、ファイル、実際に実行したチェック、配信結果を報告します。ローカルでの検証と要求の受理だけでは、クライアントでのレンダリングは証明されません。