BiliLiveCut 文档

外观

BiliLiveCut Portable 小白使用说明

约 11143 字大约 37 分钟

适用版本：v0.1.20.0-Alpha · 适用系统：Windows 10/11 x64

本版重构任务提交、执行资源、配置生效、模型路由和页面状态恢复。设置中心显示配置何时生效，同一模型连接可供不同业务独立选择模型；取消任务后不会被迟到结果改成成功。下载、录制和运行失败继续保留根因，Web 错误提供日志定位编号。启动失败记录保存在 logs/launcher-error.log，详细排错见使用指南。升级前应停止服务并备份；数据库完整格式校验通过时可以复用，操作边界见第 13 节。

这份说明面向不懂 Python、Git 或命令行的普通 Windows 用户。按顺序操作即可完成下载安装、首次启动、基础配置、添加直播间和首次录制。

需要了解程序架构、构建或版本变化时，请查看项目 README、Portable 构建说明、当前 Changelog和历史归档索引。V0.1.17～V0.1.17.4 的逐项记录位于独立归档。

BiliLiveCut 只能用于你拥有录制和使用授权的内容。不要录制、剪辑或传播未经授权的直播内容。

先看结论

  • 新手请选择 Full 完整版 ZIP，不要先用 Lite 单 EXE。
  • Full 已包含 Python、程序依赖、FFmpeg 和 FFprobe，不需要自己安装开发工具。
  • Full 不包含语音模型。如果没有当前发行版本的 Engine Pack 或已通过同版清单校验的 models/，首次启动仍需联网下载约 5.5 GB 模型。
  • 程序运行时会出现一个黑色 Launcher 窗口。使用期间不要关闭它；关闭后 Web 控制台和录制都会停止。
  • 服务启动后按黑色窗口打印的地址访问；首次默认是 http://127.0.0.1:8000。当前版本不保证自动打开浏览器。
  • “账号管理”会优先调用电脑已安装的 Google Chrome；没有 Chrome 时会自动下载一次 Playwright Chromium。
  • 第一次测试先完成一小段授权直播录制，并在 storage/raw/ 找到文件。Cookie、大模型 API 和自动上传都不是首次使用的必需项。

V0.1.20.0 Alpha 先知道的新流程

  • 设置中心区分立即生效、下一次任务或资源申请生效、重启生效，并展示等待生效事项；正在运行的任务与录制使用原快照。模型连接统一保存凭据，分析、转写整理、热点、整场总结、文案及远程 ASR 可分别选择路由。

  • 页面接收授权状态通知，并通过 HTTP 查询恢复数据。断线重连不会重放写操作或丢弃未保存草稿；已返回 4xx 的请求仍需按页面提示手动重试。任务取消、失败和退出均以服务端持久状态为准。

  • 已有视频可从工作台导航进入“录播分析”，按需附带 XML、JSON、SRT、ASS 弹幕。预处理后由本地模型转写，再按已配置的本地或远程 LLM 分析；具体格式、进度和恢复方式见录播导入说明。

  • “场次时间线”先展示热点事件，再独立判断是否成片。每场录制按 GMT+8 展示标题、摘要、1～2 条代表弹幕、热度、成片分、语义置信度和证据覆盖；未达到成片阈值的事件仍留在时间线上，但不会出现“精审/预览”入口。达到阈值的候选仍可调整边界、批准或拒绝。

  • 热点由弹幕、音频、SenseVoice、ASR 和趋势共同召回；ASR 不可用或质量不足时不会停掉整条高光流水线。事件可跨连续 TS 分段合并，一个分段也可有多个无关事件；真实断流缺口不可跨越，成片边界按完整事件和前后文动态计算。

  • 整场结束并完成最终分析后，系统会把同场全部最终 ASR 按时间顺序组成一个上下文，交给 LLM 做一次全局分析，生成不按五分钟分片拆开的全场高光总结；这不是把节点摘要直接拼起来。

  • Portable 首次在线准备模型时会使用已经装好依赖的 .venv Python。程序托管的 .venv 损坏会自动重建，依赖或单个模型下载中断可在下次启动续跑；真实 Python 3.10/3.13/3.14 等不支持版本会明确拒绝且不会被误删。

  • Engine Pack ZIP 只接受 schema 5 内容清单，安装后的 models/ 只接受 schema 7 清单。四个引擎按各自不可变来源与内容指纹独立校验；全部未变时不会下载，只有一个变化时只更新一个。其他 schema 不会被迁移或补写。

  • 当前 Payload 内置 C、Cython、Rust 三个 app.accelerators 原生模块：候选聚类和弹幕文本特征使用 Rust/rayon，音频峰值、静音区间和热点滚动基线使用 Cython；不提供旧模块路径。源码环境没有编译扩展时会按函数使用等价 Python 实现。

  • 设置页的“Web 服务端口”保存的是下次启动值；当前服务不会重新绑定。重启后 Launcher 读取程序根目录 config\launcher.json，默认仍为 8000，监听地址固定为 127.0.0.1。

  • Bilibili 弹幕默认向前校正 7.5 秒来对齐画面，同场过近且内容相似的节点会去重，减少一个爆点重复出片。

  • “实时转写”和“弹幕热度”都可用“录制场次”下拉查看数据库中的完整历史；新增直播不会把旧转写挤掉，两个页面会分别记住当前选择。“实时转写”还可以人工改正文，并可填写“错误词=正确词”加入该直播间的专属词典；每条记录会显示并可复制对应的源 TS 文件名，也可“无损导出 MP4”直接进入剪辑软件。导出保留原始编码并校准首个视频帧到 0s，不会因 AAC 预滚在开头留下黑帧；保存纠错后可自动重分析本场。

  • 修改阈值后使用“按新阈值重分析”；修改房间词典或 ASR 模型后使用“按新词典/模型重新转写”。人工审核、手工边界、草稿、成片和人工正文不会被静默覆盖。

  • 主播下播需连续确认 3 次，再等待 60 秒收尾；期间恢复直播会取消停止。单场默认最长 12 小时，断流仍受 20 次或 180 秒的恢复预算限制；预算耗尽后要等房间真实离线，才允许下一次开播自动录制。

  • 五秒轮询会保留转写纠错、房间词典、房间配置、功能开关和下拉选择中的未保存内容，也会记住原始 ASR、已学习词典及时间线评分详情的展开状态。转写编辑器展开或有未保存内容时，“录制场次”下拉会锁定，保存或取消后才可切换。时间线内容没有变化时不会重建页面；出现新节点或状态变化时也会恢复原滚动位置，阅读摘要或来源评分时不会自动跳到顶部。

  • 人工提交审核后，任务不会继续显示 awaiting_review；“独立成片”会进入受心跳保护的后台渲染，完成后出现在成品切片。

