预览进度¶

最后更新时间：2026-04-23 UTC

本文件跟踪专用预览分支上预览工作的当前状态，并记录实时弹窗预览窗口的下一设计方向。

工作区¶

仓库：/root/CLI-Anything-preview
分支：feat/preview-protocol
主要协议文档：docs/PREVIEW_PROTOCOL.md

已实现内容¶

当前分支已具备可用的首版预览堆栈：

共享预览包辅助器： cli-anything-plugin/preview_bundle.py
共享静态查看器/检查器： cli-hub/cli_hub/preview.py
预览协议已记录在： docs/PREVIEW_PROTOCOL.md
已为以下工具实现框架级预览支持：
shotcut
openscreen
blender
freecad
renderdoc

当前形态为：

各框架生成 preview-bundle/v1 包
cli-hub 可检查或渲染某个包的静态 HTML
预览命令已围绕以下命令规范化：
preview recipes
preview capture
preview latest
renderdoc 还支持 preview diff

本轮新增内容¶

预览分支现在具备以下工具的实时弹窗预览循环：

shotcut
freecad
blender

当前 FreeCAD 演示选型说明现位于：

docs/FREECAD_DEMO_PROPOSALS.md

首个入选的地标后展示为：

mars-rover

当前 FreeCAD 机械建模质量提升还新增了：

part bounds
part align
新一轮 Curiosity v6 连接件处理：
镜像右侧车轮外侧对齐
6 个车轮级轴块
4 个悬架枢轴壳体
添加这些连接件后进行了完整的真实实时预览重跑

这些命令提供图元级世界包围盒和 bbox 锚点对齐，使 CLI 构建的模型无需完全依赖猜测式 -pos/-rot 放置。

当前 FreeCAD 视频工具现在还包括：

真实的 combo 组合动作结尾，用于 Curiosity：
先完整旋转一圈
再向前行驶
重新设计的左右分屏左侧面板：
Agent Command Stream
基于卡片的命令展示，而非字面终端转储
演示脚本中的渲染修复：自定义输出路径会在调用 ffmpeg 前创建父目录

新增内容：

shotcut 实时会话生命周期：
preview live start
preview live push
preview live status
preview live stop
shotcut 生产者侧自动轮询：
preview live start --mode poll --source-poll-ms ...
隐藏后台 preview live monitor --session-dir ...
工程文件指纹轮询，并自动重新采集预览
freecad 实时会话生命周期：
preview live start
preview live push
preview live status
preview live stop
freecad 生产者侧自动轮询：
preview live start --mode poll --source-poll-ms ...
隐藏后台 preview live monitor --session-dir ...
已保存工程 JSON 指纹轮询，并自动重新采集预览
用于 freecad 的演示工具：
docs/scripts/freecad_live_preview_demo.py collect
docs/scripts/freecad_live_preview_demo.py render
docs/scripts/freecad_live_preview_demo.py run-all
场景：
- orbital-relay
- empire-state-building
- taipei-101
blender 实时会话生命周期：
preview live start
preview live push
preview live status
preview live stop
blender 生产者侧自动轮询：
preview live start --mode poll --source-poll-ms ...
隐藏后台 preview live monitor --session-dir ...
已保存场景 JSON 指纹轮询，并自动重新采集预览
用于 blender 的演示工具：
docs/scripts/blender_orbital_relay_drone_demo.py
docs/scripts/blender_preview_story_demo.py
场景：
- orbital-relay-drone
- 真实分阶段预览包
- 真实转盘运动视频
- 带有转盘结尾的精修构建故事视频
cli-hub 实时查看器界面：
previews inspect 现在可理解实时会话
previews html 现在渲染包和实时会话 HTML
previews watch 现在通过 localhost 提供实时会话服务并自动刷新
previews open 现在在独立窗口中打开包或实时会话
实时页面和检查输出现在会在存在 trajectory.json 时使用它

当前实时拆分如下：

框架负责预览包生成和实时会话状态发布
框架现在还可负责源状态轮询和自动包刷新
cli-hub 负责弹窗、本地服务器、轮询页面和浏览器启动

这是预期的跨软件方向。

当前验证状态¶

已在本机上完全验证¶

