remote-cmd-manager 2.3.0__tar.gz → 2.4.0__tar.gz

{remote_cmd_manager-2.3.0/remote_cmd_manager.egg-info → remote_cmd_manager-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remote_cmd_manager
-Version: 2.3.0
+Version: 2.4.0
 Summary: Cross-platform SSH remote server management tool (Linux/macOS/Windows) — lightweight, zero-configuration CLI and Python API for managing servers over SSH. Supports host CRUD, batch commands, file transfer, credential encryption, async execution, and more.
 Author-email: Vae-Scrooge <vaescrooge@gmail.com>
 License: MIT
@@ -89,28 +89,30 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.3.0 Release Highlights
+## v2.4.0 Release Highlights
 
-v2.3.0 makes blocking SFTP operations timeout-safe, hardens async cancellation cleanup,
-and aligns the supported Python range and release tooling. See the
+v2.4.0 adds an opt-in retained-output cap for batch execution and cleans up logging
+handler resources, with default behavior and public result schemas unchanged. See the
 [full migration notes](./CHANGELOG.md) before upgrading automated callers.
 
-### SFTP Timeouts & Reliability
+### Bounded Batch Output
 
-- Blocking SFTP operations now support an inactivity timeout (default: `ConnectionConfig.timeout`, 30 s): uploads, downloads, directory listing, directory creation, removal, and file-info calls accept an optional `timeout` argument.
-- The synchronous `SSHClient` applies the timeout to the Paramiko SFTP channel, so a stalled read/write aborts the actual operation and raises `SSHFileTransferError`.
-- The asynchronous `AsyncSSHClient` bounds SFTP channel startup with a timeout and uses a progress-based inactivity watchdog to cancel stalled transfers, awaiting the aborted operation and preserving caller cancellation during cleanup.
-- Timed-out or cancelled SFTP sessions are closed and discarded, so a stale or desynchronized channel can never be reused.
+- `BatchExecutor` / `AsyncBatchExecutor` accept an optional `max_output_bytes` (default `None`): `None` keeps full `stdout`/`stderr`, while a positive value caps each host's retained streams and appends a `[output truncated: N bytes omitted]` marker.
+- Truncation is deterministic and UTF-8 byte-boundary safe, applies to `stdout` and `stderr` independently, and never changes command success/failure or exit codes.
+- The cap bounds the retained `BatchResult`; the SSH client may still hold full output transiently during execution, so it is not a process-wide RSS limit.
 
-### Release Engineering
+### Reliability
 
-- Python 3.9–3.14 are officially supported and CI-tested; `Requires-Python` remains `>=3.9`.
-- CI runs release-metadata validation for CHANGELOG.md-only changes.
-- Publish builds pin `build==1.5.0` and `twine==7.0.0`.
+- `setup_logging` now closes previous root-logger handlers before removing them, avoiding unclosed-file resource warnings when logging is reconfigured.
+- Connection-pool lifetime wording in the documentation now matches the actual behavior: internal pools are created lazily per host and closed as soon as that host finishes (including its retries).
+
+### Compatibility
+
+- Default behavior is unchanged (`max_output_bytes=None` retains full output) and the public `BatchResult` / `BatchHostResult` schemas are unchanged.
 
 ## Table of Contents
 
-- [v2.3.0 Release Highlights](#v230-release-highlights)
+- [v2.4.0 Release Highlights](#v240-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -258,7 +260,7 @@ with SSHClient(config) as client:
 | **File Transfer** | Upload/download via SFTP (`remote-cmd upload/download`) |
 | **Host Management** | CRUD with pluggable JSON or **SQLite** persistence |
 | **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
-| **Batch Ops** | Run commands across any host group, synchronously or asynchronously |
+| **Batch Ops** | Run commands across any host group, synchronously or asynchronously; optional per-host retained-output cap (`max_output_bytes`) |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
 | **Connection Test** | Test all host SSH connections and report status |

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.4.0}/README.md

@@ -36,28 +36,30 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.3.0 Release Highlights
+## v2.4.0 Release Highlights
 
-v2.3.0 makes blocking SFTP operations timeout-safe, hardens async cancellation cleanup,
-and aligns the supported Python range and release tooling. See the
+v2.4.0 adds an opt-in retained-output cap for batch execution and cleans up logging
+handler resources, with default behavior and public result schemas unchanged. See the
 [full migration notes](./CHANGELOG.md) before upgrading automated callers.
 
-### SFTP Timeouts & Reliability
+### Bounded Batch Output
 
-- Blocking SFTP operations now support an inactivity timeout (default: `ConnectionConfig.timeout`, 30 s): uploads, downloads, directory listing, directory creation, removal, and file-info calls accept an optional `timeout` argument.
-- The synchronous `SSHClient` applies the timeout to the Paramiko SFTP channel, so a stalled read/write aborts the actual operation and raises `SSHFileTransferError`.
-- The asynchronous `AsyncSSHClient` bounds SFTP channel startup with a timeout and uses a progress-based inactivity watchdog to cancel stalled transfers, awaiting the aborted operation and preserving caller cancellation during cleanup.
-- Timed-out or cancelled SFTP sessions are closed and discarded, so a stale or desynchronized channel can never be reused.
+- `BatchExecutor` / `AsyncBatchExecutor` accept an optional `max_output_bytes` (default `None`): `None` keeps full `stdout`/`stderr`, while a positive value caps each host's retained streams and appends a `[output truncated: N bytes omitted]` marker.
+- Truncation is deterministic and UTF-8 byte-boundary safe, applies to `stdout` and `stderr` independently, and never changes command success/failure or exit codes.
+- The cap bounds the retained `BatchResult`; the SSH client may still hold full output transiently during execution, so it is not a process-wide RSS limit.
 
-### Release Engineering
+### Reliability
 
-- Python 3.9–3.14 are officially supported and CI-tested; `Requires-Python` remains `>=3.9`.
-- CI runs release-metadata validation for CHANGELOG.md-only changes.
-- Publish builds pin `build==1.5.0` and `twine==7.0.0`.
+- `setup_logging` now closes previous root-logger handlers before removing them, avoiding unclosed-file resource warnings when logging is reconfigured.
+- Connection-pool lifetime wording in the documentation now matches the actual behavior: internal pools are created lazily per host and closed as soon as that host finishes (including its retries).
+
+### Compatibility
+
+- Default behavior is unchanged (`max_output_bytes=None` retains full output) and the public `BatchResult` / `BatchHostResult` schemas are unchanged.
 
 ## Table of Contents
 
-- [v2.3.0 Release Highlights](#v230-release-highlights)
+- [v2.4.0 Release Highlights](#v240-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -205,7 +207,7 @@ with SSHClient(config) as client:
 | **File Transfer** | Upload/download via SFTP (`remote-cmd upload/download`) |
 | **Host Management** | CRUD with pluggable JSON or **SQLite** persistence |
 | **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
-| **Batch Ops** | Run commands across any host group, synchronously or asynchronously |
+| **Batch Ops** | Run commands across any host group, synchronously or asynchronously; optional per-host retained-output cap (`max_output_bytes`) |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
 | **Connection Test** | Test all host SSH connections and report status |

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.4.0}/remote_cmd/__init__.py

@@ -48,7 +48,7 @@ Remote CMD - SSH 远程服务器管理工具
     - 文档: 参见 docs/ 目录
 
 Author: Vae-Scrooge
-Version: 2.3.0（单一真相源见 remote_cmd._version）
+Version: 2.4.0（单一真相源见 remote_cmd._version）
 License: MIT
 """
 

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.4.0}/remote_cmd/_version.py

@@ -9,4 +9,4 @@
 - ``__version__`` 由 ``remote_cmd/__init__.py`` 导入并继续作为公共 API 导出。
 """
 
-__version__ = "2.3.0"
+__version__ = "2.4.0"

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.4.0}/remote_cmd/service/_host_runner.py

@@ -19,17 +19,71 @@
     ... )
 """
 
-from typing import Union
+from typing import Optional, Union
 
 from remote_cmd.core.host import Host
 from remote_cmd.core.ssh_client import CommandResult, ConnectionConfig
 from remote_cmd.service._types import BatchHostResult
 from remote_cmd.service.host_service import HostService
+from remote_cmd.utils.exceptions import ValidationError
+
+# 输出截断标记：追加在被截断的输出流末尾（确定性、便于测试与用户识别）
+OUTPUT_TRUNCATION_MARKER = "\n[output truncated: {omitted} bytes omitted]"
 
 # host 解析结果：成功返回 Host，失败返回带错误信息的 BatchHostResult
 ResolveOutcome = Union[Host, BatchHostResult]
 
 
+def validate_max_output_bytes(value: Optional[int]) -> Optional[int]:
+    """校验批量结果的单流输出上限并原样返回。
+
+    Args:
+        value: ``None``（不截断）或正整数（每台主机每个输出流保留的最大字节数）
+
+    Returns:
+        Optional[int]: 校验后的值
+
+    Raises:
+        ValidationError: 非 None、非正整数（bool 亦被拒绝，避免 True/False
+            被当作 1/0 使用）
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ValidationError(
+            f"max_output_bytes must be None or a positive integer, got: {value!r}"
+        )
+    return value
+
+
+def truncate_output(text: str, max_bytes: Optional[int]) -> str:
+    """按 UTF-8 字节上限确定性地截断单个输出流。
+
+    ``max_bytes`` 为 ``None`` 时原样返回（保持既有行为，绝不静默截断）。
+    超过上限时按 UTF-8 字节切片（丢弃被切断的多字节序列尾部）并追加固定
+    格式的截断标记，标记不计入 ``max_bytes``。截断只影响保留的输出文本，
+    不改变命令的成功/失败语义与退出码。
+
+    Args:
+        text: 已解码的输出文本
+        max_bytes: 保留的最大字节数（按 ``text.encode("utf-8")`` 度量），
+            或 ``None`` 表示不截断
+
+    Returns:
+        str: 原文本或截断后的文本（含标记）
+    """
+    if max_bytes is None or not text:
+        return text
+    encoded = text.encode("utf-8", errors="replace")
+    if len(encoded) <= max_bytes:
+        return text
+    prefix = encoded[:max_bytes].decode("utf-8", errors="ignore")
+    # omitted 按“原始字节数 - 实际保留字节数”计算：UTF-8 边界处的
+    # 残字节不会被错误计入保留量
+    omitted = len(encoded) - len(prefix.encode("utf-8"))
+    return prefix + OUTPUT_TRUNCATION_MARKER.format(omitted=omitted)
+
+
 def build_connection_config(host: Host, timeout: int) -> ConnectionConfig:
     """由主机配置构造 SSH 连接配置。
 
@@ -92,6 +146,7 @@ def to_host_result(
     command: str,
     cmd_result: CommandResult,
     duration: float,
+    max_output_bytes: Optional[int] = None,
 ) -> BatchHostResult:
     """由命令结果构造成功的单主机结果。
 
@@ -100,6 +155,8 @@ def to_host_result(
         command: 执行的命令
         cmd_result: 命令执行结果
         duration: 本次执行耗时（秒）
+        max_output_bytes: 每个输出流保留的最大字节数；``None`` 表示
+            保留完整输出（既有行为）。仅影响保留文本，不影响成功/失败
 
     Returns:
         BatchHostResult: 成功结果
@@ -108,8 +165,8 @@ def to_host_result(
         host=host_name,
         success=cmd_result.success,
         command=command,
-        stdout=cmd_result.stdout,
-        stderr=cmd_result.stderr,
+        stdout=truncate_output(cmd_result.stdout, max_output_bytes),
+        stderr=truncate_output(cmd_result.stderr, max_output_bytes),
         exit_code=cmd_result.exit_code,
         duration=duration,
     )

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.4.0}/remote_cmd/service/async_batch_executor.py

@@ -36,6 +36,7 @@ from remote_cmd.service._host_runner import (
     build_connection_config,
     resolve_host_or_error,
     to_host_result,
+    validate_max_output_bytes,
 )
 from remote_cmd.service._types import BatchHostResult, BatchResult, ProgressCallback
 from remote_cmd.service.host_service import HostService
@@ -61,6 +62,11 @@ class AsyncBatchExecutor:
             内部按主机惰性创建 AsyncConnectionPool，该主机执行结束后
             立即关闭；内部池上限 1 条连接，整批并发存活连接数受
             ``max_concurrency`` 约束。
+        max_output_bytes: 每台主机每个输出流（stdout/stderr）保留的最大
+            字节数（UTF-8），默认 ``None`` 保留完整输出（既有行为）。
+            设置正整数时输出会被确定性截断并追加 ``[output truncated: N
+            bytes omitted]`` 标记；截断不改变命令成功/失败与退出码。
+            仅约束保留的批量结果，客户端在执行期间仍可能短暂持有完整输出
 
     连接池所有权约定（与同步 BatchExecutor 一致）：
 
@@ -77,6 +83,7 @@ class AsyncBatchExecutor:
         max_concurrency: int = 10,
         command_timeout: int = 30,
         pool_factory: Optional[PoolFactory] = None,
+        max_output_bytes: Optional[int] = None,
     ) -> None:
         if max_concurrency < 1:
             raise ValueError(f"max_concurrency must be >= 1, got: {max_concurrency}")
