目前第一、二阶段可运行，第三阶段已接入部件画布准备、图片编辑请求、候选几何检查及可见像素恢复。第二阶段在 ai-spine Conda 环境的临时子进程中加载本地 SAM 3.1 权重，使用 GPU 分割并生成半透明标注图、白底拆解图和透明部件。分割与补全结果仍需语义复核；新管线的 Spine 导出尚未完成。第三阶段已通过离线及 mock 接口验证，真实图片编辑质量尚待验证。

仓库仍保留旧版“AI 生成白底拆件图 → OpenCV 拆分 → Genielabs 定位 → Spine 导出”流程，用于对照和回归测试。

文档

项目修改约定：每次修改都必须遵守，Python 固定使用 ai-spine Conda 环境。
第一阶段：视觉 LLM 角色结构理解：执行流程、代码对应关系、数据格式和输出文件。
第二阶段：本地 SAM 分割：环境、运行命令、权重适配、输出和质量边界。
第三阶段：部件补全：局部画布、遮挡/关节延展区域、生成调用、可见像素恢复及几何检查。
模型阶段配置与实验说明：模型切换、协议适配、图片编辑探针、缓存和错误处理。

环境准备

Node.js

第一阶段要求 Node.js 20 或更高版本，以及下方 Python 几何依赖；没有额外 npm 运行时依赖。

node --version
conda run -n ai-spine npm test

中转站配置

在项目目录复制环境变量模板：

Copy-Item .\.env.example .\.env

编辑 .env：

VECTOR_ENGINE_BASE_URL=https://router.genarrative.world/v1
VECTOR_ENGINE_API_KEY=你的令牌

# 可选：覆盖配置文件中的默认模型
SPINE_UNDERSTANDING_MODEL=deepseek-flash
SPINE_COMPLETION_MODEL=qwen-image-3.0

# 本地 SAM 根目录和源码仓库；分割结束后子进程退出
SAM_MODEL_DIR=F:/Study/SAM3
SAM_CODE_DIR=F:/Study/SAM3/sam3

模型 ID 会原样发送给中转站，不进行隐式别名转换。不要把 API Key 写进 JSON 配置或提交到版本库。

另一个中转站 Tiantoken 使用独立配置 configs/tiantoken.json。在本地 .env 设置 TIANTOKEN_BASE_URL=https://api.tiantoken.com 和 TIANTOKEN_API_KEY，运行时增加 --config .\configs\tiantoken.json；原中转站配置保持独立。

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

该配置默认第一阶段使用 gpt-6-astra（Responses），第三阶段使用 gpt-image-2（images/edits），可通过 TIANTOKEN_UNDERSTANDING_MODEL、TIANTOKEN_COMPLETION_MODEL 或对应 CLI 参数覆盖。2026-09-20 已验证认证与模型列表访问，返回 113 个模型，含上述两个 ID；尚未验证实际理解、图片编辑或 Responses 图片生成工具能力。此配置不等于已接入 Astra 主导的第三阶段图片生成。

Python 与外部项目

本项目固定使用 Conda 环境 ai-spine，不使用或创建 .venv。第一阶段的 Alpha 校验需要 Python 3、Pillow、numpy、opencv-python。

执行项目命令前先 conda activate ai-spine。Node 管线会检查 Python 属于该 Conda 环境；--python 也只能指定该环境的解释器。未激活环境或缺少依赖时会报错，不会自动创建环境或安装依赖。

旧版拆件和 Spine 导出还需要：

Python 3；
Pillow、numpy、opencv-python；
相邻目录中的 spine-animation-ai 项目。

当前本机验证组合为 Python 3.11、PyTorch 2.7.1 + CUDA 12.6、torchvision 0.22.1。在 AI_spine 目录补全依赖；已有此 CUDA 版本时跳过第一条安装命令：

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

检查解释器和依赖：

conda run -n ai-spine python -c "import sys, cv2, PIL, numpy; print(sys.executable); print('Dependencies OK')"

spine-animation-ai 是外部只读依赖，使用时需要遵守其 PolyForm Noncommercial 许可证。

常用命令

以下命令默认在 AI_spine 目录、已激活的 ai-spine Conda 环境中运行。自动化可使用 conda run -n ai-spine node ...。

查询中转站模型

node .\tools\model-check.mjs --list-models

检查本地配置

不请求模型，也不生成付费内容：

