feat: unify blocking and streaming HTTP modes

Author: loong10k

src/main/java/io/github/easy4j/opencode/HttpResponseMode.java

@@ -0,0 +1,16 @@
+package io.github.easy4j.opencode;
+
+/**
+ * HTTP 对话响应模式。
+ */
+public enum HttpResponseMode {
+
+    /** 等待完整响应后一次性返回。 */
+    BLOCKING,
+
+    /** 消费 Provider SSE 并逐段回调。 */
+    STREAM,
+
+    /** 由调用方根据结构化输出等请求特征选择。 */
+    AUTO
+}

src/main/java/io/github/easy4j/opencode/OpenCodeClient.java

@@ -21,6 +21,7 @@
 import java.util.concurrent.ThreadPoolExecutor;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicInteger;
+import java.util.function.Consumer;
 
 /**
  * Facade client for OpenCode: HTTP Server + SSE event stream + local CLI.
@@ -233,6 +234,7 @@ public boolean isCliEnabled() {
     // ============================================================
 
     private void copyHttpConfig(OpenCodeHttpClientConfig src) {
+        this.config.getHttp().setMode(src.getMode());
         this.config.getHttp().setEnabled(src.isEnabled());
         this.config.getHttp().setStartupCheckEnabled(src.isStartupCheckEnabled());
         this.config.getHttp().setFailFastOnUnavailable(src.isFailFastOnUnavailable());
@@ -251,7 +253,7 @@ private void copyHttpConfig(OpenCodeHttpClientConfig src) {
         this.config.getHttp().setStreamMaxPoolSize(src.getStreamMaxPoolSize());
         this.config.getHttp().setStreamQueueCapacity(src.getStreamQueueCapacity());
         this.config.getHttp().setStreamKeepAliveMillis(src.getStreamKeepAliveMillis());
-        this.config.getHttp().setSseEventQueueCapacity(src.getSseEventQueueCapacity());
+        this.config.getHttp().setStreamEventQueueCapacity(src.getStreamEventQueueCapacity());
         this.config.getHttp().setRetryOnConnectionFailure(src.isRetryOnConnectionFailure());
         this.config.getHttp().setVerifySsl(src.isVerifySsl());
         this.config.getHttp().setDefaultModel(src.getDefaultModel());
@@ -367,10 +369,19 @@ public ChatStreamingResponse chatCompletionStream(ChatRequest request, String se
 
     public ChatStreamingResponse chatCompletionStream(ChatRequest request, String sessionKey,
                                                        OpenCodeRequestContext context) {
+        return chatCompletionStream(request, sessionKey, context, null);
+    }
+
+    /**
+     * 流式对话，并在订阅启动前绑定增量回调，避免丢失首批分片。
+     */
+    public ChatStreamingResponse chatCompletionStream(ChatRequest request, String sessionKey,
+                                                       OpenCodeRequestContext context,
+                                                       Consumer<String> deltaConsumer) {
         String sessionId = httpClient.ensureSession(sessionKey, context);
         PromptRequest promptRequest = ChatMessageMapper.toPromptRequest(request);
 
-        ChatStreamingResponse stream = new ChatStreamingResponse();
+        ChatStreamingResponse stream = new ChatStreamingResponse().onDelta(deltaConsumer);
 
         OpenCodeSseClient.QueueSubscription subscription =
                 sseClient.subscribeQueueSubscription(context);

src/main/java/io/github/easy4j/opencode/OpenCodeHttpClientConfig.java

@@ -16,6 +16,9 @@
 @Data
 public class OpenCodeHttpClientConfig {
 
+    /** 对话响应模式，默认保持兼容的完整响应模式。 */
+    private HttpResponseMode mode = HttpResponseMode.BLOCKING;
+
     /**
      * 是否启用 HTTP 子系统。
      * <p>为 false 时跳过 HTTP 客户端初始化和检查。</p>
@@ -102,14 +105,26 @@ public class OpenCodeHttpClientConfig {
     /** 流式事件处理线程空闲保活时间（毫秒）。 */
     private long streamKeepAliveMillis = 60_000L;
 
-    /** 单个 SSE 订阅的事件缓存上限。 */
-    private int sseEventQueueCapacity = 1_024;
+    /** 单个流式订阅的事件缓存上限。 */
+    private int streamEventQueueCapacity = 1_024;
 
     /**
      * 遇到失效连接等传输故障时是否允许 OkHttp 自动恢复。
      */
     private boolean retryOnConnectionFailure = true;
 
+    /** @deprecated 使用 {@link #getStreamEventQueueCapacity()}。 */
+    @Deprecated
+    public int getSseEventQueueCapacity() {
+        return streamEventQueueCapacity;
+    }
+
+    /** @deprecated 使用 {@link #setStreamEventQueueCapacity(int)}。 */
+    @Deprecated
+    public void setSseEventQueueCapacity(int value) {
+        this.streamEventQueueCapacity = value;
+    }
+
     /**
      * 是否校验 HTTPS 证书；为 false 时关闭校验（仅建议开发环境）。
      */

src/main/java/io/github/easy4j/opencode/api/OpenCodeSseClient.java

@@ -126,7 +126,7 @@ public BlockingQueue<Event> subscribeQueue(OpenCodeRequestContext context) {
 
     public QueueSubscription subscribeQueueSubscription(OpenCodeRequestContext context) {
         BlockingQueue<Event> queue = new ArrayBlockingQueue<>(
-                Math.max(1, config.getSseEventQueueCapacity()));
+                Math.max(1, config.getStreamEventQueueCapacity()));
         EventSource source = subscribe(event -> offerLatest(queue, event), context);
         return new QueueSubscription(queue, source);
     }

src/test/java/io/github/easy4j/opencode/OpenCodeHttpClientConfigTest.java

@@ -12,6 +12,7 @@ class OpenCodeHttpClientConfigTest {
     @Test
     void shouldHaveCorrectDefaults() {
         OpenCodeHttpClientConfig config = new OpenCodeHttpClientConfig();
+        assertEquals(HttpResponseMode.BLOCKING, config.getMode());
         assertTrue(config.isEnabled());
         assertFalse(config.isStartupCheckEnabled());
         assertFalse(config.isFailFastOnUnavailable());
@@ -30,7 +31,7 @@ void shouldHaveCorrectDefaults() {
         assertEquals(32, config.getStreamMaxPoolSize());
         assertEquals(128, config.getStreamQueueCapacity());
         assertEquals(60_000L, config.getStreamKeepAliveMillis());
-        assertEquals(1_024, config.getSseEventQueueCapacity());
+        assertEquals(1_024, config.getStreamEventQueueCapacity());
         assertTrue(config.isRetryOnConnectionFailure());
         assertTrue(config.isVerifySsl());
         assertNull(config.getDefaultModel());
@@ -50,4 +51,11 @@ void shouldResolveEmptyPasswordWhenNull() {
         assertNull(config.getPassword());
         assertEquals("", config.resolvePassword());
     }
+
+    @Test
+    void shouldKeepLegacySseEventQueueAlias() {
+        OpenCodeHttpClientConfig config = new OpenCodeHttpClientConfig();
+        config.setSseEventQueueCapacity(17);
+        assertEquals(17, config.getStreamEventQueueCapacity());
+    }
 }