1. 电脑和网络要求

项目最低要求推荐配置
操作系统Windows 10/11 64 位Windows 11 64 位
CPU支持 64 位 Windows 的现代 CPU近几年 6 核及以上 CPU
内存8 GB16 GB 或更多
可用磁盘15 GB，仅够安装和短时测试30 GB 以上；长期录制建议准备独立大容量磁盘
显卡不要求独立显卡，默认使用 CPUNVIDIA 显卡可用于后续加速调试，但首次测试保持 CPU 默认值
网络下载发行包、下载模型和访问 Bilibili 时需要稳定宽带；首次模型下载流量约 5.5 GB
浏览器Edge、Chrome 等现代浏览器可访问控制台推荐安装最新版 Google Chrome，账号登录可直接复用

Full 版不要求系统安装 Python、FFmpeg、Visual Studio、Git 或其他编程工具。

以下位置不适合作为程序目录：

  • C:\Program Files、C:\Windows 等需要管理员权限的目录；
  • OneDrive 等正在自动同步的目录；
  • 临时目录、压缩包预览窗口和网络共享盘；
  • FAT32 U 盘。大文件可能超过 FAT32 的单文件限制。

推荐使用 D:\BiliLiveCut；没有 D 盘时可使用 C:\BiliLiveCut。

2. 下载正确的文件

打开项目的 GitHub Releases 页面，进入 v0.1.20.0-Alpha，下载：

  1. BiliLiveCut-Portable-Full-0.1.20.0-alpha-x64.zip
  2. SHA256SUMS.txt

不要把下面这些文件当成 Windows 小白版：

  • BiliLiveCut-Portable-Lite-*.exe：Lite 版，需要系统 Python 3.11/3.12，并依赖联网安装组件；
  • .whl 或 .tar.gz：面向 Python 开发者；
  • full-build-manifest.json、lite-build-manifest.json：构建清单，不是启动程序。

3. 校验下载文件

校验可以确认文件没有下载损坏，也能避免误用来源不明的文件。

  1. 把 Full ZIP 和 SHA256SUMS.txt 放在同一个下载目录。
  2. 在该目录空白处按住 Shift 并单击鼠标右键，选择“在终端中打开”。
  3. 复制并执行：
Get-FileHash ".\BiliLiveCut-Portable-Full-0.1.20.0-alpha-x64.zip" -Algorithm SHA256
  1. 将输出的 Hash 与 SHA256SUMS.txt 中同名文件前面的值比较。英文字母大小写不同不影响结果。
  2. 两者必须完全一致。若不一致，删除 ZIP 并从 Releases 页面重新下载；不要继续解压或运行。

4. 正确解压 Full ZIP

  1. 新建目录，例如 D:\BiliLiveCut。
  2. 右键 ZIP，选择“全部解压”。
  3. 打开解压出来的 BiliLiveCut-Portable-Full-0.1.20.0-alpha-x64 文件夹。
  4. 确认同一层能看到：
BiliLiveCut-Portable.exe
portable-python\
vendor\wheels\
bin\ffmpeg.exe
bin\ffprobe.exe
README.txt
LICENSE.txt

必须保留整个目录结构。不要只把 BiliLiveCut-Portable.exe 单独拖到桌面，也不要直接在 ZIP 预览窗口里双击运行。

5. 准备模型

Full 版包含运行环境，但不包含四个语音识别模型。

情况 A：没有 Engine Pack

这是普通测试者最常见的情况。保持网络连接，首次启动时 Launcher 会从 ModelScope 和 Hugging Face 下载全部模型。模型总量约 5.5 GB，可能需要较长时间。

情况 B：分发者提供了 Engine Pack

当前版本新生成的 Engine Pack 文件名是：

BiliLiveCut-EnginePack-0.1.20.0-alpha.zip

将 ZIP 原样放到 BiliLiveCut-Portable.exe 同级目录，不要手动解压。Launcher 会先校验逐引擎内容身份，再把需要的模型原子安装到 models/。Engine Pack 内容清单仅支持 schema 5，已安装模型清单仅支持 schema 7，不迁移旧 schema。模型仓库、不可变 revision、格式、子模型/随附组件及逐文件完整性必须符合当前定义；发行版本或源码提交差异仅记录来源警告，内容相同的旧包及完整安装目录可以复用。Runtime、Payload 和数据库继续遵循各自严格身份与格式规则。

不要从不明网盘或陌生人处下载模型包。Engine Pack 校验失败时，程序会拒绝使用该包、保留已经验证的既有模型，并只在线准备缺失或身份变化的引擎。

