calicat-cli-operator

Calicat CLI デザインデータ

Calicat ファイルのデータが必要で、ローカルの calicat CLI が実行手段となる場合に、このスキルを使用します。

このファイルを読む場面

• スキルのトリガー条件
• リンク形式の判定
• 段階的な取得ルール
• ユーザーの意図に応じたタスクの振り分け

必要な場合にのみ追加のリファレンスを読む

• CLI がインストールされていることの確認、バージョンの確認や更新、または別のエージェント／ユーザーへのインストール・更新方法の案内がタスクに関係する場合は、references/cli-lifecycle.md を読んでください。

リンクの解析

Calicat のデザインリンクは、一般に次の3つの形式で表示されます。

ファイルのみ

https://www.calicat.cn/design/2066708151519244288

次のように解析します。

• file_id = 2066708151519244288
• canvas_id = unknown
• selected_layer_id = unknown

意味：

• ユーザーはファイルを指定していますが、特定のキャンバスやレイヤーは指定していません。
• タスクがキャンバス固有の内容に関する場合は、まず get_canvas_list を呼び出してください。

キャンバスリンク

https://www.calicat.cn/design/2066708151519244288?node-id=2066708151531827200&node-type=canvas

次のように解析します。

• file_id = 2066708151519244288
• canvas_id = 2066708151531827200
• selected_layer_id = unknown

意味：

• ここでは node-id がキャンバス ID です。
• この node-id をレイヤー ID として get_meta_data や get_design_data に渡さないでください。
• キャンバス全体に関する作業では、この canvas_id を指定して get_design_page_list を直接呼び出してください。

レイヤーリンク

https://www.calicat.cn/design/2066708151519244288?node-id=21c84811-08c9-42f6-9dc7-82c6992a6ae8&node-type=group

次のように解析します。

• file_id = 2066708151519244288
• selected_layer_id = 21c84811-08c9-42f6-9dc7-82c6992a6ae8
• canvas_id = unknown

意味：

• ここでは node-id がレイヤー ID です。
• node-type=group は、これがキャンバスではなくレイヤーに類するオブジェクトであることを強く示しています。
• まず get_meta_data を呼び出し、その後、デザインデータ全体を取得するかどうかを判断してください。

解析ルール

• 必ず最初に /design/{file_id} から file_id を抽出してください。
• node-type=canvas の場合、node-id を canvas_id として扱います。
• node-type が存在し、canvas ではない場合、node-id を selected_layer_id として扱います。
• node-id は存在するものの node-type がない場合、すぐに推測しないでください。
  • ID が UUID のような形式なら、通常はレイヤー ID です。
  • ID が長い数字列なら、キャンバス ID の可能性があります。
  • ただし、次の手順が重要な場合は、最も軽量で安全な API の経路を選んで確認してください。

安全な解決方法

リンクが曖昧な場合：

• file_id を解析します。
• node-type を確認します。
• それでも曖昧な場合は、大きなデータの取得より先にキャンバスの検出を優先します。
• キャンバスリンクと思われるものに、無理にレイヤー用の手順を適用しないでください。

基本ルール

段階的な取得を優先してください。

大きな get_design_data のペイロードは、コンテキストを簡単に圧迫します。次の判断に必要な情報を得られる、最も軽量な構造取得エンドポイントから始めてください。

• get_canvas_list
• get_design_page_list
• get_meta_data
• get_design_data
• get_interaction_design_data

まずはディレクトリ情報を取得し、完全な内容は後から取得するものと考えてください。

API の選択：get_meta_data と get_design_data

• get_meta_data：ページ／レイヤーの簡略化された構造（レイヤー名、ID、位置、寸法）を、階層を XML 形式で表現して取得します。レイヤーの概要をすばやく確認したり、キャンバス構造を把握したり、容量の大きいスタイル情報を読み込まずに特定のネストされた要素を見つけたりする場合に使用します。
• get_design_data：レイアウト全体と、詳細な CSS／スタイル情報を取得します。正確なコードを生成したり、スタイルを分析したりする場合に使用します。
• 直接取得のルール：対象ページのレイヤー ID がすでに特定されていて（例：get_design_page_list から取得済み）、そのページのフロントエンドコードを実装することが目的の場合は、先に get_meta_data を呼び出さないでください。ページ ID を指定して get_design_data を直接呼び出してください。

ペイロードの保存とコンテキスト管理

