Java SDK

概述

iFlow SDK是用于与iFlow CLI进行编程交互的SDK，通过他可以快速将iFlow CLI集成到你的业务系统中，结合workflow等智能体扩展，允许开发者构建具有对话、工具执行和任务规划能力的 AI 驱动应用程序，让业务系统具备AI的能力。目前已支持Python、Java、TypeScript、Android版本。

✨ 核心特性：SDK 自动管理 iFlow 进程 - 无需手动配置！

基于 Project Reactor 构建，支持现代响应式编程，为Java开发者提供强大的异步处理能力。

系统要求

Java: 11 或更高版本
iFlow CLI: 0.2.24 或更高版本
操作系统: Windows、macOS、Linux

安装

1. 安装 iFlow CLI

如果您还没安装 iFlow CLI：

Mac/Linux/Ubuntu
Windows

bash -c "$(curl -fsSL https://gitee.com/iflow-ai/iflow-cli/raw/main/install.sh)"

npm install -g @iflow-ai/iflow-cli@latest

2. 添加 SDK 依赖

Maven
Gradle

<dependency>
    <groupId>cn.iflow</groupId>
    <artifactId>iflow-cli-sdk</artifactId>
    <version>1.0.4-fix</version>
</dependency>

implementation 'cn.iflow:iflow-cli-sdk:1.0.4-fix'

快速开始

基础示例

SDK 会自动检测并启动 iFlow 进程，无需手动配置：

import cn.iflow.sdk.core.IFlowClient;
import cn.iflow.sdk.types.messages.*;
import reactor.core.publisher.Flux;

public class BasicExample {
    public static void main(String[] args) throws Exception {
        // SDK 自动处理：
        // 1. 检测 iFlow 是否已安装
        // 2. 启动 iFlow 进程（如果未运行）
        // 3. 查找可用端口并建立连接
        // 4. 退出时自动清理资源
        try (IFlowClient client = IFlowClient.create()) {
            client.connect().block();
            client.sendMessage("你好，iFlow！").block();
            
            // 使用 blockLast() 等待流完成，避免资源过早关闭
            client.receiveMessages()
                .doOnNext(message -> {
                    if (message instanceof AssistantMessage) {
                        AssistantMessage assistantMsg = (AssistantMessage) message;
                        System.out.print(assistantMsg.getChunk().getText());
                    } else if (message instanceof TaskFinishMessage) {
                        System.out.println("\n对话完成");
                    }
                })
                .doOnError(error -> error.printStackTrace())
                .doOnComplete(() -> System.out.println("流结束"))
                .blockLast(); // 阻塞直到流完成
        }
    }
}

简单查询

最简单的使用方式是通过 IFlowQuery 工具类：

import cn.iflow.sdk.query.IFlowQuery;
import cn.iflow.sdk.types.messages.Message;
import java.util.List;

public class SimpleQuery {
    public static void main(String[] args) throws Exception {
        // 同步查询
        List<Message> response = IFlowQuery.querySync("法国的首都是哪里？");
        for (Message msg : response) {
            if (msg instanceof AssistantMessage) {
                System.out.println(((AssistantMessage) msg).getChunk().getText());
            }
        }
    }
}

核心概念

IFlowClient

IFlowClient 是与 iFlow CLI 交互的主要接口，基于 Project Reactor 构建：

import cn.iflow.sdk.core.IFlowClient;
import cn.iflow.sdk.types.config.IFlowOptions;
import cn.iflow.sdk.types.enums.PermissionMode;
import java.time.Duration;

// 使用默认配置（自动管理进程）
try (IFlowClient client = IFlowClient.create()) {
    client.connect().block();
    client.sendMessage("你的问题").block();
    // 处理消息...
}

// 使用自定义配置
IFlowOptions options = IFlowOptions.builder()
    .url("ws://localhost:8090/acp")       // WebSocket URL
    .autoStartProcess(true)               // 自动启动 iFlow
    .timeout(Duration.ofSeconds(30))      // 超时时间
    .permissionMode(PermissionMode.AUTO)  // 工具调用权限模式
    .build();

try (IFlowClient client = IFlowClient.create(options)) {
    client.connect().block();
    client.sendMessage("你的问题").block();
    // 处理消息...
}

响应式编程支持

SDK 基于 Project Reactor 构建，支持 Mono 和 Flux：

