blender-toolkit

⚠️ 安装检查（请先阅读）

重要：使用此技能前，请检查 Blender 插件的安装状态。

配置位置：检查共享配置文件，确认安装状态：

~/.claude/plugins/marketplaces/dev-gom-plugins/blender-config.json

务必先使用 --help 运行脚本，查看用法。除非先尝试运行脚本，并确认确实有必要使用自定义方案，否则请勿阅读源代码。这些脚本可能非常庞大，会占用上下文窗口。它们是供直接调用的黑盒脚本，而不是供读入上下文窗口的内容。

根据配置执行必要操作：

1. 如果未检测到 Blender（blenderExecutable: null）

初始化期间未找到 Blender。请：

1. 安装 Blender 4.0+，网址：https://www.blender.org
2. 重启 Claude Code 会话以触发自动检测
3. 查看日志：.blender-toolkit/init-log.txt

2. 如果检测到多个版本（detectedBlenderVersions 数组）

系统检测到了多个 Blender 安装。如果想使用其他版本：

1. 打开配置文件（路径如上所示）
2. 将 blenderExecutable 字段编辑为首选版本的路径
3. 重启 Claude Code 会话

示例：

{
  "detectedBlenderVersions": [
    {"version": "4.2.0", "path": "C:\\Program Files\\Blender Foundation\\Blender 4.2\\blender.exe"},
    {"version": "4.1.0", "path": "C:\\Program Files\\Blender Foundation\\Blender 4.1\\blender.exe"}
  ],
  "blenderExecutable": "C:\\Program Files\\Blender Foundation\\Blender 4.2\\blender.exe"
}

3. 如果未安装插件（addonInstalled: false）

需要手动安装插件。请按以下步骤操作：

手动安装步骤：

方法 1：从 ZIP 安装（推荐）

# 1. Open Blender 4.0+
# 2. Edit > Preferences > Add-ons > Install
# 3. Select: .blender-toolkit/blender-toolkit-addon-v*.zip
# 4. Enable "Blender Toolkit WebSocket Server"

方法 2：从源代码安装

# 1. Open Blender 4.0+
# 2. Edit > Preferences > Add-ons > Install
# 3. Select: plugins/blender-toolkit/skills/addon/__init__.py
# 4. Enable "Blender Toolkit WebSocket Server"

启动 WebSocket 服务：

1. 打开 3D 视图 → 侧栏（按 N 键）
2. 找到“Blender Toolkit”选项卡
3. 点击“Start Server”按钮
4. 默认端口：9400（每个项目自动分配）

更新配置：

• 打开配置文件（路径如上所示）
• 设置 "addonInstalled": true
• 保存文件

验证连接：

• 尝试运行简单命令：node .blender-toolkit/bt.js list-objects
• 如果成功，你会看到场景中的对象列表

故障排除：

• 如果 Blender 路径不正确：更新配置中的 blenderExecutable
• 如果端口被占用：系统会自动分配下一个可用端口（9401-9500）
• 查看日志：.blender-toolkit/init-log.txt
• 查看 Blender 控制台中的错误消息

4. 如果一切就绪（addonInstalled: true）

✅ 一切就绪！你可以使用所有 Blender Toolkit 命令。

---

blender-toolkit

通过基于 WebSocket 的实时控制自动化 Blender 工作流。创建几何体、管理材质和修改器，并借助智能骨骼映射将 Mixamo 动画重定向到自定义骨架。

用途

提供全面的 Blender 自动化功能：

• 🎨 创建几何体 - 基本体（立方体、球体、圆柱体、平面、圆锥体、圆环）
• 🎭 材质管理 - 创建、分配和配置材质
• 🔧 修改器控制 - 添加、应用和管理修改器
• 🎬 动画重定向 - 通过自动骨骼映射，将 Mixamo 动画重定向到自定义骨架

适用场景

在以下情况下使用此技能：

• 创建 3D 几何体： 用户想创建基本体或操作网格
• 管理材质： 用户需要创建或分配具有 PBR 属性的材质
• 添加修改器： 用户想使用细分、镜像、阵列或其他修改器
• 重定向动画： 用户需要将 Mixamo 动画应用到自定义角色
• 批量操作： 用户想处理多个对象或动画

注意： Mixamo 不提供官方 API。用户必须从 Mixamo.com 手动下载 FBX 文件。

快速入门

前置条件检查清单

开始前，请确保：