shotcut
预览实现可用
黑帧问题已通过优先使用 ffmpeg 预览路径修复
预览 E2E 通过
实时预览会话 + 实时查看器现已端到端可用
自动轮询模式现已端到端可用，无需手动 preview live push
openscreen
预览实现可用
预览 E2E 通过
blender
预览实现可用
预览 E2E 通过
实时预览会话生命周期现已端到端可用
自动轮询模式现已端到端可用，无需手动 preview live push
现在已存在真实的分阶段 gyro-observatory 构建，包含：
- 4 个预览包检查点
- 一个持久化实时会话
- 最终 1600x1600 Blender 静帧渲染
freecad
预览实现在当前 Ubuntu 机器上完成本地环境配置后可用
预览 E2E 通过
实时预览会话 + 实时轮询模式现已端到端可用
现在已存在真实编程式演示视频，由真实 CLI 输出和真实实时预览包构建而成
预览宏现在可重建真实实体/加运算/减运算图元特征，以及线性/极轴/镜像阵列特征并带放置信息
现在已存在多个真实的 Taipei 101 研究；旧有自带场景已被替换，因为早期堆叠盒版本不可接受
预览/导出宏生成现在还可为基于图元的镜像零件重建 part mirror，这是如实构建对称机械模型（如火星车）所必需的
现在已存在首个真实的 mars-rover 实时预览轨迹，并成功端到端完成
实时演示收集器现在将预览事件视为稳定序列，即使 FreeCAD 实时会话在 bundle_count 行为并非严格单调的情况下更改了包 ID
现在已存在真实的 curiosity 实时预览轨迹，并成功端到端完成
框架现在具备图元级 part bounds 和 part align 命令，并带有单元和 CLI 子进程覆盖
现在已存在更完整的 Curiosity v6 运行，并带有显式悬架连接件成功完成；最终右/前视图比早期 v5 构建对称性和结构一致性明显更好
现在已存在精修的 Curiosity 分屏视频，包含：
- 真实命令卡片轨迹视图
- 真实实时预览包
- 真正的逐帧组合运动结尾

本机已部分验证¶

renderdoc
重放现有的 .rdc 捕获文件可用
renderdoccmd thumb 可对合适的示例捕获文件生成缩略图
本机上的本地捕获生成仍受当前图形后端环境的限制

当前机器说明¶

FreeCAD¶

为了让 freecad 预览在这台 Ubuntu 机器上正常工作，需要在本地补齐相关环境：

FreeCAD AppImage 已解压至 /opt/freecad/app
本地启动器/包装脚本已安装至 /usr/local/bin/freecad
包装脚本通过 xvfb-run 强制以支持 GUI 的方式执行，用于脚本驱动的预览捕获

这是机器本地的配置，不属于仓库内容。

结果：

freecad 预览 E2E 现已在这台机器上通过
生成的 4 视图预览图像有效且非空

RenderDoc¶

为了让 renderdoc 预览在这台 Ubuntu 机器上可用，需要在本地补齐相关环境：

RenderDoc 已安装至 /opt/renderdoc
renderdoccmd 与 qrenderdoc 已暴露在 /usr/local/bin
已安装 Vulkan 与着色器工具：
vulkan-tools
glslang-tools

在这台机器上发现的重要限制：

在当前使用软件渲染（llvmpipe / lavapipe）的终端 Ubuntu 环境中，RenderDoc 可以注入演示应用并暴露应用内 API，但本地的 StartFrameCapture/EndFrameCapture 仍然不会返回已保存的捕获
这不是 CLI 接线问题，而是当前图形环境的后端/运行时限制

仍然可用的功能：

重放现有的 .rdc 捕获文件
当捕获文件包含可用的内嵌缩略图时，可从现有的 .rdc 文件导出缩略图

本地产物¶

当前可用的本地验证输出：

