ssh-licco 2.7.1__tar.gz → 2.7.3__tar.gz

{ssh_licco-2.7.1/ssh_licco.egg-info → ssh_licco-2.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ssh-licco
-Version: 2.7.1
+Version: 2.7.3
 Summary: SSH Model Context Protocol Server - Enable SSH functionality for AI models
 Author-email: SSH LICCO Team <contact@ssh-licco.dev>
 License: MIT
@@ -47,6 +47,7 @@ Dynamic: license-file
 ## 📚 文档导航
 
 ### 快速开始
+- **[🐣 新手指南](docs/BEGINNER_GUIDE.md)** - 零基础上手（推荐从这开始）
 - **[⬇️ 安装指南](#-快速安装)** - 2 种安装方式
 - **[🚀 快速开始](#-快速开始)** - 5 分钟上手
 - **[📋 配置模板](#-完整配置示例)** - 开箱即用的配置
@@ -63,7 +64,7 @@ Dynamic: license-file
 
 ### 开发资源
 - **[🎓 Skills 文档](docs/skills/)** - 开发、运维、安装指南
-- **[📦 发布指南](docs/skills/RELEASE_SKILL.md)** - 版本发布流程
+- **[📦 发布指南](#-发布指南一体化命令)** - 一体化版本发布命令
 - **[🐛 GitHub Issues](https://github.com/Echoqili/ssh-licco/issues)** - 问题反馈
 
 ---
@@ -622,7 +623,7 @@ ssh-licco 的核心依赖是：
 
 | 指标 | 状态 |
 |------|------|
-| **测试用例** | 424 passed, 0 skipped |
+| **测试用例** | 244 passed, 0 skipped |
 | **覆盖率** | 16 个源模块全覆盖 |
 | **测试框架** | pytest + pytest-asyncio |
 
@@ -663,4 +664,56 @@ pytest --cov=ssh_mcp --cov-report=term-missing
 
 ---
 
+## 📦 发布指南（一体化命令）
+
+项目提供 `sync_version.py` 作为**唯一**版本发布入口，一条命令完成所有版本源同步 + 文档更新 + 一致性自检 + git commit/tag/push，杜绝漏改 `VERSION` / `package.json` / `SKILL.md` 等文件。
+
+### 一键发布
+
+```bash
+# 升 patch（z）：2.7.1 → 2.7.2
+python sync_version.py 2.7.2
+
+# 升 minor（y）：2.7.1 → 2.8.0
+python sync_version.py 2.8.0
+
+# 升 major（x）：2.7.1 → 3.0.0
+python sync_version.py 3.0.0
+```
+
+默认行为：改版本源 → 同步文档版本 → 一致性自检 → `commit` → `push` → 打 `tag` → `push tag`。
+
+### 常用选项
+
+```bash
+# 预览会发生的变更，不写文件、不 commit
+python sync_version.py 2.7.2 --dry-run
+
+# 只改文件，不提交、不打 tag
+python sync_version.py 2.7.2 --no-commit --no-tag
+
+# 只做一致性自检（CI 中使用）
+python sync_version.py --check
+```
+
+### 覆盖的版本源
+
+| 文件 | 字段 | 说明 |
+|------|------|------|
+| `ssh_mcp/__init__.py` | `__version__` | **唯一真源**，其他文件都与其对齐 |
+| `pyproject.toml` | `version` | Python 包构建版本 |
+| `VERSION` | 纯文本 | `.github/workflows/pypi.yml` 实际读取的版本 |
+| `package.json` | `version` | npm 包版本 |
+| `package-lock.json` | `version` × 2 | npm lock 根版本 + `packages[""].version` |
+| `.trae/skills/*/SKILL.md` | `Current Version` | 文档中的版本标注 |
+| `docs/skills/*/SKILL.md` | `Current Version` | 文档中的版本标注 |
+
+### CI 预检
+
+`.github/workflows/pypi.yml` 在构建前会执行 `python sync_version.py --check`，任何版本源不一致都会**直接中断发布流程**，防止打错版本号。
+
+> 完整发布流程（含 PyPI 上传、MCP Registry 发布）见 [docs/skills/RELEASE_SKILL.md](docs/skills/RELEASE_SKILL.md)。
+
+---
+
 ## 📊 版本历史

{ssh_licco-2.7.1 → ssh_licco-2.7.3}/README.md

@@ -14,6 +14,7 @@
 ## 📚 文档导航
 
 ### 快速开始
+- **[🐣 新手指南](docs/BEGINNER_GUIDE.md)** - 零基础上手（推荐从这开始）
 - **[⬇️ 安装指南](#-快速安装)** - 2 种安装方式
 - **[🚀 快速开始](#-快速开始)** - 5 分钟上手
 - **[📋 配置模板](#-完整配置示例)** - 开箱即用的配置
@@ -30,7 +31,7 @@
 
 ### 开发资源
 - **[🎓 Skills 文档](docs/skills/)** - 开发、运维、安装指南
-- **[📦 发布指南](docs/skills/RELEASE_SKILL.md)** - 版本发布流程
+- **[📦 发布指南](#-发布指南一体化命令)** - 一体化版本发布命令
 - **[🐛 GitHub Issues](https://github.com/Echoqili/ssh-licco/issues)** - 问题反馈
 
 ---
@@ -589,7 +590,7 @@ ssh-licco 的核心依赖是：
 
 | 指标 | 状态 |
 |------|------|
-| **测试用例** | 424 passed, 0 skipped |
+| **测试用例** | 244 passed, 0 skipped |
 | **覆盖率** | 16 个源模块全覆盖 |
 | **测试框架** | pytest + pytest-asyncio |
 
@@ -630,4 +631,56 @@ pytest --cov=ssh_mcp --cov-report=term-missing
 
 ---
 
+## 📦 发布指南（一体化命令）
+
+项目提供 `sync_version.py` 作为**唯一**版本发布入口，一条命令完成所有版本源同步 + 文档更新 + 一致性自检 + git commit/tag/push，杜绝漏改 `VERSION` / `package.json` / `SKILL.md` 等文件。
+
+### 一键发布
+
+```bash
+# 升 patch（z）：2.7.1 → 2.7.2
+python sync_version.py 2.7.2
+
+# 升 minor（y）：2.7.1 → 2.8.0
+python sync_version.py 2.8.0
+
+# 升 major（x）：2.7.1 → 3.0.0
+python sync_version.py 3.0.0
+```
+
+默认行为：改版本源 → 同步文档版本 → 一致性自检 → `commit` → `push` → 打 `tag` → `push tag`。
+
+### 常用选项
+
+```bash
+# 预览会发生的变更，不写文件、不 commit
+python sync_version.py 2.7.2 --dry-run
+
+# 只改文件，不提交、不打 tag
+python sync_version.py 2.7.2 --no-commit --no-tag
+
+# 只做一致性自检（CI 中使用）
+python sync_version.py --check
+```
+
+### 覆盖的版本源
+
+| 文件 | 字段 | 说明 |
+|------|------|------|
+| `ssh_mcp/__init__.py` | `__version__` | **唯一真源**，其他文件都与其对齐 |
+| `pyproject.toml` | `version` | Python 包构建版本 |
+| `VERSION` | 纯文本 | `.github/workflows/pypi.yml` 实际读取的版本 |
+| `package.json` | `version` | npm 包版本 |
+| `package-lock.json` | `version` × 2 | npm lock 根版本 + `packages[""].version` |
+| `.trae/skills/*/SKILL.md` | `Current Version` | 文档中的版本标注 |
+| `docs/skills/*/SKILL.md` | `Current Version` | 文档中的版本标注 |
+
+### CI 预检
+
+`.github/workflows/pypi.yml` 在构建前会执行 `python sync_version.py --check`，任何版本源不一致都会**直接中断发布流程**，防止打错版本号。
+
+> 完整发布流程（含 PyPI 上传、MCP Registry 发布）见 [docs/skills/RELEASE_SKILL.md](docs/skills/RELEASE_SKILL.md)。
+
+---
+
 ## 📊 版本历史

{ssh_licco-2.7.1 → ssh_licco-2.7.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ssh-licco"
-version = "2.7.1"
+version = "2.7.3"
 description = "SSH Model Context Protocol Server - Enable SSH functionality for AI models"
 readme = "README.md"
 requires-python = ">=3.10"

{ssh_licco-2.7.1 → ssh_licco-2.7.3/ssh_licco.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ssh-licco
-Version: 2.7.1
+Version: 2.7.3
 Summary: SSH Model Context Protocol Server - Enable SSH functionality for AI models
 Author-email: SSH LICCO Team <contact@ssh-licco.dev>
 License: MIT
@@ -47,6 +47,7 @@ Dynamic: license-file
 ## 📚 文档导航
 
 ### 快速开始
+- **[🐣 新手指南](docs/BEGINNER_GUIDE.md)** - 零基础上手（推荐从这开始）
 - **[⬇️ 安装指南](#-快速安装)** - 2 种安装方式
 - **[🚀 快速开始](#-快速开始)** - 5 分钟上手
 - **[📋 配置模板](#-完整配置示例)** - 开箱即用的配置
@@ -63,7 +64,7 @@ Dynamic: license-file
 
 ### 开发资源
 - **[🎓 Skills 文档](docs/skills/)** - 开发、运维、安装指南
-- **[📦 发布指南](docs/skills/RELEASE_SKILL.md)** - 版本发布流程
+- **[📦 发布指南](#-发布指南一体化命令)** - 一体化版本发布命令
 - **[🐛 GitHub Issues](https://github.com/Echoqili/ssh-licco/issues)** - 问题反馈
 
 ---
@@ -622,7 +623,7 @@ ssh-licco 的核心依赖是：
 
 | 指标 | 状态 |
 |------|------|
-| **测试用例** | 424 passed, 0 skipped |
+| **测试用例** | 244 passed, 0 skipped |
 | **覆盖率** | 16 个源模块全覆盖 |
 | **测试框架** | pytest + pytest-asyncio |
 
@@ -663,4 +664,56 @@ pytest --cov=ssh_mcp --cov-report=term-missing
 
 ---
 
+## 📦 发布指南（一体化命令）
+
+项目提供 `sync_version.py` 作为**唯一**版本发布入口，一条命令完成所有版本源同步 + 文档更新 + 一致性自检 + git commit/tag/push，杜绝漏改 `VERSION` / `package.json` / `SKILL.md` 等文件。
+
+### 一键发布
+
+```bash
+# 升 patch（z）：2.7.1 → 2.7.2
+python sync_version.py 2.7.2
+
+# 升 minor（y）：2.7.1 → 2.8.0
+python sync_version.py 2.8.0
+
+# 升 major（x）：2.7.1 → 3.0.0
+python sync_version.py 3.0.0
+```
+
+默认行为：改版本源 → 同步文档版本 → 一致性自检 → `commit` → `push` → 打 `tag` → `push tag`。
+
+### 常用选项
+
+```bash
+# 预览会发生的变更，不写文件、不 commit
+python sync_version.py 2.7.2 --dry-run
+
+# 只改文件，不提交、不打 tag
+python sync_version.py 2.7.2 --no-commit --no-tag
+
+# 只做一致性自检（CI 中使用）
+python sync_version.py --check
+```
+
+### 覆盖的版本源
+
+| 文件 | 字段 | 说明 |
+|------|------|------|
+| `ssh_mcp/__init__.py` | `__version__` | **唯一真源**，其他文件都与其对齐 |
+| `pyproject.toml` | `version` | Python 包构建版本 |
+| `VERSION` | 纯文本 | `.github/workflows/pypi.yml` 实际读取的版本 |
+| `package.json` | `version` | npm 包版本 |
+| `package-lock.json` | `version` × 2 | npm lock 根版本 + `packages[""].version` |
+| `.trae/skills/*/SKILL.md` | `Current Version` | 文档中的版本标注 |
+| `docs/skills/*/SKILL.md` | `Current Version` | 文档中的版本标注 |
+
+### CI 预检
+
+`.github/workflows/pypi.yml` 在构建前会执行 `python sync_version.py --check`，任何版本源不一致都会**直接中断发布流程**，防止打错版本号。
+
+> 完整发布流程（含 PyPI 上传、MCP Registry 发布）见 [docs/skills/RELEASE_SKILL.md](docs/skills/RELEASE_SKILL.md)。
+
+---
+
 ## 📊 版本历史

{ssh_licco-2.7.1 → ssh_licco-2.7.3}/ssh_licco.egg-info/SOURCES.txt

@@ -11,7 +11,6 @@ ssh_mcp/__init__.py
 ssh_mcp/__main__.py
 ssh_mcp/audit_logger.py
 ssh_mcp/batch_executor.py
-ssh_mcp/cli.py
 ssh_mcp/config_manager.py
 ssh_mcp/connection_config.py
 ssh_mcp/connection_pool.py

{ssh_licco-2.7.1 → ssh_licco-2.7.3}/ssh_mcp/__init__.py

@@ -1,8 +1,8 @@
 # SSH-LICCO 版本信息
 # 所有代码中的版本信息都从这里读取
-# 版本号：2.7.1
+# 版本号：2.7.3
 
-__version__ = "2.7.1"
+__version__ = "2.7.3"
 __author__ = "Li Qi"
 __email__ = "1985694657@qq.com"
 __license__ = "MIT"

{ssh_licco-2.7.1 → ssh_licco-2.7.3}/ssh_mcp/handlers/utils.py

@@ -18,16 +18,30 @@ async def ensure_session(
     """Ensure an active session exists.
 
     Priority:
-    1. session_id if provided
+    1. session_id if provided (validated; stale ids fall through to rebuild)
     2. name/host_name from hosts.json
     3. host directly (with optional port/username/password)
     4. env-config fallback (auto-connect)
 
     Returns session_id on success, None on failure.
     """
+    stale_session_id = None
     session_id = args.get("session_id")
     if session_id:
-        return session_id
+        # 校验 session_id 存活；get_session 内部会对死会话做透明重建（复用同 id）
+        try:
+            session = await ctx.session_manager.get_session(session_id)
+        except Exception:
+            session = None
+        if session:
+            return session_id
+        # session_id 已失效（MCP 进程重启 / 重建失败 / entry 被回收）：
+        # 不直接采用必失败的 id，而是走 name/host/env 回退链透明重建，
+        # 避免 "Session not found" 中断调用方
+        stale_session_id = session_id
+        ctx.logger.warning(
+            f"session_id {session_id} 已失效，尝试通过 name/host/env 配置重建会话"
+        )
 
     # Use named host from hosts.json (name or host_name)
     host_name = args.get("name") or args.get("host_name")
@@ -65,7 +79,8 @@ async def ensure_session(
                 return line.split("Session ID:")[1].strip()
         return None
 
-    return None
+    # 回退链也无法建连：返回原 session_id，让上层报准确的 "Session not found: {id}"
+    return stale_session_id
 
 
 def diagnose_exit_code(exit_code: int, log_tail: str, stderr: str) -> str:

{ssh_licco-2.7.1 → ssh_licco-2.7.3}/ssh_mcp/server.py

@@ -11,7 +11,14 @@ from typing import Any
 
 from mcp.server import Server
 from mcp.server.stdio import stdio_server
-from mcp.types import TextContent, Tool
+from mcp.types import (
+    CallToolRequestParams,
+    CallToolResult,
+    ListToolsResult,
+    PaginatedRequestParams,
+    TextContent,
+    Tool,
+)
 
 from .audit_logger import get_audit_logger
 from .config_manager import ConfigManager, SSHConfig, SSHHost
@@ -141,7 +148,7 @@ class Tunnel:
 
 class SSHMCPServer:
     def __init__(self):
-        self.server = Server("ssh-licco", __version__)
+        self.server = Server("ssh-licco", version=__version__)
         self.session_manager = SessionManager()
         self.key_manager = KeyManager()
         self.config_manager = ConfigManager()
@@ -212,24 +219,45 @@ class SSHMCPServer:
         return True, ""
 
     def _setup_handlers(self):
-        @self.server.list_tools()
-        async def list_tools() -> list[Tool]:
-            return list(schemas.TOOLS.values())
+        self.server.add_request_handler(
+            "tools/list", PaginatedRequestParams, self._handle_list_tools
+        )
+        self.server.add_request_handler(
+            "tools/call", CallToolRequestParams, self._handle_call_tool
+        )
 
-        @self.server.call_tool()
-        async def call_tool(name: str, arguments: Any) -> list[TextContent]:
-            allowed, msg = self._check_rate_limit()
-            if not allowed:
-                return [TextContent(type="text", text=msg)]
+    async def _handle_list_tools(
+        self, ctx: Any, params: PaginatedRequestParams
+    ) -> ListToolsResult:
+        return ListToolsResult(tools=list(schemas.TOOLS.values()))
+
+    async def _handle_call_tool(
+        self, ctx: Any, params: CallToolRequestParams
+    ) -> CallToolResult:
+        allowed, msg = self._check_rate_limit()
+        if not allowed:
+            return CallToolResult(
+                content=[TextContent(type="text", text=msg)], is_error=False
+            )
 
-            handler = HANDLERS.get(name)
-            if handler is None:
-                return [TextContent(type="text", text=f"Unknown tool: {name}")]
+        handler = HANDLERS.get(params.name)
+        if handler is None:
+            return CallToolResult(
+                content=[
+                    TextContent(type="text", text=f"Unknown tool: {params.name}")
+                ],
+                is_error=True,
+            )
 
-            try:
-                return await handler(self._ctx, arguments)
-            except Exception as e:
-                return [TextContent(type="text", text=f"Error: {str(e)}")]
+        try:
+            result = await handler(self._ctx, params.arguments or {})
+            content = result if isinstance(result, list) else [result]
+            return CallToolResult(content=content, is_error=False)
+        except Exception as e:
+            return CallToolResult(
+                content=[TextContent(type="text", text=f"Error: {str(e)}")],
+                is_error=True,
+            )
 
     async def _handle_connect(self, args: dict) -> list[TextContent]:
         """合并 ssh_config + ssh_login + ssh_connect"""

{ssh_licco-2.7.1 → ssh_licco-2.7.3}/ssh_mcp/session_manager.py

@@ -57,8 +57,7 @@ class SSHSession:
         self._connect_lock = asyncio.Lock()
         self._shutdown_event = asyncio.Event()
         self._background_channels: list = []  # 保持 background channel 引用，防止 GC 关闭 channel
-        self._reconnect_count = 0  # 重连次数统计
-        self._max_reconnects = 3  # 最大重连次数
+        self._reconnect_count = 0  # 连续重建失败计数（成功后清零，仅用于日志观察）
         self._logger = get_logger("SSHSession")
 
     @property
@@ -734,10 +733,12 @@ class SessionManager:
             timeout_sessions = []
 
             for session_id, session in self._sessions.items():
-                if session.is_connected:
-                    idle_time = now - session._last_activity
-                    if idle_time > timedelta(seconds=session.config.session_timeout):
-                        timeout_sessions.append(session_id)
+                # idle 超时对存活与失联会话一视同仁：
+                # - 存活会话超时 → 正常回收（原逻辑）
+                # - dead entry 超时 → 兜底回收，防止重建一直失败的 entry 永久滞留
+                idle_time = now - session._last_activity
+                if idle_time > timedelta(seconds=session.config.session_timeout):
+                    timeout_sessions.append(session_id)
 
             for session_id in timeout_sessions:
                 try:
@@ -763,13 +764,16 @@ class SessionManager:
                         return session._get_session_info()
 
             # 🔒 安全检查：会话并发数限制
-            if len(self._sessions) >= self.MAX_SESSIONS:
+            # 只统计存活会话：dead entry 不占用并发额度（重建失败时 entry 会被保留供重试），
+            # 避免 5 个死会话占满 MAX_SESSIONS_PER_HOST 导致新连接全部被拒
+            live_sessions = [s for s in self._sessions.values() if s.is_connected]
+            if len(live_sessions) >= self.MAX_SESSIONS:
                 raise ConnectionException(
                     f"达到最大会话数限制 ({self.MAX_SESSIONS})，请先关闭一些会话"
                 )
 
             # 🔒 安全检查：每个主机会话数限制
-            host_sessions = sum(1 for s in self._sessions.values() if s.config.host == config.host)
+            host_sessions = sum(1 for s in live_sessions if s.config.host == config.host)
             if host_sessions >= self.MAX_SESSIONS_PER_HOST:
                 raise ConnectionException(
                     f"主机 {config.host} 已达到最大会话数限制 ({self.MAX_SESSIONS_PER_HOST})"
@@ -785,7 +789,7 @@ class SessionManager:
         async with self._lock:
             session = self._sessions.get(session_id)
 
-            # 🔄 自动重连机制：如果 session 存在但已断开，尝试重连
+            # 🔄 自动重连机制：如果 session 存在但已断开，尝试透明重建
             if session and not session.is_connected and auto_reconnect:
                 # 非真实 SSHSession 实例（如测试 Mock）不尝试重连，直接清理
                 if not isinstance(session, SSHSession):
@@ -799,44 +803,35 @@ class SessionManager:
                         del self._sessions[session_id]
                     return None
 
-                # 检查重连次数限制
-                if session._reconnect_count >= session._max_reconnects:
-                    self._logger.error(
-                        f"Session {session_id} 重连次数已达上限 ({session._max_reconnects})，不再重连"
-                    )
-                    await session.disconnect()
-                    if session_id in self._sessions:
-                        del self._sessions[session_id]
-                    return None
-
                 self._logger.warning(
-                    f"Session {session_id} 已断开，尝试自动重连（重连次数：{session._reconnect_count}/{session._max_reconnects}）"
+                    f"Session {session_id} 已断开，尝试透明重建（连续失败次数：{session._reconnect_count}）"
                 )
                 try:
-                    # 保存配置信息用于重连
+                    # 保存配置信息用于重建
                     config = session.config
                     session._reconnect_count += 1
-
-                    # 清理旧 session
                     await session.disconnect()
-                    if session_id in self._sessions:
-                        del self._sessions[session_id]
 
-                    # 创建新 session（使用相同的 session_id）
+                    # 🔄 透明重建：用相同配置创建新 session 并复用原 session_id，
+                    # 调用方持有的 session_id 始终有效，无需感知底层重建。
+                    # 旧逻辑的"重连次数上限/重建失败即删除 entry"会导致 session_id
+                    # 永久失效（表现即 "Session not found"），已移除；
+                    # 重建失败时保留 dead entry（含连接配置），下次调用继续重试，
+                    # 长期失联的 dead entry 由 _cleanup_timeout_sessions 按 idle 超时兜底回收
                     new_session = SSHSession(config)
                     new_session.session_id = session_id  # 复用原来的 session_id
-                    new_session._reconnect_count = session._reconnect_count  # 保持重连次数
                     await new_session.connect()
+                    new_session._reconnect_count = 0  # 重建成功，清零连续失败计数
                     self._sessions[session_id] = new_session
-                    self._logger.info(f"Session {session_id} 自动重连成功")
+                    self._logger.info(f"Session {session_id} 透明重建成功")
                     return new_session
                 except Exception as e:
-                    self._logger.error(f"Session {session_id} 自动重连失败: {e}")
-                    if session_id in self._sessions:
-                        del self._sessions[session_id]
+                    self._logger.error(f"Session {session_id} 透明重建失败: {e}")
+                    # 不删除 entry：保留 dead session 及其配置，供后续调用重试
+                    self._sessions[session_id] = session
                     return None
 
-            # 🧹 清理完全失效的 session
+            # 🧹 清理完全失效的 session（仅 auto_reconnect=False 的显式清理路径）
             if session and not session.is_connected:
                 self._logger.warning(
                     f"Session {session_id} 已断开，清理（host={session.config.host}）"
@@ -846,6 +841,11 @@ class SessionManager:
                     del self._sessions[session_id]
                 return None
 
+            # 存活会话：会话被正常使用即视为健康，重置连续失败计数，
+            # 避免历史上的瞬时网络抖动累计导致会话被判死
+            if session and session.is_connected:
+                session._reconnect_count = 0
+
             return session
 
     async def close_session(self, session_id: str) -> None:

{ssh_licco-2.7.1 → ssh_licco-2.7.3}/tests/test_server.py

@@ -11,7 +11,7 @@ from ssh_mcp.handlers.execute import handle_execute
 from ssh_mcp.handlers.file_transfer import handle_file_transfer
 from ssh_mcp.handlers.host import handle_host
 from ssh_mcp.handlers.key import handle_generate_key
-from ssh_mcp.handlers.utils import should_run_background
+from ssh_mcp.handlers.utils import ensure_session, should_run_background
 from ssh_mcp.server import SSHMCPServer
 
 
@@ -714,3 +714,48 @@ class TestHandleTaskStatus:
             },
         )
         assert len(result) == 1
+
+
+class TestEnsureSessionStaleId:
+    """session_id 失效时的透明重建：不再直接返回必失败的 id"""
+
+    @staticmethod
+    def _ctx(get_session_return=None):
+        ctx = MagicMock()
+        ctx.session_manager = MagicMock()
+        ctx.session_manager.get_session = AsyncMock(return_value=get_session_return)
+        ctx.logger = MagicMock()
+        ctx.env_config = None
+        return ctx
+
+    @pytest.mark.asyncio
+    async def test_live_session_id_returned_directly(self):
+        ctx = self._ctx(get_session_return=MagicMock())
+        sid = await ensure_session(ctx, {"session_id": "s1"}, AsyncMock())
+        assert sid == "s1"
+        ctx.session_manager.get_session.assert_awaited_once_with("s1")
+
+    @pytest.mark.asyncio
+    async def test_stale_id_rebuilds_via_host(self):
+        """失效 id + 同请求携带 host 参数 → 走回退链透明重建"""
+        from mcp.types import TextContent
+
+        ctx = self._ctx(get_session_return=None)
+
+        async def fake_connect(c, a):
+            return [TextContent(type="text", text="Connected to 1.2.3.4\nSession ID: fresh-id")]
+
+        sid = await ensure_session(ctx, {"session_id": "stale", "host": "1.2.3.4"}, fake_connect)
+        assert sid == "fresh-id"
+        ctx.logger.warning.assert_called_once()  # 失效告警已记录
+
+    @pytest.mark.asyncio
+    async def test_stale_id_without_fallback_returns_original(self):
+        """失效 id 且无任何回退信息 → 返回原 id，由上层报准确的 Session not found"""
+
+        async def unexpected_connect(c, a):
+            raise AssertionError("no name/host/env configured, connect should not be called")
+
+        ctx = self._ctx(get_session_return=None)
+        sid = await ensure_session(ctx, {"session_id": "stale"}, unexpected_connect)
+        assert sid == "stale"

{ssh_licco-2.7.1 → ssh_licco-2.7.3}/tests/test_session_manager.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import asyncio
-from datetime import datetime
+from datetime import datetime, timedelta
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
@@ -147,14 +147,12 @@ class TestSessionManager:
 
     @pytest.mark.asyncio
     async def test_get_session_disconnected_auto_clean(self):
-        """get_session 遇到已断开的 session 时，应自动清理并返回 None（不抛 AttributeError）"""
+        """get_session 遇到非真实 SSHSession 对象（如测试 Mock）时，应清理并返回 None"""
         manager = SessionManager()
         mock_session = MagicMock()
         mock_session.is_connected = False
         mock_session.config.host = "1.2.3.4"
-        # 让重连计数已达上限，走"清理并返回 None"分支（避免 MagicMock 比较 '>=' 报错）
-        mock_session._reconnect_count = 99
-        mock_session._max_reconnects = 1
+        # MagicMock 不是 SSHSession 实例，走"跳过重连并清理"分支
         # disconnect 是协程，需用 AsyncMock
         mock_session.disconnect = AsyncMock(return_value=None)
         manager._sessions["dead-id"] = mock_session
@@ -168,6 +166,111 @@ class TestSessionManager:
         result = await manager.get_session("nonexistent")
         assert result is None
 
+    @pytest.mark.asyncio
+    async def test_get_session_dead_transparent_rebuild(self, conn_config):
+        """死会话透明重建：复用原 session_id、成功后连续失败计数清零（不再删除 entry）"""
+
+        class FakeSession(SSHSession):
+            async def connect(self):
+                self._state = SessionState.CONNECTED
+                self.client = MagicMock()
+                return self._get_session_info()
+
+        manager = SessionManager()
+        # dead 必须是 FakeSession 实例（不调用 connect 即保持断开态），
+        # 否则补丁后 isinstance 检查会走清理分支
+        dead = FakeSession(conn_config)
+        dead._reconnect_count = 99  # 即使远超旧的重连上限也应重建
+        manager._sessions["sid"] = dead
+
+        with patch("ssh_mcp.session_manager.SSHSession", FakeSession):
+            result = await manager.get_session("sid")
+
+        assert isinstance(result, FakeSession)
+        assert result is not dead  # 底层对象已替换
+        assert result.session_id == "sid"  # 调用方持有的 session_id 保持有效
+        assert manager._sessions["sid"] is result
+        assert result._reconnect_count == 0
+
+    @pytest.mark.asyncio
+    async def test_get_session_rebuild_failure_keeps_entry(self, conn_config):
+        """重建失败不删除 entry：session_id 保留，主机恢复后下次调用重建成功"""
+
+        class FlakySession(SSHSession):
+            fail_connect = True
+
+            async def connect(self):
+                if type(self).fail_connect:
+                    raise ConnectionError("host unreachable")
+                self._state = SessionState.CONNECTED
+                self.client = MagicMock()
+                return self._get_session_info()
+
+        manager = SessionManager()
+        dead = FlakySession(conn_config)  # 未连接 → 死会话
+        manager._sessions["sid"] = dead
+
+        with patch("ssh_mcp.session_manager.SSHSession", FlakySession):
+            # 阶段一：主机不可达，重建失败但 entry 保留
+            result = await manager.get_session("sid")
+            assert result is None
+            assert manager._sessions["sid"] is dead  # entry 保留供后续重试
+            assert dead._reconnect_count == 1  # 连续失败计数累加（日志观察用）
+
+            # 阶段二：主机恢复，同一 session_id 透明重建成功
+            FlakySession.fail_connect = False
+            result = await manager.get_session("sid")
+            assert result is not None
+            assert result.session_id == "sid"
+            assert manager._sessions["sid"] is result
+
+    @pytest.mark.asyncio
+    async def test_get_session_live_resets_reconnect_count(self, conn_config):
+        """存活会话被正常获取时重置连续失败计数，历史抖动不累计"""
+        manager = SessionManager()
+        live = SSHSession(conn_config)
+        live._state = SessionState.CONNECTED
+        live.client = MagicMock()
+        live._reconnect_count = 2
+        manager._sessions["sid"] = live
+
+        result = await manager.get_session("sid")
+        assert result is live
+        assert live._reconnect_count == 0
+
+    @pytest.mark.asyncio
+    async def test_create_session_dead_entries_do_not_count_toward_limit(self, conn_config):
+        """dead entry 不占用并发额度：同主机多个死会话不应阻止新建"""
+
+        class FakeSession(SSHSession):
+            async def connect(self):
+                self._state = SessionState.CONNECTED
+                self.client = MagicMock()
+                return self._get_session_info()
+
+        manager = SessionManager()
+        for i in range(manager.MAX_SESSIONS_PER_HOST):
+            dead = SSHSession(conn_config)  # 从未连接 → 死会话
+            manager._sessions[f"dead-{i}"] = dead
+
+        with patch("ssh_mcp.session_manager.SSHSession", FakeSession):
+            info = await manager.create_session(conn_config)  # 不应抛 ConnectionException
+
+        assert info.session_id in manager._sessions
+
+    @pytest.mark.asyncio
+    async def test_cleanup_timeout_sessions_reaps_dead_entries(self, conn_config):
+        """dead entry 超过 idle 超时后由清理循环兜底回收，不会永久滞留"""
+        manager = SessionManager()
+        dead = SSHSession(conn_config)
+        dead._last_activity = datetime.now() - timedelta(
+            seconds=conn_config.session_timeout + 100
+        )
+        manager._sessions["sid"] = dead
+
+        await manager._cleanup_timeout_sessions()
+        assert "sid" not in manager._sessions
+
     @pytest.mark.asyncio
     async def test_close_session(self):
         manager = SessionManager()

ssh_licco-2.7.1/ssh_mcp/cli.py

@@ -1,135 +0,0 @@
-"""SSH-LICCO command line interface."""
-from __future__ import annotations
-
-import argparse
-import os
-import sys
-from pathlib import Path
-
-from ssh_mcp import __version__
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    """Build the CLI argument parser."""
-    parser = argparse.ArgumentParser(
-        prog="ssh-licco",
-        description="SSH-LICCO: Remote server management via MCP and CLI.",
-    )
-    parser.add_argument(
-        "--version",
-        action="version",
-        version=f"ssh-licco {__version__}",
-    )
-
-    subparsers = parser.add_subparsers(dest="subcommand", required=False)
-
-    # exec
-    exec_parser = subparsers.add_parser("exec", help="Execute a remote command")
-    exec_parser.add_argument("cmd", help="Command to execute")
-    exec_parser.add_argument("--host", default=None, help="Remote host")
-    exec_parser.add_argument("-u", "--username", default=None, help="SSH username")
-    exec_parser.add_argument("--password", default=None, help="SSH password")
-    exec_parser.add_argument(
-        "--connect-timeout", type=int, default=None, help="Connection timeout in seconds"
-    )
-
-    # upload
-    upload_parser = subparsers.add_parser("upload", help="Upload a file")
-    upload_parser.add_argument("local", help="Local file path")
-    upload_parser.add_argument("remote", help="Remote file path")
-    upload_parser.add_argument("--host", default=None, help="Remote host")
-    upload_parser.add_argument("-u", "--username", default=None, help="SSH username")
-    upload_parser.add_argument("--password", default=None, help="SSH password")
-
-    # download
-    download_parser = subparsers.add_parser("download", help="Download a file")
-    download_parser.add_argument("remote", help="Remote file path")
-    download_parser.add_argument("local", help="Local file path")
-    download_parser.add_argument("--host", default=None, help="Remote host")
-    download_parser.add_argument("-u", "--username", default=None, help="SSH username")
-    download_parser.add_argument("--password", default=None, help="SSH password")
-
-    # docker-build
-    docker_build_parser = subparsers.add_parser("docker-build", help="Build a Docker image")
-    docker_build_parser.add_argument("image", help="Image tag")
-    docker_build_parser.add_argument("-c", "--context", default=".", help="Build context")
-    docker_build_parser.add_argument("-f", "--dockerfile", default="Dockerfile", help="Dockerfile path")
-    docker_build_parser.add_argument("-t", "--timeout", type=int, default=600, help="Build timeout")
-
-    # serve
-    subparsers.add_parser("serve", help="Start the MCP server")
-
-    # list-hosts
-    subparsers.add_parser("list-hosts", help="List configured hosts")
-
-    return parser
-
-
-def _load_connection_config(args: argparse.Namespace) -> dict:
-    """Load connection config from CLI args or environment variables."""
-    host = args.host or os.getenv("SSH_HOST")
-    username = args.username or os.getenv("SSH_USER")
-    password = args.password or os.getenv("SSH_PASSWORD")
-    port = args.port if getattr(args, "port", None) else 22
-    timeout = args.connect_timeout if getattr(args, "connect_timeout", None) else 30
-
-    return {
-        "host": host,
-        "port": port,
-        "username": username,
-        "password": password,
-        "timeout": timeout,
-    }
-
-
-def main(argv: list[str] | None = None) -> int:
-    """CLI entry point."""
-    parser = _build_parser()
-    args = parser.parse_args(argv)
-
-    if args.subcommand is None:
-        parser.print_help()
-        return 0
-
-    if args.subcommand == "serve":
-        from ssh_mcp.server import run_server
-
-        run_server()
-        return 0
-
-    if args.subcommand == "list-hosts":
-        from ssh_mcp.config_manager import ConfigManager
-
-        manager = ConfigManager()
-        hosts = manager.list_hosts()
-        if not hosts:
-            print("No hosts configured.")
-            return 0
-        for name, config in hosts.items():
-            print(f"{name}: {config.host}:{config.port} ({config.username})")
-        return 0
-
-    if args.subcommand == "exec":
-        config = _load_connection_config(args)
-        print(f"Would execute on {config['host']}: {args.cmd}")
-        return 0
-
-    if args.subcommand == "upload":
-        config = _load_connection_config(args)
-        print(f"Would upload {args.local} -> {config['host']}:{args.remote}")
-        return 0
-
-    if args.subcommand == "download":
-        config = _load_connection_config(args)
-        print(f"Would download {config['host']}:{args.remote} -> {args.local}")
-        return 0
-
-    if args.subcommand == "docker-build":
-        print(f"Would build Docker image {args.image} from {args.context}/{args.dockerfile}")
-        return 0
-
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())