yokingma/flow-diagram

Flow Diagram

Flow Diagramは、実行可能なシステム図やプロセス図を作成するためのオーサリングスキルです。一度作成すれば、再生、埋め込み、検査、エクスポートが可能です。

説明やソース資料を視覚的な説明に変換します。静的またはアニメーションの図で、構造、関係、プロセスを明確にします。目的は、ソースの意味を保持し、読者が物事がどのように構成され、接続され、時間とともに変化するかを理解できるようにすることです。

タスクを選択する

このスキルは図アセットを生成します。PPTXファイルやネイティブなPowerPoint図形は対象外です。

タスクの種類、使用する入力、プロセスを開始または再開する場所を特定します。

リクエスト	開始点
新規図、または作成・改訂されるJSONインポート	プリファレンスの事前確認を完了し、その後5つのステップすべてを実行します。必要な場合は、変更されていないインポートバイトを保持します。
エクスポートまたは検査のための変更なしJSONインポート	エクスポートまたは診断のエントリポイントを使用します。プリファレンスの事前確認はスキップし、入力デザインを維持します。
確定済み図の改訂	既存の図と最終レポートを読み取ります。要求された変更と範囲を確立し、プリファレンスの事前確認を完了してから5ステップのプロセスを実行し、依然として有効な設計上の決定を再利用します。ユーザーが変更しない限り、要求されたフォーマットを引き継ぎます。
エクスポート形式のみの追加	既存の図を変更せずにステップ3から開始します。ドラフト、スタイリング、測定、レイアウトの変更はスキップし、要求されたファイルを検査して確定します。
未完了タスクの継続	タスクレコードを読み取り、継続する保存済みリビジョンを選択します。未完了のステップ、または変更の影響を受けるステップから再開します。
検証または診断のみ	構造チェックにはvalidateを使用します。視覚的診断が要求された場合は、ステップ4の該当する検査ワークフローに従います。実行したチェック、その制限、発見された問題を報告し、停止します。

独立した保存、変更、またはリセットのリクエストについては、プロジェクトのプリファレンスに従い、図を作成せずに操作を報告します。

既存の図からのインポート、改訂、またはエクスポートについては、入力と親の選択を読みます。タスクファイルを作成する前に、タスクワークスペースの要件を読みます。検証コマンドとレポート状態については、ランタイムと結果のコントラクトを読みます。

入力、許可された変更、プロセスのエントリポイントが明確になったら進めます。

プロセス

0. 設計プリファレンスを初期化する

新規および改訂ドラフトについては、ステップ1の前にプロジェクトのプリファレンスに従います。関連する視覚的な選択肢を解決し、そのソースを記録して事前確認を完了します。要求された保存を完了するか、その失敗を開示します。独立したプリファレンス管理リクエストは、そのリファレンスを使用し、操作を報告した後に停止します。純粋なエクスポート、検証、診断タスクは既存のエントリポイントを維持します。未完了のタスクは記録された決定を引き継いで再開し、関連する選択肢が変更された場合にのみ事前確認を再訪します。

1. 説明の目標を定義する

読者の質問から始めます。読者は図を見た後、何を理解すべきでしょうか？この質問を使用して、その後のコンテンツ、レイアウト、アニメーションの決定を導きます。

• 質問を定義する。 主題と、ユーザーのリクエストから読者が何を理解すべきかを特定します。

• 事実を確立する。 ユーザーが指定したソースまたは既存の図を、許可された範囲内で読み取ります。関連するオブジェクト、関係、プロセス、状態変化を特定します。既知の事実と情報の明確化が必要な部分を区別し、ソースメタデータを通じてソースを記録します。

  広範な調査（コードリポジトリの探索など）の場合は、サブエージェントを起動して、読者の質問に関連する部分を調査させます。サブエージェントに質問と許可されたソース範囲を与えます。関連するオブジェクト、関係、プロセス、状態変化を、ソースの場所と未解決の質問とともに求めます。それらの発見を使用して、説明に必要な事実を確立します。

  少数の記事、少数の参考資料、または「RAGワークフローをフローチャートで説明してください」のような短いリクエストの場合は、現在のセッションで事実を確立します。

