cli-anything-freecad 完全指南：用 258 条命令让 FreeCAD 成为 Agent-Native 参数化建模引擎

cli-anything-freecad 完全指南：用 258 条命令让 FreeCAD 成为 Agent-Native 参数化建模引擎

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything

本篇指南聚焦 CLI-Anything 项目中的cli-anything-freecad——一个为 FreeCAD 参数化 3D CAD 建模器打造的完整命令行 harness（共 258 条命令、17 个命令组）。它把 FreeCAD 的 Part、Sketcher、PartDesign、Assembly、Mesh、TechDraw、Draft、FEM、CAM 等工作台全部封装为可脚本化、可被 AI Agent 直接消费的命令，并内置「真实预览（Preview）」「实时预览（Live Preview）」「运动渲染（Motion）」三条可视化链路。读完本文，你将掌握从安装、交互式 REPL、JSON 输出协议，到覆盖全部工作台的分组命令实战、以及 headless 导出 STEP/IGES/STL/OBJ/DXF/PDF/glTF/3MF 的完整方案，并理解其「JSON 项目文件 + FreeCAD 宏 + freecadcmd 无头执行」的底层工作原理。

cli-anything-freecad 通过 Agent 命令流驱动项目构建，并配合 Live Preview 实时监控渲染产物的典型工作流（图中为 "Curiosity" 探测车模型的 CLI 构建与实时预览界面）。

一、它是什么：从 GUI 到 Agent-Native 的 FreeCAD

cli-anything-freecad是 CLI-Anything 生态中针对 FreeCAD 的 CLI harness，核心目标是「Making Software Agent-Native」：把原本需要鼠标点击的 FreeCAD 建模流程，全部转化为确定性的命令行操作，使 LLM Agent 可以像调用普通 API 一样创建、修改和导出三维模型。

关键设计（对应 freecad/agent-harness/cli_anything/freecad/README.md）：

• 无需 GUI：所有建模指令都由 CLI 生成 FreeCAD Python 宏，再通过freecadcmd无头执行；
• 有状态会话：CLI 内部维护一个Session，通过 JSON 项目文件保存/恢复parts、sketches、bodies、materials等全部集合；
• 命令总数：17 个命令组、258 条命令，覆盖 FreeCAD 的绝大多数工作台。

从源码结构看，CLI 入口位于 freecad_cli.py：顶层cli组通过 Click 提供--json、--project/-p、--dry-run三个全局选项；未指定子命令时会自动进入 REPL 模式。全部业务逻辑按工作台拆分在 core/ 下，例如parts.py、sketch.py、body.py、assembly.py、mesh.py、techdraw.py、draft.py、fem.py、cam.py、preview.py、motion.py等 19 个模块，与文档中的命令组一一对应。

二、安装与前置条件

2.1 前置：FreeCAD 可执行文件

CLI 依赖freecadcmd（FreeCAD 控制台可执行文件）位于 PATH 中。验证方法：

freecadcmd --version

查找逻辑在 freecad_backend.py 中实现，搜索顺序为：

1. FREECAD_PATH环境变量（显式覆盖）；
2. PATH 中的freecadcmd/FreeCADCmd/freecad/FreeCAD；
3. 常见 Windows 安装目录、macOS 应用包路径、常见 Linux 路径。

若找不到，会抛出带完整安装指引的RuntimeError（Windows 安装包、brew install --cask freecad、apt install freecad、snap install freecad等）。

2.2 安装 harness

pip install -e freecad/agent-harness

setup.py（见 setup.py）会注册控制台入口cli-anything-freecad=cli_anything.freecad.freecad_cli:main，运行时依赖仅click>=8.0.0与prompt-toolkit>=3.0.0，并要求 Python >= 3.10。安装后验证：

cli-anything-freecad --help

三、基本用法与 JSON 输出协议

3.1 三种运行形态

cli-anything-freecad --json <command> # JSON 输出（供 Agent 解析） cli-anything-freecad --json -p proj.json <cmd> # 携带项目文件 cli-anything-freecad # 交互式 REPL

