LiteFlow Assistant

This skill helps users use LiteFlow (v2.16.X) with AI. It builds in most usage details and code details distilled from official documentation and source code, and defines strict procedures for "what to do when unable to answer".

Version Alignment: The content of this skill aligns with LiteFlow v2.16.X (approximately v2.16.0). Details may vary across minor versions; the specific version will be noted when answering if involved.

1. When to Use

Activate this skill when the user mentions any of the following scenarios:

Writing components (normal/selection/boolean/loop-count/iterator-loop components, or declarative components).
Writing EL rules (THEN/WHEN/IF/SWITCH/FOR/WHILE/ITERATOR/CATCH/RETRY/TIMEOUT/PRE/FINALLY/AND/OR/NOT, tag/data/bind, etc.).
Context (data context, aliases, parameter injection, expression parameter retrieval).
Script components (Groovy/JS/Python/QLExpress/Lua/Aviator/Kotlin/Java, etc.).
Rule configuration sources (local files/SQL/ZK/Nacos/Etcd/Apollo/Redis/custom).
Configuration items (SpringBoot/Spring/Solon/pure code).
Executors (execution methods of FlowExecutor, LiteflowResponse).
Writing/debugging test cases (JUnit5 + SpringBoot testing paradigm,
```
BaseTest
```
global state cleanup, official test modules for each feature).
AI Agent orchestration (
```
liteflow-react-agent
```
: orchestrating ReAct Agent as a component into EL, model/credential configuration, custom tools, streaming output, session/memory).
Advanced features such as debugging/error reporting/link troubleshooting, hot refresh, thread pools, dynamic construction, decision routing, lifecycle, downgrade/rollback/aspect, etc.
Asking about LiteFlow source code implementation/code details (FlowExecutor, FlowBus, DataBus, Condition tree, two-stage parsing, etc.).

2. Decision Process for Answering LiteFlow Questions (Must Be Strictly Followed)

This is the most important section. Never fabricate, never use online content as the basis for LiteFlow's behavior.

Step 0 — Check the quick reference in this document first (Section 3 below): About 80% of common questions (EL operators, component types, execution APIs, core configurations) can be answered directly without loading any files.

Step 1 — Load the corresponding reference: When the quick reference is insufficient, use

Read

to open

references/<file>.md

according to the "Knowledge Map" (Section 4). Most usage and code detail issues are resolved here. Mark the source reference file name when answering.

Step 2 — Local source code: If the reference does not cover the issue (usually more obscure or deeper source code details), first detect the local LiteFlow repository, in the priority order: environment variable

LITEFLOW_REPO

→

~/openSource/liteFlow

→

./liteFlow

Use
```
scripts/source-lookup.sh path
```
to detect (prints the absolute path if found; exit code 2 if not found).

After finding it, use

scripts/source-lookup.sh grep <keyword>

(search

*.java

) /

grepall

find <name>

show <relative path> [a-b]

to locate, answer with reference to
path:line
.

Step 3 — Request cloning (must obtain user consent first): If the local repository is not available, or the issue clearly requires online/latest source code, stop and inform the user to request confirmation, for example:

"This content is not in my built-in knowledge. I can git clone the official LiteFlow repository (gitee.com/dromara/liteFlow, default
v2.16.0
tag, aligned with built-in content) to a temporary directory, confirm from the source code and then answer. Is this allowed?"

User agrees → Run
```
scripts/source-lookup.sh clone
```
(clone to cache
```
~/.cache/liteflow-skill
```
), then use
```
grep/find/show
```
to locate, answer with reference to
path:line
.
User refuses / does not explicitly agree → Truthfully state "Cannot confirm temporarily, it is not recommended to speculate", do not clone on your own, do not fabricate, do not use web search results as the basis for LiteFlow's behavior.

Absolute Prohibitions

Fabricate APIs, method names, parameters, configuration items, default values or behaviors based on memory before reading the corresponding reference or source code.
Treat web search (WebSearch/webpage) results as the basis for LiteFlow's actual behavior (unless the user explicitly requests online verification).
Execute
```
git clone
```
or
```
source-lookup.sh clone
```
without the user's explicit consent.

