CLI-Anything 演示资产全解读：FreeCAD、Blender、Draw.io 等 Harness 如何用 Preview、Live Preview 与 Trajectory 闭环产出真实工件

面向 AI Agent 的软件自动化框架 CLI-Anything 将任意桌面软件「翻译」为可被 Agent 驱动的 CLI。而仓库中的演示资产（Demo Assets）则是检验这套体系的最直观窗口：五个来自社区的典型场景——FreeCAD 中的 Curiosity 漫游车建模、Blender 中的轨道中继卫星硬表面建模、Draw.io 中的 HTTPS 握手时序图、Slay the Spire II 的游戏自动化，以及 VideoCaptioner 的字幕生成——展示了 Agent 在纯 CLI 环境下如何通过 preview、preview live 与 trajectory.json 组成的“预览-实时-轨迹”闭环，逐步逼近并产出可验证的真实工件。读完本文，你将理解演示资产在仓库中的定位、支撑它们运行的 Preview Protocol 核心数据结构，以及每个演示背后对应的 Harness 实现与源码位置。

演示资产库的定位：一份“资产侧”的落地页

assets/demos/README.md 是整个仓库演示页所用 GIF 与图片的集中地。它的功能被原文明确描述为：仓库顶层 README.md 是“首要展示页”（primary showcase），而这份文档是“资产侧落地页”（asset-side landing page），保证该目录在仓库中即使被单独访问也仍然自洽、可读。

也就是说，读者存在两条阅读路径：

• 顶层 README：在 ## 🎬 Real-World Demos 一节集中展示各演示的动图与说明，属于完整叙事；
• 资产目录 README：本文件，按“Harness（命令行工具包）→ Preview 技术栈 → 最终工件”的方式，为每个演示提供卡片式的索引信息。

每则演示都遵循统一的元信息格式，例如：

Harness: cli-anything-freecad | Preview Stack: preview + preview live + trajectory.json | Artifact: Agent-built Curiosity-style rover

这三元组概括了 CLI-Anything 演示背后最核心的工程思想：Agent 并不是一次性“跑完”命令，而是在预览、实时预览与轨迹记录的循环中迭代构建工件。这也是解读以下五个演示共同的关键词。

贯穿五个演示的技术主线：Preview Bundle、Live Session 与 trajectory.json

要读懂演示动图里“画面逐步长出模型”的过程，需要先理解仓库中 docs/PREVIEW_PROTOCOL.md 提出的跨 Harness 预览协议（该协议文档标注更新于 2026-04-23）。协议的目标是：中间过程的可视化反馈不依赖各个软件自研的监控界面，而是统一为一种可被 Agent 运行时与 cli-hub 消费的“预览产物协议”。

协议中最核心的对象有三个层级：

1. Preview Bundle（预览包）——不可变的一次快照目录，结构固定：

<bundle_dir>/
  manifest.json      # 机器可读契约
  summary.json       # 人类 / Agent 摘要
  artifacts/
    hero.png
    gallery_01.png
    preview.mp4
    pipeline_diff.json

其中 manifest.json 是机器契约，summary.json 面向人类/Agent 快速阅读，artifacts/ 里才是由“真实软件或其原生工具”生成的预览产物。

2. Live Session（实时会话）——用于 preview live 工作流，稳定的会话对象：

<session_dir>/
  session.json        # 可变会话头（当前 head）
  trajectory.json     # 追加式的命令→预览发布历史（永久回放对象）
  current -> ../quick/<bundle_id>/

3. trajectory.json——这是演示元信息中反复出现的文件名。协议文档特别强调：单个 bundle_dir 是“不可变快照”而非“稳定历史对象”，当缓存键、源指纹、recipe、选项或协议版本变化时都会生成新的 bundle 目录。因此会话的真正稳定句柄是：session_dir 代表当前频道，trajectory.json 代表完整发布历史。它记录每一步的 command、bundle_id、bundle_dir、source_fingerprint、publish_reason 等字段，让查看器能够“左侧渲染命令流、右侧渲染对应画面、并支持回退到任意历史检查点”。

源码侧的实现证据：FreeCAD Harness 的 preview 命令族

这套协议不是停留在纸面设计，freecad/agent-harness/cli_anything/freecad/freecad_cli.py 中真实存在一组完整的 preview 命令：