get_design_data からの大きなペイロードは、LLM のコンテキストウィンドウを簡単に圧迫します。膨大な JSON ペイロードをターミナルに直接出力するとコンテキストが汚染され、応答が遅くなり、トークンコストが高くなり、トークンが上限を超える可能性があります。

LLM のコンテキストをクリーンに保ち、パフォーマンスを最適化するには、次の点に注意してください。

• 出力をファイルにリダイレクトする：大きな出力ペイロードは、必ずワークスペース内の一時ファイル（例：scratch/page_design.json または temp_design.json）にリダイレクトしてください。
  • Unix Bash/Zsh：

    calicat tools-call --name get_design_data --args '{"file_id":"123","selected_layer_id":"xyz"}' > scratch/page_design.json
    

  • PowerShell：

    $json = '{\"file_id\":\"123\",\"selected_layer_id\":\"xyz\"}'
    calicat tools-call --name get_design_data --args $json > scratch/page_design.json
    

• データに厳密に基づいて実装する（推測や幻覚を避ける）：
  • 不完全なデザインデータやプレースホルダーに基づいて、フロントエンド全体のコードの実装を始めないでください。コーディングは、実際のページデザインデータとユーザーの要件に厳密に対応させる必要があります。推測すると、デザインとコードに不一致が生じます。
  • ページごとにデザインレイアウトを実装してください。単一ページの design_data は、通常、コンテキストの上限を超えない程度のサイズです。または、対象のモジュールコンポーネント／コンテナを特定し、まずそのノードデータのみを抽出してから、その部分を開発してください。
• 巨大な JSON ファイルの処理（ハーネスによる切り詰めを防ぐための分割）：
  • 出力ファイルが非常に大きい場合、ファイル全体を一度に読み取ったり表示したりしないでください。巨大なファイルを直接読み取ると、エージェントハーネスによって切り詰められます。
  • Python や NodeJS などで簡単な解析スクリプトを作成し、巨大な JSON ファイルを小さく論理的なファイル（単一コンポーネント、画面セクション、レイアウトツリーの深さなどで分割）に分けて、scratch/ に保存してください。
  • 分割した小さな JSON ファイルを一つずつ処理し、コードを実装してください。
• 段階的かつ対象を絞った読み取り：保存したファイル全体を一度にコンテキストに読み込まないでください。標準のワークスペースファイル表示ツールで行数を制限して（例：特定の範囲を指定した view_file）、または小さなスクリプト（例：Python／JS）で JSON を解析し、コーディングに必要な特定の UI ノードの詳細だけに絞り込んでください。

最小限の CLI

ツール一覧：

calicat tools-list

Windows シェルでの JSON 引数のエスケープ

実行環境が Windows（PowerShell または CMD）の場合、JSON オブジェクトをシングルクォートで囲んで渡すと、引数の解析で問題が発生することがあります（引用符が削除されるなど）。次のエスケープ規則に従ってください。

• PowerShell：JSON 文字列を変数に宣言し、内部の二重引用符をバックスラッシュ（\）でエスケープしてから、その変数を渡してください。

  $json = '{\"file_id\":\"2045068433773035520\",\"selected_layer_id\":\"e449643f-0bc3-4b75-9fa4-9db5c0b0e402\"}'
  calicat tools-call --name get_meta_data --args $json
  

• CMD：引数オブジェクト全体を二重引用符で囲み、内部の二重引用符をバックスラッシュ（\"）でエスケープしてください。

  calicat tools-call --name get_meta_data --args "{\"file_id\":\"2045068433773035520\",\"selected_layer_id\":\"e449643f-0bc3-4b75-9fa4-9db5c0b0e402\"}"
  

CLI コマンド例（Unix 系 Bash/Zsh）

Canvas 一覧：

calicat tools-call --name get_canvas_list --args '{"file_id":"123456"}'

ページ一覧：

calicat tools-call --name get_design_page_list --args '{"file_id":"123456","canvas_id":"canvas-id"}'

レイヤーメタデータ：

calicat tools-call --name get_meta_data --args '{"file_id":"123456","selected_layer_id":"layer-uuid"}'

レイヤーデザインデータ：

calicat tools-call --name get_design_data --args '{"file_id":"123456","selected_layer_id":"layer-uuid"}'

インタラクションデザイン：

calicat tools-call --name get_interaction_design_data --args '{"file_id":"123456","selected_layer_id":"layer-uuid"}'

PRD 一覧：

calicat tools-call --name get_prd_list --args '{"file_id":"123456"}'

PRD 全文：

calicat tools-call --name get_prd_full_content --args '{"file_id":"123456","prd_id":"prd-id"}'

