AIGC+PlantUML：用自然语言生成技术图表，重构高效文档工作流

1. 项目概述：当AIGC遇上PlantUML，画图这件事彻底变了

作为一名在技术文档和架构设计领域摸爬滚打了十多年的老手，我画过的图比我写过的代码行数可能还要多。从最初用Visio拖拽，到后来用各种在线工具，再到沉迷于代码画图的优雅，我一直在寻找那个“终极”方案。直到最近，我把AIGC（人工智能生成内容）和PlantUML结合了起来，才真正体会到什么叫“高效画图”。这不再是简单的工具叠加，而是一次工作流的彻底重构。

简单来说，这个方案的核心是：你用自然语言描述你想要什么图，AI帮你生成标准的PlantUML代码，然后PlantUML引擎瞬间将其渲染成清晰、规范的图表。它完美解决了几个长期痛点：一是构思与绘制脱节，脑子里有想法，手上画不出来或者画得慢；二是维护困难，图形化工具生成的图，后续修改简直是噩梦；三是风格不统一，团队协作时，十个人能画出十种风格的流程图。现在，你只需要关心“逻辑”本身，剩下的脏活累活，交给AI和代码。

这套方案适合所有需要频繁产出技术图表的人，无论是软件架构师、产品经理、开发工程师，还是技术文档工程师。如果你受够了反复调整框线对齐，厌倦了因图表更新不及时而导致的文档过期，那么接下来的内容，就是你一直在等的“解药”。我们将深入拆解如何搭建这套自动化流水线，并分享那些只有踩过坑才知道的实操细节。

2. 核心思路与方案选型：为什么是AIGC + PlantUML？

在决定采用这个组合之前，我评估过市面上几乎所有主流的画图方案。Visio、Draw.io、Lucidchart这类图形化工具，优点是上手快、所见即所得，但缺点同样明显：效率瓶颈在“手”，修改成本高，难以版本化管理。Mermaid.js这类基于文本的图表工具是一大进步，它用代码定义图表，解决了维护和版本控制的问题。但它的语法依然需要学习和记忆，对于复杂图表，手写代码的脑力负担并不小。

而PlantUML在这个领域堪称“隐藏的王者”。它是一门领域特定语言（DSL），语法极其丰富，支持序列图、用例图、类图、活动图、组件图、部署图、状态图、对象图、定时图，甚至还有思维导图和架构图。它的渲染效果专业、风格统一，并且由于是纯文本，可以完美融入Git进行版本控制，差异对比一目了然。但它的学习曲线，尤其是复杂布局和样式定制，劝退了不少人。

这时，AIGC的价值就凸显出来了。以大语言模型（LLM）为代表的AIGC，最擅长的就是理解自然语言并将其转化为结构化的指令或代码。我们不需要教会AI PlantUML的全部语法，只需要让它学会将我们的设计意图“翻译”成正确的PlantUML代码。这相当于为PlantUML配了一个“理解你想法”的智能助手。

我选择这个组合，基于以下几个核心考量：

1. 关注点分离：人的大脑专注于高层逻辑和设计（做什么），AI负责将逻辑转化为规范语法（怎么做），PlantUML负责最终呈现（做成什么样）。各司其职，效率最大化。
2. 质量与一致性：AI生成的PlantUML代码遵循标准语法，渲染出的图表在样式、间距、字体上天然保持一致，极大提升了文档的专业度。
3. 可迭代性：修改图表不再是重画，而是修改描述或调整生成的代码。你可以对AI说：“把用户模块改成蓝色，并在数据库前面加一个缓存服务器”，它就能给出新的代码。这种交互式的设计过程，流畅得超乎想象。
4. 无缝集成：PlantUML代码可以嵌入Markdown、Confluence、GitLab Wiki等几乎所有文档系统。结合CI/CD，可以实现文档随代码自动更新。

注意：这里说的AIGC，特指能够处理代码和结构化文本的大语言模型，例如GPT-4、Claude 3、DeepSeek等通过API调用的模型，或者是本地部署的Llama、Qwen等开源模型。绝对不涉及任何其他违规或敏感的技术领域。

3. 环境搭建与工具链配置