import reactor.core.publisher.Mono;
import reactor.core.publisher.Flux;

try (IFlowClient client = IFlowClient.create()) {
    // Mono<Void> - 单个操作
    Mono<Void> connectionMono = client.connect();
    Mono<Void> sendMono = client.sendMessage("你好");
    
    // Flux<Message> - 消息流
    Flux<Message> messageFlux = client.receiveMessages();
    
    // 链式操作
    connectionMono
        .then(sendMono)
        .then(messageFlux.take(10).collectList())
        .subscribe(messages -> {
            // 处理消息列表
        });
}

消息类型

SDK 支持多种消息类型，对应 iFlow 协议的不同响应：

AssistantMessage - AI 助手响应

import cn.iflow.sdk.types.messages.AssistantMessage;

try (IFlowClient client = IFlowClient.create()) {
    client.connect().block();
    client.sendMessage("请介绍一下Java").block();
    
    client.receiveMessages()
        .doOnNext(message -> {
            if (message instanceof AssistantMessage) {
                AssistantMessage assistantMsg = (AssistantMessage) message;
                System.out.print(assistantMsg.getChunk().getText());
                
                // 访问代理信息（如果有）
                if (assistantMsg.getAgentInfo() != null) {
                    System.out.println("代理ID: " + assistantMsg.getAgentInfo().getAgentId());
                    if (assistantMsg.getAgentInfo().getTaskId() != null) {
                        System.out.println("任务ID: " + assistantMsg.getAgentInfo().getTaskId());
                    }
                }
            } else if (message instanceof TaskFinishMessage) {
                System.out.println("\n响应完成");
            }
        })
        .blockLast(); // 等待流完成
}

ToolCallMessage - 工具调用

import cn.iflow.sdk.types.messages.ToolCallMessage;
import cn.iflow.sdk.types.enums.ToolCallStatus;

try (IFlowClient client = IFlowClient.create()) {
    client.connect().block();
    client.sendMessage("列出当前目录的文件").block();
    
    client.receiveMessages()
        .doOnNext(message -> {
            if (message instanceof ToolCallMessage) {
                ToolCallMessage toolCall = (ToolCallMessage) message;
                System.out.println("工具调用状态: " + toolCall.getStatus());
                System.out.println("工具标题: " + toolCall.getTitle());
                
                // 访问工具调用内容
                if (toolCall.getContent() != null) {
                    System.out.println("工具内容: " + toolCall.getContent());
                }
                
                // 访问代理信息
                if (toolCall.getAgentInfo() != null) {
                    System.out.println("代理ID: " + toolCall.getAgentInfo().getAgentId());
                }
            } else if (message instanceof TaskFinishMessage) {
                System.out.println("工具执行完成");
            }
        })
        .blockLast(); // 等待流完成
}

PlanMessage - 任务计划

import cn.iflow.sdk.types.messages.PlanMessage;

try (IFlowClient client = IFlowClient.create()) {
    client.connect().block();
    client.sendMessage("帮我创建一个Java项目结构").block();
    
    client.receiveMessages()
        .doOnNext(message -> {
            if (message instanceof PlanMessage) {
                PlanMessage planMsg = (PlanMessage) message;
                System.out.println("执行计划:");
                
                planMsg.getEntries().forEach(entry -> {
                    String statusIcon = "completed".equals(entry.getStatus()) ? "✅" : "⏳";
                    System.out.printf("%s [%s] %s%n", 
                        statusIcon, entry.getPriority(), entry.getContent());
                });
            } else if (message instanceof TaskFinishMessage) {
                System.out.println("计划制定完成");
            }
        })
        .blockLast(); // 等待流完成
}

TaskFinishMessage - 任务完成

import cn.iflow.sdk.types.messages.TaskFinishMessage;
import cn.iflow.sdk.types.enums.StopReason;

try (IFlowClient client = IFlowClient.create()) {
    client.connect().block();
    client.sendMessage("计算 1+1").block();
    
    client.receiveMessages()
        .doOnNext(message -> {
            if (message instanceof AssistantMessage) {
                AssistantMessage assistantMsg = (AssistantMessage) message;
                System.out.print(assistantMsg.getChunk().getText());
            } else if (message instanceof TaskFinishMessage) {
                TaskFinishMessage finishMsg = (TaskFinishMessage) message;
                System.out.println(); // 换行
                
                if (finishMsg.getStopReason() == StopReason.END_TURN) {
                    System.out.println("任务正常完成");
                } else if (finishMsg.getStopReason() == StopReason.MAX_TOKENS) {
                    System.out.println("达到最大令牌限制");
                }
                // TaskFinishMessage 表示对话结束
            }
        })
        .blockLast(); // 等待流完成
}

