liteFlow/CLAUDE.md

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指引。

概述

LiteFlow（v2.16.0）是一个轻量级规则引擎框架，用于复杂的组件化业务编排。它通过 DSL 驱动工作流，支持热重载和 11 种脚本语言。项目面向 Java 8+（最高支持到 JDK 25），拥有 2000+ 测试用例。

官方文档：https://liteflow.cc/pages/5816c5/

命令

构建

# 构建整个项目（模块集由 JDK 版本自动选择 —— 见下方说明）
mvn clean package -DskipTests

# 带测试构建
mvn clean package

# 构建指定模块
mvn clean package -DskipTests -pl liteflow-core

# 发布生产模块（手动选择 profile，不会自动激活）
mvn clean package -DskipTests -P release-on-8     # JDK 8 发布产物
mvn clean package -DskipTests -P release-on-17     # react-agent + spring-boot4-starter

JDK 驱动的模块选择（重要）： 根 pom.xml 中没有顶层的 <modules> 块 —— 构建的模块列表完全由按 JDK 激活的 profile 提供：

• compile-8-to-16（在 JDK [1.8,17) 上激活）：core、scripts、rules、spring-boot-starter、spring、solon、testcase-el、el-builder、benchmark。
• compile-17+（在 JDK [17,) 上激活）：以上全部，外加 liteflow-react-agent 和 liteflow-spring-boot4-starter。

因此 liteflow-react-agent 和 liteflow-spring-boot4-starter 只有在 JDK 17+ 上构建时才会被纳入。这两个模块以 maven.compiler.target=17 编译，但根 pom 注释指出 agentscope-java（react-agent 背后的引擎）运行时需要 Java 21+ —— 本仓库当前的开发 JDK 为 21。release-on-8 / release-on-17 这两个 profile 没有 <activation>，必须用 -P 手动选择。

运行测试

# 运行所有测试
mvn test

# 运行指定模块的测试（liteflow-testcase-el/ 下有 30+ 个测试模块）
mvn test -pl liteflow-testcase-el/liteflow-testcase-el-springboot

# 运行单个测试类
mvn test -pl liteflow-core -Dtest=FlowExecutorTest

# 运行指定的测试方法
mvn test -pl liteflow-core -Dtest=FlowExecutorTest#testExecute

其他命令

# 依赖树
mvn dependency:tree

# 查看模块结构
ls liteflow-*/pom.xml

高层架构

核心执行模型

FlowExecutor → Chain → Condition Tree（条件树） → Node Components（节点组件）

1. FlowExecutor：执行工作流的入口（execute2Resp(chainId, param)）
2. FlowBus：所有 chain 和 node 的中央元数据注册中心（线程安全，支持热重载）
3. Chain：由 EL 表达式组成的命名工作流，编译为一棵 Condition 树
4. Slot/DataBus：基于 slot 池的线程安全上下文管理（slotSize 可配置）
5. NodeComponent：所有业务逻辑组件的基类

关键架构模式

1. 两阶段解析

为处理循环依赖，chain 的构建分两个阶段进行：

• 阶段 1：注册 chain ID（创建占位 chain）
• 阶段 2：通过 EL 解析构建完整的条件树

2. EL 表达式语言

使用 QLExpress 解析声明式工作流。示例算子：

• THEN(a, b, c)：顺序执行
• WHEN(a, b, c)：并行执行（异步）
• IF(condition, trueNode, falseNode)：条件分支
• SWITCH(selector).to(a, b, c)：多路分支
• FOR(count).DO(loop)：固定次数循环
• WHILE(condition).DO(loop)：条件循环
• ITERATOR(iterator).DO(loop)：迭代器循环
• RETRY(node).times(3).forException(Ex.class)：重试机制
• CATCH(node).DO(handler)：异常处理
• TIMEOUT(node).time(1000)：执行超时（毫秒）
• PRE(a, b)：前置条件（始终在 chain 之前执行，出错也会执行）
• FINALLY(a, b)：finally 条件（始终在 chain 之后执行）
• AND(a, b)、OR(a, b)、NOT(a)：用于 IF 条件的布尔逻辑
• node.tag("t")、.data("k","v")、.id("id")：节点级修饰符

规则在 XML/JSON/YML 中定义：

<chain name="myChain">
    THEN(a, WHEN(b, c).maxWaitSeconds(5), IF(e, f, g));
</chain>

3. 组件类型

均继承 NodeComponent，但具有专门的行为：

