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

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: remote_cmd_manager
-Version: 2.1.0
-Summary: SSH 远程服务器管理工具 / Python SSH remote server management tool
+Version: 2.3.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
 Project-URL: Homepage, https://github.com/Vae-Scrooge/remote-cmd
@@ -9,8 +9,8 @@ Project-URL: Repository, https://github.com/Vae-Scrooge/remote-cmd
 Project-URL: Documentation, https://github.com/Vae-Scrooge/remote-cmd#readme
 Project-URL: Bug Tracker, https://github.com/Vae-Scrooge/remote-cmd/issues
 Project-URL: Download, https://pypi.org/project/remote_cmd_manager/
-Keywords: ssh,remote,server-management,sysadmin,devops
-Classifier: Development Status :: 4 - Beta
+Keywords: ssh,remote,server-management,sysadmin,devops,cross-platform
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
 Classifier: License :: OSI Approved :: MIT License
@@ -18,9 +18,15 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: System :: Networking
 Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -42,7 +48,7 @@ Requires-Dist: ruff>=0.4; extra == "dev"
 Requires-Dist: mypy>=1.10; extra == "dev"
 Requires-Dist: keyring>=24.0; extra == "dev"
 Provides-Extra: docs
-Requires-Dist: pdoc<16,>=15; extra == "docs"
+Requires-Dist: pdoc==15.0.4; extra == "docs"
 Dynamic: license-file
 
 <p align="center">
@@ -54,6 +60,7 @@ Dynamic: license-file
   <img src="https://img.shields.io/github/actions/workflow/status/Vae-Scrooge/remote-cmd/ci.yml?style=for-the-badge&logo=githubactions&label=CI" alt="CI">
 </p>
 
+<p align="center"><strong>Tested on Linux, macOS, and Windows</strong></p>
 <h1 align="center">Remote CMD — SSH Server Management<br><small>Without the Overhead</small></h1>
 
 <p align="center">
@@ -71,12 +78,6 @@ Dynamic: license-file
   <a href="#contributing">Contributing</a>
 </p>
 
-<p align="center">
-  <a href="https://asciinema.org/a/9yLeYj73muPUuAQY" target="_blank">
-    <img src="https://asciinema.org/a/9yLeYj73muPUuAQY.svg" width="720" alt="Demo">
-  </a>
-</p>
-
 ---
 
 **Remote CMD** is a lightweight Python CLI + API for managing servers over SSH. Add hosts, run commands, transfer files, and organize hosts with tags — no Ansible DSL or shell loops required.
@@ -88,32 +89,28 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.1.0 Release Highlights
+## v2.3.0 Release Highlights
 
-v2.1.0 contains both major implementation changes and a final release-hardening pass. See the
+v2.3.0 makes blocking SFTP operations timeout-safe, hardens async cancellation cleanup,
+and aligns the supported Python range and release tooling. See the
 [full migration notes](./CHANGELOG.md) before upgrading automated callers.
 
-### Major Implementation Changes
+### SFTP Timeouts & Reliability
 
-- Paramiko command execution drains stdout and stderr before retrieving the exit status, preventing SSH channel-window deadlocks on large output.
-- Paramiko command timeouts are wall-clock enforced; a silent or hung command closes its channel and raises `SSHCommandTimeoutError`.
-- `AsyncBatchExecutor` now uses `AsyncConnectionPool` for multi-host and retry workloads, reusing connections across attempts.
-- `pool_factory` enables caller-supplied pools; external pools are caller-owned and never closed by either executor, while internally created pools are closed automatically after `execute()`.
-- Retries classify permanent failures (authentication, credentials, configuration, validation, and programming errors) as non-retryable; unknown `Exception` subclasses remain retryable for backward compatibility. `retry_delay` is now the exponential-backoff base and full jitter is applied with a 60-second cap.
-- Unknown hosts produce per-host failure results instead of aborting a multi-host batch, and duplicate host names are executed once.
-- The exception hierarchy adds `SSHAuthenticationError`, `SSHTimeoutError`, `SSHCommandTimeoutError`, `CredentialError`, and the `ConfigurationError` alias without removing existing catch paths.
-- Environment-variable names are validated before shell interpolation, and command text is excluded from library logs and execution errors.
-- `remote-cmd run` supports `--timeout/-T` for command execution limits.
+- 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.
 
-### Final Release Hardening
+### Release Engineering
 
