Archify
Archify 部署：在 CI 中运行确定性的架构图构建
覆盖 skill 与事实输入固定、校验门禁、last-good 预览、导出检查、权限和回滚。
你将学会
- Version Archify inputs and compiler
- Design CI validation and last-good gates
- Operate safe export and rollback paths
开始前需要
- 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.
先看结论
- Pin compiler and authored facts together.
- Make validation and last-good previews release gates.
- Treat exports, permissions, and visual diffs as operational surfaces.
Pin the compiler and the facts
可复现的 Archify 构建要同时固定 skill/compiler 和承载事实的 JSON 或代码提交，在 CI 中把校验、候选与 last-good 对比、导出校验和 checksum 设为门禁，并保留可回滚的版本化产物。
Keep secrets and private source out of the rendered artifact unless the repository policy explicitly permits them. Prefer a sanitized architecture fixture for public CI and link back to the private evidence system when necessary.
Use last-good as an explicit release boundary
The README describes validation and last-good preview behavior. In CI, render the candidate beside the last accepted artifact, fail the job on schema or layout errors, and keep the last-good output available for reviewers. Do not replace a trustworthy diagram with a partially rendered candidate just because the export step produced a file.
Compare normalized JSON and visual diffs for a fixed input. A changed edge, missing source trace, or unexpected animation should be reviewed as a semantic change, not dismissed as cosmetic noise.
Harden exports and permissions
Run diagram generation with least-privilege access to the repository and an isolated output directory. Check that HTML is self-contained, external requests are expected, and generated media cannot escape the artifact root. Treat agent-produced JSON and source descriptions as untrusted input to the renderer.
Collect duration, node/edge counts, validation status, export format, artifact checksum, and input revision. These fields help distinguish a real architecture change from a toolchain or environment drift.
Upgrade and rollback
Canary a new Archify release on representative diagrams, including sequence and lifecycle cases, and compare validation, render, export, and source-trace results. Keep the previous skill revision and last-good artifacts available so rollback is a versioned change rather than a manual redraw.
如何选择
| 比较维度 | 方案 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
Pin the Archify skill and input revision.
- 2
Run validation and candidate/last-good comparisons in an isolated job.
- 3
Verify self-contained exports, permissions, checksums, and source traces.
- 4
Canary upgrades and retain a rollback revision and artifact.
可复制示例
archify:
skill_revision: <commit>
input_revision: <commit>
validation: required
last_good: artifacts/architecture-last-good.html
output_sha256: <recorded-hash>常见问题
Should CI publish every render even when validation fails?
Keep failed output as a review artifact, but publish it as failed and preserve the last-good diagram as the trusted release surface.
What belongs in the build record?
Record skill/compiler revision, input revision, host, validation status, node/edge counts, export format, duration, and checksum.
资料来源
- Archify README (captured 2026-08-31)来源核查 2026-08-31
- Archify repository来源核查 2026-08-31