archify

Archify

小規模な型付き JSON 仕様から、自己完結型のインタラクティブな HTML 図を作成します。静的な出力がデフォルトです。モーションを有効にするのは、ユーザーがデモまたはプレゼンテーションを求めた場合に限ります。

すばやく作成する手順

通常の生成では、この範囲を限定した手順を使用してください。ユーザーがこれらの機能について尋ねない限り、任意の Viewer Runtime リファレンスは読み込まないでください。

1. 質問に応じて、architecture、workflow、sequence、dataflow、lifecycle のいずれかを選択します。

2. schemas/ にある対応するスキーマを1つ、schemas/common.schema.json、および examples/ にある対応する JSON の例を1つ読みます。それらのファイルだけを読み込んでください。新規作成では、新しい安定した ID、ドメインに即した表現、レイアウトを使用します。例はフィールドの形式を確認するために使い、事実の根拠にはしないでください。新しいワークフローでは schema_version: 2 とその読みやすいレイアウト規約を使用します。既存のワークフローの固定ジオメトリを維持する場合に限り、schema_version: 1 を使用してください。実在する製品のブランド情報が必要な場合は、node bin/archify.mjs brands "<name>" --json を実行します。ユーザーが URL を提示した未知のブランドの場合に限り、references/brand-marks.md を読みます。

3. 成果物を最初に作成します。次のツール操作では候補を書き出してください。レンダラーの内部を調べる前に候補を書き出します。正確な座標を文章で計画しないでください。明確なメイン経路を1つ、短い分岐を少数、ラベルを控えめにし、主要ノードは最大12個にします。ユーザーが密度の高い standard マップを明示的に求めない限り、meta.quality_profile を "showcase" に設定します。まずは自動ルートと自動ラベルを使用します。診断で必要とされるまでは via、channelX、channelY、labelAt を追加しないでください。修正1回につき、診断されたジオメトリ制御を最大1つだけ適用します。

4. 候補を編集するたびに、また引き渡しの直前にも検証します。

   node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json
   

   成果物チェックが4項目だけの結果は基本的な検証であり、ショーケースとしての合格ではありません。ショーケースの合格では、9項目すべての成果物チェックが報告され、構成エラーが0件、警告が0件でなければなりません。候補で meta.quality_profile フィールドが省略されているか、正確に記述されていない場合は、ジオメトリを調整する前に修正してください。workflow v2 のジオメトリ診断では、node bin/archify.mjs validate workflow <candidate.json> --layout-json を実行し、安定したコンパイラーの結果を使用します。ソルバーの内部情報は作成時の制御項目ではありません。最終検証に合格した候補は確定済みとして扱い、その後は編集しないでください。

5. HTML を納品する場合、deliver が最終の受け入れコマンドです。

   node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
   

   終了コードが0以外の場合、成功と説明することはできません。納品に失敗しても以前の出力は保持されます。そのため、その状態で visual-check を実行しないでください。失敗した候補ではなく、最後に正常だった古い成果物を検査してしまいます。検証に失敗した場合は、診断された subject だけを変更し、evidence を確認して、supportedFixes から選択して再実行します。客観的なエラー件数が新たな最小値に達するまで、対象を絞った修正を続けます。連続する2回の修正で最良の件数が改善しなかった場合は中止し、未解決の診断結果を正確に報告してください。

更新の確認

最初の候補ができたら、パッケージに含まれるチェッカー scripts/check-update.mjs を Node で一度実行してから、依頼されたワークフローを続けます。コマンドを実行できない場合は、確認について触れずに続けます。

• silent の場合は、更新確認について触れずに続けます。
• update_available の場合は、インストール済みバージョン、最新バージョン、チェッカーに固定されたローカルの概要、公式リリースノートへのリンクを含む簡潔な通知を、ユーザーとの会話で使われている言語で表示します。severity が security の場合は、セキュリティ更新であることを明確に示し、控えめな警告マーカーを使います。これは強調の変更にすぎず、ユーザーの選択権には影響しません。インストール済みの Skill は変更されておらず、更新するかどうか、いつ更新するかはユーザーが決めることを明記します。この固定されたローカルの文は翻訳してもかまいませんが、リモートマニフェストの概要を引用、要約、翻訳してはいけません。通知を表示したら、同じチェッカーを --ack "<eventKey>" 付きで実行して、その正確な eventKey を確認してから、ユーザーの元の依頼を続けます。

