1. 本期目标

上一篇文章分析了 AI Code Mother 的代码生成类型路由机制。我们已经知道，项目在正式生成代码之前，会先判断用户需求适合生成 HTML、MULTI_FILE 还是 VUE_PROJECT。

这一期继续深入项目中更有代表性的部分：

LangGraph4j 工作流编排。

在 AI Code Mother 中，AI 代码生成并不是简单地调用一次大模型接口，而是被拆成多个步骤执行。项目的 langgraph4j 目录中包含 node、state、model、tools 等子目录，以及 CodeGenWorkflow.java、CodeGenConcurrentWorkflow.java、CodeGenSubgraphWorkflow.java、WorkflowApp.java 等工作流相关文件。(GitHub)

本期主要解决几个问题：

1. 为什么 AI 代码生成需要工作流？
2. CodeGenWorkflow 的整体流程是什么？
3. 每个工作流节点分别负责什么？
4. WorkflowContext 在流程中起什么作用？
5. 代码质检失败后为什么会回到代码生成节点？
6. HTML、多文件和 Vue 项目在工作流中有什么差异？
7. 这个工作流设计有什么优点和不足？

---

2. 为什么需要工作流？

如果只是做一个简单 Demo，AI 代码生成可以写成：

用户输入需求
    ↓
调用大模型
    ↓
返回代码

但是 AI Code Mother 的目标不是简单返回一段代码文本，而是希望形成一个完整的代码生成过程。

这个过程可能包括：

收集图片素材
增强用户提示词
判断代码生成类型
生成代码
检查代码质量
必要时重新生成
必要时构建 Vue 项目

如果这些步骤全部堆在一个 Service 方法里，代码会越来越复杂，也很难维护。

所以项目引入了工作流编排。工作流的作用是：

把复杂任务拆成多个节点
明确每个节点的输入和输出
定义节点之间的执行顺序
在关键位置加入条件判断
让失败重试、跳过构建等逻辑更清晰

也就是说，LangGraph4j 在这个项目中的作用，可以理解为：

把 AI 代码生成从“一次模型调用”升级为“多步骤任务流程”。

---

3. 工作流源码位置

主工作流位于：

src/main/java/com/aicode/codemother/langgraph4j/CodeGenWorkflow.java

此外，项目中还有一些扩展工作流文件：

CodeGenConcurrentWorkflow.java
CodeGenSubgraphWorkflow.java
WorkflowApp.java
SimpleWorkflowApp.java
SimpleStatefulWorkflowApp.java

从目录结构看，langgraph4j 下还包含 node、state、model、tools 等子目录，用于存放工作流节点、状态对象、模型对象和工具类。(GitHub)

本期主要分析实际可用的主流程：

CodeGenWorkflow.java

---

4. CodeGenWorkflow 的整体流程

在 CodeGenWorkflow 中，核心方法是：

createWorkflow()

这个方法会创建一个完整的工作流图。源码中可以看到，它向 MessagesStateGraph 中添加了这些节点：

image_collector
prompt_enhancer
router
code_generator
code_quality_check
project_builder

然后通过边把这些节点连接起来。整体流程是：

START
  ↓
image_collector
  ↓
prompt_enhancer
  ↓
router
  ↓
code_generator
  ↓
code_quality_check
  ↓
根据质检结果决定下一步
  ├─ build → project_builder → END
  ├─ skip_build → END
  └─ fail → code_generator

CodeGenWorkflow 源码中确实添加了图片收集、提示词增强、智能路由、代码生成、代码质检、项目构建等节点，并在代码质检节点之后设置了条件边：build 进入项目构建，skip_build 直接结束，fail 回到代码生成节点。(GitHub)

这说明项目的工作流不是单向走到底，而是具备条件分支和失败重试能力。

---

5. 用流程图理解工作流

可以用下面这张文字流程图理解：

用户原始需求
    ↓
图片收集节点
    ↓
提示词增强节点
    ↓
智能路由节点
    ↓