• 已安装 Blender 4.0+
• 已安装并启用 Blender Toolkit 插件
• 已在 Blender 中启动 WebSocket 服务（默认端口：9400）
• 已加载角色骨架（用于动画重定向）

安装插件：

1. Open Blender → Edit → Preferences → Add-ons
2. Click "Install" → Select plugins/blender-toolkit/skills/addon/__init__.py
3. Enable "Blender Toolkit WebSocket Server"
4. Start server: View3D → Sidebar (N) → "Blender Toolkit" → "Start Server"

常见操作

创建几何体：

# Create cube at origin
blender-toolkit create-cube --size 2.0

# Create sphere with custom settings
blender-toolkit create-sphere --radius 1.5 --segments 64

# Subdivide mesh
blender-toolkit subdivide --name "Cube" --cuts 2

管理对象：

# List all objects
blender-toolkit list-objects

# Transform object
blender-toolkit transform --name "Cube" --loc-x 5 --loc-y 0 --scale-x 2

# Duplicate object
blender-toolkit duplicate --name "Cube" --new-name "Cube.001" --x 3

材质：

# Create material
blender-toolkit material create --name "RedMaterial"

# Assign to object
blender-toolkit material assign --object "Cube" --material "RedMaterial"

# Set color
blender-toolkit material set-color --material "RedMaterial" --r 1.0 --g 0.0 --b 0.0

重定向动画：

# Basic retargeting with UI confirmation
blender-toolkit retarget \
  --target "HeroRig" \
  --file "./Walking.fbx" \
  --name "Walking"

# Rigify preset (skip confirmation)
blender-toolkit retarget \
  --target "MyRigifyCharacter" \
  --file "./Walking.fbx" \
  --mapping mixamo_to_rigify \
  --skip-confirmation

# Show Mixamo download instructions
blender-toolkit mixamo-help Walking

架构

基于 WebSocket 的设计：

┌──────────────┐         ┌─────────────┐    WebSocket    ┌──────────────┐
│ Claude Code  │   IPC   │ TypeScript  │◄──────────────►│   Blender    │
│   (Skill)    │────────►│   Client    │   Port 9400+   │  (Addon)     │
└──────────────┘         └─────────────┘                └──────────────┘
                              │                               │
                              ▼                               ▼
                     ┌─────────────────┐         ┌────────────────────┐
                     │  - Geometry     │         │  - WebSocket       │
                     │  - Material     │         │    Server          │
                     │  - Modifier     │         │  - Command         │
                     │  - Retargeting  │         │    Handlers        │
                     │  - Bone Mapping │         │  - Bone Mapping UI │
                     └─────────────────┘         └────────────────────┘

关键组件：

• WebSocket 服务端： Blender 中的 Python 插件（端口 9400-9500）
• TypeScript 客户端： 通过 JSON-RPC 发送命令
• 骨骼映射系统： 模糊匹配并通过 UI 确认
• 两阶段工作流： 生成 → 审核 → 应用

核心工作流

1. 几何体创建工作流

提取需求：

• 基本体类型（立方体、球体、圆柱体等）
• 位置（x、y、z 坐标）
• 尺寸参数（半径、深度、分段数）
• 可选对象名称

执行：

import { BlenderClient } from 'blender-toolkit';

const client = new BlenderClient();
await client.connect(9400);

// Create sphere
const result = await client.sendCommand('Geometry.createSphere', {
  location: [0, 0, 2],
  radius: 1.5,
  segments: 64,
  name: 'MySphere'
});

console.log(`✅ Created ${result.name} with ${result.vertices} vertices`);

2. 材质分配工作流

步骤：

1. 创建材质
2. 将材质分配给对象
3. 配置属性（颜色、金属度、粗糙度）

执行：

# Create and configure material
blender-toolkit material create --name "Metal"
blender-toolkit material set-color --material "Metal" --r 0.8 --g 0.8 --b 0.8
blender-toolkit material set-metallic --material "Metal" --value 1.0
blender-toolkit material set-roughness --material "Metal" --value 0.2

# Assign to object
blender-toolkit material assign --object "Sphere" --material "Metal"

3. 动画重定向工作流 ⭐

最常见的用例

阶段 1：设置并生成映射

1. User provides:
   - Target character armature name
   - Animation FBX file path
   - (Optional) Animation name for NLA track

2. System executes:
   - Connects to Blender WebSocket
   - Imports FBX file
   - Analyzes bone structure
   - Auto-generates bone mapping (fuzzy matching)
   - Displays mapping in Blender UI for review