• 要件を記録する。 ユーザーがすでに指定したオーディエンス、使用コンテキスト、配信要件を取得します。欠落した配信コンテキストに従い、既知の選択肢を再利用し、関連するギャップを一度だけ収集し、ジオメトリを選択する前に採用した仮定を記録します。

読者の質問を一文で述べ、その回答を裏付ける事実を特定できるようになったら進めます。図の意味を変えるような情報のギャップは、ドラフト作成前に明確にします。SDKがリクエストを忠実に表現できない場合は、制限を説明し、ユーザーの選択を待ちます。

2. 視覚的な説明を設計する

ステップ1で定義された質問に読者が答えられるように、主題をどのように提示するかを選択します。

新規または改訂ドラフトについては、配信コンテキストを読み、キャンバスと密度を選択します（目的が不明な場合も含みます）。能力の棚卸し、責任、リソースステータス、リクエストとレスポンス、状態遷移、データ処理、アーキテクチャについては、読者の質問による選択テーブルを使用します。

• コンテンツを選択する。 説明に必要なオブジェクト、関係、プロセス、状態を選択します。コンテンツを省略または集約する前、または未知のソース情報をどのように提示するかを決定する前に、ソースの忠実性と情報の選択を読みます。これらの選択においてソースの意味を保持します。
• コンテンツをその表面に割り当てる。 図のジオメトリの前に、コンテンツの配置に従い、ページ導入部、図にバインドされたラベル、キャプション、補足散文を割り当てます。割り当てと、要求された各フォーマットに必要なコンテキストを記録します。
• 構造を整理する。 グループ、階層、読書順序を定義して、読者が主要ポイントを特定し、その関係を追跡できるようにします。
• ビジュアルの方向性を設定する。 ビジュアルデザインに従い、使用コンテキストに応じた方向性を選択します。サイドバー付きの階層構造、分岐やリターンがあるプロセス、長いコンテンツを含む繰り返しカードには、該当する構成レシピを選択します。プロダクションに必要な具体的な選択を記録します。
• 静的図またはアニメーションを選択する。 構造と関係を説明するには静的レイアウトを使用します。アニメーションでは、持続的な関係フロー、注意と段階的変化を区別します。線の流れのリクエストでは、図全体を表示し続けることができます。
• アニメーションナラティブを計画する。 アニメーションを使用する場合、アニメーションのリズムと視覚的な連続性に従い、各ステージの説明目標、状態変化、トランジション、読むための一時停止を定義します。

計画が、選択されたコンテンツ、その保持面、グループ、読書順序、ビジュアルの選択、静的またはアニメーションでの提示を記録したら進めます。アニメーションの場合は、ステージ計画を含めます。

3. 図を作成する

ステップ2の設計を実装し、ステップ4の検査に必要なアーティファクトを生成します。

Node 20以上とnpmを使用します。ユーザーが選択した作業ディレクトリから、必要に応じて引用符でパスを囲んで node <skill-directory>/scripts/flowsvg.mjs を実行します。このインストールされたスキル内でツールとタスクリソースを解決します。CLIは、アプリケーションの依存関係を変更せずに、独自の固定SDKランタイムを準備します。