常见用例

交互式聊天机器人

import java.util.Scanner;

public class ChatBot {
    public static void main(String[] args) throws Exception {
        System.out.println("iFlow 聊天机器人 (输入 'quit' 退出)");
        System.out.println("-".repeat(50));
        
        Scanner scanner = new Scanner(System.in);
        
        try (IFlowClient client = IFlowClient.create()) {
            client.connect().block();
            
            while (true) {
                System.out.print("\n你: ");
                String userInput = scanner.nextLine();
                
                if ("quit".equalsIgnoreCase(userInput) || 
                    "exit".equalsIgnoreCase(userInput) || 
                    "q".equalsIgnoreCase(userInput)) {
                    System.out.println("再见！");
                    break;
                }
                
                client.sendMessage(userInput).block();
                
                System.out.print("iFlow: ");
                client.receiveMessages()
                    .takeUntil(msg -> msg instanceof TaskFinishMessage)
                    .doOnNext(message -> {
                        if (message instanceof AssistantMessage) {
                            AssistantMessage assistantMsg = (AssistantMessage) message;
                            System.out.print(assistantMsg.getChunk().getText());
                        } else if (message instanceof TaskFinishMessage) {
                            System.out.println(); // 换行
                        }
                    })
                    .blockLast(); // 等待当前对话完成
            }
        }
    }
}

工具调用控制

import cn.iflow.sdk.types.config.IFlowOptions;
import cn.iflow.sdk.types.enums.PermissionMode;

public class ToolControlExample {
    public static void main(String[] args) throws Exception {
        IFlowOptions options = IFlowOptions.builder()
            .permissionMode(PermissionMode.AUTO)  // 自动批准工具调用
            .fileAccess(true)                     // 启用文件系统访问
            .fileReadOnly(false)                  // 允许文件写入
            .build();
            
        try (IFlowClient client = IFlowClient.create(options)) {
            client.connect().block();
            client.sendMessage("创建一个名为test.txt的文件，包含一些内容").block();
            
            client.receiveMessages()
                .doOnNext(message -> {
                    if (message instanceof AssistantMessage) {
                        AssistantMessage assistantMsg = (AssistantMessage) message;
                        System.out.print(assistantMsg.getChunk().getText());
                    } else if (message instanceof ToolCallMessage) {
                        ToolCallMessage toolCall = (ToolCallMessage) message;
                        System.out.println("工具请求: " + toolCall.getTitle());
                    } else if (message instanceof TaskFinishMessage) {
                        System.out.println("\n任务完成");
                    }
                })
                .blockLast(); // 等待流完成
        }
    }
}

高级配置

手动进程管理

如果需要手动管理 iFlow 进程：

import cn.iflow.sdk.types.config.IFlowOptions;

public class ManualProcessExample {
    public static void main(String[] args) throws Exception {
        // 禁用自动进程管理
        IFlowOptions options = IFlowOptions.builder()
            .autoStartProcess(false)
            .url("ws://localhost:8090/acp")  // 连接到已存在的 iFlow
            .build();
        
        try (IFlowClient client = IFlowClient.create(options)) {
            client.connect().block();
            client.sendMessage("你的问题").block();
            
            client.receiveMessages()
                .doOnNext(message -> {
                    if (message instanceof AssistantMessage) {
                        AssistantMessage assistantMsg = (AssistantMessage) message;
                        System.out.print(assistantMsg.getChunk().getText());
                    } else if (message instanceof TaskFinishMessage) {
                        System.out.println("\n对话完成");
                    }
                })
                .blockLast(); // 等待流完成
        }
    }
}

注意
手动模式需要您单独启动 iFlow：
iflow --experimental-acp --port 8090

错误处理

SDK 提供了详细的错误处理机制：

import cn.iflow.sdk.exceptions.*;

