TiXL 版本感知启动全解析：Alpha 与稳定版数据隔离、欢迎向导与升级导入机制

TiXL 版本感知启动全解析：Alpha 与稳定版数据隔离、欢迎向导与升级导入机制

【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3

TiXL 采用「main 分支即下一版本 alpha」的发布节奏，本指南基于仓库内 Plan_AlphaSeparation.md 的实现计划，系统讲解 TiXL 如何通过「版本单一事实源 + 版本化用户文件夹 + lastRunVersion 标记 + 欢迎/导入向导」解决 alpha 与稳定版共存时的数据隔离与升级引导问题。读完本文，你将掌握Tixl.props→RuntimeAssemblies→FileLocations的版本数据流、versionMarker.json的启动分类机制、上一版本数据导入的实现细节，以及如何通过TIXL_OVERRIDE_VERSION_ID让同一版本的多个构建并行共存。

一、背景与动机：为什么需要版本感知的启动

TiXL 的发布节奏决定了main分支在每次稳定版分支切出后立即承载下一版本的工作，因此main始终是「下一个版本的 alpha」。在过去几个版本周期中，这一节奏给用户带来了三类问题：

1. 文件夹冲突（Folder collision）：相同major.minor的 alpha 与稳定版写入相同的用户文件夹（%APPDATA%\TiXL4.2\、~\Documents\TiXL4.2\）。若 alpha 引入了设置格式变更、破坏了布局或在保存时重写了项目，就可能损坏对应的稳定版安装，反之亦然。
2. 缺少 alpha 引导（No alpha onboarding）：首次运行 alpha 的用户看不到「这是 alpha、有什么新功能、数据去了哪里、如何从稳定版导入」的指引，只会面对一个没有自己任何项目的空 TiXL。
3. 稳定版缺少版本升级信号（No version-bump signal）：用户从 4.3.0 升到 4.3.1（或从 4.2 升到 4.3）时，编辑器内没有途径了解变化内容，发布说明仅存在于 GitHub 上，极易被忽略。

该计划落地前的状态是「半成品」：文件夹名称已包含版本号（TiXL4.2），但Tixl.props中的-alpha后缀只被接入了 Editor 的InformationalVersion，从未进入文件夹名称或任何运行时 API。没有可读取的IsAlpha属性，也没有记录上次运行的版本。

二、版本单一事实源：Tixl.props→ 构建管道 →RuntimeAssemblies

2.1 源头：Tixl.props

版本的唯一权威来源是仓库根目录的 Tixl.props：

<TixlVersion>4.3.0.0</TixlVersion> <TixlVersionSuffix>alpha</TixlVersionSuffix>

这两项在发布切分支时手工编辑：切出稳定分支时清空后缀，main重新加上alpha。该文件还定义了目标框架（net10.0-windows与net10.0）等共享属性，供各项目csproj通过<Import Project="$(SolutionDir)/Tixl.props" />引入。

2.2 构建管道：将后缀接入 Core

Phase 1 的关键改动是在 Core.csproj 中补齐版本属性（与Editor.csproj中已有的写法保持一致）：

<VersionPrefix>$(TixlVersion)</VersionPrefix> <VersionSuffix>$(TixlVersionSuffix)</VersionSuffix> <InformationalVersion>$(Version)</InformationalVersion>

此前只有 Editor 的InformationalVersion携带后缀，而RuntimeAssemblies（读取 Core 程序集）看不到它。补齐后，Core 程序集的AssemblyInformationalVersionAttribute会形如4.3.0.0-alpha+<sha>，从而让后缀可供整个运行时读取。

2.3 运行时读取：RuntimeAssemblies

Core/Compilation/RuntimeAssemblies.cs 是 Core 中既有的版本单例，从任何位置可达且无依赖环风险（这也是选择它而非 Editor 专属的App/Program的原因——运算符既运行于 Editor 也运行于 Player，Player 的日志路径同样需要知道版本）。Phase 1 之后它暴露如下字段：

