{
  "markdown": "# 🚀 SSH LICCO\n\n<!-- mcp-name: io.github.Echoqili/ssh-licco -->\n\n[![PyPI version](https://img.shields.io/pypi/v/ssh-licco.svg?cacheSeconds=1800)](https://pypi.org/project/ssh-licco/)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-green.svg)](https://registry.modelcontextprotocol.io/)\n\n> **让 AI 帮你操作服务器！** 通过自然语言对话，AI 可以帮你执行命令、管理文件、查看日志、部署应用等。\n\n---\n\n## 📚 文档导航\n\n### 快速开始\n- **[⬇️ 安装指南](#-快速安装)** - 2 种安装方式\n- **[🚀 快速开始](#-快速开始)** - 5 分钟上手\n- **[📋 配置模板](#-完整配置示例)** - 开箱即用的配置\n\n### 核心功能\n- **[🔐 安全配置](#-安全配置)** - 多级安全策略\n- **[🛠️ 可用工具](#-可用工具)** - 完整功能列表\n- **[💡 使用示例](#-使用示例)** - 实际应用场景\n\n### 高级主题\n- **[📖 完整配置指南](MCP_CONFIG_GUIDE.md)** - 所有配置选项详解\n- **[🔧 故障排除](docs/API_REFERENCE.md)** - 常见问题解决\n- **[📊 API 参考](docs/API_REFERENCE.md)** - 详细 API 文档\n\n### 开发资源\n- **[🎓 Skills 文档](docs/skills/)** - 开发、运维、安装指南\n- **[📦 发布指南](#-发布指南一体化命令)** - 一体化版本发布命令\n- **[🐛 GitHub Issues](https://github.com/Echoqili/ssh-licco/issues)** - 问题反馈\n\n---\n\n## ✨ 特性亮点\n\n- 🎯 **自然语言控制** - 用对话方式操作服务器\n- 🔐 **多种认证方式** - 密码、密钥、Agent 转发\n- 🔗 **长连接支持** - 自动保活（30 秒心跳），避免账户锁定\n- ⏱️ **可配置超时** - Banner 超时 (60s)、会话超时 (2 小时)，支持自动重连\n- 📦 **异步高性能** - 基于 Paramiko 的异步架构（线程池 + asyncio）\n- 🛡️ **完善的异常处理** - 统一的错误处理机制（7 层异常层次）\n- 📊 **会话管理** - 支持多个并发 SSH 会话（最大 10 个，每主机 3 个）\n- 📁 **SFTP 文件传输** - 上传、下载、目录管理\n- 🖊️ **远程文件编辑** - 直接写入/追加文件内容，无需下载再上传\n- 🔑 **密钥管理** - 生成和管理 SSH 密钥对（RSA/Ed25519）\n- 📝 **审计日志** - 完整的操作审计记录（JSON 结构化日志）\n- 🚀 **连接池** - 高性能连接复用（PooledConnection + ConnectionPool）\n- 📊 **批量执行** - 多主机并行命令执行（BatchExecutor + AsyncBatchExecutor）\n- 🐳 **Docker 支持** - Docker 构建和状态监控\n- 📋 **后台任务** - 可靠的后台进程启动（nohup + bash -c 包装，单次 SSH 调用无竞态）\n- 🖥️ **screen/tmux 会话** - 持久化远程会话，SSH 断开后进程依然存活\n- 🪟 **Windows 服务器支持** - 支持 Windows Server（OpenSSH for Windows）与 Linux/macOS 目标主机\n- 🔍 **进程管理** - 启动/停止/查询远程进程、SSH 端口转发（tunnel）\n- 🔍 **看门狗** - 任务监控、心跳检测、全局异常处理\n- 🛡️ **文件传输路径安全校验** - `ssh_file_transfer` delete 自动识别 Windows / Unix 路径风格并拦截敏感路径与路径遍历\n\n---\n\n## 🖥️ 目标主机支持\n\nSSH-LICCO 基于标准 SSH/SFTP 协议，可连接以下目标主机：\n\n| 操作系统 | 要求 | 备注 |\n|---|---|---|\n| **Linux** | OpenSSH 7.0+ | 推荐，完整支持所有功能 |\n| **Windows Server** | OpenSSH for Windows / PowerShell Remoting over SSH | v2.1.3+ 支持 Windows 路径风格与安全校验 |\n| **macOS** | 系统内置 OpenSSH | 完整支持 |\n\n> **提示**：连接 Windows 服务器时，请使用 Windows 风格路径（如 `C:\\temp\\file.txt`），系统会自动识别并进行路径安全校验。\n\n---\n\n## 📦 快速安装\n\n### 方式一：pip 安装（推荐）\n\n```bash\npip install ssh-licco\n```\n\n### 方式二：从源码安装\n\n```bash\ngit clone https://github.com/Echoqili/ssh-licco.git\ncd ssh-licco\npip install -e .\n```\n\n**Python 版本要求：** Python 3.10+\n\n---\n\n## 🚀 快速开始\n\n### 1️⃣ 配置 MCP 服务器\n\n#### 在 Trae / Cursor / Claude Desktop 中使用\n\n打开设置 → MCP → 添加新服务器：\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh\": {\n      \"command\": \"python -m ssh_mcp.server\"\n    }\n  }\n}\n```\n\n### 2️⃣ 配置 SSH 连接（可选但推荐）\n\n#### 方式 A：环境变量配置（推荐）\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh\": {\n      \"command\": \"python -m ssh_mcp.server\",\n      \"env\": {\n        \"SSH_HOST\": \"192.168.1.100\",\n        \"SSH_USER\": \"root\",\n        \"SSH_PASSWORD\": \"your_password\",\n        \"SSH_PORT\": \"22\",\n        \"SSH_TIMEOUT\": \"60\",\n        \"SSH_KEEPALIVE_INTERVAL\": \"30\",\n        \"SSH_SESSION_TIMEOUT\": \"7200\",\n        \"SSH_CLIENT_TYPE\": \"common\"\n      }\n    }\n  }\n}\n```\n\n**环境变量说明：**\n- `SSH_HOST`: SSH 服务器地址\n- `SSH_USER`: 用户名\n- `SSH_PASSWORD`: 密码\n- `SSH_PORT`: 端口（默认 22）\n- `SSH_TIMEOUT`: 连接超时（秒）\n- `SSH_KEEPALIVE_INTERVAL`: 保活间隔（秒）\n- `SSH_SESSION_TIMEOUT`: 会话超时（秒）\n- `SSH_CLIENT_TYPE`: SSH 客户端类型（可选，默认 `common`）\n  - `common` - paramiko（稳定可靠，推荐）⭐\n  - `performance` - asyncssh（高性能，适合高并发）🚀\n  - `development` - fabric（简化 API，适合快速开发）👨‍💻\n\n---\n\n## 🔐 安全配置\n\n> **重要**：从 v0.2.1 开始，ssh-licco 提供多级安全策略，可根据使用场景灵活配置。\n\n### 多级安全策略\n\n| 级别 | 名称 | 适用场景 | 安全评分 |\n|------|------|----------|----------|\n| **STRICT** | 严格模式 | 生产环境、公共服务器 | 最高 ⭐⭐⭐ |\n| **BALANCED** | 平衡模式 | 开发环境、个人服务器（默认） | 高 ⭐⭐ |\n| **RELAXED** | 宽松模式 | 测试环境、完全信任的服务器 | 中等 ⭐ |\n\n### 快速配置\n\n#### 方式 1：环境变量（推荐）\n\n**Windows PowerShell**:\n```powershell\n$env:SSH_SECURITY_LEVEL = \"balanced\"\n$env:SSH_EXTRA_ALLOWED_COMMANDS = \"git,pip,npm\"\n```\n\n**Linux/Mac**:\n```bash\nexport SSH_SECURITY_LEVEL=\"balanced\"\nexport SSH_EXTRA_ALLOWED_COMMANDS=\"git,pip,npm\"\n```\n\n#### 方式 2：MCP 配置文件\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh\": {\n      \"command\": \"python -m ssh_mcp.server\",\n      \"env\": {\n        \"SSH_SECURITY_LEVEL\": \"balanced\",\n        \"SSH_EXTRA_ALLOWED_COMMANDS\": \"git,pip,npm\",\n        \"SSH_BASE_DIR\": \"/home\"\n      }\n    }\n  }\n}\n```\n\n### 📖 详细文档\n\n- **[MCP_CONFIG_GUIDE.md](MCP_CONFIG_GUIDE.md)** - 完整配置指南，包含 5 种使用场景示例\n- **[SECURITY_CONFIG_GUIDE.md](SECURITY_CONFIG_GUIDE.md)** - 安全配置详解\n\n### 🛡️ 硬拦截灾难性命令（v2.2.0 新增）\n\n为防止任何误操作或越权调用直接打到远程 shell，ssh-licco 在所有安全级别下都**无条件**拦截以下灾难性命令模式，**无法通过 `confirm_dangerous=true`、`confirmation_layer=N`、调整 `SSH_SECURITY_LEVEL` 等任何方式绕过**：\n\n- `rm -rf` 作用于绝对路径（含 `/`、`/*`、`/path`、`/path/*`，`-fr` 变体同效）\n- `mkfs.*` 任意文件系统格式化\n- `dd if=/dev/(zero|random|urandom) of=/dev/(sd|nvme)` 覆写裸盘\n- bash fork-bomb（`:(){ :|:& };:` 及空白变体）\n- `chmod -R 777 /` / `chmod -R 000 /` 根目录递归改权限\n- `> /dev/(sd|nvme)` / `>> /dev/(sd|nvme)` 裸设备重定向\n\n如确需执行上述操作，请直接通过 SSH 登录服务器（绕过 MCP 网关）进行。安全且可逆的替代方案：\n\n```bash\n# 旧做法（v2.2.0 之前）：rm -rf /path/to/junk  ← 现已被硬拦截\n# 推荐做法：mv 到回收站，约定时间后清理\nmv /path/to/junk /tmp/.trash_$(date +%s)/\n```\n\n命中硬拦截时会输出 `WARNING` 审计日志（含 category 与命令），便于 SOC 监控。\n\n---\n\n## 🛠️ 可用工具（v2.2.0 维持 9 个；v2.1.0 曾增加的 3 个审批工具因流程闭环风险已下线）\n\n| 工具 | 描述 | 核心能力 |\n|------|------|---------|\n| `ssh_connect` | 连接管理 | 自动读取环境变量/配置，支持密码+密钥认证，可保存配置，登录后自动执行命令 |\n| `ssh_execute` | 命令执行 | 自动连接、智能后台检测、长任务等待、超时控制，支持 nohup/screen/tmux 三种后台模式；v2.2.0 起对灾难性命令（rm -rf 绝对路径、mkfs、raw-disk dd、fork-bomb 等）做**无条件硬拦截** |\n| `ssh_disconnect` | 会话管理 | 断开指定会话 OR 列出所有活跃会话 |\n| `ssh_file_transfer` | 文件传输 | 上传/下载/列表/写入/追加/删除/创建目录/查看元信息（8 种操作）；v2.1.3+ delete 操作新增 Windows/Unix 敏感路径拦截与路径遍历防护 |\n| `ssh_host` | 主机管理 | `action=list/add/remove` 增删查主机配置 |\n| `ssh_docker` | Docker 管理 | `action=ps/images/build/logs` 全生命周期管理 |\n| `ssh_generate_key` | 密钥生成 | RSA / Ed25519 密钥对 |\n| `ssh_session` | screen/tmux 会话 | 持久化远程会话管理（create/send/capture/list/kill），SSH 断开后进程依然存活 |\n| `ssh_process` | 进程管理 | 启动/停止/查询远程进程，SSH 端口转发（tunnel_open/tunnel_close/tunnel_list） |\n\n> **关于 v2.1.0 引入的 3 个审批工具**（`ssh_request_approval` / `ssh_approve_command` / `ssh_list_approvals`）：已从 MCP `list_tools()` 移除，**代码已在 v2.2.0 删除**（`ssh_mcp/approval.py`、`ssh_mcp/handlers/approval.py`）。审批流程依赖 AI 自报命令、运维侧背书，存在闭环风险；v2.2.0 的硬拦截更直接——灾难性命令在 MCP 网关层就被拒绝，运维侧不需要再走\"先申请再审批\"流程。\n\n### 📖 详细文档\n\n- **[docs/API_REFERENCE.md](docs/API_REFERENCE.md)** - 完整 API 参考\n- **[docs/skills/ssh-mcp-ops/SKILL.md](docs/skills/ssh-mcp-ops/SKILL.md)** - 运维操作指南\n\n---\n\n## 💡 使用示例\n\n### 示例 1：执行命令\n\n```\n用户：帮我查看服务器上的 Docker 容器\nAI：调用 ssh_connect → ssh_execute \"docker ps\"\n\n[执行结果]\nCONTAINER ID   IMAGE     COMMAND   STATUS   PORTS\nabc123         nginx     \"nginx\"   Up 2 days 80:80\n```\n\n### 示例 2：文件上传\n\n```\n用户：把这个文件上传到 /var/www/html\nAI：调用 ssh_connect → ssh_file_transfer\n\n[上传成功]\n本地：./index.html\n远程：/var/www/html/index.html\n大小：2.3 KB\n```\n\n### 示例 3：Docker 构建（长任务）\n\n```\n用户：帮我构建 Docker 镜像\nAI：调用 ssh_execute(background=True) 后台执行 docker build...\n\n[后台任务已启动]\nSession ID: a1b2c3d4\n命令：docker build -t myapp .\n使用 ssh_execute(session_id=\"a1b2c3d4\", command=\"cat /tmp/build.log\") 查看进度\n```\n\n### 示例 4：数据库检查\n\n```\n用户：检查 PostgreSQL 是否正常运行\nAI：调用 ssh_execute \"pg_isready -h localhost -p 5432\"\n\n[检查结果]\nlocalhost:5432 - accepting connections\n✅ PostgreSQL 运行正常\n```\n\n### 📖 更多示例\n\n- **[docs/skills/ssh-mcp-ops/SKILL.md](docs/skills/ssh-mcp-ops/SKILL.md)** - 运维操作示例\n- **[docs/skills/ssh-mcp-dev/SKILL.md](docs/skills/ssh-mcp-dev/SKILL.md)** - 开发场景示例\n\n---\n\n## 📋 完整配置示例\n\n### 场景 1：Web 开发者\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh\": {\n      \"command\": \"python -m ssh_mcp.server\",\n      \"env\": {\n        \"SSH_SECURITY_LEVEL\": \"balanced\",\n        \"SSH_EXTRA_ALLOWED_COMMANDS\": \"git,npm,docker,composer,pm2\",\n        \"SSH_BASE_DIR\": \"/var/www\",\n        \"SSH_HOST\": \"192.168.1.100\",\n        \"SSH_USER\": \"deploy\",\n        \"SSH_PASSWORD\": \"your-password\"\n      }\n    }\n  }\n}\n```\n\n### 场景 2：Python 开发者\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh\": {\n      \"command\": \"python -m ssh_mcp.server\",\n      \"env\": {\n        \"SSH_SECURITY_LEVEL\": \"balanced\",\n        \"SSH_EXTRA_ALLOWED_COMMANDS\": \"pip,poetry,python3,pytest,black\",\n        \"SSH_HOST\": \"192.168.1.100\",\n        \"SSH_USER\": \"developer\",\n        \"SSH_PASSWORD\": \"your-password\"\n      }\n    }\n  }\n}\n```\n\n### 场景 3：数据库管理员\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh\": {\n      \"command\": \"python -m ssh_mcp.server\",\n      \"env\": {\n        \"SSH_SECURITY_LEVEL\": \"balanced\",\n        \"SSH_EXTRA_ALLOWED_COMMANDS\": \"psql,mysql,mongosh,pg_isready\",\n        \"SSH_HOST\": \"192.168.1.100\",\n        \"SSH_USER\": \"dbadmin\",\n        \"SSH_PASSWORD\": \"your-password\"\n      }\n    }\n  }\n}\n```\n\n### 场景 4：系统管理员\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh\": {\n      \"command\": \"python -m ssh_mcp.server\",\n      \"env\": {\n        \"SSH_SECURITY_LEVEL\": \"relaxed\",\n        \"SSH_EXTRA_ALLOWED_COMMANDS\": \"sudo,apt,yum,systemctl,journalctl,docker,kubectl\",\n        \"SSH_HOST\": \"192.168.1.100\",\n        \"SSH_USER\": \"root\",\n        \"SSH_PASSWORD\": \"your-password\"\n      }\n    }\n  }\n}\n```\n\n### 场景 5：生产环境（最高安全）\n\n```json\n{\n  \"mcpServers\": {\n    \"ssh\": {\n      \"command\": \"python -m ssh_mcp.server\",\n      \"env\": {\n        \"SSH_SECURITY_LEVEL\": \"strict\",\n        \"SSH_HOST\": \"192.168.1.100\",\n        \"SSH_USER\": \"app-user\",\n        \"SSH_PASSWORD\": \"your-password\",\n        \"SSH_BASE_DIR\": \"/home/app-user\"\n      }\n    }\n  }\n}\n```\n\n### 📖 更多配置\n\n- **[MCP_CONFIG_GUIDE.md](MCP_CONFIG_GUIDE.md)** - 包含所有配置选项的详细说明\n\n### 🌐 完整环境变量速查（v2.3.0）\n\n> 下表所有变量均被代码读取。**注意**：\n> - `SSH_RATE_LIMIT` 是 **bool** 总开关（true/false），`SSH_RATE_LIMIT_MAX` 才是次数上限，两者分开配置\n> - 主机密钥检查（strict_host_key_checking）**不通过 env 配置**，请用 `ssh_connect` 工具参数或 `hosts.json`\n\n| 分类 | 变量 | 默认 | 说明 |\n|------|------|------|------|\n| **安全** | `SSH_SECURITY_LEVEL` | `balanced` | 安全级别：`strict` / `balanced` / `relaxed` |\n|  | `SSH_BASE_DIR` | `/home` | 路径校验基目录 |\n|  | `SSH_EXTRA_ALLOWED_COMMANDS` | (空) | 额外允许的命令（逗号分隔） |\n|  | `SSH_ALLOWED_COMMANDS_FILE` | (空) | 命令白名单 JSON 文件路径 |\n|  | `SSH_AUDIT_LOG_PATH` | (空) | 审计日志文件路径 |\n| **限流** | `SSH_RATE_LIMIT` | `true` | 限流总开关（bool） |\n|  | `SSH_RATE_LIMIT_MAX` | `30` | 限流次数上限 |\n|  | `SSH_RATE_LIMIT_WINDOW` | `60` | 限流窗口（秒） |\n| **硬拦截** | *(无 env)* | — | 灾难性命令硬拦截，零配置零绕过 |\n| **连接默认** | `SSH_HOST` / `SSH_PORT` / `SSH_USER` / `SSH_PASSWORD` | `127.0.0.1` / `22` / `root` / (空) | 单 host 模式默认连接参数 |\n|  | `SSH_TIMEOUT` | `60` | 连接超时（秒） |\n|  | `SSH_KEEPALIVE_INTERVAL` | `30` | keepalive 间隔（秒） |\n|  | `SSH_SESSION_TIMEOUT` | `7200` | 会话超时（秒） |\n|  | `SSH_CLIENT_TYPE` | `paramiko` | SSH 客户端实现：`paramiko` / `asyncssh` |\n|  | `SSH_FORCE_ENV_CONFIG` | `false` | 强制 env 配置覆盖 hosts.json |\n|  | `SSH_SUDO_PASSWORD` | (空) | sudo 密码，配合 `use_sudo=true` 走 `sudo -S` |\n\n---\n\n## ⚠️ 依赖版本兼容性\n\n### 已知依赖冲突\n\n以下依赖版本冲突已在测试环境中验证，**不影响 ssh-licco 的正常使用**：\n\n#### 1. starlette 版本冲突\n\n```\nfastapi 需要 starlette<0.51.0\n但安装了 starlette 0.52.1\n```\n\n**影响范围：**\n- ✅ **ssh-licco**: 无影响，正常工作\n- ⚠️ **fastapi**: 可能存在兼容性问题（如果同时使用 fastapi）\n\n**解决方案：**\n- 如果只使用 ssh-licco，可以忽略此警告\n- 如果同时使用 fastapi，建议：\n  ```bash\n  pip install starlette==0.50.0\n  ```\n\n#### 2. cryptography 版本冲突\n\n```\npyopenssl 需要 cryptography<45\n但安装了 cryptography 46.0.5\n```\n\n**影响范围：**\n- ✅ **ssh-licco**: 无影响，正常工作\n- ⚠️ **pyopenssl**: 可能存在兼容性问题（如果同时使用 pyopenssl）\n\n**解决方案：**\n- 如果只使用 ssh-licco，可以忽略此警告\n- 如果同时使用 pyopenssl，建议：\n  ```bash\n  pip install cryptography==44.0.0\n  ```\n\n### 测试环境\n\n**测试通过的配置：**\n- ✅ starlette 0.52.1 + ssh-licco 0.4.1\n- ✅ cryptography 46.0.5 + ssh-licco 0.4.1\n- ✅ mcp 1.26.0 + ssh-licco 0.4.1\n\n**测试场景：**\n- ✅ SSH 连接和执行命令\n- ✅ 文件上传和下载\n- ✅ 后台任务执行\n- ✅ Docker 构建和监控\n- ✅ 多语言后台命令自动检测\n\n### 为什么允许这些冲突？\n\nssh-licco 的核心依赖是：\n- `mcp` - MCP 协议实现\n- `asyncssh` - SSH 客户端\n- `paramiko` - SSH 客户端（稳定模式）\n- `pydantic` - 数据验证\n\n而 `starlette` 和 `cryptography` 是通过 `mcp` 间接引入的。ssh-licco 本身不直接使用这些库的 API，因此版本冲突不会影响 ssh-licco 的功能。\n\n---\n\n## 🔧 故障排查\n\n### 常见问题\n\n#### 1. 连接失败\n\n**错误**: `Connection refused`\n\n**解决**:\n- 检查 SSH 服务是否运行：`systemctl status sshd`\n- 检查防火墙设置：`ufw status`\n- 确认端口正确：默认 22\n\n#### 2. 认证失败\n\n**错误**: `Authentication failed`\n\n**解决**:\n- 检查用户名和密码\n- 尝试使用密钥认证\n- 查看 SSH 日志：`/var/log/auth.log`\n\n#### 3. 命令被阻止\n\n**错误**: `命令 'xxx' 不在允许列表中`\n\n**解决**:\n```json\n{\n  \"SSH_SECURITY_LEVEL\": \"balanced\",\n  \"SSH_EXTRA_ALLOWED_COMMANDS\": \"被阻止的命令\"\n}\n```\n\n### 📖 详细文档\n\n- **[docs/API_REFERENCE.md](docs/API_REFERENCE.md)** - API 参考和错误处理\n- **[docs/skills/ssh-mcp-troubleshoot/SKILL.md](docs/skills/ssh-mcp-troubleshoot/SKILL.md)** - 故障排除指南\n- **[MCP_CONFIG_GUIDE.md](MCP_CONFIG_GUIDE.md)** - 配置故障排查\n\n---\n\n## 🎓 学习资源\n\n### Skills 文档\n\n- **[📦 发布指南](docs/skills/RELEASE_SKILL.md)** - 完整的版本发布流程\n- **[🔧 开发指南](docs/skills/ssh-mcp-dev/SKILL.md)** - 开发环境和流程\n- **[🛠️ 运维指南](docs/skills/ssh-mcp-ops/SKILL.md)** - 运维操作最佳实践\n- **[⚙️ 安装指南](docs/skills/ssh-mcp-setup/SKILL.md)** - 安装和配置步骤\n- **[🔍 故障排除](docs/skills/ssh-mcp-troubleshoot/SKILL.md)** - 常见问题解决\n\n### 配置文档\n\n- **[MCP_CONFIG_GUIDE.md](MCP_CONFIG_GUIDE.md)** - 完整配置指南\n- **[SECURITY_CONFIG_GUIDE.md](SECURITY_CONFIG_GUIDE.md)** - 安全配置详解\n\n### API 文档\n\n- **[docs/API_REFERENCE.md](docs/API_REFERENCE.md)** - API 参考文档\n\n---\n\n## 🔗 相关链接\n\n### 项目资源\n\n- **GitHub**: https://github.com/Echoqili/ssh-licco\n- **PyPI**: https://pypi.org/project/ssh-licco/\n- **MCP Registry**: https://registry.modelcontextprotocol.io/servers/io.github.Echoqili/ssh-licco\n- **Issues**: https://github.com/Echoqili/ssh-licco/issues\n\n### 文档索引\n\n| 文档 | 描述 | 位置 |\n|------|------|------|\n| 📖 配置指南 | 完整配置选项和场景 | [MCP_CONFIG_GUIDE.md](MCP_CONFIG_GUIDE.md) |\n| 🔐 安全指南 | 安全配置详解 | [SECURITY_CONFIG_GUIDE.md](SECURITY_CONFIG_GUIDE.md) |\n| 📊 API 参考 | 完整 API 文档 | [docs/API_REFERENCE.md](docs/API_REFERENCE.md) |\n| 🎓 Skills | 开发、运维、安装指南 | [docs/skills/](docs/skills/) |\n| 📦 发布指南 | 版本发布流程 | [docs/skills/RELEASE_SKILL.md](docs/skills/RELEASE_SKILL.md) |\n\n---\n\n## 🧪 测试\n\n### 测试状态\n\n| 指标 | 状态 |\n|------|------|\n| **测试用例** | 244 passed, 0 skipped |\n| **覆盖率** | 16 个源模块全覆盖 |\n| **测试框架** | pytest + pytest-asyncio |\n\n### 测试模块覆盖\n\n| 源模块 | 测试文件 | 用例数 |\n|--------|----------|--------|\n| `exceptions.py` | `test_exceptions.py` | 7 |\n| `connection_config.py` | `test_connection_config.py` | 8 |\n| `security.py` | `test_security.py` | 24 |\n| `logging_config.py` | `test_logging_config.py` | 8 |\n| `audit_logger.py` | `test_audit_logger.py` | 12 |\n| `executor.py` | `test_executor.py` | 8 |\n| `watchdog.py` | `test_watchdog.py` | 18 |\n| `key_manager.py` | `test_key_manager.py` | 6 |\n| `config_manager.py` | `test_config_manager.py` | 10 |\n| `clients/interface.py` | `test_factory.py` | 10 |\n| `clients/paramiko_client.py` | `test_paramiko_client.py` | 18 |\n| `clients/factory.py` | `test_factory.py` | 10 |\n| `session_manager.py` | `test_session_manager.py` | 18 |\n| `connection_pool.py` | `test_connection_pool.py` | 10 |\n| `batch_executor.py` | `test_batch_executor.py` | 10 |\n| `server.py` | `test_server.py` | 30+ |\n| `service.py` | `test_service.py` | 14 |\n\n### 运行测试\n\n```bash\n# 运行全部测试\npytest tests/ -v\n\n# 运行特定模块测试\npytest tests/test_security.py -v\n\n# 查看覆盖率\npytest --cov=ssh_mcp --cov-report=term-missing\n```\n\n---\n\n## 📦 发布指南（一体化命令）\n\n项目提供 `sync_version.py` 作为**唯一**版本发布入口，一条命令完成所有版本源同步 + 文档更新 + 一致性自检 + git commit/tag/push，杜绝漏改 `VERSION` / `package.json` / `SKILL.md` 等文件。\n\n### 一键发布\n\n```bash\n# 升 patch（z）：2.7.1 → 2.7.2\npython sync_version.py 2.7.2\n\n# 升 minor（y）：2.7.1 → 2.8.0\npython sync_version.py 2.8.0\n\n# 升 major（x）：2.7.1 → 3.0.0\npython sync_version.py 3.0.0\n```\n\n默认行为：改版本源 → 同步文档版本 → 一致性自检 → `commit` → `push` → 打 `tag` → `push tag`。\n\n### 常用选项\n\n```bash\n# 预览会发生的变更，不写文件、不 commit\npython sync_version.py 2.7.2 --dry-run\n\n# 只改文件，不提交、不打 tag\npython sync_version.py 2.7.2 --no-commit --no-tag\n\n# 只做一致性自检（CI 中使用）\npython sync_version.py --check\n```\n\n### 覆盖的版本源\n\n| 文件 | 字段 | 说明 |\n|------|------|------|\n| `ssh_mcp/__init__.py` | `__version__` | **唯一真源**，其他文件都与其对齐 |\n| `pyproject.toml` | `version` | Python 包构建版本 |\n| `VERSION` | 纯文本 | `.github/workflows/pypi.yml` 实际读取的版本 |\n| `package.json` | `version` | npm 包版本 |\n| `package-lock.json` | `version` × 2 | npm lock 根版本 + `packages[\"\"].version` |\n| `.trae/skills/*/SKILL.md` | `Current Version` | 文档中的版本标注 |\n| `docs/skills/*/SKILL.md` | `Current Version` | 文档中的版本标注 |\n\n### CI 预检\n\n`.github/workflows/pypi.yml` 在构建前会执行 `python sync_version.py --check`，任何版本源不一致都会**直接中断发布流程**，防止打错版本号。\n\n> 完整发布流程（含 PyPI 上传、MCP Registry 发布）见 [docs/skills/RELEASE_SKILL.md](docs/skills/RELEASE_SKILL.md)。\n\n---\n\n## 📊 版本历史",
  "bytes": 16371,
  "sha": "7182b84440e60f55891d445cbe7aea1b531af39eab19133a7a2ecaf370debb13",
  "repo_slug": "echoqili/ssh-licco",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_echoqili_ssh_licco_c9ae08dc/readme"
}