• 所有命令都支持--json，响应为结构化数据；错误统一返回{"error": "message"}；
• -p proj.json加载 JSON 项目文件；在一次性命令结束后，若项目被修改会自动保存（--dry-run时跳过），该逻辑在 freecad_cli.py 的_auto_save回调中实现；
• 不带子命令直接启动时，进入带提示符美化（repl_skin.py提供横幅、命令补全、未保存警告）的 REPL。

3.2 项目文件即数据库

JSON 项目文件由 document.py 创建，结构包含：version、name、units，以及parts/sketches/bodies/materials四个必需集合，和assemblies/meshes/techdraw_pages/draft_objects/measurements/surfaces/fem_analyses/cam_jobs/spreadsheets/motions等可选集合。单位系统限定为mm/m/in，并由PROFILES预置了default、metric_small、metric_large、imperial、print3d、cnc六套文档配置（见 document.py）。

3.3 错误处理约定

• 缺少 FreeCAD：给出清晰的安装指引；
• 非法类型/取值：列出合法选项；
• 索引越界：报告合法范围；
• 文件已存在：提示使用--overwrite。

四、Preview / Live Preview / Motion：三条可视化链路

FreeCAD 是当前分支中预览集成最深的一个 harness。三者定位明确：

4.1 一次性预览捕获

# 列出可用预览配方 cli-anything-freecad --json -p proj.json preview recipes # 捕获一组真实的 4 视图 bundle cli-anything-freecad --json -p proj.json preview capture --recipe quick

quick配方在 preview.py 中定义，包含等轴测 hero 视图 + 前/顶/右三个正交视图，输出 1280×960、白底的四张图：hero.png、front.png、top.png、right.png。捕获结果支持指纹缓存（--force可绕过缓存重新生成）。

4.2 轮询式实时预览

# 启动轮询模式实时预览（推荐在项目文件被反复保存时使用） cli-anything-freecad --json -p proj.json preview live start --recipe quick --mode poll --source-poll-ms 500 # 不渲染、仅查询当前实时状态 cli-anything-freecad --json -p proj.json preview live status --recipe quick # 停止实时预览发布（不删除产物） cli-anything-freecad --json -p proj.json preview live stop --recipe quick

Live Preview 会持久化三类产物：session.json、不可变的 bundle 目录、trajectory.json。preview live status --json面向 Agent 设计，除_session_dir、当前 bundle 引用、_trajectory_path外，还返回紧凑的trajectory_summary，可作为廉价的状态探针。

从实现看（freecad_cli.py）：--mode poll会通过_spawn_live_poller在后台启动preview live monitor --session-dir <dir>轮询进程，其轮询间隔默认 500ms（下限 250ms，见 preview.py）；--open则调用cli-hub previews watch --open启动浏览器查看器。--poll-ms参数用于向查看器提示刷新间隔（默认 1500ms）。

4.3 查看已发布的预览

cli-hub previews inspect /path/to/bundle-or-session cli-hub previews html /path/to/bundle-or-session -o page.html cli-hub previews watch /path/to/session --open cli-hub previews open /path/to/bundle-or-session

Agent 使用约定：cli-hub previews ...仅用于查看/打开已发布的预览，不应混入构建流程。

4.4 Motion：面向最终展示的真实帧渲染

Motion 与 Preview 相互独立，专门用于最终的真实帧渲染与展示视频：

cli-anything-freecad --json -p proj.json motion new --name spin --duration 6 --fps 24 cli-anything-freecad --json -p proj.json motion keyframe spin --time 0.0 --part 0 --position 0,0,0 cli-anything-freecad --json -p proj.json motion render-video spin output.mp4

motion new支持--camera（相机预设）、--width/--height（默认 1280×960）、--background（默认 White）、--fit-mode等参数；render-video也可用--frames-dir持久化帧序列、--keep-frames保留临时帧（详见 freecad_cli.py）。

五、258 条命令速查：按工作台分组实战

5.1 document（5 条）—— 文档管理

