FIT Framework：Java 企业级 AI 开发框架的架构全貌、构建流程与快速上手

• 人工智能
• 大模型
• AI 应用
• 后端
• AI Agent
• RAG
• 流程编排
• 微服务

FIT Framework（v3.7.0-SNAPSHOT）是一个 Java 企业级 AI 开发框架，由多语言函数引擎 FIT、流式编排引擎 WaterFlow 以及面向 Java 生态的 LangChain 替代方案 FEL 三大核心组成，支持原生与 Spring 双模运行、插件热插拔与“智能聚散”部署。本文基于仓库根目录的 README，结合 构建脚本、FIT 运行时、FEL 样例工程 等仓库内容，系统讲解它的三大核心架构、设计哲学、环境配置、构建启动全流程以及 AI 编程沙箱等开发工具，帮助你在本仓库中完成从编译构建到启动第一个应用的全过程。

一、项目定位与三大核心架构

仓库根 pom.xml 显示，当前工程以org.fitframework:parent:3.7.0-SNAPSHOT作为聚合父 POM，包含examples（示例）与framework（框架本体）两大模块；README 中的徽章表明其运行于 MIT 协议、面向 JDK 17 / JDK 21。README 将 FIT 的架构划分为三个维度：

1. FIT Core：语言无界，算力随需多语言函数计算底座（Java/Python/C++）支持插件化热插拔，提供智能聚散部署——代码无需修改即可在单体应用与分布式服务之间切换，运行时自动路由本地调用或远程调用。
2. WaterFlow Engine：流式智能，万物可编排统一 BPM 式图形化编排与响应式声明式 API 双模驱动，业务逻辑可按节点动态拼接，覆盖从毫秒级微流程到跨系统长事务的场景。
3. FEL（FIT Expression for LLM）为 Java 开发者提供基于标准化原语封装大模型、知识库与工具链的方案，让 AI 能力以工程化方式融入 Java 技术栈。

1.1 FIT Core：插件化、聚散部署与类加载隔离

framework/fit/java/README.md 对 FIT 函数平台给出四条核心能力定义：

• 多语言融合编程：在多种语言中采用统一的接口描述标准分别实现并相互调用；
• 插件化开发：插件在不依赖其他插件的前提下调用其他插件提供的服务；
• 聚散部署：插件既可以单插件独立进程运行，也可以多插件共享进程运行；
• 共享内存：即使插件分散为多进程部署，也可以以内存访问效率访问共享数据。

从源码结构看，这些能力都有对应的模块承载：framework/fit/java/下包含fit-ioc（IoC 容器）、fit-api（API 定义）、fit-plugin（插件架构）、fit-conf（配置）、fit-runtime（运行时）、fit-launcher（启动程序）等子模块，README 中列出的《工具集设计》《API 设计》《IoC 容器设计》《配置架构设计》《插件架构设计》《运行时设计》《启动程序设计》等设计文档与这些模块一一对应。

“聚散部署”在运行时层面有直接的代码证据。fit-runtime 的入口 提供FitStarter.start(...)静态方法启动应用；其runtime包下按部署形态划分了aggregated（聚合运行时）、direct（直连运行时）、discrete（离散运行时）与shared（共享类加载）四类实现，例如DiscreteFitRuntime、AggregatedFitRuntime等，对应 README 所说“单体应用与分布式服务一键切换”的底层支撑。启动器模块 fit-launcher 则通过AbstractClassLoader、FrameworkClassLoader、SharedClassLoader构建类加载结构。

fit-runtime 的 README 解释了为何要这样组织类加载：为了确保框架与插件之间的类隔离（避免三方包版本冲突），FIT 框架与每个插件使用独立的ClassLoader；而框架与插件间可能通过Genericable通信，要求接口在双方呈现为同一个类，因此SharedClassLoader统一加载fit-api、fit-util及所有Genericable定义，FrameworkClassLoader与每个插件的PluginClassLoader均双亲委派至它。这套机制正是“资源自管理：插件依赖自动注入”的实现基础。

