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

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

---

## 一句话说清楚

比格熊是一个 **装在你电脑上的 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 模式」(描述目标,自动执行),两者互补而非替代。