企业官网建设流程全解析

“画技术架构图”这件事，几乎每个工程师都绕不过。方案评审要画、技术文档要画、对外分享要画，有时候一天能画好几版。麻烦的不是画本身，而是改图——结构一调整，连线全乱，标注要重新摆，配色又得重来一遍。我在 GitHub 上翻到一个评分相当高的项目推荐：Fireworks Tech Graph。它做的事情很简单：用一句或一段自然语言描述系统，就能自动生成一张可以直接放进文档、甚至打印输出的技术架构图——出版级质量，不是随手涂鸦的草图。

这个项目适合谁？我自己看下来，主要是三类人：需要快速出图的架构师、写技术方案却不想在绘图工具上耗时间的开发者，以及要把复杂系统讲清楚的一线团队。它把“画图”这件事，从手动拖拽变成了自然语言表达，再由模型和布局引擎自动完成。下面我把项目的核心思路、上手流程、描述技巧、常见坑，以及真正适合的场景一次讲透。

1. 这个项目到底做了什么

1.1 自然语言到图表的本质转变

传统画架构图的工作流，是把脑子里已经想清楚的结构，用手或工具翻译成图形。不管用什么工具，都要经过一个物理操作：点击、拖动、对齐、连线。Fireworks Tech Graph 把这层物理操作去掉了，它把“从想法到图形”变成了一次文本生成。

用户输入类似“请帮我画一张电商系统架构图，前端是 React 应用，后端分成订单、支付、库存三个服务，数据库用 MySQL，服务之间通过消息队列异步通信”这样的描述，工具会解析出节点、层级、连接关系、分组边界，然后通过布局引擎自动排布节点位置，生成矢量图。关键是，它生成的不是位图，而是 SVG 这类可缩放格式，所以缩放、嵌入文档、后续编辑都还有余地。

这个想法的价值，不是“AI 会画图了”这么简单，而是把架构表达的最小单位从“画布上的图形”变成了“可复用的文本描述”。文本可以进版本控制，可以用 diff 对比，可以在交流中直接复制。挂在文档里是一张图，放进对话里是一段话。对于经常维护多张架构图的团队来说，这个转变非常实用。

1.2 为什么不是“AI 画一张示意图”

现在很多 AI 生图工具也能根据文字生成图片，但那是给营销海报、插画用的。你让它画一张“架构图”，它常常会画出一张看起来很像架构图、但节点名全是乱码的假图。原因在于，生图模型优化的是“像不像”，而不是“连接关系是否准确”。架构图的价值在于信息结构必须精确，一个箭头画错，整张图就误导人。

Fireworks Tech Graph 的做法更务实：用语言模型做语义解析，再用专业的自动布局引擎做节点排布。也就是说，模型负责“把话拆成实体和关系”，引擎负责“怎么摆才不重叠、不绕线”。这一步拆得值，因为解析错误容易发现，布局正确与否要调整的代价更小，而且每一步都可解释、可干预。

还有个容易被忽略的点：它生成的 SVG 文本本身就带有节点 ID 和连接逻辑，这意味着可以反向编辑、局部修改，而不是像位图一样只能整张重画。对强者频繁改稿的人，这是救命级的功能。

2. 五步快速上手：从安装到第一张图

2.1 环境准备与安装

这个工具以命令行工具为主，也提供了 Python API。安装方式很常规，建议用虚拟环境隔离，避免污染系统环境。我实际操作时用的是 Python 3.10 以上的版本：

python -m venv .venv source .venv/bin/activate pip install fireworks-tech-graph

装完后先跑一次版本检查：

ftg --version

能看到版本号，就说明安装成功了。如果网速不好或依赖安装慢，可以先用国内镜像源再装，比如在 pip 命令里加上-i https://pypi.tuna.tsinghua.edu.cn/simple。这一步没什么技术含量，但很多人会卡在依赖缺失上，所以建议装完先跑一次自检命令，而不是直接上项目案例。

2.2 第一个最小架构图

我建议你不要一上来就画复杂的系统。先用一个最小案例跑通流程，体验一下“文本到图”的完整链路。新建一个文件order.txt，写入：

请画一张订单系统架构图。系统包含三个节点：客户端、订单服务、数据库。客户端通过 HTTP 调用订单服务，订单服务读写数据库。

然后执行：

ftg render order.txt --output order.svg

这句命令的意思是：读取order.txt中的描述，生成order.svg。你会看到一个非常朴素的架构图，三个节点按层次排布，两个箭头表明连接方向。虽然简单，但这是理解后面所有操作的基础——节点、连接、层级，就是这张图的全部原始信息。

2.3 渲染与导出格式

导出格式是下一步要考虑的。命令行支持输出 SVG、PNG 和 PDF。SVG 是最值得推荐的，因为它是矢量格式，放大不糊，还能在代码里继续改。PNG 适合直接贴在文档里，生成时可以通过参数指定分辨率，否则默认像素可能不够高清。PDF 通常用于对外交付或打印。

