AiRobotNews 人工智能机器人技术网

一句话画出能点的架构图:Archify 把「图」做成了可校验的产物

一句话画出能点的架构图:Archify 把「图」做成了可校验的产物

给 agent 描述一句「浏览器调 API,API 查 Redis,缓存没命中再查 PostgreSQL」,它会回你一个能点、能缩放、能导出图片的 HTML 文件。

这就是 Archify 在做的事。项目作者 tt-a1i,Apache-2.0 开源,9 月 1 日登上 GitHub Trending 周榜第一(全语言),其后被量子位采访报道过。

Archify 的交互式架构图

它产出的不是一张图片

Archify 的输出是一个自包含的 HTML 文件。双击打开就能用:点节点看详情,沿连线追上游下游,按 R 抽一条路径,按 M 打开全局雷达图,按 F 进演示模式。

样式有四套,明暗主题一键切换;导出支持 PNG、WebP、JPG 长图和打印成 PDF。追完一条路径可以导出 Route Share Card——一张 1200×630 的图,把整张架构图留着当上下文。

关键在于它同时保留了一份可编辑的源。图不是一次性渲染结果:每次都由一份带类型的 JSON 中间格式生成。想加 Redis、想把鉴权挪到左边、想高亮回滚路径,都是继续对话,agent 改源文件,其余结构不动。

除了图,它还能输出「一页答案」。让 agent 用 explainer 模式回答一个问题,得到的是一张单页:结论和理由打头,每个面板回答一个问题,步骤贴在它正在讲解的那张时序图旁边,读到哪一步就点亮图里对应的部分。

Use Archify to answer as one page: our API's P99 went from 80 ms to 600 ms
while the mean barely moved. What is the likely cause, and how should we investigate?

这种页面的价值在可核对:结论里每条论断都带编号来源,仓库摘录钉在某一个 commit 上,点开是来源卡片。也方便分享——还是一个 HTML 文件,四种样式、明暗主题,可以导长图或打印成 PDF。

用起来是三步

装:

npx -y skills@latest add https://archify.si --skill archify --agent cursor --global --copy --yes

不想装也可以先试:

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

然后对 agent 说一句话。要图,不需要有仓库:

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

要有出处的图,就让 agent 读仓库:

Analyze this repository, then use archify to create a high-level runtime architecture diagram.
Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.

最后是聊着改:add Redis、move auth to the left、highlight the rollback path。

它现在支持 Cursor、Claude Code、Codex CLI、opencode,也能作为 zip 上传到 Claude.ai 的 Skills 里;另外有社区集成接进 Hermes Agent 和 DeepSeek Harness。

十种图,别都往架构图上套

图型适合什么提示词里要写清
Architecture组件、服务、存储、边界范围、核心组件、主路径
WorkflowCI/CD、审批、工具调用、runbook参与者、顺序、分支、异常
SequenceAPI 调用、缓存回退、鉴权、异步链路调用方、被调方、返回、时序
Data Flow数据管道、血缘、PII、下游消费来源、变换、存储、边界
Lifecycle状态、重试、等待、终态状态、事件、重试与取消路径
ERD数据库表、字段、键、基数每张表每个字段的类型、主外键、关系基数
Class类、接口、成员、类型关系类型、关键成员、继承与实现、组合、依赖
Tree单父层级:仓库、模块、能力拆解根、层级、每支装什么
Timeline事故复盘、发布历史带时区的时间戳、事件、来源泳道
Waterfall一次请求或一次 agent 运行的时间都花在哪跨度、起止、嵌套、时间是否实测

拿不准用哪种,可以问那个零依赖 CLI:

node archify/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json

3.1 起新增了 ERD、Class、Tree、Timeline、Waterfall 五种;当前稳定版是 v3.2.0(2026-10-18)。

为什么不是让模型直接吐 Mermaid

README 里有一句划界的话:Archify 不是通用绘图编辑器,也不是 Mermaid 主题。

差别在流程上。它要求 agent 先生成带类型的 JSON IR,再跑校验:schema、布局、HTML/SVG、路由,以及标签与路径之间的避让检查,全过了才允许替换上一份「已知良好」的产物。任何一步失败,validate --json 和 deliver --json 会返回稳定的规则码、具体对象、实测证据,以及只允许的修复手段——而不是丢一段 Node 报错栈给 agent 自由发挥。

还有个细节挺实用:本地的 preview 只监听 127.0.0.1 的一个随机端口,看着一份 JSON 文件;只有最新候选过完所有闸,页面才刷新,中途失败就继续显示上一版验证过的图。

另外,它把「不装懂」写进了设计:聚焦、追上下游、精确路径、角色对比这些交互,复用的都是图里已声明的节点和关系,不会自己编拓扑,也不会声称运行时影响。需要出处时,节点会标 SRC n,点开是钉在某一个公开 commit 上的文件与行号。

想在 PR 里比对,就用 CLI

仓库自带一个零依赖 CLI,不经过对话也能跑:doctor 查环境,demo 出示例,validate 校验源,preview 起本地预览,deliver 渲染并交付。

做设计评审或 PR 评审时,有个子命令值得单独拿出来讲:compare。它把 Before / Delta / After 三份快照比对,产出带机器回执的架构变更图——新增了什么、删掉了什么、改了什么、挪到哪去了,都是声明过的事实,不是推断出来的运行时影响。

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

它明确不做什么

README 的 scope 一节列了四条:自动解析 Mermaid、通用自动布局、托管分享、所见即所得编辑,全都不在范围内。

有人拿它做的第一件事,是把一张手绘的多 agent 架构图变成可交互版本,然后用对话接上了一个 Kimi 执行池。也有人把上海 CityWalk 攻略做成了四天行程:切 D1–D4,点开某一站看详情,再跳到高德、小红书、大众点评——作者还自己加了到达打卡和停留时间。

在 Kimi Work 的插件商店里,它以「Interactive Architecture Diagram」的名字上架,一句话描述系统就能出图。

许可证是 Apache-2.0,早前以 MIT 发布的版本继续有效。

如果要给这套东西挑一句定位,大概是它把架构图从「画出来给人看」变成了「能被人核对、也能被机器校验的文件」——顺带还能当 explainer 用:让 agent 把答案写成一页,结论在前,每个面板回答一个问题,步骤贴着它正在讲解的时序图点亮。

项目地址

资料来源