比格熊博客 - 软件更新日志

AI写一堆屎山代码怎么破?

我是大熊 2026-06-12

给你的Vibecoding的agent前面加上一个禁止屎山代码的约束就好了

# 屎山代码鉴定准则 v1.0

> 本文档提供一套系统化的代码质量鉴定标准，用于客观评估代码库的"屎山化"程度。
> 评级体系采用**扣分制**：满分 100 分，每个问题扣对应分值，最终得分越低越"山"。

---

## 评级总览

| 得分区间 | 等级 | 称号 | 说明 |
|---------|------|------|------|
| 90-100 | ⭐ 优秀 | 清风明月 | 可读、可测、可维护，新人半天能上手 |
| 75-89 | 🟢 良好 | 小有瑕疵 | 整体规范，局部有改进空间 |
| 60-74 | 🟡 及格 | 勉强能看 | 能跑，但改一个地方要查三个地方 |
| 40-59 | 🟠 山脚 | 初具规模 | 已经出现明显的维护困难 |
| 20-39 | 🔴 山腰 | 山高路远 | 每次修改都像在拆炸弹 |
| 0-19 | 💀 山顶 | 不可名状 | 别动，动就崩；重写比重构快 |

---

## 第一章：命名与可读性（20 分）

### 1.1 变量/函数命名（-3 分/项）

- [ ] **谜语命名**：`a`, `b`, `temp`, `data2`, `handleStuff()`, `doIt()`
- [ ] **拼音缩写混搭**：`getYongHuList()`, `chaXunShuJu()`, `tmp_canshu`
- [ ] **命名与含义不符**：函数叫 `isValid()` 但实际会修改数据库；变量叫 `count` 存的是数组
- [ ] **同类不同风格**：同一文件里 `get_user_name()` / `fetchUserName()` / `queryusername()` 共存

### 1.2 注释（-2 分/项）

- [ ] **零注释**：整个文件没有任何注释，全靠"读代码"
- [ ] **废话注释**：`i++; // i 加 1`
- [ ] **注释与代码不符**：注释说"返回用户列表"，实际返回的是订单
- [ ] **大量注释掉的代码**：超过 20 行被注释的死代码没人清理

### 1.3 魔法数字与硬编码（-2 分/项）

- [ ] **魔法数字满天飞**：`if (status == 3)` —— 3 是什么意思？
- [ ] **硬编码路径/地址**：`"/Users/zhangsan/Desktop/test.txt"`, `"http://192.168.1.100:8080"`
- [ ] **硬编码密钥/密码**：`password = "123456"` 直接写在源码里

---

## 第二章：结构与设计（25 分）

### 2.1 函数/方法（-3 分/项）

- [ ] **超长函数**：单个函数超过 200 行（超过 500 行扣 5 分）
- [ ] **参数爆炸**：函数参数超过 5 个
- [ ] **嵌套地狱**：if/for/try 嵌套超过 4 层（金字塔/箭头形代码）
- [ ] **职责混乱**：一个函数同时做数据查询、业务计算、格式化输出、发邮件

### 2.2 类/模块（-3 分/项）

- [ ] **上帝类**：一个类超过 1000 行，什么功能都在里面
- [ ] **万能工具类**：`Utils.java` / `helpers.ts` 包含 50+ 个互不相关的方法
- [ ] **循环依赖**：A 依赖 B，B 依赖 C，C 依赖 A
- [ ] **没有分层**：UI 逻辑、业务逻辑、数据访问全混在一个文件里

### 2.3 代码重复（-4 分/项）

- [ ] **复制粘贴编程**：相同/相似代码块出现 3 次以上未抽取
- [ ] **复制后只改一处**：两段 100 行代码只有第 50 行不同，但没人合并

---

## 第三章：错误处理（15 分）

### 3.1 异常处理（-3 分/项）

- [ ] **吞异常**：`catch (e) {}` 空 catch 块，错误被默默吃掉
- [ ] **万能 catch**：`catch (Exception e)` 捕获所有异常然后打一行日志了事
- [ ] **用异常控制流程**：用 try/catch 代替 if/else 做业务判断
- [ ] **错误信息丢失**：catch 之后不记录原始错误，只输出"操作失败"