汇总后的最终产物：
/root/preview-artifacts/20260420/final/freecad-preview.png
/root/preview-artifacts/20260420/final/renderdoc-preview.png
Blender Gyro Observatory 产物：
/root/preview-artifacts/20260422/blender-gyro-observatory/gyro_observatory.blend-cli.json
/root/preview-artifacts/20260422/blender-gyro-observatory/live-root/blender/live/gyro-observatory-blend-cli-0043d42f-quick/session.json
/root/preview-artifacts/20260422/blender-gyro-observatory/live-root/blender/quick/20260422T123252Z_a0409b02_quick/artifacts/hero.png
/root/preview-artifacts/20260422/blender-gyro-observatory/live.html
/root/preview-artifacts/20260422/blender-gyro-observatory/renders/gyro_observatory_final.png
FreeCAD 实时轮询演示产物：
/root/preview-artifacts/20260421/freecad-live-demo/live-root/freecad/live/project-379d4e4a-quick/session.json
/root/preview-artifacts/20260421/freecad-live-demo/live-root/freecad/quick/20260421T051634Z_88a6b6d6_quick/artifacts/hero.png
/root/preview-artifacts/20260421/freecad-live-demo/live.html
FreeCAD 程序化视频演示产物：
/root/preview-artifacts/20260421/freecad-live-video/demo.mp4
/root/preview-artifacts/20260421/freecad-live-video/trajectory.json
/root/preview-artifacts/20260421/freecad-live-video/live.html
/root/preview-artifacts/20260421/freecad-live-video/stills/frame_10s.png
/root/preview-artifacts/20260421/freecad-live-video/stills/frame_35s.png
/root/preview-artifacts/20260421/freecad-live-video/stills/frame_60s.png
FreeCAD 摩天楼演示产物：
/root/preview-artifacts/20260421/freecad-taipei-101-video/demo.mp4
/root/preview-artifacts/20260421/freecad-taipei-101-video/trajectory.json
/root/preview-artifacts/20260421/freecad-taipei-101-video/live.html
/root/preview-artifacts/20260421/freecad-taipei-101-video/stills/frame_15s.png
/root/preview-artifacts/20260421/freecad-taipei-101-video/stills/frame_55s.png
/root/preview-artifacts/20260421/freecad-taipei-101-video/stills/frame_95s.png
/root/preview-artifacts/20260421/freecad-taipei-101-video/snapshots/15_spire-tip/front.png
/root/preview-artifacts/20260421/freecad-taipei-101-video/snapshots/15_spire-tip/hero.png
FreeCAD 火星车原型产物：
/root/preview-artifacts/20260421/freecad-mars-rover-proto3/trajectory.json
/root/preview-artifacts/20260421/freecad-mars-rover-proto3/live.html
/root/preview-artifacts/20260421/freecad-mars-rover-proto3/snapshots/21_sample-head/hero.png
/root/preview-artifacts/20260421/freecad-mars-rover-proto3/snapshots/21_sample-head/front.png
/root/preview-artifacts/20260421/freecad-mars-rover-proto3/snapshots/21_sample-head/top.png
这次火星车运行在当前机器上产生了 22 条真实 CLI 命令和 21 次真实预览更新
FreeCAD Curiosity 产物：
/root/preview-artifacts/20260421/freecad-curiosity-proto4/trajectory.json
/root/preview-artifacts/20260421/freecad-curiosity-proto4/live.html
/root/preview-artifacts/20260421/freecad-curiosity-proto4/snapshots/35_deck-sensor-pack/hero.png
/root/preview-artifacts/20260421/freecad-curiosity-proto4/snapshots/35_deck-sensor-pack/front.png
/root/preview-artifacts/20260421/freecad-curiosity-proto4/snapshots/35_deck-sensor-pack/top.png
/root/preview-artifacts/20260421/freecad-curiosity-proto4/snapshots/35_deck-sensor-pack/right.png
这次 Curiosity 运行在当前机器上产生了 36 条真实 CLI 命令和 35 次真实预览更新
本次运行的平均预览刷新延迟为 8.503s
FreeCAD Curiosity 机械臂/附件细化产物：
/root/preview-artifacts/20260421/freecad-curiosity-v3-armfix-preview/freecad/quick/20260421T162607Z_12c18d75_quick/artifacts/hero.png
/root/preview-artifacts/20260421/freecad-curiosity-v3-armfix-preview/freecad/quick/20260421T162607Z_12c18d75_quick/artifacts/front.png
/root/preview-artifacts/20260421/freecad-curiosity-v3-armfix-preview/freecad/quick/20260421T162607Z_12c18d75_quick/artifacts/top.png
这些是在对上部/前部机械臂和炮塔链应用 part align 修复后，从真实 Curiosity 项目生成的
FreeCAD Curiosity 完整悬架/对齐细化：
/root/preview-artifacts/20260421/freecad-curiosity-v5/trajectory.json
/root/preview-artifacts/20260421/freecad-curiosity-v5/live.html
/root/preview-artifacts/20260421/freecad-curiosity-v5/snapshots/58_align-sensor-pack/hero.png
/root/preview-artifacts/20260421/freecad-curiosity-v5/snapshots/58_align-sensor-pack/front.png
/root/preview-artifacts/20260421/freecad-curiosity-v5/snapshots/58_align-sensor-pack/right.png
本次运行产生了 62 条真实 CLI 命令和 58 次真实预览更新
本次运行的平均预览刷新延迟为 14.454s
悬架更新现在会在添加上部装配堆叠之前，对摇臂/转向架/连杆部件进行显式的轮平面对齐
FreeCAD Curiosity 连接件重建：
/root/preview-artifacts/20260421/freecad-curiosity-v6/trajectory.json
/root/preview-artifacts/20260421/freecad-curiosity-v6/live.html
悬架连接件检查点：
- /root/preview-artifacts/20260421/freecad-curiosity-v6/snapshots/50_align-right-bogie-pivot-housing/right.png
- /root/preview-artifacts/20260421/freecad-curiosity-v6/snapshots/50_align-right-bogie-pivot-housing/front.png
- /root/preview-artifacts/20260421/freecad-curiosity-v6/snapshots/50_align-right-bogie-pivot-housing/hero.png
v6 最终快照：
- /root/preview-artifacts/20260421/freecad-curiosity-v6/snapshots/82_align-sensor-pack/hero.png
- /root/preview-artifacts/20260421/freecad-curiosity-v6/snapshots/82_align-sensor-pack/front.png
- /root/preview-artifacts/20260421/freecad-curiosity-v6/snapshots/82_align-sensor-pack/right.png
本次运行产生了 85 条真实 CLI 命令和 82 次真实预览更新
本次运行的平均预览刷新延迟为 10.059s
与 v5 相比，最大的改进在于右侧履带宽度对称，并且关键的前视/右视图中车轮/悬架连接件清晰可见
现在也有一个针对同一条 v6 轨迹的程序化视频：
- /root/preview-artifacts/20260421/freecad-curiosity-v6/demo.mp4
- /root/preview-artifacts/20260421/freecad-curiosity-v6/showcase/sequence.json
- /root/preview-artifacts/20260421/freecad-curiosity-v6/stills/showcase-start.png
- /root/preview-artifacts/20260421/freecad-curiosity-v6/stills/showcase-mid.png
- /root/preview-artifacts/20260421/freecad-curiosity-v6/stills/showcase-final.png
结尾展示画面基于额外的真实 FreeCAD hero 捕获构建而成，这些捕获源自最终 Curiosity v6 项目在阶段性地面运行中的结果
Shotcut 实时预览演示产物：
/root/preview-artifacts/20260420/shotcut-live-demo/live-viewer-shot.png
/root/preview-artifacts/20260420/shotcut-live-demo/live-root/shotcut/live/project-9e62c8c7-quick/live.html
/root/preview-artifacts/20260420/shotcut-live-demo/live-root/shotcut/live/project-9e62c8c7-quick/session.json
临时轮询模式演示产物：
/tmp/shotcut-poll-demo/live-initial.png
/tmp/shotcut-poll-demo/live-updated.png
/tmp/shotcut-poll-demo/live-red-updated.png
/tmp/shotcut-poll-demo/live-root/shotcut/live/project-35fa4f1f-quick/session.json
FreeCAD 捆绑包快照：
/root/preview-artifacts/20260420/freecad/
RenderDoc 示例重放产物：
/root/preview-artifacts/20260420/renderdoc/sample/

