[jamiesun]

根因

「小助手这次没想好，再试一次吧。」出现在两条互不相通的路径上，中间把原因丢掉了：

1. Worker 把上游的 429、超时、空回答、非 JSON 正文、网络失败都收成 upstream_failed（或未捕获异常）。errorResponse 还会把意外错误的 Error.message 原样返回，里面可能带上接口地址。
2. 浏览器 askGateway 只看 HTTP 状态：不是 401 / 403 / 503 就抛 GatewayError("failed")。noteApiProblem 于是固定显示 text.ai.failed。
3. 一轮的结果里其实有 outcome.message（解析失败、没有 main.py、素材复制被拒），但对话卡的 outcomeCopy 不读它，一律 text.pane.failed。
4. 讲解无论是断网、要登录还是解析失败，回答都写成同一句「没想好」。

所以孩子看不到超时、限额、断网、未登录和解析位置。控制台里的 console.warn 刷新就没了，也没有 requestId 能到 Cloudflare 日志里对上。

顺手修掉的高频原因

• 上游 fetch 没有超时。挂起会拖到平台杀掉 Worker，浏览器只看到一段非 JSON。现在 45 秒后返回分类 timeout。
• 429 和 Retry-After 与「模型没按 JSON 回答」长得一样。现在是 rate_limit，细节里只有状态码和秒数。
• 上游 200 但正文不是 JSON 时，response.json() 抛出的异常可能带上正文。现在是固定的 parse 细节。
• 部分兼容接口把 content 做成片段数组，旧代码当成空回答。现在会把文本片段拼起来。
• JSON.parse 的 SyntaxError 会引用模型原文（可能含孩子的代码或密钥样式的字符串）。解析失败只保留字符位置。
• 已经登录过、会话又丢了的时候，401 的分类句是「请登录后使用。」孩子本来看到的是「登录已经过期了，重新登录就好。」现在这句话还在，查看详情里仍是 sign_in 和 requestId。

新行为

• 每次 POST /api/ai 生成 gk_ 开头的 requestId（身份被拒也有）。失败返回 category、给孩子的一句话、可公开细节。旧的 code（sign_in_required、upstream_failed 等）还在。
• Worker 打一行 console JSON（source: "gamekit.ai"）：操作、耗时、状态、用量、失败分类。不记录邮箱、密钥、提示词、源码。
• 孩子仍看到一句人话，旁边有「查看详情」（分类、编号、时间、细节、复制给大人）。太忙、网络断了、请登录、登录过期，不再都叫「没想好」。
• 工作室「日志」：本机内存环 + IndexedDB（gamekit 版本 4 的 logs 表，最近 200 条）。可筛选、搜索、查看、复制、清空。不登录、不上传。

句子的唯一来源是 shared/assistant-error.ts。docs/ai-rules.md 和 docs/roadmap.md 的验收矩阵已补上这一行。

截图

上游返回 429 时，对话里是「小助手太忙了，稍后再试。」点开「查看详情」能看到分类 rate_limit、gk_ 编号、时间和 upstream HTTP 429。正文里没有密钥。

小助手太忙时展开查看详情

工具栏「日志」打开本机记录。同一条请求在「小助手」筛选里，带出错标记和同一句人话。

日志面板里的小助手出错记录

_{To show artifacts inline, enable in settings.}