1. 为什么你需要一个“画图机器人”：告别手动画图的痛苦

我猜很多开发者和技术文档写作者都跟我有一样的烦恼：每次写设计文档，最头疼的部分就是画那张系统架构图。打开绘图工具，拖拽一个个方框、箭头，调整位置、颜色、连线，一两个小时就过去了，而且画出来的图还经常被同事吐槽“不够专业”、“关系不清晰”。更痛苦的是，当代码迭代、架构调整时，你不得不回过头去手动修改那张图，确保文档和代码同步，这简直是个永无止境的体力活。

其实，我们需要的并不是一个更复杂的绘图软件，而是一个能理解代码、并能自动将代码结构可视化的“智能助手”。想象一下，你写完一段后端服务的代码，或者拿到一个开源项目的源码，只需要把代码文件丢给一个工具，它就能自动分析出里面的模块、类、函数之间的调用关系、数据流向，然后生成一张清晰、标准的架构图。这不仅能省下大量时间，更能保证图的准确性和实时性——毕竟，它是直接从代码生成的。

这就是我折腾 Dify 工作流，结合 Kimi-K2 和 Mermaid 想要解决的问题。这不是一个简单的“玩具”，而是一套完整的、可落地的自动化解决方案。它把目前最强的代码理解模型（Kimi-K2）和最强的文本绘图语言（Mermaid）串联起来，构建了一个“上传代码 -> 输出架构图”的自动化流水线。你不需要懂复杂的 Mermaid 语法，甚至不需要知道 Kimi 模型怎么调用，只需要在 Dify 这个可视化界面上，像搭积木一样把几个节点连起来，一个属于你自己的“架构图生成机器人”就诞生了。

我实测下来，这套方案特别适合几种场景：一是个人开发者或小团队快速为项目生成文档配图；二是技术布道者需要为开源项目制作讲解材料；三是在代码评审或架构梳理时，快速可视化现有代码结构，帮助发现设计问题。接下来，我就带你从零开始，手把手搭建这个工作流，让你也能拥有这个提效神器。

2. 核心武器库：认识你的三位“队友”

在开始动手搭建之前，我们得先搞清楚这个自动化流水线里的三位核心“队友”各自扮演什么角色，以及如何把它们请到你的“工作室”里来。这就像组队打游戏，你得先了解每个英雄的技能。

第一位队友：Dify——你的自动化指挥中心。 你可以把 Dify 理解为一个可视化的“胶水”平台。它本身不直接提供 AI 模型或者画图功能，但它擅长把各种不同的 AI 模型、工具、API 像乐高积木一样连接起来，组装成一个完整的工作流。我们不需要写复杂的集成代码，只需要在它的图形化界面上拖拽节点、配置参数，就能定义好“先做什么、后做什么”。在这个项目里，Dify 就是那个负责调度整个流程的“大脑”，它告诉 Kimi 模型何时分析代码，告诉 Mermaid 转换器何时开始画图。

第二位队友：Kimi-K2-Instruct——代码理解与翻译官。 这是整个流程的“智慧核心”。月之暗面（Moonshot）推出的 Kimi-K2-Instruct 模型，在多项代码理解和生成基准测试中表现非常亮眼。它的核心能力是深度理解你提供的编程代码，无论是 Python、Java 还是 Go，它都能识别出其中的关键组件（比如类、函数、数据库连接池、消息队列客户端）、它们之间的依赖关系（比如 A 类调用了 B 类的方法）、以及数据流动的方向。我们的任务就是引导它，将这份理解“翻译”成一种特殊的、机器可读的绘图语言，也就是 Mermaid 语法。所以，给 Kimi-K2 的“指令”（即提示词）设计得是否精准，直接决定了最终生成的架构图质量。

