# Luckylin

**Repository Path**: fensl/luckylin

## Basic Information

- **Project Name**: Luckylin
- **Description**: 一个桌面ai助手
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-04
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Luckylin 智能桌面助手

```
                  /|
                 / |
                /__|______
               |  __  __  |
               | |  ||  | |
               | |__||__| |
               |  __  __()| 
               | |  ||  | |
               | |  ||  | |
               | |__||__| |
               |__________|
                  ^    ^
                 /|    |\
                / |    | \
               /  |    |  \
                  |    |
                  |    |
```

Luckylin 是一个基于Django和MCP（Model Context Protocol）服务的智能桌面助手系统，旨在提高用户的工作效率与openkylin用户体验。

## 功能特性

- **Django Web框架** - 提供现代化的Web界面
- **Qwen Agent集成** - 基于通义千问的智能对话能力
- **MCP服务支持** - 提供系统级操作封装，包括文件操作、应用管理、系统控制等
- **多工具集成** - 支持本地命令执行、音乐播放控制、Git操作、网络搜索等
- **跨平台兼容** - 支持Windows、Linux、macOS系统
- **RESTful API** - 提供HTTP接口供其他应用调用

## 项目结构

```
luckylin/
├── django_qwen_agent/              # Django Web应用
│   ├── agent_app/                 # 核心应用模块
│   │   ├── views.py               # 视图处理和API接口
│   │   ├── urls.py                # URL路由配置
│   │   └── utils.py               # 工具函数
│   ├── qwen_agent_project/        # Django项目配置
│   │   └── settings.py            # 项目设置
│   ├── templates/                  # HTML模板
│   │   └── index.html             # Web界面
│   ├── manage.py                   # Django管理脚本
│   └── start_server.py            # 服务器启动脚本
├── lucylin-mcp-server/            # MCP服务器
│   ├── src/luckylin_mcp_server/   # MCP服务器源码
│   │   ├── server.py              # MCP服务器主文件
│   │   ├── system_tools/          # 系统工具模块
│   │   ├── web_service/           # 网络服务模块
│   │   └── file_operation.py      # 文件操作模块
│   └── pyproject.toml             # 项目依赖配置
└── README.md                       # 项目说明文档
```

## 环境要求

- Python 3.8+ (推荐3.12+)
- pip (Python包管理工具)
- 现代浏览器 (用于访问Web界面)

## 依赖项说明

本项目包含两个主要组件，每个组件有其独立的依赖：

### Django Qwen Agent 依赖
- `django` - Web框架
- `qwen-agent` - 通义千问智能体库
- `mcp` - MCP协议支持
- `django-simple-ui` - 美化Django后台界面
- `django-mdeditor` - Markdown编辑器

### Luckylin MCP Server 依赖
- `mcp[cli]>=1.6.0` - MCP协议实现
- `httpx>=0.28.1` - HTTP客户端
- `requests>=2.30.0` - HTTP请求库
- `PyPDF2` - PDF文件处理
- `python-docx` - Word文档处理
- `pandas` - 数据分析
- `python-pptx` - PowerPoint文件处理
- `beautifulsoup4>=4.12.0` - HTML解析
- `lxml>=4.9.0` - XML/HTML解析器
- 其他文档处理库

## 安装与使用

### 1. 克隆项目
```bash
git clone <repository_url>
cd luckylin
```

### 2. 安装MCP服务器依赖
```bash
cd lucylin-mcp-server
pip install -r requirements.txt
```

### 3. 安装Django应用依赖
```bash
cd ../django_qwen_agent
pip install -r requirements.txt
```

或者使用根目录的requirements.txt一次性安装所有依赖（不推荐，推荐分别安装）：
```bash
cd ..
pip install -r requirements.txt
```

### 4. 配置环境

#### 4.1 配置Qwen Agent API密钥
编辑 `django_qwen_agent/agent_app/views.py` 文件，将第176行的API密钥替换为您自己的DashScope API密钥：
```python
api_key = 'your-api-key-here',  # 替换为实际的API密钥
```

#### 4.2 配置MCP服务器路径
Django应用已配置为使用本地MCP服务器，路径为：
`/media/fslong/data/01-Projects/luckylin/lucylin-mcp-server/src/luckylin_mcp_server/server.py`

如果您的项目路径不同，请修改 `django_qwen_agent/agent_app/views.py` 中第189行的路径。

### 5. 启动MCP服务器（可选）
通常MCP服务器会在Django应用调用时自动启动，您也可以手动启动：
```bash
cd lucylin-mcp-server
python src/luckylin_mcp_server/server.py
```