解读：

freecad-preview.png 是由本机上的 FreeCAD 预览路径生成的真实 4 视图预览联系表。
20260421/freecad-live-demo/ 目录证明了新的 FreeCAD 轮询模式行为：在对已保存项目进行变更后，live session 会从 bundle 1 推进到 2，无需任何手动的 preview live push 命令。
20260421/freecad-live-video/ 目录包含一个真实的端到端演示：左侧是类似 agent 的 CLI 构建，右侧是实际的 FreeCAD 实时预览输出；视频是程序化生成的，但底层的命令、输出、时序和预览图像都是真实的。
20260421/freecad-empire-state-video/ 目录对微型的 Empire State Building 复刻做了同样的事情；该复刻完全使用 cli-anything-freecad 原语和真实的轮询模式预览刷新构建。
经过自我审查，这个 Empire State Building 尝试不被视为可发布版本，因为其轮廓仍然像是普通的阶梯状塔楼。
20260421/freecad-taipei-101-video/ 目录是第二次真实的摩天楼实验，使用相同的 CLI + 真实实时预览流水线构建。
经过后来的审查，它也不能作为 Taipei 101 演示发布；轮廓仍然过于普通，命令脚本只是构建了一个粗略的堆叠盒子近似。
不要将其视为已完成的地标复刻。
在 FreeCAD body/additive/pattern 预览对齐工作之后，一组新的真实 Taipei 研究直接针对改进后的测试平台生成：
/root/preview-artifacts/20260421/taipei-body-proto1/
/root/preview-artifacts/20260421/taipei-body-proto7/
/root/preview-artifacts/20260421/taipei-parts-proto2/
当前最佳轮廓是 /root/preview-artifacts/20260421/taipei-parts-proto2/ 中的阶梯肩部零件研究。
docs/scripts/freecad_live_preview_demo.py 现在使用那个更新的 Taipei 101 阶梯生成器，而不是之前错误的堆叠盒子场景。
更新后的 taipei-101 场景随后被端到端重新采集到：
/root/preview-artifacts/20260421/freecad-taipei-101-rework/trajectory.json
/root/preview-artifacts/20260421/freecad-taipei-101-rework/final-preview.html
/root/preview-artifacts/20260421/freecad-taipei-101-rework/snapshots/30_spire-tip/
这次返工运行在本机产生了 31 条真实 CLI 命令和 30 次真实预览更新。
在启动漫游车方向时，又暴露了一个真实的预览缺口：part mirror 对象是有效的项目状态，但 FreeCAD 预览宏层没有重建它们。
一旦对称的右侧车轮副本进入项目，就会导致预览漂移或捕获停滞。
宏生成器现在将镜像图元零件解析为可渲染的镜像图元，用于预览/导出。
第一个漫游车原型还不是最终的展示模型，但它现在在真实的 hero/front/top 预览中清晰可辨为六轮探测漫游车，并且比失败的地标演示更适合继续迭代。
renderdoc-preview.png 是从本机上现有的 .rdc 示例捕获中导出的真实缩略图。
live-viewer-shot.png 是新的 Shotcut 实时预览窗口 UI 的真实截图，由本机上的 live-session 查看器通过 localhost 渲染。
/tmp/shotcut-poll-demo/ 下的产物证明了新的轮询模式行为：在对项目文件进行变更后，live session 会从 bundle 1 依次推进到 2 和 3，无需任何手动的 preview live push 命令。

