Jeecg Aiflow

JeecgBoot AIFlow — AI 编排流程管理

设计原则

本 skill 的核心架构是模板驱动：AI 不直接生成节点 JSON，而是选择节点类型后由脚本从权威模板生成完整结构，AI 只负责填写业务配置。这样做的原因是 AIFlow 的节点配置字段非常多且结构严格，让 AI 从零生成容易产生格式错误。chain（LiteFlow EL 表达式）也由 Python 脚本自动生成，AI 不需要关心。

修改已有流程时，先查询再修改——因为流程的 design JSON 包含所有节点状态，凭记忆操作容易丢失配置。

前置条件

用户需提供两个信息：

1. API 地址（默认 http://localhost:3100/jeecgboot）
2. X-Access-Token（从浏览器 F12 → Network → Request Headers 复制）

工作目录机制

所有操作基于「工作目录」。首先通过 init-work 创建工作目录，后续所有命令只需传 -w，脚本自动从工作目录中的 meta.json 读取 API 凭证和流程信息，design.json 也存放在工作目录中。

工作目录结构：
  {临时目录}/jeecg-aiflow/{workId}/
    ├── meta.json      ← name, descr, apiBase, token, flowId
    └── design.json    ← 节点和连线的完整 JSON

创建流程（核心流程）

1. 初始化工作目录

python "<skill目录>/scripts/aiflow_creator.py" init-work \
  --name "流程名称" \
  --descr "流程描述" \
  --api-base "<api_base>" \
  --token "<token>"

返回 workId，后续所有命令都用这个 ID。

2. 理解需求，选择节点

根据用户描述，从下方「节点类型速查表」选择节点。每个流程必须包含 1 个 start 和至少 1 个 end。

3. 展示摘要，等待用户确认（强制）

生成之前必须展示完整摘要并等待用户明确确认。除非用户事先说过"不用确认直接生成"，否则不要跳过这一步。

摘要需要包含三部分：节点列表、节点关系（连线）、关键配置：

流程名称：知识库问答助手

节点列表：
  1. start — 开始（接收用户问题）
  2. knowledge — 知识库检索
  3. llm — 大模型（根据检索结果回答）
  4. end — 结束（返回回答文本）

节点关系：
  start → knowledge → llm → end

关键配置：
  - knowledge: 知识库待选择（需要您提供知识库ID或让我查询列表）
  - llm: 模型待选择，系统提示词="你是一个知识库问答助手..."
  - end: 输出类型=text，内容引用 llm 的回复

等待用户回复确认后再继续下一步。如果用户提出修改意见，调整后重新展示摘要。

4. 生成模板 JSON

python "<skill目录>/scripts/aiflow_creator.py" generate \
  -w "<workId>" \
  --types "start,knowledge,llm,end"

脚本从权威模板生成 design.json 到工作目录。返回包含文件定位信息的结构：

{
  "totalLines": 168,
  "nodes": [
    {"id": "start-node", "type": "start", "startLine": 3, "endLine": 50},
    {"id": "746...", "type": "llm", "startLine": 51, "endLine": 92},
    {"id": "746...", "type": "end", "startLine": 93, "endLine": 110}
  ],
  "edgesLines": {"startLine": 112, "endLine": 167}
}

• totalLines — design.json 的总行数。行数较少时可全量读取，较多时按节点行号精准定位
• nodes[i].startLine / endLine — 该节点在 design.json 中的起止行号（1-based），用于 Read 工具的 offset/limit 参数精准读取单个节点
• edgesLines.startLine / endLine — edges 数组的起止行号，修改连线时精准定位
• generate、export、add-node、remove-node 命令都返回以上信息

5. 读取 JSON，编辑业务配置

利用返回的行号，用 Read 工具按需读取目标节点或 edges 片段，再用 Edit 工具修改。需要关注两类内容：

A. 业务配置（根据用户需求填写）

每种节点需要配置的核心字段：

查询系统资源（不需要手动 init_api，通过 query 子命令自动从工作目录读取凭证）：

python "<skill目录>/scripts/aiflow_creator.py" query -w "<workId>" --resource models        # LLM 模型
python "<skill目录>/scripts/aiflow_creator.py" query -w "<workId>" --resource knowledge     # 知识库
python "<skill目录>/scripts/aiflow_creator.py" query -w "<workId>" --resource datasources   # 数据源
python "<skill目录>/scripts/aiflow_creator.py" query -w "<workId>" --resource subflows      # 子流程

start 和 end 是每个流程必有的节点，完整配置参考如下（无需查索引）：

start — 开始节点

进阶配置见 references/node-reference.md 的 start — 定时触发配置 章节，包含：cronTrigger 开关与 cronType 选择（minute/hour/day/custom）、cronExp 表达式生成规则、custom 对象结构（时/天/周/月的精细控制）。

inputParams 结构

固定的默认 inputParams（3 个）：

type 枚举值（开始节点支持 4 种）：

注意：图片字段的 field 必须命名为 images，否则 LLM 节点无法接收图片。

禁止使用数组类型：start 节点的 inputParams 只支持以上 4 种类型，不支持 string[]、object[] 等数组类型。如果流程需要数组输入（如 loop 的 array 迭代模式），应通过前置的 code 节点构造数组，而不是在 start 节点定义数组字段。

其他节点的 inputParams/outputParams 还可能使用 string[]、number[]、object[]、object、text、boolean 等扩展类型。

outputParams

无（开始节点没有输出参数）。

校验规则

特殊行为

• 固定 ID: start-node，不可修改
• 只有右侧锚点（无左侧输入）
• 不允许删除

end — 结束节点

options 字段

outputType 三种模式区别：

校验规则

