# Air Spark — 开发交互记录 > 记录开发者与 Claude Code 的协作过程，积累 AI 辅助开发的最佳实践。 > 持续更新中。 --- ## Session 1 — 项目基础搭建 **日期**：2026-03-03 ### 用户需求 - 提供了产品 PRD 初稿，定义了 AI 驱动动画生产平台的完整功能 - 要求确定技术选型和项目架构 ### Claude 完成的工作 - 审阅 PRD，与用户讨论并迭代到 v0.4 - 确定技术栈：Next.js 14 + FastAPI + PostgreSQL + Celery/Redis - 设计了七阶段流水线架构（剧本→规划→人设→分镜→切分→视频→拼接） - 创建了三套自动化 Skill 提示词（storyboard / segmentation / json-schemas） - 确定了关键设计决策（网格按场景分、PIL 精确裁切、Stage 6 全并发等） ### 关键决策 - **网格尺寸按场景时长决定**（≤45s→4格, 45s-2min→9格, >2min→两个9格） - **JSON-only 输出**用于自动化 Skill（区别于人用的 Markdown Skill） - **移除 prev_frame 依赖**，Stage 6 全部片段可并发提交 --- ## Session 2 — UI 设计系统 & 组件展示页 **日期**：2026-03-04 ### 用户需求 - 要求建立完整的 UI 设计系统 - 风格关键词：liquid glass、glassmorphism、dark mode、premium、cinematic - 使用 ui-ux-pro-max skill 生成设计建议 ### Claude 完成的工作 1. **运行 ui-ux-pro-max 设计系统生成器**，获得专业推荐（配色、字体、风格） 2. **编写 UI-Design-System.md v0.3**，包含： - 色彩系统（影院暗色背景 + 品牌色 + 状态色） - 玻璃拟态层级规范（标准/激活/悬停三层） - 字体系统（Space Grotesk + DM Sans + JetBrains Mono） - 按钮/表单/卡片/Toast 等组件规范 3. **搭建 Next.js 14 前端项目**（App Router + TypeScript + Tailwind CSS v4） 4. **开发 21 节组件展示页**（`/showcase`），覆盖： - 色彩 & 玻璃层、字体排版、按钮、状态格子 - 流水线步骤条、审核卡片、骨架屏、剧本确认 - 日志面板、模态框、表单、Toast、空状态 - 徽章/标签、头像、导航路径、标签页 - 危险按钮 & 搜索框、提示气泡、文字对比度 5. **添加全局环境背景动效**（CSS 渐变光晕 + 动画） ### 用户反馈 & 迭代 - 用户要求添加**中英文切换**（i18n） - Claude 实现了页面级 `lang` 状态 + `t` 翻译对象（~110 个键） - 用户指出多处翻译问题，逐一修正： - 字体排版区域仍显示英文 → 添加中文示例文本 - "Stage 6" 未翻译 → 改为"第六阶段" - "面包屑" 翻译生硬 → 改为"导航路径" - "Air Spark 工作室" → 去掉"工作室"/"Studio" - 补充了 **Noto Sans SC（思源黑体）** 中文字体支持 ### 关键决策 - Showcase 页面用**页面级 `t` 对象**做 i18n（临时方案） - 正式应用将来用 **next-intl** + URL 路由（`/zh/...`, `/en/...`） - 品牌名统一为 **Air Spark**（不带 Studio / 工作室） --- ## Session 3 — 开发策略讨论 **日期**：2026-03-04 ### 用户需求 - 了解 Claude Code 2026 新功能（Swarm、Worktree、Batch 等） - 考虑使用 Swarm 团队模式进行并行开发 - 要求 Claude 给出客观建议，以最快完成项目为目标 - 要求建立**开发交互记录文档**，积累协作经验 ### Claude 的建议 用户原有流程（先 UI → 再交互 → 再后端）本质正确。**不建议为了用新功能而改变有效流程。** Swarm 现阶段不适合全面启用的原因： 1. 缺少清晰的任务边界（核心页面 UI 未确定） 2. 前后端 API 契约未定义（并行开发会导致接口不一致） 3. 实验功能有额外协调开销 **推荐路线：** - **阶段 A**（串行）：设计锁定 → 确定核心页面 UI → 反推 API 契约 - **阶段 B**（并行/Swarm）：前端交互 + 后端 API + 数据库同时推进 - **阶段 C**：集成联调 ### 经验总结 > **给团队的建议**：AI 新功能（如 Swarm）应在**任务边界清晰时**才启用。 > 过早并行化 = 用协调开销换开发速度，得不偿失。 > 正确做法是先串行想清楚，再并行干活。 --- ## Session 4 — 核心页面开发（阶段 A：App Shell + 项目列表） **日期**：2026-03-04 ### 用户需求 - 要求后续每完成一步主动更新交互文档 - 开始开发核心页面，询问逐个做还是一起做 ### Claude 的建议 **先做一个页面锁定 App Shell，再批量出剩余页面。** 原因： - 第一个页面确定布局骨架（侧边栏 + 内容区），所有页面共用 - Shell 确认后，剩余页面只是填内容，可以快速批量产出 ### Claude 完成的工作 #### 1. App Shell 布局骨架 - **Sidebar 组件**（`components/layout/Sidebar.tsx`）： - 可折叠侧边栏（240px ↔ 68px），玻璃拟态背景 - 四个导航项：项目、资产库、Skills、设置 - 当前路由高亮（accent 紫色） - 底部用户信息区 + 折叠按钮 - collapsed 状态由父组件控制，sidebar 和 main 内容区联动 - **Dashboard Layout**（`app/dashboard/layout.tsx`）： - 管理 collapsed 状态，传递给 Sidebar - main 区域 margin-left 随 sidebar 折叠联动动画 #### 2. 项目列表页（`app/dashboard/page.tsx`） - **页面头部**：标题 + 「创建项目」CTA 按钮 - **搜索栏 + 统计**：实时搜索过滤 + 项目数/运行数统计 - **项目卡片网格**：响应式（1/2/3/4 列） - 每张卡片包含：类型标签、项目名、集数、运行状态 - **七阶段进度条**：彩色条形图，直观展示流水线进度 - 当前阶段 + 最后更新时间 - Hover 效果 + 更多操作按钮 - **空状态**：无项目时的引导界面 - **搜索无结果**：提示换关键词 - 4 条 Mock 数据覆盖不同状态（running / completed / failed） #### 3. Build 验证 - `npx next build` 通过，无 TypeScript 错误 ### 新增文件 | 文件 | 用途 | |------|------| | `components/layout/Sidebar.tsx` | 可折叠侧边栏组件 | | `app/dashboard/layout.tsx` | Dashboard 布局（sidebar + main） | | `app/dashboard/page.tsx` | 项目列表页 | ### 用户确认 - 用户确认项目列表页视觉方向 OK，要求继续做其他页面 - 发现左下角有黑色小圆球 → 是 Next.js Dev Indicator，在 `next.config.ts` 中关闭 --- ## Session 4（续）— 批量产出核心页面 **日期**：2026-03-04 ### 用户需求 - 确认 App Shell 视觉方向后，批量产出剩余核心页面 ### Claude 完成的工作 #### 1. 项目详情页（`app/dashboard/[projectId]/page.tsx`） - **面包屑导航**：项目 > T仔的上班日记 - **项目信息卡**：名称、类型标签、描述、Skill 标签列表 - **统计行**：总集数、运行中、已完成 - **剧集列表**：每行包含： - 集数编号（大字）+ 标题 + 状态标签（草稿/运行中/已完成/失败/空闲） - Mini 七阶段进度条 - 当前阶段 + 时长 + 更新时间 - Hover 显示操作按钮（剧本 / 流水线 / 开始写剧本） - 5 条 Mock 剧集数据覆盖各种状态 #### 2. 剧本对话页（`app/dashboard/[projectId]/chat/page.tsx`） - **类 Claude.ai 风格**的全屏对话界面 - **顶栏**：返回按钮 + 项目/集数标题 + Skill 信息 + 「保存为正式剧本」按钮 - **消息区域**： - 用户消息（紫色气泡，右对齐） - AI 回复（玻璃卡片，左对齐，带复制/重新生成按钮） - 简单的 Markdown 渲染（加粗、分隔线） - **输入区域**：多行文本框 + 发送按钮（有内容时亮紫色） - **剧本确认流程**：点「保存为正式剧本」→ 顶部出现绿色 banner → 按钮变为「确认剧本，启动流水线」 - 4 条 Mock 对话，包含完整的剧本内容（T仔第一天上班的 7 个场景） #### 3. 流水线监控页（`app/dashboard/[projectId]/pipeline/[episodeId]/page.tsx`） - **七阶段步骤条**：可点击切换查看每个阶段，当前阶段高亮 - **Stage 6 视频生成视图**（主要展示）： - 渐变进度条 + 百分比 + 完成数 - 状态统计行（完成/生成中/失败/队列中） - 8×4 片段状态网格（32 个格子，颜色编码 + 图标） - 失败片段操作栏（编辑提示词 / 重跑） - 「导出 Seedance 批次包」按钮 - **Stage 3 人设审核视图**： - 4 张角色卡片（占位图 + 名称 + 通过/重跑按钮） - 底部汇总 CTA（全部通过后可点击） - **已完成阶段**：绿色 ✓ + 描述 + 「查看输出详情」 - **待执行阶段**：灰色时钟 + 等待提示 - **可折叠系统日志面板**：时间戳 + 级别颜色 + 消息 #### 4. Build 验证 所有 6 个路由编译通过： - `/dashboard` — 项目列表 - `/dashboard/[projectId]` — 项目详情 - `/dashboard/[projectId]/chat` — 剧本对话 - `/dashboard/[projectId]/pipeline/[episodeId]` — 流水线监控 ### 新增文件 | 文件 | 用途 | |------|------| | `app/dashboard/[projectId]/page.tsx` | 项目详情页（剧集列表） | | `app/dashboard/[projectId]/chat/page.tsx` | 剧本对话页（Claude.ai 风格） | | `app/dashboard/[projectId]/pipeline/[episodeId]/page.tsx` | 流水线七阶段监控页 | ### 页面导航路径 ``` /dashboard → 项目列表（4 张卡片） /dashboard/proj_001 → 项目详情（5 集剧集列表） /dashboard/proj_001/chat?ep=1 → 剧本对话（AI 对话 + 剧本确认） /dashboard/proj_001/pipeline/ep_01 → 流水线监控（七阶段 + 片段网格） ``` ### 经验总结 > **批量产出的前提是 Shell 已锁定。** 确认了侧边栏 + 布局后，三个页面只用了一轮就全部产出， > 没有布局返工。这验证了「先串行锁定骨架，再批量出内容」的策略。 --- ## Session 5 — 用户反馈 & 迭代修复 **日期**：2026-03-04 ### 用户反馈（4 个页面全部审阅后） 1. **流水线监控页** — 片段网格是正方形，不符合设计规范（应为自然高度 + padding） 2. **剧本对话页** — 纯对话模式不合理，需要改为**左右分栏**： - 左：剧本文档（可查看/可编辑，类似 IDE 中的文件面板） - 右：AI 对话（提需求、提修改意见） - 用户原话："如果把所有内容都堆在一个对话框里，我无法看到完整的剧本，也没办法手动微调" 3. **路由 bug** — 点击侧边栏「资产库」跳到了项目详情（`/dashboard/assets` 被 `[projectId]` 动态路由匹配了） 4. **项目列表 + 项目详情** — 暂无大问题 ### Claude 修复内容 #### 1. 路由 bug 修复 **根因**：`/dashboard/assets` 没有对应的 `page.tsx`，被 `[projectId]` 动态路由吞掉。 **修复**：创建三个静态路由页面（优先级高于动态路由）： - `app/dashboard/assets/page.tsx` — 资产库（空状态占位） - `app/dashboard/skills/page.tsx` — Skills 管理（3 个 Skill 卡片） - `app/dashboard/settings/page.tsx` — 设置（API Key、流水线模式配置） #### 2. 剧本对话页重设计 → 分栏式剧本工作台 **核心改造**：从纯对话布局改为左右分栏（可拖拽调整宽度）： - **左侧 — 剧本面板（55% 默认宽度）**： - 预览模式：Markdown 渲染（标题、对话、舞台指示、分隔线） - 编辑模式：纯文本 textarea，可手动修改 - 顶部切换按钮（预览 ↔ 编辑） - 场景数 + 时长统计 - **中间 — 可拖拽分隔条**（hover 显示拖拽图标） - **右侧 — AI 对话面板**： - 更紧凑的气泡（7px avatar、更小的间距） - AI 回复内容改为摘要式（"已更新场景二和场景五"），而非全文 - 输入框 2 行高度，适配右侧窄面板 - **联动逻辑**（Mock 演示）：AI 修改剧本后左侧同步更新 #### 3. 片段网格修复 移除 `aspect-square`，改为 showcase 标准：`p-2.5 flex-col items-center gap-1.5`，自然高度。 #### 4. Build 验证 9 个路由全部编译通过。 ### 新增文件 | 文件 | 用途 | |------|------| | `app/dashboard/assets/page.tsx` | 资产库页面（空状态） | | `app/dashboard/skills/page.tsx` | Skills 管理页面 | | `app/dashboard/settings/page.tsx` | 设置页面 | ### 经验总结 > **最有价值的反馈来自用户的使用场景描述。** 用户没有说"把聊天框放左边"，而是描述了 > 实际使用痛点："无法看到完整剧本，也没办法手动微调"。从痛点推导出分栏式设计， > 比纯视觉反馈更能驱动正确的产品决策。 > **动态路由的坑**：Next.js App Router 中，`[projectId]` 会匹配所有未定义的子路径。 > 静态路由必须显式创建 `page.tsx` 才能优先匹配。 --- ## Session 6 — 用户深度反馈 & 功能完善 **日期**：2026-03-04 ### 用户反馈（详细审阅全部页面后） 1. **剧本对话页**：需支持 3 种使用模式（引导生成 / 大纲辅助 / 优化已有剧本 + 文件上传） 2. **发送按钮**：与输入框不对齐、样式丑，需修复 3. **剧本内容**：用真实剧本 `ep01.md` 替换 Mock 数据 4. **资产库页**：需要 Mock 画廊（角色立绘做缩略图，点击查看三视图） 5. **Skills 页**：卡片需可点击进入详情/管理页 6. **项目卡片**：点击不跳转到项目详情（缺少路由链接） 7. **全局路由**：确保所有页面间跳转正确 ### Claude 完成的工作 #### 1. 项目卡片导航修复（`dashboard/page.tsx`） - 将 `ProjectCard` 组件的容器从 `
` 改为 ` **Mock 数据应尽早使用真实内容。** 用真实的 ep01.md 剧本做 Mock，不仅让页面更有代入感， > 还能验证 Markdown 渲染逻辑是否正确覆盖了实际格式（标题、角色表、舞台指示等）。 > **UI 组件要考虑不同数据类型的差异化展示。** 资产库中角色（三视图）和场景（单张大图）的 > 展示方式不同，需要在组件层面做类型判断而非统一模板。 --- ## 附录：交互模式总结 ### 有效的交互习惯 | 习惯 | 说明 | |------|------| | **给出风格关键词** | "liquid glass, cinematic dark" 比 "好看一点" 有效 10 倍 | | **即时指出翻译/文案问题** | 逐条修正比最后统一改效率高 | | **要求客观建议** | 明确说"要冷静客观"，避免 AI 一味附和 | | **先确认视觉再写逻辑** | 减少返工，UI 是需求的最佳载体 | | **描述使用场景而非UI指令** | "我无法看到完整剧本" > "把文本放左边" | ### 可以改进的地方 | 场景 | 建议 | |------|------| | 大批量文本替换 | 可以一次性提供所有翻译对照表，减少来回 | | 品牌命名 | 尽早统一（我们到 Session 2 末尾才去掉 "Studio"） | | 设计规范 | 先锁定再开发，避免边开发边改规范 | | 路由设计 | 动态路由旁的静态路由要提前占位，避免被吞 | --- ## Session 7 — 深度迭代：命名修正 + Skills 架构重设计 **日期**：2026-03-04 ### 用户反馈 1. **Stage 3 命名**："人设"不准确，只涵盖角色但该阶段生成所有参考图 → 改为"图片资产" 2. **项目卡片三点菜单**：三个点按钮无功能，应弹出操作菜单（设置/复制/归档/删除） 3. **三视图展示**：不应是三张分割图，而是一张横版 16:9 图（正面半身+正面全身+侧面+背面） 4. **Skills 架构根本问题**：当前 UI 把 Skill 当成"单一系统提示词"，但实际 Skill 是目录级知识包： ``` skill-name/.claude/skills/{name}/ ├── SKILL.md ← 入口文件 ├── references/ ← AI 按需读取的知识库 └── templates/ ← 输出模板 ``` 需要完全重设计为文件树 + 文件编辑器（IDE 风格） 5. **Stage 2 命名**："规划"太模糊，用户不明白这步做什么 → 改为"提示词提取" 6. **未来 Skill 安装**：需要"安装 Skill"按钮，支持导入外部 Skill ### Claude 完成的工作 #### 1. 流水线阶段命名修正（全局 7 文件） - Stage 2：`"规划"` → `"提示词提取"`（6 个文件，描述更清楚地告诉用户此步做什么） - Stage 3：`"人设"` → `"图片资产"`（5 个文件，覆盖角色/场景/道具所有参考图） - 涉及文件：`dashboard/page.tsx`, `[projectId]/page.tsx`, `pipeline/[episodeId]/page.tsx`, `showcase/page.tsx`, `skills/page.tsx` - Showcase 页英文同步更新：`"Planning"` → `"Prompt Extract"`, `"Characters"` → `"Image Assets"` #### 2. 项目卡片下拉菜单（`dashboard/page.tsx`） - 新增 `ProjectCardMenu` 组件，处理 `stopPropagation`（菜单在 Link 包裹的卡片内） - 四个操作项：项目设置 / 复制项目 / 归档 / 删除（红色危险操作） - 点击外部自动关闭（`useRef` + `useEffect` 监听 `mousedown`） - 菜单样式：毛玻璃深色背景 `rgba(15,15,25,0.95)` + `backdropFilter: blur(20px)` #### 3. 三视图修复（`dashboard/assets/page.tsx`） - **之前**：3 列网格展示 3 张独立的正面/侧面/背面图 - **修复**：单张 `aspect-video` 横版 16:9 图，内部用 `flex` 等分 4 区域 - 4 区域：正面半身 / 正面全身 / 侧面 / 背面 - 底部半透明标签标注每个区域 - 区域间白色分隔线 #### 4. Skills 管理页完整重写（`dashboard/skills/page.tsx`） **架构级重设计**，从"单一提示词编辑器"改为"目录级知识包管理器"： - **列表视图**： - 每张卡片显示文件统计（总文件数 / references / templates） - 顶部新增"安装 Skill"按钮（为未来外部 Skill 导入预留） - **详情视图**（IDE 风格）： - **左侧文件树**（260px 宽）： - 可折叠文件夹（SKILL.md、CLAUDE.md、references/、templates/） - 文件类型图标区分（FileText / Folder） - 当前选中文件高亮 - **右侧文件编辑器**： - 预览 / 编辑模式切换 - 文件路径面包屑 - 文件描述显示 - Mock 数据基于真实 Skill 目录结构 - Mock 数据来源：`D:\Air spark\skills\测试skills三件套\` 的实际文件结构 #### 5. Build 验证 9 个路由全部编译通过，零 TypeScript 错误。 ### 修改文件 | 文件 | 修改内容 | |------|---------| | `dashboard/page.tsx` | 阶段命名修正 + ProjectCardMenu 下拉菜单 | | `[projectId]/page.tsx` | 阶段命名修正 | | `pipeline/[episodeId]/page.tsx` | 阶段命名修正（"人设"→"图片资产" + "规划"→"提示词提取"） | | `showcase/page.tsx` | 阶段命名修正（中英文 + toast） | | `dashboard/assets/page.tsx` | 三视图改为单张 16:9 横图 | | `dashboard/skills/page.tsx` | 完整重写 → 文件树 + 编辑器（IDE 风格） | ### 经验总结 > **命名即沟通。** "规划"对开发者清楚但用户困惑，"提示词提取"直接告诉用户这步做什么。 > 面向用户的阶段名应该用动词+名词结构描述动作，而非抽象名词。 > **Skill 不是 prompt。** 把 Skill 简化为单一系统提示词是对其能力的阉割。 > 真实的 Skill 是一个目录结构化的知识包，模型根据用户需求选择性读取不同文件。 > UI 设计必须反映这种目录结构，否则管理界面会误导用户。 --- ## Session 8 — 阶段 A 收尾：全流程页面补全 **日期**：2026-03-05 ### 背景 用户确认了完整计划后，从 Step 0 到 Step 9 全部执行。核心目标：补全端到端流程链路 + 审核回退 + 剧本三栏工作台 + 所有管线阶段视图。 ### 完成的工作 #### Step 0+1: Pipeline 组件拆分 + ReviewGate + 级联失效 - 提取 `components/pipeline/` 目录，4 个核心组件：PipelineStepper、ReviewGate、SegmentGrid、LogPanel - PipelineStepper 新增 `invalidated` 状态（amber ⚠️ + 删除线）+ 可点击跳转 - ReviewGate 通用审核门：3 种模式（review / auto_passed / invalidated） - 级联失效逻辑：重跑/回退 → 下游全部标记 `invalidated`，旧数据保留 - `page.tsx` 瘦身：430 → ~200 行，纯布局 + 状态管理 + stage 分发 #### Step 2: 剧本工作台（三栏 IDE 布局） - `chat/page.tsx` 从双栏改为三栏：文件树(200px) + 文件预览/编辑(flex-1) + AI Chat(380px) - 文件树反映 screenplay-skill 7 阶段产出：concept → outline → characters → world → synopsis → beats → scripts - 4 种文件状态：✅ done / 📝 draft / ⏳ pending / ⚠️ outdated - Markdown 预览 + 纯文本编辑模式切换 - 顶栏：剧本阶段指示器（① ② ③ ④ ⑤ ⑥ ⑦）+ "确认剧本，启动流水线" CTA - 引导模式提示：当前进度、下一步建议 #### Steps 3-7: 五个阶段视图 | 文件 | 阶段 | 内容 | |------|------|------| | `StagePromptExtract.tsx` | Stage 2 | 三 Tab（角色/场景/Keyshot）+ 可展开编辑提示词 | | `StageImageAssets.tsx` | Stage 3 | 三 Tab（角色/场景/道具）+ 总进度 + 单资产重跑 | | `StageKeyshots.tsx` | Stage 4 | 按场景手风琴 + 宫格预览 + 裁切格子横滚画廊 | | `StageSegments.tsx` | Stage 5 | 片段列表 + 时码 + 参考图引用 + Seedance 提示词预览 | | `StageTimeline.tsx` | Stage 7 | 16:9 预览区 + 时间轴条 + 场景色编码 + 导出CTA | #### Step 8: 流程串联 - `dashboard/page.tsx` 新增 CreateProjectModal（2步表单：名称+类型 → 集数+技能预览） - 项目详情"添加剧集"按钮 → Link 到 chat 页面 - 项目详情"设置"按钮 → Link 到项目设置页 - chat 页"确认剧本，启动流水线" → Link 到 pipeline 页面 #### Step 9: 设置 + 项目设置 - `dashboard/settings/page.tsx`：完善 API Keys（Claude + Banana Pro + Seedance）+ 流水线模式（全自动/逐步审核/自定义）+ 自定义时 7 阶段审核开关 - 新建 `[projectId]/settings/page.tsx`：项目名/描述/类型 + 技能配置 + 渲染风格（6选项）+ 视频参数（比例+模型）+ 危险区（归档/删除） - 首页 `/` 重定向从 `/showcase` 改为 `/dashboard` ### 文件变更清单 | 操作 | 文件 | |------|------| | 新建 | `components/pipeline/PipelineStepper.tsx` | | 新建 | `components/pipeline/ReviewGate.tsx` | | 新建 | `components/pipeline/SegmentGrid.tsx` | | 新建 | `components/pipeline/LogPanel.tsx` | | 新建 | `components/pipeline/StagePromptExtract.tsx` | | 新建 | `components/pipeline/StageImageAssets.tsx` | | 新建 | `components/pipeline/StageKeyshots.tsx` | | 新建 | `components/pipeline/StageSegments.tsx` | | 新建 | `components/pipeline/StageTimeline.tsx` | | 新建 | `dashboard/[projectId]/settings/page.tsx` | | 重写 | `dashboard/[projectId]/pipeline/[episodeId]/page.tsx` | | 重写 | `dashboard/[projectId]/chat/page.tsx` | | 重写 | `dashboard/settings/page.tsx` | | 修改 | `dashboard/page.tsx`（添加 CreateProjectModal） | | 修改 | `dashboard/[projectId]/page.tsx`（添加剧集→chat，设置→settings 链接） | | 修改 | `app/page.tsx`（重定向 → /dashboard） | ### 经验总结 > **端到端先于细节。** 用户最在意的不是单个页面的精美度，而是"从创建项目到导出成片"的完整链路是否畅通。 > 先把 ReviewGate + 步骤条跳转 + 页面间 Link 全部串起来，再逐个打磨阶段视图。 > **三栏布局是内容创作工具的正确范式。** 剧本工作台从双栏升级为三栏后，"文件即产出"的概念变得清晰 —— 用户能看到 AI 生成了什么文件、当前在第几步、下一步做什么。 > **组件拆分的时机。** 当一个文件超过 300 行且包含多个独立子组件时，就应该拆。Pipeline page 从 430 行拆到 ~200 行后，添加 5 个新阶段视图几乎零成本。 --- ## Session 9 — 用户预览反馈：流水线三阶段 UI 修复 **日期**：2026-03-12 ### 背景 用户启动前端预览，对 Stage 4 / 6 / 7 三个阶段视图进行了详细审阅，提出了 3 类问题。 ### 用户反馈 1. **Stage 4（宫格生成）内容重复**：场景列表渲染了两遍 —— 上方 `grid-cols-2` 卡片组展示宫格缩略图，下方 accordion 又列了同样的场景带可展开的格子描述。 2. **Stage 6（视频生成）无法预览视频**：只有状态格子（完成/生成中/失败），点击完成的片段没有任何反馈。用户无法判断视频质量是否需要重跑。此外失败提示硬编码"片段 08"，多个失败时不会动态列出。 3. **Stage 7（剪辑导出）布局问题**： - 视频预览窗口 `max-w-2xl mx-auto` 偏小且居中，不符合剪辑软件操作直觉 - 时间轴片段下方出现一个 glass-card 展示"片段01 — 黑屏OS引入"，用户标注"干嘛用的？？？"——该卡片是点击时间轴片段后显示的选中详情，与预览区信息完全重复 ### Claude 修复内容 #### 1. StageKeyshots.tsx — 删除重复，合并视图 - **删除**上方 `grid grid-cols-2` 独立卡片组（4 个场景卡片 + 宫格缩略图） - **合并**到 accordion 展开面板内：先展示宫格缩略图（mini grid），再展示格子描述横滚画廊 - 移除未使用的 `Camera` import #### 2. SegmentGrid.tsx — 新增视频预览 + 动态失败处理 - **新增** `selectedId` 状态 + 点击"已完成"片段打开顶部预览面板（16:9 播放区 + 关闭按钮） - **选中态** ring 高亮，区分当前预览的片段 - **点击约束**：只有 `status === "done"` 的片段可点击预览，其余 cursor-default - **动态失败列表**：`segments.filter(s => s.status === "failed").map(...)` 替代硬编码"片段 08"，多个失败时逐行显示 #### 3. StageTimeline.tsx — 全宽预览 + 删除重复信息卡 - **预览区**：移除 `max-w-2xl mx-auto`，改为 `aspect-video` 全宽填充，尺寸与页面宽度一致 - **删除** "Selected Clip Info" glass-card（lines 147-164），该信息已在预览区内通过文字叠层展示 - 保留 `Image` import（预览区占位图标仍在使用） ### 修改文件 | 文件 | 修改内容 | |------|---------| | `components/pipeline/StageKeyshots.tsx` | 删除重复卡片组，宫格缩略图合并入 accordion | | `components/pipeline/SegmentGrid.tsx` | 新增视频预览面板 + 动态失败列表 | | `components/pipeline/StageTimeline.tsx` | 预览全宽 + 删除冗余信息卡 | ### 经验总结 > **重复信息 = 用户困惑。** 同一份数据渲染两次（Stage 4 的卡片+手风琴、Stage 7 的预览区+详情卡）， > 用户不会认为"这是两种视角"，只会觉得"为什么出现两遍"。宁可合并到一处，也不要拆成两个看起来类似的组件。 > **Mock 阶段也要考虑交互完整性。** Stage 6 只展示状态格子而没有点击预览，用户会认为功能缺失。 > 即使是占位 UI，也应该提供基本交互反馈（选中高亮、预览面板），让用户理解"这里将来能做什么"。 > **硬编码 Mock 的陷阱。** 失败提示写死"片段 08"在单个失败时没问题，但用户会追问"如果 4/5/6/7/8 都失败呢？" > 从一开始就用 `.filter().map()` 动态渲染，成本几乎为零但避免了这个问题。