Skip to Content
开发者指南Java SDK（Alpha）

Qwen Code Java SDK

Qwen Code Java SDK 是一个用于程序化访问 Qwen Code 功能的最小实验性 SDK。它提供了与 Qwen Code CLI 交互的 Java 接口，使开发者能够将 Qwen Code 的能力集成到 Java 应用程序中。

环境要求

  • Java >= 1.8
  • Maven >= 3.6.0（从源码构建时必需）
  • qwen-code >= 0.5.0

依赖项

  • 日志: ch.qos.logback:logback-classic
  • 工具库: org.apache.commons:commons-lang3
  • JSON 处理: com.alibaba.fastjson2:fastjson2
  • 测试: JUnit 5 (org.junit.jupiter:junit-jupiter)

安装

在 Maven pom.xml 中添加以下依赖：

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>qwencode-sdk</artifactId>
    <version>{$version}</version>
</dependency>

如果使用 Gradle，则在 build.gradle 中添加：

implementation 'com.alibaba:qwencode-sdk:{$version}'

构建与运行

构建命令

# 编译项目
mvn compile
 
# 运行测试
mvn test
 
# 打包 JAR
mvn package
 
# 安装到本地仓库
mvn install

快速开始

使用 SDK 最简单的方式是通过 QwenCodeCli.simpleQuery() 方法：

public static void runSimpleExample() {
    List<String> result = QwenCodeCli.simpleQuery("hello world");
    result.forEach(logger::info);
}

更高级的用法，可以自定义传输选项：

public static void runTransportOptionsExample() {
    TransportOptions options = new TransportOptions()
            .setModel("qwen3-coder-flash")
            .setPermissionMode(PermissionMode.AUTO_EDIT)
            .setCwd("./")
            .setEnv(new HashMap<String, String>() {{put("CUSTOM_VAR", "value");}})
            .setIncludePartialMessages(true)
            .setTurnTimeout(new Timeout(120L, TimeUnit.SECONDS))
            .setMessageTimeout(new Timeout(90L, TimeUnit.SECONDS))
            .setAllowedTools(Arrays.asList("read_file", "write_file", "list_directory"));
 
    List<String> result = QwenCodeCli.simpleQuery("who are you, what are your capabilities?", options);
    result.forEach(logger::info);
}

流式内容处理，可自定义内容消费者：

public static void runStreamingExample() {
    QwenCodeCli.simpleQuery("who are you, what are your capabilities?",
            new TransportOptions().setMessageTimeout(new Timeout(10L, TimeUnit.SECONDS)), new AssistantContentSimpleConsumers() {
 
                @Override
                public void onText(Session session, TextAssistantContent textAssistantContent) {
                    logger.info("Text content received: {}", textAssistantContent.getText());
                }
 
                @Override
                public void onThinking(Session session, ThinkingAssistantContent thinkingAssistantContent) {
                    logger.info("Thinking content received: {}", thinkingAssistantContent.getThinking());
                }
 
                @Override
                public void onToolUse(Session session, ToolUseAssistantContent toolUseContent) {
                    logger.info("Tool use content received: {} with arguments: {}",
                            toolUseContent, toolUseContent.getInput());
                }
 
                @Override
                public void onToolResult(Session session, ToolResultAssistantContent toolResultContent) {
                    logger.info("Tool result content received: {}", toolResultContent.getContent());
                }
 
                @Override
                public void onOtherContent(Session session, AssistantContent<?> other) {
                    logger.info("Other content received: {}", other);
                }
 
                @Override
                public void onUsage(Session session, AssistantUsage assistantUsage) {
                    logger.info("Usage information received: Input tokens: {}, Output tokens: {}",
                            assistantUsage.getUsage().getInputTokens(), assistantUsage.getUsage().getOutputTokens());
                }
            }.setDefaultPermissionOperation(Operation.allow));
    logger.info("Streaming example completed.");
}

更多示例请参考 src/test/java/com/alibaba/qwen/code/cli/example

架构

SDK 采用分层架构：

  • API 层：通过 QwenCodeCli 类提供主要入口，包含简单静态方法供基本使用
  • 会话层：通过 Session 类管理与 Qwen Code CLI 的通信会话
  • 传输层：处理 SDK 与 CLI 进程之间的通信机制（当前使用基于进程传输的 ProcessTransport）
  • 协议层：根据 CLI 协议定义通信所需的数据结构
  • 工具类：提供并发执行、超时处理、错误管理的通用工具