进阶配置见 references/node-reference.md 的 end — 进阶配置 章节，包含：cardConfig 卡片结构（outputType='card' 时的字段绑定）、作为子流程时各 outputType 的输出行为差异。

特殊行为

• 只有左侧锚点（无右侧输出）
• 一个流程至少需要 1 个 end 节点

使用要点：end 与 reply 的区别

end 是流程的最终输出，流程结束后只保留 end 节点的内容作为最终返回结果。需要给用户返回内容并结束流程时，必须用 end。

常见错误：用 reply 节点代替 end 节点来结束某个分支（如"商务问题直接回复请联系销售团队"）。reply 在流式传输时能看到内容，但流程最终结果中不会保留。正确做法是用 end 节点。

其他节点的完整字段说明在 references/node-reference.md — 修改具体字段前按下方索引表 Read 对应片段（只读该片段，不要全量读）：

<!-- NODE_OPTIONS_INDEX:START -->

!python ${CLAUDE_SKILL_DIR}/scripts/gen_node_options_index.py 2>/dev/null || echo '> （节点选项索引自动生成失败，请用 Grep 搜索 "## <节点type>" 定位 references/node-reference.md 中的对应章节）'

<!-- NODE_OPTIONS_INDEX:END -->

B. 流程结构（AI 自行填写）

1. 节点坐标 — 按以下常量布局：

线性流程：所有节点在同一行（y=300），x 依次 +400。

分支流程（switch/classifier/varExtract 有多个下游）：分支下游节点竖向排列，以父节点 y 为中心上下分散，相邻分支间距 ≥ Y_GAP(180px)。示例（switch 有 3 个分支）：

分支1 y = 300 - 180 = 120
分支2 y = 300           （与 switch 同行）
分支3 y = 300 + 180 = 480

防重叠规则：放置节点时，检查同一 x 列上已有节点，确保任意两个节点的 y 差值 ≥ Y_GAP(180px)。如果分支后的节点再次汇合（多条路径合并到同一个节点），汇合节点 y 取所有入边来源节点 y 的平均值。

2. 连线 edges — 描述节点间的连接关系

每条边必须包含 sourceAnchorId 和 targetAnchorId，否则前端渲染效果不一致。

每条边必须包含 id、pointsList 和 properties：

pointsList 格式（严格要求，违反会导致前端 Cannot read properties of undefined (reading 'x') 报错）：

• base-edge（贝塞尔曲线边）必须恰好 4 个点：[源锚点, 源控制点, 目标控制点, 目标锚点]

  源锚点:    {x: 源节点.x + 332,       y: 源节点.y + 31}   // 节点右边缘中点
  源控制点:  {x: 源节点.x + 332 + 100,  y: 源节点.y + 31}   // 右偏移100px
  目标控制点: {x: 目标节点.x - 100,      y: 目标节点.y + 31}  // 左偏移100px
  目标锚点:  {x: 目标节点.x,            y: 目标节点.y + 31}   // 节点左边缘中点

  其中 332 = 节点宽度，31 = 节点高度(62) / 2。分支节点的源锚点 y 坐标需根据分支索引微调。

• base-line-edge（直线边，loop↔loopBody 专用）必须为空数组 []，不能省略字段

完整边示例（base-edge）：

{"id": "325590000000000001", "type": "base-edge", "sourceNodeId": "A", "targetNodeId": "B", "sourceAnchorId": "A_output", "targetAnchorId": "B_input", "pointsList": [{"x": 532, "y": 331}, {"x": 632, "y": 331}, {"x": 500, "y": 331}, {"x": 600, "y": 331}], "properties": {"runStatus": ""}}

完整边示例（base-line-edge）：

{"id": "325590000000000002", "type": "base-line-edge", "sourceNodeId": "loop1", "targetNodeId": "loop1_loopBody", "sourceAnchorId": "loop1_link_body", "targetAnchorId": "loop1_loopBody_link_loop", "pointsList": [], "properties": {"runStatus": ""}}

anchorId 规则：

• 普通出边：sourceAnchorId = "{sourceNodeId}_output"
• 普通入边：targetAnchorId = "{targetNodeId}_input"

分支节点的出边用专用 sourceAnchorId 替代 _output：

• switch: {id}_source_if（IF）、{id}_case_{n}（ELIF n≥2）、{id}_source_else（ELSE）
• classifier: {id}_case_{n}（分类 n≥1）、{id}_case_else
• varExtract: {id}_success、{id}_fail

并行分支：普通节点（非 switch/classifier）也可以有多条出边连接到不同下游，形成并行执行路径。多条出边都使用同一个 sourceAnchorId = "{nodeId}_output"，连到不同的 targetNodeId。并行路径可以汇合到同一个下游节点。

分支流程关键规则（必须遵守）：

1. 每个分支出口都必须有独立的边：switch 的 IF/ELIF/ELSE、classifier 的每个 category + ELSE、varExtract 的 success/fail，每个分支都必须有一条带对应 sourceAnchorId 的边连接到下游节点。不能遗漏任何分支（尤其是 ELSE），即使多个分支指向同一个目标节点也需要各自独立的边。
2. 分支出口的 next 字段必须和 edges 一致：switch 的 if[i].next/else.next、classifier 的 categories[i].next/else.next、varExtract 的 success.next/fail.next 必须填写，且值与 edges 中的 targetNodeId 一致。
3. 互斥分支汇合时用 varMerge：当 switch/classifier 的多个分支各自产出结果后需要汇合到同一个下游节点时，不要让下游节点直接分别引用各分支的输出变量（运行时只有一个分支执行，其他变量为空）。正确做法是在汇合处插入 varMerge 节点，将各分支的同类输出聚合为一个变量，下游节点引用聚合后的变量。