仍存在的缺口¶

跨进程 live session 稳定性¶

本轮迭代暴露并修复了一个重要问题：

第一个实现部分根据进程内的 session_id 来派生 live session 名称。
这破坏了一次性 CLI 的使用，因为每条命令会得到不同的 session 目录。

当前行为现在是：

如果项目有已保存的 project_path，则 live session 标识由稳定的项目路径 + recipe 派生。
只有未保存的内存中项目才会回退到 session_id。

对于一次性命令流来说，这才是正确的面向 agent 的行为。

RenderDoc 捕获生成¶

当前仓库中 renderdoc 预览的实现仍然假设已经存在一个可重放的真实捕获。

对于 RenderDoc 作为产品来说这是正常的，但在本机上还有一个进一步的限制：

在当前软件渲染的终端环境中，从测试应用本地生成新的 .rdc 文件还不可靠。

这意味着：

renderdoc 预览可用于现有捕获。
renderdoc 预览在这台特定机器上尚未完全自托管。

FreeCAD 布尔运算预览缺口¶

在构建视频演示时，出现了一个真实的限制：

在 part boolean fuse 之后，当前 FreeCAD 预览路径仍然可以生成 bundle，但可能降级为 partial 且没有图像产物。

这就是为什么当前演示轨迹避免使用布尔运算，只使用零件添加，以保持实时预览图像流有效。

Empire State Building 尝试¶

我在首个 Empire State Building 视频和产物生成后，明确地对其进行了审查。

结果：

模型过于普通，无法被识别为 Empire State Building。
正确的做法不是继续声称它是正确的。

当前处理方式：

仅将 Empire State 尝试保留为实验。
不要将其视为已发布的摩天楼演示。
同样不要将旧的 Taipei 101 堆叠盒子运行视为已发布。
当前的 Taipei 101 工作已转移到更新的研究产物和更新后的 freecad_live_preview_demo.py 场景中。

FreeCAD body 预览对齐¶

糟糕的地标演示背后，主要的 FreeCAD 缺口是真实存在的：

