OpenScreen 数据模型深度剖析AxcutDocument 单一数据源与版本迁移机制全解【免费下载链接】openscreenRecord your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.项目地址: https://gitcode.com/gh_mirrors/opens/openscreenOpenScreen 是一款免费开源、GPU 加速、无水印的屏幕录制与视频演示工具Windows / macOS / Linux。它的编辑能力建立在一个核心设计之上AxcutDocument单一数据源。本文用通俗语言拆解这套数据模型的字段构成、只进不退的版本迁移机制和双层持久化架构帮你在不读大量源码的情况下理解 OpenScreen 如何保证每一个项目文件都完整、可升级、可撤销。什么是 AxcutDocument项目的唯一真相在 OpenScreen 里一个项目 一个文档对象 磁盘上的一个 JSON 文件。这个文档类型就是AxcutDocument它用 Zod 类型校验定义是整个编辑器所有界面时间轴、预览、字幕、AI 智能体共同读写的单一数据源Single Source of Truth。它的当前版本号schemaVersion是8定义在 src/lib/ai-edition/schema/index.ts 顶部export const axcutSchemaVersion 8;顶层字段一览文档的完整结构声明在 schema/index.ts 的documentSchemaShape中核心字段如下字段承载内容小白解读schemaVersion固定为8版本身份证迁移的起点projectid、标题、创建/更新时间一个文件对应一个项目assets[]每条录制/导入的媒体素材含原始路径、摄像头轨道、时长timeline剪辑 clips、空隙、剪切、静音、变速、字幕区间时间轴的骨架annotations[]文本、模糊等标注覆盖层锚定在某个 clip 上zoomRanges[]放大特效深度 1–6同样锚定 clipaudioTracks[]导入的旁白/背景音乐/音效按时间轴秒数定位transcripts[]每条素材的语音转写文本字幕层真正读取的数据legacyEditor旧版编辑器的外观/光标设置无损兼容老项目一句话你在界面上的每一次操作最终都只是对这个 JSON 的一次修改。版本迁移机制为什么老项目永远不会打不开这是 OpenScreen 数据模型最精彩的部分。官方文档在 technical-documentation/architecture/document-model.md 中明确了两条铁律单向、只前进迁移只有升版路径没有降级。新版文档落到旧版程序上会被直接拒绝而不是被悄悄截断——宁可报错不丢数据。加载时执行所有升级链在读取文件时一次性跑完migrateRawDocumentToCurrent之后的内存解析只是一次轻量的字面量校验避免每次保存都重复跑整条迁移链的开销。v3 → v8 的演进故事每一次版本号提升背后都解决一个真实问题版本升级做了什么为什么v3 → v4摄像头轨道cameraTrack从文档根移到所属素材上多剪辑项目里每条素材可以有自己的摄像头v4 → v5放大/标注/变速等区域变成剪辑锚定片段同一素材出现两次时特效不再张冠李戴v5 → v6废弃native宽高比烘焙成具体W:H让解析结果永久确定尺寸未知时留待下次加载再转绝不乱猜v6 → v7剪切trim也加入clipId锚定复制的 clip 上的剪切互不串扰v7 → v8Auto成为默认宽高比旧文档写入16:9保证老项目画面在升级后一帧都不变这些升级器以函数嵌套的方式串成一条链集中在 schema/index.ts 的migrateRawDocumentToCurrentexport function migrateRawDocumentToCurrent(raw: unknown): unknown { return readFollowCursorAsAutoOrbit( raiseInvertedTranscriptEnds( dropAudioAnchoredTrims( liftZoomClickImpact( upgradeV7DocumentToV8( upgradeV6DocumentToV7( upgradeV5DocumentToV6(upgradeV4DocumentToV5(upgradeV3DocumentToV4(raw))) ) ), ), ), ), ); }链外还有一道兜底闸门documentSchema中的z.literal(axcutSchemaVersion)检查会拒绝任何未知版本——不认识的文件不会被半吊子地读进来。更老的 v2 项目怎么办OpenScreen 合并前的旧编辑器保存的是另一种格式EditorProjectData。首次在新编辑器中打开时纯函数migrateProjectDataToAxcutDocumentsrc/lib/ai-edition/document/migrate.ts会把它翻译成当前结构单条录屏变成一条素材 一个剪辑旧剪切区间按原语义平移未纳入新模型的约 20 个外观设置原样塞进legacyEditor包裹层——关闭再打开 AI 编辑模式也不会丢任何设置。这个小技巧很妙函数故意输出一篇v4 草稿再走完整升级链确保 v4→v5 的锚定逻辑一定被执行到。双层持久化谁来读、谁来写OpenScreen 的文档字节恰好只有两个主人职责严格分离渲染进程界面层主进程落盘层代码src/lib/ai-edition/store/projectStore.tselectron/ai-edition/document-service.ts职责持有活动文档、播放状态、dirty脏标记读、写、列出、增删素材磁盘位置—userData/projects/id.openscreen一个项目一个 JSON两个工程细节值得称道原子写入每次保存走临时文件 重命名并为每个项目维护写入队列串行化程序崩溃也绝不会出现写了一半的文件document-service.ts 的saveProject。扩展名自动迁移更早的版本把这些文档存成.axcut现在的服务在首次访问时会静默改名为.openscreen——依据的是 JSON 里的版本号而非文件名文件内容一个字节都不动。两层读取路径都必须先过migrateRawDocumentToCurrent再documentSchema.parse所以无论磁盘上是 v3 还是 v8 的老文档进入内存时都已经是最新的AxcutDocument形态。撤销/重做50 步快照栈你可能会问那撤销是怎么和这份单一数据源配合的OpenScreen 没有把撤销历史写进文件而是在渲染进程维护了一个有界快照栈src/lib/ai-edition/store/undo.tspast[]/future[]最多各保留50份文档快照MAX_HISTORY 50每次setDocument把即将被替换的文档压入pastCtrlZ / CmdShiftZ / CtrlY 沿栈游走因为 AI 智能体的每次工具调用也走setDocument所以撤销一整轮 AI 修改天然按调用顺序逐一回退。好处很直接撤销历史不会让项目文件无限膨胀文件里只保留当前文档本身。小结这套设计给你带来了什么放心升级版本迁移单向链 未知版本拒绝老项目打开即自动升版画面一帧不变不怕损坏原子写入 写队列中途断电也不留半截文件操作可逆50 步内存快照栈人肉修改和 AI 修改都能撤销单一数据源界面、预览、字幕、AI 智能体共享同一份文档不会出现时间轴和预览打架。想继续深挖推荐阅读官方架构文档 technical-documentation/architecture/document-model.md 与 technical-documentation/architecture/timeline-model.md以及迁移逻辑的单元测试 src/lib/ai-edition/document/migrate.test.ts——那里面有每个版本迁移的边界用例。【免费下载链接】openscreenRecord your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.项目地址: https://gitcode.com/gh_mirrors/opens/openscreen创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考