CLI-Anything 跨 Harness 预览机制解析：从 Preview Bundle 协议到 FreeCAD 实时轨迹与真渲染展示

2026-09-08 22:18:31作者：郦嵘贵Just

导读：本文以 docs/PREVIEW_MECHANISM_PROGRESS.md 为主线，系统讲解 CLI-Anything 为"让所有软件具备 Agent 原生能力"而建立的跨软件预览机制（cross-harness preview mechanism）——一套五层架构：标准化的 Preview Bundle 磁盘产物契约、软件 harness 侧统一的 preview 命令组、可追踪可回放的 Live Session、通用查看器 cli-hub previews ...，以及最终的真渲染 Motion Showcase。读完你将掌握协议如何设计、bundle 的 JSON 契约长什么样、live session 如何用 session.json + trajectory.json 记录命令到预览的完整轨迹、五个试点 harness 各自集成到什么程度，以及 FreeCAD 为何是目前最深的落地样板。

一、机制概述：为什么需要一个"跨 Harness 预览协议"

CLI-Anything 早有一套针对最终渲染的强规则：必须使用真实软件、操作原生格式、校验真实输出文件。但对"中间过程的视觉反馈"，此前每个 harness 都各自为政——视频缩略图抽取、截图导出、渲染预设、capture 缩略图、输出目标 dump……这些能力存在，却是"应用本地的命令"，彼此没有统一的产物形态，Agent runtime、cli-hub 或未来的宿主 UI 无法用同一套方式消费。

正如 docs/PREVIEW_PROTOCOL.md 指出的：

The missing abstraction is not "a universal monitor widget". The missing abstraction is "a universal preview artifact protocol".

缺少的不是"一个通用监视器控件"，而是**"一个通用的预览产物协议"**。预览机制就是补上这一层的抽象，让视频剪辑、CAD、3D、GPU 调试等不同领域共享同一种中间结果消费方式。

设计目标与非目标

协议的目标（见 docs/PREVIEW_PROTOCOL.md）：

渲染路径诚实：预览必须来自真实软件、真实后端或真实项目格式，禁止用玩具渲染器重实现；
跨领域通用：同一协议同时覆盖视频时间线、CAD 视图、Blender 渲染、RenderDoc 输出；
足够便宜：预览要快、分辨率低、可缓存、体积小，能在 Agent 循环中高频使用；
可增量采纳：一个命令组 + 一个小 helper 即可接入，不必新写前端；
无头可用：bundle 生成与校验不依赖 GUI。

明确的非目标：这不是最终渲染/导出的替代品；不是实时远端帧缓冲或 GUI 流式协议；不要求每个 harness 都支持交互式时间线拖动；不强制单一产物类型。

二、机制架构：五层结构

按 docs/PREVIEW_MECHANISM_PROGRESS.md，当前机制分五层：

层级	职责	关键落点
1. Preview Bundle	预览产物的稳定磁盘契约	协议见 docs/PREVIEW_PROTOCOL.md；实现于 cli-anything-plugin/preview_bundle.py，各 harness 再 vendor 一份 helper
2. Harness Preview Commands	归一化命令面：`preview recipes` / `preview capture` / `preview latest` / `preview diff`	每个 harness 用真实后端产出真实产物，禁止"截图替身"
3. Live Session	长生命周期目录，追踪可变 `session.json`、只追加 `trajectory.json` 与当前 bundle head	支持显式 push 与基于源状态指纹的 poll-first 自动刷新
4. Generic Viewer	通用查看器	实现在 cli-hub，命令为 `previews inspect/html/watch/open`
5. Final Motion Showcase	独立于 preview 的最终演示渲染	静态预览不够时才使用；当前 FreeCAD 以真实逐帧 motion 渲染实现

分层的关键语义：软件 harness 通过 cli-anything-<software> preview ... 发布预览，cli-hub previews ... 只负责检查、渲染、打开或监视已存在的 bundle 与 live session。当前命令面中不存在 cli-hub preview、cli-hub review、cli-hub open-preview 之类的别名。

