Design & Motion · tt-a1i/archify
archify
description: Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG, dark/light themes, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. Accept plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input; inspect repository evidence when the diagram must reflect real code. Use when the user asks to visualize system architecture, infrastructure, cloud/security/network topology, technical workflows, API call sequences, request lifecycles, data pipelines, ETL/ELT, data lineage, state machines, or to convert/beautify Mermaid.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
The toolchain is essentially a 'JSON-IR → standalone HTML' compiler: authors only need to write a compact, strongly-typed JSON spec, and the Node CLI renders it into a single-file HTML with inline SVG, free of runtime backend dependencies.
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.
What happens here: 'Drawing diagrams' is demoted to 'filling JSON fields'. Typed IR + official schemas separate geometry, semantics, and styling; the HTML output is self-contained (templates and fonts are embedded as bytes within assets/template.html) and ready for direct distribution.
Enforces a 'bounded authoring path': standard generation is strictly limited to reading 1 type schema + common schema + 1 example, prohibiting premature reading of renderer, validator, or test source code—swapping reading budget for tokens and stability.
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.
Supporting hard instructions appear in the latter part of SKILL.md ('Do not read `renderers/shared/geometry.mjs`, renderer source, validator source, tests, or benchmarks before the first candidate'): reading the implementation is only permitted when unexplainable internal diagnostics arise or after two consecutive failed repair attempts. This design prevents long-context agents from drifting off course.
'Artifact-first' discipline: the next tool action must be outputting a candidate JSON, strictly forbidding precise coordinate planning in prose; initial constraints start with a single primary path + sparse labels + at most 12 primary nodes.
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.
What happens here: Replaces 'think first, then write' with 'write first, then get diagnosed by machine', avoiding in-model geometric calculations (which is its least reliable area). `quality_profile` defaults to showcase, downgrading to standard only when the user explicitly requests dense diagrams.
Verification relies on machine receipts rather than model self-reports: a validate receipt with only 4 checks indicates basic pass, whereas showcase requires all 9 artifact checks to pass with 0 composition errors and 0 warnings.
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.
Actual run verification: `node bin/archify.mjs validate architecture examples/web-app.architecture.json --quality showcase --json` returns ok:true, with exactly 9 items in the checks array (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.
Delivery is deterministic: deliver freezes the specification bytes into a private snapshot in the same directory, renders and validates this snapshot, then atomically commits the HTML, outputting SHA-256 and byte counts for both the spec and the artifact.
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 defines three distinct, mutually non-substitutable forms of evidence: deliver = deterministic artifact checks, visual-check = bounded behavior inside a real browser, and perceptual visual review = must be completed by a human or a vision-capable reviewer ('Report browser evidence and perceptual review independently'). Honesty discipline: non-zero exits are never described as success; failed deliveries preserve the previous build's output, and running visual-check on failed paths is prohibited (as it would evaluate stale, last-good artifacts).
Update awareness is implemented via a runnable local script that performs read-only checks and never downloads or installs anything: check-update.mjs fetches the official manifest, presents a notification, and acknowledges it via eventKey receipt.
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.
Line 44 of SKILL.md hardcodes the boundaries: '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.' Furthermore, paraphrasing the remote manifest's summary is prohibited (only fixed local strings from the checker may be cited), serving as prompt injection protection against remote copy being treated as instructions.
The manifest URL is hardcoded: fetchCandidate first asserts that the URL matches the DEFAULT_MANIFEST_URL constant, then performs a GET with redirect:'error', a timeout, and bounded JSON parsing; non-200 responses or non-application/json types fail unconditionally.
archify/scripts/update-contract.mjs
export const DEFAULT_MANIFEST_URL = 'https://tt-a1i.github.io/archify/skill-updates/archify/stable.json';
The frozen constant matches the updateManifestUrl in skill-release.json (local version metadata also validates for consistency), completely blocking attempts to redirect update checks to third-party endpoints. Supporting evidence: inside fetchCandidate in scripts/check-update.mjs, `if (manifestUrl !== DEFAULT_MANIFEST_URL) throw new UpdateContractError('unexpected manifest URL');` alongside `redirect: 'error'`.
Brand icons use 'digest pinning' rather than guesswork: the built-in Simple Icons catalog supports offline lookups; fetching only occurs when the user provides an official HTTP(S) URL, pinning the fetched graphic as a sha256 into the node, while rendering and validation never perform unpinned fetches.
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.
The fetch side includes SSRF protection: HTTP(S) only, credentials forbidden, non-standard ports rejected, localhost/.local rejected, private IP ranges rejected post-resolution, and validated IPs are pinned into socket lookup to close DNS rebinding windows (see renderers/shared/brand-marks.mjs). Byte limits are capped at 256KiB (HTML) / 1MiB (images), concurrency at 3, with an overall timeout.
Browser evidence is collected via local Chrome/Chromium headless CDP (--remote-debugging-pipe) without introducing Playwright/Puppeteer dependencies; if no browser is found, it explicitly skips instead of faking a pass.
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); }
Local environment test: when Chrome is absent, visual-check exits via EXIT.skipped and outputs diagnostic code viewer/chrome-unavailable ('Chrome or Chromium is unavailable. Set ARCHIFY_CHROME to its executable path.'). Headless flags include --headless=new / --remote-debugging-pipe / --disable-gpu; --no-sandbox is only appended when running as root or when ARCHIFY_CHROME_NO_SANDBOX=1 is explicitly set.
Uses git forensics when 'diagrams must reflect real code': repository-evidence.mjs inspects remote/revision via `git -C <repo>` and validates repo-relative POSIX paths, forbidding absolute paths and control characters.
archify/renderers/shared/repository-evidence.mjs
function runGit(repoRoot, args) { const result = spawnSync('git', ['-C', repoRoot, ...args], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, });
What happens here: Turns 'repo links / revision tags in architecture diagrams' into verifiable facts rather than model hallucinations; path shape validation (rejecting absolute paths, backslashes, and control characters) prevents arbitrary local paths from being written into output artifacts.
2Core Capabilities
01Unified IR across five diagram types: architecture / workflow / sequence / dataflow / lifecycle, each backed by official JSON Schemas and scenario decision matrices
02Natural language or Mermaid inputs: reads topology from flowchart/graph, sequenceDiagram, and stateDiagram and rewrites them into Archify JSON without mechanically replicating Mermaid styles
03Showcase-grade machine validation: passes only when all 9 artifact checks succeed with 0 composition errors and 0 warnings
04Deterministic delivery receipts: outputs SHA-256 and byte counts for both spec and artifact, freezing the spec against post-delivery modifications
05Self-contained interactive viewer: theme toggling, pan/zoom, search, focus, relationship tracing, semantic views, and presentation mode; PNG/JPEG/WebP/SVG/WebM export is built directly into the viewer without extra authoring overhead
06Browser behavioral evidence: gathers payload size, readability, viewer chrome clearance metrics, and screenshot sidecars from delivered HTML without rewriting or re-rendering artifacts
07Built-in brand library + secure capture: offline lookup via `brands`, digest pinning via `brands capture <url>`
08Specialized workflow/lifecycle engineering: workflow schema v2 layout contracts, v1→v2 migration, architecture diffing (delta), and scenario recipe guides
3External Dependencies
| 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 根路径） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Executes local scripts or commands: node bin/archify.mjs <validate|deliver|preview|compare|migrate|inspect|chec
- 网络端点: Declares external network access: GET https://tt-a1i.github.io/archify/skill-updates/archify/stable.json —— f
- 本地工作目录: File I/O and artifact output: Delivered artifacts and sidecars: <output.html> and co-located receipt/contact-sheet/screenshots (deliver
Audit Notes: This is a genuine executable skill bundle (Node CLI + local Chrome + git), not a prompt-only skill. Its external network surface is clear and predictable: a toggleable official manifest GET (hardcoded URL, redirect:'error', read-only) plus optional, explicitly triggered brand captures with SSRF defenses. It accesses no credentials, secrets, or cookies (env vars serve purely as configuration flags: ARCHIFY_CHROME, ARCHIFY_BRAND_ALLOW_PRIVATE, etc.). Disk writes are restricted to user-designated output paths and cache directories. Given that its network and disk activities exceed those of typical yellow-tier scrapers, it is appropriately designated as yellow rather than blue.
5Second-Pass Verification
- [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。
6Verdict & Scenarios
Best for: Ideal for those needing 'deliverable, auditable, and archivable' technical diagrams: architecture, workflows, sequence diagrams, data flows, and state machines—especially when artifacts must open offline, provide validation and hash evidence, and integrate into CI or documentation pipelines. Also well-suited for engineering teams requiring diagrams to strictly match real code and repositories (via repository evidence + brand digest pinning). Requires host shell (Node) and disk write permissions; collecting browser evidence additionally requires local Chrome/Chromium.
Not for: Not suitable for lightweight use cases seeking quick scratchpad sketches without installation or validation overhead; not intended for deliveries demanding guaranteed perceptual aesthetics (machine receipts do not evaluate beauty; human or vision-capable reviewers are required); not suitable for shell-free environments (SKILL.md retains a fallback path for manual assets/template.html editing, but this forfeits validation and delivery receipts); not designed to treat update checks as an auto-update mechanism (this version never downloads or installs updates).
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload archify.tar.gz
sha256:
Option B · Copy Guide for Agent6a2bea3e072ab6aa…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d673e8300d.