1. 场景与痛点在 AI 辅助开发越来越普及的今天一个典型场景正在高频出现开发者把仓库结构、一段核心代码或者一段「系统如何工作」的中文描述丢给 AI希望它直接产出一张能看懂、能点、还能回到源码的架构图 / 时序图 / 数据流图。但现实往往是AI 返回一小段 Mermaid 或 PlantUML 文本渲染后节点无法点击或者返回一张截图既不能缩放、不能搜索更无法追溯某个节点对应的是哪一段代码。想要「可交互 可溯源」通常还得手工搬运到 Draw.io 或自研前端链路又长又脆。tt-a1i/archify日增 ≈3.9k–14.9kJS正试图把这条链路做短、做确定让 Agent 只负责产出结构化数据让编译器负责从数据到图表的确定渲染。2. archify 解决什么问题archify 的核心主张可以概括为一句话把「画图」从 Agent 手里拿回来交给确定性的编译器。传统做法中如果你让 LLM 直接生成 Mermaid 源码存在几个典型问题语法不稳定节点文本里出现(、:、、中文、空格时Mermaid 经常解析失败Agent 需要反复试错。样式不可控同一份语义两次请求可能画出完全不同的布局难以沉淀为团队规范。无法溯源图上的框只是字符串没有办法反查到它来自哪一行代码、哪个函数、哪段系统描述。archify 的方案是Agent 输出带类型的 JSON IR中间表示再由确定性编译器把它编译成自包含的 HTML/SVG。类型系统约束了「哪些节点、哪些边、哪些属性」是合法的渲染层则保证同样的 IR 永远得到同样风格的图。{type:architecture,nodes:[{id:gateway,label:API Gateway,kind:service,source:{repo:my-app,file:src/index.ts,line:42}},{id:orders,label:Order Service,kind:service,source:{repo:my-app,file:src/orders/main.ts,line:15}},{id:db,label:PostgreSQL,kind:storage,source:{repo:my-app,file:infra/compose.yml,line:8}}],edges:[{from:gateway,to:orders,label:REST /order},{from:orders,to:db,label:SQL}]}3. 核心原理类型化 JSON IRarchify 位于中间的那一层就是这篇文章的重点——类型化的 JSON IR。它不是简单的 JSON 字符串拼接而是一套带 Schema 的中间表示type区分图种类architecture架构图、sequence时序图、dataflow数据流图。nodes是带类型的节点集合kind限定节点类别如service、storage、queue、client、function。edges描述关系label是带语义的连线说明而不是随意画一条箭头。source是溯源锚点记录repo、file、line让每个节点都能回到原始代码位置。为什么强调「带类型」因为有了类型上层可以被验证、被补全、被自动补默认样式一旦 Agent 生成了不合法的 IR编译器能给出确定性的错误信息而不是产出半张烂图。这也让 LLM 的 Function Calling / Tool Use 模式特别适配把 IR 的 Schema 当作工具的入参 JSON SchemaAgent 的产出天然就是合法数据。4. 确定性编译从 IR 到自包含 HTML/SVG「确定性编译」是 archify 与「让 LLM 直接画图」的本质区别。编译器的职责是输入同一份 IR输出同一个 HTML 文档。布局、配色、节点形状、连线路由都由代码决定不交给随机采样或模型猜测。这样带来的好处是可重复同样的系统描述每次渲染结果一致便于 CI 中回归比对。可版本化IR 是纯文本可以放进 Gitdiff 清晰图只是 IR 的「构建产物」。自包含输出是单文件 HTML/SVG内联样式与脚本发给同事双击就能打开不依赖在线服务。编译产物支持交互缩放、拖拽、节点高亮、连线走向展示、点击节点查看详情与溯源信息。这些行为也都由编译器固定生成而不是前端运行时临时拼装。Agent 理解代码 / 系统描述输出类型化 JSON IRSchema 校验 / 补全确定性编译器自包含 HTML / SVG可交互 可溯源图谱5. 可交互设计一张「能交互的图」至少要解决三个问题看得清、走得动、点得开。archify 的交互层围绕节点和边来设计缩放与平移大图不糊局部细节可以放大查看。节点聚焦点击某个服务高亮它关联的所有边弱化无关节点快速看清上下游。连线含义即图边上的label不是装饰而是接口、消息、数据流向等语义标注悬停可见。布局自适应根据节点数量与关系密度选择适合的布局策略避免 100 个节点挤成一团。因为交互行为在编译期就固化进产物所以分享出去的 HTML 不需要后端服务器也就能稳定地复现这些体验。6. 可溯源节点反查源码「可溯源」是 archify 与一般绘图库最值得单拎出来讲的能力。每个节点可以携带source元数据记录它来自哪个仓库、哪个文件、甚至第几行。当读者在图上点击某个节点时产物里的脚本体可以展示该节点对应的代码定位信息若在浏览器环境中可拼接出 GitHub 链接跳转到对应行在开发者本地可跳转到编辑器打开对应文件位置。这恰好补上了「看完图想去读代码」的最后一步图不再是孤立的视觉结果而是一张可以反向索引回代码的地图。对架构评审、新人 onboarding、遗留系统梳理尤其有价值——人们一边看图一边就能定位到真实实现。constir{type:architecture,nodes:[{id:auth,label:Auth Middleware,kind:service,source:{repo:my-app,file:src/middleware/auth.ts,line:7}}],edges:[]};consthtmlcompile(ir);// 自包含 HTML节点可点击并反查源码7. 与 AI 结合Agent 是主编编译器是排版在 archify 的定位里AI 和编译器的分工很清晰Agent 负责「理解」读代码、读文档、读用户描述提取出有哪些系统组件、它们之间怎么调用、数据如何流动然后把理解结果结构化成 IR。编译器负责「渲染」把 IR 变成可交互、可溯源、风格统一的可视化产物。这个分工的价值在于它把模型最容易出错的部分生成图形的文本语法从循环里拿掉。模型只需要产出 JSON这是它最擅长、也最容易被 Schema 约束的任务图形的正确性和美观度则由确定性代码保证。于是 AI 生成架构图这件事就从「碰运气式地写 Mermaid」变成了「可审校、可验证、可自动化」的结构化产出流程。8. 快速上手archify 是 JS 生态项目安装与调用都比较轻量npminstallarchify核心用法是把 IR 交给编译函数得到 HTML 产物import{compile}fromarchify;constir{type:sequence,nodes:[{id:client,label:Browser,kind:client},{id:api,label:API,kind:service},{id:worker,label:Job Worker,kind:queue}],edges:[{from:client,to:api,label:POST /jobs},{from:api,to:worker,label:enqueue}]};consthtmlcompile(ir);生成的结果可以直接写入文件并在浏览器中打开也可以在网页里作为 Iframe 或独立页面嵌入。由于产物自包含部署到静态托管即可无需额外服务。10. 实战从代码仓库生成架构图rom a或missing required property “type”时通常不是随机错误而是 Schema 校验没有通过。关键是看错误里的路径与枚举值node[3].kind说明问题出现在第 3 个节点的kind字段unknown kind则多半是大小写或拼写不符合 IR 规范。先用node和edge 下标收缩到出问题的对象再对照 IR 类型定义修正字段值通常就能从“半张烂图”恢复到可编译状态。节点 source 定位不准的调整方法如果图上节点能生成但点击后跳到了错误文件或错误行优先检查扫描器能否拿到可靠的baseDir / root。source.file最好以仓库根为基准、使用相对路径如果扫描器没有统一路径就可能把同一模块识别成两个节点或指错文件。对于动态导入、路由注册等隐式调用可以让扫描器输出采样到的符号与位置人工确认后再把解析规则收口而不是直接接受自动结果。扫描 include 规则优化建议include不宜直接写**/*否则会把测试、构建产物、Node_modules 都卷进来节点多且杂。更稳的做法是按目录聚焦比如只扫routes/**/*.ts、services/**/*.ts、data/**/*.ts并用exclude排除*.test.ts、*.spec.ts、dist/**、node_modules/**。扫描前可以先加--dry-run输出命中文件清单确认没有漏掉核心模块也没有把噪声文件纳入 IR。编译产物在浏览器中无法交互的排查步骤如果打开 HTML 后只能看到静态图、不能缩放或点击建议按顺序排查确认调用compile时传入了{ interactive: true }否则产物可能退化为静态 SVG。检查输出文件是否为单文件自包含产物内联脚本没有被构建流程、邮件或网盘预览过滤掉。尽量避免直接双击使用file://打开改在项目目录启动静态服务器例如python -m http.server 8080再访问http://localhost:8080/architecture.html。打开浏览器 DevTools 的 Console 面板查看是否有脚本报错根据红色错误定位是资源缺失还是交互层初始化失败。10. 一个更完整的示例订单处理数据流这里用一个 Express 单体应用为例展示如何先用 archify 扫描真实代码仓库得到 IR再把 IR 编译成可交互 HTML。my-express-app/ ├── src/ │ ├── app.ts │ ├── routes/ │ │ ├── orders.ts │ │ └── users.ts │ ├── services/ │ │ ├── orderService.ts │ │ ├── userService.ts │ │ └── paymentService.ts │ └── data/ │ ├── db.ts │ └── redis.ts └── package.json假设 archify 的扫描器会按文件路径与导入调用关系识别节点routes下的文件是入口路由services下的文件是业务服务data下的文件是存储依赖调用关系来自import/require与函数调用。9.1 使用 CLI 扫描并编译# 扫描 src 目录生成类型化 IRnpx archify scan ./src-fexpress-oarchitecture.ir.json# 把 IR 编译为自包含 HTMLnpx archify compile architecture.ir.json-oarchitecture.html执行后终端会输出类似Scanned 12 files, extracted 8 nodes and 8 edges. Wrote architecture.ir.json Wrote architecture.html (23.6 KB)9.2 使用 Node.js API 完成同样的事如果你需要把扫描、IR 清洗、编译串进 CI 或自己的脚本可以用 Node.js APIimport{scanProject,compile}fromarchify;import{writeFile}fromnode:fs/promises;asyncfunctionmain(){// 1. 扫描代码仓库自动提取 service 节点与调用关系constirawaitscanProject(./src,{format:express,include:[routes/**/*.ts,services/**/*.ts,data/**/*.ts]});// 2. 可选打印 IR便于 Code Review 或保存版本console.log(JSON.stringify(ir,null,2));// 3. 确定性地编译为自包含 HTMLconsthtmlcompile(ir,{interactive:true});// 4. 写入本地文件awaitwriteFile(architecture.html,html,utf8);console.log(Generated architecture.html);}main().catch(console.error);9.3 自动生成的 IR 片段上述扫描可能得到这样的中间表示路由、服务、存储被分为不同类型的节点连线标签则保留真实调用语义。{type:architecture,nodes:[{id:app,label:Express App,kind:service,source:{file:src/app.ts,line:1}},{id:routes_orders,label:Order Routes,kind:service,source:{file:src/routes/orders.ts,line:8}},{id:routes_users,label:User Routes,kind:service,source:{file:src/routes/users.ts,line:6}},{id:order_service,label:Order Service,kind:service,source:{file:src/services/orderService.ts,line:12}},{id:user_service,label:User Service,kind:service,source:{file:src/services/userService.ts,line:9}},{id:payment_service,label:Payment Service,kind:service,source:{file:src/services/paymentService.ts,line:5}},{id:db,label:PostgreSQL,kind:storage,source:{file:src/data/db.ts,line:3}},{id:redis,label:Redis,kind:storage,source:{file:src/data/redis.ts,line:2}}],edges:[{from:app,to:routes_orders,label:mount /orders},{from:app,to:routes_users,label:mount /users},{from:routes_orders,to:order_service,label:createOrder},{from:order_service,to:payment_service,label:charge},{from:order_service,to:db,label:SQL},{from:routes_users,to:user_service,label:getUser},{from:user_service,to:db,label:SQL},{from:user_service,to:redis,label:cache}]}这里最关键的是生成的 HTML 中的每个服务节点都带有source信息点击「Order Service」就能直接跳回src/services/orderService.ts:12架构图和真实代码形成闭环。9.4 运行结果说明打开architecture.html后你会得到一张可缩放、可拖拽的架构图节点按类型自动配色点击「Order Service」时会高亮它到Payment Service、PostgreSQL的调用关系并展示源码位置产物是单文件 HTML可以直接提交到 Git 仓库、放到静态站点或发给同事不依赖 archify 服务端。如果扫描结果不够准确通常只需要调整include规则、补几张白名单表或修改少量 IR不需要手工重画整张图。这也正是「扫描/Agent 生成 IR 确定性编译」模式比直接生成图表源码更可靠的地方。11. 一个更完整的示例订单处理数据流下面用一个「下单 → 扣库存 → 发消息」的场景展示如何用 IR 描述数据流并让编译器生成可交互图谱。{type:dataflow,nodes:[{id:web,label:Web 前端,kind:client,source:{file:src/pages/order.tsx,line:12}},{id:order_api,label:订单 API,kind:service,source:{file:src/order/api.ts,line:30}},{id:inventory,label:库存服务,kind:service,source:{file:src/inventory/service.ts,line:58}},{id:mq,label:消息队列,kind:queue,source:{file:infra/broker.yml,line:4}}],edges:[{from:web,to:order_api,label:提交订单},{from:order_api,to:inventory,label:预占库存},{from:inventory,to:mq,label:发布库存扣减事件}]}同样的数据交给编译器就得到一张每个节点都能点回源码的数据流图。团队在评审时看到「库存服务」就能直接跳到对应实现讨论会更聚焦。12. 与 Mermaid / PlantUML / Draw.io 的对比它们不是替代关系而是侧重点不同这里做一个简要对照方案表达方式可交互可溯源布局可控性Mermaid文本 DSL部分点击/链接弱依赖渲染器PlantUML文本 DSL弱弱较强Draw.io手工/XML强弱强但手工archify类型化 JSON IR强原生支持编译器确定Mermaid 和 PlantUML 的优势是输入简单、生态成熟适合快速草图Draw.io 适合人手工精修。archify 的差异化在于「给 AI 生成」这个场景输入是结构化 JSON IR产物是自包含 HTML/SVG并且把源码溯源作为一等能力。它瞄准的不是把图「画得更漂亮」而是把「AI 理解系统 → 生成图谱」这条链路变得可靠、可验证、可追溯。13. 总结archify 的思路值得记录当 AI 开始参与工程可视化时与其让模型去「猜」一套容易出错的图形语法不如把它约束在结构化数据上把渲染交给确定性编译器。于是整条链路变成AI 理解代码或系统描述产出类型化的 JSON IR编译器确定性地编译为自包含 HTML/SVG读者得到一个可交互、可溯源、可分享的架构/时序/数据流图谱。对于需要频繁用 AI 生成架构图、又希望产物稳定可追溯的团队来说这套「IR 确定性编译」的范式比直接生成 Mermaid 截图要实用得多也更接近工程化的长期形态。