6. 第一次启动

  1. 双击 BiliLiveCut-Portable.exe。
  2. 如果 Windows SmartScreen 弹出提醒，先确认文件来自本项目 Releases 且 SHA-256 已校验，再选择“更多信息”查看是否允许运行。不要为了运行程序而关闭整个杀毒软件。
  3. 黑色 Launcher 窗口会依次执行：
[1/6] 安装内置业务源码
[2/6] 创建 .env 配置
[3/6] 创建 Python 虚拟环境
[4/6] 从 vendor/wheels 离线安装依赖
[5/6] 校验或下载四引擎模型
[6/6] 启动 Web 控制台
  1. 首次运行不要关闭窗口。Full 的 Python 依赖来自本地 wheelhouse，不会回退到 PyPI 镜像；模型仍可能需要联网下载。
  2. 出现类似下面的文字后，服务已经启动。若你改过 Web 端口，以黑色窗口实际打印的地址为准：
Starting Web console...
http://127.0.0.1:8000
  1. 打开 Edge 或 Chrome，在地址栏输入：
http://127.0.0.1:8000

如果页面没有自动弹出，手动输入地址即可。

6.1 修改 Web 管理端口

  1. 打开“配置 → 功能开关”，找到“Web 管理端口”。
  2. 输入 1 到 65535 之间的整数并保存。页面会分别显示“已保存端口”和“当前监听端口”。
  3. 保存不会中断或热重绑当前服务；先停止 Launcher，再重新双击启动。
  4. 重启后黑色窗口和页面中的当前端口都会变为新值，需要重启 提示消失。

端口保存在程序根目录 config\launcher.json，业务 Runtime 更新和修复不会覆盖它。不要手工写入无效 JSON；若文件已损坏，Launcher 会告警并回退到 8000，但为保留排障现场不会自动覆盖原文件。端口已被其他程序占用时，Launcher 会明确指出端口并停止，不会随机换端口。

7. 首次使用前的基础配置

第一次测试不需要填写 Cookie 或购买大模型 API。建议先保持最少配置。

7.1 找到并编辑 .env

首次启动后，程序目录会自动生成 .env。

  1. 先在黑色窗口中按 Ctrl+C，等待服务停止。
  2. 在程序目录找到 .env，右键选择“打开方式”→“记事本”。
  3. 每个配置占一行，只修改等号右侧，不要删除变量名。
  4. 保存后重新双击 BiliLiveCut-Portable.exe。

.env 可能包含密码、Cookie 和 API Key，不要截图公开，也不要发送给其他人。

7.2 第一次测试建议值

APP_ENV=prod
LOG_LEVEL=INFO
ADMIN_PASSWORD=
STORAGE_ROOT=./storage
STREAM_QUALITY=10000
SEGMENT_DURATION_S=300
LIVE_OFFLINE_CONFIRM_COUNT=3
LIVE_SESSION_END_DELAY_S=60
RECORDING_MAX_DURATION_S=43200
RECORDING_RECONNECT_MAX_ATTEMPTS=20
RECORDING_RECONNECT_MAX_ELAPSED_S=180
COLLECT_DANMAKU=true
DANMAKU_LOGIN_RETRY_MAX_ATTEMPTS=5
DANMAKU_LOGIN_RETRY_INTERVAL_S=60
RECORDING_PIPELINE_ENABLED=true
ASR_PRIMARY=funasr_nano
ASR_VAD_MAX_SEGMENT_S=30
ASR_TASK_MAX_CONCURRENCY=1
TRANSCRIPT_LLM_REFINE_ENABLED=true
TRANSCRIPT_LLM_REFINE_MAX_TOKENS=65536
HIGHLIGHT_LLM_MAX_TOKENS=65536
HIGHLIGHT_INIT_THRESHOLD=0.28
HIGHLIGHT_THRESHOLD=0.38
HIGHLIGHT_REVIEW_THRESHOLD=0.32
HIGHLIGHT_AUTO_APPROVE_THRESHOLD=0.72
HIGHLIGHT_MAX_CANDIDATES_PER_SEGMENT=4
HIGHLIGHT_PEAK_MIN_DISTANCE_S=25
HIGHLIGHT_MIN_PRE_ROLL_S=20
HIGHLIGHT_MIN_POST_ROLL_S=30
DANMAKU_EVENT_LAG_S=7.5
AUTO_PUBLISH_THRESHOLD=0.80
TREND_ENABLED=false