• NodeComponent：标准同步组件（process() 方法）
• NodeBooleanComponent：为 IF 条件返回 boolean（processBoolean()）
• NodeSwitchComponent：为 SWITCH 路由返回 string（processSwitch()）
• NodeIteratorComponent：为 ITERATOR 结构提供迭代逻辑
• NodeForComponent：控制 FOR 循环行为
• ScriptComponent：基于脚本的组件（Groovy、JS、Python 等）

声明式组件模式：任何 Spring bean 都可以在不继承基类的情况下成为组件，方式是使用 @LiteflowCmpDefine（类级别，指定 NodeTypeEnum）和 @LiteflowMethod（方法级别，映射到 LiteFlowMethodEnum）。这样可以摆脱类继承层级的约束。

组件生命周期钩子（在 NodeComponent 子类中覆写，或通过 @LiteflowMethod 实现）：

• isAccess() – 执行前的准入检查；返回 false 则跳过
• beforeProcess() / afterProcess() – 每个组件的前/后置钩子
• onSuccess() / onError() – 结果回调
• isContinueOnError() – 当该节点失败时 WHEN 是否继续
• isEnd() – 标记该节点之后应停止 chain
• rollback() – 失败时按逆序调用

@FallbackCmp：标注一个兜底组件，当主组件不存在或抛异常时启用。

4. 基于 Slot 的上下文

线程安全的执行上下文：

• DataBus.offerSlot(chainId) 从池中获取一个 slot
• Slot 包含执行元数据、上下文 bean 和步骤跟踪
• DataBus.releaseSlot(slotIndex) 将 slot 归还到池
• 池大小通过 slotSize 属性配置

5. 解析模式策略

三种模式（ParseModeEnum）：

• PARSE_ALL_ON_START：启动时解析所有 chain（默认）
• PARSE_ONE_ON_FIRST_EXEC：每个 chain 在首次使用时惰性解析（启动更快）
• PARSE_ALL_ON_FIRST_EXEC：在任意 chain 首次执行时解析全部 chain

模块结构

核心模块

• liteflow-core：核心引擎（FlowExecutor、FlowBus、DataBus、Slot、Condition 系统、组件模型）
• liteflow-el-builder：基于 QLExpress 的编程式 chain 构建器 API

规则源插件（liteflow-rule-plugin/ 下 6 种实现）

• liteflow-rule-zk：ZooKeeper 配置源
• liteflow-rule-sql：SQL 数据库配置源
• liteflow-rule-nacos：Nacos 配置中心
• liteflow-rule-etcd：etcd 配置源
• liteflow-rule-apollo：Apollo 配置中心
• liteflow-rule-redis：Redis 配置源

脚本插件（liteflow-script-plugin/ 下 11 种语言）

• liteflow-script-groovy：Groovy 脚本
• liteflow-script-javascript：Rhino JavaScript（JSR223）
• liteflow-script-graaljs：GraalVM JavaScript
• liteflow-script-qlexpress：阿里 QLExpress
• liteflow-script-python：Jython（JVM 上的 Python）
• liteflow-script-lua：LuaJ
• liteflow-script-aviator：Aviator 表达式语言
• liteflow-script-java：Janino（Java 编译器）
• liteflow-script-javax：JSR223 标准 Java 编译器
• liteflow-script-javax-pro：基于 Liquor 的 Java 编译器（增强版）
• liteflow-script-kotlin：Kotlin 脚本

框架集成

• liteflow-spring：Spring 框架集成（组件扫描、bean 生命周期、AOP）
• liteflow-spring-boot-starter：Spring Boot 2/3 自动配置，使用 @ConfigurationProperties
• liteflow-spring-boot4-starter：Spring Boot 4 starter（仅 JDK 17+ —— 在 compile-17+ profile 下构建）
• liteflow-solon-plugin：Solon 框架集成（Spring 的轻量替代方案）

ReAct Agent（liteflow-react-agent/，仅 JDK 17+）

让一个 LLM ReAct agent（由 agentscope-java 驱动）作为普通 LiteFlow 节点编排进 EL 链路。这是一个聚合模块，包含一个 core 模块 + 每个模型供应商各一个模块：

