# flowable-agent

**Repository Path**: tony2y/flowable-agent

## Basic Information

- **Project Name**: flowable-agent
- **Description**: Spring AI + spring-ai-agent-utils + Skill 驱动的 Flowable BPMN 生成器。对话式生成符合 OMG 规范的 BPMN 2.0 XML，支持工具调用、SSE 流式响应、外部 Skill 仓库热加载。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: SpringAI, flowable, flowable-skill, flowable-agent

## README

# Flowable Agent

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

[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.1.0-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![Spring AI](https://img.shields.io/badge/Spring%20AI-2.0.0-blue.svg)](https://spring.io/projects/spring-ai)

---

## 一、项目简介

`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+**
   ```bash
   java -version
   ```

2. **Maven 3.9+**
   ```bash
   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 拉取与构建

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

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

### 5.3 配置模型参数

对应 `application.yaml`：

```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 启动服务

#### 方式一：本地运行

```bash
mvn spring-boot:run
```

#### 方式二：JAR 启动

```bash
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`

**请求体**：

```json
{
  "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）**：

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

**应用端 SSE 消费示例**：

```js
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](https://github.com/tony2y/flowable-skills) | 推荐，CI 拉取用 |
| Gitee  | [https://gitee.com/tony2y/flowable-skills](https://gitee.com/tony2y/flowable-skills)  | 国内网络备选 |


#### 5.6.2 下载 skill 文件

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

```bash
# 选一个平台即可
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 打包

```bash
mvn clean package -DskipTests
```

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

### 6.3 服务部署

```bash
# 启动服务
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](LICENSE) 文件。

---

## 九、致谢

- [Spring AI](https://spring.io/projects/spring-ai) — Spring 官方 AI 框架
- [spring-ai-agent-utils](https://github.com/spring-ai-community) — Skills / Grep / Glob 等 Agent 工具
- [Flowable](https://www.flowable.com/) — BPMN 2.0 流程引擎