GitHub 今日推荐｜archify：AI 代理自动生成可交互架构图的技能模块

一句话看懂

项目地址：github.com/tt-a1i/arch...

Archify 是为 AI 编码代理设计的图表生成技能模块，将系统描述或代码仓库转换为可交互的技术架构图。当前稳定版本 v3.0.1，MIT 协议开源，Star 75820，Fork 5096，当日新增 Star 1002。产物为单一自包含 HTML 文件，内嵌图表逻辑、样式与交互能力，无需安装即可浏览。支持 Cursor、Claude Code、Codex CLI、OpenCode，统一命令 npx skills add tt-a1i/archify -g。

它解决什么问题

Archify 通过 AI 代理对话直接从自然语言描述或仓库路径生成图表，输出单一 HTML 文件，可离线浏览和分享。内置验证机制在交付前检查 schema、布局、路由、标签间距，失败时返回规则码和修复建议。支持源码关联的架构图，节点标记 SRC n 可打开 Git 验证的文件及行范围，锁定到特定公开 commit。Architecture Delta 模式支持两个快照的 Before/Delta/After 对比，输出机器可读变更收据，用于 PR 评审和合规检查。

核心概念速览

Agent Skill：为 AI 编码代理设计的可安装能力模块，接收自然语言描述生成图表。

Typed JSON IR：类型化的 JSON 中间表示，图表生成前先输出符合 schema 的 JSON，经验证后渲染为 HTML。

Self-contained HTML：单文件包含全部资源的 HTML，最终产物为内嵌图表逻辑、样式、交互的独立 HTML。

Evidence-backed Architecture ：源码关联的架构图，节点标记 SRC n 可打开 Git 验证的文件及行范围。

Architecture Delta：架构快照对比模式，比较两个 JSON 快照，输出 Before/Delta/After 视图及机器可读变更收据。

五类图表类型：Architecture（架构）展示组件、服务、存储、信任边界；Workflow（工作流）展示 CI/CD、审批流、工具调用；Sequence（序列）展示 API 调用、缓存回退、认证；Data Flow（数据流）展示数据管道、血缘关系、PII 边界；Lifecycle（生命周期）展示状态机、重试、终态。

交互能力包括四种视觉预设、深色/浅色主题、可选动效、节点搜索、路由追踪（最短有向路径）、上下游可达性分析、语义角色对比（Semantic Lens）和命名故事（Guided Story）播放。导出能力包括 PNG（含剪贴板复制）、SVG、WebM、1200×630 分享卡、路由分享卡、可达性分享卡。

架构拆解

核心模块：

archify/bin/archify.mjs 为 CLI 入口，解析命令（deliver/compare/finalize），管理 sidecar 文件命名空间和交付锁，根据 diagram type 动态加载对应渲染器。

archify/renderers/architecture/render-architecture.mjs 为 Architecture 图表渲染器，处理组件布局、边界计算、路由绘制、标签放置。

archify/renderers/workflow/workflow-compiler.mjs 为 Workflow 图表编译器，构建泳道、节点、边的几何结构，执行布局反馈迭代。

archify/renderers/shared/validator.mjs 为 JSON schema 验证器，检查输入符合性，输出带路径标注的诊断信息，被所有渲染器调用。

archify/renderers/shared/geometry.mjs 为共享几何工具，提供路由碰撞检测、标签放置、箭头计算等函数。