工欲善其事，必先利其器。这套方案的落地，需要一个稳定、高效的工具链。下面是我经过多次实践后，总结出的最流畅的配置方案。

3.1 PlantUML环境部署

PlantUML本身是一个Java程序，它需要Graphviz来执行布局渲染。因此，第一步是搭建PlantUML的运行环境。

方案一：本地安装（推荐给高频、离线用户）这是最可控的方式。首先，确保你的系统安装了Java运行环境（JRE 8或以上）。然后，从PlantUML官网下载最新的plantuml.jar文件。接着，安装Graphviz。在macOS上，使用brew install graphviz；在Ubuntu/Debian上，使用sudo apt-get install graphviz；Windows用户可以从Graphviz官网下载安装包。

安装完成后，你可以通过命令行测试：java -jar plantuml.jar -tsvg test.txt。如果test.txt里有一段简单的PlantUML代码，这条命令会生成一个SVG图片。

方案二：使用VS Code插件（最适合日常开发）对于绝大多数开发者而言，在VS Code中集成是最佳体验。安装“PlantUML”插件（作者：jebbs）。这个插件会自动在后台处理Java和Graphviz的依赖（或引导你安装），并提供实时预览功能。你新建一个.puml或.plantuml文件，编写代码，右侧就会同步渲染出图表，保存时自动导出图片，无比顺畅。

方案三：在线服务器/ Docker对于团队共享或集成到Web应用，可以搭建PlantUML服务器。官方提供了Docker镜像：docker run -d -p 8080:8080 plantuml/plantuml-server:jetty。之后，你就可以通过向http://your-server:8080发送POST请求（内容为PlantUML代码）来获取图片。这在一些内部Wiki系统中非常有用。

实操心得：个人开发强烈推荐VS Code插件方案，几乎零配置，所见即所得。如果团队需要统一渲染服务（比如用于CI中自动生成文档），则采用Docker部署方案。本地JAR包方式更适合写脚本进行批量处理。

3.2 AIGC工具接入与选择

接下来是关键：让AI理解并生成PlantUML代码。这里有两个主流路径。

路径一：使用通用大语言模型的API这是最灵活、能力最强的方案。你需要一个OpenAI、Anthropic或国内合规且能力相当的AI服务商API Key。核心是构造一个有效的提示词（Prompt）。例如，你可以创建一个这样的系统提示词：

你是一个PlantUML专家，擅长将自然语言描述转化为准确、简洁、规范的PlantUML代码。请遵循以下规则： 1. 只输出PlantUML代码，不要有任何解释。 2. 使用标准的PlantUML语法。 3. 对于时序图，明确参与者（participant）和消息。 4. 对于类图，注意属性和方法的可见性（+、-、#）。 5. 如果描述中有不确定的地方，按照最常见的软件设计模式来补充。

然后，用户的请求可以是：“画一个用户登录的时序图，包括用户、前端、后端服务和数据库。” AI就会返回一段完整的PlantUML代码。你可以用Python、Node.js等写一个简单的脚本，将这段代码发送到本地或远程的PlantUML服务端，生成图片，一气呵成。

路径二：使用集成了AI的PlantUML工具现在已经有一些工具开始原生集成AI。例如，某些在线的PlantUML编辑器增加了“AI生成”按钮，你输入描述，它直接在编辑框里生成代码。这类工具开箱即用，适合快速尝试，但灵活性和定制性不如直接调用API。

路径三：本地模型部署出于数据隐私或网络考虑，你可以在本地部署一个开源的大语言模型（如Qwen、Llama的某个量化版本），并通过其API接口进行类似路径一的调用。这对硬件有一定要求，但数据完全私有。

注意事项：无论选择哪种路径，提示词工程（Prompt Engineering）都是成败关键。最初的AI回复可能不完美，你需要通过迭代优化你的提示词。例如，加入“使用skinparam将所有背景设为白色，箭头为黑色”、“组件图使用rectangle并加上阴影”等样式指令，可以让生成的图表更符合你的审美。

3.3 自动化流水线构思

当基础工具就位后，我们可以构思一个完整的自动化流程，这将把效率提升到另一个维度。