3. High-Frequency Quick Reference (Answer Directly, No Need to Load Reference)

All the following content has been verified against official documentation + source code. If the following is still insufficient, check the corresponding reference for details.

3.1 EL Operator Quick Reference (See

references/el-rules.md

for details)

Operator	Semantics	Minimal Example
`THEN(a,b,c)` (alias `SER` )	Serial	`THEN(a, b, c)`
`WHEN(a,b,c)` (alias `PAR` )	Parallel (asynchronous)	`WHEN(a, b, c)`
`IF(x, a, b)`	Condition (x is a boolean component/expression; supports `ELIF` / `ELSE` )	`IF(x, a, b)`
`SWITCH(x).to(a,b,c)`	Selection (x returns target nodeId)	`SWITCH(x).to(a, b, c)`
`FOR(x).DO(y)`	Count loop (x returns the number of times)	`FOR(n).DO(a)`
`WHILE(x).DO(y)`	Condition loop	`WHILE(x).DO(a)`
`ITERATOR(x).DO(y)`	Iterator loop (x returns Iterator)	`ITERATOR(it).DO(a)`
`BREAK(x)`	Loop interruption (used with loops)	`WHILE(x).DO(a).BREAK(b)`
`CATCH(a).DO(b)`	Catch exceptions of a and pass to b for processing	`CATCH(a).DO(b)`
`RETRY(a).times(n)`	Retry	`RETRY(a).times(3)`
`a.maxWaitSeconds(5)` / `maxWaitMilliseconds(...)`	Timeout control	`WHEN(a,b).maxWaitSeconds(5)`
`PRE(a,b)` / `FINALLY(a,b)`	Pre / Post (always executed)	`THEN(PRE(a), b, FINALLY(c))`
`AND(a,b)` / `OR(a,b)` / `NOT(a)`	Boolean AND/OR/NOT (used for IF conditions)	`IF(AND(a,b), c, d)`
`let`	Sub-variable (reuse fragments)	See el-rules.md
Node modifiers	`tag` / `data` / `bind` / `id`	`a.tag("t").data("k","v")`
Link inheritance	`extends`	See el-rules.md

WHEN Parallel Modifiers:

ignoreError

(ignore errors and continue),

any

(end when any completes),

must(a,b)

(nodes that must complete),

percentage(n)

(by proportion), whether to use an independent thread pool, etc. — details see el-rules.md.

Where to write rules: In rule files such as

flow.xml

flow.json

flow.el

within

<chain name="..."> ... </chain>

, the trailing semicolon can be omitted; comments are supported.

3.2 Component Type Quick Reference (See

references/components.md

for details)

Desired Behavior	Component Type	Key Method/Annotation
Normal processing	`NodeComponent`	`process()`
Multi-way selection (returns nodeId)	`NodeSwitchComponent`	`processSwitch()` returns string
Boolean judgment (IF/WHILE condition)	`NodeBooleanComponent`	`processBoolean()` returns boolean
Count loop	`NodeForComponent`	`processFor()` returns count
Iterator loop	`NodeIteratorComponent`	`processIterator()` returns `Iterator`
Declarative (no base class inheritance)	Register Bean with `@LiteflowComponent("id")`	Add `@LiteflowMethod(PROCESS, nodeType=...)` to the method; or declare nodeType with `@LiteflowCmpDefine(type)` on the class

Registration: Both inherited/declarative components use
```
@LiteflowComponent("nodeId")
```
(can also use
```
name
```
to set alias).
Component lifecycle hooks (overridable for inherited components, use
```
@LiteflowMethod
```
for declarative components):
```
isAccess()
```
(admission, skip if false),
```
beforeProcess()
```
/
```
afterProcess()
```
,
```
onSuccess()
```
/
```
onError()
```
,
```
isContinueOnError()
```
,
```
isEnd()
```
,
```
rollback()
```
.

Retrieve context within component:

this.getContextBean(XxxContext.class)

this.getFirstContextBean()

; Retrieve process input parameters:

this.getRequestData()

3.3 Execution API Quick Reference (See

references/executor.md

for details)

java

@Resource private FlowExecutor flowExecutor;

