一天多了 4,260 颗星，Archify 想让 Agent 交付能核验的架构图

今天 GitHub Trending 里增长最快的 AI 相关项目之一是 tt-a1i/archify：榜单显示它当天新增 4,260 stars。北京时间 2026 年 8 月 28 日 05:02 复查时，仓库累计 22,800 stars；前者是 GitHub 当日榜单信号，后者是同一时点的累计数，不能混成一个“日增”数字。GitHub Trending 与 仓库 API 分别给出了这两类数据。

archify 的钩子不只是“让 Agent 画图”。它把架构图当成一份需要通过检查的交付物：Agent 写类型化 JSON，中间经过布局与产物验证，最后才生成可离线打开的 HTML、SVG、PNG 或分享卡。对那些已经会让 Agent 读仓库、却不太敢直接相信它画出的系统图的人，这个边界很具体。

我会利用这个突然冲上榜单的 Skill，梳理它到底在约束什么，以及什么时候值得装进项目。期望对大家有所帮助。

不是先让模型自由画一张图

传统的“把代码库画成架构图”请求，最容易得到两种结果：一张信息量很大但无法追溯的 Mermaid，或一张看起来完整、节点关系却不一定成立的图片。archify 选择了另一条路径。它支持 Architecture、Workflow、Sequence、Data Flow 与 Lifecycle 五种图，但中间表示不是一段 HTML，而是带 schema 的 JSON IR。README 和 完整 SKILL.md 都把这条路径写得很明确：

flowchart LR
  A[代码库或系统描述] --> B[Agent 编写 JSON IR]
  B --> C[Schema 与布局验证]
  C -->|通过| D[单文件 HTML/SVG]
  C -->|失败| E[带规则码的诊断]
  E --> B

这里的关键不在于 JSON 本身，而在于它把“看上去对”拆成几个可检查的问题。Skill 要求一个图先有明确主路径、最多约 12 个主节点；validate --json 会检查 schema、布局、路由和标签间距；deliver 只会用通过检查的候选文件替换目标产物，并返回 hash 与字节数收据。生成后仍可运行 visual-check 捕获不同桌面尺寸下的画面证据。交付规则 没有保证图中的业务事实自动正确，它保证的是：已经写进 JSON 的关系不会在渲染时悄悄变形。

这也解释了它为什么不把 Mermaid 解析和通用自动布局当成目标。README 明说，Mermaid 只是可接受的输入语言，最终仍要重新编写 Archify JSON；通用自动布局、托管分享和 WYSIWYG 编辑目前都在范围之外。项目范围 划得很窄，但换来的是可复现的产物边界。

这轮关注不只是旧仓库被翻出来

archify 创建于 2026 年 4 月 15 日，所以不能把今天的 22,800 累计 stars 当成“刚发布就爆发”。真正可观察的短期信号是 GitHub Today 的 +4,260；仓库 API 在上述观察时点显示它当天仍有推送，最近的提交集中在 DeepSeek Harness 集成验收、可复现 ZIP 与示例证明等细节上。提交历史 可以逐项核对。

它也不是一次性放出一个 README 后不再维护。最新稳定版 v2.15.0 发布于 8 月 17 日，加入了带来源约束的品牌标记和 sequence 图的列宽控制；当前开发版本 v2.16.0-dev.0 则继续补 Viewer 本地化。仓库的 CHANGELOG 还保留了每个版本的限制和修复原因。

所以更稳妥的说法不是“某个神奇制图模型突然出现了”，而是一个正在持续迭代的 Agent Skill，正好踩中了一项很实际的需求：当 AI 开始参与架构梳理和 PR 评审，团队需要的不只是图，还需要知道它从哪份结构化描述生成、哪里没通过检查、哪些结论仍须回到代码确认。

它把“可信”拆成了两层

Archify 的 README 里有一句很值得注意：交互只能重用已写入的节点和关系，不应凭空补出系统拓扑。比如从某个节点追踪上下游、查看指定路径、比较角色，都是基于作者给定的关系；如果要把节点连到源代码，Skill 要求把证据固定到公开 Git commit 与文件行号。证据约束 是可选项，而且不会默认开启。

这形成两层不同的“可信”：

层次	Archify 能做什么	仍需人核实什么
产物可信	用 schema、布局、路线与最终 HTML 检查，避免交付损坏或遮挡的图	图是否足够清晰、范围是否合适
事实可信	可把已核验的代码位置固定到特定 commit	节点、边、部署边界是否真的反映系统

不要把第一层误读成第二层。一个 JSON 文件即使通过全部验证，也只说明它是一张合格的图，不说明 Agent 对业务架构的理解天然正确。对于陌生仓库，先限定“8 到 12 个核心组件、一条主路径、外部依赖和信任边界”，再让人审核 JSON 与证据链接，通常比要求它“画出完整系统”更有用。

适合什么人先试

如果你的实际需要是开会时快速白板、自由拖拽或多人在线协作，Archify 的约束会显得重，现成绘图工具反而更快。它适合的是已经有代码库、规格或明确流程，并且希望把一次架构说明留成可版本化文件的开发者：例如 PR 前比较“Before / Delta / After”，或把缓存未命中、认证、重试这样的单一路径讲清楚。

安装命令是 npx skills add tt-a1i/archify -g，也可以用 npx skills use tt-a1i/archify@archify --agent codex 临时试用。官方安装说明 覆盖 Codex、Claude Code、Cursor 与 OpenCode。动手前应先读完整 Skill：它会要求 Agent 在本地写 JSON、HTML 及验证副产物；preview 会启动仅绑定 127.0.0.1 的本地预览；而任何“证据驱动”的图都应由你确认引用的 commit 和行号。

真正有价值的地方，也许不是得到一张更漂亮的架构图。是把 Agent 最容易含糊带过的那一步单独拿出来：先说明图的事实从哪里来，再让渲染器负责把它交付得清楚、稳定、可复查。