1仕組みと動作原理

ツールチェーンの本質は「JSON-IR → スタンドアロンHTML」コンパイラ：作成者は小さな強い型付けのJSON仕様を記述するだけで、Node CLIがインラインSVGを含む単一ファイルのHTMLにレンダリングし、ランタイムバックエンドに依存しません。

archify/SKILL.md

Create a self-contained, interactive HTML diagram from a small typed JSON specification. Static output is the default; enable motion only when the user asks for a demo or presentation.

ここでの処理：「作図」を「JSONフィールドの入力」へと簡略化しています。型付きIRと公式スキーマにより幾何構造・セマンティクス・スタイルの3つを分離。HTMLは自己完結した成果物（テンプレートとフォントは assets/template.html 内にバイト単位でインライン化）であり、直接配布可能です。

「境界のある作成パス」の強制：通常の生成では1つの type schema ＋ common schema ＋ 1つのサンプルの閲覧のみが許可され、レンダラー／バリデータ／テストのソースコードを事前に確認することは禁止されています。読解バジェットをトークン効率と安定性に充てています。

archify/SKILL.md

Use this bounded path for ordinary generation. Do not read the optional Viewer Runtime reference unless the user asks about those features.

付随する厳格な指示はSKILL.mdの後半に記載（'Do not read `renderers/shared/geometry.mjs`, renderer source, validator source, tests, or benchmarks before the first candidate'）：説明のつかない内部診断が発生した場合、または2回連続で修復に失敗した場合にのみ実装の閲覧が許可されます。これは長文コンテキストを持つエージェントの脱線を防ぐための設計です。

「成果物先行」の規律：次のツールアクションは必ず候補JSONの出力でなければならず、プロンプト文（prose）内で正確な座標を計画することは禁止されています。開始時の制約は、1本のメインパス＋まばらなラベル＋最大12個の主要ノードです。

archify/SKILL.md

3. Artifact first: the next tool action must write the candidate. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, sparse labels, and at most 12 primary nodes. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; apply at most one diagnosed geometry control per repair.

ここでの処理：「考えてから書く」を「書いてから機械に診断させる」に置き換え、モデルが脳内で幾何計算を行うこと（最も信頼性の低い部分）を回避します。quality_profile はデフォルトで showcase となり、ユーザーが密度の高い図を明示的に要求した場合にのみ standard に引き下げられます。

検収はモデルの自己報告ではなく機械のレシートに依拠：validate のレシートが4項目のみのチェックの場合は基本合格、showcase では9つの成果物チェック項目をすべて満たし、composition error が0件、warning が0件である必要があります。

archify/SKILL.md

A receipt with only 4 artifact checks is basic validation, never showcase acceptance. A showcase pass must report all 9 artifact checks with 0 composition errors and 0 warnings. If the candidate omits or misspells the exact `meta.quality_profile` field, fix it before geometry. For a workflow v2 geometry diagnosis, run `node bin/archify.mjs validate workflow <candidate.json> --layout-json` and use the stable compiler receipt; solver internals are not authoring controls. A passing final validation freezes the candidate: never edit it afterward.

実際の実行確認：`node bin/archify.mjs validate architecture examples/web-app.architecture.json --quality showcase --json` を実行すると ok:true が返され、checks 配列はちょうど9項目（single_svg / finite_svg / orthogonal_arrows / label_route_clearance / relationship_crossings / relationship_corridors / container_border_runs / route_rhythm / legend_clearance）、composition.profile=showcase、errors=0、warnings=0 となります。

納品は確定的：deliver は仕様のバイトデータを同ディレクトリのプライベートスナップショットに固定し、そのスナップショットをレンダリングおよび検証した上でHTMLをアトミックにコミットし、仕様と成果物の両方のSHA-256およびバイト数を出力します。

archify/SKILL.md

