5 分钟上手一行命令把整个仓库变成可交互架构图【免费下载链接】archifyTurn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.项目地址: https://gitcode.com/GitHub_Trending/arch/archifyGitHub Trending 上有一个反复冲榜的开源项目 Archify稳定版 v3.0.1MIT 协议社区里的说法是「一句话把仓库变成可交互地图」。它的工作方式很特别不是又一个 AI 画图工具而是一条「AI 生成结构化 JSON 确定性渲染 多重校验」的流水线——AI 只负责把自然语言或代码理解成数据真正的绘图、布局、校验全由确定性的 Node.js 程序完成从机制上避免 AI 编造拓扑。这篇文章从一条命令开始带你走完「装好 → 生成 → 看懂产物 → 导出分享」的全流程并落到仓库源码上解释每一步。一条命令跑通全流程Archify 以 Agent Skill 的形式分发给 Cursor、Claude Code、Codex CLI、OpenCode 等 AI 编程工具安装只需要一行npx skills add tt-a1i/archify -g想先试用再安装可以用npx skills use tt-a1i/archifyarchify --agent codex。装好后不需要打开任何 GUI直接对 Agent 下指令即可例如仓库 README.md 里给出的最小用例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.甚至不需要真实仓库——从一个纯文字描述就能生成图。当你想分析真实代码库时在仓库目录里告诉 AgentAnalyze this repository, then use archify to create a high-level runtime architecture diagram并约束规模8–12 个核心组件、一条主路径、外部依赖、信任边界Agent 会读取代码、把行为映射成 JSON 再交付图。细看 Skill 的交付路径 archify/SKILL.md每一步都是显式 CLI 调用写完整 JSON 候选后运行node bin/archify.mjs finalize type candidate.json output.html --quality showcase --jsonfinalize是一条复合命令内部按validate → deliver → check → browser-check四阶段串行执行见 archify/bin/finalize.mjs 的FINALIZE_STAGES定义。也就是说一次调用要同时通过 Schema 校验、布局规则校验、HTML/SVG 结构检查以及真实浏览器渲染检查才算成功。如果失败非零退出码意味着不是成功——输出是稳定的规则码 精确的失败位置 唯一允许的修复动作而不是一段 Node 堆栈。仓库还提供了不需要 AI 的「零依赖 CLI」入口安装后可直接验证产物node archify/bin/archify.mjs doctor检查环境node archify/bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json校验一个 JSON。README 中展示的完整命令序列如下cd archify node bin/archify.mjs doctor node bin/archify.mjs demo /tmp/archify-demo node bin/archify.mjs guide Show CI/CD checks, approval, deploy, and rollback node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json其中preview是可选的真浏览器桌面循环监听一个 JSON 文件只有最新版本通过全部校验才刷新失败时保留上一个已验证的图——这正好呼应了社区里「交图前过五道校验」的说法。读懂 AI 生成 JSON 确定性渲染的产物结构Archify 的中间产物JSON IR是整个体系的枢纽。它不是让 AI 直接输出 HTML而是先输出一份严格类型的 JSON再交给确定性的渲染器。打开一个最小例子 archify/examples/web-app.architecture.json可以看到architecture类型的顶层结构{ schema_version: 1, diagram_type: architecture, meta: { title: Sample Web App, output: web-app-rendered.html, quality_profile: showcase }, components: [ { id: api, type: backend, label: API Server, sublabel: FastAPI :8000, pos: [670, 300], size: [130, 60] } ], boundaries: [ { kind: region, label: AWS Region: us-west-2, wraps: [cdn, lb, api] } ], connections: [ { id: api-sql, from: api, to: db, label: SQL } ], cards: [] }五种图型各有专属 Schema全部在 archify/schemas/README.md 中登记workflowlanes/phases/groups/nodes/edges、sequenceparticipants/messages、dataflowstages/nodes/flows、lifecyclelanes/states/transitions、architecturecomponents/boundaries/connections。所有 Schema 在每一层都设置additionalProperties: false未知字段直接被拒——这保证了 AI 输出的 JSON 不会悄悄带进渲染器不认识的属性。类型定义好后第一道关卡是 Schema 校验。看 archify/renderers/shared/validator.mjs 的实现validateSchema(diagramType, data)调用编译好的校验器失败时不是笼统报错而是把instancePath注解成/nodes/3 (id: router)/label这种带 id/label 的路径并给出supportedFixes——这是刻意设计的「AI 可修复」错误格式。校验通过后进入确定性渲染。以架构图渲染器 archify/renderers/architecture/render-architecture.mjs 为例它内部的validateArchitecture()会做一系列机械性检查组件 ID 必须唯一、组件不能相互重叠最小间距 8px、标签宽度不能超过组件宽度、边界boundary包裹的组件必须真实存在、边界帧不能越出 viewBox、自动连线不能穿过组件、标签不能压住组件、箭头不能互相碰撞……这些全是可测量的硬规则没有任何「凭感觉」。渲染器还会做边界标题的可读性收敛resolveBoundaryTitles最多迭代 32 轮并针对showcase质量档自动摆放连线标签placeAutomaticLabels。连线是另一个值得注意的细节架构渲染器对自动路由的交叉点专门画了一个不透明的 haloautomatic-crossover-underlay让 X 形交叉在视觉上明确可读而显式手写的交叉则直接算阻断性错误。这意味着「AI 决定大方向、程序决定几何」——布局判断由 Agent 给出层级、间距、强调但真正的路由与间距由确定性代码完成README.md里把这称为「layout judgment over generic auto-layout」。最终渲染器把 SVG、卡片cards、来源证据注入模板 archify/assets/template.html生成单个自包含 HTML 文件。writeDiagram在 archify/renderers/shared/cli.mjs以原子方式替换输出先写临时文件、再绑定校验、最后提交输出路径守卫贯穿全程避免把渲染结果覆盖到输入文件上。产物 HTML 是自包含的——没有网络依赖别人收到文件就能直接打开交互。仓库里可直接打开体验的成品示例包括examples/web-app.html示例 Web 应用架构、examples/workflow-agent-tool-call.htmlAgent 工具调用工作流、examples/dataflow-product-analytics.html数据管道以及examples/archify-repo.htmlArchify 自己的仓库架构图。在浏览器里探索可交互到底指什么生成的是一个可探索的 Viewer而不是一张静态大图。README 里的快捷键表说明了一部分能力动作控制打开事实型 Diagram Guide?查找并聚焦语义节点/追踪上游/下游 authored reach聚焦节点 → Upstream / Downstream探测一条有向路径R或PATH对比一到两个语义角色L或LENS打开全局雷达视图M或MAP进入演示模式F切换视觉风格 / 主题 / 导出S/T/E这些交互的语义来源是 JSON 里的关系数据。看 archify/renderers/shared/cli.mjs 的focusNodeAttrs与focusEdgeAttrs每个节点会被打上data-node-id、data-node-kind、data-node-label等语义属性每条边有data-edge-from/data-edge-toViewer 里的聚焦、路径探测、角色对比全部复用这些「已经过校验的作者事实」而不是运行时重新推断拓扑——README.md把这称为 truthful interaction诚实的交互。同时 Viewer 支持稳定的深链状态#focusid、#focusidreachupstream|downstream、#routesource~target、#lenskind~kind都能直接还原到对应视图复制链接即可分享精确视角。导出 PNG/SVG/分享卡的几种姿势交互体验之外Archify 的导出管线同样值得看源码它解决了「矢量图导出糊掉」的常见问题。看 viewer/export.js默认以4 倍源分辨率栅格化RASTER_SCALE 4。实现技巧是把序列化后的 SVG 的width/height直接设为viewBox × 4让浏览器原生按该分辨率栅格化再以图片自然尺寸drawImage不做上采样、不产生模糊画布总像素超过 16 Mpx 上限时MAX_CANVAS_PIXELS自动在 {4,3,2,1} 中选择最大安全倍数。JPEG/WebP 由于没有 alpha 通道会显式绘制当前主题背景色。导出菜单覆盖的格式包括PNG / JPEG / WebP4x 栅格化当前主题定格JPEG/WebP 质量 0.95。SVG默认导出双主题自适配 SVG——同时内嵌 dark/light 两套 CSS 变量 media (prefers-color-scheme)规则嵌进 README 或任何支持色彩方案的环境会自动换肤也支持themelight|dark锁定单主题。WebM可选动图meta.animation: trace开启的 trace 动效以固定 6 秒、30fps 捕获。Route Share Card / Reach Share Card把当前追踪的路径或上游/下游 reach 快照成 1200×630 的分享卡 PNG全图保留为上下文其余部分淡化导出时其他节点降到 0.18/0.14 不透明度只高亮你要讲的那条路。导出实现还特意做了「规范状态检查」只有 SVG 处于无残留 Viewer 状态的干净快照canonicalStateClean才允许导出分享卡路由/Reach 快照也会独立校验routeStateClean/reachStateClean避免把交互残留带进静态图。值得强调的一个细节导出的是「完整图」不会带上 Viewer 的临时状态——README.md将之总结为「exports remain full-diagram and free of temporary viewer state」即静态产物与交互运行时严格分离。仓库里现成的导出效果可以直接看docs/assets/archify-menu.png 展示了导出菜单docs/assets/archify-route-share-card.png 是一张路由分享卡成品1200×630、全图上下文保留docs/assets/archify-dark.png 与 docs/assets/archify-light.png 则展示了同一张图在暗/亮两套主题下的切换效果。而针对真实代码库的产物样例可以看 docs/assets/mco-runtime-share-card.png对mco-org/mco仓库追踪生成的架构分享卡。它解决的不只是「画图」问题把整条链路放在一起看Archify 最有价值的地方在于它重新定义了「AI 画架构图」的可信度AI 不直接产图而是产数据数据过 Schema、过布局规则、过浏览器渲染三重闸门失败时返回可机器读取、可精确修复的诊断。这正契合当下 AI 编程工具从「黑盒建议」走向「可干预、可追溯、可集成」的社区共识。对个人开发者它是 5 分钟就能跑通的一次性工具对团队它是一份可以进 CI、可以复查、可以留档的架构资产。一行命令把整个仓库变成可交互架构图之后剩下的问题不再是「怎么画」而是「接下来想让它长成什么样」。【免费下载链接】archifyTurn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考