@@ -86,6 +93,7 @@ class AsyncBatchExecutor:
         self._max_concurrency = max_concurrency
         self._command_timeout = command_timeout
         self._pool_factory = pool_factory
+        self._max_output_bytes = validate_max_output_bytes(max_output_bytes)
 
     async def execute(
         self,
@@ -318,7 +326,13 @@ class AsyncBatchExecutor:
                                 command,
                                 timeout=self._command_timeout,
                             )
-                    return to_host_result(host_name, command, cmd_result, time.time() - start)
+                    return to_host_result(
+                        host_name,
+                        command,
+                        cmd_result,
+                        time.time() - start,
+                        max_output_bytes=self._max_output_bytes,
+                    )
                 except Exception as e:  # noqa: BLE001
                     last_error = str(e)
                     last_duration = time.time() - start

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.4.0}/remote_cmd/service/batch_executor.py

@@ -40,6 +40,7 @@ from remote_cmd.service._host_runner import (
     build_connection_config,
     resolve_host_or_error,
     to_host_result,
+    validate_max_output_bytes,
 )
 from remote_cmd.service._types import (
     BatchHostResult,
@@ -84,6 +85,11 @@ class BatchExecutor:
             立即关闭；内部池 ``max_connections=1``，整批并发存活连接数受
             ``max_concurrency`` 约束。工厂返回的池类型须与内核匹配
             （见 PoolFactory 注释）。
+        max_output_bytes: 每台主机每个输出流（stdout/stderr）保留的最大
+            字节数（UTF-8），默认 ``None`` 保留完整输出（既有行为）。
+            设置正整数时输出会被确定性截断并追加 ``[output truncated: N
+            bytes omitted]`` 标记；截断不改变命令成功/失败与退出码。
+            仅约束保留的批量结果，客户端在执行期间仍可能短暂持有完整输出
 
     连接池所有权约定（与 AsyncBatchExecutor 一致）：
 
@@ -105,6 +111,7 @@ class BatchExecutor:
         command_timeout: int = 30,
         use_async: bool = False,
         pool_factory: Optional[PoolFactory] = None,
+        max_output_bytes: Optional[int] = None,
     ) -> None:
         if max_concurrency < 1:
             raise ValueError(f"max_concurrency must be >= 1, got: {max_concurrency}")