3. Quality Assessment:
   - Excellent (8-9 critical bones) → Safe to auto-apply
   - Good (6-7 critical bones) → Quick review recommended
   - Fair (4-5 critical bones) → Thorough review required
   - Poor (< 4 critical bones) → Manual mapping needed

阶段 2：用户确认

1. User reviews mapping in Blender:
   - View3D → Sidebar (N) → "Blender Toolkit" → "Bone Mapping Review"
   - Check source → target correspondence
   - Edit incorrect mappings using dropdowns
   - Use "Auto Re-map" button to regenerate if needed

2. User confirms:
   - Click "Apply Retargeting" button in Blender

3. System completes:
   - Creates constraint-based retargeting
   - Bakes animation to keyframes
   - Adds to NLA track
   - Cleans up temporary objects

示例：

import { AnimationRetargetingWorkflow } from 'blender-toolkit';

const workflow = new AnimationRetargetingWorkflow();

// If user doesn't have FBX yet
console.log(workflow.getManualDownloadInstructions('Walking'));

// After user downloads FBX
await workflow.run({
  targetCharacterArmature: 'HeroRig',
  animationFilePath: './Walking.fbx',
  animationName: 'Walking',
  boneMapping: 'auto',           // Auto-generate with fuzzy matching
  skipConfirmation: false        // Enable UI review workflow
});

跳过确认（适用于已验证可靠的映射）：

# Rigify preset - instant application
blender-toolkit retarget \
  --target "RigifyCharacter" \
  --file "./Walking.fbx" \
  --mapping mixamo_to_rigify \
  --skip-confirmation

# Excellent quality - trusted auto-mapping
blender-toolkit retarget \
  --target "MyCharacter" \
  --file "./Walking.fbx" \
  --skip-confirmation

主要功能

自动骨骼映射与 UI 审核 🌟

对于未知或自定义骨架，建议使用此工作流：

工作原理：

1. 模糊匹配算法

   • 规范化骨骼名称（处理各种命名约定）
   • 计算相似度分数（0.0-1.0）
   • 以下情况会获得额外加分：
     • 子字符串匹配（+0.15）
     • 常见前缀：left、right（+0.1）
     • 常见后缀：.L、.R、_l、_r（+0.1）
     • 数字匹配：Spine1、Spine2（+0.1）
     • 解剖学关键词：arm、leg、hand（+0.05）

2. 质量评估

   • 跟踪 9 根关键骨骼（Hips、Spine、Head、Arms、Legs、Hands）
   • 提供质量评级（Excellent/Good/Fair/Poor）
   • 根据质量推荐操作

3. UI 确认面板

   • 显示完整映射表
   • 每个映射都提供可编辑的下拉菜单
   • “Auto Re-map”按钮（重新生成）
   • “Apply Retargeting”按钮（继续）

优势：

• 适用于任何骨架结构
• 无需手动配置
• 用户可在应用前进行验证
• 防止动画错误

三种骨骼映射模式

1. 自动模式（推荐） ⭐

# Default: Auto-generate with UI confirmation
blender-toolkit retarget --target "Hero" --file "./Walk.fbx"

• 模糊匹配算法
• UI 审核工作流
• 最适合未知骨架

2. Rigify 模式

# Preset for Rigify control rigs
blender-toolkit retarget --target "Hero" --file "./Walk.fbx" --mapping mixamo_to_rigify

• 预定义 Mixamo → Rigify 映射
• 立即应用
• 对 Rigify 的准确度最高

3. 自定义模式

// Explicit bone mapping
const customMapping = {
  "Hips": "root_bone",
  "Spine": "torso_01",
  "LeftArm": "l_upper_arm",
  // ... complete mapping
};

await workflow.run({
  boneMapping: customMapping,
  skipConfirmation: true
});

• 完全掌控
• 可在多个动画中重复使用
• 适用于非标准骨架

多项目支持

自动端口管理：

• 自动为项目分配唯一端口（9400-9500）
• 配置会跨会话保留
• 可同时运行多个 Blender 实例

配置存储：

// ~/.claude/plugins/.../blender-config.json
{
  "projects": {
    "/path/to/project-a": { "port": 9400 },
    "/path/to/project-b": { "port": 9401 }
  }
}

重要指南

何时询问用户

如果出现以下情况，请使用 AskUserQuestion 工具：