1.2 WaterFlow：水流式流程编排引擎

waterflow-core 的 README 说明 WaterFlow 是一个水流式流程编排引擎，核心特点是支持有界流与无界流处理，任意节点可单独灌入数据，节点入参水流与出参水流支持 M:N 关系。最小入门示例是：

ProcessFlow<Integer> flow = Flows.<Integer>create() .map(i -> i + 2) .map(i -> i.toString()) .close(r -> r.getAll().stream().forEach(i -> System.out.println(i.getData()))); flow.offer(new Integer[] {1, 2, 3, 4, 5});

它提供了一套完整的声明式节点操作 API，这也是 FEL 上层流程编排的“语法基础”：

需要注意的两条使用限制：编排流程须保证无死循环，否则数据会持续在循环节点上流转；数据流转线程池上限 100，每个节点最大同时处理 16 个批次，超出的批次排队等待。此外，README 还介绍了核心的FlowSessionCache会话缓存机制：按flowId -> sessionId层级组织缓存，负责nextToSessions、flatMapSourceWindows、matchWindows等资源的管理与自动释放，确保同一批数据在节点间使用相同会话汇聚、会话结束时自动清理，避免内存泄漏。offer是向流投递数据的操作，流的运行是异步的，offer返回的是本次运行的实例 ID。

1.3 FEL：用 Java 原语编排大模型应用

FEL 面向 Java 生态提供标准化原语（模型、模板、记忆、输出解析器、检索增强生成、智能体），仓库中保留了两个有代表性的端到端样例，README 正文中的两段代码即取自它们。

RAG（retrieve）样例，对应 RetrievalExampleController，其核心流程是一个“查询改写 + 向量检索 + 结果综合”的子流程：

AiProcessFlow<Tip, Content> retrieveFlow = AiFlows.<Tip>create() .runnableParallel(history(), passThrough()) .conditions() .match(tip -> !tip.freeze().get(DEFAULT_HISTORY_KEY).text().isEmpty(), node -> node.prompt(Prompts.human(REWRITE_PROMPT)) .generate(chatFlowModel) .map(ChatMessage::text)) .others(node -> node.map(tip -> tip.freeze().get("query").text())) .retrieve(new DefaultVectorRetriever(vectorStore, SearchOption.custom().topK(1).build())) .synthesize(docs -> Content.from(docs.stream().map(Document::text).collect(Collectors.joining("\n\n")))) .close();

逐行理解：runnableParallel(history(), passThrough())将对话历史与原始查询并行放入上下文Tip；conditions().match(...)分支判断历史是否为空——非空时用REWRITE_PROMPT调用chatFlowModel改写检索词，others分支则直接取query；随后retrieve(...)用DefaultVectorRetriever按topK(1)从向量库召回文档，synthesize(...)将文档文本拼合为Content。完整控制器中还包含索引构建流程indexFlow（load(new JsonFileSource(...)).index(vectorStore)）以及最终 RAG 主流程（prompt+generate），可结合 05. 检索增强生成 阅读。

Agent 样例，对应 AgentExampleController：

AiProcessFlow<String, ChatMessage> agentFlow = AiFlows.<String>create() .map(query -> Tip.fromArray(query)) .prompt(Prompts.human("{{0}}")) .delegate(agent) .close();

流程将用户查询包装为Tip，经prompt组织提示词后delegate(agent)交给智能体接管——示例中的DefaultAgent由ChatFlowModel与ToolExecuteService构造，调用时通过.bind(ChatOption...tools(toolInfos).build())动态绑定工具列表。

两段示例的共同入口是 AiFlows：除create()建立流程头结点外，还提供mono(D)、flux(D...)、source(Emitter)三个数据前置流构造方法。从源码看，AiFlows.create()内部先调用 WaterFlow 的Flows.create()生成Start节点，再包装出AiProcessFlow——这正是 FEL 建立在 WaterFlow 流编排能力之上的直接证据。

