项目修改约定

本文件适用于 AI_spine/ 及其所有子目录。每次修改代码、文档、依赖或运行测试前，都必须阅读并遵守。

Python 环境

本项目固定使用名为 ai-spine 的 Conda 环境。
不创建、不使用 .venv、venv 或其他 Python 虚拟环境；不把依赖安装到 Conda base 或系统 Python。
交互式终端先执行 conda activate ai-spine；自动化命令使用 conda run -n ai-spine ...。
Python 依赖统一记录在 requirements.txt。安装命令使用 conda run -n ai-spine python -m pip install -r requirements.txt，避免裸 pip 指向错误环境。
Node 管线调用 Python 时也必须使用此 Conda 环境。--python 只能指向 ai-spine 环境中的解释器。
不在代码中硬编码本机 Conda 安装路径，不自动创建环境或自动安装依赖。缺少环境或依赖时给出明确的安装/激活命令。

修改与验证

修改环境选择、依赖或启动方式时，同步更新 README、相关文档和 CLI 帮助，保持一致。
测试在 ai-spine 环境下执行：conda run -n ai-spine npm test。不要为了绕过依赖问题临时新建环境。
验证结果必须如实记录；缺少依赖导致未运行的检查，不得声称通过。
保留用户已有修改和实验产物，不覆盖旧实验输出。

跨会话上下文与阅读顺序

本节于 2026-09-21 根据当前代码与已检查产物整理。它是后续对话的上下文入口；后续修改应同步更新对应状态，实际源码、配置和具体实验 manifest 优先于历史总结。不要把旧实验统计套到新输出上。

先阅读本文件和 git status --short，保留用户已有修改。
阅读 README 了解项目、环境、配置与命令。
按任务阅读第一阶段、第二阶段、第三阶段，再核对相关实现与实际产物。
用户说“继续”时，先核对工作区和最近任务进展，不能只凭历史总结重复请求付费模型或覆盖实验。

用户目标与固定偏好

目标是将单张 2D 角色图拆成可以用于 Spine 的部件，保留画风、姿态、左右、不对称性及原有像素关系，补足遮挡和关节连接。
第二阶段使用本地 SAM 代码和权重，通过临时 Conda 子进程在本机 GPU 推理，完成后退出；不部署常驻独立服务。
需要可直接执行的 PowerShell 命令；说明当前已实现行为、实测结果与未来计划，不能把几何通过写成资产合格。
不确定的部件语义、遮挡和候选点需要复核，不得用前景检查、覆盖率或模型分数代替语义准确性。
输出使用独立目录，保留原候选和诊断；已有候选优先离线复检，避免无意义重复生成。

文档维护约定

各文档文件名保持不变。docs/ 当前保留三份阶段文档；docs/model-stages.md 在本次文档整理前已处于用户删除状态，不自行恢复，相关说明归入 README 和阶段文档。
三份阶段文档有且仅有以下八个二级章节，细节必须归入对应章节：
1. 阶段简介
2. 输入、输出与执行链路
3. 阶段执行命令示例及参数说明
4. 输入格式要求
5. 执行链路中重要部分代码文件及原理说明（包括重点说明）
6. 各个代码文件职责索引
7. 产物详细说明
8. 当前阶段可改进点说明
外层 README 负责整体介绍、Conda 准备、配置及每阶段命令；本文件负责约定和后续会话必要上下文。已存在的环境与修改约定必须保留。
改进项明确写为待实现/待验证；实现后更新状态、命令、产物说明及本文件。PowerShell 反引号后不能有空格；示例变量先定义，示例输出目录相互独立。

工作区、环境与配置

