fix(cli): 同步执行器四项审计加固与新命令补齐——JDK 8 线经 decodeUtf8 helper 走 toString("UTF-8")（UTF-8 全 JVM 保证，catch 分支不可达）

Author: loong10k

src/main/java/io/github/easy4j/hermes/cli/HermesCli.java

@@ -634,6 +634,96 @@ public HermesCliResult cronAdd(String schedule, String prompt) {
      * @since 1.0.0
      */
     public HermesCliResult update() { return executor.execute("update"); }
+
+    /**
+     * <p>执行 Hermes CLI 的 {@code update} 命令并附带更新选项。</p>
+     *
+     * <p>文档化选项包括 {@code --check}、{@code --plan}、{@code --branch}、
+     * {@code --backup}、{@code --force}、{@code --force-venv}、
+     * {@code --no-gateway-restart}、{@code --keep-stash}、{@code --switch-branch}。</p>
+     *
+     * @param args 更新选项
+     * @return 包含退出码、标准输出和标准错误的命令结果
+     * @since 1.0.0
+     */
+    public HermesCliResult update(String... args) { return executor.execute(prefix("update", args)); }
+
+    /**
+     * <p>执行 Hermes CLI 的 {@code acp} 子命令（编辑器 ACP 模式）。</p>
+     *
+     * @param args 附加参数
+     * @return 包含退出码、标准输出和标准错误的命令结果
+     * @since 1.0.0
+     */
+    public HermesCliResult acp(String... args) { return executor.execute(prefix("acp", args)); }
+
+    /**
+     * <p>执行 Hermes CLI 的 {@code serve} 子命令（远程 Desktop 后端服务）。</p>
+     *
+     * @param args 附加参数
+     * @return 包含退出码、标准输出和标准错误的命令结果
+     * @since 1.0.0
+     */
+    public HermesCliResult serve(String... args) { return executor.execute(prefix("serve", args)); }
+
+    /**
+     * <p>执行 Hermes CLI 的 {@code desktop} 子命令。</p>
+     *
+     * @return 包含退出码、标准输出和标准错误的命令结果
+     * @since 1.0.0
+     */
+    public HermesCliResult desktop() { return executor.execute("desktop"); }
+
+    /**
+     * <p>执行 Hermes CLI 的 {@code skills browse} 子命令（浏览技能目录）。</p>
+     *
+     * @param args 附加参数
+     * @return 包含退出码、标准输出和标准错误的命令结果
+     * @since 1.0.0
+     */
+    public HermesCliResult skillsBrowse(String... args) { return executor.execute(prefix("skills", prefixArgs("browse", args))); }
+
+    /**
+     * <p>执行 Hermes CLI 的 {@code skills opt-in <skill>} 子命令。</p>
+     *
+     * @param skill 要启用的技能名
+     * @return 包含退出码、标准输出和标准错误的命令结果
+     * @since 1.0.0
+     */
+    public HermesCliResult skillsOptIn(String skill) { return executor.execute("skills", "opt-in", skill); }
+
+    /**
+     * <p>执行 Hermes CLI 的 {@code egress setup} 子命令（出口代理初始化）。</p>
+     *
+     * @param args 附加参数
+     * @return 包含退出码、标准输出和标准错误的命令结果
+     * @since 1.0.0
+     */
+    public HermesCliResult egressSetup(String... args) { return executor.execute(prefix("egress", prefixArgs("setup", args))); }
+
+    /**
+     * <p>执行 Hermes CLI 的 {@code egress start} 子命令（启动出口代理）。</p>
+     *
+     * @return 包含退出码、标准输出和标准错误的命令结果
+     * @since 1.0.0
+     */
+    public HermesCliResult egressStart() { return executor.execute("egress", "start"); }
+
+    /**
+     * <p>执行 Hermes CLI 的 {@code import} 子命令（导入备份）。</p>
+     *
+     * @param args 附加参数
+     * @return 包含退出码、标准输出和标准错误的命令结果
+     * @since 1.0.0
+     */
+    public HermesCliResult importData(String... args) { return executor.execute(prefix("import", args)); }
+
+    private static String[] prefixArgs(String head, String... tail) {
+        String[] all = new String[tail.length + 1];
+        all[0] = head;
+        System.arraycopy(tail, 0, all, 1, tail.length);
+        return all;
+    }
     /**
      * <p>执行 Hermes CLI 的 {@code uninstall} 命令。</p>
      *

src/main/java/io/github/easy4j/hermes/cli/HermesCliExecutor.java

@@ -4,24 +4,42 @@
 import lombok.extern.slf4j.Slf4j;
 import org.apache.commons.exec.CommandLine;
 import org.apache.commons.exec.DefaultExecutor;
+import org.apache.commons.exec.ExecuteException;
 import org.apache.commons.exec.ExecuteWatchdog;
+import org.apache.commons.exec.PumpStreamHandler;
 
+import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
 import java.io.File;
 import java.io.IOException;
+import java.nio.charset.StandardCharsets;
 import java.util.Objects;
 
 /**
  * <p>Hermes CLI 子进程执行器。</p>
  *
  * <p>负责命令构造、工作目录、超时等待以及标准输出和错误输出收集；调用方负责限制并发子进程数。</p>
  *
+ * <p>加固约定：</p>
+ * <ul>
+ *   <li>参数经 {@code addArgument(arg, false)} 原样进入 argv——子进程经 exec 启动而非 shell，
+ *       默认引号策略会把含空格参数的字面双引号烤进 argv，损坏多词 prompt 与路径；</li>
+ *   <li>子进程始终收到（可能为空的）立即关闭的 stdin——读取型命令读到 EOF 即结束，
+ *       已关闭管道也不会与输入泵产生写后关闭竞态；</li>
+ *   <li>输出按 UTF-8 显式解码——{@code toString()} 走平台默认字符集，C locale 或
+ *       Windows GBK 环境会损坏中文输出；</li>
+ *   <li>非零退出经 {@link ExecuteException} 单独捕获，保留真实退出码与两路输出；
+ *       超时判定用截止时间法，规避 {@code watchdog.killedProcess()} 的观察竞态。</li>
+ * </ul>
+ *
  * @author <a href="https://github.com/loong10k">Loong Wan</a>
  * @since 1.0.0
  */
 @Slf4j
 public class HermesCliExecutor {
 
+    private static final String TIMEOUT_PREFIX = "hermes CLI timed out after ";
+
     /**
      * 当前客户端使用的配置快照。
      */
@@ -47,16 +65,80 @@ public HermesCliExecutor(HermesCliConfig config) {
      * @since 1.0.0
      */
     public HermesCliResult execute(String... args) {
+        return runProcess(null, args);
+    }
+
+    /**
+     * <p>执行 Hermes CLI 命令并向子进程 stdin 管道写入 {@code stdin} 内容。</p>
+     *
+     * <p>供从标准输入读取载荷的命令形态使用；{@code stdin} 为 {@code null} 或空时
+     * 行为与 {@link #execute(String...)} 一致（子进程收到立即关闭的空管道）。失败语义
+     * 与变参重载相同。</p>
+     *
+     * @param stdin 写入子进程标准输入的可选文本
+     * @param args  传递给 Hermes CLI 的参数
+     * @return 包含退出码、标准输出和标准错误的命令结果
+     * @since 1.0.0
+     */
+    public HermesCliResult executeWithStdin(String stdin, String... args) {
+        return runProcess(stdin, args);
+    }
+
+    /**
+     * <p>探测 Hermes CLI 是否可执行。</p>
+     *
+     * @return CLI 版本命令成功退出时返回 {@code true}
+     * @since 1.0.0
+     */
+    public boolean probe() {
+        try {
+            HermesCliConfig probeConfig = copyForProbe(config);
+            HermesCliResult result = new HermesCliExecutor(probeConfig).execute("--version");
+            return result.isSuccess();
+        } catch (Exception e) {
+            return false;
+        }
+    }
+
+    /**
+     * <p>以 UTF-8 显式解码子进程输出。</p>
+     *
+     * <p>{@code toString(Charset)} 是 Java 10+ API，JDK 8 线经由
+     * {@code toString("UTF-8")}；UTF-8 在所有 JVM 上保证存在，
+     * catch 分支不可达，仅为满足受检异常。</p>
+     *
+     * @param buffer 待解码的输出缓冲
+     * @return UTF-8 解码后的文本
+     * @since 1.0.0
+     */
+    private static String decodeUtf8(ByteArrayOutputStream buffer) {
+        try {
+            return buffer.toString("UTF-8");
+        } catch (java.io.UnsupportedEncodingException e) {
+            return new String(buffer.toByteArray(), StandardCharsets.UTF_8);
+        }
+    }
+
+    private HermesCliResult runProcess(String stdin, String... args) {
         // 按参数边界构造命令，避免手工拼接引入空格转义错误和命令注入风险。
         CommandLine cmd = new CommandLine(config.getExecutable());
         for (String arg : args) {
-            cmd.addArgument(arg);
+            if (arg == null) {
+                continue;
+            }
+            // handleQuoting=false：子进程经 exec(argv) 启动而非 shell，默认引号策略
+            // 会把含空格参数的字面双引号烤进 argv，损坏多词 prompt 与路径。
+            cmd.addArgument(arg, false);
         }
 
         DefaultExecutor executor = new DefaultExecutor();
         ByteArrayOutputStream stdout = new ByteArrayOutputStream();
         ByteArrayOutputStream stderr = new ByteArrayOutputStream();
-        executor.setStreamHandler(new org.apache.commons.exec.PumpStreamHandler(stdout, stderr));
+        // 始终向子进程提供（可能为空的）立即关闭的 stdin：消费型命令读到 EOF 即结束，
+        // 已关闭管道不会与输入泵产生写后关闭竞态。
+        byte[] stdinBytes = stdin == null ? new byte[0] : stdin.getBytes(StandardCharsets.UTF_8);
+        executor.setStreamHandler(new PumpStreamHandler(stdout, stderr,
+                new ByteArrayInputStream(stdinBytes)));
 
         File workingDirectory = resolveWorkingDirectory();
         if (workingDirectory != null) {
@@ -68,38 +150,50 @@ public HermesCliResult execute(String... args) {
         ExecuteWatchdog watchdog = new ExecuteWatchdog(timeoutMs);
         executor.setWatchdog(watchdog);
 
+        long startNanos = System.nanoTime();
         try {
             int exitCode = executor.execute(cmd);
-            String out = stdout.toString().trim();
-            String err = stderr.toString().trim();
+            String out = decodeUtf8(stdout).trim();
+            String err = decodeUtf8(stderr).trim();
             if (config.getDebug().allows(HttpLogLevel.BASIC)) {
                 log.debug("Hermes CLI executed: exitCode={}, stdoutLength={}, stderrLength={}",
                         exitCode, out.length(), err.length());
             }
             if (config.getDebug().allows(HttpLogLevel.BODY)) {
                 log.debug("Hermes CLI output: stdout={}, stderr={}", truncate(out), truncate(err));
             }
+            if (watchdog.killedProcess()) {
+                return timeoutResult(stdout, stderr, timeoutMs);
+            }
             return new HermesCliResult(exitCode, out, err);
+        } catch (ExecuteException e) {
+            // commons-exec 对每次非零退出（以及 watchdog 击杀）都会抛出 ExecuteException；
+            // 抛出前输出泵已 join，两路缓冲是完整的——原样保留真实退出码与输出，
+            // 超时判定用截止时间法规避 killedProcess() 的观察竞态。
+            String out = decodeUtf8(stdout).trim();
+            String err = decodeUtf8(stderr).trim();
+            boolean timedOut = watchdog.killedProcess()
+                    || System.nanoTime() - startNanos >= timeoutMs * 1_000_000L;
+            if (timedOut) {
+                log.warn("Hermes CLI timed out after {} ms", timeoutMs);
+                return timeoutResult(stdout, stderr, timeoutMs);
+            }
+            if (config.getDebug().allows(HttpLogLevel.BASIC)) {
+                log.debug("Hermes CLI failed: exitCode={}, stdoutLength={}, stderrLength={}",
+                        e.getExitValue(), out.length(), err.length());
+            }
+            return new HermesCliResult(e.getExitValue(), out, err);
         } catch (IOException e) {
             log.warn("CLI execution failed", e);
             return new HermesCliResult(-1, "", e.getMessage());
         }
     }
 
-    /**
-     * <p>探测 Hermes CLI 是否可执行。</p>
-     *
-     * @return CLI 版本命令成功退出时返回 {@code true}
-     * @since 1.0.0
-     */
-    public boolean probe() {
-        try {
-            HermesCliConfig probeConfig = copyForProbe(config);
-            HermesCliResult result = new HermesCliExecutor(probeConfig).execute("--version");
-            return result.isSuccess();
-        } catch (Exception e) {
-            return false;
-        }
+    private HermesCliResult timeoutResult(ByteArrayOutputStream stdout, ByteArrayOutputStream stderr,
+                                          long timeoutMs) {
+        String out = decodeUtf8(stdout).trim();
+        String err = TIMEOUT_PREFIX + timeoutMs + " ms\n" + decodeUtf8(stderr).trim();
+        return new HermesCliResult(-1, out, err);
     }
 
     private static HermesCliConfig copyForProbe(HermesCliConfig source) {

src/main/java/io/github/easy4j/hermes/cli/HermesCliResult.java

@@ -34,4 +34,16 @@ public class HermesCliResult {
     public boolean isSuccess() {
         return exitCode == 0;
     }
+
+    /**
+     * <p>判断本次调用是否因超时被 watchdog 终止。</p>
+     *
+     * @return 退出码为 {@code -1} 且标准错误携带超时说明时返回 {@code true}
+     * @since 1.0.0
+     */
+    public boolean isTimeout() {
+        return exitCode == -1 && stderr != null && stderr.startsWith(TIMEOUT_PREFIX);
+    }
+
+    private static final String TIMEOUT_PREFIX = "hermes CLI timed out after ";
 }