如果你经常让Agent写技术文档、画架构图,那么Archify我是极力推荐你安装的,Archify 是一个开源 AI Agent Skill,能把代码库或系统描述直接变成可交互的技术图表。它支持 Cursor、Claude Code、Codex CLI 等主流 Agent,输出自包含的 HTML 文件,离线也能查看。 Archify能帮你做什么
画架构图最烦的不是没思路,是拖框连线调颜色。系统一迭代,图就过时了,又得重来。Archify 想干掉的就是这个流程。
它本质上是一个 Agent Skill,不是独立软件。你把它装到 Cursor、Claude Code、Codex CLI、OpenCode 或 Raven 里,直接跟 Agent 说"帮我画一下这个仓库的运行时架构"。Agent 读取代码库,生成结构化 JSON 描述,经过校验渲染,最终给你一个单文件 HTML。双击浏览器打开,深色浅色一键切换,不需要联网,也不需要起本地服务。 这个 HTML 是可交互的。搜索节点、追踪调用链路、对比组件角色、播放引导故事,都能直接操作。还能导出 PNG、SVG、WebP 和 1200×630 社交分享卡,方便贴到技术博客或 Twitter。
安装Archify其实就一条命令
不需要全局装一堆 npm 包,也不需要配环境变量。终端里跑:
装完 Agent 就能自动识别。只想临时试试,不永久安装,可以跑:
codex 换成 claude-code 或 opencode 都行。装好后对 Agent 说"Use archify to map this repository's runtime architecture",它就开始分析出图。 产物是独立 HTML,打包了所有逻辑和样式。发给同事,随便什么浏览器打开都是同样的交互效果,不需要额外装依赖。离线可用,飞机上也能正常查看和导出。
Archify怎么上手
第一次用,别急着拿整个单体应用开刀。先挑一个小模块,让 Agent 生成一张 Architecture 总览图,熟悉输出风格和交互方式。你会发现,跟 Agent 说"把 auth 服务往左边挪一点"或"加一条 Redis 缓存连线",比自己在画图软件里拖框快得多。
如果团队对架构准确性要求高,可以把 Delta 对比接入 CI 流程。每次提 PR 自动生成 Before/Delta/After 对比图,审查者一眼就能看出改动影响了哪些组件。生成的 HTML 文件本身就可以提交到版本库,作为架构演进的历史记录。
回头看三个月前的架构图,你能清楚知道当时系统长什么样,以及为什么做了那些调整。
五种图表,各管一摊
Archify 内置五种图表类型,各自对应不同场景。Architecture 看系统整体结构,Workflow 看业务流程和状态流转,Sequence 看接口间的时序调用,Data Flow 追踪数据从哪来、经过哪些处理、落到哪,Lifecycle 管对象或服务的创建销毁过程。
你不需要自己纠结选哪个类型。直接告诉 Agent 想看什么,它通常能自己判断。比如你想理解微服务系统的调用链路,说"画一张时序图,展示用户下单后各个服务怎么交互",Agent 就会生成对应的 Sequence 图表。每种类型都有独立的 JSON Schema 和渲染器,保证输出符合视觉规范。
改架构前先看看影响有多大
Archify 最实用的功能之一是 Delta 对比。拿两个已验证的架构快照——比如上一版本和当前开发分支——生成三视图对比:左边 Before,右边 After,中间 Delta。
Delta 视图会精确标注每一处变化:新增了哪些节点、删掉了什么、哪里被修改、哪些组件移动了位置、调用关系有没有被重路由。不是简单文本 Diff,而是直接在图上用颜色标出来。合并代码前,你能直观审查这次架构变更的影响范围,避免"以为只改了一个接口,结果连带拖垮三个服务"的情况。
系统会列出每一个事实层面的变化,不会漏掉关键节点。这种能力特别适合接入 CI,在 PR 阶段自动生成变更影响图,作为代码审查的参考。
四层校验,不通过就不给你看图
图表交给你之前,Archify 会过四层关卡。Schema 结构检查确认 JSON 描述符合类型规范,没有缺字段或类型错误。布局合理性验证确保节点排布和连线符合可视化规范,不会出现线条交叉成一团、节点重叠或箭头指向空白处。HTML 和 SVG 语法检查杜绝非法标签、破损结构或非标准属性。路由与标签关联检查保证点击节点时能正确跳转,搜索和追踪不会指向不存在的元素。
任何一层挂了,它都不会硬着头皮把半成品塞给你。而是返回机器可读的诊断 JSON,告诉你具体问题在哪,甚至附带修复建议。
这种"零猜测"的交付策略,保证每张图都可信任,不会出现"看起来差不多,实际连不上"的幻觉。
每个节点都能点回源代码
图表里的每个节点都有 SRC N 标记,不是装饰,而是实打实的来源链接,指向 Git 仓库里经过验证的具体文件和行号范围。
浏览器里点击任意节点,就能直接跳转到对应源代码。所有交互基于已认证的拓扑关系,不是 Agent 凭空推断的运行时状态,也不会"发明"原本不存在的连接关系。你看到的架构图和代码库是严格对齐的。
这在几个场景下特别有用:架构评审时,有人质疑某个调用关系是否真实存在,直接点过去给他看代码;新人入职,对着图表理解系统结构还能一键跳转到实现;事故复盘时,快速确认组件的上游依赖和下游影响范围,而不是凭记忆猜。
本地预览不会把半成品甩你脸上
本地迭代图表时,Archify 的预览模式只在 127.0.0.1 监听,监视你的 JSON 描述文件。但关键是,只有最新生成的候选图表通过全部四层验证,浏览器视图才会刷新。如果某次修改导致校验失败——比如手滑删了必填字段,或连线指向不存在的节点——它会保留上一个有效版本,而不是给你看残缺的图或空白页面。
这避免了编辑中途文件损坏导致图表突然变空或出现奇怪错误的尴尬。你可以放心边改边看,不用担心中间状态会误导你。
键盘操作,不用鼠标也能逛完整张图
图表 Viewer 是键盘优先设计。按问号打开图表指南,斜杠搜索节点或路由端点,R 追踪调用路径,L 比较不同语义种类的组件,F 进入全屏演示舞台,P 播放引导故事。T 切换深浅主题,E 呼出导出菜单。
完全不用鼠标,像操作代码编辑器一样浏览整张架构图。搜索、跳转、对比、演示,核心功能都有快捷键。图表不只是"看看而已"的静态产物,而是真正能拿来分析、讲解和演示的工具。
Archify 解决了一个很实际的痛点:架构图总是画得慢、过时快、验证难。它把图表生成搬到聊天里,用结构化校验保证准确性,用来源追溯建立信任。如果你已经习惯用 Claude Code 或 Cursor 跟代码库对话,这个 Skill 几乎没有任何学习成本,值得一试。