• liteflow-react-agent-core：ReActAgentComponent（一个 process() 为 final 的 NodeComponent，通过 model()、systemPrompt()、userPrompt()、tools()、handleReply() 等受保护钩子定制行为）、ModelSpec 凭据/模型抽象、conversation/agentKey 会话模型（AgentSessionManager）、可插拔的 memory 持久化（通过 AgentSessionFactory SPI 支持 JVM/NONE/LOCAL_FILE/REDIS/MYSQL）、桥接为 LiteFlow FlowEvent 的流式事件、workspace 文件工具，以及受管 shell 工具。
• liteflow-react-agent-openai / -anthropic / -gemini / -dashscope：各供应商的入口类（如 OpenAI、DeepSeek、Kimi、Anthropic、Gemini、DashScope），返回对应供应商的 ModelSpec 子类型。业务应用通常只依赖其中一个供应商模块（每个都会传递依赖 -core）。

两层标识：conversationId（业务/对话维度，决定 workspace 子目录，整条 chain 内一致）和 agentKey（组件维度，默认取 nodeId，隔离各 agent 的 memory）。完整使用指南：docs/liteflow-react-agent-guide.md —— 修改 agent 行为前请查阅它，不要在此处复制其配置表格。

测试基础设施

liteflow-testcase-el/ 下有 30+ 个测试模块，按以下维度组织：

1. 框架：springboot、springnative、solon、nospring
2. 配置源：zk、nacos、etcd、apollo、redis、sql
3. 脚本：每种语言一个模块 + 多语言混合场景
4. 特性：builder、declare、routechain、monitoring、timeout 等

测试范式：

@SpringBootTest
@TestPropertySource(value = "classpath:/application.properties")
public class MyTest {
    @Resource private FlowExecutor flowExecutor;

    @Test
    public void test() {
        LiteflowResponse response = flowExecutor.execute2Resp("chainId", "arg");
        Assertions.assertTrue(response.isSuccess());
    }
}

重要设计模式

用于扩展的 SPI 模式

广泛用于：

• ContextAware：框架抽象（Spring vs 非 Spring）
• PathContentParser：自定义文件路径解析
• CmpAroundAspect：全局组件生命周期钩子
• DeclComponentParser：声明式组件解析
• 各语言的脚本执行器

生命周期钩子

多个扩展点：

• PostProcessChainBuildLifeCycle：chain 构建前/后
• PostProcessNodeBuildLifeCycle：node 构建前/后
• PostProcessChainExecuteLifeCycle：chain 执行前/后
• PostProcessFlowExecuteLifeCycle：flow 执行前/后

回滚机制

组件实现 rollback() 以在失败时自动回滚（通过 executeSteps deque 按逆序执行）。

热重载支持

• MonitorFile 监听规则文件变化
• reloadRule() 无需重启即可刷新
• Copy-on-write 集合（除非 fastLoad=true）防止并发修改

元数据缓存

• FlowBus 使用 CopyOnWriteHashMap（或在 fastLoad 下使用普通 HashMap）
• EL 的 MD5 缓存以复用表达式
• chain 缓存可配置（chainCacheEnabled、chainCacheCapacity）

关键配置（LiteflowConfig）

• ruleSource：规则文件位置（支持 XML、JSON、YML）
• parseMode：解析策略（影响启动性能）
• slotSize：上下文 slot 池大小
• enableMonitorFile：规则文件热重载
• supportMultipleType：混用 XML/JSON/YML 规则
• whenMaxWaitTime：WHEN 并行执行的超时时间
• fastLoad：关闭 CopyOnWrite 以加快启动
• enableVirtualThread：使用虚拟线程（JDK 21+）

关键文件位置

• 核心引擎：liteflow-core/src/main/java/com/yomahub/liteflow/flow/
• FlowExecutor：liteflow-core/src/main/java/com/yomahub/liteflow/core/FlowExecutor.java
• FlowBus：liteflow-core/src/main/java/com/yomahub/liteflow/flow/FlowBus.java
• 组件基类：liteflow-core/src/main/java/com/yomahub/liteflow/core/NodeComponent.java
• Condition 系统：liteflow-core/src/main/java/com/yomahub/liteflow/flow/element/condition/
• EL 解析器：liteflow-core/src/main/java/com/yomahub/liteflow/parser/el/

重要约定

• 命名：组件以 nodeId 标识，chain 以 chainId 标识
• 线程安全：大量使用 ThreadLocal 和并发集合
• 快速失败：解析期校验，并给出详细错误信息
• 流式 API：chain 构建采用 builder 模式（EL builder）
• 命名空间：chain 可组织进命名空间
• 版本管理：通过 flatten-maven-plugin 使用 ${revision} 占位符（当前 2.16.0）