根据统计结果，比格熊数字导演工作站 (bgxiong-ai-story) 项目的整体代码量如下：

📊 总体概况

🔧 后端代码（Rust）

💻 前端代码（TypeScript/React）

📁 其他文件类型

🏗️ 项目架构特点

1. 前后端分离：前端使用 React + TypeScript（~13.4万行），后端使用 Rust + Tauri（~8.1万行）
2. 代码比例：前端约占 57%，后端约占 43%
3. 文档丰富：Markdown 文档约 15.5 万行，说明项目文档完善
4. 配置繁多：大量 JSON/TOML 配置文件，支持多 AI 服务商配置

这是一个中大型桌面应用项目，采用 Tauri 2 框架构建，具备完整的 AI 故事创作功能（包括角色管理、剧集/场次/分镜管线、文生图/图生图/视频生成等）。

目标（已确认）

• 「全部场次 + 点场次」与「选集 + 点同一场次」读写同一 storyboard_graph_state 键：(project_id, episode_id=剧集节点 id, chapter_id=场次节点 id)。

• 不需要兜底、不考虑历史兼容：可删除/收紧依赖 __all__ / STORYBOARD_SCOPE_ALL 的故事板前端路径；遗留库中仅 __all__ 键下的 graph 行可视为可丢弃（不迁移）。

• 以项目最优解落地：单一解析函数 + 全链路同一 episodeId，避免双轨。

核心结论

• 场次节点已有 chapter_id（剧集 id）：list_nodes_by_type scene 分支 LEFT JOIN edges ... contains → source_node_id as chapter_id。

• 当前缺口：StoryboardTab 中 sceneGraphEpisodeId 在未选集时落到 STORYBOARD_SCOPE_ALL，与「选集」下的真实 episode_id 分裂。

推荐实现（最优、改动面收敛）

1. 单一「故事板剧集作用域」解析（前端）

新增小工具（例如 ui/src/domain/storyboardEpisodeScope.ts）或内联 useMemo：

// 语义：显式选集 > App 传入的 chapter > 当前场次所属剧集
resolvedStoryboardEpisodeId =
  (activeChapterId?.trim() ||
    chapter?.id?.trim() ||
    activeScene?.chapter_id?.trim() ||
    "");

• StoryboardTab：sceneGraphEpisodeId 改为上述 resolvedStoryboardEpisodeId（不再 || STORYBOARD_SCOPE_ALL）。

• 无场次：不加载 graph（现有逻辑已处理）。

• 有场次但 resolved 为空：视为数据损坏/孤儿场次 — 不兜底：toast 固定文案（如「场次未关联剧集，无法加载故事板画布」），loadStoryboardGraph / save 不调用；与「不要兼容」一致。

2. 与 graph 键一致的所有调用点（前端）

以下必须使用同一 resolvedStoryboardEpisodeId（从 StoryboardTab 下传或从 App 用相同公式计算，避免分叉）：

3. [sceneStoryboardChildNodes.ts](d:/00Dev/bgxiong-ai-story/ui/src/domain/sceneStoryboardChildNodes.ts)

• 删除 episodeId 默认值 STORYBOARD_SCOPE_ALL；改为调用方必传 已解析 的剧集 id。

• 若 episodeId 为空：直接返回 [] 或 throw（二选一；推荐返回 [] + 上层 toast，避免未处理异常）。

4. 常量与类型清理

• [storyboardGraph.ts](d:/00Dev/bgxiong-ai-story/ui/src/domain/storyboardGraph.ts)：STORYBOARD_SCOPE_ALL 若仅故事板 graph 使用，可删除并全量替换；若 片段画布等仍用 __all__（见 [types.ts](d:/00Dev/bgxiong-ai-story/ui/src/components/segment-canvas/types.ts)、App Clips），则保留常量但 故事板模块禁止再引用。

• [useStoryboardSceneGraph](d:/00Dev/bgxiong-ai-story/ui/src/components/storyboard/hooks/useStoryboardSceneGraph.ts)：移除仅用于 __all__ 回退的 import/拼接。

5. 后端（可选收紧，与「无兜底」对齐）

• [storyboard_graph::normalize_scope_id](d:/00Dev/bgxiong-ai-story/src-tauri/src/storyboard_graph.rs)：对 load_storyboard_graph_state / upsert_storyboard_graph_state 的入口，若 trim 为空则 Err 而非写入/读取 __all__（需同步改 [commands/storyboard.rs](d:/00Dev/bgxiong-ai-story/src-tauri/src/commands/storyboard.rs) 三处 normalize_scope_id）。