字段	类型	含义与示例
Version	Version	4 段数字程序集版本，如4.3.0.0，不含 semver 预发布段（既有字段，语义不变）
VersionSuffix	string	semver 预发布段："alpha"、未来的"beta.2"/"rc.1"，稳定版为空字符串
IsPreview	bool	!string.IsNullOrEmpty(VersionSuffix)——任何预发布段都算「非稳定」，未来beta/rc周期无需改代码即获得同样的隔离
IsAlpha	bool	严格限定后缀等于"alpha"（VersionSuffix == "alpha"）
FormattedVersion	string	无 SHA 的格式串，如"4.3.0.0-alpha"或"4.3.0.0"

VersionSuffix的解析逻辑是ParseVersionSuffix()：读取 Core 的AssemblyInformationalVersionAttribute（形如<numeric>[-<suffix>][+<sha>]），先截掉+之后的 SHA 段，再取第一个-与结尾之间的内容。Program.FormattedEditorVersion（见 Editor/Program.cs）则退化为一个薄封装，在其基础上追加+sha与Debug标记。

需要注意源码中的静态字段按声明顺序初始化（_coreAssembly必须最先声明），这一顺序保证所有依赖它的字段初始化时不会读到null。

三、文件夹隔离：FileLocations与版本化应用文件夹名

3.1VersionedAppFolderName的生成

Core/Settings/FileLocations.cs 不再自行做反射读版本，而是统一读取RuntimeAssemblies。核心常量是VersionedAppFolderName，其解析规则为：

• 设置了VersionIdOverride时：TiXL<major>.<minor>-<override>（如TiXL4.2-skillQuest）；
• 否则若IsPreview为真：TiXL<major>.<minor>-<suffix>（如TiXL4.2-alpha）；
• 否则：TiXL<major>.<minor>（如TiXL4.2）。

该常量同时喂给两个用户目录：

• SettingsDirectory→%APPDATA%\TiXL4.2-alpha\（或稳定版%APPDATA%\TiXL4.2\）
• DefaultProjectFolder→~\Documents\TiXL4.2-alpha\（或~\Documents\TiXL4.2\）

3.2 继承者：所有下游消费者免费获得隔离

文档明确指出：其余所有FileLocations.SettingsDirectory的消费方——主题（Themes）、键位绑定（KeyBindings）、布局（Layouts）、录制、技能进度、测试、渐变、自动备份锁文件——都自动继承新的文件夹名，无需逐个迁移。Player 的唯一接触点是日志路径（Player/Program.cs），它已经经由FileLocations.SettingsDirectory解析，因此 alpha 构建的 Player 会自动把日志写入TiXL4.2-alpha\Player\...，Phase 1 无需改动任何 Player 代码。

3.3 版本字符串的刻意保留

预存在的公共常量TixlVersion（"4.2"形状，major.minor）被刻意保留——它被IoDataSetRecorder用于录制元数据的溯源（provenance）。不带后缀意味着稳定版与 alpha 构建的同 minor 录制文件仍可相互比较；后缀只进入文件夹名称。

3.4 风险与缓解

• 存量 alpha 用户的首次启动：改动落地后首次启动，已有 alpha 用户会得到一个全新的空文件夹，旧数据孤立在TiXL4.2\中且看起来像稳定版安装。缓解方案是在引入该改动的 alpha 的发布说明中提前宣告，并让 Phase 1 与 Phase 2（欢迎界面 + 导入）在同一个发布中一起上线。
• UserSettings中的ProjectDirectories存的是绝对路径：设置导入时需逐项目决策是原样导入（与稳定版共享）还是复制进 alpha 目录树。

四、开发/高级用户逃生舱：覆盖文件夹后缀

FileLocations.cs 在静态初始化期间读取环境变量TIXL_OVERRIDE_VERSION_ID（常量VersionIdOverrideEnvVar）。设置后它替换VersionedAppFolderName中的预发布后缀：TiXL4.2-skillQuest而非TiXL4.2-alpha。这样同一版本的多个构建（例如两个并行的开发 checkout）可以保持各自独立的设置与项目。

安全上，值会经过Path.GetInvalidFileNameChars()消毒，无法把设置树重定向到 AppData 之外。Editor 还接受命令行参数--override-version-id=<id>（Editor/Program.cs 的ApplyVersionIdOverrideArg），它只是在任何FileLocations访问前设置同一个环境变量，并记录解析出的文件夹；参数支持--flag=value与--flag value两种写法。Player 则免费继承环境变量路径（无 CLI 参数）。实测手动测试集见 .tests-manual/alpha-folder-separation.md 的「Override the folder suffix」与「Override via the command-line argument」两节。

