# 版本识别与 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 版本已经在本机准备好并能在断网时运行。

离线验收必须在网络被禁用的独立测试环境进行，不能只通过代码审查推断。