第三位队友：Mermaid——从文本到图形的魔法师。 Mermaid 是一个基于 JavaScript 的图表生成工具，它最大的魅力在于，你用纯文本描述图表逻辑，它就能自动渲染出美观的矢量图。它支持流程图、时序图、类图、甘特图，当然也包括我们需要的系统架构图。它的语法对人类相对友好，比如 A --> B 就表示从 A 到 B 有一个箭头。在这个工作流中，Kimi-K2 模型生成的 Mermaid 代码文本，会交给 Mermaid 转换器这个插件，由它来执行“文本转图形”的魔法，最终输出 PNG、SVG 等格式的图片文件。

把这三位队友的能力串联起来，整个流程就清晰了：Dify 指挥流程，接收你上传的代码文件；调用 Kimi-K2 模型读取代码，并按照要求输出 Mermaid 代码；再将这段代码交给 Mermaid 转换器，生成最终的图片。下面，我们就进入具体的配置和搭建环节。

3. 环境搭建与核心配置：让“队友”就位

搭建任何自动化流程，第一步永远是准备好环境和依赖。这部分我会讲得非常细，包括一些我踩过的坑和注意事项，确保你一次配置成功。

3.1 在 Dify 中接入 Kimi-K2 模型

首先，你需要一个可用的 Dify 服务。你可以使用 Dify 官方提供的云服务，也可以在自己的服务器上部署开源版本。登录后，我们进入模型配置环节。

1. 安装模型提供商插件：在 Dify 左侧菜单找到“插件市场”。在搜索框里输入“Moonshot”或“月之暗面”，找到对应的模型提供商插件（目前最新版本可能是 0.0.6 或更高）。点击“安装”。这个插件的作用是告诉 Dify 平台如何与月之暗面的 API 进行通信。
2. 配置 API 密钥：安装完插件后，进入“设置” -> “模型供应商”。你应该能看到列表里多了“月之暗面”的选项。点击它进行配置。这里最关键的一步是填入你的 Moonshot AI API Key。如果你还没有，需要去月之暗面的官网注册账号并申请。这个 Key 是调用 Kimi 模型的通行证，务必妥善保管。
3. 验证连接：保存 API Key 后，留意“月之暗面”供应商旁边是否出现了一个绿色的小圆点。这个绿点代表 Dify 已经成功连接到了月之暗面的 API 服务。如果没有绿点，请检查网络连通性、API Key 是否正确以及是否有额度余额。

注意：不同模型提供商的计费方式和速率限制不同，建议先在月之暗面平台查看相关文档，了解 Kimi-K2-Instruct 模型的计费标准，避免意外消耗。

3.2 安装 Mermaid 转换器插件

这是将文本代码变成图片的关键工具。同样在“插件市场”中，搜索“Mermaid”。你应该能找到名为“Mermaid Converter”或类似名称的插件，点击安装。安装成功后，在“已安装插件”列表中可以看到它。这个插件内部封装了 Mermaid 的渲染引擎，我们只需要把代码文本传给它，并指定输出格式，它就能返回图片文件。

3.3 创建你的第一个工作流

环境配置好后，我们就可以开始搭建核心的自动化流程了。在 Dify 左侧菜单点击“工作流”，然后选择“创建新工作流”。我建议你给工作流起一个清晰的名字，比如“代码转架构图自动化”。Dify 的工作流界面是一个可视化的画布，左侧是各种可用的节点（称为“组件”），我们可以把它们拖到画布上并连接起来。

至此，你的三位“队友”已经在 Dify 这个指挥中心里集结完毕。接下来，就是设计它们如何协同工作的“作战计划”了。

4. 工作流搭建详解：一步步组装你的自动化流水线

现在来到最核心、也最有意思的部分——像搭积木一样构建整个工作流。我会按照数据流动的顺序，详细讲解每个节点的作用和配置细节。你可以跟着我的步骤，在自己的 Dify 画布上同步操作。

4.1 流程起点：接收用户输入的代码文件

任何工作流都需要一个开始。我们的输入是一段或多段源代码。