五、VersionMarker：记录上次运行的版本

5.1 存储与分类

Editor/Gui/Dialog/VersionMarker.cs（注意：版本标记位于Editor/而非Core/，因为这是编辑器行为）在SettingsDirectory/versionMarker.json中持久化单个字段lastRunVersion（字符串，semver）。LoadOrDefault()在文件缺失或损坏时返回null。

每次启动的Classify()依据RuntimeAssemblies.Version.CompareTo(previous)产生三种结果：

LaunchKind	触发条件	行为
Silent	lastRunVersion == current（稳态）	大多数启动，不弹窗
NewToUser	标记缺失或低于当前版本	触发欢迎弹窗，alpha/稳定版均触发；弹窗自行判断当前文件夹是否已有数据以决定是否显示导入区
Downgrade	标记高于当前版本	记录警告，按Silent处理，不覆盖标记（用户可能还会升回去）

MarkCurrentVersionSeen()在弹窗关闭后（或未弹窗时立即）调用，且拒绝把记录的版本写低——保证降级运行不会抑制用户原本来自的较新构建的欢迎弹窗。写盘通过JsonUtils.TrySaveJson完成。

5.2 关键设计决策（已决议）

• 触发器模型：每种构建类型一个弹窗，都由同一条件触发——lastRunVersion != current（缺失或更低）。IsAlpha只切换内容变体。冷启动 vs 版本升级的区分在弹窗内部处理：导入区仅在当前文件夹为空（无先验数据）时显示，而非依据独立阶段。
• "文件夹已被使用"的判定：依据版本标记 +userSettings.json（两者都只在真实会话后写入），而不是主题/布局文件——因为主题/布局默认值在启动期间就可能被写入，不能作为「文件夹曾被使用」的可靠信号（见PreviousVersionImport.CurrentFolderHasPriorData()）。

六、版本感知欢迎窗口：Welcome 系列

6.1 演进过程

计划最初设想为WelcomeDialog（模态弹窗，仿Help → About TiXL），随后经历了两次落地调整：

• 窗口集成：WelcomeAlphaWindow改为继承编辑器的Window基类并注册进WindowManager（跳过 Windows 菜单，由版本欢迎触发器与Help → Welcome经Open()打开），免费获得与 Settings 窗口相同的窗口 chrome/背景，去掉了自制的ImGui.Begin/可见性/标记处理（现在由Config.Visible与基类的Close()覆写负责盖章）。WindowPaddingOverride = Vector2.Zero让侧边栏与窗口齐平。
• 重设计：根据设计反馈，单列模态改为非模态、Settings 风格的分页窗口，复用SettingsWindow的子布局模式。

6.2 共享外壳：WelcomeWindowBase

Editor/Gui/Dialog/WelcomeWindowBase.cs 为稳定版WelcomeWindow与 alpha 版WelcomeAlphaWindow提供共享外观：浮动 Settings 风格窗口、带版本标题与「Show on startup」开关的头部横带、发布说明渲染，以及关闭时盖章版本标记（Close()覆写调用VersionMarker.MarkCurrentVersionSeen()）。窗口尺寸为 680×480，CenterOnAppearing = true。「Show on startup」开关写入UserSettings.Config.ShowWelcomeOnStartup。

发布说明通过ReleaseNotesLoader.TryLoadForCurrentVersion()加载，并以 Markdown 渲染（支持text链接与[OperatorName]操作符引用），文件缺失时显示「No release notes for this version yet.」。

6.3 Alpha 变体：WelcomeAlphaWindow

Editor/Gui/Dialog/WelcomeAlphaWindow.cs 标题为「Welcome to the TiXL Alpha」，侧边栏四个页签，完成导入后对应条目显示对勾：