1. 输入：你在IDE或笔记软件中，用自然语言写下图表描述，可能保存在一个Markdown文件里，用特定的标记（如<!-- AI_UML: 描述文字 -->）包裹。
2. 处理：一个本地脚本（比如用Python写的）定期扫描你的项目目录，找到这些标记，提取描述文字。
3. 生成：脚本调用AI API，将描述和优化后的提示词一起发送，获得PlantUML代码。
4. 渲染与替换：脚本调用本地plantuml.jar或HTTP请求PlantUML服务器，将代码渲染成PNG或SVG图片，保存到指定目录。同时，用生成的图片Markdown链接（![描述](图片路径)）替换掉原来的标记。
5. 输出：你的Markdown文件现在包含了实时、准确的图表。结合Git，每次提交都是文档和代码的同步更新。

这套流水线听起来复杂，但用脚本实现起来可能不到100行代码。它实现了“描述即图表”，文档真正成为了“活文档”。

4. 核心应用场景与Prompt实战技巧

有了工具，更重要的是知道怎么用。不同的图表类型，需要不同的描述方式和Prompt技巧。下面我结合几个最常用的场景，分享具体的操作方法和“咒语”。

4.1 场景一：快速生成系统架构图

架构图是技术沟通的基石。以前画一个清晰的架构图，调整布局就要花半天。现在，你可以这样对AI说：

原始描述：“画一个微服务架构图。有一个API网关接收外部请求。网关后面是四个微服务：用户服务、订单服务、商品服务和支付服务。它们都连接到一个共用的Redis缓存集群和一个MySQL主从数据库。所有服务都注册到一个服务中心，并由配置中心管理配置。使用矩形框表示组件，箭头表示依赖关系，给数据库和缓存加上不同的图标。”

优化后的Prompt（给AI的指令）：

请生成PlantUML代码，绘制一个组件图（component diagram）。 要求： 1. 使用 `rectangle` 组件，并加上 `<<组件>>` 的标记。 2. 组件包括：API网关、用户服务、订单服务、商品服务、支付服务、服务中心、配置中心、Redis缓存集群、MySQL数据库。 3. 用箭头表示依赖方向：外部请求 -> API网关。API网关 -> [用户服务， 订单服务， 商品服务， 支付服务]。所有微服务 -> 服务中心。所有微服务 -> 配置中心。所有微服务 --> Redis缓存集群。所有微服务 --> MySQL数据库。 4. 使用 `database` 关键字和 `(缓存)` 标记来区分MySQL和Redis。 5. 整体布局从左到右，逻辑清晰。 只输出PlantUML代码。

AI可能会返回如下代码：

@startuml !define RECT rectangle skinparam componentStyle rectangle rectangle “外部请求” as req rectangle “<<组件>>\nAPI网关” as gateway rectangle “<<组件>>\n用户服务” as user rectangle “<<组件>>\n订单服务” as order rectangle “<<组件>>\n商品服务” as product rectangle “<<组件>>\n支付服务” as payment rectangle “<<组件>>\n服务中心” as registry rectangle “<<组件>>\n配置中心” as config database “MySQL数据库” as db database “(缓存)\nRedis集群” as cache req --> gateway gateway --> user gateway --> order gateway --> product gateway --> payment user --> registry order --> registry product --> registry payment --> registry user --> config order --> config product --> config payment --> config user --> cache order --> cache product --> cache payment --> cache user --> db order --> db product --> db payment --> db @enduml

将这段代码放入PlantUML，一张标准的架构图就生成了。如果对布局不满意，你可以在生成的代码基础上微调，或者给AI更详细的布局指令，如“使用left to right direction布局，将数据库放在最右边”。

4.2 场景二：梳理业务流程时序图

时序图是理解复杂交互的利器。用自然语言描述交互流程，AI能很好地将其转化为带生命线的时序图。

原始描述：“描述一个用户通过手机App扫码登录电脑端网站的过程。用户打开网站，看到二维码。用户用手机App扫描二维码。App向认证服务器请求临时令牌。认证服务器生成令牌并返回。App将令牌和用户信息发送给网站后端。后端验证令牌，并建立会话。最后，网站页面跳转，显示登录成功。”

