tt-a1i/archify

TL;DR

Archify 是一个面向 AI Coding Agent（如 Cursor、Claude Code）的 Skill，旨在将代码库或系统描述转化为可交互、带验证机制的技术架构图。它通过生成自包含的 HTML 文件，解决了传统静态图表无法随代码迭代和 Agent 交互动态演进的问题。

它解决什么问题

在 AI 辅助开发中，Agent 生成的架构图往往是一次性的、静态的且缺乏事实依据。开发者难以在 Chat 中直接审查架构变更，也无法追踪组件间的真实依赖路径。 Archify 的出现动机在于实现 "Architecture as Code"。它试图让架构图成为可验证、可追溯且支持交互的通信工件，而非单纯的视觉展示。通过引入 typed JSON IR 和确定性检查机制，它确保生成的图表与源代码事实一致。

核心做法

Archify 的核心架构基于 Agent Skill 模式，通过 CLI 工具链与 LLM 交互： 1. Typed JSON IR：Agent 生成的不是直接渲染的图像，而是结构化的中间表示（IR）。每个图表类型都有对应的 Schema。 2. 原子化验证管道：在交付前，IR 需经过 schema、布局逻辑、路由连通性等多重检查。失败时返回机器可读的修复建议，而非堆栈跟踪。 3. 自包含 HTML 渲染：最终产物是一个单文件 HTML，内嵌 CSS/JS。支持 Dark/Light 主题、有限动画（Finite Motion）及多种导出格式。 4. 五种图表类型：支持 Architecture、Workflow、Sequence、Data Flow 和 Lifecycle，每种都有特定的布局算法（非通用自动排版）。 5. 交互与溯源：支持节点搜索、上下游路径追踪（Upstream/Downstream Reach）、角色对比及引导式故事播放，所有交互均基于已验证的拓扑结构。

作者

tt-a1i（个人开发者）。README 未提供其详细背景或过往项目履历。从技术实现看，作者对前端渲染、Agent Skill 规范及确定性系统设计有深入理解。

社区反应

截至数据截止日，该项目 Stars: 17,751，Forks: 1,230。在 Agent Skill 领域属于高热度项目。 - Star/Fork 比：约 14:1，表明用户不仅收藏，还有较高的参与意愿。 - Open Issues：30 个。相对于高 Star 数，Issue 数量适中，说明项目处于快速迭代期但核心功能相对稳定。 - 生态整合：明确支持 Raven、Cursor、Claude Code、Codex CLI 和 OpenCode，覆盖了主流 Agent 工具链。 - 赞助商：获得 EverMind (Raven) 和 APINEBULA 赞助，显示其在 Agent 基础设施层有一定认可度。

怎么上手

依赖：Node.js (建议 v22+，部分插件需 >=24)。
安装： bash npx skills add tt-a1i/archify -g
最小复现：在支持 Agent 的环境中（如 Cursor），输入 Prompt: text Use archify to map this repository's runtime architecture. Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
本地预览：安装后可通过 node bin/archify.mjs preview <input.json> output.html 验证 IR。

争议与局限

非通用绘图工具：Archify 明确声明不是 WYSIWYG 编辑器，也不支持 Mermaid 解析。它依赖 Agent 生成 IR，对 Prompt Engineering 和 Agent 能力有较高要求。
自动布局受限：采用 "Layout judgment over generic auto-layout"，Agent 需手动指定层级和间距。这增加了控制力但降低了自动化程度。
无托管分享：产物为本地 HTML，不支持云端托管和实时协作。分享依赖导出文件或自部署。
Agent 幻觉风险：虽然验证机制严格，但 IR 的生成仍依赖 Agent。若 Agent 错误理解代码结构，验证仅能检查逻辑一致性，无法纠正事实性误解（除非启用 Source Evidence 模式）。
平台依赖：部分功能（如实时预览）绑定本地桌面环境，且不同 Agent 的 Skill 安装路径和权限各异。