# LocalAgent - 本地 AI 执行助手

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.10+-blue.svg" alt="Python">
  <img src="https://img.shields.io/badge/Platform-Windows-lightgrey.svg" alt="Platform">
  <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
</p>

LocalAgent 是一个基于大语言模型的本地 AI 助手，能够理解自然语言指令，自动生成并执行 Python 代码来完成文件处理任务。所有代码在本地沙箱环境中安全执行。

## ✨ 功能特性

### 🤖 智能对话
- **意图识别**：自动区分闲聊对话、操作指导和执行任务
- **上下文记忆**：支持多轮对话，记住之前的对话内容
- **Markdown 渲染**：支持标题、列表、代码块、链接等格式
- **环境感知**：根据用户操作系统给出针对性建议

### 📝 需求澄清
- **智能检测**：自动识别模糊或不完整的需求
- **交互式问答**：通过单选、多选、输入框收集缺失信息
- **效果预览**：颜色选择器、位置预览等可视化辅助

### 💻 代码生成与执行
- **自动生成**：根据结构化需求生成 Python 代码
- **多层安全检查**：静态规则检查 + LLM 语义审查
- **沙箱执行**：隔离环境运行，保护系统安全
- **执行日志**：完整记录每次执行的输入输出

### 📚 任务管理
- **历史记录**：保存所有执行过的任务
- **代码复用**：自动匹配相似任务，复用成功代码
- **失败重试**：AI 自动分析错误并修复代码

## 🏗️ 项目结构

```
LocalAgent/
├── app/                    # 主应用
│   └── agent.py           # 核心应用类，管理 UI 和工作流
├── llm/                    # LLM 集成
│   ├── client.py          # API 客户端（支持流式传输和重试）
│   └── prompts.py         # Prompt 模板
├── intent/                 # 意图分类
│   ├── classifier.py      # 意图分类器
│   └── labels.py          # 意图标签定义
├── safety/                 # 安全检查
│   ├── rule_checker.py    # 静态规则检查器
│   └── llm_reviewer.py    # LLM 代码审查
├── executor/               # 代码执行
│   └── sandbox_runner.py  # 沙箱执行器
├── history/                # 历史管理
│   └── manager.py         # 历史记录管理器
├── ui/                     # 用户界面
│   ├── chat_view.py       # 聊天界面（支持 Markdown）
│   ├── clarify_view.py    # 需求澄清界面
│   ├── task_guide_view.py # 任务确认界面
│   ├── history_view.py    # 历史记录界面
│   └── settings_view.py   # 设置界面
├── tests/                  # 单元测试
├── workspace/              # 工作目录（自动创建）
│   ├── input/             # 输入文件
│   ├── output/            # 输出文件
│   ├── codes/             # 生成的代码
│   └── logs/              # 执行日志
├── main.py                # 程序入口
├── requirements.txt       # 依赖列表
└── .env                   # 配置文件
```

## 🚀 快速开始

### 环境要求

