# opencode-java-sdk

**Repository Path**: tianchaixiaoniuniu/opencode-java-sdk

## Basic Information

- **Project Name**: opencode-java-sdk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-12
- **Last Updated**: 2026-02-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenCode Java SDK

适用于 OpenCode 的 Java SDK - 开源 AI 编程助手。

## 概述

本 SDK 提供了一个类型安全的 Java 客户端，用于与 OpenCode 服务器进行交互。它支持所有 OpenCode API，并能无缝集成到 Spring Boot 应用程序中。

## 功能特性

- 完整的 OpenCode API 支持
- 基于 Project Reactor 的响应式非阻塞 API
- Spring Boot 自动配置
- 配置属性支持
- 身份验证支持
- 连接池和超时配置
- 自动重试机制

## 安装

### Maven

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

```xml
<dependency>
    <groupId>ai.opencode</groupId>
    <artifactId>opencode-java-sdk</artifactId>
    <version>1.0.0</version>
</dependency>
```

### Gradle

在 `build.gradle` 中添加以下依赖：

```groovy
implementation 'ai.opencode:opencode-java-sdk:1.0.0'
```

## 快速开始

### 1. 配置 OpenCode

在 `application.yml` 中添加以下配置：

```yaml
opencode:
  sdk:
    base-url: http://localhost:4096
    connection-timeout: 5000      # 连接超时（毫秒）
    request-timeout: 30000        # 请求超时（毫秒）
    username: opencode            # 用户名（可选）
    password: your-password       # 密码（可选）
```

### 2. 在 Spring Boot 应用中使用

```java
import ai.opencode.sdk.client.OpenCodeClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Mono;

@RestController
@RequestMapping("/api/opencode")
public class OpenCodeController {

    @Autowired
    private OpenCodeClient openCodeClient;

    @GetMapping("/health")
    public Mono<HealthResponse> health() {
        return openCodeClient.getHealth();
    }

    @PostMapping("/sessions")
    public Mono<Session> createSession(@RequestParam String title) {
        return openCodeClient.createSession(title);
    }

    @PostMapping("/sessions/{sessionId}/message")
    public Mono<MessageResponse> sendMessage(
            @PathVariable String sessionId,
            @RequestParam String message) {
        return openCodeClient.sendMessage(sessionId, message);
    }
}
```

### 3. 独立使用（非 Spring Boot 项目）

```java
import ai.opencode.sdk.config.OpenCodeProperties;
import ai.opencode.sdk.client.OpenCodeClient;
import com.fasterxml.jackson.databind.ObjectMapper;

// 配置
OpenCodeProperties properties = new OpenCodeProperties();
properties.setBaseUrl("http://localhost:4096");
properties.setConnectionTimeout(5000);
properties.setRequestTimeout(30000);

// 创建客户端
ObjectMapper objectMapper = new ObjectMapper();
OpenCodeClient client = new OpenCodeClient(properties, objectMapper);

// 使用
HealthResponse health = client.getHealthSync();
System.out.println("服务器版本: " + health.getVersion());

Session session = client.createSession("我的会话").block();
System.out.println("会话 ID: " + session.getId());
```

## API 参考

### 健康检查

```java
// 异步方式
Mono<HealthResponse> health = openCodeClient.getHealth();

// 同步方式
HealthResponse health = openCodeClient.getHealthSync();
```

### 项目管理

```java
// 列出所有项目
Mono<List<Project>> projects = openCodeClient.listProjects();

// 获取当前项目
Mono<Project> currentProject = openCodeClient.getCurrentProject();
```

### 会话管理

```java
// 创建新会话
Mono<Session> session = openCodeClient.createSession("我的会话");

// 列出所有会话
Mono<List<Session>> sessions = openCodeClient.listSessions();

// 获取指定会话
Mono<Session> session = openCodeClient.getSession("session-id");

// 删除会话
Mono<Boolean> deleted = openCodeClient.deleteSession("session-id");
```

### 消息发送

```java
// 发送简单消息
Mono<MessageResponse> response = openCodeClient.sendMessage("session-id", "你好！");

// 发送完全控制的消息
SendMessageRequest request = SendMessageRequest.builder()
    .parts(List.of(new Part("text", "解释 Java Stream 的用法")))
    .model(new ModelInfo("anthropic", "claude-3-5-sonnet"))
    .build();
Mono<MessageResponse> response = openCodeClient.sendMessage("session-id", request);

// 中止运行中的会话
Mono<Boolean> aborted = openCodeClient.abortSession("session-id");
```

### 文件操作