CLI 能够描述的 body/additive/pattern 编辑比预览宏能够忠实重建的内容更丰富。

这在当前分支中已得到改进：

加法和减法 body 图元现在支持特征放置。
预览/导出宏现在会重建：
加法/减法 box/cylinder/sphere/cone/torus/wedge
linear_pattern
polar_pattern
mirrored
multi_transform 作为受支持阵列特征的顺序展开
本机上的完整验证现在全部通过：
cli_anything/freecad/tests/test_core.py -> 76 passed
cli_anything/freecad/tests/test_full_e2e.py -k 'macro_generation or preview_capture_bundle or preview_capture_subprocess or preview_live_poll_auto_refresh' -> 6 passed

共享运行时清理¶

preview bundle 辅助工具当前存在于：

cli-anything-plugin/preview_bundle.py 中的规范形式
每个 harness 下 utils/preview_bundle.py 中的复制形式

这对第一版来说是可以接受的，但长期方向应该是：

一个共享的运行时辅助工具
不再有基于复制导致的漂移

简短回答：

可以，但它应作为宿主/查看器功能来实现，而不是五个不同的应用专属迷你 GUI
通用解决方案应面向近实时的 live preview session，而不是通用的原始 GUI 流式传输协议

为什么窗口应位于 `cli-hub` 中¶

原因：

弹窗行为是跨 harness 的 UI 逻辑，而不是应用专属的渲染逻辑
查看器已经理解 preview bundle 契约
Linux/Ubuntu 弹窗行为属于宿主层
这避免了在每个 harness 中重建相同的预览监视器

如果每个 harness 都实现自己的弹窗：

命令表面会发生漂移
依赖会发生漂移
实时刷新逻辑会被重复实现
Linux 窗口行为怪癖会被重复解决五次

这里的“实时”应意味着什么¶

有两种可能的含义：

以交互式帧率进行真正的持续流式传输
在专用实时窗口中快速、重复地刷新预览

通用跨软件解决方案应针对第二种。

这意味着：

自动刷新静帧
替换低分辨率审阅片段
在每个变更命令后由事件驱动重绘
对长时间运行的任务可选地定期刷新

这在视频、CAD、3D 和 GPU 调试工作流中是现实可行的。

一个适用于所有受支持软件的通用 30-60 FPS 实时远程视口，并不是 CLI-Anything 的良好根抽象。

拟议的新抽象：Live Preview Session¶

当前协议以 bundle 为中心。

为了支持弹窗实时预览，添加第二个对象：

Live Preview Session

建议结构：

<root>/
  sessions/
    <session_id>/
      session.json
      current/
        manifest.json
        summary.json
        artifacts/
      history/
        <bundle_id_1>/
        <bundle_id_2>/

其中：

history/ 存储不可变的 preview bundle
current/ 指向实时查看器可见的最新状态
session.json 存储会话元数据和刷新序列号

这增加了一项关键能力：

实时窗口可以观察一个稳定的路径，同时 harness 持续发布新的预览状态

规范命令表面¶

`cli-hub`¶

当前规范的查看器命令为：

cli-hub previews inspect <bundle-or-session>
以文本或 JSON 检查现有的 bundle 或 live session
cli-hub previews html <bundle-or-session>
为 bundle 或 live session 渲染 HTML
cli-hub previews watch <session-dir>
针对 session 运行实时预览查看器
cli-hub previews open <bundle-or-session>
在浏览器窗口中打开 bundle 或 live session

有用的标志：

--open
--browser default|chromium|firefox
--app-mode
--poll-ms 500
--host 127.0.0.1
--port 0

Harnesses¶

保持 harness 命令表面最小且标准化：

preview live start --recipe quick [--open]
preview live push
preview live stop
preview live status

行为：

start 创建 live session，并可选地打开查看器窗口
push 将新的预览状态发布到 session 中
stop 干净地关闭 session
status 报告 session 路径、当前 bundle 元数据，以及供智能体使用的紧凑 trajectory_summary

第一个实现可以让 push 为显式调用。

之后，当 session 处于活动状态时，变更命令可以选择自动触发 push。

这必须支持桌面会话中的普通 Ubuntu 终端。

推荐的打开顺序：

chromium --app=http://127.0.0.1:PORT/...
google-chrome --app=...
microsoft-edge --app=...
firefox --new-window ...
xdg-open ...

规则：