- **Python**: 3.10 或更高版本
- **操作系统**: Windows 10/11
- **API Key**: SiliconFlow API Key（[点击获取](https://siliconflow.cn)）

### 安装步骤

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd LocalAgent
   ```

2. **创建虚拟环境**（推荐使用 Anaconda）
   ```bash
   conda create -n localagent python=3.10
   conda activate localagent
   ```

3. **安装依赖**
   ```bash
   pip install -r requirements.txt
   ```

4. **配置 API Key**
   ```bash
   # 复制配置模板
   copy .env.example .env
   
   # 编辑 .env 文件，填入你的 API Key
   # LLM_API_KEY=sk-xxxxx
   ```

5. **运行程序**
   ```bash
   python main.py
   ```

## ⚙️ 配置说明

在 `.env` 文件中配置（也可以在应用内的设置界面修改）：

```env
# API 配置
LLM_API_URL=https://api.siliconflow.cn/v1/chat/completions
LLM_API_KEY=你的API密钥

# 模型配置
# 意图识别模型（推荐小模型，速度快）
INTENT_MODEL_NAME=Qwen/Qwen2.5-7B-Instruct

# 对话模型（推荐中等模型，平衡速度和质量）
CHAT_MODEL_NAME=Qwen/Qwen2.5-32B-Instruct

# 代码生成模型（推荐大模型，质量高）
GENERATION_MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
```

### 推荐模型配置

| 用途 | 推荐模型 | 说明 |
|------|---------|------|
| 意图识别 | Qwen2.5-7B | 快速响应，节省 token |
| 对话/指导 | Qwen2.5-32B | 平衡速度和质量 |
| 代码生成 | Qwen2.5-72B | 高质量代码生成 |

## 📖 使用指南

### 三种工作模式

#### 1. 对话模式 💬
直接提问或闲聊：
- "Python 是什么？"
- "解释一下机器学习"
- "今天天气怎么样"

#### 2. 操作指导模式 📋
询问无法通过代码完成的操作：
- "怎么修改浏览器主题？"
- "如何设置 Windows 开机启动项？"
- "怎么下载 QQ？"

#### 3. 执行模式 ⚡
描述文件处理任务：
- "把 input 里的图片都转成 PNG 格式"
- "给所有图片添加水印"
- "把文件按日期重命名"

### 执行任务流程

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  输入需求   │ ──▶ │  意图识别   │ ──▶ │ 需求完整？  │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                    ┌──────────────────────────┼──────────────────────────┐
                    │ 否                       │                     是   │
                    ▼                          │                          ▼
           ┌─────────────┐                     │                 ┌─────────────┐
           │  需求澄清   │ ────────────────────┘                 │  生成代码   │
           └─────────────┘                                       └──────┬──────┘
                                                                        │
                                                                        ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  查看结果   │ ◀── │  沙箱执行   │ ◀── │  确认执行   │ ◀── │  安全检查   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
```

### 需求澄清示例

当输入模糊需求如 "给图片加水印" 时，系统会：

1. **检测缺失信息** - 水印类型、位置、内容等
2. **交互式询问** - 提供可视化选项：
   - 水印类型：文字 / 图片（单选）
   - 位置：左上 / 右上 / 左下 / 右下 / 居中（多选 + 预览）
   - 文字内容：[输入框]
   - 透明度：[输入框，默认 50%]
3. **结构化需求** - 整合所有信息
4. **生成代码** - 根据完整需求生成代码

## 🔒 安全机制

LocalAgent 实现了多层安全保护：

### 硬规则（直接拦截）
- ❌ 网络模块：`socket`, `subprocess`
- ❌ 代码执行：`eval()`, `exec()`
- ❌ 系统命令：`os.system()`, `os.popen()`

### 软规则（警告提示）
- ⚠️ 文件删除：`os.remove()`, `shutil.rmtree()`
- ⚠️ 网络请求：`requests`, `urllib`

### LLM 审查
- 语义分析生成的代码
- 检查是否与用户意图一致
- 识别潜在的危险操作

### 沙箱执行
- 隔离的子进程环境
- 限制文件访问范围
- 完整的执行日志

## 📦 支持的文件操作

生成的代码可以使用以下库：

### 标准库
| 库 | 用途 |
|---|------|
| `os`, `pathlib` | 路径操作 |
| `shutil` | 文件复制/移动 |
| `json`, `csv` | 数据格式处理 |
| `zipfile`, `tarfile` | 压缩解压 |
| `datetime` | 日期时间处理 |
| `re` | 正则表达式 |

### 第三方库
| 库 | 用途 |
|---|------|
| `Pillow` | 图片处理（缩放、裁剪、水印等） |
| `openpyxl` | Excel 文件读写 |
| `python-docx` | Word 文档处理 |
| `PyPDF2` | PDF 文件处理 |
| `chardet` | 文件编码检测 |

## 🧪 测试

运行单元测试：
```bash
python -m pytest tests/ -v
```

当前测试覆盖：
- ✅ 意图分类器测试
- ✅ 安全规则检查测试
- ✅ 历史记录管理测试

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## 🙏 致谢

- [SiliconFlow](https://siliconflow.cn) - 提供 LLM API 服务
- [Qwen](https://github.com/QwenLM/Qwen) - 优秀的开源大语言模型