说明：

  • ADMIN_PASSWORD 留空：只允许本机通过 127.0.0.1 使用，首次测试最简单。
  • STORAGE_ROOT 保持 ./storage：数据库、原始录像和成品都在程序目录内，便于备份。
  • STREAM_QUALITY=10000：请求原画；若匿名访问无法取得，可改为 400 或 250。
  • SEGMENT_DURATION_S=300：每个原始片段以 5 分钟为目标；FFmpeg 按关键帧落盘，实际时长允许小幅浮动。
  • LIVE_OFFLINE_CONFIRM_COUNT=3 与 LIVE_SESSION_END_DELAY_S=60：连续确认三次下播后等待 60 秒再收尾；等待期间恢复直播会撤销停止。
  • RECORDING_MAX_DURATION_S=43200：单场最长 12 小时；达到后安全收尾，若直播仍在继续则由自动监控开启下一场会话。
  • RECORDING_RECONNECT_MAX_ATTEMPTS=20 与 RECORDING_RECONNECT_MAX_ELAPSED_S=180：连续无法恢复取流时，达到 20 次或 180 秒中的任一上限即自动结束本场；若 Bilibili 仍报告直播中，程序会等待一次真实离线再允许下一场自动启动。成功产出新片段后两项预算归零。某项设为 0 只禁用该项，两项都为 0 会无限重试，不建议无人值守时使用。
  • COLLECT_DANMAKU=true：采集公开弹幕；有 Cookie 时登录优先，失败后立即匿名兜底。
  • DANMAKU_LOGIN_RETRY_MAX_ATTEMPTS=5：单场最多累计 5 次登录失败（首次计入）；达到后本场固定匿名，设为 0 可始终匿名。
  • DANMAKU_LOGIN_RETRY_INTERVAL_S=60：匿名连接存活期间，每 60 秒后台探测一次登录链路。
  • 若日志出现 code=-352，表示请求触发平台风控，不能只据此判定 Cookie 过期。登录请求失败会匿名兜底；匿名请求也失败时会按配置间隔重试，录像与实时转写仍会继续。
  • RECORDING_PIPELINE_ENABLED=true：新开始或恢复的录制默认实时转写；也可在“配置 → 功能开关”中修改，下一次录制生效。
  • ASR_PRIMARY=funasr_nano：优先使用本地 Fun-ASR-Nano；无有效输出时自动回退 Paraformer，再回退 Whisper。
  • ASR_VAD_MAX_SEGMENT_S=30：先把 TS 标准化为 16 kHz 单声道 WAV，再由 FSMN-VAD 把 Nano 的单句限制在 30 秒；建议保持默认值。
  • ASR_TASK_MAX_CONCURRENCY=1：同时转写的录制分段数。CUDA 可在“配置 → 功能开关”中逐步提高到 2～8，但每个独立 ASR worker 进程会加载模型，显存占用通常近似线性增加；CPU 或显存不足时保持 1。
  • TRANSCRIPT_LLM_REFINE_ENABLED=true：每个切片完成 ASR 后，用已配置的大模型整理正文并生成概括；失败时保留原始 ASR，不中断分析。
  • TRANSCRIPT_LLM_REFINE_MAX_TOKENS=65536 与 HIGHLIGHT_LLM_MAX_TOKENS=65536：分别控制五分钟转写整理和高光复核的最大输出预算；实际消耗由模型响应决定，可按服务商能力调低。
  • 高光默认初筛/候选/人工审核阈值为 0.28/0.38/0.32，自动批准/发布阈值为 0.72/0.80。阈值越低越容易产生候选；房间级值可在“功能开关”中调整。
  • HIGHLIGHT_MAX_CANDIDATES_PER_SEGMENT=4 与 HIGHLIGHT_PEAK_MIN_DISTANCE_S=25：每个原始分段最多分析 4 个分散窗口；真实峰值优先，不足时补充均匀探针，相邻窗口至少间隔 25 秒，跨分段分析仍按场次统一去簇。
  • HIGHLIGHT_MIN_PRE_ROLL_S=20 与 HIGHLIGHT_MIN_POST_ROLL_S=30：动态切片至少保留的前文和后文，LLM 与静音吸附仍可继续向外扩展。活动直播会等待下一相邻分段完成转写，避免断点附近的后半段尚未落盘就提前定界。
  • DANMAKU_EVENT_LAG_S=7.5：评分时把弹幕信号向前对齐 7.5 秒，不修改数据库中的原始弹幕时间。
  • Web「配置 → 大模型」没有启用服务商：转写梳理自动跳过，高光判断使用本地规则评分，不产生 API 费用；整场 ASR 全局分析会明确显示不可用。
  • TREND_ENABLED=false：不启用联网热点采集。

若当前场次出现明显重复转写，可在“实时转写”页点击“重新识别”。该操作会重建本场自动分析结果；有活动任务时会等待或显示明确原因。

7.3 不要先改这些配置

首次测试请保持 ASR 设备为默认 CPU、任务并行数为 1，不要直接改为 CUDA：

ASR_PRIMARY_DEVICE=cpu
ASR_AUXILIARY_DEVICE=cpu
ASR_REVIEW_DEVICE=cpu
ASR_FALLBACK_DEVICE=cpu
WHISPER_DEVICE=cpu
WHISPER_COMPUTE_TYPE=int8
ASR_TASK_MAX_CONCURRENCY=1

首次启动后，可在“设置中心”的 ASR 分类直接修改设备、计算类型及并发；上面的环境配置作为部署默认。先证明录制链路正常，再单独测试 GPU。启用 CUDA 后可逐步提高“ASR 分段并行数”；实际模型由共享池按角色并发上限分配，过高的模型并发仍可能导致显存不足。页面标明下一任务或下一检查生效，已有任务保留启动快照。 如果显式设置的 WHISPER_COMPUTE_TYPE 不受当前 CPU/CUDA 支持，Whisper 兜底会自动改用 CTranslate2 auto 并记录告警；CUDA 驱动、模型文件或显存本身的错误不会被该回退隐藏。

8. 添加直播间并完成第一次录制

请选用你自己或已明确取得授权、并且当前正在直播的房间做短时测试。

  1. 保持黑色 Launcher 窗口开启，并打开窗口实际打印的 http://127.0.0.1:<端口>；首次默认端口为 8000。
  2. 进入“直播间”页面。
  3. 在“添加直播间”中输入完整链接或数字房间号，例如：
