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