1.8.5最新版本

feat(config): 模型名称改为下拉选择（优先拉供应商 /models，仍可手填）(v1.8.15)

问题
- 模型名要用户自己填，很多人填错

填错的影响
- 不存在的 id → 供应商 400/404（报错明显）
- 更麻烦：存在但更弱/更贵的模型，或中转静默换成默认模型 → 质量静默下降，用户看不出来

修复
- 模型名称改为 el-select（filterable + allow-create）：优先 GET {base_url}/models（Ollama 用 /api/tags），
  失败回退内置候选；仍可手动输入
- 新增 GET /api/config/models?provider=xxx 返回 {models, source, error}
- PROVIDERS 增加 models 内置候选（deepseek/kimi/qwen/openai）

顺带发现
- 该接口返回的 DeepSeek 列表里确实有 deepseek-v4-pro —— 用户填的模型是真的，
  之前撞上限是因为输出上限写死 8192（v1.8.14 已可配置）

验证
- 实测 GET /api/config/models?provider=deepseek → source=live，
  models=deepseek-chat, deepseek-reasoner, deepseek-flash, deepseek-v4-pro
- 前端构建通过；13 个测试文件全 PASS
- 版本号 1.8.14 → 1.8.15

解决了长视频生成速度慢和实时进度的问题

fix(whisper): 长视频「进度卡住」——真实转写进度 + 转写提速 + 前端不再假装进度 (v1.8.13)

问题
- 用户反映 1 小时左右的视频笔记生成"卡住"，进度一直不动

根因（实测）
1. 前端进度条在转写阶段用"已用时"估算且 Math.min(35,…) 封顶 35%：
   转写一开始就爬到 35%，之后永远不动 → 看起来就是卡死
2. 无字幕视频要走本地 faster-whisper，1 小时音频 CPU + beam_size=5 通常几十分钟，
   这期间后端只写一句静态文案，没有任何真实进度

修复
- _decode 逐段消费识别结果并回调 progress(已转写秒, 总秒)；
  notes._run_generation 据此写「正在转写：12/60 分钟（20%）」（节流：每 20 秒或每 5%）
- 前端：能解析真实百分比就用它；转写/下模型等无法估算的阶段隐藏进度条，
  显示「⏳ 已用时 3 分 20 秒 · 正在本地转写」
- beam_size 5 → 1（CPU 快 2-3 倍，讲课音频差异很小），可用 whisper_beam 设置改回 5
- 生成中提示文案说明"无字幕视频要走本地转写，1 小时可能要几十分钟"

说明
- 有字幕的视频走大模型分段，长视频几分钟；截断时 v1.8.9 起会明确报「输出被截断」
- 无字幕视频慢在本地 CPU 转写，与用哪个大模型无关

验证
- 新增 test_whisper_hf.py::test_transcription_progress_is_plumbed
- 13 个测试文件全 PASS；前端构建通过
- 版本号 1.8.12 → 1.8.13

本版只解决安装/启动环节的问题，笔记与复习资料功能与 v1.8.10 相同。

如果你是"依赖安装失败"的那位用户

先看报错关键词，对症处理：

你看到的报错	原因	怎么办
ResolutionImpossible / no matching distribution found for ctranslate2	Python 版本太新（3.15 等预发布版还没有预编译包）	装 Python 3.12，并在「设置 → 应用 → 已安装的应用」里卸载那个预发布版本
did not find executable at '...\Python3xx\python.exe'	系统里残留了已卸载的 Python 路径	装 Python 3.12（勾选 Add python.exe to PATH）；把旧 Python 卸载干净再装更稳妥
下载超时 / 连接被重置	真的是网络	换网络或挂代理后重试

注意：这不是网络问题。 以前这类失败一律显示"请检查网络连接"，把人引到了错误方向 —— 本版改掉了。

🔧 本版做了什么

1. 启动前先检查 Python 版本（新增 launcher/pycompat.py）

• 支持 Python 3.10 ~ 3.14，推荐 3.12
• 3.15 及以后的预发布版本直接拦住，并说明原因与下载地址，而不是让用户等到 pip 报一堆看不懂的冲突
  （查过 PyPI：ctranslate2 4.x 与 av 12~18 都已提供 cp314 轮子，所以 3.14 是能装的；cp315 一个都没有）
• start.ps1 / start.sh 启动前同样检查

2. 自动跳过"幽灵 Python"