代码生成节点
    ↓
代码质量检查节点
    ↓
是否通过质检？
    ├─ 否 → 回到代码生成节点重新生成
    └─ 是 → 判断是否需要构建
              ├─ HTML / MULTI_FILE → 结束
              └─ VUE_PROJECT → 项目构建 → 结束

这里最关键的是两个判断：

第一，代码质量是否通过。
第二，当前生成类型是否需要构建。

如果代码质检失败，流程不会直接结束，而是回到代码生成节点，让模型根据错误信息重新生成代码。

如果代码质检通过，则继续判断生成类型。如果是 HTML 或 MULTI_FILE，不需要构建，直接结束；如果是 VUE_PROJECT，则进入项目构建节点。

---

6. image_collector：图片收集节点

第一个节点是：

image_collector

对应源码文件是：

ImageCollectorNode.java

这个节点的作用是根据用户原始需求收集图片资源。源码中可以看到，它会先调用 ImageCollectionPlanService 获取图片收集计划，然后并发执行多种图片收集任务，包括内容图片搜索、插画搜索、Mermaid 架构图生成和 Logo 生成，最后把收集到的图片资源保存到 WorkflowContext 中。(GitHub)

可以理解为：

用户需求
    ↓
分析需要哪些图片
    ↓
搜索内容图片
    ↓
搜索插画资源
    ↓
生成架构图
    ↓
生成 Logo
    ↓
保存到上下文

这个节点的意义是：让后续生成的网站不只是纯文字和布局，还可以带有更合适的图片素材。

---

7. prompt_enhancer：提示词增强节点

第二个节点是：

prompt_enhancer

对应源码文件是：

PromptEnhancerNode.java

这个节点负责把原始用户需求和前面收集到的图片资源组合起来，生成一个增强后的 Prompt。源码中可以看到，它会读取 originalPrompt、imageListStr 和 imageList，如果存在图片资源，就在原始提示词后追加“可用素材资源”，并要求模型在生成网站时合理使用这些图片。(GitHub)

也就是说，用户原始输入可能只是：

帮我生成一个科技公司官网。

经过提示词增强后，可能变成：

帮我生成一个科技公司官网。

## 可用素材资源
请在生成网站使用以下图片资源，将这些图片合理地嵌入到网站的相应位置中。
- 内容图片：科技办公场景（图片 URL）
- 插画：AI 数据分析插画（图片 URL）
- Logo：科技风 Logo（图片 URL）

这样做的好处是：

用户不需要自己找图片
模型可以直接利用已有素材
生成页面的视觉内容更丰富

---

8. router：智能路由节点

第三个节点是：

router

对应源码文件是：

RouterNode.java

这个节点的作用是判断代码生成类型。源码中可以看到，它会从 Spring 容器中获取 AiCodeGenTypeRoutingService，然后根据原始提示词调用 routeCodeGenType 方法，得到 CodeGenTypeEnum。如果路由失败，则默认使用 HTML 类型。(GitHub)

也就是说，这个节点完成的是：

用户需求
    ↓
AI 判断生成类型
    ↓
HTML / MULTI_FILE / VUE_PROJECT
    ↓
保存到 WorkflowContext

这一点和第六期讲的代码生成类型路由机制是对应的。

不过这里要注意一个区别：

普通应用创建流程：
在 createApp 时判断 codeGenType，并保存到 app 表。

工作流流程：
在 router 节点中判断 generationType，并保存到 WorkflowContext。

也就是说，工作流内部也有自己的路由步骤，用于后续节点判断该怎么生成和是否构建。

---

9. code_generator：代码生成节点

第四个节点是：

code_generator

对应源码文件是：

CodeGeneratorNode.java

这个节点是真正触发 AI 生成代码的地方。源码中可以看到，它会从上下文中获取增强后的 Prompt 和生成类型，然后通过 AiCodeGeneratorFacade.generateAndSaveCodeStream() 生成并保存代码。生成完成后，它会根据生成类型和 appId 计算生成目录，并写回 WorkflowContext。(GitHub)