• preview recipes：列出可用预览配方；
• preview capture：按指定 recipe 生成新的预览包，支持强制刷新与自定义根目录；
• preview latest：查看当前最新预览包；
• preview live start / push / status / stop：启动实时会话、把新 bundle 推入当前会话、查询会话状态、停止会话（且不删除已生成产物）；
• preview live monitor：隐藏的内部后台轮询命令（通过 --session-dir 指向会话目录）。

此外，该文件顶部（freecad_cli.py#L84-L128）实现了两个关键的“联动”函数：_spawn_live_viewer 负责在可用时拉起 cli-hub 的实时预览查看窗口，_spawn_live_poller 则把 preview live monitor --session-dir <dir> 作为后台进程启动，从而实现“Agent 每次构建后自动发布、查看器自动刷新”的闭环。这与协议文档中“Host/runtime 层可选地把 bundle 产物回填进模型上下文”的设计一脉相承。

默认的 bundle 存放位置遵循协议约定：有稳定项目路径时为 <project_dir>/.cli-anything/previews/<software>/<recipe>/<bundle_id>/；没有项目路径时则回退到用户目录下的 ~/.cli-anything/previews/...。

演示一：FreeCAD — 用预览循环“长出”一台 Curiosity 风格漫游车

维度	说明
Harness	cli-anything-freecad
Preview 技术栈	preview + preview live + trajectory.json
最终工件	Agent 构建的 Curiosity 风格漫游车

Harness: cli-anything-freecad | Preview Stack: preview + preview live + trajectory.json | Artifact: Agent-built Curiosity-style rover

Agent 通过 FreeCAD Harness 增量组装一台灵感源自火星车 Curiosity 的漫游车，其间持续发布真实的 FreeCAD 预览包、刷新实时预览会话，并把“命令→预览画面”的对应关系记录进历史以便回放。动图中可以看到工件逐步成型的过程。

深入 FreeCAD Harness 的实现，预览并非独立于 CAD 操作之外的功能：cli_anything/freecad/core/preview.py 与 cli_anything/freecad/utils/preview_bundle.py 负责生成与封装预览包，而 tests/test_full_e2e.py 等测试则覆盖了从建模操作到预览发布的全链路。这也呼应了协议的第一条设计目标：预览必须来自真实软件及其真实后端或真实工程格式，不允许对渲染器做玩具式的重实现——动图中的每一帧画面都是 FreeCAD 真实导出结果。

演示二：Blender — 硬表面轨道中继卫星的“分阶段生长”

维度	说明
Harness	cli-anything-blender
Preview 技术栈	preview + preview live + trajectory.json
最终工件	Agent 构建的轨道中继卫星

Harness: cli-anything-blender | Preview Stack: preview + preview live + trajectory.json | Artifact: Agent-built orbital relay drone

第二个演示把“实时预览循环”的机制体现得更为明显：Agent 使用 Blender Harness 在真实的预览循环中逐阶段生长出一台硬表面风格的轨道中继卫星——每个构建阶段都推送新的“渲染支撑”预览包，实时会话跟踪当前 head，trajectory 则把每一条命令与对应的视觉状态绑定；演示在完成整个场景、准备好做转盘展示（polished turntable）时收尾。

协议文档中给出的 trajectory.json 示例正是以 Blender 场景（orbital-relay-drone，工程文件 scene.blend-cli.json）为背景，展示了典型的步骤记录形态——每条 step 都包含 step_id、执行的完整命令、起止时间、publish_reason（例如 live-start）、源指纹与 bundle 路径等字段。对应实现可继续阅读 blender/agent-harness/cli_anything/blender/blender_cli.py、blender/agent-harness/cli_anything/blender/core/preview.py 以及 tests/test_core.py 中的相关测试。

演示三：Draw.io — 纯命令行绘制 HTTPS 握手时序图

维度	说明
Harness	cli-anything-drawio
耗时	约 4 分钟
最终工件	.drawio + .png

Harness: cli-anything-drawio | Time: ~4 min | Artifact: .drawio + .png

与前两个“逐步建模”的场景不同，Draw.io 演示展示的是从零开始、完全经由 CLI 命令产出文档型工件的能力：Agent 创建一张完整的 HTTPS 连接生命周期图。结合顶层 README 的补充描述，这幅图覆盖 TCP 三次握手、TLS 协商、加密数据传输直至 TCP 四次挥手终止的完整链路，最终同时产出可继续编辑的 .drawio 工程文件与渲染好的 .png。