优化后的Prompt：

请生成PlantUML代码，绘制一个序列图（sequence diagram）。 参与者包括：用户、手机App、电脑网站前端、网站后端、认证服务器。 流程如下： 1. 用户访问网站，前端显示二维码。 2. 用户用App扫描二维码。 3. App向认证服务器请求临时令牌。 4. 认证服务器生成并返回令牌。 5. App将令牌和用户信息发送给网站后端。 6. 后端向认证服务器验证令牌。 7. 认证服务器返回验证结果。 8. 后端建立用户会话，并通知前端登录成功。 9. 前端页面跳转。 请使用`participant`关键字，并注意消息的先后顺序。可以适当使用`note`关键字在关键步骤加注释。 只输出PlantUML代码。

通过这样的Prompt，AI生成的代码结构会非常清晰，你几乎可以直接使用。如果流程有分支（比如扫码失败），可以在描述中加入“如果...否则...”，AI通常也能处理。

4.3 场景三：设计数据库ER图

虽然PlantUML不是专业的ER工具，但其类图语法非常适合快速勾勒表结构关系。

原始描述：“设计一个博客系统的核心ER图。需要有用户表（id，用户名，邮箱）、文章表（id，标题，内容，作者id，分类id）、分类表（id，名称）。用户和文章是一对多关系。文章和分类是多对一关系。再给文章加一个标签表，文章和标签是多对多关系。”

优化后的Prompt：

请使用PlantUML的类图（class diagram）语法，生成一个实体关系图。 实体（用`class`表示）： 1. User：字段包括 id (主键)， username， email。 2. Article：字段包括 id (主键)， title， content， author_id (外键)， category_id (外键)。 3. Category：字段包括 id (主键)， name。 4. Tag：字段包括 id (主键)， tag_name。 关系： - 一个User拥有多篇Article（`User “1” -- “*” Article`）。 - 一篇Article属于一个Category（`Article “*” -- “1” Category`）。 - 一篇Article可以有多个Tag，一个Tag可以属于多篇Article（需要中间关联表`article_tags`，包含article_id和tag_id）。 请清晰地表示出主键、外键和关系基数（1, *）。使用`+`表示public字段。 只输出PlantUML代码。

AI会根据这个描述，生成带有字段和关联关系的类图代码。虽然不如专业ER工具美观，但对于快速设计、沟通和文档化来说，已经完全足够，并且修改起来极其方便。

实操心得：对于AI生成PlantUML，我的经验是“分步描述，逐步细化”。不要试图在第一句Prompt中就描述一个极其复杂的图表。可以先让AI生成主干框架，然后基于输出的代码，再让AI进行“美化：调整一下布局，让线条不要交叉”、“给所有服务加上淡蓝色背景”等局部优化。这种“人机协同”的方式，效果往往比一次性提出复杂要求更好。

5. 高级技巧与样式深度定制

当你能熟练生成基础图表后，下一步就是让图表变得“好看”且“专业”。PlantUML的强大之处在于其丰富的样式定制能力，而AI可以帮助我们管理这些样式。

5.1 使用Skinparam统一全局样式

PlantUML的skinparam指令可以控制几乎所有视觉元素。我们可以创建一个样式“模板”，让AI在生成代码时自动应用。

创建样式模板： 你可以定义一个包含常用样式的代码块，让AI在生成任何图表前先插入它。例如：

‘ 通用样式定义 skinparam backgroundcolor #F5F5F5 skinparam defaultFontName Helvetica skinparam defaultFontSize 12 skinparam shadowing false ‘ 序列图样式 skinparam sequence { ArrowColor #333333 ActorBorderColor #4A90E2 LifeLineBorderColor #CCCCCC ParticipantBackgroundColor #FFFFFF } ‘ 类图/组件图样式 skinparam class { BackgroundColor #E3F2FD BorderColor #1976D2 ArrowColor #1976D2 } skinparam component { BackgroundColor #FFF3E0 BorderColor #FF9800 }

你可以将这个模板保存为一个单独的文件（如common_style.puml），然后在你的主文件中用!include引入。更高级的做法是，在给AI的Prompt中直接加入：“在生成的代码开头，加入以下样式定义：[粘贴上面的样式代码]”。这样，AI生成的所有图表都会遵循统一的视觉规范。

