[Skill 名] lark-whiteboard

ホワイトボード CLI スキル

[!NOTE] 環境依存関係：ホワイトボードを描画するには、@larksuite/whiteboard-cli（ホワイトボード Node.js CLI ツール）と lark-cli（LarkSuite CLI ツール）が必要です。 実行に失敗した場合は、手動でインストールしてから再試行してください：npm install -g @larksuite/whiteboard-cli@^0.1.0

[!IMPORTANT] npm install を実行して新しい依存関係をインストールする前に、必ずユーザーの同意を得てください！

ワークフロー

これはホワイトボードであり、ウェブページではありません。 ホワイトボードは無限のキャンバス上に要素を自由に配置するもので、Flex レイアウトはオプションの強化機能です。

ステップ 1: ルーティングと知識の読み込み
  - レンダリングパスを判断（ルーティングテーブルを参照）：Mermaid か DSL か？
  - 対応する scene ガイドを読み込む — 構造的特徴とレイアウト戦略を理解する
  - レイアウト戦略（以下のクイック判断を参照）と構築方法を決定する
  - references/ コアモジュールを読み込む — 構文、レイアウト、配色、タイポグラフィ、コネクタ

ステップ 2: 完全な DSL を生成（色を含む）
  - content.md に従って情報量とグループ化を計画する
  - layout.md に従ってレイアウトモードと間隔を選択する
  - style.md に従って色を付ける（ユーザーが指定しない場合はデフォルトのクラシックカラーパレットを使用）
  - schema.md 構文に従って完全な JSON を出力する
  - コネクタは connectors.md を、タイポグラフィは typography.md を参照する

  注意：一部の図形（魚骨図/フライホイール図/棒グラフ/折れ線グラフなど）は、scene ガイドのスクリプトテンプレートに従って .js スクリプトを記述し、JSON を生成する必要があります：
    - node xxx.js → JSON ファイルを出力
    - 出力された JSON ファイルを使用してステップ 3 に進む

ステップ 3: レンダリングとレビュー → 納品
  - レンダリング前の自己チェック（以下のチェックリストを参照）
  - PNG をレンダリングし、以下を確認する：
    ・情報が完全か？レイアウトは適切か？配色は調和しているか？
    ・テキストは途切れていないか？コネクタは交差していないか？
  - 問題がある場合 → 症状表に従って修正 → 再レンダリング（最大 2 回）
  - 2 回後も深刻な問題がある場合 → Mermaid パスをフォールバックとして検討する
  - 問題がない場合 → 納品：
    ・ユーザーが Feishu へのアップロードを要求した場合 → 以下の「Feishu ホワイトボードへのアップロード」セクションの説明を参照
    ・ユーザーが指定しない場合 → PNG 画像をユーザーに表示

レイアウト戦略クイック判断（詳細は layout.md を参照）：

構築方法は強い制約です：scene ガイドが「スクリプト生成」を要求する場合、まずスクリプト（.js）を記述し、node を実行して JSON ファイルを出力する必要があります。絶対位置指定のシナリオ（魚骨図、フライホイール図、棒グラフ、折れ線グラフなど）の座標は数学的な計算が必要であり、JSON を直接手書きするとノードの重なりやコネクタの貫通が非常に発生しやすくなります。

レンダリングパスの選択（DSL または Mermaid）

ルーティングルール：

1. 自動 Mermaid：マインドマップ、シーケンス図、クラス図、円グラフ、フローチャート → デフォルトで Mermaid パス
2. 明示的な Mermaid：ユーザー入力に Mermaid 構文が含まれる → Mermaid パス
3. DSL パス：その他すべてのタイプ → まずコアモジュールを読み込み、次に該当するシーンガイドを読み込む

Mermaid パス：scenes/mermaid.md を参照して .mmd ファイルを記述し、DSL モジュールをスキップします。 DSL パス：ワークフローの 3 ステップに従って実行します。

モジュールインデックス

コア参照（DSL パスで必須）

シーンガイド（タイプ別にいずれかを選択）

CLI コマンド

レンダリング：

npx -y @larksuite/whiteboard-cli@^0.1.0 -i my-diagram.json -o ./images/my-diagram.png        # DSL パス
npx -y @larksuite/whiteboard-cli@^0.1.0 -i diagram.mmd -o ./images/diagram.png               # Mermaid パス
npx -y @larksuite/whiteboard-cli@^0.1.0 -i skeleton.json -o ./images/step1.png -l coords.json  # 2 段階（座標抽出）

