# QuickDeskAgent

**Repository Path**: Barryda/quick-desk-agent

## Basic Information

- **Project Name**: QuickDeskAgent
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-28
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QuickDesk Agent

AI 驱动的远程桌面助手。通过自然语言对话控制远程计算机。

QuickDesk Agent 是一个独立的 AI 代理，利用 [QuickDesk](https://github.com/aspect-home/QuickDesk) 的 MCP 服务器来查看、理解和操作远程桌面 —— 一切通过聊天界面完成。

## 功能特性

- **对话即控制** —— 用自然语言描述你的需求，AI 自动操作远程桌面
- **多模型支持** —— Claude、GPT-4o、DeepSeek、通义千问、Gemini、Ollama 及任意 OpenAI 兼容端点
- **40+ 远程桌面工具** —— 截图、OCR、点击、输入、拖拽、滚动、快捷键、剪贴板、主机端命令执行
- **流式响应** —— 实时 AI 输出，工具调用过程实时可视化
- **快捷操作** —— 常见任务一键预设（健康检查、故障诊断、安全审计）
- **对话历史** —— 持久化会话，支持上下文连续追问
- **视觉理解** —— 视觉模型可直接分析截图，更准确地理解屏幕内容

## 架构

```
┌──────────────────────────────────────────────┐
│  QuickDesk Agent                             │
│                                              │
│  ┌────────────┐  ┌──────────┐  ┌──────────┐ │
│  │ Chainlit   │  │ Pydantic │  │ FastMCP  │ │     ┌──────────────┐
│  │ 聊天 UI    │←→│ AI Agent │←→│ Client   │─┼────→│ QuickDesk    │
│  │ :18090     │  │ Loop     │  │ (HTTP)   │ │ MCP │ MCP Server   │
│  └────────────┘  └────┬─────┘  └──────────┘ │     │ :18080       │
│                       │                      │     └──────────────┘
│                  ┌────▼─────┐                │
│                  │ LLM APIs │                │
│                  │ Claude   │                │
│                  │ GPT-4o   │                │
│                  │ DeepSeek │                │
│                  │ Qwen     │                │
│                  │ Ollama   │                │
│                  └──────────┘                │
└──────────────────────────────────────────────┘
```

## 技术栈

| 组件 | 库 | 用途 |
|------|-----|------|
| Agent 框架 | [Pydantic AI](https://ai.pydantic.dev/) | 多模型 Agent 循环，类型安全的工具调用 |
| MCP 客户端 | [FastMCP](https://github.com/PrefectHQ/fastmcp) | 通过 HTTP 连接 QuickDesk MCP 服务器 |
| 聊天 UI | [Chainlit](https://github.com/Chainlit/chainlit) | 生产级对话式 AI 界面 |
| LLM 提供商 | Pydantic AI 原生 SDK | Anthropic、OpenAI、Google、Ollama 等 |
| 打包 | PyInstaller | Windows 和 macOS 单文件可执行程序 |

## 前置条件

- **QuickDesk** 已运行并开启 MCP HTTP 模式（端口 18080）
- **Python 3.11+**（仅开发时需要）
- 至少配置一个 LLM API Key（或本地 Ollama 实例）

## 快速开始

### 开发模式

```bash
# 克隆仓库
git clone https://github.com/aspect-home/QuickDeskAgent.git
cd QuickDeskAgent

# 安装依赖
pip install -e ".[dev]"

# 配置
cp .env.example .env
# 编辑 .env，填入 API Key 和 QuickDesk MCP 地址

# 运行
chainlit run app.py
```

### 配合 QuickDesk 使用

QuickDesk Agent 随 QuickDesk 安装程序一起分发。当 QuickDesk 启用 AI Agent 后：

1. QuickDesk 启动 MCP HTTP 服务（端口 18080）
2. QuickDesk 启动 Agent 进程
3. Agent 连接 MCP 服务器，自动发现可用工具
4. 系统浏览器打开聊天界面 `http://localhost:18090`
5. 开始聊天，控制你的远程桌面

## 配置

### 环境变量

```bash
# QuickDesk MCP 服务器
QUICKDESK_MCP_URL=http://localhost:18080/mcp

# LLM 提供商（配置一个或多个）
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
DEEPSEEK_API_KEY=sk-...
GOOGLE_API_KEY=...
QWEN_API_KEY=sk-...

# Ollama（本地模型，无需 Key）
OLLAMA_BASE_URL=http://localhost:11434

# 默认模型
DEFAULT_MODEL=claude-sonnet-4-6

# Agent 设置
MAX_TOOL_CALLS_PER_TURN=20
AGENT_TIMEOUT_SECONDS=300
```

### 支持的模型

| 提供商 | 模型 | 视觉能力 | 工具调用 |
|--------|------|---------|---------|
| Anthropic | Claude Opus 4、Sonnet 4、Haiku 3.5 | 支持 | 支持 |
| OpenAI | GPT-4o、GPT-4o-mini、o1、o3 | 支持 | 支持 |
| DeepSeek | DeepSeek-V3、DeepSeek-R1 | 不支持 | 支持 |
| Google | Gemini 2.0 Flash、Gemini 2.0 Pro | 支持 | 支持 |
| 通义千问 | Qwen-Max、Qwen-Plus、Qwen-Turbo | 支持 | 支持 |
| Ollama | Llama 3、Qwen2、Mistral 等 | 视模型而定 | 视模型而定 |

## 项目结构

```
QuickDeskAgent/
├── app.py                  # Chainlit 入口
├── pyproject.toml          # 项目配置和依赖
├── .env.example            # 环境变量模板
├── src/
│   └── quickdesk_agent/
│       ├── __init__.py
│       ├── agent.py        # Pydantic AI Agent 定义和循环
│       ├── providers.py    # LLM 提供商配置
│       ├── mcp_client.py   # FastMCP 客户端连接 QuickDesk
│       ├── tools.py        # 工具注册和执行
│       ├── prompts.py      # System Prompt 模板
│       ├── session.py      # 会话管理
│       └── config.py       # 设置和凭证管理
├── docs/
│   ├── requirements.md     # 产品需求文档
│   ├── architecture.md     # 系统架构文档
│   └── ui-design.md        # UI 设计文档
├── tests/
│   ├── test_agent.py
│   ├── test_mcp_client.py
│   └── test_providers.py
└── build/
    ├── build_windows.py    # PyInstaller 打包脚本（Windows）
    └── build_macos.py      # PyInstaller 打包脚本（macOS）
```

## 开发

```bash
# 运行测试
pytest

# 类型检查
mypy src/

# 代码检查
ruff check src/

# 代码格式化
ruff format src/
```

## 许可证

专有软件，保留所有权利。