feat: SSHClient v1.0.0 - PyQt5 + paramiko 跨平台 SSH 客户端

功能: - 多主机管理 (增删改查, 密码/私钥双认证, 导入导出) - 远程终端 (命令执行 + 常用命令快捷栏 + 超时控制) - SFTP 文件浏览 (上传/下载带进度, 新建/删除/重命名) - 实时监控 (CPU/内存/磁盘/网络, 1-10秒可调刷新) - AI Agent (OpenAI 兼容 API, 5 工具自动调用: 命令/指标/列文件/读文件/上传) 技术栈: PyQt5 + paramiko + psutil + requests + PyInstaller 打包: build_windows.bat / build.sh 一键产出 ~57MB 单文件 exe 测试: core 6/6 + UI 3/3 + E2E 6/6 全部通过
2026-07-28 21:01:31 +08:00
commit a57dbc0252
22 changed files with 3294 additions and 0 deletions
@@ -0,0 +1,126 @@
+# SSHClient
+
+> 基于 **PyQt5 + paramiko** 的 Windows SSH 客户端，支持远程终端、SFTP 文件浏览、CPU/内存/磁盘/网络实时监控，以及 OpenAI 兼容的 **AI Agent**（可调用工具操作远程主机）。
+
+![main](docs/screenshot.png)
+
+## ✨ 功能特性
+
+| 模块 | 说明 |
+| --- | --- |
+| 多主机管理 | 增删改查、密码/私钥双认证、配置导入导出、配置持久化到 `~/.sshclient/` |
+| 远程终端 | 命令执行 + 输出捕获 + 退出码 + 超时控制 + 常用命令快捷栏 |
+| SFTP 文件浏览 | 目录树浏览、上传/下载（带进度条）、新建目录、删除、重命名、双击进入 |
+| 实时监控 | CPU/内存/负载/启动时间/磁盘/网络速率，1-10 秒可调刷新间隔 |
+| AI Agent | OpenAI 兼容 API（OpenAI / DeepSeek / Moonshot / 通义千问 / Ollama 等），5 个工具自动调用：执行命令、查指标、列文件、读文件、上传 |
+| 跨平台 | 代码兼容 Windows / macOS / Linux（PyQt5 + paramiko） |
+
+## 📦 在 Windows 上构建 exe
+
+**最简单的方式：双击 `build_windows.bat`**
+
+1. 安装 [Python 3.10+](https://www.python.org/downloads/windows/)（勾选 Add to PATH）
+2. 把整个项目目录拷到 Windows 电脑
+3. 双击 `build_windows.bat`，等 2-3 分钟
+4. 产物：`dist\SSHClient.exe`（单文件，约 50-60 MB，可拷给任何人直接双击运行）
+
+**手动方式：**
+
+```bat
+python -m venv venv
+venv\Scripts\activate
+pip install -r requirements.txt
+pyinstaller build.spec --clean --noconfirm
+```
+
+## 🚀 在 Linux/macOS 上开发
+
+```bash
+./build.sh        # 一键打包当前平台二进制
+python main.py    # 直接开发运行
+```
+
+## 🧪 测试
+
+```bash
+source venv/bin/activate
+python test_core.py   # 核心模块 smoke test（无网络依赖）
+python test_ui.py     # UI 组件加载测试（offscreen 渲染）
+python test_e2e.py    # 端到端测试（需本机或可访问的 sshd）
+```
+
+## 🎮 使用说明
+
+### 1. 添加主机
+左侧 **➕ 新增主机**，填主机名/IP、端口、用户名、密码（可选私钥文件）。
+
+### 2. 连接
+选中主机 → **🔌 连接**。状态指示器变绿后即可使用。
+
+### 3. 终端
+**⌨ 终端** Tab 直接输入命令回车执行。常用命令（pwd / df / free / top / netstat）有快捷按钮。
+
+### 4. 文件浏览
+**📁 文件** Tab 双击目录进入，双击文件直接下载。可拖入 / 上传任意文件。
+
+### 5. 监控
+**📊 监控** Tab 点击 **开始监控**，指标会按设定间隔刷新。CPU/内存用大字突出，磁盘用进度条，网络显示当前速率。
+
+### 6. AI Agent
+1. 先点 **⚙ AI 设置**，选择预设（OpenAI/DeepSeek/Kimi/通义千问/Ollama）或自定义填 API Key
+2. 回到 **🤖 AI Agent** Tab，用自然语言提问：
+   - "帮我看 CPU 为什么这么高"
+   - "找出 /var/log 下最大的 10 个文件"
+   - "重启 nginx 服务"
+3. AI 会自动调用工具（执行命令、查指标等）并给出结论
+
+> **安全提示**：AI Agent 可以执行任意命令，请使用只读权限的 API Key，或在 prompt 中限定危险操作前需确认。
+
+## 🔌 支持的 AI 提供商
+
+| 预设 | Base URL | 模型 |
+| --- | --- | --- |
+| OpenAI | `https://api.openai.com/v1` | gpt-4o-mini |
+| DeepSeek | `https://api.deepseek.com/v1` | deepseek-chat |
+| Moonshot Kimi | `https://api.moonshot.cn/v1` | moonshot-v1-8k |
+| 通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | qwen-turbo |
+| 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` | glm-4-flash |
+| Ollama (本地) | `http://127.0.0.1:11434/v1` | qwen2.5:7b |
+| 自定义 | - | 任意 OpenAI 兼容端点 |
+
+## 📂 项目结构
+
+```
+sshclient/
+├── main.py                # 入口
+├── requirements.txt       # 依赖
+├── build.spec             # PyInstaller 打包配置
+├── build_windows.bat      # Windows 一键打包
+├── build.sh               # Linux/macOS 打包
+├── core/                  # 业务逻辑
+│   ├── ssh_client.py      # SSH 连接 + SFTP
+│   ├── monitor.py         # 远程系统监控
+│   ├── ai_agent.py        # AI Agent (OpenAI 兼容)
+│   └── manager.py         # 多主机管理 + 配置持久化
+├── ui/                    # PyQt5 界面
+│   ├── main_window.py     # 主窗口
+│   ├── widgets.py         # FileBrowser / MonitorPanel / AIChatPanel
+│   ├── host_dialog.py     # 主机编辑对话框
+│   ├── config_dialog.py   # AI 设置对话框
+│   └── workers.py         # 后台线程
+└── test_*.py              # 测试脚本
+```
+
+## 🔧 故障排查
+
+| 问题 | 解决 |
+| --- | --- |
+| `python` 不识别 | 安装 Python 时勾选 "Add Python to PATH" |
+| 打包失败 `ModuleNotFoundError` | 用 `pip install <module>` 后重新打包 |
+| exe 启动黑窗闪过 | 已用 `console=False`，如还出现请检查杀毒软件 |
+| SSH 连接超时 | 检查防火墙、22 端口、目标主机 sshd 是否运行 |
+| AI 设置测试连接失败 | 检查 API Key 是否正确、Base URL 是否可访问、代理设置 |
+
+## 📄 License
+
+MIT