-- Sync and async pools re-check their closed state after semaphore acquisition, preventing a shutdown race from issuing a connection from a closed pool.
-- `BatchExecutor(use_async=True)` now reports an actionable error when called from an active event loop; use `AsyncBatchExecutor.execute()` there instead.
-- The Paramiko stderr drain join is bounded to prevent an exceptional reader path from blocking the caller indefinitely.
+- 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`.
 
 ## Table of Contents
 
-- [v2.1.0 Release Highlights](#v210-release-highlights)
+- [v2.3.0 Release Highlights](#v230-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -270,6 +267,20 @@ with SSHClient(config) as client:
 
 ---
 
+## Cross-Platform Support
+
+`remote-cmd` is a pure-Python client, **tested and supported on Linux, macOS, and Windows**. No native dependencies or platform-specific builds are required.
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Linux | ✅ Fully tested | Primary development platform |
+| macOS | ✅ Supported | Use `brew install openssh` for a newer OpenSSH |
+| Windows | ✅ Supported | PowerShell / CMD / WSL all work |
+
+> **Note on Windows file permissions:** Credential encryption keys are protected with `0600` permissions on Unix. On Windows this restriction is not enforced by the filesystem — the key file is still encrypted at rest. For production Windows use, consider adding filesystem-level ACLs.
+
+---
+
 ## Installation
 
 ```bash
@@ -309,14 +320,14 @@ are simply not exported.
 | [Changelog](./CHANGELOG.md) | Release history |
 | [Mobile Remote Guide](./MOBILE-REMOTE-GUIDE.md) | Manage servers from your phone |
 
-> **Note:** The documentation center and tutorials are maintained in **Chinese**. See
+> **Note:** The documentation center and tutorials are maintained in **English**. See
 > [README.zh-CN.md](./README.zh-CN.md) for the Chinese version of this page.
 
 ---
 
 ## Project Status
 
-**Beta.** The core API is stable. Breaking changes will be communicated via semantic versioning.
+**Stable.** The core API is stable and versioned under semantic versioning. Breaking changes are communicated via major-version bumps, and the public API surface has been stable since the 1.x line.
 
 **Roadmap:**
 - [x] Async SSH operations (parallel execution) — v1.1.0

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

@@ -7,6 +7,7 @@
   <img src="https://img.shields.io/github/actions/workflow/status/Vae-Scrooge/remote-cmd/ci.yml?style=for-the-badge&logo=githubactions&label=CI" alt="CI">
 </p>
 
+<p align="center"><strong>Tested on Linux, macOS, and Windows</strong></p>
 <h1 align="center">Remote CMD — SSH Server Management<br><small>Without the Overhead</small></h1>
 
 <p align="center">
@@ -24,12 +25,6 @@
   <a href="#contributing">Contributing</a>
 </p>
 
-<p align="center">
-  <a href="https://asciinema.org/a/9yLeYj73muPUuAQY" target="_blank">
-    <img src="https://asciinema.org/a/9yLeYj73muPUuAQY.svg" width="720" alt="Demo">
-  </a>
-</p>
-
 ---
 
 **Remote CMD** is a lightweight Python CLI + API for managing servers over SSH. Add hosts, run commands, transfer files, and organize hosts with tags — no Ansible DSL or shell loops required.
@@ -41,32 +36,28 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.1.0 Release Highlights
+## v2.3.0 Release Highlights
 
-v2.1.0 contains both major implementation changes and a final release-hardening pass. See the
+v2.3.0 makes blocking SFTP operations timeout-safe, hardens async cancellation cleanup,
+and aligns the supported Python range and release tooling. See the
 [full migration notes](./CHANGELOG.md) before upgrading automated callers.
 
-### Major Implementation Changes
+### SFTP Timeouts & Reliability
 
-- Paramiko command execution drains stdout and stderr before retrieving the exit status, preventing SSH channel-window deadlocks on large output.
-- Paramiko command timeouts are wall-clock enforced; a silent or hung command closes its channel and raises `SSHCommandTimeoutError`.
-- `AsyncBatchExecutor` now uses `AsyncConnectionPool` for multi-host and retry workloads, reusing connections across attempts.
-- `pool_factory` enables caller-supplied pools; external pools are caller-owned and never closed by either executor, while internally created pools are closed automatically after `execute()`.
-- Retries classify permanent failures (authentication, credentials, configuration, validation, and programming errors) as non-retryable; unknown `Exception` subclasses remain retryable for backward compatibility. `retry_delay` is now the exponential-backoff base and full jitter is applied with a 60-second cap.
-- Unknown hosts produce per-host failure results instead of aborting a multi-host batch, and duplicate host names are executed once.
-- The exception hierarchy adds `SSHAuthenticationError`, `SSHTimeoutError`, `SSHCommandTimeoutError`, `CredentialError`, and the `ConfigurationError` alias without removing existing catch paths.
-- Environment-variable names are validated before shell interpolation, and command text is excluded from library logs and execution errors.
-- `remote-cmd run` supports `--timeout/-T` for command execution limits.
+- 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.
 