Feishu ホワイトボードへのアップロード：

アップロードには Feishu 認証が必要です。認証または権限エラーが発生した場合は、../lark-shared/SKILL.md を読んでログインと権限処理について理解してください。

ステップ 1：ホワイトボードトークンの取得

Feishu ドキュメントの作成、読み込みなどの詳細な操作については、lark-doc スキル ../lark-doc/SKILL.md を参照してください。

ステップ 2：アップロード

[!CAUTION] MANDATORY PRE-FLIGHT CHECK (アップロード前の強制インターセプトチェック) 既存のホワイトボードトークンにコンテンツを書き込む場合、アップロードコマンドを直接実行することは絶対に禁止です！以下の 2 つのステップを厳守する必要があります： 強制的なドライランの実行（状態検出） まず、コマンドに --overwrite --dry-run パラメータを追加して、ホワイトボードの現在の状態を検出する必要があります。コマンド例：

npx -y @larksuite/whiteboard-cli@^0.1.0 --to openapi -i <入力ファイル> --format json | lark-cli docs +whiteboard-update --whiteboard-token <Token> --overwrite --dry-run --as user

結果の解析とインターセプト

• ドライランの出力ログを注意深く読んでください。
• ログに XX whiteboard nodes will be deleted が含まれている場合：これはホワイトボードが空ではないことを意味し、現在の操作はユーザーの既存の図表を上書きして破壊します！
• 直ちに操作を停止し、AskUserQuestion ツール（または直接返信）を通じてユーザーに確認してください：「ターゲットのホワイトボードは現在空ではありません。更新を続行すると、既存の XX 個のノードがクリアされますが、上書きしてもよろしいですか？」
• ユーザーが「上書きに同意する」と明確に承認した場合にのみ、--dry-run を削除して実際にアップロードを実行できます。
• ユーザーがホワイトボードの内容を上書きせずに更新することを要求する場合があります。その場合は、--overwrite と --dry-run パラメータを削除してからアップロードしてください。

npx -y @larksuite/whiteboard-cli@^0.1.0 --to openapi -i <入力ファイル> --format json | lark-cli docs +whiteboard-update --whiteboard-token <画板Token> --yes --as user

ホワイトボードは一度アップロードされると変更できません。アプリケーションIDでアップロードする場合は、--as user を --as bot に置き換えてください。 ホワイトボードが空でない場合は、まず --overwrite --dry-run を追加して削除されるノードの数を確認し、ユーザーに確認した後、--dry-run を削除して実行してください。

症状→修正表（視覚レビューで問題が発見された場合）：

レンダリング前の自己チェック

DSL 生成後、レンダリング前に、以下を素早くチェックしてください：

• [ ] 異なるグループに異なる色が使用されていますか？同じグループのノードスタイルは完全に一致していますか？
• [ ] 外側が薄い色、内側が白いノードですか？（外重内軽）
• [ ] すべてのノードに境界線（borderWidth=2）がありますか？テキストは背景上で鮮明に読めますか？
• [ ] コネクタは灰色（#BBBFC4）を使用し、色付きではありませんか？
• [ ] frame はすべて layout 属性を記述していますか？gap と padding は明示的に設定されていますか？
• [ ] テキストを含むノードの height は fit-content を使用していますか？connector は最上位の nodes 配列にありますか？

主要な制約クイックチェック

最も頻繁にエラーが発生するルールであり、サブモジュールファイルを読まなくても遵守する必要があります。

1. テキストを含むノードの height は 'fit-content' を使用する必要があります — 数値をハードコードするとテキストが途切れます
2. fill-container は flex 親コンテナ内でのみ有効です — layout: 'none' の下では幅が 0 に退化します
3. connector は最上位の nodes 配列に配置する必要があります — frame の children 内にネストすることはできません
4. レイヤー順序 — 配列の順序 = 描画順序です。後に定義された要素ほどレイヤーが高くなり、先に定義された要素を覆い隠します。重なり合う/フローティング/注釈要素は必ず配列の最後に配置してください。
5. flex コンテナ内の x/y は完全に無視されます — 自由な位置指定が必要な場合は layout: 'none' を使用するか、最上位の nodes に配置してください

❌ 致命的なエラー：flex コンテナ内に x/y を設定すると、座標が有効にならず、ノードは順序通りに配置されます

{ "type": "frame", "layout": "vertical", "children": [
  { "type": "rect", "x": 100, "y": 0, "text": "成都" },
  { "type": "rect