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