Archify
Archify 未来与实践项目：构建可复现的架构观测台
围绕版本化拓扑事实、conformance 夹具、变更影响、无障碍和治理发布，规划 Archify 实践项目。
你将学会
- Design a versioned topology package
- Build a conformance fixture and change-impact view
- Plan governed, reversible publishing
开始前需要
- 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.
先看结论
- Versioned topology packages can keep facts, visuals, and decisions together.
- A narrow observatory fixture is more useful than claiming automatic completeness.
- Adopt trace-only, advisory, then enforced publishing with fallback and conformance tests.
The next useful abstraction
Archify 的下一步可以是版本化拓扑包：把类型化事实、源码提交、校验回执、渲染投影、变更理由和审核决定一起保存。本文设计一个单仓库、单图表类型、单导出的观测台，并以 trace-only、advisory、enforced 逐步治理自动发布。
A capability manifest could declare supported diagram types, export formats, interaction modes, source-link policies, and resource budgets. CI could explain why a candidate changed and whether the change is a topology fact, a layout adjustment, or a renderer upgrade.
Capstone: the architecture observatory
Build a service that runs a fixed set of public fixtures through a pinned Archify revision. Store normalized JSON, validation receipts, source-link coverage, visual snapshots, export checksums, accessibility findings, and reviewer approval. Add a change-impact view that highlights which downstream routes or components moved between revisions.
Keep the first version narrow: one repository, one diagram type, and one export. The value is replayability and explainability, not a claim of complete automatic architecture discovery.
Evaluation and governance
Measure edge evidence coverage, false-positive and missing-edge rates, validation stability, render and export latency, artifact size, accessibility, and reviewer time. Add adversarial fixtures for prompt injection in source text, unsafe links, duplicate IDs, stale revisions, and oversized graphs.
Govern publication with signed input revisions, allow-listed source domains, redacted private topology, and a deletion path for sensitive artifacts. A future plugin or host adapter should pass the same conformance suite before it is marked compatible.
A reversible roadmap
Start with trace-only snapshots, then advisory diffs, then enforce publication gates for protected architecture docs. Keep last-good artifacts and a manual editor fallback available. These are proposed directions; the practical contribution is a small fixture, a measurable contract, and evidence that another maintainer can replay.
如何选择
| 比较维度 | 方案 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
Choose one repository, diagram type, export, and public fixture set.
- 2
Store normalized IR, receipts, source coverage, snapshots, checksums, and accessibility.
- 3
Measure evidence, diffs, latency, size, and reviewer time across revisions.
- 4
Roll out trace-only → advisory → enforced gates with signed inputs and fallback.
可复制示例
{
"input_revision": "<commit>",
"diagram_type": "architecture",
"ir_sha256": "<hash>",
"source_coverage": 0,
"validation": { "status": "pass" },
"publication": { "status": "review" }
}常见问题
Is an architecture observatory part of Archify now?
No. It is a proposed project built around the repository's typed IR, validation, source tracing, and exports.
How do I prevent automatic diagrams from becoming stale?
Run pinned fixtures in CI, compare candidate with last-good, require source coverage and review, and keep the input revision beside the artifact.
资料来源
- Archify README (captured 2026-08-31)来源核查 2026-08-31
- Archify repository来源核查 2026-08-31