mcpField
C
cli-anything-blender

cli-anything-blender

github.com/hkuds创意与媒体57.6k975 次安装5 周前更新
代码仓库

关于 cli-anything-blender

cli-anything-blender 是用于编辑 Blender 场景的有状态命令行工具，面向自动化 3D 工作的 Agent 和用户。它以 JSON 保存项目状态，提供场景控制与渲染预览，便于检查视觉效果。

主要功能

  1. 01管理场景和项目
  2. 02编辑对象、材质与修改器
  3. 03配置摄像机、灯光和动画
  4. 04渲染场景并生成 bpy 脚本
  5. 05捕获并追踪视觉预览
  6. 06交互式 REPL，支持撤销与重做

适用场景

  1. 01通过命令创建或修改 Blender 场景
  2. 02调整材质、灯光和动画
  3. 03渲染预览以核验场景变更

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/hkuds/cli-anything --skill cli-anything-blender

安装后在 Claude Code 中输入/cli-anything-blender确认已加载。

详细介绍

cli-anything-blender

一个有状态的 3D 场景编辑命令行界面，遵循与 GIMP CLI harness 相同的模式。使用 JSON 场景描述格式，并生成 bpy 脚本用于实际的 Blender 渲染。

安装

此 CLI 作为 cli-anything-blender 包的一部分进行安装：

pip install cli-anything-blender

前置要求：

  • Python 3.10+
  • 系统上必须已安装 blender (>= 4.2)

用法

基本命令
# Show help
cli-anything-blender --help

# Start interactive REPL mode
cli-anything-blender

# Create a new scene project
cli-anything-blender scene new -o scene.blend-cli.json

# Run with JSON output (for agent consumption)
cli-anything-blender --json --project scene.blend-cli.json scene info
REPL 模式

当不带子命令调用时，CLI 会进入交互式 REPL 会话：

cli-anything-blender
# Enter commands interactively with tab-completion and history

命令组

Scene

场景管理命令。

命令描述
new创建新场景
open打开现有场景
save保存当前场景
info显示场景信息
profiles列出可用的场景配置
json打印原始场景 JSON
Object Group

3D 对象管理命令。

命令描述
add添加一个 3D 基本体对象
remove按索引移除对象
duplicate复制对象
transform变换对象（平移、旋转、缩放）
set设置对象属性（名称、可见性、位置、旋转、缩放、父级）
list列出所有对象
get获取对象的详细信息
Material

材质管理命令。

命令描述
create创建新材质
assign为对象指定材质
set设置材质属性（颜色、金属度、粗糙度、镜面反射、alpha 等）
list列出所有材质
get获取材质的详细信息
Modifier Group

修改器管理命令。

命令描述
list-available列出所有可用的修改器
info显示修改器的详细信息
add为对象添加修改器
remove按索引移除修改器
set设置修改器参数
list列出对象上的修改器
Camera

摄像机管理命令。

命令描述
add向场景中添加摄像机
set设置摄像机属性
set-active设置活动摄像机
list列出所有摄像机
Light

灯光管理命令。

命令描述
add向场景中添加灯光
set设置灯光属性
list列出所有灯光
Animation

动画和关键帧命令。

命令描述
keyframe在对象上设置关键帧
remove-keyframe从对象上移除关键帧
frame-range设置动画帧范围
fps设置动画 FPS
list-keyframes列出对象的关键帧
Render Group

渲染设置和输出命令。

命令描述
settings配置渲染设置
info显示当前渲染设置
presets列出可用的渲染预设
execute渲染场景（生成 bpy 脚本）
script生成 bpy 脚本但不渲染
预览

真实预览包捕获与实时预览会话命令。

命令描述
preview recipes列出可用的预览配方
preview capture为当前场景渲染真实预览包
preview latest返回最新的现有预览包
preview live start启动实时预览会话并发布首个包
preview live push将刷新后的包发布到实时会话中
preview live status在不渲染的情况下读取当前实时会话状态
preview live stop停止实时会话而不删除产物

配方 quick 的典型包产物：

  • hero.png 来自真实的 Eevee 预览渲染
  • workbench.png 来自真实的 Blender Workbench 渲染

实时会话持久化保存：

  • session.json 作为可变头部
  • 不可变的包目录
  • trajectory.json 作为仅追加的命令到预览历史记录

查看器侧：

  • cli-hub previews inspect <bundle-or-session>
  • cli-hub previews html <bundle-or-session> -o page.html
  • cli-hub previews watch <session-dir> --open
  • cli-hub previews open <bundle-or-session>
会话

会话管理命令。

命令描述
status显示会话状态
undo撤销上一次操作
redo重做上一次撤销的操作
history显示撤销历史记录

示例

创建新项目

创建一个新的 Blender 场景项目文件。

cli-anything-blender scene new -o myscene.blend-cli.json
# Or with JSON output for programmatic use
cli-anything-blender --json scene new -o myscene.blend-cli.json
交互式 REPL 会话

启动支持撤销/重做的交互式会话。

cli-anything-blender
# Enter commands interactively
# Use 'help' to see available commands
# Use 'undo' and 'redo' for history navigation

状态管理

命令行工具通过以下方式维护会话状态：

  • 撤销/重做：最多 50 级历史记录
  • 项目持久化：将项目状态保存/加载为 JSON
  • 会话跟踪：跟踪修改和变更

输出格式

所有命令支持双输出模式：

  • 人类可读（默认）：表格、颜色、格式化文本
  • 机器可读（--json 标志）：为 Agent 消费提供的结构化 JSON
# Human output
cli-anything-blender --project scene.blend-cli.json scene info

# JSON output for agents
cli-anything-blender --json --project scene.blend-cli.json scene info

预览工作流

当 Agent 需要真实的视觉检查点时，使用 Blender 预览：

# List preview recipes
cli-anything-blender --project scene.blend-cli.json preview recipes

# Capture a real preview bundle
cli-anything-blender --json --project scene.blend-cli.json preview capture --recipe quick

# Start a live preview loop
cli-anything-blender --json --project scene.blend-cli.json preview live start --recipe quick --mode poll --source-poll-ms 500

# Query current live head without rendering
cli-anything-blender --json --project scene.blend-cli.json preview live status --recipe quick

对于 Agent，preview capture --json 返回包元数据以及产物文件路径。preview live status --json 返回会话元数据以及紧凑的 trajectory_summary。

供 AI Agent 使用

以编程方式使用此命令行工具时：

  1. 始终使用 --json 标志以获得可解析的输出
  2. 检查返回码——0 表示成功，非零表示错误
  3. 解析 stderr以获取失败时的错误消息
  4. 强制要求：对所有文件操作（渲染、项目文件）使用绝对路径。相对路径在后台执行时容易失败。
  5. 使用 preview capture 或 preview live ... 进行视觉验证，而不是仅从 JSON 推断场景质量
  6. 读取返回的产物路径，如 hero.png 和 workbench.png；JSON 载荷引用文件，而不是内联图像字节
  7. 将 _bundle_dir 视为仅一个快照；对于稳定的实时历史记录，请使用 _session_dir 加 _trajectory_path
  8. 仅使用 cli-hub previews ... 来检查/打开现有预览；预览生成本身始终通过 cli-anything-blender preview ... 进行

更多信息

  • 完整文档：请参阅包中的 README.md
  • 测试覆盖率：请参阅包中的 TEST.md
  • 方法论：请参阅 cli-anything-plugin 中的 HARNESS.md

版本

1.0.0

评论

支持 Markdown