```java
// 在文件中搜索文本
Mono<List<TextSearchResult>> results = openCodeClient.searchText("function.*opencode");

// 按名称查找文件
Mono<List<String>> files = openCodeClient.findFiles("*.java");

// 读取文件内容
Mono<FileContent> content = openCodeClient.readFile("src/main/java/App.java");
```

### 配置管理

```java
// 获取当前配置
Mono<Config> config = openCodeClient.getConfig();

// 列出可用的 providers
Mono<ProvidersResponse> providers = openCodeClient.listProviders();
```

### 身份验证

```java
// 为 provider 设置身份验证
AuthCredentials credentials = AuthCredentials.builder()
    .type("api")
    .apiKey("your-api-key")
    .build();

Mono<Boolean> result = openCodeClient.setAuth("anthropic", credentials);
```

### 日志记录

```java
// 写入日志条目
Mono<Boolean> logged = openCodeClient.writeLog("my-app", "info", "操作已完成");
```

### TUI 控制

```java
// 向提示符追加文本
Mono<Boolean> appended = openCodeClient.appendPrompt("你的文本");

// 提交提示符
Mono<Boolean> submitted = openCodeClient.submitPrompt();

// 显示 toast 通知
Mono<Boolean> shown = openCodeClient.showToast("任务完成", "success");
```

## 高级用法

### 自定义 WebClient

如果需要自定义 WebClient：

```java
@Bean
public WebClient.Builder openCodeWebClientBuilder(OpenCodeProperties properties) {
    HttpClient httpClient = HttpClient.create()
        .responseTimeout(Duration.ofMinutes(5))
        .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 10000);

    return WebClient.builder()
        .baseUrl(properties.getBaseUrl())
        .clientConnector(new ReactorClientHttpConnector(httpClient))
        .defaultHeader("X-Custom-Header", "value");
}
```

### 错误处理

```java
openCodeClient.getHealth()
    .doOnSuccess(response -> System.out.println("健康状态: " + response.isHealthy()))
    .doOnError(error -> {
        if (error instanceof WebClientResponseException) {
            WebClientResponseException ex = (WebClientResponseException) error;
            System.err.println("HTTP 状态码: " + ex.getStatusCode());
            System.err.println("响应内容: " + ex.getResponseBodyAsString());
        } else {
            System.err.println("错误: " + error.getMessage());
        }
    })
    .subscribe();
```

### 响应式流

```java
// 使用 Flux 处理多个项目
openCodeClient.listSessions()
    .flatMapMany(Flux::fromIterable)
    .filter(session -> "active".equals(session.getStatus()))
    .subscribe(session -> System.out.println("活跃会话: " + session.getId()));

// 使用 Mono 处理单个项目
openCodeClient.getSession("session-id")
    .map(Session::getTitle)
    .subscribe(title -> System.out.println("会话标题: " + title));
```

## 配置属性

| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `opencode.sdk.base-url` | String | `http://localhost:4096` | OpenCode 服务器的基础 URL |
| `opencode.sdk.connection-timeout` | int | `5000` | 连接超时时间（毫秒） |
| `opencode.sdk.request-timeout` | int | `30000` | 请求超时时间（毫秒） |
| `opencode.sdk.username` | String | - | HTTP 基本认证的用户名 |
| `opencode.sdk.password` | String | - | HTTP 基本认证的密码 |
| `opencode.sdk.auto-reconnect` | boolean | `false` | 启用自动重连 |
| `opencode.sdk.max-retries` | int | `3` | 最大重试次数 |
| `opencode.sdk.default-provider` | String | - | 默认 provider ID |
| `opencode.sdk.default-model` | String | - | 默认模型 ID |
| `opencode.sdk.validate-ssl` | boolean | `true` | 是否验证 SSL 证书 |

## 环境要求

- Java 17 或更高版本
- Spring Boot 3.2.0 或更高版本（可选，用于自动配置）

## 构建

```bash
# 构建 SDK
mvn clean install

# 运行测试
mvn test

# 生成 JavaDoc
mvn javadoc:javadoc
```

## 发布

```bash
# 发布到 Maven Central
mvn clean deploy -P release
```

## 贡献指南

1. Fork 本仓库
2. 创建功能分支
3. 提交你的更改
4. 推送到分支
5. 提交 Pull Request

## 许可证

MIT 许可证 - 详情请参阅 [LICENSE](LICENSE) 文件。

## 技术支持

- 官方文档: https://opencode.ai/docs/
- GitHub: https://github.com/anomalyco/opencode
- Discord: https://opencode.ai/discord