bitool 0.1.2__py3-none-any.whl

bitool/utils/executor.py

@@ -0,0 +1,881 @@
+"""子进程命令执行模块.
+
+本模块提供一个智能的子进程执行器,根据系统 CPU 配置自动选择最优的
+命令执行方式,并将所有输出记录到日志系统中.
+
+核心功能
+--------
+- 根据 CPU 核心数自动选择串行/并行执行策略
+- 实时捕获并记录命令的标准输出和标准错误
+- 支持超时控制和进程管理
+- 线程安全的执行环境
+- 可扩展的命令执行策略
+
+快速开始
+--------
+>>> from pytola_core.command import execute
+>>> result = execute(["ffmpeg", "-i", "input.mp4", "output.avi"])
+"""
+
+from __future__ import annotations
+
+import subprocess
+import threading
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from io import TextIOBase
+from pathlib import Path
+from typing import Callable, List, Sequence, Union, overload
+
+from ..core import ConfigMixin, logger
+
+__all__ = ["execute"]
+
+
+class RunMode(str, Enum):
+    """执行模式常量."""
+
+    SERIAL = "serial"
+    CONCURRENT = "concurrent"
+    STREAMING = "streaming"
+
+
+class _DefaultExecutorConfig(ConfigMixin):
+    """默认执行器配置."""
+
+    TIMEOUT: int = 30  # 默认超时时间(秒)
+    STREAM_CHUNK_SIZE: int = 1024
+    ENABLE_STREAMING: bool = True
+
+
+_conf = _DefaultExecutorConfig()
+
+
+@dataclass
+class RunResult:
+    """命令执行结果.
+
+    Attributes
+    ----------
+    returncode : int
+        命令返回码,0 表示成功
+    stdout : str
+        标准输出内容
+    stderr : str
+        标准错误内容
+    execution_time : float
+        执行耗时(秒)
+    mode : str
+        使用的执行模式
+    cmd : list[str]
+        执行的命令
+    """
+
+    returncode: int
+    stdout: str
+    stderr: str
+    execution_time: float
+    mode: str = RunMode.SERIAL
+    cmd: list[str] = field(default_factory=list)
+
+    @property
+    def success(self) -> bool:
+        """命令是否执行成功."""
+        return self.returncode == 0
+
+
+# 类型别名 (使用 Union 以兼容 Python 3.8)
+ProcessArgs = Sequence[Union[List[str], Callable[[], RunResult]]]
+
+
+class ProcessExecutor:
+    """智能命令执行器.
+
+    根据系统 CPU 配置自动选择最优执行策略,并将输出记录到日志系统.
+
+    Parameters
+    ----------
+    long_running_cmds : set[str], optional
+        自定义长时间运行命令集合,默认使用内置集合
+
+    Examples
+    --------
+    >>> executor = ProcessExecutor()
+    >>> result = executor.run(["ls", "-la"])
+    >>> if result.success:
+    ...     print("命令执行成功")
+    """
+
+    def _select_execution_mode(self, cmd: list[str]) -> str:
+        """根据系统配置选择执行模式.
+
+        所有命令统一使用流式模式,实时显示执行进展.
+
+        Parameters
+        ----------
+        cmd : list[str]
+            命令及其参数列表
+
+        Returns
+        -------
+        str
+            选择的执行模式
+        """
+        if not cmd:
+            return RunMode.SERIAL
+
+        # 所有命令统一使用流式模式,实时显示输出
+        return RunMode.STREAMING
+
+    def run(
+        self,
+        cmd: list[str],
+        cwd: Path | None = None,
+        env: dict[str, str] | None = None,
+        timeout: int | None = None,
+        *,
+        check: bool = False,
+        capture_output: bool = True,
+        text: bool = True,
+    ) -> RunResult:
+        """执行命令并返回结果.
+
+        Parameters
+        ----------
+        cmd : list[str]
+            命令及其参数列表
+        cwd : Path, optional
+            工作目录
+        env : dict[str, str], optional
+            环境变量
+        timeout : int, optional
+            超时时间(秒),默认使用实例配置
+        check : bool, optional
+            是否检查返回码,非零时抛出异常
+        capture_output : bool, optional
+            是否捕获输出
+        text : bool, optional
+            是否以文本模式处理输出
+
+        Returns
+        -------
+        RunResult
+            命令执行结果
+
+        Raises
+        ------
+        subprocess.TimeoutExpired
+            命令执行超时
+        subprocess.CalledProcessError
+            命令返回非零退出码(当 check=True 时)
+        ValueError
+            命令列表为空
+        """
+        if not cmd:
+            msg = "命令列表不能为空"
+            raise ValueError(msg)
+
+        effective_timeout: int = timeout if timeout is not None else _conf.TIMEOUT
+        mode: str = self._select_execution_mode(cmd=cmd)
+
+        logger.info(
+            f"开始执行命令: `{' '.join(cmd)}`, 模式:{mode}, 超时:{effective_timeout}秒"
+        )
+
+        if mode == RunMode.STREAMING:
+            return self._run_streaming(
+                cmd,
+                cwd,
+                env,
+                effective_timeout,
+                check=check,
+                capture_output=capture_output,
+                text=text,
+            )
+        elif mode == RunMode.CONCURRENT:
+            return self._run_concurrent(
+                cmd,
+                cwd,
+                env,
+                effective_timeout,
+                check=check,
+                capture_output=capture_output,
+                text=text,
+            )
+        else:
+            return self._run_serial(
+                cmd,
+                cwd,
+                env,
+                effective_timeout,
+                check=check,
+                capture_output=capture_output,
+                text=text,
+            )
+
+    def _run_serial(
+        self,
+        cmd: list[str],
+        cwd: Path | None,
+        env: dict[str, str] | None,
+        timeout: int,
+        *,
+        check: bool,
+        capture_output: bool,
+        text: bool,
+    ) -> RunResult:
+        """串行执行命令.
+
+        Parameters
+        ----------
+        cmd : list[str]
+            命令及其参数列表
+        cwd : Path, optional
+            工作目录
+        env : dict[str, str], optional
+            环境变量
+        timeout : int
+            超时时间(秒)
+        check : bool
+            是否检查返回码
+        capture_output : bool
+            是否捕获输出
+        text : bool
+            是否以文本模式处理输出
+
+        Returns
+        -------
+        RunResult
+            命令执行结果
+        """
+        start_time = time.time()
+        stdout_lines: list[str] = []
+        stderr_lines: list[str] = []
+        execution_time: float = 0.0
+
+        try:
+            # 使用 Popen 实现实时输出
+            # 注意：行缓冲（bufsize=1）仅在 text=True 时有效
+            process = subprocess.Popen(  # noqa: S603
+                cmd,
+                cwd=cwd,
+                env=env,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=text,
+                bufsize=1 if text else -1,  # 行缓冲（仅文本模式）或使用默认缓冲
+            )
+
+            # 启动线程读取输出
+            stdout_thread = threading.Thread(
+                target=self._read_stream,
+                args=(process.stdout, stdout_lines, "STDOUT"),
+                daemon=True,
+            )
+            stderr_thread = threading.Thread(
+                target=self._read_stream,
+                args=(process.stderr, stderr_lines, "STDERR"),
+                daemon=True,
+            )
+
+            stdout_thread.start()
+            stderr_thread.start()
+
+            # 等待进程完成或超时
+            returncode: int = process.wait(timeout=timeout)
+
+            # 等待输出读取完成（设置合理的超时避免无限等待）
+            stdout_thread.join(timeout=5)
+            stderr_thread.join(timeout=5)
+
+            execution_time = time.time() - start_time
+
+            stdout_content = "\n".join(stdout_lines)
+            stderr_content = "\n".join(stderr_lines)
+
+            log_msg = f"命令执行完成: `{' '.join(cmd)}`, 返回码:{returncode}, 耗时:{execution_time:.2f}秒`"
+
+            # uv 工具特殊处理：返回码 2 表示有警告但成功
+            is_uv_command = cmd and cmd[0] == "uv"
+            is_uv_success = is_uv_command and returncode == 2
+
+            if returncode == 0 or is_uv_success:
+                logger.info(log_msg)
+                # uv 返回码 2 时添加警告提示
+                if is_uv_success:
+                    logger.warning("uv 命令有警告信息，请检查上方输出")
+                # 已实时输出, 不再重复输出
+            else:
+                # 根据返回码决定日志级别
+                if returncode < 0:
+                    logger.error(log_msg)
+                else:
+                    logger.warning(log_msg)
+
+                # 失败时显示错误输出（排除 uv 的进度信息）
+                if stderr_content:
+                    for line in stderr_content.strip().split("\n"):
+                        if line.strip():
+                            # uv 的进度信息不算错误
+                            if is_uv_command and any(
+                                keyword in line
+                                for keyword in [
+                                    "Resolved",
+                                    "Building",
+                                    "Built",
+                                    "Prepared",
+                                ]
+                            ):
+                                logger.info(f"  uv 进度: `{line.strip()}`")
+                            else:
+                                logger.error(f"  错误: `{line.strip()}`")
+                elif stdout_content:
+                    for line in stdout_content.strip().split("\n"):
+                        if line.strip():
+                            logger.warning(f"  输出: `{line.strip()}`")
+
+            if check and returncode != 0:
+                self._raise_on_failure(returncode, cmd, stdout_content, stderr_content)
+
+            return RunResult(
+                returncode=returncode,
+                stdout=stdout_content,
+                stderr=stderr_content,
+                execution_time=execution_time,
+                mode=RunMode.SERIAL,
+                cmd=cmd,
+            )
+
+        except subprocess.TimeoutExpired:
+            execution_time = time.time() - start_time
+            logger.error(f"命令执行超时: {' '.join(cmd)}, 超时时间:{timeout}秒")
+            raise
+        except FileNotFoundError as e:
+            execution_time = time.time() - start_time
+            logger.error(f"命令未找到: {' '.join(cmd)}, 错误:{e}")
+            raise
+        except (OSError, RuntimeError, ValueError) as e:
+            execution_time = time.time() - start_time
+            logger.error(f"命令执行异常: {' '.join(cmd)}, 错误:{e}", exc_info=True)
+            raise
+
+    def _run_concurrent(
+        self,
+        cmd: list[str],
+        cwd: Path | None,
+        env: dict[str, str] | None,
+        timeout: int,
+        *,
+        check: bool,
+        capture_output: bool,
+        text: bool,
+    ) -> RunResult:
+        """并发执行命令(使用线程池优化).
+
+        注意: 对于单个命令,并发模式与串行模式相同.
+        此方法预留接口用于未来批量命令执行优化.
+
+        Parameters
+        ----------
+        cmd : list[str]
+            命令及其参数列表
+        cwd : Path, optional
+            工作目录
+        env : dict[str, str], optional
+            环境变量
+        timeout : int
+            超时时间(秒)
+        check : bool
+            是否检查返回码
+        capture_output : bool
+            是否捕获输出
+        text : bool
+            是否以文本模式处理输出
+
+        Returns
+        -------
+        RunResult
+            命令执行结果
+        """
+        return self._run_serial(
+            cmd,
+            cwd,
+            env,
+            timeout,
+            check=check,
+            capture_output=capture_output,
+            text=text,
+        )
+
+    def _run_streaming(
+        self,
+        cmd: list[str],
+        cwd: Path | None,
+        env: dict[str, str] | None,
+        timeout: int,
+        *,
+        check: bool,
+        capture_output: bool,
+        text: bool,
+    ) -> RunResult:
+        """流式执行命令,实时捕获输出.
+
+        Parameters
+        ----------
+        cmd : list[str]
+            命令及其参数列表
+        cwd : Path, optional
+            工作目录
+        env : dict[str, str], optional
+            环境变量
+        timeout : int
+            超时时间(秒)
+        check : bool
+            是否检查返回码
+        capture_output : bool
+            是否捕获输出
+        text : bool
+            是否以文本模式处理输出
+
+        Returns
+        -------
+        RunResult
+            命令执行结果
+        """
+        start_time = time.time()
+        stdout_lines: list[str] = []
+        stderr_lines: list[str] = []
+        execution_time: float = 0.0
+
+        try:
+            process = subprocess.Popen(  # noqa: S603
+                cmd,
+                cwd=cwd,
+                env=env,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=text,
+                bufsize=1 if text else -1,  # 行缓冲（仅文本模式）或使用默认缓冲
+            )
+
+            # 启动线程读取输出
+            stdout_thread = threading.Thread(
+                target=self._read_stream,
+                args=(process.stdout, stdout_lines, "STDOUT"),
+                daemon=True,
+            )
+            stderr_thread = threading.Thread(
+                target=self._read_stream,
+                args=(process.stderr, stderr_lines, "STDERR"),
+                daemon=True,
+            )
+
+            stdout_thread.start()
+            stderr_thread.start()
+
+            # 等待进程完成或超时
+            try:
+                returncode: int = process.wait(timeout=timeout)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                execution_time = time.time() - start_time
+                logger.error(
+                    f"流式命令执行超时: `{' '.join(cmd)}, 超时时间:{timeout}秒`"
+                )
+                raise
+
+            # 等待输出读取完成（设置合理的超时避免无限等待）
+            stdout_thread.join(timeout=5)
+            stderr_thread.join(timeout=5)
+
+            # 如果线程仍在运行，记录警告（daemon 线程会在主线程退出时自动终止）
+            if stdout_thread.is_alive() or stderr_thread.is_alive():
+                logger.warning("输出读取线程未在预期时间内完成")
+
+            execution_time = time.time() - start_time
+
+            stdout_content = "\n".join(stdout_lines)
+            stderr_content = "\n".join(stderr_lines)
+
+            log_msg = f"流式命令执行完成: `{' '.join(cmd)}, 返回码:{returncode}, 耗时:{execution_time:.2f}秒`"
+
+            # uv 工具特殊处理：返回码 2 表示有警告但成功
+            is_uv_command = cmd and cmd[0] == "uv"
+            is_uv_success = is_uv_command and returncode == 2
+
+            if returncode == 0 or is_uv_success:
+                logger.info(log_msg)
+                # uv 返回码 2 时添加警告提示
+                if is_uv_success:
+                    logger.warning("uv 命令有警告信息，请检查上方输出")
+                # 流式模式已实时输出, 不再重复输出
+            else:
+                # 根据返回码决定日志级别
+                if returncode < 0:
+                    logger.error(log_msg)
+                else:
+                    logger.warning(log_msg)
+
+                # 失败时显示错误输出（排除 uv 的进度信息）
+                if stderr_content:
+                    for line in stderr_content.strip().split("\n"):
+                        if line.strip():
+                            # uv 的进度信息不算错误
+                            if is_uv_command and any(
+                                keyword in line
+                                for keyword in [
+                                    "Resolved",
+                                    "Building",
+                                    "Built",
+                                    "Prepared",
+                                ]
+                            ):
+                                logger.info(f"  uv 进度: `{line.strip()}`")
+                            else:
+                                logger.error(f"  错误: `{line.strip()}`")
+                elif stdout_content:
+                    for line in stdout_content.strip().split("\n"):
+                        if line.strip():
+                            logger.warning(f"  输出: `{line.strip()}`")
+
+            if check and returncode != 0:
+                self._raise_on_failure(returncode, cmd, stdout_content, stderr_content)
+
+            return RunResult(
+                returncode=returncode,
+                stdout=stdout_content,
+                stderr=stderr_content,
+                execution_time=execution_time,
+                mode=RunMode.STREAMING,
+                cmd=cmd,
+            )
+
+        except FileNotFoundError as e:
+            execution_time = time.time() - start_time
+            logger.error(f"流式命令未找到: `{' '.join(cmd)}, 错误:{e}`")
+            raise
+        except (OSError, RuntimeError, ValueError) as e:
+            execution_time = time.time() - start_time
+            logger.error(
+                f"流式命令执行异常: `{' '.join(cmd)}, 错误:{e}`, exc_info=True"
+            )
+            raise
+
+    def _raise_on_failure(
+        self, returncode: int, cmd: list[str], stdout: str, stderr: str
+    ) -> None:
+        """命令失败时抛出异常.
+
+        Parameters
+        ----------
+        returncode : int
+            命令返回码
+        cmd : list[str]
+            命令及其参数列表
+        stdout : str
+            标准输出内容
+        stderr : str
+            标准错误内容
+
+        Raises
+        ------
+        subprocess.CalledProcessError
+            命令返回非零退出码
+        """
+        raise subprocess.CalledProcessError(returncode, cmd, stdout, stderr)
+
+    def _read_stream(
+        self, stream: TextIOBase, output_list: list[str], stream_name: str
+    ) -> None:
+        """读取流式输出.
+
+        Parameters
+        ----------
+        stream : file-like object
+            输出流
+        output_list : list[str]
+            存储输出内容的列表
+        stream_name : str
+            流名称(STDOUT/STDERR)
+        text_mode : bool
+            是否为文本模式
+        """
+        try:
+            # 预分配列表容量以提升性能（估计值）
+            for line in stream:
+                # 处理bytes或str类型
+                line_str = (
+                    line.decode("utf-8", errors="replace")
+                    if isinstance(line, bytes)
+                    else line
+                )
+
+                line_str = line_str.rstrip("\n")
+                if line_str.strip():  # 只记录非空白行
+                    output_list.append(line_str)
+                    # 实时记录输出到INFO级别,确保用户能看到执行进展
+                    if stream_name == "STDERR":
+                        logger.info(f"[STDERR] {line_str}")
+                    else:
+                        logger.info(f"[STDOUT] {line_str}")
+        except (OSError, RuntimeError) as e:
+            logger.error(f"读取{stream_name}流时发生错误:{e}")
+        except ValueError as e:
+            # 处理流关闭时的 ValueError
+            logger.debug(f"读取{stream_name}流时发生ValueError, 可能是流已关闭:{e}")
+
+    def run_batch(
+        self,
+        commands: Sequence[list[str] | Callable[[], RunResult]],
+        max_concurrent: int | None = None,
+        timeout: int | None = None,
+    ) -> list[RunResult]:
+        """批量执行命令.
+
+        Parameters
+        ----------
+        commands : Sequence[list[str] | Callable[[], RunResult]]
+            命令列表或可调用对象列表
+        max_concurrent : int, optional
+            最大并发数,默认根据 CPU 配置计算
+        timeout : int, optional
+            每个命令的超时时间
+
+        Returns
+        -------
+        list[RunResult]
+            命令执行结果列表
+        """
+        from concurrent.futures import ThreadPoolExecutor, as_completed
+
+        if not commands:
+            logger.info("批量执行命令列表为空, 直接返回")
+            return []
+
+        effective_timeout = timeout if timeout is not None else _conf.TIMEOUT
+        effective_max_workers = (
+            max_concurrent if max_concurrent is not None else _conf._MAX_WORKERS
+        )
+
+        logger.info(
+            f"开始批量执行 {len(commands)} 个命令, 最大并发数:{effective_max_workers}, 超时时间:{effective_timeout}秒"
+        )
+
+        results: list[RunResult] = []
+        batch_start_time = time.time()
+        completed_count = 0
+        total_count = len(commands)
+
+        with ThreadPoolExecutor(max_workers=effective_max_workers) as executor:
+            # 提交所有任务
+            future_to_cmd = {}
+            for idx, cmd in enumerate(commands):
+                if callable(cmd):
+                    # 如果是可调用对象,直接提交
+                    future = executor.submit(cmd)
+                    future_to_cmd[future] = (cmd, idx)
+                    logger.debug(
+                        f"提交可调用任务 [{idx + 1}/{total_count}]: {cmd.__name__ if hasattr(cmd, '__name__') else 'lambda'}"
+                    )
+                else:
+                    # 如果是命令列表,调用 self.run
+                    future = executor.submit(self.run, cmd, timeout=effective_timeout)
+                    future_to_cmd[future] = (cmd, idx)
+                    logger.debug(
+                        f"提交命令任务 [{idx + 1}/{total_count}]: {' '.join(cmd)}"
+                    )
+
+            # 收集结果
+            for future in as_completed(future_to_cmd):
+                cmd, idx = future_to_cmd[future]
+                completed_count += 1
+                try:
+                    result = future.result()
+                    results.append(result)
+
+                    # 记录单个命令执行结果
+                    cmd_str = (
+                        " ".join(cmd)
+                        if isinstance(cmd, list)
+                        else (cmd.__name__ if hasattr(cmd, "__name__") else str(cmd))
+                    )
+                    if result.success:
+                        logger.info(
+                            f"[{completed_count}/{total_count}] 成功: {cmd_str} (耗时:{result.execution_time:.2f}秒)"
+                        )
+                        # 显示命令输出
+                        if result.stdout:
+                            for line in result.stdout.strip().split("\n"):
+                                if line.strip():
+                                    logger.info(f"  输出: {line.strip()}")
+                    else:
+                        # 根据返回码决定日志级别
+                        if result.returncode < 0:
+                            logger.error(
+                                f"[{completed_count}/{total_count}] 失败: {cmd_str} (返回码:{result.returncode})"
+                            )
+                        else:
+                            logger.warning(
+                                f"[{completed_count}/{total_count}] 失败: {cmd_str} (返回码:{result.returncode})"
+                            )
+
+                        # 显示错误输出
+                        if result.stderr:
+                            for line in result.stderr.strip().split("\n"):
+                                if line.strip():
+                                    logger.error(f"  错误: {line.strip()}")
+                        elif result.stdout:
+                            for line in result.stdout.strip().split("\n"):
+                                if line.strip():
+                                    logger.warning(f"  输出: {line.strip()}")
+                except (OSError, RuntimeError, ValueError) as e:
+                    cmd_str = " ".join(cmd) if isinstance(cmd, list) else str(cmd)
+                    logger.error(
+                        f"[{completed_count}/{total_count}] 异常: {cmd_str}, 错误:{e}"
+                    )
+                    # 添加失败结果
+                    cmd_list = cmd if isinstance(cmd, list) else []
+                    results.append(
+                        RunResult(
+                            returncode=-1,
+                            stdout="",
+                            stderr=str(e),
+                            execution_time=0.0,
+                            mode="failed",
+                            cmd=cmd_list,
+                        )
+                    )
+
+        batch_execution_time = time.time() - batch_start_time
+        success_count = sum(1 for r in results if r.returncode == 0)
+        failed_count = len(results) - success_count
+
+        logger.info(
+            f"批量命令执行完成 | 总数:{total_count} | 成功:{success_count} | 失败:{failed_count} | "
+            f"总耗时:{batch_execution_time:.2f}秒"
+        )
+
+        # 如果有失败的命令,输出详细信息
+        if failed_count > 0:
+            failed_results = [r for r in results if r.returncode != 0]
+            logger.warning("失败的命令详情:")
+            for r in failed_results:
+                cmd_str = " ".join(r.cmd) if r.cmd else "unknown"
+                logger.warning(f"  - {cmd_str} (返回码:{r.returncode})")
+
+        return results
+
+
+_executor = ProcessExecutor()
+
+
+# 类型重载: 单个命令模式
+@overload
+def execute(
+    cmd: list[str],
+    cwd: Path | None = ...,
+    env: dict[str, str] | None = ...,
+    timeout: int | None = ...,
+    *,
+    check: bool = ...,
+    capture_output: bool = ...,
+    text: bool = ...,
+    max_concurrent: int | None = ...,
+) -> RunResult: ...
+
+
+# 类型重载: 批量命令模式
+@overload
+def execute(
+    cmd: Sequence[list[str] | Callable[[], RunResult]],
+    cwd: Path | None = ...,
+    env: dict[str, str] | None = ...,
+    timeout: int | None = ...,
+    *,
+    check: bool = ...,
+    capture_output: bool = ...,
+    text: bool = ...,
+    max_concurrent: int | None = ...,
+) -> list[RunResult]: ...
+
+
+def execute(
+    cmd: list[str] | Sequence[list[str] | Callable[[], RunResult]],
+    cwd: Path | None = None,
+    env: dict[str, str] | None = None,
+    timeout: int | None = None,
+    *,
+    check: bool = False,
+    capture_output: bool = True,
+    text: bool = True,
+    max_concurrent: int | None = None,
+) -> RunResult | list[RunResult]:
+    """执行命令或批量执行命令.
+
+    智能判断输入类型:
+    - 如果 cmd 是 list[str],执行单个命令
+    - 如果 cmd 是 Sequence[list[str] | Callable],批量执行命令
+
+    Parameters
+    ----------
+    cmd : list[str] | Sequence[list[str] | Callable[[], RunResult]]
+        单个命令列表或命令列表序列(支持可调用对象)
+    cwd : Path, optional
+        工作目录(仅单个命令模式有效)
+    env : dict[str, str], optional
+        环境变量(仅单个命令模式有效)
+    timeout : int, optional
+        超时时间(秒),默认使用实例配置
+    check : bool, optional
+        是否检查返回码,非零时抛出异常(仅单个命令模式有效)
+    capture_output : bool, optional
+        是否捕获输出(仅单个命令模式有效)
+    text : bool, optional
+        是否以文本模式处理输出(仅单个命令模式有效)
+    max_concurrent : int, optional
+        最大并发数(仅批量命令模式有效)
+
+    Returns
+    -------
+    RunResult | list[RunResult]
+        单个命令返回 RunResult,批量命令返回 list[RunResult]
+
+    Examples
+    --------
+    >>> # 执行单个命令
+    >>> result = execute(["ls", "-la"])
+    >>> print(result.returncode)
+
+    >>> # 批量执行命令
+    >>> results = execute([
+    ...     ["echo", "hello"],
+    ...     ["echo", "world"],
+    ... ])
+    >>> for r in results:
+    ...     print(r.returncode)
+    """
+    # 判断是否为批量命令模式：检查第一个元素是否为 list 或 Callable
+    # 注意：单个命令如 ["echo", "hello"] 的第一个元素是字符串，不是 list
+    if cmd and isinstance(cmd[0], (list, Callable)):
+        # 批量命令模式：通过重载推断类型
+        return _executor.run_batch(
+            cmd,  # ty: ignore[invalid-argument-type]
+            max_concurrent=max_concurrent,
+            timeout=timeout,
+        )
+    else:
+        # 单个命令模式：通过 isinstance 守卫确保类型安全
+        if not isinstance(cmd, list):
+            msg = f"命令列表应为 list[str],实际为 {type(cmd).__name__}"
+            raise TypeError(msg)
+        # 单个命令：直接传递，通过类型重载匹配第一个签名
+        return _executor.run(
+            cmd,  # ty: ignore[invalid-argument-type]
+            cwd=cwd,
+            env=env,
+            timeout=timeout,
+            check=check,
+            capture_output=capture_output,
+            text=text,
+        )