-### Final Release Hardening
+### Release Engineering
 
-- Sync and async pools re-check their closed state after semaphore acquisition, preventing a shutdown race from issuing a connection from a closed pool.
-- `BatchExecutor(use_async=True)` now reports an actionable error when called from an active event loop; use `AsyncBatchExecutor.execute()` there instead.
-- The Paramiko stderr drain join is bounded to prevent an exceptional reader path from blocking the caller indefinitely.
+- 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`.
 
 ## Table of Contents
 
-- [v2.1.0 Release Highlights](#v210-release-highlights)
+- [v2.3.0 Release Highlights](#v230-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -223,6 +214,20 @@ with SSHClient(config) as client:
 
 ---
 
+## Cross-Platform Support
+
+`remote-cmd` is a pure-Python client, **tested and supported on Linux, macOS, and Windows**. No native dependencies or platform-specific builds are required.
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Linux | ✅ Fully tested | Primary development platform |
+| macOS | ✅ Supported | Use `brew install openssh` for a newer OpenSSH |
+| Windows | ✅ Supported | PowerShell / CMD / WSL all work |
+
+> **Note on Windows file permissions:** Credential encryption keys are protected with `0600` permissions on Unix. On Windows this restriction is not enforced by the filesystem — the key file is still encrypted at rest. For production Windows use, consider adding filesystem-level ACLs.
+
+---
+
 ## Installation
 
 ```bash
@@ -262,14 +267,14 @@ are simply not exported.
 | [Changelog](./CHANGELOG.md) | Release history |
 | [Mobile Remote Guide](./MOBILE-REMOTE-GUIDE.md) | Manage servers from your phone |
 
-> **Note:** The documentation center and tutorials are maintained in **Chinese**. See
+> **Note:** The documentation center and tutorials are maintained in **English**. See
 > [README.zh-CN.md](./README.zh-CN.md) for the Chinese version of this page.
 
 ---
 
 ## Project Status
 
-**Beta.** The core API is stable. Breaking changes will be communicated via semantic versioning.
+**Stable.** The core API is stable and versioned under semantic versioning. Breaking changes are communicated via major-version bumps, and the public API surface has been stable since the 1.x line.
 
 **Roadmap:**
 - [x] Async SSH operations (parallel execution) — v1.1.0

{remote_cmd_manager-2.1.0 → remote_cmd_manager-2.3.0}/pyproject.toml

@@ -5,16 +5,16 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "remote_cmd_manager"
 dynamic = ["version"]
-description = "SSH 远程服务器管理工具 / Python SSH remote server management tool"
+description = "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."
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "MIT" }
 authors = [
     { name = "Vae-Scrooge", email = "vaescrooge@gmail.com" },
 ]