archify/schemas/*.schema.json 为五类图表的 JSON Schema 定义，定义节点、边、元数据的合法结构。

数据流：用户向 AI 代理发送描述 → 代理生成类型化 JSON → CLI 加载 JSON 并验证 → 渲染器计算布局 → 路由器生成连接路径 → 验证布局质量 → 生成自包含 HTML → 写入交付凭证。

关键实现走读

validateSchema 验证机制

export function validateSchema(diagramType, data) {
  const validate = validators[diagramType];
  if (!validate) {
    throw new Error(`validateSchema: unknown diagram type "${diagramType}"`);
  }
  if (!validate(data)) {
    const diagnostics = validate.errors.map((error) => {
      const annotated = annotatedPath(error.instancePath, data);
      const subject = {
        diagramType,
        path: annotated.path,
        ...(annotated.identity != null ? { identity: String(annotated.identity) } : {}),
      };
      const evidence = {
        keyword: error.keyword,
        expected: error.schema,
        ...error.params,
      };
      const supportedFixes = {
        additionalProperties: [`remove unsupported property ${JSON.stringify(error.params?.additionalProperty)}`],
        required: [`add required property ${JSON.stringify(error.params?.missingProperty)}`],

从 validators 映射表获取验证函数，检查 data 是否符合 schema。验证失败时遍历错误列表，为每个错误构建 diagnostic 对象，包含 subject（图表类型、路径、identity）、evidence（关键字、期望值、参数）、supportedFixes（针对 additionalProperties 和 required 错误的修复建议）。

结构化错误信息让 AI 代理能理解具体问题和修复方向。annotatedPath 提供路径标注，evidence 提供验证证据，supportedFixes 提供可执行的修复建议，避免代理反复试错。

gridLayout 和 measureComponent 布局计算

const grid = gridLayout(arch);

function measureComponent(c) {
  const [x, y] = resolveComponentPos(c, grid);
  const [w, h] = Array.isArray(c.size) ? c.size : [layout.defaultW, layout.defaultH];
  return { ...c, x, y, width: w, height: h, cx: x + w / 2, cy: y + h / 2 };
}

const components = new Map(asArray(arch.components).map((c) => [c.id, measureComponent(c)]));
const enforcesBoundaryTitleComposition = Boolean(arch.meta?.quality_profile);
const componentSteps = new Map();
for (const [index, conn] of asArray(arch.connections).entries()) {
  if (!componentSteps.has(conn.from)) componentSteps.set(conn.from, index);
  if (!componentSteps.has(conn.to)) componentSteps.set(conn.to, index + 1);
}

调用 gridLayout 解析网格布局配置。measureComponent 从组件的网格坐标解析为像素坐标，处理组件尺寸（使用显式 size 或默认值），计算中心点 cx 和 cy。将所有组件映射为 Map，key 为组件 id。遍历连接，为每个组件记录其在连接序列中的步骤索引。

JSON 中的网格坐标需要转换为像素坐标才能渲染 SVG。中心点用于路由器计算连接线的起点和终点。使用 Map 索引组件提高查找性能。componentSteps 记录组件在连接序列中的位置，用于路由器确定连接线的绘制顺序。

动手上手

安装为全局 Skill：

npx skills add tt-a1i/archify -g

通过代理生成简单序列图：

Use Archify to diagram a web request: Browser calls the API, the API checks Redis, and a cache miss queries PostgreSQL and fills the cache.

通过代理分析仓库并生成架构图：

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.

使用 Delta 模式比对两个架构快照（需预先生成 before.architecture.json 和 after.architecture.json）：

生成包含 Before/Delta/After 视图的 HTML 文件，同目录生成 .delivery.json sidecar 文件，记录变更收据。

应用场景

仓库架构快照：向代理提供仓库路径，生成运行时架构图，标注核心组件、主路径、外部依赖和信任边界。

登录流程序列图：描述 Browser → Web App → API → JWT → Redis → PostgreSQL 链路，生成 Sequence 图。

PR 架构评审（Delta 模式） ：对合并前后两个 JSON 快照执行 archify compare，输出 Delta 图及变更收据。

生产部署合规检查：生成包含信任边界和外部依赖的架构图，导出分享卡用于评审。

CI/CD 流程可视化：使用 Workflow 图表展示构建、测试、部署步骤及审批节点。

数据管道血缘追踪：使用 Data Flow 图表展示数据来源、转换逻辑、存储位置和 PII 边界。

独立分析

Archify 的核心价值在于验证式交付。README 强调"validated, interactive diagrams"，CHANGELOG v3.0 强调"delivery workflow that verifies the generated artifact before handing it back"。源码中 validator.mjs 抛出 diagnostic 失败时阻止输出，保证交付物符合质量标准。这与传统图表工具的"生成即交付"模式不同，Archify 要求生成的 JSON 通过 schema、布局、路由、标签间距等全量检查后才输出 HTML。

Topics 包含 mermaid-alternative，但与 Mermaid 的对比在于：Mermaid 采用文本定义语法，用户手动编写图表定义，Archify 采用 AI 代理生成 JSON，用户通过自然语言描述。Mermaid 输出为嵌入式 SVG 或 PNG，Archify 输出为自包含 HTML，内嵌交互能力。Mermaid 适合熟悉语法的开发者快速编写简单图表，Archify 适合需要复杂交互和验证的架构可视化。

Archify 作为 Agent Skill 的定位决定了它依赖 AI 代理的能力边界。如果代理无法准确理解系统描述或生成符合 schema 的 JSON，Archify 无法交付有效产物。成功率取决于代理的理解和生成能力。

局限与风险

材料未说明支持的最大节点数或边数。对于超大规模系统（数百个组件），布局和路由算法的性能可能成为瓶颈。

材料未说明是否支持实时协作编辑。多人同时编辑同一架构图的场景无法满足，只能通过版本控制工具管理 JSON 快照。

源码中未说明 Layout Feedback 迭代的收敛保证。如果布局算法无法收敛，生成过程可能进入无限循环或超时失败。

材料未说明 Evidence-backed Architecture 的 Git 托管平台支持范围。源码关联功能可能仅支持特定托管平台（如 GitHub），私有 GitLab 或 Bitbucket 实例可能不支持。

Delta 模式仅支持 Architecture 类型。其他四类图表类型无法进行 Before/After 对比，限制了变更追踪能力。

验证机制在保证质量的同时增加了生成失败的可能性。代理需要具备根据 diagnostic 修复 JSON 的能力，否则可能陷入反复生成失败的循环。

结论卡片

适合：需要快速将系统描述或代码仓库可视化的开发者、需要生成可分享架构图的架构师、需要结构化评审架构变更的技术评审人员、在 Cursor/Claude Code 等环境构建自动化流程的 AI 代理工作流构建者。

不适合：需要实时协作编辑架构图的团队、需要将图表嵌入动态 Web 应用的前端开发者、需要导出为 Visio/Lucidchart 格式的企业用户。

观点：Archify 通过 Agent Skill 模式和验证式交付，将图表生成嵌入代理对话，适合快速迭代和分享的场景。验证机制保证产物质量，但依赖代理的理解和生成能力。自包含 HTML 输出简化分享流程，Delta 模式为架构变更追踪提供机器可读收据，但仅支持 Architecture 类型。适合需要高质量可分享产物的架构可视化场景，不适合需要实时协作或动态集成的场景。

---

项目地址：github.com/tt-a1i/arch...