该演示由社区贡献者 @zhangxilong-43 提供，对应 Harness 的实现位于 drawio/agent-harness/cli_anything/drawio，配套文档为 drawio/DRAWIO.md。

演示四：Slay the Spire II — Agent 实时决策的游戏自动化

维度	说明
Harness	cli-anything-slay-the-spire-ii
最终工件	自动化游戏对局

Harness: cli-anything-slay-the-spire-ii | Artifact: Automated gameplay session

该演示验证了 CLI-Anything 向游戏领域的延伸：Agent 借助 CLI Harness 完整游玩一局 Slay the Spire II，通过读取游戏状态、选择卡牌、规划路线，实时做出策略决策（详见顶层 README 的同一小节）。其背后是 slay_the_spire_ii 目录下的完整 agent-harness——包含负责与游戏本体通信的 bridge/plugin 部分与 Python CLI 部分——而 skills/cli-anything-slay-the-spire-ii/SKILL.md 则为 Agent 提供了“如何驱动该 Harness”的操作技能说明。演示由社区贡献者 @TianyuFan0504 提供。

演示五：VideoCaptioner — 字幕自动生成与叠加

维度	说明
Harness	cli-anything-videocaptioner
最终工件	已叠加字幕的视频帧

Harness: cli-anything-videocaptioner | Artifact: Captioned video frames

最后一个演示聚焦视频后期：Agent 使用 VideoCaptioner CLI 为视频内容自动生成并叠加带样式的字幕。原始文档通过 “Sub A / Sub B” 的前后对照表格展示效果——videocaptioner-before.png 为加字幕前的原始帧，videocaptioner-after.png 为处理后的帧。结合顶层 README 的说明，字幕渲染支持双语文本与可定制的排版样式。该演示由社区贡献者 @WEIFENG2333 提供，Harness 实现见 videocaptioner/agent-harness/cli_anything，技能说明见 skills/cli-anything-videocaptioner/SKILL.md。

演示素材的生成方式与可复现路径

assets/demos/README.md 在两则主要演示的配图下方注明了素材来源：“README GIF generated from the full local demo video with a speed-adjusted, high-quality ffmpeg palette workflow”——即这些动图并非脚本录屏的简单压缩，而是从完整本地演示视频出发，经过调速处理与高质量 ffmpeg palette 流程生成的产物，这保证了演示画面在 README 中的清晰度与体积的平衡。

如果你想亲身体验这些演示背后的闭环，仓库中已准备好完整的复现素材：

• 技能文件：所有 Harness 的 Agent 操作说明统一收纳在仓库顶层 skills/ 目录下，例如 cli-anything-freecad/SKILL.md、cli-anything-blender/SKILL.md、cli-anything-drawio/SKILL.md；
• Harness 源码与测试：每个演示对应的 agent-harness/ 目录既是 Python 包（含 setup.py），又带有完整测试（例如 FreeCAD 的 tests/test_full_e2e.py）；协议层面可进一步阅读 docs/PREVIEW_PROTOCOL.md 与仓库内 docs/PREVIEW_MECHANISM_PROGRESS.md、docs/PREVIEW_PROGRESS.md 等进展文档；
• 运行前提：按协议“渲染路径必须保持真实”的原则，驱动这些演示需要在本机真实安装对应软件（FreeCAD、Blender、Draw.io、Slay the Spire II、VideoCaptioner 等），CLI 只是操作这些真实软件的命令层。

小结

五则演示资产覆盖了 CLI-Anything 从 3D/CAD 创作（FreeCAD、Blender）、图表工程（Draw.io）、游戏自动化（Slay the Spire II）到视频字幕（VideoCaptioner）的多元领域，而它们共享同一条技术主线——由 preview（一次性预览包）、preview live（实时会话）与 trajectory.json（追加式轨迹历史）构成的分层反馈机制。这条主线让 Agent 的每次操作都能被真实软件渲染成可检视的画面，让每次发布都能被记录成可回放的历史，最终让“Agent 构建真实工件”从一次性运气变为可观测、可中断、可复现的工程过程。