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.
2026-01-07 12:57:37 +08:00
parent 1843a74d16
commit ab5bbff6f7
1 changed files with 193 additions and 128 deletions
--- 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.
+<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>

-## 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 <repository-url>
   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) - 优秀的开源大语言模型