EPEEAIKit/.cursor/changelog/changelog-recent.md

Dev Changelog — Recent

最近 ~10 次改动的摘要记录，按时间倒序排列。 当 Agent 检测到当前任务与近期改动相关时自动读取。

[CL-20260416-0830] 2026-04-16 — 生图按模型预处理 prompt

• tags: 后端, 生图, prompt, SDXL, Flux, Replicate, image_gen, Agent工具
• affected_files: image_prompt_strategy.py, image_gen.py, tools.py
• summary: 新增 image_prompt_strategy：按注册表 id 为 7 个生图模型应用策略（OpenAI/Gemini 自然语言规范化；BFL Flux 指南对齐、剥 SD 式 Negative 段；SDXL 默认负向词 + ---NEGATIVE---/|||NEG||| 拆分；IP-Adapter 侧重内容描述）。generate_images 统一调用后下发；Replicate 非 Flux 路径写入 negative_prompt。GenerateResult 增加 effective_prompt/negative_prompt；工具返回与描述补充 SDXL 分隔符约定。

[CL-20260416-0810] 2026-04-16 — 对话栏粘贴剪贴板图片为参考图

• tags: 前端, ChatInput, 剪贴板, 参考图, UX
• affected_files: chat-input.tsx
• summary: 在 ChatInput 根容器上使用 onPasteCapture：从 clipboardData.items 收集 kind===file 且 image/* 的项，调用 getAsFile 后复用现有 startUpload。无图片文件时不拦截，纯文本粘贴照常。placeholder 与 textarea title 提示可粘贴图片。

[CL-20260416-0745] 2026-04-16 — Gemini 原生生图：超时与断连重试

• tags: 后端, Gemini, httpx, 超时, 重试, 向量引擎, image_gen
• affected_files: image_gen.py, .env.example
• summary: 用户遇到 Server disconnected without sending a response（httpx RemoteProtocolError 等）。将 Gemini generateContent 默认 read 超时提高到 600s、write 180s、connect/pool 60s；对 RemoteProtocolError/ConnectError/ReadTimeout 等可恢复错误默认最多重试 3 次（指数退避 1s/2s）；失败时错误信息附带调优提示。可通过 VECTORENGINE_GEMINI_* 环境变量覆盖。

[CL-20260416-0720] 2026-04-16 — 修复拖拽参考图到 ChatInput 区域后覆盖层卡住不消失

• tags: bug修复, 拖拽, 覆盖层, ChatInput, stopPropagation, UX
• affected_files: chat-input.tsx, page.tsx
• summary: 文件拖拽到 ChatInput 区域时，ChatInput.handleDrop 的 stopPropagation 阻止事件冒泡到 main.onDrop，导致 mainDragging 状态无法重置为 false，拖拽覆盖层（"松开以添加参考图"）卡住不消失。修复：ChatInput 新增 onFileDrop 回调 prop，在 handleDrop 中调用，page.tsx 传入回调重置 dragCounter 和 mainDragging。

[CL-20260416-0700] 2026-04-16 — 新增 GeminiNativeImageProvider：Gemini 原生 generateContent 接口对接

• tags: 后端, Gemini, Provider, 原生API, generateContent, 多图参考, 架构
• affected_files: image_gen.py, config.py
• summary: 新增 GeminiNativeImageProvider，通过向量引擎中转调用 Gemini 原生 /v1beta/models/{model}:generateContent 接口（非 OpenAI 兼容的 images/edit）。支持文字+图片混合输入（最多 14 张参考图），图片以 inline_data base64 内联传入。新增 _resolve_image_base64 工具函数统一处理 data URI 和本地路径到 (mime, b64) 的解析。config.py 中 Gemini 模型改用 gemini_native provider 并恢复 supports_ref_image: True。Provider 注册表新增 gemini_native 条目。

[CL-20260416-0620] 2026-04-16 — 修复拖拽上传重复 + Gemini 改回不支持参考图 + images.edit 参数修正

• tags: bug修复, 拖拽, Gemini, 向量引擎, images.edit, config
• affected_files: chat-input.tsx, config.py, image_gen.py
• summary: 三个问题修复：(1) 拖拽到 ChatInput 区域时事件冒泡导致 page.tsx 和 ChatInput 各触发一次上传 → ChatInput handleDrop/handleDragOver 加 stopPropagation；(2) 向量引擎 Gemini 图片编辑走原生 generateContent 接口而非 OpenAI 兼容 images/edits，对 Gemini 调用 images.edit 返回 500 → Gemini 改回 supports_ref_image=False；(3) images.edit 端点不支持 quality 参数 → 从 _edit_with_refs 中移除。

[CL-20260416-0600] 2026-04-16 — 多张参考图全链路支持

• tags: 前端, 后端, 参考图, 多图, OpenAI, images.edit, Provider, API, Agent Loop
• affected_files: chat-input.tsx, page.tsx, chat-messages.tsx, api.ts, types.ts, chat.py, loop.py, tools.py, image_gen.py, config.py
• summary: 从单张参考图扩展为多张参考图全链路支持。前端：ChatInput 改为多图状态数组+file input multiple+多图预览/删除/拖拽；API层 sendChat 改为 ref_image_urls: string[]；消息气泡和沿用逻辑适配多图。后端：chat.py 新增 ref_image_urls JSON 数组参数（兼容旧 ref_image_url）；Agent Loop 多图注入 vision LLM 上下文；OpenAIImageProvider 有参考图时改用 images.edit 端点（支持最多16张）；Replicate 取首张兼容；GPT Image 1.5 和 Gemini 注册表标记 supports_ref_image=True。

[CL-20260416-0510] 2026-04-16 — 生图模型新增 Gemini 3.1 Flash Image

• tags: 后端, 生图模型, Gemini, 向量引擎, config
• affected_files: config.py, .env
• summary: IMAGE_MODELS 注册表新增 gemini-3.1-flash-image（model_id: gemini-3.1-flash-image-preview），provider 为 openai，复用 OpenAIImageProvider 走向量引擎中转。无需新增 Provider 代码。

[CL-20260416-0500] 2026-04-16 — 全区域拖拽添加参考图

• tags: 前端, UX, 拖拽, 参考图, 上传
• affected_files: page.tsx, chat-input.tsx
• summary: 拖拽上传参考图区域从底部输入栏扩展到整个对话区域。ChatInput 改为 forwardRef 暴露 uploadFile 方法，main 区域处理拖放事件并调用。拖入时显示全屏覆盖层提示，用 dragCounter 防止子元素冒泡导致闪烁。

[CL-20260416-0430] 2026-04-16 — 接入 GPT Image 1.5 生图模型（向量引擎中转）

• tags: 后端, 生图模型, GPT-Image, OpenAI, 向量引擎, provider
• affected_files: image_gen.py, config.py, .env
• summary: 新增 OpenAIImageProvider，通过向量引擎 API 中转调用 /v1/images/generations 端点。IMAGE_MODELS 注册表新增 gpt-image-1.5（provider: openai），支持 size/quality 参数和 URL/base64 双格式返回。

[CL-20260416-0400] 2026-04-16 — Session 级参考图自动沿用 + 缺参考图前置校验

• tags: 前端, 后端, 参考图, UX, InstantStyle, 风格迁移
• affected_files: page.tsx, chat-input.tsx, image_gen.py
• summary: 用户发送带参考图的消息后，前端在 session 级别记住该参考图 URL，后续消息自动沿用（输入框显示"沿用上次参考图"提示条，可清除）。解决切换 InstantStyle 后无参考图导致 "No input, Save money" 的问题。后端对需要参考图但未收到的模型统一返回友好错误。

[CL-20260416-0300] 2026-04-16 — System Prompt 禁止 LLM 嵌入图片链接

• tags: 后端, agent-loop, system-prompt, LLM行为约束
• affected_files: loop.py
• summary: LLM（GPT 系列）在收到 generate_image 工具返回的本地路径后，自行拼凑 sandbox:/generated/xxx.png Markdown 图片链接。前端图片展示由 image_result SSE 事件独立处理，文字中的链接无效且多余。在 System Prompt 注意事项中新增禁止嵌入图片 Markdown 的约束。

[CL-20260416-0245] 2026-04-16 — 修复三点菜单 z-index 层级问题

• tags: 前端, UI, sidebar, 菜单, z-index
• affected_files: session-list.tsx
• summary: 三点菜单原用 fixed 定位在侧栏右侧弹出，被主内容区遮挡。改为 inline 在会话项正下方展开，模型子菜单改为折叠式内联列表（带 max-h 滚动），全部在侧栏内部完成，不再溢出。移除了 menuPos 状态和 fixed 定位逻辑。

[CL-20260416-0230] 2026-04-16 — LLM 注册表扩充 + 默认模型改 GPT-5.4

• tags: 后端, config, LLM, 模型注册表
• affected_files: config.py, .env
• summary: LLM_MODELS 从 3→7 个：新增 gpt-5.4、claude-sonnet-4-6、claude-opus-4-6、gemini-3.1-pro-preview、glm-4.7，全部走 vectorengine provider。默认模型从 gpt-4o-mini 改为 gpt-5.4。gpt-4o-mini/deepseek-chat 保留。

[CL-20260416-0200] 2026-04-16 — 接入向量引擎中转 API + 对话级 LLM 模型切换

• tags: 后端, 前端, LLM, 向量引擎, 中转API, 模型切换, config, UI, session
• affected_files: config.py, loop.py, chat.py, .env, types.ts, api.ts, app-context.tsx, session-list.tsx, page.tsx
• summary: 新增 LLM_MODELS 注册表（gpt-4o-mini/gpt-4o/deepseek-chat），provider 分发为 vectorengine（中转）和 deepseek（直连）。loop.py 改为按 provider 创建 AsyncOpenAI 客户端，vision 检测从注册表读取。chat.py 新增 llm_model 参数和 GET /api/llm-models 端点。前端 Session 新增 llmModel 字段，侧栏三点菜单支持模型选择子菜单，sendChat 传递 llm_model。

[CL-20260416-0030] 2026-04-16 — 青绿山水风格改造：千里江山图色调 + 云烟雾气动效

• tags: 前端, UI改造, 视觉风格, 青绿山水, 千里江山图, CSS动画, 色彩体系, 云烟
• affected_files: globals.css, top-nav.tsx, sidebar.tsx, session-list.tsx, chat-messages.tsx, chat-input.tsx, image-grid.tsx, image-detail-panel.tsx, profile-modal.tsx, page.tsx, gallery/page.tsx, login/page.tsx, VISUAL-STYLE-GUIDE.md
• summary: 全站从 Cyberpunk 霓虹改为青绿山水风格。色彩替换为石青绿(#4DB8A4)/石绿蓝(#3A8FB7)/墨绿底色(#0C1210)。背景改为双层漂移云雾(60s+45s)。.glow-border hover 效果柔化为云烟缭绕(6s/宽弧段/blur 12px)。.glass-panel 加绿底渐变+增强模糊。新增 .fog-scroll 雾气滚动边缘。11 个组件硬编码颜色全部替换。VISUAL-STYLE-GUIDE.md 完全重写。

[CL-20260415-2330] 2026-04-15 — 用户个人信息 + 记忆查看面板：右上角菜单弹窗

• tags: 前端, 后端, 用户信息, 记忆系统, Mem0, Modal, ProfileModal
• affected_files: api/memory.py, main.py, profile-modal.tsx, top-nav.tsx
• summary: 后端新建 GET /api/memory/list 端点（Mem0 get_all + run_in_executor），前端新建 ProfileModal 组件（glass-panel 风格居中弹窗），展示用户信息 + 按时间分组的记忆列表（只读）。TopNav 的 username 行改为可点击按钮，点击打开弹窗。

[CL-20260415-2230] 2026-04-15 — 光影流动边框效果：导航活动项 + 活动会话项

• tags: 前端, CSS动画, 视觉效果, conic-gradient, 霓虹边框
• affected_files: globals.css, top-nav.tsx, session-list.tsx, sidebar.tsx
• summary: 用 @property + conic-gradient 实现旋转光影边框效果。双伪元素方案：::before 做渐变边框（mask-composite 裁内部），::after 做模糊扩散光晕。提供 .glow-border（动画）和 .glow-border-static（hover 静态发光）两个类，分别应用到导航活动 Tab 和活动会话项。

[CL-20260415-2200] 2026-04-15 — 全站 UI 风格改造：Cyberpunk Dark Neon 主题

• tags: 前端, UI改造, 视觉风格, Cyberpunk, Neon, 毛玻璃, 全局样式
• affected_files: globals.css, page.tsx, gallery/page.tsx, login/page.tsx, top-nav.tsx, sidebar.tsx, session-list.tsx, tag-filter.tsx, chat-messages.tsx, chat-input.tsx, image-grid.tsx, model-selector.tsx, image-detail-panel.tsx, VISUAL-STYLE-GUIDE.md
• summary: 参考 SolCasino Dribbble 设计，全站从朴素暗色改为 Cyberpunk Dark Neon 风格。主色从紫色改为青绿霓虹(#00E5A0)，新增环境光晕背景、毛玻璃面板(backdrop-blur)、霓虹发光边框。所有组件统一升级圆角和过渡效果，图片卡片加 hover 缩放+发光。同时编写了完整的视觉风格文档。

[CL-20260414-2350] 2026-04-14 — 修复登录后 useApp must be used within AppProvider 报错

• tags: bug修复, 前端, 认证, AppProvider, 初始化时序
• affected_files: app-context.tsx
• summary: AppProvider 在 !initialized 时不提供 context 但渲染了需要 useApp() 的子组件。修复：已认证但未初始化时显示加载状态，未认证时才渲染裸 children（/login）。

[CL-20260414-2340] 2026-04-14 — 用 pwdlib (Argon2id) 替换 passlib (bcrypt)，彻底解决兼容性问题

• tags: 重构, 安全, 密码哈希, Argon2, pwdlib, passlib, 依赖升级
• affected_files: auth.py, requirements.txt, docs/art-agent/USER-SYSTEM.md
• summary: passlib 已停止维护且与 bcrypt 5.x 不兼容。替换为 pwdlib[argon2,bcrypt]，新密码用 Argon2id，旧 bcrypt 哈希仍可验证。不再需要锁定 bcrypt 版本。

[CL-20260414-2330] 2026-04-14 — 修复 passlib + bcrypt 5.x 兼容性问题，锁定 bcrypt<4.1

• tags: bug修复, 依赖, bcrypt, passlib, 用户系统
• affected_files: requirements.txt, docs/art-agent/USER-SYSTEM.md
• summary: passlib 1.7.4 与 bcrypt 5.0.0 不兼容（__about__ 移除 + 密码长度 ValueError），后端启动报错。降级 bcrypt 到 4.0.1 并在 requirements.txt 中锁定 >=4.0.1,<4.1。同时在用户系统文档故障排除中补充此问题。

[CL-20260414-2300] 2026-04-14 — 用户系统：管理员邀请制 + JWT 认证 + 数据按用户隔离

• tags: 用户系统, 认证, JWT, SQLite, 数据隔离, 多用户, 安全
• affected_files: db.py, auth.py, api/auth.py, api/admin.py, chat.py, main.py, loop.py, auth-context.tsx, auth-guard.tsx, api.ts, store.ts, app-context.tsx, layout.tsx, login/page.tsx, top-nav.tsx, model-selector.tsx, requirements.txt, .env.example
• summary: 后端新增 SQLite 用户表 + JWT 认证（access+refresh）+ 管理员/普通用户路由，所有 API 加鉴权，Mem0 user_id 改为真实用户 ID。前端新增登录页 + AuthProvider/AuthGuard + 401 自动跳转 + localStorage 按用户 ID 隔离。TopNav 新增用户菜单。首次启动自动创建 admin。

[CL-20260414-2230] 2026-04-14 — 对话区域新增"回到底部"浮动按钮

• tags: 前端, UX, 滚动, 浮动按钮
• affected_files: art-agent/frontend/src/app/page.tsx
• summary: 长对话中不在底部时，右下角显示向下箭头按钮，点击平滑滚到最新消息。复用 scroll 监听器检测距底部距离（>200px 显示），切换会话后也同步按钮状态。

[CL-20260414-2220] 2026-04-14 — 修复长对话切换回来滚动位置上移：scroll 事件实时保存取代 effect 延迟保存

• tags: 前端, bug修复, 滚动, 多会话, UX, scroll 事件
• affected_files: art-agent/frontend/src/app/page.tsx
• summary: effect 中保存 scrollTop 时 DOM 已变为短对话内容，浏览器 clamp scrollTop 导致保存值偏小。改用 scroll 事件实时记录位置，确保在任何 DOM 变更之前数据已正确保存。

[CL-20260414-2210] 2026-04-14 — 修复会话切换时滚动位置跳动：时序竞争 + 抑制切换期间 smooth scroll

• tags: 前端, bug修复, 滚动, 多会话, UX, 时序
• affected_files: art-agent/frontend/src/app/page.tsx
• summary: CL-20260414-2200 的 rAF 恢复时序不可靠——React 可能还没渲染新会话内容，scrollHeight 是旧值。拆为两个 effect（保存+标记 / 等 messages 更新后恢复），新增 isSwitching 抑制切换期间的 smooth scroll 干扰，instant 模式改为同步赋值 scrollTop。

[CL-20260414-2200] 2026-04-14 — 修复多会话滚动位置共享 bug：per-session 独立记录 + 切换恢复

• tags: 前端, bug修复, 滚动, 多会话, UX
• affected_files: art-agent/frontend/src/app/page.tsx
• summary: 所有会话共用同一 scrollRef，切换时不保存/恢复 scrollTop。修复：新增 scrollPositions Map 按 sessionId 记录滚动位置，useEffect 监听 activeSessionId 变化时保存旧位置、恢复新位置（有记录则恢复，无记录则 scrollToBottom）。scrollToBottom 改为 useCallback + 支持 instant 模式。

[CL-20260413-2320] 2026-04-13 — 集成 Mem0 记忆系统：滑动窗口 + 跨会话长期记忆

• tags: Mem0, 记忆系统, 上下文管理, 长期记忆, Ollama, embedding, 滑动窗口
• affected_files: app/memory.py, app/agent/loop.py, app/config.py, app/api/chat.py, requirements.txt, .env, frontend/src/lib/api.ts, frontend/src/app/page.tsx
• summary: 集成 Mem0 OSS 作为统一记忆方案。DeepSeek 做事实提取，Ollama nomic-embed-text 做本地 embedding，Qdrant 文件模式做向量存储。agent loop 新增滑动窗口（MAX_RECENT_TURNS=20）、记忆检索注入 system prompt、异步事实存储。前端传递 session_id 实现会话级记忆作用域。不做静默降级，所有错误显式报告。

[CL-20260413-1130] 2026-04-13 — 修复 SDXL 模型 404 错误：补全 Replicate 版本 hash

• tags: bug修复, Replicate, SDXL, 模型配置, 404
• affected_files: art-agent/backend/app/config.py
• summary: SDXL 调用 Replicate 404，根因同 Kolors（CL-20260413-0440）：非 Flux 官方模型需要 owner/model:version_hash 完整格式。将 stability-ai/sdxl 补全为 stability-ai/sdxl:39ed52f2...e08b。

[CL-20260413-1100] 2026-04-13 — 修复切换模型后 LLM 仍声称使用旧模型名

• tags: Agent Loop, system prompt, 模型选择, LLM 幻觉
• affected_files: art-agent/backend/app/agent/loop.py
• summary: System Prompt 不含模型信息，LLM 从对话历史幻觉旧模型名。修复：在 system prompt 末尾动态注入当前模型名 + 强调忽略历史中的旧记录，假生成重试消息也附带模型名。debug 日志验证传递链路正确，问题仅在 LLM 文字层。

[CL-20260413-1030] 2026-04-13 — Agent Loop 假生成检测 + 自动重试机制

• tags: Agent Loop, DeepSeek, function calling, 防幻觉, 自动修复
• affected_files: art-agent/backend/app/agent/loop.py
• summary: DeepSeek 无视 prompt 约束，仍用文字模拟生图。新增代码层面检测：LLM 纯文字回复中命中"已生成"等关键词 >= 2 次时，自动注入纠正消息强制重试调用工具。重试消耗一次迭代配额。

[CL-20260413-1000] 2026-04-13 — 助手消息气泡添加复制文本按钮

• tags: 前端, UX, chat-messages, 复制
• affected_files: art-agent/frontend/src/components/chat/chat-messages.tsx
• summary: 助手回复气泡下方新增复制文本按钮（hover 显示），点击通过 clipboard API 复制文本并显示 1.5s 对勾反馈。只对 assistant 消息展示。

[CL-20260413-0930] 2026-04-13 — System Prompt 加入"禁止模拟工具调用"约束

• tags: prompt 工程, system prompt, DeepSeek, function calling, 防幻觉
• affected_files: art-agent/backend/app/agent/loop.py
• summary: DeepSeek 在多步生图任务中有时不调用工具而是用文字模拟"已生成"，导致前端收不到图片。在 System Prompt 注意事项中加入硬性约束："生成图片必须调用 generate_image 工具，禁止用文字模拟"。

[CL-20260413-0900] 2026-04-13 — 非 vision + 参考图场景：尊重用户主动指定的风格意图

• tags: prompt 工程, IP-Adapter, 风格, system prompt, UX
• affected_files: art-agent/backend/app/agent/loop.py
• summary: SYSTEM_PROMPT 和非 vision hint 中对风格关键词的禁止从"绝对禁止"改为"不自行猜测，但用户明确指定则保留到 prompt 中"。之前的绝对性措辞导致 LLM 即使用户主动写了"赛博朋克风"也会丢弃。修正后 IP-Adapter 风格迁移与用户文字风格可叠加。

[CL-20260413-0800] 2026-04-13 — 修复 InstantStyle ReadTimeout + 多次生成丢失参考图

• tags: bug修复, Replicate, InstantStyle, timeout, 参考图, Agent Loop, wait
• affected_files: art-agent/backend/app/services/image_gen.py, art-agent/backend/app/agent/loop.py
• summary: 运行时日志证实两个问题：(1) wait=60 时 SDK 内部 read=60.5s timeout 覆盖客户端 300s timeout，上传 1.6MB base64 + 等待初始响应超过 60s → ReadTimeout。改为 wait=False，create 请求立即返回 prediction ID，SDK 自动走 prediction.async_wait() 轮询，轮询用客户端级 read=300s timeout。(2) 成功生成后清除 ref_image_url 导致后续工具调用丢失参考图（InstantStyle 返回 "No input, Save money"）。完全移除清除逻辑，ref_image_url 在整个对话期间保持有效。

[CL-20260413-0730] 2026-04-13 — 修复生图失败后 LLM 重试丢失参考图

• tags: bug修复, Agent Loop, 参考图, InstantStyle, ref_image_url
• affected_files: art-agent/backend/app/agent/loop.py
• summary: LLM 第一次生图工具调用失败后重试时，参考图丢失。InstantStyle 返回 "No input, Save money"。根因：loop.py 在每轮工具调用结束后无条件清除 ref_image_url。修复：改为只在本轮至少有一次成功产出图片时才清除，失败时保留参考图供 LLM 重试。

[CL-20260413-0700] 2026-04-13 — 修复 InstantStyle 生图 422 + ReadTimeout：wait 参数超限

• tags: bug修复, Replicate, InstantStyle, API参数, async_run, timeout
• affected_files: art-agent/backend/app/services/image_gen.py
• summary: InstantStyle 生图 422（Prefer: wait=x must be 1-60）+ ReadTimeout（61.4s）。两个问题同根因：async_run(wait=300) 超出 API 限制，改为 wait=True 后 SDK 内部 60.5s timeout 覆盖了客户端 300s timeout。最终改为 wait=60（API 最大合法值），初始请求 60s 内未完成则 SDK 自动 fallback 到异步轮询，轮询用客户端级 read=300s timeout。

[CL-20260413-0630] 2026-04-13 — 修复 Replicate SDK 不走代理 + 超时不够

• tags: bug修复, Replicate, InstantStyle, 代理, httpx, 超时
• affected_files: art-agent/backend/app/services/image_gen.py
• summary: Replicate SDK 内部显式传 transport 给 httpx，绕过了环境变量代理配置导致 ConnectTimeout，且默认 read 30s 不够 InstantStyle 的 ~128s。修复：_make_replicate_client() 工厂函数从 HTTPS_PROXY 读取代理注入 AsyncHTTPTransport(proxy=...)，read 300s / connect 30s。_download_image 同步加了代理。

[CL-20260413-0600] 2026-04-13 — 新增 InstantStyle 模型：强风格迁移选项

• tags: 模型注册, InstantStyle, 风格迁移, IP-Adapter
• affected_files: art-agent/backend/app/config.py
• summary: 注册 InstantStyle（jyoung105/instant-style）到模型注册表，block_mode: "style-only" + style_strength: 1.0，通过 ref_image_param: "style_image" 适配现有抽象。与 Kolors 并列为参考图模型，提供强风格迁移能力。

[CL-20260413-0540] 2026-04-13 — 非 vision LLM + 参考图时禁止猜测风格

• tags: prompt 工程, IP-Adapter, 风格一致性, system prompt
• affected_files: art-agent/backend/app/agent/loop.py
• summary: 修改 system prompt 和非 vision 模型的参考图提示，明确禁止猜测画风。LLM 只描述画面内容，风格交给 IP-Adapter 从参考图提取。解决了 DeepSeek 看不到参考图时脑补 "pixel art" 导致生成结果与参考图风格不一致的问题。

[CL-20260413-0520] 2026-04-13 — 多图生成改为单次 API 调用 + 修复空错误信息

• tags: 性能优化, Replicate, 速率限制, 错误处理, 模型配置
• affected_files: art-agent/backend/app/services/image_gen.py, art-agent/backend/app/config.py
• summary: 多图生成从 for 循环改为单次 API 调用（新增 num_images_param 配置），避免低余额账户的速率限制。同时修复空异常时 [生成失败: ] 信息丢失的问题，改为显示异常类型名和 repr。

[CL-20260413-0500] 2026-04-13 — 生成图片后显示使用的模型名称

• tags: 模型溯源, SSE, 图片生成, 前端展示
• affected_files: art-agent/backend/app/services/image_gen.py, art-agent/backend/app/agent/tools.py, art-agent/backend/app/agent/loop.py, art-agent/frontend/src/lib/types.ts, art-agent/frontend/src/app/page.tsx, art-agent/frontend/src/components/chat/chat-messages.tsx
• summary: generate_images 返回 GenerateResult（含 model_name），SSE 事件携带模型名称，前端在图片下方和错误提示中展示。ChatMessage 新增 modelName 字段，归档后仍可溯源。

[CL-20260413-0440] 2026-04-13 — 修复 Kolors IP-Adapter 模型 404 错误：补全 Replicate 版本 hash

• tags: bug修复, Replicate, Kolors, IP-Adapter, 模型配置
• affected_files: art-agent/backend/app/config.py
• summary: Kolors IP-Adapter 生图 404 的根因是 Replicate SDK 对社区模型需要 owner/model:version_hash 格式。在 config.py 中补全 kolors-ipadapter 的版本 hash 后，实测生图成功。

[CL-20260413-0430] 2026-04-13 — 图片生成失败时将具体错误信息透传到前端

• tags: 错误处理, Agent Loop, SSE, 调试体验
• affected_files: art-agent/backend/app/agent/loop.py, art-agent/frontend/src/app/page.tsx, art-agent/frontend/src/lib/api.ts
• summary: 新增 tool_error SSE 事件类型。Agent Loop 在工具执行产生错误时，额外 yield 一个 tool_error 事件携带具体报错信息；前端处理该事件并以 ⚠️ 前缀展示在对话流中。解决了之前工具失败时用户只能看到 LLM 模糊翻译、无法获取真实错误详情的问题。

[CL-20260413-0330] 2026-04-13 — README 补充访问地址汇总 + 穿透管理文档

• tags: 文档, README, 穿透, Cloudflare, cloudflared
• affected_files: art-agent/README.md
• summary: README 新增"访问地址"章节（本机/局域网/外网三种场景表格），重写"远程访问（外网穿透）"章节，补充 cloudflared 安装指引（winget + 手动下载）、穿透管理操作表（启动/停止/查看状态/重启）、代理配置排错说明。

[CL-20260412-2345] 2026-04-12 — 参考图上传独立化：进度条 + 状态反馈 + 失败重试

• tags: 前端, 后端, 参考图, 上传, UX, 进度反馈
• affected_files: art-agent/backend/app/api/chat.py, art-agent/frontend/src/lib/api.ts, art-agent/frontend/src/components/chat/chat-input.tsx, art-agent/frontend/src/app/page.tsx
• summary: 参考图从"随消息提交"改为"选中即独立上传"。后端新增 POST /api/upload-ref-image 端点；前端用 XMLHttpRequest 获取上传进度事件，ChatInput 显示环形进度条、成功/失败角标、失败可重选。sendChat 参数从 File 改为服务端路径。同时修复 file input 多次上传不重置的问题。

[CL-20260412-2315] 2026-04-12 — 修复 Cloudflare Tunnel 跨域开发警告

• tags: 前端, 配置, Next.js, Cloudflare, 跨域
• affected_files: art-agent/frontend/next.config.ts
• summary: Next.js 检测到来自 trycloudflare.com 的跨域请求发出警告。在 next.config.ts 中添加 allowedDevOrigins: ["*.trycloudflare.com"] 消除警告，通配符覆盖所有 Quick Tunnel 随机域名。

[CL-20260412-2300] 2026-04-12 — 集成 Kolors IP-Adapter，参考图可直接用于风格生成

• tags: 后端, 前端, IP-Adapter, 风格迁移, 参考图, 模型注册, Replicate, 架构
• affected_files: art-agent/backend/app/config.py, art-agent/backend/app/services/image_gen.py, art-agent/backend/app/agent/loop.py, art-agent/frontend/src/lib/types.ts, art-agent/frontend/src/components/chat/model-selector.tsx
• summary: 集成 Kolors IP-Adapter 模型（fofr/kolors-with-ipadapter，~$0.004/次），参考图通过 base64 data URI 直接传给 Replicate 的 IP-Adapter 参与风格生成。模型注册表新增 supports_ref_image / ref_image_param 通用字段，新增 IP-Adapter 模型只需加配置。to_data_uri 抽为公共函数供 loop.py 和 image_gen.py 共用。前端模型列表显示绿色"参考图"徽章。

[CL-20260412-2230] 2026-04-12 — 用户消息气泡中显示参考图缩略图

• tags: 前端, 参考图, UX, chat-messages
• affected_files: art-agent/frontend/src/lib/types.ts, art-agent/frontend/src/app/page.tsx, art-agent/frontend/src/components/chat/chat-messages.tsx
• summary: 用户上传参考图后发送消息，之前聊天气泡中不显示参考图，无法确认是否成功附带。修复：ChatMessage 类型新增 refImageUrl 字段，page.tsx 构造用户消息时用 URL.createObjectURL 保存预览 URL，chat-messages.tsx 在用户消息气泡中渲染缩略图（最大 160×120px）。Blob URL 仅当前会话有效，不持久化。

[CL-20260412-2200] 2026-04-12 — 修复 DeepSeek 不支持 image_url 导致参考图上传报错

• tags: bug修复, 后端, Agent Loop, vision, DeepSeek, 多模态
• affected_files: art-agent/backend/app/agent/loop.py
• summary: 上传参考图时使用 OpenAI Vision 格式（image_url content type）发送给 DeepSeek API，但 DeepSeek 只支持 text 类型，导致 400 错误。修复：新增 vision 能力检测（基于模型名称关键词），不支持 vision 的模型改为文字提示方式告知 LLM 有参考图，参考图仍传给图像生成工具处理。

[CL-20260412-2130] 2026-04-12 — 修复图片生成失败时前端显示破碎图标

• tags: bug修复, 前端, 后端, 图像生成, 错误处理
• affected_files: art-agent/backend/app/agent/tools.py, art-agent/frontend/src/app/page.tsx
• summary: Replicate API 调用失败（如余额不足 402）时，错误字符串 [生成失败: ...] 被混入 images 列表传给前端，导致 <img> 标签渲染破碎图标。修复：后端 tools.py 分离有效 URL 和错误信息为 images/errors 两个字段；前端 page.tsx 过滤掉以 [ 开头的无效 URL，无有效图片时不渲染图片网格。

[CL-20260412-2100] 2026-04-12 — 生图模型动态切换：Provider 抽象 + 前端模型选择器

• tags: 后端, 前端, 图像生成, 模型切换, Provider, 重构, Replicate
• affected_files: art-agent/backend/app/config.py, art-agent/backend/app/services/image_gen.py, art-agent/backend/app/api/chat.py, art-agent/backend/app/agent/loop.py, art-agent/backend/app/agent/tools.py, art-agent/backend/.env, art-agent/backend/.env.example, art-agent/frontend/src/lib/types.ts, art-agent/frontend/src/lib/api.ts, art-agent/frontend/src/components/chat/model-selector.tsx, art-agent/frontend/src/components/chat/chat-input.tsx, art-agent/frontend/src/app/page.tsx
• summary: 将图像生成从 Replicate 硬绑定重构为 Provider 抽象层。后端：config.py 新增 IMAGE_MODELS 注册表（flux-schnell / flux-dev / SDXL），image_gen.py 引入 ImageProvider 基类 + ReplicateProvider 实现，chat.py 新增 GET /api/models + POST /api/chat 增加 image_model 参数，agent loop / tools 全链路透传。前端：新建 ModelSelector 下拉组件集成到 ChatInput，每条消息可选不同模型，选择持久化到 localStorage。

[CL-20260412-1800] 2026-04-12 — 移动端适配 + Cloudflare Tunnel 内网穿透

• tags: 前端, 响应式, 移动端, 部署, Cloudflare, 穿透, 配置
• affected_files: art-agent/frontend/src/app/layout.tsx, art-agent/frontend/src/app/globals.css, art-agent/frontend/src/app/page.tsx, art-agent/frontend/src/app/gallery/page.tsx, art-agent/frontend/src/components/sidebar/sidebar.tsx, art-agent/frontend/src/components/layout/top-nav.tsx, art-agent/frontend/src/components/detail/image-detail-panel.tsx, art-agent/frontend/src/components/chat/chat-messages.tsx, art-agent/frontend/src/components/chat/chat-input.tsx, art-agent/frontend/src/components/chat/image-grid.tsx, art-agent/frontend/src/lib/app-context.tsx, art-agent/frontend/next.config.ts, art-agent/start-tunnel.ps1, art-agent/README.md
• summary: 为实现"手机浏览器远程访问"做了两大块工作。(1) 移动端响应式适配：侧边栏改为固定定位抽屉式（md 以下），顶栏新增汉堡菜单，图片详情面板移动端全屏 overlay，气泡/输入框/Gallery 网格间距微调，hover 操作在移动端始终可见，默认小屏折叠侧边栏。(2) 穿透方案：安装 cloudflared，编写 start-tunnel.ps1 一键脚本自动创建双隧道 + 更新 .env.local + 退出时恢复。Next.js 图片白名单加 trycloudflare.com。uvicorn 改绑 0.0.0.0。路线 B（云服务器部署）记为延期方案。

[CL-20260412-1530] 2026-04-12 — 修复 .env 配置加载时序问题

• tags: 后端, bug修复, 配置, dotenv, Python
• affected_files: art-agent/backend/app/main.py, art-agent/backend/app/config.py, art-agent/backend/app/agent/loop.py, art-agent/backend/app/services/image_gen.py, art-agent/backend/.env
• summary: 切换 DeepSeek 后报 "Model Not Exist"。根因：(1) load_dotenv() 在业务模块 import 之后执行，config.py 的模块级变量在 import 时就固化为默认值 gpt-4o-mini；(2) load_dotenv 默认 override=False 不覆盖已有环境变量。修复：load_dotenv(override=True) 提到所有 import 之前；config.py 常量改为函数式懒读取；.env base_url 改为不带 /v1。

[CL-20260412-1500] 2026-04-12 — 品牌重命名 EPEEKit + API 配置集中化

• tags: EPEEKit, 品牌, 配置, 后端, 前端, 重构
• affected_files: art-agent/frontend/src/app/layout.tsx, art-agent/frontend/src/components/layout/top-nav.tsx, art-agent/frontend/src/app/page.tsx, art-agent/frontend/src/lib/store.ts, art-agent/frontend/src/app/gallery/page.tsx, art-agent/frontend/src/components/detail/image-detail-panel.tsx, art-agent/frontend/src/components/chat/image-grid.tsx, art-agent/frontend/package.json, art-agent/backend/app/main.py, art-agent/backend/app/config.py, art-agent/backend/app/agent/loop.py, art-agent/backend/app/services/image_gen.py, art-agent/backend/.env, art-agent/backend/.env.example, art-agent/README.md
• summary: 应用正式命名为 "EPEEKit"，全部用户可见文案 + 文件名前缀 + localStorage 键名统一替换。后端新增 config.py 集中管理 LLM_MODEL、IMAGE_MODEL 等原硬编码配置，.env 重组为带注释的分组结构，切换 LLM 只需改 3 个环境变量。同时新增 .env.example 模板和 Logo SVG。