feat: restore okhttp3-extension 2.0.x.20260630 dep + sync WS enhancements from 1.0.x

- Restore okhttp3-extension dependency (release 2.0.x.20260630)
- OpenClawDebugConfig: restore HttpLogLevel from okhttp3-extension
- Sync all WS protocol enhancements, debug config, integration tests

Author: loong10k

pom.xml

@@ -473,6 +473,7 @@
         <junit-jupiter.version>5.11.4</junit-jupiter.version>
         <lombok.version>1.18.46</lombok.version>
         <okhttp3.version>4.12.0</okhttp3.version>
+        <okhttp3-extension.version>2.0.x.20260630</okhttp3-extension.version>
         <slf4j.version>2.0.18</slf4j.version>
         <!-- Maven Plugin versions -->
         <maven-central-publishing-plugin.version>0.11.0</maven-central-publishing-plugin.version>
@@ -513,6 +514,12 @@
                 <artifactId>mockwebserver</artifactId>
                 <version>${okhttp3.version}</version>
             </dependency>
+            <!-- For OkHttp Extension -->
+            <dependency>
+                <groupId>io.github.easy4j</groupId>
+                <artifactId>okhttp3-extension</artifactId>
+                <version>${okhttp3-extension.version}</version>
+            </dependency>
             <!-- For Websocket -->
             <dependency>
                 <groupId>org.java-websocket</groupId>
@@ -613,5 +620,10 @@
             <artifactId>mockwebserver</artifactId>
             <scope>test</scope>
         </dependency>
+            <!-- For OkHttp Extension -->
+            <dependency>
+                <groupId>io.github.easy4j</groupId>
+                <artifactId>okhttp3-extension</artifactId>
+            </dependency>
     </dependencies>
 </project>

src/main/java/io/github/easy4j/openclaw/OpenClawDebugConfig.java

@@ -1,20 +1,21 @@
 package io.github.easy4j.openclaw;
 
 import lombok.Data;
+import okhttp3.extension.logging.HttpLogLevel;
 
 /**
  * OpenClaw SDK 统一调试配置，用于控制生命周期、请求头和正文日志。
  *
  * <p>调试默认关闭。正文日志始终受长度限制，认证头和敏感令牌仍由客户端脱敏。</p>
  *
- * <p>{@link #level} 字段使用字符串表示日志级别。可选值：
+ * <p>{@link #level} 使用 {@link HttpLogLevel} 表示日志级别。可选值：
  * <ul>
  *     <li>{@code "NONE"} — 不输出</li>
  *     <li>{@code "BASIC"} — 仅方法/路径/状态/耗时</li>
  *     <li>{@code "HEADERS"} — BASIC + 请求/响应头</li>
  *     <li>{@code "BODY"} — HEADERS + 请求/响应正文（受 {@link #maxContentLength} 限制）</li>
  * </ul>
- * 当 classpath 上有 {@code io.github.easy4j:okhttp3-extension} 时，{@link #level} 会按相同语义传递给底层日志拦截器；否则仅用于 SDK 自身 DEBUG 输出。</p>
+ * 该类型继续作为 SDK 的公共 API，避免升级 SDK 后破坏既有调用方的源码和二进制兼容性。</p>
  *
  * @author <a href="https://github.com/loong10k">Loong Wan</a>
  * @since 1.0.0
@@ -25,26 +26,47 @@ public class OpenClawDebugConfig {
     /** 是否允许 SDK 输出调试诊断信息。 */
     private boolean enabled;
 
-    /**
-     * 启用调试后的详细程度；字符串常量，对齐 {@code okhttp3.extension.logging.HttpLogLevel}。
-     */
-    private String level = "BASIC";
+    /** 启用调试后的详细程度。 */
+    private HttpLogLevel level = HttpLogLevel.BASIC;
 
     /** BODY 级别单项正文允许记录的最大字符数。 */
     private int maxContentLength = 2_000;
 
     /**
      * 判断指定级别的日志是否允许输出。
-     * <p>简单的字符串排序：{@code NONE &lt; BASIC &lt; HEADERS &lt; BODY}。</p>
+     * @param required 待输出信息要求的最低级别
+     * @return 调试已启用且当前级别满足要求时返回 {@code true}
+     */
+    public boolean allows(HttpLogLevel required) {
+        return enabled && level != null && required != null && level.allows(required);
+    }
+
+    /**
+     * 兼容短期使用字符串级别的调用方。
      *
-     * @param required 待输出信息要求的最低级别（字符串）
+     * @param required 待输出信息要求的最低级别名称
      * @return 调试已启用且当前级别满足要求时返回 {@code true}
      */
     public boolean allows(String required) {
-        if (!enabled || level == null || required == null) {
-            return false;
-        }
-        return rank(level) >= rank(required);
+        return required != null && allows(resolveLevel(required));
+    }
+
+    /**
+     * 设置日志级别，保持旧版 SDK 公共 API 的源码与二进制兼容性。
+     *
+     * @param level 日志级别
+     */
+    public void setLevel(HttpLogLevel level) {
+        this.level = level;
+    }
+
+    /**
+     * 兼容 Spring 配置及短期使用字符串级别的调用方。
+     *
+     * @param level 日志级别名称
+     */
+    public void setLevel(String level) {
+        this.level = resolveLevel(level);
     }
 
     /**
@@ -56,13 +78,14 @@ public int resolveMaxContentLength() {
         return Math.max(1, maxContentLength);
     }
 
-    private static int rank(String level) {
-        switch (level.toUpperCase()) {
-            case "BODY":    return 3;
-            case "HEADERS": return 2;
-            case "BASIC":   return 1;
-            case "NONE":    return 0;
-            default:        return 1;
+    private static HttpLogLevel resolveLevel(String level) {
+        if (level == null) {
+            return HttpLogLevel.BASIC;
+        }
+        try {
+            return HttpLogLevel.valueOf(level.trim().toUpperCase());
+        } catch (IllegalArgumentException ex) {
+            return HttpLogLevel.BASIC;
         }
     }
-}
+}

src/test/java/io/github/easy4j/openclaw/OpenClawHttpClientConfigTest.java

@@ -1,5 +1,6 @@
 package io.github.easy4j.openclaw;
 
+import okhttp3.extension.logging.HttpLogLevel;
 import org.junit.jupiter.api.Test;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
@@ -11,7 +12,14 @@ void debugLoggingIsOptIn() {
         OpenClawHttpClientConfig config = new OpenClawHttpClientConfig();
         org.junit.jupiter.api.Assertions.assertFalse(config.getDebug().isEnabled());
         org.junit.jupiter.api.Assertions.assertEquals(2_000, config.getDebug().getMaxContentLength());
-        org.junit.jupiter.api.Assertions.assertEquals("BASIC",
+        org.junit.jupiter.api.Assertions.assertEquals(HttpLogLevel.BASIC,
+                config.getDebug().getLevel());
+
+        config.getDebug().setLevel(HttpLogLevel.BODY);
+        org.junit.jupiter.api.Assertions.assertEquals(HttpLogLevel.BODY,
+                config.getDebug().getLevel());
+        config.getDebug().setLevel("HEADERS");
+        org.junit.jupiter.api.Assertions.assertEquals(HttpLogLevel.HEADERS,
                 config.getDebug().getLevel());
     }