Archify
Archify 源码分析：追踪类型化 IR、校验器与渲染器
从 JSON IR 和最小夹具出发，分析 schema、布局校验、来源追踪、自包含导出和 last-good 保护。
你将学会
- Use typed IR as a source-analysis seam
- Trace validation and rendering boundaries
- Design a deterministic export regression fixture
开始前需要
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
先看结论
- Typed JSON IR is the seam between agent output and deterministic code.
- Validation must precede rendering and protect last-good artifacts.
- Fixtures and export regression tests turn source reading into maintainable contributions.
Use the JSON IR as the seam
Archify 源码阅读的最佳入口是类型化 JSON IR：先构造三节点两边的最小夹具，定位 schema/types，再追踪校验、来源链接、渲染和导出。用重复渲染与回归夹具验证确定性，区分 README 声明、观察到的调用路径和仍需验证的假设。
Record which fields are required, how identifiers are normalized, and whether unknown properties are rejected or ignored. A strict schema protects the renderer from plausible but malformed model output; a permissive schema needs an explicit warning path so missing semantics do not disappear silently.
Trace validation before rendering
Follow the call path from parsed JSON into schema, layout, and relationship validation. Note whether validation is pure, whether it mutates the input, and how errors map back to a node or edge. Then run the same fixture through the CLI or skill entry point and compare the receipt with the direct library path if both are documented.
Validation should run before any export side effect. A last-good preview or atomic output directory is valuable because a failed candidate cannot overwrite the artifact a reviewer trusts. Test malformed IDs, disconnected nodes, duplicate edges, and an empty diagram as separate fixtures.
Inspect renderer and interaction code
Once the IR passes, locate the renderer that produces self-contained HTML/SVG and the modules that add finite motion, themes, route tracing, or Before/Delta/After comparison. Check how source links are carried into the visual layer, how HTML is escaped, and whether external assets are fetched at build time or runtime.
Export behavior is part of correctness. For a fixed fixture, render HTML and SVG twice and compare normalized output or checksums. If timestamps or random IDs make output differ, isolate those fields so a visual diff reflects a topology change rather than incidental noise.
Contribution-sized findings
The safest first contribution is a fixture plus a regression test: preserve a source trace through rendering, reject a duplicate edge, keep last-good output on validation failure, or make an export self-contained. Include the input revision, expected validation result, and a redacted artifact in the issue.
Avoid inferring architecture from a screenshot or a marketing bullet. Separate README claims, observed call paths, and hypotheses, and measure performance with the same fixture and host before proposing a renderer optimization. That discipline keeps Archify's deterministic promise meaningful as its diagram features grow.
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
Create a three-node fixture and locate its schema/types.
- 2
Trace validation, error mapping, and side-effect boundaries.
- 3
Inspect renderer, source links, interactions, and export determinism.
- 4
Submit a focused fixture/regression test with revision and receipt.
可复制示例
agent prompt -> typed JSON IR -> schema/layout validation
-> renderer + source traces -> HTML/SVG/export
-> checksum + last-good artifact常见问题
Where should I begin in a large Archify checkout?
Begin at the typed JSON schema and a tiny fixture; it is the clearest seam between the agent skill and renderer code.
What proves an export is deterministic?
Render the same pinned fixture repeatedly, normalize intentional metadata, and compare output or visual checksums.
资料来源
- Archify README (captured 2026-08-31)来源核查 2026-08-31
- Archify repository来源核查 2026-08-31