AI Spine 角色拆件与动画管线

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

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

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

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

文档入口

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

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

Conda 环境准备

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

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

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

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

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

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

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

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

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

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

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

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

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 不存在时复制模板，随后自行填写密钥：

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

# 原中转站
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	deepseek-flash，Chat Completions，非流式	qwen-image-3.0，images/edits	SPINE_UNDERSTANDING_MODEL / SPINE_COMPLETION_MODEL
astra-qwen.json	gpt-6-astra，Responses，流式	qwen-image-3.0，images/edits	同上
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 已生成但不默认发送。改进计划见第三阶段文档。

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

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；分阶段重开终端时，将路径变量设置成已有的对应目录。

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

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

第一阶段：理解角色结构

此命令调用视觉模型：

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 距离变换，落在前景不代表属于正确部件。

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

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 分割

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 归属，错误部件应先修正。

第三阶段：准备与补全

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

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

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

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

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

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/ 仅包含通过检查的补全部件。所有结果仍需语义复核。

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

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；参数及中转实测边界见第三阶段文档。

旧管线与验证

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

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 导出。

测试与命令帮助：

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 只复用完整匹配产物，失败任务另建输出目录。