一个实用的组合是：工作阶段存 SVG，交付阶段导出高清 PNG 或 PDF。如果你需要批量生成，可以在同一个目录下放多个描述文件，用脚本循环调用接口。实际用下来，SVG 是唯一能满足“改了描述还能局部更新”的格式，所以如果条件允许，尽量保留 SVG 源文件。

3. 像写代码一样描述系统

3.1 描述的基本组成

要把自然语言描述写好，先要理解工具在描述里会提取哪些元素。概括起来是四类：

• 节点：系统里的实体，比如服务、组件、数据库、客户端。
• 连接：节点之间的关系，比如调用、读写、发送消息。
• 分组：把相关节点圈在一起的逻辑边界，比如“业务层”“基础设施层”。
• 注释：辅助表达的文字说明，不是实体，但会影响排版。

我刚开始用的时候，以为描述越随意越好，后来发现不是。自然语言生成的图，质量上限由描述质量决定。你描述得模糊，画出来就模糊。就像写需求文档，输入含糊，输出一定含糊。

描述时要注意两点。第一，明确主语和动词，比如“订单服务调用支付服务”比“订单和支付有关系”要清晰得多。第二，明确层级关系，比如“前端调用网关，网关再转发到后端服务”这种带顺序的描述，能帮助布局引擎做出更合理的层次排布。

3.2 一个完整示例

光说规则比较抽象，我拿一个具体的“电商系统架构图”举例。假设我要画一张包含用户端、网关、业务服务和数据存储的架构图，描述可以这样写：

请画一张电商系统架构图。最上层是客户端，包括网页端和手机端。中间层是 API 网关，客户端通过网关访问后端。后端分为四个微服务：会员服务、商品服务、订单服务、支付服务。订单服务需要调用会员服务，支付服务需要调用订单服务。商品服务和订单服务都读写 MySQL 数据库，支付服务使用 Redis 缓存。最下层是基础设施：MySQL、Redis、消息队列。服务之间通过消息队列异步通知事件。

注意我是怎么组织的：从顶层到底层，先列节点，再讲连接，最后交代基础组件。这种“分层叙述 + 明确动词”的风格，生成出来的图通常层次清晰。反观如果写成“画一个电商系统，有客户端、网关、微服务、数据库”，节点间连接全靠猜，出来的图就会是散落一地的方块。

3.3 描述中的常见表达误区

我总结几个反复踩过的坑，你尽量绕开。

• 不要过度使用“相关的”这类模糊词。用“调用”“读写”“订阅”“发送到”等具体动作，布局引擎才能真正理解关系。
• 不要在一段话里堆太多节点。一个描述文件写二十个以上节点，生成时间会增加，布局也容易乱。建议拆成多个子图，或者用“层次”拆分描述。
• 不要忽略“位置”描述。工具支持手动指定方位，比如“把支付服务放在订单服务下方”之类的语句也能理解。善用位置描述，可以省掉大量后期调整。
• 不要把所有说明都塞进图里。长注释会让布局失衡，短文案更适合作为节点标签。

4. 从能用到耐看的调整技巧

4.1 布局与层级控制

自动生成的布局，默认是按描述里出现的先后顺序排列的，但有些系统天然不适合线性排布。比如双向交互很多的系统，默认布局容易出现连线交叉。Fireworks Tech Graph 支持几种布局方向：自上而下、自左向右、自底向上，以及环形布局。

我的经验是，上下层关系明确的系统选自上而下，调用链路长的选自左向右，核心围绕一个总线的系统选环形。这些可以在描述尾部加一句指定，比如“请使用自左向右的布局”。如果你的系统里有大量跨层调用，那么再好的布局引擎也救不回来，应该在描述阶段先把跨层依赖减少，或者把跨层调用单独画一张关系图。

4.2 样式与可读性

出版级的观感，往往不在内容，而在样式。这个工具提供了一套默认样式，但你可以通过自定义样式文件或描述指令来覆盖。我常用的几项调整：

• 配色：给不同层设置不同底色，比如“业务层使用浅蓝色，基础设施层使用浅灰色”，视觉层次立刻出来。
• 字体：指定 SVG 字体，中文建议用系统已有的开源字体，避免最终渲染出现豆腐块。
• 间距：节点边距、分组边距、连线拐角半径，这几个参数决定了图是否透气。太紧显得乱，太松显得信息密度低。
• 线型：实线表示同步调用，虚线表示异步，这个规范如果能在描述里体现，别人看图会轻松很多。

另外，在图上加图例是出版级图很重要的细节。可以加一句“给这张图添加一个图例，说明实线和虚线的含义”，工具会生成对应的标注。图例能省掉大量口头解释，尤其适合把图发给跨团队的人看的时候。