node .\pipeline.mjs --mode annotated-parts `
  --config .\configs\deepseek-qwen.json `
  --reference ..\spine-animation-ai\demo\character_reference.png `
  --dry-run

使用 DeepSeek Flash 理解角色结构

当前已验证可用的配置是 deepseek-flash + chat-completions + stream=false：

node .\pipeline.mjs --mode annotated-parts `
  --config .\configs\deepseek-qwen.json `
  --reference ..\spine-animation-ai\demo\character_reference.png `
  --out-dir .\output\sombrero-understand-deepseek `
  --stop-after understand

重点检查输出目录中的：

report.html：人工复核页面；
semantic-parts.json：v2 语义计划，包含 rig_role、bind_to、三项 completion；
geometry-validation.json：原始点诊断、框内前景比例、候选及阻塞原因；
segmentation-prompts.json：程序生成的 SAM 候选提示；模型原始正负点不会传入；
validation.json：本地结构校验结果；
manifest.json：模型、输入、代码版本和产物记录。

输入保留画布尺寸。已有透明背景直接保留 Alpha；不透明白底只移除与边界连通的近白区域。其他背景需先提供抠图 PNG。候选来自粗框内前景的距离变换，不能保证属于目标部件，仍需语义复核。关节点不会吸附到前景。

已有结果可离线检查，无需再次请求模型：

node .\tools\model-check.mjs `
  --reference .\output\sombrero-understand-deepseek-flash\source.png `
  --parts-file .\output\sombrero-understand-deepseek-flash\semantic-parts.json `
  --out-dir .\output\sombrero-grounding-review

旧版 v1 计划会保守迁移到 v2，迁移推断写入 notes，仍需复核；原文件不覆盖。

使用 GPT-6 Astra 做对照实验

node .\pipeline.mjs --mode annotated-parts `
  --config .\configs\astra-qwen.json `
  --reference ..\spine-animation-ai\demo\character_reference.png `
  --out-dir .\output\sombrero-understand-astra `
  --stop-after understand

当前中转站的 Astra 通道要求 Responses 协议和流式响应。若中转站返回 overloaded，应使用新的输出目录稍后重试。

临时覆盖理解模型

node .\pipeline.mjs --mode annotated-parts `
  --config .\configs\deepseek-qwen.json `
  --understanding-model YOUR_EXACT_MODEL_ID `
  --understanding-protocol chat-completions `
  --stream false `
  --reference .\reference.png `
  --out-dir .\output\model-experiment `
  --stop-after understand

每组模型实验应使用独立的输出目录，避免覆盖对照结果。只有输入、配置、代码和产物哈希全部一致时，才可以通过 --resume 复用结果。

使用本地 SAM 生成标注和拆解图

复用已有第一阶段结果，不重新请求 DeepSeek，也不需要中转站密钥：

conda run --no-capture-output -n ai-spine node .\tools\model-check.mjs `
  --stage segmentation `
  --input-dir .\output\sombrero-grounding-v2 `
  --out-dir .\output\sombrero-sam-local `
  --sam-dir F:/Study/SAM3

打开输出目录的 report.html：annotated.png 是原图上的不同半透明颜色标注，parts-sheet.png 是白底拆解图，parts/ 保存原像素透明部件。运行期间加载 GPU 权重，完成后子进程退出，不启动常驻服务。

加入 --dry-run 可检查环境与本地路径，不加载权重推理。输入必须含 source.png、v2 semantic-parts.json、segmentation-prompts.json。完整参数与质量检查见第二阶段文档。

第三阶段：按部件补全

先从已有 SAM 输出准备画布、允许新增区域和提示词，不请求模型：

node .\tools\model-check.mjs --stage completion `
  --input-dir .\output\sombrero-sam31-v3 `
  --out-dir .\output\sombrero-completion-prepare `
  --completion-model qwen-image-3.0 `
  --prepare-only

打开 report.html 检查部件和允许新增区域。以下命令对 head 发起一次部件编辑任务，再检查候选并恢复原图可见像素；会调用中转站图片模型：

node .\tools\model-check.mjs --stage completion `
  --input-dir .\output\sombrero-sam31-v3 `
  --out-dir .\output\sombrero-completion-head `
  --completion-model qwen-image-3.0 `
  --part head

--part 可重复；省略则处理所有具备可见 mask、补全需求和允许区域的部件。当前 SAM 示例仍有错分，应先复核。补全不会自动纠正上游语义；通过几何检查的 PNG 保存到 parts/，仍需人工复核。完整参数、离线候选导入与限制见第三阶段文档。

单独测试图片补全接口

此命令只验证图片编辑适配器并保存原始候选，不代表补全部件已经验收通过：

node .\tools\model-check.mjs --stage completion `
  --image .\local-part.png `
  --prompt-file .\task.txt `
  --out-dir .\output\qwen-edit-test `
  --completion-model qwen-image-3.0

运行旧版完整管线

node .\pipeline.mjs `
  --reference ..\spine-animation-ai\demo\character_reference.png `
  --out-dir .\output\legacy-character `
  --genielabs-dir ..\spine-animation-ai `
  --image-model qwen-image-3.0 `
  --attempts 1 `
  --animations idle,walk,wave

旧流程依赖生成式拆件与传统 CV 定位，对低纹理、低分辨率和生成后外观变化较大的角色不稳定。其输出应通过 assembled.png 和 preview-rigged.html 人工检查后再导入 Spine。

运行测试

conda run -n ai-spine npm test

测试使用本地 mock HTTP 服务或注入响应，不调用真实付费模型。

README.md Unescape Escape

AI Spine 角色拆件与动画管线

文档