virtualbox_client/README.md

# VirtualBox Client

**VirtualBox 虚拟机自动化管理工具** — 通过 SSH 和 VirtualBox SDK 实现对 Ubuntu 20.04 虚拟机的全生命周期管理，支持 AI 智能任务执行、文件传输、脚本部署和图形化管理。

---

## ✨ 功能特性

- 🖥️ **虚拟机管理** — 启动、关闭、状态检测（VirtualBox SDK）
- 🔌 **纯 SSH 模式** — 不依赖 VirtualBox，直接通过 SSH 管理远程服务器
- 🤖 **AI 智能代理** — 接入大语言模型（OpenAI API），通过自然语言描述自动执行运维任务
- 📁 **文件传输** — 支持上传/下载文件、上传整个文件夹
- 📂 **工作区浏览器** — 树形文件管理器，支持浏览、新建、重命名、复制、删除、下载文件夹（zip 打包）
- ⚡ **脚本执行** — 上传并执行 Shell 脚本，自动区分部署脚本（sudo）和普通脚本
- 🎨 **图形界面** — 基于 PySide6 构建的现代化暗色主题 GUI
- 📋 **日志面板** — 带等级标识的彩色日志输出，支持自动滚动

---

## 📦 系统要求

| 依赖           | 说明                     |
| -------------- | ------------------------ |
| Python         | >= 3.14                  |
| VirtualBox     | 含 VirtualBox SDK（可选） |
| 操作系统       | Windows（主控端）        |
| 目标虚拟机     | Ubuntu 20.04（受控端）   |

---

## 🚀 快速开始

### 1. 安装依赖

```powershell
# 同步 Python 依赖
uv sync

# 安装 VirtualBox SDK（仅 VirtualBox 模式需要）
# 确保已安装 VirtualBox，找到 sdk 路径后执行：
cd ./sdk/installer/python/
uv run ./vboxapisetup.py install
```

> **📥 VirtualBox SDK 下载**
>
> 如果项目中尚未包含 SDK，请先下载 VirtualBox SDK 并解压到项目目录：
>
> ```powershell
> # 下载 VirtualBox SDK 7.2.8
> curl -L https://download.virtualbox.org/virtualbox/7.2.8/VirtualBoxSDK-7.2.8-173730.zip -o VirtualBoxSDK.zip
> # 解压到项目根目录
> tar -xf VirtualBoxSDK.zip
> ```
>
> SDK 目录结构应包含 `sdk/installer/python/vboxapisetup.py`。
>
> *注意：SDK 版本需与本地安装的 VirtualBox 版本匹配。*

### 2. 配置环境变量

复制 `.env.example` 为 `.env`（或直接在 GUI 中填写）：

```env
# 虚拟机配置
VM_NAME=ubuntu20.04
VM_SSH_HOST=127.0.0.1
VM_SSH_PORT=2222
VM_SSH_USER=your_username
VM_SSH_PASS=your_password

# 大模型配置（AI 代理模式需要）
LLM_API_KEY=sk-your-api-key
LLM_BASE_URL=https://api.openai.com
LLM_MODEL=gpt-4o
```

### 3. 启动方式

#### 🖥️ 图形界面

```powershell
uv run gui
```

![GUI Screenshot](docs/images/gui.png) *(screenshot placeholder)*

#### ⌨️ 命令行示例

```powershell
uv run example
```

---

## 📖 使用指南

### 配置面板

左侧配置面板包含三个区域：

1. **运行模式** — 切换「纯 SSH 模式」或「VirtualBox 模式」
2. **虚拟机配置** — SSH 连接信息（主机、端口、用户名、密码）
3. **大模型配置** — AI 代理的 API Key、Base URL 和模型名称

### 任务执行面板

在「任务执行」Tab 中，输入自然语言描述，AI 代理将自动解析并执行：

```
在 /home/user/myproject 下有一个 "myproject" 项目，
请安装 nginx 并确认服务状态
```

系统会自动：
1. 启动虚拟机（VirtualBox 模式）
2. 连接 SSH
3. 调用 LLM 生成执行计划
4. 逐步执行命令并反馈日志
5. 任务完成后询问是否关闭虚拟机

### 文件传输

在「文件传输」Tab 中：
- **上传** — 选择本地文件，指定远程路径，点击上传
- **下载** — 输入远程路径，选择本地保存位置，点击下载

### 脚本执行

在「Script」Tab 中：
1. 点击「Browse」选择本地的 `.sh` 脚本文件
2. 点击「Upload and Execute Script」
3. 脚本会自动上传到 `/tmp/`，执行完成后下载日志并清理临时文件
4. 以 `deploy_` 开头的脚本自动使用 `sudo` 权限执行

### 工作区浏览器

在「工作区」Tab 中，可以像本地文件管理器一样操作远程文件：
- **双击文件夹** — 懒加载展开子目录
- **单击文件** — 显示文件详情
- **右键菜单** — 重命名、复制、删除、下载
- **工具栏** — 上传文件、上传文件夹、新建文件夹、回到根目录

