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

Dev Changelog — Recent

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

[CL-20260420-2237] 2026-04-20 — 前端一次性铺开文档中心 / 3D / 动作三大功能 UI（占位 + Phase 2 徽章）

• tags: 前端, UI, 文档中心, 3D, 动作, 命令面板, 工作台, 资源库, 占位, react-markdown, model-viewer
• affected_files: types.ts, placeholder-store.ts, app-context.tsx, layout.tsx, top-nav.tsx, app/docs/page.tsx, components/docs/*, task-type-tabs.tsx, workbench/params-3d.tsx, workbench/params-motion.tsx, app/page.tsx, task-card.tsx, detail/model-3d-panel.tsx, detail/motion-panel.tsx, app/gallery/page.tsx, motion-presets.ts
• summary: 按用户要求一次性把"文档管理中心（类似 Cursor）/ 3D 模型生成 / 动作生成"的界面与交互全部用占位实现落地。文档中心：/docs 三栏（DocTree+Tabs+Editor+Outline），textarea+react-markdown+remark-gfm 编辑预览，[[asset:id]] 在正文内渲染为资产卡片，AssetPicker 浮层 + Ctrl/Cmd+K CommandPalette 全站搜索。工作台：TaskTypeTabs 切 2D/3D/动作，按类型显示 Params3D（管道/视图/分辨率）或 ParamsMotionBar（模型/帧数/fps/循环/输出/角色/动作描述）；TaskCard 加 variant 区分颜色图标和 3D/动作专有字段。结果详情：Model3DPanel（多视图+360°占位+<model-viewer> 三模式，通道切 color/normal/stylized）、MotionPanel（视频/帧序列双模式+scrubber+MP4/GIF 下载占位）。资源库：顶部模态 Tab（图片/3D/动作）+ 计数与 Phase 徽章，3D/动作网格叠徽章+视角/帧数，动作卡片 hover 自动播放视频。<model-viewer> 通过 next/script lazyOnload 引入，真实管线接入时只换数据源。一次性写完避免后续反复返工；npx next build 通过。

[CL-20260420-1800] 2026-04-20 — Mesh Pipeline Phase 3 风格还原接入（IP-Adapter + ControlNet）

• tags: 视角变换, Mesh Pipeline, 风格还原, IP-Adapter, ControlNet, style_restorer, Phase 3
• affected_files: config.py, services/style_restorer.py (新增), services/view_transform.py, scripts/test_style_restore.py (新增), VIEW-TRANSFORM-MESH-PIPELINE-PLAN.md
• summary: 按 SPEC §4 Phase 3 落地 Mesh Pipeline 最后一段。在 IMAGE_MODELS 以 internal=True 注册 chigozienri/ip_adapter-sdxl-controlnet-depth（$0.07/张 ~72s，L40S），get_image_models_list() 改过滤 internal 防污染前端下拉；新增 helper get_style_restore_model_id()。新增 services/style_restorer.py：restore() 调 Replicate（image=用户原图做 IP-Adapter 风格参考，controlnet_input=Stage 2 的 normal 帧做结构约束，即 SPEC §1.4 的"路 A"），restore_batch() 用 asyncio.Semaphore(3) 批量重绘防 Replicate rate limit。view_transform._transform_view_mesh 接入 Stage 3：preserve_style=True 时对每帧调 restore_batch，单帧失败自动回退为 Stage 2 color 帧且不阻塞整体（error 字段挂出原因），与"Stage 2 失败不影响 Stage 1"的独立交付设计一致；images[i] 新增 color_url/restyled/restyle_error 字段，_stage 升级为 stage3 (N/M restyled)。新增 scripts/test_style_restore.py 供 Checkpoint 3：支持 --single 冒烟（$0.07）/全量（$0.42）、--scale/--cn-scale 覆盖参数、默认自动挑最新一组 normal 帧，复用 Phase 2 产物无需再跑 Trellis。默认参 scale=0.75 / controlnet=0.8，P3-4 调参由用户验收阶段确认。一次完整 6 视角请求 ~$0.46 / ~105s。

[CL-20260420-1700] 2026-04-20 — Mesh Pipeline Phase 2 抽帧 + combined_video 左右切分

• tags: 视角变换, Mesh Pipeline, Trellis, ffmpeg, imageio-ffmpeg, PIL, video_frame_extractor, Phase 2
• affected_files: video_frame_extractor.py (新增), view_transform.py, requirements.txt, scripts/test_frame_extract.py (新增), VIEW-TRANSFORM-MESH-PIPELINE-PLAN.md
• summary: 按 SPEC §4 Phase 2 落地 Mesh Pipeline 的阶段 2 抽帧。系统 ffmpeg 未装，改用 imageio-ffmpeg==0.5.1 自带的 Windows 静态二进制（ffmpeg-win64-v4.2.2.exe，wheel 22.6MB，免系统依赖）。新增 services/video_frame_extractor.py 实现 extract_by_azimuth(combined_video_path, azimuths, elevations, total_rotation_deg=360)：策略采用"一次全帧抽取到临时目录 + 按帧索引挑 + PIL 按中线切左右半"，比 -ss 逐帧抽更稳（免 keyframe 对齐），5s 视频成本可忽略；ffmpeg + PIL 阻塞部分用 run_in_executor 丢到线程池。view_transform._transform_view_mesh 串接 Stage1→Stage2，默认 azimuths=[0,60,120,180,240,300]，返回 images[{url,azimuth,elevation,normal_url,frame_idx}]；Stage 2 失败不会把整体置为失败（Stage 1 的 mesh/video 仍有交付价值，单独填 error 字段）。新增 scripts/test_frame_extract.py 供用户复用已有 generated/trellis_combined_*.mp4 做 Checkpoint 2 验收，无需再花钱跑 Trellis。Agent 已自测 120 帧 combined_video：6 视角映射到 frame_idx=0/20/40/60/80/100（完全均匀）+ 所有切图 512×512 方形。等用户 Checkpoint 2 验收后开 Phase 3（IP-Adapter+ControlNet 风格还原）。

[CL-20260420-1600] 2026-04-20 — Mesh Pipeline Phase 1 接入 Trellis（阶段 1 地基）

• tags: 视角变换, Mesh Pipeline, Trellis, Replicate, services, config, tools, Phase 1
• affected_files: mesh_generator.py (新增), view_transform.py, config.py, tools.py, scripts/test_trellis.py (新增), VIEW-TRANSFORM-MESH-PIPELINE-PLAN.md
• summary: 按 SPEC §4 Phase 1 落地 Mesh Pipeline 第二条视角变换管道的阶段 1。新增 services/mesh_generator.py 封装 Trellis 调用（firtoz/trellis:e8f6c452...）+ httpx 下载 .glb/color_video/normal_video 到 generated/；config.py 在 VIEW_TRANSFORM_MODELS 注册 trellis（enabled）和 hunyuan3d（enabled=False 占位），给所有条目加 pipeline 字段；view_transform.py 按 pipeline 分流 grid/mesh，mesh 阶段 1 只返回 mesh_url + color_video + normal_video，images 暂空；tools.py 的 transform_view 工具扩 model_id/azimuths/preserve_style。另新增 scripts/test_trellis.py 作为独立验收入口。Zero123++ 现有行为完全不变。等用户手跑脚本验收后开 Phase 2（ffmpeg 抽帧）。

[CL-20260420-1530] 2026-04-20 — 写入 Mesh-Pipeline 视角变换方案 SPEC（跨会话实施计划）

• tags: 视角变换, Mesh Pipeline, Trellis, Hunyuan3D-2, SPEC, 方案
• affected_files: docs/art-agent/VIEW-TRANSFORM-MESH-PIPELINE-PLAN.md
• summary: 针对"Zero123++ 只出 6 固定视角 + 建筑大角度易崩"的痛点，规划第二条视角变换路径 Mesh Pipeline。三段式：Trellis 生 .glb + 360° color_video（$0.041/30s） → ffmpeg 按 azimuth 抽帧 → chigozienri/ip_adapter-sdxl-controlnet-depth 用原图做 IP-Adapter 风格还原。文档含三个 Replicate 模型的版本 ID/OpenAPI schema、config 扩展设计、6 个 Phase 可独立执行任务清单、跨会话恢复指引。Hunyuan3D-2 + pyrender 自由相机留作 Phase 5 二期可选。一期工程量 ~5h，单次总成本 ~$0.46/~105s。

[CL-20260420-1501] 2026-04-20 — 后端增加 watchfiles 依赖，修复 Windows uvicorn --reload 失效

• tags: uvicorn, watchfiles, 热重载, Windows, reload, requirements
• affected_files: requirements.txt, requirements-lock.txt
• summary: 排查"Zero123++ 切图还是错位"时发现：CL-20260420-1212 的修复在磁盘上完全正确，但后端 uvicorn 进程是 11:55 启动从未 reload。根因是 venv 里 watchfiles 和 watchdog 都没装，--reload 退化成 StatReload 轮询式 reloader，在 Windows + 深层子目录 + 新建文件 (view_transform.py) 场景下基本失效。解决：pip 安装 watchfiles==0.24.0 并写入 requirements 两个文件。仅装依赖不会对当前进程生效，必须 kill + 重启后端。踩坑记为 PF-20260420-1501。

[CL-20260420-1212] 2026-04-20 — 修复 Zero123++ 视角切图布局反转（3×2→2×3）

• tags: Zero123++, 视角变换, 切图, bug修复, grid_layout
• affected_files: config.py, view_transform.py
• summary: 用户反馈 transform_view 输出的 6 张视角图严重错位（每张呈窄长条、上下拼两个物体）。根因是 jd7h/zero123plusplus Replicate 部署版实际输出 2 列 × 3 行 的高图，但 config.py 里按官方 README "3×2 grid" 字面意思配成了 cols=3, rows=2。修复：(1) grid_layout 改为 {"cols": 2, "rows": 3}；(2) _split_grid_image 新增健壮性保护——假定单视角正方形，若配置 ratio 与实际图像 ratio 差异 >20%，自动交换 cols/rows 并打 warning，让未来换其他视角变换模型时免疫类似布局歧义。踩坑已记录 PF-20260420-1212。

[CL-20260417-1510] 2026-04-17 — Cloudflare 穿透脚本兼容 PS5.1 + 本地 cloudflared

• tags: 内网穿透, cloudflared, PowerShell, start-tunnel, env
• affected_files: art-agent/start-tunnel.ps1, .gitignore
• summary: Windows PowerShell 5.1 在 UTF-8 无 BOM 下解析含中文的 @" here-string 会报错，导致穿透脚本无法运行。改为用 WriteAllLines 写入 frontend/.env.local，并将脚本保存为 UTF-8 BOM。脚本启动时若存在 art-agent/cloudflared.exe 则自动加入 PATH 优先使用。根目录 .gitignore 忽略本地下载的 cloudflared.exe（体积大）。

[CL-20260417-1500] 2026-04-17 — 按 INFOLAYER.md 实现完整前端信息架构（Phase 1+ 占位骨架）

• tags: 前端, UI骨架, INFOLAYER, 多项目, 风格库, 角色库, 训练中心, 项目设置, TaskCard, 候选评估, 占位数据
• affected_files: types.ts, placeholder-store.ts, app-context.tsx, globals.css, app/page.tsx, app/gallery/page.tsx, app/styles/, app/characters/, app/training/*, app/settings/page.tsx, top-nav.tsx, project-switcher.tsx, project-card.tsx, session-quick-picks.tsx, task-card.tsx, advanced-controls.tsx, candidate-panel.tsx, sidebar.tsx
• summary: 一次性铺开 INFOLAYER.md Phase 1–3 完整 UI 骨架：新增 /styles /characters /training /settings 四大模块（列表+详情+创建流程），工作台加入风格/角色/规格快选条、高级控制抽屉、候选评估面板、Task Card 组件，资源库加二级过滤（资产类型/风格/角色）+ 语义搜索切换；TopNav 加项目切换器和新导航项；Sidebar 加项目信息卡。所有 Phase 1+ 数据通过新建的 placeholder-store.ts + localStorage 占位持久化（首次注入示例），AppContext 扩充相关字段。所有真实后端行为均为 alert("（占位）...")，UI 上以 phase-chip（P1/P2/P3）明示阶段。搜索"（占位）"可快速定位待接入点。

[CL-20260416-1600] 2026-04-16 — 视觉风格从暗绿底全面转为白底青绿（绢本山水）

• tags: 前端, 视觉风格, 色彩体系, CSS变量, 白底, 千里江山图
• affected_files: globals.css, page.tsx, login/page.tsx, gallery/page.tsx, chat-messages.tsx, chat-input.tsx, top-nav.tsx, sidebar.tsx, session-list.tsx, profile-modal.tsx, image-detail-panel.tsx, ambient-particles.tsx, VISUAL-STYLE-GUIDE.md
• summary: 背景从墨绿黑(#0C1210)改为绢本白(#FAFAF7)，文字改为墨黑(#1A1A1A)，accent色加深(#4DB8A4→#2E8B7A)适配白底，所有面板从深色毛玻璃改为白色毛玻璃，13个文件中硬编码的旧rgba全部替换，云雾/粒子透明度降低，VISUAL-STYLE-GUIDE.md同步重写。设计理念：千里江山图是青绿设色于绢本白底，白底留白才能让青绿有呼吸感。

[CL-20260416-1500] 2026-04-16 — UX 风格指南实现度补全（10 项未实现特性 + 文档状态标注）

• tags: 前端, UX补全, 动效, framer-motion, 微交互, 文档
• affected_files: chat-input.tsx, chat-messages.tsx, image-grid.tsx, motion-presets.ts, page.tsx, login/page.tsx, gallery/page.tsx, globals.css, app-context.tsx, sidebar.tsx, profile-modal.tsx, UX-STYLE-GUIDE.md
• summary: 逐项分析 UX-STYLE-GUIDE.md 中所有特性的实现度（原 ~65%），补全 10 项未实现特性：涟漪接入发送按钮、sendBounce 弹缩、会话切换滑入滑出动画、Error 飘散消失+自动清除、回到底部水滴形、全屏云雾凝聚加载、AI 回复逐行 opacity 阶梯、typo-h1/h2/strong 实际使用、用户消息左上切角、图片占位石青渐变呼吸脉冲。文档更新为每项标注 ✅ 状态 + 实现文件路径。

[CL-20260416-1330] 2026-04-16 — 交互体验全面升级：信息层级 + 科技质感 + 微交互趣味性

• tags: 前端, UX升级, 动效, framer-motion, 排版体系, 微交互, 视觉层级, 科技感
• affected_files: globals.css, page.tsx, chat-messages.tsx, chat-input.tsx, image-grid.tsx, session-list.tsx, sidebar.tsx, top-nav.tsx, image-detail-panel.tsx, profile-modal.tsx, model-selector.tsx, login/page.tsx, gallery/page.tsx, UX-STYLE-GUIDE.md, motion-presets.ts, ambient-particles.tsx, data-stream.tsx, ripple-effect.tsx, firefly-burst.tsx
• summary: 四阶段全面升级。Phase 1：globals.css 新增 7 级排版体系（Display 渐变→Micro 大写）+ 4 级 Surface 层级 + 点阵网格底纹 + 水波纹/shimmer/涟漪等CSS动画。Phase 2：新建环境萤火粒子组件（纯CSS）+ 数据流光组件（AI 活动时输入栏上方），用户/助手消息视觉差异（渐变背景+切角 vs glass-panel+左侧竖线）。Phase 3：引入 framer-motion，统一动画参数 motion-presets.ts；发送按钮投石入水（spring 弹缩+呼吸脉冲）、输入框水面感应（焦点扩展线+亮度随输入增强）、AI 回复云雾凝聚（blur 消散入场）、收藏萤火点亮（金色粒子爆发）、图片水墨晕染（clip-path 圆形揭示）。Phase 4：统一 Loading 水波纹 + shimmer 骨架屏 + 错误赭石红震动 + 空态 Display 渐变欢迎语 + stagger 入场，滚到底部按钮改圆形 spring 弹入，侧栏会话左侧竖线 hover，全组件 hover 浮起。新增 UX-STYLE-GUIDE.md 交互体验文档。

[CL-20260416-1000] 2026-04-16 — 集成 Zero123++ 视角变换工具（单图→6视角）

• tags: 视角变换, Zero123++, Novel View Synthesis, 新工具, Replicate
• affected_files: config.py, tools.py, loop.py, view_transform.py
• summary: 新增 transform_view 工具集成 Zero123++（Replicate），输入一张图片生成 6 个固定视角图片。独立服务模块 view_transform.py 处理 Replicate 调用 + grid 拼接图 Pillow 拆分。config.py 新增 VIEW_TRANSFORM_MODELS 注册表。loop.py 对视角变换结果做特殊 SSE 事件处理。进阶方案（3D重建+ControlNet）记入延期方案。

[CL-20260416-0930] 2026-04-16 — 设备绑定配置与 Skill/Hooks 解耦（local-env.json）

• tags: 基础设施, local-env, 跨设备, hooks, project-launcher, Skill
• affected_files: local-env.json, local-env.example.json, hooks.json, run-hook.ps1, session-init.sh, check-changelog.sh, local-env-check.mdc, project-launcher/SKILL.md, .gitignore, ENVIRONMENT.md
• summary: 新增 .cursor/local-env.json（gitignored）存放设备绑定配置（nodejs_path、shell），project-launcher Skill 和 hooks 均改为从中读取。hooks 增加 bash 版脚本 + PowerShell dispatcher 支持跨平台。新增 local-env-check Rule 在会话开始时自动探测生成。ENVIRONMENT.md 去除平台硬编码改为通用说明。

[CL-20260416-0900] 2026-04-16 — 环境依赖全面修复 + 统一环境文档

• tags: 环境, 依赖, Node.js, Python, venv, npm, requirements, ENVIRONMENT
• affected_files: requirements.txt, requirements-lock.txt, ENVIRONMENT.md, project-launcher/SKILL.md
• summary: 排查缺失依赖（venv/node_modules 均不存在），安装 Node.js v22.15.0 到 %LOCALAPPDATA%\nodejs\，创建后端 venv 并安装全部依赖（14 个直接 + 47 个间接），npm install 前端依赖（46 个包）。requirements.txt 锁定精确版本，新增 requirements-lock.txt 和 ENVIRONMENT.md 统一环境文档。project-launcher Skill Node.js 路径已同步更新。

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