2.1 各 Harness 的集成进度（截至 2026-04-23）

文档记录了五个试点 harness 的状态：

shotcut：快速预览 capture、live session、poll 模式自动刷新；已修复黑帧预览回归；
openscreen：快速预览 capture、bundle 发射、在稳定预览根旁维护只追加的 trajectory.json；
blender：preview capture、live session、poll 自动刷新；preview live status --json 返回 trajectory_summary；真实 Gyro Observatory 演示脚本带分阶段预览检查点；
freecad：快速预览 capture、live session、poll 自动刷新、trajectory_summary、更丰富的 preview/export 宏重建、用于真实逐帧渲染的 motion CLI；
renderdoc：preview capture、preview diff、面向回放的 bundle 生成、capture/diff 历史的追加式 trajectory.json。

三、Preview Bundle：统一产物契约

3.1 目录布局与位置

Preview Bundle 是一个目录，包含机器契约 manifest.json、给人/Agent 看的摘要 summary.json，以及真实软件（或检查真实产物的原生工具）生成的预览产物 artifacts/：

<bundle_dir>/
  manifest.json
  summary.json
  artifacts/
    hero.png
    gallery_01.png
    gallery_02.png
    preview.mp4
    pipeline_diff.json

默认位置分两种（源码见 cli-anything-plugin/preview_bundle.py 的 bundle_root()）：

已知项目路径：<project_dir>/.cli-anything/previews/<software>/<recipe>/<bundle_id>/
尚无稳定项目路径：~/.cli-anything/previews/<software>/<recipe>/<bundle_id>/

设计理由：预览产物尽量贴近项目；bundle 便于垃圾回收；cli-hub 可以扫描可预测的根目录。

3.2 Bundle ID 与缓存键

推荐 bundle id 格式：<UTC timestamp>_<short fingerprint>_<recipe>，示例 20260419T104530Z_9f0a2c4b_quick。指纹应派生自：项目/capture 指纹、recipe 名、归一化 preview 参数、harness 版本、协议版本——使 bundle 可缓存、可复现。

源码中的 build_cache_key()（cli-anything-plugin/preview_bundle.py）正是把上述五要素做 SHA-256 派生：

def build_cache_key(software, recipe, bundle_kind, source_fingerprint,
                    options=None, harness_version=None,
                    protocol_version=PROTOCOL_VERSION) -> str:
    return fingerprint_data({
        "protocol_version": protocol_version,
        "software": software,
        "recipe": recipe,
        "bundle_kind": bundle_kind,
        "source_fingerprint": source_fingerprint,
        "options": options or {},
        "harness_version": harness_version or "",
    })

prepare_bundle()（同文件 L171-L223）先算缓存键，非 --force 时调用 find_cached_manifest() 按缓存键查找磁盘上状态为 ok/partial 的既有 manifest；命中则返回 cached: True，否则用 datetime.now(timezone.utc) 生成 bundle id、创建目录。

3.3 Manifest Schema（机器契约）

manifest.json 的必填顶层字段：

字段	类型	说明
`protocol_version`	string	起始为 `preview-bundle/v1`
`bundle_id`	string	本 bundle 稳定 id
`bundle_kind`	string	`capture` 或 `diff`
`software`	string	Harness 名，如 `shotcut`
`recipe`	string	Harness recipe 名，如 `quick`、`quad`、`turntable`
`status`	string	`ok`、`partial` 或 `error`
`created_at`	string	ISO-8601 UTC
`generator`	object	CLI 命令、harness 版本、后端信息
`source`	object	项目/capture 身份与指纹
`artifacts`	array	预览产物描述符
`summary_path`	string	相对 `summary.json` 的路径

推荐可选字段：source_bundles（diff bundle 用）、context（事件 id、帧、相机等应用上下文）、warnings、metrics（廉价摘要指标）、labels（宿主过滤标签）。从源码看，finalize_bundle()（preview_bundle.py L262-L311）还额外写入了 cache_key，把缓存键固化进 manifest 以便 find_cached_manifest 匹配。

