尧图网页设计 
用命令行驱动 Blender 3D 场景CLI-Anything 的 JSON 场景描述与 bpy 脚本生成式渲染实践【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything本篇技术指南围绕 CLI-Anything 仓库中 Blender Agent Harness 展开讲解如何在不打开 Blender GUI、甚至不需要本机安装 Blender 的前提下以「JSON 场景描述 bpy 脚本生成」的方式完成 3D 场景的建模、材质、修改器、相机灯光、动画与渲染全流程。读完本文你将掌握一套可脚本化、可被 Agent 调用的有状态 Blender CLI 用法包括 JSON 场景格式、渲染管线、撤销/重做会话以及实时预览机制可直接用于自动化批量出图与 Agent 工作流集成。一、设计背景为什么用 JSON 场景而非直接操作 .blendBlender 的原生工程格式.blend是自定义二进制格式无法像普通文本文件那样在命令行中被稳定地解析、差分与合并。正如 harness 分析文档 所述CLI-Anything 对 Blender 采取的 CLI 策略是用 JSON 文本维护全部场景状态再按需将 JSON 翻译为完整的 Blender Pythonbpy脚本交给 Blender 后台执行渲染。这一分层带来三个直接影响使用的特性场景编辑零依赖新增对象、调配材质、添加修改器等操作全部发生在 JSON 层面不要求本机安装 Blender全量还原、无翻译损耗生成的 bpy 脚本完整重建 JSON 描述的场景再渲染。由于 bpy 本身就是 Blender 的原生 API从 JSON 到渲染结果不存在功能裁剪这也是该方案渲染缺口风险极低的原因见 BLENDER.md 的Rendering Gap: Low Risk分析可审计、可回滚场景文件是文本 JSON天然支持 Git 跟踪、机器读取与程序化 diff配合会话层快照可实现撤销/重做。二、安装与环境准备本 harness 仅依赖两个 Python 库场景编辑本身不需要安装 Blender# 在 agent-harness 目录下安装基础依赖 pip install click prompt_toolkit # 说明场景编辑不需要安装 Blender # 仅当你需要执行生成的渲染脚本渲染出图时才需要本机有 Blender从源码结构看包布局为cli_anything.blender因此除文档中的历史示例python3 -m cli.blender_cli之外在当前仓库中以模块方式运行的等效命令是python3 -m cli_anything.blender.blender_cli仓库同时在 blender/agent-harness 下提供了 setup.py而 blender_cli.py 与 preview.py 中均通过shutil.which(cli-anything-blender)探测入口命令说明安装后还提供cli-anything-blender控制台命令预览相关的指令建议使用该入口详见实时预览一节。渲染后端 blender_backend.py 会通过 PATH 查找blender可执行文件找不到时会抛出异常并给出安装提示# Debian/Ubuntu apt install blender # macOS brew install --cask blender需要渲染时find_blender 会执行blender --version探测版本后续渲染命令统一为blender --background --python script.py。三、15 分钟快速上手纯命令行构建一个可渲染场景下面的命令序列完整复现了 README 快速开始 的示例流程从空场景一路做到出渲染脚本覆盖建模、材质、修改器、相机、灯光五大类操作# 1) 新建场景并落盘 python3 -m cli.blender_cli scene new --name MyScene -o scene.json # 2) 添加基础体立方体 放置在 (3,0,1) 的球体 python3 -m cli.blender_cli --project scene.json object add cube --name Box python3 -m cli.blender_cli --project scene.json object add sphere --name Ball -l 3,0,1 # 3) 创建材质并把它指定给 0 号对象材质 / 对象均按列表索引引用 python3 -m cli.blender_cli --project scene.json material create --name Red --color 1,0,0,1 python3 -m cli.blender_cli --project scene.json material assign 0 0 # 4) 给 0 号对象叠加细分曲面修改器级别为 2 python3 -m cli.blender_cli --project scene.json modifier add subdivision_surface -o 0 -p levels2 # 5) 添加相机与灯光相机位于 (7,-6,5) 朝向 (63,0,46) 度并设为活动相机 python3 -m cli.blender_cli --project scene.json camera add -l 7,-6,5 -r 63,0,46 --active python3 -m cli.blender_cli --project scene.json light add sun -r -45,0,30 # 6) 保存场景 JSON python3 -m cli.blender_cli --project scene.json scene save # 7) 生成渲染脚本产出 _render_script.py 的绝对路径 python3 -m cli.blender_cli --project scene.json render execute render.png --overwrite # 8) 本机装有 Blender 时执行该脚本完成渲染 blender --background --python /path/to/_render_script.py需要理解的关键点--project全局开关它把整个命令会话绑定到一个场景文件上。入口处 blender_cli.py 会先检查当前进程内会话是否已挂载项目未挂载则调用scene.open_scene载入之后的每个子命令都作用在这个场景上object add的类型白名单cube | sphere | cylinder | cone | plane | torus | monkey | empty八种源码中以click.Choice强制校验见 blender_cli.py 中object add的定义--param keyvalue可重复传参修改器、网格参数均采用该模式解析器会把带小数点的值转成float否则转成int失败则保留字符串逗号分隔向量-l 3,0,1、-r 63,0,46、--color 1,0,0,1等位置、旋转、颜色参数统一使用x,y,z/R,G,B,A的逗号分隔写法索引寻址对象、材质、相机、灯光均以列表顺序从 0 开始作为身份引用例如material assign 0 0表示把 0 号材质赋给 0 号对象自动保存每个一次性命令结束后若会话状态被修改result_callback会自动把场景写回磁盘--dry-run可跳过落盘。3.1 新建场景时的可用参数scene new在 CLI 层暴露以下选项均能在 scene.py 的create_scene中看到对应校验逻辑选项默认值说明--name / -nuntitled场景名称会写入 JSON 顶层name--profile / -p无直接套用内置场景预设见下文--resolution-x / -rx1920水平分辨率像素必须为正整数--resolution-y / -ry1080垂直分辨率像素必须为正整数--engineCYCLES渲染引擎仅限CYCLES/EEVEE/WORKBENCH--samples128采样数必须为正整数--fps24帧率必须为正整数--output / -o无场景文件保存路径引擎非法、分辨率为 0、samples 小于 1 等都会在create_scene内直接抛出ValueErrorCLI 层经handle_error统一捕获并按 JSON 或文本格式报告详见JSON 输出模式一节。3.2 内置场景预设scene profilesscene new --profile与scene profiles列出当前 scene.py 中定义的 10 个常用预设覆盖从快速预览到印刷输出的常见分辨率预设分辨率引擎采样FPS典型用途default1920×1080CYCLES12824默认出图preview960×540EEVEE1624快速预览hd720p1280×720CYCLES6424高清 720phd1080p1920×1080CYCLES12824全高清4k3840×2160CYCLES256244K 输出instagram_square1080×1080EEVEE6430方形社交图youtube_short1080×1920EEVEE6430竖屏短视频product_render2048×2048CYCLES51224产品渲染animation_preview1280×720EEVEE1624动画预览print_a4_300dpi2480×3508CYCLES25624A4 300DPI 印刷预设本质上是对分辨率/引擎/采样/FPS 的一组赋值传了--profile时预设值覆盖默认值但create_scene中预设只影响上述四类字段。四、九大命令组参考手册下面按 README 的 Command Groups 章节 原样保留全部命令清单并结合 blender_cli.py 补充关键参数与作用对象方便作为速查手册使用。4.1 场景管理scenescene new - 创建新场景可带 --profile/--engine/--resolution-x/--samples/--fps 与 -o 落盘 scene open - 打开已有场景文件校验 version 与 scene 键存在 scene save - 保存当前场景未指定路径时写回 --project 绑定路径 scene info - 输出场景摘要单位系统、帧区间、fps、渲染配置、各实体数量与对象简表 scene profiles - 列出全部内置场景预设 scene json - 直接打印原始场景 JSON等价于 cat 场景文件值得补充的是scene open会做结构校验文件必须含version与scene两个顶层键否则视为非法场景文件抛错见 scene.py 的open_scene。4.2 对象管理objectobject add - 添加基础体cube/sphere/cylinder/cone/plane/torus/monkey/empty 支持 --name、--location x,y,z、--rotation x,y,z角度、--scale x,y,z、 --param keyvalue可重复、--collection 指定集合 object remove - 按下标删除对象 object duplicate - 复制对象 object transform - 变换--translate dx,dy,dz / --rotate rx,ry,rz角度 / --scale sx,sy,sz object set - 设置对象属性name、visible、location、rotation、scale、parent 等 object list - 列出全部对象 object get - 获取单个对象的详细信息object transform只对传入的维度做累加修改未传的维度保持不变object set对向量型属性会自动把逗号分隔字符串解析为浮点列表见 blender_cli.pyobject set的实现。4.3 材质管理materialmaterial create - 新建 Principled BSDF 材质--name、--color R,G,B,A0-1 区间、 --metallic默认 0.0、--roughness默认 0.5、--specular默认 0.5 material assign - 把材质赋给对象material assign 材质下标 对象下标 material set - 修改材质属性color、metallic、roughness、specular、alpha、 emission_color、use_backface_culling 等 material list - 列出全部材质 material get - 获取单个材质详情material set对color/emission_color使用逗号分隔 RGBA 数组对use_backface_culling原样透传布尔其余标量属性尝试转成浮点。4.4 修改器管理modifiermodifier list-available - 列出可用修改器可按 --category generate|deform 过滤 modifier info - 查看某个修改器的参数说明 modifier add - 添加修改器modifier add type -o 对象下标 -p keyvalue ... modifier remove - 移除指定修改器默认作用于 0 号对象 modifier set - 设置修改器参数 modifier list - 列出某对象上的修改器从 BLENDER.md 的修改器注册表可知当前内置 8 类修改器并带参数校验subdivision_surfacelevels、render_levelsmirroraxis_x/y/z、use_bisectarraycount、offsetbevelwidth、segmentssolidifythickness、offsetdecimateratio、typebooleanoperationunion/intersect/difference、objectsmoothfactor、iterations4.5 相机管理cameracamera add - 添加相机--location、--rotation角度、--type PERSP|ORTHO|PANO默认 PERSP、 --focal-length默认 50.0mm、--active 直接设为活动相机 camera set - 设置相机属性location、rotation、focal_length 等 camera set-active - 将某相机设为活动相机决定渲染视点 camera list - 列出全部相机4.6 灯光管理lightlight add - 添加灯光类型仅限 point|sun|spot|area--name、--location、--rotation、 --color R,G,B、--power/-w 功率能量 light set - 设置灯光属性location、rotation、color 及类型专属参数 light list- 列出全部灯光4.7 动画animationanimation keyframe - 打关键帧animation keyframe 对象 帧号 属性 值 -i 指定插值 CONSTANT|LINEAR|BEZIER默认 BEZIER向量属性用逗号分隔 animation remove-keyframe - 删除关键帧可加 --prop 只删特定属性否则删除该帧全部关键帧 animation frame-range - 设置动画帧区间animation frame-range start end animation fps - 设置帧率 animation list-keyframes - 列出对象关键帧可用 --prop 过滤4.8 渲染renderrender settings - 配置渲染设置详见第六章参数表支持 --preset 一键套用预设 render info - 查看当前渲染设置含分辨率缩放后的有效分辨率 render presets - 列出全部渲染预设 render execute - 渲染场景生成 bpy 脚本文件并返回其绝对路径--frame 指定单帧、 --animation 渲染整段动画、--overwrite 允许覆盖已存在输出 render script - 只把生成的 bpy 脚本打印到 stdout不写文件4.9 会话sessionsession status - 会话状态是否挂载项目、路径、修改标记、undo/redo 栈深度、场景名 session undo - 撤销上一步操作返回被撤销操作的描述 session redo - 重做 session history - 列出撤销历史含操作描述与时间戳五、JSON 场景格式详解场景文件是一个自描述的 JSON 文档README 给出的结构 如下它与create_scene产出的真实结构完全对应{ version: 1.0, name: scene_name, scene: { fps: 24, frame_start: 1, frame_end: 250, ... }, render: { engine: CYCLES, resolution_x: 1920, samples: 128, ... }, world: { background_color: [0.05, 0.05, 0.05], ... }, objects: [ { name: Cube, mesh_type: cube, location: [0,0,0], ... } ], materials: [ { name: Material, color: [0.8,0.8,0.8,1], ... } ], cameras: [ { name: Camera, focal_length: 50, ... } ], lights: [ { name: Light, type: POINT, power: 1000, ... } ], collections: [ { name: Collection, objects: [0, 1] } ], metadata: { created: ..., modified: ..., software: blender-cli 1.0 } }对照 scene.py 中create_scene的完整初始化各顶层键的默认与含义如下顶层键默认内容说明version1.0场景格式版本scene open校验存在性name命令行--name场景名作为scene info的名称来源sceneunit_systemmetric、unit_scale1.0、frame_start1、frame_end250、frame_current1、fps24时间线与单位设置被animation frame-range/fps修改renderengineCYCLES、resolution_x1920、resolution_y1080、resolution_percentage100、samples128、use_denoisingTrue、film_transparentFalse、output_formatPNG、output_path./render/渲染配置由render settings修改worldbackground_color[0.05,0.05,0.05]、use_hdriFalse、hdri_pathnull、hdri_strength1.0世界环境与背景色objects[]对象数组含name、mesh_type、location等materials[]Principled BSDF 材质数组cameras[]相机数组lights[]灯光数组collections一个默认Collectionid0空对象列表visibleTrue集合通过对象下标引用成员metadata创建/修改 ISO 时间戳与softwareblender-cli 1.0每次scene save刷新modified六、渲染管线从 JSON 场景到成图的完整链路6.1 三段式工作流因为.blend是二进制harness 把渲染拆成三段可独立验证的步骤README 原文 与 render.py 的实现一致用 CLI 命令编辑场景 —— 所有修改都落到 JSON用render execute或render script生成一个完整 bpy 脚本用blender --background --python script.py执行脚本完成渲染。render execute生成脚本时会先把输出路径转为绝对路径再写入脚本——这是有意的设计Blender 后台进程的工作目录可能与 CLI 不同绝对路径可避免找不到输出文件见 render.py 的注释。生成的脚本固定命名为输出同目录下的_render_script.py并返回{script_path, output_path, engine, resolution, samples, format, animation, command}结构其中command就是可直接执行的 Blender 命令行。6.2 生成的 bpy 脚本做了什么utils/bpy_gen.py 的generate_full_script按固定顺序拼装脚本大致对应 JSON 到 Blender 的翻译表import bpy后清空默认场景全选删除写入场景设置单位系统、scale_length、frame_start/end/current、render.fps写入渲染设置引擎、分辨率、resolution_percentage、film_transparentCycles 下写scene.cycles.samples与use_denoisingEEVEE 下写scene.eevee.taa_render_samples写入世界背景与 HDRI 设置创建全部材质Principled BSDF 各通道属性按 JSON 创建所有对象网格类型与变换处理对象父子关系创建相机与灯光并配置参数写入动画关键帧设置输出路径并触发渲染单帧或整段动画。6.3 后台渲染执行细节blender_backend.py 的render_scene_headless把脚本写入临时文件后调用render_script执行并处理一个现实坑点Blender 单帧渲染会在输出文件名后追加帧号例如render.png实际产出render0001.png后端会依次尝试0001/0000/1后缀来定位真实产物。渲染失败或未产出文件都会抛出带 stderr 尾部的错误信息便于诊断。6.4 渲染参数与预设render settings支持的完整参数如下含 render.py 中的校验规则参数取值范围/格式校验--engineCYCLES/EEVEE/WORKBENCH白名单--resolution-x / -ry正整数像素需 ≥ 1--resolution-percentage整数 1–100区间校验--samples正整数需 ≥ 1--denoising / --no-denoising布尔开关—--transparent / --no-transparent布尔开关透明胶片背景—--formatPNG/JPEG/BMP/TIFF/OPEN_EXR/HDR/FFMPEG白名单校验--output-path文件或目录路径—--preset见下方预设表未知预设报错预设机制是先套预设、再叠加单项覆盖传入--preset时先整体赋值随后其他显式参数可覆盖预设值。内置 7 个预设render.py 中RENDER_PRESETS预设引擎采样其他cycles_defaultCYCLES128降噪、100%cycles_highCYCLES512降噪、100%cycles_previewCYCLES32降噪、50% 分辨率eevee_defaultEEVEE64100%eevee_highEEVEE256100%eevee_previewEEVEE1650% 分辨率workbenchWORKBENCH1扁平/工作室着色预览注意 render.py 中cycles_high实际采样数为 512harness 分析文档 BLENDER.md 所列 4096 为早期设计值以源码当前实现为准。render info还会额外给出按resolution_percentage折算的effective_resolution用于估算最终像素尺寸。6.5 动画渲染render execute --animation会渲染scene.frame_start至scene.frame_end的整段区间结果返回frame_range不带--frame也不带--animation时默认渲染frame_current对应帧。输出文件已存在且未加--overwrite时会抛出FileExistsError防止误覆盖。七、无头场景的机器可读交互JSON 输出模式所有命令都接受全局开关--json把结果以结构化 JSON 输出到 stdout供 Agent、脚本或其他程序消费python3 -m cli.blender_cli --json scene new -o scene.json python3 -m cli.blender_cli --json --project scene.json object listJSON 模式的实现要点可以从 blender_cli.py 确认输出统一走output()函数开启--json时用json.dumps(data, indent2, defaultstr)输出否则以人类可读的缩进字典/列表打印错误也结构化handle_error装饰器把异常转换为{error: 消息, type: 异常类型名}type取值包括file_not_found、file_exists以及 ValueError/IndexError/RuntimeError 的类名便于上层程序做分支判断一次性命令模式下错误会sys.exit(1)而 REPL 内错误不退出进程。八、有状态会话与撤销 / 重做CLI-Anything 的 Blender harness 是一个有状态CLI同一进程内维护一个全局Session对象跨命令保持场景上下文。会话层实现在 core/session.py核心机制快照式撤销每个会修改场景的命令在变更前调用sess.snapshot(操作描述)把当前完整场景做copy.deepcopy推入撤销栈最多保留MAX_UNDO 50步再执行变更undo时把当前态压入重做栈、弹出撤销栈恢复场景redo反向操作。因此session undo能精确回到上一步操作之前的完整 JSON 状态修改标记与自动保存快照会把_modified置为 True一次命令结束后入口的result_callback检查到有项目、被修改且非 dry-run 时自动save_session()落盘见 blender_cli.py 顶部装饰器定义保证每条命令结束时磁盘文件与服务端状态一致原子落盘save_session使用_locked_save_json先独占加锁fcntl.flock非 POSIX 平台自动降级再截断写入避免并发进程写坏场景文件保存同时刷新metadata.modified时间戳状态可查session status输出has_project/project_path/modified/undo_count/redo_count/scene_namesession history按时间倒序列出每条操作描述。这意味着在无人值守的批处理脚本里Agent 可以先session status确认载入状态在连续object add、transform之后用一条session undo安全回退不必担心破坏磁盘上的中间产物。九、预览与实时预览Preview Live Preview9.1 预览包preview bundle捕获Blender harness 在通用命令组之外还暴露preview命令组用于产出真实的 Blender 渲染预览图并打包为可复查的 bundle# 捕获真实预览包quick 配方 cli-anything-blender --json --project scene.blend-cli.json preview capture --recipe quick # 查询该场景最新一份预览包的清单 cli-anything-blender --json --project scene.blend-cli.json preview latest --recipe quick # 查看可用的预览配方 cli-anything-blender --json --project scene.blend-cli.json preview recipescore/preview.py 中的RECIPES定义了唯一内置配方quick主渲染使用eevee_preview预设生成hero.png辅以workbench预设、50% 分辨率生成workbench.png。前者的用途是检查着色、材质与取景后者以结构视角暴露轮廓与形体问题二者构成一套互补的快速审查素材。捕获过程有若干值得注意的自动化细节均可在 preview.py 源码确认自动补景若场景没有相机会注入PreviewCamera位置 [6.5, -6.5, 4.75]旋转 [63, 0, 46]焦距 45mm并设为活动相机没有灯光则注入PreviewSun旋转 [42, 0, 32]功率 2.2。这是为了让预览在裸场景下也可读同时会以 warning 形式记录注入行为指纹缓存去重捕获前计算项目内容指纹命中缓存时直接返回既有 bundlecached: true--force可绕过缓存强制重渲产物自描述最终 manifest 记录场景名、当前帧、两张图的有效分辨率、对象/材质/相机/灯光数量等指标并把建议的下一步检查动作inspect hero.png / workbench.png写入next_actions存储约定预览默认落在场景文件同级的.cli-anything/previews/blender/可用--root-dir覆盖bundle 目录一旦生成即为不可变。9.2 实时预览会话live sessionpreview live把预览升级为可持续追踪的会话# 启动 poll 模式的实时预览会话每 500ms 轮询源场景文件变化 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 # 手动向会话推入一份新渲染 cli-anything-blender preview live push --recipe quick # 结束会话保留产物只标记 stopped cli-anything-blender preview live stop --recipe quick实时会话在磁盘上持久化三类数据session.json会话元数据含协议版本preview-live/v1、status、live_mode、refresh_hint_ms、轮询后台进程poller的 PID/心跳、源文件指纹状态、历史摘要以及可复制的 inspect/html/watch 命令不可变的 bundle 目录历史最多保留最近 12 个 bundle配合current符号链接指向当前最新一份trajectory.json把每次发布live-start/manual-push/auto-poll追加为带 step id 的时间线步骤记录发布原因与对应的 bundle。--mode决定会话行为poll模式下preview.py 的run_live_poller会以--source-poll-ms指定的间隔轮询对源场景文件做指纹比对一旦发现内容变化就自动重新渲染并发布新 bundle心跳与错误信息写回session.json的poller与source_state段manual模式则只在显式preview live push时更新。轮询间隔下限为 250ms低于该值会被钳制。注意 poll 模式要求场景已经落盘为文件否则无从比对指纹源码中对此有显式校验。查看已发布预览的配套工具是仓库根级cli-hubcli-hub previews inspect /path/to/bundle-or-session # 查看 bundle/会话清单 cli-hub previews html /path/to/bundle-or-session -o page.html # 导出 HTML 页 cli-hub previews watch /path/to/session --open # 实时监听并自动打开 cli-hub previews open /path/to/bundle-or-session # 在浏览器打开blender_cli.py 的_spawn_live_viewer会探测cli-hub是否在 PATH 上存在时以独立进程拉起 watch 命令preview live start --open即对应这一行为。十、交互式 REPL 模式对需要人机协同探索的场景harness 还内置了 REPL# 无项目直接进入 python3 -m cli.blender_cli repl # 挂载已有项目进入 python3 -m cli.blender_cli repl --project scene.json进入后每一行都会被当作一条 CLI 命令执行输入行先经shlex.split解析因此带空格的引号参数可用随后递归调用主 CLI 分发help打印命令速览quit/exit退出。REPL 场景下执行session类命令可以边操作边观察_modified标记状态栏提示文件是否已保存。整个循环、命令速查表与彩蛋提示实现在 blender_cli.py 的repl命令以及 utils/repl_skin.py。十一、测试与仓库源码结构11.1 运行测试测试从agent-harness目录运行# 运行全部测试 python3 -m pytest cli_anything/blender/tests/ -v # 仅单测合成数据场景覆盖 100 用例 python3 -m pytest cli_anything/blender/tests/test_core.py -v # 仅 E2E脚本生成、往返校验、完整工作流 python3 -m pytest cli_anything/blender/tests/test_full_e2e.py -v # 带覆盖率/精简回溯运行 python3 -m pytest cli_anything/blender/tests/ -v --tbshortREADME 的 Running Tests 章节 中说明了测试分层test_core.py面向核心模块做纯内存的合成数据单测100 用例无需 Blendertest_full_e2e.py验证脚本生成、往返一致性与端到端工作流。仓库另有 test_bpy_gen.py 专门对生成的 bpy 脚本做语法合法性校验这与生成脚本必须是可执行 Python这一约束直接对应。11.2 源码结构对照README 的 Architecture 章节 给出了历史cli/布局按当前仓库实际落盘结构cli_anything/blender包内划分为cli_anything/blender/ ├── __init__.py ├── __main__.py # 支持 python3 -m cli_anything.blender.blender_cli ├── blender_cli.py # CLI 入口Click 命令 全局会话 REPL ├── core/ # 九大业务域 预览 │ ├── scene.py # 场景创建/打开/保存、场景预设、信息摘要 │ ├── objects.py # 对象增删改查与变换 │ ├── materials.py # Principled BSDF 材质管理 │ ├── modifiers.py # 修改器注册表与参数设置 │ ├── lighting.py # 相机 灯光 │ ├── animation.py # 关键帧与时间线 │ ├── render.py # 渲染设置、预设、bpy 脚本生成入口 │ ├── preview.py # 预览配方、bundle 捕获、live 会话与轮询 │ └── session.py # 有状态会话快照撤销/重做、原子保存 ├── utils/ │ ├── bpy_gen.py # JSON → bpy 脚本翻译器 │ ├── blender_backend.py # 无头 Blender 调用、产物校验 │ ├── preview_bundle.py # bundle/轨迹/清单/指纹工具函数 │ └── repl_skin.py # REPL 皮肤横幅、提示符、帮助 ├── skills/SKILL.md # 面向 Agent 的技能描述 └── tests/ # 单测、E2E 与 bpy 语法测试 测试说明各模块职责单一、边界清晰业务域只操作传入的project字典状态与持久化收敛在Session与 Blender 的全部接触点集中在bpy_gen与blender_backend两个 utils 中便于在无 Blender 环境做纯逻辑验证。十二、在 Agent 工作流中如何组合使用综合以上能力一个典型的 Agent 渲染任务可以这样编排全部可无头执行scene new --profile hd1080p -o job.json创建带正确分辨率/引擎的工程多次object add、object transform、material create/assign、modifier add -p ...精确装配场景camera add ... --active与light add sun ...完成取景与照明需要过程可视化时启动preview live start --mode poll边改边自动产出hero.png/workbench.png供上层 Agent 通过cli-hub previews inspect复核画面最终render execute out.png --overwrite单帧或render execute --animation动画拿到脚本后交给blender --background --python _render_script.py执行全程可通过--json让每一步的输出与错误都可被程序解析用session undo/redo对不满意的操作安全回退。这套「JSON 状态机 原生 API 脚本生成」的组合让 Blender 从一个需要图形界面的桌面应用变为一个可被 CLI 与 Agent 全自动驱动的渲染后端——这正是 CLI-Anything 仓库中 Blender harness 的核心价值所在。延伸阅读本文档主体blender/agent-harness/cli_anything/blender/README.md领域分析与渲染风险评估blender/agent-harness/BLENDER.mdAgent 技能描述blender/agent-harness/cli_anything/blender/skills/SKILL.md测试说明blender/agent-harness/cli_anything/blender/tests/TEST.md【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用命令行驱动 Blender 3D 场景：CLI-Anything 的 JSON 场景描述与 bpy 脚本生成式渲染实践
用命令行驱动 Blender 3D 场景CLI-Anything 的 JSON 场景描述与 bpy 脚本生成式渲染实践【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything本篇技术指南围绕 CLI-Anything 仓库中 Blender Agent Harness 展开讲解如何在不打开 Blender GUI、甚至不需要本机安装 Blender 的前提下以「JSON 场景描述 bpy 脚本生成」的方式完成 3D 场景的建模、材质、修改器、相机灯光、动画与渲染全流程。读完本文你将掌握一套可脚本化、可被 Agent 调用的有状态 Blender CLI 用法包括 JSON 场景格式、渲染管线、撤销/重做会话以及实时预览机制可直接用于自动化批量出图与 Agent 工作流集成。一、设计背景为什么用 JSON 场景而非直接操作 .blendBlender 的原生工程格式.blend是自定义二进制格式无法像普通文本文件那样在命令行中被稳定地解析、差分与合并。正如 harness 分析文档 所述CLI-Anything 对 Blender 采取的 CLI 策略是用 JSON 文本维护全部场景状态再按需将 JSON 翻译为完整的 Blender Pythonbpy脚本交给 Blender 后台执行渲染。这一分层带来三个直接影响使用的特性场景编辑零依赖新增对象、调配材质、添加修改器等操作全部发生在 JSON 层面不要求本机安装 Blender全量还原、无翻译损耗生成的 bpy 脚本完整重建 JSON 描述的场景再渲染。由于 bpy 本身就是 Blender 的原生 API从 JSON 到渲染结果不存在功能裁剪这也是该方案渲染缺口风险极低的原因见 BLENDER.md 的Rendering Gap: Low Risk分析可审计、可回滚场景文件是文本 JSON天然支持 Git 跟踪、机器读取与程序化 diff配合会话层快照可实现撤销/重做。二、安装与环境准备本 harness 仅依赖两个 Python 库场景编辑本身不需要安装 Blender# 在 agent-harness 目录下安装基础依赖 pip install click prompt_toolkit # 说明场景编辑不需要安装 Blender # 仅当你需要执行生成的渲染脚本渲染出图时才需要本机有 Blender从源码结构看包布局为cli_anything.blender因此除文档中的历史示例python3 -m cli.blender_cli之外在当前仓库中以模块方式运行的等效命令是python3 -m cli_anything.blender.blender_cli仓库同时在 blender/agent-harness 下提供了 setup.py而 blender_cli.py 与 preview.py 中均通过shutil.which(cli-anything-blender)探测入口命令说明安装后还提供cli-anything-blender控制台命令预览相关的指令建议使用该入口详见实时预览一节。渲染后端 blender_backend.py 会通过 PATH 查找blender可执行文件找不到时会抛出异常并给出安装提示# Debian/Ubuntu apt install blender # macOS brew install --cask blender需要渲染时find_blender 会执行blender --version探测版本后续渲染命令统一为blender --background --python script.py。三、15 分钟快速上手纯命令行构建一个可渲染场景下面的命令序列完整复现了 README 快速开始 的示例流程从空场景一路做到出渲染脚本覆盖建模、材质、修改器、相机、灯光五大类操作# 1) 新建场景并落盘 python3 -m cli.blender_cli scene new --name MyScene -o scene.json # 2) 添加基础体立方体 放置在 (3,0,1) 的球体 python3 -m cli.blender_cli --project scene.json object add cube --name Box python3 -m cli.blender_cli --project scene.json object add sphere --name Ball -l 3,0,1 # 3) 创建材质并把它指定给 0 号对象材质 / 对象均按列表索引引用 python3 -m cli.blender_cli --project scene.json material create --name Red --color 1,0,0,1 python3 -m cli.blender_cli --project scene.json material assign 0 0 # 4) 给 0 号对象叠加细分曲面修改器级别为 2 python3 -m cli.blender_cli --project scene.json modifier add subdivision_surface -o 0 -p levels2 # 5) 添加相机与灯光相机位于 (7,-6,5) 朝向 (63,0,46) 度并设为活动相机 python3 -m cli.blender_cli --project scene.json camera add -l 7,-6,5 -r 63,0,46 --active python3 -m cli.blender_cli --project scene.json light add sun -r -45,0,30 # 6) 保存场景 JSON python3 -m cli.blender_cli --project scene.json scene save # 7) 生成渲染脚本产出 _render_script.py 的绝对路径 python3 -m cli.blender_cli --project scene.json render execute render.png --overwrite # 8) 本机装有 Blender 时执行该脚本完成渲染 blender --background --python /path/to/_render_script.py需要理解的关键点--project全局开关它把整个命令会话绑定到一个场景文件上。入口处 blender_cli.py 会先检查当前进程内会话是否已挂载项目未挂载则调用scene.open_scene载入之后的每个子命令都作用在这个场景上object add的类型白名单cube | sphere | cylinder | cone | plane | torus | monkey | empty八种源码中以click.Choice强制校验见 blender_cli.py 中object add的定义--param keyvalue可重复传参修改器、网格参数均采用该模式解析器会把带小数点的值转成float否则转成int失败则保留字符串逗号分隔向量-l 3,0,1、-r 63,0,46、--color 1,0,0,1等位置、旋转、颜色参数统一使用x,y,z/R,G,B,A的逗号分隔写法索引寻址对象、材质、相机、灯光均以列表顺序从 0 开始作为身份引用例如material assign 0 0表示把 0 号材质赋给 0 号对象自动保存每个一次性命令结束后若会话状态被修改result_callback会自动把场景写回磁盘--dry-run可跳过落盘。3.1 新建场景时的可用参数scene new在 CLI 层暴露以下选项均能在 scene.py 的create_scene中看到对应校验逻辑选项默认值说明--name / -nuntitled场景名称会写入 JSON 顶层name--profile / -p无直接套用内置场景预设见下文--resolution-x / -rx1920水平分辨率像素必须为正整数--resolution-y / -ry1080垂直分辨率像素必须为正整数--engineCYCLES渲染引擎仅限CYCLES/EEVEE/WORKBENCH--samples128采样数必须为正整数--fps24帧率必须为正整数--output / -o无场景文件保存路径引擎非法、分辨率为 0、samples 小于 1 等都会在create_scene内直接抛出ValueErrorCLI 层经handle_error统一捕获并按 JSON 或文本格式报告详见JSON 输出模式一节。3.2 内置场景预设scene profilesscene new --profile与scene profiles列出当前 scene.py 中定义的 10 个常用预设覆盖从快速预览到印刷输出的常见分辨率预设分辨率引擎采样FPS典型用途default1920×1080CYCLES12824默认出图preview960×540EEVEE1624快速预览hd720p1280×720CYCLES6424高清 720phd1080p1920×1080CYCLES12824全高清4k3840×2160CYCLES256244K 输出instagram_square1080×1080EEVEE6430方形社交图youtube_short1080×1920EEVEE6430竖屏短视频product_render2048×2048CYCLES51224产品渲染animation_preview1280×720EEVEE1624动画预览print_a4_300dpi2480×3508CYCLES25624A4 300DPI 印刷预设本质上是对分辨率/引擎/采样/FPS 的一组赋值传了--profile时预设值覆盖默认值但create_scene中预设只影响上述四类字段。四、九大命令组参考手册下面按 README 的 Command Groups 章节 原样保留全部命令清单并结合 blender_cli.py 补充关键参数与作用对象方便作为速查手册使用。4.1 场景管理scenescene new - 创建新场景可带 --profile/--engine/--resolution-x/--samples/--fps 与 -o 落盘 scene open - 打开已有场景文件校验 version 与 scene 键存在 scene save - 保存当前场景未指定路径时写回 --project 绑定路径 scene info - 输出场景摘要单位系统、帧区间、fps、渲染配置、各实体数量与对象简表 scene profiles - 列出全部内置场景预设 scene json - 直接打印原始场景 JSON等价于 cat 场景文件值得补充的是scene open会做结构校验文件必须含version与scene两个顶层键否则视为非法场景文件抛错见 scene.py 的open_scene。4.2 对象管理objectobject add - 添加基础体cube/sphere/cylinder/cone/plane/torus/monkey/empty 支持 --name、--location x,y,z、--rotation x,y,z角度、--scale x,y,z、 --param keyvalue可重复、--collection 指定集合 object remove - 按下标删除对象 object duplicate - 复制对象 object transform - 变换--translate dx,dy,dz / --rotate rx,ry,rz角度 / --scale sx,sy,sz object set - 设置对象属性name、visible、location、rotation、scale、parent 等 object list - 列出全部对象 object get - 获取单个对象的详细信息object transform只对传入的维度做累加修改未传的维度保持不变object set对向量型属性会自动把逗号分隔字符串解析为浮点列表见 blender_cli.pyobject set的实现。4.3 材质管理materialmaterial create - 新建 Principled BSDF 材质--name、--color R,G,B,A0-1 区间、 --metallic默认 0.0、--roughness默认 0.5、--specular默认 0.5 material assign - 把材质赋给对象material assign 材质下标 对象下标 material set - 修改材质属性color、metallic、roughness、specular、alpha、 emission_color、use_backface_culling 等 material list - 列出全部材质 material get - 获取单个材质详情material set对color/emission_color使用逗号分隔 RGBA 数组对use_backface_culling原样透传布尔其余标量属性尝试转成浮点。4.4 修改器管理modifiermodifier list-available - 列出可用修改器可按 --category generate|deform 过滤 modifier info - 查看某个修改器的参数说明 modifier add - 添加修改器modifier add type -o 对象下标 -p keyvalue ... modifier remove - 移除指定修改器默认作用于 0 号对象 modifier set - 设置修改器参数 modifier list - 列出某对象上的修改器从 BLENDER.md 的修改器注册表可知当前内置 8 类修改器并带参数校验subdivision_surfacelevels、render_levelsmirroraxis_x/y/z、use_bisectarraycount、offsetbevelwidth、segmentssolidifythickness、offsetdecimateratio、typebooleanoperationunion/intersect/difference、objectsmoothfactor、iterations4.5 相机管理cameracamera add - 添加相机--location、--rotation角度、--type PERSP|ORTHO|PANO默认 PERSP、 --focal-length默认 50.0mm、--active 直接设为活动相机 camera set - 设置相机属性location、rotation、focal_length 等 camera set-active - 将某相机设为活动相机决定渲染视点 camera list - 列出全部相机4.6 灯光管理lightlight add - 添加灯光类型仅限 point|sun|spot|area--name、--location、--rotation、 --color R,G,B、--power/-w 功率能量 light set - 设置灯光属性location、rotation、color 及类型专属参数 light list- 列出全部灯光4.7 动画animationanimation keyframe - 打关键帧animation keyframe 对象 帧号 属性 值 -i 指定插值 CONSTANT|LINEAR|BEZIER默认 BEZIER向量属性用逗号分隔 animation remove-keyframe - 删除关键帧可加 --prop 只删特定属性否则删除该帧全部关键帧 animation frame-range - 设置动画帧区间animation frame-range start end animation fps - 设置帧率 animation list-keyframes - 列出对象关键帧可用 --prop 过滤4.8 渲染renderrender settings - 配置渲染设置详见第六章参数表支持 --preset 一键套用预设 render info - 查看当前渲染设置含分辨率缩放后的有效分辨率 render presets - 列出全部渲染预设 render execute - 渲染场景生成 bpy 脚本文件并返回其绝对路径--frame 指定单帧、 --animation 渲染整段动画、--overwrite 允许覆盖已存在输出 render script - 只把生成的 bpy 脚本打印到 stdout不写文件4.9 会话sessionsession status - 会话状态是否挂载项目、路径、修改标记、undo/redo 栈深度、场景名 session undo - 撤销上一步操作返回被撤销操作的描述 session redo - 重做 session history - 列出撤销历史含操作描述与时间戳五、JSON 场景格式详解场景文件是一个自描述的 JSON 文档README 给出的结构 如下它与create_scene产出的真实结构完全对应{ version: 1.0, name: scene_name, scene: { fps: 24, frame_start: 1, frame_end: 250, ... }, render: { engine: CYCLES, resolution_x: 1920, samples: 128, ... }, world: { background_color: [0.05, 0.05, 0.05], ... }, objects: [ { name: Cube, mesh_type: cube, location: [0,0,0], ... } ], materials: [ { name: Material, color: [0.8,0.8,0.8,1], ... } ], cameras: [ { name: Camera, focal_length: 50, ... } ], lights: [ { name: Light, type: POINT, power: 1000, ... } ], collections: [ { name: Collection, objects: [0, 1] } ], metadata: { created: ..., modified: ..., software: blender-cli 1.0 } }对照 scene.py 中create_scene的完整初始化各顶层键的默认与含义如下顶层键默认内容说明version1.0场景格式版本scene open校验存在性name命令行--name场景名作为scene info的名称来源sceneunit_systemmetric、unit_scale1.0、frame_start1、frame_end250、frame_current1、fps24时间线与单位设置被animation frame-range/fps修改renderengineCYCLES、resolution_x1920、resolution_y1080、resolution_percentage100、samples128、use_denoisingTrue、film_transparentFalse、output_formatPNG、output_path./render/渲染配置由render settings修改worldbackground_color[0.05,0.05,0.05]、use_hdriFalse、hdri_pathnull、hdri_strength1.0世界环境与背景色objects[]对象数组含name、mesh_type、location等materials[]Principled BSDF 材质数组cameras[]相机数组lights[]灯光数组collections一个默认Collectionid0空对象列表visibleTrue集合通过对象下标引用成员metadata创建/修改 ISO 时间戳与softwareblender-cli 1.0每次scene save刷新modified六、渲染管线从 JSON 场景到成图的完整链路6.1 三段式工作流因为.blend是二进制harness 把渲染拆成三段可独立验证的步骤README 原文 与 render.py 的实现一致用 CLI 命令编辑场景 —— 所有修改都落到 JSON用render execute或render script生成一个完整 bpy 脚本用blender --background --python script.py执行脚本完成渲染。render execute生成脚本时会先把输出路径转为绝对路径再写入脚本——这是有意的设计Blender 后台进程的工作目录可能与 CLI 不同绝对路径可避免找不到输出文件见 render.py 的注释。生成的脚本固定命名为输出同目录下的_render_script.py并返回{script_path, output_path, engine, resolution, samples, format, animation, command}结构其中command就是可直接执行的 Blender 命令行。6.2 生成的 bpy 脚本做了什么utils/bpy_gen.py 的generate_full_script按固定顺序拼装脚本大致对应 JSON 到 Blender 的翻译表import bpy后清空默认场景全选删除写入场景设置单位系统、scale_length、frame_start/end/current、render.fps写入渲染设置引擎、分辨率、resolution_percentage、film_transparentCycles 下写scene.cycles.samples与use_denoisingEEVEE 下写scene.eevee.taa_render_samples写入世界背景与 HDRI 设置创建全部材质Principled BSDF 各通道属性按 JSON 创建所有对象网格类型与变换处理对象父子关系创建相机与灯光并配置参数写入动画关键帧设置输出路径并触发渲染单帧或整段动画。6.3 后台渲染执行细节blender_backend.py 的render_scene_headless把脚本写入临时文件后调用render_script执行并处理一个现实坑点Blender 单帧渲染会在输出文件名后追加帧号例如render.png实际产出render0001.png后端会依次尝试0001/0000/1后缀来定位真实产物。渲染失败或未产出文件都会抛出带 stderr 尾部的错误信息便于诊断。6.4 渲染参数与预设render settings支持的完整参数如下含 render.py 中的校验规则参数取值范围/格式校验--engineCYCLES/EEVEE/WORKBENCH白名单--resolution-x / -ry正整数像素需 ≥ 1--resolution-percentage整数 1–100区间校验--samples正整数需 ≥ 1--denoising / --no-denoising布尔开关—--transparent / --no-transparent布尔开关透明胶片背景—--formatPNG/JPEG/BMP/TIFF/OPEN_EXR/HDR/FFMPEG白名单校验--output-path文件或目录路径—--preset见下方预设表未知预设报错预设机制是先套预设、再叠加单项覆盖传入--preset时先整体赋值随后其他显式参数可覆盖预设值。内置 7 个预设render.py 中RENDER_PRESETS预设引擎采样其他cycles_defaultCYCLES128降噪、100%cycles_highCYCLES512降噪、100%cycles_previewCYCLES32降噪、50% 分辨率eevee_defaultEEVEE64100%eevee_highEEVEE256100%eevee_previewEEVEE1650% 分辨率workbenchWORKBENCH1扁平/工作室着色预览注意 render.py 中cycles_high实际采样数为 512harness 分析文档 BLENDER.md 所列 4096 为早期设计值以源码当前实现为准。render info还会额外给出按resolution_percentage折算的effective_resolution用于估算最终像素尺寸。6.5 动画渲染render execute --animation会渲染scene.frame_start至scene.frame_end的整段区间结果返回frame_range不带--frame也不带--animation时默认渲染frame_current对应帧。输出文件已存在且未加--overwrite时会抛出FileExistsError防止误覆盖。七、无头场景的机器可读交互JSON 输出模式所有命令都接受全局开关--json把结果以结构化 JSON 输出到 stdout供 Agent、脚本或其他程序消费python3 -m cli.blender_cli --json scene new -o scene.json python3 -m cli.blender_cli --json --project scene.json object listJSON 模式的实现要点可以从 blender_cli.py 确认输出统一走output()函数开启--json时用json.dumps(data, indent2, defaultstr)输出否则以人类可读的缩进字典/列表打印错误也结构化handle_error装饰器把异常转换为{error: 消息, type: 异常类型名}type取值包括file_not_found、file_exists以及 ValueError/IndexError/RuntimeError 的类名便于上层程序做分支判断一次性命令模式下错误会sys.exit(1)而 REPL 内错误不退出进程。八、有状态会话与撤销 / 重做CLI-Anything 的 Blender harness 是一个有状态CLI同一进程内维护一个全局Session对象跨命令保持场景上下文。会话层实现在 core/session.py核心机制快照式撤销每个会修改场景的命令在变更前调用sess.snapshot(操作描述)把当前完整场景做copy.deepcopy推入撤销栈最多保留MAX_UNDO 50步再执行变更undo时把当前态压入重做栈、弹出撤销栈恢复场景redo反向操作。因此session undo能精确回到上一步操作之前的完整 JSON 状态修改标记与自动保存快照会把_modified置为 True一次命令结束后入口的result_callback检查到有项目、被修改且非 dry-run 时自动save_session()落盘见 blender_cli.py 顶部装饰器定义保证每条命令结束时磁盘文件与服务端状态一致原子落盘save_session使用_locked_save_json先独占加锁fcntl.flock非 POSIX 平台自动降级再截断写入避免并发进程写坏场景文件保存同时刷新metadata.modified时间戳状态可查session status输出has_project/project_path/modified/undo_count/redo_count/scene_namesession history按时间倒序列出每条操作描述。这意味着在无人值守的批处理脚本里Agent 可以先session status确认载入状态在连续object add、transform之后用一条session undo安全回退不必担心破坏磁盘上的中间产物。九、预览与实时预览Preview Live Preview9.1 预览包preview bundle捕获Blender harness 在通用命令组之外还暴露preview命令组用于产出真实的 Blender 渲染预览图并打包为可复查的 bundle# 捕获真实预览包quick 配方 cli-anything-blender --json --project scene.blend-cli.json preview capture --recipe quick # 查询该场景最新一份预览包的清单 cli-anything-blender --json --project scene.blend-cli.json preview latest --recipe quick # 查看可用的预览配方 cli-anything-blender --json --project scene.blend-cli.json preview recipescore/preview.py 中的RECIPES定义了唯一内置配方quick主渲染使用eevee_preview预设生成hero.png辅以workbench预设、50% 分辨率生成workbench.png。前者的用途是检查着色、材质与取景后者以结构视角暴露轮廓与形体问题二者构成一套互补的快速审查素材。捕获过程有若干值得注意的自动化细节均可在 preview.py 源码确认自动补景若场景没有相机会注入PreviewCamera位置 [6.5, -6.5, 4.75]旋转 [63, 0, 46]焦距 45mm并设为活动相机没有灯光则注入PreviewSun旋转 [42, 0, 32]功率 2.2。这是为了让预览在裸场景下也可读同时会以 warning 形式记录注入行为指纹缓存去重捕获前计算项目内容指纹命中缓存时直接返回既有 bundlecached: true--force可绕过缓存强制重渲产物自描述最终 manifest 记录场景名、当前帧、两张图的有效分辨率、对象/材质/相机/灯光数量等指标并把建议的下一步检查动作inspect hero.png / workbench.png写入next_actions存储约定预览默认落在场景文件同级的.cli-anything/previews/blender/可用--root-dir覆盖bundle 目录一旦生成即为不可变。9.2 实时预览会话live sessionpreview live把预览升级为可持续追踪的会话# 启动 poll 模式的实时预览会话每 500ms 轮询源场景文件变化 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 # 手动向会话推入一份新渲染 cli-anything-blender preview live push --recipe quick # 结束会话保留产物只标记 stopped cli-anything-blender preview live stop --recipe quick实时会话在磁盘上持久化三类数据session.json会话元数据含协议版本preview-live/v1、status、live_mode、refresh_hint_ms、轮询后台进程poller的 PID/心跳、源文件指纹状态、历史摘要以及可复制的 inspect/html/watch 命令不可变的 bundle 目录历史最多保留最近 12 个 bundle配合current符号链接指向当前最新一份trajectory.json把每次发布live-start/manual-push/auto-poll追加为带 step id 的时间线步骤记录发布原因与对应的 bundle。--mode决定会话行为poll模式下preview.py 的run_live_poller会以--source-poll-ms指定的间隔轮询对源场景文件做指纹比对一旦发现内容变化就自动重新渲染并发布新 bundle心跳与错误信息写回session.json的poller与source_state段manual模式则只在显式preview live push时更新。轮询间隔下限为 250ms低于该值会被钳制。注意 poll 模式要求场景已经落盘为文件否则无从比对指纹源码中对此有显式校验。查看已发布预览的配套工具是仓库根级cli-hubcli-hub previews inspect /path/to/bundle-or-session # 查看 bundle/会话清单 cli-hub previews html /path/to/bundle-or-session -o page.html # 导出 HTML 页 cli-hub previews watch /path/to/session --open # 实时监听并自动打开 cli-hub previews open /path/to/bundle-or-session # 在浏览器打开blender_cli.py 的_spawn_live_viewer会探测cli-hub是否在 PATH 上存在时以独立进程拉起 watch 命令preview live start --open即对应这一行为。十、交互式 REPL 模式对需要人机协同探索的场景harness 还内置了 REPL# 无项目直接进入 python3 -m cli.blender_cli repl # 挂载已有项目进入 python3 -m cli.blender_cli repl --project scene.json进入后每一行都会被当作一条 CLI 命令执行输入行先经shlex.split解析因此带空格的引号参数可用随后递归调用主 CLI 分发help打印命令速览quit/exit退出。REPL 场景下执行session类命令可以边操作边观察_modified标记状态栏提示文件是否已保存。整个循环、命令速查表与彩蛋提示实现在 blender_cli.py 的repl命令以及 utils/repl_skin.py。十一、测试与仓库源码结构11.1 运行测试测试从agent-harness目录运行# 运行全部测试 python3 -m pytest cli_anything/blender/tests/ -v # 仅单测合成数据场景覆盖 100 用例 python3 -m pytest cli_anything/blender/tests/test_core.py -v # 仅 E2E脚本生成、往返校验、完整工作流 python3 -m pytest cli_anything/blender/tests/test_full_e2e.py -v # 带覆盖率/精简回溯运行 python3 -m pytest cli_anything/blender/tests/ -v --tbshortREADME 的 Running Tests 章节 中说明了测试分层test_core.py面向核心模块做纯内存的合成数据单测100 用例无需 Blendertest_full_e2e.py验证脚本生成、往返一致性与端到端工作流。仓库另有 test_bpy_gen.py 专门对生成的 bpy 脚本做语法合法性校验这与生成脚本必须是可执行 Python这一约束直接对应。11.2 源码结构对照README 的 Architecture 章节 给出了历史cli/布局按当前仓库实际落盘结构cli_anything/blender包内划分为cli_anything/blender/ ├── __init__.py ├── __main__.py # 支持 python3 -m cli_anything.blender.blender_cli ├── blender_cli.py # CLI 入口Click 命令 全局会话 REPL ├── core/ # 九大业务域 预览 │ ├── scene.py # 场景创建/打开/保存、场景预设、信息摘要 │ ├── objects.py # 对象增删改查与变换 │ ├── materials.py # Principled BSDF 材质管理 │ ├── modifiers.py # 修改器注册表与参数设置 │ ├── lighting.py # 相机 灯光 │ ├── animation.py # 关键帧与时间线 │ ├── render.py # 渲染设置、预设、bpy 脚本生成入口 │ ├── preview.py # 预览配方、bundle 捕获、live 会话与轮询 │ └── session.py # 有状态会话快照撤销/重做、原子保存 ├── utils/ │ ├── bpy_gen.py # JSON → bpy 脚本翻译器 │ ├── blender_backend.py # 无头 Blender 调用、产物校验 │ ├── preview_bundle.py # bundle/轨迹/清单/指纹工具函数 │ └── repl_skin.py # REPL 皮肤横幅、提示符、帮助 ├── skills/SKILL.md # 面向 Agent 的技能描述 └── tests/ # 单测、E2E 与 bpy 语法测试 测试说明各模块职责单一、边界清晰业务域只操作传入的project字典状态与持久化收敛在Session与 Blender 的全部接触点集中在bpy_gen与blender_backend两个 utils 中便于在无 Blender 环境做纯逻辑验证。十二、在 Agent 工作流中如何组合使用综合以上能力一个典型的 Agent 渲染任务可以这样编排全部可无头执行scene new --profile hd1080p -o job.json创建带正确分辨率/引擎的工程多次object add、object transform、material create/assign、modifier add -p ...精确装配场景camera add ... --active与light add sun ...完成取景与照明需要过程可视化时启动preview live start --mode poll边改边自动产出hero.png/workbench.png供上层 Agent 通过cli-hub previews inspect复核画面最终render execute out.png --overwrite单帧或render execute --animation动画拿到脚本后交给blender --background --python _render_script.py执行全程可通过--json让每一步的输出与错误都可被程序解析用session undo/redo对不满意的操作安全回退。这套「JSON 状态机 原生 API 脚本生成」的组合让 Blender 从一个需要图形界面的桌面应用变为一个可被 CLI 与 Agent 全自动驱动的渲染后端——这正是 CLI-Anything 仓库中 Blender harness 的核心价值所在。延伸阅读本文档主体blender/agent-harness/cli_anything/blender/README.md领域分析与渲染风险评估blender/agent-harness/BLENDER.mdAgent 技能描述blender/agent-harness/cli_anything/blender/skills/SKILL.md测试说明blender/agent-harness/cli_anything/blender/tests/TEST.md【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考