Flowable Agent

基于 Spring AI 2.0 + spring-ai-agent-utils Skills 的 Flowable BPMN 2.0 流程图 AI 生成服务。 通过自然语言对话，让大模型直接产出符合 Flowable 规范的 BPMN XML。

---

一、项目简介

flowable-agent 是一个 AI 流程设计助手 后端服务。用户在前端用自然语言描述业务需求（如"做一个请假审批流程，3 天以内部门经理审批，超过 3 天总经理审批"），后端通过大模型自动生成符合 BPMN 2.0 + Flowable 扩展规范 的 XML，并通过 SSE 流式协议实时把 XML 推给前端，应用端可以调用 Bpmn-Modeler(bpmn.js) 的 importXML 完成画布渲染。

核心特性：

• 对话即建模：自然语言 → BPMN XML，零代码拖拽
• SSE 流式输出：思考链、文本、工具调用、最终 XML 实时推送
• SkillsTool 注入规范：BPMN 建模规范以 Skill 形式按需加载，避免一次性塞入全部 prompt
• 多轮会话记忆：基于 MessageChatMemoryAdvisor + conversationId 维持上下文
• 思考链可开关：支持 thinkingEnabled 开关 reasoning_content 增量推送
• 工具回调总线：自定义 @Tool applyProcessXml 在执行时主动推送 xml 事件

---

二、技术栈

类别	技术	用途
Web 框架	Spring Boot 4.1.0	容器、Web MVC、SSE
AI 框架	Spring AI 2.0.0	ChatClient、@Tool、Advisors、ChatMemory
Agent 工具集	spring-ai-agent-utils 0.10.0	SkillsTool、GrepTool、GlobTool、FileSystemTools
LLM 协议	OpenAI Compatible	通过 spring-ai-starter-model-openai 接入 DeepSeek/Qwen/OpenAI 等

spring-ai-agent-utils 提供的 SkillsTool 是关键依赖：它把 classpath:.claude/skills/flowable-bpmn/SKILL.md 暴露为 LLM 可调用的工具，让模型按需读取 BPMN 规范，避免在 system prompt 里塞超长文档。

---

三、版本依赖

3.1 核心依赖

依赖	版本	说明
spring-ai-starter-model-openai	由 BOM 管理	OpenAI 兼容协议 LLM 客户端
spring-ai-agent-utils	0.10.0	Skills / Grep / Glob / FileSystem 工具
JDK	17+	Spring Boot 4.1 要求 JDK 17+
Maven	3.9+	支持 Spring Boot 4.x 插件
LLM	OpenAI / DeepSeek / Qwen / 任何 OpenAI 兼容协议	通过 base-url + api-key 接入

---

四、使用场景

场景	描述
零代码流程设计	业务人员用自然语言描述需求，自动产出 BPMN XML
存量流程改造	上传现有 BPMN，让 AI 按指令调整节点、网关、扩展属性
流程脚手架生成	快速产出可执行的流程骨架，工程师再二次微调
学习 / 培训	给定的业务需求自动产出规范 BPMN，作为学习参考
校验闭环	XML 校验失败时 AI 根据错误信息自动修复并重新提交

---

五、使用说明

5.1 环境准备

1. JDK 17+

   java -version

2. Maven 3.9+

   mvn -version

3. OpenAI 兼容协议的 LLM 接入信息

   • AI_API_KEY：API 密钥
   • AI_BASE_URL：服务地址（例：https://api.deepseek.com/v1）
   • AI_MODEL：模型名（例：deepseek-reasoner、qwen-plus、gpt-4o）

5.2 拉取与构建

git clone <repository-url>
cd flowable-agent
mvn clean package -DskipTests

构建产物：target/flowable-agent-0.0.1.jar

5.3 配置模型参数

对应 application.yaml：

spring:
  ai:
    openai:
      api-key: ${AI_API_KEY}
      base-url: ${AI_BASE_URL}
      chat:
        model: ${AI_MODEL}
        timeout: 1H
        temperature: 0.1

5.4 启动服务

方式一：本地运行

mvn spring-boot:run

方式二：JAR 启动

java -jar target/flowable-agent-0.0.1.jar

启动成功后控制台日志：

Started FlowableAiApplication in 3.x seconds

5.5 API 使用

5.5.1 SSE 流式对话

端点：POST /flowable/ai/chat/stream Content-Type：application/json 响应：text/event-stream

请求体：

{
  "message": "做一个请假审批流程：3 天以内部门经理审批，超过 3 天总经理审批",
  "conversationId": "conv_abc123",
  "thinkingEnabled": true
}