流程可以理解为：

读取 enhancedPrompt
    ↓
读取 generationType
    ↓
调用 AiCodeGeneratorFacade
    ↓
生成并保存代码
    ↓
记录 generatedCodeDir

这个节点还有一个很重要的逻辑：如果前一次代码质检失败，它会根据质检结果构造错误修复提示词。

源码中 buildUserMessage 会检查 qualityResult，如果质检失败且存在错误列表，就构造“上次生成的代码存在以下问题，请修复”的提示词，并要求模型重新生成代码。(GitHub)

这意味着工作流支持：

生成代码
    ↓
质检失败
    ↓
提取错误信息
    ↓
重新构造修复提示词
    ↓
再次生成代码

这比简单的一次性代码生成更可靠。

---

10. code_quality_check：代码质量检查节点

第五个节点是：

code_quality_check

对应源码文件是：

CodeQualityCheckNode.java

这个节点负责检查生成出来的代码质量。源码中可以看到，它会读取生成目录下的代码文件，把代码内容拼接起来，然后调用 CodeQualityCheckService 进行质量检查。需要检查的文件扩展名包括 .html、.css、.js、.json、.vue、.ts、.jsx、.tsx 等。(GitHub)

如果找不到可检查的代码文件，它会返回失败结果，并给出错误和建议。如果检查过程中出现异常，代码中目前会把 isValid 设置为 true，也就是异常时直接跳到下一步。(GitHub)

这个节点的输出是：

QualityResult

QualityResult 包含三个核心字段：

isValid：是否通过质检
errors：错误列表
suggestions：改进建议

源码中的 QualityResult 类也定义了这三个字段。(GitHub)

---

11. 质检后的条件分支

代码质检完成后，工作流不会直接进入下一步，而是调用：

routeAfterQualityCheck()

这个方法会根据 QualityResult 判断下一步。

逻辑可以概括为：

如果 qualityResult 为空或 isValid 为 false
    ↓
返回 fail
    ↓
回到 code_generator 重新生成

如果质检通过
    ↓
继续判断是否需要构建

源码中 routeAfterQualityCheck 确实会在质检失败时返回 fail，并把流程路由回 code_generator；质检通过后则调用 routeBuildOrSkip 判断是否需要构建。(GitHub)

这个设计很关键，因为它让工作流形成了一个“生成—检查—修复”的闭环。

code_generator
    ↓
code_quality_check
    ↓
失败？
    ├─ 是 → code_generator
    └─ 否 → build / skip_build

---

12. project_builder：项目构建节点

第六个节点是：

project_builder

对应源码文件是：

ProjectBuilderNode.java

这个节点主要服务于 Vue 工程模式。源码中可以看到，它会获取 generatedCodeDir 和 generationType，然后调用 VueProjectBuilder.buildProject() 执行 Vue 项目构建。如果构建成功，就把结果目录设置为 dist 目录；如果构建失败或异常，则记录错误，并把结果目录回退为原始生成目录。(GitHub)

也就是说：

VUE_PROJECT
    ↓
npm install
    ↓
npm run build
    ↓
dist 目录

而 HTML 和 MULTI_FILE 不需要构建，因此会跳过这个节点。

在 CodeGenWorkflow 中，routeBuildOrSkip 方法会判断当前生成类型。如果是 HTML 或 MULTI_FILE，返回 skip_build；如果是 VUE_PROJECT，返回 build。(GitHub)

---

13. WorkflowContext：工作流状态对象

在整个流程中，各个节点之间不是直接互相传参，而是通过：

WorkflowContext

传递状态。

它可以理解为整个工作流的“上下文对象”。

不同节点会从 WorkflowContext 中读取自己需要的信息，也会把处理结果写回去。例如：

image_collector 写入 imageList
prompt_enhancer 写入 enhancedPrompt
router 写入 generationType
code_generator 写入 generatedCodeDir
code_quality_check 写入 qualityResult
project_builder 写入 buildResultDir

