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

Dev Changelog — Recent

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

[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。