# blender-ai

**Repository Path**: liuyong-byte/blender-ai

## Basic Information

- **Project Name**: blender-ai
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-05
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Blender AI Agent - 智能3D创作助手

<div align="center">

![Blender AI Agent](https://img.shields.io/badge/Blender-3.6+-orange.svg)
![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)
![Version](https://img.shields.io/badge/Version-2.0.0-red.svg)

**让AI成为你的3D创作搭档，效率提升10倍+**

[快速开始](#-快速开始) • [功能特性](#-核心功能) • [使用教程](#-使用教程) • [商业授权](#-商业授权)

</div>

---

## 🎯 项目简介

Blender AI Agent 是一款革命性的Blender插件，通过集成先进的AI模型，将自然语言指令自动转换为Blender Python脚本并执行。**无需编写代码**，只需描述你想要的效果，AI即可帮你完成复杂的3D建模、动画制作和场景搭建工作。

### 💡 核心价值

- **🚀 极速创作**：从想法到实现，时间缩短80%
- **🎨 零门槛**：不需要Python编程基础，用自然语言即可控制Blender
- **🔄 智能迭代**：支持多轮对话，逐步完善作品
- **⚡ 自动化工作流**：批量处理、模板复用、一键生成
- **💼 商业级稳定**：错误自动修复、进度可视化、任务管理

### 📊 效率对比

| 任务类型 | 传统方式 | 使用AI Agent | 效率提升 |
|---------|---------|-------------|---------|
| 创建角色模型 | 2-4小时 | 15-30分钟 | **8倍** |
| 场景搭建 | 4-8小时 | 30-60分钟 | **6倍** |
| 动画制作 | 6-12小时 | 1-2小时 | **7倍** |
| 材质调整 | 1-2小时 | 5-10分钟 | **10倍** |

---

## ✨ 核心功能

### 🤖 AI智能生成

- **流式实时响应**：边思考边显示，无需等待完整结果
- **上下文感知**：自动分析当前场景状态，生成精准代码
- **多轮对话记忆**：记住之前的操作，支持渐进式创作
- **错误自愈**：执行失败时自动分析错误并修复

### 📝 聊天式交互

- **历史消息管理**：完整的对话记录，随时回顾
- **消息分类显示**：文本/代码/成功/错误不同类型着色
- **一键重试**：不满意结果？重新生成或修改指令
- **代码预览**：执行前可查看AI生成的Python代码

### 🎬 预设模板系统

- **角色建模模板**：人形角色、动物、机械生物
- **场景搭建模板**：室内环境、自然景观、科幻场景
- **动画模板**：行走循环、飞行轨迹、相机运动
- **特效模板**：粒子系统、物理模拟、光影效果

### ⚙️ 高级工作流

- **批量任务队列**：一次性提交多个任务，按序执行
- **宏命令录制**：记录常用操作，一键回放
- **快捷键自定义**：为常用功能分配快捷键
- **收藏夹**：保存常用的提示词和生成结果

### 🔒 企业级特性

- **许可证管理**：支持个人版/团队版/企业版授权
- **API密钥加密存储**：安全保存敏感信息
- **离线模式**（专业版）：本地AI模型部署
- **团队协作**：共享模板和工作流配置

---

## 🚀 快速开始

### 系统要求

- **Blender版本**：3.6.0 或更高
- **Python版本**：3.10+
- **操作系统**：Windows / macOS / Linux
- **网络**：需要访问OpenAI API（或使用自定义API端点）

### 安装步骤

#### 方法一：一键安装（推荐）

1. **下载插件**
   ```bash
   git clone https://gitee.com/your-repo/blender-ai.git
   cd blender-ai/src
   ```

2. **在Blender中安装**
   - 打开 Blender
   - 进入 `Edit` → `Preferences` → `Add-ons`
   - 点击 `Install...` 按钮
   - 选择 `src.zip` 文件
   - 勾选 "Interface: Blender AI Agent" 启用插件

3. **配置API密钥**
   - 按 `N` 键打开3D视图侧边栏
   - 切换到 `AI Agent` 标签页
   - 在 "Configuration" 区域输入你的 OpenAI API Key
   - 点击 "Save Config" 保存

#### 方法二：开发模式安装

```bash
# 克隆仓库
git clone https://gitee.com/your-repo/blender-ai.git

# 进入插件目录
cd blender-ai/src

# 在Blender Scripting工作区运行 test_plugin.py
```

### 首次使用向导

1. **打开AI Agent面板**
   - 在3D视图中按 `N` 键
   - 点击右侧 "AI Agent" 标签

2. **测试连接**
   - 输入简单指令：`Create a cube at origin`
   - 点击 "Send & Execute" 按钮
   - 观察控制台输出和3D视图变化

3. **探索模板**
   - 点击 "Templates" 标签
   - 选择一个预设模板
   - 根据需要修改参数后执行

---

## 📖 使用教程

### 基础用法

#### 1. 创建简单对象

```
提示词：Create a red sphere with radius 2 at position (0, 0, 3)
```

AI会自动生成并执行以下操作：
- 创建球体网格
- 设置半径为2
- 移动到指定位置
- 应用红色材质

#### 2. 分步构建复杂场景

**第1步：创建基础结构**
```
提示词：Create a simple house base - a cube 4x4x3 meters
```

**第2步：添加屋顶**
```
提示词：Add a pyramid roof on top of the house
```

**第3步：添加门窗**
```
提示词：Cut out a door on the front face and two windows on side faces
```

**第4步：添加环境**
```
提示词：Add ground plane and a sun light source
```

#### 3. 角色建模工作流

```
第1步：Create a humanoid character body mesh
第2步：Add armature with bones for arms, legs, and spine
第3步：Parent the mesh to the armature with automatic weights
第4步：Create a T-pose for the character
第5步：Add a simple walking animation cycle
```

### 高级技巧

#### 💡 提示词优化指南

**✅ 好的提示词：**
- 具体明确：`Create a wooden table 1.5m x 0.8m x 0.75m with 4 legs`
- 分步描述：先整体后细节
- 包含参数：尺寸、颜色、位置等具体数值
- 参考风格：`in low-poly style` 或 `realistic PBR materials`

**❌ 避免的提示词：**
- 过于模糊：`Make something cool`
- 缺少参数：`Create a big object`
- 一次性要求太多：`Create a full city with buildings, roads, cars, people...`

#### 🎯 常用快捷指令

```python
# 查看当前场景信息
提示词：Show me the current scene statistics

# 清理场景
提示词：Delete all objects and start fresh

# 复制对象
提示词：Duplicate the selected object 5 times in a row

# 材质应用
提示词：Apply a glass material to the selected object

# 动画关键帧
提示词：Set keyframes for rotation from frame 1 to 60
```

#### 🔧 故障排除

**问题1：API连接超时**
- 检查网络连接
- 验证API密钥是否正确
- 尝试更换Base URL（如使用代理）

**问题2：生成的代码执行失败**
- 查看控制台错误信息
- AI会自动尝试修复一次
- 手动调整提示词，更详细描述需求

**问题3：结果不符合预期**
- 使用更具体的参数
- 分多步执行，每步验证结果
- 查看聊天历史，了解AI的理解

---

## 🎨 应用场景

### 🎮 游戏开发

- **快速原型设计**：几分钟内创建关卡原型
- **NPC角色生成**：批量创建多样化角色
- **道具资产库**：自动生成武器、家具等道具
- **场景布局**：快速搭建测试场景

### 🎬 动画制作

- **角色绑定**：自动生成骨骼和权重
- **动画预览**：快速创建动作循环
- **相机运动**：设计复杂的镜头轨迹
- **表情动画**：面部 rigs 自动生成

### 🏗️ 建筑可视化

- **室内设计**：快速布置房间家具
- **建筑外观**：生成立面图和结构
- **景观规划**：树木、道路、水体布局
- **光照方案**：自动配置日光和人工光源

### 📐 产品设计

- **概念草图**：3D快速建模验证想法
- **材质展示**：应用不同材质对比效果
- **装配演示**：创建爆炸视图动画
- **渲染准备**：自动设置相机和灯光

---

## 💼 商业授权

### 版本对比

| 功能 | 社区版（免费） | 专业版（$49/年） | 企业版（定制） |
|-----|--------------|----------------|---------------|
| AI代码生成 | ✅ | ✅ | ✅ |
| 聊天历史 | ✅（最多50条） | ✅（无限） | ✅（无限） |
| 预设模板 | 10个基础模板 | 100+高级模板 | 自定义模板 |
| 批量处理 | ❌ | ✅（最多10个任务） | ✅（无限制） |
| 宏命令录制 | ❌ | ✅ | ✅ |
| 离线模式 | ❌ | ❌ | ✅（本地部署） |
| 团队协作 | ❌ | ✅（最多5人） | ✅（无限制） |
| 优先支持 | ❌ | ✅ | ✅（专属客服） |
| 商业用途 | ✅ | ✅ | ✅ |
| 源码访问 | ✅ | ✅ | ✅ |

### 获取授权

- **社区版**：直接从本仓库下载安装，完全免费开源
- **专业版**：访问 [官方网站](https://buymeacoffee.com/iamreality) 购买许可证
- **企业版**：联系邮箱 business@blender-ai.com 获取定制方案

### 开源协议

本项目采用 **MIT License**，你可以：
- ✅ 商业使用
- ✅ 修改源码
- ✅ 分发副本
- ✅ 私人使用

唯一要求：在副本中包含原始版权声明和许可声明。

---

## 🛠️ 技术架构

### 核心技术栈

- **前端**：Blender Python API (bpy)
- **AI引擎**：OpenAI GPT-4/Codex
- **通信**：RESTful API + Streaming
- **数据存储**：JSON配置文件
- **异步处理**：Python Threading

### 工作流程

```
用户输入提示词
    ↓
收集Blender场景上下文
    ↓
构建增强提示词（含历史记录）
    ↓
调用OpenAI API（流式传输）
    ↓
实时显示生成内容
    ↓
清理并验证Python代码
    ↓
在Blender中执行代码
    ↓
捕获错误并自动修复（如有必要）
    ↓
更新UI并显示结果
```

### 安全机制

- **沙箱执行**：所有生成的代码在受控环境中运行
- **权限检查**：禁止执行危险操作（如文件系统写入）
- **超时保护**：单个任务最长执行时间限制
- **撤销支持**：每步操作可单独撤销（Ctrl+Z）

---

## 🤝 参与贡献

我们欢迎任何形式的贡献！

### 贡献方式

1. **报告Bug**：在Issues中详细描述问题
2. **功能建议**：提出新功能想法或改进建议
3. **代码贡献**：Fork仓库 → 创建分支 → 提交PR
4. **文档完善**：帮助改进教程和文档
5. **模板分享**：创建并分享你的预设模板

### 开发指南

详见 [DEVELOPMENT_GUIDE.md](src/DEVELOPMENT_GUIDE.md)

### 行为准则

- 尊重所有贡献者
- 保持友好的讨论氛围
- 代码需符合PEP 8规范
- 新功能需包含测试用例

---

## 📞 支持与反馈

### 获取帮助

- **文档**：查看本README和开发指南
- **Issues**：在GitHub/Gitee提交问题
- **社区**：加入Discord/QQ群交流
- **邮件**：support@blender-ai.com

### 支持开发者

如果这个插件对你有帮助，欢迎支持我们持续开发：

[☕ Buy Me a Coffee](https://buymeacoffee.com/iamreality)

你的支持是我们前进的动力！❤️

---

## 📄 许可证

MIT License

Copyright (c) 2024 Blender AI Agent Team

详见 [LICENSE](LICENSE) 文件

---

<div align="center">

**Made with ❤️ by the Blender AI Community**

[⭐ Star this repo](https://gitee.com/your-repo/blender-ai) • [🐛 Report Bug](https://gitee.com/your-repo/blender-ai/issues) • [💡 Request Feature](https://gitee.com/your-repo/blender-ai/issues)

</div>