https://live.bilibili.com/123456
  1. 勾选“我已确认拥有录制授权”。未勾选时系统会拒绝添加。
  2. 点击“添加”。
  3. 打开“设置中心”→“房间自动化与端口”，找到刚添加的直播间；首次测试可只开启“自动分析”，确认录制和分析后再逐项开启自动渲染、自动审核与自动上传。
  4. 点击“保存本直播间开关”。预约录制、阈值自学习、弹幕情绪、审核阈值和 ASR 手工词典也在这里按直播间独立设置；热词一行一个。
  5. 在房间卡片中点击“开始录制”。 程序在开录前查询标题与主播名，录制中默认每 30 秒刷新，并保存场次标题历史。接口失败时保留缓存、显示上次获取状态并继续录制。需要守候开播时，可在房间卡片选择“开播后自动录制并分析”，启用两个开关并解除暂停；Launcher 必须保持运行。
  6. 打开“录制状态”，确认状态变为 recording，片段数量开始增加。
  7. 先录制 2～5 分钟，再回到“直播间”点击“停止录制”。
  8. 在程序目录检查：
storage\raw\session_<数字>\

目录中出现 .ts 片段，表示从安装到录制的第一条链路已经成功。

“房间自动化与端口”中的流水线设置按直播间独立生效。关闭某一项只会阻止后续自动推进，仍可手动处理；自动投稿同时要求房间开关、设置中心的全局自动上传和上传工具开关开启，且候选分数达到房间投稿阈值。

编辑直播间录制选项或独立功能开关时，页面会显示“有未保存修改”，并暂停对应表单的五秒自动重绘；输入中的草稿不会被后台轮询覆盖，开始、停止或恢复录制后的状态、会话号和操作按钮仍会立即更新。保存后恢复完整刷新。

9. 弹幕登录回退、Cookie 和高清访问

Cookie 不是公开直播录制或弹幕采集的必需项。程序会按网页 WBI 请求格式获取短期 token：存在 Cookie 时先尝试登录请求并使用 DedeUserID 鉴权；接口业务错误或登录鉴权被拒绝后，立即改用无 Cookie、uid=0 的匿名链路。匿名连接保持工作时会按配置间隔探测登录恢复，达到单场失败上限后不再尝试 Cookie。平台允许的部分高清晰度仍可能需要登录态。

  • 首次测试可保持 COLLECT_DANMAKU=true，在“弹幕热度”页选择本次“录制场次”，确认已经收到数据。以后可从同一下拉切回任何仍保存在数据库中的旧场次。
  • 点击“设置中心”→“账号登录”→“扫码登录”，用手机 Bilibili 扫描页面上的二维码并确认；确认成功后自动保存 Cookie。这种方式不需要 Chrome 或下载 Chromium。二维码过期后重新申请，或点击“取消扫码”结束轮询。
  • 也可点击“浏览器登录”。程序会优先在独立临时资料目录中打开电脑已安装的 Google Chrome，并保持浏览器 sandbox 开启；它不会读取你的日常 Chrome Profile。
  • 在这个由程序打开的独立登录窗口中完成 Bilibili 登录，程序会直接从本次受控浏览器上下文保存 Cookie；不要改用原先已经打开的普通 Chrome 窗口登录。
  • 如果没有找到可用的 Chrome，页面会显示“正在下载 Playwright Chromium”。程序会联网下载浏览器到 vendor\playwright-browsers\，完成后自动打开登录页；下载大小和耗时以 Playwright 当前版本为准。
  • 浏览器下载期间不要关闭 Launcher。失败时先检查网络、磁盘空间和安全软件，然后再次点击“浏览器登录”；已经完整下载的 Chromium 会被后续启动复用。
  • 如果电脑只有 Edge，仍可用 Edge 访问 Web 控制台；账号登录窗口会按上述规则下载 Playwright Chromium。
  • 不要向他人提供 Cookie，也不要把 Cookie 粘贴到聊天、截图或问题报告中。
  • 如果测试人员不了解 Cookie 的含义，应继续匿名测试，不要手动提取登录态。

10. 大模型配置（可选）

不配置大模型时，系统仍可使用本地规则进行高光评分。大模型用于辅助复核、文案和网感资料库，可能产生服务商费用。

需要测试时：

  1. 打开 Web 控制台的“设置中心”→“大模型服务商”。
  2. 点击“新增模型”。
  3. 填写服务商名称、base_url、模型名和 API Key。
  4. 保持“启用”，设置优先级。
  5. 可先直接点击“测试连通”；它使用当前表单且不会保存配置。页面会保留每个模型的成功响应或错误详情。服务只返回推理过程或空正文时会显示失败；DeepSeek 思考模式因此没有最终正文时，程序会关闭思考模式自动重试一次。
  6. 确认连通后点击“保存全部”。

只有显示测试成功后再启用相关功能。不要把真实 API Key 写进公开文档或问题报告。

11. 场次时间线、审核和成品文件

分析流水线只要检测到热点事件，场次时间线就会出现数据；是否生成视频候选由后续成片分独立决定：

  1. 打开“场次时间线”，按主播、房间和录制场次找到本次直播；页面时间统一显示为 GMT+8。
  2. 录制结束且最终分析稳定后，展开场次即可在节点上方阅读“全场高光总结”；它把整场最终 ASR 按 GMT+8 时间顺序组成一个上下文，交给 LLM 一次完成全局分析，不拼接节点摘要，也不按 TS/五分钟分片拆段。人工纠错或重分析后旧总结会自动失效并重新排队；也可点击“重新生成”。LLM 没有返回有效正文时任务会明确失败并重试，不会用规则文本冒充分析结果。
  3. 展开场次卡片查看热点节点。每个节点提供时刻、标题、摘要、最多两条代表弹幕、热度、成片分、语义置信度、证据覆盖和来源信号。黄色节点标记“仅时间线，不生成视频”，仍可用于回看整场发生了什么。
  4. 达到房间成片阈值的节点会显示候选编号和“精审/预览”；确认内容后点击“批准并出片”，不需要的候选点击“拒绝”。没有候选编号的热点无需审核。
  5. 默认不显示已拒绝节点；需要核查时打开“包含已拒绝”。
  6. 在“成品切片”中播放并检查成品。“发布（置 ready）”只会标记本地交付状态并导出清单，默认不会自动投稿。
  7. 在“上传 / 设置”中点击“打开切片目录”。