如果已设置 DISPLAY 或 WAYLAND_DISPLAY，--open 可以启动弹窗
如果机器是无头（headless）环境，不要仅仅因为弹窗无法打开就让预览命令失败
打印本地 URL 并继续提供服务

为什么浏览器应用模式是推荐的根解决方案：

仓库中不需要额外重的 GUI 依赖
容易布局图像/视频/JSON
容易自动刷新
从终端简单支持 Linux 弹窗
智能体和人类可以共享同一个查看器

每个软件如何适配¶

Shotcut / Openscreen¶

适合实时窗口预览的良好候选。

实时行为：

重新生成低分辨率审阅片段
重新生成采样帧/联系表
查看器自动重新加载片段和主画面帧

这是近实时的，而非逐帧编辑播放。

Blender¶

适合实时预览的良好候选。

实时行为：

重新运行快速的 Workbench 或 Eevee 预览
发布主静帧、备选静帧或转盘片段
查看器自动刷新图像和元数据

FreeCAD¶

适合实时预览的良好候选。

实时行为：

重新生成等轴测/前/顶/右视图图像
查看器更新四视图布局

这对于几何变更后的智能体验证尤其有用。

RenderDoc¶

RenderDoc 有所不同。

实时行为应当意味着：

监听新选中的采集/事件状态
刷新缩略图/输出目标/流水线摘要

它并不是 Blender 或 Shotcut 那种意义上的连续渲染监视器。

首个实时窗口版本的非目标¶

没有通用远程帧缓冲流式传输
不要求 60 FPS 交互式播放
没有每个 harness 的自定义桌面应用
不强制整个仓库依赖 Qt

分阶段实施计划¶

目标：

从终端在独立窗口中打开已有的 preview bundle
在 Linux/Ubuntu 上以浏览器应用模式启动
无头模式回退到 URL 输出

交付物：

cli-hub previews open
Linux/Ubuntu 上的浏览器应用模式启动
无头模式下回退到 URL 输出

这是最快且高价值的一步。

阶段 2：实时会话协议¶

目标：

让查看器在 bundle 持续更新的同时观看一个稳定会话

交付物：

session.json
trajectory.json
current/
cli-hub previews watch
基于轮询的实时重载

阶段 3：Harness 集成¶

目标：

让主要的支持 preview 的 harness 发布实时更新

推荐的首批集合：

shotcut
openscreen
blender
freecad

RenderDoc 应在实时会话机制稳定之后再加入。

阶段 4：自动发布钩子¶

目标：

当实时会话处于活动状态时，变更类命令会自动发布新的 preview

这应当是可选加入的，因为自动生成 preview 可能代价较高。

结论¶

是的，preview 系统可以支持独立弹出的实时预览窗口。

正确的根本设计是：

不是“每个 harness 各自拥有一个实时监视器”
而是“每个 harness 发布 preview 状态，由 cli-hub 拥有实时弹出查看器”

这是 CLI-Anything 最通用、最精简且最具扩展性的解决方案。

2026-04-22：FreeCAD Motion CLI¶

状态：

已为 cli-anything-freecad 实现一个真实的 motion 命令组
保持 motion 与 preview/live preview 相互独立
motion 输出现在是 keyframes -> real FreeCAD GUI frame renders -> ffmpeg video

新的 CLI 表面：

motion new
motion list
motion get
motion delete
motion keyframe
motion sample
motion render-frames
motion render-video

当前范围：

当前支持的目标类型：part
插值：关键帧之间的线性位置 + 欧拉旋转插值
相机预设：hero、front、top、right
适配模式：initial、per-frame
视频格式：mp4、webm、gif

实现说明：

新核心模块：freecad/core/motion.py
FreeCAD 序列渲染在单个 GUI 宏进程中完成，而不是每帧启动一个 FreeCAD 进程
帧目录现在会写入 sequence.json 清单，以便后续编辑/复用
这是一条真实逐帧渲染路径；它不会合成中间运动帧

验证：

test_core.py -k 'TestMotion or test_get_info' -> 6 passed
test_full_e2e.py -k 'motion_render_frames_subprocess or motion_render_video_subprocess' -> 2 passed
包含 motion/bounds/align 的定向单元运行 -> 9 passed

真实冒烟测试产物：

项目：/root/preview-artifacts/20260422/freecad-motion-smoke/project.json
帧：/root/preview-artifacts/20260422/freecad-motion-smoke/frames
视频：rollout.mp4

