# 阶段 0 技术原型记录

## 记录日期

2026-09-07

## 当前结论

首批工程骨架已经建立并在 macOS Apple Silicon 上通过构建测试。此阶段证明多版本 Runtime 隔离、基础输入识别、本地 Editor 发现和跨平台进程抽象可以按既定架构继续推进；尚未证明完整动画预览或 `.spine` 恢复流程。

## 本机环境

- Apple Clang 17
- CMake 4.4.3（项目最低要求仍为 3.25）
- Ninja 1.13.2
- Qt Base 6.11.2
- Qt Image Formats 6.11.2
- Spine Launcher 4.3.06 Apple Silicon
- Launcher 当前观察到启动 Spine Editor 3.8.99 Professional

只安装 Qt Base 与 Qt Image Formats，没有安装 Qt WebEngine、Location、NetworkAuth 等与产品无关的 Qt 元组件。

## 固定 Runtime 提交

| Runtime | 官方分支 | 提交 |
|---|---|---|
| 3.8 | `3.8` | `8b4844bd4b193ba9e54487ed397a777993cbad56` |
| 4.0 | `4.0` | `425ce416bb218b28caeec47b317aa57cd7140375` |
| 4.1 | `4.1` | `77a5db0ec6d16331f5efbaa7662bba9355bd3424` |
| 4.2 | `4.2` | `e7dc1435fa4a0083ab431f1b28e083c14a1f5c68` |
| 4.3 | `4.3` | `4309c05c287d3f15da778e68f5d2a483fe10a6a3` |

当前只展开各分支的 `spine-cpp` 源码。4.3 官方 Spineboy 资源仅用于开发测试，不进入安装目标和发行包。

## 已实现

- CMake/C++20 工程和 macOS、Windows Preset。
- 标准 C++ 核心库，不依赖 Qt。
- Spine 版本值对象和正式支持范围判断。
- JSON 最小 Spine schema 与版本探测。
- SKEL 二进制头部 hash/version 有界读取。
- Atlas 多页、page、region、PMA、scale、rotate、bounds/legacy 字段基础解析。
- macOS 常见 Spine 路径发现和 `.app` 规范化。
- Windows 常见路径骨架和 `.exe` → `.com` 规范化。
- 不经过 shell 的 POSIX/Windows 子进程执行器。
- 超时后终止本软件启动的整个子进程树。
- Launcher 版本与实际 Editor 版本分离解析。
- 五个 Runtime 独立静态目标和动态 adapter。
- 稳定 C ABI 版本与 metadata 加载验证。
- 极简 Qt 桌面外壳：资源拖放/选择、资源切换、动画切换和一键转换。
- Editor 自动发现；仅在自动发现失败时请求自定义路径。
- 4.3 Runtime 已实际加载官方 JSON、SKEL 和 Atlas，并输出动画/Skin/骨骼元数据。
- 4.3 Runtime 已输出裁剪后的纹理三角形，Qt 画布可循环播放并切换真实动画。
- 4.3 beta 后缀版本和新版 SKEL 文件头识别。
- CLI：Editor 发现、路径探测、数据版本检查。

## 构建与测试结果

- `cmake --preset macos-debug`：通过。
- `cmake --build --preset macos-debug`：通过。
- 五个官方 Runtime：通过 Apple Clang 编译。
- 五个 Runtime adapter：通过动态加载和 ABI/版本检查。
- 核心单元测试：全部通过。
- 官方 Spineboy JSON/SKEL 真实加载测试：通过，识别到 11 个动画。
- Qt 应用 offscreen 启动冒烟测试：通过。

Spine 4.3 上游源码在 Apple Clang 下产生一条未覆盖枚举值的 warning。第三方源码没有被修改，该警告暂不影响构建，后续记录在上游警告基线中。

## 实际 Editor 探测发现

直接执行本机 `Spine --version` 时先报告 Launcher 4.3.06，随后启动 3.8.99 Professional。旧版 launcher 在当前系统产生字体兼容警告，并且探测可能长时间不退出。

因此代码已经采用：

- 分离解析 Launcher 和 Editor 版本。
- 探测超时。
- 进程树终止。
- “已观察到 Spine 但探测超时”独立状态。

仅看到 Launcher 版本不能代表目标 Editor 版本可用。

## 尚未完成的阶段 0 关卡

1. 对 3.8—4.2 执行真实资源预览。
2. 目标 Editor 版本选择与离线缓存能力验证。
3. 官方 Texture Unpacker 调用与结果验证。
4. JSON/SKEL 到 `.spine` 的端到端恢复。
5. SKEL 图片路径双重导入/导出方案验证。
6. Windows MSVC 构建与真实 Editor 测试。

## 下一步

先扩展 Runtime C ABI，以 4.3 adapter 实现真实资源加载、动画/Skin 元数据与 draw list；通过后把版本差异分别适配到 4.2、4.1、4.0 和 3.8。随后接 Qt OpenGL 预览画布，再进入 Editor 导入和官方解包流水线。