### 6. 启动Django应用
有两种方式启动Django应用：

#### 方式一：使用内置启动脚本（推荐）
```bash
cd django_qwen_agent
python start_server.py
```
应用将在 http://127.0.0.1:8181 启动

#### 方式二：使用Django标准命令
```bash
cd django_qwen_agent
python manage.py runserver 8181
```

### 7. 访问应用
打开浏览器访问 http://127.0.0.1:8181 即可使用Luckylin智能桌面助手。

## API接口说明

### 对话接口
- **地址**: `POST /chat/`
- **参数**: 
  ```json
  {
    "message": "用户消息内容"
  }
  ```
- **响应**:
  ```json
  {
    "response": "AI助手回复"
  }
  ```

### 数据管理接口

#### 添加数据
- **地址**: `POST /add_data/`
- **参数**:
  ```json
  {
    "title": "数据标题",
    "content": "数据内容（可选）"
  }
  ```

#### 查询数据
- **地址**: `POST /query_data/`
- **参数**:
  ```json
  {
    "id": "数据ID（可选，不提供则查询所有）"
  }
  ```

## MCP可用工具

MCP服务器提供以下工具供AI助手调用：

### 系统应用管理
- `launch_app` - 启动应用程序
- `launch_control_center_module` - 打开控制中心指定模块

### 系统状态与信息
- `get_system_status` - 获取系统整体状态
- `get_system_info` - 获取系统基本信息
- `get_cpu_info` - 获取CPU信息
- `get_memory_info` - 获取内存信息
- `get_disk_info` - 获取磁盘使用情况
- `get_network_info` - 获取网络信息

### 文件操作
- `open_file` - 打开文件
- `create_file` - 创建文件
- `create_folder` - 创建文件夹
- `list_dir` - 列出目录内容
- `read_document` - 读取文档内容
- `copy_file` - 复制文件
- `move_file` - 移动文件
- `rename_file` - 重命名文件
- `delete_file` - 删除文件
- `search_files` - 搜索文件
- `search_files_by_content` - 搜索文件内容

### Git工具
- `git_clone` - 克隆Git仓库
- `git_status` - 查看Git状态
- `git_pull` - 拉取远程代码
- `git_push` - 推送代码
- `git_add` - 添加文件到暂存区
- `git_commit` - 提交代码
- `git_merge` - 合并分支

### 网络工具
- `web_search` - 网络搜索
- `fetch_web_content` - 获取网页内容
- `download_file` - 下载文件

## 故障排除

### 常见问题

1. **MCP服务器连接失败**
   - 检查MCP服务器路径是否正确
   - 确保MCP服务器依赖已正确安装

2. **Qwen Agent API错误**
   - 检查API密钥是否有效
   - 确认网络连接正常

3. **Django应用启动失败**
   - 检查端口是否被占用
   - 确认所有依赖已正确安装

## 开发指南

### 添加自定义工具
1. 在 `lucylin-mcp-server/src/luckylin_mcp_server/server.py` 中添加新工具函数
2. 使用 `@mcp.tool()` 装饰器标记函数
3. 实现具体功能逻辑

### 扩展Django应用
1. 在 `django_qwen_agent/agent_app/views.py` 中添加新工具类
2. 继承 `BaseTool` 类
3. 在 `initialize_agent()` 函数中注册新工具

## 许可证

本项目采用 MIT 许可证。详情请参见 [LICENSE](LICENSE) 文件。

## 贡献指南

欢迎提交问题报告和合并请求。对于重大更改，请先开issue讨论您想要更改的内容。

## 联系方式

如有任何问题或建议，请通过以下方式联系我们：

- 提交 GitHub Issue
- 发送电子邮件至：[fslong@tju.edu.cn]

## 致谢

1. 感谢【猫粮】为本项目提供的素材
2. 感谢所有为这个项目做出贡献的开发者。

## 许可证

本项目采用 MIT 许可证。详情请参见 [LICENSE](LICENSE) 文件。

## 贡献指南

欢迎提交问题报告和合并请求。对于重大更改，请先开issue讨论您想要更改的内容。

## 联系方式

如有任何问题或建议，请通过以下方式联系我们：

- 提交 GitHub Issue
- 发送电子邮件至：[fslong@tju.edu.cn]

## 致谢

1. 感谢【猫粮】为本项目提供的素材
2. 感谢所有为这个项目做出贡献的开发者。