一句话看懂项目地址https://github.com/tt-a1i/archifyArchify 是为 AI 编码代理设计的图表生成技能模块将系统描述或代码仓库转换为可交互的技术架构图。当前稳定版本 v3.0.1MIT 协议开源Star 75820Fork 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。将所有组件映射为 Mapkey 为组件 id。遍历连接为每个组件记录其在连接序列中的步骤索引。JSON 中的网格坐标需要转换为像素坐标才能渲染 SVG。中心点用于路由器计算连接线的起点和终点。使用 Map 索引组件提高查找性能。componentSteps 记录组件在连接序列中的位置用于路由器确定连接线的绘制顺序。动手上手安装为全局 Skillnpx 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 diagramsCHANGELOG 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 或 PNGArchify 输出为自包含 HTML内嵌交互能力。Mermaid 适合熟悉语法的开发者快速编写简单图表Archify 适合需要复杂交互和验证的架构可视化。Archify 作为 Agent Skill 的定位决定了它依赖 AI 代理的能力边界。如果代理无法准确理解系统描述或生成符合 schema 的 JSONArchify 无法交付有效产物。成功率取决于代理的理解和生成能力。局限与风险材料未说明支持的最大节点数或边数。对于超大规模系统数百个组件布局和路由算法的性能可能成为瓶颈。材料未说明是否支持实时协作编辑。多人同时编辑同一架构图的场景无法满足只能通过版本控制工具管理 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 类型。适合需要高质量可分享产物的架构可视化场景不适合需要实时协作或动态集成的场景。项目地址https://github.com/tt-a1i/archify