预览机制进展¶

最后更新：2026-04-23 UTC

本文档记录了专用 preview 分支上跨 harness 预览机制工作的当前状态。

工作区¶

• Repo: /root/CLI-Anything-preview
• Branch: feat/preview-protocol
• Current checkpoint commit: 81dbe58

该检查点包含预览栈的第一个端到端版本，包括实时预览会话、bundle 协议、通用查看工具，以及 FreeCAD 中基于 motion 的展示渲染。

机制概述¶

当前机制由五层组成：

1. Preview Bundle
2. 预览输出的稳定磁盘契约。
3. 定义于 docs/PREVIEW_PROTOCOL.md。

4. 由 cli-anything-plugin/preview_bundle.py 和随附的 harness 辅助器实现。

5. Harness Preview Commands

6. 标准化命令面：
   • preview recipes
   • preview capture
   • preview latest
   • preview diff 在相关处

7. 每个 harness 负责使用真实后端生成可信的预览产物，而不是通过屏幕抓取。

8. Live Session

9. 一个长期存在的目录，用于跟踪：
   • 可变的 session.json
   • 仅追加的 trajectory.json
   • 当前 bundle 头

10. 支持以下两种方式：

    • 显式推送
    • 基于源状态指纹的轮询优先自动刷新

11. Generic Viewer

12. 在 cli-hub 中实现。
13. 支持：
    • cli-hub previews inspect
    • cli-hub previews html
    • cli-hub previews watch
    • cli-hub previews open

14. 让 agent 和人类通过不同界面使用同一预览状态。

15. Final Motion Showcase

16. 与 preview 分离。
17. 用于静态预览不足以满足需求的收尾演示。
18. 目前通过真实的逐帧 motion 渲染为 FreeCAD 实现。

已实现内容¶

协议 / 平台¶

• docs/PREVIEW_PROTOCOL.md
• cli-anything-plugin/preview_bundle.py
• cli-anything-plugin/HARNESS.md preview 需求
• cli-hub/cli_hub/preview.py
• cli-hub previews CLI 集成

支持预览的 Harness¶

• shotcut
• 快速预览捕获
• Live Session
• 轮询模式自动刷新

• 已修复黑色预览回归问题

• openscreen

• 快速预览捕获
• bundle 生成

• 在稳定的预览根目录旁生成仅追加的 trajectory.json

• blender

• 预览捕获
• Live Session
• 轮询模式自动刷新
• preview live status --json 返回 trajectory_summary

• 带有分阶段预览检查点的真实 Gyro Observatory 演示脚本

• freecad

• 快速预览捕获
• Live Session
• 轮询模式自动刷新
• preview live status --json 返回 trajectory_summary
• 更丰富的预览/导出宏重建

• 用于真实帧渲染的 motion CLI

• renderdoc

• 预览捕获
• 预览差异
• 面向回放的 bundle 生成
• 用于捕获/差异历史的仅追加 trajectory.json

规范命令划分¶

请一致使用以下表述：

• 软件 harness 通过 cli-anything-<software> preview ... 发布预览
• cli-hub previews ... 仅检查、渲染、打开或监视现有的 bundle 和 Live Session

当前命令面中没有 cli-hub preview、cli-hub review 或 cli-hub open-preview 别名。

FreeCAD 特有的预览机制进展¶

FreeCAD 目前是该分支上集成最深的预览机制。

已实现：

• 预览捕获与实时预览
• 轮询优先的实时刷新
• part bounds
• part align
• 更好的预览/导出宏重建，用于：
• 加法/减法图元
• 阵列特征
• 镜像零件
• motion CLI 命令面：
• motion new
• motion list
• motion get
• motion delete
• motion keyframe
• motion sample
• motion render-frames
• motion render-video

这使得 FreeCAD 成为完整机制的主要验证点：

• 真实的 CLI 轨迹
• 真实的 Preview Bundle
• 真实的 Live Session 更新
• 真实的最终 motion 渲染
• 程序化分屏视频合成

视频 / 演示状态¶

当前参考产物记录在：

• docs/FREECAD_VIDEO_REFERENCE.md

已完成的重要部分：

• 分屏 agent 操作可视化视频
• 重新设计左侧 Agent Command Stream
• 真实的 FreeCAD motion 结尾
• 驱动
• 转台旋转
• 组合：先旋转一整圈，再向前移动

已知差距¶

该机制可以工作，但尚未功能完备。

当前限制：

• 实时预览是近实时的，不是连续的视口流式传输
• 部分 harness 的预览集成仍处于首轮实现阶段
• FreeCAD motion 目前由零件放置驱动，而非装配约束驱动
• RenderDoc 预览在本地生成新捕获时受到机器图形/运行时限制
• Blender 现在在协议/会话层面与实时预览具备同等能力，但其展示/演示工具仍然比 FreeCAD 的 motion/video 技术栈更浅

建议的后续工作¶

1. 将 Blender 演示工具扩展到首个 Gyro Observatory 验证点之外。
2. 在 PR 堆栈进一步变大之前，将此 preview 分支重组到干净的 origin/main 基础之上。
3. 稍后将此大型检查点拆分为可审查的提交堆栈：
4. 协议 + cli-hub
5. shotcut / openscreen
6. blender
7. freecad
8. renderdoc
9. 演示/视频工具

相关文档¶

• docs/PREVIEW_PROTOCOL.md
• docs/PREVIEW_PROGRESS.md
• docs/FREECAD_VIDEO_REFERENCE.md
• docs/FREECAD_DEMO_PROPOSALS.md