# 火宝短剧 · 本地多显卡版

基于 [chatfire-AI/huobao-drama](https://github.com/chatfire-AI/huobao-drama) 4.0.11 的本地定制代码。上游源码基线为 `b48e6b2312166e25b1ff141832d2e82e5d63c142`，原项目说明和许可证保留在 `huobao-source/`。

## 已集成功能

- 模型桥接与多显卡图片、视频调度；可按单个分镜选择显卡重新生成。
- 显示实际执行节点：GPU1 / ComfyUI 8189、GPU2 / ComfyUI 8188、GPU3 / ComfyUI 8191。
- MiniMax H3 视频及 VDN-H3 2K/4K 高清版本，保留原版供对比。
- 角色、场景、道具的图片参考图上传与编辑接口。
- 本地长任务持续查询、重启后恢复查询和原任务结果恢复。
- 固定数据目录、一键启动、升级备份与真人实拍、仙侠风格预设。
- 跨集结尾上下文、分镜起止状态、前镜头尾帧接续与持久化依赖队列。

## 镜头衔接

视频制作中、视频提示词上方的「镜头衔接」面板提供三种模式：

- **独立镜头 / 转场**：不依赖前段，适合换场景、时间跳跃或开场。
- **状态承接**：将前镜头结束状态与本镜头起止状态加入生成约束；允许换角度，仍使用本镜头的资产参考图。
- **尾帧接续**：同场景连续动作。等待前段完成，从所选视频结束前 0.05–3 秒提取画面作为单张首帧，再向选定 GPU 提交。支持当前本地 MiniMax-H3、MiniMax-H3-Hybrid、Wan2.2-I2V；不与多张参考图或参考音色混用。

来源默认为按集号、镜号排序的前一镜，也可选择本项目更早的镜头。不能引用未来、自身、其他项目或已删除的镜头。第一镜、转场需用独立模式。拆分镜工具会读取上一集结尾剧本及最后三个分镜；起止状态是文字设定，不代表系统已经识别或审核了成片画面。

已有分镜升级后保持原模式、原视频，不会自动重新生成。新拆分时 Agent 会填写起止状态并选择衔接方式；旧分镜可在面板中补填后保存。尾帧预览仅提取画面，不生成新视频。前镜头失败时下游保持等待；可取消等待，或先处理前镜头。等待中的任务可重启恢复，并保留原模型与显卡选择。

前镜头版本或起止设定改变后，已生成的下游视频显示核对提示，旧版保留，不自动重跑。依赖链按顺序提交，独立镜头仍可多卡并行。VDN-H3 高清制作仍使用其参考图工作流，不支持固定首帧接续。

## 目录

| 目录或文件 | 用途 |
| --- | --- |
| `huobao-source/` | 前端、后端、Electron 桌面端源码及上游文档 |
| `model-bridge/` | 模型桥接、启动、打包、升级、数据检查和测试脚本 |
| `integration-work/*.py`、`*.ps1`、`*.cjs` | 服务器适配、部署、迁移及验证脚本；部分为历史维护步骤，运行前阅读脚本 |
| `integration-work/browser-test/` | 浏览器界面验证脚本 |
| `一键启动火宝.cmd` | 当前 Windows 工作站的启动入口 |
| `升级与高清制作说明.txt` | 本地升级和高清制作说明 |

## 本地数据与配置

此仓库保存代码，**不包含项目数据库、模型密钥、生成素材、视频、安装包和备份**。现有机器上的这些文件不会因为加入 `.gitignore` 而被删除。

- `huobao-data/`：项目、模型配置、素材和生成记录，必须单独备份。
- `HuobaoDrama/`：安装后的桌面应用，不随代码上传。
- `model-bridge/client.json`、`grok-client.json`：本机连接配置和令牌，不上传。
- `integration-work/backups/`、`previous-app-*/`、`stage-4.0.11/`：升级备份及打包产物，不上传。
- 所有常见视频扩展名均已加入忽略规则；TypeScript 的 `.ts` 源码正常跟踪。

在新机器上仅克隆代码不会恢复原项目和模型配置，需要另外恢复数据备份并配置私有接口。维护脚本含当前工作站路径和内网节点约定，迁移前需按部署环境检查。

## 开发与构建

按 `huobao-source/README.md` 和各目录的 `package.json` 安装对应依赖并构建。当前本地升级流程还使用 `model-bridge/build_upgrade.py` 与 `switch_upgrade.ps1`，需要准备已验证的 4.0.11 桌面运行包；安装包与暂存包不存入 Git。

`一键启动火宝.cmd` 面向已经安装、已有数据的工作站，不是全新安装程序。升级前先保存编辑并完成数据库、素材和配置备份。

## Git 同步

```powershell
git pull --ff-only origin main
git status
git add <需要提交的代码路径>
git commit -m "说明本次修改"
git push origin main
```

拉取代码不会自动替换正在运行的桌面程序。构建和升级需单独执行。当前工作站 `huobao-source/.git` 中的上游历史保留在本地，不作为子模块提交；新克隆会直接得到完整源码。