Persona

在图层列表中选中自有模型后，可以在模型设置的版本区块中为模型文件保存版本，随时对比任意两个版本、单独还原个别文件、整体切换回旧版本，或将某个版本导出为 ZIP。在用 Cubism Editor 重新导出、调整物理或修改参数绑定前先存一个版本，改坏了也能随时退回。

版本历史按模型单独开启，默认关闭。内置模型 与从素材库下载的目录模型由官方分发管理，因此没有版本区块。

保留版本复制锚点链接

打开版本区块中的保留版本开关后，Persona 会立即保存第一个版本（列表中显示为「开始记录历史」）。若模型文件不在本地磁盘上则无法开启；对于 Persona 无法正常读取的文件夹（例如 Windows 的 \\server\share UNC 网络共享路径，或 macOS / Linux 上名称包含反斜杠的文件夹），也会拒绝开启，避免生成空版本。

关闭开关只会暂停记录，已保存的版本仍会保留（区块中显示为已保留的历史记录）；重新开启后，期间的改动会显示为 未保存的更改。

历史记录一行会显示已占用的磁盘空间，菜单中提供显示历史记录文件夹与删除历史记录…。选择后者会将该模型的全部历史版本移至废纸篓（Windows 为回收站）并关闭版本历史，模型本身的文件不受影响。

版本包含哪些文件复制锚点链接

版本只收录模型文件夹内的常规模型文件。放在导出文件旁的 PSD、.cmo3 等工程源文件不属于模型，指向文件夹外部的路径引用与符号链接也不会纳入。每个版本都会保存完整文件（包括 moc3 与贴图），即使重新导出出错也能完整回退；未改动的文件会在版本间共享存储，不会重复占用空间。

保存版本复制锚点链接

版本仅在手动操作时保存，不会定时或自动触发。当磁盘上的文件与当前版本不一致时，区块中会出现未保存的更改一行，点击保存版本…即可保存。对话框会自动预填名称（如「版本 3」），备注为选填；同一模型下的版本名称不能重复（不区分大小写）。

未保存的更改复制锚点链接

未保存的更改会显示当前有多少个文件与已保存版本不同。点击标题或在菜单中选择显示更改…可查看具体差异；选择丢弃更改…会将文件恢复为当前版本并重新加载模型，该操作无法撤销。

• 在 Persona 内所做的修改（如 参数绑定、快捷键、模型整体移动、表情编辑器、录制或编辑的动作 等）会立即计入未保存更改。
• 在 VTube Studio、文本编辑器或 Cubism Editor 等外部工具中修改文件后，切回 Persona 的任意窗口时即会刷新检测。
• 开关表情不会计为文件改动。触发表情快捷键虽然会更新 .vtube.json 或 .persona.json 中记录当前激活表情的字段，但版本历史会自动忽略这部分变化；切换版本或还原文件时，当前开启的表情状态也会保持不变。

版本列表复制锚点链接

版本按日期分组（「今天」「昨天」或具体日期），从新到旧排列，每次加载 50 个，点击显示更早的版本可继续查看。

• 未命名的版本会根据保存方式显示为「开始记录历史」「已保存的版本」或「未保存更改的备份」；由其他 Git 工具创建的提交则直接显示提交说明。
• 已命名的版本会加粗显示并附带书签图标，备注显示在标题下方。
• 当前徽标表示当前磁盘文件所基于的版本，即使文件之后做过修改，该标记也不会改变。

每个版本的菜单提供显示更改…、与磁盘上的文件比较…、切换到此版本…、为此版本命名…（已命名时为重命名…与移除名称）以及导出为 ZIP…。

Persona 不会覆盖、压缩或单独删除某个历史版本，也不会改写提交历史；如需清理空间，可通过删除历史记录…将整份历史记录一并移除。

比较版本复制锚点链接

点击列表中的版本（或选择显示更改…）会打开比较版本对话框，展示该版本相对于上一版本的改动。通过从与到下拉框可以任选两个版本，或选择磁盘上的文件进行对比。