• Welcome：以 Markdown 渲染 Alpha 欢迎文案（提示 alpha 版会创建自己的 Settings/Projects 文件夹以免影响已装版本、当前处于活跃开发中请勿用于生产、并引导用户报告问题与浏览规划看板），下方渲染滚动式 alpha 发布说明。
• Import Settings：细粒度分类清单——Editor Settings / Themes / Keyboard Maps / Layouts，每项对应一个PreviousVersionImport操作；源缺失时复选框禁用并显示 tooltip；导入完成后提示「Restart TiXL to apply the imported settings, themes, keymaps and layouts.」（注意：与计划早期「两个按钮」的草图不同，此处恢复了分类粒度）。
• Import Projects：逐项目清单（PreviousVersionImport.EnumerateProjects），已导入行禁用并标注「(already imported)」，每行有打开源文件夹的图标按钮，复制在后台任务执行，完成状态在 UI 线程处理。
• Test new Features：通过TestSetParser.LoadAll列出.tests-manual测试集，单选行（标签胶囊 + 步骤数），「Start Test」调用ManualTestRunnerWindow.StartSet(id)（新入口点）并关闭欢迎窗口（关闭即盖章）。

alpha 欢迎文案的要点（源码内联常量AlphaWelcomeMarkdown）：alpha 版总是为 Settings 和 Projects 创建自己的文件夹以避免影响已安装版本；本版本处于活跃开发中，请勿用于生产工作；请在 Discord 或项目规划看板报告问题。

6.4 稳定版变体：WelcomeWindow

Editor/Gui/Dialog/WelcomeWindow.cs 标题为「Welcome to TiXL」，侧边栏为 Welcome / Getting Started / Release Notes 三个页签，无导入或功能测试页、无 alpha 警告。Welcome 页还包含升级前备份提示（DrawPreUpgradeBackupNotice）：当一次启动检测到新版本且格式可能变更时，PreUpgradeSnapshot会在任何保存可能升级项目格式前为现有项目创建备份，弹窗列出每个备份的绝对路径与「Reveal」按钮，让用户可以安全降级回旧版本。

6.5 触发时序：CheckForVersionWelcome

Editor/Gui/T3Ui.Update.cs 中的一次性检查在布局就绪且任何启动弹窗（如用户名弹窗）关闭后触发：先分类启动类型（VersionMarker.Classify()）；若是新版本，先为现有项目创建升级前快照（AutoBackup.PreUpgradeSnapshot.CreateForExistingProjects()，在标记写入之前执行，崩溃后可重试）；随后按「用户设置保留欢迎启动开关或新版本」打开欢迎窗口，否则直接MarkCurrentVersionSeen()。

关键的用户名弹窗延迟逻辑：CheckForVersionWelcome()在用户名提示之前运行，用户名提示受_versionWelcomeChecked && !WelcomeWindow.IsVisible门控，因此全新安装时欢迎窗口先出现，关闭后用户名提示才跟随——两者绝不重叠。Help → Welcome菜单项可随时重新打开同一内容变体的欢迎窗口。

七、上一版本发现与数据导入：PreviousVersionImport

7.1 上一版本发现

Editor/Gui/Dialog/PreviousVersionImport.cs 的TryFindBest()扫描ApplicationData与MyDocuments中当前文件夹名的同级目录，用正则^TiXL(\d+)\.(\d+)(?:-(.+))?$匹配TiXL<major>.<minor>[-suffix]模式。选取规则：最高major.minor且非当前版本，同版本时稳定版优先于 alpha（例如运行4.3.0-alpha时优先选TiXL4.2而非TiXL4.2-alpha）。选中的源文件夹会显示在弹窗中，让用户明确知道将要复制的内容。

7.2 导入类别与白名单

所有导入操作均为复制，源永不修改。五个类别如下：

• Projects：递归复制上一版本的DefaultProjectFolder到当前目录，跳过bin/、obj/、.temp/（排除集取自Migrations.ProjectFormats.V1.Layout.GeneratedStateDirectories），后台任务执行并在弹窗页脚显示进度。EnumerateProjects将每个直接子目录视为一个项目，「已导入」判定为当前默认项目文件夹中是否已存在同名目录；TryGetProjectsSizeBytes在勾选前估算源文件夹大小供用户参考。
• Settings：读取上一版本userSettings.json，反序列化后仅把白名单键复制进当前设置并保存。源码中的白名单当前为：UserName、UiScaleFactor、KeyBindingName、ColorThemeName（计划文档初稿为KeyBindingName、UiScaleFactor、最近文件列表；实现以当前源码为准）。白名单刻意保持狭窄——只复制不随版本漂移的值；Themes/Layouts/Keymaps 是独立类别，不在此白名单内。
• Layouts：复制<previous>/Layouts/内容到<current>/Layouts/，覆盖单个文件，绝不删除当前文件夹中源里没有的用户文件。
• Themes：复制<previous>/Themes/内容。
• Keymaps：复制<previous>/KeyBindings/内容。