Use `validate` during repair and `deliver` once for final acceptance. Delivery freezes the exact specification bytes into a private same-directory snapshot, renders and checks that snapshot, atomically commits the HTML, and reports SHA-256 plus byte counts for both specification and artifact. This is deterministic artifact evidence; it does not exercise the Viewer in a browser.

SKILL.md は互いに代替不可能な3つの証拠を明確に区分しています：deliver = 確定的な成果物チェック、visual-check = 実ブラウザ内での有界な挙動、知覚的ビジュアルレビュー = 人間または視覚能力を持つレビュアーによって行われる必要があります（'Report browser evidence and perceptual review independently'）。誠実さの規律：ゼロ以外の終了ステータスを決して成功と表現してはなりません。失敗した納品は前バージョンの出力を維持し、失敗したパスに対して visual-check を実行することは禁止されています（古い、最後に正常だった成果物をチェックしてしまうため）。

更新検知は実行可能なローカルスクリプトであり、読み取り専用のチェックのみを行い、ダウンロードやインストールは一切行いません：check-update.mjs が公式マニフェストを取得し、通知を表示した後に eventKey レシートによって確認を行います。

archify/SKILL.md

After the first candidate exists, run the packaged checker `scripts/check-update.mjs` once with Node and continue the requested workflow. If the command cannot run, continue without mentioning the check.

SKILL.md の44行目で境界を厳格に定義：'The notice is information, not permission. Keep the installed version unchanged; this v0.1 workflow never downloads, installs, or executes an update, and silence is never consent.' さらに、リモートマニフェストの summary を言い換えることは禁止されており（チェッカーの固定されたローカル文字列のみ引用可能）、リモートの文言が指示として扱われるのを防ぐインジェクション対策の規律となっています。

マニフェストURLはコードにハードコード：fetchCandidate はURLが定数 DEFAULT_MANIFEST_URL と一致することをアサートした上で、GET ＋ redirect:'error' ＋タイムアウト＋有界なJSON読み込みを行い、200以外または application/json 以外は例外なく失敗します。

archify/scripts/update-contract.mjs

export const DEFAULT_MANIFEST_URL = 'https://tt-a1i.github.io/archify/skill-updates/archify/stable.json';

固定された定数は skill-release.json の updateManifestUrl と一致しており（ローカルのバージョンメタデータとも整合性を検証）、更新チェックが第三者にリダイレクトされる経路を完全に遮断しています。裏付け証拠：scripts/check-update.mjs の fetchCandidate 内にある `if (manifestUrl !== DEFAULT_MANIFEST_URL) throw new UpdateContractError('unexpected manifest URL');` および `redirect: 'error'`。

ブランドロゴは推測ではなく「ダイジェスト固定」を採用：内蔵の Simple Icons カタログをオフラインで照会可能。ユーザーが公式の HTTP(S) URL を提供した場合にのみ取得を実行し、取得した画像を sha256 としてノードに固定します。レンダリングおよび検証時に未固定の取得を行うことはありません。

archify/SKILL.md

- Brand identity is optional and explicit. Put a canonical built-in ID in `brand` when the node names that real product. If no preset matches and the user supplied the official HTTP(S) URL, first run `node bin/archify.mjs brands capture "<url>" --json`, then author the returned digest-pinned `brand` object. Render and validate never perform an unpinned capture. Otherwise omit `brand`. Never infer a brand from a vague role such as "database", and never let a badge replace the semantic `type`, label, or relationship facts.

取得側にはSSRF防御を実装：HTTP(S)のみ許可、認証情報付きは禁止、非標準ポート拒否、localhost/.local 拒否、名前解決後にプライベートIP帯に該当する場合は拒否し、検証に合格したIPをソケットルックアップに固定してDNSリバインディングの脆弱性を塞ぎます（renderers/shared/brand-marks.mjs 参照）。上限は256KiB（HTML）／1MiB（画像）、同時実行数3、全体タイムアウトあり。