1. 从左侧组件面板，找到“开始”节点，拖入画布。它通常是一个圆角矩形，代表工作流的入口。
2. 我们需要让这个开始节点支持文件上传。点击开始节点，在右侧配置面板中，找到“变量”或“输入”设置区域。添加一个变量，变量类型选择“文件”。你可以给这个变量起个直观的名字，比如 code_file。这样，当用户运行这个工作流时，第一步就是上传一个代码文件。
3. 我强烈建议在这里添加一段变量描述，比如“请上传包含源代码的 .txt 或 .md 文件”，这能很好地引导使用者。因为 Dify 工作流对直接上传 .py, .java 等源码文件的支持可能有限，最稳妥的方式是让用户将代码复制到一个纯文本文件（.txt）或 Markdown 文件（.md）中再上传。这是我踩过的第一个坑：直接传 .py 文件可能导致后续节点无法正确读取内容。

4.2 文本提取器：从文件中“读”出代码

上传的文件对于 AI 模型来说还是一个二进制对象，我们需要先把里面的文本内容提取出来。

1. 从左侧面板搜索或找到“文档提取”或“文本提取”相关的节点（在 Dify 中可能叫 “Text Extractor” 或 “Document Loader”），拖到画布上，放在开始节点后面。
2. 用连接线将开始节点的输出（通常是 code_file 变量）指向文本提取器节点的输入。
3. 配置文本提取器节点。一般来说，它需要你指定输入的是哪个文件变量。选择我们上一步创建的 code_file。这个节点会自动处理文件编码，将文件内容转换成纯文本字符串。它的输出就会是一个包含了所有代码的文本块，我们假设这个输出变量叫 code_text。

4.3 灵魂节点：用 Kimi-K2 生成 Mermaid 代码

这是整个工作流的“大脑”，也是最需要精心配置的部分。我们要让 Kimi-K2 模型扮演一个严格的“Mermaid 代码生成器”角色。

1. 从左侧面板拖入一个“LLM”或“大语言模型”节点到画布，放在文本提取器后面。
2. 连接文本提取器的输出（code_text）到 LLM 节点的输入。
3. 关键步骤：选择模型。点击 LLM 节点，在右侧配置面板的模型选择处，找到并选择“Moonshot / Kimi-K2-Instruct”。确保你前面配置的 API Key 是有效的，这里才能正确列出模型。
4. 更关键的步骤：编写系统提示词（System Prompt）。这是指挥 AI 如何行动的核心指令。我的经验是，提示词必须清晰、严格、无歧义。以下是我经过多次调试后效果非常好的一个版本，你可以直接复制使用，并根据需要微调：

你是一个专业的 Mermaid 代码生成器。你的唯一任务是分析用户提供的软件代码，并输出一个完整、正确、可直接渲染的 Mermaid 系统架构图代码块。

请严格遵守以下规则：
1.  仔细分析代码，识别出所有主要的组件（如微服务、数据库、消息队列、缓存、前端应用、API 网关等）、它们之间的调用关系、数据流向和依赖关系。
2.  使用 Mermaid 的 `graph TD`（自上而下图）或 `graph LR`（从左到右图）语法来绘制架构图。优先选择能清晰展示层级关系的布局。
3.  输出的内容必须且只能是一个完整的 Mermaid 代码块。严禁在代码块前后添加任何解释、总结、问候语或额外文字。
4.  代码块必须以 ```mermaid 开头，并以 ``` 结束。
5.  确保生成的 Mermaid 语法是正确的，避免出现无法渲染的错误。