### 3.2 防御性编程（-2 分/项）

- [ ] **不做空值检查**：直接 `user.profile.avatar.url` 不考虑任何中间环节为 null
- [ ] **不做边界检查**：数组/列表直接取下标不检查长度
- [ ] **不做输入校验**：外部输入直接拼 SQL / 直接渲染到页面

---

## 第四章：状态管理与副作用（15 分）

### 4.1 全局状态（-3 分/项）

- [ ] **全局变量满天飞**：超过 10 个全局可变状态
- [ ] **隐式状态传递**：通过全局变量在函数间传递数据，看不出数据流
- [ ] **状态不同步**：多个地方维护同一份数据的一致性，但没有统一管理

### 4.2 副作用（-3 分/项）

- [ ] **函数有隐藏副作用**：调用 `getData()` 实际会修改数据库
- [ ] **时序依赖**：必须按特定顺序调用一系列函数，否则就崩，但没有文档说明
- [ ] **资源泄漏**：打开的文件/连接/句柄不关闭，靠"程序退出自动回收"

---

## 第五章：依赖与配置（10 分）

### 5.1 依赖管理（-3 分/项）

- [ ] **依赖版本不锁定**：没有 lock 文件，不同环境构建出不同结果
- [ ] **大量无用依赖**：`package.json` / `Cargo.toml` 里有一堆不再使用的依赖
- [ ] **循环依赖 / 版本冲突**：依赖之间互相打架，靠降版本凑合

### 5.2 配置管理（-2 分/项）

- [ ] **配置散落各处**：同一类配置分散在 5 个不同的文件里
- [ ] **环境判断硬编码**：`if (location.hostname === 'localhost')` 判断是否开发环境

---

## 第六章：测试与文档（10 分）

### 6.1 测试（-5 分/项）

- [ ] **零测试**：没有任何单元测试、集成测试
- [ ] **测试形同虚设**：测试只测 `2 + 2 = 4`，不覆盖核心业务逻辑
- [ ] **测试不稳定**：同一个测试有时过有时不过（flaky test）

### 6.2 文档（-3 分/项）

- [ ] **零文档**：没有 README、没有架构说明、没有 API 文档
- [ ] **文档过期**：文档描述的和实际代码完全不同

---

## 第七章：版本控制（5 分）

### 7.1 Git 提交（-2 分/项）

- [ ] **提交信息是谜语**：`fix`, `update`, `aaa`, `临时提交`
- [ ] **巨型提交**：一个 commit 改动超过 20 个文件、1000 行
- [ ] **提交无关改动**：一个 commit 里混杂功能开发、Bug 修复、格式化、依赖更新

### 7.2 分支管理（-2 分/项）

- [ ] **长期不合并的分支**：分支超过 2 周不合并，冲突已无法解决
- [ ] **直接在 main 上开发**：没有分支隔离，main 随时可能崩

---

## 第八章：专项扣分（附加项，不计入基础 100 分）

以下情况属于"一票否决"级别，发现即判定为屎山：

| 编号 | 项 | 扣分 | 说明 |
|------|-----|------|------|
| S1 | SQL 注入漏洞 | -20 | 用户输入直接拼 SQL |
| S2 | 明文存储密码 | -20 | 数据库里存明文密码 |
| S3 | 生产环境 print 调试 | -10 | `console.log` / `print` / `println!` 散落在线上代码里 |
| S4 | 无意义的提交历史 | -10 | 50 个 commit 全是 `fix` / `update` |
| S5 | 大文件入库 | -15 | 二进制文件、视频、模型文件被 git 跟踪 |
| S6 | 死代码占比 > 30% | -10 | 大量未被调用的函数/类/文件 |
| S7 | 单文件超 2000 行 | -10 | 一个源文件超过 2000 行 |

---

## 附录 A：快速自查清单

回答以下 10 个问题，每个"否"计 1 分（满分 10 分，越低越山）：

