0.1 到 0.2 | 从 30万 到 50万 | 我造了一台AIGC生产机器

# 从 0.1 到 0.2,比格熊跨了一大步:直连官方 API、本地化运行、52 万行代码造一台真正的「数字导演机器」

> 版本号从 0.1.613 跳到 0.2.612,不是修了几个 Bug 那么简单。这是一次架构层面的跨越式升级——跨平台地基打好、画布内核重写、六边形架构落地、故事管线深度重构。如果你之前觉得「AI 分镜工具就是调调 API」,这篇文章会让你重新认识这个产品。

---

## 先说人话:0.2 到底升级了什么?

打开比格熊,你可能第一眼看不出太大区别——界面还是那个界面,菜单还是那个菜单。但如果你把 0.1.613 和 0.2.612 的代码放在一起对比,你会发现:**底层几乎重写了一遍**

用一句话概括这次升级:

> **把一台「能用的机器」,升级成了一台「能扩展、能移植、能扛住未来三年迭代的机器」。**

具体来说,0.2 版本做了这几件大事:

1. **跨平台地基浇筑完成**——为未来在 iPad 上运行铺好了路
2. **画布内核全面重写**——连线系统统一、缩放控件统一、支持面板弹出多屏
3. **六边形架构正式落地**——33 个 Repository 端口,领域层与存储层彻底解耦
4. **故事管线深度重构**——故事圣经变更自动同步到受影响的剧集
5. **提示词工程全仓统一**——五层架构、17 条 SSOT 入口、CI 门禁自动检查
6. **字号系统 SSOT 化**——全仓字号用一套 CSS 变量管理,改一处全局生效

听起来很技术?别急,下面我一个一个用大白话讲清楚。

---

## 一、直连官方 API,不降级、不中转

这是比格熊最硬核的一点,也是很多人误解最深的一点。

市面上大部分「AI 创作工具」做的事情是:把几家模型的 API 包一层,做成一个统一的界面。用户在里面点按钮,工具在后台转发请求,拿到结果展示出来。这种做法有个致命问题——**你不知道中间经历了什么**

有些工具会在后台偷偷做「降级处理」:你选了 A 模型,但 A 模型排队太久或者报错了,工具静默换成 B 模型给你出结果。你拿到的图或者视频,可能根本不是你以为的那个模型生成的。

比格熊的做法完全不同:

**你选了什么模型,系统就用什么模型。不会偷偷换通道,不会静默兜底。没有适配过的模型宁可报错也不给你废图。**

这不是一句口号,是写在架构里的硬规则。后端有一个「统一端点注册表」——即梦、可灵、通义万相、Seedance、OpenAI,每家模型的接口都不一样,但比格熊把它们的差异全部封装在底层。业务管线只认统一接口,新增一家模型厂商,只需要注册一个新端点,业务层零改动。

更重要的是:**每一次生成请求,都是从你的电脑直连到模型厂商的官方 API**。没有中间服务器转发,没有第三方中转站。你的请求路径是:

```
你的电脑 → 模型厂商官方 API → 结果返回你的电脑
```

不是:

```
你的电脑 → 某个中转服务器 → 模型厂商 API → 中转服务器 → 你的电脑
```

**直连意味着什么?**

- **速度更快**——少一跳就少一层延迟
- **隐私更安全**——你的提示词、你的素材,不经过任何第三方服务器
- **成本更透明**——你用的就是官方定价,没有中间商加价
- **稳定性更高**——不依赖某个中转服务的存活

而且比格熊不只是接了一两家模型。当前已接入的模型矩阵:

| 能力 | 已接入模型 |
|------|-----------|
| 文本生成 | OpenAI、本地 llama.cpp 等 |
| 图片生成 | 即梦、通义万相、ComfyUI 等 |
| 视频生成 | 即梦、可灵、Seedance、通义万相等 |
| 语音合成 | 多家云端 TTS + 本地方案 |
| 唇形同步 | Hedra、LivePortrait、MuseTalk、Wav2Lip、可灵 — 5 种适配器 |

**今天能用的模型,明天全部能用。明天出来的模型,后天就能接上。** 这就是统一端点注册表的威力。

---

## 二、本地化运行,数据主权在你手里

比格熊是一个**安装在你电脑上的桌面客户端**,不是网页,不是在线白板。

这意味着什么?意味着你的故事、剧本、分镜、任务记录、生成的图片和视频——**全部存在你自己的电脑上**。不是存在某个云服务商的服务器上,不是存在某个网站的数据库里,是实实在在落在你硬盘的 SQLite 文件里。

**「本地化运行」到底好在哪?**

**第一,数据不会莫名消失。** 用网页工具,你有没有过这种经历:某天打开一个常用的在线工具,发现它改版了、下线了、或者你的账号出了问题,所有数据都没了。比格熊不存在这个问题——你的工程文件就在你的电脑上,拷到另一台电脑上照样打开。

**第二,断网也能用。** 比格熊内置了本地 AI 能力:通过 llama.cpp 可以跑本地大模型做文本推理,通过 Whisper 可以做本地语音识别。在飞机上、在偏远地区、在保密环境里,你照样能编辑工程、跑本地推理。云端 AI 是「可选外挂」,不是「唯一脊梁」。

**第三,隐私有保障。** 你的剧本不会自动上传到任何地方。对外发出的请求,只有你在某个按钮上**明确触发**的那次生成。机构关心「剧情与素材出不出域」的时候,比格熊的架构能给出清晰的边界——数据默认在本地,只有你主动发起的生成请求才会出境。

**第四,不绑定任何网站的生命周期。** 关闭浏览器不会丢工作,清理 Cookie 不会清空项目,某家网站改版不会影响你的工程。比格熊就像 Word 或 Photoshop 一样——装在你电脑上,打开就是你的工作环境。

---

## 三、52 万行代码,不是套壳 API 聚合器

很多人看到「AI 工具」四个字,第一反应是:不就是调几个 API,拼一个界面嘛。

比格熊的代码规模会让这种想法彻底破灭:

| 类别 | 文件数 | 代码行数 |
|------|--------|----------|
| Rust 后端 | 1147 | 20.3 万 |
| TSX 前端 | 519 | 11.0 万 |
| TS 逻辑层 | 1766 | 19.3 万 |
| **合计** | **≈3598** | **≈52.3 万** |

52.3 万行自研代码,3598 个文件。这不是一个周末项目,不是从 GitHub 上 clone 下来改改就发布的东西。这是一个人、从零开始、持续迭代的**正经生产软件**

而且这些代码不是「能跑就行」的堆砌。0.2 版本做了几个架构层面的大动作:

### 六边形架构正式落地

这是软件工程里一个很高级的设计模式。简单说就是:**你的业务逻辑和数据存储完全分开**

0.2 版本新增了 33 个 Repository 端口和 5 个 DTO(数据传输对象),覆盖画布、片段、角色、分镜、迁移等全领域。这意味着什么?意味着将来如果要换一个数据库,业务逻辑完全不用改;如果要加一个云端存储选项,只需要写一个新的适配器。

**四层分离**——领域层、应用层、基础设施层、组装层——每一层只干自己的事。上层知道下层,下层不知道上层。就像一栋楼:三楼知道有二楼,但二楼不知道三楼长什么样。加一个四楼,二楼完全不受影响。

### 故事管线深度重构

0.2 版本新增了一个 830 行的「故事同步管线」。这个管线做的事情是:当你修改了故事圣经(角色设定、世界观等核心设定),系统会自动检测哪些剧集受到影响,自动合并冲突,然后逐章同步更新。

以前你改了一个角色的性格设定,可能需要手动去每一集检查有没有矛盾。现在系统帮你做了。这不是「AI 帮你写故事」,是**工程化的自动同步机制**

### 提示词工程全仓统一

比格熊的提示词系统不是「写一句 prompt 发给 AI」那么简单。它有五层架构(UPEA),17 条 SSOT 入口,还有 CI 门禁脚本自动检查。

什么是 SSOT?Single Source of Truth——单一数据源。一个提示词模板,从数据库到接口到界面,只有一个权威来源。改一处,全局生效;不会出现「数据库里是 A,界面上显示 B」的情况。

0.2 版本还做了视觉样式词表统一、negative prompt 统一管理,甚至写了自动化检查脚本——每次提交代码前自动检查提示词有没有违反规范。这种工程严谨度,在消费级 AI 工具里极其罕见。

---

## 四、画布内核全面重写——自研引擎的真正威力

比格熊的无限画布是**完全自研**的,不依赖任何第三方商业画布包。0.2 版本对画布内核做了一次全面重写。

### 连线系统统一

以前,片段画布、分镜画布、角色画布各自有一套连线逻辑,交互方式不完全一致。0.2 版本新增了 `canvas-connector` 统一模块,把所有画布的连线系统收归一处。

这意味着什么?意味着你在一个画布里学会的连线操作,在其他画布里完全通用。**改一处交互,五处同时受益。**

### 缩放控件全仓统一

以前每个画布有自己的缩放组件——有的是滑块,有的是按钮,有的是快捷键。0.2 版本把这些全部统一成 `CanvasZoomHud` 通用组件,删除了 5 套旧的缩放组件,减少了约 600 行冗余代码。

### 面板弹出多屏

这是一个很实用的新功能:你可以把画布上的某个面板「弹出来」变成一个独立窗口,拖到第二个显示器上。对于有双屏或者多屏工作环境的创作者来说,这大大提升了工作效率。

### 性能策略

比格熊的画布不是「能显示就行」的简单实现。它有一套完整的性能策略:

- **虚拟渲染**——只重点处理屏幕附近的内容,视野外的卡片不画
- **分批加载**——几百张图不会一次性涌入,按需加载
- **视野外降级**——视频、大图离开视野后自动释放资源,不白占内存
- **指针中心缩放**——以鼠标位置为中心缩放,手感一致不跳帧

内部规格对**数百个节点**量级写了性能目标——先定体验指标,再实现。这是基础设施思路,不是「能用就行」。

---

## 五、跨平台地基浇筑——iPad 版已在路上

0.2 版本做了一件看起来「用户感知不到」但极其重要的事:**跨平台基础架构升级**

比格熊目前是 Windows 桌面应用,但 0.2 版本已经开始为 iPad 支持做准备。核心改造包括三个 trait(特征抽象):

- **PlatformPaths**——抽象文件系统访问。Windows 上读 `C:\Users\...`,iPad 上读 `NSDocumentDirectory`。上层代码不需要知道底层是什么系统。
- **ProcessExecutor**——抽象外部进程调用。Windows 上可以直接调 FFmpeg、llama.cpp,iOS 上全部走云端降级。
- **AiCapabilities**——抽象 AI 能力。iPad 上不能跑本地大模型?没关系,自动降级到云端。

这三个抽象层意味着:**将来移植到 iPad,核心业务逻辑几乎不用改**。只需要为 iOS 写一套「适配器」,把文件操作、进程调用、AI 能力替换成 iOS 版本就行。

这不是「以后再说」的规划,是**已经写进代码里的架构**。跨平台地基已经浇筑完成,后续的 iPad 适配是在这个地基上盖楼。

---

## 六、你选什么模型,就用什么模型——能力映射系统

这是比格熊最被低估的功能之一。

在设置里,有一个「能力映射」面板。在这个面板里,你可以精确控制:文本生成用哪家模型、图片生成用哪家模型、视频生成用哪家模型、语音合成用哪家模型。

而且这个映射是**全局生效**的。你在这里设置好了,整个应用所有需要生成的地方都按这个来。不会出现「分镜工作台用 A 模型,角色工作台用 B 模型」的混乱情况——除非你明确在某个地方做了单独设置。

**更关键的是:系统记住你上次实际使用了什么。** 你上次用可灵生成了一个视频,下次打开视频工作台,默认就是可灵。但这个「记住」是基于你实际使用的结果,不是基于某个硬编码的默认值。

多家供应商加多台本地模型混用时,这种「列表可控、心智稳定」的体验至关重要。你不需要每次都去翻下拉列表找你常用的那个模型——系统帮你记住了。

---

## 七、双脑分镜——AI 不只是帮你画画,是帮你当导演

这是比格熊区别于所有「AI 分镜工具」的核心能力。

市面工具的「AI 分镜」通常是:你写一句话,AI 出一张图。完事。

比格熊不是。每个镜头经过**两层大脑**处理:

**导演脑(语义层)**——理解剧本,拆出镜头语言:景别、机位角度、运镜方式、角色走位、身体朝向、视线方向、对白模式……这些是影视工业几十年积累的专业概念,不是随机排列。

**工程脑(渲染层)**——把导演语义翻译成画面可执行的结构化参数:构图锚点、头部空间、鼻前空间、纵深层次、光线方向、轴线规则……

两层分开的好处:导演语义可以反复调整,不用每次从头重画;工程参数可以批量替换,换一套渲染风格只需改工程脑,不用动导演脑。

0.2 版本对这两层都做了重大升级——后端新增了五阶段提示词管线(编译门控→布局提取→参考引导→文本锚定→解析),前端对齐了相同的管线逻辑。**前后端的提示词生成逻辑完全一致**,不会再出现「前端算出来的和后端算出来的不一样」的尴尬。

而且还有**叙事保真协议(NFP)**:每集剧本自动对照 NFP 规则做结构化检查——戏剧弧位是否完整、冲突类型是否合理、节奏目标是否匹配。检查结果不是笼统的「写得不好」,而是精确到规则 ID + 违规依据。

对话场景还有**自动质检**:必须有 master 镜、双方各有 OTS 和 reaction 镜——这是好莱坞几十年的覆盖拍摄规范,系统会自动检查并补全。

**AI 不只是帮你写故事,还帮你守规矩。**

---

## 八、自研通用图引擎——故事结构不是树,是网

传统的项目管理工具用「文件夹」组织内容——一层套一层,像树状目录。但故事不是这样的:角色跨集出场、场景跨章引用、镜头之间有因果和并行关系。

比格熊内置了一个**自研的通用有向图引擎**(GraphCore),用节点和连线来表达故事结构。每个节点可以连接任意多个其他节点,支持拓扑排序、连通性分析、环路检测。

这套引擎是**通用**的——分镜故事板、片段画布、Clips 片段管理——所有涉及「关系」的场景,共用同一套图引擎。**造一次,用五处。**

0.2 版本对图引擎做了性能优化和存储层升级,配合六边形架构的端口抽象,图引擎的持久化层可以灵活切换。

---

## 九、AI 任务队列——加一种能力,只写一个文件

比格熊的 AI 任务系统不是「调一个 API 等结果」那么简单。它有一套完整的任务生命周期管理:

- **状态机**——每个任务有明确的状态流转:排队→执行中→成功/失败/取消
- **调度器**——多个任务自动排队、并发控制、配额管理
- **持久化**——任务记录落盘,关掉软件再打开,任务状态还在
- **事件总线**——任务状态变化实时通知前端,进度条不是假的

已经支持 14 种不同的 AI 任务类型(文生图、图生图、视频生成、语音合成、唇形同步……),每种任务只需要注册一个 Handler,调度、排队、持久化、前端通知——全部自动生效。

**加一种新的 AI 能力,就像往书架上放一本新书——书架不用重建。**

---

## 十、ComfyUI 深度集成——不只是调用,是完整嵌入

如果你是 AI 图像生成的重度用户,你一定知道 ComfyUI——最流行的本地 Stable Diffusion 工作流工具。

比格熊对 ComfyUI 的集成不是「简单调个 API」那么粗糙。它是**完整集成**

- HTTP/WebSocket 双协议客户端
- 工作流扫描与编译器
- 占位符注入
- 自定义工作流支持
- 图像/视频双管线
- 设置管理

27 个源文件,覆盖了 ComfyUI 的方方面面。你可以在比格熊里直接使用你在 ComfyUI 里搭建的自定义工作流,不需要在两个软件之间来回切换。

---

## 十一、FFmpeg 媒体运行时——视频转码、音频提取、字幕合成

比格熊内置了完整的 FFmpeg 集成(12 个源文件),封装了 FFmpeg CLI 的定位、参数构建、执行、探测解析。

这意味着什么?意味着在从分镜图到最终成片的全链路中,所有需要媒体处理的环节——视频转码、音频提取、字幕合成、格式转换——都可以在应用内完成,不需要你另外安装和配置 FFmpeg。

---

## 十二、权限系统与配额管理——面向机构的设计

比格熊不只是给个人用户用的。它内置了一套可插拔的权限框架:

- **权限后端**——支持多种认证方式
- **装饰器**——函数级权限控制
- **审计日志**——每一次操作都有记录
- **缓存层**——权限检查不影响性能
- **日配额管理**——控制每天的 AI 生成次数

这套系统面向的是机构采购和团队使用场景。对于影视公司、教育机构、内容团队来说,「谁能用、用了多少、做了什么」是必须回答的问题。比格熊从架构层面就考虑了这些需求。

---

## 十三、唇形同步——5 种适配器,总有一款适合你

这是比格熊在视频生成领域的一个独特能力。当你的角色需要「开口说话」时,光有配音是不够的——嘴型要对得上。

比格熊内置了 5 种唇形同步适配器:

- **Hedra**——高质量唇形驱动
- **LivePortrait**——实时肖像动画
- **MuseTalk**——开源唇形同步
- **Wav2Lip**——经典的音频驱动唇形
- **可灵**——视频模型自带的唇形能力

5 种方案,覆盖从「够用」到「精雕」的不同需求。你可以根据自己的预算和质量要求,选择最适合的方案。

---

## 十四、自动更新与断点续传

0.2 版本改进了应用更新体验:

- **静默后台下载**——更新包在后台下载,不打断你的工作
- **断点续传**——网络中断后恢复下载,不需要从头再来
- **被动安装模式**——下载完成后提示你安装,你选择合适的时间重启

这些看起来是「小功能」,但对于一个需要频繁更新的桌面应用来说,更新体验的好坏直接影响用户的留存意愿。

---

## 说到底,0.2 版本意味着什么?

0.1 是「能用」。0.2 是「能扩展、能移植、能扛住未来三年迭代」。

从用户视角看,0.2 版本的体验提升是渐进的——你可能不会立刻感觉到「哇,完全不同了」。但从架构视角看,这是一次质的飞跃:

- **跨平台地基浇筑完成**——iPad 版不再是一个遥远的梦想,而是一个「写适配器就能实现」的工程任务
- **六边形架构落地**——换数据库、换云服务商、加新功能,都不会牵一发动全身
- **画布内核重写**——所有画布共用一套引擎,改一处交互,五处同时受益
- **提示词工程统一**——前后端逻辑一致,CI 门禁自动检查,不会再出现「前端算的和后端不一样」

**架构决定上限。比格熊的上限,远不止你现在看到的样子。**

---

## 适合谁用?

- 🎬 **独立创作者**——一个人也能产出完整的分镜和视频草稿
- 📹 **短视频团队**——批量试制 AI 辅助前期,快速验证创意
- 🎓 **影视院校**——学生在可控环境下练习分镜和导演思维
- 📖 **网文/漫画作者**——把文字故事可视化,试拍「纸上电影」
- 🏢 **内容机构**——数据不出域、操作可追溯、模型可审计

---

## 现在就试试

比格熊数字导演工作站,Windows 桌面客户端,本地安装,即开即用。

- ✅ 直连官方 API,不降级、不中转
- ✅ 本地化运行,数据主权在你手里
- ✅ 52 万行自研代码,不是套壳
- ✅ 支持即梦、可灵、通义万相、Seedance、OpenAI 等多家模型
- ✅ 内置 llama.cpp + Whisper 离线推理
- ✅ 5 种唇形同步方案
- ✅ ComfyUI 本地工作流深度集成
- ✅ 自研无限画布内核,数百节点流畅运行

**你的故事。你的数据。你的选择。**