主要特性

权限模式

SDK 支持多种权限模式来控制工具的执行：

  • default：写入工具默认被拒绝，除非通过 canUseTool 回调或在 allowedTools 中批准。只读工具无需确认即可执行。
  • plan：阻止所有写入工具，指示 AI 先提出计划。
  • auto-edit：自动批准编辑工具（edit、write_file、notebook_edit），其他工具需要确认。
  • yolo：所有工具自动执行，无需确认。

会话事件消费者与助手内容消费者

SDK 提供了两个关键接口来处理来自 CLI 的事件和内容：

SessionEventConsumers 接口

SessionEventConsumers 接口提供了在会话期间处理不同类型消息的回调：

  • onSystemMessage：处理来自 CLI 的系统消息（接收 Session 和 SDKSystemMessage）
  • onResultMessage：处理来自 CLI 的结果消息（接收 Session 和 SDKResultMessage）
  • onAssistantMessage：处理助手消息（AI 响应）（接收 Session 和 SDKAssistantMessage）
  • onPartialAssistantMessage：处理流式响应期间的局部助手消息（接收 Session 和 SDKPartialAssistantMessage）
  • onUserMessage：处理用户消息（接收 Session 和 SDKUserMessage）
  • onOtherMessage：处理其他类型的消息（接收 Session 和 String 消息）
  • onControlResponse：处理控制响应（接收 Session 和 CLIControlResponse）
  • onControlRequest：处理控制请求（接收 Session 和 CLIControlRequest，返回 CLIControlResponse）
  • onPermissionRequest：处理权限请求（接收 Session 和 CLIControlRequest，返回 Behavior）

AssistantContentConsumers 接口

AssistantContentConsumers 接口处理助手消息中不同类型的内容：

  • onText：处理文本内容（接收 Session 和 TextAssistantContent）
  • onThinking：处理思考内容（接收 Session 和 ThinkingAssistantContent）
  • onToolUse：处理工具使用内容（接收 Session 和 ToolUseAssistantContent）
  • onToolResult：处理工具结果内容（接收 Session 和 ToolResultAssistantContent）
  • onOtherContent：处理其他内容类型（接收 Session 和 AssistantContent）
  • onUsage：处理用量信息（接收 Session 和 AssistantUsage）
  • onPermissionRequest：处理权限请求（接收 Session 和 CLIControlPermissionRequest，返回 Behavior）
  • onOtherControlRequest：处理其他控制请求（接收 Session 和 ControlRequestPayload，返回 ControlResponsePayload）

接口之间的关系

事件层级的重要说明：

  • SessionEventConsumers 是高层事件处理器，处理不同的消息类型（系统、助手、用户等）
  • AssistantContentConsumers 是底层内容处理器，处理助手消息中不同类型的内容（文本、工具、思考等）

处理器关系：

  • SessionEventConsumers → AssistantContentConsumers（SessionEventConsumers 使用 AssistantContentConsumers 来处理助手消息中的内容）

事件派生关系：

  • onAssistantMessage → onText、onThinking、onToolUse、onToolResult、onOtherContent、onUsage
  • onPartialAssistantMessage → onText、onThinking、onToolUse、onToolResult、onOtherContent
  • onControlRequest → onPermissionRequest、onOtherControlRequest

事件超时关系：

每个事件处理方法都有一个对应的超时方法，允许自定义该事件的超时行为：

  • onSystemMessage ↔ onSystemMessageTimeout
  • onResultMessage ↔ onResultMessageTimeout
  • onAssistantMessage ↔ onAssistantMessageTimeout
  • onPartialAssistantMessage ↔ onPartialAssistantMessageTimeout
  • onUserMessage ↔ onUserMessageTimeout
  • onOtherMessage ↔ onOtherMessageTimeout
  • onControlResponse ↔ onControlResponseTimeout
  • onControlRequest ↔ onControlRequestTimeout