通知は情報提供であり、許可ではありません。インストール済みバージョンは変更しないでください。この v0.1 ワークフローでは、更新のダウンロード、インストール、実行は一切行いません。また、無反応は同意を意味しません。

最初の候補ができるまでは、renderers/shared/geometry.mjs、レンダラーのソース、バリデーターのソース、テスト、ベンチマークを読まないでください。未対応の内部診断がある場合、または重点を絞った修正が 2 回失敗した場合に限り、実装を調べてください。

ワークフローに関する注記：新しいワークフローにはスキーマ v2 を使い、既存のソースで固定されたレガシーのジオメトリが必要な場合はスキーマ v1 を維持してください。意味を表すエッジラベルを保ち、コンパイラーの診断に従って対応してください。正式なレイアウト、ピン、移行、レシートの契約は renderers/workflow/README.md に記載されています。

ライフサイクルに関する注記：フェーズ列 0..4 はメインレールを占め、イベント／終端列 N の 0..2 は、メイン列 N + 2 の真下に正確に揃えます。復帰可能な状態には type: "failure" を使い、アクティブな状態に戻る実際の遷移を設定します。

タイプルーター

タイプ	用途
architecture	コンポーネント、サービス、クラウド／セキュリティ境界、インフラストラクチャ
workflow	プロセス、承認ゲート、ツール呼び出し、ランブック、CI/CD
sequence	API 呼び出しチェーン、リクエストのライフサイクル、非同期トレース、戻り値
dataflow	パイプライン、ETL/ELT、リネージ、ガバナンス、コンシューマー
lifecycle	状態／ステータスの遷移、再試行、待機状態、終端状態

判断に迷う場合は、node bin/archify.mjs guide "<scenario>" --json を実行してください。シナリオの証明例は構造上の参考資料であり、事実としてそのまま転記するものではありません。

Mermaid 入力

トポロジーと意味を把握するために Mermaid を読み、新たに Archify JSON を作成してください。Mermaid のスタイルを機械的に変換してはいけません。

• flowchart ／ graph → workflow。コンポーネントマップの場合は architecture。
• sequenceDiagram → sequence。参加者は意味を表す参加者になり、矢印はメッセージになります。
• stateDiagram → lifecycle。状態と遷移の意味を保ち、Mermaid のスタイルは引き継ぎません。

作成時の不変条件

• 明確なメイン経路を1つ設け、分岐は最も近いメイン経路上のノードから分岐させます。ルーティング制御を追加する前に、価値の低いエッジを削除します。
• デフォルトでは meta.visual_preset を省略し、解決されたカラーモードがライトでもダークでも、すべての図が classic で開くようにします。カラーモードとビジュアルプリセットは独立しています。ライト／ダークを切り替えても、現在のプリセットは維持してください。ユーザーがそのビジュアルスタイルを明示的にリクエストした場合に限り、signal-flow、blueprint、editorial を設定します。
• デフォルトでは meta.subtitle を省略します。タイトル、ノード、カードの内容を言い換えたサブタイトルを決して作らないでください。ユーザーが明示的に求めた場合に限り、補足となる短い一文を含めます。
• スタンドアロンのデスクトップビューアーは、デフォルトで最初の画面に表示する成果物として扱い、薄い帯状のレイアウトにはしないでください。ノートパソコンと外部ディスプレイの両方に対応する単一のレスポンシブ成果物を生成し、デバイス固有の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の高さ、小さくしたタイポグラフィで、検証に合格したように見せかけてはいけません。狭い画面やモバイルのレイアウトでは、コンテンツの収まりに必要な場合、縦方向にスクロールしてかまいません。
• 正確な auto デフォルトを保つため、meta.legend は省略してください。必要な場合は、mode: auto|all|hidden と、レンダラーがサポートする entries.<kind>.label|visible だけを使用します。ラベルによって意味が変わることはありません。
• 主に使う作成言語は、ユーザーが明示的に選択していればそれに従い、そうでなければ依頼または会話で主に使われている言語にします。meta.locale が制御するのは、レンダラーが表示するビューアーUIのみです。対応している主言語に応じて "en" または "zh-CN" を使用します。それ以外の言語では meta.locale を省略し、固定のビューアーUIと <html lang> が英語にフォールバックすることを明示してください。レンダラーは作成したコンテンツを翻訳しません。詳細は references/authoring-contract.md を参照してください。
• 製品名、コード識別子、コマンド、プロトコル、APIパス、環境名は正確に維持してください。ローカライズされた文章の中で英語のまま使用してかまいませんが、その周囲の説明文を別の言語のままにする理由にはなりません。
• ブランドの使用は任意であり、明示的に行ってください。ノード名が実在の製品を指す場合は、組み込みの正規IDを brand に設定します。一致するプリセットがなく、ユーザーから公式HTTP(S) URLが提供されている場合は、まず node bin/archify.mjs brands capture "<url>" --json を実行し、返されたダイジェスト固定の brand オブジェクトを作成します。レンダリングと検証で、固定されていないキャプチャが実行されることはありません。それ以外の場合は brand を省略します。「database」のような曖昧な役割からブランドを推測してはいけません。また、バッジを意味上の type、ラベル、関係の事実の代わりにしてはいけません。
• シーケンス図では、安定した fixed レイアウトを使うため、meta.column_fit を省略します。幅広のviewBoxで水平方向に未使用のスペースが残る場合、または意味のある参加者ラベルが固定ボックスに収まらない場合は "spread" を設定します。spread を試す前に、意味上のラベルを短縮してはいけません。
• コンポーネントのタイプは frontend、backend、database、cloud、security、messagebus、external です。バリアントは default、emphasis、security、dashed です。
• 関係ラベルは意味データです。ラベルが重なる場合は、ラベルを移動し、経路または間隔を調整してから、意味を保ったまま表現を短くします。両方の端点から内容が完全に読み取れ、プロトコル、アクション、方向、同期／非同期の動作、境界を越える仕組みのいずれも含まない表現に限り、省略できます。意味のあるラベルはすべて維持してください。削除はジオメトリの修正ではありません。端点から内容が完全に読み取れるため関係ラベルを付けない場合は、その表現が冗長である理由を説明してください。これは意味に関する作成上の判断であり、ジオメトリの修正ではありません。
• デフォルトでは meta.engineering_profile を省略します。リージョン、クラスター、セキュリティ境界に関する表現だけでは、有効化の理由になりません。ユーザーが本番環境のデプロイトポロジー、所有権の引き継ぎ、またはフェイルクローズのデプロイレビューを明示的に求め、元となる事実が判明している場合に限り、deployment-ownership を有効化します。有効化した後は、検証に合格するためだけにエンジニアリングプロファイルを削除してはいけません。事実を修正するか、診断結果を正確に報告してください。
• 間隔とは中心間距離ではなく、明確な空きです。関係ラベルでは、空きの幅が測定したマスク幅を超えていなければなりません。ラベルを維持するための修正順序に従ってください。
• 自動ルートでは、端点の辺が確定されます。辺は方向の契約です。最初のセグメントはその辺に対して垂直に出発し、最後のセグメントはその辺に対して垂直に進入しなければなりません。
• アーキテクチャ、ワークフロー、データフロー、ライフサイクルでは、自動ポートスプレッドがレンダラーのデフォルトの動作です。単一の関係と、明示的な via、channelX、channelY、labelAt、または auto 以外のルートは対象外です。近接する平行ポートでは外側ブリッジを使用し、自動ルーティングによって8px未満のセグメントや16px未満の内側の折れ曲がりが生じないようにします。アーキテクチャではさらに、互いに遮られていない対向する自動ポート（left／right または top／bottom）のオフセットが16px未満で、両方のポートが角のクリアランスを保っている場合、同じ軸上に配置します。スプレッドされた端点が一方だけなら、軸上に移動できるのは共有されていない端点だけです。両方の端点がスプレッドされている場合は、競合するポートを別々に保つため、外側ブリッジを維持してください。
• 関係のない不透明ノードを横切るエッジ、共有経路が曖昧な状態、または別のルートを覆う関係ラベルは、決して許容してはいけません。 フィールドの列挙値、間隔の計算、ジオメトリの修正ルール、リポジトリの根拠、またはモードごとの配置が必要な場合に限り、references/authoring-contract.md を読みます。

成果物の確定

修正中は validate を使用し、最終確認では deliver を一度だけ使用します。成果物の確定時には、仕様の正確なバイト列を同じディレクトリ内の非公開スナップショットに固定し、そのスナップショットをレンダリングしてチェックしたうえで、HTML をアトミックにコミットし、仕様と成果物の SHA-256 およびバイト数を報告します。これは決定論的な成果物の根拠であり、ブラウザーで Viewer を動作させるものではありません。

成果物の確定後、信頼済み HTML を変更または再レンダリングせずに、範囲を限定したデスクトップの根拠を収集します。

node bin/archify.mjs visual-check <output.html> --json

visual-check は、確定した HTML を変更または再レンダリングせずに、自動化されたブラウザーの根拠を収集します。機械可読な測定値とスクリーンショットは、視覚的な仕上がりを承認するものではありません。標準的な受領記録のフィールド、カバレッジ、サイドカー、終了時の動作、補足の手動記録要件については、references/delivery-contract.md に従ってください。

次の 3 つの主張は分けてください。deliver は決定論的な成果物チェックを証明し、visual-check は実際のブラウザーで範囲を限定した動作を証明します。また、視覚的なレビューには実際の人間、または画像を扱えるレビュアーが必要です。ブラウザーの根拠と視覚的なレビューは、それぞれ独立して報告してください。制約のない目視確認で裏付けられるのは、視覚的なレビューのみです。補足の手動ブラウザー作業を記録するとき、または環境上の障害に対応するときは、標準の成果物確定コントラクトを使用してください。

ユーザーがローカルプレビューをすぐに確認したい場合に限り、--open を追加します。デスクトップで作成作業を続ける場合、任意で使用できるコマンドは次のとおりです。

node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase

プレビューは既定では開始しないでください。プレビュー、リポジトリの根拠、エクスポートの受領記録、視覚的なレビュー、またはコミット後のオープンを行う場合は、references/delivery-contract.md を読んでください。

Viewer の任意機能

生成される HTML には、テーマ切り替え、パン／ズーム、検索、フォーカス、関係の追跡、セマンティックビュー、プレゼンテーション、正確なエクスポートがすでに含まれています。これらは閲覧者向けの機能であり、追加の作成作業ではありません。meta.animation: "trace" はオプトインです。meta.views は任意で、厳選したチャプターを 5 つ以内で含めてください。

ユーザーが Share Cards、Route/Reach cards、モーション、ガイド付きストーリー、ディープリンク、プレゼンテーション、検索／フォーカス、その他の Viewer Runtime 機能を明示的に求めた場合に限り、references/viewer-runtime.md を読んでください。

セットアップと代替手段

スキルパッケージ内へのインストールは不要です。次のコマンドで確認してください。

node bin/archify.mjs doctor
node bin/archify.mjs demo <output-directory>

シェルを使用できない場合は、アーキテクチャ SVG を assets/template.html に手動で配置し、インラインカラーではなく CSS のセマンティッククラスを使用して、references/delivery-contract.md の視覚的なレビューコントラクトに従ってください。

出力

チェック済み HTML のパス、図の種類、検証の概要、仕様／成果物の受領記録、ブラウザーの根拠のステータス、正確な視覚的レビューのステータスを返してください。コマンドの終了コードが 0 以外の場合に成功を主張したり、実際に行っていない視覚的な確認を行ったと主張したりしないでください。