5.2 处理复杂布局与逻辑

有时AI生成的布局可能不理想，比如线条交叉过多。PlantUML提供了一些指令来手动调整。

• 调整方向：在图开头使用left to right direction或top to bottom direction改变整体布局方向。
• 隐藏/显示元素：使用hide/show指令可以控制某些参与者或消息的显示。
• 手动排列：对于组件图，你可以使用[A] -up- [B]或[A] -left- [B]来指定相对位置。虽然不如拖拽直观，但对于固定架构图，一次调整后即可复用。

你可以指示AI：“在生成的代码中，使用left to right direction，并手动排列组件，确保从API网关到微服务的箭头不交叉。” AI会在代码中加入相应的位置指令。

5.3 构建可复用的模块库

在大型项目中，很多组件（如“数据库”、“消息队列”、“网关”）会反复出现。我们可以让AI学习这些“模块”的定义。

方法：创建一个“模块定义库”文件（如modules.puml），里面用!define和!procedure定义好这些组件的画法。

!define RDS(name, color) database name as “<<RDS>>\n”+name #color !procedure Kafka(name) rectangle “<<消息队列>>\n”+name as name #lightblue !endprocedure

然后在Prompt中告诉AI：“请参考我们已有的组件定义（如下），在生成代码时使用这些宏。[粘贴modules.puml内容]”。这样，AI生成的代码会调用RDS(“订单库”, “#FFE”)和Kafka(“日志队列”)，使得所有图表中的同类组件外观完全一致。

6. 集成到日常工作流与CI/CD

让工具融入现有流程，才能产生最大价值。以下是几种常见的集成姿势。

6.1 与文档系统（如Markdown, Confluence）结合

这是最直接的用法。在Markdown中，你可以使用“代码块标记+渲染插件”的方式。

1. 本地写作（VS Code）：安装Markdown Preview Enhanced这类插件，它支持直接渲染Markdown中的PlantUML代码块（语言标记为plantuml）。你写文档时，预览窗格就能实时看到图表。
2. GitLab/GitHub Wiki：两者都支持PlantUML。GitLab需要管理员启用PlantUML集成（使用自建或官方的PlantUML服务器）。启用后，在wiki或issue中，使用````plantuml`代码块即可。
3. Confluence：需要安装PlantUML for Confluence插件。安装后，使用{plantuml}宏包裹你的代码。

自动化流程：你的文档仓库里存放的是.puml源文件。在CI流水线（如GitLab CI）中，可以添加一个生成图片的Job。这个Job遍历所有.puml文件，调用PlantUML Docker容器或命令行生成PNG，并将图片作为产物存档或提交到另一个分支。这样，每次合并请求，都能自动更新文档中的图表。

6.2 与设计评审流程结合

在设计阶段，我们经常需要快速产出和迭代架构图。可以建立一个“设计文档模板”。

1. 模板中预留出图表位置，用特定的占位符表示，例如{{ARCH_DIAGRAM}}。
2. 设计师或架构师在对应的文本段落中，用自然语言描述图表。
3. 运行一个脚本，扫描文档，找到描述，调用AI生成PlantUML代码，再渲染成图片，最后替换占位符。
4. 生成的文档可以直接用于评审。评审者如果对图表有意见，可以直接修改描述文字，再次运行脚本即可更新，极大提升了评审和迭代的效率。

6.3 遇到的典型问题与排查清单

即使方案再完美，实践中也难免会遇到问题。下面是我踩过的一些坑和解决方案。

这套AIGC+PlantUML的方案，我用了大半年，它已经彻底改变了我创作技术文档的方式。从绞尽脑汁思考如何画图，到专注于思考逻辑本身，这种转变带来的效率提升是惊人的。更重要的是，它让图表和文档都变成了“活”的资产，可以随着设计的演进而轻松迭代。如果你也受困于画图的低效，不妨花上一个下午，按照上面的步骤搭建起你自己的环境，从画一个简单的登录时序图开始，你会立刻感受到那种“动动嘴皮子就把图画了”的畅快感。