对于 AssistantContentConsumers 的超时方法：

  • onText ↔ onTextTimeout
  • onThinking ↔ onThinkingTimeout
  • onToolUse ↔ onToolUseTimeout
  • onToolResult ↔ onToolResultTimeout
  • onOtherContent ↔ onOtherContentTimeout
  • onPermissionRequest ↔ onPermissionRequestTimeout
  • onOtherControlRequest ↔ onOtherControlRequestTimeout

默认超时值：

  • SessionEventSimpleConsumers 默认超时：180 秒（Timeout.TIMEOUT_180_SECONDS）
  • AssistantContentSimpleConsumers 默认超时：60 秒（Timeout.TIMEOUT_60_SECONDS）

超时层级要求：

为了正常运行，应保持以下超时关系：

  • onAssistantMessageTimeout 返回值应大于 onTextTimeout、onThinkingTimeout、onToolUseTimeout、onToolResultTimeout 和 onOtherContentTimeout 的返回值
  • onControlRequestTimeout 返回值应大于 onPermissionRequestTimeout 和 onOtherControlRequestTimeout 的返回值

传输选项

TransportOptions 类允许配置 SDK 与 Qwen Code CLI 的通信方式：

  • pathToQwenExecutable：Qwen Code CLI 可执行文件的路径
  • cwd：CLI 进程的工作目录
  • model：会话使用的 AI 模型
  • permissionMode：控制工具执行的权限模式
  • env：传递给 CLI 进程的环境变量
  • maxSessionTurns：限制会话中的对话轮次
  • coreTools：AI 可用的核心工具列表
  • excludeTools：要从可用工具中排除的工具列表
  • allowedTools：预先批准无需额外确认即可使用的工具列表
  • authType：会话使用的认证类型
  • includePartialMessages：启用流式响应期间接收局部消息
  • turnTimeout：完整对话轮次的超时时间
  • messageTimeout：单条消息在轮次内的超时时间
  • resumeSessionId：要恢复的先前会话的 ID
  • otherOptions：传递给 CLI 的其他命令行选项

会话控制功能

  • 创建会话：使用 QwenCodeCli.newSession() 创建带有自定义选项的新会话
  • 会话管理：Session 类提供发送提示、处理响应和管理会话状态的方法
  • 会话清理：始终使用 session.close() 关闭会话以正确终止 CLI 进程
  • 会话恢复：在 TransportOptions 中使用 setResumeSessionId() 恢复之前的会话
  • 会话中断：使用 session.interrupt() 中断当前正在运行的提示
  • 动态模型切换：使用 session.setModel() 在会话期间切换模型
  • 动态权限模式切换：使用 session.setPermissionMode() 在会话期间切换权限模式

线程池配置

SDK 使用线程池来管理并发操作，默认配置如下：

  • 核心线程数：30
  • 最大线程数：100
  • 线程存活时间：60 秒
  • 队列容量：300 个任务（使用 LinkedBlockingQueue）
  • 线程命名前缀：“qwen_code_cli-pool-{number}”
  • 守护线程：false
  • 拒绝执行处理器：CallerRunsPolicy

错误处理

SDK 针对不同错误场景提供了特定的异常类型：

  • SessionControlException：会话控制（创建、初始化等）出现问题时抛出
  • SessionSendPromptException：发送提示或接收响应出现问题时抛出
  • SessionClosedException：尝试使用已关闭的会话时抛出

常见问题 / 故障排除

Q: 是否需要单独安装 Qwen CLI？

A: 是的，需要安装 Qwen CLI 0.5.5 或更高版本。

Q: 支持哪些 Java 版本？

A: SDK 需要 Java 1.8 或更高版本。

Q: 如何处理长时间运行的请求？

A: SDK 包含超时工具。可以通过 TransportOptions 中的 Timeout 类配置超时。

Q: 为什么某些工具没有执行？

A: 这很可能是由于权限模式所致。请检查权限模式设置，并考虑使用 allowedTools 预先批准某些工具。

Q: 如何恢复之前的会话？

A: 使用 TransportOptions 中的 setResumeSessionId() 方法恢复之前的会话。

Q: 能否自定义 CLI 进程的环境？

A: 可以，使用 TransportOptions 中的 setEnv() 方法将环境变量传递给 CLI 进程。

许可证

Apache-2.0 - 详情请参见 LICENSE。

Last updated on
TypeScript SDK简介