端到端快速开始

本教程完成“浏览器编辑并导出 JSON，再由 Java 解析执行”的最小闭环。只需要编辑器时可停在前半部分。

需要直接运行的 Vue 3 + Java 17 + Spring Boot 工程结构、动态开始参数表单和完整 HTTP 接口，请阅读 Vue + Spring Boot 完整示例，或直接访问 tinyflow-demo Gitee 仓库。

环境要求

• 前端：满足当前包 engines 要求的 Node.js，建议使用 Node.js 20.19+。
• 后端：JDK 8+、Maven 3.6+。
• 容器：编辑器挂载元素必须有明确高度。

1. 创建前端页面

npm install @tinyflow-ai/ui

<div id="tinyflow-editor"></div>
<button id="save-flow" type="button">保存工作流</button>

#tinyflow-editor {
  width: 100%;
  height: 640px;
}

import { Tinyflow } from '@tinyflow-ai/ui';
import '@tinyflow-ai/ui/dist/index.css';

const editor = new Tinyflow({
  element: '#tinyflow-editor',
  data: { nodes: [], edges: [], viewport: { x: 0, y: 0, zoom: 1 } },
  defaultTheme: 'system',
  provider: {
    llm: async () => [{ value: 'support-main', label: '客服主模型' }]
  },
  onDataChange(data) {
    console.debug('workflow changed', data);
  }
});

document.querySelector('#save-flow').addEventListener('click', async () => {
  const definition = editor.getData();
  await fetch('/api/workflow-definitions/support-flow/drafts', {
    method: 'PUT',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(definition)
  });
});

getData() 返回 nodes、edges 和 viewport。不要只保存节点：连线决定执行拓扑，parentId 决定 Loop 子图关系。

2. 设计一个可执行流程

在编辑器中创建：

开始(start) -> 内容模板(welcome) -> 结束(end)

开始节点声明输入 name；模板节点引用 start.name；结束节点引用模板输出。可直接使用 Java 集成页中的完整 JSON 作为后端联调样例。

保存草稿后，业务服务应检查节点 ID、边端点、节点 type、参数引用和安全策略，再生成不可变发布版本。不要直接执行浏览器提交的任意 JSON。

3. 添加 Java 运行时

<dependency>
  <groupId>dev.tinyflow</groupId>
  <artifactId>tinyflow-core</artifactId>
  <version>2.0.7</version>
</dependency>

ChainParser parser = ChainParser.builder()
    .withDefaultParsers(true)
    .build();

ChainDefinitionRepository definitions = definitionId -> {
    String json = loadPublishedJson(definitionId);
    ChainDefinition definition = parser.parse(json);
    if (definition == null) {
        throw new IllegalArgumentException("Invalid workflow: " + definitionId);
    }
    definition.setId(definitionId);
    return definition;
};

ChainExecutor executor = new ChainExecutor(
    definitions,
    new InMemoryChainStateRepository(),
    new InMemoryNodeStateRepository()
);

Map<String, Object> inputs = new HashMap<>();
inputs.put("name", "Ada");
Map<String, Object> result = executor.execute("support-flow", inputs);

内存仓库只适合本地演示。生产环境必须实现持久化状态仓库和锁，并设置超时、重试、限流与日志脱敏。

4. 接入 AI 框架

工作流包含 llmNode 时，除 tinyflow-core 外还需选择与业务一致的适配模块：

技术栈	模块	文档
Agents-Flex	tinyflow-support-agentsflex	接入说明
Spring AI	tinyflow-support-springai	接入说明
LangChain4j	tinyflow-support-langchain4j	接入说明
Solon AI	tinyflow-support-solonai	接入说明

前端 provider.llm 只为下拉框提供逻辑 ID；真正的模型对象和密钥留在服务器，由后端用该 ID 解析。

5. 上线前检查

• 保存草稿、发布版本和运行实例使用不同的数据模型。
• 发布时拒绝未知 node type；当前 ChainParser 会静默忽略它。
• 不允许普通用户任意配置内网 HTTP 地址或动态代码。
• onDataChange 适合标记 dirty 或节流自动保存，最终保存仍调用 getData()。
• 页面卸载时调用 editor.destroy()。
• 对历史发布 JSON 做解析和执行回归测试。

下一步阅读配置项与 API、Java 快速集成和生产部署。