public class ErrorHandlingExample {
    public static void main(String[] args) {
        try (IFlowClient client = IFlowClient.create()) {
            client.connect().block();
            client.sendMessage("测试").block();
            
            client.receiveMessages()
                .doOnNext(message -> {
                    if (message instanceof AssistantMessage) {
                        AssistantMessage assistantMsg = (AssistantMessage) message;
                        System.out.print(assistantMsg.getChunk().getText());
                    } else if (message instanceof TaskFinishMessage) {
                        System.out.println("\n任务完成");
                    }
                })
                .doOnError(error -> {
                    if (error instanceof ConnectionException) {
                        System.err.println("连接错误: " + error.getMessage());
                    } else if (error instanceof TimeoutException) {
                        System.err.println("超时错误: " + error.getMessage());
                    } else {
                        System.err.println("未知错误: " + error.getMessage());
                    }
                })
                .blockLast(); // 等待流完成
        } catch (ConnectionException e) {
            System.err.println("连接错误: " + e.getMessage());
        } catch (Exception e) {
            System.err.println("未知错误: " + e.getMessage());
        }
    }
}

同步查询工具

对于需要同步调用的场景，可以使用查询工具类：

import cn.iflow.sdk.query.IFlowQuery;
import cn.iflow.sdk.types.config.IFlowOptions;
import java.time.Duration;
import java.util.List;

public class SyncQueryExample {
    public static void main(String[] args) throws Exception {
        // 同步调用，带超时控制
        IFlowOptions options = IFlowOptions.builder()
            .timeout(Duration.ofSeconds(30))
            .build();
            
        List<Message> response = IFlowQuery.querySync("你的问题", options);
        
        for (Message msg : response) {
            if (msg instanceof AssistantMessage) {
                System.out.println(((AssistantMessage) msg).getChunk().getText());
            }
        }
    }
}

API 参考

核心类

类名	描述
`IFlowClient`	主客户端类，管理与 iFlow 的连接
`IFlowOptions`	配置选项类，使用建造者模式
`IFlowQuery`	查询工具类，提供同步和异步查询方法

IFlowOptions 参数

IFlowOptions 类使用建造者模式配置 iFlow 客户端的行为:

核心连接参数

参数	类型	默认值	描述
`url`	`String`	`"ws://localhost:8090/acp"`	WebSocket 连接 URL
`autoStartProcess`	`boolean`	`true`	是否自动启动 iFlow 进程。设为 false 时需手动启动 iFlow
`processStartPort`	`int`	`8090`	自动启动 iFlow 进程时使用的起始端口号
`timeout`	`Duration`	`30秒`	连接和操作超时时间
`cwd`	`String`	当前工作目录	CLI 操作的工作目录

认证参数

参数	类型	默认值	描述
`authMethodId`	`String`	`"iflow"`	认证方法 ID (例如: "use_iflow_ak")
`authMethodInfo`	`AuthMethodInfo`	`null`	认证方法信息 (包含 apiKey, baseUrl, modelName 等)

工具执行控制参数

参数	类型	默认值	描述
`permissionMode`	`PermissionMode`	`MANUAL`	工具执行权限模式: AUTO(自动执行), MANUAL(需要确认), SELECTIVE(选择性自动)
`approvalMode`	`ApprovalMode`	`DEFAULT`	协议级别的批准模式: DEFAULT(标准确认), AUTO_EDIT(自动编辑), YOLO(自动执行), PLAN(计划模式)
`autoApproveTypes`	`List<String>`	`[]`	在选择性模式下自动批准的工具类型列表

文件系统访问参数

参数	类型	默认值	描述
`fileAccess`	`boolean`	`false`	是否启用文件系统访问(出于安全考虑默认禁用)
`fileAllowedDirs`	`List<String>`	`null`	允许 iFlow 访问的目录列表。null 表示仅当前目录
`fileReadOnly`	`boolean`	`false`	是否仅允许读取操作(启用时禁止写入)
`fileMaxSize`	`long`	`10485760`	读取操作允许的最大文件大小(字节),默认 10MB

MCP 服务器支持

参数	类型	默认值	描述
`mcpServers`	`List<McpServerConfig>`	`[]`	MCP 服务器配置列表，支持多种传输类型

消息类型