当前实际项目目录：F:\Study\taonier\AI_spine。用户历史命令也出现过 F:\Study\taonier\AI\_spine，不要盲目复制旧路径，先确认 cwd。
当前 SAM 根目录为 F:\Study\SAM3；源码仓库 F:\Study\SAM3\sam3；权重 F:\Study\SAM3\sam3.1checkpoint\sam3.1_multiplex.pt。早期 F:\Study\sam3.1 已不是当前约定路径。
已验证组合：Python 3.11、torch 2.7.1+cu126、torchvision 0.22.1、NumPy 1.26.4、OpenCV 4.11.0.86；RTX 3060 Laptop 6 GB。机器环境可能变化，执行前按需探测。
Node.js >=20，无额外 npm 运行时依赖。自动化使用 Conda ai-spine 执行 Node/Python；运行 SAM 可用 conda run --no-capture-output -n ai-spine node ...。
默认配置是 configs/astra-qwen.json；示例推荐明确传 config，避免环境变量导致选错提供方。
configs/deepseek-qwen.json：deepseek-flash / Chat Completions / 非流式；补全 qwen-image-3.0。
configs/astra-qwen.json：gpt-6-astra / Responses / 流式；补全 qwen-image-3.0。
上述两份读取 VECTOR_ENGINE_BASE_URL / VECTOR_ENGINE_API_KEY，模型变量为 SPINE_UNDERSTANDING_MODEL / SPINE_COMPLETION_MODEL。
configs/tiantoken.json：独立 TIANTOKEN_BASE_URL / TIANTOKEN_API_KEY，地址 https://api.tiantoken.com；理解 gpt-6-astra，补全 gpt-image-2；模型变量为 TIANTOKEN_UNDERSTANDING_MODEL / TIANTOKEN_COMPLETION_MODEL。
CLI 模型 > stage.model > 对应模型环境变量 > default_model；shell 同名变量优先于 .env。模型 ID 原样发送，不加隐式别名。
用户提供的密钥仅留在本地忽略的 .env；禁止在文档、命令日志、聊天或提交中暴露，不要读取/打印完整 .env 来诊断。
三份配置的图片编辑能力均为 multiple_images=false、mask=false。接口已预留分支不代表中转已支持；开启前需验证。Astra 理解接口与图片编辑接口不同，当前没有 Astra Responses 图片生成工具链。

三阶段实现与不能丢失的边界

第一阶段：理解与几何候选

入口 tools/model-check.mjs --stage understanding，或 pipeline.mjs --mode annotated-parts；后者仅转发新入口。
stages/model-stage.mjs 调用视觉模型，lib/validate-parts.mjs 校验 v2：rig_role、bind_to、三项 completion 及 needs_completion 一致性。
normalize_reference.py 保留原画布，使用 Alpha 或边界连通近白背景处理；geometry_grounding.py 用 Alpha/ROI 距离变换生成候选，不是再次请求 AI。
模型原始点仅诊断；程序候选也未获语义确认；pivot 独立保留，不吸附前景。
第二阶段输入必须为同一实验的 source.png、semantic-parts.json、segmentation-prompts.json。
--parts-file 可离线迁移 v1/检查 v2 并生成新候选；旧 annotated.svg 不会自动更新。

第二阶段：SAM 可见拆件

入口 --stage segmentation --input-dir 理解目录；实现为 stages/segmentation-stage.mjs、sam_runtime.py、sam_segment.py、segmentation_outputs.py。
环境探测与推理分别为短期子进程，禁止在线下载权重。multiplex detector 适配实际严格加载 1130 个张量，忽略 36 个未使用视频 neck 张量；不要因此改成 strict=False 或修改外部 SAM 源码。
BF16 仅用于推理 autocast；不要整体转换模型而破坏复数缓冲区/FP32 路径。
使用文本和文本+粗框两组候选；当前图像概念接口未接收点提示，Alpha 种子仅参与 mask 排序。
与原图 Alpha 取交集后提取原像素；mask 为原画布二值图，parts 为紧裁剪 RGBA。重叠保留、覆盖率仅为像素覆盖，semantic_verified=false。
annotated.png 为原图纹理上半透明颜色叠加，parts-sheet.png 为白底拆件；纯色遮罩角色图与可选大模型去毛边尚未实现。

第三阶段：受限部件补全

入口 --stage completion --input-dir SAM目录；实现为 stages/completion-stage.mjs、completion_geometry.py、providers/image-edits.mjs。
输入须含 source.png、v2 计划、segmentation.json 及所有记录的全画布 masks；单独 parts/ 不够。
仅处理 needs_completion=true、非隐藏、有可见 mask 且允许区域非空的部件。--part 不绕过筛选；目前不重新评估 SAM 缺损。
默认 1024 方形局部画布，原像素不缩放。允许区来自轮廓外 32 像素范围与遮挡 mask / pivot 圆盘交集，排除可见 mask；不是完整隐藏形状生成。
当前真实请求只发白底 input.png；context.png、edit-mask.png 默认不发送。开启 multiple_images 也只是发送同坐标局部 context，并非独立全角色参考。
图片解码已修复“空 b64_json 但有有效 URL”情况，回退下载 URL；该问题与画布尺寸不符不同。
在线请求现显式传 size，配置冲突失败。strict 默认拒绝尺寸不同；uniform 仅恢复同宽高比整画布尺寸，保留原候选，继续原有验收，不单独移动/缩放物体。
验收阈值：可见不透明像素 RGB MAE≤30、保留率≥95%；有效新增须在允许区且连接可见部件；原可见 RGBA 随后逐像素恢复。
unfulfilled_regions 当前只记录、不硬拒绝；语义错误、接缝、关节补够与否尚无可靠验收。错误 SAM 可见像素会被强制保留。
prepare-only 不联网；candidates-dir 可读平铺 ID.png 或匹配 manifest 的旧任务首张候选。--resume 不是失败断点续发，准备/生成/复检使用独立目录。
parts/ 只含通过检查的补全部件，不包含全部原拆件。完整角色组装、旋转验收、新管线 Spine 导出尚未接入。
旧 --stage completion --image ... --prompt-file ... 是接口探针，不能和 input-dir 混用，不执行完整几何验收。

