Genarrative/docs/technical/SQUARE_HOLE_AGENT_LLM_TIMEOUT_GUARD_2026-05-05.md

方洞挑战 Agent LLM 超时兜底修复 2026-05-05

1. 问题

现场错误：

方洞挑战聊天生成失败，请稍后重试。：LLM 请求超时，累计尝试 1 次

方洞挑战创作 Agent 在同一轮流式 JSON 中需要返回 replyText、玩法配置、形状选项、洞口选项和图片提示词。模型可能先返回可见回复，再继续输出完整 JSON；如果上游在流式读取阶段超过通用 LLM 请求超时，后端会发送 SSE error，前端只能保留本地 warning 消息，本轮后端会话不会成功推进。

2. 根因

platform-llm 的 LlmTextRequest 只有全局 AppConfig.llm_request_timeout_ms。创作 Agent 统一走 Responses 流式协议，方洞提示词扩展为视觉资产配置后，单轮输出长度明显增加；通用 30 秒超时更适合普通聊天，不适合结构化创作 Agent 的完整 JSON 流。

request_text 的初始 HTTP 请求会按 max_retries 重试，但 stream_text 已经进入 response.chunk() 读取后，当前错误路径固定记录为一次读取超时，所以用户看到“累计尝试 1 次”。

3. 落地策略

1. 在 platform-llm::LlmTextRequest 增加请求级 request_timeout_ms 覆写。
2. execute_request 优先使用请求级超时，没有覆写时继续使用全局配置。
3. creation_agent_llm_turn 的流式 JSON 请求统一使用更长的创作 Agent 超时窗口。
4. 该超时窗口只影响创作 Agent 的结构化流式 turn，不改变 RPG 运行时聊天、图片生成、SpacetimeDB procedure 或方洞玩法判定。
5. 不新增 SpacetimeDB 表结构，不修改 migration.rs。

4. 验收标准

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 并确认 /healthz。

5. 追加：视觉资产动作 503 降级

现场后续日志：

status=503 method=POST uri=/api/creation/square-hole/sessions/{sessionId}/actions

该请求落在方洞 /actions，草稿编译成功后前端会自动追加执行 square_hole_generate_visual_assets。视觉资产生成依赖 VectorEngine GPT-image-2 图片入口；当本地或部署环境缺少 VECTOR_ENGINE_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，后端只重生成该洞口选项图；未传槽位的自动补齐需要同时补缺失的形状贴图和洞口选项图。