CopyDirectory实现为递归复制，可传被排除目录名集合。所有「源缺失」情况都有探测函数（HasSettingsFile、HasSubfolder等）驱动 UI 层的禁用与 tooltip。

7.3 决策记录：为何只复制不链接

已决议：项目导入只复制，不提供链接选项。复制让源项目保持不动，并规避「新版写入旧版读不了的格式」的隐患；早期草案中的链接模式 UI、banner 与ProjectDirectories管道被放弃。设置导入提供分类清单、每项独立开关、默认全部关闭、用户显式勾选；弹窗展示源文件夹让用户看清每类数据来自哪里。

八、发布说明内容管线（Phase 3）

8.1 文件格式

发布说明按版本落在.help/release-notes/目录（经ShippedContent解析，打包构建中该目录随二进制一同复制）。每个 stable minor 一个文件v<major>.<minor>.md，alpha 与 stable 共享（ReleaseNotesLoader不再按IsAlpha分支）；alpha 另有滚动式alpha.md。格式含 frontmatter：

--- version: 4.3.1 date: 2026-06-14 highlights: - "Faster shader compilation on cold start" - "Timeline now supports per-clip waveforms" - "Fixed crash on closing the parameter window with an active drag" --- ## What's new in 4.3.1 <full markdown body>

highlights在弹窗内联渲染，正文由「See full notes」打开。缺失文件时的回退文案为「TiXL was updated to<version>— see release notes on GitHub」，不让升级体验阻塞在发布说明作者是否写了笔记上。

8.2 加载器与打包

Editor/Gui/Help/ReleaseNotesLoader.cs 按运行构建的major.minor拼出v<major>.<minor>.md文件名并从.help/release-notes读取。打包间隙已在实现中解决：新增的 ShippedContent 统一解析随附的 markdown 文件夹——开发 checkout 中解析仓库源文件（供测试运行器热重载），打包发布中解析二进制旁的副本；ReleaseNotesLoader、TestSetParser、EmbeddedHelpLoader都经由它，且Editor.csproj会把.help/release-notes、.tests-manual、.help/embedded复制进输出目录。

8.3[OpName]操作符引用链接

发布说明正文中的[OpName]（无(url)后缀的裸片段）由 MarkdownOperatorLinks 解析：经缓存的名称查找（EditorSymbolPackage.AllSymbols）把OpName解析为 symbol；悬停显示命名空间 + 描述 tooltip（描述本身也经 markdown 渲染，代码跨度、列表、嵌套[OpName]引用均正确，嵌套引用传suppressTooltip避免 tooltip 堆叠）；点击调用SymbolLibrary.Reveal(symbolId)——复用库的既有树展开机制_expandToSymbolTargetId与新增的_scrollToSymbolId把操作符滚动进视野，且不触碰搜索过滤条件。操作符引用片段按其输出类型颜色着色（未知名称回退为正文色，看起来不像可点击链接）。无法解析的名称（重命名/移除的操作符）渲染为纯文本，而非死链。

九、手动功能测试的排序与运行历史（Phase 4）

该阶段让测试者打开 Feature Tests 时最新测试排在最前、已完成测试集被标记完成。关键落地（2026-05-31）：

• TestSet新增Added（日期）与AddedInVersion，从.tests-manualfrontmatter 的added:/added-in-version:解析（TestSetParser）；既有的 11 个测试集已用 git 首次提交日期回填（均为4.2）。
• 运行器新增「Recently added / Alphabetical / By scope」排序下拉，LoadAll默认按新旧排序，因此欢迎页列表自动继承。
• 完成状态持久化到testRunHistory.json（TestRunHistoryStore）：一个测试集的所有步骤都获得结果后写入；已完成集在运行器列表与欢迎页列表的左槽显示对勾（蓝=通过，强调色=有问题）。
• 完整结果由 TestRunExport 序列化：每次完成的运行自动保存到TestRuns/<timestamp>.json（每步结果+评论+时间戳，外加每集的 pass/fail/other/skipped/pending 计数），Summary 界面的「Copy JSON」/「Open Saved Runs」按钮已接好。