字段	类型	必填	说明
message	string	是	用户需求描述
conversationId	string	否	会话 ID；不传则后端自动生成 conv_xxxx
thinkingEnabled	boolean	否	是否启用深度思考，默认 false
modelId	long	否	模型 ID（预留，当前未启用）

SSE 事件类型（data: {json}\n\n）：

type	字段	触发时机
thinking	thinking	模型推理过程增量（仅 thinkingEnabled=true）
text	content	LLM 可见文本增量
tool_start	toolName, toolArgs	工具开始调用
tool_end	toolName, toolResult	工具执行完成
xml	xml	AI 生成的完整 BPMN XML
error	error	异常信息
done	done=true	流结束，前端关闭连接

示例调用（curl）：

curl -N -X POST http://localhost:8080/flowable/ai/chat/stream \
  -H "Content-Type: application/json" \
  -d '{
    "message": "做一个请假审批流程：3 天以内部门经理审批，超过 3 天总经理审批",
    "thinkingEnabled": true
  }'

应用端 SSE 消费示例：

const es = new fetchEventSource('/flowable/ai/chat/stream', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: '...', thinkingEnabled: true })
});

es.onmessage = (e) => {
  const event = JSON.parse(e.data);
  switch (event.type) {
    case 'thinking': renderThinking(event.thinking); break;
    case 'text':     renderText(event.content); break;
    case 'xml':      bpmnViewer.importXML(event.xml); break;
    case 'done':     es.close(); break;
  }
};

5.6 Skill 扩展（外部仓库依赖）

重要说明：所需的 BPMN 建模规范 skill 必须从下述官方仓库下载并放置到 classpath 根目录的 .claude/skills/flowable-bpmn/ 下。

skill 仓库与本项目 同时在 GitHub / Gitee 双平台发布，使用前请任选一个平台 clone。

5.6.1 Skill 仓库地址

平台	仓库 URL	用途
GitHub	https://github.com/tony2y/flowable-skills	推荐，CI 拉取用
Gitee	https://gitee.com/tony2y/flowable-skills	国内网络备选

5.6.2 下载 skill 文件

git clone（推荐，便于后续升级）

# 选一个平台即可
git clone https://github.com/tony2y/flowable-skills.git
# 或 Gitee 镜像
# git clone https://gitee.com/tony2y/flowable-skills.git

5.6.3 放置到 resources

将 skill 文件放置到 resources 目录的 `.claude/skills/flowable-bpmn/` 目录下。

---

5.6.4 必要的文件结构

放置完成后，目标目录必须包含以下文件：

src/main/resources/.claude/skills/flowable-bpmn/
├── SKILL.md                       # 必需：总入口
└── references/                    # 必需：参考文件目录
    ├── xxx.md                     # 参考文件

六、测试部署

6.1 测试

进入 `AiChatServiceTest.java` 文件运行测试

6.2 打包

mvn clean package -DskipTests

产物：target/flowable-agent-0.0.1.jar

6.3 服务部署

# 启动服务
nohup java -jar flowable-agent-0.0.1.jar > app.log 2>&1 &

---

七、目录结构

flowable-agent/
├── pom.xml
├── README.md
├── LICENSE
└── src/
    ├── main/
    │   ├── java/com/tony/flowable/ai/
    │   │   ├── FlowableAiApplication.java        # 启动类
    │   │   ├── config/
    │   │   │   └── AiChatConfig.java             # ChatClient / SkillsTool 配置
    │   │   ├── controller/
    │   │   │   └── AiChatController.java         # SSE 端点
    │   │   ├── service/
    │   │   │   ├── AiChatService.java            # 流式对话主服务
    │   │   │   └── BpmnToolService.java          # @Tool applyProcessXml
    │   │   └── model/
    │   │       ├── AiChatRequest.java
    │   │       ├── AiChatEvent.java
    │   │       └── AiChatEventType.java
    │   └── resources/
    │       ├── application.yaml
    │       └── .claude/skills/flowable-bpmn/     # BPMN 建模规范 Skill
    └── test/
        └── java/com/tony/flowable/ai/
            └── service/
                └── AiChatServiceTest.java

---

八、协议

本项目基于 MIT License 开源，详见 LICENSE 文件。

---

九、致谢

• Spring AI — Spring 官方 AI 框架
• spring-ai-agent-utils — Skills / Grep / Glob 等 Agent 工具
• Flowable — BPMN 2.0 流程引擎