协议文档给出的完整 manifest 示例（含 generator.command 形如 cli-anything-shotcut --json -p demo.mlt preview capture --recipe quick，以及两条 artifact：hero.png 与 640x360 的 preview.mp4）可直接作为各 harness 实现的参照。

3.4 Artifact 描述符与标准角色

源码侧 artifact_record() 自动把传入路径转成相对 bundle 根的 POSIX 相对路径，media_type 缺省时用 mimetypes.guess_type() 推断。

角色词汇比文件类型更重要（查看器只认角色和 kind，不关心具体软件"意味着什么"）：

角色	含义
`hero`	快速检查时最优先的单张预览
`gallery`	一组相关视觉预览中的一张
`preview-clip`	短视频低清预览
`before` / `after`	diff bundle 中的基线/目标产物
`diff-json`	机器 diff 负载
`pipeline-json`	结构化管线/调试状态
`viewport`	特定相机/视图输出
`render-output`	输出目标或渲染帧
`thumb`	capture/媒体缩略图

3.5 性能预算与渲染规则

默认性能目标（指南性而非硬限制）：hero 图最长边 ≤ 1280px；gallery 3~8 张；preview clip ≤ 8 秒且 ≤ 720p；bundle 体积目标 ≤ 25MB。

渲染规则与 CLI-Anything 其余部分一致：

允许：用真实 app/后端生成低清预览；用 ffmpeg、RenderDoc API 等原生工具从真实渲染抽取帧或 dump 输出；打包进 bundle；
禁止：伪造渲染器近似 app 的预览行为；把无关 GUI 窗口截图当作唯一真相来源。

FreeCAD harness 的实现证据：capture()（freecad/agent-harness/cli_anything/freecad/core/preview.py）先 prepare_bundle，再生成一段重建整个工程的 FreeCAD 宏（_generate_preview_macro()，覆盖 parts/boolean/bodies/placements，最后用 view.saveImage(path, width, height, 'White') 真实导出 PNG），通过 freecad_backend.run_macro_content(..., gui_required=True, env={"QT_QPA_PLATFORM": "offscreen"}) 用真实 FreeCAD 后端执行。缺图时会记 warnings 并把 manifest status 降为 partial。

四、Live Session：命令到预览的实时轨迹

Live preview 在 bundle 之上新增两个对象：

session.json：可变的会话头，记录当前 bundle、查看器命令与实时 poller 状态；
trajectory.json：会话内命令→预览发布的只追加历史，是永久回放对象。

推荐布局：

<session_dir>/
  session.json
  trajectory.json
  current -> ../quick/<bundle_id>/

4.1 为什么需要 trajectory.json

bundle_dir 是单次不可变快照，不是稳定历史对象：缓存键不变时 bundle 目录可复用，而源指纹/recipe/选项/harness 版本/协议版本任一变化都会创建新目录。因此 Agent 与宿主 UI 不应把 bundle_dir 当作整个构建的永久句柄——稳定句柄是 session_dir（当前频道）与 trajectory.json（完整发布历史）。

4.2 session.json 推荐字段

包括 protocol_version（起始 preview-live/v1）、software、recipe、status（active|stopped）、current_bundle_id、current_bundle_dir、current_manifest_path、current_summary_path、current_step_id、latest_command、latest_publish_reason、trajectory_path、trajectory_step_count、history（为兼容保留的近期 bundle 列表，非权威回放日志）。

FreeCAD 的 _publish_live_session()（core/preview.py L473-L581）写的正是这套结构，还附带 watch_command/inspect_command/html_command/start_command/monitor_command 等可直接调用的辅助命令，并把 current 建为指向最新 bundle 目录的符号链接（_update_current_symlink）。

4.3 trajectory.json 的 schema

顶层包含 protocol_version（preview-trajectory/v1）、software、recipe、session_name、project_path、step_count、current_step_id 和 steps[]。每个 step 至少含 step_id、command、command_started_at、command_finished_at、publish_reason、source_fingerprint、bundle_id、bundle_dir、manifest_path、summary_path；可选 stage_label、note、status、cached。