• 関連するオーサリングガイダンスを読み取る。 新規または改訂ドラフトについては、ドキュメントモデルとレイアウトガイダンスを読み、選択された設計レシピを実装します。ジオメトリを配置する前に、レンダリングの落とし穴をチェックします（短いパスと長いラベル、サイドバー、境界線のないテキスト、狭いカードや任意の言語での折り返しリスク、短いラベルの光学的位置合わせ、共有された読書エッジ、変更されたコンテンツサイズなど）。アニメーションの場合は、シーン、継承状態、タイミングも読みます。要求されたSVG、PNG、GIFファイルについては、エクスポートのオプションと制限を読みます。
• 図文書を構築する。 新規または改訂ドラフトについては、計画されたオブジェクト、グループ、接続、テキスト、アニメーションステージを実装します。ソースの言語と選択されたビジュアル方向性を保持します。方向性が指定されていない新しい図の場合は、ライトテーマと角丸グループから始めます。完全なドラフトでテキストを測定し、繰り返しジオメトリに計画が必要な場合はレイアウト計画ワークフローに従います。すべてのオブジェクト、関係方向、親境界、状態変化をソースと比較します。許可された変更を新しいワークスペースドラフトに保存します。変更されていないインポートまたはエクスポートの場合は、選択された入力バイトを直接使用します。
• 検証して修正する。 反復中に読み取り専用のvalidateを使用し、すべての診断を読み取ります。これは、図のリビジョンを作成せずに、正確な入力IDと有限のチェックを返します。作業中のドラフトを保持します。現在の認可範囲内で修正を適用し、診断と改訂の決定に従います。説明の意味を変更する修正については、ユーザーに確認します。
• HTMLページを構成する。 新規または改訂されたHTML説明については、図の外部に割り当てられたコンテンツのページHTML/CSSを作成し、編集可能なHTMLページを通じて送信します。既存の結果の場合は、ページの継続に従って、そのデザインを保持し、意図した図の変更を明示的に同期します。有用な場合は、インストール済みのスターターを新しいページに再利用します。管理されたプレーヤー領域を保持し、完全なページをタスクワークスペースに保持します。
• 検査アーティファクトを生成する。 ブラウザキャプチャまたはプレビューサンプル数の選択の前に、ブラウザの準備とサンプリングを読みます。authorを使用して、必要なオフラインHTML、必要なプレビュー、要求されたエクスポートファイルを生成します。中間HTMLのみが必要な場合は、author --browser noneを使用します。複数の名前付き静的状態については、名前付きバッチエクスポートに従います。マニフェストをバインドする前に、実際のコンパイルされたビートから選択された時間をユーザーと確認します。セットアップ、SDK互換性、レポートフィールドについては、ランタイムと結果のコントラクトに従います。コマンドオプションについては、CLI --helpを使用します。

ドラフトが計画を実装したか、変更されていない入力が保持され、ブロックエラーが解決され、残りの診断に記録された処理決定があり、検査に必要なすべてのファイルが完了したら進めます。エクスポートが失敗した場合は、以下の回復ルールに従い、完了したファイルと未完了のファイルを別々に報告します。

4. 結果を検査する

配信されたSVG/PNGについては、オンデマンドアーティファクト証拠に従います。明示的に保存された対象に対してevidenceを実行し、その画像を表示して個別にレビューします。既存の有効な条件は再利用され、新しい条件は検査されるまで未表示のままです。

生成された図を表示し、主題を正確かつ明確に説明していることを確認します。

• 意味的正確性をチェックする。 オブジェクト、関係方向、グループ境界、状態変化をソースと比較します。省略と集約がソースの意味を保持していることを確認します。
• 視覚的可読性をチェックする。 意図された表示サイズで実際のレンダリング画像を表示します。テキスト、スペーシング、オクルージョン、読書順序を検査します。各関連接続をそのソースから曲がりや交差を通って矢印までトレースします。ポート、ラベル、無関係なノードからのクリアランスをチェックします。
• ビジュアルデザインを評価する。 ビジュアルデザインの検査に従い、目に見える欠陥を特定し、ユーザーの最終的な設計判断のために観察結果を記録します。
• アニメーションの説明をチェックする。 アニメーションの場合は、初期状態、主要な変更、最終状態をステージ計画と照らし合わせて検査します。サンプリングされた状態については、プレビュー検査に従います。ペーシングを評価するときは実際の再生を使用します。サンプルのみの検査は、表示された状態に限定されていると報告します。
• 配信ファイルをチェックする。 ツールに実際に保存されたオフラインHTMLを開かせ、その初期一時停止状態、コントロール、オフラインリクエスト、関連する再生状態をチェックします。HTML検査ワークフローを通じてキャプチャされた画像を表示します。要求されたエクスポートファイルを配信されたとおりに検査します。最終的なSVG/PNGファイルについては、ターゲットサイズアーティファクト検査を使用します。