// Synchronous execution: chainId + input parameter + multiple context Classes (instantiated by framework)
LiteflowResponse resp = flowExecutor.execute2Resp("chain1", param, OrderContext.class, UserContext.class);

// Directly execute a segment of EL (v2.15.0+, no rule file required)
LiteflowResponse resp2 = flowExecutor.execute2RespWithEL("THEN(a, b, c)", param, OrderContext.class);

// Asynchronous / Routing
Future<LiteflowResponse> f = flowExecutor.execute2Future("chain1", param, OrderContext.class);
List<LiteflowResponse> rs = flowExecutor.executeRouteChain(param, OrderContext.class);

Common values for

LiteflowResponse

(method names are based on source code):

Requirement	Method
Whether successful	`resp.isSuccess()`
Failure exception	`resp.getCause()` (it's `getCause` , not `getException` )
Exception code/message	`resp.getCode()` / `resp.getMessage()`
Context	`resp.getContextBean(XxxContext.class)` / `getFirstContextBean()`
Step string (with time consumption)	`resp.getExecuteStepStrWithTime()`
Structured steps	`resp.getExecuteSteps()` ( `Map<String, List<CmpStep>>` ) / `getExecuteStepQueue()`
Request/session/link ID	`getRequestId()` / `getConversationId()` / `getChainId()`
Timeout nodes (v2.12.3+)	`getTimeoutItems()`
Rollback steps	`getRollbackStepQueue()` / `getRollbackSteps()`

3.4 Core Configuration Quick Reference (See

references/config.md

for details, SpringBoot

liteflow.*

)

key	Default	Description
`rule-source`	—	Rule file path, required when using rule files; automatically invalid when changed to code dynamic construction
`parse-mode`	`PARSE_ALL_ON_START`	Also available `PARSE_ONE_ON_FIRST_EXEC` / `PARSE_ALL_ON_FIRST_EXEC` (lazy loading)
`slot-size`	`1024`	Context slot count, automatically expands
`when-max-wait-time` (+ `-unit` )	`15000` (ms)	Overall timeout for WHEN parallel execution
`global-thread-pool-size`	`64`	Global asynchronous node concurrency limit
`support-multiple-type`	`false`	Set to true when mixing multiple rule sources
`enable-monitor-file`	`false`	Auto-reload when local rule files change
`fast-load`	`false`	Fast parsing mode
`enable-virtual-thread`	`true`	Only takes effect for JDK21+
`print-execution-log`	`true`	Execution process log
`monitor.enable-log`	`false`	Simple monitoring statistics

⚠️ These configuration names do not exist in v2.16.X, do not fabricate:
whenMaxWorkers
(concurrency is controlled by
global-thread-pool-size
),
printExecutionResult
(should be
print-execution-log
),
chainCache*
.

4. Knowledge Map (Question Type → Reference File)

Use

Read

to open the corresponding file under

references/

for details:

Question Type / Keywords	Load File
Framework positioning, execution model, module map, version/JDK support, performance	`references/overview.md`
Installation and operation, Hello World (SpringBoot/Spring/Solon/others)	`references/quickstart.md`
All configuration items, scenario differences, LiteflowConfig	`references/config.md`
Components (5 inherited types / declarative / lifecycle hooks)	`references/components.md`
Full EL syntax, component parameter syntax, retry/timeout/inheritance/validation	`references/el-rules.md`
Data context, aliases, parameter injection, expression parameter retrieval	`references/context.md`
FlowExecutor methods, input parameters, LiteflowResponse	`references/executor.md`
Test cases and examples (testing paradigm, BaseTest cleanup, feature→test module quick reference, DEMO)	`references/testing.md`
Script components, coordinates for various languages, bound variables, dynamic refresh/validation/uninstallation	`references/scripts.md`
Rule configuration sources (local/SQL/ZK/Nacos/Etcd/Apollo/Redis/custom)	`references/rule-sources.md`
Metadata operator, smooth hot refresh, no startup check	`references/metadata.md`
Asynchronous thread pools (FlowExecutor layer/component asynchronous layer/virtual threads)	`references/thread-pools.md`
Dynamic construction of Node/EL/Chain	`references/dynamic-build.md`
Decision routing (concept/usage/executeRouteChain)	`references/decision-routing.md`
Framework-level lifecycle (startup/execution hook interfaces)	`references/lifecycle.md`
Advanced features (downgrade/rollback/aspect/implicit sub-process/steps/monitoring...18 items)	`references/advanced.md`
AI Agent orchestration (ReAct Agent components, model/credentials, custom tools, streaming output, session memory, `liteflow-react-agent` )	`references/react-agent.md`
Source code details (FlowExecutor/FlowBus/DataBus/Condition tree/operator→class mapping)	`references/code-internals.md`
Common pitfalls and FAQ	`references/faq-pitfalls.md`

5. Citation Specifications

Usage-related questions: Mark the source reference file name at the end of the answer, e.g., "See
```
references/el-rules.md
```
for details".
Code/source code-related questions: Cite source code
```
path:line
```
(from
```
references/code-internals.md
```
or source code found in Step 2/3).
For APIs/configurations involving version dependencies, mark the aligned version (default v2.16.X).

6. About

scripts/source-lookup.sh

A command-line assistant that prioritizes local usage / controlled cloning + retrieval (POSIX sh, can be run directly on macOS):

Subcommand	Function
`path`	Print the path of the detected local repository (exit code 2 if not found, no cloning)
`clone`	Explicitly clone the gitee repository to cache (default `v2.16.0` tag, aligned with built-in content; can specify other tags/branches using `LITEFLOW_TAG` ); only call after obtaining user consent
`grep <pattern>`	Search in `*.java` files of the repository (prioritize `rg` , fallback to `grep -rn` )
`grepall <pattern>`	Search in all files of the repository
`find <name>`	Search by file name
`show <relpath> [a-b]`	Display a file (with line numbers, optional range)

Environment variables:

LITEFLOW_REPO

(specify local repository to override detection),

LITEFLOW_TAG

(optional, specify tag/branch; if not set, clone

v2.16.0

, only fallback to master if explicitly set to empty

LITEFLOW_TAG=

LITEFLOW_CACHE

(default

~/.cache/liteflow-skill

Responsibility Boundary: The script does not handle user interaction; whether to clone is determined by the decision process of this skill (Step 3) after obtaining user consent.

how2useliteflow

NPX Install

Tags

SKILL.md Content (Chinese)

LiteFlow Assistant

1. When to Use

2. Decision Process for Answering LiteFlow Questions (Must Be Strictly Followed)

Absolute Prohibitions

3. High-Frequency Quick Reference (Answer Directly, No Need to Load Reference)

3.1 EL Operator Quick Reference (See
`references/el-rules.md`
for details)

3.2 Component Type Quick Reference (See
`references/components.md`
for details)

3.3 Execution API Quick Reference (See
`references/executor.md`
for details)

3.4 Core Configuration Quick Reference (See
`references/config.md`
for details, SpringBoot
`liteflow.*`
)

4. Knowledge Map (Question Type → Reference File)

5. Citation Specifications

6. About
`scripts/source-lookup.sh`

how2useliteflow

NPX Install

Tags

SKILL.md Content (Chinese)

LiteFlow Assistant

1. When to Use

2. Decision Process for Answering LiteFlow Questions (Must Be Strictly Followed)

Absolute Prohibitions

3. High-Frequency Quick Reference (Answer Directly, No Need to Load Reference)

3.1 EL Operator Quick Reference (See references/el-rules.md for details)

3.2 Component Type Quick Reference (See references/components.md for details)

3.3 Execution API Quick Reference (See references/executor.md for details)

3.4 Core Configuration Quick Reference (See references/config.md for details, SpringBoot liteflow.*)

4. Knowledge Map (Question Type → Reference File)

5. Citation Specifications

6. About scripts/source-lookup.sh

3.1 EL Operator Quick Reference (See
`references/el-rules.md`
for details)

3.2 Component Type Quick Reference (See
`references/components.md`
for details)

3.3 Execution API Quick Reference (See
`references/executor.md`
for details)

3.4 Core Configuration Quick Reference (See
`references/config.md`
for details, SpringBoot
`liteflow.*`
)

6. About
`scripts/source-lookup.sh`