落地方洞挑战图片与运行态交互

docs/technical/SQUARE_HOLE_AGENT_LLM_TIMEOUT_GUARD_2026-05-05.md

@@ -29,4 +29,56 @@
 1. `platform-llm` 测试覆盖请求级 timeout 会让慢响应提前超时。
 2. `creation_agent_llm_turn` 测试覆盖流式 JSON 请求带创作 Agent timeout。
 3. `cargo test -p platform-llm -p api-server creation_agent --manifest-path server-rs/Cargo.toml` 通过。
-4. 后端代码变更后按项目约束运行 `npm run api-server:maincloud` 并确认 `/healthz`。
+4. 后端代码变更后按项目约束运行 `npm run api-server` 并确认 `/healthz`。
+
+## 5. 追加：视觉资产动作 503 降级
+
+现场后续日志：
+
+```text
+status=503 method=POST uri=/api/creation/square-hole/sessions/{sessionId}/actions
+```
+
+该请求落在方洞 `/actions`，草稿编译成功后前端会自动追加执行 `square_hole_generate_visual_assets`。视觉资产生成依赖 APIMart OpenAI 兼容图片入口；当本地或部署环境缺少 `APIMART_API_KEY` 时，后端会在 `require_openai_image_settings()` 阶段快速返回 `503 SERVICE_UNAVAILABLE`，因此日志 latency 只有个位毫秒。
+
+这类错误只表示“图片自动生成服务不可用”，不代表方洞草稿编译失败。前端处理规则：
+
+1. `square_hole_compile_draft` 成功后，如果自动图片生成失败，保留错误横幅。
+2. 立即进入方洞结果页，展示已生成的形状/洞口配置。
+3. 保留封面图、背景图、形状贴图和洞口选项图上传入口。
+4. 进度页仍可通过“重新生成图片”在配置补齐后重试。
+
+## 6. 追加：结果页图片重生成入口
+
+方洞结果页需要保留用户上传入口，同时提供 `AI重生成图片` 操作。该按钮先保存当前编辑内容，再复用 `/api/creation/square-hole/sessions/{sessionId}/actions` 的 `square_hole_generate_visual_assets` 动作，并额外传入 `regenerateVisualAssets=true`。
+
+后端收到该标记后，不再按已有 `coverImageSrc`、`backgroundImageSrc` 或形状 `imageSrc` 跳过图片生成，而是重新生成封面图、背景图和所有形状贴图。自动编译后的图片补齐流程仍保持默认 `false`，只补缺失图片，避免覆盖创作者刚上传的素材。
+
+## 7. 追加：图片槽位查看模式与历史素材
+
+方洞结果页的封面图、背景图、每个形状贴图和每个洞口选项图不再把上传入口直接散落在卡片上。点击任一图片槽位后打开独立查看面板，面板内负责：
+
+1. 展示当前槽位图片。
+2. 展示当前账号历史生成的方洞图片素材。
+3. 提供本地上传入口，上传后只替换当前槽位。
+4. 提供 `AI生成图片` 入口，触发 `square_hole_generate_visual_assets` 并带 `regenerateVisualAssets=true`、`visualAssetSlot` 与可选 `visualAssetOptionId`。
+5. 后端按槽位定向生成：封面面板只替换封面图，背景面板只替换背景图，形状贴图面板只替换当前形状选项的贴图，洞口选项图面板只替换当前洞口选项图。草稿编译后的自动图片补齐仍不传槽位，保持“只补缺失图片”的原逻辑。
+
+历史素材来源必须是真实资产索引，不允许只从前端当前草稿拼假列表。方洞图片生成成功后，API 层需要像拼图封面一样写入 OSS 与 `asset_object`：
+
+1. 封面图使用 `asset_kind = square_hole_cover_image`。
+2. 背景图使用 `asset_kind = square_hole_background_image`。
+3. 形状贴图使用 `asset_kind = square_hole_shape_image`。
+4. 洞口选项图使用 `asset_kind = square_hole_hole_image`。
+5. 资产历史接口 `/api/assets/history` 与 SpacetimeDB 侧历史素材白名单同步放行这四类。
+6. 如果 OSS 或 SpacetimeDB 资产索引不可用，本次生成仍允许以 Data URL 回写作品，历史素材列表只降级为空或缺少本次记录。
+
+## 8. 追加：选项图片不再局限于形状
+
+方洞挑战的可展示图片不再只挂在 `shapeOptions`。创作者配置中的 `holeOptions` 也需要具备：
+
+1. `imagePrompt`：洞口选项图的生成提示词，默认由题材主题和洞口标签补齐。
+2. `imageSrc`：洞口选项图地址，可来自 AI 生成、历史素材套用或本地上传 Data URL。
+3. 结果页需要把洞口选项图做成与形状贴图相同的图片槽位，打开查看面板后支持历史、上传和 AI 生成。
+4. 运行态洞口按钮优先展示 `hole.imageSrc`，没有图片时再回落到几何剪影。
+5. `visualAssetSlot = hole` 时必须携带 `visualAssetOptionId = holeId`，后端只重生成该洞口选项图；未传槽位的自动补齐需要同时补缺失的形状贴图和洞口选项图。