LocalAgent - 本地 AI 执行助手

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（点击获取）

安装步骤

1. 克隆项目

   git clone <repository-url>
   cd LocalAgent
   

2. 创建虚拟环境（推荐使用 Anaconda）

   conda create -n localagent python=3.10
   conda activate localagent
   

3. 安装依赖

   pip install -r requirements.txt
   

4. 配置 API Key

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

5. 运行程序

   python main.py
   

⚙️ 配置说明

在 .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	文件编码检测

🧪 测试

运行单元测试：

python -m pytest tests/ -v

当前测试覆盖：

• ✅ 意图分类器测试
• ✅ 安全规则检查测试
• ✅ 历史记录管理测试

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🙏 致谢

• SiliconFlow - 提供 LLM API 服务
• Qwen - 优秀的开源大语言模型