testRunHistory.json刻意保持最小化（set id →{lastRunUtc, status}）以抵御测试集编辑带来的 schema 漂移，并忽略未知/已移除的 id。

十、后续阶段展望（Phase 5–7）

• Phase 5：AddedInVersion元数据与新操作符高亮——在SymbolUi上增加major.minor字符串（或空），在 Symbol Library 中为当前版本（或 N 个版本内）新增的操作符绘制强调色圆点，低缩放阈值下与其它库细节一样剔除；新增 Symbol Library 设置弹窗（对齐 Asset Library 的设置图标+弹窗模式），首选项为「Highlight new operators」。
• Phase 6：功能交叉引用注册表（先设计后编码）——用单一「功能」注册表把发布说明 ↔ 功能条目（added in version）↔ 实际 UI 组件串起来，让用户直接在界面发现新功能、发布说明可深链到具体菜单路径；FeatureMenuItem作为普通MenuItem的即插即用替代品携带功能引用；「Highlight new features」开关高亮匹配当前版本的功能条目。开放设计问题包括注册表存放位置（静态表 vs 特性 vs 数据文件）、FeatureMenuItem如何避免菜单栏的逐帧分配、功能 id 手工编写还是生成。该阶段的已落地构件包括 EmbeddedHelpLoader（读取.help/embedded/<id>.md）与 DocumentationButton（HelpOutline图标，悬停渲染内嵌 markdown tooltip、点击打开 wiki 页），首个实例位于 Guided Feature Tests 头部，种子文档为 .help/embedded/GuidedFeatureTests.md。
• Phase 7（推迟）：智能发布说明生成——release-notes/<version>.md作为数据契约；技能或 CI 任务遍历自上一版本标签以来的提交信息、按领域（操作符/UI/音频…）分组，产出highlights草稿与正文，合并前由作者编辑；「新发布说明落地时重新打开欢迎」仅在用户显式选择时才做。该阶段不改变运行时所见内容，纯属编写工具。

十一、非目标与边界

计划明确列出了不在范围内的内容，理解这些边界有助于判断该机制的适用面：

• 不自动从提交生成发布说明（v1 发布说明由发布作者手写进按版本命名的 markdown 文件）。
• 不迁移 Tooll3（v3.x）数据。
• 不改变 Player 解析自身内容文件夹的方式（导出的游戏保持自包含，位于 exe 旁）。
• 不做跨版本项目格式兼容（计划假定既有向后兼容读取器继续处理旧数据）。
• 不做自动更新机制——弹窗只是在用户升级后告知变化，不下载、不安装任何东西。

十二、风险与缓解策略汇总

风险	缓解
存量 alpha 用户首次启动得到空文件夹	在同版本 alpha 发布说明中宣告；Phase 1+2 同版上线；Phase 2 的欢迎+导入兜底
ProjectDirectories存绝对路径	设置导入时逐项目决策（原样导入 vs 复制进当前树）
userSettings.jsonschema 漂移	精选白名单限定爆炸半径，漂移只影响白名单内的键
项目磁盘占用	勾选前在弹窗中显示源文件夹大小
旧版 Layouts/Themes/Keymaps 引用已不存在的资源	编辑器既有的缺失资源回退机制优雅降级；需要手动测试 4.2 布局不会搞崩 4.3
上一版本发现选错文件夹	选取规则「最新非当前 + 稳定优先」基本安全；「Choose other folder…」逃生舱覆盖罕见歧义
发布说明缺失	回退到 GitHub 链接，不阻塞升级体验；可在Tixl.props版本上增加 CI 存在性检查
回填准确性	种子日期只需让真正新增的测试集排在旧集之上，不必过度投入

十三、手动验证清单

仓库提供了两份官方手动测试集，分别验证两条主链路：

