106 lines
19 KiB
Markdown
106 lines
19 KiB
Markdown
# 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` 条目。
|
||
|