例如协议文档中的步骤字段记录 cli-anything-blender --project scene.blend-cli.json preview live start --recipe quick 对应 bundle 20260423T101007Z_deadbeef_quick。这套结构让查看器能渲染"左侧命令流 + 右侧对应预览状态 + 任意回退到先前构建检查点"。

源码 helper 提供了完整能力：append_live_trajectory()（preview_bundle.py L405-L468）负责追加 step（自动编号 step-0001...）、维护 step_count/current_step_id/updated_at；summarize_trajectory()（L329-L359）产出紧凑的 trajectory_summary（含 latest_command、latest_publish_reason、recent_steps），使 Agent 不必二次读文件即可理解最近几步。

4.4 会话身份与跨进程稳定性

PREVIEW_PROGRESS 记录过一个重要修复：第一版实现部分依赖进程内 session_id 派生会话名，导致一次性 CLI 每次命令得到不同目录。现在（core/preview.py 的 _live_session_name）：有已保存 project_path 时，会话身份由稳定项目路径 + recipe 派生；仅未保存的内存项目才回退到会话内标识。

4.5 两种发布模式

Live session 支持两种刷新方式（FreeCAD CLI 见 freecad_cli.py L2273-L2367）：

显式 push：Agent 用 preview live push 主动打一个"命令→预览"检查点，适合源变化不足以触发 poll 的场景；
poll-first 自动刷新：preview live start --mode poll --source-poll-ms <ms> 启动隐藏后台进程 preview live monitor --session-dir ...，对项目文件指纹轮询（默认 500ms、下限 250ms），变化即自动重新 capture。

FreeCAD 的 poll_live_session_once()（core/preview.py L727-L848）每轮对比 last_rendered_fingerprint 与当前 fingerprint_file()，一致则 idle，不一致则重新 live_start(..., publish_reason="auto-poll") 并回写 poller 心跳。

五、通用查看器：cli-hub previews

查看器与发布方的职责切分是刻意设计（实现见 cli-hub/cli_hub/preview.py）：

cli-anything-<software> preview ... 发布预览状态
cli-hub previews ... 检查已有预览状态

规范命令：

cli-hub previews inspect <bundle-or-session>：文本打印 bundle 元数据、source 身份、summary 的 headline/facts/warnings、产物表、可用时的轨迹摘要；
cli-hub previews html <bundle-or-session> [-o output.html]：写出静态 HTML——先展示 summary，用 hero/gallery 渲染图片画廊，为 preview-clip 内嵌可播放 <video>，为 JSON 产物提供下载链接，有 trajectory.json 时渲染会话历史（源码对应 render_html() 与 _render_artifact_card()）；
cli-hub previews watch <session-dir> [--open] [--poll-ms 1500]：本地 HTTP 服务 + 自动刷新页面（源码中 _pick_trajectory_events、_normalize_trajectory 等把各种轨迹/时间线结构归一为同一 timeline 视图）；
cli-hub previews open <bundle-or-session>：打开 bundle 生成的 HTML，或浏览器版 live 监视器。

这是"通用"的真正含义：查看器不知道 Shotcut、FreeCAD、Blender、RenderDoc 各自是什么，它只知道 bundle role 与 artifact kind。inspect_bundle() / inspect_session() 在 CLI 与 HTML 两端共用同一套数据装载逻辑（resolve_bundle_ref 接受目录或 manifest.json 路径，is_live_session_ref 用 session.json 判别会话）。

六、FreeCAD：当前最深的 Preview 集成样板

PREVIEW_MECHANISM_PROGRESS.md 明确写道 "FreeCAD is currently the deepest preview integration"，它是整套机制的完整证明点：

真实 CLI 轨迹
真实 preview bundles
真实 live session 更新
真实最终 motion 渲染
程序化分屏视频合成

已实现项包括 part bounds（基元级世界包围盒）、part align（bbox 锚点对齐，替代纯靠猜的 -pos/-rot），以及更完整的 preview/export 宏重建：支持增/减材基元、线性/极坐标/镜像 pattern 特征、镜像零件（part mirror），并支持带特征放置的 body/additive/subtractive primitives。

