增加几何校验

README.md

@@ -4,8 +4,8 @@
 
 当前正在实现的新管线分为三个核心阶段：
 
-1. 视觉 LLM 理解角色结构，输出部件语义、层级、遮挡关系、粗框和分割提示点。
-2. 使用 SAM 根据提示点生成精确 mask，并从原图提取可见像素。
+1. 视觉 LLM 输出语义、层级、骨骼/附件分类、遮挡、粗框和粗关节；程序用 Alpha 检查 ROI 并生成候选种子。
+2. 使用 SAM 根据语义、粗框和程序候选生成 mask，经语义/几何检查后从原图提取可见像素。
 3. 使用图片编辑模型补全被遮挡的部件，再进行几何验收和 Spine 导出。
 
 目前第一阶段已经可以完整运行。SAM 3.1 checkpoint 路径和图片编辑适配器已经接入配置，但 SAM 推理、补全结果合并及新管线的 Spine 导出尚未完成。
@@ -14,6 +14,7 @@
 
 ## 文档
 
+- [项目修改约定](AGENTS.md)：每次修改都必须遵守，Python 固定使用 `ai-spine` Conda 环境。
 - [第一阶段：视觉 LLM 角色结构理解](docs/1-understanding-stage.md)：执行流程、代码对应关系、数据格式和输出文件。
 - [模型阶段配置与实验说明](docs/model-stages.md)：模型切换、协议适配、图片编辑探针、缓存和错误处理。
 
@@ -21,11 +22,11 @@
 
 ### Node.js
 
-第一阶段要求 Node.js 20 或更高版本，不需要 Python，也没有额外 npm 运行时依赖。
+第一阶段要求 Node.js 20 或更高版本，以及下方 Python 几何依赖；没有额外 npm 运行时依赖。
 
 ```powershell
 node --version
-npm test
+conda run -n ai-spine npm test
 ```
 
 ### 中转站配置
@@ -54,27 +55,40 @@ SAM_MODEL_DIR=F:/Study/sam3.1
 
 ### Python 与外部项目
 
-运行第一阶段不需要 Python。
+本项目固定使用 **Conda 环境 `ai-spine`**，不使用或创建 `.venv`。第一阶段的 Alpha 校验需要 Python 3、`Pillow`、`numpy`、`opencv-python`。
 
-只有旧版拆件和 Spine 导出流程需要：
+执行项目命令前先 `conda activate ai-spine`。Node 管线会检查 Python 属于该 Conda 环境；`--python` 也只能指定该环境的解释器。未激活环境或缺少依赖时会报错，不会自动创建环境或安装依赖。
+
+旧版拆件和 Spine 导出还需要：
 
 - Python 3；
 - `Pillow`、`numpy`、`opencv-python`；
 - 相邻目录中的 `spine-animation-ai` 项目。
 
-安装旧流程依赖：
+在 `AI_spine` 目录安装缺失的 Python 依赖（已满足版本要求的包会保留）：
 
 ```powershell
-python -m venv .venv
-.\.venv\Scripts\Activate.ps1
+conda activate ai-spine
 python -m pip install -r .\requirements.txt
 ```
 
+不激活终端也可明确指定安装目标：
+
+```powershell
+conda run -n ai-spine python -m pip install -r .\requirements.txt
+```
+
+检查解释器和依赖：
+
+```powershell
+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` 目录、已激活的 `ai-spine` Conda 环境中运行。自动化可使用 `conda run -n ai-spine node ...`。
 
 ### 查询中转站模型
 
@@ -108,10 +122,25 @@ node .\pipeline.mjs --mode annotated-parts `
 重点检查输出目录中的：
 
 - `report.html`：人工复核页面；
-- `semantic-parts.json`：后续 SAM 阶段的正式输入；
+- `semantic-parts.json`：v2 语义计划，包含 `rig_role`、`bind_to`、三项 `completion`；
+- `geometry-validation.json`：原始点诊断、框内前景比例、候选及阻塞原因；
+- `segmentation-prompts.json`：程序生成的 SAM 候选提示；模型原始正负点不会传入；
 - `validation.json`：本地结构校验结果；
 - `manifest.json`：模型、输入、代码版本和产物记录。
 
+输入保留画布尺寸。已有透明背景直接保留 Alpha；不透明白底只移除与边界连通的近白区域。其他背景需先提供抠图 PNG。候选来自粗框内前景的距离变换，不能保证属于目标部件，仍需语义复核。关节点不会吸附到前景。
+
+已有结果可离线检查，无需再次请求模型：
+
+```powershell
+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 做对照实验
 
 ```powershell
@@ -168,7 +197,7 @@ node .\pipeline.mjs `
 ### 运行测试
 
 ```powershell
-npm test
+conda run -n ai-spine npm test
 ```
 
 测试使用本地 mock HTTP 服务或注入响应，不调用真实付费模型。