需要重算时：

  • 只改了审核阈值，点击场次卡片的“按新阈值重分析”。
  • 改了房间手工词典、人工学习别名或 ASR 模型，点击“按新词典/模型重新转写”。
  • 在“实时转写”先从下拉选择录制场次，再编辑该场正文。可额外输入若干行 错误词=正确词，勾选加入直播间词典；编辑器展开或存在未保存内容时，自动刷新不会覆盖草稿，场次下拉也会保持锁定。
  • 重分析会按当前模型、词典和阈值重建本场自动结果；正在运行的任务会阻止操作并显示原因。

审片时请注意：

  • 事件标题与摘要来自带 ID 的弹幕、ASR、音频等证据束；成片边界从完整事件起止点增加前后文，再向外吸附自然静音并限制在同一连续录像块内。播放器预览和最终成片使用同一候选边界，不会跨断流缺口。
  • start_offset 表示视频开始点，end_offset 表示理由所述事件完整结束后的出点，不是事件开始时刻。
  • 点击“拒绝”会同步停止该候选仍可取消的任务，并把所有未发布关联成片标记为拒绝；已经发布的成片保留真实状态。
  • Alpha 当前版只处理由同版本创建的场次数据，不读取或迁移其他版本的数据库。

常用目录：

storage\raw\              原始录制分片
storage\clips\            成品切片
storage\ready_to_upload\  待上传清单
storage\blc.db             本地数据库
models\                    本地语音模型

建议小规模测试期间保持 Biliup 和“成品就绪后自动上传”关闭。

12. 正常停止和再次启动

正常停止

  1. 先在 Web 页面停止所有正在录制的房间。
  2. 等待“录制状态”不再显示活动会话。
  3. 回到黑色 Launcher 窗口，按 Ctrl+C。
  4. 等待出现服务已停止的提示，再关闭窗口。

不要在写入录像、安装依赖或下载模型时直接关机。

再次启动

以后直接双击同一个 BiliLiveCut-Portable.exe。已安装的依赖和有效模型会被复用，不会每次重新下载。

13. 数据备份和 Alpha 版本切换

最重要的用户数据是：

.env
storage\

备份前必须先停止录制并关闭 Launcher。把 .env 和整个 storage 文件夹复制到安全位置即可。

数据库的应用版本只记录创建来源，格式版本、模型指纹、实际表列、约束和完整性全部符合时可复用，创建来源不会被改写。当前格式为 Schema 6，仅编号相同不足以通过校验。不兼容格式会保留并拒绝启动，不自动备份、迁移、删除或替换；先在副本上核查受支持的转换方案，或显式配置独立新库。历史版本的功能和修复记录只用于查阅，见 0.1.17 系列 Changelog，不能当作当前数据迁移说明。

同一安装目录中，Launcher 的运行目录始终是 EXE 所在目录；runtime/releases/ 中的版本化源码不改变数据库位置。默认数据仍在 storage\blc.db，显式 DATABASE_URL 继续生效。更换目录前核查数据库、存储和媒体的实际路径，避免把空目录误认成旧数据丢失；不要同时运行两个版本写入同一数据库。

测试其他版本或需要保留独立环境时：

  1. 把新版本解压到全新目录。
  2. 不要复制其他版本的 .venv、runtime 或 vendor\wheels；这些运行资产必须由对应版本重新准备。
  3. 可复制 schema 7 的 models\engine-pack-installed.json 及完整对应模型目录；启动器按当前模型内容身份和文件完整性检查，不改写不支持的旧 schema。
  4. 对照当前 .env.example 核查配置，并使用停机备份的数据副本；显式确认 DATABASE_URL、STORAGE_ROOT 和媒体路径指向测试副本。程序完整校验数据库，失败时保留现场，不手改元信息。
  5. 按新版本说明完成基础自检。降级前另行核查旧程序是否支持已保存的配置和业务记录，必要时使用升级前备份；原始录像或成片也可作为普通媒体文件另行归档。

14. 常见问题

双击后没有任何反应

  • 确认不是在 ZIP 预览窗口中运行。
  • 检查 Windows 安全中心或杀毒软件是否隔离了 EXE。
  • 先核对 SHA-256；不要直接关闭杀毒软件。
  • 将完整目录移动到 D:\BiliLiveCut 后重试。

浏览器没有自动打开

保持黑色窗口开启，按窗口打印的 http://127.0.0.1:<端口> 地址手动访问；未修改时端口为 8000。

浏览器显示“无法访问此网站”

  • 检查黑色窗口是否仍在运行。
  • 等待模型准备和 [6/6] Starting Web console 完成。
  • 如果提示某个端口被占用，先关闭之前启动的 BiliLiveCut 或占用该端口的程序；也可以在控制台保存另一个端口后重启。程序不会自动随机换端口。

账号登录提示正在下载 Chromium

这是“浏览器登录”在电脑没有可用 Google Chrome 时的回退流程。保持网络和 Launcher 窗口开启；下载完成后登录窗口会自动出现，以后会复用 vendor\playwright-browsers\ 中的浏览器文件。“扫码登录”直接在管理页显示二维码，不需要下载浏览器。