🔗 [bgxiong.com](https://www.bgxiong.com)

---

*52.3 万行代码,从零到一。不是套壳,不是聚合器,是造机器。版本号从 0.1 跳到 0.2,不是修 Bug,是重建地基。*

比格熊对外项目综述 | 0609

# 项目综述(bgxiong-ai-story)— 比格熊数字导演工作站

| 项 | 说明 |
|----|------|
| **文档性质** | 面向非技术读者的项目全景:市场背景、产品与技术要点、阶段性成果与方向(中性表述)。 |
| **统计口径** | 工程规模统计截至 **2026-06-09**(v0.1.615),仅统计个人自研源码与内部文档,不含第三方依赖库与自动生成的安装包内容。 |

---

## 1. 定位概览

比格熊数字导演工作站(bgxiong-ai-story)是一套 **AI 驱动的多模态故事与分镜工作台**,产品形态上是 **安装在电脑上的桌面客户端软件**(而非「打开浏览器即用」的纯网页产品)。它把故事结构(项目—剧集—场次—片段/镜头)[^工程命名]、角色与演员资产、分镜故事板,以及文本 / 图像 / 视频 / 语音生成链路放在 **同一套本地工程与同一应用窗口** 里闭环完成,面向影视、短视频、动漫与教育实训等 **前期创意与试制** 场景。

[^工程命名]: 工程代码中对应 `story`(故事根)→ `chapter`(剧集节点)→ `scene`(场次节点)→ `segment`(片段/镜头节点),详见 `项目文档/20260509-SPEC-全仓语义命名权威规范.md` §1 冻结词表。

产品名称「比格熊数字导演工作站」体现其核心理念:**用 AI 将「一句话故事」自动拆解为完整的可视化制作管线**——从故事种子到剧集、场次、镜头、分镜图、视频成片,全链路自动化,大幅降低短视频与动画制作门槛。

云端 AI、开放平台接口在本产品中的角色,更接近 **用户按需接驳的能力插件**:用来完成某次生成或某种模型推理;**工程本体、数据结构、任务编排、设置与日志** 仍以客户端与本地存储为主轴。这与「做一个网站外壳,里面嵌各家网页或只转发接口」有本质区别——前者是 **可离线打开的工程文件型生产力工具**,后者往往离不开会话、Cookie 与远端页面形态,数据和体验的掌控链也更短。

---

## 2. 市场视角

- **需求背景**:多工具并行(文档、表格、浏览器里各家模型页面)容易造成上下文断裂、素材与版本散落;创作方难复盘「用了哪家模型、最终下过怎样指令」。机构使用场景还对 **可控、可追溯** 有刚性要求。
- **产品切入点**:用 **结构化本地工程** 承接创意流程;用户在设置与各界面里 **明确选定** 文本、配图、改图、视频、语音等通道,系统按选择执行,**不做**用户未同意的暗中替换,降低合规与品控风险。
- **典型用户**:独立创作者、小型制作组、内容团队与院校实训等需要在 **可控环境** 下批量试制 AI 辅助前期的群体。

---

## 3. 为什么是桌面客户端

下面几条概括 **客户端路线相对「云端套壳」或「纯浏览器工具」** 的差异;不是说「完全不用云」,而是 **云服务于生成能力,客户端承载创作资产与工业流程**

- **工程与数据默认在用户自己电脑上**
  项目、章节场次关系、分镜结构、任务记录、素材引用等落在 **本地数据库与本地目录**,用户对自己的剧本与物料拥有直观的 **占有感与备份方式**(拷贝文件夹、整机备份、离线归档),而不是默认「全部托管在第三方网页账号背后」。

- **不绑死在浏览器标签页的生命周期**
  关闭浏览器、清理站点数据、某家网站改版或下线,通常 **不会**一笔勾销你的「工作台形态」。客户端像普通办公软件一样常驻本机,打开即是同一套界面与同一套工程逻辑。

- **云端是「可选外挂」,不是「唯一脊梁」**
  需要文生图、图生图、视频、语音等时再按用户选择去访问各家开放平台;同时支持 **本地装载的大模型**(llama.cpp 文本推理、Whisper 语音识别),弱网、断网或保密环境下仍可浏览与编辑工程结构、跑本地推理,**不把「能上网」当作使用产品的绝对前提**

- **更深地接入本机能力**
  日志与诊断、数据目录配置、可选本地工作流(如 ComfyUI)、大批量读写与路径解析、媒体运行时(FFmpeg 集成)、磁盘清理等,都是 **操作系统级客户端** 天然擅长的领域;这些若仅靠网页沙箱,往往处处受限或体验割裂。

- **复杂界面与大体量交互敢往深了做**
  例如大面积无限画布、多标签重度工作台、长列表任务中心——按 **桌面性能预期** 做虚拟渲染与内存策略,而不是在手机浏览器或嵌套网页里「凑合能用」。

- **隐私与对内合规更好叙事**
  敏感台词与设定默认留在本机;对外发出的仅是用户在某个按钮上 **明确触发** 的那次生成请求。机构关心「剧情与素材出不出域」时,客户端架构更容易给出清晰边界。

- **产品心智:工具 vs 入口**
  「云端套壳」常常是聚合入口,换一个模型页等于换一个站;本产品则在客户端内固定 **同一套菜单、同一套设置与能力映射、同一套任务与日志语义**,长期使用成本低,也更像 **正经的生产软件**

---

## 4. 产品与系统概要(技术人员可读作架构)

- **形态**:Windows 等环境下的 **桌面应用**,界面为现代 Web 技术(React 19 + TypeScript 5.9)呈现,与 **本机 Rust 后台服务**(Tauri 2)协同工作,数据主要落在本机。
- **数据**:核心资料使用 **本地 SQLite 数据库**(WAL 模式 + r2d2 连接池)持久保存;数据库采用 **40+ 张表** 覆盖故事结构、画布状态、AI 任务、媒体轨道、权限等全领域;数据库、对外接口与界面之间 **字段命名规则统一**(冻结词表 + SSOT 索引),减少「同名不同义」导致的差错。
- **智能能力**:既支持对接 **云端** 图像、视频、语音等开放平台能力(即梦、可灵、通义万相、Seedance、OpenAI 等),也支持 **本地大模型**(llama.cpp 文本推理、Whisper 语音识别),兼顾联网弹性、离线可能以及隐私敏感场景。
- **运维与排障**:关键操作链路会写入 **本地日志**(tracing 分级日志 + 日志保留策略);涉及后台任务时,从「已提交 → 执行过程 → 结束结果」分段留痕,便于出问题后按时间线追查,而不是只靠口头描述。
- **自动化扩展**:同一套故事与素材的领域模型,还提供 **命令行工具****离线数据库迁移脚本**,便于以后做批处理、脚本或与外部系统对接。

### 4.1 设计上值得单独说的几点

- **用户选定的模型才生效,禁止暗中换通道**
  每一次云端或本地推理,都必须对应用户在当前界面或设置里 **明确选好的服务商与模型**;全局默认值只在「用户尚未选择」时起补充作用。**不允许**对用户没选中的通道自动轮询、悄悄兜底,也不允许例如「参考图失败就无声改成纯文字生图」这类隐蔽替换。这在消费级工具里不常见,但对 **采购合规、成本可归因、结果可复现** 很重要;产品上用统一的模型选择与「记住上次实际使用」的体验,避免多套界面、多套记忆规则打架。

- **最终指令与任务过程可追溯**
  在 **真正发出请求之前**,会把下发给所选模型的 **最终文本指令** 记入可检索日志;纳入任务中心的流程则按 **提交 → 进行中更新 → 结束汇总** 留存。多步骤、多模态的长链路事后可以对齐时间线,有利于长期维护与企业环境交付。

- **故事板:最终台词稿单一来源**
  数据库、接口与界面之间遵循同一套数据约定;分镜故事板里,**最终送给模型的那段提示** 集中在约定的分段内容里统一维护,而不是在多个地方各存一份、时间一长就对不上。这样导出、备份或多端协作时不容易分叉。

- **演员库可以不绑死在某一个故事上**
  「演员」允许作为 **全局可复用资产** 管理,不必先创建某个故事才能建档;跨项目共用肖像与设定时,边界更清晰,后续若做协作或素材库也更容易扩展。

- **设置里的「能力映射」统领全站的模型列表顺序**
  文本、配图、改图、视频、语音等能力,按账号区块与模型行的顺序组成清单,再反映到各功能页的模型下拉列表;顺序与是否隐藏由用户在设置里 **保存****不跟着**厂商网页或偶然的网络返回顺序飘。多家供应商加多台本地模型混用时,这是 **列表可控、心智稳定** 的关键。

- **自研无限画布:为「很多张图 / 很多卡」做的性能策略**
  大面积拖拽、缩放、摆卡片(演员形象墙、场次、分镜浏览、片段画布等)共用一套 **自研画布内核****不依赖**额外的重型第三方画布商业包。做法是分层减负:**只重点处理屏幕附近的内容**(外加一圈缓冲,避免边缘闪烁)、**分批加载**避免一口气创建成百上千张卡片卡住界面、对视野外的元素 **减少无谓绘制**,并对视频、大图在 **离开视野后主动降级或收回资源**,避免「划走了还在后台解码占内存」。缩放以指针为中心、手感一致;瀑布流排布与画布核心分开,多处界面复用同一套交互习惯。内部规格文档中对 **数百个节点** 量级写了性能目标(首次打开耗时、拖动流畅度、内存占用上限),属于「先定体验指标再实现」的基础设施思路。

- **统一 AI 端点注册表与调度层**
  后端 `open_platform` 模块实现统一端点注册表(39 个源文件),即梦、可灵、通义万相、Seedance、OpenAI 等各家接口各异,但业务管线只需调用统一接口。新增厂商只需注册新端点,业务管线零侵入,可持续升级。支持文生图、图生图、图生视频、文生视频、TTS 语音合成、唇形同步等多种生成能力。

- **通用有向图引擎(GraphCore)**
  自研通用图引擎模块,提供有向图的 CRUD、拓扑排序、连通性分析、性能优化等能力,统一支撑分镜故事板、片段画布等多个画布场景的节点连线与关系管理,避免各模块重复造轮子。

- **AI 任务队列与状态机**
  内置完整的 AI 任务队列系统(30 个源文件),含状态机、调度器、分发器、14 种任务类型 Handler、持久化层与事件总线。支持任务并发控制、进度心跳、失败重试、配额管理,面向批量生成场景。

- **本地 AI 能力内置**
  通过 llama.cpp 集成本地文本推理(含 llama-server 灵活模型加载),通过 Whisper 集成本地语音识别。在离线、保密或低成本场景下,核心 AI 能力不依赖云端。

- **权限系统与配额管理**
  内置可插拔权限框架(权限后端、装饰器、审计日志、缓存层),支持用户激活、账号管理、AI 任务日配额控制,面向机构采购与团队使用场景。

- **全链路视频生成管线**
  从分镜图到视频成片,支持多家视频模型(即梦、可灵、Seedance、通义万相等)的统一调度,含视频定价、限流、任务生命周期管理、唇形同步(5 种适配器:Hedra、LivePortrait、MuseTalk、Wav2Lip、可灵)、TTS 语音合成、字幕生成等完整管线。

- **ComfyUI 本地工作流深度集成**
  不仅是简单调用,而是完整集成:HTTP/WebSocket 双协议客户端、工作流扫描与编译器、占位符注入、自定义工作流支持、图像/视频双管线、设置管理等(27 个源文件),让用户可以用 ComfyUI 自定义本地生图/生视频流程。

- **FFmpeg 媒体运行时**
  统一的媒体处理层(12 个源文件),封装 FFmpeg CLI 的定位、参数构建、执行、探测解析,提供媒体能力注册与格式选择,供视频转码、音频提取、字幕合成等全链路使用。

---

## 5. 当前成果(产品与工程)

**功能范围(摘要)**
主要功能页覆盖故事总览、剧集与场次看板、场景与素材管理、分镜故事板与镜头工作台、片段画布(无限画布)、视频片段管理(Clips)、角色与演员、任务中心、帮助学习中心等;设置中提供账号与绑定、**能力与模型映射**、可选本地工作流(如 ComfyUI)、本地模型管理、TTS/视频实验室、诊断与数据存储位置、BUG 报告与日志上云等;界面文案支持中英文。

**研发体量(静态统计,便于理解投入)**

| 类别 | 文件数 | 代码行数(约) |
|------|--------|----------------|
| 后端桌面服务(Rust,src-tauri) | 993 | 18.4 万 |
| 后端核心库(Rust,src) | 24 | 0.19 万 |
| **Rust 合计** | **1017** | **18.6 万** |
| 前端界面组件(TSX) | 466 | 9.7 万 |
| 前端逻辑脚本(TS) | 1497 | 16.6 万 |
| **前端 TS/TSX 合计** | **1963** | **26.3 万** |
| 工具脚本(Python) | 71 | 1.2 万 |
| 工具脚本(PowerShell) | 83 | 0.6 万 |
| **自研程序合计** | **≈ 3134** | **≈ 46.7 万** |
| 内部设计 / 规范 / 记录文档 | ≈ 730 | — |
| 前端测试用例 | — | 1.52 万 |
| Rust 测试用例 | 234 | — |

**技术栈明细**

| 层 | 技术选型 |
|----|----------|
| 桌面壳 | Tauri 2(Rust 进程托管,非 Electron) |
| 前端框架 | React 19.2 + TypeScript 5.9 + Vite 8 |
| 前端测试 | Vitest 4.1 |
| 后端语言 | Rust(edition 2021) |
| 数据库 | SQLite(WAL 模式 + r2d2 连接池) |
| Rust 依赖 | 771 个 crate |
| AI 调度 | 统一端点注册表(open_platform),云端/本地双模式 |
| 本地 AI | llama.cpp(文本推理 + llama-server)+ Whisper(语音识别) |
| 媒体处理 | FFmpeg 集成(视频转码、探测、合成) |
| 图像生成 | 即梦、通义万相、ComfyUI 等 |
| 视频生成 | 即梦、可灵、Seedance、通义万相等 |
| 语音合成 | TTS 管线(多家云端 + 本地) |
| 唇形同步 | 多适配器架构(Hedra、LivePortrait、MuseTalk、Wav2Lip、可灵) |
| 本地工作流 | ComfyUI 完整集成(HTTP/WebSocket、工作流编译器、管线注入) |
| 自动更新 | Tauri Updater(被动安装模式) |
| 权限系统 | 可插拔权限框架 + 日配额管理 + 审计日志 |
| 异步运行时 | Tokio(多线程) |
| HTTP 客户端 | reqwest 0.13(native-tls、HTTP/2、gzip、multipart、stream) |

大量内部文档对应作者在 **数据约定、交互规范、故障排查与版本迁移** 上的持续沉淀,便于长期维护与日后扩展。

---

## 6. 后端核心模块地图

后端(`src-tauri/src`)共 993 个 Rust 源文件,按职责划分为以下核心模块群:

| 模块群 | 关键文件/目录 | 文件数 | 职责 |
|--------|---------------|--------|------|
| **故事管线** | `story_chapter_pipeline`, `chapter_scenes_plan` | — | 故事→剧集→场次的 LLM 级联生成 |
| **分镜引擎** | `storyboard_*`(specs / stage_a / stage_b / merge / rules / render / graph) | — | 分镜生成、导演化语义层、质量门、渲染输出 |
| **故事板合并** | `storyboard_merge/`(prompt_assembler / consistency_context / shot_conditioning_merge / pad_resolve / block_registry) | 8 | 提示词组装、一致性上下文、镜头条件合并 |
| **AI 提示词** | `ai_prompts/`(builtins×25+ / render / types / registry) | 38 | 内置提示词模板库、渲染引擎、类型定义、注册表 |
| **AI 任务队列** | `ai_queue/`(state_machine / scheduler / dispatcher / facade / events / persistence / handlers×14) | 30 | 完整任务队列:状态机、调度、分发、14 种 Handler、持久化 |
| **开放平台** | `open_platform/`(provider / dispatch / gen_error / provider_metadata / tts / jimeng / volc_* / kling_* / dashscope_* / qwen / seedance) | 39 | 统一端点注册表、多厂商适配、错误归一化 |
| **图像生成** | `image_generation`, `commands/image/`(task_lifecycle / video / dialogue / placeholders / commands×8) | 20+ | 生图管线、任务生命周期、视频提交 |
| **视频管线** | `video_task`, `video_task_poller`, `video_param_mapper`, `video_rate_limiter`, `video_pricing`, `segment_video_pipeline`, `video_delivery`, `video_prompt_compiler`, `video_prompt_pipeline` | — | 视频任务调度、轮询、参数映射、限流、定价、提示词编译 |
| **ComfyUI** | `comfyui/`(client / commands / pipeline / workflow / http / settings / analyzer) | 27 | 本地 ComfyUI 完整集成(双协议、编译器、管线) |
| **本地 AI** | `local_ai/`(text_generation / speech_recognition / llama_server / model_manager / types) | 6 | llama.cpp 文本推理、Whisper 语音识别、模型管理 |
| **语音与唇形** | `audio_pipeline`, `stt_pipeline`, `subtitle_pipeline`, `tts`, `lipsync_provider/`(factory / hedra / kling / liveportrait / musetalk / wav2lip) | 7 | TTS、语音识别、字幕、5 种唇形同步适配器 |
| **角色与演员** | `role_nodes`, `role_physique`, `role_portrait_supplement`, `portrait_*`, `visual_asset/`, `role_display_name` | 12+ | 角色管理、体型管线、肖像版本链、场景/道具资产、显示名 |
| **片段画布** | `segment_canvas/`(commands / queries / types / utils / canvas_commands×8 / grouping) | 16 | 无限画布引擎、画布状态持久化、快照、迁移 |
| **Clips 片段** | `clips/`(commands×11 / types / clip_video_meta) | 17 | 视频片段 CRUD、导入、导出、画布、视频绑定 |
| **图引擎** | `graph_core/`(engine / runtime / store / types / perf) | 6 | 通用有向图引擎,支撑分镜与片段画布 |
| **媒体运行时** | `media_runtime/`(ffmpeg_cli / service / registry / selector / capabilities) | 12 | FFmpeg 集成、媒体能力注册、格式探测 |
| **权限与安全** | `permission/`(mod / backends / decorator / integration / db_migrations / example), `authz`, `credential_crypto`, `quota_guard` | 7+ | 可插拔权限框架、授权、凭证加密、配额管理 |
| **数据库** | `db/`(schema / pool / backup / migrations×15+ / model_catalog_repo), `migration/` | 42 | SQLite 迁移(40+ 张表)、连接池、备份、模型目录 |
| **运维** | `log_init`, `disk_cleanup`, `bug_report`, `app_update_*` | — | 日志、磁盘清理、BUG 报告打包上传、自动更新 |

---

## 7. 前端核心模块地图

前端(`ui/src`)共 1963 个 TSX/TS 源文件,按职责划分为以下核心模块群:

| 模块群 | 关键目录 | 职责 |
|--------|----------|------|
| **故事 Tab** | `components/story-tab/` | 故事总览、剧集列表、导出脚本 |
| **剧集 Tab** | `components/chapter-tab/`(panels / sections / modals / hooks) | 剧集看板、场次规划、关键帧、批量生成 |
| **场次 Tab** | `components/scene-tab/` | 场次列表、上下文菜单、加载态 |
| **分镜工作台** | `components/storyboard/`(panels / modals / hooks / history / graph) | 分镜故事板、镜头工作台、AI 提示词版本历史 |
| **片段画布** | `components/segment-canvas/`(graph / domain / transitions) | 无限画布、图推导、撤销重做、瓦片同步 |
| **分镜画布** | `components/storyboard-shot-canvas/`(renderers / overlays / handlers / minimap) | 分镜节点画布、边渲染、缩放控件 |
| **角色 Tab** | `features/character-tab/`(canvas / editor / actor-list / columns / layout / ai / pads) | 角色管理、演员列表、定妆照画布、AI 生成 |
| **角色 Tab** | `features/role-tab/`(canvas / detail / hooks / modals / lightbox / portrait-pads / domain / ai) | 角色详情、肖像灯箱、批量肖像生成 |
| **Clips 片段** | `clips/`(ClipsCanvas / ClipsNodeEditor / ClipsMinimap / ClipsVideoPreview / ClipsImportModal / ClipsExportAllModal) | 片段画布、节点编辑、导入导出、视频预览 |
| **设置 Tab** | `components/settings-tab/` / `components/settings/` | 账号、能力映射、ComfyUI、本地模型、TTS/视频实验室、数据迁移 |
| **帮助模块** | `help-module/` | 学习中心、引导 |
| **认证** | `auth/` | 登录、注册、密码重置、Token 管理 |
| **UI 组件库** | `components/ui-*`(modal / toast / panel / form / icon / list / lightbox / edge-resize-shell / chrome-textarea / misc) | 通用 UI 原子组件 |
| **无限画布内核** | `infinite-canvas/`(InfiniteCanvas / components / hooks / utils / layout / canvas-chrome) | 自研画布引擎:四叉树空间索引、masonry 布局、虚拟化渲染、缩放平移、瓦片边框、持久化 |
| **领域逻辑** | `domain/`(model-surfaces / local-media-upload / audio / imageGenWarnings / multi-view / reference-pad) | 模型选择编解码、上传队列、音频、生成警告、多视角生成、参考面板 |
| **API 层** | `api/`(graphApi / migration / segmentCanvasV2Api / clipFramework) | Tauri IPC 调用封装 |
| **系统** | `system/`(form-control-clipboard / selectable-copy) | 右键复制粘贴、可选复制 |

---

## 8. 数据架构概览

本地 SQLite 数据库采用 **幂等迁移** 策略(`CREATE TABLE IF NOT EXISTS`),当前包含 **40+ 张表**,按领域分组:

| 领域 | 核心表 | 说明 |
|------|--------|------|
| **故事结构** | `stories`, `nodes`, `edges`, `node_chapter_order` | 故事→剧集→场次→片段的层级图 |
| **画布状态** | `segment_canvas_node`, `segment_canvas_edge`, `segment_canvas_layout_state`, `segment_canvas_view_state`, `segment_canvas_snapshot`, `segment_canvas_file_ref`, `segment_canvas_delete_audit`, `segment_canvas_placement_order` | 片段画布全量持久化 |
| **AI 任务** | `ai_tasks`, `ai_queue_tasks`, `ai_queue_task_events` | 任务记录 + 队列持久化 + 事件流 |
| **分镜** | `storyboard_graph_state`, `storyboard_shot_specs`, `storyboard_scene_revision` | 分镜图状态、镜头规格、场次修订 |
| **角色与资产** | `assets`, `scene_assets`, `prop_assets`, `role_portrait_versions`, `portrait_last_generations` | 全局资产、场景/道具资产、肖像版本链 |
| **内容历史** | `node_content_history`, `story_content_history`, `scene_asset_content_history`, `prop_asset_content_history`, `video_workbench_session_history` | 版本回溯、撤销依据 |
| **Clips** | `clips`, `clip_edges`, `clip_framework_index`, `clips_canvas_viewport`, `clips_canvas_tile_pos`, `clips_canvas_placement_order` | 视频片段图、画布视口、排列 |
| **媒体轨道** | `audio_tracks`, `dialogue_tracks`, `lipsync_providers` | 音频轨、对话轨、唇形同步供应商 |
| **模型配置** | `model_official_catalog`, `model_capability_catalog`, `app_user_settings` | 官方模型目录、能力目录、用户设置 |
| **权限** | `user_permissions`, `permission_audit_log`, `user_permissions_cache` | 用户权限、审计日志、缓存 |
| **布局** | `actor_list_layout`, `story_node_list_layout`, `chapter_scene_list_layout`, `scene_asset_list_layout`, `prop_asset_list_layout` | 各列表拖拽排序持久化 |
| **图引擎** | `graph_core_graph` | 通用有向图持久化 |
| **其他** | `user_tier_cloud`, `task_running_wait_tips`, `dialogue_tracks`, `video_workbench_session_history` | 云端用户层级、运行提示、对话轨 |

---

## 9. 近期重点更新(v0.1.530 → v0.1.615)

自 2026-05-30 统计以来,10 天内完成 70+ 次提交,净增约 11 万行自研代码。重点更新包括:

### 9.1 画布架构升级(v0.1.608 → v0.1.615)

- **画布连线 SSOT 统一**(v0.1.608):新增 `canvas-connector` 模块,移除旧 edgeDrag/linkDrag 系统,实现片段画布、分镜画布等多处画布的连线逻辑统一
- **画布删除可逆性与 Ctrl+Z 撤销重做**:完整的撤销重做栈,支持画布节点删除恢复
- **画布连线与输入端口 UI 全仓统一**:破坏性重构,统一所有画布的连线交互与端口样式
- **面板弹出多屏架构**:支持画布面板弹出为独立窗口,实现多屏协作工作流
- **画布缩放工具条全仓统一**:片段画布、分镜画布等多处画布的缩放控件统一为一致的工具条样式

### 9.2 提示词工程治理(v0.1.610)

- **全仓提示词工程 SSOT**:建立五层 UPEA(User Prompt Engineering Architecture)架构,17 条 SSOT 入口
- **视觉样式词表统一**`visual_style` lexicon 词表 SSOT,negative prompt 统一管理
- **CI 门禁脚本**`check-prompt-ssot-index.ps1` + `check-visual-style-lexicon.ps1` 接入预发布检查

### 9.3 角色与资产系统增强(v0.1.612)

- **角色卡片 Hover 扇形展开形象照**(v0.1.606):角色列表卡片悬浮时以扇形动画展示关联形象照
- **资产图生图参考图记忆独立模块**`asset-i2i-pad-memory` 模块,Envelope v4 尾块持久化
- **视觉资产生图全通道解绑故事 ID**:共用资产不再要求绑定故事即可生图
- **角色定妆参考图 Tab 分类名称 Hover 筛选下拉**:参考图选择器增强

### 9.4 工程基建(v0.1.613)

- **字号 SSOT CSS 变量 + TS 引用层 + 门禁脚本**:Y0 基建,统一全仓字号管理
- **跨平台基础架构升级**(desktop X0-X5):PlatformPaths/ProcessExecutor/AiCapabilities trait 抽象,为 iOS/iPad 支持奠基
- **外挂运行时统一目录**`runtimes/` 目录统一管理 llama.cpp、Whisper 等外挂运行时
- **应用更新静默后台下载与断点续传**:改进更新体验

### 9.5 其他改进

- **分镜号独立列与改号弹框**:分镜列表中分镜号独立展示,支持弹框修改编号
- **视频工作台优化**:能力冲突检测、pad-aware 默认值协调、工作台提示计算、警告横幅
- **模型选择器升级**:生成视频工作台模型选择体验优化
- **全局助手独立窗口**:Chat 后端与 AgentLoop 架构设计
- **全局 Ctrl+S 统一保存功能**:跨模块统一保存快捷键

---

## 10. 未来与演进方向

### 10.1 跨平台架构升级(iOS/iPad 支持)

已启动跨平台基础架构升级,目标是让产品能在 iPad 上运行。核心改造包括:

- **PlatformPaths trait**:抽象文件系统访问,替换 144 个文件的直接 `std::fs` 调用
- **ProcessExecutor trait**:抽象外部进程调用,iOS 上全部走云端降级
- **AiPlatformCapabilities trait**:iOS 禁用本地 AI(llama/TTS/whisper),自动降级到云端
- **配置源抽象**:iOS 无环境变量,改用 bundled config + NSUserDefaults

预估工期 14 周(~3.5 个月),已完 desktop X0-X5 阶段基础架构搭建。

### 10.2 本地 TTS 引擎框架整合

正在构建可扩展的本地 TTS 引擎架构,支持 VoxCPM、IndexTTS 等多种本地语音合成模型:

- **adapter 架构**:统一的 TTS 适配器接口,支持云端/本地双模式
- **对白合成管线**:Phase 5 对白合成与 adapter 架构整合
- **TTS 语音合成工作台**:模型区一致性与可扩展架构

### 10.3 持久化层六边形架构升级

规划将持久化层升级为六边形架构(端口-适配器模式),提升代码可测试性与可维护性:

- **端口抽象**:定义领域层与基础设施层的清晰边界
- **适配器实现**:SQLite、内存、文件系统等多种持久化后端
- **依赖反转**:领域层不依赖具体持久化实现

### 10.4 产品演进

- **分镜与生成一体化**:强化分镜与生成的一体化体验,批量任务、模板与复用
- **更多云端能力接入**:按场景接入更多云端能力与本地模型组合
- **NLE 时间线导出**:NLE 时间线 XML 导出对接专业剪辑软件(Final Cut Pro、DaVinci Resolve、Premiere Pro)
- **全局助手**:Chat 后端与 AgentLoop 架构,提供 AI 辅助创作体验

### 10.5 工程演进

- **四层分层重构**:持续 domain / application / infrastructure / composition 四层分层重构
- **松耦合对接**:与云端素材、协同类产品探索松耦合对接(本地工程仍是权威数据源)
- **全仓颜色主题模块**:统一的深色/浅色主题切换系统

### 10.6 生态演进

- **可信、可选、可审计**:持续面向中文创作者工作流,向可信、可选、可审计的多模态前期工具链演进
- **模板市场**:灯光/风格预设、分镜模板、角色外观包的社区分享
- **云端渲染农场**:大模型推理卸载到云端,桌面端保持低功耗

---

*代码仓库内另行维护更细的技术约束与模块说明(约 730 篇内部文档),供开发与测试使用;本文不展开。*

比格熊数字导演工作站 — 用一句话,拍一部片

> 你有一个好故事,但不会画画、不会剪辑、不会建模。
> 比格熊帮你把「一句话创意」变成完整的分镜、视频、对白——全在同一台电脑上完成。

---

## 一句话说清楚

比格熊是一个 **装在你电脑上的 AI 导演工具**

不是网页,不是在线白板,不是 API 聚合器。
是一个正儿八经的桌面软件——打开就能用,关了数据还在,断网也不怕。

---

## 它能帮你做什么?

### 🎬 从故事到成片,一条链走完

你只需要输入一个故事想法,比格熊会自动帮你:

1. **扩展成完整故事** — 角色、情节、冲突、转折,AI 帮你构思
2. **拆成剧集和场次** — 像真正的制片流程一样,把故事结构化
3. **生成分镜故事板** — 每个镜头都有景别、角度、运镜、角色走位
4. **批量生成图片和视频** — 对接即梦、可灵、通义万相、Seedance 等多家模型
5. **配音和字幕** — TTS 语音合成 + 唇形同步,角色能开口说话
6. **导出交付** — 视频片段、分镜图、剧本,随时导出

**从第一句话到最终成片,不用切换任何其他工具。**

### 🎭 角色是活的,不是一张图

在比格熊里,角色不是贴在白板上的一张图片。每个角色有自己的:

- **多角度定妆照** — 正面、侧面、3/4 视角,一次生成多张
- **体型与外貌设定** — 系统记住你的角色长什么样
- **跨场景一致性** — 换场次、换镜头,角色还是那个人
- **全局资产库** — 角色不绑死在一个故事里,跨项目复用

你设定好的角色,会贯穿整部作品的每一个镜头。

### 🖥️ 全部在你电脑上完成

比格熊是 **本地桌面软件**,这意味着:

- ✅ **数据在你手里** — 故事、剧本、素材全部存在你自己的电脑上
- ✅ **关掉不丢失** — 不像网页,关了浏览器还在
- ✅ **断网也能用** — 本地大模型(llama.cpp、Whisper)离线也能跑
- ✅ **隐私有保障** — 敏感剧本不会自动上传到任何地方
- ✅ **不绑账号** — 云端 AI 是可选的,不是必须的

### 🎨 你选什么模型,就用什么模型

比格熊对接了多家 AI 能力:

| 能力 | 可选模型 |
|------|----------|
| 文本生成 | OpenAI、本地 llama.cpp 等 |
| 图片生成 | 即梦、通义万相、ComfyUI 等 |
| 视频生成 | 即梦、可灵、Seedance、通义万相等 |
| 语音合成 | 多家 TTS + 本地方案 |
| 唇形同步 | Hedra、LivePortrait、MuseTalk 等 5 种 |

**关键是:你选了什么,系统就用什么。** 不会偷偷换通道,不会静默兜底。每一次生成,都明确对应你选定的模型。

---

## 为什么不是网页工具?

市面上有很多"AI 分镜"、"AI 故事板"的在线工具。它们能做的是:

> 你写一句话 → AI 出一张图 → 排在白板上 → 结束

比格熊做的是:

> 你写一句话 → 故事展开 → 剧集规划 → 场次拆解 → 分镜工程 → 批量生图/生视频 → 配音 → 成片

**白板给你一块布,比格熊给你一台机器。**

而且这台机器装在你电脑上,不依赖任何网站的存活。你的工程文件就是你的,拷到另一台电脑上照样打开。

---

## 技术上有多认真?

> 这一段给想深挖的朋友看。不想看技术细节?跳过就行,不影响你用。

### 🔌 全量模型接入:市面上主流 AI,一个不落

比格熊不是"只能用一两家模型"的小工具。它**全量接入**了当前市面上的主流 AI 能力:

| 能力 | 已接入模型 |
|------|-----------|
| 文本生成 | OpenAI、本地 llama.cpp 等 |
| 图片生成 | 即梦、通义万相、ComfyUI 等 |
| 视频生成 | 即梦、可灵、Seedance、通义万相等 |
| 语音合成 | 多家云端 TTS + 本地方案 |
| 唇形同步 | Hedra、LivePortrait、MuseTalk、Wav2Lip、可灵 — 5 种适配器 |

而且接入方式不是"能调 API 就行"。每家模型的接口都不一样,比格熊内部做了一层**统一端点注册表**——所有业务管线只认统一接口,厂商差异全部封装在底层。

这就像一个**万能插座**:不管你插的是国产电器还是进口电器,插座的形状是一样的。新增一家模型厂商,业务层零改动,注册一个新端点就完事。

更关键的是:**你选了什么模型,系统就用什么模型。** 不会偷偷换通道,不会静默兜底。没有适配过的模型宁可报错也不给你废图。

**今天能用的模型,明天全部能用。明天出来的模型,后天就能接上。**

### 🧩 高内聚,低耦合:改一块,不动其他

这是比格熊架构设计的核心哲学。用大白话说:

**高内聚** = 每个模块只管自己的事,把相关的功能紧紧聚在一起。
**低耦合** = 模块之间尽量不互相依赖,改一个不会牵连一大片。

在比格熊里,这句话体现在每一个层面:

**故事 → 剧集 → 场次 → 片段 → 分镜,每一层都是独立的。**

- 你改了一个片段的镜头,不会影响同一场次里其他片段
- 你重新规划了一集的场次,不会破坏已经画好的分镜
- 你换了一个角色的形象,所有引用该角色的地方自动更新,但故事结构纹丝不动
- 你删了一个场景,不会牵连到其他场景的素材

每个层级就像**乐高积木**——每块积木是完整的、独立的,但拼在一起就是一座城堡。你可以随时拆掉一块、换掉一块、加一块,城堡的其余部分稳如磐石。

**这不是"碰巧能用",是"设计成必须这样"。** 从第一天起,比格熊的数据结构、接口规范、模块边界就是按这个原则搭的。

### 🎯 四层分离:每一层只干自己的事

比格熊的后端不是一坨"什么都往里塞"的大杂烩。它分成清晰的四层:

- **领域层** — 只管"是什么":故事是什么、镜头是什么、角色是什么。纯粹的业务概念,不关心数据存在哪里、不关心怎么展示。
- **应用层** — 只管"做什么":生成一集分镜、提交一个视频任务、更新一段对白。编排业务流程,但不亲自干活。
- **基础设施层** — 只管"怎么存、怎么调":数据库怎么读写、云端 API 怎么对接、本地文件怎么管理。所有"外部世界"的细节都封装在这里。
- **组装层** — 把上面三层拼起来,让应用能跑起来。

四层分离意味着:**换一个数据库,业务逻辑不用改;换一家云服务商,存储层不用动;加一个新功能,只需要在对应的那一层加,不会牵一发动全身。**

这不是"凑合着分开",是**严格的单向依赖**——上层知道下层,下层不知道上层。就像一栋楼:三楼知道有二楼,但二楼不知道三楼长什么样。加一个四楼,二楼完全不受影响。

### 🏷️ 一个名字,全局统一:冻结词表

在很多软件里,同一个东西在数据库叫一个名字、在接口里叫另一个、在界面上又叫第三个——时间一长,谁也搞不清哪个是哪个。

比格熊从第一天起就锁定了**一套冻结词表**:故事、剧集、场次、片段——从数据库到接口到界面,**同一个概念只有一个名字**,全局统一,不可随意改动。

这不是洁癖,是**工程可靠性**的基石:改一个地方不会因为名字对不上而悄悄出 Bug。

### 🎬 双脑分镜:导演脑 + 工程脑

比格熊生成分镜不是"AI 随便画一张图"。每个镜头经过**两层大脑**处理:

- **导演脑(语义层)**——理解剧本,拆出镜头语言:景别、机位角度、运镜方式、角色走位、身体朝向、视线方向、对白模式……这些是影视工业几十年积累的专业概念,不是随机排列。
- **工程脑(渲染层)**——把导演语义翻译成画面可执行的结构化参数:构图锚点、头部空间、鼻前空间、纵深层次、光线方向、轴线规则……

两层分开的好处:导演语义可以反复调整,不用每次从头重画;工程参数可以批量替换,换一套渲染风格只需改工程脑,不用动导演脑。

**这不是"AI 帮你画画",是"AI 帮你当导演"。**

### 🎯 叙事保真协议(NFP):AI 帮你守规矩

比格熊内置了一套**结构化违规检查系统**

每集剧本会自动对照 NFP 规则做逐条检查——戏剧弧位是否完整、冲突类型是否合理、节奏目标是否匹配、转场方式是否连贯。检查结果不是笼统的"写得不好",而是精确到**规则 ID + 违规依据 + 逐条列出**

对话场景还有**自动质检**:必须有 master 镜、双方各有 OTS 和 reaction 镜——这是好莱坞几十年的覆盖拍摄规范,系统会自动检查并补全。

**AI 不只是帮你写故事,还帮你守规矩。**

### 🕸️ 通用有向图引擎:故事结构不是树,是网

传统的项目管理工具用"文件夹"组织内容——一层套一层,像树状目录。但故事不是这样的:角色跨集出场、场景跨章引用、镜头之间有因果和并行关系。

比格熊内置了一个**自研的通用有向图引擎**,用节点和连线来表达故事结构。每个节点可以连接任意多个其他节点,支持拓扑排序、连通性分析、环路检测。

而且这套引擎是**通用的**——分镜故事板、片段画布、Clips 片段管理——所有涉及"关系"的场景,共用同一套图引擎。**造一次,用五处。**

**故事是网状的,比格熊用网状的方式理解它。**

### ⚡ 自研画布内核:现在的性能,未来的想象

市面上的无限画布工具,拖几十张卡片就开始卡。比格熊的画布是**完全自研**的,不依赖任何第三方商业画布包:

- **虚拟渲染**——只处理屏幕上的内容,视野外的卡片不画
- **分批加载**——几百张图不会一次性涌入,按需加载
- **视野外降级**——视频、大图离开视野后自动释放资源,不白占内存
- **指针中心缩放**——以鼠标位置为中心缩放,手感一致不跳帧

而且这套画布内核是**通用的**——片段画布、分镜画布、角色画布、场景画布、参考图画布,五种画布共用同一套引擎。**改一处交互,五处同时受益。**

但这只是起点。因为画布内核是自研的,**没有天花板**。未来想在画布上加什么能力——多人实时协作、3D 预览、时间线轨道、音频波形可视化——只需要在自己的引擎上扩展,不用等第三方厂商更新,不用受别人的架构限制。

**自研引擎的好处不是"现在够用",是"未来想做什么就能做什么"。**

### 🤖 AI 任务队列:加一种能力,只写一个文件

比格熊的 AI 任务系统不是"调一个 API 等结果"那么简单。它有一套完整的**任务生命周期管理**

- **状态机** — 每个任务有明确的状态流转:排队 → 执行中 → 成功/失败/取消
- **调度器** — 多个任务自动排队、并发控制、配额管理
- **持久化** — 任务记录落盘,关掉软件再打开,任务状态还在
- **事件总线** — 任务状态变化实时通知前端,进度条不是假的

最厉害的是**扩展方式**:已经支持 14 种不同的 AI 任务类型(文生图、图生图、视频生成、语音合成、唇形同步……),每种任务只需要注册一个 Handler,调度、排队、持久化、前端通知——全部自动生效。

**加一种新的 AI 能力,就像往书架上放一本新书——书架不用重建。**

### 🏗️ 41.6 万行,造的是机器

| 类别 | 规模 |
|------|------|
| 自研代码 | 41.6 万行,2642 个文件 |
| 后端模块 | 52 个独立模块,各司其职,互不侵入 |
| 前端组件 | 48 个顶层功能模块 |
| AI 任务类型 | 14 种,每种独立 Handler,新增即插即用 |
| 内部文档 | 730 篇设计规范、交互约定、故障排查手册 |

### 🔮 无限扩展空间:这才是真正的护城河

以上所有设计——全量模型接入、高内聚低耦合、四层分离、冻结词表、通用图引擎、自研画布——它们单独看是"技术亮点",**拼在一起才是真正的力量**

因为这套架构,比格熊可以:

- **今天接 5 家模型,明天接 50 家** — 统一端点注册表,接一家只需注册一个端点
- **今天支持 14 种任务,明天支持 140 种** — 任务队列是插件式的,加一种只写一个 Handler
- **今天 5 种画布,明天 50 种** — 画布内核是通用的,新画布只管内容,不管交互
- **今天是一个人做,明天是一个团队做** — 四层分离 + 冻结词表,新人只需理解自己负责的那一层
- **今天是桌面端,明天可能是 Web 端或移动端** — 领域层和应用层不依赖任何具体的界面技术

**架构决定上限。比格熊的上限,远不止你现在看到的样子。**

**这不是一个周末项目。这是一个人、从零开始、持续迭代的正经生产软件。**

---

## 适合谁用?

- 🎬 **独立创作者** — 一个人也能产出完整的分镜和视频草稿
- 📹 **短视频团队** — 批量试制 AI 辅助前期,快速验证创意
- 🎓 **影视院校** — 学生在可控环境下练习分镜和导演思维
- 📖 **网文/漫画作者** — 把文字故事可视化,试拍"纸上电影"
- 🏢 **内容机构** — 数据不出域、操作可追溯、模型可审计

---

## 现在就试试

比格熊数字导演工作站,Windows 桌面客户端,本地安装,即开即用。

📦 下载地址:
https://pan.baidu.com/s/1URSWFhfrTS6kDQQH6q53iw?pwd=0000
https://pan.quark.cn/s/403c6fec8151
[bgxiong.com](https://www.bgxiong.com)

**你的故事。你的数据。你的选择。**
*41.6 万行自研代码,不是套壳,不是聚合器。是一个人从零开始造的机器。*

当所有人都在做"AI 白板",我们做了一座"数字导演工作站

## 市面上的无限画布,到底在画什么?

打开 Product Hunt 或者各大 AI 工具站,搜"AI storyboard"、"infinite canvas",你会看到一大堆产品——Miro、FigJam、LTX Studio、Katalist、Boords……它们有一个共同点:

**画布是通用的,故事是附属的。**

什么意思?这些工具本质上是**白板**——你可以往上面贴便签、贴图片、贴链接,AI 帮你生成几张分镜图,排列整齐,然后呢?然后就没有然后了。

你的故事结构在哪里?角色关系在哪里?镜头语言在哪里?对白归属在哪里?

**它们给你一块布,但不给你一台机器。**

---

## 比格熊的本质区别:不是"画布 + AI",是"工业管线 + 画布"

比格熊数字导演工作站从第一天起,就不是在做一块"更聪明的白板"。

我们做的是一个**完整的故事生产管线**,画布只是这个管线的一个交互界面:

```
一句话创意 → 故事种子扩展 → 剧集规划 → 场次拆解 → 分镜语义规格 → 渲染规格 → 生图/生视频 → 对白音频 → 成片
```

这条链路上的每一步,都有**结构化的数据契约****可追溯的任务记录****用户明确选定的模型通道**

市面工具给你的是:`文本 → AI → 图片 → 排列`
比格熊给你的是:`创意 → 剧本 → 导演语义 → 分镜工程 → 多模态生成 → 工程化交付`

**这不是同一个物种。**

---

## 三大绝对优势,每一项都是硬基建

### 一、本地优先,数据主权在你手里

比格熊是一个**安装在电脑上的桌面客户端**(Tauri 2,不是 Electron 套壳),你的故事、剧本、分镜、任务记录全部落在**本地 SQLite 数据库**

- 关闭浏览器不会丢工作
- 清理 Cookie 不会清空项目
- 某家网站下线不会带走你的资产
- 断网、弱网、保密环境,照样能编辑工程、跑本地推理

云端 AI 只是"可选外挂",不是"唯一脊梁"。你可以用即梦、可灵、通义万相、Seedance、OpenAI,也可以用本地的 llama.cpp 和 Whisper。**你的选择才生效,系统不会暗中替你换通道。**

这一点,对机构采购、合规审查、成本归因来说,不是锦上添花,是**刚性需求**

### 二、34.6 万行自研代码,不是套壳 API 聚合器

很多人以为"AI 工具"就是调几个 API,拼一个界面。比格熊的代码规模:

| 类别 | 文件数 | 行数 |
|------|--------|------|
| Rust 后端 | 748 | 13.96 万 |
| TSX 前端 | 401 | 8.01 万 |
| TS 逻辑层 | 1134 | 12.01 万 |
| **合计** | **≈2333** | **≈34.6 万** |

这不是一个周末项目。这是一个人、从零开始、持续迭代的**正经生产软件**

后端有 domain/application/infrastructure/composition 四层分层架构;前端有统一的 Entity Host AI 任务锁、模型选择器厂牌优先二级菜单、画布输入端口布局引擎 Rust SSOT;整条视频生成管线有厂商专属 profile、压缩、lint、参考媒体索引——**未知厂商硬失败,不兜底**

这不是"调 API",这是**造机器**

### 三、自研无限画布内核,为"大量节点"而生

市面的无限画布工具,拖几十张卡片就开始卡。比格熊的画布内核是**完全自研**的,不依赖任何重型第三方商业包:

- **虚拟渲染**:只重点处理屏幕附近的内容(外加一圈缓冲,避免边缘闪烁)
- **分批加载**:避免一口气创建成百上千张卡片卡住界面
- **视野外降级**:视频、大图离开视野后主动降级或收回资源
- **指针中心缩放**:手感一致,不会跳帧

内部规格对**数百个节点**量级写了性能目标——先定体验指标,再实现。这是基础设施思路,不是"能用就行"。

---

## 对文学剧本的尊重,藏在每一个提示词里

这是比格熊最被低估的部分。

市面工具的"AI 分镜"通常是:你写一句话,AI 出一张图。完事。

比格熊不是。我们把**影视工业的专业语言**编码进了整个系统:

**分镜有两层大脑:**
- **Stage A — 导演脑(语义层)**:把剧本拆成连贯的分镜语义规格。每个镜头包含景别(shotSizeId)、机位角度(angleId)、运镜方式(movementId)、覆盖关系(coverageRoleId)、角色走位(screenSlotId)、身体朝向(bodyOrientationId)、视线方向(gazeTarget)、对白模式(dialogueMode)、结构化台词(dialogueLines)……
- **Stage B — 工程脑(渲染层)**:把语义规格转成可渲染的结构化数据——构图锚点、头部空间、鼻前空间、纵深层次、光线方向、屏向一致性、轴线规则……

**对白场有自动质检:**
对话场景必须有 master 镜、双方各有 OTS 和 reaction 镜——这是好莱坞几十年的覆盖拍摄规范,系统会自动检查并补全。

**有 NFP(叙事保真协议):**
每集剧本会对照 NFP 规则做结构化违规检查——规则 ID、违规依据、逐条列出。这不是"AI 帮你写故事",这是**AI 帮你守规矩**

**戏剧元数据是结构化的:**
剧集规划输出包含戏剧弧位(setup/rising_action/midpoint/climax/resolution)、冲突类型(internal/interpersonal/external/dilemma)、节奏目标(slow/medium/fast/staccato)、转场方式(cut/dissolve/fade/smash_cut/match_cut)……

**视频提示词有厂商专属 profile:**
不是所有视频模型都能听懂同一种提示词。比格熊为 Seedance、Kling Omni、阿里万象、即梦豆包分别维护了专属的提示词优化管线——压缩、lint、中文角色走位输出,**未知厂商硬失败,不兜底**

---

## 说到底,我们做的是什么?

市面工具在做的是:**降低"看"的门槛**——让不会画画的人也能看到画面。

比格熊做的是:**降低"拍"的门槛**——让不会拍片的人也能产出可交付的制作管线。

从一句话创意,到剧集大纲、场次拆解、分镜工程、角色资产、多视角定妆照、视频成片、对白音频——全链路在同一套本地工程里闭环。

**不是给你一块布让你画画。是给你一台机器让你拍片。**

---

## 📦 现在就体验

比格熊数字导演工作站,Windows 桌面客户端,本地安装,即开即用。

支持即梦、可灵、通义万相、Seedance、OpenAI 等多家云端模型,也支持本地 llama.cpp + Whisper 离线推理。

**你的故事,你的数据,你的选择。**

🔗 [bgxiong.com](https://www.bgxiong.com)

---

*一个人,34.6 万行代码,从零到一。不是套壳,不是聚合器,是造机器。*

使用OpenAI协议接入即梦、可灵等官方API,会不会能力被阉割?

OpenAI 的 API 协议是围绕 文本对话 LLM 设计的,messages → role/content 这个结构天然适合文本交互。但图像/视频生成模型的参数结构和它差异很大。

具体会丢什么能力

从你项目里接入的三家来看:

1. 多图输入 + 多图输出

即梦 4.0 支持一次输入最多 10 张图、输出最多 15 张关联图(组图/分镜)。OpenAI 的 /v1/images/generations 只有一个 image 字段(单张参考图)和 n(生成数量),没法表达"多张参考图各自扮演不同角色"这种语义。

2. 框选区域编辑(bbox)

万相 2.7 的 bbox_list 支持指定图片的哪些区域需要编辑,这是交互式编辑的核心能力。OpenAI 协议完全没有这个概念。

3. 参考类型区分

可灵的 image_reference 区分 subject(角色特征参考)和 face(人脸参考),直接影响生成策略。OpenAI 的 image 参数没有这个维度。

4. 高级生成控制

能力万相/即梦/可灵原生支持OpenAI 协议
组图模式(enable_sequential
思考模式(thinking_mode
色彩主题(color_palette
负向提示词(negative_prompt❌(DALL-E 不暴露)
智能比例适配只有 size 字段
4K 超高清输出受限

5. 视频生成完全没覆盖

OpenAI 协议根本没有视频生成的标准端点。你项目里的可灵视频、即梦视频、万相视频、火山 Seedance 等全部无法走 OpenAI 协议。

实际情况

其实各家的 API 也都不统一——即梦用自己的格式、万相走 DashScope 格式、可灵的 /v1/images/generations 算是"半兼容"但加了大量自定义字段。所以并不存在一个"OpenAI 兼容"的统一方案能通吃所有能力。

对项目的建议

如果要最大化利用各模型的能力,应该走各家官方 API,为每个 provider 写适配层。OpenAI 兼容协议适合的场景是:

  • 纯文本对话(各家 LLM 大部分都兼容)
  • 最基础的文生图(只需要 prompt + size 的简单场景)

但对于你项目这种需要多图参考、组图生成、视频生成的创作工具,OpenAI 协议会成为一个能力瓶颈。

V0.1.601 更新日志

一、重大新功能

1. 视频生成全链路

  • 视频生成工作台:三栏 UX(左栏输入/中栏预览/右栏参数),支持即梦、Seedance、万相 wan2.7、HappyHorse 等多模型
  • 万相 wan2.7 全量接入:R2V 参考生视频、I2V 图生视频、首尾帧模型切换
  • DashScope 视频管线:HappyHorse t2v/r2v/i2v 全量接入,UI 成片参数合并
  • 视频 Prompt 编译器:分隔符编译、超长 UI 预警、文本模型压缩
  • 片段画布视频瓦片:生成态、长任务恢复、缩略图修复
  • 片段视频导出:NLE 时间线 XML 导出规划

2. 对白/语音系统(Phase 1)

  • 对白编辑器:四入口(右栏 Tab / 分镜快捷块 / 右键「编辑对白」/ 瓦片 footer 气泡)
  • 批量 TTSsubmit_segment_dialogue_tts 批量语音合成
  • Entity Host 锁/取消:对白任务锁定与取消机制

3. 模型选择器 v5 重构

  • controller 化:五通道 Picker(Text/ImageT2i/ImageI2i/Video/Keyframe)统一 controller 模式
  • 能力卡片 SSOT:模型能力真相源、per-model 精确行、官方简介统一
  • 偏好持久化:记住上次选择的模型、镜头语言参数

4. 激活与权限系统

  • 两档配额:用户等级云端下放、本地缓存对齐
  • DashScope 激活入口:兑换/购后激活闭环
  • 日配额调度:AI 任务按用户等级限流

5. 画布 Chrome v4 统一

  • CanvasNodeTileRoot:hover 边框、选中态、CTA scale 统一
  • 浮动 CTA 定位 SSOTresolveCanvasFloatingActionPlacement 双层容器
  • PadPicker 画布:参考图选择器原子架构(T0-T3)

6. 其他新功能

  • 帮助学习中心模块
  • 弹窗壳关闭按钮与层级统一
  • Dialog 系统统一到 modal/ + 用户偏好模块
  • 图片元数据模块 + 提示词合法性校验与压缩
  • 无限画布全屏 F11 切换
  • 演员长相锁定与角色造型智能融合定妆提示词
  • 分镜一致性合并模块:SceneMergeCache 场次 L2 预取
  • 场次列表剧集行交互升级与批量生成入口
  • 片段场次列表复刻场次模块样式
  • 分镜工作台文学剧本与 AI 提示词双 Tab
  • 道具概念图管线独立拆分

🐛 二、BUG 修复(共 ~60+ 个,按模块分类)

🔴 P0 崩溃/白屏/功能不可用(~20 个)

日期BUG问题根因
06-01浮动 CTA 定位错位片段重叠/故事板点不到transform 合成顺序错位
05-31对白 Phase 1 零实现文档已规划但代码零实现前期仅交付文档未落代码
05-31导入视频框架后白屏含 dlg 节点的场次画布整页白屏Hooks 规则违反 + Entity Host 重复挂载
05-31全站模型选择器崩溃capabilityBindings 为 nullpickDefault(null) 传入
05-31TextModelPicker 崩溃.filter on undefinedfallback settings 为空对象
05-30片段 AI 优化全局禁用多 segment 切换 busy 错乱Panel 级 useState 非 per-host
05-27分镜参考图 dismiss 丢失重开工作台后参考图恢复默认陈旧 content 覆盖 DB
05-25场次画布白屏卡死InfiniteCanvas setState-in-rendercommitDrag 在 updater 内调父级 setState
05-25场景/道具概念图「消失」orphan 清理误删 portrait_cachedisk_cleanup 未扫描 asset 表
05-25兑换/购后激活 gate 不关闭激活闭环不可用recheckGate 恒为 true
05-22生成视频工作台空白Modal 未注册导致渲染失败modalFrameCatalog 缺注册
05-20参考图选择层全项目无法打开useModalWithOpen 首帧 open=true 未触发useRef 初始化 prevOpen 错误
05-20空分段引导弹窗构建失败Modal 迁移后 props 未同步删除Portals props 链未瘦身
05-23启动 Loading 卡住旧库缺列导致 APP_BOOT failedscene_asset_list_layout 列名迁移遗漏
05-24SubmitBugReportModal 崩溃useAuth 未挂 AuthProviderProvider 从未挂入 React 树

🟠 P1 功能异常/体验严重(~25 个)

日期BUG问题
05-31编译预览不刷新切换模型后去重键缺 videoModel
05-30切 Tab/重启后 busy 丢失inflight 未接 App Provider 注册表
05-30工作台打开空提示词openHost 无 handoff
05-29演员 Tab 选中状态重启丢失无 localStorage 持久化
05-28故事板 DEL 删除后画布抖动冗余全量 refresh
05-28角色卡灯箱大量裂图orphan 清理范围不全
05-27分镜工作台景别/焦段恢复默认executeSegmentShot 补全 productLanguageDraft 依赖
05-26万相升级后旧库仍用 wanx2.1种子/迁移/脚本未对齐
05-26DashScope 视频管线未合并 UI 参数generation 消费遗漏
05-25画布拖拽后上一张图复位queueMicrotask 导致 dragEpoch 门禁拒收
05-24列表布局表冷启动未迁移layout 迁移误留离线专属
05-23场次场景图生成成功但画布无图异步写回绑定了当前 UI 选中实体
05-23面包屑换故事后片段画布铺满旧瓦片跨故事缓存未清空
05-22视频提示词压缩假成功压缩成功判定未与 preview 门禁对齐
05-22正文超限但看不到压缩按钮role_block early-return 阻断 primary 判断
05-21视频工作台 graphSnapshot 覆盖 dirty未 dirty 门禁
05-21片段「生成视频」长期禁用Context value 高频变化误清注册
05-19演员有参考图时 AI 生成报错invoke plan 缺 i2i 参数
05-19演员生图仅见「信息提炼」无肖像任务hints_gate 失败时未建任务
05-19场次生成场景图 styleDomain 秒失败前端 cinematic 后端仅 realistic/anime
05-18角色定妆照 CONFIG_ERRORresolutionMode 缺失未回填
05-18生图弹层镜头语言不记住无 localStorage 持久化
05-17生产剧集 parse failed: missing field chapters模型返回 chapters_outline 非 chapters
05-17剧集生成场次 parse failed: missing field headline模型输出旧字段名
05-13分镜生图参考图未传入模型I2I 参数未传 + 参考图未写入 content

🟡 P2 体验/视觉不一致(~15 个)

日期BUG问题
06-01画布 chrome v4 hover/CTA/PadPicker 未对齐isHovered/scale 未贯通
05-21弹层切换 Tab 后几何不记忆Tab 切换卸载时未落盘几何
05-16F11 全屏快捷键与 PLAN 不一致非画布 Tab 也写全屏状态
05-14Clips 章节排序与主路径不一致独立 SQL 未复用 Service

🏗️ 三、架构重构

  1. 全栈分层重构:持久化与应用服务隔离、SSOT 化
  2. SQLite 迁移体系统一:唯一管道 apply_schema_migrations、冷启动幂等
  3. Entity Host AI 任务架构:domain 作用域、按上下文锁定任务状态
  4. 弹窗系统统一AppModal + modalFrameCatalog + 几何持久化
  5. 光箱/工作台/弹窗壳三大模块统一重构
  6. 角色系统全面重构:模型选择、AI 任务 UI 升级
  7. 模型请求单一出口:dispatch 层与官方端点硬对齐(Phase A-E)
  8. 全产品生图前置统一:底层管线改造、参数以 UI 提交为准
  9. 分镜导演化扫尾:prompt_assembler_v2、shot_specs 引擎
  10. 设置写回 debounce:合并 IPC + layout 批量 flush

📊 四、数据统计

指标数量
BUG 修复总数~60+
P0 崩溃/白屏~20
P1 功能异常~25
P2 体验优化~15
新增 PLAN 文档~70+
版本号变化0.1.530 → 0.1.601(+71)

🔑 五、关键经验总结

  1. setState-in-render:画布 drag commit 禁止在 setState updater 内回写父级
  2. Hooks 规则:InfiniteCanvas renderNode 内组件禁止 conditional early return 在 Hooks 之前
  3. orphan 清理:新增落盘目录/表时须同步更新 disk_cleanup.rs 引用源
  4. Modal 迁移:凡新增 AppModal 必须同步注册 MODAL_FRAME_ITEMS
  5. 参数以 UI 提交为准:前后端 task_typeimage_extensions 必须同一规则解析
  6. Preview 去重键:须与 IPC 合同字段同构,providerKind 合并 channel 时不能代替 modelId
  7. 异步写回:不得绑定「当前 UI 选中实体」,须按 nodeId 更新全局列表

0531的需求和BUG

# 需求记录 · 2026-05-31

## REQ-2026-05-31-001

- **需求描述**:将架构评审指出的对白音频 PLAN 缺陷(既有 `dialogue_tracks` 对齐、`ai_tasks`/Entity Host、禁止平行表与 Edge 兜底、三层对白 SSOT、双视频路径、orphan 清理等)补齐写入 `20260531T140000+0800-PLAN-片段画布对白音频系统架构与开发计划.md`
- **实现方案**:文档升版 v1.1;重写 §1/§3/§4/§5/§6.0/§6.5/§7–§13 与附录 C;保留 §6.2 四入口 UX 设计。
- **代码变更**`项目文档/20260531T140000+0800-PLAN-片段画布对白音频系统架构与开发计划.md`
- **验证方式**:人工通读 §3.2 INV、§4.1 与 `content_assets.rs` 对照;Phase 1 任务表不再含「新建 dialogue_tracks / Edge-TTS 默认」。

## REQ-2026-05-31-002

- **需求描述**:对白音频 PLAN 将 ComfyUI 优先级降到最低;优先采用与项目 `local_ai`(llama/Whisper)一致的**本地 TTS 子进程**方案,明确 llama 不做朗读。
- **实现方案**:文档 v1.2:§7.1–7.4、Phase 4/5/6 拆分、§9 实验定位、INV-DIALOGUE-10。
- **代码变更**`项目文档/20260531T140000+0800-PLAN-片段画布对白音频系统架构与开发计划.md`
- **验证方式**:§7.2 路线图无「Phase 4 = ComfyUI」;§7.4.1 表格说明 llama vs TTS 分工。

## REQ-2026-05-31-003

- **需求描述**:架构须同时支持「生成视频时带入对白」与「后期对口型贴回」;结合小米 MiMo TTS、阿里声音设计官方 API 设计视频模型能力;灵活可扩展、无兼容无兜底;ComfyUI 最低优先级。
- **实现方案**:PLAN v1.3:§3.5 四域、`integrated_native`/`integrated_prerender`/`post_hoc``SegmentVideoDeliverySession``voice_profiles` 厂商绑定、Phase 3 视频编排。
- **代码变更**`项目文档/20260531T140000+0800-PLAN-片段画布对白音频系统架构与开发计划.md`
- **验证方式**:§8.0 三模式表;§7.2.2 target_model 硬约束;无「失败改路径」条文。

## REQ-2026-05-31-004

- **需求描述**:开工前澄清对白音频 PLAN 评审 11 项(DATA/SPEC 门禁、Session vs `segment_video_state`、catalog 扩展方式、Phase 1 planner、Cast 数据源、voice_profiles 情感策略、MiMo API、FFmpeg、`audio_tracks` 列、0.3s 间隔、Phase 任务编号)。
- **实现方案**:PLAN v1.4 + §0/§14;新建 DATA/SPEC 两篇 SSOT;修正 Phase 5–7 任务号与 §4.4 orphan 表述。
- **代码变更**`项目文档/20260531T140000+0800-PLAN-片段画布对白音频系统架构与开发计划.md``项目文档/20260531T183000+0800-DATA-对白轨道与音频资产契约.md``项目文档/20260531T183000+0800-SPEC-片段画布对白音频-v1.md``项目文档/需求-20260531.md`
- **验证方式**:§14 表 11 行与 DATA/SPEC 交叉引用一致;`media_tracks.rs` / `content_assets.rs` 列名与 DATA §2–4 一致。

## REQ-2026-05-31-005

- **需求描述**:澄清 kind/Cancel 前置、TTS materialize SSOT、`StepVideoWithAudioUrl` 分期、`actorId` DTO 缺口、INV 编号权威、Phase 任务表。
- **实现方案**:PLAN v1.5 + DATA/SPEC v1.1;§14 扩至 17 项;Phase 1 增 **1.2a**
- **代码变更**`项目文档/20260531T140000+0800-PLAN-…md``20260531T183000+0800-DATA-…md``20260531T183000+0800-SPEC-…md``需求-20260531.md`
- **验证方式**`segment.rs``actorId` 与 DATA §3.1「现网」一致;`ai_task_kinds.rs` 无对白 kind 与 SPEC §4.1 分期一致。

## REQ-2026-05-31-006

- **需求描述**:全面验收 PLAN Phase 1「开箱即用」— 文档规划的后端/前端此前未实现,需落地可运行闭环。
- **实现方案**:Rust `speech::materialize_dialogue_tts``upsert/delete/submit_segment_dialogue_tts` IPC;`dialogue_tracks` orphan 登记;`ai_task_kinds` + Cancel 注册;前端对白 Tab + `domain/dialogue-track`
- **代码变更**`src-tauri/src/speech/``video_delivery/``commands/dialogue_track_cmd.rs``commands/image/dialogue/*``disk_cleanup.rs``ui/src/domain/dialogue-track/``SegmentCanvasDialogueTab.tsx` 等。
- **验证方式**`cargo check` · `cd ui && npm run build` · `scripts/check-no-direct-cancel.ps1`

## REQ-2026-05-31-007

- **需求描述**:Phase 1 任务表 1.4–1.10 全量落地(组件库、四入口、Entity Host、批量 TTS),达到真开箱即用。
- **实现方案**`ui/src/components/dialogue-editor/*``resolveDialogueHostSegmentNodeId`;右栏/分镜快捷/右键/瓦片 footer;`resolveSegmentNodeOnlyPanelLock` 接入 `segment_dialogue_tts``submit_segment_dialogue_tts_batch`
- **代码变更**`dialogue-editor/``SegmentCanvas*``entity-host-ai-task/``dialogue_track_cmd.rs``apiPart3.ts`、i18n。
- **验证方式**`cargo check` · `npm run build` · `check-no-direct-cancel.ps1`;片段画布:保存对白 → 生成配音 → 播放 mp3 → 任务页可见 → 取消可用。

## REQ-2026-05-31-008

- **需求描述**:废弃右栏「对白」Tab 主入口;在片段画布以 `dlg:` 节点编辑对白,生成视频时识别连线对白轨。
- **实现方案**:PLAN v1.6 §6.2;`useSegmentCanvasDialogueNodes` + `SegmentCanvasDialogueNodeRenderer` + `useAddDialogueCanvasNode``dlg→seg` reference 边;`resolveDialogueCanvasForVideoSubmit``vendorFeatures.dialogueCanvas`;Rust `apply_dialogue_canvas`
- **代码变更**`ui/src/domain/dialogue-track/``ui/src/components/segment-canvas/*``useVideoGenerationWorkbench.ts``segment_video_vendor_features.rs``项目文档/20260531T140000+0800-PLAN-…md`
- **验证方式**`npm run build` · `cargo check`;手测:添加对白节点 → 连线 seg → 生成视频日志含 `SEG_DIALOGUE_VIDEO_*` / `SEG_VIDEO_DIALOGUE_CANVAS_MERGED`

## REQ-2026-05-31-009

- **需求描述**:文学剧本生成分镜即带结构化对白;跨镜对白随故事板连线在「生成视频框架」合并为单 `seg:`;片段画布默认出现可编辑 `dlg:` 节点。
- **实现方案**:PLAN v1.7 §6.3 — Stage A 增 `dialogueLines[]`(默认不单增 LLM);`importVideoFramework``seedDialogueTracksForImportGroup``dlg→seg` reference;用户可删改。
- **代码变更**`src-tauri/src/storyboard_specs.rs``DialogueLineSpec` / `dialogue_lines`)、`story_storyboard_semantic_shots.rs` + `story_storyboard_semantic_system_v3.txt``ui/src/domain/dialogue-track/{parseShotSemantic,extractDialogueSeedLines,dialogueTrackSeedId,ensureDialogueCanvasNode,seedDialogueTracksForImportGroup}.ts``useSegmentCanvasAddStoryboardShots.ts``track_ops.rs`(幂等 upsert by id)。
- **验证方式**`cargo check` · `npm run build`;对白场 JSON 含 `dialogueLines`;导入日志 `SEG_DIALOGUE_IMPORT_SEED`;A→B→C → 1 seg + N dlg;重导入不 duplicatedlg。

## REQ-2026-05-31-010

- **需求描述**:对白节点 UI 调整:标题识别角色名时演员下拉默认选中;演员 label 与选框同一行;台词 textarea 接入全仓 `UiChromeTextarea` 版本历史与底边拖高;底部按钮居中;卡片内容不被裁切(瓦片内可滚动、高度随 textarea 拖高自适应)。
- **实现方案**`resolveDefaultDialogueActorId`(saved `actorId` 或标题「对白 · 角色名」);共享 `DialogueTextEditorField` / `DialogueTrackActionBar`;Rust `maybe_append_dialogue_text_history`;画布瓦片 `overflowY: auto`
- **代码变更**`ui/src/domain/dialogue-track/dialogueRoleOptions.ts``ui/src/components/dialogue-editor/*``SegmentCanvasDialogueNodeRenderer.tsx``src-tauri/src/commands/image/dialogue/track_ops.rs``textarea-version-history/adapters/dialogueTrackTextAdapter.ts`
- **验证方式**`cargo check` · `npm run build`;导入框架后首条 dlg 标题与演员下拉一致;textarea 角标可恢复历史、底边可拖高;底部保存/TTS/删除居中可见。

## REQ-2026-05-31-011

- **需求描述**:恢复 dlg 瓦片标题为「对白 · 角色名」;演员下拉与标题默认一致;选中 dlg 时右栏不再显示乱码内容编辑,直接展示成片(有口型/基底视频播视频,否则播 TTS 音频);修复手动节点右栏按钮乱码。
- **实现方案**`canvasDataBuilder` 占位标题 + `dialogueActorDisplayLabel`(Cast/Role id);`DialogueTrackHistoryPanel`;dlg 选中跳过 content/history Tab;i18n 补全 manual 节点文案。
- **代码变更**`dialogueRoleOptions.ts``useSegmentCanvasDialogueNodes.ts``SegmentCanvasRightPanel.tsx``DialogueTrackHistoryPanel.tsx``useSegmentCanvasInfiniteHostCallbacks.ts`
- **验证方式**`npm run build`;dlg 标题为角色名、下拉默认选中;点选 dlg 右栏仅成片预览;其它节点 manual 面板按钮中文正常。

## REQ-2026-05-31-012

- **需求描述**:恢复 dlg 标题「对白 · 角色名」;对白节点默认 reference 连线到宿主 seg 视频节点。
- **实现方案**`buildDialogueTrackTitle`(actor/Cast/分镜 semantic 回查);`useRepairDialogueSegmentReferenceEdges` 幂等补边;导入/手工添加时同步 `effectiveTransitions`
- **代码变更**`dialogueTrackTitle.ts``useSegmentCanvasDialogueNodes.ts``useRepairDialogueSegmentReferenceEdges.ts``ensureDialogueCanvasNode.ts``useSegmentCanvasAddStoryboardShots.ts`
- **验证方式**`npm run build`;导入框架后 dlg 标题含角色名;画布可见 dlg→seg 连线;日志 `SEG_DIALOGUE_EDGE_REPAIR` / `SEG_DIALOGUE_NODE_ENSURED`

## REQ-2026-05-31-013

- **需求描述**:对白瓦片标题默认显示角色名;下拉切换演员后标题即时更新(无需切换/刷新);导入时 dlg 与 sb 不共用 seg 同一输入端口。
- **实现方案**`SegmentCanvasDialogueTileRenderer` 受控 `dlgActorId` + `buildDialogueTrackTitle` 驱动壳层 title;`dialogueReferenceTargetPort` 为 dlg reference 边分配独立 `targetPort`(排在 sb transition 之后);repair/导入/手工添加均写入端口。
- **代码变更**`SegmentCanvasDialogueTileRenderer.tsx``SegmentCanvasNodeRenderer.tsx``SegmentCanvasDialogueNodeRenderer.tsx``dialogueTrackTitle.ts``dialogueReferenceTargetPort.ts``ensureDialogueCanvasNode.ts``seedDialogueTracksForImportGroup.ts``useRepairDialogueSegmentReferenceEdges.ts``useSegmentCanvasAddStoryboardShots.ts``useSegmentCanvasWorkspaceGraph.ts`
- **验证方式**`npm run build`;导入框架后 dlg 标题为「对白 · 角色名」;下拉改演员标题即时变;dlg/sb 连线落在 seg 不同输入口;视频工作台对白仍走 `dialogueCanvas` 独立链路。

## REQ-2026-05-31-014

- **需求描述**:生成视频片段导入对白后,下拉框默认选中与 title 同名角色(如 title「对白 · 苏晚」→ 下拉选中「苏晚」)。
- **实现方案**`resolveDialogueActorIdMatchingTitle``buildDialogueTrackTitle` 同源解析展示名再映射 roleOptions;瓦片层 `useMemo` 在 storyRoles 晚到后自动刷新默认选中。
- **代码变更**`dialogueTrackTitle.ts``SegmentCanvasDialogueTileRenderer.tsx``dialogueRoleOptions.ts`(标题分隔符兼容)
- **验证方式**`npm run build`;导入框架后 dlg 下拉默认与 title 角色名一致(剧本角色 Tab 须存在同名 role)。

## REQ-2026-05-31-015

- **需求描述**:按 `20260531-PLAN-全站模型选择器厂牌优先二级菜单重构.md` §10 验收,修复 model-picker v5 迁移漏网导致的构建失败与类型不一致。
- **实现方案**:补全 `ShotModelPickerRow` / `ChapterScenesPlanSection` 五通道组件迁移;`ModelPickerPickSource.useSourceState` 入 types SSOT;精简 `ShotWorkbenchModal` props;CI 增 legacy import 检查。
- **代码变更**:见 BUG-2026-05-31-005 代码变更列表。
- **验证方式**`scripts/check-model-picker-ssot.ps1``cd ui && npm run build`;分镜工作台三列下拉为厂牌二级 UI;Comfy loading 文案可见。

## REQ-2026-05-31-016

- **需求描述**:模型选择器无任何可用模型时(未配置账号中心 Key),下拉内提供可选项,选中后跳转账号中心便于配置 Key。
- **实现方案**`VendorModelPicker` 空态可点开下拉,展示说明 +「前往账号中心配置 Key」;`openAccountCenter()``app:openAccountCenter` 事件;`App.tsx` 切设置 Tab 并 `settings:navigate` 至 accounts。
- **代码变更**`ui/src/domain/app-navigation/openAccountCenter.ts``VendorModelPicker.tsx``App.tsx``i18n``modelPicker.*`
- **验证方式**`npm run build`;清空 Key 后点击模型选择器 → 选「前往账号中心」→ 进入设置 · 账号中心。

## REQ-2026-05-31-017

- **需求描述**:按 `20260531T223000+0800-PLAN-画布节点输入端口布局引擎-全仓统一与破坏性重构.md` 完成 Rust SSOT + TS 客户端 + 三画布删边压实;修复「删中间入边后圆点不回收」。
- **实现方案**`canvas_input_ports/` 算法 + IPC;`canvas-input-ports-client/` 薄客户端 + `useCanvasInputPortLayout`;片段 `segment_canvas_delete_edges_and_compact_ports` + 队列;故事板 delete 后 graph 压实;Clips `clips_delete_edges_and_compact_ports`;删除 `storyboardCanvasPorts.ts` / `dialogueReferenceTargetPort.ts`
- **代码变更**`src-tauri/src/canvas_input_ports/*``ui/src/domain/canvas-input-ports-client/*`、片段/故事板/Clips 画布接入、`scripts/check-no-legacy-canvas-ports-import.ps1`
- **验证方式**`cd ui && npm run build``cargo test canvas_input_ports`(54 passed);`npm run test -- geometryMirror.golden`;片段/故事板/Clips「三入边删中间」圆点数与 `target_port` 连续;日志 `CANVAS_INPUT_PORT_COMPACT`
- **R2/V14 补全(2026-05-31)**`offline.rs` + `bgxiong-port-compact` + §5.1–5.3 ps1;`geometryMirror.golden.test.ts`;AGENTS.md `canvas_input_ports` 索引条。

## REQ-2026-05-31-018

- **需求描述**:单图/多图生图时,演员定妆画布(及全站瀑布流画布)的**占位符与成片落位**须在**最上层**显示,且**不得**与任意已有瓦片左上角完全重合(避免整图盖住旧图);写入项目规范。
- **实现方案**`INV-CANVAS-PLACE``canvasTilePlacementPolicy.ts`(避让 + 栈 bump);`computeMasonryFinalNodes` 对无持久化坐标自动步进;`InfiniteCanvas` 合并父级 `initialNodeDragStackAt`;演员画布生图占位/新键/上传 worldPos 接入。
- **代码变更**`ui/src/infinite-canvas/layout/canvasTilePlacementPolicy.ts``masonryCanvasLayout.ts``InfiniteCanvas.tsx``useCastPortraitCanvas.ts``INTEGRATION.md``GUIDE-Agent协作-模块规范汇编.md``AGENTS.md`
- **验证方式**`npm run test -- canvasTilePlacementPolicy masonryCanvasLayout``cd ui && npm run build`;演员页单图/三视图生图:占位与成片在最上层且不与旧图左上角重合。

# BUG 修复记录 · 2026-05-31

## BUG-2026-05-31-001

- **发现/修复时间**:2026-05-31
- **严重级别**:P0(功能缺失)
- **影响范围**:片段画布对白 Phase 1;文档已规划但代码零实现
- **问题描述**:PLAN Phase 1 任务(`upsert_dialogue_track``submit_segment_dialogue_tts`、orphan 登记、对白 Tab)仅存在于文档,仓库无对应 IPC/前端,无法「开箱即用」。
- **根因分析**:前期会话仅交付 DATA/SPEC/PLAN 澄清,未落代码。
- **修复方案**:按 PLAN v1.5 落地 Phase 1 全量(REQ-006 + REQ-007):组件库、四入口、Entity Host 锁/取消、批量 TTS。
- **代码变更**`speech/materialize.rs``commands/dialogue_track_cmd.rs`(含 batch)、`disk_cleanup.rs``dialogue-editor/``entity-host-ai-task/resolveSegmentNodeOnlyPanelLock.ts``SegmentCanvas*` 四入口。
- **验证方式**`cargo check``npm run build``scripts/check-no-direct-cancel.ps1`;手动:右栏对白 Tab / 分镜快捷块 / 右键「编辑对白」/ 瓦片 footer 气泡。
- **经验总结**:文档「已建」≠ 可运行;验收须对照 `grep` 命令注册与 `main.rs` handler;Phase 1 须逐项对照 §10 任务表而非仅「有一条能跑」。

## BUG-2026-05-31-002

- **发现/修复时间**:2026-05-31
- **严重级别**:P0(整 Tab 白屏)
- **影响范围**:片段画布「导入视频框架」完成后,含 `dlg:` 对白节点的场次画布
- **问题描述**:导入成功(日志 `importVideoFramework.complete`),画布闪一下后整页白屏;`logs/frontend-2026-05-31-*.log` 出现 `An error occurred in the <SegmentCanvasDialogueNodeRenderer> component`
- **根因分析**
  1. **`SegmentCanvasNodeRenderer` 违反 Hooks 规则**:对白分支在 `useNodePortraitPreviewUrl` / `useState` 之前 early return,同一瓦片实例在「非 dlg → dlg」或热更新时 hook 顺序变化,React 抛错并拖垮整树。
  2. **对白瓦片内调用 `useSegmentCanvasEntityHost`**:在 InfiniteCanvas `renderNode` 子树重复挂载 Entity Host 重 Hook,放大崩溃面。
  3. **`segmentCanvasDataFromWorkspaceNode` 未解析 dlg payload**`hostSegmentNodeId` / `dialogueTrackId` 缺失,首帧 dlg 数据不完整(次要,已一并修复)。
- **修复方案**
  1. 将所有 Hooks 移到 `SegmentCanvasNodeRenderer` 顶部,再分支渲染 dlg / 其它节点。
  2. dlg 瓦片 TTS 运行态改由 `SegmentCanvasTabWorkspace``getDialogueTtsRunForSegment` / `cancelDialogueTtsForSegment` 注入,瓦片内禁止 Entity Host Hook。
  3. `canvasDataBuilder.segmentCanvasDataFromWorkspaceNode` 解析 `dlg:` id 与 payload,设置 `segmentCanvasKind: dialogue_node`
  4. 新增 `SegmentCanvasTileErrorBoundary`,单瓦片渲染失败不再白屏整 Tab。
- **代码变更**`canvasDataBuilder.ts``SegmentCanvasNodeRenderer.tsx``SegmentCanvasDialogueNodeRenderer.tsx``useSegmentCanvasEntityHost.ts``SegmentCanvasTabWorkspace.tsx``SegmentCanvasTileErrorBoundary.tsx`(新)。
- **验证方式**`npm run build`;复现路径:场次 `5cf5179a-9a83-4c9d-978b-aaf1f9ffc7d0` →「导入视频框架」→ 画布应稳定显示 7 节点(含 1 个 dlg),无白屏;日志无 `SegmentCanvasDialogueNodeRenderer` React error。
- **经验总结**:InfiniteCanvas `renderNode` 内组件**禁止 conditional early return 在 Hooks 之前**;Entity Host 类 Hook 仅在 Tab/Panel 层调用,经 props 下发到瓦片。

## BUG-2026-05-31-003

- **发现/修复时间**:2026-05-31
- **严重级别**:P1(预览 stale,误导用户)
- **影响范围**:片段视频生成工作台 · 编译预览
- **问题描述**:同 `videoProviderKind` 不同 `videoModel` 切换后,编译预览不刷新;手动「刷新预览」同样 skip。
- **根因分析**`buildPreviewInputKey` 未含 `videoModel`,与 `previewVideoGenerationPrompt` 入参不一致,命中 `preview_skip_duplicate_input`
- **修复方案**:抽取 `previewModelId` 写入去重键;`doPreview` 复用同一值。
- **代码变更**`ui/src/domain/video-generation/useVideoGenerationWorkbench.ts``previewModelId` useMemo + `buildPreviewInputKey` + `doPreview` deps)
- **验证方式**:§1.2 即梦 720p↔1080p/Pro;日志无错误 skip;`npm run build`;同 model 去重仍生效。
- **经验总结**:预览去重键须与 IPC 合同字段同构;`providerKind` 合并 channel 时不能代替 `modelId`

## BUG-2026-05-31-004

- **发现/修复时间**:2026-05-31
- **严重级别**:P0(运行时崩溃)
- **影响范围**:全站模型选择器(尤其首尾帧 keyframe lane、视频工作台 keyframe TAB)
- **问题描述**:打开含 keyframe 模型选择器的界面时控制台报错 `Cannot read properties of null (reading 'capabilityBindings')`,堆栈指向 `listBindingsByCapability``pickDefaultKeyframeModelPick``resolvePreferenceState`
- **根因分析**`resolvePreferenceState` 在解析全局默认时调用 `binding.pickDefault(null as any)`,将 `null` 传入 `pickDefaultKeyframeModelPick``listConfiguredKeyframeModelPicks``listBindingsByCapability`,访问 `null.capabilityBindings` 崩溃。
- **修复方案**`resolvePreferenceState` 新增 `appSettings` 参数;`useModelPickerLane` 将已有 `appSettings` 传入;`pickDefault(appSettings)` 替代 `pickDefault(null)`
- **代码变更**`ui/src/domain/model-picker/core/preference/resolvePreferenceState.ts``ui/src/domain/model-picker/runtime/useModelPickerLane.ts`
- **验证方式**`ReadLints` 无新增告警;复现路径:打开视频生成工作台 keyframe TAB,控制台无 TypeError,模型列表正常渲染。
- **经验总结**`pickDefault` 签名要求 `AppSettingsV4`,编排层不得传 `null` 占位;偏好解析与 picks 合并同源依赖 settings。

## BUG-2026-05-31-005

- **发现/修复时间**:2026-05-31
- **严重级别**:P0(运行时崩溃)
- **影响范围**:全站 `TextModelPicker` 等五通道 Picker 组件(尤其 `controller={...}` 且未传 `appSettings` 的用法)
- **问题描述**:控制台报错 `Cannot read properties of undefined (reading 'filter')`,堆栈 `listBindingsByCapability``listConfiguredTextModelPicks``cloudBindingSource.resolve``createModelPickerPair` Picker。
- **根因分析**`createModelPickerPair``props.appSettings` 缺失时用 `{} as AppSettingsV4` 占位,空对象无 `capabilityBindings``.filter` 崩溃。常见路径:父级已 `useTextModelPicker(appSettings)` 并只传 `controller` 给 Picker。
- **修复方案**:模块级 `PICKER_FALLBACK_APP_SETTINGS = defaultsAppSettingsV4()` 替代 `{}``listBindingsByCapability` 对缺失字段防御 `(s?.capabilityBindings ?? [])`
- **代码变更**`ui/src/domain/model-picker/runtime/createModelPickerPair.tsx``ui/src/settings/appSettings.ts`
- **验证方式**`ReadLints` 无新增告警;复现路径:`ShotModelPickerRow` / 各 Modal 仅传 `controller` 的 TextModelPicker,控制台无 TypeError。
- **经验总结**:Picker 内部 hook 与外部 controller 并存时,fallback settings 须为合法 V4 空壳,不得 type assertion 空对象。

## BUG-2026-05-31-005

- **发现/修复时间**:2026-05-31
- **严重级别**:P0(构建失败 / 迁移漏网)
- **影响范围**:全站 model-picker v5 验收;`ShotModelPickerRow``ChapterScenesPlanSection`、Lane 类型
- **问题描述**:按 PLAN §10 验收时 `npm run build` 失败:`ShotModelPickerRow` 仍 import 已删除的 `components/ModelPicker``ChapterScenesPlanSection` 仍 import 已删除的 `TextModelPickSelect`;Lane 的 `useSourceState``ModelPickerPickSource` 类型不一致;`ShotWorkbenchModalProps` 仍要求已废弃的 `imageModelPickKey`/`imageModelPickOptionLabel``useShotWorkbenchCapabilities` 引用已删除的 `UseVideoModelPickerColumnResult`
- **根因分析**:Track F 业务迁移未覆盖分镜工作台三列与剧集场次规划区块;PickSource 异步 hook 仅写在 runtime 局部接口,Lane 声明未纳入 SSOT 类型;Modal props 契约未随 controller 化同步删除。
- **修复方案**
  1. `ShotModelPickerRow` 改用 `TextModelPicker` / `ImageT2iModelPicker` / `ImageI2iModelPicker` + `controller`;loading 读 `controller.loading`
  2. `ChapterScenesPlanSection` 改用 `TextModelPicker` + `appSettings` + `preferenceMode="none"`
  3. `ModelPickerPickSource` 正式增加可选 `useSourceState``registerModelPickerLane<TPick extends ModelPickBase>`
  4. 删除 `ShotWorkbenchModalProps` 中 legacy label/key props;capabilities hook 改用 `ModelPickerController<VideoModelPick>`
  5. `check-model-picker-ssot.ps1` 增第 6 项:业务目录禁止 legacy ModelPicker import。
- **代码变更**`ui/src/domain/model-picker/types.ts``runtime/modelPickerLaneRegistry.ts``runtime/useModelPickerLane.ts``ShotModelPickerRow.tsx``ChapterScenesPlanSection.tsx``shot-workbench/types.ts``useShotWorkbenchCapabilities.ts``ShotWorkbenchModal.tsx``scripts/check-model-picker-ssot.ps1`
- **验证方式**`powershell scripts/check-model-picker-ssot.ps1` 全绿;`cd ui && npm run build` 通过。
- **经验总结**:破坏性重构验收必须以 `npm run build` 为硬门禁;CI 脚本应覆盖「已删文件仍被 import」而不仅是目录存在性。

## BUG-2026-05-31-006

- **发现/修复时间**:2026-05-31
- **严重级别**:P2(交互阻断)
- **影响范围**:全站 VendorModelPicker 下拉面板
- **问题描述**:打开模型选择器后,在列表内用鼠标滚轮滚动时面板立即关闭,无法浏览长列表。
- **根因分析**`window.addEventListener("scroll", …, true)` 在捕获阶段监听**任意**元素 scroll;面板 `overflowY: auto` 内滚轮触发的 scroll 事件同样命中该监听,误调 `setOpen(false)`
- **修复方案**`onScroll` 判断 `event.target` 是否在 `panelRef` / `btnRef` 内,内部滚动不关闭;面板 `onWheel` 阻止冒泡,避免滚轮链式带动外层滚动。
- **代码变更**`ui/src/domain/model-picker/core/ui/VendorModelPicker.tsx`
- **验证方式**`npm run build`;打开含多模型的选择器,滚轮在列表内上下滚动,面板保持打开。
- **经验总结**:portal 浮层「scroll 关闭」须排除浮层自身 scroll target;捕获阶段全局 scroll 监听不能无差别关窗。

## BUG-2026-05-31-008

- **发现/修复时间**:2026-05-31
- **严重级别**:P0(整 Tab 崩溃)
- **影响范围**:片段画布 Tab;凡调用 `usePadPickerController` 的 lazy Tab(故事板等)
- **问题描述**:进入片段画布时控制台 `Uncaught Error: usePadPickerHost must be used within <PadPickerHost>``SegmentCanvasTabWorkspace.tsx:365`)。
- **根因分析**`PadPickerHost.tsx` 与 lazy chunk(`segment-canvas`)各自打包一份 `createContext`,Provider 在 main chunk、Consumer 在 lazy chunk 读到不同 Context 实例,表现为「已在 App 挂载 Provider 仍报未包裹」。
- **修复方案**
  1. 抽出 `padPickerHostContext.ts` 为共享 chunk;`usePadPickerController` 只 import 该模块。
  2. `PadPickerHost` 挂载点迁至 `AppEntityHostShell`(仍在 `AppSettingsProvider` 内)。
  3. Vite `resolve.dedupe: ['react', 'react-dom']`
- **代码变更**`padPickerHostContext.ts`(新)、`PadPickerHost.tsx``usePadPickerController.ts``AppEntityHostShell.tsx``App.tsx``vite.config.ts``main.tsx`
- **验证方式**`npx vite build``dist/assets``usePadPickerHost must be used within` 仅出现于单一 `padPickerHostContext-*.js`;进入片段画布 Tab 无崩溃。
- **经验总结**:全局 React Context 须放在独立 side-effect-free 模块,避免 Provider 组件文件被 main + lazy 重复打包;验收可 grep 构建产物中 error 字符串是否只出现一次。

## BUG-2026-05-31-009

- **发现/修复时间**:2026-05-31
- **严重级别**:P1(工作台 AI 优化不可用)
- **影响范围**:片段画布 → 生成视频工作台 →「AI 优化提示词」
- **问题描述**:已连接来源分镜或右栏已有提示词时,工作台内点击「AI 优化提示词」仍弹「请先填写提示词或连接来源分镜后再优化」。
- **根因分析**`VideoGenerationWorkbenchShell` 调用 `useSegmentVideoPromptOptimize` 时写死 `liveSourcePrompts: []``baseSegmentContent: ""`,校验 `hasInput` 永远看不到工作台左栏入边与片段 content 来源。
- **修复方案**:新增 `projectInputBindingsToLiveSourcePrompts` / `resolveLiveSourcePromptsForVideoOptimize``useVideoGenerationWorkbench` 暴露 `liveSourcePromptsForOptimize` + `baseSegmentContentForOptimize`;Shell 接入与右栏同源参数。
- **代码变更**`projectInputBindingsToLiveSourcePrompts.ts`(新)、`useVideoGenerationWorkbench.ts``VideoGenerationWorkbenchShell.tsx``__tests__/projectInputBindingsToLiveSourcePrompts.test.ts`
- **验证方式**`vitest` 单测;手动:连接分镜 → 打开生成视频工作台 → 完整提示词为空时点「AI 优化提示词」应正常发起(不再弹空输入提示)。
- **经验总结**:复用 Hook 时须对齐全部入参契约;工作台与右栏「AI 优化」共享 `useSegmentVideoPromptOptimize`,不可省略来源投影字段。

## BUG-2026-05-31-010

- **发现/修复时间**:2026-05-31
- **严重级别**:P1(优化结果不可见 / 未落库)
- **影响范围**:片段画布 → 生成视频工作台 →「AI 优化提示词」
- **问题描述**:工作台内 AI 优化提示词成功后,右栏「完整视频提示词」不显示;重启后内容丢失。
- **根因分析**
  1. Rust `optimize_segment_video_prompt` **故意不写 DB**(仅返回 `optimizedPrompt` + `ai_tasks` 记录)。
  2. 右栏 `useSegmentPromptDraft.persistActionDescription``updateNode` 落库;工作台 Shell 的 `persistActionDescription` **仅** `setActionDescriptionDraft`(会话 overlay),未写 `nodes.content`
  3. 工作台 Host 与片段画布 **pending ref 分离**,且无 patch 桥,外部落库无法驱动右栏 draft 刷新。
- **修复方案**
  1. 抽取 `persistSegmentVideoActionDescription`(右栏 / 工作台共用)。
  2. `patchSegmentCanvasContent` + `SegmentCanvasContentBridge` 注册,落库后同步画布 pending 并 bump `segmentContentUpdateKey`
  3. `useSegmentPromptDraft` 监听 `segmentContentUpdateKey` 外部同步 textarea。
  4. 工作台 `persistActionDescriptionToSegment` 落库 + 刷新片段列表。
- **代码变更**`persistSegmentVideoActionDescription.ts``segmentCanvasContentPatch.ts``SegmentCanvasContentBridge.tsx``useSegmentPromptDraft.ts``useVideoGenerationWorkbench.ts``VideoGenerationWorkbenchHost.tsx``VideoGenerationWorkbenchShell.tsx`
- **验证方式**`npm run build`;工作台 AI 优化成功后关闭弹层,右栏应显示相同完整提示词;重启后仍在。
- **经验总结**:AI 优化 API 不写 DB 是设计;**前端 persist 回调**必须在各入口(右栏 / 工作台)对齐落库与画布 pending 同步。

## BUG-2026-05-31-011

- **发现/修复时间**:2026-05-31
- **严重级别**:P2(任务详情噪声 / 库膨胀)
- **影响范围**:资产演员/场景/道具生图、片段视频等全部写入 `ai_tasks.last_payload` 的链路;AI 任务详情页
- **问题描述**:任务详情 / `compiledApiPayload` / `referenceMediaSlots` 中落盘完整 `urlB64`(及同类内联图频 base64),体积大且无排障价值。
- **根因分析**`ai_task::sanitize_payload_for_storage` 仅剥离 `reference_images_b64` 等 snake_case 键,未覆盖 `urlB64` / `voiceUrlB64`;片段视频 `body_for_log` 构建时 `referenceMediaSlots` 整包复制进 `compiledApiPayload`
- **修复方案**
  1. 扩展 `INLINE_MEDIA_B64_KEYS`(含 `urlB64``voiceUrlB64`、参考视频/音频 b64 等),递归替换为 `*Present` / `*_count` 摘要。
  2. 片段视频 `body_for_log``referenceMediaSlots` / `referenceVoiceBindings` 走同一 sanitize。
- **代码变更**`src-tauri/src/ai_task.rs``src-tauri/src/segment_video_pipeline.rs`
- **验证方式**`cargo test --lib``sanitize_payload_strips_reference_media_slot_url_b64`);新建演员/场景资产/道具生图或视频任务后,任务详情 JSON 无 `urlB64` 长串,仅有 `urlB64Present: true` 或张数摘要。
- **经验总结**:凡内联媒体字段落 `ai_tasks`,统一走 `sanitize_payload_for_storage` SSOT;新增厂商槽位字段时同步登记剥离键表。

## BUG-2026-05-31-012

- **发现/修复时间**:2026-05-31
- **严重级别**:P1(无 UI 反馈 / 结果不刷新)
- **影响范围**:演员 Tab · 生成定妆照 · 多视角模式(view3/4/9)
- **问题描述**:确认多视角生图后用户感知「什么都没发生」:画布无占位进度、完成后版本网格不更新。
- **根因分析**
  1. `genLoading` 在分支前已置 true,但进度订阅固定为 `cast_portrait_still_progress`,多视角后端 emit `multi_view_asset_progress`,进度文案不更新。
  2. 多视角 IPC 返回 `MultiViewOutput`(无 `portraitVersionsJson`),分支 early return 未 `getActorPortraitVersions` 刷新 `state.imageVersions` / `selected.portraitVersions`
  3. 无成功 toast / `onRefresh`
- **修复方案**
  1. 多视角分支改订 `subscribeMultiViewAssetProgress``formatCastMultiViewProgressLine` 驱动 `castProgressLine`
  2. 单视角分支再订 `subscribeCastStillProgress`(避免无效监听)。
  3. 成功后 `api.getActorPortraitVersions` + 与单张相同的版本/默认图/缓存清理 + toast + `onRefresh`
- **代码变更**`ui/src/features/character-tab/ai/useCastPortraitStillPipeline.ts``ui/src/features/character-tab/utils.ts`
- **验证方式**`npm run build`;演员 → 生成定妆照 → 选 view3/4/9 → 确认:画布占位 + 进度(如 `2/4`);完成后网格出现多角图 + 成功 toast。
- **经验总结**:多视角与单张须分事件总线;IPC 无 `portraitVersionsJson` 时前端须主动拉库刷新。

## BUG-2026-05-31-013

- **发现/修复时间**:2026-05-31
- **严重级别**:P0(IPC 秒失败、无 AI 任务、无可见错误)
- **影响范围**:演员定妆照 · 可灵经典生图(`image_kling_image_generation_*`)· 多视角;独立 I2I + 垫图场景
- **问题描述**:弹层选「可灵 Kling v3(经典生图)」图生图 + 单图/3 视角确认后无反应;`AI 任务` 列表无记录;前端 toast「未配置 [api.jimeng_image] 或 [api.image_gen]」被 dedupe 抑制未展示。
- **根因分析**`logs/frontend-2026-05-31-*.log` + `logs/bgxiong-ai-story-2026-05-31-*.log`):
  1. `generate_multi_view_asset``insert_running` **之前**调用 `resolve_effective_image_service``has_service_override=false`,设置页凭证未传入 IPC。
  2. 多视角 + 独立 I2I 时 `invokePlan.imageProvider` 仅为图生图 backend,未拆分正面 T2I 的 provider/override。
  3. `multiViewInvoke` 未显式携带 `imageServiceOverride` / `i2iImageServiceOverride`
- **修复方案**
  1. `resolveCastMultiViewServiceBundle`:从能力映射构建 T2I/I2I `AiServiceOverride`;独立 I2I 时正面走文生图 pick、其余角走图生图 pick。
  2. `ensureInvokePlanImageServiceOverride`:单张 `castPortrait` 路径补全 override。
  3. `executeImageGeneration` 多视角优先读 `multiViewInvoke.imageServiceOverride`
  4. 提交前凭证门禁 + `[CAST_PORTRAIT_STILL] invoke.multi_view.service_bundle` 日志。
- **代码变更**`useCastPortraitStillPipeline.ts``buildImageSubmitPacket.ts``executeImageGeneration.ts`
- **验证方式**`npm run build`;可灵图生图 + 垫图 + view3:后端日志 `has_service_override=true``ai_tasks` 出现 `multi_view_asset`;画布有进度与结果。
- **经验总结**:桌面端生图凭证以 **AppSettings 能力映射 override** 为准,不得依赖 `config.toml``[api.jimeng_image]`;多视角 IPC 须双通道 provider + 双 override;失败须在 `insert_running` 前打日志。

## BUG-2026-05-31-014

- **发现/修复时间**:2026-05-31
- **严重级别**:P0(有垫图仍全文生图,多视角策略错误)
- **影响范围**:演员 4 视角/3 视角/9 视角 + 垫图;视觉资产库道具/场景多视角 + 参考图
- **问题描述**:UI 已选垫图,4 视角生成仍走文生图(`FrontAnchor`),未带参考图提交。
- **根因分析**
  1. `generate_multi_view_asset``user_reference_images_b64`**TODO 空 Vec**`referenceImageRelPaths` 从未 materialize)。
  2. `determine_ref_policy(0)``FrontAnchor` → 正面无 ref、通道 `text_to_image`
  3. 编排循环 HTTP 始终用 `ctx.image_service`(T2I),独立 I2I 通道在 `has_refs` 时未切 `i2i_service`
  4. 视觉资产库多视角 `referenceImageRelPaths: null` 且 IPC 无 `referenceImagesB64` 字段,道具/场景垫图同样丢失。
- **修复方案**
  1. 新增 `reference_materialize::materialize_multi_view_user_references`(演员 rel → b64,与 `cast_still_impl` 同源)。
  2. IPC 增 `referenceImagesB64`;前端 visual asset 多视角透传。
  3. `run_multi_view``channel::resolve` 选择 `image_service` / `i2i_service`
  4. 日志键 `MULTI_VIEW_REF_MATERIALIZE`(含 materialized_pad_count)。
- **代码变更**`multi_view.rs``reference_materialize.rs``multi_view_impl.rs``apiPart2.ts``executeImageGeneration.ts``buildImageSubmitPacket.ts``useVisualAssetConceptGeneration.ts``useCastPortraitStillPipeline.ts`
- **验证方式**`cargo test reference_materialize``cd ui && npm run build`;演员垫图 + view4:日志 `materialized_pad_count>=1``multiViewRefPolicy=shared_original`;任务详情 channel 为 `image_to_image`
- **经验总结**:多视角 Prepare 的 `user_reference_images_b64` 与单张 `cast_portrait_still` 须同一 materialize 路径;禁止 command 层留空 TODO 垫图。

项目综述(bgxiong-ai-story)— 比格熊数字导演工作站

# 项目综述(bgxiong-ai-story)— 比格熊数字导演工作站

| 项 | 说明 |
|----|------|
| **文档性质** | 面向非技术读者的项目全景:市场背景、产品与技术要点、阶段性成果与方向(中性表述)。 |
| **统计口径** | 工程规模统计截至 **2026-05-30**,仅统计个人自研源码与内部文档,不含第三方依赖库与自动生成的安装包内容。 |

---

## 1. 定位概览

比格熊数字导演工作站(bgxiong-ai-story)是一套 **AI 驱动的多模态故事与分镜工作台**,产品形态上是 **安装在电脑上的桌面客户端软件**(而非「打开浏览器即用」的纯网页产品)。它把故事结构(项目—剧集—场次—片段/镜头)[^工程命名]、角色与演员资产、分镜故事板,以及文本 / 图像 / 视频 / 语音生成链路放在 **同一套本地工程与同一应用窗口** 里闭环完成,面向影视、短视频、动漫与教育实训等 **前期创意与试制** 场景。

[^工程命名]: 工程代码中对应 `story`(故事根)→ `chapter`(剧集节点)→ `scene`(场次节点)→ `segment`(片段/镜头节点),详见 `项目文档/20260509-SPEC-全仓语义命名权威规范.md` §1 冻结词表。

产品名称「比格熊数字导演工作站」体现其核心理念:**用 AI 将「一句话故事」自动拆解为完整的可视化制作管线**——从故事种子到剧集、场次、镜头、分镜图、视频成片,全链路自动化,大幅降低短视频与动画制作门槛。

云端 AI、开放平台接口在本产品中的角色,更接近 **用户按需接驳的能力插件**:用来完成某次生成或某种模型推理;**工程本体、数据结构、任务编排、设置与日志** 仍以客户端与本地存储为主轴。这与「做一个网站外壳,里面嵌各家网页或只转发接口」有本质区别——前者是 **可离线打开的工程文件型生产力工具**,后者往往离不开会话、Cookie 与远端页面形态,数据和体验的掌控链也更短。

---

## 2. 市场视角

- **需求背景**:多工具并行(文档、表格、浏览器里各家模型页面)容易造成上下文断裂、素材与版本散落;创作方难复盘「用了哪家模型、最终下过怎样指令」。机构使用场景还对 **可控、可追溯** 有刚性要求。
- **产品切入点**:用 **结构化本地工程** 承接创意流程;用户在设置与各界面里 **明确选定** 文本、配图、改图、视频、语音等通道,系统按选择执行,**不做**用户未同意的暗中替换,降低合规与品控风险。
- **典型用户**:独立创作者、小型制作组、内容团队与院校实训等需要在 **可控环境** 下批量试制 AI 辅助前期的群体。

---

## 3. 为什么是桌面客户端

下面几条概括 **客户端路线相对「云端套壳」或「纯浏览器工具」** 的差异;不是说「完全不用云」,而是 **云服务于生成能力,客户端承载创作资产与工业流程**

- **工程与数据默认在用户自己电脑上**
  项目、章节场次关系、分镜结构、任务记录、素材引用等落在 **本地数据库与本地目录**,用户对自己的剧本与物料拥有直观的 **占有感与备份方式**(拷贝文件夹、整机备份、离线归档),而不是默认「全部托管在第三方网页账号背后」。

- **不绑死在浏览器标签页的生命周期**
  关闭浏览器、清理站点数据、某家网站改版或下线,通常 **不会**一笔勾销你的「工作台形态」。客户端像普通办公软件一样常驻本机,打开即是同一套界面与同一套工程逻辑。

- **云端是「可选外挂」,不是「唯一脊梁」**
  需要文生图、图生图、视频、语音等时再按用户选择去访问各家开放平台;同时支持 **本地装载的大模型**(llama.cpp 文本推理、Whisper 语音识别),弱网、断网或保密环境下仍可浏览与编辑工程结构、跑本地推理,**不把「能上网」当作使用产品的绝对前提**

- **更深地接入本机能力**
  日志与诊断、数据目录配置、可选本地工作流(如 ComfyUI)、大批量读写与路径解析、媒体运行时(FFmpeg 集成)、磁盘清理等,都是 **操作系统级客户端** 天然擅长的领域;这些若仅靠网页沙箱,往往处处受限或体验割裂。

- **复杂界面与大体量交互敢往深了做**
  例如大面积无限画布、多标签重度工作台、长列表任务中心——按 **桌面性能预期** 做虚拟渲染与内存策略,而不是在手机浏览器或嵌套网页里「凑合能用」。

- **隐私与对内合规更好叙事**
  敏感台词与设定默认留在本机;对外发出的仅是用户在某个按钮上 **明确触发** 的那次生成请求。机构关心「剧情与素材出不出域」时,客户端架构更容易给出清晰边界。

- **产品心智:工具 vs 入口**
  「云端套壳」常常是聚合入口,换一个模型页等于换一个站;本产品则在客户端内固定 **同一套菜单、同一套设置与能力映射、同一套任务与日志语义**,长期使用成本低,也更像 **正经的生产软件**

---

## 4. 产品与系统概要(技术人员可读作架构)

- **形态**:Windows 等环境下的 **桌面应用**,界面为现代 Web 技术(React + TypeScript)呈现,与 **本机 Rust 后台服务** 协同工作,数据主要落在本机。
- **数据**:核心资料使用 **本地 SQLite 数据库**(WAL 模式 + r2d2 连接池)持久保存(项目、创作节点关系、任务记录、素材引用等);数据库、对外接口与界面之间 **字段命名规则统一**,减少「同名不同义」导致的差错。
- **智能能力**:既支持对接 **云端** 图像、视频、语音等开放平台能力(即梦、可灵、通义万相、Seedance、OpenAI 等),也支持 **本地大模型**(llama.cpp 文本推理、Whisper 语音识别),兼顾联网弹性、离线可能以及隐私敏感场景。
- **运维与排障**:关键操作链路会写入 **本地日志**(tracing 分级日志 + 日志保留策略);涉及后台任务时,从「已提交 → 执行过程 → 结束结果」分段留痕,便于出问题后按时间线追查,而不是只靠口头描述。
- **自动化扩展**:同一套故事与素材的领域模型,还提供 **命令行工具****离线数据库迁移脚本**,便于以后做批处理、脚本或与外部系统对接。
- **架构分层**:后端采用 **domain / application / infrastructure / composition** 四层分层重构,职责清晰、可测试性好。

### 4.1 设计上值得单独说的几点

- **用户选定的模型才生效,禁止暗中换通道**
  每一次云端或本地推理,都必须对应用户在当前界面或设置里 **明确选好的服务商与模型**;全局默认值只在「用户尚未选择」时起补充作用。**不允许**对用户没选中的通道自动轮询、悄悄兜底,也不允许例如「参考图失败就无声改成纯文字生图」这类隐蔽替换。这在消费级工具里不常见,但对 **采购合规、成本可归因、结果可复现** 很重要;产品上用统一的模型选择与「记住上次实际使用」的体验,避免多套界面、多套记忆规则打架。

- **最终指令与任务过程可追溯**
  在 **真正发出请求之前**,会把下发给所选模型的 **最终文本指令** 记入可检索日志;纳入任务中心的流程则按 **提交 → 进行中更新 → 结束汇总** 留存。多步骤、多模态的长链路事后可以对齐时间线,有利于长期维护与企业环境交付。

- **故事板:最终台词稿单一来源**
  数据库、接口与界面之间遵循同一套数据约定;分镜故事板里,**最终送给模型的那段提示** 集中在约定的分段内容里统一维护,而不是在多个地方各存一份、时间一长就对不上。这样导出、备份或多端协作时不容易分叉。

- **演员库可以不绑死在某一个故事上**
  「演员」允许作为 **全局可复用资产** 管理,不必先创建某个故事才能建档;跨项目共用肖像与设定时,边界更清晰,后续若做协作或素材库也更容易扩展。

- **设置里的「能力映射」统领全站的模型列表顺序**
  文本、配图、改图、视频、语音等能力,按账号区块与模型行的顺序组成清单,再反映到各功能页的模型下拉列表;顺序与是否隐藏由用户在设置里 **保存****不跟着**厂商网页或偶然的网络返回顺序飘。多家供应商加多台本地模型混用时,这是 **列表可控、心智稳定** 的关键。

- **自研无限画布:为「很多张图 / 很多卡」做的性能策略**
  大面积拖拽、缩放、摆卡片(演员形象墙、场次、分镜浏览、片段画布等)共用一套 **自研画布内核****不依赖**额外的重型第三方画布商业包。做法是分层减负:**只重点处理屏幕附近的内容**(外加一圈缓冲,避免边缘闪烁)、**分批加载**避免一口气创建成百上千张卡片卡住界面、对视野外的元素 **减少无谓绘制**,并对视频、大图在 **离开视野后主动降级或收回资源**,避免「划走了还在后台解码占内存」。缩放以指针为中心、手感一致;瀑布流排布与画布核心分开,多处界面复用同一套交互习惯。内部规格文档中对 **数百个节点** 量级写了性能目标(首次打开耗时、拖动流畅度、内存占用上限),属于「先定体验指标再实现」的基础设施思路。

- **统一 AI 端点注册表与调度层**
  后端 `open_platform` 模块实现统一端点注册表,即梦、可灵、通义万相、Seedance、OpenAI 等各家接口各异,但业务管线只需调用统一接口。新增厂商只需注册新端点,业务管线零侵入,可持续升级。支持文生图、图生图、图生视频、文生视频、TTS 语音合成、唇形同步等多种生成能力。

- **本地 AI 能力内置**
  通过 llama.cpp 集成本地文本推理,通过 Whisper 集成本地语音识别。在离线、保密或低成本场景下,核心 AI 能力不依赖云端。

- **权限系统与配额管理**
  内置用户权限调度层与日配额机制,支持用户激活、账号管理、AI 任务配额控制,面向机构采购与团队使用场景。

- **全链路视频生成管线**
  从分镜图到视频成片,支持多家视频模型(即梦、可灵、Seedance 等)的统一调度,含视频定价、限流、任务生命周期管理、唇形同步、TTS 语音合成、字幕生成等完整管线。

---

## 5. 当前成果(产品与工程)

**功能范围(摘要)**
主要功能页覆盖故事总览、剧集与场次看板、场景与素材、分镜故事板与镜头工作台、片段画布(无限画布)、角色与演员、任务中心、帮助学习中心等;设置中提供账号与绑定、**能力与模型映射**、可选本地工作流(如 ComfyUI)、诊断与数据存储位置、BUG 报告与日志上云等;界面文案支持中英文。

**研发体量(静态统计,便于理解投入)**

| 类别 | 文件数(约) | 行数(约) |
|------|----------------|------------|
| 后端与桌面服务(Rust) | 657 | 12.83 万 |
| 前端界面组件(TSX) | 368 | 7.56 万 |
| 前端逻辑脚本(TS) | 1018 | 11.05 万 |
| 小型工具脚本(Python) | 80 | 1.19 万 |
| **自研程序合计** | **≈ 2123** | **≈ 32.6 万** |
| 内部设计 / 规范 / 记录文档 | ≈ 618 | — |

**技术栈明细**

| 层 | 技术选型 |
|----|----------|
| 桌面壳 | Tauri 2(Rust 进程托管,非 Electron) |
| 前端框架 | React 19 + TypeScript 5.9 + Vite 8 |
| 后端语言 | Rust(edition 2021) |
| 数据库 | SQLite(WAL 模式 + r2d2 连接池) |
| AI 调度 | 统一端点注册表(open_platform),云端/本地双模式 |
| 本地 AI | llama.cpp(文本推理)+ Whisper(语音识别) |
| 媒体处理 | FFmpeg 集成(视频转码、探测、合成) |
| 图像生成 | 即梦、通义万相、ComfyUI 等 |
| 视频生成 | 即梦、可灵、Seedance 等 |
| 语音合成 | TTS 管线(多家云端 + 本地) |
| 唇形同步 | 多适配器架构(Hedra、LivePortrait、MuseTalk、Wav2Lip、可灵) |
| 本地工作流 | ComfyUI 完整集成(HTTP/WebSocket、工作流编译、管线注入) |
| 自动更新 | Tauri Updater(被动安装模式) |
| 权限系统 | 可插拔权限框架 + 日配额管理 |

大量内部文档对应作者在 **数据约定、交互规范、故障排查与版本迁移** 上的持续沉淀,便于长期维护与日后扩展。

---

## 6. 后端核心模块地图

后端(`src-tauri/src`)共 657 个 Rust 源文件,按职责划分为以下核心模块群:

| 模块群 | 关键文件/目录 | 职责 |
|--------|---------------|------|
| **故事管线** | `story_chapter_pipeline`, `chapter_scenes_plan`, `chapter_scenes_plan_pipeline` | 故事→剧集→场次的 LLM 级联生成 |
| **分镜引擎** | `storyboard_*`(specs / stage_a / stage_b / merge / rules / render / graph) | 分镜生成、导演化语义层、质量门、渲染输出 |
| **AI 提示词** | `ai_prompts/`(builtins / render / types) | 内置提示词模板、渲染引擎、类型定义 |
| **AI 任务** | `ai_task`, `ai_task_kinds`, `ai_queue`, `ai_progress_heartbeat` | 任务生命周期、并发队列、进度心跳 |
| **开放平台** | `open_platform/`(provider / dispatch / gen_error / provider_metadata / tts / jimeng / volc_*) | 统一端点注册表、多厂商适配、错误归一化 |
| **图像生成** | `image_generation`, `commands/image/`(task_lifecycle / video / dialogue / placeholders) | 生图管线、任务生命周期、视频提交 |
| **视频管线** | `video_task`, `video_task_poller`, `video_param_mapper`, `video_rate_limiter`, `video_pricing`, `segment_video_pipeline` | 视频任务调度、轮询、参数映射、限流、定价 |
| **ComfyUI** | `comfyui/`(client / commands / pipeline / workflow / http) | 本地 ComfyUI 完整集成 |
| **本地 AI** | `local_ai/`(text_generation / speech_recognition) | llama.cpp 文本推理、Whisper 语音识别 |
| **语音与字幕** | `audio_pipeline`, `stt_pipeline`, `subtitle_pipeline`, `tts`, `lipsync_provider/` | TTS、语音识别、字幕生成、唇形同步 |
| **角色与演员** | `role_nodes`, `role_physique`, `role_physique_pipeline`, `role_portrait_supplement`, `portrait_*` | 角色管理、体型管线、肖像版本链 |
| **片段画布** | `segment_canvas/`, `canvas_state_store`, `segment_content_markers`, `segment_pad_refs` | 无限画布引擎、画布状态持久化 |
| **图引擎** | `graph_core/`(engine / runtime / store / types / perf) | 通用有向图引擎,支撑分镜与片段画布 |
| **媒体运行时** | `media_runtime/`(ffmpeg_cli / service / registry / selector / capabilities) | FFmpeg 集成、媒体能力注册、格式探测 |
| **权限与安全** | `permission/`, `authz`, `credential_crypto`, `quota_guard` | 权限系统、授权、凭证加密、配额管理 |
| **数据库** | `db/`(migrations / model_catalog_repo), `migration/` | SQLite 迁移、模型目录缓存 |
| **分层架构** | `domain/`, `application/`, `infrastructure/`, `composition/` | 全栈四层分层重构 |
| **运维** | `log_init`, `disk_cleanup`, `bug_report`, `app_update_*` | 日志、磁盘清理、BUG 报告、自动更新 |

---

## 7. 前端核心模块地图

前端(`ui/src`)共 1386 个 TSX/TS 源文件,按职责划分为以下核心模块群:

| 模块群 | 关键目录 | 职责 |
|--------|----------|------|
| **故事 Tab** | `components/story-tab/` | 故事总览、剧集列表、导出脚本 |
| **剧集 Tab** | `components/chapter-tab/`(panels / sections / modals / hooks) | 剧集看板、场次规划、关键帧、批量生成 |
| **场次 Tab** | `components/scene-tab/` | 场次列表、上下文菜单、加载态 |
| **分镜工作台** | `components/storyboard/`(panels / modals / hooks / history / graph) | 分镜故事板、镜头工作台、AI 提示词版本历史 |
| **片段画布** | `components/segment-canvas/`(graph / domain / transitions) | 无限画布、图推导、撤销重做、瓦片同步 |
| **分镜画布** | `components/storyboard-shot-canvas/`(renderers / overlays / handlers / minimap) | 分镜节点画布、边渲染、缩放控件 |
| **角色 Tab** | `features/character-tab/`(canvas / editor / actor-list / columns / layout) | 角色管理、演员列表、定妆照画布 |
| **角色 Tab** | `features/role-tab/`(canvas / detail / hooks / modals / lightbox) | 角色详情、肖像灯箱 |
| **设置 Tab** | `components/settings-tab/` / `components/settings/` | 账号、能力映射、ComfyUI、本地模型、TTS/视频实验室 |
| **Clips** | `clips/`(ClipsNodeEditor / ClipsMinimap / ClipsVideoPreview) | 片段节点编辑器、缩略图、视频预览 |
| **帮助模块** | `help-module/` | 学习中心、引导 |
| **认证** | `auth/` | 登录、注册、密码重置、Token 管理 |
| **UI 组件库** | `components/ui-*`(modal / toast / panel / form / icon / list / lightbox / edge-resize-shell / chrome-textarea) | 通用 UI 原子组件 |
| **无限画布内核** | `infinite-canvas/`(components / hooks) | 画布网格、缩放控件、默认边渲染 |
| **领域逻辑** | `domain/`(model-surfaces / local-media-upload / audio / imageGenWarnings) | 模型选择编解码、上传队列、音频、生成警告 |
| **API 层** | `api/`(graphApi / migration / segmentCanvasV2Api / clipFramework) | Tauri IPC 调用封装 |
| **系统** | `system/`(form-control-clipboard / selectable-copy) | 右键复制粘贴、可选复制 |

---

## 8. 未来与演进方向

- **产品**:强化分镜与生成的一体化体验,批量任务、模板与复用;按场景接入更多云端能力与本地模型组合;NLE 时间线 XML 导出对接专业剪辑软件。
- **工程**:在坚持「用户明确选模」的前提下,完善任务编排、监控与配置迁移;持续 domain / application / infrastructure / composition 四层分层重构;与云端素材、协同类产品探索 **松耦合对接**(本地工程仍是权威数据源,**除非**产品战略另有决策)。
- **生态**:持续面向中文创作者工作流,向 **可信、可选、可审计** 的多模态前期工具链演进。

---

*代码仓库内另行维护更细的技术约束与模块说明,供开发与测试使用;本文不展开。*

比格熊AI导演工作站v0.1.530

**文档时间**:2026-05-28T21:00:00+0800

# 项目定位分析:软件 vs 智能体

## 一、核心结论

**bgxiong-ai-story 是一款 AI 增强型桌面创作软件,不是智能体(Agent)。**

它是一个具备完整 UI、本地数据持久化、多模态 AI 管线调度能力的**桌面生产力工具**,AI 是它的核心能力模块之一,但不是它的全部身份。

---

## 二、软件与智能体的本质区别

| 维度 | 软件(Software) | 智能体(Agent) |
|------|------------------|-----------------|
| **交互模式** | 用户主动操作 UI,软件响应 | 用户下达目标,自主规划并执行 |
| **决策权** | 用户决定做什么、怎么做 | Agent 自主决定步骤、工具调用顺序 |
| **状态管理** | 显式 UI 状态 + 用户确认 | 内部记忆 + 自主状态机 |
| **执行边界** | 功能确定,用户控制流程 | 开放式,可跨工具/系统组合 |
| **可观测性** | 用户全程可见每一步 | 中间过程可能不透明 |
| **典型例子** | Photoshop、Premiere、Figma | Claude Code、AutoGPT、Devin |

### 2.1 软件的特征(bgxiong-ai-story 具备)

- **确定性 UI 交互**:用户点击「生成分镜」「生成视频」按钮触发具体管线
- **用户控制流程**:故事 → 章节 → 场次 → 分镜 → 视频,每一步用户都有主导权
- **显式状态管理**:SQLite 持久化、画布状态、任务队列,用户可查看和回溯
- **工具属性**:服务于创作者的具体创作流程,而非自主完成开放式目标

### 2.2 智能体的特征(bgxiong-ai-story 不具备)

- **自主规划**:根据高层目标自动拆解子任务(bgxiong 的 AI 管线是预定义的,不是自主规划的)
- **工具调用决策**:Agent 自己决定何时调用什么工具(bgxiong 的工具调用由用户触发或预定义管线驱动)
- **循环推理**:观察 → 思考 → 行动 → 再观察的 ReAct 循环(bgxiong 的 AI 调用是单次请求-响应模式)
- **跨系统协调**:自主与外部系统交互(bgxiong 的云端调用是固定通道,不是自主探索)

---

## 三、bgxiong-ai-story 的定位

### 3.1 产品定义

> **AI 驱动多模态剧本引擎**
> ——面向影视/短视频创作者的桌面端一站式创作平台

它是一款**专业级桌面软件**,将 AI 能力深度嵌入影视创作的完整工作流,但核心交互范式仍然是「**用户主导 + AI 辅助**」。

### 3.2 AI 在项目中的角色

AI 在本项目中以**管线(Pipeline)**的形式存在,而非以 Agent 的形式:

| AI 管线 | 触发方式 | 执行模式 |
|---------|---------|---------|
| 故事章节规划 | 用户点击「AI 规划」 | 单次 LLM 请求 → 结构化输出 |
| 场次分镜规划 | 用户点击「批量生成」 | 预定义管线 → 结果落库 |
| 分镜静帧图生成 | 用户确认参数后提交 | 文生图 API → 图片落盘 |
| 角色定妆照 | 用户选择风格后生成 | 多轮管线 → 版本管理 |
| 视频生成 | 用户选择分镜后提交 | 视频 API → 轮询 → 成片 |
| 语音识别(STT) | 用户上传音频 | 本地 Whisper → 文本 |
| TTS 朗读 | 用户点击朗读 | 云端 TTS → 音频 |

每一管线都是**确定性的、用户可预期的、可中断/重试的**,而非 Agent 式的自主决策。

---

## 四、项目架构分析

### 4.1 技术栈

```
┌─────────────────────────────────────────────────┐
│                   前端 (React + TypeScript)       │
│  Vite · Infinite Canvas · i18n · 瀑布流布局      │
├─────────────────────────────────────────────────┤
│              Tauri 2 IPC 桥接层                   │
├─────────────────────────────────────────────────┤
│                   后端 (Rust)                     │
│  SQLite · r2d2 连接池 · reqwest · tokio          │
│  ┌──────────┐ ┌──────────┐ ┌──────────────┐    │
│  │ AI 管线   │ │ 媒体管线  │ │ 权限/配额    │    │
│  └──────────┘ └──────────┘ └──────────────┘    │
│  ┌──────────────────────────────────────────┐   │
│  │      open_platform (多厂商 AI 调度)       │   │
│  │  可灵 · 万相 · 即梦 · DashScope · 本地AI  │   │
│  └──────────────────────────────────────────┘   │
├─────────────────────────────────────────────────┤
│              本地存储 (SQLite + 文件系统)          │
│  story.db · portrait_cache/ · story_media/       │
└─────────────────────────────────────────────────┘
```

### 4.2 分层架构

| 层级 | 目录 | 职责 |
|------|------|------|
| **Domain** | `domain/` | 核心业务模型(Story、Node、Edge、Asset、Task) |
| **Application** | `application/` | 业务服务编排 |
| **Infrastructure** | `infrastructure/` | SQLite 仓储、外部 API 适配 |
| **Presentation** | `commands/` + `ui/` | Tauri IPC 命令 + React UI |
| **AI 调度** | `open_platform/` | 多厂商统一出口、模型能力映射、配额管控 |

### 4.3 核心数据模型

```
Story (故事根)
 ├── Chapter (剧集/章节)
 │    └── Scene (场次)
 │         └── Segment (片段/镜头)
 │              ├── Shot (分镜静帧)
 │              └── Video (视频成片)
 ├── Cast (演员库,跨故事共享)
 └── Asset (媒体资产)
```

### 4.4 多厂商 AI 统一调度

项目最大的架构亮点之一是 **open_platform** 模块——统一的多厂商 AI 调度层:

- **图像生成**:可灵(Kling)、万相(DashScope WAN)、即梦(Jimeng)
- **视频生成**:可灵视频、万相视频、即梦视频、Seedance 2.0
- **文本生成**:多 LLM 服务商(通过云端 API 或本地模型)
- **语音**:Whisper(本地 STT)、云端 TTS
- **能力映射(SSOT)**:每个模型的能力边界(分辨率、画幅、参考图数量等)由统一的 `model_capability_catalog` 管理

---

## 五、项目优势

### 5.1 对比纯 AI Agent 的优势

| 优势 | 说明 |
|------|------|
| **确定性与可控性** | 用户永远知道下一步会发生什么,不会出现 Agent 幻觉导致的不可控行为 |
| **专业工作流** | 深度适配影视创作流程(故事 → 场次 → 分镜 → 视频),而非通用 Agent 的泛化能力 |
| **数据主权** | 所有数据本地 SQLite 存储,用户完全掌控,不依赖云端 |
| **离线能力** | 支持本地 AI 模型(Candle + Whisper),断网可用 |
| **版本管理** | 分镜版本、角色定妆照版本、场次概念图版本,完整的版本对比与回溯 |
| **批量效率** | 支持全故事/全剧集批量生成分镜,AI Agent 通常只能逐条处理 |

### 5.2 对比传统创作软件的优势

| 优势 | 说明 |
|------|------|
| **AI 原生** | AI 不是插件/后加功能,而是从架构层深度集成的核心能力 |
| **多模态** | 文本(LLM)+ 图像(文生图/图生图)+ 视频 + 音频(STT/TTS)全覆盖 |
| **多厂商** | 不绑定单一 AI 服务商,用户可自由选择/切换模型 |
| **参数透明** | 生图参数以 UI 为准,禁止静默覆盖,用户所见即所得 |
| **桌面原生** | Tauri 2 打包,启动快、体积小、原生体验 |

### 5.3 技术架构优势

- **Rust 后端**:高性能、内存安全、优秀的并发处理(tokio async runtime)
- **数据契约严格**:SQLite ↔ IPC ↔ TS 全栈命名一致(冻结词表),杜绝数据层混乱
- **AI 提示词全量日志**:每个 AI 请求的最终提示词必落盘,可审计、可复现
- **任务三阶段记录**:submitted → running → done/failed/cancelled,完整生命周期追踪
- **离线迁移为主**:SQLite 结构变更走离线脚本,程序内禁止兜底兼容,保证数据一致性

---

## 六、核心功能清单

### 6.1 创作流程

| 功能 | 描述 |
|------|------|
| 故事管理 | 创建、编辑故事根节点,支持多项目并行 |
| 章节规划 | AI 辅助规划剧集/章节结构,支持手动调整 |
| 场次编排 | 场次列表、场次概念图生成、场次间引用关系 |
| 分镜系统 | 故事板画布(Infinite Canvas)、分镜静帧图生成、分镜版本管理 |
| 视频生成 | 分镜 → 视频工作台、首尾帧控制、多视频模型选择 |
| 角色管理 | 演员库(跨故事共享)、角色定妆照、角色叙事 × 外形 × 生图三域 |
| 参考图系统 | 统一参考图选择器(PadPicker)、参考图策略记忆与恢复 |

### 6.2 AI 能力

| 能力 | 实现 |
|------|------|
| 文本生成(LLM) | 多服务商接入,结构化输出 |
| 文生图(T2I) | 可灵、万相、即梦等多厂商 |
| 图生图(I2I) | 参考图 + 提示词 → 新图 |
| 视频生成 | T2V、I2V、首尾帧控制、多模型 |
| 语音识别 | 本地 Whisper(whisper-rs) |
| 语音合成 | 云端 TTS |

### 6.3 工程能力

| 能力 | 实现 |
|------|------|
| 无限画布 | 自研 Infinite Canvas,支持缩放、拖拽、瀑布流布局 |
| 本地存储 | SQLite + WAL 模式 + r2d2 连接池 |
| 权限系统 | 两档用户身份(注册/激活)、日配额管控 |
| 自动更新 | Tauri Plugin Updater |
| 日志系统 | 前后端统一落盘日志,全链路可排障 |
| 国际化 | i18n 多语言支持 |

---

## 七、未来扩展方向

### 7.1 从软件到「软件 + Agent」的混合架构

当前是纯软件模式(用户主导),未来可以引入 Agent 能力,形成**混合架构**

```
当前:用户 → UI → AI 管线 → 结果
未来:用户 → 目标 → Agent 规划 → 多步执行 → 用户确认 → 结果
```

具体方向:

| 扩展方向 | 描述 | 优先级 |
|---------|------|--------|
| **智能导演 Agent** | 用户描述故事大纲,Agent 自动完成「分章 → 分场 → 分镜 → 生图 → 生视频」全流程 | 高 |
| **风格一致性 Agent** | 自动维护全片视觉风格一致,检测并修正偏离 | 中 |
| **自动剪辑 Agent** | 根据分镜顺序和节奏自动剪辑视频片段 | 中 |
| **市场分析 Agent** | 分析热门题材、观众偏好,辅助创作决策 | 低 |

### 7.2 平台化扩展

| 方向 | 描述 |
|------|------|
| **插件系统** | 开放 AI 管线接口,允许第三方接入新模型/新能力 |
| **协作功能** | 多人协作编辑同一故事/分镜(需引入 CRDT 或 OT) |
| **云端同步** | 本地优先 + 云端同步,支持跨设备创作 |
| **素材市场** | 模板、风格预设、角色模型的共享/交易平台 |
| **API 开放** | 将核心能力以 API 形式开放,支持嵌入其他工具链 |

### 7.3 技术演进

| 方向 | 描述 |
|------|------|
| **本地大模型** | 当前已有 Candle 框架骨架,可逐步接入更多本地模型 |
| **实时预览** | 视频生成的实时预览、流式输出 |
| **3D 场景** | 从 2D 分镜扩展到 3D 场景预览 |
| **多端同步** | 桌面端 + Web 端 + 移动端数据互通 |

---

## 八、能为创作者带来什么

### 8.1 效率提升

- **从文字到视频的全链路自动化**:一个故事大纲可以快速拆解为章节、场次、分镜、视频
- **批量生成**:支持全故事/全剧集批量分镜,省去逐帧手绘的时间
- **AI 辅助创作**:LLM 辅助规划剧情结构、生成提示词,降低创作门槛

### 8.2 质量保障

- **视觉一致性**:角色定妆照系统 + 参考图策略,确保同一角色在不同场景中形象一致
- **版本管理**:每个分镜、每个角色都有完整的版本历史,支持对比和回溯
- **参数透明**:所有 AI 生成参数用户可见、可调,不存在黑箱操作

### 8.3 降低门槛

- **非专业用户**:不需要绘画、剪辑技能,通过文字描述即可生成视觉内容
- **独立创作者**:一个人可以完成从剧本到成片的全流程,不再需要大型团队
- **快速验证**:创意可以快速可视化,用于 pitch、众筹、团队沟通

### 8.4 数据主权

- **本地优先**:所有数据存储在本地,创作者完全掌控
- **离线可用**:支持本地 AI 模型,不依赖网络
- **无平台锁定**:数据格式开放,不绑定特定云服务

---

## 九、代码量统计

> 统计时间:2026-05-28,基于当前 main 分支

### 9.1 总览

| 指标 | 数值 |
|------|------|
| **总代码行数** | **~347,000 行** |
| Rust 后端(src-tauri/src) | ~138,000 行(627 个 .rs 文件) |
| Rust 核心库(src/) | ~1,900 行 |
| TypeScript/TSX 前端(ui/src) | ~197,000 行(1,334 个文件) |
| CSS 样式 | ~1,100 行 |
| 维护脚本(scripts/) | ~9,200 行(84 个文件) |
| 项目文档(项目文档/) | ~108,000 行(264 个 .md 文件) |
| 项目文档历史记录(项目文档历史记录/) | ~139,000 行(311 个 .md 文件) |

### 9.2 Rust 后端模块分布(按代码量排序)

| 模块 | 行数 | 职责 |
|------|------|------|
| `commands/` | 20,949 | Tauri IPC 命令层(图片/视频/文本/故事板等) |
| `open_platform/` | 15,375 | 多厂商 AI 统一调度(可灵/万相/即梦/DashScope) |
| `db/` | 5,882 | SQLite schema、迁移、仓储 |
| `storyboard_merge/` | 4,648 | 分镜合并与一致性引擎 |
| `ai_prompts/` | 3,808 | AI 提示词模板与编译 |
| `chapter_scenes_plan/` | 3,558 | 剧集场次规划管线 |
| `comfyui/` | 3,488 | ComfyUI 本地生图集成 |
| `segment_canvas/` | 3,244 | 片段画布(视频节点画布) |
| `permission/` | 3,133 | 权限系统 |
| `ai_queue/` | 3,111 | AI 任务队列管理 |
| `migration/` | 3,099 | 数据库迁移脚本 |
| `pad_policy/` | 2,954 | 参考图策略引擎(SSOT) |
| `clips/` | 2,935 | 视频片段管理 |
| `delete_service/` | 2,586 | 统一删除服务 |
| `media_runtime/` | 2,509 | 媒体运行时(本地文件管理) |
| `authz/` | 2,342 | 用户权限调度层与日配额 |
| `storyboard_rules/` | 2,137 | 故事板规则引擎 |
| `appearance/` | 2,054 | 外观/主题系统 |
| 其他模块(25+) | ~17,000 | 本地AI、语音、唇同步、视频管线等 |

### 9.3 前端模块分布(按代码量排序)

| 模块 | 行数 | 职责 |
|------|------|------|
| `components/` | 42,757 | UI 组件库(画布、弹窗、设置、故事板等) |
| `features/` | 19,352 | 业务功能模块(角色、演员、分镜等) |
| `domain/` | 11,075 | 领域模型与业务逻辑(视频生成、参考图、AI任务等) |
| `i18n/` | 8,485 | 国际化(中英文) |
| `infinite-canvas/` | 6,457 | 无限画布引擎(自研) |
| `settings/` | 4,883 | 设置系统 |
| `hooks/` | 4,602 | 通用 React Hooks |
| `api/` | 4,413 | IPC API 层与类型定义 |
| `clips/` | 3,467 | 视频片段 UI |
| `app-shell/` | 3,423 | 应用外壳与布局 |
| `layout-persistence/` | 1,926 | 布局持久化(跨重启记忆) |
| 其他模块(10+) | ~6,200 | 认证、快捷键、引导等 |

### 9.4 Top 10 最大单文件

| 文件 | 行数 | 说明 |
|------|------|------|
| `i18n/en.ts` | 2,952 | 英文语言包 |
| `i18n/zh-CN.ts` | 2,911 | 中文语言包 |
| `infinite-canvas/InfiniteCanvas.tsx` | 2,147 | 无限画布核心组件 |
| `segment_video_pipeline.rs` | 3,469 | 片段视频生成管线 |
| `storyboard_stage_b_ingest.rs` | 2,158 | 故事板阶段 B 摄入 |
| `story_chapter_pipeline.rs` | 1,858 | 故事章节规划管线 |
| `commands/text.rs` | 1,557 | 文本相关 IPC 命令 |
| `video-generation/useVideoGenerationWorkbench.ts` | 2,445 | 视频生成工作台 Hook |
| `scene_concept_image_pipeline.rs` | 1,515 | 场次概念图生成管线 |
| `settings/appSettings.ts` | 1,835 | 应用设置管理 |

### 9.5 工程规模指标

| 指标 | 数值 |
|------|------|
| Rust 依赖(Cargo.toml) | ~40 个 crate(含可选 local-ai feature) |
| 前端依赖(package.json) | 9 个 runtime + 13 个 dev |
| 内联测试文件(Rust) | 145 个文件含 `#[test]` |
| 集成测试(tests/) | 2 个文件,239 行 |
| 数据库表 | 10+ 张(stories/nodes/edges/assets/ai_tasks 等) |
| AI 厂商接入 | 5+ 家(可灵/万相/即梦/DashScope/本地模型) |
| IPC 命令数 | 100+ 个 Tauri invoke 命令 |

---

## 十、总结

bgxiong-ai-story 是一个 **~347,000 行代码**的中大型桌面应用,本质上是一款**专业的 AI 增强型桌面创作软件**,而非智能体。它的核心价值在于:

1. **将 AI 深度嵌入影视创作的完整工作流**,而非将 AI 作为独立的对话工具
2. **用户始终掌握主导权**,AI 是助手而非决策者
3. **工程品质过硬**——Rust 后端、严格的数据契约、全链路日志、多厂商统一调度
4. **面向创作者的真实需求**——从故事到成片的全链路,而非技术演示

未来,随着 Agent 技术的成熟,项目可以在保持「用户主导」核心体验的同时,逐步引入 Agent 能力,形成「**软件 + Agent 混合架构**」——让用户可以选择「手动模式」(当前的精细控制)或「Agent 模式」(描述目标,自动执行),两者互补而非替代。