cli-anything-freecad --json document new --name "Part" -o proj.json cli-anything-freecad --json document new --profile print3d -o proj.json cli-anything-freecad --json -p proj.json document info cli-anything-freecad --json -p proj.json document save -o copy.json cli-anything-freecad --json document profiles

document new支持--units（mm/m/in，默认 mm）与--profile（profile 优先于 units），document info返回各集合计数（在 document.py 的get_document_info中实现，测试见 test_core.py）。

5.2 part（29 条）—— 3D 图元、布尔、变换、操作

# 图元：box, cylinder, sphere, cone, torus, wedge, helix, spiral, thread, plane, polygon_3d cli-anything-freecad --json -p p.json part add box -P length=20 -P width=15 -P height=5 cli-anything-freecad --json -p p.json part add cylinder -P radius=3 -P height=10 --position 10,7.5,0 # 操作 cli-anything-freecad --json -p p.json part boolean cut 0 1 cli-anything-freecad --json -p p.json part copy 0 cli-anything-freecad --json -p p.json part mirror 0 --plane XY cli-anything-freecad --json -p p.json part scale 0 --factor 2.0 cli-anything-freecad --json -p p.json part loft --indices 0,1,2 cli-anything-freecad --json -p p.json part sweep 0 1 cli-anything-freecad --json -p p.json part revolve 0 --axis Z --angle 360 cli-anything-freecad --json -p p.json part extrude 0 --direction 0,0,1 --length 10 cli-anything-freecad --json -p p.json part fillet-3d 0 --radius 2 cli-anything-freecad --json -p p.json part thickness 0 --thickness 1 cli-anything-freecad --json -p p.json part compound --indices 0,1,2 cli-anything-freecad --json -p p.json part section 0 --plane XY cli-anything-freecad --json -p p.json part info 0 cli-anything-freecad --json -p p.json part line-3d --start 0,0,0 --end 10,5,0 cli-anything-freecad --json -p p.json part wire --points "0,0,0;10,0,0;10,10,0"

命令约定的关键点（源自 freecad_cli.py 的参数解析器）：

• -P key=value：图元参数，值解析为浮点数；
• --position x,y,z/--rotation x,y,z（度）：_parse_vec3严格校验三元组；
• --indices 0,1,2：逗号分隔整数列表；
• --points "x,y,z;x,y,z;…"：分号分隔的多点；
• part scale的--factor支持单个数值（等比）或x,y,z（非等比）。

5.3 sketch（26 条）—— 二维约束草图

cli-anything-freecad --json -p p.json sketch new --plane XY cli-anything-freecad --json -p p.json sketch add-line 0 --start 0,0 --end 20,0 cli-anything-freecad --json -p p.json sketch add-circle 0 --center 10,10 --radius 5 cli-anything-freecad --json -p p.json sketch add-rect 0 --corner 0,0 --width 20 --height 15 cli-anything-freecad --json -p p.json sketch add-arc 0 --center 0,0 --radius 5 cli-anything-freecad --json -p p.json sketch add-ellipse 0 --center 0,0 --major-radius 10 --minor-radius 5 cli-anything-freecad --json -p p.json sketch add-polygon 0 --center 0,0 --sides 6 --radius 10 cli-anything-freecad --json -p p.json sketch add-bspline 0 --points "0,0;5,10;10,0;15,10" cli-anything-freecad --json -p p.json sketch add-slot 0 --center1 0,0 --center2 10,0 --radius 2 cli-anything-freecad --json -p p.json sketch constrain 0 distance --elements 0,1 --value 10 cli-anything-freecad --json -p p.json sketch edit-element 0 0 --radius 8 cli-anything-freecad --json -p p.json sketch remove-element 0 2 cli-anything-freecad --json -p p.json sketch validate 0 cli-anything-freecad --json -p p.json sketch solve-status 0

支持的约束类型共 18 种：coincident（重合）、horizontal、vertical、parallel、perpendicular、equal、fixed、distance、angle、radius、tangent、symmetric、block、diameter、point_on_object、distance_x、distance_y。2D 坐标使用x,y格式（_parse_vec2）。草图侧还提供mirror、offset、trim、extend、set-construction、project-external、intersection、add-external-face（后三者对应 FreeCAD 1.1 外部几何功能）。

