Archify：把系统描述变成可验证、可交互的系统地图

项目地址：https://github.com/tt-a1i/archify  协议：MIT  Stars：65,999  更新：2026-09-17  版本：v2.17.0-dev.1

一、产品深度介绍

（一）它是什么

Archify 的自我定位很直接：「在对话里，把代码仓库或系统描述变成漂亮、可靠、可交互的系统地图」。它是一套基于 Node.js 的渲染与校验系统，并以 Agent Skill 的形式支持 Raven、Cursor、Claude Code、Codex CLI 和 OpenCode。Agent 负责生成 Typed JSON IR（带类型的 JSON 中间表示），Archify 再校验并确定性编译为便携、独立的 HTML/SVG 成品。

关键在于，它并非通用绘图编辑器，也不是某个 Mermaid 主题。它的价值是把「技术意图」变成「可交流的成品」：你描述系统，Agent 产出结构化源文件，Archify 负责排版判断、校验门禁与可交互渲染。普通成品不携带源码信息，需要证据时节点才标记 SRC n 并打开由 Git 校验、固定到公开 commit 的文件与行号。

（二）技术表现

从 README 与官方文档可以归纳出它的几项硬指标：

• 零依赖 CLI：node bin/archify.mjs 提供 doctor / demo / guide / validate / preview / deliver / compare 等子命令。
• 五类图 + 四套预设：架构、工作流、时序、数据流、生命周期五类；signal-flow、blueprint、classic、editorial 四套视觉预设。
• 深浅双主题：同一张图一键切换，导出始终保持完整原图，不携带临时 Viewer 状态。
• 确定性编译：相同 Typed JSON IR 产出可复现结果，每种渲染模式都有 Schema 与可复现源。
• 协议与实现：MIT 协议，JavaScript 实现，无需后端服务，结果默认就是一个可分享的 HTML 文件。

二、主要功能特点与应用场景

Archify 的能力可以归纳为「打开即成品、评审有依据、分享零摩擦」三条主线：

• 打开就是成品：五种技术图、四套视觉预设、深浅主题、内置品牌徽标，以及显式启用的有限动效（如 trace 描边动画）。
• 合并前看清架构变化：Architecture Delta 把两份已校验快照对比为 Before / Delta / After，精确区分新增、删除、语义变化、移动与重路由，并附机器回执。
• 每次探索都有依据：搜索节点、按需打开版本校验源码、追踪作者定义的上下游可达与精确路径、对比语义角色、播放引导故事，全程复用作者节点与关系，不编造拓扑。
• 一键分享：Export 菜单可复制 PNG 到剪贴板、下载静态或动效格式；Copy Share Card 产出标准 1200×630 图，Route Share Card 与 Reach Share Card 分别固化路径与可达范围阅读。

适用场景包括：PR / 设计评审中展示架构变更、给团队讲解系统结构、沉淀 CI/CD 与运维 Runbook、新人 onboarding 时快速建立全局认知，以及为 README、Release 或社交平台生成标准分享卡片。

三、如何安装与使用

安装以 skills 命令分发，全局安装只需一行：

npx skills add tt-a1i/archify -g

对 Cursor 做显式、非交互安装：

npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

只想临时体验、不落地安装，可让 Codex 直接调用：

npx skills use tt-a1i/archify@archify --agent codex

安装后并不需要绑定代码库——在任意 Agent 对话里描述系统即可：「用 Archify 画出：Browser → API → Redis 缓存 → PostgreSQL 回源。」需要源码证据时，打开仓库再让 Agent 分析并生成高层运行时架构图。之后还能在对话里细调，例如「增加 Redis」「把鉴权移到左侧」「突出回滚路径」，Archify 会保留 Typed Source 只改相关部分。

仓库内还提供零依赖 CLI 做质量校验与本地交付：

node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

四、官方地址与获取方式

• GitHub 仓库：https://github.com/tt-a1i/archify
• 在线项目页：https://tt-a1i.github.io/archify/
• Proof Lab：https://tt-a1i.github.io/archify/gallery.html（收录 11 个已校验场景、JSON 源与校验回执）
• 场景选图指南：https://tt-a1i.github.io/archify/guide.html
• Skill 契约：仓库内 archify/SKILL.md 与 archify/schemas/README.md

五、与同类方案对比

总体而言，Archify 的差异化不在「又能画一种图」，而在于把渲染、校验、交互与导出打包进 Agent 工作流，并用 Typed JSON IR 保证产物可复现、可信任。

六、核心机制深度解析

Archify 把一次出图拆成生成、校验、预览、交付、迭代五步，每一步都有明确契约：

其中最关键的是「原子交付前校验」：Schema、布局、HTML/SVG、线路与标签到其他路径的净空检查必须全部通过，Showcase 成品才会替换上一份可信结果。失败时 validate –json 与 deliver –json 返回稳定规则码、准确对象与测量证据，并只列出真正支持的修复旋钮，而不是把 Node 堆栈丢给 Agent 去猜。可选的桌面循环还会在半写入或无效保存时保留「最后好图」，保证预览永远不崩。

七、实用技巧

• 稳定链接还原视图：导出与分享链接可用 #focus=<id>、#route=<source>~<target>、#lens=<kind>~<kind>、#view=<view-id> 等锚点精确恢复阅读状态。
• Viewer 键盘流：/ 搜节点、R 探路径、L 比角色、M 开雷达、P 播放故事、F 进演示台、S/T/E 切风格/主题/导出。
• 本地化配置：在源文件 meta 中设 locale 与视觉预设，不改作者内容；不设置 animation 时结果完全静态。
• 关闭联网检查：在 Agent 环境设 ARCHIFY_UPDATE_CHECK_DISABLED=1，可完全禁用发布检查的网络请求与提醒状态写入。
• 生产评审画像：架构图可启用 deployment-ownership 工程画像，负责人、区域归属、数据库私有边界或边界穿越缺失时直接阻断，从不静默开启。

需要显式动效与编辑风格时，可这样配置：

{
  "meta": {
    "locale": "zh-CN",
    "animation": "trace",
    "visual_preset": "signal-flow"
  }
}

八、最新更新动态

当前开发版本为 v2.17.0-dev.1（详见仓库 CHANGELOG.md）。从近期文档可看到几条能力主线：Architecture Delta 已支持 Before/Delta/After 机器回执对比；deployment-ownership 画像把生产部署评审做成了「缺失即阻断」的校验；视觉侧新增 editorial 暖纸深墨编辑风格，且几何完全不变；Proof Lab 已沉淀 11 个仓库内场景及其 JSON 源与校验回执；并通过社区集成支持 DeepSeek Harness（@tt-a1i/archify-dsh）。项目坚持 Agent-first，优先完善稳定的机器可读诊断，避免新增容易与 CLI 漂移的重复说明。

九、常见问题 FAQ

十、总结

Archify 把「系统描述 → 可信任系统地图」这一步塞进了 Agent 的对话流里：你描述、它排版、校验门禁兜底、交互与分享一键完成。它的真正价值不在于又能画一种图，而在于用 Typed JSON IR 与原子校验，把架构、工作流、时序、数据流、生命周期五类图变成了可复现、可依据的沟通产物。对于经常在 PR 评审、技术分享与文档配图中需要「讲清楚系统长什么样」的开发者与团队，这是一个值得装进编码 Agent 的 Skill。

在撰写本文的过程中，我主要参考了 Archify 的 GitHub 仓库（tt-a1i/archify）README.md、README_ZH.md、archify/SKILL.md、CHANGELOG.md 与在线项目页 tt-a1i.github.io/archify。文中数据以官方公开信息为准，可能随版本更新而变化。