第三步补全接入

README.md

@@ -8,7 +8,7 @@
 2. 使用 SAM 根据语义、粗框和程序候选生成 mask，经语义/几何检查后从原图提取可见像素。
 3. 使用图片编辑模型补全被遮挡的部件，再进行几何验收和 Spine 导出。
 
-目前第一阶段和第二阶段均可运行。第二阶段在 `ai-spine` Conda 环境的临时子进程中加载本地 SAM 3.1 权重，使用 GPU 分割并生成半透明标注图、白底拆解图和透明部件。分割结果仍需语义复核；补全结果合并及新管线的 Spine 导出尚未完成。
+目前第一、二阶段可运行，第三阶段已接入部件画布准备、图片编辑请求、候选几何检查及可见像素恢复。第二阶段在 `ai-spine` Conda 环境的临时子进程中加载本地 SAM 3.1 权重，使用 GPU 分割并生成半透明标注图、白底拆解图和透明部件。分割与补全结果仍需语义复核；新管线的 Spine 导出尚未完成。第三阶段已通过离线及 mock 接口验证，真实图片编辑质量尚待验证。
 
 仓库仍保留旧版“AI 生成白底拆件图 → OpenCV 拆分 → Genielabs 定位 → Spine 导出”流程，用于对照和回归测试。
 
@@ -17,6 +17,7 @@
 - [项目修改约定](AGENTS.md)：每次修改都必须遵守，Python 固定使用 `ai-spine` Conda 环境。
 - [第一阶段：视觉 LLM 角色结构理解](docs/1-understanding-stage.md)：执行流程、代码对应关系、数据格式和输出文件。
 - [第二阶段：本地 SAM 分割](docs/2-segmentation-stage.md)：环境、运行命令、权重适配、输出和质量边界。
+- [第三阶段：部件补全](docs/3-completion-stage.md)：局部画布、遮挡/关节延展区域、生成调用、可见像素恢复及几何检查。
 - [模型阶段配置与实验说明](docs/model-stages.md)：模型切换、协议适配、图片编辑探针、缓存和错误处理。
 
 ## 环境准备
@@ -55,6 +56,15 @@ SAM_CODE_DIR=F:/Study/SAM3/sam3
 
 模型 ID 会原样发送给中转站，不进行隐式别名转换。不要把 API Key 写进 JSON 配置或提交到版本库。
 
+另一个中转站 Tiantoken 使用独立配置 [configs/tiantoken.json](configs/tiantoken.json)。在本地 `.env` 设置 `TIANTOKEN_BASE_URL=https://api.tiantoken.com` 和 `TIANTOKEN_API_KEY`，运行时增加 `--config .\configs\tiantoken.json`；原中转站配置保持独立。
+
+```powershell
+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`。
@@ -188,7 +198,31 @@ conda run --no-capture-output -n ai-spine node .\tools\model-check.mjs `
 
 加入 `--dry-run` 可检查环境与本地路径，不加载权重推理。输入必须含 `source.png`、v2 `semantic-parts.json`、`segmentation-prompts.json`。完整参数与质量检查见[第二阶段文档](docs/2-segmentation-stage.md)。
 
-### 测试图片补全接口
+### 第三阶段：按部件补全
+
+先从已有 SAM 输出准备画布、允许新增区域和提示词，不请求模型：
+
+```powershell
+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` 发起一次部件编辑任务，再检查候选并恢复原图可见像素；会调用中转站图片模型：
+
+```powershell
+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/`，仍需人工复核。完整参数、离线候选导入与限制见[第三阶段文档](docs/3-completion-stage.md)。
+
+### 单独测试图片补全接口
 
 此命令只验证图片编辑适配器并保存原始候选，不代表补全部件已经验收通过：