• 角色骨架名称不明确
• 存在多个骨架（目标不明确）
• 未提供动画 FBX 路径
• Blender WebSocket 连接失败
• 用户需要 Mixamo 下载指导

不要猜测：

• 角色名称
• 文件路径
• 骨架结构

Mixamo 下载流程

由于 Mixamo 没有 API，用户必须手动下载：

提供说明：

// Show download help
const workflow = new AnimationRetargetingWorkflow();
console.log(workflow.getManualDownloadInstructions('Walking'));
console.log(workflow.getRecommendedSettings());

等待用户：

• 引导用户从 Mixamo.com 下载
• 下载完成后获取文件路径
• 然后继续进行重定向

故障排除

“Blender 未运行”

# Check connection
blender-toolkit daemon-status

# If failed:
1. Verify Blender is open
2. Check addon is enabled
3. Start server: Blender → N → "Blender Toolkit" → "Start Server"

“未找到目标骨架”

• 确认骨架的准确名称（区分大小写）
• 检查角色是否位于当前场景中
• 使用 list-objects --type ARMATURE 查看可用的骨架

骨骼映射“质量较差”

1. 在 Blender 中查看骨骼名称（编辑模式）
2. 为关键骨骼创建自定义映射
3. 降低相似度阈值（默认值：0.6）
4. 检查骨架是否具有正确的层级结构

“四肢扭曲或反转”

• 检查左右骨骼映射
• 在编辑模式下验证骨骼滚转
• 检查约束轴
• 先使用简单动画进行测试

最佳实践

1. 🌟 使用自动模式并确认界面

   • 对未知骨架最可靠
   • 始终检查关键骨骼（Hips、Spine、Arms、Legs）
   • 应用前编辑错误的映射

2. 先测试简单动画

   • 从 Idle 或 Walking 开始
   • 确认骨骼映射正常工作
   • 检查根运动（Hips 骨骼）
   • 然后再处理复杂动画

3. 从 Mixamo 下载正确的格式

   • 格式：FBX（.fbx）
   • 蒙皮：不带蒙皮
   • FPS：30 fps
   • 关键帧精简：无

4. 自动应用前检查质量

   • 优秀（8-9 个关键项）→ 可安全跳过确认
   • 良好（6-7 个关键项）→ 快速检查
   • 一般（4-5 个关键项）→ 彻底检查
   • 较差（< 4 个关键项）→ 使用自定义映射

5. 保存自定义映射以便复用

   • 记录成功的映射
   • 复用于同一角色的动画
   • 与团队成员分享

6. 让系统管理端口

   • 不要手动配置端口
   • 系统会处理多项目冲突
   • 配置会自动持久化

参考资料

详细文档位于 references/ 文件夹中：

• commands-reference.md - 完整的 CLI 命令参考

  • 所有几何体、对象、材质和修改器命令
  • 详细的选项和示例
  • 端口管理和提示

• bone-mapping-guide.md - 骨骼匹配系统详情

  • 模糊匹配算法说明
  • 质量评估指标
  • 常见映射模式（Rigify、UE4、Unity）
  • 映射问题故障排除

• workflow-guide.md - 完整的工作流文档

  • 逐步讲解重定向工作流
  • Mixamo 下载流程
  • 两阶段确认详情
  • 批量处理工作流
  • 多项目工作流

• addon-api-reference.md - WebSocket API 文档

  • JSON-RPC 协议详情
  • 所有 API 方法和参数
  • 错误处理
  • 安全和性能提示

何时加载参考资料：

• 用户需要详细的命令选项
• 排查复杂问题
• 了解骨骼映射算法
• 设置高级工作流
• API 集成要求

输出结构

.blender-toolkit/
├── skills/scripts/          # Local TypeScript scripts (auto-initialized)
│   ├── src/                 # Source code
│   ├── dist/                # Compiled JavaScript
│   └── node_modules/        # Dependencies
├── bt.js                    # CLI wrapper
├── logs/                    # Log files
│   ├── typescript.log
│   ├── blender-addon.log
│   └── error.log
└── .gitignore

Shared config:
~/.claude/plugins/.../blender-config.json

备注

• 端口范围： 9400-9500（Browser Pilot 使用 9222-9322）
• 文件格式： 推荐使用 FBX，支持 Collada（.dae）
• Blender 版本： 需要 4.0+（2023+）
• 自动初始化： SessionStart hook 会安装并构建脚本
• 无需手动管理守护进程： 系统会处理所有事务
• WebSocket 协议： JSON-RPC 2.0