AirSpark/DEV-LOG.md

# 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` 组件的容器从 `<div>` 改为 `<Link href={/dashboard/${project.id}}`
- 卡片现在可正确点击跳转到项目详情页

#### 2. 真实剧本替换（`[projectId]/chat/page.tsx`）
- 读取 `skills/测试skills三件套/原创剧本-skill/scripts/ep01.md` 的完整内容
- 替换 MOCK_SCRIPT 为《恐龙也是打工龙》第1集完整剧本（4 场 + 片尾彩蛋）
- 更新 MOCK_MESSAGES 对话内容，匹配真实剧本场景

#### 3. 发送按钮修复（`[projectId]/chat/page.tsx`）
- **之前**：`absolute` 定位在 textarea 内部，位置不准且样式突兀
- **修复**：改为 `flex items-end gap-2` 布局，按钮独立在输入框右侧
  - 固定 `w-10 h-10 rounded-xl`，与输入框底部对齐
  - 有内容时紫色发光，无内容时半透明 + 边框
  - 去掉 `pr-12`（不再需要为内嵌按钮留位置）

#### 4. 资产库画廊页（`dashboard/assets/page.tsx`）— 完整重写
- **搜索 + 分类筛选**：全部 / 角色 / 场景 / 道具（带计数）
- **资产卡片网格**（响应式 2-6 列）：
  - 缩略图用渐变色占位（角色=暖色、场景=冷色、道具=粉色）
  - 类型标签（左上角）+ 关联剧集标签（右下角）
  - 名称 + 更新时间 + 版本号
  - Hover 效果（缩略图亮度提升）
- **资产详情弹窗**（点击卡片打开）：
  - 角色：展示正面/侧面/背面三视图
  - 场景/道具：展示大图预览
  - 生成提示词（可编辑）
  - 关联剧集列表 + 版本历史
  - 操作按钮：重新生成 / 编辑提示词后重新生成
- Mock 数据：4 个角色 + 3 个场景 + 1 个道具（来自 ep01.md 剧本）

#### 5. Skills 管理页（`dashboard/skills/page.tsx`）— 完整重写
- **列表视图**：3 个 Skill 卡片（可点击进入详情）
  - 显示名称 + 英文 ID + 描述 + 关联阶段 + 更新时间
  - Hover 显示箭头指引
- **详情视图**（点击卡片后展示）：
  - 左侧：系统提示词编辑器（预览/编辑切换，类似剧本面板）
  - 右侧信息栏：
    - 基本信息（描述、关联阶段、模型、类型标签、更新时间）
    - 使用此 Skill 的项目列表
    - 版本历史
  - 操作：编辑 → 保存 → 版本自增
- Mock 数据包含真实的 Skill 提示词摘要

#### 6. Build 验证
9 个路由全部编译通过，无 TypeScript 错误。

### 修改文件
| 文件 | 修改内容 |
|------|---------|
| `dashboard/page.tsx` | ProjectCard 包裹 Link 实现点击导航 |
| `[projectId]/chat/page.tsx` | 真实剧本 + 发送按钮修复 |
| `dashboard/assets/page.tsx` | 完整重写 → 画廊 + 详情弹窗 |
| `dashboard/skills/page.tsx` | 完整重写 → 卡片列表 + 详情编辑 |

### 经验总结
> **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()` 动态渲染，成本几乎为零但避免了这个问题。