5.4 body（38 条）—— PartDesign 特征

cli-anything-freecad --json -p p.json body new cli-anything-freecad --json -p p.json body pad 0 0 --length 10 cli-anything-freecad --json -p p.json body pocket 0 1 --length 5 cli-anything-freecad --json -p p.json body groove 0 0 --angle 360 cli-anything-freecad --json -p p.json body fillet 0 --radius 2 cli-anything-freecad --json -p p.json body chamfer 0 --size 1.5 cli-anything-freecad --json -p p.json body revolution 0 0 --angle 360 cli-anything-freecad --json -p p.json body additive-loft 0 --sketch-indices 0,1 cli-anything-freecad --json -p p.json body additive-pipe 0 0 1 cli-anything-freecad --json -p p.json body additive-helix 0 0 --pitch 5 --height 20 cli-anything-freecad --json -p p.json body additive-box 0 -P length=10 -P width=10 -P height=10 cli-anything-freecad --json -p p.json body hole 0 0 --diameter 5 --depth 10 --threaded cli-anything-freecad --json -p p.json body draft-feature 0 --angle 5 cli-anything-freecad --json -p p.json body thickness-feature 0 --thickness 1 cli-anything-freecad --json -p p.json body linear-pattern 0 --occurrences 5 --length 50 cli-anything-freecad --json -p p.json body polar-pattern 0 --occurrences 6 --angle 360 cli-anything-freecad --json -p p.json body mirrored 0 --plane XY cli-anything-freecad --json -p p.json body datum-plane 0 --reference XY --offset 10

Body 组的能力矩阵相当完整：加料特征（pad/pocket/groove/revolution/loft/pipe/helix + 7 种 additive 图元）、减料特征（subtractive-loft/pipe/helix + 7 种 subtractive 图元）、修饰特征（fillet/chamfer/draft/thickness/hole，其中 hole 支持--threaded、--thread-standard（metric/BSW/BSF/BSP/NPT）、--tapered）、阵列特征（linear/polar/mirrored/multi-transform，其中 multi-transform 接受 JSON 变换数组）、基准特征（datum-plane/line/point、shape-binder、local-coordinate-system、toggle-freeze）。

5.5 material（8 条）—— 带工程属性的 PBR 材质

# 21 种预设：steel, aluminum, copper, brass, titanium, stainless_steel, cast_iron, # carbon_fiber, nylon, abs, pla, petg, plastic_white, plastic_black, wood, glass, # rubber, gold, concrete, granite, marble cli-anything-freecad --json -p p.json material create --preset steel cli-anything-freecad --json -p p.json material create --preset titanium cli-anything-freecad --json -p p.json material assign 0 0 cli-anything-freecad --json -p p.json material set 0 density 7800 cli-anything-freecad --json -p p.json material import-material mat.json cli-anything-freecad --json -p p.json material export-material 0 --output mat.json

预设定义在 materials.py 中：每个预设含 PBR 外观参数（color（RGBA 0.0-1.0）、metallic、roughness），工程金属/塑料预设还带density、youngs_modulus、poisson_ratio、yield_strength、ultimate_strength等力学属性，可直接服务 FEM。material create也可用--color r,g,b,a、--metallic、--roughness手工覆盖。

5.6 assembly（11 条）—— 装配管理

cli-anything-freecad --json -p p.json assembly new --name "MyAssembly" cli-anything-freecad --json -p p.json assembly add-part 0 0 cli-anything-freecad --json -p p.json assembly constrain 0 coincident --components 0,1 cli-anything-freecad --json -p p.json assembly constrain 0 distance --components 0,1 --distance 10 cli-anything-freecad --json -p p.json assembly solve 0 cli-anything-freecad --json -p p.json assembly dof 0 cli-anything-freecad --json -p p.json assembly bom 0 cli-anything-freecad --json -p p.json assembly explode 0 --factor 2.0