PATH 里残留的、已被卸载的 Python 路径，过去会被当成可用解释器（于是 venv 报
did not find executable at ...）。现在启动器会逐个真跑一次确认，不能用就换下一个，并告诉你原因。

3. 依赖安装失败分类

• 是"版本太新导致没有预编译包" → 明确写出缺哪个包、建议装 3.12
• 是"网络超时/连接失败" → 才提示检查网络
• 只有拿不准时才回退到原来的通用提示

4. 新版 Python 也能用（轻量模式）

av / faster-whisper 改为条件依赖（python_version < "3.15"）：3.15+ 上会跳过本地语音转写，
核心功能照常可用（有 CC 字幕的视频照样能生成笔记）。

5. 「环境自检」新增「Python 版本」

设置页点一下就能看到当前版本是否受支持；「离线语音转写」也会说明"当前是轻量模式"。

6. 日志乱码

启动器创建虚拟环境时强制子进程用 UTF-8，修掉日志里中文系统错误变成 ?????? 的问题。

长视频不再「JSON 解析失败」、复习资料支持「详版逐章生成」

修复：长视频「笔记生成失败 / JSON 解析失败：未找到合法 JSON」（v1.8.9）
现象：短视频能生成，长视频生成到一半报「JSON 解析失败：未找到合法 JSON」；有用户反馈"昨天成功了两三个，后面开始失败"。

原因：生成笔记要先把字幕分段写成小节，最后一次性汇总成整篇笔记 JSON；而调用模型时没有设置输出上限，用的是 DeepSeek 默认的 4096 tokens。视频越长 → 段数越多 → 汇总输出越大 → 在 4096 处被硬截断，JSON 缺了后半截。数据库里也能对上：失败笔记的字幕中位数 32,007 字，成功的是 17,491 字。

已修：

每次调用显式带上供应商的输出上限（DeepSeek/Kimi/通义/OpenAI = 8192），不再被静默截断
读到 finish_reason=length 时直接提示「模型输出被截断」，不再含糊地说"格式错误"
JSON 提取更宽容：模型在 JSON 前后写说明文字、甚至正文里先出现 LaTeX 大括号，也能正确取出
长视频两级汇总：小节超过 4 段时先分批汇总、再总汇总
错误提示说人话：401→Key 失效 / 402→余额不足请充值 / 429→限流 / 5xx→服务端故障（以前这些也都被显示成"JSON 解析失败"，很容易误判成格式问题）

环境自检

v1.8.8 — Edge 侧边栏修复、OpenAI 供应商、设置页与安装体验全面修复
v1.8.8 已包含 v1.8.1 ~ v1.8.8 的全部改动，升级只需装这一个。请使用 v1.8.8（不要发 v1.8.5）。

⚠️ 升级须知（重要）
浏览器插件必须重新加载并刷新页面：插件已升到 2.3.0。 打开 edge://extensions/（或 chrome://extensions/）→ 在插件卡片上点一次 🔄 重新加载 → 回到 B 站按一次 F5。 （不重载插件，或重载后不刷新已打开的 B 站页面，都会继续报错——内容脚本是页面加载时注入的。）
首次启动会自动安装依赖：解压后双击 BiliLearn-AI-Launcher.exe → 「启动服务」。新版会先并发测速挑最快的 PyPI 镜像再并发下载，界面显示真实进度、速度与预计剩余时间（旧版这里看起来像卡死）。
笔记不会丢：笔记数据一直放在 C:\Users<你的用户名>\BiliLearn-AI，与程序目录分离，升级或重新解压都不受影响。
✨ 新增：环境自检（v1.8.8）
「设置 → 环境自检」→ 点「开始自检」，一次过完生成笔记链路上的每个环节，逐项给出结论和处理建议：

后端版本 / Python / 数据目录；关键依赖版本（yt-dlp、huggingface_hub、hf_xet、faster-whisper、av）
B站连通性与登录态；大模型供应商 / 模型 / Key，勾选「深度检测」会真调一次模型验证连通
离线语音转写开关与依赖；语音模型缓存（没下载就会走"首次下载"这条高风险路）
模型下载环境：端点、Xet 是否已禁用、下载超时
填上 BV 号后：视频能否解析 + 有没有官方字幕（直接告诉你走「抓字幕」还是「本地转写」）
勾选「深度检测」后：真实试拉 1MB 音频，验证「音频下载」这一环
结果可「复制结果」或「下载 txt」发给开发者，不含任何 API Key / Cookie。 遇到生成失败，先跑一次自检再反馈，定位会快很多。