• 风险：仅当保证前端永远传非空剧集 id 时安全；否则 Tauri 命令会报错（符合「严格」）。

• 文档注释：chapter_scene_board_pipeline.rs 1388 行附近 更新为「episode_scope_id 必须为剧集节点 id，与前端一致」。

6. 数据（不兼容策略）

• 不编写迁移合并 __all__ → 真实剧集：旧行自然废弃。

• 可选（本地开发）：手动删 storyboard_graph_state 中 episode_id='__all__' 的行；不作为代码交付必选项。

验证

• 选集 A → 选场次 S → 改画布 → 切「全部场次」→ 再点 S：布局与节点与选集时一致。

• 从未选集路径进入：仅点 S（activeScene.chapter_id 有值）：同上。

• 清除场次或孤儿场次：resolved 为空时行为符合预期（不静默读 __all__）。

实施任务清单

1. 引入 resolvedStoryboardEpisodeId 解析并接入 StoryboardTab + 所有子 hook / API 参数。

2. 更新 App.refreshStoryboardShots 与 sceneStoryboardChildNodes（去默认 __all__）。

3. 删除故事板路径上对 STORYBOARD_SCOPE_ALL 的依赖；保留或收缩常量定义。

4. （可选）后端 normalize_scope_id 对空串改为 Err + cargo check。

5. 手动回归两条路径 + npm run build / 相关 ReadLints。

基于 Rust + WebGPU 的技术栈是目前高性能跨平台开发（Native + Web）的最前沿方案。对于追求性能和系统稳定性的开发者来说，这套组合几乎是“终极形态”。

以下是这套技术栈的核心构成及入门路径：

1. 核心架构：wgpu 生态

在 Rust 社区中，wgpu 是 WebGPU 规范的旗舰级实现。它不仅能让代码运行在浏览器中，还能直接调用 Windows (Direct3D 12)、macOS (Metal) 和 Linux (Vulkan) 的原生驱动。

• wgpu-rs (核心库)： 提供安全的 Rust 绑定。

• WGSL (WebGPU Shading Language)： 官方指定的着色器语言，语法类似 Rust，易于上手，且避开了 GLSL 的历史包袱。

• naga (着色器翻译器)： 负责将 WGSL 翻译为底层 API 能理解的指令。

2. 为什么选择 Rust + WebGPU？

这套方案之所以强大，是因为它解决了两个痛点：内存安全与跨平台统一性。

3. 入门技术栈建议

如果你准备从零开始构建一个高性能工具（例如 AI 图像处理或视频滤镜引擎），可以参考以下配置：

• UI 层： egui 或 iced。这两个库在 Rust 生态中非常流行，且都完美支持 wgpu 后端，适合快速构建跨平台工具界面。

• 窗口管理： winit。这是 Rust 处理窗口、输入事件的事实标准。

• 数学运算： nalgebra 或 glam。后者专门为图形学优化，性能极佳。

• Web 部署： wasm-bindgen。将你的 Rust 逻辑打包成 WebAssembly。

4. 关键应用场景：AI 推理与视频处理

对于本地 AI 推理，你可以利用 WebGPU 的计算着色器 (Compute Shader) 直接对张量进行并行运算。

• 模型转换： 将模型权重的二进制数据映射到 GPU 的 Storage Buffer。

• 并行计算： 在 WGSL 中编写计算内核（Kernel），实现类似矩阵乘法 (GEMM) 的操作。

• 零拷贝： 借助 Rust 的高效内存布局，减少 CPU 与 GPU 之间的数据交换延迟。

快速开始建议

1. 环境配置： 确保 Rust 环境已更新，安装 cargo。

2. 克隆 Demo： 到 GitHub 搜索 gfx-rs/wgpu 仓库，查看其 examples 文件夹。里面有从简单的三角形渲染到复杂的计算着色器应用。

3. 学习 WGSL： 如果你熟悉 Rust，你会发现 WGSL 的语法非常亲切。

小贴士： 由于你可能处理大量资源或追求极高性能，建议在开发时开启 wgpu 的验证层（Validation Layers），它能帮你捕捉到 90% 以上的非法显存访问错误。

到 2026 年，WebGPU 已经正式告别了“试验田”阶段，成为了 Web 高性能计算和图形渲染的绝对标准。

如果说 WebGL 是在浏览器里“画图”，那么 WebGPU 则是在浏览器里“直接操控 GPU”。