新方案v1角色结构理解

docs/model-stages.md

@@ -0,0 +1,165 @@
+# 第一阶段：可替换模型接口与角色结构理解
+
+本轮实现 GPT6Astra 结构理解、Qwen Image 3.0 图片编辑适配器、结构 JSON 校验、粗标注预览、实验记录和缓存。新增模式不需要 Python，不运行旧的“拆件图 → SIFT 定位”流程。
+
+结构理解当前停在 `understand`；SAM 分割、掩码修正、隐藏部件合并、Spine 骨骼导出是后续阶段。图片编辑测试保存的是原始候选，不是验收通过的最终资产。
+
+## 环境与模型
+
+要求 Node.js 20 或更高版本，无新增 npm 依赖。在 `AI_spine` 目录运行。
+
+复用现有 `.env` 的地址和密钥，可增加：
+
+```dotenv
+SPINE_UNDERSTANDING_MODEL=gpt-6-astra
+SPINE_COMPLETION_MODEL=qwen-image-3.0
+SAM_MODEL_DIR=F:/Study/sam3.1
+```
+
+不配置这三项时，`configs/astra-qwen.json` 已提供相同默认值。不会自动改写用户的 `.env`。
+
+查询中转站模型 ID（只读取列表，不调用生成）：
+
+```powershell
+node .\tools\model-check.mjs --list-models
+```
+
+模型展示名不等于 API ID。2026-09-17 的本机接口查询包含 `gpt-6-astra` 和 `qwen-image-3.0`。支持列表不保证所有端点/多图/mask 参数可用，需要分别验证。
+
+本地配置检查（不联网，不生成图片）：
+
+```powershell
+node .\tools\model-check.mjs --dry-run
+```
+
+## 运行结构理解
+
+```powershell
+node .\pipeline.mjs --mode annotated-parts --reference ..\spine-animation-ai\demo\character_reference.png --out-dir .\output\sombrero-astra --stop-after understand
+```
+
+首次调用会向配置的中转站发送参考图。每个实验使用新输出目录；本轮不会自动覆盖旧产物。
+
+切换理解模型：
+
+```powershell
+node .\pipeline.mjs --mode annotated-parts --reference ..\spine-animation-ai\demo\character_reference.png --out-dir .\output\sombrero-other --understanding-model YOUR_EXACT_MODEL_ID --stop-after understand
+```
+
+切换协议（需中转站实际支持）：
+
+```powershell
+node .\pipeline.mjs --mode annotated-parts --reference ..\spine-animation-ai\demo\character_reference.png --out-dir .\output\sombrero-responses --understanding-protocol responses --stop-after understand
+```
+
+协议可选 `chat-completions` / `responses`，默认 `responses`：本机中转站实测 Astra 的 codex channel 明确拒绝 `/v1/chat/completions`。输出模式默认 `text-json`：在提示词中提供 Schema，并始终在本地严格校验。显式确认中转站支持后，可使用 `--output-mode json-object` 或 `--output-mode json-schema`。不会因 400/不支持的协议自动换模型或偷偷降低输出约束。
+
+该 Astra 通道还要求 `stream=true`，所以默认配置启用流式 Responses，并设置 `store=false`。适配器收集 SSE 后只接受完整的终止事件，输出仍是普通 JSON 文件。新模型可在阶段配置中设置 `stream: false`。`response.raw.json` 对 SSE 保存终止事件中的 response 对象，非逐字节 SSE 日志；`request-metadata.json` 记录 wire_format。
+
+切换到非流式 Chat Completions 模型时可使用 `--understanding-protocol chat-completions --stream false`，不会沿用 Astra 的流式设置。
+
+项目同时提供 `configs/deepseek-qwen.json`。它把第一阶段固定为
+`deepseek-flash + chat-completions + stream=false`，第三阶段仍使用
+`qwen-image-3.0`，适合与默认的 `configs/astra-qwen.json` 做对照实验：
+
+```powershell
+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
+```
+
+主要产物：
+
+| 文件 | 含义 |
+| --- | --- |
+| `source.png` | 实际提交的原图，不缩放、不裁剪 |
+| `semantic-parts.json` | 已通过结构校验的部件清单 |
+| `annotated.svg` | 原图上的粗框、关节点、正点和父子连线，可直接浏览器打开 |
+| `report.html` | 自包含检查页面，带部件表和模型记录 |
+| `validation.json` | 字段、坐标、引用、父子环和遮挡环校验结果 |
+| `response.raw.json` / `response.txt` | 原始服务端响应 / 提取的文本 |
+| `prompt.txt` / `request.json` | 提示词 / 请求设置与输入哈希；图片内容单独保存在 source.png |
+| `request-metadata.json` | requested/returned model、request ID、usage、耗时和请求次数 |
+| `manifest.json` | 运行状态、配置、代码版本、源文件哈希和产物哈希 |
+
+`status=completed` 仅表示这一步执行完成。`quality_status=needs_review` 表示仍需人工检查语义和框的位置。粗框不是像素 mask，输出也不是自动批准的骨骼。
+
+校验失败保存原始响应、validation 和报告，退出码为非零，不继续分割。网络/API 失败保存失败 manifest。拒绝、截断和不完整 Responses 都不会被当作成功。
+
+HTTP/SSE/网络失败还保存 `response.error.json`：状态码、请求 ID、耗时、尝试次数、响应体（最多 2 MB）或网络错误代码，密钥会脱敏。若服务端返回 overloaded，使用新目录稍后重跑；这不表示 schema 或分割模型出错。
+
+## 独立测试图片编辑接口
+
+先准备一个局部部件 PNG 和任务文本 `task.txt`，例如：
+
+```text
+The input canvas contains the screen-left forearm. Complete the hidden elbow
+connection behind the sleeve. Keep the visible hand and forearm in their exact
+positions. Preserve the original outline and shading. Do not add other parts.
+```
+
+调用 Qwen：
+
+```powershell
+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
+```
+
+改 `--completion-model` 即可对比另一个兼容的图片编辑模型。此命令直接调用图片接口并可能计费，不调用结构理解。
+
+结果保存 `candidate-1.png`（或服务端实际返回的 JPEG/WebP 扩展名）、输入图、任务提示词、原始响应和运行记录。PNG 输出会记录是否与输入画布同尺寸；尺寸相同不代表内容对齐。
+
+默认图片适配器只发送一张图。若中转站确认支持多图，在配置中启用 `capabilities.multiple_images`，并使用重复 `--image`：第一张是局部画布，其余是原图/标注图参考。字段名通过 `image_field` 选择 `image` 或 `image[]`。
+
+若确认支持编辑 mask，再启用 `capabilities.mask` 并使用 `--mask edit-mask.png`。当前适配器约定透明像素可编辑，要求 mask 与第一张图同尺寸、包含 alpha 通道。SAM 的普通黑白 mask 不能直接当作编辑 alpha mask。未启用能力时参数会明确报错，不静默忽略。
+
+本轮没有恢复原始可见像素，也没有生成隐藏区域的透明掩码；因此候选始终标记 `raw_completion_probe` 和 `needs_review`，不能直接接入最终 atlas。
+
+## 配置与切换规则
+
+`configs/astra-qwen.json` 分离 `providers` 和 `stages`：
+
+- provider：协议、base URL/key 的环境变量名、超时、重试次数、多图和 mask 声明。
+- stage：provider 名称、模型、提示词文件、输出模式和模型特定参数。
+- 提示词路径相对于配置 JSON 所在目录解析；命令行输入/输出路径相对于当前目录。
+- 模型优先级：CLI > 阶段显式 `model` > `model_env` 环境变量 > `default_model`。
+- shell 环境覆盖 `.env`。实验 JSON 不应存放密钥，仅引用密钥环境变量名。
+- 不同服务可配置各自的 base URL/key 环境变量。
+- 模型 ID 原样发送，不再把 `gpt-image-2.5` 映射成其他模型。
+- `params` 允许模型特定参数，但不能覆盖 model、prompt、messages、input 等适配器保留字段。
+- 新模式的超时/重试来自 provider 配置；旧模式的图片超时仍用 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`。
+
+例如把理解阶段改为固定模型：
+
+```json
+{
+  "provider": "relay-vision",
+  "model": "YOUR_EXACT_MODEL_ID",
+  "prompt": "../prompts/understand-v1.txt",
+  "output_mode": "text-json",
+  "params": {}
+}
+```
+
+## 重跑与对比
+
+同一命令增加 `--resume`，仅当上次完整结束，且模型、协议、参数、提示词、Schema、源图、适配器代码和所有产物校验一致时复用。模型变化时要求新的输出目录，防止覆盖对照组。失败任务也保留原目录，使用新目录重跑。
+
+本轮实现单阶段缓存；跨 SAM/补全/导出的依赖缓存留到后续阶段接入。对比补全模型时，固定相同局部画布、任务文本与掩码。
+
+显式 429/5xx 最多按配置重试，超时或网络断开不自动重试，因为服务端可能已经执行任务。完整请求不保证模型内容可复现；seed 只在提供方确认支持时放入 params，usage 不存在时记录 null，不估造价格或 token 数。
+
+## SAM 路径
+
+默认 `F:/Study/sam3.1`，检查 `sam3.1_multiplex.pt` 是否存在。该目录 README 明确说明它仅提供 checkpoint，不是可直接调用的推理服务。本轮仅记录路径和 checkpoint 存在性，状态为 `not_integrated`，不加载权重、不占用 GPU。
+
+## 测试
+
+```powershell
+npm test
+```
+
+测试使用本地 mock HTTP 服务或注入响应，不调用真实付费模型。覆盖模型优先级、协议请求/响应、multipart、能力限制、数值/引用/环校验、错误响应、重试、缓存和 CLI 全链路。
+
+2026-09-17 的集成检查：模型列表请求成功；Astra 要求 Responses + stream=true，切换后服务端返回 overloaded，尚未得到成功的真实角色标注。Qwen 适配器通过 mock 请求/响应测试，本轮未执行真实图片编辑生成。此状态不等于视觉质量已验证。