在已存在 FreeCAD 项目文件的前提下,CLI-Anything 通过 cli-anything-freecad preview 命令生成符合标准协议的预览 Bundle,并利用 cli-hub previews 工具进行可视化检查。该流程分为确认配方、捕获静态快照、启动轮询式实时预览以及使用通用客户端查看结果四个阶段,所有操作均依赖真实的 FreeCAD 后端渲染引擎。
要预览freecad项目的运行结果,首先得保证环境里装好了可用的freecadcmd,当前目录下还有合法的proj.json项目配置文件。预览的核心逻辑,是把freecad的几何状态转成标准的「预览bundle」,里面包含manifest.json元数据、summary.json摘要,还有实际的图片或者模型文件。下面我们按从环境验证到结果查看的顺序,一步步走完预览构建和校验的全流程。
下面所有步骤都针对已经存在proj.json的项目,要求安装原生FreeCAD后端。所有命令都对照官方文档核对过,演示用的是官方提供的小车案例,我们不会在本地重新搭建完整的小车模型。预览命令只会检查现有项目,不会自动生成复杂模型。
确认可用的预览配方
生成任何可视化内容之前,得先验证当前环境支持的预览配方(Recipe)。FreeCAD的CLI Harness已经内置了特定的配方,用来定义预览的生成规则,比如常用的快速四视图渲染。要是找不到对应配方,后面的快照捕获、实时预览命令都跑不起来。
直接用preview recipes命令,就能列出当前项目支持的所有预览配方。执行后会返回一个JSON列表,清晰标出所有可用的配方。
cli-anything-freecad --json -p proj.json preview recipes
跑完先看返回的配方列表里有没有quick。这一步只是能力查询,不代表当前模型已经渲染成功,真正的项目和后端合法性校验要等后面跑capture的时候才会执行。如果列表里找不到quick,就按当前版本返回的实际可用名称调整,别直接硬套示例里的命令。
捕获静态预览 Bundle
静态预览是校验当前项目状态最直接的方式。它会把FreeCAD里的模型渲染成一组固定图片,一般包含主视图、前视图、顶视图、右视图,再把所有资源打包成标准目录结构,这个目录就叫「Bundle」。
执行preview capture命令,指定对应配方就能生成快照。这里我们用官方演示里最常用的quick配方,专门用来快速验证几何形状的基础外观。
cli-anything-freecad --json -p proj.json preview capture --recipe quick
捕获完成后,直接读JSON返回的bundle路径,当前版本的返回字段可能是_bundle_dir,别靠目录名瞎猜结果位置。接着打开这个目录,检查里面的manifest.json、summary.json和渲染资产。要是JSON文件都存在但缺有效图片,就去查后端的执行日志和警告信息。
注意bundle_dir是不可变的快照,每次重新跑capture命令(除非命中缓存),都会生成一个带时间戳ID的全新Bundle目录。做静态检查直接引用这个路径就行。要是想强制跳过缓存重新渲染,可以加--force参数,常规调试一般用不上。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

启动轮询式实时预览
如果是迭代开发场景,反复手动跑capture命令效率太低。FreeCAD Harness支持Live Preview实时预览,后台会持续监控项目文件变动,自动更新预览状态,特别适合AI Agent循环或者频繁改参数的场景。
启动实时预览会话用preview live start命令,为了降低系统负载、适配文件保存的频率,推荐用poll轮询模式,设置合理的轮询间隔就行。
cli-anything-freecad --json -p proj.json preview live start --recipe quick --mode poll --source-poll-ms 500
poll模式会按你指定的间隔检查项目变动,检测到改动后才会更新会话对应的预览。这里设置的间隔不代表每500毫秒一定能完成一次渲染,实际更新速度还要看模型复杂度、后端执行效率和缓存状态。改完项目记得先保存,再看状态记录有没有推进。
实时预览运行期间,系统会维护两个核心对象:
1. Session(会话):用_session_dir标识,存着当前最新状态的指针。
2. Trajectory(轨迹):记录每次命令执行到预览发布的完整历史,存在_trajectory_path指向的文件里。
想确认实时预览是不是正常运行,又不想触发额外的渲染开销,可以用status命令。
cli-anything-freecad --json -p proj.json preview live status --recipe quick
这个命令只会返回轻量的JSON数据,包含_session_dir、当前Bundle ID和最新的发布原因,是Agent判断运行进度的最优方式。不需要实时更新的时候一定要停掉会话,释放系统资源。
cli-anything-freecad --json -p proj.json preview live stop --recipe quick
执行停止命令不会删掉已经生成的Bundle文件,只会终止后台监听进程,把会话状态改成stopped。

使用通用客户端检查预览结果
CLI-Anything的设计逻辑是把「生成」和「查看」完全分开。cli-anything-freecad负责调用FreeCAD生成标准的Bundle或者Session数据,cli-hub作为通用的预览消费端,提供可视化检查界面。也就是说你不用专门为FreeCAD写独立的查看器代码,直接用统一的协议接口就行。
从实际输出获取路径:静态 capture 使用返回的 _bundle_dir 或 bundle_dir,live status 使用 _session_dir。字段和路径以当前实现为准,不能把文档里的示例目录当成本轮生成的位置。
假设你拿到的静态Bundle路径是/path/to/your/bundle_dir,就可以用下面的命令做校验:
文本详细信息检查
用inspect命令打印Bundle的元数据、摘要和资产清单,就能验证Manifest结构是不是符合协议规范。
cli-hub previews inspect /path/to/your/bundle_dir
输出内容会显示headline标题、facts事实数据(比如分辨率、配方类型)还有warnings警告信息。一切正常的话,你能看到hero.png和其他视图资产的完整列表。
生成 HTML 报告
想要更直观的本地校验,可以用html命令生成一个静态HTML页面。页面会自动解析manifest.json,渲染图片画廊,有视频资源的话也会自动嵌入视频元素。
cli-hub previews html /path/to/your/bundle_dir -o preview_report.html
生成的preview_report.html直接用任意现代浏览器打开就行,页面会展示hero视角的高清大图和其他gallery视图。这个方法特别适合没法跑GUI的环境,把文件传出来就能人工审核。
实时会话观察
针对Live Session,cli-hub还有更方便的观察工具。用watch命令就能在本地启一个简易HTTP服务器,自动轮询session.json的变动,同步刷新浏览器页面。
cli-hub previews watch /path/to/your/session_dir --open --poll-ms 1500
这里的--open参数执行完命令后会自动唤起默认浏览器,--poll-ms 1500用来控制查看器的刷新频率。你在另一个终端修改proj.json触发FreeCAD更新的时候,浏览器页面会自动同步最新的预览状态,连trajectory.json里记录的每一步变更历史都会同步显示。
直接打开查看
要是你只想快速看一眼某个Bundle的结果,不需要复杂交互,直接用open命令就行。
cli-hub previews open /path/to/your/bundle_dir
命令会自动生成临时HTML视图,直接在浏览器里打开展示。
理解 Bundle 与 Session 的区别
操作的时候一定要分清楚Bundle和Session的差异。Bundle是静态、不可变的目录集合,代表项目某一个时间点的快照,适合用来存档、对比差异或者做最终交付。Session是动态的上下文容器,关联了一系列按时间排序的Bundle,通过trajectory.json记录从初始状态到当前状态的完整演变过程。
trajectory.json用来记录命令和预览的对应关系,session.json指向当前生效的预览。官方演示里会把建模命令、多个视角和历史状态放在一起展示,但别默认所有包装器都自带完全一样的界面。所有操作优先以实际返回的路径、状态和资产为准,再使用当前查看器支持的功能。