当前限制：

motion 目前只动画化 part 的放置位置
它尚未直接驱动 FreeCAD Assembly 关节 / Simulation 对象
它足以满足我们当前通过 CLI 构建的 rover/Curiosity 风格展示流程，但还不是原生关节求解器动画流水线

2026-04-22：Curiosity V6 True Motion Showcase¶

状态：

将新的 FreeCAD motion CLI 连接到真实的 Curiosity v6 最终项目
为 freecad_live_preview_demo.py 添加了可复用的 motion-showcase 模式
渲染了一个完全真实的逐帧 Curiosity 展示视频

新的脚本路径：

python3 docs/scripts/freecad_live_preview_demo.py motion-showcase --timeline ... --output-dir ...

它的功能：

从现有 trajectory 加载真实的最终 Curiosity v6 项目
添加展示舞台几何体作为真实部件
将 13 个关键姿态写入真实项目的 motions 集合
调用 cli-anything-freecad motion render-video
保留真实帧序列和静态帧

产物集合：

motion 项目：curiosity_true_motion.json
视频：curiosity_true_motion.mp4
清单：motion_manifest.json
帧：/root/preview-artifacts/20260422/freecad-curiosity-v6-true-motion/frames
静态帧： start.png mid.png final.png

验证：

脚本 py_compile 通过
motion-showcase 运行成功完成
输出统计：
时长：6.0s
帧率：12
帧数：73
文件大小：315,872 bytes

质量说明：

现在这是一条真实可信的运动渲染路径。
运动本身仍然是由位置驱动（placement-driven）驱动，而不是由关节求解器驱动（joint-solver-driven）。
从视觉上看，火星车的平移和布景地面看起来正确，但实际的轮式/rocker-bogie（摇臂-转向架）机构模拟仍是未来工作。

2026-04-22：Curiosity 转盘运动¶

状态：

扩展了 motion-showcase，以支持 --motion-style spin。
渲染了第二个真实逐帧的 Curiosity 运动片段，用于旋转 / 转盘展示。

产物集：

运动项目：curiosity_turntable_motion.json
视频：curiosity_turntable_motion.mp4
清单：motion_manifest.json
帧：/root/preview-artifacts/20260422/freecad-curiosity-v6-turntable-motion/frames
静帧： start.png mid.png final.png

验证：

脚本 py_compile 在 spin 模式改动后通过。
motion-showcase --motion-style spin 成功完成。
输出统计：
时长：7.0s
fps：12
帧数：85
文件大小：719,298 bytes
对 start/mid/final 的人工目视检查确认了真正的转盘式旋转视图变化。

质量说明：

这是真正渲染出的转盘，而非稀疏姿态混合。
它仍然使用位置驱动（placement-driven）运动，而不是 FreeCAD Assembly/Robot 机构仿真。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/CLI-Anything

预览进度¶

工作区¶

已实现内容¶

本轮新增内容¶

当前验证状态¶

已在本机上完全验证¶

本机已部分验证¶

当前机器说明¶

FreeCAD¶

RenderDoc¶

本地产物¶

仍存在的缺口¶

跨进程 live session 稳定性¶

RenderDoc 捕获生成¶

FreeCAD 布尔运算预览缺口¶

Empire State Building 尝试¶

FreeCAD body 预览对齐¶

共享运行时清理¶

设计问题：预览是否能支持独立的实时弹窗？¶

推荐立场¶

为什么窗口应位于 cli-hub 中¶

这里的“实时”应意味着什么¶

拟议的新抽象：Live Preview Session¶

规范命令表面¶

cli-hub¶

Harnesses¶

Linux/Ubuntu 上的弹窗策略¶

推荐的实时传输方式¶

每个软件如何适配¶

Shotcut / Openscreen¶

Blender¶

FreeCAD¶

RenderDoc¶

首个实时窗口版本的非目标¶

分阶段实施计划¶

阶段 1：为已有 Bundle 提供弹出窗口¶

阶段 2：实时会话协议¶

阶段 3：Harness 集成¶

阶段 4：自动发布钩子¶

推荐的下一步具体行动¶

结论¶

2026-04-22：FreeCAD Motion CLI¶

2026-04-22：Curiosity V6 True Motion Showcase¶

2026-04-22：Curiosity 转盘运动¶

为什么窗口应位于 `cli-hub` 中¶

`cli-hub`¶