# PyClaw **Repository Path**: gdzsfun/pyclaw ## Basic Information - **Project Name**: PyClaw - **Description**: No description available - **Primary Language**: Python - **License**: GPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 6 - **Forks**: 1 - **Created**: 2026-03-04 - **Last Updated**: 2026-03-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # PyClaw-AI助手 一个基于 LLM 的智能助手 GUI 应用，支持插件化工具调用，可以实现文件操作、浏览器访问、代码执行等功能。 ## 功能特性 ### 🤖 核心功能 - **自然语言交互**：使用自然语言与 AI 助手对话 - **插件化架构**：支持动态加载插件，扩展功能 - **现代化 GUI**：基于 Tkinter 的现代化界面设计 - **插件管理**：支持导入、管理和开发自定义插件 ### 🔌 已实现插件 #### 1. 文件管理器 (File Manager) - ✅ 创建文件和文件夹 - ✅ 读取和写入文件 - ✅ 删除文件和文件夹 - ✅ 移动和复制文件 - ✅ 搜索文件（按名称和内容） - ✅ 获取文件信息 - ✅ 保存HTML文件（自动添加HTML结构） - ✅ 保存文本文件 #### 2. 浏览器控制器 (Browser Controller) - ✅ 打开网页 - ✅ 获取网页 HTML 内容 - ✅ 提取网页纯文本 - ✅ 检查 URL 状态 #### 3. 代码执行器 (Code Executor) - ✅ 执行 Python 代码 - ✅ 执行 Shell 命令 - ✅ 安全的工作区隔离 #### 4. 系统信息 (System Info) - ✅ 获取系统基本信息 - ✅ 查看 CPU 使用情况 - ✅ 查看内存使用情况 - ✅ 查看磁盘使用情况 - ✅ 查看运行中的进程 #### 5. 网络请求 (Network Request) - ✅ HTTP GET 请求 - ✅ HTTP POST 请求 - ✅ 自定义 HTTP 请求（支持所有方法） #### 6. 定时任务 (Schedule Timer) - ✅ 定时提醒（每隔指定时间弹出提醒） - ✅ 定时执行脚本（每隔指定时间执行脚本文件） - ✅ 任务管理（查看、停止定时任务） - ✅ 支持无限重复或指定次数 ### 🔌 插件系统 - ✅ 插件化架构，支持动态加载 - ✅ 插件管理界面（添加、移除、重新加载） - ✅ 支持自定义插件开发 - ✅ 完整的插件开发文档 ## 安装 ### 1. 克隆或下载项目 ```bash cd xxx ``` ### 2. 安装依赖 ```bash pip install -r requirements.txt ``` ### 3. 配置 API Key 有三种方式配置 API Key： **方式 1：在 GUI 界面中配置（推荐）** - 启动程序后，点击菜单栏「设置」→「配置 API」 - 输入 API Key、API URL 和模型名称 - 点击「保存并重新加载」，配置会自动保存到 `config.json` **方式 2：编辑配置文件** - 复制 `config.example.json` 为 `config.json` - 编辑 `config.json`，填入你的配置： ```json { "api_key": "your-api-key-here", "api_url": "https://api.deepseek.com/chat/completions", "model_name": "deepseek-chat" } ``` **方式 3：编辑 main.py（不推荐）** - 直接修改 `main.py` 中的配置（仅用于开发测试） ### 4. 运行程序 ```bash python main.py ``` **首次启动**：程序会显示登录窗口，需要输入密码才能访问。 - 默认密码：`gdzs@gitee.com` - 最多允许 5 次错误尝试 ## 插件开发 AI Agent 支持插件化扩展，你可以开发自定义插件来添加新功能。 ### 快速开始 1. **查看开发文档**：打开应用 → **设置** → **插件管理** → **📖 开发文档** 2. **或直接查看**：`docs/plugin-development.md` ### 插件管理 1. 打开应用 2. 点击菜单：**设置** → **插件管理** 3. 可以： - ➕ 添加插件（选择 `.py` 文件） - ➖ 移除插件 - 🔄 重新加载插件 - 📖 查看开发文档 ### 开发示例 创建一个简单的插件： ```python from plugins.plugin_base import BasePlugin class MyPlugin(BasePlugin): @property def name(self): return "My Plugin" @property def description(self): return "我的第一个插件" def get_tools_definition(self): return [{ "type": "function", "function": { "name": "hello", "description": "打招呼", "parameters": { "type": "object", "properties": { "name": {"type": "string"} }, "required": ["name"] } } }] def get_tools_map(self): def hello(name: str): return f"你好，{name}！" return {"hello": hello} ``` 详细文档请查看 `docs/plugin-development.md`。 ## 使用说明 ### 基本使用 1. 启动程序后，在输入框中输入你的问题或指令 2. 按 `Ctrl+Enter` 或点击"发送"按钮 3. Agent 会自动理解你的意图并调用相应的工具 4. 支持多轮工具调用（链式调用），Agent 可以连续执行多个操作 ### 示例对话 **文件操作：** ``` 你: 创建一个名为 test.txt 的文件，内容是 "Hello World" Agent: ✅ 成功创建文件: test.txt (11 字符) ``` **浏览器操作和保存：** ``` 你: 从腾讯新闻获取内容并保存为HTML文件 Agent: ⚙️ 调用工具: extract_text_from_url ✅ 工具执行成功 ⚙️ 调用工具: save_html_file ✅ 成功保存HTML文件: news.html ``` **代码执行：** ``` 你: 执行 Python 代码计算 1+2+3+...+100 Agent: ✅ 执行成功: 5050 ``` **系统信息：** ``` 你: 查看系统内存使用情况 Agent: 总内存: 16.00 GB 可用内存: 8.50 GB 已用内存: 7.50 GB 使用率: 46.9% ``` **链式操作（多轮工具调用）：** ``` 你: 获取百度首页内容，提取文本，然后保存为HTML文件 Agent: ⚙️ 调用工具: fetch_url_content ✅ 工具执行成功 ⚙️ 调用工具: extract_text_from_url ✅ 工具执行成功 ⚙️ 调用工具: save_html_file ✅ 成功保存HTML文件: baidu.html ``` **定时提醒：** ``` 你: 每5秒提醒我喝水 Agent: ⚙️ 调用工具: schedule_reminder ✅ 已创建定时提醒任务: reminder_1 消息: 喝水 间隔: 5 秒 重复: 无限 ``` ## 项目结构 ``` 待更新 ``` ## 开发插件 ### 创建新插件 1. 在 `plugins/` 目录下创建新的 Python 文件 2. 继承 `BasePlugin` 类 3. 实现必要的方法： ```python from .plugin_base import BasePlugin class MyPlugin(BasePlugin): @property def name(self): return "My Plugin" @property def description(self): return "插件描述" def get_tools_definition(self): # 返回工具定义的 JSON Schema 列表 return [...] def get_tools_map(self): # 返回 {函数名: 实际函数} 的映射 return {...} ``` 插件会自动被加载，无需修改其他代码。 ## 安全说明 - 所有文件操作限制在 `agent_workspace/` 目录内 - 代码执行在隔离的工作区中进行 - 网络请求有超时限制（30秒） - 建议在生产环境中添加更多安全检查 ## 支持的 API 理论上支持所有 OpenAI 兼容的 API，包括： - DeepSeek API - OpenAI API - 其他兼容 OpenAI 格式的 API 只需修改 `main.py` 中的 `API_URL` 和 `MODEL` 配置。 ## 最新改进 ### v1.0.0 (当前版本) - ✅ **定时任务插件**：支持定时提醒和定时执行脚本 - ✅ **后台线程执行**：使用独立线程执行定时任务，不阻塞主程序 - ✅ **GUI 提醒**：定时提醒会弹出消息框 - ✅ **任务管理**：可以查看和停止活动的定时任务 - ✅ **用户登录验证**：首次打开需要输入密码才能访问 - ✅ **登录安全**：密码输入隐藏显示，最多允许 5 次错误尝试 - ✅ **现代化登录界面**：深色主题，美观易用 - ✅ **GUI 配置界面**：在界面中直接配置 API Key、API URL 和模型 - ✅ **配置持久化**：配置自动保存到 `config.json` 文件 - ✅ **预设模型快速切换**：提供常用模型的快速选择按钮 - ✅ **配置查看**：可以查看当前使用的配置信息 - ✅ **实时重新加载**：修改配置后无需重启程序 - ✅ **多轮工具调用支持**：Agent 可以连续执行多个工具调用（链式调用） - ✅ **改进的错误处理**：更好的错误提示和异常处理 - ✅ **HTML文件保存**：新增 `save_html_file` 工具，自动添加完整的HTML结构 - ✅ **文本文件保存**：新增 `save_text_file` 工具，专门用于保存文本内容 - ✅ **结果长度限制**：自动截断过长的工具执行结果，避免API限制 - ✅ **更好的日志输出**：详细的工具调用日志和执行状态 ### 使用技巧 1. **链式操作**：你可以要求 Agent 执行一系列操作，例如： - "获取网页内容并保存为HTML文件" - "创建文件夹，然后在里面创建文件" - "执行代码并将结果保存到文件" 2. **结果保存**：使用 `save_html_file` 保存网页内容时，会自动添加完整的HTML结构，包括样式 3. **查看日志**：右侧日志面板会显示所有工具调用的详细信息 ## 配置说明 ### 支持的 API 提供商 程序支持所有 OpenAI 兼容的 API，包括： - **DeepSeek**: `https://api.deepseek.com/chat/completions` - **OpenAI**: `https://api.openai.com/v1/chat/completions` - **其他兼容 API**: 任何支持 OpenAI 格式的 API ### 预设模型 配置界面提供了常用模型的快速选择： - DeepSeek Chat - OpenAI GPT-3.5 Turbo - OpenAI GPT-4 - 自定义模型 ### 配置文件位置 配置文件保存在项目根目录的 `config.json`，格式如下： ```json { "api_key": "sk-...", "api_url": "https://api.deepseek.com/chat/completions", "model_name": "deepseek-chat" } ``` ⚠️ **安全提示**：`config.json` 包含敏感信息，已被 `.gitignore` 忽略，不会提交到版本控制。 ## 贡献 欢迎提交 Issue 和 Pull Request！