-keywords = ["ssh", "remote", "server-management", "sysadmin", "devops"]
+keywords = ["ssh", "remote", "server-management", "sysadmin", "devops", "cross-platform"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Intended Audience :: System Administrators",
     "License :: OSI Approved :: MIT License",
@@ -22,9 +22,15 @@ classifiers = [
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: System :: Systems Administration",
     "Topic :: System :: Networking",
     "Environment :: Console",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
 ]
 dependencies = [
     "paramiko>=3.0",
@@ -50,8 +56,10 @@ dev = [
     # 测试 keyring 凭据提供者（生产为可选依赖，测试环境固定安装）
     "keyring>=24.0",
 ]
-# 文档生成（pdoc>=16 需 Python>=3.10，固定到 15.x 以兼容 requires-python>=3.9）
-docs = ["pdoc>=15,<16"]
+# 文档生成（pdoc>=16 需 Python>=3.10，固定到 15.x 以兼容 requires-python>=3.9）。
+# 精确 pin 15.0.4：pdoc HTML 输出随版本/解释器变化，docs/api 漂移门禁
+# （scripts/check_docs_drift.py）要求生成结果可复现。
+docs = ["pdoc==15.0.4"]
 
 [project.urls]
 Homepage = "https://github.com/Vae-Scrooge/remote-cmd"

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

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

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

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

{remote_cmd_manager-2.1.0 → remote_cmd_manager-2.3.0}/remote_cmd/core/async_connection_pool.py

@@ -26,6 +26,7 @@ from remote_cmd.service._pool_policy import (
     lifetime_expired,
     should_close,
 )
+from remote_cmd.utils.exceptions import PoolClosedError
 
 logger = logging.getLogger(__name__)
 
@@ -120,17 +121,18 @@ class AsyncConnectionPool:
 
         Raises:
             SSHConnectionError: 创建连接失败
-            RuntimeError: 连接池已关闭（close_all 之后）
+            PoolClosedError: 连接池已关闭（close_all 之后），
+                同时是 RuntimeError 子类（既有捕获行为不变）
         """
         if self._closed:
-            raise RuntimeError("connection pool is closed")
+            raise PoolClosedError("connection pool is closed")
         await self._semaphore.acquire()
         # 竞态守卫：等待信号量期间 close_all() 可能已完成——
         # 取得槽位后必须复查，已关闭则归还槽位并抛出既有错误，
         # 否则会向调用方发放来自已关闭池的连接
         if self._closed:
             self._semaphore.release()
-            raise RuntimeError("connection pool is closed")
+            raise PoolClosedError("connection pool is closed")
         try:
             # 优先复用空闲连接
             while not self._free.empty():

{remote_cmd_manager-2.1.0 → remote_cmd_manager-2.3.0}/remote_cmd/core/async_ssh_client.py

@@ -14,9 +14,12 @@
 - 密码、密钥等敏感信息不入日志（沿用项目 SensitiveDataFilter 规范）。
 """
 
+import asyncio
+import contextlib
 import logging
 import shlex
 import stat
+from collections.abc import Awaitable, Callable, Sequence
 from pathlib import Path
 from typing import Any, Optional
 
@@ -34,6 +37,7 @@ from remote_cmd.utils.exceptions import (
     SSHConnectionError,
     SSHFileTransferError,
     SSHTimeoutError,
+    ValidationError,
 )
 
 logger = logging.getLogger(__name__)
@@ -286,45 +290,169 @@ class AsyncSSHClient:
     # ------------------------------------------------------------------
     # SFTP / 文件传输
     # ------------------------------------------------------------------
-    async def _get_sftp(self) -> asyncssh.SFTPClient:
+    async def _get_sftp(self, timeout: Optional[float] = None) -> asyncssh.SFTPClient:
+        """获取 SFTP 客户端（延迟初始化）。
+
+        v2.3：打开 SFTP channel 本身也受有效超时约束，避免握手阶段永久挂起。
+        """
         conn = await self._get_conn()
         if self._sftp is None:
+            effective = self._effective_sftp_timeout(timeout)
             try:
-                self._sftp = await conn.start_sftp_client()
+                self._sftp = await asyncio.wait_for(conn.start_sftp_client(), timeout=effective)
+            except asyncio.TimeoutError as e:
+                raise SSHFileTransferError(
+                    f"failed to open SFTP channel: timed out after {effective:g} seconds"
+                ) from e
             except (OSError, asyncssh.Error) as e:
                 raise SSHFileTransferError(f"failed to open SFTP channel: {e}") from e
         return self._sftp
 
-    async def upload_file(self, local_path: str, remote_path: str) -> None:
-        """异步上传本地文件到远程服务器。"""
-        sftp = await self._get_sftp()
+    def _effective_sftp_timeout(self, timeout: Optional[float]) -> float:
+        """返回 SFTP 操作的有效 inactivity 超时（秒）。
+
+        显式 timeout 优先，否则回退到 ``ConnectionConfig.timeout``。
+        """
+        if timeout is not None:
+            if timeout <= 0:
+                raise ValidationError(f"timeout must be > 0, got: {timeout}")
+            return timeout
+        return self.config.timeout
+
+    def _discard_sftp(self) -> None:
+        """关闭并丢弃缓存的 SFTP 会话（超时后防止复用可能失步的会话）。"""
+        sftp, self._sftp = self._sftp, None
+        if sftp is not None:
+            with contextlib.suppress(Exception):
+                sftp.exit()
+
+    async def _run_sftp_operation(
+        self,
+        operation: Callable[[Callable[..., None]], Awaitable[Any]],
+        timeout: Optional[float],
+        description: str,
+    ) -> Any:
+        """运行 SFTP 操作并施加 inactivity（静默）超时。
+
+        asyncssh 的 SFTP API 没有原生超时参数，因此使用 watchdog：
+        ``operation`` 收到一个 progress 回调（传给 ``put``/``get`` 的
+        ``progress_handler``），每次有数据进展就刷新时间戳；超过有效超时
+        没有任何进展则取消操作、丢弃失步的 SFTP 会话并抛出
+        ``SSHFileTransferError``。只要数据持续流动，长时间传输不会被打断。
+        """
+        effective = self._effective_sftp_timeout(timeout)
+        loop = asyncio.get_running_loop()
+        last_activity = loop.time()
+
+        def _mark_progress(*_args: Any) -> None:
+            nonlocal last_activity
+            last_activity = loop.time()
+
+        task = asyncio.ensure_future(operation(_mark_progress))
+        interval = min(0.5, max(effective / 10.0, 0.01))
+        cancelled: Optional[asyncio.CancelledError] = None
+        try:
+            while True:
+                done, _pending = await asyncio.wait({task}, timeout=interval)
+                if task in done:
+                    return task.result()
+                if loop.time() - last_activity >= effective:
+                    break
+        except asyncio.CancelledError as exc:
+            # 外层取消：记录后统一走清理路径（不在此处 await，避免
+            # 取消事件再次进入本处理器）
+            cancelled = exc
+
+        # 统一清理：立即丢弃可能失步的 SFTP 会话；取消并等待子任务收尾。
+        # shield 确保清理期间到达的再次取消只打断"等待"本身，而不会
+        # 把清理过程转换成超时错误或被整体吞掉。
+        self._discard_sftp()
+        task.cancel()
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            if not task.cancelled():
+                # 清理期间外层再次取消：保留取消语义
+                raise
+        except Exception:  # noqa: BLE001 - 子任务失败不应掩盖超时/取消语义
+            pass
+
+        if cancelled is not None:
+            raise cancelled
+        raise SSHFileTransferError(
+            f"{description} timed out after {effective:g} seconds of inactivity"
+        )
+
+    async def upload_file(
+        self,
+        local_path: str,
+        remote_path: str,
+        timeout: Optional[float] = None,
+    ) -> None:
+        """异步上传本地文件到远程服务器。
+
+        Args:
+            local_path: 本地文件路径
+            remote_path: 远程目标路径
+            timeout: inactivity 超时（秒）；None 表示使用
+                ``ConnectionConfig.timeout``。静默超过该时长即中止
+        """
+        sftp = await self._get_sftp(timeout)
         local_file = Path(local_path)
         if not local_file.exists():
             raise SSHFileTransferError(f"Local file not found: {local_path}")
         logger.info(f"uploading file: {local_path} -> {remote_path}")
+
+        async def _operation(progress: Callable[..., None]) -> None:
+            await sftp.put(str(local_file), remote_path, progress_handler=progress)
+
         try:
-            await sftp.put(str(local_file), remote_path)
+            await self._run_sftp_operation(_operation, timeout, "file upload")
         except (OSError, asyncssh.Error) as e:
             raise SSHFileTransferError(f"file upload failed: {e}") from e
         logger.info("file upload finished")
 
-    async def download_file(self, remote_path: str, local_path: str) -> None:
-        """异步从远程服务器下载文件到本地。"""
-        sftp = await self._get_sftp()
+    async def download_file(
+        self,
+        remote_path: str,
+        local_path: str,
+        timeout: Optional[float] = None,
+    ) -> None:
+        """异步从远程服务器下载文件。
+
+        Args:
+            remote_path: 远程文件路径
+            local_path: 本地目标路径
+            timeout: inactivity 超时（秒）；None 表示使用
+                ``ConnectionConfig.timeout``。静默超过该时长即中止
+        """
+        sftp = await self._get_sftp(timeout)
         local_file = Path(local_path)
         local_file.parent.mkdir(parents=True, exist_ok=True)
         logger.info(f"downloading file: {remote_path} -> {local_path}")
+
+        async def _operation(progress: Callable[..., None]) -> None:
+            await sftp.get(remote_path, str(local_file), progress_handler=progress)
+
         try:
-            await sftp.get(remote_path, str(local_file))
+            await self._run_sftp_operation(_operation, timeout, "file download")
         except (OSError, asyncssh.Error) as e:
             raise SSHFileTransferError(f"file download failed: {e}") from e
         logger.info("file download finished")
 
-    async def list_remote_directory(self, remote_path: str = ".") -> list[RemoteFileEntry]:
+    async def list_remote_directory(
+        self,
+        remote_path: str = ".",
+        timeout: Optional[float] = None,
+    ) -> list[RemoteFileEntry]:
         """异步列出远程目录内容（结构与同步 SSHClient 一致）。"""
-        sftp = await self._get_sftp()
+        sftp = await self._get_sftp(timeout)
+
+        async def _operation(_progress: Callable[..., None]) -> Sequence[Any]:
+            return await sftp.readdir(remote_path)
+
         try:
-            names = await sftp.readdir(remote_path)
+            names = await self._run_sftp_operation(_operation, timeout, "list remote directory")
         except (OSError, asyncssh.Error) as e:
             raise SSHFileTransferError(f"failed to list remote directory: {e}") from e