ブラウザのエビデンスはローカルの Chrome/Chromium のヘッドレスCDP（--remote-debugging-pipe）を使用して収集され、Playwright/Puppeteer の依存関係は導入しません。ブラウザが見つからない場合は、合格を装うことなく明確にスキップ（skip）します。

archify/bin/visual-check.mjs

export function findChrome({ env = process.env, platform = process.platform } = {}) { if (Object.prototype.hasOwnProperty.call(env, 'ARCHIFY_CHROME')) { return executable(env.ARCHIFY_CHROME, platform); }

実機検証：Chrome が存在しない環境では visual-check は EXIT.skipped となり、診断コード viewer/chrome-unavailable（'Chrome or Chromium is unavailable. Set ARCHIFY_CHROME to its executable path.'）を出力します。headless パラメータには --headless=new / --remote-debugging-pipe / --disable-gpu が含まれ、root 実行時または ARCHIFY_CHROME_NO_SANDBOX=1 が明示された場合にのみ --no-sandbox が追加されます。

「図が実際のコードを反映する必要がある」場合は git による検証を使用：repository-evidence.mjs が `git -C <repo>` を通じて remote/revision を取得し、リポジトリ相対のPOSIXパスを検証し、絶対パスや制御文字を禁止します。

archify/renderers/shared/repository-evidence.mjs

function runGit(repoRoot, args) { const result = spawnSync('git', ['-C', repoRoot, ...args], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, });

ここでの処理：アーキテクチャ図内のリポジトリリンクやバージョンを、モデルによる捏造ではなく検証可能な事実へと変換します。パス形式の検証（絶対パス、バックスラッシュ、制御文字の拒否）により、任意のローカルパスが成果物に混入するのを防ぎます。

2コア機能

015種類の図に対応する統一IR：architecture / workflow / sequence / dataflow / lifecycle、それぞれに公式JSONスキーマとユースケース判定表を完備

02自然言語またはMermaidによる入力：flowchart/graph、sequenceDiagram、stateDiagram からトポロジを読み取り、Mermaidのスタイルを機械的に模倣することなくArchify JSONに書き換え

03showcase クラスの機械検証：9項目の成果物チェック＋ composition error/warning が0件であることでのみ合格

04確定的納品レシート：仕様と成果物のSHA-256およびバイト数を出力し、納品後の仕様改ざんを防止

05自己完結型インタラクティブビューア：テーマ切り替え、パン／ズーム、検索、フォーカス、リレーション追跡、セマンティックビュー、プレゼンテーションモード。PNG/JPEG/WebP/SVG/WebMエクスポートはビューア側の機能として備わっており、追加の作成作業は不要

06ブラウザ挙動のエビデンス：成果物を書き換えたり再レンダリングすることなく、納品済みHTMLのサイズ／可読性／ビューアUI（chrome）のクリアランスおよびスクリーンショット（sidecar）を収集

07内蔵ブランドライブラリ＋安全な取得：`brands` によるオフライン照会、`brands capture <url>` によるダイジェスト固定

08ワークフロー／ライフサイクル専用エンジニアリング：workflow schema v2 レイアウト契約、v1→v2 移行（migrate）、アーキテクチャ比較（delta）、およびシナリオ別レシピガイド

3外部依存関係

Kind	Dependency / Endpoint
network	Archify 官方更新 manifest（唯一固定外发端点）
network	用户提供的官方品牌页/图标 URL（仅在显式 brands capture 或节点钉住品牌时抓取；私网地址被拒绝）
cli	Node.js >= 18（技能包内无需 npm install，doctor 可直接自检）
cli	git（仅在使用 repository evidence 时调用 `git -C <repo>` 取 remote/revision）
cli	本机 Google Chrome / Chromium（visual-check 的无头 CDP 浏览器；缺失则跳过并解释）
package	devDependencies（仅仓库开发/测试用，技能包运行时不依赖）：ajv 8.17.1 / parse5 7.3.0 / saxes 6.0.0 / simple-icons 16.28.0
network	本地预览 HTTP 服务（仅绑定 127.0.0.1，URL 必须是 loopback 根路径）

4推奨統制措置と判定根拠

安全運用のための推奨統制措置

Agent 向け

段階的・都度認可、サンドボックス推奨

管理者向け

承認フロー、ロールバック可能、全履歴監査

判定根拠（ファイルパスと抜粋）

scripts/: ローカルスクリプトまたはコマンドの実行: node bin/archify.mjs <validate|deliver|preview|compare|migrate|inspect|chec
网络端点: 外部ネットワークアクセスの宣言: GET https://tt-a1i.github.io/archify/skill-updates/archify/stable.json —— f
本地工作目录: ファイルの読み書きとアーティファクトの出力: 納品成果物とsidecar：<output.html> および同ディレクトリの receipt/contact-sheet/screenshots（deliver

監査ノート： 純粋なプロンプトではなく、実際に実行可能なスキルパッケージ（Node CLI ＋ローカル Chrome ＋ git）です。外部通信の範囲は明確で予測可能であり、無効化可能な公式マニフェストの GET（URL固定、redirect:'error'、読み取り専用）と、SSRF防御を備えたオプションの明示的にトリガーされるブランド取得のみです。認証情報／秘密鍵／Cookie の読み取りは一切行わず（環境変数は ARCHIFY_CHROME、ARCHIFY_BRAND_ALLOW_PRIVATE などの設定フラグとしてのみ使用）、ディスク書き込みもユーザーが指定した成果物パスおよびキャッシュディレクトリに限定されています。同じ黄判定の一般的なスクレイピング系スキルと比較してネットワークおよび書き込みの挙動が多いため、青ではなく黄として分類されています。

5二重目の独立検証

[ok] SKILL.md 声明的 9 项 showcase 检查真实存在 — 实跑 validate architecture examples/web-app.architecture.json --quality showcase --json：ok:true，checks 恰 9 项且全 ok:true，composition.errors=0 / warnings=0，与 SKILL.md 第 28 行「must report all 9 artifact checks with 0 composition errors and 0 warnings」逐字对应。
[ok] 更新检查只读、不下载不安装 — check-update.mjs 只有 fetch GET(candidate manifest)、有界读取与本地状态文件写入，无下载/解包/执行路径；SKILL.md 第 44 行明文承诺 'never downloads, installs, or executes an update'；fetchCandidate 首行即断言 manifestUrl === DEFAULT_MANIFEST_URL。
[ok] 固定外发端点只有一个 — http(s) 字面量扫描后，可执行代码里的外发目标仅 DEFAULT_MANIFEST_URL（scripts/update-contract.mjs:3 = https://tt-a1i.github.io/archify/skill-updates/archify/stable.json）；其余 http 命中为 docs/许可声明/品牌 source 元数据/data-URI、以及 preview 的 127.0.0.1。
[ok] 品牌抓取的 SSRF 防护成立 — validateUrlShape 拒绝非 HTTP(S)、带凭证 URL、非标准端口、localhost/.local；resolveRequestTarget 对解析出的每个地址做 isPrivateBrandAddress 检查；requestPinned 在 transport.request 的 lookup 中直接返回已校验地址，注释明说是为 'closes the DNS-rebinding gap'；ARCHIFY_BRAND_ALLOW_PRIVATE=1 才放开（默认关）。
[ok] 无凭证/密钥读取 — 对 bin/ renderers/ scripts/ delta/ 的 api_key|secret|password|token|keychain|.netrc|.ssh|bearer|authorization 扫描：命中仅为 URL 凭证字段的反向拒绝（brand-marks.mjs:126、repository-location.mjs:24-25、open-artifact.mjs:82）与 SVG tokenizer 变量名；process.env 命中全部为行为开关（ARCHIFY_*、LOCALAPPDATA、XDG_CACHE_HOME、PROGRAMFILES）。
[ok] visual-check 的浏览器依赖与降级行为 — findChrome 支持 ARCHIFY_CHROME 覆盖 + 三平台固定路径 + linux 命令探测；不可用时 receipt.status='skipped'、exit code 2（EXIT.skipped）、诊断 viewer/chrome-unavailable，绝不谎报通过。本环境未装 Chrome，故本报告未做浏览器证据冒烟（已如实标注）。
[ok] repository evidence 的 git 调用与路径校验 — runGit 用 spawnSync('git', ['-C', repoRoot, ...])（maxBuffer 16MiB）；verifiedSourcePath 拒绝绝对路径、反斜杠、控制字符，只接受 repo-relative POSIX 路径。
[ok] 预览服务器只在 loopback — bin/preview.mjs:13 `const loopbackHost = '127.0.0.1'`，server.listen(0, loopbackHost)；bin/open-artifact.mjs 拒绝非 http/非 127.0.0.1/带端口之外形状的 URL。

6結論

「見栄えの良い作図」の課題をエンジニアリングで解決：型付きIR ＋公式スキーマ＋機械検証レシートにより、モデルはフィールドを埋めるだけで済み、幾何学的な正しさはコンパイラと9項目のチェックによって担保されます。

極めて厳格な自己欺瞞防止規律：ゼロ以外の終了ステータスを成功と呼ぶことの禁止、失敗時の visual-check 実行禁止、3種類のエビデンス（確定的チェック／ブラウザ挙動／知覚的レビュー）の個別報告、納品後の仕様固定。

コンテキストの経済性：候補作成前の「閲覧禁止リスト」と必要に応じて参照する references 層を明確に区分し、長期タスクでも脱線しにくい設計。

狭いネットワーク露出面とインジェクション対策：唯一の固定エンドポイントは自社の Pages マニフェストのみ。取得処理はダイジェスト固定＋プライベートネットワーク拒否＋ DNS固定を実施し、更新文言を指示として解釈することを禁止。

真に自己完結した成果物：テンプレート、フォントサブセット、ブランドベクターをすべてインライン化。納品されたHTMLは実行時依存がなく、アーカイブや共有が容易。

検証可能なエンジニアリング水準：ジェネレーター自体に --check、ゴールデンテスト、136件のテストファイル、SECURITY.md の非公開脆弱性報告手順、THIRD_PARTY_NOTICES の個別ライセンスを完備。

最適な用途： 「納品可能、再検証可能、アーカイブ可能」な技術図面を必要とする方に最適：アーキテクチャ／ワークフロー／シーケンス／データフロー／ステート図など、特に成果物がオフラインで開けること、検証およびハッシュのエビデンスが提示できること、CIやドキュメントパイプラインに組み込めることが求められるユースケース。また、「図が実際のコードやリポジトリと一致していること」を厳格に要求するエンジニアリングチームにも適しています（repository evidence ＋ブランドのダイジェスト固定）。ホスト環境にはシェル（Node）とディスク書き込み権限が必要であり、ブラウザエビデンスを取得するにはローカルの Chrome/Chromium も必要です。

不向きな用途： 手軽なスケッチ図だけを求め、インストールや検証のコストをかけたくない軽量なユースケースには不向き。「感覚的な美観保証」を求める納品には不向き（機械レシートは見た目の美しさを評価しないため、人間または視覚能力を持つレビュアーが必要）。シェルのない環境には不向き（SKILL.md には assets/template.html を手動編集する縮退パスが用意されていますが、検証や納品レシートを放棄することになります）。更新チェックを自動アップデート機能として利用したいケースには不向き（本バージョンではダウンロードやインストールは一切行いません）。

Install Agent-Ready

① Verified Mirror 2026-09-15

Option A · Direct DownloadDownload archify.tar.gz

sha256: 6a2bea3e072ab6aa…

Option B · Copy Guide for Agent

install.json

Agent はこの JSON ガイドから自動的にダウンロードして検証します。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d673e8300d.