消息类型	描述	主要属性
`AssistantMessage`	AI 助手的文本响应	`chunk.text`, `agentId`, `timestamp`
`ToolCallMessage`	工具执行请求和状态	`label`, `status`, `toolName`, `content`, `agentId`
`PlanMessage`	结构化任务计划	`entries` (包含 `content`, `priority`, `status`)
`TaskFinishMessage`	任务完成信号	`stopReason`, `timestamp`
`UserMessage`	用户输入消息	`chunk.text`, `timestamp`
`ToolResultMessage`	工具执行结果	`toolCallId`, `content`, `agentId`
`ErrorMessage`	错误信息	`errorMessage`, `timestamp`

AgentInfo - 代理信息

AgentInfo 类提供了从 iFlow 代理ID 解析的详细信息：

属性	类型	描述
`agentId`	`String`	完整的代理ID
`agentIndex`	`Integer`	代理在任务中的索引
`taskId`	`String`	任务或实例ID
`timestamp`	`Long`	创建时间戳

AgentInfo 使用示例

import cn.iflow.sdk.types.protocol.AgentInfo;

// 从消息中获取代理信息
if (message instanceof AssistantMessage) {
    AssistantMessage assistantMsg = (AssistantMessage) message;
    AgentInfo agentInfo = assistantMsg.getAgentInfo();
    
    if (agentInfo != null) {
        System.out.println("代理ID: " + agentInfo.getAgentId());
        System.out.println("任务ID: " + agentInfo.getTaskId());
        System.out.println("代理索引: " + agentInfo.getAgentIndex());
        System.out.println("时间戳: " + agentInfo.getTimestamp());
    }
}

故障排除

连接问题

如果遇到连接错误，请检查：

iFlow 是否已安装
```
iflow --version
```

端口是否被占用

Linux/Mac
Windows

lsof -i :8090

netstat -an | findstr :8090

手动测试连接
```
iflow --experimental-acp --port 8090
```

超时问题

对于长时间运行的任务，可以增加超时时间：

import java.time.Duration;

IFlowOptions options = IFlowOptions.builder()
    .timeout(Duration.ofMinutes(10))  // 10分钟超时
    .build();
    
IFlowClient client = IFlowClient.create(options);

日志调试

启用详细日志以便调试：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class DebuggingExample {
    private static final Logger logger = LoggerFactory.getLogger(DebuggingExample.class);
    
    public static void main(String[] args) throws Exception {
        // 在 logback.xml 或 log4j2.xml 中配置日志级别为 DEBUG
        
        try (IFlowClient client = IFlowClient.create()) {
            logger.debug("开始连接到 iFlow");
            client.connect().block();
            logger.debug("连接成功");
            
            // 其他操作...
        }
    }
}

Maven 构建配置

确保您的 pom.xml 包含正确的Java版本配置：

<properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

概述​

系统要求​

安装​

1. 安装 iFlow CLI​

2. 添加 SDK 依赖​

快速开始​

基础示例​

简单查询​

核心概念​

IFlowClient​

响应式编程支持​

消息类型​

AssistantMessage - AI 助手响应​

ToolCallMessage - 工具调用​

PlanMessage - 任务计划​

TaskFinishMessage - 任务完成​

常见用例​

交互式聊天机器人​

工具调用控制​

高级配置​

手动进程管理​

错误处理​

同步查询工具​

API 参考​

核心类​

IFlowOptions 参数​

核心连接参数​

认证参数​

工具执行控制参数​

文件系统访问参数​

MCP 服务器支持​

消息类型​

AgentInfo - 代理信息​

AgentInfo 使用示例​

故障排除​

连接问题​

超时问题​

日志调试​

Maven 构建配置​

概述

系统要求

安装

1. 安装 iFlow CLI

2. 添加 SDK 依赖

快速开始

基础示例

简单查询

核心概念

IFlowClient

响应式编程支持

消息类型

AssistantMessage - AI 助手响应

ToolCallMessage - 工具调用

PlanMessage - 任务计划

TaskFinishMessage - 任务完成

常见用例

交互式聊天机器人

工具调用控制

高级配置

手动进程管理

错误处理

同步查询工具

API 参考

核心类

IFlowOptions 参数

核心连接参数

认证参数

工具执行控制参数

文件系统访问参数

MCP 服务器支持

消息类型

AgentInfo - 代理信息

AgentInfo 使用示例

故障排除

连接问题

超时问题

日志调试

Maven 构建配置