FreeCAD 的 quick recipe（core/preview.py RECIPES L39-L52）一次导出四张 1280x960 PNG：hero(Isometric) + front/top/right(gallery)，背景白色；list_recipes() 将其注册为产物 hero+gallery、视图四选一。

6.1 Motion CLI：真实逐帧渲染

motion 与 preview/live preview 分离，管道为 keyframes -> 真实 FreeCAD GUI 逐帧渲染 -> ffmpeg 视频：

命令面：motion new / list / get / delete / keyframe / sample / render-frames / render-video
当前范围：目标 kind 为 part；关键帧间线性位置 + Euler 旋转插值；相机预设 hero|front|top|right；适配模式 initial|per-frame；输出 mp4|webm|gif
实现要点：整个序列在一个 GUI 宏进程内渲染而非逐帧启停 FreeCAD；帧目录写出 sequence.json 清单供后续编辑/复用；逐帧真实渲染，不合成中间运动帧

6.2 视频 / Showcase 状态

成品参考记录在 docs/FREECAD_VIDEO_REFERENCE.md：以真实 Curiosity v6 轨迹（对应 /root/preview-artifacts/20260421/freecad-curiosity-v6/trajectory.json，属本机产物、非仓库内容）构建的分屏"Agent 操作可视化"视频、重设计后的左侧 Agent Command Stream 命令卡片、以及三种真实 FreeCAD motion 结尾：drive（前进）、turntable spin（转盘旋转）、combo（先转一整圈再前进）。

Polished 渲染的结尾不再使用稀疏 hero-capture 混帧，而是走真实 combo 序列：从 cli-anything-freecad motion render-video 输出中取帧（对应 showcase-motion 目录）。分屏主体仍基于真实 CLI 轨迹与真实 live session，结尾不是屏幕录制，而是由最终项目状态派生的额外真实 FreeCAD hero captures 合成。

七、协议落地策略与演进计划

7.1 采纳模式：复制 canonical helper

仓库已有验证过的 "copy canonical helper into harness" 先例 repl_skin.py。preview 协议 v1 沿用同法：

canonical helper 在 cli-anything-plugin/preview_bundle.py；
试点 harness vendor 一份小 helper 为 utils/preview_bundle.py（如 freecad/agent-harness/cli_anything/freecad/utils/preview_bundle.py）；
helper 负责 bundle 目录创建、manifest/summary 写入、相对 artifact 描述符、缓存键生成。

这样避免给所有 harness 包引入新的共享运行时依赖。PREVIEW_PROGRESS.md 也承认复制式存在漂移风险，长期方向是收敛为一份共享运行时 helper。

7.2 首个 4-PR 落地规划

协议文档规划了四个务实的 PR：

PR1 地基：协议文档 + canonical helper + cli-hub 通用检查器（验收：样本 bundle 可被 inspect；HTML 查看器仅凭 manifest 元数据渲染图片与视频）
PR2 视频试点 shotcut/openscreen：preview capture --recipe quick = 低清渲染（shotcut 复用 core/export.py 渲染与 core/media.py 缩略图；默认预设 h264-fast、640x360，按固定百分比抽 5 张 PNG，中点帧作 hero）+ bundle 装配
PR3 3D/CAD 试点 blender/freecad：blender 用 eevee_preview/workbench 预设渲染单张低清静帧（用真实 Blender 后端执行 bpy，而非只生成脚本）；freecad 出 quick(单张 iso PNG) 与 quad(iso/front/top/right 四张，iso 为 hero、四视图为 gallery)
PR4 GPU 调试试点 renderdoc：preview capture --event-id 抽取 capture 缩略图 + 保存该事件 render target 输出 + dump 该事件管线状态 JSON；preview diff --event-a 100 --event-b 200 把 A/B 输出目标标为 before/after 并附 diff-json

四 PR 后的下一波推荐目标是 kdenlive（复用大部分 shotcut 逻辑）、godot（matrix 中已列为 preview-capable 提供方）、krita（帧/图像预览天然契合）。

