离线包怎么安装

本章只讲设置里的① 离线包投放（官方 zip / 裸模型文件 → 软件自己校验并放到数据目录）。Comfy 权重包请走 ComfyUI 离线资源，不要放到投放目录里当普通 zip 猜。

有网时：设置 → 本地引擎 → 引擎与组件，卡片上点「下载」即可，不必走离线投放。离线投放适合网络受限、需要拷贝到别的电脑、或想提前把大文件备好的情况。

先确认数据目录

离线包不装在程序安装目录，而是装在用户数据目录（项目存档目录）里，下文简称「数据目录」。

• 默认：%APPDATA%\bgxiong-ai-story（资源管理器地址栏可直接粘贴）。
• 安装时或设置里改过存档目录的：看安装目录下的 app_data_root.txt（一行绝对路径），或 设置 → 数据存储 → 当前项目存档目录。

投放目录固定是 数据目录\offline-drop，不存在时软件会自动创建。

离线投放怎么做

1. 打开 设置 → 本地引擎 → 离线包投放安装 → 打开投放文件夹。这就是本机唯一扫描根（一般在数据目录下的 offline-drop）。
2. 把官方文件原样放进去：不要改名、不要自己解压、不要新建版本号文件夹。可以放在子文件夹里，软件会逐层扫描。
3. 回到面板点扫描，再点「安装推荐」（或勾选后「安装已勾选」），等进度走完。大文件安装前会先做完整性校验，可能要等几秒。
4. 列表上出现「已安装」只表示文件已经在磁盘上。配音/音乐等还要到对应卡片点启动服务，等环境装好、服务健康，才能生成。

三类文件，识别规则不同

设置面板里的「官方文件名白名单」和下面的清单出自同一份软件内置目录。若两者不一致，以面板为准。

文件清单与网盘

官方包已上传网盘，网盘里按组件分文件夹，文件名和下表一致。大文件请用网盘客户端多线程下载。

• 夸克网盘：https://pan.quark.cn/s/544afe5c6f1e?pwd=4vCC
• 百度网盘：https://pan.baidu.com/s/1sa3Dmof-bscMqjPMl-bzrw?pwd=0000（提取码 0000）

下表列出离线投放能装的全部模块。投放时都放进同一个 offline-drop，软件会自己装到下表「装到哪里」那一列的位置（相对数据目录），你不用自己拷，那一列方便排查。<版本号> 是软件按包内版本自动建的文件夹，_store 存放依赖包和模型权重。模块怎么启动、三层状态怎么看，见第 09 章：运行时模块。

版本与升级

• 只针对上表里的官方 zip / tar.gz：投放目录里有更高版本时会升级；已装的版本相同或更高就跳过，不会用旧包降级。
• 应用内「下载/更新」会联网查询；断网时可能提示使用内置版本，同样不会降级。
• .gguf 和 ggml-*.bin 不受版本规则约束，按下一节更换。

更换或升级本地模型（.gguf / ggml-*.bin）

1. 下载新模型文件，不要再包一层 zip，原样放进 offline-drop。
2. 扫描 → 勾选该模型 → 「安装已勾选」（「安装推荐」也会带上已识别的模型）。
3. models 目录里已有同名文件时，「安装模式」要选覆盖安装，否则会提示 model already exists (use replace)。换个文件名就能和旧模型并存，例如 ggml-base.bin 和 ggml-small.bin。
4. 装完到「文本模型」或「语音识别」里重新选中新文件并保存。Llama / Whisper 已在运行的话，重启对应运行时再用。

也可以直接把模型拷进 models\text_generation\ 或 models\speech_recognition\，再在界面里选中。这条路不经过扫描和校验，网盘没下完的半截文件不要直接拷进去。

装完怎么确认

• 设置 → 本地引擎：对应卡片显示「已安装」和版本号。
• 配音 / 音乐 / 人声：卡片能启动服务，或「预下载」显示已就绪。
• 文本 / 语音识别：在对应模型配置里能选到刚投放的 .gguf 或 ggml-*.bin。

仍显示未安装时：核对文件名和上表完全一致（.gguf / ggml-*.bin 核对扩展名）；再点一次「扫描」→「安装推荐」；重启应用后刷新列表；提示 LAUNCHER_REQUIRED 就先装同一引擎的启动器包。