AI Des2WF — I/O 定義
guinness-ai-v2 の apps/des2wf/ の契約です。1 つの Figma デザインフレームをワイヤーフレーム spec と
構造レコードへ変換します。フィールドや挙動を変更したら、テストケース と
Backend 契約 にも反映します。
実行ファミリー
生成は one-shot です。同一 invocation 内で parse から assemble へ続き、
confirm の停止点、awaiting_confirm、ルール取り込みはありません。ワーカーは PostgreSQL に書きません。
別の完了後レンダーレビューメッセージが、プラグイン構築後に完了済み結果を更新できます。
共有契約プリミティブ
edge 識別子
生成は専用 DES2WF キューへ edge=des2wf を送り、Webhook は type=des2wf を使います。
任意フィールドの有無から推論しません。共有 PG テーブル名は wf2des のままなので、
manifest の反映先は両 edge とも row_effects.wf2des です。
Generation メッセージ
{
"edge": "des2wf",
"job_id": "01J...",
"attempt": 1,
"nonce": "...",
"phase": "parse",
"organization_id": 1,
"project_id": 7,
"figma_file_key": "...",
"source_node_id": "64:6716",
"design_snapshot_url": "s3://bucket/path/design.json",
"design_png_url": "s3://bucket/path/version-matched-source.png",
"source_hash": "<frame-subtree-sha256>",
"screen_id": null,
"mode": "primitives",
"layout": "auto"
}
| フィールド | 契約 |
|---|---|
edge |
必須の des2wf リテラル |
job_id、attempt、nonce |
空でない共有行 ID、1 以上の attempt、空でない attempt nonce |
phase |
parse（既定）または assemble。通常は同一 invocation で両方を実行 |
organization_id、project_id |
正の ID |
figma_file_key、source_node_id |
入力ファイルとデザインフレームの identity |
design_snapshot_url、source_hash |
必須の S3 snapshot URL とフレームサブツリーのハッシュ |
design_png_url |
任意の S3 URL、既定 null。backend が取得した同一バージョンの元画像。旧メッセージも有効 |
screen_id |
任意。通常の DES2WF では null |
mode |
primitives（既定）または kit |
layout |
absolute（API／ワーカーの既定）または auto。現在のプラグインは上例のように auto を明示送信 |
2 種類のワイヤーフレーム
mode |
出力 | モデル利用 |
|---|---|---|
primitives |
中立的なプリミティブ、原文の文言、意味を持つグラフィックの保持 | 利用可能な元 PNG がある場合、文脈を使う画像分類 |
kit |
同じ方針に採用されたキットバリアントを追加 | 画像分類に加え、サンプリングの多数決によるキット選択 |
キット選択は異なるデザインコンポーネントの文脈ごとに行い、コードに埋め込んだ対応表ではありません。 キットがない／使えない場合や提案が拒否された場合はプリミティブを保持します。 両 mode ともモデルを利用でき、再実行時のバイト単位の一致は保証しません。
2 種類のレイアウト
absolute は描画行を root 直下の元座標に置き、再フローしません。
auto は子が 1 つのラッパーも含め、元の所有階層と itemSpacing、padding、alignment、baseline、
wrap を保持します。ラッパーを削除して新しい兄弟間隔を実測する方式ではありません。
絶対配置オーバーレイはフロー外に置き、軸ごとの sizing と最小／最大寸法は source_layout で運びます。
どちらも文言を保持します。
スナップショットエンベロープ — マップを保持すること
保存する document はデザインフレームのサブツリーのみです。マップは参照分に絞り、
publish key と名前付き style identity を保持します。sectionNodeId は backend の取得範囲だけを狭め、
不正ならファイル全体の検索へ戻りますが、兄弟やボード注記は保存しません。
source_hash はフレームサブツリーのハッシュです。
backend はフレームを取得したレスポンスのトップレベル Figma version を保持し、 同一 version・absolute bounds の元 PNG を best-effort で取得します。両方で要求ユーザーの PAT を使います。 version がない、export／upload が失敗した場合は、新しい未固定画像で代用せず PNG URL を省略します。 不変の PNG キーには source hash と render hash を含めます。ストア を参照してください。
Generation — parse フェーズ
parse は JSON snapshot から決定的にツリーを抽出します。identity、境界、文言、paint、style key、
component ID／variant、元の layout、source_layout、text_geometry を含みます。
コンポーネントマスターにはページ用の tree extractor ではなく derive_component_context を使い、
バリアント境界を保ちます。
| 不正入力 | エラー |
|---|---|
| 入力が FRAME に解決しない | invalid_input.not_a_frame |
| 可視の作成済み子孫がない | invalid_input.empty_frame |
| snapshot が設定上限（既定 20 MB）を超える | invalid_input.snapshot_too_large |
プラグインは受け付けたフレーム系の選択を取得前に正規化できますが、ワーカーの FRAME 契約は変わりません。
デザインかどうかの判定器はありません。based_on=1 は出力の由来を記録するもので、
このフィールドだけで全下流利用者が再入力を拒否するとはみなせません。
Generation — assemble フェーズ
現在の順序は、任意のキット選択 → classify_sync → census → apply_kit →
record_rendered_policy → emit → score です。census の種別は text、box、region、
rule、ink、ornament、instance、glyph で、出力 spec は既存の 5 ケースのままです。
分類器は画面全体、元図形と所属コントロールの切り抜き、名前、variant、祖先、境界、ローカルラベルを受け取ります。 候補の発見は構造的であり、名前・サイズ・画像形式だけで置換を許可しません。
| 判断 | 適用する出力 |
|---|---|
| direction、action、state、identity、list marker、unknown、不確かな図形 | glyph：元図形を保持 |
高信頼の simplify、情報を持たず、role が content_image または redundant_artwork |
ink：プレースホルダー。redundant artwork は実在するローカル label_node_id も必要 |
同じガードで role が decoration |
ornament：非描画。必要な透明フロー領域は残す |
| 明示的な人手 override | スコープ付き preserve → glyph、simplify → ink。ノード指定が完全一致 component／variant より優先 |
ワーカーは graphic_override_v1 だけを読み、旧キャッシュ verdict は使いません。
分類は出現箇所ごとで、AI 判断を文脈間で自動再利用しません。
1 バッチ 6 候補、3 並列、分類全体で 180 秒とし、再帰的な交互配置で全候補を対象にします。
PNG は取得サイズ 20 MiB、デコード後 32,000,000 ピクセルまでで、境界とアスペクト比を検証します。
根拠の欠落／不正、不正／不完全な返答、未知／重複 ID、provider 障害、タイムアウトでは
図形を保持し、フォールバック理由を記録します。
キット提案には unreachable、copy_truncated、slot_overflow、imagery_heavy、
size_implausible、unknown_atom のガードを適用します。描画行は lineage に対応させます。
意図的な装飾抑止は明示的な例外であり、任意のノード削除ではありません。
文言は原文のままです。source-aware text は組版と中立色のリテラルを保ちますが、 フォント代替や必要な再フローで改行は変わり得ます。通常の面は中立的な境界にし、罫線と選択状態の印は 塗りを持つ場合があります。保持グラフィックを強制的に塗り直しません。 構築の詳細は 抽象化アーキテクチャ を参照してください。
出力
| 出力 | 契約 |
|---|---|
| キャンバスのフレーム | プラグインが構築。既定 des2wf · {source_name}、名前が空なら spec version。明示的な spec.name が優先 |
WireframeDoc |
DocumentDB wireframe。based_on=1、type=0、memos=[]、算出済み summaries。注記は生成しない |
| 結果成果物 | S3 result.json：spec、score フィールド、graphic_classification |
| 結果ドキュメント | des2wf_generation_result：run identity／scope、spec、入れ子の score、flag_count、lineage、graphic_classification |
| Manifest | S3 成果物参照と row_effects.wf2des |
| 完了 PG 行 | ワーカーではなく backend の ai-status が更新 |
render_review |
結果ドキュメントへの任意の完了後追加 |
PG の wireframe／structure、コンポーネント出力 |
延期中。参照可能な出力は DocumentDB ドキュメント |
保存された WireframeDoc.name は引き続き wf · {デザインフレーム名} を使います。
これは修正済みのプラグインのキャンバス名とは別です。出力 ID は
{project_id}_{figma_file_key}_{node_id}~des2wf で、WF2Des の接尾辞なしドキュメントには触れません。
Spec の追加フィールド
Des2wfSpec は {spec_version, edge, source_name, source_file_key?, name?, root} です。
style_bindings と parse_confirmed はありません。source_file_key は元グラフィックとテキストの
検索範囲を限定し、別ファイルの同じ ID を黙って clone してはいけません。
| フィールド | 形状 |
|---|---|
source_layout（source-aware node の任意項目） |
horizontal／vertical：FIXED、HUG、FILL。positioning：AUTO、ABSOLUTE。strokes_in_layout、hidden。任意の min_width、max_width、min_height、max_height |
text_geometry（text の任意項目） |
font_family、auto_resize（NONE／HEIGHT／WIDTH_AND_HEIGHT／TRUNCATE）、line_height、line_height_pct、px の letter_spacing、leading_trim（NONE／CAP_HEIGHT）、vertical_align（TOP／CENTER／BOTTOM）、paragraph_spacing、paragraph_indent |
glyph_source（layout frame 上） |
実際の元図形を保持するノード参照。既定マスターではなく、実インスタンスと override を clone |
これらは opt-in です。元ジオメトリを持たない旧 spec は従来の構築動作を維持します。 clone は PALT などの読み取り専用テキスト設定も保持できますが、フォントの利用可能性は実行時の制約です。
グラフィック監査
旧結果では graphic_classification の既定値は {} です。新規実行は以下を記録します。
| フィールド | 意味 |
|---|---|
prompt_version、model |
分類器の identity。現在の prompt は des2wf-graphics-visual-2 |
status |
not-needed、fallback、partial、complete |
source_render_sha256 |
元 PNG のハッシュ、または null |
candidate_count、decisions |
候補数と出現箇所ごとのレコード |
fallback_count、simplified_count |
任意の集計値。候補なしの早期 return では存在しない |
各判断は node_id、適用 action（preserve／simplify）、status
（fallback／override／classified）、reason を持ちます。根拠付きの判断は evidence_sha256 と
proposal を追加でき、proposal は node_id、role、action、confidence、
carries_information、reason、任意の label_node_id を含みます。
キット適用後の rendered_kind、rendered_reason、covered_by は最終表現を示し、
covered-by-source／covered も含みます。simplify が提案された子が保持された親で覆われる場合もあるため、
提案数は可視のプレースホルダー数ではありません。
レンダーレビュー
メッセージは edge=des2wf、kind=render_review、job_id、organization_id、
project_id、必須 S3 design_png_url と wireframe_png_url、任意 nonce を持ちます。
生成時の任意の元 PNG と異なり、レビュー画像は両方必須です。
プラグインは生成開始時の元ノードとプロジェクトに capture を紐づけ、構築結果の job ID を確認します。
backend は upload／enqueue 前に、書き込み権限、行の scope、ボディ jobId の一致
（不一致は 400）、COMPLETED 状態（それ以外は 409）を検証します。
ワーカーは画像 download、モデル、レビュー書き込みより前に結果の scope を検証します。
結果へ render_review を追加し、既存ブロックは render_review_previous へ残します。
reviewed は findings を持ち、skipped は理由と null の finding_count を持ちます。0 ではありません。
export はレビュー用の 8000px 上限に収めます。レビュー失敗で完了済み生成を取り消しません。
Webhook
X-API-Key で認証する POST /v1/webhooks/ai-status に
{type: "des2wf", job_id, attempt, nonce, status} と、成功時の result_manifest_url を送ります。
manifest の row_effects.wf2des は status、result_url、flag_count、score、
score_version を持ち、score 関連は共有 WF2Des 形状への追加です。
parse_done は parse 境界、succeeded は完了と参照、failed は型付き失敗を報告します。
反映は attempt でガードし、古いイベントや終端の再送で新しい結果を上書きしません。
スコア
ds@1.0 = 出力可能性ゲート × 原文の文言保持率（多重集合）。
ゲート失敗は unmatched、strings_invented、text_displaced、cross_over_text、
boxes_coincident、および absolute の場合のみ深さ 2 超です。
strings_lost は保持率を下げ、独立したゲートではありません。
integrity、flatness、ink_covered、boundary_fidelity は weight 0 で報告します。
結果ドキュメントは {score, score_version, gate, band, terms}、PG は score／version のみを持ちます。
kit selection または graphic classification により llm_assisted が true の場合 margin は 0.07、
それ以外は 0.0 です。mode による再現性保証ではありません。
構造スコア 1.0 はアイコン精度や視覚的一致を証明しません。JSON のみの offline corpus は フォールバックとレイアウト、mock model はガードを検証するもので、認識精度ではありません。 視覚評価には実プロバイダーの実行と再生成結果の確認が必要です。
冪等性とフェンシング
- backend が投入前に共有行を作成し、完了時に PG を書く唯一の主体です。
- 結果 commit は job ID と attempt でフェンスし、終端再実行は短絡します。
- open-generation fence は project／file／node／edge を含み、終端または cancel で解放します。 定期 sweep の存在を意味しません。
- レンダーレビューは既存のスコープ付き結果を更新し、未知の job を upsert しません。