194 lines
5.3 KiB
Markdown
194 lines
5.3 KiB
Markdown
# 版本识别与 Spine Editor 检测
|
||
|
||
## 1. 目标
|
||
|
||
在用户确认转换前，软件必须回答：
|
||
|
||
1. 资源由哪个 Spine 主/次版本导出？
|
||
2. 本机是否有可以处理该版本的 Spine Editor？
|
||
3. 配置路径是否指向可用的 Spine CLI？
|
||
4. 在断网状态下，该版本是否能实际启动和导入？
|
||
|
||
路径存在不等于 Editor 可用。当前实现先读取本机 Spine 更新缓存，只把已经存在的精确版本视为可转换；转换时再次执行同一门禁。
|
||
|
||
## 2. 资源版本识别
|
||
|
||
### 2.1 JSON
|
||
|
||
读取 `skeleton.spine` 字段，并同时验证最小 Spine schema：
|
||
|
||
- 根对象
|
||
- `bones` 数组
|
||
- 可选 `slots`、`skins`、`animations`
|
||
- 版本字段格式
|
||
|
||
只解析识别所需的小范围数据。无 Spine schema 的业务 JSON 必须忽略。
|
||
|
||
### 2.2 SKEL
|
||
|
||
识别顺序：
|
||
|
||
1. 对二进制头执行有界读取，尝试提取 hash 和版本字符串。
|
||
2. 用候选版本 Runtime 插件执行只读探测。
|
||
3. 必要时用已配置 Editor 的 info 命令验证。
|
||
4. 多个版本都失败则要求用户选择版本，并标记为未确认。
|
||
|
||
解析必须限制字符串长度、数组大小和文件大小，损坏文件不能导致无限分配。
|
||
|
||
## 3. Editor 数据模型
|
||
|
||
```text
|
||
EditorInstallation
|
||
id
|
||
displayName
|
||
platform
|
||
userSelectedPath
|
||
canonicalExecutable
|
||
discoverySource
|
||
lastVerifiedAt
|
||
baseVersion
|
||
signatureStatus
|
||
capabilities[]
|
||
|
||
EditorCapability
|
||
versionLine // 3.8, 4.0, 4.1, 4.2, 4.3
|
||
launchSelector // 可选 -u 参数或独立 executable
|
||
status
|
||
lastProbeResult
|
||
```
|
||
|
||
同一个安装入口可以声明多个本地版本能力；多个安装入口也可以映射到同一版本。用户可为每个版本选择首选项。
|
||
|
||
## 4. 自动发现
|
||
|
||
### 4.1 macOS
|
||
|
||
优先位置：
|
||
|
||
```text
|
||
/Applications/Spine.app
|
||
~/Applications/Spine.app
|
||
```
|
||
|
||
补充来源：
|
||
|
||
- 系统应用索引
|
||
- 当前会话已知应用路径
|
||
- 历史用户配置
|
||
|
||
用户选择 `.app` 时规范化为：
|
||
|
||
```text
|
||
Spine.app/Contents/MacOS/Spine
|
||
```
|
||
|
||
不递归扫描整个磁盘。
|
||
|
||
### 4.2 Windows
|
||
|
||
发现来源：
|
||
|
||
- HKLM/HKCU 安装与卸载注册信息
|
||
- `Program Files`、`Program Files (x86)` 常见位置
|
||
- `PATH`
|
||
- 开始菜单快捷方式目标
|
||
- 历史用户配置
|
||
|
||
CLI 优先选择 `Spine.com`。如果用户选择 `Spine.exe`，查找同目录同名 `.com`；找不到时允许保存，但状态为“GUI 路径，CLI 待验证”。
|
||
|
||
## 5. 自定义路径
|
||
|
||
用户可选择：
|
||
|
||
- macOS `.app`
|
||
- 内部 Spine 可执行文件
|
||
- Windows `Spine.com` 或 `Spine.exe`
|
||
- 包含上述文件的目录
|
||
|
||
保存前执行路径规范化：
|
||
|
||
- 解析相对路径
|
||
- 清理多余分隔符
|
||
- 保留用户显示路径
|
||
- 保存 canonical path
|
||
- 记录文件标识和修改时间，用于发现安装被替换
|
||
|
||
路径移动或升级后，不自动删除旧配置，而是标记失效并允许重新定位。
|
||
|
||
## 6. 验证步骤
|
||
|
||
### 6.1 静态验证
|
||
|
||
- 文件存在且不是目录。
|
||
- 当前用户可执行。
|
||
- macOS bundle 结构或 Windows 同目录文件合理。
|
||
- 可选检查平台签名；旧版签名异常只警告，不直接否定合法安装。
|
||
|
||
### 6.2 基础进程验证
|
||
|
||
使用参数数组执行 `--version`，捕获：
|
||
|
||
- 退出码
|
||
- 标准输出和错误输出
|
||
- 启动耗时
|
||
- 报告版本
|
||
|
||
设置短超时，只终止该次探测进程。
|
||
|
||
### 6.3 版本能力验证
|
||
|
||
对用户配置的目标版本执行实际启动探测。若使用 `-u <version>` 选择器：
|
||
|
||
- 只允许已确认在本地缓存中存在的精确版本，例如资源线为 4.3 时选择本地最新的 `4.3.23`。
|
||
- 不使用 `--force`。
|
||
- 不使用 `latest`、`stable`、`beta` 或 `x.x.xx` 版本选择器。
|
||
- 不由 DateToSpine 发起下载。
|
||
- 缓存缺失时不启动 Spine Launcher，直接报告“本地未缓存目标版本”，从源头避免 Launcher 下载。
|
||
- 启动进程前再次检查精确缓存文件，避免检测后被移动导致意外联网。
|
||
|
||
当前 macOS 检查 `~/Library/Application Support/Spine/updates`，Windows 检查 `%APPDATA%/Spine/updates` 和 `%LOCALAPPDATA%/Spine/updates`。后续若 Spine 改变缓存结构，需要同步更新并重新做断网回归。
|
||
|
||
### 6.4 导入冒烟测试
|
||
|
||
在用户点击“深度验证”或首次转换前，可在临时目录执行小型导入：
|
||
|
||
- 输入与版本匹配的最小测试数据。
|
||
- 输出到临时目录。
|
||
- 验证退出码和 `.spine` 可再次读取。
|
||
- 完成立即清理临时结果。
|
||
|
||
发行版不能使用未获再分发确认的官方测试资产作为内置冒烟样本；需要自有最小样本或仅对用户当前资源执行验证。
|
||
|
||
## 7. 状态与用户提示
|
||
|
||
```text
|
||
Available
|
||
PathMissing
|
||
NotExecutable
|
||
NotSpine
|
||
CliCompanionMissing
|
||
VersionMismatch
|
||
VersionNotPrepared
|
||
NotActivated
|
||
ProbeTimedOut
|
||
PermissionDenied
|
||
LaunchFailed
|
||
Unknown
|
||
```
|
||
|
||
每个状态需要：
|
||
|
||
- 用户可读说明
|
||
- 技术详情
|
||
- 可执行的修复建议
|
||
- 是否允许预览
|
||
- 是否允许转换
|
||
|
||
资源全部载入后，主界面顶部直接显示当前资源的结果，例如“可转换 · Spine 4.3.23”或“缺少 Spine 4.1”。自动检测失败时，转换按钮才变为“指定 Spine 路径”。
|
||
|
||
## 8. 离线要求
|
||
|
||
DateToSpine 本身不联网。完整转换成立的前提是对应 Editor 版本已经在本机准备好并能在断网时运行。
|
||
|
||
离线验收必须在网络被禁用的独立测试环境进行，不能只通过代码审查推断。
|