remote-cmd-manager 2.5.0__tar.gz → 2.6.0__tar.gz

{remote_cmd_manager-2.5.0/remote_cmd_manager.egg-info → remote_cmd_manager-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remote_cmd_manager
-Version: 2.5.0
+Version: 2.6.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,36 +89,32 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.5.0 Release Highlights
+## v2.6.0 Release Highlights
 
-v2.5.0 is a hardening and scalability release: dependency security floors, Python 3.9
-removal, bounded async scheduling, and explicit output-retention / credential-persistence
-policies. Backward-compatible defaults are preserved where behavior is involved. See the
-[full migration notes](./CHANGELOG.md) before upgrading automated callers.
+v2.6.0 is an architecture and runtime-scalability release: the compatibility facade
+moved out of `core` (eliminating the `core → service` dependency) and a process-wide
+live-connection budget was added for fleet-scale resource control. Public APIs remain
+backward compatible. See the [full migration notes](./CHANGELOG.md).
 
-### Security & Platform
+### Architecture
 
-- Minimum supported Python is now **3.10** (3.9 reached EOL on 2025-10-31).
-- Security floors raised: **Paramiko >= 5.0,<6** and **AsyncSSH >= 2.24.0,<3** (2.23.x and earlier are affected by 2026 AsyncSSH advisories).
+- `HostManager` now lives in `remote_cmd.api.host_manager`; `remote_cmd.core.host_manager` remains a re-export shim, so existing imports keep working.
+- Pool policy helpers moved to `remote_cmd.core.pool_policy` (shim kept at the old path); `core` no longer imports `service`.
+- The async kernel's worker queue now converts unexpected per-host errors into failure results, so a single internal error can no longer stall an entire batch.
 
-### Scalability
+### Global Connection Budget
 
-- `AsyncBatchExecutor` now uses a **bounded worker queue**: only `min(max_concurrency, host count)` worker tasks are created instead of one task per host, so scheduling memory no longer grows with fleet size.
-- New `OutputPolicy` (exported from `remote_cmd`) gives an explicit, mutually exclusive alternative to `max_output_bytes`; `None` still means full retention in v2.5, and a bounded default is planned for v3.0.
-
-### Credential Safety
-
-- `JsonHostRepository` / `SqliteHostRepository` accept `allow_plaintext_credentials` (default `None`): plaintext persistence now emits `PlaintextCredentialWarning`; pass `True` to opt in silently or `False` to reject it with `CredentialError`. v3.0 plans to reject by default.
-- JSON repository concurrency semantics are now explicit: single-process/single-writer; use SQLite for multi-process writers.
-- The `dev` extra now includes `asyncssh`, so `pip install -e ".[dev]"` runs the full test suite out of the box.
+- New `ConnectionBudget` (exported from `remote_cmd`): caps **live** SSH connections process-wide across pools and executors — idle pooled connections count, and slots release on close/cleanup/`close_all`.
+- One instance can be shared by both kernels via `connection_budget=` on `BatchExecutor`, `AsyncBatchExecutor`, `SyncConnectionPool`, and `AsyncConnectionPool`.
+- Optional `acquire_timeout` raises the transient `BudgetTimeoutError`; the default (`None`) keeps unlimited behavior.
 
 ### Compatibility
 
-- `max_output_bytes=None` still retains full output, and the public `BatchResult` / `BatchHostResult` schemas are unchanged; the legacy `max_output_bytes` parameter continues to work alongside `OutputPolicy`.
+- All existing imports and constructor signatures keep working; new parameters are optional and default to previous behavior.
 
 ## Table of Contents
 
-- [v2.5.0 Release Highlights](#v250-release-highlights)
+- [v2.6.0 Release Highlights](#v260-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -268,6 +264,7 @@ with SSHClient(config) as client:
 | **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
 | **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 |
+| **Global Connection Budget** | Optional `ConnectionBudget` caps live SSH connections process-wide across pools and executors |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
 | **Connection Test** | Test all host SSH connections and report status |
 | **Secure Logging** | Structured logging that filters sensitive data (`SensitiveDataFilter`) |

{remote_cmd_manager-2.5.0 → remote_cmd_manager-2.6.0}/README.md

@@ -36,36 +36,32 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.5.0 Release Highlights
+## v2.6.0 Release Highlights
 
-v2.5.0 is a hardening and scalability release: dependency security floors, Python 3.9
-removal, bounded async scheduling, and explicit output-retention / credential-persistence
-policies. Backward-compatible defaults are preserved where behavior is involved. See the
-[full migration notes](./CHANGELOG.md) before upgrading automated callers.
+v2.6.0 is an architecture and runtime-scalability release: the compatibility facade
+moved out of `core` (eliminating the `core → service` dependency) and a process-wide
+live-connection budget was added for fleet-scale resource control. Public APIs remain
+backward compatible. See the [full migration notes](./CHANGELOG.md).
 
-### Security & Platform
+### Architecture
 
-- Minimum supported Python is now **3.10** (3.9 reached EOL on 2025-10-31).
-- Security floors raised: **Paramiko >= 5.0,<6** and **AsyncSSH >= 2.24.0,<3** (2.23.x and earlier are affected by 2026 AsyncSSH advisories).
+- `HostManager` now lives in `remote_cmd.api.host_manager`; `remote_cmd.core.host_manager` remains a re-export shim, so existing imports keep working.
+- Pool policy helpers moved to `remote_cmd.core.pool_policy` (shim kept at the old path); `core` no longer imports `service`.
+- The async kernel's worker queue now converts unexpected per-host errors into failure results, so a single internal error can no longer stall an entire batch.
 
-### Scalability
+### Global Connection Budget
 
-- `AsyncBatchExecutor` now uses a **bounded worker queue**: only `min(max_concurrency, host count)` worker tasks are created instead of one task per host, so scheduling memory no longer grows with fleet size.
-- New `OutputPolicy` (exported from `remote_cmd`) gives an explicit, mutually exclusive alternative to `max_output_bytes`; `None` still means full retention in v2.5, and a bounded default is planned for v3.0.
-
-### Credential Safety
-
-- `JsonHostRepository` / `SqliteHostRepository` accept `allow_plaintext_credentials` (default `None`): plaintext persistence now emits `PlaintextCredentialWarning`; pass `True` to opt in silently or `False` to reject it with `CredentialError`. v3.0 plans to reject by default.
-- JSON repository concurrency semantics are now explicit: single-process/single-writer; use SQLite for multi-process writers.
-- The `dev` extra now includes `asyncssh`, so `pip install -e ".[dev]"` runs the full test suite out of the box.
+- New `ConnectionBudget` (exported from `remote_cmd`): caps **live** SSH connections process-wide across pools and executors — idle pooled connections count, and slots release on close/cleanup/`close_all`.
+- One instance can be shared by both kernels via `connection_budget=` on `BatchExecutor`, `AsyncBatchExecutor`, `SyncConnectionPool`, and `AsyncConnectionPool`.
+- Optional `acquire_timeout` raises the transient `BudgetTimeoutError`; the default (`None`) keeps unlimited behavior.
 
 ### Compatibility
 
-- `max_output_bytes=None` still retains full output, and the public `BatchResult` / `BatchHostResult` schemas are unchanged; the legacy `max_output_bytes` parameter continues to work alongside `OutputPolicy`.
+- All existing imports and constructor signatures keep working; new parameters are optional and default to previous behavior.
 
 ## Table of Contents
 
-- [v2.5.0 Release Highlights](#v250-release-highlights)
+- [v2.6.0 Release Highlights](#v260-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -215,6 +211,7 @@ with SSHClient(config) as client:
 | **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
 | **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 |
+| **Global Connection Budget** | Optional `ConnectionBudget` caps live SSH connections process-wide across pools and executors |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
 | **Connection Test** | Test all host SSH connections and report status |
 | **Secure Logging** | Structured logging that filters sensitive data (`SensitiveDataFilter`) |

{remote_cmd_manager-2.5.0 → remote_cmd_manager-2.6.0}/remote_cmd/__init__.py

@@ -48,7 +48,7 @@ Remote CMD - SSH 远程服务器管理工具
     - 文档: 参见 docs/ 目录
 
 Author: Vae-Scrooge
-Version: 2.5.0（单一真相源见 remote_cmd._version）
+Version: 2.6.0（单一真相源见 remote_cmd._version）
 License: MIT
 """
 
@@ -74,8 +74,9 @@ try:
 except ImportError:  # pragma: no cover - 依赖 asyncssh，未安装时不导出异步符号
     _HAS_ASYNC = False
 
+from remote_cmd.api.host_manager import HostManager
+from remote_cmd.core.budget import ConnectionBudget
 from remote_cmd.core.host import Host
-from remote_cmd.core.host_manager import HostManager
 from remote_cmd.core.ssh_client import SSHClient
 from remote_cmd.core.sync_connection_pool import SyncConnectionPool
 
@@ -105,7 +106,7 @@ from remote_cmd.service.batch_executor import (
 from remote_cmd.service.credential_provider import KeyringCredentialProvider
 from remote_cmd.service.task_runner import Task, TaskRunner, TaskStatus
 from remote_cmd.utils.crypto import CredentialEncryption
-from remote_cmd.utils.exceptions import PlaintextCredentialWarning
+from remote_cmd.utils.exceptions import BudgetTimeoutError, PlaintextCredentialWarning
 from remote_cmd.utils.logging_utils import (
     SensitiveDataFilter,
     get_logger,
@@ -142,6 +143,8 @@ if _HAS_ASYNC:
         "BatchHostResult",
         "OutputPolicy",
         "PlaintextCredentialWarning",
+        "ConnectionBudget",
+        "BudgetTimeoutError",
         "SyncConnectionPool",
         "TaskRunner",
         "Task",
@@ -177,6 +180,8 @@ else:
         "BatchHostResult",
         "OutputPolicy",
         "PlaintextCredentialWarning",
+        "ConnectionBudget",
+        "BudgetTimeoutError",
         "SyncConnectionPool",
         "TaskRunner",
         "Task",

{remote_cmd_manager-2.5.0 → remote_cmd_manager-2.6.0}/remote_cmd/_version.py

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

remote_cmd_manager-2.6.0/remote_cmd/api/__init__.py

@@ -0,0 +1,22 @@
+"""
+API facade 包（向后兼容层）
+
+存放从 ``core`` 迁出的公共兼容 facade，使核心层（``core``）保持对
+``service`` 的零依赖。当前包含:
+
+    - :class:`remote_cmd.api.host_manager.HostManager`：v1.x 的 HostManager
+      API，内部委托给 HostService + JsonHostRepository。
+
+旧导入路径 ``remote_cmd.core.host_manager`` 仍然可用（re-export shim），
+但新代码应使用 ``remote_cmd.api.host_manager`` 或直接使用 HostService。
+
+依赖方向（v2.6 契约）::
+
+    cli / api → service → core → utils
+    repository ← service / cli
+    core 绝不 import service / cli / api 的实现
+"""
+
+from remote_cmd.api.host_manager import HostManager
+
+__all__ = ["HostManager"]

{remote_cmd_manager-2.5.0/remote_cmd/core → remote_cmd_manager-2.6.0/remote_cmd/api}/host_manager.py

@@ -1,12 +1,18 @@
 """
-主机管理模块（向后兼容层）
+主机管理模块（向后兼容 facade，canonical 位置）
 
-保持原有 API 兼容，内部委托给新的 Repository + Service 层。
+保持原有 HostManager API 兼容，内部委托给新的 Repository + Service 层。
 
 新的代码应直接使用:
     - remote_cmd.core.host.Host (代替 Host)
     - remote_cmd.service.host_service.HostService (代替 HostManager)
     - remote_cmd.repository.json_host_repository.JsonHostRepository
+    - remote_cmd.api.host_manager.HostManager（本模块；仅在需要旧 API 时）
+
+v2.6 架构说明：
+    本模块自 ``remote_cmd.core.host_manager`` 迁至 ``remote_cmd.api``，
+    使 ``core`` 层不再依赖 ``service`` 层。旧导入路径由
+    ``remote_cmd.core.host_manager`` 的 re-export shim 保持可用。
 """
 
 import logging

{remote_cmd_manager-2.5.0 → remote_cmd_manager-2.6.0}/remote_cmd/core/async_connection_pool.py

@@ -19,13 +19,14 @@ import uuid
 from typing import Any, Optional
 
 from remote_cmd.core.async_ssh_client import AsyncSSHClient
-from remote_cmd.core.ssh_client import ConnectionConfig
-from remote_cmd.service._pool_policy import (
+from remote_cmd.core.budget import ConnectionBudget
+from remote_cmd.core.pool_policy import (
     ConnectionMeta,
     idle_expired,
     lifetime_expired,
     should_close,
 )
+from remote_cmd.core.ssh_client import ConnectionConfig
 from remote_cmd.utils.exceptions import PoolClosedError
 
 logger = logging.getLogger(__name__)
@@ -40,6 +41,9 @@ class AsyncConnectionPool:
         max_lifetime: 连接最大生命周期（秒），超过自动关闭
         idle_timeout: 空闲超时（秒），超过自动关闭
         health_check_interval: 后台清理任务周期（秒）
+        connection_budget: 可选的全局连接预算（v2.6）。提供时本池创建的
+            每条存活连接都占用一个预算槽位（含空闲连接），连接关闭/清理/
+            close_all 时释放；跨多个池共享同一预算实例可获得全局连接上限
     """
 
     def __init__(
@@ -50,6 +54,7 @@ class AsyncConnectionPool:
         idle_timeout: int = 300,
         health_check_interval: int = 60,
         client_factory: Optional[Any] = None,
+        connection_budget: Optional[ConnectionBudget] = None,
     ) -> None:
         """
         Args:
@@ -60,6 +65,7 @@ class AsyncConnectionPool:
             health_check_interval: 后台清理任务周期（秒）
             client_factory: 客户端工厂，默认为 AsyncSSHClient；测试可注入
                 mock（与 SyncConnectionPool 对齐）
+            connection_budget: 可选的全局连接预算（ConnectionBudget）
         """
         self.config = config
         self._max = max_connections
@@ -68,6 +74,7 @@ class AsyncConnectionPool:
         self._health_check_interval = health_check_interval
         # 客户端工厂：默认为 AsyncSSHClient；测试可注入 mock
         self._client_factory = client_factory or AsyncSSHClient
+        self._connection_budget = connection_budget
 
         # 容器
         self._connections: list[AsyncSSHClient] = []
@@ -190,10 +197,16 @@ class AsyncConnectionPool:
     # ------------------------------------------------------------------
     async def _create_connection(self) -> AsyncSSHClient:
         client = self._client_factory(self.config)
+        if self._connection_budget is not None:
+            await self._connection_budget.acquire_async()
         try:
             await client.connect()
         except Exception:  # noqa: BLE001
-            # 信号量由 acquire() 的 except 统一释放，此处不再释放
+            # 信号量由 acquire() 的 except 统一释放，此处不再释放。
+            # 连接预算仅在成功建连后由 _close_connection 释放；
+            # 建连失败立即归还预算，避免预算泄漏
+            if self._connection_budget is not None:
+                await self._connection_budget.release_async()
             self._total_failed += 1
             raise
         self._connections.append(client)
@@ -237,8 +250,14 @@ class AsyncConnectionPool:
         with contextlib.suppress(Exception):
             await conn.disconnect()
         self._meta.pop(id(conn), None)
-        if conn in self._connections:
+        tracked = conn in self._connections
+        if tracked:
             self._connections.remove(conn)
+        # exactly-once：仅对仍被池追踪的连接释放预算。
+        # close_all 与 release 可能对同一连接重复调用 _close_connection，
+        # 用 tracked 守卫避免预算被超额释放（BoundedSemaphore 会抛 ValueError）
+        if tracked and self._connection_budget is not None:
+            await self._connection_budget.release_async()
 
     # ------------------------------------------------------------------
     # 后台监控

remote_cmd_manager-2.6.0/remote_cmd/core/budget.py

@@ -0,0 +1,211 @@
+"""
+全局连接预算（v2.6 P2.5；同步 / 异步内核共用）
+
+用于在**多个连接池 / 多个执行器**之间封顶进程内同时存活的 SSH 连接数，
+避免大规模 fleet 场景下 per-pool 上限叠加导致的 fd/socket 耗尽：
+
+    池 A(max=10) + 池 B(max=10) + …   无预算时可无限叠加
+    预算(max=50)                       全局硬上限 50 条存活连接
+
+预算语义（评审定稿：存活连接预算）：
+- 预算单位 = **存活连接**（含池中空闲连接）。
+- 获取时机：连接创建（``connect``）前；释放时机：连接断开 / 关闭 /
+  被清理 / 池 ``close_all``。
+- 池归还空闲连接**不**释放预算（连接仍存活）；``acquire`` 复用空闲连接
+  **不**重复获取预算。
+
+双接口：
+- 同步：:meth:`acquire` / :meth:`release` / :meth:`acquire_context`
+- 异步：:meth:`acquire_async` / :meth:`release_async` /
+  :meth:`acquire_context_async`
+
+同一实例可被同步与异步执行器共享（底层是单个
+``threading.BoundedSemaphore``；异步侧以非阻塞轮询等待，轮询间隔
+10ms 起步、指数退避至 50ms——相对于 SSH 建连耗时（数十到数百 ms）
+开销可忽略）。
+
+超时：``acquire_timeout=None``（默认）无限等待；配置正整数/浮点秒数时
+超时抛出 :class:`~remote_cmd.utils.exceptions.BudgetTimeoutError`。
+
+用法:
+    >>> from remote_cmd.core.budget import ConnectionBudget
+    >>> budget = ConnectionBudget(max_connections=50)
+    >>> with budget.acquire_context():
+    ...     pass  # 持有预算期间创建/保有连接
+    >>> budget.get_metrics()["in_use"]
+    0
+    >>>
+    >>> async def use():
+    ...     async with budget.acquire_context_async():
+    ...         pass
+"""
+
+import asyncio
+import contextlib
+import threading
+import time
+from typing import Any, AsyncIterator, Iterator, Optional
+
+from remote_cmd.utils.exceptions import BudgetTimeoutError, ValidationError
+
+# 异步轮询等待参数（秒）：起步 10ms，指数退避至 50ms 上限
+_DEFAULT_POLL_INTERVAL = 0.01
+_MAX_POLL_INTERVAL = 0.05
+
+
+class ConnectionBudget:
+    """全局连接预算（同步 / 异步共用）。
+
+    Args:
+        max_connections: 全局最大存活连接数（正整数；bool 被拒绝）
+        acquire_timeout: 获取预算的等待上限（秒）。``None``（默认）
+            表示无限等待；正数表示超时后抛 ``BudgetTimeoutError``
+
+    Raises:
+        ValidationError: 参数非法（构造时校验）
+    """
+
+    def __init__(
+        self,
+        max_connections: int,
+        acquire_timeout: Optional[float] = None,
+    ) -> None:
+        if (
+            isinstance(max_connections, bool)
+            or not isinstance(max_connections, int)
+            or max_connections <= 0
+        ):
+            raise ValidationError(
+                f"max_connections must be a positive integer, got: {max_connections!r}"
+            )
+        if acquire_timeout is not None and (
+            isinstance(acquire_timeout, bool)
+            or not isinstance(acquire_timeout, (int, float))
+            or acquire_timeout <= 0
+        ):
+            raise ValidationError(
+                f"acquire_timeout must be None or a positive number, got: {acquire_timeout!r}"
+            )
+
+        self._max = max_connections
+        self._acquire_timeout = acquire_timeout
+        # 单一底层信号量：同步/异步共享同一个全局上限
+        self._semaphore = threading.BoundedSemaphore(max_connections)
+        self._lock = threading.Lock()
+
+        # 指标
+        self._in_use = 0
+        self._total_acquired = 0
+        self._total_released = 0
+        self._total_timeouts = 0
+
+    # ------------------------------------------------------------------
+    # 属性 / 指标
+    # ------------------------------------------------------------------
+    @property
+    def max_connections(self) -> int:
+        """全局最大存活连接数。"""
+        return self._max
+
+    @property
+    def acquire_timeout(self) -> Optional[float]:
+        """获取预算的等待上限（秒）；``None`` 表示无限等待。"""
+        return self._acquire_timeout
+
+    def get_metrics(self) -> dict[str, Any]:
+        """预算指标快照。"""
+        with self._lock:
+            return {
+                "max_connections": self._max,
+                "in_use": self._in_use,
+                "available": self._max - self._in_use,
+                "total_acquired": self._total_acquired,
+                "total_released": self._total_released,
+                "total_timeouts": self._total_timeouts,
+            }
+
+    # ------------------------------------------------------------------
+    # 同步接口
+    # ------------------------------------------------------------------
+    def acquire(self) -> None:
+        """获取一个连接预算槽位（阻塞，受 ``acquire_timeout`` 约束）。
+
+        Raises:
+            BudgetTimeoutError: 等待超过 ``acquire_timeout``
+        """
+        acquired = self._semaphore.acquire(timeout=self._acquire_timeout)
+        if not acquired:
+            with self._lock:
+                self._total_timeouts += 1
+            raise BudgetTimeoutError(
+                "connection budget exhausted: "
+                f"waited {self._acquire_timeout}s for a slot "
+                f"(max_connections={self._max})"
+            )
+        with self._lock:
+            self._in_use += 1
+            self._total_acquired += 1
+
+    def release(self) -> None:
+        """释放一个连接预算槽位。
+
+        Raises:
+            ValueError: 释放次数超过获取次数（BoundedSemaphore 保护）
+        """
+        # 先释放信号量：超额释放时 BoundedSemaphore 抛出 ValueError，
+        # 指标不会进入不一致状态
+        self._semaphore.release()
+        with self._lock:
+            self._in_use -= 1
+            self._total_released += 1
+
+    @contextlib.contextmanager
+    def acquire_context(self) -> Iterator[None]:
+        """同步上下文管理器：进入获取预算，退出释放。"""
+        self.acquire()
+        try:
+            yield
+        finally:
+            self.release()
+
+    # ------------------------------------------------------------------
+    # 异步接口
+    # ------------------------------------------------------------------
+    async def acquire_async(self) -> None:
+        """获取一个连接预算槽位（asyncio 友好，受 ``acquire_timeout`` 约束）。
+
+        以非阻塞尝试 + 指数退避轮询等待，不阻塞事件循环。
+        """
+        timeout = self._acquire_timeout
+        deadline = None if timeout is None else time.monotonic() + timeout
+        interval = _DEFAULT_POLL_INTERVAL
+        while not self._semaphore.acquire(blocking=False):
+            if deadline is not None and time.monotonic() >= deadline:
+                with self._lock:
+                    self._total_timeouts += 1
+                raise BudgetTimeoutError(
+                    "connection budget exhausted: "
+                    f"waited {timeout}s for a slot "
+                    f"(max_connections={self._max})"
+                )
+            await asyncio.sleep(interval)
+            interval = min(interval * 2, _MAX_POLL_INTERVAL)
+        with self._lock:
+            self._in_use += 1
+            self._total_acquired += 1
+
+    async def release_async(self) -> None:
+        """释放一个连接预算槽位（异步接口；与 :meth:`release` 等价）。"""
+        self.release()
+
+    @contextlib.asynccontextmanager
+    async def acquire_context_async(self) -> AsyncIterator[None]:
+        """异步上下文管理器：进入获取预算，退出释放。"""
+        await self.acquire_async()
+        try:
+            yield
+        finally:
+            await self.release_async()
+
+
+__all__ = ["ConnectionBudget"]

remote_cmd_manager-2.6.0/remote_cmd/core/host_manager.py

@@ -0,0 +1,16 @@
+"""
+向后兼容 shim：HostManager 实现已迁移到 ``remote_cmd.api.host_manager``。
+
+v2.6 起 ``HostManager`` 的 canonical 位置是 ``remote_cmd.api.host_manager``，
+使 ``core`` 层不再依赖 ``service``。本模块仅为保留既有导入路径而存在：
+
+    >>> from remote_cmd.core.host_manager import HostManager  # 仍可用（shim）
+    >>> from remote_cmd.api.host_manager import HostManager   # canonical
+
+``Host`` 也原样 re-export，兼容历史用法
+``from remote_cmd.core.host_manager import Host, HostManager``。
+"""
+
+from remote_cmd.api.host_manager import Host, HostManager
+
+__all__ = ["Host", "HostManager"]

remote_cmd_manager-2.5.0/remote_cmd/service/_pool_policy.py → remote_cmd_manager-2.6.0/remote_cmd/core/pool_policy.py

@@ -4,6 +4,10 @@
 从 SyncConnectionPool 与 AsyncConnectionPool 中提取的纯时间判断逻辑：
 不涉及任何 I/O 与并发原语，便于两个池共享并单独测试。
 
+v2.6（P2.1）起 canonical 位置为 ``remote_cmd.core.pool_policy``：该模块
+只被 core 连接池消费，放在 core 可保持 ``core`` 对 ``service`` 的零依赖。
+旧导入路径 ``remote_cmd.service._pool_policy`` 仍可用（re-export shim）。
+
 注意：探活（liveness probe，如 ``conn.execute("true")``）是真实 I/O，
 不属于本模块职责，保留在各池的 ``_check_connection`` 内。
 
@@ -13,7 +17,7 @@
   的弱类型写法。
 
 用法:
-    >>> from remote_cmd.service._pool_policy import (
+    >>> from remote_cmd.core.pool_policy import (
     ...     ConnectionMeta, lifetime_expired, idle_expired, should_close,
     ... )
     >>> meta = ConnectionMeta(created_at=1000.0, last_used=1000.0, conn_id="x")

{remote_cmd_manager-2.5.0 → remote_cmd_manager-2.6.0}/remote_cmd/core/sync_connection_pool.py

@@ -19,13 +19,14 @@ import time
 import uuid
 from typing import Any, Optional
 
-from remote_cmd.core.ssh_client import ConnectionConfig, SSHClient
-from remote_cmd.service._pool_policy import (
+from remote_cmd.core.budget import ConnectionBudget
+from remote_cmd.core.pool_policy import (
     ConnectionMeta,
     idle_expired,
     lifetime_expired,
     should_close,
 )
+from remote_cmd.core.ssh_client import ConnectionConfig, SSHClient
 from remote_cmd.utils.exceptions import PoolClosedError
 
 logger = logging.getLogger(__name__)
@@ -40,6 +41,9 @@ class SyncConnectionPool:
         max_lifetime: 连接最大生命周期（秒），超过自动关闭
         idle_timeout: 空闲超时（秒），超过自动关闭
         health_check_interval: 后台清理线程周期（秒）
+        connection_budget: 可选的全局连接预算（v2.6）。提供时本池创建的
+            每条存活连接都占用一个预算槽位（含空闲连接），连接关闭/清理/
+            close_all 时释放；跨多个池共享同一预算实例可获得全局连接上限
     """
 
     def __init__(
@@ -50,6 +54,7 @@ class SyncConnectionPool:
         idle_timeout: int = 300,
         health_check_interval: int = 60,
         client_factory: Optional[Any] = None,
+        connection_budget: Optional[ConnectionBudget] = None,
     ) -> None:
         self.config = config
         self._max = max_connections
@@ -58,6 +63,7 @@ class SyncConnectionPool:
         self._health_check_interval = health_check_interval
         # 客户端工厂：默认为 SSHClient；测试可注入 mock
         self._client_factory = client_factory or SSHClient
+        self._connection_budget = connection_budget
 
         # 容器
         self._connections: list[SSHClient] = []
@@ -181,10 +187,16 @@ class SyncConnectionPool:
     # ------------------------------------------------------------------
     def _create_connection(self) -> SSHClient:
         client = self._client_factory(self.config)
+        if self._connection_budget is not None:
+            self._connection_budget.acquire()
         try:
             client.connect()
         except Exception:  # noqa: BLE001
-            # 信号量由 acquire() 的 except 统一释放，此处不再释放
+            # 信号量由 acquire() 的 except 统一释放，此处不再释放。
+            # 连接预算仅在成功建连后由 _close_connection 释放；
+            # 建连失败立即归还预算，避免预算泄漏
+            if self._connection_budget is not None:
+                self._connection_budget.release()
             self._total_failed += 1
             raise
         with self._lock:
@@ -229,8 +241,14 @@ class SyncConnectionPool:
             conn.disconnect()
         self._meta.pop(id(conn), None)
         with self._lock:
-            if conn in self._connections:
+            tracked = conn in self._connections
+            if tracked:
                 self._connections.remove(conn)
+        # exactly-once：仅对仍被池追踪的连接释放预算。
+        # close_all 与 release 可能对同一连接重复调用 _close_connection，
+        # 用 tracked 守卫避免预算被超额释放（BoundedSemaphore 会抛 ValueError）
+        if tracked and self._connection_budget is not None:
+            self._connection_budget.release()
 
     # ------------------------------------------------------------------
     # 后台监控

remote_cmd_manager-2.6.0/remote_cmd/service/_pool_policy.py

@@ -0,0 +1,16 @@
+"""
+向后兼容 shim：连接池策略已迁移到 ``remote_cmd.core.pool_policy``。
+
+v2.6（P2.1）起该模块只被 core 连接池消费，canonical 位置为
+``remote_cmd.core.pool_policy``，以保持 ``core`` 对 ``service`` 的零依赖。
+本模块仅为保留既有导入路径（含测试）而存在。
+"""
+
+from remote_cmd.core.pool_policy import (  # noqa: F401
+    ConnectionMeta,
+    idle_expired,
+    lifetime_expired,
+    should_close,
+)
+
+__all__ = ["ConnectionMeta", "idle_expired", "lifetime_expired", "should_close"]