内容
# BlenderAI
**您在Blender中的AI副驾驶 — 私密性高，功能强大**
BlenderAI连接Blender到本地和云端模型（Ollama、OpenAI、Claude、DeepSeek、Qwen、GLM、OpenCode Zen，以及任何兼容OpenAI的API）。在Blender的 **N面板** 中聊天，运行用于建模、材质、灯光等的领域 **技能**，并通过 **MCP** 控制光标处的实时场景。浏览器WebUI是为提供商和更丰富的屏幕提供的可选功能。
> [README.fa.md](README.fa.md) · 用户指南：[GUIDE.md](GUIDE.md) · 贡献指南：[CONTRIBUTING.md](CONTRIBUTING.md)
| | |
|--|--|
| **仓库** | [github.com/kakajan/blenderAI](https://github.com/kakajan/blenderAI) |
| **作者** | [AsherQelich SayyedMuhammadi](https://github.com/kakajan) (`@kakajan`) |
| **问题** | [打开一个问题](https://github.com/kakajan/blenderAI/issues) |
| **网站** | [kakajan.github.io/blenderAI](https://kakajan.github.io/blenderAI/) |
| **许可证** | [MIT](LICENSE) |
### 文档概览
| 需要 | 英语 | فارسی |
|------|---------|--------|
| 概述（此文件） | [README.md](README.md) | [README.fa.md](README.fa.md) |
| 逐步指南 | [GUIDE.md](GUIDE.md) | [GUIDE.fa.md](GUIDE.fa.md) |
| 贡献 | [CONTRIBUTING.md](CONTRIBUTING.md) | [CONTRIBUTING.fa.md](CONTRIBUTING.fa.md) |
| 架构 / MCP / 技能 | [docs/](docs/) | 同一文件夹（`*.fa.md`） |
---
## 为什么选择BlenderAI？
- **您始终在控制** — API密钥保留在您的机器上；本地模式锁定云提供商。
- **离线工作** — Ollama优先用于私人工作室和隔离环境。
- **为真实的流程而构建** — 技能、预设、无撤消工具友好和Blender N面板，保持在您的视线之外。
- **开放和欢迎** — MIT许可。想法、修复和新技能真正受到欢迎。
---
## 要求
| 工具 | 版本 |
|------|---------|
| Blender | **4.2+** |
| Python | **3.11+** （辅助） |
| Node.js | **20+** （可选；用于重建WebUI） |
| Ollama | 可选，用于本地模型 |
支持的平台：**Windows**、**macOS**、**Linux**。
---
## 快速入门（推荐）
### 1. 运行安装程序
**Windows**
```bat
installer\Install.bat
```
**macOS / Linux**
```bash
chmod +x installer/Install.sh
./installer/Install.sh
```
或从任何操作系统：
```bash
python installer/install.py
# 无界面：python installer/install.py --cli
```
安装程序查找Blender，安装扩展程序，并在用户数据文件夹中设置Sidecar + WebUI。
### 2. 重启Blender
打开Blender → 在3D视口N面板中查找 **BlenderAI** 标签（按 `N`）。
### 3. 在N面板中聊天
在 **BlenderAI** 侧边栏选项卡中，输入提示并单击 **发送**。聊天在Blender内部运行。
对于提供商/历史/技能，请使用更大的UI中的 **在浏览器中打开** （或访问 [http://127.0.0.1:8765](http://127.0.0.1:8765)）。
### 4. 连接模型
前往 **提供商**：
1. 启用 **Ollama** （本地）和/或云提供商。
2. 输入基本URL/API密钥。
3. 单击 **测试连接**。
4. 设置默认模型。
您可以使用自然语言创建网格、材质和灯光。
---
## 日常使用
完整演练（安装 → 提供商 → 技能 → MCP → 故障排除）： **[GUIDE.md](GUIDE.md)**。
### 在Blender中（N面板）
| 操作 | 它执行的操作 |
|--------|----------------|
| **聊天 → 发送** | 从Blender内部与场景交谈 |
| **聊天 → 停止 / 新聊天** | 取消生成或清除历史记录 |
| 提供商（浏览器） | 在WebUI中打开AI连接设置 |
| 捕获 | 发送视口快照用于视觉/批评技能 |
| 撤消AI | 撤消上一个AI工具组 |
| 在浏览器中打开 | 可选的丰富WebUI（提供商，历史记录，技能） |
| 启动/停止 | 控制本地Sidecar服务 |
### 在WebUI中（可选）
| 选项卡 | 目的 |
|-----|---------|
| **聊天** | 与场景交谈；选择提供商、模型和技能 |
| **技能** | 浏览内置技能并 **创建您自己的技能** |
| **预设** | 预制提示和工作流程 |
| **提供商** | 所有AI连接设置（源） |
| **历史记录** | 过去的对话 |
| **设置** | 语言（EN/FA），文本方向（LTR/RTL），自主性，MCP令牌 |
**提示：** 语言和文本方向是独立的 — 如果您喜欢，可以保留英语UI和RTL布局。
### 自主级别
- **询问** — 确认风险较大的操作
- **自动安全** — 自动运行安全工具
- **自动全部** — 运行允许的工具而无需提示
---
## 手动设置（开发人员）
### Sidecar
```bash
cd sidecar
python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate # macOS / Linux
pip install -e ".[dev]"
python -m blender_ai_sidecar.main serve
```
健康检查： [http://127.0.0.1:8765/health](http://127.0.0.1:8765/health)
### WebUI（开发）
```bash
cd webui
npm install
npm run dev
```
### 扩展
在Blender中： **编辑 → 首选项 → 获取扩展 → 从磁盘安装** → 选择
`%APPDATA%\BlenderAI\cache\blender_ai_extension.zip` （或 `extension/` 文件夹）→ 在 **插件** 选项卡中启用 **BlenderAI**。
---
## MCP（Cursor，Claude Desktop等代理）
控制 **同一个打开的Blender场景** 来自Cursor，Claude Desktop，Claude Code，Windsurf，VS Code，Cline，Continue或任何MCP客户端。
**安装程序自动配置MCP客户端** （Cursor，Claude Desktop，Claude Code，…）— 安装后重新启动每个应用程序。
查看完整指南和示例JSON文件： [docs/mcp.md](docs/mcp.md)
保持Blender打开并启用插件，Sidecar运行。
---
## 项目布局
| 路径 | 角色 |
|------|------|
| `extension/` | Blender 4.2+ 扩展（N面板，桥梁，工具） |
| `sidecar/` | 本地AI路由器，聊天代理，技能，MCP服务器 |
| `webui/` | 聊天 + 提供商UI |
| `installer/` | 跨平台图形安装程序 |
| `skills/` | 技能定义（YAML） |
| `presets/` | 系统提示和工作流程 |
| `docs/` | 架构和指南 |
更多详情： [docs/architecture.md](docs/architecture.md) · [docs/skills.md](docs/skills.md)
---
## 数据和隐私
| 平台 | 数据目录 |
|----------|----------------|
| Windows | `%APPDATA%\BlenderAI` |
| macOS | `~/Library/Application Support/BlenderAI` |
| Linux | `~/.local/share/BlenderAI` |
- API密钥通过OS密钥环存储（从不存储在 `.blend` 文件中）。
- 只有在您选择使用这些提供商时，场景上下文才会被发送到云模型。
- 提供商中的 **仅本地** 禁用云端点。
---
## 贡献
我们欢迎您的帮助 — 无论您是交付一项技能，修复一个错字，还是重新设计一个流程。
1. 阅读用户 [GUIDE.md](GUIDE.md) 以了解顺利的路径。
2. 遵循 [CONTRIBUTING.md](CONTRIBUTING.md) （فارسی: [CONTRIBUTING.fa.md](CONTRIBUTING.fa.md)）。
3. 为错误或想法打开一个问题，然后发送一个专注的拉取请求。
**尤其欢迎**
- 新技能（雕塑，几何节点，绑定，合成）
- 提供商适配器和测试
- UI/UX润色和无障碍
- 文档，翻译和教程
- 工具允许列表/MCP表面的安全审查
---
## 支持项目
如果BlenderAI为您节省了时间：
- [加星仓库](https://github.com/kakajan/blenderAI) 并与您的工作室分享
- [报告错误](https://github.com/kakajan/blenderAI/issues) 并附上清晰的步骤（Blender版本 + 操作系统帮助很大）
- 关注/联系作者： [@kakajan](https://github.com/kakajan) — AsherQelich SayyedMuhammadi
- 如果我们发布支持链接，请赞助或捐赠 — 每一分钱都让灯亮着
- 资助/承包有助于开放改进的工作始终欢迎讨论
感谢您在这里。创意工具应该感觉像伙伴，而不是障碍。
---
## 许可证
[MIT](LICENSE) — 版权所有 © 2026 [AsherQelich SayyedMuhammadi](https://github.com/kakajan)。使用它，fork它，构建它。
---
**BlenderAI** — [github.com/kakajan/blenderAI](https://github.com/kakajan/blenderAI) · 今天创造一些美好的东西。