🐛 重要修复
修复：B站短链（b23.tv）无法生成笔记（v1.8.8 重新打包）
复制 B站「分享」出来的短链（形如
https://b23.tv/SPap0F0
）去解析时，会报： 音频下载失败：ERROR: Unsupported URL: https://www.bilibili.com/video/https://b23.tv/SPap0F0?p=1 原因是短链本身不含 BV 号，而旧代码在取不到编号时会把原始链接当成 BV 号存下去，最后拼出畸形地址。 现在会先跟随跳转把短链展开成真实地址（连 ?p=7 这种分P参数也能正确识别），所有拼地址的地方统一校验编号； 取不到编号时给出可读提示，而不是拿畸形 URL 去问 yt-dlp。

模型下载报 401 / 音频下载超时（v1.8.8）
两个用户反馈的错误，都属于「无字幕视频走本地转写」这条路：

CAS Client Error ... 401 Unauthorized, domain: https://cas-server.xethub.hf.co/... HuggingFace 新的 Xet 存储协议：huggingface_hub 1.x 下载大文件会走 Xet，而国内镜像不代理 Xet，于是去连真实的 xethub 服务器并 401（小文件正常、大权重失败）。 v1.8.8 起自动禁用 Xet（同时禁用隐式 token、下载超时 10 秒 → 60 秒），无需手动处理。
音频下载失败：ERROR: [download] Got error: The read operation timed out yt-dlp 默认读超时只有 20 秒且没有重试。现已放宽到 60 秒、重试次数拉满，并额外自动重试 3 次（支持断点续传）。
临时规避（旧版本用户）：设置环境变量 HF_HUB_DISABLE_XET=1 后重启程序；或直接用"有官方字幕"的视频——有字幕就不需要下载语音模型、也不需要下载音频，这条路完全绕开上面两个问题。