7.3 测试要求

任何采纳协议的 harness 应补充：单元测试（bundle 写入路径归一化、manifest 生成、recipe 列表、缓存键稳定性）；E2E 测试（用真实后端生成真实 preview bundle，验证 manifest/summary 存在、每个清单内 artifact 路径存在、至少一个视觉产物、JSON 输出含 manifest_path）。对支持 diff 的 harness：验证 diff bundle 引用 source bundle/ref，且 diff JSON 产物存在。

FreeCAD 在本机验证证据（PREVIEW_PROGRESS.md 记录）：test_core.py → 76 passed；E2E 子集（macro_generation / preview_capture_bundle / preview_capture_subprocess / preview_live_poll_auto_refresh）→ 6 passed。运行前提：FreeCAD 需以 GUI 能力执行，该机器通过 xvfb-run 包装完成，属于本机环境配置而非仓库内容。

八、已知边界与推荐后续工作

按 PREVIEW_MECHANISM_PROGRESS.md 的诚实记录，机制"能工作但未 feature-complete"：

live preview 是近实时，不是连续视口流式传输；
部分 harness 只是 first-pass 集成；
FreeCAD motion 目前是零件放置驱动，不是 Assembly 关节驱动；真实的轮/rocker-bogie 机构模拟仍是未来工作（PREVIEW_PROGRESS 中多条逐帧视频的质量说明都强调这一点：真实渲染、无合成帧、但方向由 per-part placement 关键帧驱动）；
RenderDoc 生成全新本地 capture 受机器图形/运行时约束限制——在 llvmpipe/lavapipe 软件渲染环境下可注入并暴露 in-app API，但本地 StartFrameCapture/EndFrameCapture 无保存输出；回放已有 .rdc 与导出缩略图可用；
Blender 在协议/会话层面已与 FreeCAD 拉平 live preview 能力，但 showcase/demo 工具链比 FreeCAD 的 motion/video 栈浅。

其他已记录的真实限制：FreeCAD 在 part boolean fuse 后 preview 可能降级为 partial 且无图片产物，因此当前 demo 轨迹刻意用纯加操作保持图像流有效；早期地标还原 demo（Empire State、堆叠盒版 Taipei 101）经自查不合格，只保留为实验不作展示。

推荐的下一步工作（文档原样列出）：

扩展 Blender demo 工具链，突破首个 Gyro Observatory 证明点；
在 PR 栈变大前，把 preview 分支 rebase 到干净的 origin/main 基线上；
把这个大 checkpoint 拆成可评审的提交栈：protocol + cli-hub / shotcut / openscreen / blender / freecad / renderdoc / demo-video tooling。

九、核心结论

一套简单、务实、可横向扩展的机制已经成形，其关键设计决定可概括为（协议文档的 Decision Summary）：

标准化产物而不是标准化应用专属查看器：一切中间结果收敛到 preview-bundle/v1；
用真实软件生成预览：渲染路径始终诚实，禁止伪造；
让预览便宜、可缓存、可检查：默认 budget 让 Agent 循环高频可用；
把预览消费集中到 cli-hub：harness 只发布、cli-hub 统一查看/渲染/打开/监视。

从架构演进方向看（PREVIEW_PROGRESS.md 的 "Recommended Position"）：bundle 生成留在 harness，其上新增 live session 抽象，弹窗与实时刷新交给 cli-hub 统一拥有——harnesses 发布预览更新、cli-hub 打开与更新独立窗口，这也是 Agent 与人共享同一预览状态的最通用、最少重复实现的路（本地 HTTP + poll 刷新优先，必要时再升级 SSE/websocket）。相关背景与姊妹文档可继续阅读 docs/PREVIEW_PROTOCOL.md、docs/PREVIEW_PROGRESS.md 与 docs/FREECAD_VIDEO_REFERENCE.md。

CLI-Anything

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

项目地址：https://gitcode.com/GitHub_Trending/cl/CLI-Anything

登录后查看全文