这样每个节点只需要关心自己的输入和输出，不需要直接依赖其他节点。

可以理解为：

WorkflowContext
    ├─ originalPrompt
    ├─ imageList
    ├─ enhancedPrompt
    ├─ generationType
    ├─ generatedCodeDir
    ├─ qualityResult
    └─ buildResultDir

这个设计让工作流节点之间更加解耦。

---

14. 工作流的执行方式

CodeGenWorkflow 中提供了几种执行方式。

14.1 普通执行

普通执行方法是：

executeWorkflow(String originalPrompt)

它会创建工作流，初始化 WorkflowContext，然后通过 workflow.stream(...) 逐步执行每个节点，并在日志中打印每一步的状态。源码中也会通过 getGraph(GraphRepresentation.Type.MERMAID) 输出 Mermaid 格式的工作流图。(GitHub)

这个方法适合后端内部测试或调试工作流。

---

14.2 Flux 流式执行

另一个方法是：

executeWorkflowWithFlux(String originalPrompt)

这个方法会返回 Flux<String>，并在工作流开始、每个步骤完成、工作流完成或错误时输出事件数据。源码中使用虚拟线程执行工作流，并通过 sink.next(...) 推送 workflow_start、step_completed、workflow_completed、workflow_error 等事件。(GitHub)

这种方式适合和响应式接口结合。

---

14.3 SSE 流式执行

还有一个方法是：

executeWorkflowWithSse(String originalPrompt)

它返回 SseEmitter，并通过 sendSseEvent 推送 SSE 事件。源码中同样会发送 workflow_start、step_completed、workflow_completed、workflow_error 等事件。(GitHub)

这说明项目不仅关心最终生成结果，也希望前端能够看到工作流每一步的执行进度。

---

15. 子图工作流：CodeGenSubgraphWorkflow

除了主工作流，项目中还有一个：

CodeGenSubgraphWorkflow.java

这个文件展示了更复杂的子图编排方式。

源码中可以看到，它把内容图片收集、插画收集、架构图生成和 Logo 生成分别拆成子图，然后在主流程中并发执行这些子图，最后通过 image_aggregator 聚合图片结果，再继续执行提示词增强、路由、代码生成、代码质检和项目构建。(GitHub)

可以理解为：

image_plan
    ↓
并发子图
    ├─ content_image_subgraph
    ├─ illustration_subgraph
    ├─ diagram_subgraph
    └─ logo_subgraph
    ↓
image_aggregator
    ↓
prompt_enhancer
    ↓
router
    ↓
code_generator
    ↓
code_quality_check
    ↓
project_builder / END

这个文件更像是工作流能力的增强版本，展示了如何把复杂任务拆成多个子图并进行聚合。

---

16. 这个工作流设计的优点

我认为这个工作流设计有三个明显优点。

16.1 主流程非常清晰

如果不用工作流，图片收集、提示词增强、路由、代码生成、质检、构建这些逻辑可能都会挤在一个 Service 方法里。

现在拆成节点后，流程变得很清楚：

收集素材 → 增强提示词 → 判断类型 → 生成代码 → 质检 → 构建

每个节点只负责一件事。

---

16.2 支持失败重试

代码质检失败后，流程可以回到代码生成节点。

这比简单地报错结束更好，因为它形成了自动修复闭环：

生成
  ↓
检查
  ↓
发现问题
  ↓
带着错误信息重新生成

这对 AI 代码生成非常重要，因为模型第一次输出的代码不一定完全可靠。

---

16.3 方便扩展新节点

如果后续想增加功能，可以直接在工作流中插入新节点。

例如：

安全检查节点
ESLint 检查节点
页面截图节点
可访问性检查节点
性能评分节点
自动部署节点

工作流式设计比硬编码在一个方法中更容易扩展。

---

17. 当前实现中需要注意的问题

虽然工作流设计很有价值，但当前实现也有一些需要注意的地方。