已检查实验与质量结论

以下为已有实验记录，不代表后续每次运行的结果；不必为了文档修改重跑 GPU 或付费模型。

目录（相对于项目）	事实与意义
output/sombrero-grounding-v2	旧计划离线几何检查，28 个程序候选通过前景检查；未证明语义正确
output/sombrero-sam31-v3	较早 SAM 实验，28 个 mask，约 67.18% 覆盖率；肢体/鞋子重复、漏分，不合格
output/20260918-183532/sam	当前讨论基线：32 个计划项、10 个 hidden、22 个 mask；约 83.3% 覆盖，32719 像素未分配；前臂/手混入衣料、袖子与上衣缺损
output/20260918-183532/complete2_gpt	真实 Tiantoken gpt-image-2 请求 12 部件；旧请求未传 size，返回 1248/1254，预期 1024，全部 CANVAS_SIZE_MISMATCH
output/20260918-183532/complete2_gpt-size-recheck-v2	离线 uniform 复检，未重生成：8 个几何通过；head、pants_thigh_l、pants_thigh_r、shoe_l 4 个拒绝；通过项仍有误分和未完成区域
output/20260918-183532/complete-recovered-head-check	更早 Qwen 头部候选恢复检查，不能与 GPT 批次混为一谈

当前 22→12 的原因：sombrero、sleeve_l、sleeve_r、eye_l、eye_r、eyebrow_l、eyebrow_r、nose、mouth、mustache 共 10 个被第一阶段标记 NO_COMPLETION_NEEDED；不能解释为它们的实际 SAM mask 已完整。
2026-09-20 尺寸修复后曾通过 22 项 Node 测试（含 Python 补全回归）。这是历史验证；新改动按范围重新验证，不自动沿用“全部通过”。显式 size 构造已测试，修复后中转是否遵守尚无新实测。
总体判断：上游部件归属、模型缺少原图参考与遮罩、区域规则粗糙、验收不足共同导致低质量。不能仅换模型、强制处理全部 mask、放宽阈值或解决尺寸错误就宣称修好。

当前改进方向与后续顺序

本轮用户要求重整文档，以下功能是待实现需求，不因写入文档就成为已完成功能：

第二阶段输出仅色彩遮罩组成的完整角色图，保留当前原图叠色预览，并明确未分配/重叠区域。
第二阶段每个 SAM 部件可选经过一次大模型去毛边，保留原始拆件、原图参考、坐标、变更区域与前后对照。
第三阶段将角色原图或部件相关原图局部作为参考交给补全模型，验证中转多图/遮罩能力及实际发送内容。
第三阶段输出使用补全部件组装的完整角色，复用无需补全的原部件，明确失败/回退状态。
技术优先级：先修正 SAM 部件归属与输入门槛，再按实际 mask 重建补全计划；用头、前臂、上衣三类小样验证参考图和遮罩，然后增加回贴与关节旋转验收，最后批量与 Spine 导出。

详细改进说明保留在各阶段文档第 8 节；若后续用户改变优先级，应更新此处。

旧管线与范围识别

pipeline.mjs 未指定 --mode annotated-parts 时走旧“生成拆件图→CV 定位→Spine”流程，不是新三阶段自动串联。
segment.py 为旧拆件图分割；compose_preview.py 为旧布局组装；run_case_matrix.py 为旧定位对照工具。不要因为 IDE 当前打开这些文件就误改新阶段入口。
相邻 spine-animation-ai 为外部只读依赖，保留其 PolyForm Noncommercial 许可证约束；新阶段尚未复用为完成的导出流程。
不要把文档改写任务扩大成付费图片生成、SAM 推理、依赖安装或功能实现；需要实现时遵从用户后续任务范围。

13 KiB Raw Blame History Unescape Escape