支持的装配约束 13 种：fixed、coincident、distance、angle、parallel、perpendicular、tangent、revolute、prismatic、cylindrical、ball、planar、gear、belt。assembly bom生成物料清单、assembly dof估算自由度、explode/collapse用于可视化拆解。对应 FreeCAD 1.1 的扩展命令还包括insert-part（内联插入图元）、create-simulation、add-sim-step（关节运动仿真）。

5.7 mesh（16 条）—— 网格操作

cli-anything-freecad --json -p p.json mesh from-shape 0 --deviation 0.1 cli-anything-freecad --json -p p.json mesh import path/to/model.stl cli-anything-freecad --json -p p.json mesh export 0 output.stl --format stl cli-anything-freecad --json -p p.json mesh boolean union 0 1 cli-anything-freecad --json -p p.json mesh decimate 0 --target-faces 1000 cli-anything-freecad --json -p p.json mesh smooth 0 --iterations 5 cli-anything-freecad --json -p p.json mesh repair 0 cli-anything-freecad --json -p p.json mesh to-shape 0

from-shape用--deviation（默认 0.1）控制曲面偏差；网格管线还包含remesh（--target-length）、fill-holes、flip-normals、merge、split、analyze、check等，覆盖从实体到网格再到实体的完整往返。

5.8 techdraw（15 条）—— 工程图纸

cli-anything-freecad --json -p p.json techdraw new-page cli-anything-freecad --json -p p.json techdraw add-view 0 0 --direction 0,0,1 --scale 1.0 cli-anything-freecad --json -p p.json techdraw add-projection-group 0 0 cli-anything-freecad --json -p p.json techdraw add-section-view 0 0 cli-anything-freecad --json -p p.json techdraw add-dimension 0 0 length --references 0,1 cli-anything-freecad --json -p p.json techdraw add-annotation 0 "Note text" cli-anything-freecad --json -p p.json techdraw export-pdf 0 drawing.pdf cli-anything-freecad --json -p p.json techdraw export-svg 0 drawing.svg

new-page默认使用A4_LandscapeTD模板（可用--template更换，也可用set-template修改）。视图类型包括标准视图（add-view，可指定--direction/--scale/--position）、投影组（add-projection-group，--directions front,right,top）、剖视图（add-section-view）、局部放大视图（add-detail-view）。标注类型：length、distance、radius、diameter、angle，并支持add-centerline、add-hatch、add-leader与 PDF/SVG 导出。

5.9 draft（33 条）—— 二维制图

cli-anything-freecad --json -p p.json draft wire --points "0,0,0;10,0,0;10,10,0" cli-anything-freecad --json -p p.json draft rectangle --width 20 --height 15 cli-anything-freecad --json -p p.json draft circle --radius 10 cli-anything-freecad --json -p p.json draft polygon --sides 6 --radius 10 cli-anything-freecad --json -p p.json draft text --content "Hello" --position 0,0,0 cli-anything-freecad --json -p p.json draft move 0 --vector 10,5,0 cli-anything-freecad --json -p p.json draft array-linear 0 --direction 1,0,0 --count 5 --spacing 10 cli-anything-freecad --json -p p.json draft array-polar 0 --center 0,0,0 --count 6 cli-anything-freecad --json -p p.json draft extrude 0 --direction 0,0,1 --length 10 cli-anything-freecad --json -p p.json draft to-sketch 0

Draft 组覆盖 2D 几何（wire/rectangle/circle/ellipse/polygon/bspline/bezier/point/text/shapestring/dimension/label/hatch）、变换（move/rotate/scale/mirror/offset/copy/clone）、阵列（array-linear/array-polar/array-path）与对象操作（upgrade/downgrade/trim/join/extrude/fillet-2d/to-sketch）。注意draft to-sketch可将 2D 对象转换为可供 PartDesign 使用的草图，是 2D→3D 工作流的桥接点。

5.10 measure（12 条）—— 测量与分析