.tests-manual/alpha-folder-separation.md（Phase 1 文件夹分离）：

• 启动构建并核对版本串（v4.2.0.2-alpha为 alpha，无后缀为稳定版）；
• 检查%APPDATA%下出现TiXL<major>.<minor>-alpha或TiXL<major>.<minor>，且另一构建类型未因本次运行创建目录；
• 检查 Documents 下同名文件夹，另一方不受影响；
• 检查日志落在匹配的<folder>\Log\下，另一文件夹本次会话无新日志；
• 若两种构建都有，交替运行验证互不干扰；
• 设置TIXL_OVERRIDE_VERSION_ID=skillQuest后启动，日志应出现Settings folder overridden via 'TIXL_OVERRIDE_VERSION_ID': ...TiXL<version>-skillQuest，且后缀是替换而非追加（不产生-alpha-skillQuest）；
• 清空环境变量后用--override-version-id=parallelB启动（如Tooll3.exe --override-version-id=parallelB），验证两个会话的设置/布局/项目完全分离。

.tests-manual/version-welcome-and-import.md（Phase 2 欢迎与导入）：

• 全新设置文件夹首启 → alpha 弹窗显示四个页签并带开发版警告；稳定版弹窗显示三个页签、无警告；
• 全新文件夹且有上一版本 → 显示导入区（Projects/Settings/Layouts/Themes/Keymaps），无源数据的类别禁用并带 tooltip，Projects 行显示大小估算；文件夹已有数据则无导入区；
• 只勾 Settings → 用户名/UI 缩放/主题/键位生效，布局与已存主题不迁移，源版本原封不动；
• 只勾 Projects → 复制期间显示「Importing…」，完成提示，项目出现在新版本，源版本项目仍在；
• 发布说明渲染：悬停[SwiftCamDevice]显示描述 tooltip，点击打开 Symbol Library 定位到该操作符，未知名称渲染为纯文本，无文件时显示「No release notes for this version yet.」；
• 从 Test new Features 页签选择测试集并「Start Test」→ 功能测试窗口可见并启动该测试集，欢迎窗口关闭。

十四、关键文件速查

• 版本源头：Tixl.props（TixlVersion/TixlVersionSuffix，发布切分支时手工编辑）
• 构建管道：Core/Core.csproj（VersionSuffix+InformationalVersion接入 Core）、Editor/Editor.csproj
• 运行时版本 API：Core/Compilation/RuntimeAssemblies.cs（Version/VersionSuffix/IsPreview/IsAlpha/FormattedVersion）
• 文件夹解析：Core/Settings/FileLocations.cs（VersionedAppFolderName/SettingsDirectory/DefaultProjectFolder/TIXL_OVERRIDE_VERSION_ID）
• 版本标记：Editor/Gui/Dialog/VersionMarker.cs（versionMarker.json、Classify()、MarkCurrentVersionSeen()）
• 上一版本导入：Editor/Gui/Dialog/PreviousVersionImport.cs
• 欢迎窗口：Editor/Gui/Dialog/WelcomeWindowBase.cs、Editor/Gui/Dialog/WelcomeAlphaWindow.cs、Editor/Gui/Dialog/WelcomeWindow.cs
• 触发时序：Editor/Gui/T3Ui.Update.cs（CheckForVersionWelcome()）、Editor/Program.cs（ApplyVersionIdOverrideArg/FormattedEditorVersion）
• 发布说明：Editor/Gui/Help/ReleaseNotesLoader.cs、Editor/Gui/Help/ShippedContent.cs、Editor/Gui/Styling/Markdown/MarkdownOperatorLinks.cs
• 手动测试集：.tests-manual/alpha-folder-separation.md、.tests-manual/version-welcome-and-import.md

从源码结构看，该机制的设计意图清晰：Tixl.props是唯一版本事实源，RuntimeAssemblies将预发布段暴露给整个运行时（含 Player），FileLocations将后缀折叠进用户文件夹名，VersionMarker提供启动分类，PreviousVersionImport提供纯复制的安全迁移，欢迎窗口把「这是什么版本、有什么新功能、数据在哪、如何导入」一次性呈现给用户——最终让 alpha 与稳定版可以在同一台机器上长期共存而不互相伤害。

【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3