• 左侧文件树会列出有差异的文件，并标注新增、更改或删除；打开显示未更改的文件可一并显示其余文件。拖拽文件树右侧边缘可调整栏宽。
• 文本文件支持以合并或分栏视图展示逐词差异（最大 4 MiB）；图片支持并排或滑动对比（最大 32 MiB）；其他格式及超出大小上限的文件仅对比文件体积。
• 若配置文件仅在当前开启的表情状态上有差异，会视为未更改。

还原文件复制锚点链接

当对比的其中一侧为磁盘上的文件时，勾选文件并点击还原所选文件…，即可将这些文件恢复为另一侧版本的内容，并立即重新加载模型。还原后的文件在正式保存前仍属于未保存更改，因此临时换回旧版物理文件测试效果时，不会额外产生新版本。若所选文件本身包含未保存的更改，Persona 会先询问要保存还是不保存。

切换版本复制锚点链接

切换到此版本…会将模型的全部文件替换为该版本的内容并重新加载模型。若当前存在未保存的更改，Persona 会先提示确认：

切换版本不会产生新的历史条目，目标版本会直接变为当前版本，因此来回切换对比不会让版本列表变长。

• 目标版本中不存在的多余文件会移至废纸篓，不会直接永久删除；若无法移至废纸篓，切换会直接中止，不会改动任何文件。
• 只要有任一文件无法写入（例如被设为只读），整个切换操作都会取消，所有文件保持原样。
• 同一文件夹下由其他已添加模型加载的文件不会被移除。

导出为 ZIP复制锚点链接

导出为 ZIP…会将指定版本的文件打包到以模型命名的文件夹中，文件修改时间设为该版本的保存时间。导出的压缩包仅包含模型文件，不包含历史记录。模型文件夹内的目录链接不会保留；如果模型通过目录链接加载贴图，解压后需要重新创建链接。

历史记录存放位置复制锚点链接

每个模型的历史记录都存放在 配置文件夹 下的 history/<模型 ID>/ 中，不会在模型目录里创建 .git 文件夹。无论你是将模型打包发给客户、放在云盘同步目录中，还是模型目录本身就在你自己的 Git 仓库里，都不会受到干扰。

历史记录采用标准 Git 仓库格式，由 Persona 内置的 Git 实现直接读写，无需安装 Git，也可以随时用任意 Git 工具查看：

git --git-dir ~/.laplace/persona/history/<模型 ID> log

• Persona 不会执行推送、拉取或克隆，也不会发起任何网络请求。你可以自行使用 Git 将仓库推送到远程；由于历史记录从不改写，推送出去的提交始终可以安全保留。
• 提交作者固定为 LAPLACE Persona（邮箱为空），不会读取系统账户名，避免在提交记录中暴露真实姓名。如需修改，可在该仓库的 Git 配置中单独设置 user.name。
• 已命名的版本以附注标签（annotated tag）形式保存，可在各类 Git 工具中直接作为标签查看。
• 如果其他 Git 工具让仓库停留在未完成的操作状态（例如存在已暂存文件、合并或变基尚未结束、处于未检出分支状态），Persona 会给出警告，并暂停保存与切换操作，直到你在外部 Git 工具中完成或撤销该操作。

移动或重新添加模型复制锚点链接

• 模型文件夹移动位置后，点击重新定位…重新指定路径，原有的版本历史会自动保留。
• 通过从素材库中移除将模型移出 素材库 后，如果再次导入同一文件夹下的同一个模型，虽然会分配新的模型 ID，但在开启保留版本时，Persona 会自动找回并接管此前的历史记录，不会从头建库。

插件 API 与 MCP复制锚点链接

通过 插件 API 可以开启或关闭版本历史，执行版本列表查询、保存、命名、对比、切换及单文件还原，并可在历史记录变更时接收事件通知。与界面操作一致，当切换版本或还原文件会覆盖未保存更改时，调用方必须明确指定是先保存还是直接丢弃。MCP 服务器 提供了 list_versions、save_version 与 switch_version 工具：AI 助手在修改模型前可以先保存一个版本，切换版本前若遇到未保存的更改会先向你确认处理方式；但版本历史只能由你在界面中手动开启，AI 助手无法代为开启。