Mirofy は何をしますか？
小さな型付きJSON仕様から、自己完結型のインタラクティブHTML図を作成します。静的出力がデフォルトです。ユーザーがデモやプレゼンテーションを明示的に要求した場合のみ、アニメーションを有効にします。
スキャンファースト：実際のリポジトリから図を導出する
図が実際に存在するコードを説明する必要がある場合、記憶に頼って作成しないでください。以下の手順で導出します。
npm run scan # リポジトリ -> エビデンスグラフ（事実とギャップ）
npm run model # エビデンス + ドキュメント -> 1つのシステムモデル
npm run compile # モデル -> 意図を持った境界のあるビュー
各ステップは判断できなかったことを報告します。scan は分析できなかったすべてのファイルのギャップを記録し、compile は省略したすべてのオブジェクトとその理由を記録します。それらをユーザーに伝えます。システムの半分を黙って省略する図は、何を省略したかを示す図よりも劣ります。
ユーザーがまだ存在しないもの、またはリポジトリが利用できないものを説明している場合は、以下の高速パスを使用してください。
高速オーサリングパス
通常の生成にはこの境界のあるパスを使用します。ユーザーがそれらの機能について質問しない限り、オプションのビューアランタイムリファレンスを読まないでください。
-
質問から
architecture、workflow、sequence、dataflow、lifecycleのいずれかを選択します。 -
schemas/の一致するスキーマ1つ、schemas/common.schema.json、およびexamples/の一致するJSON例を1つ読みます。これらのファイルのみを読んでください。新規作成とは、新しい安定したID、ドメイン用語、レイアウトを意味します。例はフィールドの形状のためだけに使用し、事実として使用しないでください。実際の製品IDが重要な場合は、node bin/mirofy.mjs brands "<name>" --jsonを実行し、不明なブランドでユーザー提供のURLがある場合のみreferences/brand-marks.mdを読んでください。 -
まずアーティファクトを作成する：次のツールアクションは候補を書き出す必要があります。レンダラーの内部を調査する前に候補を書き出してください。散文で正確な座標を計画しないでください。1つの明確なメインパス、短いサイドブランチ、最小限のラベル、最大12のプライマリノードから始めてください。
meta.quality_profileを"showcase"に設定します。ただし、ユーザーが明示的に高密度のstandardマップを要求した場合を除きます。自動ルートとラベルから始めてください。診断で必要になる前にvia、channelX、channelY、labelAtを追加しないでください。修復ごとに最大1つの診断されたジオメトリコントロールを適用してください。 -
候補を編集するたび、および引き渡しの直前に検証します。
node bin/mirofy.mjs validate <type> <candidate.json> --quality showcase --jsonアーティファクトチェックが4つだけのレシートは基本検証であり、showcaseの受け入れではありません。showcaseパスは、9つすべてのアーティファクトチェックが、0個の構成エラーと0個の警告で報告される必要があります。候補が正確な
meta.quality_profileフィールドを省略または誤って綴っている場合は、ジオメトリの前に修正してください。最終検証に合格すると候補が確定します。その後は決して編集しないでください。 -
配信されたHTMLの場合、
deliverが最終受け入れコマンドです。node bin/mirofy.mjs deliver <type> <candidate.json> <output.html> --quality showcase --jsonゼロ以外の終了コードは成功として説明することはできません。検証が失敗した場合、診断された
subjectのみを変更し、evidenceを確認し、supportedFixesから選択して再実行してください。客観的なエラー数が新しい最小値に達するまで、焦点を絞った修正を続けてください。2回連続してその最良のカウントが改善されない場合は、停止し、未解決の診断を正直に報告してください。
最初の候補の前に renderers/shared/geometry.mjs、レンダラーソース、バリデーターソース、テスト、またはベンチマークを読まないでください。実装を調査するのは、サポートされていない内部診断の場合、または2回の集中修復が失敗した後のみです。
タイプルーター
| タイプ | 用途 |
|---|---|
architecture | コンポーネント、サービス、クラウド/セキュリティ境界、インフラストラクチャ |
workflow | プロセス、承認ゲート、ツール呼び出し、Runbook、CI/CD |
sequence | API呼び出しチェーン、リクエストライフサイクル、非同期トレース、戻り値 |
dataflow | パイプライン、ETL/ELT、系列、ガバナンス、コンシューマー |
lifecycle | 状態/ステータス遷移、リトライ、待機および終了状態 |
曖昧な場合は、node bin/mirofy.mjs guide "<scenario>" --json を実行してください。シナリオ証明の例は構造的な参照であり、コピーする事実ではありません。
Mermaid 入力
node bin/mirofy.mjs import mermaid <input.mmd> [output.json] [--json]
flowchart/graph → architecture、sequenceDiagram → sequence、stateDiagram(-v2) → lifecycle。
インポーターは推測しません。読み取れない行は行番号とともにギャップになるため、結果を完全と呼ぶのではなく、何が引き継がれなかったかを報告してください。また、位置も割り当てません。変換されたアーキテクチャは layout.mode: "grid" を使用し、ファンアウトによってエッジがノードを通過する可能性があり、これは常時オンの clean-flow ゲートに失敗します。インポート後は常に検証してください。ソースから意味も読み取ってください。インポーターはトポロジーを運びますが、ドメイン判断は行わないため、ラベルとタイプはしばしば書き換えが必要です。
ジオメトリの修復
検証でコンポーネントの重なりが報告された場合、座標を1つずつ手動編集しないでください。
node bin/mirofy.mjs repair <type> <input.json> [output.json] --safe
--safe は、これがオーサリングされた座標を書き換えるため必須です。修復は重なりに関与するコンポーネントのみを、バリデーターの8pxギャップをクリアする最小の修正で移動し、すべての微調整のレシートを出力し、ジオメトリのみに触れ、ラベル、タイプ、接続、IDには触れません。再検証し、変位で修正できないもの（ルーティング、ラベル配置）を、次の実行で再発見させるのではなく明示します。
オーサリングの不変条件
- 1つの明白なメインパス。サイドブランチは最も近いメインパスノードから分岐します。ルーティング制御を追加する前に、価値の低いエッジを削除してください。
- デフォルトでは
meta.visual_presetを省略し、すべての図が解決されたカラーモード（明るい/暗い）に関係なくclassicで開くようにします。カラーモードとビジュアルプリセットは独立しています。Light/Dark を切り替えても現在のプリセットを維持する必要があります。signal-flow、blueprint、editorialは、ユーザーがそのビジュアルスタイルを明示的に要求した場合のみ設定してください。 - デフォルトでは
meta.subtitleを省略します。タイトル、ノード、カードを言い換えるサブタイトルを決して作成しないでください。ユーザーが明示的に要求した場合のみ、1行の短いサポートラインを含めてください。 - スタンドアロンのデスクトップビューアを、デフォルトでは浅いストリップではなく、ファーストスクリーンアーティファクトとして扱います。ノートパソコンと外部ディスプレイ用に1つのレスポンシブアーティファクトを生成します。デバイス固有のHTMLや代替トポロジーは決して生成しないでください。ビューアは、ライブビューポートの高さからの外側の読み取り幅のみを適応させる場合があります。オーサリングされたSVG/viewBox、比率、意味論的なジオメトリ、および通常のドキュメントフローを維持する必要があります。ワイドまたはハイデスクトップでは、図パネルとその必要な結論カードがバランスの取れた全体として画面を占めるように、十分なオーサリングされた垂直リズムを使用します。ランタイムのスケーリングは、過度に圧縮されたYレイアウトや小さすぎる明示的な
meta.viewBoxを修復できません。引き渡し前に、実際のHTMLを1440×900、1600×1000、1920×1080で開き、構成が大きなデスクトップディスプレイ向けの場合は2048×1320も追加で確認します。すべての確認サイズでdocument.documentElement.scrollWidth <= window.innerWidthおよびscrollHeight <= window.innerHeightを要求し、最大の確認ビューポートで図が快適に読み取れ、垂直方向にバランスが取れていることを視覚的に確認します。オーバーフローは、ノード、ラベル、またはメインパネルを縮小する前に、真に冗長なコンテンツを削除するか、間隔をコンパクトにすることで修復します。最大のビューポートでもビューアの幅制限で顕著な空の下部バンドがある場合は、オーサリングされたY位置を再配分し、viewBoxの高さを比例して増やします。フィラーのコピーや装飾的なカードを追加しないでください。overflow: hidden、クリップされたコンテンツ、内部図スクローラー、引き伸ばされたSVG高さ、または小さいタイポグラフィで合格を偽装しないでください。狭い/モバイルレイアウトは、コンテナが必要とする場合に垂直スクロールする場合があります。 - デフォルトでは
meta.legendを省略し、真実のautoデフォルトにします。必要な場合のみ、mode: auto|all|hiddenとレンダラーがサポートするentries.<kind>.label|visibleを使用します。ラベルがセマンティクスを変更することは決してありません。 - 明示的なユーザーの選択から1つの主要なオーサリング言語を選択します。それ以外の場合は、リクエストまたは会話の支配的な言語に従います。
meta.localeはレンダラー所有のビューアUIのみを制御します。対応するサポートされている主要言語には"en"または"zh-CN"を使用します。他のすべての言語については、meta.localeを省略し、固定されたビューアUIと<html lang>が英語にフォールバックすることを明示的に開示します。レンダラーはオーサリングされたコンテンツを翻訳しません。詳細はreferences/authoring-contract.mdを参照してください。 - 正確な製品名、コード識別子、コマンド、プロトコル、APIパス、環境名を保持します。これらはローカライズされたコピー内で英語のままである場合がありますが、周囲の説明文を別の言語のままにすることを正当化することは決してありません。
- ブランドIDはオプションであり、明示的です。ノードが実際の製品に名前を付ける場合、標準の組み込みIDを
brandに入れます。プリセットが一致せず、ユーザーが公式のHTTP(S) URLを提供した場合、最初にnode bin/mirofy.mjs brands capture "<url>" --jsonを実行し、返されたダイジェスト固定されたbrandオブジェクトをオーサリングします。レンダリングと検証は、固定されていないキャプチャを決して実行しません。それ以外の場合はbrandを省略します。「データベース」のような曖昧な役割からブランドを推測したり、バッジにセマンティックなtype、ラベル、または関係の事実を置き換えさせたりしないでください。 - シーケンス図の場合、安定した
fixedレイアウトにはmeta.column_fitを省略します。ワイドなviewBoxが未使用の水平スペースを残す場合、または意味のある参加者ラベルが固定ボックスに収まらない場合は、"spread"に設定します。spreadを試す前にセマンティックラベルを短縮しないでください。 - コンポーネントタイプは
frontend、backend、database、cloud、security、messagebus、externalです。バリアントはdefault、emphasis、security、dashedです。 - 関係ラベルはセマンティックデータです。衝突する場合、ラベルを移動し、ルートまたは間隔を調整し、次に意味を保持しながら文言を短縮します。両方のエンドポイントが関係を完全に暗示し、プロトコル、アクション、方向、同期/非同期動作、または境界を越えるメカニズムを含まない場合のみラベルを削除します。削除されたラベルがなぜ冗長であるかを説明してください。単に
showcaseを通過させるために意味のあるラベルを削除しないでください。 - デフォルトでは
meta.engineering_profileを省略します。リージョン、クラスター、セキュリティ境界の文言だけではこれを有効にしません。ユーザーが明示的に本番デプロイメントトポロジー、所有権の引き継ぎ、または障害時クローズドデプロイメントレビューを要求し、ソース事実が既知の場合のみdeployment-ownershipを有効にします。一度有効にした場合、単に検証を通過させるためにエンジニアリングプロファイルを削除してはなりません。事実を修復するか、診断を正直に報告してください。 - 間隔は、中心間距離ではなく、明確なギャップを意味します。関係ラベルの場合、明確なギャップは測定されたマスク幅を超える必要があります。削除を検討する前に、ラベルを保持する修復順序を使用してください。
- 自動ルートはそれら自身のエンドポイント側を所有します。側は方向契約です。最初と最後のセグメントは、その側に対して垂直に出入りする必要があります。
- 自動ポート分散は、アーキテクチャ、ワークフロー、データフロー、ライフサイクルのデフォルトのレンダラー動作です。単一の関係と明示的な
via、channelX、channelY、labelAt、または非autoルートをスキップします。近接するパラレルポートは外部ブリッジを使用するため、自動ルーティングは8px未満のセグメントや16px未満の内部ターンを作成できません。アーキテクチャは別途、それらのオフセットが16px未満で両方のポートがコーナークリアランスを保持する場合、遮るもののない対面する自動ポート（left/rightまたはtop/bottom）を1つの共有軸上に保持します。正確に1つのエンドポイントが分散された場合、共有されていないエンドポイントのみがその軸上に移動できます。両方のエンドポイントが分散された場合、競合するポートが区別可能なままになるように外部ブリッジを維持します。 - 無関係な不透明なノード、曖昧な共有コリドー、または別のルートをマスクする関係ラベルをエッジが横切ることを決して受け入れないでください。
references/authoring-contract.md は、フィールド列挙型、間隔計算、自動ポート配置、ジオメトリ修復ルール、リポジトリエビデンス、またはモード固有の配置が必要な場合のみ読んでください。
配信
修復中は validate を、最終受け入れには deliver を1回使用します。配信は、正確な仕様バイトをプライベートな同一ディレクトリのスナップショットに固定し、そのスナップショットをレンダリングしてチェックし、アトミックにHTMLをコミットし、仕様とアーティファクトの両方のSHA-256とバイト数を報告します。
配信後、信頼できるHTMLを変更または再レンダリングせずに、境界のあるデスクトップエビデンスを収集します。
node bin/mirofy.mjs visual-check <output.html> --json
visual-check は1440×900、1600×1000、1920×1080、2048×1320でのコンテナメントを測定します。最小および最大サイズで明るい/暗いスクリーンショットをキャプチャし、アーティファクトの横に相対パスのコンタクトシートとJSONサイドカーを書き込みます。その自動レシートは常に visualReview: "pending" を報告します。スクリーンショットは検査のためのエビデンスであり、自動的なポリッシュクレームではありません。終了コード0はコンテナメントとキャプチャが成功したことを意味し、1はオーバーフローまたはキャプチャ失敗、2はChrome/Chromiumが利用できずレシートが skipped であることを意味します。このコマンドは配信されたHTMLを決して変更しません。ユーザーが即座のローカルプレビューを希望する場合のみ --open を追加します。アクティブなデスクトップオーサリングループの場合、オプションのコマンドは次のとおりです。
node bin/mirofy.mjs preview <type> <input>.json <output>.html --quality showcase
デフォルトではプレビューを開始しないでください。プレビュー、リポジトリエビデンス、エクスポートレシート、ビジュアルレビュー、またはコミット後のオープンを使用する場合は references/delivery-contract.md を読んでください。
オプションのビューア機能
生成されたHTMLにはすでにテーマ切り替え、パン/ズーム、検索、フォーカス、関係トレース、セマンティックビュー、プレゼンテーション、真実のエクスポートが含まれています。これらはリーダー機能であり、追加のオーサリング作業ではありません。meta.animation: "trace" はオプトインです。meta.views はオプションであり、最大5つの厳選されたチャプターを含む必要があります。ユーザーが明示的にShare Cards、Route/Reach Cards、モーション、ガイド付きストーリー、ディープリンク、プレゼンテーション、検索/フォーカス、またはその他のビューアランタイム機能を要求した場合のみ references/viewer-runtime.md を読んでください。
セットアップとフォールバック
スキルのインストールはオプションです。