sync: cherry-pick changes from feature/3.0.x

Author: loong10k

src/main/java/io/github/easy4j/opencli/OpenCliClient.java

@@ -23,9 +23,18 @@
 import lombok.Getter;
 
 /**
- * OpenCLI Java SDK 入口：持有一组运行时配置与共享 {@link OpenCliExecutor}。
- */
-public class OpenCliClient {
+ * Entry point for the OpenCLI Java SDK. Holds a set of runtime configuration properties
+ and a shared {@link OpenCliExecutor}.
+ *
+ * <p>Usage example:</p>
+ * <pre>{@code
+ * OpenCliClient client = new OpenCliClient();
+ * OpenCliResult result = client.chatgpt().ask("hello", null, null);
+ * }</pre>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ */public class OpenCliClient {
 
     @Getter
     private final OpenCliProperties properties;
@@ -34,7 +43,7 @@ public class OpenCliClient {
     private final OpenCliExecutor executor;
 
     /**
-     * 使用默认配置构造（可执行文件假定名为 {@code opencli}）。
+     * Constructs with default configuration (executable assumed to be {@code opencli} on PATH).
      */
     public OpenCliClient() {
         this(new OpenCliProperties());

src/main/java/io/github/easy4j/opencli/OpenCliExecutionTarget.java

@@ -1,12 +1,15 @@
 package io.github.easy4j.opencli;
 
 /**
- * OpenCLI 命令实际执行位置：本机子进程或与 opencli-admin 兼容的远端 Agent HTTP API。
- */
-public enum OpenCliExecutionTarget {
+ * Determines where an OpenCLI command is executed: as a local subprocess or via a remote
+ Agent HTTP API compatible with opencli-admin.
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ */public enum OpenCliExecutionTarget {
 
     /**
-     * 在本机通过 {@link OpenCliProperties} 的 {@code executable} 配置启动子进程（默认）。
+     * Launch a subprocess on the local machine using the {@code executable} configured in {@link OpenCliProperties} (default).
      */
     LOCAL_PROCESS,
 

src/main/java/io/github/easy4j/opencli/OpenCliProperties.java

@@ -7,7 +7,7 @@
 import lombok.Data;
 
 /**
- * OpenCLI 运行时配置（纯 POJO，无 Spring 耦合）。
+ * OpenCLI runtime configuration POJO with no Spring dependency.
  * <p>
  * 描述可执行文件、工作目录、超时、全局 argv 前缀、远端 Agent 以及需要注入子进程的环境变量
  *（例如 {@code OPENCLI_CDP_ENDPOINT}）。Spring Boot 可由上层以
@@ -18,7 +18,26 @@
  * {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP} 模式下用作 HTTP 客户端超时上限。
  * </p>
  */
-@Data
+@Data/**
+
+ * OpenCLI runtime configuration POJO with no Spring dependency.
+ *
+ * <p>Describes the executable path, working directory, timeout, global argv prefix,
+ * remote Agent settings, and environment variables injected into the subprocess
+ * (e.g.&nbsp;{@code OPENCLI_CDP_ENDPOINT}). Spring Boot applications can bind these
+ * fields via {@code @ConfigurationProperties(prefix = "opencli")}.</p>
+ *
+ * <p>{@link #commandTimeoutMillis} is used as the subprocess watchdog timeout in local
+ * mode and as the HTTP client timeout in {@link OpenCliExecutionTarget#REMOTE_AGENT_HTTP} mode.</p>
+
+ *
+
+ * @author [@Loong Wan](https://github.com/loong10k)
+
+ * @since 3.0.0
+
+ */
+
 public class OpenCliProperties {
 
     /**

src/main/java/io/github/easy4j/opencli/adapter/browser/chatgpt/ChatgptOpenCliClient.java

@@ -18,7 +18,21 @@
 /**
  * OpenCLI {@code chatgpt}（ChatGPT Web）浏览器适配器。
  */
-@RequiredArgsConstructor
+@RequiredArgsConstructor/**
+
+ * OpenCLI {@code chatgpt} (ChatGPT Web) browser adapter client.
+ *
+ * <p>Provides typed methods for ChatGPT Web interactions such as {@code ask}, {@code send},
+ * {@code history}, {@code image}, and session management.</p>
+
+ *
+
+ * @author [@Loong Wan](https://github.com/loong10k)
+
+ * @since 3.0.0
+
+ */
+
 public final class ChatgptOpenCliClient {
 
     private final OpenCliExecutor executor;
@@ -35,11 +49,22 @@ public static class ChatgptCommonOptions {
 
         private Integer historyLimit;
 
+        private Integer stableSeconds;
+
         private Boolean readAsMarkdown;
 
-        /** 文档：{@code --new} 开启新会话。 */
         private Boolean newConversation;
 
+        private String conversation;
+
+        private String project;
+
+        private Boolean waitForResponse;
+
+        private Boolean deepResearch;
+
+        private Boolean webSearch;
+
         private Boolean jsonOutput;
 
         public void appendTo(List<String> target) {
@@ -52,9 +77,27 @@ public void appendTo(List<String> target) {
             if (historyLimit != null) {
                 OpenCliArgSupport.addOptionPair(target, "--limit", String.valueOf(historyLimit));
             }
+            if (stableSeconds != null) {
+                OpenCliArgSupport.addOptionPair(target, "--stable", String.valueOf(stableSeconds));
+            }
             if (readAsMarkdown != null) {
                 OpenCliArgSupport.addOptionPair(target, "--markdown", String.valueOf(readAsMarkdown));
             }
+            if (conversation != null) {
+                OpenCliArgSupport.addOptionPair(target, "--conversation", conversation);
+            }
+            if (project != null) {
+                OpenCliArgSupport.addOptionPair(target, "--project", project);
+            }
+            if (waitForResponse != null) {
+                OpenCliArgSupport.addOptionPair(target, "--wait", String.valueOf(waitForResponse));
+            }
+            if (Boolean.TRUE.equals(deepResearch)) {
+                target.add("--deep-research");
+            }
+            if (Boolean.TRUE.equals(webSearch)) {
+                target.add("--web-search");
+            }
             if (Boolean.TRUE.equals(jsonOutput)) {
                 target.add("-f");
                 target.add("json");
@@ -118,6 +161,63 @@ public OpenCliResult status(List<String> more) {
         return ch().invoke(OpenCliArgSupport.merge(OpenCliLists.of("status"), more));
     }
 
+    public OpenCliResult deepResearchResult(String id, Boolean wait, Integer timeoutSeconds,
+        Integer stableSeconds, List<String> more) {
+        List<String> args = new ArrayList<>();
+        args.add("deep-research-result");
+        args.add(id);
+        if (wait != null) {
+            OpenCliArgSupport.addOptionPair(args, "--wait", String.valueOf(wait));
+        }
+        if (timeoutSeconds != null) {
+            OpenCliArgSupport.addOptionPair(args, "--timeout", String.valueOf(timeoutSeconds));
+        }
+        if (stableSeconds != null) {
+            OpenCliArgSupport.addOptionPair(args, "--stable", String.valueOf(stableSeconds));
+        }
+        return ch().invoke(OpenCliArgSupport.merge(args, more));
+    }
+
+    public OpenCliResult login(Integer timeoutSeconds, List<String> more) {
+        List<String> args = new ArrayList<>();
+        args.add("login");
+        if (timeoutSeconds != null) {
+            OpenCliArgSupport.addOptionPair(args, "--timeout", String.valueOf(timeoutSeconds));
+        }
+        return ch().invoke(OpenCliArgSupport.merge(args, more));
+    }
+
+    public OpenCliResult model(String model, String project, List<String> more) {
+        List<String> args = new ArrayList<>();
+        args.add("model");
+        args.add(model);
+        if (project != null) {
+            OpenCliArgSupport.addOptionPair(args, "--project", project);
+        }
+        return ch().invoke(OpenCliArgSupport.merge(args, more));
+    }
+
+    public OpenCliResult projectFileAdd(String file, String id, List<String> more) {
+        List<String> args = new ArrayList<>();
+        args.add("project-file-add");
+        args.add(file);
+        OpenCliArgSupport.addOptionPair(args, "--id", id);
+        return ch().invoke(OpenCliArgSupport.merge(args, more));
+    }
+
+    public OpenCliResult projectList(Integer limit, List<String> more) {
+        List<String> args = new ArrayList<>();
+        args.add("project-list");
+        if (limit != null) {
+            OpenCliArgSupport.addOptionPair(args, "--limit", String.valueOf(limit));
+        }
+        return ch().invoke(OpenCliArgSupport.merge(args, more));
+    }
+
+    public OpenCliResult whoami(List<String> more) {
+        return ch().invoke(OpenCliArgSupport.merge(OpenCliLists.of("whoami"), more));
+    }
+
     /**
      * {@code chatgpt image} 文生图参数。
      */
@@ -144,7 +244,7 @@ public void appendTo(List<String> target) {
                 OpenCliArgSupport.addOptionPair(target, "--op", outputDir);
             }
             if (Boolean.TRUE.equals(skipDownload)) {
-                OpenCliArgSupport.addOptionPair(target, "--sd", "true");
+                target.add("--sd");
             }
             if (timeoutSeconds != null) {
                 OpenCliArgSupport.addOptionPair(target, "--timeout", String.valueOf(timeoutSeconds));

src/main/java/io/github/easy4j/opencli/adapter/browser/claude/ClaudeOpenCliClient.java

@@ -19,7 +19,21 @@
 /**
  * OpenCLI {@code claude} 浏览器适配器。
  */
-@RequiredArgsConstructor
+@RequiredArgsConstructor/**
+
+ * OpenCLI {@code claude} browser adapter client.
+ *
+ * <p>Provides typed methods for Claude Web interactions such as {@code ask}, {@code send},
+ * {@code history}, {@code detail}, and session management.</p>
+
+ *
+
+ * @author [@Loong Wan](https://github.com/loong10k)
+
+ * @since 3.0.0
+
+ */
+
 public final class ClaudeOpenCliClient {
 
     private final OpenCliExecutor executor;
@@ -98,6 +112,18 @@ public OpenCliResult send(String prompt, ClaudeAskOptions options, List<String>
         return ch().invoke(OpenCliArgSupport.merge(args, more));
     }
 
+    public OpenCliResult login(Integer timeoutSeconds, List<String> more) {
+        List<String> args = new ArrayList<>();
+        args.add("login");
+        if (timeoutSeconds != null) {
+            OpenCliArgSupport.addOptionPair(args, "--timeout", String.valueOf(timeoutSeconds));
+        }
+        return ch().invoke(OpenCliArgSupport.merge(args, more));
+    }
+
+    public OpenCliResult whoami(List<String> more) {
+        return ch().invoke(OpenCliArgSupport.merge(OpenCliLists.of("whoami"), more));
+    }
     public OpenCliResult newChat(List<String> more) {
         return ch().invoke(OpenCliArgSupport.merge(OpenCliLists.of("new"), more));
     }

src/main/java/io/github/easy4j/opencli/adapter/browser/deepseek/DeepseekOpenCliClient.java

@@ -18,7 +18,21 @@
 /**
  * OpenCLI {@code deepseek} 浏览器适配器。
  */
-@RequiredArgsConstructor
+@RequiredArgsConstructor/**
+
+ * OpenCLI {@code deepseek} browser adapter client.
+ *
+ * <p>Provides typed methods for DeepSeek Web interactions such as {@code ask}, {@code send},
+ * {@code history}, {@code detail}, and session management.</p>
+
+ *
+
+ * @author [@Loong Wan](https://github.com/loong10k)
+
+ * @since 3.0.0
+
+ */
+
 public final class DeepseekOpenCliClient {
 
     private final OpenCliExecutor executor;
@@ -103,7 +117,20 @@ public OpenCliResult send(String conversationId, String prompt, DeepseekAskOptio
         return ch().invoke(OpenCliArgSupport.merge(args, more));
     }
 
-    /** {@code deepseek new}。 */
+    public OpenCliResult login(Integer timeoutSeconds, List<String> more) {
+        List<String> args = new ArrayList<>();
+        args.add("login");
+        if (timeoutSeconds != null) {
+            OpenCliArgSupport.addOptionPair(args, "--timeout", String.valueOf(timeoutSeconds));
+        }
+        return ch().invoke(OpenCliArgSupport.merge(args, more));
+    }
+
+    public OpenCliResult whoami(List<String> more) {
+        return ch().invoke(OpenCliArgSupport.merge(OpenCliLists.of("whoami"), more));
+    }
+
+
     public OpenCliResult newChat(List<String> more) {
         return ch().invoke(OpenCliArgSupport.merge(OpenCliLists.of("new"), more));
     }