Extend square-hole creation flow with visual asset timeout guard

docs/prd/AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md

@@ -74,7 +74,8 @@
 8. 后端初始化单局形状队列、洞口兼容规则和计分状态。
 9. 玩家拖拽或点击形状投入洞口。
 10. 后端裁决投入结果、连击、扣时、失败、胜利和成绩。
-11. 前端只渲染后端快照与即时反馈，不承接正式规则真相。
+11. 形状贴图、封面图和背景图必须由后端图片生成接口生成或由创作者上传，前端只保存和展示 URL / data URL。
+12. 前端只渲染后端快照与即时反馈，不承接正式规则真相。
 
 ---
 
@@ -106,7 +107,23 @@ Agent 需要把玩家一句灵感收束为上述锚点，不允许逐项盘问
     "themeText": "",
     "twistRule": "",
     "shapeCount": 12,
-    "difficulty": 4
+    "difficulty": 4,
+    "shapeOptions": [
+      {
+        "shapeKind": "circle",
+        "label": "圆形",
+        "imagePrompt": "一个圆形办公室印章贴纸"
+      }
+    ],
+    "holeOptions": [
+      {
+        "holeId": "square-hole",
+        "holeKind": "square",
+        "label": "方洞",
+        "bonus": true
+      }
+    ],
+    "backgroundPrompt": "办公室纸箱玩具桌面背景"
   }
 }
 ```
@@ -119,6 +136,10 @@ Agent 需要把玩家一句灵感收束为上述锚点，不允许逐项盘问
 4. `quickFillRequested=true` 时，模型应直接补齐剩余配置，后端把 `progressPercent` 固定为 `100`。
 5. 模型不可用或结果无法解析时，接口返回明确错误，不允许用确定性模板伪装成 AI 回复。
 6. 非流式消息接口和 SSE 流式消息接口都必须走同一套方洞 Agent turn，SSE 只额外负责把 `replyText` 增量回传。
+7. `shapeOptions` 至少包含 `6` 个候选项；缺失时后端用当前题材生成默认候选项。
+8. `holeOptions` 至少包含 `3` 个选项，最多 `6` 个选项；创作者可以自定义 label、洞口类型与是否为加分选项。
+9. `bonus=true` 只表示“该选项被后端判定为正确时额外加 50 分”，不是公开提示；运行态 UI 不允许直接显示哪个选项是加分选项。
+10. `backgroundPrompt` 用于生成运行态背景图；为空时后端用题材和反差规则拼出默认提示词。
 
 ---
 
@@ -147,7 +168,30 @@ Agent 需要把玩家一句灵感收束为上述锚点，不允许逐项盘问
 
 其中 `square_hole_priority` 是参考视频核心反差的首选默认规则。
 
-## 6.3 前端表现
+## 6.3 计分规则
+
+首版计分由 `module-square-hole` 统一裁决：
+
+1. 正确投入基础得分：`100 + 当前连击数 * 10`。
+2. 如果本次投入的洞口是创作者配置的 `bonus=true` 选项，并且本次投入被判定为正确，额外加 `50` 分。
+3. 错误投入不扣分，但连击清零。
+4. 时间到、主动退出或本局结束不追加结算奖励。
+5. 前端只展示后端返回的 `score / combo / bestCombo`，不自行计算分数。
+
+## 6.4 图片资产规则
+
+1. 草稿生成后必须进入生成进度页，后端按草稿配置生成：
+   - 封面图 `coverImageSrc`
+   - 背景图 `backgroundImageSrc`
+   - 每个 `shapeOptions[].imageSrc`
+2. 创作者上传入口保留；上传图片可以覆盖生成图片。
+3. 图片生成失败时保留草稿和可编辑配置，结果页展示缺失槽位，允许创作者重试生成或上传替代图。
+4. 结果页必须展示每个形状选项及其图片、背景图、封面图和洞口选项配置。
+5. 运行态当前形状优先显示 `imageSrc`，没有图片时才回退到 CSS 形状。
+6. 运行态背景优先显示 `backgroundImageSrc`，没有图片时才回退到默认渐变。
+7. 运行态顶部不显示“方洞是唯一解”或等价真实规则提示；只保留时间、进度、分数和连击。
+
+## 6.5 前端表现
 
 1. 竖屏优先，桌面端居中显示游戏台。
 2. 当前形状位于屏幕下半区域，洞板位于上半区域。
@@ -207,10 +251,13 @@ Agent 需要把玩家一句灵感收束为上述锚点，不允许逐项盘问
 10. `coverImageSrc`
 11. `shapeCount`
 12. `difficulty`
-13. `publicationStatus`
-14. `playCount`
-15. `updatedAt`
-16. `publishedAt`
+13. `shapeOptions`
+14. `holeOptions`
+15. `backgroundImageSrc`
+16. `publicationStatus`
+17. `playCount`
+18. `updatedAt`
+19. `publishedAt`
 
 ## 8.3 运行态 run snapshot
 
@@ -228,9 +275,12 @@ Agent 需要把玩家一句灵感收束为上述锚点，不允许逐项盘问
 12. `bestCombo`
 13. `score`
 14. `ruleLabel`
-15. `currentShape`
-16. `holes`
-17. `lastFeedback`
+15. `backgroundImageSrc`
+16. `currentShape`
+17. `holes`
+18. `lastFeedback`
+
+运行态 `ruleLabel` 仅保留后端调试兼容字段，前端默认不展示。
 
 ---
 

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`。