qwen-code/packages/sdk-java/QWEN.md

Qwen Code Java SDK

Project Overview

The Qwen Code Java SDK is a minimum experimental SDK for programmatic access to Qwen Code functionality. It provides a Java interface to interact with the Qwen Code CLI, allowing developers to integrate Qwen Code capabilities into their Java applications.

The project is structured as a Maven-based Java library with the following key characteristics:

• Group ID: com.alibaba
• Artifact ID: qwencode-sdk-java
• Version: 0.0.1
• Packaging: JAR
• Java Version: 1.8+ (source and target)

Architecture

The SDK follows a layered architecture:

• CLI Layer: Provides the main entry point through QwenCodeCli class
• Session Layer: Manages communication sessions with the Qwen Code CLI
• Transport Layer: Handles communication between the SDK and CLI process
• Protocol Layer: Defines data structures for communication
• Utils: Common utilities for concurrent execution and timeout handling

Key Components

Main Classes

• QwenCodeCli: Main entry point with static methods for simple queries
• Session: Manages communication sessions with the CLI
• Transport: Abstracts the communication mechanism (currently using process transport)
• ProcessTransport: Implementation that communicates via process execution

Dependencies

• Logging: ch.qos.logback:logback-classic
• Utilities: org.apache.commons:commons-lang3
• JSON Processing: com.alibaba.fastjson2:fastjson2
• Testing: JUnit 5 (org.junit.jupiter:junit-jupiter)

Building and Running

Prerequisites

• Java 8 or higher
• Apache Maven 3.6.0 or higher

Build Commands

# Compile the project
mvn compile

# Run tests
mvn test

# Package the JAR
mvn package

# Install to local repository
mvn install

# Run checkstyle verification
mvn checkstyle:check

Testing

The project includes basic unit tests using JUnit 5. The main test class QwenCodeCliTest demonstrates how to use the SDK to make simple queries to the Qwen Code CLI.

Code Quality

The project uses Checkstyle for code formatting and style enforcement. The configuration is defined in checkstyle.xml and includes rules for:

• Whitespace and indentation
• Naming conventions
• Import ordering
• Code structure

Development Conventions

Coding Standards

• Java 8 language features are supported
• Follow standard Java naming conventions
• Use UTF-8 encoding for source files
• Line endings should be LF (Unix-style)
• No trailing whitespace allowed
• Use 8-space indentation for line wrapping

Testing Practices

• Write unit tests using JUnit 5
• Test classes should be in the src/test/java directory
• Follow the naming convention *Test.java for test classes
• Use appropriate assertions to validate functionality

Documentation

• API documentation should follow JavaDoc conventions
• Update README files when adding new features
• Include examples in documentation

API Reference

QwenCodeCli Class

The main class provides two primary methods:

• simpleQuery(String prompt): Synchronous method that returns a list of responses
• simpleQuery(String prompt, Consumer<String> messageConsumer): Asynchronous method that streams responses to a consumer

Permission Modes

The SDK supports different permission modes for controlling tool execution:

• default: Write tools are denied unless approved via canUseTool callback or in allowedTools. Read-only tools execute without confirmation.
• plan: Blocks all write tools, instructing AI to present a plan first.
• auto-edit: Auto-approve edit tools (edit, write_file) while other tools require confirmation.
• yolo: All tools execute automatically without confirmation.

Usage Example

import com.alibaba.qwen.code.cli.QwenCodeCli;
import java.util.List;

public class Example {
    public static void main(String[] args) {
        List<String> result = QwenCodeCli.simpleQuery("hello world");
        result.forEach(System.out::println);
    }
}

Project Structure

src/
├── main/
│   └── java/
│       └── com/
│           └── alibaba/
│               └── qwen/
│                   └── code/
│                       └── cli/
│                           ├── QwenCodeCli.java
│                           ├── protocol/
│                           ├── session/
│                           ├── transport/
│                           └── utils/
└── test/
    └── java/
        └── com/
            └── alibaba/
                └── qwen/
                    └── code/
                        └── cli/
                            └── QwenCodeCliTest.java

Configuration Files

• pom.xml: Maven build configuration and dependencies
• checkstyle.xml: Code style and formatting rules
• .editorconfig: Editor configuration settings

License

Apache-2.0 - see LICENSE for details.