@@ -115,6 +122,7 @@ class BatchExecutor:
         self._command_timeout = command_timeout
         self._use_async = use_async
         self._pool_factory = pool_factory
+        self._max_output_bytes = validate_max_output_bytes(max_output_bytes)
         # 延迟导入以避免在未安装 asyncssh 的环境下的导入失败
         # 使用前向引用避免在模块加载期引入 asyncssh 硬依赖（开启 use_async 时才惰性导入）
         self._async_executor: Optional["AsyncBatchExecutor"] = None  # noqa: UP037
@@ -126,6 +134,7 @@ class BatchExecutor:
                 max_concurrency=max_concurrency,
                 command_timeout=command_timeout,
                 pool_factory=pool_factory,
+                max_output_bytes=self._max_output_bytes,
             )
 
     def execute(
@@ -458,7 +467,13 @@ class BatchExecutor:
                         # 连接池模式：复用主机连接，避免每次操作握手
                         with pool.acquire_context() as client:
                             cmd_result = client.execute(command, timeout=self._command_timeout)
-                        return to_host_result(host_name, command, cmd_result, time.time() - start)
+                        return to_host_result(
+                            host_name,
+                            command,
+                            cmd_result,
+                            time.time() - start,
+                            max_output_bytes=self._max_output_bytes,
+                        )
 
                     # 非连接池路径：try/finally 确保即使 execute() 抛异常，
                     # disconnect() 也会执行，避免 SSH 连接泄漏
@@ -469,7 +484,13 @@ class BatchExecutor:
                     finally:
                         client.disconnect()
 
-                    return to_host_result(host_name, command, cmd_result, time.time() - start)
+                    return to_host_result(
+                        host_name,
+                        command,
+                        cmd_result,
+                        time.time() - start,
+                        max_output_bytes=self._max_output_bytes,
+                    )
 
                 except Exception as e:  # noqa: BLE001
                     duration = time.time() - start

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.4.0}/remote_cmd/utils/logging_utils.py