タスク別の推奨ワークフロー

単一レイヤーのデザイン分析

ユーザーからデザイン URL が提示され、1 つのレイヤーのデザインデータまたはインタラクションデータを求められた場合に使用します。

ワークフロー：

• まずリンクの形式を解析します。
• リンクがキャンバスではなく、実際にレイヤーを指していることを確認します。
• get_meta_data を呼び出します。
• そのレイヤーが対象のものに見えることを確認します。
• get_design_data を呼び出します。
• インタラクションが重要な場合は、get_interaction_design_data を呼び出します。

キャンバス単位の作業

ユーザーが「このキャンバス」「現在のキャンバス」と依頼した場合、またはキャンバス内のすべてのページの処理を依頼した場合に使用します。

ワークフロー：

• まずリンクの形式を解析します。
• URL に node-id と node-type=canvas が含まれている場合、node-id を canvas_id として扱います。
• URL に node-id が含まれていない場合（ファイルのみのリンクなど）、または node-id が曖昧な場合：
  • get_canvas_list を呼び出して、ファイル内のすべてのキャンバスの一覧を取得します。
  • 一覧から対象の canvas_id を特定します（ユーザーに選択してもらうか、コンテキストや既定値に基づいて推定します）。
• 解決した canvas_id を使用して get_design_page_list を呼び出し、ページの一覧を取得します。
• ページのレイヤーを1つずつ処理します。
• 各ページについて：
  • 目的がフロントエンドコードの実装の場合は、ページ ID を使用して直接 get_design_data を呼び出します（get_meta_data は省略します）。プロンプトのコンテキストが不要なデータで埋まらないよう、必ず一時的な JSON ファイルに出力をリダイレクトします。
  • それ以外の場合、ページの骨組みの確認や、取得するコンポーネントレイヤーの特定だけが必要であれば、まず get_meta_data を呼び出します。

要件カードの取得

ユーザーが要件、PRD、概要、または要件カードの内容を求めた場合に使用します。

ワークフロー：

• file_id を解析します。
• get_prd_list を呼び出します。
• タイトルまたは概要で照合します。
• get_prd_full_content を呼び出します。

最初に prd_id を推測してはいけません。

キャンバス全体のフロントエンド実装

ユーザーが「すべてのデザイン」「すべてのページ」「キャンバス全体」のフロントエンドコードの作成を依頼した場合に使用します。

ワークフロー：

• file_id を特定します。
• canvas_id を特定します（URL に node-id が含まれていない場合は、まず get_canvas_list を呼び出してすべてのキャンバスを一覧表示し、対象を選択します）。
• 解決した canvas_id を使用して get_design_page_list を呼び出し、ページの一覧を取得します。
• ページのレイヤーを1つずつ処理します。
• 各ページについて、完全なスタイルの詳細を取得するために get_design_data を直接呼び出し（プロンプトのコンテキストが不要なデータで埋まらないよう、必ず一時的な JSON ファイルに出力をリダイレクトします）、その後、コードを実装または要約します。get_meta_data は省略します。
• 現在のページの処理が完了してから、次のページに進みます。

すべてのページのデザインデータを一度に取得してはいけません。

既定のバッチサイズ：

• 1ステップあたり1ページ
• ペイロードが明らかに小さい場合に限り、2ページ

判断のヒューリスティクス

ユーザーが次のように述べた場合：

• 「このリンク内のレイヤー」 レイヤーパスを使用します
• 「このリンク内のキャンバス」 キャンバスパスを使用します
• 「このファイル内の PRD」 file_id を使用し、その後 get_prd_list を呼び出します
• 「このキャンバス内のすべてのページ」 canvas_id を解決し、その後 get_design_page_list を呼び出します
• 「デザイン全体をフロントエンドにして」 すべてを一度に取得してはいけません。ページごとの取得が必須です

失敗時の対応

データへのアクセスに失敗した場合：

• calicat status を実行します。
• 認証情報が古いようであれば、calicat logout を実行してから calicat login を実行します。
• 解析した file_id、canvas_id、node-id を再確認します。
• タスクがインストール、更新、バージョンの状態に依存する場合は、references/cli-lifecycle.md を読みます。

出力スタイル

ユーザーに報告する際は：

• 解析した ID を明示します
• 実行した CLI 呼び出しを明示します
• リンクがファイル、キャンバス、レイヤーのどれを指していたかを明示します
• 段階的な取得を行った場合は、大量のデザイン JSON を一度に読み込まないようにしていることを説明します