Full 安装出现 wheelhouse is missing or empty

说明完整包目录不完整。检查 vendor\wheels\ 是否存在大量 .whl 文件。不要让 Launcher 在线回退；重新解压完整 Full ZIP。

大模型测试提示“未安装 openai”

v0.1.20.0-Alpha 的 Portable 运行时包含 OpenAI 兼容 SDK。该提示说明当前 Full 的 vendor\wheels\ 不完整或目录不是本版本的干净发行包；请重新下载并解压到全新目录。不要在 Portable 目录手工执行 pip install -e。

控制台提示 pip 有新版本

最新构建已将 pip 26.2 连同 SHA-256 一起纳入 Portable 依赖锁。关闭服务并重新运行 Launcher 即会按锁自动升级；不要在 .venv 中手工执行 pip install --upgrade pip，否则本地版本会偏离发布时验证过的依赖集合。

出现 THESE PACKAGES DO NOT MATCH THE HASHES

新版 Full 应强制使用本地 wheelhouse，不应访问 PyPI 镜像。确认使用的是 v0.1.20.0-Alpha 最新 Full ZIP，并且没有只复制 EXE。不要修改锁文件或添加报错中的 sdist 哈希，直接重新下载并校验 Full ZIP。

模型下载很慢或中断

  • 保持磁盘空间和网络稳定。
  • 关闭 Launcher 后重新双击，已有有效文件会尽量复用。
  • 如果分发者提供内容兼容且来源可信的 Engine Pack，可放到 EXE 同级目录后重试。
  • 首次启动第 5 步实时显示当前引擎、文件、下载/校验/安装阶段和耗时。有可靠字节总量与速率时显示进度条和预计剩余时间；Hugging Face 网络总量估算、ModelScope 断点重试等不能提供准确计数的阶段明确显示“总量未知 / 预计剩余未知”。引擎 1/4 是处理顺序，不代表已下载 25%。下载结束后仍须通过完整性校验；复用本地模型时明确显示无下载。
  • Hugging Face 明确使用 hf-mirror.com，可恢复故障后尝试 huggingface.co；每个源最多调用下载 SDK 两次（SDK 内部仍可能执行自己的有限请求重试）。ModelScope 使用既有官方端点，每次调用的模型和 revision 不变。
  • 失败摘要中的 engine、model、revision、endpoint、failed_host、phase、kind 和 root 用于定位。磁盘不足、权限拒绝、认证或资源不存在不会靠不断换源解决；按 action 提示处理，或提供有效本地 Engine Pack。--offline 始终阻止联网；完整当前模型仍优先复用。
  • ModelScope 每个主模型和子模型下载后均核对官方文件清单、大小及可用 SHA-256；phase=verify 表示缺失、损坏或无法验证的文件，不能将 SDK 返回目录视为下载完成。已成功安装的其他引擎和续传文件保留。

反复显示录制异常

先查看 Web“错误日志”中的同一 session：摘要包含房间、exit_code、category、HTTP 状态、是否重试、次数/时间预算、下一次等待和停止原因。storage/logs/blc-<进程号>-<启动标识>.log 中保留脱敏的 stderr 尾部（最多 20 行，每行 512 字符）；超长行省略，签名 URL、认证头和令牌不保留。

磁盘、权限、FFmpeg 缺失或媒体参数错误会停止当前会话并暂停自动重新启动。解决提示的问题后手动开始，或重新开启自动录制。HTTP 403 可能与临时流地址及访问权限有关，不能只凭状态码判定 Cookie 过期。网络、上游和未知错误会有限重试；反复留下短末片也不会无限续期。

报告问题时请提供同一次运行的版本、安装根目录、时间和 session，以及该次异常摘要和对应 stderr 尾部；模型故障请提供完整脱敏摘要。只有 HTTPX 堆栈尾部不能确定失败主机，模型准备失败也不等同于录制首次中断的根因。不要上传 Cookie、Token、完整签名 URL 或真实配置文件。

添加房间失败

  • 确认勾选了录制授权。
  • 使用完整直播间链接或正确房间号。
  • 首次测试选择当前正在直播的房间。
  • 原画不可用时，在“设置中心”搜索 STREAM_QUALITY，改为 400 或 250 并保存，下一场录制生效。

能录制但没有实时转写、候选或成片

先检查 storage\raw\session_<数字>\ 是否已有 .ts 文件，再打开“设置中心”→“房间自动化与端口”核对该直播间是否启用了“自动分析”；需要自动成片时还要启用“自动渲染”。原始录制成功与后续自动阶段是否启用是两件事。请在问题报告中注明开关状态，不要反复删除整个程序目录。

主播下播后任务一直显示重连

内置 Bilibili 来源收到明确下播事件后，直接等待 LIVE_SESSION_END_DELAY_S 秒，再查询状态并核对录制实例；复核遇到临时失败或未知状态时保留录制并重试，恢复开播会取消停止。LIVE_OFFLINE_CONFIRM_COUNT 只用于不提供事件能力的查询型来源。断流恢复受 20 次或 180 秒预算限制，单场还受 RECORDING_MAX_DURATION_S 限制。预算耗尽后当前会话会停止，并等待房间至少一次真实离线后才允许下一次开播自动录制；最后一个录制任务结束时网感定时采集会恢复。详见开播事件守候。

候选理由、预览和视频内容不一致

先确认使用 V0.1.20.0 Alpha。新分析先把多源证据聚合成完整热点事件，再用同一事件生成语义、成片分和动态边界；预览与最终成片使用同一候选边界。需要重新计算当前场次时，在“场次时间线”执行重分析；改过词典或 ASR 时选择重新转写。受保护数据不会被静默改写。

