# AI Spine 角色拆件与动画管线

本项目探索将单张 2D 角色图转换为可用于 Spine 动画的部件与骨骼资源。当前主线分为三个阶段：视觉 LLM 理解结构、本地 SAM 分割可见部件、图片编辑模型补全隐藏区域和关节连接。

| 阶段 | 输入 → 输出 | 当前状态 |
| --- | --- | --- |
| 1. 结构理解 | PNG → v2 语义计划、粗框、pivot、程序候选点 | 可在线理解或离线复检；语义待复核 |
| 2. SAM 分割 | 第一阶段目录 → mask、原像素透明部件、标注图与拆解图 | 本机 GPU 实测可运行；存在误分与漏分 |
| 3. 部件补全 | SAM 目录 → 局部编辑候选、几何 QA、通过检查的补全部件 | 已真实调用图片模型；结果质量尚不合格 |

第三阶段尚未输出使用补全部件组装的完整角色，新管线 Spine 导出也未完成。执行成功、mask 覆盖率高、几何检查通过，均不等于动画资产可用。

仓库保留旧版“生成白底拆件图 → OpenCV 拆分 → Genielabs 定位 → Spine 导出”作为对照；它与当前三阶段主线并存，产物不能直接混用。

## 文档入口

- [AGENTS.md](AGENTS.md)：修改约定、跨会话上下文、当前基线及后续优先级。
- [第一阶段](docs/1-understanding-stage.md)：理解、数据契约、Alpha 候选与粗标注。
- [第二阶段](docs/2-segmentation-stage.md)：本地 SAM、mask 选择、拆件与质量边界。
- [第三阶段](docs/3-completion-stage.md)：筛选、局部画布、图片请求、几何验收及补全改进。

阶段文档统一采用八节：简介；输入输出与链路；命令参数；输入格式；重要代码原理；职责索引；产物；可改进点。配置与实验说明已归入上述文档。

## Conda 环境准备

所有 Python 操作固定使用 **ai-spine**，不使用 `.venv`、其他虚拟环境、Conda base 或系统 Python。Node.js 要求 20 或以上；项目没有额外 npm 运行时依赖。

在 PowerShell 中进入实际项目根目录。本工作区路径如下；若本机使用其他目录，仅替换这一行：

```powershell
Set-Location F:\Study\taonier\AI_spine
node --version
conda env list
```

仅在没有 ai-spine 环境的新机器上，手动创建一次；当前机器已有环境则跳过：

```powershell
conda create -n ai-spine python=3.11 -y
```

补齐项目依赖。以下是本机已验证的 CUDA 12.6 组合；已有匹配 PyTorch 时可跳过第一条安装命令。代码不会自动安装依赖或创建环境。

```powershell
conda activate ai-spine
python -m pip install torch==2.7.1 torchvision==0.22.1 --index-url https://download.pytorch.org/whl/cu126
python -m pip install -r .\requirements.txt
python -m pip install --no-deps --no-build-isolation -e F:\Study\SAM3\sam3
```

不激活终端时，明确指定目标环境：

```powershell
conda run -n ai-spine python -m pip install -r .\requirements.txt
```

本地 SAM 代码和权重由用户提供，当前位置为：

```text
F:/Study/SAM3/sam3/                              源码仓库
F:/Study/SAM3/sam3.1checkpoint/sam3.1_multiplex.pt 权重
```

检查解释器、基础依赖与 GPU：

```powershell
conda run -n ai-spine python -c "import sys, cv2, PIL, numpy, torch; print(sys.executable); print('torch', torch.__version__); print('CUDA', torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'No CUDA GPU')"
```

第二阶段要求可用 CUDA GPU。本机已验证 RTX 3060 Laptop 6 GB；默认 BF16 推理保留模型参数和缓冲区所需精度。第一、三阶段的本地几何处理不运行 SAM。Node 入口会验证 Python 属于 ai-spine；`--python` 也不能绕过此约定。

## 中转站配置

仅在本地 `.env` 不存在时复制模板，随后自行填写密钥：

```powershell
if (-not (Test-Path .\.env)) { Copy-Item .\.env.example .\.env }
```

```dotenv
# 原中转站
VECTOR_ENGINE_BASE_URL=https://router.genarrative.world/v1
VECTOR_ENGINE_API_KEY=填写你的令牌

# Tiantoken 独立配置
TIANTOKEN_BASE_URL=https://api.tiantoken.com
TIANTOKEN_API_KEY=填写你的令牌

# 本地 SAM
SAM_MODEL_DIR=F:/Study/SAM3
SAM_CODE_DIR=F:/Study/SAM3/sam3
```

不要把密钥写入文档、JSON 配置或提交到版本库；不要输出 `.env` 内容。

| 配置文件 | 第一阶段 | 第三阶段 | 模型环境变量 |
| --- | --- | --- | --- |
| [deepseek-qwen.json](configs/deepseek-qwen.json) | deepseek-flash，Chat Completions，非流式 | qwen-image-3.0，images/edits | SPINE_UNDERSTANDING_MODEL / SPINE_COMPLETION_MODEL |
| [astra-qwen.json](configs/astra-qwen.json) | gpt-6-astra，Responses，流式 | qwen-image-3.0，images/edits | 同上 |
| [tiantoken.json](configs/tiantoken.json) | gpt-6-astra，Responses，流式 | gpt-image-2，images/edits | TIANTOKEN_UNDERSTANDING_MODEL / TIANTOKEN_COMPLETION_MODEL |

