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）

用法

基本命令

# 显示帮助
cli-anything-blender --help

# 启动交互式REPL模式
cli-anything-blender

# 创建新场景项目
cli-anything-blender scene new -o scene.blend-cli.json

# 使用JSON输出运行（供Agent使用）
cli-anything-blender --json --project scene.blend-cli.json scene info

REPL模式

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

cli-anything-blender
# 交互式输入命令，支持Tab补全和历史记录

命令组

Scene（场景）

场景管理命令。

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

Object Group（对象组）

3D对象管理命令。

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

Material（材质）

材质管理命令。

命令	描述
create	创建新材质
assign	将材质分配给对象
set	设置材质属性（颜色、金属感、粗糙度、镜面反射、透明度等）
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	设置动画帧率
list-keyframes	列出对象的关键帧

Render Group（渲染组）

渲染设置和输出命令。

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

Preview（预览）

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

命令	描述
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>

Session（会话）

会话管理命令。

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

示例

创建新项目

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

cli-anything-blender scene new -o myscene.blend-cli.json
# 或者使用JSON输出供程序使用
cli-anything-blender --json scene new -o myscene.blend-cli.json

交互式REPL会话

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

cli-anything-blender
# 交互式输入命令
# 使用 'help' 查看可用命令
# 使用 'undo' 和 'redo' 进行历史导航

状态管理

CLI通过以下方式维护会话状态：

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

输出格式

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

• 人类可读（默认）：表格、颜色、格式化文本
• 机器可读（--json 标志）：供Agent使用的结构化JSON

# 人类可读输出
cli-anything-blender --project scene.blend-cli.json scene info

# 供Agent使用的JSON输出
cli-anything-blender --json --project scene.blend-cli.json scene info

预览工作流

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

# 列出预览配方
cli-anything-blender --project scene.blend-cli.json preview recipes

# 捕获实时预览包
cli-anything-blender --json --project scene.blend-cli.json preview capture --recipe quick

# 启动实时预览循环
cli-anything-blender --json --project scene.blend-cli.json preview live start --recipe quick --mode poll --source-poll-ms 500

# 查询当前实时头部（不渲染）
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

以编程方式使用此CLI时：

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