ab5bbff6f7
- Translated README.md to Chinese, providing a comprehensive overview of LocalAgent's functionalities and usage. - Enhanced feature descriptions, including intent recognition, requirement clarification, code generation, and task management. - Updated installation and configuration instructions to reflect localized content and improve clarity for Chinese-speaking users. - Improved project structure documentation for better understanding of the application layout.
265 lines
9.1 KiB
Markdown
265 lines
9.1 KiB
Markdown
# 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) - 优秀的开源大语言模型
|