拒绝候选后仍在成品列表显示 reviewing

V0.1.20.0 Alpha 的拒绝操作会同步拒绝当前候选、关联事件、任务和未发布成片，并默认从时间线过滤。已经发布的成片按设计保留，避免篡改真实外部发布结果。任何非当前精确 Schema 的数据库都会明确拒绝，不会迁移或静默改写。

修改 .env 后没有生效

业务参数优先在“设置中心”按中文名称或 ENV 键搜索并保存，界面显示来源、生效时机和部署只读原因。数据库中的 Web 覆盖优先于 .env，如需重新使用环境值，先点击该字段“恢复默认”。.env 作为启动基线在服务启动时读取，修改它后需要关闭并重新启动 Launcher；凭据“明确清空”会阻止回退到环境旧值。

想修复 Runtime

先备份 .env 和 storage\。在程序目录打开终端后执行：

.\BiliLiveCut-Portable.exe --repair

不要删除 storage\，其中包含数据库和录制文件。

15. 给测试者的问题报告模板

启动器退出报错时，安全诊断另存为安装目录下的 logs/launcher-error.log（保留最近一次启动失败）。其中包含失败阶段、子进程退出/超时信息和异常调用位置；模型准备还包含引擎、固定 revision 与实际请求主机。若无法写入该文件，窗口会显示写入失败原因。Web 启动后的详细日志位于 storage/logs/blc-<进程号>-<启动标识>.log，各进程独占文件，避免 Windows 多进程轮转占用冲突；每 10 MB 轮转为 ZIP，启动和轮转时清理超过 14 天的归档及已退出进程的日志。旧 blc.log 保留，排错时一并收集故障时间附近各进程的日志和归档。后台错误日志与文件日志使用相同的脱敏内容。不要只截最后一行“启动失败”。

Portable 的受管 Python 子进程忽略外部 PYTHONPATH、PYTHONHOME、PYTHONUSERBASE 与用户 site-packages，只使用受管虚拟环境及明确指定的 Runtime/模型准备源码。无需修改系统环境变量；下载源和业务配置仍按原有规则生效。这可避免其它开发环境的依赖被误认为 Portable 已安装版本，从而触发错误重装或离线失败。

报告问题时提供：

  • Windows 版本，例如 Windows 11 23H2；
  • 使用 Full 还是 Lite；
  • 程序版本 v0.1.20.0-Alpha；
  • 解压目录；
  • 问题发生在 [1/6]～[6/6] 的哪一步；
  • 黑色窗口最后 30 行文字或截图；
  • Web“错误日志”中的报错；
  • 是否存在 storage\raw\session_<数字>\*.ts；
  • 是否使用 Engine Pack、Cookie、LLM 或代理。

提交前必须遮住 Cookie、API Key、密码、Webhook 和其他账号信息。不要上传 .env、数据库或完整用户目录。

16. 当前 Alpha 的测试边界

v0.1.20.0-Alpha 适合小规模、受控测试，不等同于稳定正式版。当前应重点验证：

  • Full ZIP 下载、校验和解压；
  • 首次离线依赖安装；
  • 在线模型准备或 Engine Pack 安装；
  • Web 控制台启动；
  • 授权直播间添加、开始和停止录制；
  • 主播下播或断流后的重试上限、自动收尾和页面状态清理；
  • 场次时间线的主播、房间、GMT+8 时刻、摘要、代表弹幕与来源依据是否一致；
  • 同一分段多个高光、跨分段高光及动态片头片尾是否覆盖完整事件；
  • 房间词典、人工转写校正和场次重分析是否保留人工资产；
  • 拒绝候选后未发布关联成片是否从成品列表消失；
  • 原始文件完整性、磁盘占用和长时间运行稳定性；
  • 不同 Windows 版本、杀毒软件和安装路径的兼容性。

自动分析、自动渲染、Cookie 登录、GPU 加速和自动上传应分开测试，不要在第一次试运行时同时开启所有功能。

模型损坏与安装中断恢复

普通启动检查已安装模型的文件清单及大小；--repair 或显式 --engine-pack 会进一步检查全部模型 SHA-256，并只重新供给损坏或缺失的引擎。--repair --offline --engine-pack <ZIP> 可用有效本地包离线修复。无效显式包默认报错，增加 --fallback-online 才允许转在线下载；--offline 始终禁止在线回退。

安装进程意外退出后，系统会自动释放安装锁。目录中保留的 .runtime-install.lock 与 .engine-pack-install.lock 是正常锁载体，无须删除；另一个安装进程仍在运行时会继续等待或超时报错。

无语音、部分整场总结与 ASR 停止

合法音频经 PCM 与 VAD 检查后没有语音会显示“无语音”，音乐、笑声等事件仍保留；坏音频、模型异常不会作为无语音成功。整场总结标明完整、部分完成或补齐后完成，并列出缺失片段与原因。结束的场次由后台扫描补偿，无需保持时间线页面打开；重试缺失片段会重新请求总结。

ASR 在独立进程中推理，取消、超时与退出会终止该任务进程树并确认资源释放。日志中的 task_id、session_id、lease_token、pid、stage 和 elapsed_s 可用于关联；LLM 同步请求有独立超时，停机后迟到响应不会覆盖新任务。具体超时参数见配置参考。

浏览器模块脚本由服务端明确返回 JavaScript MIME；遇到白屏请提供失败资源 URL、Content-Type 和控制台错误，不能仅凭 Edge 或 Firefox 名称推断原因。

BiliLiveCut · 使用与维护文档
MIT License · Copyright © 2026 StarGazerQQD