二、设计哲学：约定优于配置

README 强调 FIT 通过“智能约定”大幅减少胶水代码，具体体现在三点：

• 部署无感化：聚散模式自动识别，开发者只需声明业务关系，无需手工标注远程/本地调用；
• 协议透明化：HTTP/gRPC/共享内存等通信方式由框架按上下文智能选择；
• 资源自管理：插件依赖自动注入，服务发现与熔断机制内置实现。

其目标是让 80% 的通用场景实现零配置，同时保留 20% 复杂场景的深度定制能力。这种“契约式”设计与上文 1.1 节的类加载结构、运行时形态划分（aggregated/direct/discrete）相互呼应：框架把部署拓扑与通信细节封装在运行时层，业务代码只面向接口（Genericable）编程，从而获得“从单机原型到云原生集群”的架构弹性。README 将其定位为面向 Java 生态的 AI 全栈方案，让 Java 开发者无需切换技术栈即可构建现代 AI 应用。

三、环境配置

开发环境要求（README「环境配置」一节）：

补充两个仓库中可确认的细节：build.sh在找不到npm时会打印警告并跳过 Sandbox CLI 构建（“Install Node.js 18+ and re-run”），因此纯 Java 构建不强制要求 Node 环境；AI 编程沙箱 则声明仅支持 macOS（依赖 Colima），且需要 Homebrew 与 Node.js 18+。

四、构建、产物与启动

4.1 三种构建命令

# 仅构建 Java 框架 mvn clean install # 全局构建（Java 框架 + Sandbox CLI），默认跳过测试 ./build.sh # 全局构建（含测试） ./build.sh --with-test

阅读 build.sh 可以看到全局构建分两个阶段：

1. Maven 阶段：mvn clean install（无参数时追加-DskipTests）；
2. Sandbox CLI 阶段：进入docker/sandbox执行npm install --no-fund --no-audit && npm run build（esbuild 将 TypeScript 源码打包为单文件dist/sandbox.cjs），随后把产物拷贝到build/bin/sandbox.cjs，并生成build/bin/sandbox可执行入口（require('./sandbox.cjs')）。

4.2 输出目录

build/ ├── bin/ │ ├── fit # FIT 启动命令 │ └── sandbox # AI 编程沙箱命令（build.sh 构建时生成） ├── fit-discrete-launcher-*.jar ├── lib/ ├── plugins/ └── ...

4.3 配置环境变量并创建插件目录

README 给出的运行方式是“框架目录 + 插件目录”分离：

1. 先用 Maven 编译打包./framework/fit/java，将build目录内容存储到本地fitframework目录，该目录即 FIT 核心框架目录；
2. 配置FIT环境变量，值指向 FIT 核心框架目录（如/demo/fitframework），使fit命令可执行；
3. 新建任意目录作为插件目录存放插件，在插件目录下执行启动命令：

./build/bin/fit start

两条必须注意的限制：环境变量的配置方式与路径分隔符需按所在操作系统调整；fit命令无法在包含 FIT 框架的目录中执行，只能在新建的动态插件目录下执行。编译出的fit、sandbox命令可通过别名或加入PATH简化输入。

在 IDE 内直接开发时，FIT 快速开始 给出的是另一条等价路径：项目中引入fit-starter、fit-plugins-starter-web、fit-api依赖，用FitStarter.start(DemoApplication.class, args)启动，并通过@Component+@GetMapping编写控制器，直接在 IDE 运行main方法或运行可执行 JAR。

五、快速开始路线图

README 将学习路径划分为三条主线，分别对应三大核心，且examples模块中均有配套可运行工程：

5.1 FIT 函数框架

