docs: 记录28-chatInput草稿恢复与AI请求content条件格式经验

工程分析/经验记录.md

@@ -588,3 +588,40 @@ ReportEditor 采用 `useRef` 作为自动保存的数据快照机制（避免 Re
   2. 若需要，是否已加入 `stateRef` 初始化？
   3. 若需要，是否已在 `saveDraftToStorage`、所有恢复分支、以及 state→ref 同步 effect 中补齐？
 - 建议维护一份 "Draft 持久化字段清单" 注释在 `stateRef` 定义附近，作为新增 state 时的检查单。
+
+
+---
+
+## 记录 28：chatInput 草稿恢复遗漏 + AI 请求 content 格式条件判断
+
+**A. 具体问题**
+1. AI 撰写面板的聊天输入框内容在路由切换后丢失——虽然 `chatMessages` 已修复，但 `chatInput`（用户正在输入但未发送的文本）未纳入 draft 恢复。
+2. Kimi 等纯文本模型在没有任何图片时，若将 `content` 以 vision 数组格式发送，会返回 `400 Bad Request`。
+
+**B. 产生问题原因**
+1. **遗漏模式**：此前修复 `chatMessages` 持久化时，只关注了已发送消息的恢复，忽略了输入框中未提交的 `chatInput` state。该 state 同样参与了 `stateRef` 同步和 `saveDraftToStorage` 保存，但所有 3 处草稿恢复分支均未恢复它。
+2. **模型格式差异**：OpenAI 兼容 API 中，vision 模型支持 `content: [{type:'image_url'...}, {type:'text'...}]`，但纯文本模型（如 Kimi 默认的 `kimi-k2-5`）要求 `content` 必须是 `string`。即使数组中只有 text 元素，也会触发 400。
+
+**C. 解决问题方案**
+1. **chatInput 恢复**：
+   - 在 `stateRef` 初始化和 `saveDraftToStorage` 中确认 `chatInput` 已存在（此前修改已完成）
+   - 在 3 处草稿恢复分支中增加：
+     ```ts
+     if (typeof draft.chatInput === 'string') setChatInput(draft.chatInput);
+     // 以及 stateRef.current 中增加 chatInput: draft.chatInput || ''
+     ```
+2. **content 条件格式**：
+   ```ts
+   let messageContent: any;
+   if (allImages.length > 0) {
+     messageContent = [];
+     allImages.forEach(url => messageContent.push({ type: 'image_url', image_url: { url } }));
+     messageContent.push({ type: 'text', text: promptText });
+   } else {
+     messageContent = promptText;
+   }
+   ```
+
+**D. 后续如何避免问题**
+- 新增任何 `useState` 时，除了问自己「是否已加入 stateRef / saveDraftToStorage / state→ref effect」，还必须**逐个审查所有 draft 恢复分支**，确认恢复逻辑完整。
+- 调用多模型兼容的 OpenAI 格式 API 时，必须根据「是否有图片附件」动态决定 `content` 的类型（`string` vs `array`），不能无条件发送数组。