# CAD_Agent **Repository Path**: yuliuse/cadagent ## Basic Information - **Project Name**: CAD_Agent - **Description**: 使用SimpleLLMFunc构建的CAD建模助手Agent框架 - **Primary Language**: Unknown - **License**: GPL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 1 - **Created**: 2026-04-21 - **Last Updated**: 2026-05-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # CAD Agent 一个专业的AI驱动CAD建模助手，帮助用户使用CADQuery创建3D模型。该Agent能够理解3D对象的自然语言描述并生成可执行的CAD代码。 ## 🚀 功能特性 - **自然语言CAD建模**：用简单的中文描述您的3D模型，Agent将生成精确的CAD代码 - **多框架支持**：支持CADQuery等不同建模需求的框架 - **交互式开发**：实时代码生成、执行和调试 - **智能查询扩展**：自动将模糊的需求扩展为详细的建模规范 - **文件管理**：内置文件操作功能，用于保存和管理生成的模型 - **错误处理与自动修复**：自动检测并修复常见的CAD建模错误 ### 核心组件 1. **BaseAgent**：协调整个工作流程的主要AI Agent 2. **Tools**：用于CAD代码生成、文件操作和命令执行的专用工具 3. **Config**：管理LLM提供商配置和API密钥 4. **CLI界面**：丰富的终端交互界面 ## 📋 先决条件 ### 系统要求 - Python 3.10或更高版本 ### 必需的Python包 本项目使用 [uv](https://github.com/astral-sh/uv) 进行快速可靠的依赖管理。 要安装所有依赖项，请运行： ```bash uv sync ``` ## ⚙️ 配置 ### 1. 环境变量配置 项目支持从工作目录下的 `.env` 文件中读取环境变量。你可以复制 `env.example` 文件并重命名为 `.env`，然后根据需要修改配置： ```bash cp env.example .env ``` 可配置的环境变量包括： - **RAGFlow 配置**： - `RAGFLOW_BASE_URL`: RAGFlow 服务器地址 - `RAGFLOW_API_KEY`: RAGFlow API 密钥 - **Redis 配置**： - `REDIS_URL`: Redis 连接 URL - `REDIS_DB`: Redis 数据库编号 - `REDIS_PASSWORD`: Redis 密码 - `REDIS_HOST`: Redis 主机地址 - `REDIS_PORT`: Redis 端口 - **存储目录配置**： - `CONTEXT_DIR`: 上下文存储目录 - `SKETCH_DIR`: SketchPad 存储目录 ### 2. LLM 提供商配置 使用您的实际API密钥编辑 `config/providers.json`： ```json { "volc_engine": [ { "model_name": "deepseek-v3-250324", "api_keys": ["your_actual_api_key_here"], "base_url": "https://ark.cn-beijing.volces.com/api/v3/", "max_retries": 3, "retry_delay": 1 } ], "chatanywhere": [ { "model_name": "claude-sonnet-4-20250514", "api_keys": ["your_actual_api_key_here"], "base_url": "https://api.chatanywhere.tech" } ] } ``` ### 3. LLM 接口配置 Agent为不同任务使用不同的LLM接口： - **BASIC_INTERFACE**：一般对话和协调 - **CODE_INTERFACE**：CAD代码生成（需要更强大的模型） - **QUICK_INTERFACE**：查询扩展和简单任务 ## 🚀 快速开始 ### 安装 1. 克隆仓库： ```bash git clone cd CAD-Agent ``` 2. 安装依赖： ```bash uv sync ``` 3. 配置您的LLM提供商（参见上面的配置部分） ### 运行Agent #### 方法1：命令行界面 启动交互式CAD Agent： ```bash mkdir sandbox && cd sandbox export LOG_LEVEL=WARNING && rlwrap python ../main.py press Ctrl+D submit your request ``` #### 方法2：Web界面（推荐） CADDesigner提供现代Web界面以便于交互： **选项A：一键启动（推荐）** ```bash # 激活虚拟环境 source .venv/bin/activate # 同时启动API服务器和Web UI python start_caddesigner_full.py ``` **选项B：分别启动** ```bash # 终端1：启动API服务器 source .venv/bin/activate python start_caddesigner_api.py # 终端2：启动Web UI source .venv/bin/activate python start_caddesigner_ui.py ``` 访问Web界面： - **Web UI**：http://localhost:7860 - **API文档**：http://localhost:8000/docs - **健康检查**：http://localhost:8000/health #### 高级配置 **自定义端口和主机：** ```bash # 自定义配置 python start_caddesigner_full.py \ --api-port 8001 \ --ui-port 7861 \ --api-host 0.0.0.0 \ --ui-host 0.0.0.0 # 开发模式自动重载 python start_caddesigner_full.py --reload --debug # 生产环境部署 python start_caddesigner_full.py \ --workers 4 \ --working-dir /var/lib/caddesigner ``` **远程部署：** ```bash # 服务器A：API服务 python start_caddesigner_api.py --host 0.0.0.0 --port 8000 # 服务器B：指向服务器A的Web UI python start_caddesigner_ui.py \ --host 0.0.0.0 \ --port 7860 \ --api-url http://server-a:8000 ``` 详细的启动选项请参见 [STARTUP_GUIDE.md](STARTUP_GUIDE.md) #### 方法3：Docker 部署（推荐用于生产环境） 使用 Docker 可以快速部署整个CAD Agent系统，包含Redis数据库、API服务和Web界面。 **前置准备：** 1. 创建必要的数据目录： ```bash mkdir -p /data/simplecad_redis ``` 2. 配置模型供应商： ```bash cd docker cp provider_template.json provider.json ``` 编辑 `provider.json` 配置你的模型供应商和API密钥： ```json { "volc_engine": [ { "model_name": "deepseek-v3-250324", "api_keys": ["your_actual_api_key_here"], "base_url": "https://ark.cn-beijing.volces.com/api/v3/", "max_retries": 3, "retry_delay": 1 } ], "chatanywhere": [ { "model_name": "claude-sonnet-4-20250514", "api_keys": ["your_actual_api_key_here"], "base_url": "https://api.chatanywhere.tech" } ] } ``` 3. 配置环境变量： ```bash cp env.example .env ``` 编辑 `.env` 文件，配置RAGFlow等服务： ```bash # RAGFlow 配置 RAGFLOW_BASE_URL=http://localhost RAGFLOW_API_KEY=ragflow-yourkey # 存储目录配置 CONTEXT_DIR=data/contexts SKETCH_DIR=data/sketches # 日志配置 LOG_DIR=./agent_logs LOG_LEVEL=WARNING ``` **启动服务：** ```bash cd docker docker compose up -d ``` **访问服务：** - **Web界面**: http://your-host:7860 - **API服务**: http://your-host:8000 - **API文档**: http://your-host:8000/docs **管理服务：** ```bash # 查看服务状态 docker compose ps # 查看日志 docker compose logs -f # 停止服务 docker compose down # 重启服务 docker compose restart # 清理所有数据（谨慎操作） docker compose down -v ``` **生产环境部署建议：** 1. 修改默认端口（如果需要）： ```bash # 编辑 docker-compose.yml，修改端口映射 ports: - "your_port:7860" # WebUI端口 - "your_port:8000" # API端口 ``` 2. 配置反向代理（推荐使用Nginx）： ```nginx server { listen 80; server_name your-domain.com; location / { proxy_pass http://localhost:7860; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /api/ { proxy_pass http://localhost:8000/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } ``` 3. 配置RAG 我们至少要保证你在一台能够连接到RAGFlow所在服务器的电脑上安装了`simplecadapi`以及`ragflow-sdk`，并配置了`RAGFLOW_BASE_URL`和`RAGFLOW_API_KEY`。 在这样的条件下，首先尝试执行： ```bash make-export --show-api-only ``` 如果能够正常打印出所有的SimpleCADAPI名称，说明你已经正确安装了`simplecadapi`。你可能会遇到有关于`LibGL`的问题，这时候请自行询问GPT如何解决。 然后尝试执行： ```bash auto-docs-gen ``` 来生成所有的markdown文档 然后尝试执行： ```bash ragflow-sync ``` 来同步所有的文档到你的RAGFlow。然后要记得去RAGFlow的UI里选中所有的文档然后批量开始解析，虽然是会解析失败的但是RAGFlow太💩了不做这一步不能检索。 ### 基本使用示例 1. **简单对象创建**： ``` >>> 创建一个边长50mm的立方体 ``` 2. **复杂机械零件**： ``` >>> 我需要一个根据ASME B16.5标准的DN100 PN16焊接法兰 ``` 3. **参数化模型**： ``` >>> 设计一个18齿、模数2.0、压力角20度的齿轮 ``` ### 工作流程 1. **查询输入**：用自然语言描述您的CAD模型 2. **需求扩展**：Agent将询问澄清问题并扩展您的需求 3. **代码生成**：使用CADQuery生成CAD代码 4. **执行与导出**：运行代码并导出为STEP格式 5. **错误处理**：自动修复出现的任何问题 ## 🛠️ 开发指南 ### 项目结构深入解析 #### `agent/BaseAgent.py` 核心Agent负责： - 管理对话历史和内存 - 协调工具使用 - 处理流式响应 - 实现内存管理策略 关键方法： - `run()`：主要执行方法 - `memory_manage()`：处理对话历史摘要 - `chat_impl()`：核心聊天逻辑和详细指令 #### `tools/tools.py` 包含专用工具： - **`cad_query_code_generation`**：生成CADQuery代码 - **`pythonocc_code_generation`**：生成PythonOCC代码 - **`make_user_query_more_detailed`**：扩展用户需求 - **`execute_command`**：运行系统命令 - **`interactive_terminal`**：处理交互式进程 - **`file_operations`**：文件读写操作 #### `config/config.py` 管理： - LLM提供商配置 - API密钥管理 - 模型选择策略 ### 添加新工具 添加新的CAD工具： 1. 在 `tools/tools.py` 中创建新函数： ```python @tool( name="your_tool_name", description="What your tool does" ) def your_tool_function(param1: str, param2: int) -> str: """ 您的工具实现 """ # 工具逻辑在这里 return result ``` 2. 在 `main.py` 中将其添加到工具包： ```python toolkit = [ cad_query_code_generation, pythonocc_code_generation, make_user_query_more_detailed, execute_command, interactive_terminal, file_operations, your_tool_function, # 在这里添加您的新工具 ] ``` ### 扩展LLM支持 添加新的LLM提供商： 1. 在 `config/providers.json` 中添加提供商配置 2. 更新 `config/config.py` 以处理新提供商 3. 使用不同模型能力进行测试 ### 自定义Agent行为 Agent的行为在 `BaseAgent.py` 中的 `chat_impl` 方法文档字符串中定义。您可以修改： - 响应模式 - 工具使用策略 - 错误处理方法 - 内存管理策略 ## 🧪 测试 ### 手动测试 ```bash # 测试基本功能 python main.py # 测试代码生成 >>> 创建一个半径10mm、高度20mm的简单圆柱体 ``` ### 自动化测试 为以下内容创建测试用例： - 代码生成质量 - 错误处理 - 文件操作 - 工具集成 示例测试结构： ```python def test_cadquery_generation(): agent = setup_agent() result = agent.run("创建一个简单的立方体") assert "cadquery" in result.lower() assert ".step" in result.lower() ``` ## 📁 输出管理 生成的模型保存在有组织的目录中： ``` ./sandbox/ ├── DN100_PN16_welding_flange/ │ ├── flange_model.py │ ├── flange_model.step │ └── generation_log.txt ├── gear_18_teeth/ │ ├── gear_model.py │ ├── gear_model.step │ └── generation_log.txt ``` ## 🤝 贡献 1. Fork 仓库 2. 创建功能分支：`git checkout -b feature-name` 3. 进行更改并彻底测试 4. 提交带有详细描述的拉取请求 ### 代码风格 - 遵循Python代码的PEP 8规范 - 尽可能使用类型提示 - 为所有函数添加文档字符串 - 在提交前测试新功能 ## 📝 许可证 GPL2.0 ## 🆘 支持 如有疑问和支持： 1. 查看故障排除部分 2. 查看仓库中的现有问题 3. 创建包含详细错误信息的新问题 ## 🔮 未来路线图 - [ ] 基于浏览器的Web界面 - [ ] 与更多CAD格式的集成（IGES、STL） - [ ] 高级参数化建模功能 - [ ] 与仿真工具的集成 - [ ] 多语言支持 - [ ] CAD模型优化建议 - [ ] 与制造数据库的集成 --- **注意**：本项目专为教育和专业CAD建模辅助而设计。请始终验证生成的模型满足您的特定要求和安全标准。