From 083d202fe491fd74e8cc6c1181c5b0b9f0899bcd Mon Sep 17 00:00:00 2001
From: cagedbird043 <cagedbird043@gmail.com>
Date: Wed, 25 Feb 2026 01:01:18 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=E8=B7=A8=E5=B9=B3?=
 =?UTF-8?q?=E5=8F=B0=E6=89=B9=E9=87=8F=E4=BF=AE=E6=94=B9=E5=AF=BC=E8=87=B4?=
 =?UTF-8?q?=E6=A8=A1=E5=9E=8B=E6=98=A0=E5=B0=84=E4=B8=A2=E5=A4=B1=E7=9A=84?=
 =?UTF-8?q?=E6=8E=92=E9=9A=9C=E7=BB=8F=E9=AA=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 DEV_GUIDE.md | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/DEV_GUIDE.md b/DEV_GUIDE.md
index 541bf1fa..d0d362e0 100644
--- a/DEV_GUIDE.md
+++ b/DEV_GUIDE.md
@@ -209,7 +209,30 @@ git add ent/       # 生成的文件也要提交
 
 ---
 
-### 坑 10：PR 提交前检查清单
+### 坑 10：前端测试看似正常，但后端调用失败（模型映射被批量误改）
+
+**典型现象**：
+- 前端按钮点测看起来正常；
+- 实际通过 API/客户端调用时返回 `Service temporarily unavailable` 或提示无可用账号；
+- 常见于 OpenAI 账号（例如 Codex 模型）在批量修改后突然不可用。
+
+**根因**：
+- OpenAI 账号编辑页默认不显式展示映射规则，容易让人误以为“没映射也没关系”；
+- 但在**批量修改同时选中不同平台账号**（OpenAI + Antigravity/Gemini）时，模型白名单/映射可能被跨平台策略覆盖；
+- 结果是 OpenAI 账号的关键模型映射丢失或被改坏，后端选不到可用账号。
+
+**修复方案（按优先级）**：
+1. **快速修复（推荐）**：在批量修改中补回正确的透传映射（例如 `gpt-5.3-codex -> gpt-5.3-codex-spark`）。
+2. **彻底重建**：删除并重新添加全部相关账号（最稳但成本高）。
+
+**关键经验**：
+- 如果某模型已被软件内置默认映射覆盖，通常不需要额外再加透传；
+- 但当上游模型更新快于本仓库默认映射时，**手动批量添加透传映射**是最简单、最低风险的临时兜底方案；
+- 批量操作前尽量按平台分组，不要混选不同平台账号。
+
+---
+
+### 坑 11：PR 提交前检查清单
 
 提交 PR 前务必本地验证：