@@ -12,6 +12,7 @@
     - 错误消息中的密码使用 [REDACTED] 替换
 """
 
+import contextlib
 import logging
 import re
 import sys
@@ -119,8 +120,12 @@ def setup_logging(
     root_logger = logging.getLogger()
     root_logger.setLevel(getattr(logging, level.upper(), logging.INFO))
 
-    # 清除已有处理器
-    root_logger.handlers.clear()
+    # 清除已有处理器：先关闭再移除，避免遗留打开的文件句柄
+    # （例如 RotatingFileHandler 的日志文件；重复配置会触发 ResourceWarning）
+    for handler in list(root_logger.handlers):
+        root_logger.removeHandler(handler)
+        with contextlib.suppress(Exception):
+            handler.close()
 
     # 创建格式化器
     if structured:

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.4.0/remote_cmd_manager.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remote_cmd_manager
-Version: 2.3.0
+Version: 2.4.0
 Summary: Cross-platform SSH remote server management tool (Linux/macOS/Windows) — lightweight, zero-configuration CLI and Python API for managing servers over SSH. Supports host CRUD, batch commands, file transfer, credential encryption, async execution, and more.
 Author-email: Vae-Scrooge <vaescrooge@gmail.com>
 License: MIT
@@ -89,28 +89,30 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.3.0 Release Highlights
+## v2.4.0 Release Highlights
 
-v2.3.0 makes blocking SFTP operations timeout-safe, hardens async cancellation cleanup,
-and aligns the supported Python range and release tooling. See the
+v2.4.0 adds an opt-in retained-output cap for batch execution and cleans up logging
+handler resources, with default behavior and public result schemas unchanged. See the
 [full migration notes](./CHANGELOG.md) before upgrading automated callers.
 
-### SFTP Timeouts & Reliability
+### Bounded Batch Output
 
-- Blocking SFTP operations now support an inactivity timeout (default: `ConnectionConfig.timeout`, 30 s): uploads, downloads, directory listing, directory creation, removal, and file-info calls accept an optional `timeout` argument.
-- The synchronous `SSHClient` applies the timeout to the Paramiko SFTP channel, so a stalled read/write aborts the actual operation and raises `SSHFileTransferError`.
-- The asynchronous `AsyncSSHClient` bounds SFTP channel startup with a timeout and uses a progress-based inactivity watchdog to cancel stalled transfers, awaiting the aborted operation and preserving caller cancellation during cleanup.
-- Timed-out or cancelled SFTP sessions are closed and discarded, so a stale or desynchronized channel can never be reused.
+- `BatchExecutor` / `AsyncBatchExecutor` accept an optional `max_output_bytes` (default `None`): `None` keeps full `stdout`/`stderr`, while a positive value caps each host's retained streams and appends a `[output truncated: N bytes omitted]` marker.
+- Truncation is deterministic and UTF-8 byte-boundary safe, applies to `stdout` and `stderr` independently, and never changes command success/failure or exit codes.
+- The cap bounds the retained `BatchResult`; the SSH client may still hold full output transiently during execution, so it is not a process-wide RSS limit.
 
-### Release Engineering
+### Reliability
 
-- Python 3.9–3.14 are officially supported and CI-tested; `Requires-Python` remains `>=3.9`.
-- CI runs release-metadata validation for CHANGELOG.md-only changes.
-- Publish builds pin `build==1.5.0` and `twine==7.0.0`.
+- `setup_logging` now closes previous root-logger handlers before removing them, avoiding unclosed-file resource warnings when logging is reconfigured.
+- Connection-pool lifetime wording in the documentation now matches the actual behavior: internal pools are created lazily per host and closed as soon as that host finishes (including its retries).
+
+### Compatibility
+
+- Default behavior is unchanged (`max_output_bytes=None` retains full output) and the public `BatchResult` / `BatchHostResult` schemas are unchanged.
 
 ## Table of Contents
 
-- [v2.3.0 Release Highlights](#v230-release-highlights)
+- [v2.4.0 Release Highlights](#v240-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -258,7 +260,7 @@ with SSHClient(config) as client:
 | **File Transfer** | Upload/download via SFTP (`remote-cmd upload/download`) |
 | **Host Management** | CRUD with pluggable JSON or **SQLite** persistence |
 | **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
-| **Batch Ops** | Run commands across any host group, synchronously or asynchronously |
+| **Batch Ops** | Run commands across any host group, synchronously or asynchronously; optional per-host retained-output cap (`max_output_bytes`) |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
 | **Connection Test** | Test all host SSH connections and report status |

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.4.0}/tests/test_async_batch_executor.py

@@ -11,6 +11,7 @@ from remote_cmd.core.async_connection_pool import AsyncConnectionPool
 from remote_cmd.core.async_ssh_client import AsyncSSHClient
 from remote_cmd.core.host import Host
 from remote_cmd.core.ssh_client import CommandResult, ConnectionConfig
+from remote_cmd.service._host_runner import OUTPUT_TRUNCATION_MARKER
 from remote_cmd.service.async_batch_executor import AsyncBatchExecutor
 from remote_cmd.service.batch_executor import BatchExecutor, BatchHostResult
 from remote_cmd.utils.exceptions import (
@@ -18,6 +19,7 @@ from remote_cmd.utils.exceptions import (
     PoolClosedError,
     SSHAuthenticationError,
     SSHTimeoutError,
+    ValidationError,
 )
 
 # ============================================================================
@@ -940,3 +942,119 @@ class TestAsyncBatchExecutorInternalPoolLifecycle:
         assert FlakyAsyncClient.created[0].calls == 3
         assert pools[0]._closed
         assert not FlakyAsyncClient.created[0].is_connected()
+
+
+# ============================================================================
+# v2.4：max_output_bytes 保留输出上限（异步语义与同步对齐）
+# ============================================================================
+
+
+def _marker(omitted: int) -> str:
+    return OUTPUT_TRUNCATION_MARKER.format(omitted=omitted)
+
+
+class TestAsyncBatchExecutorOutputCap:
+    """异步执行器 max_output_bytes 语义（默认 None = 完整输出）"""
+
+    @pytest.mark.asyncio
+    async def test_default_none_retains_full_output(self, mock_async_client_class):
+        cm, instance = mock_async_client_class
+        payload = "x" * 8192
+        instance.execute = AsyncMock(return_value=CommandResult("uptime", payload, payload, 0))
+        host = Host(name="srv1", hostname="10.0.0.1", username="admin")
+        ex = AsyncBatchExecutor(host_service=make_mock_service([host]))
+        result = await ex.execute(["srv1"], "uptime")
+        host_result = result.results["srv1"]
+        assert host_result.stdout == payload
+        assert host_result.stderr == payload
+        assert "[output truncated" not in host_result.stdout
+
+    @pytest.mark.asyncio
+    async def test_positive_cap_truncates_stdout_and_stderr(self, mock_async_client_class):
+        cm, instance = mock_async_client_class
+        instance.execute = AsyncMock(return_value=CommandResult("uptime", "o" * 500, "e" * 700, 0))
+        host = Host(name="srv1", hostname="10.0.0.1", username="admin")
+        ex = AsyncBatchExecutor(host_service=make_mock_service([host]), max_output_bytes=100)
+        result = await ex.execute(["srv1"], "uptime")
+        host_result = result.results["srv1"]
+        assert host_result.stdout == "o" * 100 + _marker(400)
+        assert host_result.stderr == "e" * 100 + _marker(600)
+        assert host_result.success is True
+
+    @pytest.mark.asyncio
+    async def test_below_and_exact_boundary_unchanged(self, mock_async_client_class):
+        cm, instance = mock_async_client_class
+        instance.execute = AsyncMock(return_value=CommandResult("uptime", "exact", "small", 0))
+        host = Host(name="srv1", hostname="10.0.0.1", username="admin")
+
+        ex = AsyncBatchExecutor(host_service=make_mock_service([host]), max_output_bytes=5)
+        result = await ex.execute(["srv1"], "uptime")
+        assert result.results["srv1"].stdout == "exact"
+        assert result.results["srv1"].stderr == "small"
+
+        ex = AsyncBatchExecutor(host_service=make_mock_service([host]), max_output_bytes=64)
+        result = await ex.execute(["srv1"], "uptime")
+        assert result.results["srv1"].stdout == "exact"
+
+    @pytest.mark.asyncio
+    async def test_cap_preserves_failure_semantics(self, mock_async_client_class):
+        cm, instance = mock_async_client_class
+        instance.execute = AsyncMock(
+            return_value=CommandResult("uptime", "x" * 1000, "e" * 1000, 7)
+        )
+        host = Host(name="srv1", hostname="10.0.0.1", username="admin")
+        ex = AsyncBatchExecutor(host_service=make_mock_service([host]), max_output_bytes=16)
+        result = await ex.execute(["srv1"], "uptime")
+        host_result = result.results["srv1"]
+        assert host_result.success is False
+        assert host_result.exit_code == 7
+        assert host_result.stdout.startswith("x" * 16)
+        assert host_result.stderr.startswith("e" * 16)
+
+    @pytest.mark.parametrize("bad", [0, -1, True, False, 1.5, "64"])
+    def test_invalid_max_output_bytes_rejected(self, bad):
+        with pytest.raises(ValidationError, match="max_output_bytes"):
+            AsyncBatchExecutor(host_service=MagicMock(), max_output_bytes=bad)
+
+    @pytest.mark.asyncio
+    async def test_large_synthetic_output_bounded(self, mock_async_client_class):
+        cm, instance = mock_async_client_class
+        chunk = "z" * (256 * 1024)
+        instance.execute = AsyncMock(return_value=CommandResult("uptime", chunk, chunk, 0))
+        hosts = [
+            Host(name=f"srv{i}", hostname=f"10.0.0.{i + 1}", username="admin") for i in range(10)
+        ]
+        ex = AsyncBatchExecutor(host_service=make_mock_service(hosts), max_output_bytes=4096)
+        result = await ex.execute([h.name for h in hosts], "uptime")
+        assert result.success == 10
+        retained = sum(len(r.stdout) + len(r.stderr) for r in result.results.values())
+        assert retained <= 10 * 2 * (4096 + 64)
+        assert retained < 10 * 2 * len(chunk) // 10
+
+
+class TestOutputCapParity:
+    @pytest.mark.asyncio
+    async def test_sync_and_async_truncation_equivalent(self, mock_async_client_class):
+        cm, instance = mock_async_client_class
+        stdout = ("o" * 5000) + ("é" * 100)
+        stderr = "e" * 3000
+        instance.execute = AsyncMock(return_value=CommandResult("uptime", stdout, stderr, 7))
+        host = Host(name="srv1", hostname="10.0.0.1", username="admin")
+
+        async_ex = AsyncBatchExecutor(host_service=make_mock_service([host]), max_output_bytes=257)
+        async_result = await async_ex.execute(["srv1"], "uptime")
+
+        with patch("remote_cmd.service.batch_executor.SSHClient") as mock_cls:
+            inst = MagicMock()
+            mock_cls.return_value = inst
+            inst.execute.return_value = CommandResult("uptime", stdout, stderr, 7)
+            sync_ex = BatchExecutor(host_service=make_mock_service([host]), max_output_bytes=257)
+            sync_result = sync_ex.execute(["srv1"], "uptime")
+
+        sync_host = sync_result.results["srv1"]
+        async_host = async_result.results["srv1"]
+        assert sync_host.stdout == async_host.stdout
+        assert sync_host.stderr == async_host.stderr
+        assert sync_host.exit_code == async_host.exit_code == 7
+        assert sync_host.success is async_host.success is False
+        assert "[output truncated" in sync_host.stdout

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.4.0}/tests/test_batch_executor.py

@@ -8,8 +8,13 @@ import pytest
 from remote_cmd.core.host import Host
 from remote_cmd.core.ssh_client import CommandResult
 from remote_cmd.core.sync_connection_pool import SyncConnectionPool
+from remote_cmd.service._host_runner import OUTPUT_TRUNCATION_MARKER
 from remote_cmd.service.batch_executor import BatchExecutor, BatchHostResult, BatchResult
-from remote_cmd.utils.exceptions import CredentialError, SSHAuthenticationError
+from remote_cmd.utils.exceptions import (
+    CredentialError,
+    SSHAuthenticationError,
+    ValidationError,
+)
 
 
 def make_mock_service(hosts: list):
@@ -847,3 +852,97 @@ class TestBatchExecutorInternalPoolLifecycle:
         assert AuthFailClient.created[0].calls == 1
         assert pools[0]._closed
         assert not AuthFailClient.created[0].is_connected()
+
+
+# ============================================================================
+# v2.4：max_output_bytes 保留输出上限
+# ============================================================================
+
+
+def _marker(omitted: int) -> str:
+    return OUTPUT_TRUNCATION_MARKER.format(omitted=omitted)
+
+
+class TestBatchExecutorOutputCap:
+    """同步执行器 max_output_bytes 语义（默认 None = 完整输出）"""
+
+    @staticmethod
+    def _run(stdout="", stderr="", exit_code=0, max_output_bytes=None, hosts=1):
+        host_list = [
+            Host(name=f"srv{i}", hostname=f"10.0.0.{i + 1}", username="admin") for i in range(hosts)
+        ]
+        service = make_mock_service(host_list)
+        with patch("remote_cmd.service.batch_executor.SSHClient") as mock_cls:
+            inst = MagicMock()
+            mock_cls.return_value = inst
+            inst.execute.return_value = CommandResult("true", stdout, stderr, exit_code)
+            executor = BatchExecutor(host_service=service, max_output_bytes=max_output_bytes)
+            return executor.execute([h.name for h in host_list], "true")
+
+    def test_default_none_retains_full_output(self):
+        payload = "x" * 8192
+        result = self._run(stdout=payload, stderr=payload)
+        host_result = result.results["srv0"]
+        assert host_result.stdout == payload
+        assert host_result.stderr == payload
+        assert "[output truncated" not in host_result.stdout
+
+    def test_positive_cap_truncates_stdout(self):
+        result = self._run(stdout="x" * 1000, max_output_bytes=64)
+        host_result = result.results["srv0"]
+        assert host_result.stdout == "x" * 64 + _marker(936)
+        assert host_result.stderr == ""
+        assert host_result.success is True
+
+    def test_positive_cap_truncates_stderr(self):
+        result = self._run(stderr="e" * 500, max_output_bytes=100)
+        host_result = result.results["srv0"]
+        assert host_result.stderr == "e" * 100 + _marker(400)
+        assert host_result.stdout == ""
+
+    def test_output_below_limit_unchanged(self):
+        result = self._run(stdout="small", stderr="tiny", max_output_bytes=1024)
+        host_result = result.results["srv0"]
+        assert host_result.stdout == "small"
+        assert host_result.stderr == "tiny"
+        assert "[output truncated" not in host_result.stdout + host_result.stderr
+
+    def test_exact_boundary_unchanged(self):
+        payload = "x" * 64
+        result = self._run(stdout=payload, stderr=payload, max_output_bytes=64)
+        host_result = result.results["srv0"]
+        assert host_result.stdout == payload
+        assert host_result.stderr == payload
+
+    def test_unicode_boundary_not_split(self):
+        # "é" 为 2 字节；上限 5 字节时只能完整保留 2 个字符（保留 4 字节）
+        result = self._run(stdout="é" * 10, max_output_bytes=5)
+        out = result.results["srv0"].stdout
+        assert out.startswith("é" * 2)
+        assert "é" * 3 not in out
+        assert "\ufffd" not in out
+        assert out.endswith(_marker(20 - 4))
+
+    def test_cap_preserves_success_and_failure_semantics(self):
+        ok = self._run(stdout="x" * 1000, exit_code=0, max_output_bytes=10)
+        assert ok.results["srv0"].success is True
+        assert ok.results["srv0"].exit_code == 0
+
+        bad = self._run(stdout="x" * 1000, exit_code=1, max_output_bytes=10)
+        assert bad.results["srv0"].success is False
+        assert bad.results["srv0"].exit_code == 1
+
+    @pytest.mark.parametrize("bad", [0, -1, True, False, 1.5, "64"])
+    def test_invalid_max_output_bytes_rejected(self, bad):
+        with pytest.raises(ValidationError, match="max_output_bytes"):
+            BatchExecutor(host_service=MagicMock(), max_output_bytes=bad)
+
+    @patch("remote_cmd.service.batch_executor.SSHClient")
+    def test_large_synthetic_output_bounded(self, _mock_ssh_class):
+        chunk = "z" * (256 * 1024)
+        result = self._run(stdout=chunk, stderr=chunk, hosts=20, max_output_bytes=4096)
+        assert result.success == 20
+        retained = sum(len(r.stdout) + len(r.stderr) for r in result.results.values())
+        marker_allowance = 64  # 标记本身很小，给足空间
+        assert retained <= 20 * 2 * (4096 + marker_allowance)
+        assert retained < 20 * 2 * len(chunk) // 10

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.4.0}/tests/test_logging_utils.py

@@ -194,6 +194,20 @@ class TestSetupLogging:
         second = set(logging.getLogger().handlers)
         assert not (first & second)
 
+    def test_previous_file_handler_closed_before_removal(self, tmp_path):
+        """测试：重新配置日志时旧的文件处理器被关闭（无未关闭句柄）"""
+        root = logging.getLogger()
+        try:
+            setup_logging(log_file=str(tmp_path / "a.log"))
+            first = [h for h in root.handlers if isinstance(h, logging.FileHandler)][-1]
+            assert first.stream is not None
+
+            setup_logging(log_file=str(tmp_path / "b.log"))
+            assert first.stream is None  # close() 释放底层文件流
+            assert first not in root.handlers
+        finally:
+            setup_logging()
+
 
 class TestLoggerAdapter:
     """带上下文日志适配器测试"""