cli-anything-freecad --json -p p.json measure volume 0 cli-anything-freecad --json -p p.json measure area 0 cli-anything-freecad --json -p p.json measure distance 0 1 cli-anything-freecad --json -p p.json measure bounding-box 0 cli-anything-freecad --json -p p.json measure center-of-mass 0 cli-anything-freecad --json -p p.json measure check-geometry 0

还包括length（可指定--edge-ref Edge1）、angle、radius、diameter、position、inertia（主惯性矩）。check-geometry支持--include-valid与--skip 0,2，用于在导出前做几何合法性校验。

5.11 surface（6 条）—— 曲面操作

cli-anything-freecad --json -p p.json surface filling --edges 0,1,2 cli-anything-freecad --json -p p.json surface sections --sections 0,1,2 cli-anything-freecad --json -p p.json surface extend 0 --length 10 cli-anything-freecad --json -p p.json surface sew --indices 0,1

另有blend-curve（两边缘间混合曲面）、cut（曲面裁剪）。surface extend的--direction可选normal/u/v；sew默认缝合公差 0.01。

5.12 fem（12 条）—— 有限元分析

cli-anything-freecad --json -p p.json fem new-analysis cli-anything-freecad --json -p p.json fem add-fixed 0 --references face1,face2 cli-anything-freecad --json -p p.json fem add-force 0 --references face3 --magnitude 1000 cli-anything-freecad --json -p p.json fem set-material 0 0 cli-anything-freecad --json -p p.json fem mesh-generate 0 --max-size 5 cli-anything-freecad --json -p p.json fem solve 0 cli-anything-freecad --json -p p.json fem results 0

约束类型包括add-fixed、add-force（N）、add-pressure（MPa）、add-displacement、add-temperature（K）、add-heatflux（W/m²）。mesh-generate可选--mesher gmsh|netgen（默认 gmsh）、--element-type（默认 Tet10）；solve可选--solver calculix|elmer|z88（默认 calculix）、--output-format vtu|vtk|result。FreeCAD 1.1 扩展还包括add-beam-section（梁截面）、add-tie（绑定约束）、purge-results、suppress。

5.13 cam（10 条）—— CNC 加工

cli-anything-freecad --json -p p.json cam new-job 0 cli-anything-freecad --json -p p.json cam set-stock 0 --stock-type box cli-anything-freecad --json -p p.json cam set-tool 0 --diameter 6 --type endmill cli-anything-freecad --json -p p.json cam add-profile 0 cli-anything-freecad --json -p p.json cam add-pocket 0 --depth 5 cli-anything-freecad --json -p p.json cam generate-gcode 0 cli-anything-freecad --json -p p.json cam export-gcode 0 output.nc

set-stock的--stock-type可选box/cylinder/from_part，并可指定三向余量--extra-x/y/z（默认 2.0）。操作类型包括 profile（轮廓）、pocket（型腔）、drilling（钻孔，支持--peck-depth啄钻）、facing（端面）。set-tool支持 6 种刀型（endmill/ballnose/drill/chamfer/vbit/facemill）、--flutes、--material、--coating；FreeCAD 1.1 扩展含add-tapping（攻丝 G84/G74）、import-tool-library/export-tool-library（刀具库）。

5.14 spreadsheet（7 条）—— 参数化数据表

cli-anything-freecad --json -p p.json spreadsheet new cli-anything-freecad --json -p p.json spreadsheet set-cell 0 A1 "50" cli-anything-freecad --json -p p.json spreadsheet set-cell 0 B1 "=A1*2" cli-anything-freecad --json -p p.json spreadsheet set-alias 0 A1 plate_width cli-anything-freecad --json -p p.json spreadsheet export-csv 0 data.csv

set-cell会自动把数值字符串解析为 int/float（见 freecad_cli.py），支持公式（=A1*2）与单元格别名（供模型参数引用）；另有import-csv（--start-cell A1）。

5.15 import（13 条）—— 导入 13 种格式