Edge 插件：从合集点进视频读不到信息（v1.8.8，插件 2.3.0）
现象：Edge 下侧边栏提示「已找到视频页，但读不到视频信息（Receiving end does not exist）」；从合集点进视频时笔记「闪一下就消失」。 根因：B 站合集/播放列表点进视频是站内 SPA 跳转（不重新加载页面），而插件原先只在 bilibili.com/video/* 页面注入内容脚本 —— 页面从未在 /video/ 上加载过，脚本就不存在，侧边栏发消息没人应答。 修复：注入范围扩大到整个 *.bilibili.com；消息失败时自动补注入并重试；内容脚本暂时读不到时不再清空已显示的笔记。 配套：插件 2.2.0 还修好了「Edge 拿不到当前活动标签页」（四级兜底：活动标签页 → 最近聚焦窗口 → 按 URL 查找 → 上次记住的标签页）。

feat(llm): 新增 OpenAI 供应商 + 修复「提取板书公式」默认项必然失败 (v1.8.5)

v1.8.5 — OpenAI 供应商、Edge 侧边栏修复、设置页与安装体验全面修复

v1.8.5 已包含 v1.8.1 ~ v1.8.5 的全部改动，升级只需装这一个。

⚠️ 升级须知（重要）

1. 浏览器插件必须重新加载：插件已升到 2.2.0。打开 edge://extensions/（或 chrome://extensions/），在插件卡片上点一次 🔄 重新加载，否则仍在跑旧代码，Edge 下会继续「看不到笔记」。
2. 首次启动会自动安装依赖：解压后双击 BiliLearn-AI-Launcher.exe → 「启动服务」。新版会先并发测速挑最快的 PyPI 镜像再并发下载，界面显示真实进度、速度与预计剩余时间（旧版这里看起来像卡死）。
3. 笔记不会丢：笔记数据一直放在 C:\Users\<你的用户名>\BiliLearn-AI，与程序目录分离，升级或重新解压都不受影响。

🐛 重要修复

设置页的「保存设置」按钮回来了（v1.8.3）

v1.8.0 误删了该按钮，导致 API Key / 默认供应商 / 模型名称 / Ollama 地址 / 转写模型 / 音频语言 / B站 Cookie / 同时处理集数 填完存不下来——这也是此前「B站 Cookie 感觉没用」的真正原因。

• 底部新增吸底保存条：保存设置 + 测试连接 + 「有未保存的修改」提示
• API Key 输入框失焦会自动保存一次，忘记点保存也不会白填
• 已保存的 Key 现在会正确显示 已保存 sk-****1234（此前前后端字段名不一致，该提示从未出现过）

Edge 浏览器插件（v1.8.4，插件 2.2.0）

Edge 下侧边栏能看到合集，但跳到视频后不显示笔记、点「生成笔记」没反应、截图也失败；Chrome 下一切正常。
根因是插件在 Edge 侧边栏里拿不到「当前活动标签页」，还把这种情况错报成「当前视频暂无笔记」。现在按 活动标签页 → 最近聚焦窗口 → 按 URL 查找所有 B 站视频页 → 上次记住的标签页 逐级兜底，内容脚本缺失时自动补注入；错误提示也会明确区分「没找到标签页」与「读不到视频信息」。

「提取板书公式」默认选项必然失败（v1.8.5）

默认选中的「DeepSeek Flash（视觉，推荐）」此前会直接报「所选供应商不支持视觉模型」，现已修复。若你的 DeepSeek 账号不支持该模型，可改选 通义千问 / Kimi / OpenAI。

本地语音转写（v1.8.1）

Windows 用户首次转写必卡在下载语音识别模型并报 WinError 10060——模型托管在 huggingface.co，国内直连会超时。

• start.ps1 / start.sh / 图形启动器默认使用国内镜像 hf-mirror.com（尊重你已设的 HF_ENDPOINT）
• 设置页新增「模型下载源」：自动（先官方、失败自动切镜像）/ 国内镜像 / 官方 / 自定义
• 模型下载失败不再被误判成「网络中断，待恢复后继续」，而是直接给出可照做的处理办法

✨ 新增

• OpenAI 供应商：默认模型 gpt-4o-mini，板书/公式识别用 gpt-4o（支持图片输入）；Key 申请 platform.openai.com，也可用环境变量 BILI_OPENAI_API_KEY
• 设置页「模型下载源」下拉
• 设置页整体重排：独立卡片分区、字段两列网格（长标签不再折行错位）、「如何获取 API Key」改为可折叠列表
• 侧栏底部：主题切换与「收起侧边栏」改为上下两行并带文字标签（原来并排在同一水平线，容易误点）

⚡ 安装提速与瘦身（v1.8.2）

• 首次安装依赖不再「看起来卡死」：并发探测 6 个 PyPI 镜像选最快 + 8 线程并发下载 wheel 后本地安装。实测同一台机器华为云 732 KB/s、阿里云仅 46 KB/s（差 16 倍），而旧版写死先试阿里云
• 进度条显示真实百分比、下载速度、预计剩余时间与当前文件名；日志逐行实时输出
• 去掉 10 分钟总超时，改为「连续 5 分钟无任何输出」才判定卡死，慢网也能装完
• 依赖瘦身：删掉 3 个零引用包（fpdf2 / python-docx / openpyxl），PyMuPDF 改为可选，uvicorn[standard] → uvicorn

📦 下载与安装

文件	说明
BiliLearn-AI-v1.8.5-portable.zip	Windows 便携版（46.7 MB，含启动器与前端）
BiliLearn-AI-Launcher.exe	启动器（便携包内已含，单独下载用于替换旧启动器）

解压后双击根目录的 BiliLearn-AI-Launcher.exe → 「启动服务」，浏览器会自动打开 http://localhost:8000

SHA256（BiliLearn-AI-v1.8.5-portable.zip）：
8DDEB4BE181DF57A7F8F345FE29973C8A807BB887BF8B843A75BC1F19EC43DF0

📝 完整更新日志

见 CHANGELOG.md

首次运行下载速度提升

提升了使用感受

v1.8.1 — 修复首次转写卡在下载语音模型

修复

• 修复国内用户首次本地转写必然失败：语音识别模型托管在 huggingface.co，国内直连会连接超时
  （WinError 10060，报错里会带 An error happened while trying to locate the files on the Hub）。
  根因是 start.sh 一直设了 HF_ENDPOINT=hf-mirror.com，但 start.ps1 和图形启动器都没有，
  而便携版恰好只有 Windows。现在三处都会默认使用国内镜像（你已自行设置过则尊重你的设置）。
• 设置页新增「模型下载源」：自动（先官方、失败自动切国内镜像）/ 国内镜像 / 官方 / 自定义地址。
  即使不改这个设置，官方源失败后也会自动改用镜像重试。
• 模型下载失败不再提示「网络中断，待恢复后继续」那种让人白等的说法，而是直接给出处理办法。
• 首次转写会明确提示「正在下载语音识别模型（约 150MB）」，不会再看不出卡在哪一步。

macOS / Linux

• start.sh：依赖安装超时与重试次数与 Windows 对齐；前端源码更新后也会重新构建（此前会一直跑旧界面）
• build_mac.sh：按实际产物提示，不再把二进制谎报成 .app

升级

遇到「一直显示正在转写，然后报连接超时」的：升级后重试即可。
旧版本也能用的临时办法：设置环境变量 HF_ENDPOINT=https://hf-mirror.com 后重启程序。

v1.8.0 — 本地视频笔记 + 笔记数据独立存放

本次更新

新增：本地视频笔记

• 首页可在「B站链接 / 本地视频」之间切换，本地 mp4/mkv/flv/avi 及常见音频格式直接生成笔记
• 「选择文件」调用系统文件选择框，原文件原地读取、不复制不上传；也支持把视频拖进页面
• 本地视频用 faster-whisper 离线转写，关键帧与板书公式直接读原文件
• 笔记详情页内置播放器（支持拖进度），时间戳点击照常跳转

重要：笔记不再丢

• 数据目录迁到 ~/BiliLearn-AI（与程序目录分离），重新下载/解压新版本不会再丢笔记
• 首次启动自动搬迁旧 backend/data 的数据
• 设置页新增「导出学习存档 / 导入合并存档」（同视频自动跳过，不覆盖本机密钥）

修复

• 合集「继续生成未完成的集数」后，之前成功的各集结果被覆盖丢失
• 浏览器插件：站内换集后停在上一集、刷新无效；题目选项 LaTeX 不渲染；截图改为按视频分组并按视频建子目录
• 主界面题目移到独立「题目」页签；「核心能力」压成一行；主题切换提示文案
• 启动器：端口被占用时自动接管本项目的旧实例（其他程序则明确报错）；启动成功以健康检查为准
• B站 Cookie 改用 yt-dlp 原生 cookiefile，新增「验证登录状态」，缺 SESSDATA 时直接告警

使用

下载 BiliLearn-AI-v1.8.0-portable.zip，解压后双击 BiliLearn-AI-Launcher.exe → 「启动服务」。
首次运行会自动创建环境并安装依赖，需要几分钟。

升级提示：如果你之前用的是 1.7 及更早版本，首次启动会把原 backend/data 里的笔记自动搬到 ~/BiliLearn-AI，不会丢数据。

v1.7.0 - 四大新功能

🎉 v1.7.0 - 四大新功能

✨ 新增功能

1. 📊 学习进度追踪

   • 每篇笔记可标记「未学 / 学习中 / 已学完」
   • 笔记列表直接点击状态标签快速切换
   • 合集详情页显示整体学习进度条
   • 插件侧边栏笔记详情页也可切换学习状态

2. 📷 截图历史管理（插件）

   • 插件顶部栏 📷 按钮一键截取当前视频画面
   • 自动命名：视频标题_时分秒.png，自动下载到本地
   • 截图历史保存在插件本地（最多 30 张，超出自动删除最早）
   • 支持查看大图、重新下载、单张删除、一键清空

3. 🔍 笔记全文搜索

   • 笔记列表页顶部搜索框，输入即搜（防抖 300ms）
   • 搜索范围：笔记标题 + 摘要
   • 搜索结果实时展示，点击跳转笔记详情

4. 🕸️ 知识点关联图谱

   • 在合集详情页点击「生成知识点关联图谱」
   • AI 分析合集内所有笔记，提取 15-30 个核心知识点
   • 按类别分色：基础概念 / 核心原理 / 关键技术 / 应用场景 / 易错点
   • 三种关联关系：前置（实线红色）、包含（虚线绿色）、相关（虚线灰色）
   • ECharts 力导向图，支持拖拽、缩放、悬停查看详情
   • 点击知识点节点跳转到对应笔记

📝 文档更新

• README 补充「下载项目」章节，说明 Download ZIP 只有 10MB 是正常的
• README 补充四大新功能的详细使用说明
• 完善 Mac/Linux 启动脚本 start.sh

🚀 快速开始

1. 下载 ZIP 并解压
2. Windows 双击 start.bat，Mac/Linux 运行 ./start.sh
3. 浏览器访问 http://localhost:8000
4. 配置 API Key 后开始使用

📦 安装浏览器插件

1. 打开 Chrome/Edge，地址栏输入 chrome://extensions/
2. 开启「开发者模式」
3. 点「加载已解压的扩展程序」，选择项目下的 extension/ 文件夹