cli-anything-blender

cli-anything-blender 是做什麼的？

一個具狀態的指令列介面，用於 3D 場景編輯，遵循與 GIMP CLI 框架相同的模式。使用 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 輸出執行（供代理使用）
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	設定動畫的 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 標誌）：供代理使用的結構化 JSON

# 人類可讀輸出
cli-anything-blender --project scene.blend-cli.json scene info

# JSON 輸出（供代理使用）
cli-anything-blender --json --project scene.blend-cli.json scene info

預覽工作流程

當代理需要真實的視覺檢查點時，請使用 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

對代理而言，preview capture --json 會回傳套件中繼資料加上成品檔案路徑。preview live status --json 會回傳工作階段中繼資料加上精簡的 trajectory_summary。

給 AI 代理的說明

以程式方式使用此 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