1

docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md

@@ -80,6 +80,7 @@ VectorEngine 文档要求使用像素尺寸，不再使用 APIMart 的比例写
    - 拼图默认 `gpt-image-2` 前端值继续兼容，但上游请求模型统一映射到 `gpt-image-2-all`。
    - `nanobanana2` / `gemini-3.1-flash-image-preview` 不再走 APIMart；当前阶段统一回落到 VectorEngine GPT-image-2-all，避免保留旧图片网关。
    - 错误 `details.provider` 改为 `vector-engine`。
+   - 入口页上传图若用于首图生成，后端必须在生成成功后同步写入首关 `pictureReference`，保证结果页重新生成默认继续带同一张参考图。
 3. `.codex/skills/gpt-image-2-apimart/`
    - 目录名暂不强制迁移，避免本地插件索引漂移；Skill 文案与脚本行为改为 VectorEngine。
 
@@ -110,7 +111,18 @@ VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=180000
 2. 请求体 `model = gpt-image-2-all`，尺寸为 VectorEngine 支持的像素尺寸。
 3. 请求体不再包含 `official_fallback`。
 4. 参考图字段使用 `image`，不再使用 APIMart 的 `image_urls`。
-5. 缺少 `VECTOR_ENGINE_BASE_URL` 或 `VECTOR_ENGINE_API_KEY` 时返回 `503 SERVICE_UNAVAILABLE`，`details.provider = "vector-engine"`。
-6. 上游错误映射为 `502 UPSTREAM_ERROR`，保留 `upstreamStatus`、业务 message 和截断后的 raw excerpt。
-7. 运行 `npm run check:encoding`、`cargo test -p api-server openai_image --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server puzzle --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server custom_world_ai --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server character_visual --manifest-path server-rs/Cargo.toml`。
-8. 后端改动后使用 `npm run api-server` 重启，并确认 `/healthz`。
+5. 拼图入口页上传图生成首图后，返回的首关 `pictureReference` 保留该 Data URL；结果页重新生成在用户未重新上传参考图时会继续把 `pictureReference` 作为 `referenceImageSrc` 传给后端。
+6. 缺少 `VECTOR_ENGINE_BASE_URL` 或 `VECTOR_ENGINE_API_KEY` 时返回 `503 SERVICE_UNAVAILABLE`，`details.provider = "vector-engine"`。
+7. 上游错误映射为 `502 UPSTREAM_ERROR`，保留 `upstreamStatus`、业务 message 和截断后的 raw excerpt。
+8. 运行 `npm run check:encoding`、`cargo test -p api-server openai_image --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server puzzle --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server custom_world_ai --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server character_visual --manifest-path server-rs/Cargo.toml`。
+9. 后端改动后使用 `npm run api-server` 重启，并确认 `/healthz`。
+
+## 拼图链路排障日志
+
+拼图 `compile_puzzle_draft` 与 `generate_puzzle_images` 进入图片生成时，api-server 会输出分阶段耗时日志。排查“是谁慢”时按同一 `session_id` 串联：
+
+1. `拼图参考图解析完成` / `拼图参考图解析跳过`：确认前端是否传入参考图，以及 Data URL 解析或旧 `/generated-*` OSS 读取耗时；日志只记录 `reference_mime` 与 `reference_bytes`，不记录图片内容。
+2. `拼图 VectorEngine 图片生成 HTTP 返回`：VectorEngine `POST /v1/images/generations` 的同步上游耗时，若这一段长，慢点在 VectorEngine 生图接口。
+3. `拼图 VectorEngine 图片下载完成`：从 VectorEngine 返回的 `data[].url` 下载正式图耗时。
+4. `拼图生成图片已写入 OSS 与资产索引`：正式图上传 OSS、确认资产对象与实体绑定耗时。
+5. `拼图图片候选生成完成`：整段候选图生成总耗时。