Portable 安装与构建
约 7754 字大约 26 分钟
版本：V0.1.20.0 Alpha (0.1.20.0-alpha)
本文介绍 Windows Portable 的发行结构、模型准备、运行依赖和构建方法。第一次使用请按下方用户指南完成安装；升级前停止服务并备份运行目录，数据库完整格式校验通过时可复用，不兼容格式会保留并拒绝启动。常见问题见故障排查。
普通用户请先阅读：Portable 小白使用说明。该说明按 Windows 用户从下载、校验、解压、首次启动到第一次录制的顺序编写。
项目入口见README，业务链路见使用指南与热点检测器，源码冻结和验证约定见开发与维护。完整更新记录见主 Changelog与历史归档索引。
Portable 包提供与源码运行相同的录制、转写、高光分析、审核与剪辑功能；已有视频可通过录播导入分析。转写引擎、设备和模型准备见语音转写指南。
Launcher 内嵌发布时冻结的完整业务源码，首次启动不需要从 GitHub 下载业务源码。实际源码身份以发行物的 version.json 和 Payload 清单为准。Full 版自带 Python 3.12、离线依赖和 FFmpeg；Lite 版需要目标电脑已有 Python 3.11/3.12，并自行满足 FFmpeg 等运行组件。
Payload 从 EXE 内置资源释放，版本固定并校验 SHA-256，安装阶段不依赖 GitHub 业务源码。
系统要求
Full 默认随附 CPU 版依赖。使用 NVIDIA GPU 转写前，可运行 BiliLiveCut-Portable.exe --torch-runtime cu126（或 cu130）安装官方哈希锁定的 CUDA 配套包，完成后退出；选择持久化并在后续启动、虚拟环境修复时保留。完全离线需把对应 ABI 的 CUDA wheel 放入 vendor/wheels/ 并加 --offline，恢复 CPU 使用 --torch-runtime cpu。实际显卡、驱动、Torch 与 CTranslate2 能力分别诊断，详见CUDA 使用说明。
| 项目 | 最低 | 推荐 |
|---|---|---|
| 操作系统 | Windows 10/11 x64 | Windows 11 |
| Python | Full 无需系统 Python；Lite 需要 3.11 或 3.12 | 3.12 |
| 内存 | 8 GB | 16 GB |
| 磁盘 | 15 GB 空闲（仅短时测试） | 30 GB 以上（含模型和录制存储） |
| 网络（运行时） | 需要 — 录直播、采集弹幕、调大模型等均需联网 | — |
| 网络（安装） | Lite: 首次安装需联网拉取依赖；Full: 预置完整，组件安装无需额外下载；模型: 通过独立 Engine Pack 或在线下载安装；账号登录: 无系统 Chrome 时会下载 Chromium | — |
| 原生构建工具 | 运行发行包不需要 | 构建发行包时准备 Visual Studio Build Tools、Rust，详见开发环境 |
发行结构
- 首次运行从 EXE 内置 Payload 释放固定版本源码，完整
payload_manifest.json记录逐文件 SHA-256。 - Runtime 通过
staging → rename原子切换，并以当前格式的current.json记录激活状态。 - 发行提供 Lite（轻量单 EXE）与 Full（预置完整依赖）两种形式。
Lite 与 Full
两种发行方式均面向联网运行场景（直播监听、弹幕采集、大模型调用等均需网络）。区别仅在于安装阶段是否需要额外从互联网下载组件。
| Portable Lite | Portable Full | |
|---|---|---|
| 定位 | 轻量化，方便下载分发 | 完整包，开箱即用 |
| 下载大小 | 以对应 Release 附件为准 | 以对应 Release 附件为准，解压后需要更多空间 |
| 内含 | EXE + 业务源码 Payload | EXE + Portable Python + Wheels + FFmpeg |
| 安装过程 | 首次安装时在线下载 Python 依赖；FFmpeg 需另行准备 | 预置 Python、依赖和 FFmpeg，组件安装无需额外下载 |
| 模型 | 不含模型，通过独立 Engine Pack 或在线下载安装 | 不含模型，通过独立 Engine Pack 或在线下载安装 |
| 适用场景 | 熟悉 Python/FFmpeg 的高级用户 | 普通用户、小规模分发测试 |
Engine Pack 内容清单仅支持 schema 5，已安装模型清单仅支持 schema 7，不迁移旧 schema。模型仓库、不可变 revision、格式、子模型/随附组件及逐文件完整性必须符合当前定义；发行版本或源码提交差异仅记录来源警告，内容相同的旧包及完整安装目录可以复用。Runtime、Payload 和数据库继续遵循各自严格身份与格式规则。
Portable Engine Pack — 独立四引擎模型包
Lite 和 Full 均不携带 ASR 模型。四个引擎模型统一由独立的 Engine Pack 提供。
四种引擎
| 引擎 | 模型 ID | 来源 | 版本 |
|---|---|---|---|
| Whisper (兜底) | faster-whisper-large-v3-turbo | Hugging Face (dropbox-dash/) | 0a363e9161cb |
| Paraformer-zh (次级回退) | paraformer-zh | ModelScope | v2.0.4 |
| SenseVoice-Small (辅助特征) | iic/SenseVoiceSmall | ModelScope | 7bf452403abd |
| Fun-ASR-Nano (主引擎) | FunAudioLLM/Fun-ASR-Nano-2512 | ModelScope | 05201c46f1c3 |
Paraformer 额外需要
fsmn-vad/ct-punc两个子模型（自动下载）。
使用方式
- 准备可信的 BiliLiveCut-EnginePack-*.zip（包括内容兼容的旧发行模型包）
- 放在 Launcher EXE 同级目录 (或 packages/ 子目录)
- 双击启动 Launcher → 外部摘要比对（有发布摘要时）→ ZIP 结构、schema、模型身份与逐文件 SHA-256 全部通过 → 离线安装（网络请求 0）
- 包缺失记录
local_not_found；包拒绝记录local_rejected及具体阶段。扫描既有models/后，只有允许联网回退时才准备缺失或内容变化的引擎，--offline禁止下载
ZIP 中的 engine-pack-manifest.json 可以直接位于根目录，或全部内容置于唯一一层包装目录。多个 manifest、多层包装、包外条目和歧义路径均拒绝。没有期望 CRC32/SHA-256 时只计算摘要并明确记录，不会伪称外部摘要已验证，也不会跳过内部验证。
摘要与内部校验
| 行为 | 说明 |
|---|---|
| CRC32 匹配 | 仅代表外部摘要相符；仍必须通过内部 manifest、模型身份及全部文件校验 |
| CRC32 不匹配 | 拒绝该 ZIP，保留既有有效模型，只在线准备缺失/变化的引擎 |
| 本地包缺失 | 扫描既有模型，逐引擎复用或在线准备 |
| 内部 Hash 失败 | 拒绝不可信 ZIP，不破坏已经提交的有效模型 |
Engine Pack 内容清单仅支持 schema 5，已安装模型清单仅支持 schema 7，不迁移旧 schema。模型仓库、不可变 revision、格式、子模型/随附组件及逐文件完整性必须符合当前定义；发行版本或源码提交差异仅记录来源警告，内容相同的旧包及完整安装目录可以复用。Runtime、Payload 和数据库继续遵循各自严格身份与格式规则。
模型安装目录
<程序根目录>/
├── BiliLiveCut-Portable.exe
├── models/
│ ├── whisper/ # Whisper large-v3-turbo
│ ├── paraformer/ # Paraformer-zh + vad/punc
│ ├── sensevoice/ # SenseVoice-Small
│ ├── funasr_nano/ # Fun-ASR-Nano
│ └── engine-pack-installed.json # 安装清单 (自动生成)模型安装在程序 Portable 根目录的 models/ 下，不写入用户主目录缓存。
构建 Engine Pack
cd packaging\portable
python build_engine_pack.py # 真实下载四引擎模型并打包
python build_engine_pack.py --fixture # 生成测试用小型 Fixture
python download_engines.py # 可选：按锁定 revision 建立本地缓存
python build_engine_pack.py --from-cache # 从已验证缓存构建--fixture 按统一模型目录生成必需文件的非空占位内容，可通过真实安装器验证安装、摘要和内容身份；它不包含可推理模型，不能作为正式 Engine Pack 分发。Release 的冻结启动器 smoke 使用此包验证离线模型准备，缺失或空必需文件仍会被拒绝。
输出:
- dist/engine-pack/BiliLiveCut-EnginePack-0.1.20.0-alpha.zip
- dist/engine-pack/engine-pack-manifest.json
- dist/engine-pack/CRC32SUMS.txt
- dist/engine-pack/SHA256SUMS.txt
- 包内 licenses/THIRD_PARTY_NOTICES.md、MIT.txt、Apache-2.0.txt
resources/engine_pack_info.json (本地 Engine Pack 构建后可供 Lite/Full EXE 嵌入；GitHub Release 不嵌入 fixture)
正式构建会执行再分发门禁：主模型、Paraformer 子模型及 Fun-ASR-Nano 随附的 Qwen3 组件必须具有固定来源、许可证证据、验证日期和随包许可证文件；任一项缺失都会终止构建。完整归属见 licenses/THIRD_PARTY_NOTICES.md。
BiliLiveCut 项目代码采用仓库根目录的 MIT License，Copyright (c) 2026 StarGazerQQD。上述第三方 MIT / Apache-2.0 文件仅适用于所列模型及组件；项目许可证不改变任何第三方条款。
注意事项
- Engine Pack 预计体积 ≥ 4 GB，请使用 NTFS 或 exFAT 文件系统 (FAT32 不支持单文件 >4GB)
- CRC32 为 8 位大写十六进制，流式计算，不将整个文件读入内存
- SHA-256 用于发布文件校验和逐文件完整性验证
- 已安装模型有效时不会重复解压或下载
- 应用升级不会自动删除模型目录
下载与启动
方式一：下载 Lite 版（高级用户，体积小）
- 确保电脑已装 Python 3.11 或 3.12（终端输入
python --version检查），并自行准备 FFmpeg/FFprobe - 双击
BiliLiveCut-Portable-Lite-*.exe - 等待自动部署（首次约 10-30 分钟，视网速而定）：
| 步骤 | 内容 | 大小 | 说明 |
|---|---|---|---|
| ① | 释放源码 Payload | ~426 KB | 从 EXE 内置 Payload 释放 app/ config/ pyproject.toml setup.py 等，无需 GitHub |
| ② | 创建虚拟环境 | — | .venv 隔离 Python 依赖 |
| ③ | 安装依赖 | ~500 MB | 内嵌 5 个经哈希校验的 bootstrap wheel，其余依赖从用户配置的 Python 包索引下载且只接受二进制 wheel |
| ④ | 模型准备 | — | 校验当前内容清单 → 校验本地 Engine Pack → 逐引擎复用或在线补齐 |
| ⑤ | 检查 FFmpeg | — | Lite 当前不内置 FFmpeg；需要系统 PATH 可用，或在 bin/ 提供 ffmpeg.exe/ffprobe.exe |
| ⑥ | 生成 .env 配置 | — | 含合理默认值 |
断点续跑：模型下载 staging 以引擎内容指纹持久化；每个引擎完成后立即独立原子提交。后续引擎失败或进程中断不会回滚已经成功的引擎，再次双击只续传未完成部分。 源码固定：发行包使用冻结的源码快照，不随上游更新而自动改变。源码提交可在
version.json和 Payload 清单中核对。
- 部署完成后按 Launcher 输出的地址打开 Web 管理控制台（首次默认
http://127.0.0.1:8000；未自动弹出时请手动访问）
Web 端口可在控制台“配置 → 功能开关 → Web 管理端口”保存为 1..65535。保存不会热重绑当前服务；重启 Launcher 后才使用新端口。持久化文件是安装根目录的 config/launcher.json，位于内容寻址 Runtime 之外，因此业务源码升级或 Runtime 修复不会覆盖它。损坏 JSON 只会告警并回退到默认端口，Launcher 不会覆盖损坏现场；配置端口被占用时也会直接报错，不会随机选择其他端口。
Web 认证：如需保护管理后台，在
.env中设置ADMIN_PASSWORD=你的密码。所有 API 操作将要求输入 Basic Auth（用户名固定为admin）。
方式二：下载 Full 版（完整包，安装无需额外下载）
拿到 BiliLiveCut-Portable-Full-*.zip，解压到任意目录，双击 BiliLiveCut-Portable.exe。启动器自动检测同目录下的 portable-python/、vendor/wheels/、bin/ffmpeg.exe，安装过程无需从互联网拉取任何额外组件；包内 LICENSE.txt 是项目代码的 MIT License。
运行依赖锁维护
Portable 使用 Python 3.11 / 3.12 两套 Windows x64 完整依赖锁。锁文件覆盖直接依赖和全部传递依赖（包括大模型连通测试所需的 OpenAI 兼容 SDK），每个条目都固定为 == 版本并校验所选 wheel 的 SHA-256。pip 固定为 26.2，Launcher 使用 pip freeze --all 检查当前环境；不符合当前锁的环境会重建。PyPI 没有提供 wheel 的五个纯 Python 包由受控脚本从固定 SHA-256 的源码构建，构建工具版本和时间戳同样固定；这 5 个 wheel 会作为最小 bootstrap 集内嵌进 Lite EXE。Lite 联网安装其余依赖时使用 --only-binary=:all: --require-hashes，不会静默回退到 sdist。
python -m pip install setuptools==84.1.0 wheel==0.47.0
python scripts/build_portable_runtime_wheels.py --output-dir packaging/portable/dist/bootstrap-wheels
python scripts/generate_portable_runtime_locks.pyRelease CI 对两套锁执行带哈希校验的下载、全新虚拟环境离线安装、pip check 和核心模块导入测试，并验证 Launcher 安装、模型准备中断恢复、持久化端口和虚拟环境修复。发布前交叉核对 Payload、Lite、Full 的版本、源码与构建提交，以及实际 SHA-256 / CRC32。
Lite 的 bootstrap wheels 仅用于引导安装，完整虚拟环境损坏后仍需联网恢复；Full 从 vendor/wheels 离线恢复依赖，目录缺失或为空时直接报错。维护依赖锁时，保留完整依赖和哈希校验，不通过跳过依赖或离线安装检查绕过兼容错误。
方式三：开发者手动构建当前发行物
在一台能联网的机器上执行：
cd packaging\portable
python build_payload.py
python build_exe.py --without-engine-pack
python build_full_bundle.py若还需独立模型包，执行 python build_engine_pack.py --from-cache（已有完整缓存）或 python build_engine_pack.py（联网下载）。构建缓存必须有当前发行版与锁定模型定义的下载记录；缺失时先运行 python download_engines.py。构建器仍严格检查当前发行身份；消费端按上述内容契约接受模型包与已安装目录。
目录结构
packaging/portable/ # ★ 即插即用分发版根目录 (原 Publish-PnP)
│
├── launcher.exe # ★★ 核心入口：双击即用，从内置 Payload 释放源码 + 部署
├── launcher.py # launcher.exe 的 Python 源码（可选，便于审查）
├── build_exe.py # Lite 版构建 (PyInstaller one-file)
├── build_full_bundle.py # Full 完整包构建脚本
├── build_payload.py # Payload 构建器 (冻结源码 → source_payload.zip)
├── portable_launcher.spec # PyInstaller 规格文件
├── pip.ini # pip 镜像源配置（阿里云 + 清华备用）
├── .env.example # 配置模板（launcher.exe 自动生成 .env）
├── .gitignore # Git 忽略规则
├── tests/ # Portable 构建、安装、安全与制品测试
├── build/ # 构建临时文件（gitignore 忽略）
├── dist/ # 构建产物
│ ├── payload/ # source_payload.zip + manifest
│ ├── lite/ # Lite EXE
│ ├── full/ # Full ZIP
│ └── engine-pack/ # Engine Pack ZIP
└── README.md # 本文件源码去哪了？
app/config/pyproject.toml等业务文件不在分发目录中，而是内嵌在launcher.exe内部作为 source_payload.zip（从配置中固定的发布提交提取，SHA-256 可校验）。launcher.exe首次运行时自动将 Payload 解压到runtime/releases/目录。PnP 目录始终保持最小体积，源码不受工作区未提交内容影响。
运行时动态生成（首次启动后）
├── runtime/ # ★ Runtime 版本管理
│ ├── current.json # 当前激活的 Release 信息
│ └── releases/
│ └── 0.1.20.0-alpha+<source-sha>+<payload-hash>/ # 内容寻址的固定版本源码
│
├── .venv/ # Python 虚拟环境（launcher.exe 自动创建）
├── models/ # 四引擎 ASR 模型 (由 Engine Pack 或在线下载安装)
│ ├── whisper/ # Whisper large-v3-turbo (兜底引擎)
│ ├── paraformer/ # Paraformer-zh (次级回退)
│ ├── sensevoice/ # SenseVoice-Small (辅助特征)
│ └── funasr_nano/ # Fun-ASR-Nano (主引擎)
├── bin/ # ffmpeg.exe / ffprobe.exe（首次运行下载，约 80 MB）
│
├── vendor/wheels/ # Full 构建使用的严格哈希离线依赖
├── data/ # 数据库
├── storage/ # ★ 运行产物目录
│ ├── raw/ # 原始录制片段
│ ├── clips/ # 成品切片
│ └── ready_to_upload/ # 待上传清单
└── .env # 用户配置文件（首次运行自动生成）Web 控制台各功能页说明
启动后在浏览器中打开的 Web 控制台包含以下 Tab：
| Tab | 功能 | 前置条件 |
|---|---|---|
| 直播间 | 添加房间号、开关录制 | 无 |
| 录制状态 | 当前录制进度、断流/重连状态 | 已添加房间 |
| 录制预约 | 定时自动录制（每日/单次） | 已添加房间 |
| 实时转写 | 按录制场次查看完整历史、多引擎 ASR、人工纠错与源 TS 导出 | 已产生转写 |
| 弹幕热度 | 按录制场次查看完整弹幕历史、登录优先和匿名兜底统计 | COLLECT_DANMAKU=true（无需登录也可用） |
| 网感资料库 | 联网采集热点话题/标签 | 已配置大模型 API |
| 候选审核 | 高光片段候选列表、横屏审片工作台 | 已完成分析 |
| 成品切片 | 已剪辑的视频、封面、文案（含多版本变体） | 已生成切片 |
| 主题管理 | 高光话题聚合、合集编辑 | 已有候选数据 |
| 上传与发布 | Biliup 与自动上传全局总开关、上传队列 | — |
| 功能开关 | 每个直播间的五项流水线开关、辅助开关和审核阈值 | 已添加房间 |
| 模型 | 多 LLM 服务商配置、优先级、当前表单连通测试 | — |
| 账号管理 | 扫码登录 Bilibili、自动采集 Cookie | — |
| 运维面板 | 任务队列监控、Worker 状态、失败重试 | — |
| 错误日志 | WARNING/ERROR 级别日志 | — |
Hugging Face 在线供给与镜像配置
模型下载进度按 SDK 实际计数显示，突发传输后的慢速小增量也会继续刷新；停滞时仍显示用时，未知总量或速率不伪造百分比和 ETA。下载完成后的文件校验独立执行。
启动器、Engine Pack 构建器及缓存下载器使用锁定的 huggingface-hub==1.30.0。SDK 支持镜像向官方 Hub 的绝对 308，以及带查询参数的相对跳转；文件元数据校验、固定 revision 和断点续传保持生效。
默认按 hf-mirror.com、huggingface.co 有限回退。镜像若委派回官方，最终仍需要能访问官方站点；主页能打开并不能证明模型文件可下载。若有独立且可信的 Hub 镜像，可在启动前设置进程环境变量：
$env:HF_ENDPOINT = "https://your-trusted-hub.example"
.\launcher.exe自定义地址覆盖默认列表，不会在失败后悄悄改用其他配置源；该服务器自身仍可能通过重定向委派到其他主机。允许 HTTPS 地址及必要的路径前缀，拒绝内嵌账号密码、查询参数、片段、控制字符及无效端口。Portable 下载不会向任何源发送本机缓存的 Hugging Face Token。不要填写不受信任的第三方地址。
在线供给发生在业务 .env 加载之前，因此仅在 .env 写入此项不会影响 Portable 下载；Docker 的 env_file 会将它传入容器进程。修改后重新启动；清除 $env:HF_ENDPOINT 可恢复默认策略。失败诊断会区分配置、网络、HTTP、文件元数据和本地磁盘问题，并保留实际失败主机名。
自定义镜像必须支持 Hub API、固定 revision、ETag 和 Content-Length；缺少必要元数据时明确失败，不伪造大小或跳过完整性检查。可换用满足协议的可信源、为实际下载主机配置代理，或提供当前内容兼容的 Engine Pack。更换端点复用已有逐引擎 staging 目录，不要求删除已经下载的模型文件。
配置文件 .env 详解
launcher.exe 首次运行会自动生成一份含默认值的 .env。以下逐段说明每个配置项的含义及何时需要修改。
通用与管理认证
APP_ENV=dev # dev=开发(更多日志) / prod=生产
LOG_LEVEL=INFO # DEBUG / INFO / WARNING / ERROR
ADMIN_PASSWORD= # ★ Web 管理后台密码（空则不启用认证，用户名固定 admin）存储
STORAGE_ROOT=./storage # 所有产物（录制片段、切片、数据库、日志）的根目录
DATABASE_URL=sqlite:///./storage/blc.db # SQLite 数据库路径，一般不改FFmpeg
FFMPEG_PATH=ffmpeg # Full 会使用随包 bin/ffmpeg.exe；Lite 需自行准备
FFPROBE_PATH=ffprobe # Full 会使用随包 bin/ffprobe.exe；Lite 可使用系统 PATH录制 / 分片
SEGMENT_DURATION_S=300 # 分片目标 300 秒；按关键帧落盘，实际时长允许小幅浮动
PREFERRED_STREAM_PROTOCOL=hls # 取流协议：hls（稳定）或 flv
STREAM_QUALITY=10000 # 清晰度：10000=原画，400=蓝光，250=超清
RECONNECT_MAX_BACKOFF_S=30 # 断流后最大重试等待秒数
LIVE_POLL_INTERVAL_S=15 # 检查直播间开播/下播的间隔（秒）
RECORDING_RECONNECT_MAX_ATTEMPTS=20 # 连续无法恢复的次数上限；成功产出片段后归零，0=禁用次数限制
RECORDING_RECONNECT_MAX_ELAPSED_S=300 # 连续断流最长秒数；成功产出片段后归零，0=禁用时间限制
COLLECT_DANMAKU=true # 录制时采集公开弹幕（登录优先、匿名兜底）
DANMAKU_LOGIN_RETRY_MAX_ATTEMPTS=5 # 单场登录失败上限（首次计入）；0=始终匿名
DANMAKU_LOGIN_RETRY_INTERVAL_S=60 # 匿名采集期间重试登录链路的间隔（秒）
RECORDING_PIPELINE_ENABLED=true # 新录制默认启用实时转写与高光分析；控制台运行时开关优先Bilibili Cookie（可选，用于部分高清访问）
REQUIRE_AUTHORIZATION=true # 必须设为 true，确认你有权录制
BILIBILI_COOKIE= # 可选登录态 Cookie，用于平台允许的部分高清晰度
# 【账号管理】优先使用系统 Chrome；没有 Chrome 时自动下载 Chromium
# 手动填写格式：DedeUserID=xxx; SESSDATA=xxx; bili_jct=xxx重要：公开弹幕不登录也能采集；存在 Cookie 时程序会优先使用登录接口，业务错误后立即改用无 Cookie、
uid=0的匿名链路。匿名连接期间会定时探测登录恢复，累计失败达到配置上限后本场固定匿名。Cookie 不会写入日志，也不会作为 WebSocket 请求头发送。 【账号登录】默认通过“扫码登录”在网页显示二维码，用手机 Bilibili 扫描并确认后保存 Cookie，不需要安装或下载浏览器。Portable 同时保留“浏览器登录”：在独立临时资料目录中启动电脑已安装的 Google Chrome，并保持浏览器 sandbox 开启；只读取此次登录窗口产生的 Cookie，不读取日常 Chrome Profile。找不到可用 Chrome 才联网下载 Playwright Chromium，保存到vendor/playwright-browsers/供后续复用。
ASR 语音转写（本地多引擎，无需联网）
# 主引擎（V0.1.12）
ASR_PRIMARY=funasr_nano # 默认 FunASR；也可设为 paraformer / whisper
ASR_VAD_MAX_SEGMENT_S=30 # Nano 的 FSMN-VAD 单句上限（秒）
ASR_PRIMARY_DEVICE=cpu # 主引擎设备，首次测试保持 cpu
ASR_AUXILIARY_DEVICE=cpu # 辅助引擎设备
ASR_REVIEW_DEVICE=cpu # 复核引擎设备
ASR_FALLBACK_DEVICE=cpu # 兜底引擎设备
# 辅助层
ASR_SENSEVOICE=true # 情感/笑声/音乐/事件检测（需 funasr + modelscope）
ASR_FUNASR_REVIEW=true # Paraformer 主路径下启用低置信片段 FunASR 复核
ASR_FALLBACK_WHISPER=true # 主引擎失败时自动回退 Whisper
WHISPER_MODEL=small # Whisper 兜底模型
WHISPER_DEVICE=cpu # Whisper 设备
WHISPER_COMPUTE_TYPE=int8 # CPU 推荐 int8若显式配置的 WHISPER_COMPUTE_TYPE 不受当前 CPU/CUDA 后端支持，Whisper 兜底会记录一次明确告警并改用 CTranslate2 的 auto 类型重试；模型损坏、CUDA 驱动不匹配和显存不足等其他错误仍会原样报告。
录制 TS 会先转换为 16 kHz 单声道 PCM WAV，Nano 再复用 Engine Pack 中的 FSMN-VAD 拆句。空输出、整段重复退化或长正文中的局部解码循环会依次切换 Paraformer、Whisper；最终仍不合格时不会落库，也不会调用 LLM 或高光分析。LLM 整理会保守清除残余的 ASR/VAD 边界复读，并保留有语义的强调、复述和口头禅。实时转写页可对历史污染结果执行“重新识别”，人工审核、确认主题与成片资产不会被自动覆盖。
大模型（可选，用于转写梳理 / 高光复核 / 文案 / 网感采集）
LLM_DAILY_BUDGET=0 # 每日预算上限（0=不限）
TRANSCRIPT_LLM_REFINE_ENABLED=true # 每个切片 ASR 后整理正文并生成概括；失败保留原始文本
TRANSCRIPT_LLM_REFINE_MAX_TOKENS=65536 # 五分钟转写整理的最大输出预算
HIGHLIGHT_LLM_MAX_TOKENS=65536 # 高光复核的最大输出预算（含推理 token）多模型配置：服务商、base_url、模型、联网参数、价格和 API Key 只在 Web 控制台「模型」Tab 管理。可同时添加 DeepSeek / 通义千问 / Kimi / 智谱 GLM 等服务商并设置优先级，某个不可用时自动切换到下一个。“测试连通”直接测试当前表单且不会保存 API Key；页面会显示每个服务商的响应或错误详情，确认无误后再点击“保存全部”。旧的 .env 服务商字段（如 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL）已废弃；LLM_REQUEST_TIMEOUT_S 等运行参数仍有效。转写梳理可在「配置 → 功能开关」独立关闭，关闭后仍保留本地 ASR 原文。两类五分钟切片请求默认各预留 65536 个最大输出 token，实际消耗仍以服务商返回为准。
网感资料库（可选，用于热点采集）
TREND_ENABLED=false # 是否启用网感资料库
TREND_API_KEY= # 趋势采集专用 API Key；留空使用首个启用的大模型
TREND_BASE_URL= # 趋势采集专用 base_url
TREND_MODEL= # 趋势采集专用模型
TREND_WEB_SEARCH=true # 是否开启联网搜索（时效性强）
TREND_WEB_SEARCH_PARAM=enable_search # 专用模型的联网搜索开关键名
TREND_MAX_ITEMS=12 # 单次采集入库条目上限（避免模型输出被截断）
TREND_RETENTION_DAYS=14 # 资料库保留天数
TREND_MATCH_DAYS=7 # 高光评分参考"近期"窗口（天）启用后可在「网感资料库」Tab 手动触发采集，或开启「定时采集」每日自动迭代。
高光判断阈值
HIGHLIGHT_INIT_THRESHOLD=0.35 # 进入 LLM 复核的初筛阈值（0-1）
HIGHLIGHT_THRESHOLD=0.45 # 进入候选池的综合评分阈值（0-1）
HIGHLIGHT_REVIEW_THRESHOLD=0.40 # 进入人工审核的综合评分阈值（0-1）
HIGHLIGHT_AUTO_APPROVE_THRESHOLD=0.72 # 自动批准候选的综合评分阈值（0-1）
AUTO_PUBLISH_THRESHOLD=0.80 # 全自动模式下直接发布的阈值（0-1）阈值越低越容易切片（更多候选但可能含低质），越高越严格（少而精）。
高光复核理由、关键词等文本特征只读取音频峰值对应的候选窗口；最终成片强制完整覆盖该分析窗口，LLM 只能向外扩展边界，静音吸附也不会向内切掉理由所描述的事件。候选审核正文和投稿文案会按最终保存的成片边界再次裁剪；词级时间戳是当前转写结果的必需数据。
切片后处理
CLIP_LOUDNORM=true # 响度标准化（EBU R128），推荐开启
CLIP_REMOVE_SILENCE=false # 去除首尾静默段
CLIP_VERTICAL=false # 竖屏重构 1080x1920（适合手机端）
CLIP_SUBTITLE=false # 烧录字幕（从转写生成 SRT）
CLIP_MAX_DURATION_S=180 # 单个切片最大时长（秒）
CLIP_VIDEO_CRF=20 # x264 画质（0-51，越小越清晰）
CLIP_PRESET=veryfast # 编码速度：ultrafast / veryfast / medium / slow上传
UPLOAD_MAX_RETRIES=3 # 上传失败重试次数
UPLOAD_MAX_PER_HOUR=5 # 每小时投稿上限（频控）
TITLE_MAX_LEN=80 # 标题长度上限
DESC_MAX_LEN=2000 # 简介长度上限biliup 上传（社区方案，合规风险自负）
BILIUP_CONFIG= # biliup 配置文件路径（如 cookies.json）
BILIUP_UPLOAD_CMD= # 自定义上传命令模板
# 例：BILIUP_UPLOAD_CMD=biliup upload "{file}" --title "{title}" --desc "{desc}"⚠ B 站无面向普通用户的官方公开投稿 API。biliup 使用你自己的登录态走网页投稿端点，可能违反平台条款、触发风控甚至封号。是否启用由你决定，风险自负。
首次使用完整流程
- 双击发行包中的 Portable EXE → 等待自动部署完成（Lite 版需联网安装依赖；Full 版依赖离线安装，但两者在没有 Engine Pack 时都需联网下载约 5.5 GB 模型）
- 打开 Web 控制台；Cookie 为可选项，首次公开直播录制可跳过「账号管理」
- 「直播间」Tab → 粘贴直播间链接（如
https://live.bilibili.com/123456）→ 勾选授权确认 → 添加 - 「功能开关」Tab → 为该房间逐项开启所需的自动录制、分析、渲染、审核和上传；首次测试建议只开启到“自动分析”，确认各阶段后再逐步扩大
- 在房间卡片点击「开始录制」，并在「录制状态」确认片段数量增加
- 首次测试先在
storage/raw/session_<id>/确认原始片段；需要转写或候选时确认该房间“自动分析”已开启 - 已产生候选时，可在 「候选审核」Tab 点击「批准并出片」，再到 「成品切片」Tab 查看
- 成品（MP4 + 封面 + 文案）输出在
storage/clips/目录；房间“自动上传”还需配合“上传与发布”页的全局总开关
拒绝候选会同步停止其未终结工作流，并从成品列表隐藏所有未发布的关联切片；已经发布的记录保留真实外部状态。审片预览与 LLM 理由使用同一候选时间窗，最终成片至少完整覆盖该窗口。
可选增强：在 Web「配置 → 大模型」启用服务商并填写 API Key 后，高光复核、整场 ASR 全局分析和文案生成将由大模型辅助（否则走纯规则；整场全局分析会明确显示不可用）。 安全建议：多人共用或暴露在局域网时，设置
ADMIN_PASSWORD启用 Web 后台认证。
常用故障排查
| 问题 | 解决 |
|---|---|
启动报 python 不是命令 | Full 应检查 portable-python/python.exe；Lite 需安装 Python 3.11/3.12 并加入 PATH |
| Payload 释放失败 | 检查 EXE 完整性，SHA-256 不匹配时自动拒绝安装 |
| 下载模型卡住不动 | 关闭窗口重新双击；已完成引擎和带完成标记的指纹 staging 会直接复用，未完成引擎由 SDK 续传 |
ASR 报 funasr / modelscope 未安装 | Full 应重新校验并解压完整 ZIP；Lite 需重新完成依赖安装 |
| ASR 主引擎无法加载 | 检查 models/ 是否完整；无 Engine Pack 时首次需联网下载模型 |
| 主播下播后仍显示重连 | 默认会在连续失败 20 次或 300 秒后自动收尾；检查 RECORDING_RECONNECT_MAX_ATTEMPTS 与 RECORDING_RECONNECT_MAX_ELAPSED_S 是否被设为 0 |
| 时间线摘要与预览内容不一致 | 确认本场全部 ASR 已完成，再执行“按新阈值重分析”或“按新词典/模型重新转写”；整场总结会把全部最终 ASR 组成一次上下文后重新分析 |
| 拒绝候选仍出现在成品列表 | 当前版拒绝操作会同步未发布关联成片；若仍出现请携带候选/成片 ID 和日志反馈 |
弹幕采集提示 code=-352 | 匿名 token 请求被平台风控拒绝；稍后重试，不要反复登录。录制与实时转写不受影响 |
| LLM 调用报错 / 空结果 | 在 Web「配置 → 大模型」检查服务商、base_url、模型和 API Key，并使用“测试连通”核验 |
| FFmpeg 未找到 | Full 应检查 bin/ffmpeg.exe 与 bin/ffprobe.exe 是否完整；Lite 需自行准备 FFmpeg |
| API 请求返回 401 | .env 中设置了 ADMIN_PASSWORD，浏览器需要输入用户名 admin + 密码 |
修改 .env 后不生效 | 重启 launcher.exe |
launcher.exe 被杀软拦截 | 添加信任白名单 |
| Runtime 损坏 | 先备份 .env 与 storage/，再执行 BiliLiveCut-Portable.exe --repair；不要直接删除用户数据 |
回主工程
此 packaging/portable/ 目录是发布给最终用户的即插即用版本，源码固定于本版本构建清单记录的 source_commit，不随远端分支变化。
React 前端构建
Portable 构建机需要 Node.js 24 与 npm。Payload 从已冻结的源码提交提取 frontend/，执行 npm ci 和 npm run build，仅把 frontend/dist/ 加入 Payload；不打包 node_modules 或前端开发源码。运行 Portable 无需 Node.js，Launcher 调用 start 启动独立前端和本机 API 进程。
引入前端或后端源码修改后，需要先提交源码，再按已有发布流程同步 Payload 的源码基线并重新构建；旧基线不包含 React 入口，构建会明确拒绝混用。