AI Spine 角色拆件与动画管线

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

阶段	输入 → 输出	当前状态
1. 结构理解	PNG → v2 语义计划、粗框、pivot、程序候选点	可在线理解或离线复检；语义待复核
2. SAM 分割	第一阶段目录 → mask、原像素透明部件、标注图与拆解图	本机 GPU 实测可运行；存在误分与漏分
3. 部件补全	SAM 目录 → 局部编辑候选、几何 QA、通过检查的补全部件	已真实调用图片模型；结果质量尚不合格
4. Spine 导出	SAM + 可选补全目录 → 完整资产、原位组装、骨骼、图集、预览	通用离线入口；含单骨骼旋转检查动画，资产与动作质量需复核

第三阶段输出通过几何检查的补全部件；第四阶段整合所有可绘制部件、组装并导出 Spine 4.2。执行成功、mask 覆盖率高、几何检查通过，均不等于动画资产可用。

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

文档入口

• AGENTS.md：修改约定、跨会话上下文、当前基线及后续优先级。
• 第一阶段：理解、数据契约、Alpha 候选与粗标注。
• 第二阶段：本地 SAM、mask 选择、拆件与质量边界。
• 第三阶段：筛选、局部画布、图片请求、几何验收及补全改进。
• 第四阶段：通用资产整合、坐标与骨骼、绘制顺序、Spine 导出与回退策略。

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

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 能力。第三阶段默认 adaptive：实际 mask 重建需求、自适应半径和可逆缩放；当前配置下 auto 会发送含目标、局部参考、完整角色参考的单张参考板。只有支持原生多图时才独立发送参考图；mask 是否发送由配置和 completion-mask 决定，未发送时明确标记 local_only。不能把本地裁剪与恢复当成模型遵循 mask 的证据。

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

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

第三阶段：准备与补全

默认 --completion-profile adaptive 会重新检查实际 SAM 缺口、骨骼连接和附件重叠，即使旧计划 needs_completion=false 也可能生成修复任务。先检查 preparation 报告的区域与参考图，再请求模型；缺口归属和附件底图仍需语义复核。

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

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 的 assessments/跳过原因、每个任务的 input.png、request-plan.json 和编辑区域；parts/ 仅包含通过检查的补全部件。所有结果仍需语义复核。--completion-review FILE 可按 ID 提供修复/替换/移除区域及部件半径，格式见第三阶段文档。

--completion-reference auto 默认在原生多图可用时发送主图→局部参考→全角色参考，否则使用 board；可显式选择 board/local/full/both/none。--completion-mask auto|required|off 控制 mask 请求，auto 遵循配置。--probe-edit-capabilities --part ID 是一次真实多图+mask 小样，固定 n=1、无 HTTP 重试，保存原候选及能力证据，不自动启用 capabilities。该实测会产生费用；当前实现只完成离线验证。

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

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" `
  --completion-profile legacy `
  --candidate-size-policy uniform

旧画布候选必须指定 legacy。adaptive 候选需匹配源图、masks、profile、参考布局、半径和复核文件哈希；不能把旧候选直接映射到新画布。uniform 仅恢复同宽高比整画布尺寸，不纠正物体位移、变形或语义。在线请求显式传 size；参数及中转实测边界见第三阶段文档。

第四阶段：离线组装与 Spine 导出

接续本轮 SAM 与补全目录，无需模型配置、密钥或 GPU：

node .\tools\model-check.mjs --stage spine `
  --input-dir "$runRoot\sam" `
  --completion-dir "$runRoot\complete" `
  --out-dir "$runRoot\spine"

省略 --completion-dir 可只用 SAM 资产；加 --dry-run 完整检查输入而不写输出。默认补全失败回退 SAM 并记录原因；--fallback-policy error 要求需补全的可见部件全部有通过结果。可见部件缺 mask、混用不同输入或非法补全坐标会直接报错。

检查 report.html、comparison.png 和 assembly.json；preview.html 显示真实骨架，setup 为静态姿态，check__骨骼ID 为单关节旋转检查动画。生成过程离线；播放器页面从 CDN 加载 Spine Player，需要网络。skeleton.json 配合 images/ 供编辑器导入，atlas/ 用于运行时。

部件数量、名称、父子关系均由 v2 计划驱动；隐藏骨骼保留，附件按 bind_to 绑定。第四阶段只复用外部只读 spine-animation-ai 的图集和播放器脚本，保留其 PolyForm Noncommercial 约束。完整参数、输入契约和绘制顺序覆盖见第四阶段文档。

旧管线与验证

旧版依赖相邻 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；新管线导出使用独立的第四阶段入口。

测试与命令帮助：

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