• 入门文档：FIT 快速开始（核心概念 + 基础应用）；
• 系统学习：构建基础 Web 应用 至 工程目录最佳实践 共 7 篇快速入门，以及 插件、IoC 容器和 Bean 至 附加功能组件 共 12 篇用户指导手册（涵盖 AOP、Conf 配置、Web MVC、Genericable 远程/本地调用、数据访问、流式功能、类加载等）；
• 配套示例：examples/fit-example 提供从 01-simple-web-app 到 08-nacos-complicated-apps 的 8 个递进工程，examples/fel-spring-example 则展示 Spring Boot 双模运行形态。

5.2 WaterFlow 流调度引擎

• 入门文档：WaterFlow 快速开始（声明式语法与 hello world）；
• 系统学习：Waterflow 快速入门指南（含前置准备、第一个示例与 8 篇常见示例）与 WaterFlow 用户指导手册。

5.3 FEL 标准原语

• 入门文档：FEL 快速开始，从模型、模板、记忆、输出解析器到检索增强生成、智能体六步构建端到端大模型应用；
• 用户手册：FEL 用户指导手册（AI 流程、提示词、模型、输入输出工具、记忆、RAG、原语、工具调用、智能体共 9 篇）；
• 配套示例：examples/fel-example 的 01-model 到 06-agent 与上述六篇入门指南一一对应，本文第一节引用的 RAG 与 Agent 样例代码即出自其中。

六、开发工具：AI 编程沙箱（macOS）

README 介绍了一个基于Colima + Docker + Git Worktree的隔离开发环境：将 Claude Code、Codex 等 AI 编程工具运行在容器内，支持多容器并发，每个容器工作在独立分支上互不干扰，即使 AI 执行了破坏性命令，影响范围也仅限该容器的 worktree。常用命令：

sandbox create feat-xxx # 创建沙箱 sandbox exec feat-xxx # 进入沙箱 sandbox ls # 查看所有沙箱 sandbox rm feat-xxx # 清理沙箱

详见 AI 编程沙箱文档。从仓库结构可确认：CLI 源码位于 docker/sandbox/src，命令实现拆分为create.ts、enter.ts、ls.ts、rebuild.ts、rm.ts、vm.ts等文件，经 esbuild 打包后由build.sh输出为全局可用的sandbox命令；沙箱要求在 fit-framework 的 git 仓库目录内运行（依赖 git worktree 与仓库内 Dockerfile）。

七、文档体系与贡献

项目完整文档位于docs/目录，除上述三份框架指南外，还有一个基于本框架开发的大模型应用编排平台（Model Engine）的商业化应用案例：Model Engine 技术白皮书，按概述、系统架构、FIT 函数平台、Waterflow 流调度平台逐层展开，可作为三大核心在真实产品中的落点参照。

参与贡献前请阅读 CONTRIBUTING.md（分支管理、标签管理、提交规则、代码审查），并导入 CodeFormatterFromIdea.xml 保持代码风格统一；仓库还内置了 git-hooks/check-utf8-encoding.sh 等钩子脚本约束提交质量。

八、小结

• 架构：FIT Core 提供多语言函数、插件热插拔与聚散部署（对应fit-runtime的 aggregated/direct/discrete 运行时与共享类加载机制）；WaterFlow 提供声明式流编排（Flows节点 API +FlowSessionCache会话管理）；FEL 在其之上以大模型原语（模型/模板/记忆/RAG/智能体）构建 AI 应用，三者以AiFlows为交汇点。
• 上手：mvn clean install或./build.sh构建 → 配置FIT环境变量 → 在插件目录执行./build/bin/fit start；IDE 内开发则走FitStarter.start(...)路径。
• 学习：三条文档主线（FIT / WaterFlow / FEL 的 quick-start-guide 与 user-guide-book）加 Model Engine 白皮书，配合examples下的可运行工程即可从基础 Web 应用一路走到智能体与 RAG 应用。

• 人工智能
• 大模型
• AI 应用
• 后端
• AI Agent
• RAG
• 流程编排
• 微服务