Extend square-hole creation flow with visual asset timeout guard

docs/technical/SQUARE_HOLE_AGENT_LLM_TIMEOUT_GUARD_2026-05-05.md

@@ -0,0 +1,32 @@
+# 方洞挑战 Agent LLM 超时兜底修复 2026-05-05
+
+## 1. 问题
+
+现场错误：
+
+```text
+方洞挑战聊天生成失败，请稍后重试。：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:maincloud` 并确认 `/healthz`。