CLI > 配置 stage.model > 对应模型环境变量 > default_model；shell 环境变量优先于 `.env`。不指定配置时入口默认 astra-qwen.json，建议实验始终显式指定。模型 ID 原样发送，中转能力以实际请求为准。Tiantoken 图片编辑已真实执行；第三阶段尚未适配 Astra Responses 图片生成工具。

三个配置当前均关闭多图参考与编辑 mask 能力。第三阶段默认只发送白底单部件图；本地 context.png/edit-mask.png 已生成但不默认发送。改进计划见第三阶段文档。

查询模型列表和检查配置：

```powershell
node .\tools\model-check.mjs --config .\configs\tiantoken.json --list-models
node .\tools\model-check.mjs --config .\configs\tiantoken.json --dry-run
```

前者联网，后者不请求模型；列表存在某个 ID 不代表其所有能力已验证。

## 三阶段执行命令

以下命令按顺序在同一个 PowerShell 会话执行。反引号后不能带空格。每次实验使用新的 runId；分阶段重开终端时，将路径变量设置成已有的对应目录。

```powershell
conda activate ai-spine
$runId = Get-Date -Format "yyyyMMdd-HHmmss"
$runRoot = ".\output\$runId"
$reference = ".\output\20260918-183532\sam\source.png"
```

示例复用现有角色原图，可替换 `$reference` 为自己的 PNG。不要混用不同实验的 source、计划和 mask。

### 第一阶段：理解角色结构

此命令调用视觉模型：

```powershell
node .\tools\model-check.mjs --stage understanding `
  --config .\configs\deepseek-qwen.json `
  --reference $reference `
  --out-dir "$runRoot\understand"
```

检查 `understand/report.html`、`semantic-parts.json`、`geometry-validation.json`。程序候选点来自 Alpha 距离变换，落在前景不代表属于正确部件。

已有计划可离线重新检查；输出独立目录，不重跑模型：

```powershell
node .\tools\model-check.mjs --stage understanding `
  --reference .\output\20260918-183532\sam\source.png `
  --parts-file .\output\20260918-183532\sam\semantic-parts.json `
  --out-dir "$runRoot\understand-offline"
```

### 第二阶段：本地 SAM 分割

```powershell
node .\tools\model-check.mjs --stage segmentation `
  --input-dir "$runRoot\understand" `
  --out-dir "$runRoot\sam" `
  --sam-dir F:/Study/SAM3
```

若使用前面的离线计划，input-dir 改为 understand-offline。该命令只运行本地临时 GPU 子进程；添加 `--dry-run` 可探测环境而不加载模型。检查 `sam/report.html`、`annotated.png`、`parts-sheet.png`、漏分图和 mask 归属，错误部件应先修正。

### 第三阶段：准备与补全

先离线准备任务，不请求模型：

```powershell
node .\tools\model-check.mjs --stage completion `
  --config .\configs\tiantoken.json `
  --input-dir "$runRoot\sam" `
  --out-dir "$runRoot\complete-prepare" `
  --prepare-only
```

复核允许区域后，按实际存在的 ID 试一个部件；下面会调用图片模型：

```powershell
node .\tools\model-check.mjs --stage completion `
  --config .\configs\tiantoken.json `
  --input-dir "$runRoot\sam" `
  --out-dir "$runRoot\complete-head" `
  --part head
```

处理所有具备可见 mask、补全需求和允许区域的部件：

```powershell
node .\tools\model-check.mjs --stage completion `
  --config .\configs\tiantoken.json `
  --input-dir "$runRoot\sam" `
  --out-dir "$runRoot\complete"
```

省略 part 不意味着强制补全全部 mask。检查 `completion-plan.json` 的跳过原因和 `completion-result.json` 的 QA；parts/ 仅包含通过检查的补全部件。所有结果仍需语义复核。

旧候选尺寸不符时，可离线导入复检，避免重新生成：

```powershell
node .\tools\model-check.mjs --stage completion `
  --config .\configs\tiantoken.json `
  --input-dir .\output\20260918-183532\sam `
  --candidates-dir .\output\20260918-183532\complete2_gpt `
  --out-dir "$runRoot\complete-size-recheck" `
  --candidate-size-policy uniform
```

uniform 仅恢复同宽高比的整画布尺寸，不纠正物体位移、变形或语义。在线请求现已显式传 size；参数及中转实测边界见[第三阶段文档](docs/3-completion-stage.md)。

## 旧管线与验证

旧版依赖相邻 `spine-animation-ai` 外部项目，使用时遵守其 PolyForm Noncommercial 许可证；不要修改外部依赖。旧版命令会调用图片生成并尝试定位、导出：

```powershell
node .\pipeline.mjs `
  --reference $reference `
  --out-dir "$runRoot\legacy" `
  --genielabs-dir ..\spine-animation-ai `
  --image-model qwen-image-3.0 `
  --attempts 1 `
  --animations idle,walk,wave
```

`segment.py` 为旧版拆件分割，`compose_preview.py` 组装预览，`run_case_matrix.py` 对照定位方案；当前 SAM 入口为 sam_segment.py。旧产物需检查 assembled.png 和 preview-rigged.html，不能据此声称新三阶段已经完成 Spine 导出。

测试与命令帮助：

```powershell
conda run --no-capture-output -n ai-spine npm test
node .\tools\model-check.mjs --help
```

测试使用本地 mock 或注入响应，不请求真实付费模型。自动化运行任一阶段可用 `conda run --no-capture-output -n ai-spine node ...`。保留旧实验；resume 只复用完整匹配产物，失败任务另建输出目录。