17.1 CodeGeneratorNode 中 appId 目前是固定值

在 CodeGeneratorNode 中，源码里目前使用了固定的：

Long appId = 0L;

代码注释也写着“后续再整合到业务中”。(GitHub)

这说明当前工作流模块和正式的应用业务流程还没有完全打通。

正式业务中，代码生成应该绑定真实的 appId，这样才能和应用、用户、对话历史、部署下载等逻辑一致。

---

17.2 质检异常时默认通过

在 CodeQualityCheckNode 中，如果代码质量检查发生异常，当前逻辑会构造 isValid=true，也就是异常时直接进入下一步。(GitHub)

这种设计可以避免工作流因为质检服务异常而中断，但也有风险：

如果质检服务真的失败
    ↓
有问题的代码可能直接进入构建或结束

后续可以考虑增加更细的异常策略，例如重试一次、标记为 warning，或者在前端提示“质检未完成”。

---

17.3 工作流和 AppService 主流程需要进一步整合

前面几期分析过，正式 AI 代码生成接口主要通过：

AppController
    ↓
AppServiceImpl
    ↓
AiCodeGeneratorFacade

而本期分析的工作流模块更多体现的是一套完整的编排流程。

从当前代码看，工作流已经具备独立执行能力，但和正式应用生成接口之间还可以进一步整合，例如：

让工作流接收真实 appId
让工作流复用当前登录用户信息
让工作流自动保存完整对话历史
让工作流输出最终部署路径

这样工作流才能完全成为正式生成链路的一部分。

---

18. 本期重点理解

这一期最重要的是理解：LangGraph4j 让 AI 代码生成变成了一个可编排的多步骤流程。

可以总结为五点：

第一，CodeGenWorkflow 是项目中的主工作流。
第二，工作流由 image_collector、prompt_enhancer、router、code_generator、code_quality_check、project_builder 等节点组成。
第三，WorkflowContext 用于在节点之间传递状态。
第四，代码质检失败后，流程会回到 code_generator 重新生成。
第五，HTML 和 MULTI_FILE 会跳过构建，VUE_PROJECT 会进入 project_builder 构建。

这个设计体现了 AI 工程中的一个重要思想：

复杂 AI 应用不要只写成一次模型调用，而应该拆成可观察、可控制、可扩展的工作流。

---

19. 我的理解

我认为这个工作流模块是项目中很值得学习的一部分。

它体现了 AI 应用开发从“调用模型”到“组织任务”的变化。

简单 AI 应用关注的是：

怎么把 Prompt 发给模型？

而这个项目进一步关注：

生成前是否需要增强 Prompt？
生成后是否需要检查？
检查失败后是否能自动修复？
不同类型项目是否需要不同后处理？
整个过程能不能流式展示给前端？

这说明 AI Code Mother 不只是一个“模型调用 Demo”，而是尝试把 AI 生成代码做成一个完整工程流程。

不过，目前工作流模块和主业务链路之间还有一定距离，尤其是 appId 固定为 0L 这一点，说明它还需要进一步整合到应用系统中。

---

20. 本期小结

本期主要分析了 AI Code Mother 中的 LangGraph4j 工作流编排机制。

项目通过 CodeGenWorkflow 将 AI 代码生成拆成多个节点：图片收集、提示词增强、智能路由、代码生成、代码质量检查和项目构建。节点之间通过 WorkflowContext 传递状态。代码质量检查通过后，系统会根据代码生成类型决定是否进入构建；如果质检失败，则会回到代码生成节点，并根据错误信息重新生成代码。

这一期可以用一句话总结：

LangGraph4j 的作用，是把 AI 代码生成过程从一次模型调用，组织成一个可控制、可观察、可扩展的多节点工作流。

下一期可以继续分析：

AI Code Mother 项目学习笔记（八）：SSE / Flux 流式输出机制

下一期会重点分析项目为什么要使用流式响应，以及 AI 生成内容和工作流执行进度是如何实时返回给前端的。