From ab5bbff6f7cf526ff182891e8d28d5082e52d2fd Mon Sep 17 00:00:00 2001 From: Mimikko-zeus Date: Wed, 7 Jan 2026 12:57:37 +0800 Subject: [PATCH] feat: update README.md for localization and feature enhancement - 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. --- README.md | 321 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 193 insertions(+), 128 deletions(-) diff --git a/README.md b/README.md index 0588614..810ebc1 100644 --- a/README.md +++ b/README.md @@ -1,199 +1,264 @@ -# LocalAgent - Windows Local AI Execution Assistant +# LocalAgent - 本地 AI 执行助手 -A Windows-based local AI assistant that can understand natural language commands and execute file processing tasks safely in a sandboxed environment. +

+ Python + Platform + License +

-## Features +LocalAgent 是一个基于大语言模型的本地 AI 助手，能够理解自然语言指令，自动生成并执行 Python 代码来完成文件处理任务。所有代码在本地沙箱环境中安全执行。 -- **Intent Recognition**: Automatically distinguishes between chat conversations and execution tasks -- **Requirement Clarification**: Interactive Q&A to clarify vague requirements before code generation -- **Code Generation**: Generates Python code based on structured requirements -- **Safety Checks**: Multi-layer security with static analysis and LLM review -- **Sandbox Execution**: Runs generated code in an isolated environment -- **Task History**: Records all executed tasks with selective deletion -- **Streaming Responses**: Real-time display of LLM responses -- **Settings UI**: Easy configuration of API and models -- **Code Reuse**: Automatically finds and reuses successful code for similar tasks -- **Auto Retry**: AI-powered code fixing for failed tasks -- **Multi-Model Support**: Different models for intent recognition, chat, and code generation +## ✨ 功能特性 -## Project Structure +### 🤖 智能对话 +- **意图识别**：自动区分闲聊对话、操作指导和执行任务 +- **上下文记忆**：支持多轮对话，记住之前的对话内容 +- **Markdown 渲染**：支持标题、列表、代码块、链接等格式 +- **环境感知**：根据用户操作系统给出针对性建议 + +### 📝 需求澄清 +- **智能检测**：自动识别模糊或不完整的需求 +- **交互式问答**：通过单选、多选、输入框收集缺失信息 +- **效果预览**：颜色选择器、位置预览等可视化辅助 + +### 💻 代码生成与执行 +- **自动生成**：根据结构化需求生成 Python 代码 +- **多层安全检查**：静态规则检查 + LLM 语义审查 +- **沙箱执行**：隔离环境运行，保护系统安全 +- **执行日志**：完整记录每次执行的输入输出 + +### 📚 任务管理 +- **历史记录**：保存所有执行过的任务 +- **代码复用**：自动匹配相似任务，复用成功代码 +- **失败重试**：AI 自动分析错误并修复代码 + +## 🏗️ 项目结构 ``` LocalAgent/ -├── app/ # Main application -│ └── agent.py # Core application class -├── llm/ # LLM integration -│ ├── client.py # API client with retry support -│ └── prompts.py # Prompt templates -├── intent/ # Intent classification -│ ├── classifier.py # Intent classifier -│ └── labels.py # Intent labels -├── safety/ # Security checks -│ ├── rule_checker.py # Static rule checker -│ └── llm_reviewer.py # LLM-based code review -├── executor/ # Code execution -│ └── sandbox_runner.py # Sandbox executor -├── history/ # Task history -│ └── manager.py # History manager -├── ui/ # User interface -│ ├── chat_view.py # Chat interface -│ ├── clarify_view.py # Requirement clarification view -│ ├── task_guide_view.py # Task confirmation view -│ ├── history_view.py # History view with Markdown support -│ └── settings_view.py # Settings configuration view -├── tests/ # Unit tests -├── workspace/ # Working directory (auto-created) -│ ├── input/ # Input files -│ ├── output/ # Output files -│ ├── codes/ # Generated code -│ └── logs/ # Execution logs -├── main.py # Entry point -├── requirements.txt # Dependencies -└── .env.example # Configuration template +├── 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 # 配置文件 ``` -## Installation +## 🚀 快速开始 -### Prerequisites +### 环境要求 -- Python 3.10+ -- Windows OS -- SiliconFlow API Key ([Get one here](https://siliconflow.cn)) +- **Python**: 3.10 或更高版本 +- **操作系统**: Windows 10/11 +- **API Key**: SiliconFlow API Key（[点击获取](https://siliconflow.cn)） -### Setup +### 安装步骤 -1. **Clone the repository** +1. **克隆项目** ```bash git clone cd LocalAgent ``` -2. **Create virtual environment** (recommended using Anaconda) +2. **创建虚拟环境**（推荐使用 Anaconda） ```bash conda create -n localagent python=3.10 conda activate localagent ``` -3. **Install dependencies** +3. **安装依赖** ```bash pip install -r requirements.txt ``` -4. **Configure environment** +4. **配置 API Key** ```bash - cp .env.example .env - # Edit .env and add your API key + # 复制配置模板 + copy .env.example .env + + # 编辑 .env 文件，填入你的 API Key + # LLM_API_KEY=sk-xxxxx ``` -5. **Run the application** +5. **运行程序** ```bash python main.py ``` -## Configuration +## ⚙️ 配置说明 -Edit `.env` file with your settings (or use the Settings UI in the app): +在 `.env` 文件中配置（也可以在应用内的设置界面修改）： ```env -# SiliconFlow API Configuration +# API 配置 LLM_API_URL=https://api.siliconflow.cn/v1/chat/completions -LLM_API_KEY=your_api_key_here +LLM_API_KEY=你的API密钥 -# Model Configuration -# Intent recognition model (small model recommended for speed) +# 模型配置 +# 意图识别模型（推荐小模型，速度快） INTENT_MODEL_NAME=Qwen/Qwen2.5-7B-Instruct -# Chat model (medium model recommended for conversation) +# 对话模型（推荐中等模型，平衡速度和质量） CHAT_MODEL_NAME=Qwen/Qwen2.5-32B-Instruct -# Code generation model (large model recommended for quality) +# 代码生成模型（推荐大模型，质量高） GENERATION_MODEL_NAME=Qwen/Qwen2.5-72B-Instruct ``` -## Usage +### 推荐模型配置 -### Chat Mode -Simply type questions or have conversations: -- "What is Python?" -- "Explain machine learning" +| 用途 | 推荐模型 | 说明 | +|------|---------|------| +| 意图识别 | Qwen2.5-7B | 快速响应，节省 token | +| 对话/指导 | Qwen2.5-32B | 平衡速度和质量 | +| 代码生成 | Qwen2.5-72B | 高质量代码生成 | -### Execution Mode -Describe file processing tasks: -- "Copy all files from input to output" -- "Convert all PNG images to JPG format" -- "Rename files with today's date prefix" +## 📖 使用指南 -### Workflow -1. Place input files in `workspace/input/` -2. Describe your task in the chat -3. **If the requirement is vague**, the system will ask clarifying questions: - - Radio buttons for single-choice options (e.g., watermark type) - - Checkboxes for multi-choice options (e.g., watermark positions) - - Input fields for custom values (e.g., watermark text, opacity) -4. Review the execution plan and generated code -5. Click "Execute" to run -6. Find results in `workspace/output/` +### 三种工作模式 -### Requirement Clarification Example +#### 1. 对话模式 💬 +直接提问或闲聊： +- "Python 是什么？" +- "解释一下机器学习" +- "今天天气怎么样" -When you input a vague request like "Add watermark to images", the system will: +#### 2. 操作指导模式 📋 +询问无法通过代码完成的操作： +- "怎么修改浏览器主题？" +- "如何设置 Windows 开机启动项？" +- "怎么下载 QQ？" -1. **Check completeness** - Detect missing information -2. **Ask questions** - Present interactive options: - - Watermark type: Text / Image (radio) - - Position: Top-left / Top-right / Bottom-left / Bottom-right / Center (checkbox) - - Text content: [input field] - - Opacity: [input field with default 50%] -3. **Structure requirement** - Convert answers into a complete specification -4. **Generate code** - Create code based on the structured requirement +#### 3. 执行模式 ⚡ +描述文件处理任务： +- "把 input 里的图片都转成 PNG 格式" +- "给所有图片添加水印" +- "把文件按日期重命名" -## Security +### 执行任务流程 -LocalAgent implements multiple security layers: +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ 输入需求 │ ──▶ │ 意图识别 │ ──▶ │ 需求完整？ │ +└─────────────┘ └─────────────┘ └──────┬──────┘ + │ + ┌──────────────────────────┼──────────────────────────┐ + │ 否 │ 是 │ + ▼ │ ▼ + ┌─────────────┐ │ ┌─────────────┐ + │ 需求澄清 │ ────────────────────┘ │ 生成代码 │ + └─────────────┘ └──────┬──────┘ + │ + ▼ +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ 查看结果 │ ◀── │ 沙箱执行 │ ◀── │ 确认执行 │ ◀── │ 安全检查 │ +└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ +``` -1. **Hard Rules** - Blocks dangerous operations: - - Network modules (socket, subprocess) - - Code execution (eval, exec) - - System commands (os.system, os.popen) +### 需求澄清示例 -2. **Soft Rules** - Warns about sensitive operations: - - File deletion - - Network requests (requests, urllib) +当输入模糊需求如 "给图片加水印" 时，系统会： -3. **LLM Review** - Semantic analysis of generated code +1. **检测缺失信息** - 水印类型、位置、内容等 +2. **交互式询问** - 提供可视化选项： + - 水印类型：文字 / 图片（单选） + - 位置：左上 / 右上 / 左下 / 右下 / 居中（多选 + 预览） + - 文字内容：[输入框] + - 透明度：[输入框，默认 50%] +3. **结构化需求** - 整合所有信息 +4. **生成代码** - 根据完整需求生成代码 -4. **Sandbox Execution** - Isolated subprocess with limited permissions +## 🔒 安全机制 -## Testing +LocalAgent 实现了多层安全保护： -Run unit tests: +### 硬规则（直接拦截） +- ❌ 网络模块：`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 ``` -## Supported File Operations +当前测试覆盖： +- ✅ 意图分类器测试 +- ✅ 安全规则检查测试 +- ✅ 历史记录管理测试 -The generated code can use these libraries: +## 🤝 贡献 -**Standard Library:** -- os, sys, pathlib - Path operations -- shutil - File copy/move -- json, csv - Data formats -- zipfile, tarfile - Compression -- And more... +欢迎提交 Issue 和 Pull Request！ -**Third-party Libraries:** -- Pillow - Image processing -- openpyxl - Excel files -- python-docx - Word documents -- PyPDF2 - PDF files -- chardet - Encoding detection - -## License +## 📄 许可证 MIT License -## Contributing - -Contributions are welcome! Please feel free to submit issues and pull requests. +## 🙏 致谢 +- [SiliconFlow](https://siliconflow.cn) - 提供 LLM API 服务 +- [Qwen](https://github.com/QwenLM/Qwen) - 优秀的开源大语言模型