レビューを送信する前に、完全なレビュー入力コントラクトとテンプレートワークフローを読みます。明示的な図対象からreview-templateを使用して未表示のフォームを生成し、別の正式な証拠のために--evidence-fromを使用します。その後、独立したreviewを使用して、HTML、プレビュー、正式なSVG/PNGの観察結果について、実際に表示された画像のID、ハッシュ、観察結果、問題のみを記録します。レビューの繰り返し送信は、別の図バージョンを必要としません。ブラウザまたは画像ビューアが利用できない場合は、未実行のチェックとその影響を明示的に記録します。

発見された問題については、ステップ3に戻り、許可された修正を適用し、アーティファクトを再生成し、影響を受けるファイルと状態を再度検査します。問題を記録するか、意味を変える修正をユーザーに明確にするときは、診断と改訂の決定に従います。

5. 図を確定する

ステップ4で確認された成果物を保存またはエクスポートします。これらのアクションは、以前のステップで最終決定が遅れた場合のバックストップです。

• 生成されたファイルを保存する。 すべてのステップ要件を満たす最終図文書を、タスクワークスペース内の新しいリビジョンファイルに保存します。リビジョンがステップ3で既に保存されている場合は、保存操作を記録してスキップします。
• エクスポートファイルを生成する。 まだ生成されていない場合、要求された各エクスポートフォーマットのファイルを生成し、タスクワークスペースに配置します。要求されたフォーマットは、開始時に指定されたもの、またはプロセス中に明示的に要求されたものです。エクスポートの制限（例: ファイルサイズ、解像度、非対応機能）は、エクスポートの参照に従って記録します。
• 完成を報告する。 図の最終状態、生成されたファイルとその場所、適用された制限、未解決の診断または明確化を要約します。完全な図文書と証拠へのパスを含めます。

改訂タスクでは、ステップ3のドラフト作成の前に確立された変更要求を満たすために、各アクションが完全に正常に実行された場合にのみ、図は確定されます。

エクスポート障害からの回復

authorのいずれかのランでエクスポートファイルの作成が失敗した場合:

1. validateがエラーを報告した場合は、すべての診断を修正して再試行します。
2. validateが合格したがエクスポートが失敗した場合は、エラーメッセージとスタックトレースを表示し、構文エラーを修正して再試行します。
3. それでも失敗する場合は、SDKツリーでnpm installを実行して、壊れたインストールがないか確認します。
4. トレースに未解決の依存関係が示されている場合は、不足しているパッケージをインストールするためにnpm install <パッケージ名>を実行し、再試行します。
5. 回復できない失敗については、完全なエラー出力を報告し、どのファイルが完成し、どのファイルが未完成かをリストします。

スキル制限

このスキルは、FlowSVGドキュメントモデルの範囲内で動作します。基盤となるツールと参照によって定義され、特定の統合の制限を尊重します。

• ドキュメントモデル： ドキュメントモデルの範囲で説明されているように、テキストスタイル、レイヤー、テーマのカスタマイズが含まれます。
• レイアウト： ほとんどの静的レイアウトタスクをサポートしますが、いくつかの複雑な構成は設計メソッドとレシピの下で手動での調整が必要な場合があります。
• アニメーション： 段階的変化、ハイライト、トランジション、パスフローをサポートしますが、複雑なモーフィングや3D変換は制限される場合があります。
• エクスポート： SVG、PNG、GIFは特定の解像度とファイルサイズの制限の対象となります。大きな図は適応が必要な場合があります。エクスポートの制限を参照してください。
• ブラウザ機能： オフラインHTMLは最新のブラウザを必要とします。古いブラウザや限られた環境では、アニメーションや特定のインタラクティブ機能が制限される場合があります。

これらの制限を超える機能や、FlowSVGモデル（PowerPointスライドの生成やフルデータベーススキーマの視覚化など）の外部にある機能のリクエストは、提供できない場合があります。