---

## 🛠️ 脚本开发

### 添加新脚本

在 `src/virtualbox_client/scripts/` 下创建 Python 文件：

```python
# src/virtualbox_client/scripts/my_script.py

def run():
    print("Hello from my script!")
```

在 `pyproject.toml` 中注册：

```toml
[project.scripts]
my-script = "virtualbox_client.scripts.my_script:run"
```

重新构建并执行：

```powershell
uv sync
uv run my-script
```

### 命令式脚本执行

```powershell
# 直接通过命令行运行脚本模块
uv run -m virtualbox_client.scripts.my_script
```

---

## 📁 项目结构

```
virtualbox_client/
├── src/virtualbox_client/
│   ├── __init__.py
│   ├── gui.py                    # PySide6 图形界面
│   ├── scripts/
│   │   ├── __init__.py
│   │   ├── agent_task.py         # AI 代理任务执行
│   │   ├── example.py            # 使用示例
│   │   └── run_script.py         # 脚本运行器
│   └── utils/
│       ├── __init__.py
│       ├── ssh_manager.py        # 纯 SSH 管理器
│       ├── vbox_ssh_manager.py   # VirtualBox + SSH 管理器
│       └── vm_agent.py           # AI 代理核心
├── resources/
│   ├── chongming_dev.sh
│   ├── deploy_docker.sh
│   ├── deploy_git.sh
│   ├── deploy_nvm.sh
│   └── deploy_uv.sh
├── scripts/
│   ├── add_script_runner.py
│   ├── add_script_tab.py
│   ├── check_syntax.py
│   ├── clean_pycache.py
│   ├── code_content.py
│   ├── fix_paths.py
│   └── fix_upload_folder.py
├── docs/
│   ├── docker使用手册.md
│   ├── git使用手册.md
│   ├── nvm使用文档.md
│   └── uv使用文档.md
├── .env.example                  # 环境变量模板
├── .gitignore
├── .python-version
├── gui.spec                      # PyInstaller 打包配置
├── pyproject.toml                # 项目配置与依赖
└── README.md
```

---

## 🧩 技术架构

### 后端

- **VirtualBox SDK** (`vboxapi`) — 通过 Windows COM 接口管理虚拟机生命周期
- **paramiko** — SSH 连接与远程命令执行
- **openai** — 大语言模型 API 调用（AI 代理模式）
- **pywin32** — Windows COM 互操作

### 前端

- **PySide6** — Qt6 的 Python 绑定，提供现代化 GUI
- **QThread** — 后台线程管理，避免 UI 阻塞
- **QTreeWidget** — 带懒加载的远程文件浏览器

### 工作模式

```
┌─────────────────────────────────────────┐
│           VirtualBox Client             │
├─────────────────┬───────────────────────┤
│ VirtualBox 模式 │    纯 SSH 模式        │
│                 │                       │
│  VirtualBox     │     SSH               │
│  SDK (COM)      │     Manager           │
│     ↓           │     ↓                 │
│  VBoxSSHManager │  SSHManager           │
│     ↓           │     ↓                 │
│  Ubuntu VM      │  远程服务器            │
└─────────────────┴───────────────────────┘
```

---

## 🐳 部署与打包

### 使用 PyInstaller 打包为可执行文件

```powershell
uv run pyinstaller gui.spec
```

打包后的可执行文件位于 `dist/` 目录。

---

## ⚙️ 环境搭建详情

| 命令                                      | 说明                          |
| ----------------------------------------- | ----------------------------- |
| `uv sync`                                 | 同步所有 Python 依赖           |
| `uv run ./sdk/installer/python/vboxapisetup.py install` | 安装 VirtualBox SDK |
| `uv run gui`                              | 启动图形界面                   |
| `uv run example`                          | 运行命令行示例                 |
| `uv run agent-task`                       | 运行 AI 代理任务               |
| `uv run run-script`                       | 运行脚本                      |
| `uv run pyinstaller gui.spec`             | 打包为 EXE                    |

---

## 📝 文档

详细使用文档请参考 `docs/` 目录：

- [Docker 使用手册](docs/docker使用手册.md)
- [Git 使用手册](docs/git使用手册.md)
- [NVM 使用文档](docs/nvm使用文档.md)
- [UV 使用文档](docs/uv使用文档.md)

---

## 🔧 常见问题

**Q: 启动报错 `CoInitialize` 相关错误？**
A: 这是 Windows COM 初始化问题，通常出现在 VirtualBox 模式下。确保已正确安装 VirtualBox SDK。

**Q: SSH 连接失败？**
A: 检查目标虚拟机是否已启动、SSH 服务是否运行、端口转发是否配置正确（默认 2222）。

**Q: AI 代理无响应？**
A: 确保 API Key、Base URL 和模型名称配置正确，且网络可以访问 LLM 服务。

---

## 📄 许可证

本项目仅供学习和参考使用。