4.3 迭代式生成

我使用这个工具时的工作节奏，不是“一次写完美”，而是快速出第一版，然后反复迭代。具体流程是：

1. 先用一句话生成一张粗糙骨架图，确认结构方向。
2. 逐步补充节点和连接，每补充一轮就让布局引擎重新排一次。
3. 结构与内容稳定后，再调样式、配色、字体。
4. 最后导出高清格式用于交付。

这个顺序很重要。很多人一上来就调样式，结果结构一变，样式全部重来。先定结构，再定样式，是最省力的路径。如果你在开发团队里，还可以把描述文件提交到代码仓库，配一个持续集成任务，每次构建都重新生成架构图，这样文档里的图永远不会和代码脱节——这一招比任何“文档及时更新”的规定都管用。

5. 常见问题与排查实录

5.1 图形乱、重叠、绕线

这是最常遇到的问题。第一次生成出来，节点叠成一团，连线像毛线球。原因一般有三个：节点太多、层级描述不清、布局方向选错。

节点太多时，先尝试拆分场景，比如把系统图拆成“请求链路图”和“数据流图”两张。层级描述不清时，在描述里明确每个节点属于哪一层，比如“商品服务属于业务层”。布局方向选错时，换一种布局再生成一次，往往能解决大多数绕线问题。

如果局部交叉仍然存在，最直接的办法是在描述中调整连接顺序。图形引擎通常会按照定义的顺序布线，先定义的连接往往路径更直。把关键链路放在前面描述，能有效减少交叉。

5.2 中文与特殊字符渲染异常

我用它画中文架构图时，遇到过字体缺失、导出 PNG 后中文变成方块的问题。这通常是字体配置问题，不是工具本身的 bug。解决方法是：在样式配置里指定一个系统已安装的中文字体；如果是服务器环境下渲染，可以把字体文件放在工具可访问的目录里。另外，尽量避免在节点名称里使用过长的中文文本，虽然技术上支持，但过长标签会让自动换行效果变得不可控，看起来反而更乱。

特殊字符方面，尖括号、引号这类字符在部分格式下需要转义。如果你在描述里用到了这些符号，建议先简化标签文案，把特殊说明放到注释字段里，不要直接塞进节点名。

5.3 图越来越大怎么办

很多用户问：系统确实庞大，一张图根本画不下，怎么办。我的建议是接受一个事实：架构图不是越全越好，越全的图越没人看得懂。真正用得上的做法是拆分。

Fireworks Tech Graph 支持多图关联。你可以为每个子系统分别生成一张子图，然后在总图上表现系统边界和子系统之间的调用关系。总图保持在一个屏幕内能看完的复杂度，细节留在子图里。这样总图是导航，子图是详情，读者按需深入，比一张塞满一切的巨图实用得多。

5.4 通用避坑清单

这份清单是我实际排查时最常对照的，多数问题不超过一分钟能定位。

6. 适配场景与边界

6.1 用得上劲的场合

真正让这个工具大放异彩的场景，是那些“图经常要改”的工作流。比如架构评审PPT、技术分享的配图、团队知识库的结构文档、系统重构前后的对比图。传统绘图工具里，改一个节点要重新对齐周边，而这里只需要改一句描述再重新生成。对强变化的场景，这套工作流的效率优势碾压手动绘图。

还有一个被低估的用途：读别人项目的源代码时，可以用它快速画一张模块关系图。先通过分析工具拿到模块依赖数据，转换成自然语言描述，再生成可视化的架构图。相当于给“读代码”这件事配了一个草稿纸，能极大缩短理解陌生系统的时间。我试过用它对一个线上系统做反向梳理，从模块列表到出图，前后不到半小时，比手动画高效得多。

6.2 别硬上的场合

这个工具不适合所有画图需求。如果你的图需要非常精确的像素级控制，比如给某供应商做的接口对接图，连线的每个拐角都有严格要求，那还是用手动绘图工具更合适。如果系统已经庞大到几十上百个节点，指望一句话生成一张准确的总览图，也不现实。工具擅长的是“描述清楚的中小型系统”和“快速迭代的方案草图”，它不是万能的画图替代品。

另外，它生成的图适合展示逻辑关系，不适合承载复杂的视觉设计。如果你的图需要很强的品牌风格、特殊的图形元素、精美的图标，那还得在生成后导入专业图形编辑器里精修。理解工具的能力边界，才不会在关键时刻被它坑一把。

最后再分享一个小技巧：如果你经常画同类架构图，可以维护一个描述模板库，把“电商系统”“监控系统”“数据采集系统”这些常见架构的骨架描述存下来，下次新项目启动直接套模板修改，十分钟就能出初稿。这个习惯帮我很多次，比每次从头描述要快得多。