你的输出格式示例：
```mermaid
graph TD
    Client[Web Client] --> APIGateway[API Gateway]
    APIGateway --> UserService[User Service]
    APIGateway --> OrderService[Order Service]
    UserService --> UserDB[(User Database)]
    OrderService --> OrderDB[(Order Database)]
    OrderService --> Cache[Redis Cache]

这段提示词明确了角色、任务、规则和输出格式，能极大地约束模型的行为，让它只输出我们想要的纯净 Mermaid 代码。
5.  **配置用户提示词（User Prompt）**：这里我们只需要简单地引用上游传来的代码文本。通常可以这样写：`请根据以下代码生成系统架构图：{{code_text}}`。这里的 `{{code_text}}` 就是引用文本提取器节点的输出变量，Dify 会在运行时自动替换为实际的代码内容。

### 4.4 图形化呈现：调用 Mermaid 转换器

现在，LLM 节点已经输出了一段 Mermaid 代码文本，我们需要把它变成图片。
1.  从左侧面板的“工具”或“插件”分类下，找到你之前安装的“**Mermaid 转换器**”节点，拖入画布，放在 LLM 节点后面。
2.  连接 LLM 节点的输出（通常是 `answer` 或 `text`）到 Mermaid 转换器节点的输入。
3.  配置 Mermaid 转换器节点：
    *   **输入**：选择上游 LLM 节点传来的文本内容变量。
    *   **输出格式**：根据你的需要选择。`PNG` 和 `JPG` 是通用的位图格式，适合插入文档；`SVG` 是矢量图，无限放大不模糊，最适合技术文档；`PDF` 则方便直接打印。我个人最常用 `SVG`。
    *   **主题**：插件通常提供几种配色主题，如 `default`（默认）、`dark`（暗黑）、`forest`（森林绿）、`neutral`（中性）。你可以根据文档风格选择，`default` 或 `neutral` 通常最保险。
    *   **宽度和高度**：如果不指定，插件会使用默认尺寸或根据图表内容自动调整。如果生成的图太大或太小，可以在这里设置具体的像素值，比如 `width: 1200`。

### 4.5 交付结果：将图片返回给用户

最后一步，我们需要把生成的图片展示给用户。
1.  添加一个“**回复**”或“输出”节点到画布，连接 Mermaid 转换器节点的输出。
2.  配置回复节点。最简单的方式是，在回复内容中直接引用 Mermaid 转换器生成的图片文件变量。在 Dify 中，引用文件变量的语法可能是 `{{#节点ID.output#}}` 或类似形式。你需要选择 Mermaid 转换器节点输出的文件变量。
3.  为了更好的用户体验，你可以在回复节点里加一些固定文本，比如：“已根据您提供的代码生成系统架构图：”。然后下面跟着图片。

至此，一个完整的“代码 -> 架构图”自动化工作流就搭建完成了。从“开始”到“回复”，五个节点环环相扣。你可以点击画布上方的“保存”按钮，然后就可以进行测试了。

## 5. 实战测试与效果优化：让你的工作流更聪明可靠

搭建完成只是第一步，我们需要实际运行它，看看效果如何，并针对可能出现的问题进行优化。这个过程就像调试程序一样，充满了发现和解决的乐趣。

### 5.1 如何进行第一次测试

在 Dify 工作流编辑界面，找到并点击“**预览**”或“测试运行”按钮。这会打开一个测试面板。
1.  **准备测试代码**：找一个结构清晰的代码文件。对于初学者，我建议不要用公司里庞大的单体仓库，而是用一个简单的、模块清晰的示例。比如，一个包含 `app.py` (主应用)、`models.py` (数据模型)、`database.py` (数据库连接) 和 `utils.py` (工具函数) 的小型 Flask 或 FastAPI 项目。将这些文件的代码内容，全部复制到一个新建的 `test_code.txt` 文本文件中。这是我推荐的测试方式，简单有效。
2.  **上传与运行**：在测试面板的文件上传区域，选择你刚创建的 `test_code.txt` 文件，然后点击“运行”或“发送”。
3.  **观察执行过程**：Dify 会高亮显示当前正在执行的节点，你可以清晰地看到数据是如何从一个节点流向下一个节点的。如果某个节点执行失败（变成红色），你可以点击它查看详细的错误信息，这是调试的最重要依据。

### 5.2 常见问题与调试技巧

在实际测试中，你可能会遇到以下几个典型问题，这里分享我的解决经验：

*   **问题一：LLM 节点输出的不是纯净的 Mermaid 代码块。**
    *   **现象**：Mermaid 转换器报错，提示语法错误。你查看 LLM 的输出，发现它在 ````mermaid` 前后加了一些话，比如“好的，这是为您生成的架构图：”。
    *   **解决方案**：这是提示词约束不够严格导致的。回到 LLM 节点的系统提示词配置，强化规则。我上面提供的提示词中“**必须且只能是一个完整的 Mermaid 代码块**”和“**严禁在代码块前后添加任何解释...**”就是为了解决这个问题。如果还出现，可以尝试在提示词最后加上更严厉的指令，例如：“如果你理解了，请直接输出代码块，不要说任何其他话。”

*   **问题二：生成的架构图过于简单或复杂，不符合预期。**
    *   **现象**：图是生成了，但可能只画出了一两个组件，或者把所有的函数、变量都画了出来，显得杂乱无章。
    *   **解决方案**：这需要优化给 AI 的“指令”。在系统提示词中更具体地描述你想要的架构图粒度。例如，你可以增加：“请聚焦于高级别的系统组件和它们之间的交互，忽略函数内部的实现细节。”或者“请识别出代码中的主要类、重要的外部服务（如数据库、缓存）以及它们之间的依赖关系。”

*   **问题三：Mermaid 转换器生成的图片布局不佳。**
    *   **现象**：图片内容正确，但线条交叉严重，布局混乱，可读性差。
    *   **解决方案**：Mermaid 有自己的自动布局算法，但我们可以通过优化 Mermaid 代码来引导它。虽然我们不能直接修改 AI 生成的代码，但可以通过提示词让 AI 生成更规范的代码。例如，在提示词中要求：“在 Mermaid 代码中，使用 `subgraph` 来对相关的组件进行分组，使图表更结构化。” 或者 “合理安排节点顺序，尽量减少连线的交叉。”

### 5.3 效果验证与迭代

当工作流成功运行并输出一张架构图后，你需要从两个维度验证效果：
1.  **准确性验证**：仔细对比生成的架构图和你的源代码。核心的组件是否都识别出来了？组件之间的关系（如调用、依赖）是否正确？数据流方向是否对？这是功能性的核心校验。
2.  **美观性与清晰度验证**：这张图是否一目了然？是否适合放入设计文档或演示文稿？如果觉得样式不好看，可以回到 Mermaid 转换器节点，尝试更换不同的“主题”（Theme）。`dark` 主题在深色背景的文档中很出彩，`forest` 主题则更清新。

经过几轮这样的测试、发现问题、调整提示词或节点配置的迭代，你的工作流会变得越来越“聪明”和可靠。你可以保存多个不同版本的工作流，针对 Python 后端、前端项目、微服务集群等不同场景，使用略微不同的提示词，达到最佳效果。

## 6. 进阶玩法与扩展思路：释放自动化流程的更大潜力

基础的工作流跑通后，我们就可以玩点更花的了。这个“代码转架构图”的流水线其实是一个范式，我们可以举一反三，扩展出更多实用的自动化场景。

### 6.1 从单一文件到整个项目

我们之前处理的是单个代码文件。但对于现代项目，代码往往分散在多个目录和文件中。如何让工作流分析整个项目？
*   **思路一：预处理压缩包**。你可以让用户上传一个项目的 ZIP 压缩包。在 Dify 工作流中，在“开始”节点后，增加一个“文件解压缩”节点（如果 Dify 有此类插件或工具节点），然后将解压后的关键代码文件（如 `*.py`, `*.java`, `*.go`）的内容合并或依次传递给文本提取器。这需要对工作流进行更复杂的设计。
*   **思路二：集成 Git**。更高级的玩法是，让工作流直接连接 Git 仓库。你可以添加一个“HTTP 请求”或“Webhook”节点，当向 Dify 发送一个包含 Git 仓库 URL 的请求时，工作流自动克隆仓库到临时目录，然后遍历分析主要源码文件。这需要一定的脚本编写能力，但实现了真正的“一键分析仓库架构”。

### 6.2 生成多种类型的图表

Mermaid 不仅仅能画系统架构图（`graph`）。我们完全可以复用这个工作流框架，通过修改给 Kimi-K2 模型的提示词，来生成其他类型的图表。
*   **生成序列图（Sequence Diagram）**：非常适合展示 API 调用链或关键业务流程。将系统提示词改为：“你是一个序列图生成器。分析这段代码，生成描述其中关键函数或模块间调用时序的 Mermaid 序列图代码。” 对应的 Mermaid 语法是 `sequenceDiagram`。
*   **生成类图（Class Diagram）**：面向对象代码分析利器。提示词可以改为：“分析这段 Python/Java 代码，提取其中的类、属性、方法以及类之间的继承、组合关系，生成 Mermaid 类图代码。” 语法是 `classDiagram`。
*   **生成流程图（Flowchart）**：用于描述某个复杂函数的内部逻辑。提示词可以聚焦于单个函数：“分析下面这个函数的逻辑，将其转换为 Mermaid 流程图代码。” 语法是 `flowchart TD` 或 `flowchart LR`。

你甚至可以在一个工作流里设置分支，根据用户的输入选择（例如，用户在下拉菜单中选择“架构图”、“序列图”或“类图”），来动态切换发送给 LLM 的提示词，从而实现一个“万能代码图表生成器”。

### 6.3 集成到你的开发流水线中

这个工作流的价值不仅在于手动上传代码，更在于它可以作为自动化流程的一环。
*   **与 CI/CD 集成**：想象一下，每次代码合并到主分支（Merge to Main）时，CI 流水线（如 GitHub Actions, GitLab CI）自动触发这个 Dify 工作流，分析最新代码的架构，生成架构图并保存为制品（Artifact），或者自动更新项目 Wiki 中的架构文档。这保证了架构文档永远与代码同步。
*   **作为代码审查的辅助工具**：在 Pull Request 中，机器人可以自动运行此工作流，生成新旧代码的架构图对比，帮助审查者更直观地理解代码改动对系统结构的影响。

要实现这些，你需要了解如何通过 Dify 提供的 API 来触发工作流。Dify 通常为每个工作流提供一个唯一的 API 端点，你可以用 `curl` 命令或任何编程语言的 HTTP 客户端来调用它，并上传代码文件或 Git 仓库信息。

### 6.4 提示词工程的持续优化

这个工作流的天花板，很大程度上取决于你给 Kimi-K2 模型的提示词写得多好。提示词工程是一个需要持续优化的过程。
*   **提供示例（Few-Shot Learning）**：在系统提示词中，除了规则，还可以直接给出一两个完美的输入输出示例。这能极大地引导模型模仿正确的格式和深度。例如：“当输入一个简单的 Flask 应用代码时，输出应类似于：[这里粘贴一个完美的 Mermaid 架构图代码示例]”。
*   **迭代与标注**：将每次不太满意的输出保存下来，分析是哪里出了问题。是组件识别不全？还是关系画错了？然后有针对性地修改提示词。例如，如果模型总是漏掉数据库连接池，就在提示词中强调：“请特别注意代码中与外部数据存储（如 MySQL, Redis, PostgreSQL）交互的组件。”

通过以上这些扩展思路，你会发现，这个基于 Dify + Kimi-K2 + Mermaid 的组合，其潜力远不止于生成一张静态的架构图。它本质上是一个“代码理解与图形化表达”的通用框架，你可以用它来解决开发流程中许多需要将代码逻辑可视化的痛点。我自己的团队已经将类似的流程用于新员工熟悉项目代码库，效果非常好。看着自己搭建的自动化工具真正派上用场，并且不断改进它，这种成就感正是技术乐趣所在。