1. 新人能否在 **半天内** 理解项目核心架构？
2. 修改一个功能是否 **只需要改动 1-2 个文件**？
3. 出现 Bug 时能否 **快速定位到相关代码**？
4. 代码是否有 **一致的命名风格和组织方式**？
5. 核心业务逻辑是否有 **单元测试覆盖**？
6. 是否能 **一键构建并运行** 项目？
7. 错误发生时是否有 **清晰的错误信息和日志**？
8. 依赖版本是否 **锁定且定期更新**？
9. 是否有 **清晰的模块边界和分层**？
10. 团队成员是否 **敢在不问原作者的情况下修改代码**？

> **评分**：10 分 = 清风明月，7-9 分 = 小有瑕疵，4-6 分 = 初具规模，0-3 分 = 不可名状。

---

## 附录 B：屎山成因分析

屎山不是一天堆成的，常见成因：

| 阶段 | 表现 | 根因 |
|------|------|------|
| 赶工期 | "先上线再说" | 业务压力，技术债无暇偿还 |
| 人走茶凉 | 核心开发者离职，无人敢动 | 知识未沉淀，代码即文档 |
| 打补丁 | 每次只修表面，不治根因 | 缺乏重构时间和勇气 |
| 需求膨胀 | 功能无限叠加，架构从未升级 | 初期设计未考虑扩展性 |
| 缺乏规范 | 每个人按自己风格写 | 没有 Code Review，没有编码规范 |
| 信息孤岛 | 同一个逻辑写了 N 遍 | 模块间缺乏沟通，重复造轮子 |

---

## 附录 C：使用方法

### 自评流程

1. **复制本文件**到目标项目
2. 逐项检查，勾选存在的问题
3. 计算总扣分，得出最终得分
4. 对照评级表确定等级

### 定期复查

建议每个迭代结束时进行一次快速自查（附录 A），每个季度进行一次全面鉴定。

---

> **免责说明**：本准则用于自我审视和团队交流，不用于人身攻击。
> 代码写成屎山不丢人，知道自己是屎山还不改才丢人。

---

*版本：v1.0 | 创建日期：2026-06-11*

阅读全文

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

我是大熊 2026-06-12

# 从 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

我是大熊 2026-06-09

# 项目综述（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 篇内部文档），供开发与测试使用；本文不展开。*

阅读全文

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

我是大熊 2026-06-05

> 你有一个好故事，但不会画画、不会剪辑、不会建模。

> 比格熊帮你把「一句话创意」变成完整的分镜、视频、对白——全在同一台电脑上完成。

---

## 一句话说清楚

比格熊是一个 **装在你电脑上的 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 白板"，我们做了一座"数字导演工作站

我是大熊 2026-06-03

## 市面上的无限画布，到底在画什么？

打开 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，会不会能力被阉割？

我是大熊 2026-06-02

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 更新日志

我是大熊 2026-06-01

一、重大新功能

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 气泡）
批量 TTS：submit_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 定位 SSOT：resolveCanvasFloatingActionPlacement 双层容器
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` 为 null	`pickDefault(null)` 传入
05-31	TextModelPicker 崩溃	`.filter` on undefined	fallback settings 为空对象
05-30	片段 AI 优化全局禁用	多 segment 切换 busy 错乱	Panel 级 useState 非 per-host
05-27	分镜参考图 dismiss 丢失	重开工作台后参考图恢复默认	陈旧 content 覆盖 DB
05-25	场次画布白屏卡死	InfiniteCanvas setState-in-render	commitDrag 在 updater 内调父级 setState
05-25	场景/道具概念图「消失」	orphan 清理误删 portrait_cache	disk_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 failed	`scene_asset_list_layout` 列名迁移遗漏
05-24	SubmitBugReportModal 崩溃	useAuth 未挂 AuthProvider	Provider 从未挂入 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-26	DashScope 视频管线未合并 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_ERROR	resolutionMode 缺失未回填
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-16	F11 全屏快捷键与 PLAN 不一致	非画布 Tab 也写全屏状态
05-14	Clips 章节排序与主路径不一致	独立 SQL 未复用 Service

🏗️ 三、架构重构

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

📊 四、数据统计

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

🔑 五、关键经验总结

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

阅读全文

0531的需求和BUG

我是大熊 2026-05-31

# 需求记录 · 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）— 比格熊数字导演工作站

我是大熊 2026-05-30

# 项目综述（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-30

**文档时间**：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 模式」（描述目标，自动执行），两者互补而非替代。

阅读全文

1 2 3 4