cli-anything-freecad --json -p p.json import auto model.step cli-anything-freecad --json -p p.json import step model.step cli-anything-freecad --json -p p.json import stl model.stl cli-anything-freecad --json -p p.json import dxf drawing.dxf cli-anything-freecad --json -p p.json import info model.step # 格式：step, iges, stl, obj, dxf, svg, brep, 3mf, ply, off, gltf

import auto按扩展名自动探测；import info仅预览文件元数据而不导入。

5.16 export（3 条）—— 导出 17 种格式

# 预设：step, iges, stl, stl_fine, obj, brep, fcstd, dxf, svg, gltf, 3mf, ply, off, amf, pdf, png, jpg cli-anything-freecad --json -p p.json export render output.step --preset step cli-anything-freecad --json -p p.json export render model.stl --preset stl --overwrite cli-anything-freecad --json -p p.json export presets

export render是 headless 导出的统一入口：--preset step对应 STEP AP214（ISO 10303）标准 CAD 交换，stl/stl_fine面向 3D 打印，另有obj、brep、fcstd、dxf、svg、gltf、3mf、ply、off、amf、pdf、png、jpg。文件已存在时需--overwrite。

5.17 session（4 条）—— 撤销/重做

cli-anything-freecad --json -p p.json session undo cli-anything-freecad --json -p p.json session redo cli-anything-freecad --json -p p.json session status cli-anything-freecad --json -p p.json session history

每次会修改模型的操作（如part add、body pad）都会先调用sess.snapshot(...)记录快照，session undo/redo因此能回滚/重放历史（该机制在 freecad_cli.py 等处可见，REPL 中还会在退出时提示未保存修改）。

六、Agent 集成要点

针对 LLM Agent 的使用，SKILL.md 给出了四条核心约定（见 skills/cli-anything-freecad/SKILL.md）：

1. 几何变更后必须做视觉验证：使用preview capture --json；
2. 迭代构建优先 live preview：项目文件被反复保存时使用preview live start的 poll 模式；
3. 状态探针要廉价：先preview live status --json，再按需读取完整的trajectory.json；
4. 区分快照与稳定身份：_bundle_dir只是单次快照，稳定的实时身份是_session_dir+_trajectory_path；cli-hub previews ...仅用于查看/打开已发布预览。

配合全局--json，Agent 可以稳定地解析每一次命令的结构化响应；配合-p proj.json的自动保存行为，Agent 的每一步修改都会持久化到项目文件中，形成可追溯的构建轨迹。

七、运行测试

仓库为 FreeCAD harness 提供了单元测试与端到端测试：

cd freecad/agent-harness python -m pytest cli_anything/freecad/tests/ -v -s

如需强制按已安装命令方式测试：

CLI_ANYTHING_FORCE_INSTALLED=1 python -m pytest cli_anything/freecad/tests/ -v -s

单元测试（test_core.py）使用合成数据、不依赖外部 FreeCAD，覆盖文档往返（save/open）、profile 校验、部件/草图/体/材质等核心模块；端到端测试（test_full_e2e.py）则验证真实 FreeCAD 环境下的完整流程。

八、底层原理小结

整条链路可以概括为「JSON 状态 + 宏生成 + 无头执行」：

• 状态层：所有实体以 JSON 项目文件持久化，document模块负责创建/校验/读写（core/document.py）；
• 命令层：Click 定义的 258 条命令把参数解析（_parse_vec3/_parse_vec2/_parse_params/_parse_indices/_parse_points等）与核心业务解耦（freecad_cli.py）；
• 执行层：freecad_backend定位freecadcmd并生成/执行宏（utils/freecad_backend.py）；
• 验证层：Preview/Motion 模块把几何结果渲染为真实图像帧与轨迹（core/preview.py、utils/preview_bundle.py）。

这套设计让 FreeCAD 成为真正「Agent-Native」的建模后端：Agent 既能通过--json获得可解析的结构化反馈，又能通过 Live Preview 获得视觉闭环，还能用 Motion 产出最终的展示视频——从参数建模到工程文档、从 FEA 分析到 G-code 生成，全流程不再需要人类在 GUI 前操作。

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything