Archify
小さな型付き JSON 仕様から、自己完結型のインタラクティブな HTML 図を作成します。デフォルトは静的出力です。ユーザーがデモやプレゼンテーションを要求した場合にのみモーションを有効にします。
高速オーサリングパス
通常の生成では、この限定されたパスを使用します。ユーザーがこれらの機能について質問しない限り、オプションのビューアーランタイムリファレンスを読まないでください。
-
質問から
architecture、workflow、sequence、dataflow、lifecycleのいずれかを選択します。 -
schemas/内の一致するスキーマ 1 つ、schemas/common.schema.json、examples/内の一致する JSON の例 1 つを読みます。それらのファイルのみを読みます。新規作成とは、新しい安定した ID、ドメイン用語、レイアウトを意味します。例はフィールドの形状の参考として使用し、事実としてコピーしないでください。 -
最初のアーティファクト: 次のツールアクションは候補を書き出す必要があります。レンダラーの内部を調査する前に候補を書き出してください。座標を散文で計画しないでください。明確なメインパス 1 つ、短いサイドブランチ、まばらなラベル、最大 12 のプライマリノードから始めてください。
meta.quality_profileを"showcase"に設定してください。ただし、ユーザーが明示的に高密度のstandardマップを要求した場合を除きます。自動ルートとラベルから始めてください。診断で必要とされるまではvia、channelX、channelY、labelAtを追加しないでください。修正ごとに、診断されたジオメトリ制御を最大 1 つ適用します。 -
候補を編集するたび、および引き渡しの直前に検証します:
node bin/archify.mjs validate <type> <candidate.json> --quality showcase --jsonアーティファクトチェックが 4 つだけのレシートは基本検証であり、ショーケース承認ではありません。ショーケースパスでは、9 つのアーティファクトチェックすべてが、構成エラー 0、警告 0 で報告される必要があります。候補が正確な
meta.quality_profileフィールドを省略または誤って綴っている場合は、ジオメトリの前に修正してください。最終検証に合格すると、候補は固定されます。その後は決して編集しないでください。 -
HTML を納品する場合、
deliverが最終承認コマンドです:node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json終了コードが 0 以外の場合、それを成功と表現することはできません。検証が失敗した場合、診断された
subjectのみを変更し、evidenceを確認し、supportedFixesから選択して再実行します。客観的なエラー数が新しい最小値に達するまで、集中的な修正を続けます。2 回連続してその最良の数が改善されなかった場合は、停止し、未解決の診断を正直に報告します。
最初の候補の前に renderers/shared/geometry.mjs、レンダラーソース、バリデーターソース、テスト、ベンチマークを読まないでください。サポートされていない内部診断があった場合、または 2 回の集中的な修正が失敗した後にのみ、実装を調査します。
ライフサイクルに関する注意: フェーズ列 0..4 はメインレールを占めます。イベント/結果列 0..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 つあること。サイドブランチは最も近いメインパスノードから分岐します。ルーティング制御を追加する前に、価値の低いエッジを削除してください。
- 真実の
autoデフォルトにはmeta.legendを省略します。必要な場合のみ、mode: auto|all|hiddenとレンダラーがサポートするentries.<kind>.label|visibleを使用します。ラベルは意味を決して変更しません。 - コンポーネントタイプは
frontend、backend、database、cloud、security、messagebus、externalです。バリアントはdefault、emphasis、security、dashedです。 - スペーシングは中心距離ではなく、明確なギャップを意味します。関係ラベルの場合、明確なギャップは測定されたマスク幅を超える必要があります。そうでない場合は、ラベルを省略するか、意図的に移動してください。
- 自動ルートは自身のエンドポイント側を所有します。側とは方向の契約です。最初と最後のセグメントは、その側に対して垂直に出入りする必要があります。
- 自動ポートスプレッドは、アーキテクチャ、ワークフロー、データフロー、ライフサイクルに対するデフォルトのレンダラー動作です。単一のリレーションシップと、明示的な
via、channelX、channelY、labelAt、または非autoルートをスキップします。ほぼ平行なポートは外側のブリッジを使用するため、自動ルーティングでは 8px 未満のセグメントや 16px 未満の内部ターンを作成できません。 - 関連のない不透明なノード、あいまいな共有コリドー、または別のルートをマスクする関係ラベルをエッジが横切ることを決して受け入れないでください。
フィールドの列挙型、スペーシングの計算、ジオメトリ修正ルール、リポジトリエビデンス、モード固有の配置が必要な場合にのみ、references/authoring-contract.md を読んでください。
納品
修正には validate を、最終承認には deliver を 1 回使用します。納品により、正確な仕様バイトがプライベートな同一ディレクトリのスナップショットに固定され、そのスナップショットをレンダリングしてチェックし、アトミックに HTML をコミットし、仕様とアーティファクトの両方の SHA-256 とバイト数を報告します。
--open は、ユーザーが即座にローカルプレビューを希望する場合にのみ追加してください。アクティブなデスクトップオーサリングループの場合、オプションのコマンドは次のとおりです:
node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase
デフォルトでプレビューを開始しないでください。プレビュー、リポジトリエビデンス、エクスポートレシート、ビジュアルレビュー、またはコミット後のオープンを使用する場合は、references/delivery-contract.md を読んでください。
オプションのビューアー機能
生成された HTML には、テーマ切り替え、パン/ズーム、検索、フォーカス、関係トレース、セマンティックビュー、プレゼンテーション、真実のエクスポートがすでに含まれています。これらはリーダーの機能であり、追加のオーサリング作業ではありません。meta.animation: "trace" はオプトインです。meta.views はオプションであり、最大 5 つの厳選されたチャプターを含める必要があります。
ユーザーが明示的に共有カード、ルート/リーチカード、モーション、ガイド付きストーリー、ディープリンク、プレゼンテーション、検索/フォーカス、またはその他のビューアーランタイム機能を要求した場合にのみ、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 パス、図タイプ、検証サマリー、仕様/アーティファクトレシート、真実のビジュアルレビューステータスを返します。ゼロ以外のコマンドを成功と主張したり、実行していないビジュアル検査を主張したりしないでください。