Archify 是一个内置技能与命令行工具把一段自然语言描述或一份 Mermaid 代码变成一份可交互、可导出的独立 HTML 技术图覆盖架构、流程、时序、数据流、状态机五大类场景。本文是一篇万字长文教程从工具定位、核心概念讲起覆盖安装验证、三种使用方式、成品效果、进阶玩法与最佳实践全部命令与截图均在本机实测验证。适用对象需要画技术图的开发、测试、产品、架构与运维同学。前置条件通过对话使用时零门槛作为独立 CLI 使用时需会打开命令行。建议按顺序通读也可以按下表直接跳到需要的章节。章节内容适合谁读Archify 是什么定位、解决什么问题、与常见工具对比所有人先建立整体认知五类图与适用场景五类图逐一讲解每类配真实成品图准备选型的人安装与环境要求依赖清单、安装验证、环境排错独立使用 CLI 的同学使用方法对话描述、Mermaid 迁移、CLI 详解三种方式准备上手的所有人使用后是什么效果交付物形态、阅读器能力、导出与质量保障评估产出价值的同学场景拓展与最佳实践团队工作流沉淀、提示词模板、FAQ推动团队落地的同学验证环境archify v2.16.0-dev.0Windows Node.js v22.16.0 Chrome验证日期 2026-09-28。工具升级后请以 doctor 自检输出与随包文档为准。Archify 是什么一句话定位Archify 是一个“描述进、成品图出”的技术图生成器你用自然语言或 Mermaid 说明“有哪些组件、谁和谁有关系、按什么流程走”它负责选型、排版、连线避让、质量校验最终交付一份双击即可打开的交互式 HTML 文件。图形以内联 SVG 绘制不依赖服务器、不依赖外部库、不依赖字体文件任何现代浏览器都能直接打开也可以直接作为附件发进群聊或邮件。它与“画图工具”的本质区别在于分工画图工具让你对每个方框和箭头负责Archify 让你对描述的准确性负责——布局、对齐、间距、配色、图例全部交给渲染器人只回答“图里应该有什么”。它解决什么问题技术图是研发协作中最高频的沟通载体也是维护成本最高的文档资产。四个常见痛点Archify 各有对应解法布局成本高手工拖拽一张 15 节点的架构图一半时间花在对齐和拉线上。Archify 自动计算节点位置、正交连线与端口分配连线自动避让节点、自动桥接并行端口。风格不统一不同人画的图配色、图标、字体各异拼在一份评审 PPT 里像草稿集。Archify 所有产物出自同一套渲染器主题、图例、字体风格天然一致。改图即重画架构调整一个节点牵动所有连线。Archify 的图源于规格描述改描述、重新生成即可旧图作废无心理成本。静态图不可探索截图放进文档读者无法追踪“这个服务依赖谁”。Archify 成品内置关系追踪、搜索、焦点模式等阅读器能力图是“可操作的”。与常见工具对比维度Visio / draw.ioMermaid / PlantUMLArchify产出形式矢量源文件需专用软件编辑文本代码 服务端或插件渲染单文件 HTML浏览器直接打开布局方式全手工拖拽自动布局控制力有限自动布局 语义化几何控制交互能力无导出即静态基本无主题切换、搜索、关系追踪、演示模式质量校验无仅语法校验构图质量 9 项检查 多分辨率适配检测上手成本高需学软件低但要记语法对话方式零语法进阶才碰 JSON版本管理二进制文件难 diff文本可 diff规格 JSON 可 diff交付带 SHA-256 回执简单说临时涂鸦用白板双人快速草图可以用 Mermaid需要交付、评审、留档、汇报的技术图Archify 是更合适的形态。核心设计理念理解四条理念能帮你预判它的行为语义优先连线上的文字是数据而非装饰渲染器宁可挪动布局也要保证关系标签不被遮挡、不被误读。自动路由优先默认不手工指定走线渲染器自动分配连线端口与路径只有在诊断确实报出问题时才做局部几何微调。质量门禁交付前强制通过构图校验showcase 档共 9 项包括连线避让、标签防遮挡、间距、边穿越等不过不交付。单文件交付所有样式、脚本、图形内联在一个 HTML 里复制、发送、归档都不丢内容。五类图与适用场景Archify 用“图类型”组织表达能力五类图对应五种完全不同的阅读意图。选型时不要问“我想画什么图”而要问“读者需要看懂什么”。architecture组件与边界的拓扑回答“系统由什么组成、边界在哪里”。适合 Web 应用架构、微服务全景、云上部署、安全域划分。节点类型覆盖前端、后端、数据库、云服务、安全组件、消息总线与外部系统支持强调与虚线变体可用安全边界把组件分组。上图为官方示例浏览器与移动端经接入层进入业务服务读写数据库边界内的分组一目了然。评审时读者可以点选任意节点追踪上下游这比静态截图的沟通效率高得多。workflow过程、流转与审批门禁回答“事情按什么顺序推进、在哪里分叉、失败走向哪”。适合审批流、CI/CD 流水线、故障响应 runbook、AI Agent 的工具调用编排。流程图强调主路径清晰一条明显的主线贯穿首尾分支就近挂靠。上图为 AI Agent 调用工具的编排示例请求进入后先做参数校验通过则执行工具调用失败走重试分支。这类图放在 runbook 里值班同学照着走即可不需要再问“然后呢”。sequence调用顺序与返回路径回答“谁在什么时刻调用了谁、返回了什么”。适合 API 调用链、缓存读写往返、异步任务轮询、跨服务请求追踪。参与者语义化呈现消息箭头区分同步与异步。时序图最适合讲解“一次请求的完整生命周期”。上图演示缓存未命中场景服务先查缓存未命中后回源数据库并回填缓存最终把结果返回客户端——用表格或文字写清楚这段逻辑需要一段话图上一眼即懂。dataflow数据从哪来、到哪去回答“数据经过哪些加工环节、最终被谁消费”。适合埋点分析管道、ETL/ELT、数据血缘与治理。与 architecture 的区别在于dataflow 关注数据本身的流动与加工而非部署组件。数仓同学用它交代口径流转风控同学用它交代数据血缘。当有人问“这个报表的数从哪来”时把图发过去比开会更有效。lifecycle状态与状态迁移回答“一个对象有哪些状态、什么事件触发迁移、哪些是终态”。适合发布状态流转、订单与工单生命周期、任务重试模型。状态机图的价值在于把“口头约定”显性化。上图把发布的每个阶段、可恢复的失败状态与终态画清楚开发、测试、SRE 对状态的理解从此对齐。选型速查与决策方法拿不准类型时用这个判断链想表达“由什么组成”→ architecture想表达“按什么步骤办”→ workflow想表达“谁调用谁、先来后到”→ sequence想表达“数据怎么加工流动”→ dataflow想表达“状态怎么变”→ lifecycle。也可以把场景描述交给 guide 命令它会返回类型建议与结构参考示例在对话模式下直接问“这个场景该用哪种图”即可。适用边界Archify 适合“表达结构与关系”的技术图不适合自由发散的头脑风暴用画板、手绘风格插画或多人同时在线拖拽编辑的协作场景。它的产物是交付物改图需要回到描述或规格。安装与环境要求需要安装的依赖项Archify 的依赖策略是“能少则少”全部运行代码随技能包自带依赖要求是否必须用途Node.js版本 ≥ 18本文在 v22.16.0 下验证必须运行渲染器与命令行Chrome / Chromium本机已安装的 Chrome 即可自动探测可选仅 visual-check 多分辨率检测与自动截图需要不用该命令可完全不装npm install无需执行无原生模块编译—技能包内开箱即用不需要数据库、不需要联网、不需要任何云服务账号渲染完全在本地完成因此也适合内网受限环境。两种安装形态形态一TRAE 内置技能推荐大多数同学。技能已随 TRAE 安装在本地技能目录对话中直接用自然语言调用即可Agent 会自动完成选型、规格生成、校验、渲染与适配检查的全流程你全程不需要碰命令行。形态二独立 CLI面向需要精细控制的开发同学。技能包本身就是一个 Node.js 命令行程序进入技能目录即可执行全部命令适合批量生产、CI 集成或脚本化流水线。首次验证三步node bin/archify.mjs doctor预期结果输出一份检查清单Node 版本、核心模板、五类渲染器与 Schema 逐项显示 [ok]末行为 Archify is ready.。本机实测 15 项全部通过。node bin/archify.mjs demo .\demo-out预期结果输出目录出现 archify-demo.html命令行同时给出下一步提示。第三步浏览器打开 archify-demo.html切换明暗主题、缩放平移、点节点追踪关系直观感受成品形态。完成这三步环境即就绪。常见环境问题Node 版本过低doctor 第一项会直接报错。升级到 18 及以上 LTS 版本即可。没有 Chrome只有 visual-check 受影响命令会明确返回“跳过”状态而不是失败其余功能完整可用。公司代理环境渲染与校验均为本地行为不需要网络仅 brands capture 捕获官网图标时需要访问对应官网。使用方法三种方式从易到难方式一对话直接描述推荐在 TRAE 中用一句话说清目标即可例如“用 archify 画一个电商下单支付架构图包含前端、订单服务、支付网关、库存服务和数据库突出支付安全边界。”Agent 会自动完成选型、生成规格、9 项构图校验与多分辨率适配检查最后交付 HTML 与验证回执。描述质量直接决定出图质量。一份好的描述包含三要素组件清单有哪些参与方用什么名字名字会原样出现在图上关系与方向谁调用谁、谁读写谁、同步还是异步关系上想标注什么如协议、动作重点与边界哪条链路最重要、哪些组件需要分组或强调。提示词模板架构图“用 archify 画一张 architecture 架构图系统是【某某】包含【组件A、B、C】【A 调用 B】、【B 读写数据库 C】第三方支付放在外部边界重点突出【支付链路】用中文标注。”方式二粘贴 Mermaid 平滑迁移已有 Mermaid 资产不必重画。Archify 读取 Mermaid 的拓扑与语义然后按自有规范重新排版与校验输出更精细的可交互版本。语法映射关系如下Mermaid 语法对应类型迁移要点flowchart / graphworkflow组件地图则用 architecture节点与箭头语义全部保留Mermaid 样式不迁移sequenceDiagramsequence参与者转为语义化角色箭头转为消息stateDiagramlifecycle状态与迁移含义保留可补全重试与终态语义对话模式下直接说“把下面这段 Mermaid 转成 archify 图”并粘贴源码即可。注意迁移的是结构与含义而非样式颜色、线型等装饰信息会被规范化处理这正是风格统一的价值。方式三CLI 命令详解需要精细控制或批量生产时直接使用命令行。全部子命令如下命令用途关键参数guide “场景描述”不确定类型时返回类型建议与参考示例--lang en|zh 切换输出语言validate 类型 规格.json按质量档校验规格并输出诊断--quality standard|showcaserender 类型 规格.json 输出.html渲染规格为 HTML--quality、--repo-rootdeliver 类型 规格.json 输出.html最终交付校验、渲染、生成 SHA-256 回执--open 创建后直接打开compare architecture A.json B.json对比两份架构规格输出对比视图适合方案评审前后对比visual-check 输出.html四档分辨率适配检测并自动截图需本机 Chromebrands “产品名”查询内置品牌图标库brands capture 官网URL 捕获新图标demo / doctor / examples示例生成、环境自检、示例清单首次使用先跑这两个常用的单图生产组合guide 选型 → 编写或生成规格 JSON → validate 校验 → deliver 交付 → visual-check 拿适配报告与截图。首次出图五步走用一句话描述系统或流程列出关键组件、调用关系或状态说明重点指明图类型或让 Archify 通过 guide 推荐类型等待生成规格自动通过 showcase 档 9 项构图校验如有问题会自动修复重试打开交付的 HTML核对组件名称与关系标签是否准确——这是唯一需要人工确认的语义部分需要静态图时在页面内导出 PNG/SVG或把 HTML 直接发进群聊与文档。了解一点图规格 JSON对话模式会替你写好规格但理解规格结构能解锁精确控制。一份规格的核心是四块meta标题、语言locale 支持 zh-CN、质量档、可选的动画与章节配置节点每个组件的稳定 ID、显示名与类型frontend、backend、database、cloud、security、messagebus、external关系起点、终点、方向与语义标签如 HTTPS 调用、异步事件标签是图上唯一承载协议与方向语义的文字分组区域、集群与安全边界用于表达部署位置或信任域。产品的名称、协议、接口路径等专有名词在规格中原样保留渲染器不会翻译或改写它们。使用后是什么效果交付物形态每次交付你得到三样东西成品 HTML单文件内联全部样式与图形、规格快照冻结本次产图的确切输入便于复现以及验证回执规格与成品的 SHA-256、字节数。回执的意义是可追溯半年后评审“当时依据哪版架构图”哈希值说了算。阅读器能力逐项讲成品 HTML 内置一整套阅读器无需任何配置明暗主题一键切换浅色深色切换不影响当前视图位置投屏和夜间阅读两相宜缩放平移滚轮缩放、拖拽平移大图细节不糊搜索与焦点按名字定位节点聚焦模式下无关内容淡出关系追踪选中节点即高亮全部上下游链路讲依赖关系时一击直达语义视图按图层或语义重新组织阅读视角演示模式按讲解节奏推进配合深度链接可以从某个状态直接分享进入。下面两张截图是同一个状态机成品在浅色与深色主题下的对照导出与分享页面内可直接导出五种格式按场景选择PNG/JPEG 适合贴进 PPT 与聊天窗SVG 矢量无损适合印刷与二次编辑WebM 录屏适合演示讲解过程的动态分享。分享 HTML 本体时对方双击即开无需安装任何东西。质量保障机制“出图好看”在 Archify 里是可度量的构图校验showcase 档共 9 项检查覆盖连线避让、标签防遮挡、间距达标、边不穿越无关节点等不通过会给出诊断与修复建议修复后重验适配检测在 1440×900、1600×1000、1920×1080、2048×1320 四档桌面分辨率下验证无横向纵向溢出节点文字投影尺寸不低于可读下限杜绝“出图好看、投屏溢出”视觉回执检测过程自动生成明暗主题截图与检测报告作为交付证据一并留档。需要说明的是校验保证构图质量而关系标签是否与真实系统一致仍需出图人自己核对——工具不替你对语义负责。场景拓展把它变成团队工作流五类基本图之上Archify 提供一组进阶能力配合得当可以沉淀为团队的标准工作流。技术评审与留档把成品 HTML 与规格 JSON 一起归档进设计文档规格是文本进版本库可 diffSHA-256 回执把“图与规格”钉在同一版本。评审后架构有变改描述重新生成旧版本自然留痕。compare 命令还能输出两份架构规格的对比视图方案 A/B 的评审效率显著提升。新人入门导览用章节导览配置最多五段把一张大系统图拆成有讲解顺序的故事线第一段看全景第二段钻交易链路第三段看数据侧。新人拿到一个 HTML像翻手册一样按章阅读比对着一张巨型图发呆友好得多。对外汇报与演示演示模式配合调用流动画trace投屏讲解调用链时镜头随调用推进比来回切静态截图流畅。给管理层汇报系统全景时深色主题加关系追踪效果专业度直接拉满。团队图规范化内置品牌图标库覆盖常见云产品与中间件一个字段即可为节点挂上官方图标库里没有的产品用 brands capture 从官网地址安全捕获。所有成员使用同一套图标与视觉预设团队产出的每张图都长在同一套规范里。可选的三套视觉预设信号流、蓝图、编辑部风格在对话中点名即可启用。部署拓扑与所有权交接启用部署所有权工程档案后图可以标注服务的归属团队与交接边界专为生产部署评审、运维接管、值班交接场景设计。SRE 接手一个新系统时一张标注了 ownership 的部署图是最先要的东西。与代码库联动出图渲染时允许提供代码仓库根目录让图基于仓库真实证据生成而不是凭记忆手写。这对“架构图和代码两张皮”的老问题是一个机制性约束图中的组件名、路径可以由代码背书。数据治理与状态机文档化数据团队用 dataflow 固化血缘与口径流转业务团队用 lifecycle 固化审批、工单、订单的状态约定。这类图一旦成为团队文档的标准件新人提问量会明显下降。与飞书文档生态结合两种用法其一把 visual-check 生成的截图直接插入飞书文档本文的配图就是这样生产的其二把成品 HTML 作为附件上传读者下载后双击即得完整交互体验。规格 JSON 建议放进代码库或文档一并留档。最佳实践与提示词技巧描述完整度决定出图质量实测下来出图返工九成源于描述缺信息。按“组件清点、关系方向、重点边界”三要素检查描述宁可初次描述长一点也不要让渲染器猜。迭代式改图对成品不满意时不要描述“把节点往左挪一点”这类几何指令而是回到语义“订单服务和库存服务分开展示”“把支付网关放进安全边界”。几何交给渲染器语义交给你。常用提示词模板用 archify 画一张 architecture 架构图系统是【名称】 包含【组件A、组件B、组件C】 【A 调用 B】、【B 读写数据库 C】、【C 与消息总线 D 异步通信】 【外部服务】放在外部边界重点突出【某条链路】中文标注。用 archify 画一张 workflow 流程图流程从【提交申请】开始 经过【主管审批、风控审核】两道门禁 任一环节拒绝则退回发起人全部通过后进入【归档】终态中文标注。把下面这段 Mermaid 转成 archify 时序图保留参与者与消息语义 粘贴 sequenceDiagram 源码团队落地建议把规格 JSON 与成品 HTML 一起入库命名带上系统名与日期评审材料中的架构图统一由 Archify 产出减少风格争议新系统立项时先出一张 architecture 全景图作为“活文档”的锚点此后每次架构变更同步再生成。常见问题 FAQQ1图生成后想改一处必须整体重新生成吗是。图是规格的渲染产物改描述或规格后重新生成即可通常只需数秒这正是“改描述不改坐标”设计的价值旧图不会被手工改坏。Q2成品 HTML 离线能用吗能。全部样式与图形内联在单文件中无网络、无服务器、无外部字体依赖内网环境与离线演示都不受影响。Q3中文支持如何节点与关系标签支持任意语言阅读器界面在中文环境下自动使用中文界面文案明暗主题、搜索、导出等能力不受语言影响。Q4节点很多、图很大会不会看不清构图规范建议单图主路径不超过约 12 个主要节点大系统建议按链路拆成多张图再用章节导览串成手册。适配检测会保证投屏分辨率下的可读性下限。Q5没有 Chrome 会怎样仅 visual-check 的适配检测与自动截图不可用明确返回跳过而非失败生成、校验、交付全部功能不受影响。Q6校验通过了图就一定正确吗不一定。9 项校验保证的是构图质量不遮挡、不穿越、间距达标组件与关系是否符合真实系统必须由熟悉系统的人核对关系标签。Q7能否只导出静态图片可以页面内一键导出 PNG/JPEG/WebP/SVG但建议保留 HTML 本体交互能力尤其是关系追踪在评审场景价值很大。Q8Mermaid 迁移后为什么样式变了迁移的是拓扑与语义装饰性样式会被规范化以便纳入统一风格与质量校验。若原样式有语义含义如虚线表示规划中在描述中明确说明即可保留对应语义表达。附录命令速查表下表汇总本文出现过的全部 CLI 命令可直接复制使用。所有命令都在 archify 安装目录下执行本文环境为C:\Users\60472\.agents\skills\archify请替换为你自己的安装路径以下路径中的反斜杠在 Windows 命令行中直接使用即可。命令作用本文示例doctor环境自检Node 版本、Chrome 可用性、目录权限等 15 项node bin/archify.mjs doctor --jsondemo在指定目录生成官方示例图开箱体验node bin/archify.mjs demo D:\archify-outrender从规格 JSON 渲染成品 HTMLquality 控制质量档位node bin/archify.mjs render workflow spec.json 系统流程.html --quality showcasevalidate9 项构图质量校验遮挡、穿越、间距、连通性等node bin/archify.mjs validate 系统流程.htmlvisual-check多分辨率适配检测并自动截图明暗主题替代人工目检node bin/archify.mjs visual-check 系统流程.html --jsondeliver打包交付规格 JSON、成品 HTML、校验回执一并入 zip 并输出 SHA-256node bin/archify.mjs deliver spec.json out.html D:\deliverguide输出构图规范全文写不好描述时先读它node bin/archify.mjs guidebrands品牌图标库查询与捕获为节点挂官方图标node bin/archify.mjs brands list/brands capture 官网 --name 别名compare图类型横向对比拿不准选型时先看输出再决定node bin/archify.mjs compare典型命令链日常单人出图的最短命令链是三条render 生成 → validate 校验 → visual-check 截图留档对外交付再多加一步 deliver。整个链条对规格 JSON 是幂等的同样的输入永远得到同样的产物适合放进持续集成流水线让“文档随代码更新”变成现实。上手建议先拿一个你最熟悉的系统练手写清“有哪些组件、谁调用谁、数据怎么流”生成后重点核对关系标签再体验一次主题切换与关系追踪你就会知道团队下一份设计文档的配图该怎么做。本文基于 archify v2.16.0-dev.0 整理全部命令与截图于 2026-09-28 在 Windows Node.js v22.16.0 环境实测验证工具升级后请以 doctor 自检输出与随包文档为准。