VuuSpot 用户使用指南

用时间线、素材和实时预览，把创意组合成可交付的动画内容。

1. 开始使用

VuuSpot 是面向动画、演示和视觉内容的组合工作台。项目由场景、轨道、片段、素材和项目元数据组成；时间线决定内容在帧上的出现顺序，预览用于检查组合结果。

推荐起步方式：从项目菜单新建项目，先确认画布尺寸与时长，再添加素材和时间线内容。每次重要修改后先保存，再同步预览，最后导出。

2. 项目与文件

2.1 项目菜单

入口用途
新建项目创建新的 VuuSpot 项目。
打开项目从磁盘打开 .vuo 项目文件。
保存 / 另存为保存当前项目，或创建新的项目副本。
最近打开的项目快速恢复最近使用的项目。
导出 MP4 / PPTX / 网页按当前项目和导出范围生成交付文件。

.vuo 是项目内容与编辑工作区状态的来源。最近项目列表只用于找回路径，不替代项目文件。

2.2 推荐项目流程

  1. 新建或打开项目。
  2. 设置项目名称、作者、摘要、版本和依赖信息（需要时）。
  3. 添加素材、场景、轨道和片段。
  4. 保存项目并确认预览与时间线一致。
  5. 按交付目标导出 MP4、PPTX 或网页。

3. 工作台

左侧工具栏用于切换项目和工作区操作；中央区域显示画布/组合结果与时间线；右侧可显示共享 AI Agent。顶部项目按钮包含打开、保存和导出操作。

区域用途
项目菜单新建、打开、保存、另存为、最近项目和导出。
预览区检查当前场景的组合、动画和播放范围。
时间线查看轨道和片段的帧范围、顺序与关键帧。
AI 按钮显示或隐藏共享 Agent 面板。
Settings打开 Host Settings 或 Agent Settings。
编辑边界：不要直接修改预览 WebView、屏幕坐标或 Flutter 界面。项目变更应通过工作台提供的编辑入口或共享 Agent 完成。

4. 时间线与动画

4.1 场景、轨道和片段

场景承载一段完整内容；轨道组织同类或同层级内容；片段是时间线上实际出现的素材或图层。先确定场景结构，再安排片段的入点、出点和层级。

4.2 关键帧

关键帧可用于位置、缩放、旋转和透明度等属性。为同一属性设置不同帧的值，预览会根据插值方式计算中间帧。

第 0 帧：opacity = 0；第 18 帧：opacity = 1；结果：片段在 0 到 18 帧渐显。

4.3 验收顺序

  1. 重新读取项目，确认场景、轨道、片段和关键帧实际写入。
  2. 同步预览，确认画面与时间线一致。
  3. 拖动或播放关键区间，检查入点、出点和插值。
  4. 确认无误后再导出。

5. 预览与导出

5.1 预览渲染模式

模式适用场景
性能默认原生渲染路径，适合日常播放和性能检查。
兼容保留 Web/React 兼容路径，适合 HTML、PPT 和兼容性验证。
实时合成面向 Live / 全窗口播放运行态的组合场景。

5.2 预览链路

“自动”会根据当前场景和能力选择 Web 或 Native surface；“Web”强制使用 Web compatibility surface；“Native”强制使用原生 texture/render surface。遇到兼容性问题时可切换链路进行对照。

5.3 导出

从项目菜单选择导出 MP4、导出 PPTX或导出网页。导出内容应只包含最终画面和交付需要的信息，不应带有编辑器卡片、调试文字或时间线辅助标记。

6. 共享 Agent

右侧 AI 面板连接 VuuMake 共享 Agent。VuuSpot 提供当前项目、选中对象、播放范围和可用 VuuSpot 工具；共享 Agent 负责理解目标并通过宿主能力完成组合操作。

6.1 推荐提问

6.2 宿主软件使用问题

共享提示规则：当用户询问 VuuSpot 的按钮、菜单、设置、项目文件、预览或导出操作时，Agent 应先参考当前 VuuSpot 宿主根目录的 User_Guide.html，再结合实时项目上下文回答或给出操作步骤。根目录指南不可用时，Agent 必须明确说明，并只回答已验证的操作。

Agent Settings 的偏好由共享 Agent 系统管理；VuuSpot 只提供本宿主的项目上下文和工具，不另建一套独立 Agent 运行时。

7. 设置

顶部右侧 Settings 菜单包含两个入口：

8. 常见问题

为什么预览没有反映最新修改？

先保存或确认修改已提交到项目状态，再执行同步预览；不要只刷新 WebView。

为什么导出的文件和编辑器画面不同？

导出以项目的最终合成状态为准，不包含编辑器辅助 UI。请先确认项目内容和播放范围，再检查导出格式。

如何恢复上次项目？

打开项目菜单，在“最近打开的项目”中选择路径；如果文件被移动，请使用“打开项目”重新选择 .vuo 文件。

如何让 Agent 修改项目？

明确目标、画布/时长、场景内容和验收标准。要求 Agent 先读取项目、执行变更、同步预览，再重新读取验收。

Agent 不知道某个按钮怎么办？

让 Agent 参考宿主根目录的 User_Guide.html。如果指南不存在，应先补齐或直接在界面中核对，不要根据猜测操作。