v2.0.0-alpha.1

v2.0.0-alpha.1：新的工作台与笔记工作区

这是 2.0 的第一个 alpha 预发布版，用于试用新版桌面流程。GitHub Latest、Homebrew 默认包和 AUR 稳定包继续提供 1.7.0；试用本版请使用下方 alpha 通道或本页附件。

本版变化

• 重做桌面工作台、我的笔记、阅读页和设置：集中输入视频来源，预览后生成；最近笔记和后台任务进度在工作台可见。
• 在线视频和本地文件分别保存草稿，单次生成选项与全局默认值独立。任务记录固定来源、识别服务、模型、导出格式及保存位置，可跨重启继续或修订。
• 任务支持暂停、继续、取消和退出恢复。成功、部分完成和失败都有持久提示，在其他页面完成时保留当前阅读或设置位置；失败及待确认请求在重启后仍可处理。
• 生成结果按版本保存，重新生成与补做截图/导出保留旧版本和手工修改的文件。笔记库支持文件夹、搜索、列表/卡片，阅读支持目录、查找、截图网格和每版本阅读进度。
• 设置按默认生成、服务与模型、账号、存储与应用分组；旧配置导入前先保全原件，提供损坏配置修复和库位置恢复入口。
• Apple 原生识别在模型已缓存时直接离线加载，避免等待远端检查；缺少模型时及时提示。修复拉丁语言字幕合并丢失句间空格等问题。
• 修复 Windows 生成笔记时文件同步报“拒绝访问”和字幕导入时文件被占用的问题，补齐三平台发布所需的内置服务样本和源码补丁准备。

安装 GUI

GUI 已包含同版本 CLI 引擎，无需再安装独立 CLI 才能使用窗口。

macOS Apple Silicon（macOS 15+）

首次通过 Homebrew 安装 alpha：

brew update
brew install --cask mizorewww/tap/course2md-gui@alpha

如果已经通过 Homebrew 安装稳定版，先退出应用，再切换通道：

brew uninstall --cask course2md-gui
brew install --cask mizorewww/tap/course2md-gui@alpha

卸载命令不加 --zap，保留配置、笔记和模型缓存。手动安装过的应用可先移出 /Applications 留作备份，再执行 Homebrew 安装；也可直接使用本页 DMG 替换应用。

以后更新 alpha 使用 brew upgrade --cask course2md-gui@alpha。返回稳定通道需退出应用，卸载 course2md-gui@alpha，再安装 mizorewww/tap/course2md-gui。

Windows / Linux

平台	下载	启动
Windows x64	桌面 ZIP	完整解压，打开 course2md-desktop.exe，保留同目录的 course2md.exe
Linux x64	桌面 tar.gz	完整解压，运行 ./course2md-desktop，保留同目录的 course2md

GUI 与 CLI 都需要 ffmpeg/ffprobe，在线视频还需要 yt-dlp。Homebrew 会安装这些依赖；其他平台请按 安装指南准备。Intel Mac 和 Linux ARM64 提供独立 CLI，本版没有预编译 GUI。

独立 CLI

Homebrew alpha 与稳定 CLI 可以同时安装。CLI 配方名为 course2md-alpha，旧写法 course2md@alpha 保留为兼容别名。alpha 默认不改动终端中的 course2md 命令，使用完整路径试用：

brew install mizorewww/tap/course2md-alpha
"$(brew --prefix course2md-alpha)/bin/course2md" --version
"$(brew --prefix course2md-alpha)/bin/course2md" doctor

若要把终端默认命令切换为 alpha，先 brew unlink course2md，再 brew link --force course2md-alpha。返回稳定版时先 unlink alpha，再 link 稳定版。

手动安装可选择本页的 macOS ARM64/x86_64、Linux ARM64/x86_64 或 Windows x64 CLI。Unix 文件需赋予执行权限；Apple Silicon 还需下载 mlx-macos-arm64.metallib 并改名为 mlx.metallib，与 CLI 放在同一目录。install.sh 和 AUR 当前只跟随稳定版。

测试范围与升级

• 本机核心回归：169 项通过、2 项需在线环境的测试忽略；桌面回归：108 项通过、3 项忽略。发布流程另执行三个平台的桌面 release 测试及打包检查。
• 已实测本地视频、受控在线视频来源、字幕路径、Apple 1.7B 本地识别、API 校对/摘要、后台任务与重启恢复、版本阅读和导出。完整记录见 UX 验收矩阵。
• 真实 Bilibili 登录与不同账号网络环境、其他硬件上的本地识别仍需试用反馈。
• 升级前退出旧应用，替换完整应用包；保留旧配置和课程输出。2.0 会建立新的工作区索引，旧笔记和手工导出会保留。若需回到 1.7.0，旧版不能管理 2.0 的任务与版本历史。

启动后在应用「关于」确认 2.0.0-alpha.1；独立 CLI 使用 --version 确认。反馈问题时附上系统、操作步骤与已脱敏的诊断信息。

English

This is the first 2.0 alpha prerelease, featuring a redesigned desktop workspace, independent drafts, resumable tasks, persistent background results, versioned notes, improved reading and settings, and offline loading of cached Apple speech models.

Install the Apple Silicon GUI with brew install --cask mizorewww/tap/course2md-gui@alpha, or use the platform assets above. Quit and uninstall the stable cask first if installed; omit --zap to preserve user data. The GUI bundles its matching engine. The optional course2md-alpha formula is keg-only, so use $(brew --prefix course2md-alpha)/bin/course2md or explicitly switch your links. Stable Homebrew, AUR and GitHub Latest remain on 1.7.0. Version 1.x cannot manage the new 2.0 task and note-version history.

Full Changelog: v1.7.0...v2.0.0-alpha.1

v1.7.0

v1.7.0：桌面课程库、首次引导与 Bilibili 扫码登录

• 首次启动引导选择识别方式和笔记目录，缺少工具时提供安装帮助。
• 课程库支持列表、卡片和文件夹分组，记住展示偏好；移动或删除逻辑文件夹不会删除笔记文件。
• 在桌面设置或 Bilibili 来源页扫码登录、检查账号状态和恢复过期会话；CLI 与 GUI 共享登录状态。
• 设置按用途分组并自动保存，改进导出格式校验、任务进度、控件对齐、无障碍名称和减少动态效果。
• CLI 新增 GPU 卸载控制；修复 CPU 模式卸载保护、Bilibili 412 重试、文件锁和失败诊断记录。

先选 GUI 或 CLI

想用窗口操作，下载 GUI。想在终端或脚本中运行，安装 CLI。GUI 已内置同版本 CLI，无需另装 CLI 才能使用窗口；Homebrew Formula course2md、AUR course2md-bin 与 install.sh 安装的是独立 CLI，不会安装桌面应用，也不会由 GUI 自动添加终端命令。

GUI 安装

推荐包管理器（自动安装视频工具）：

• macOS Apple Silicon：brew install --cask mizorewww/tap/course2md-gui
• Arch Linux / CachyOS x86_64：yay -S course2md-gui-bin（也可使用 paru）

详细的 GUI 指南与 CLI 指南已分开维护。

系统	下载文件	安装与启动
macOS Apple Silicon（M 系列，建议 macOS 15+）	course2md-gui-macos-arm64.dmg	打开 DMG，将 course2md.app 拖入「应用程序」，再从那里启动
Windows x64	course2md-desktop-windows-AMD64.zip	完整解压，打开其中的 course2md-desktop.exe；保留旁边的 course2md.exe
Linux x64（Ubuntu 24.04 构建）	course2md-desktop-linux-x86_64.tar.gz	解压，在目录中运行 ./course2md-desktop；保留旁边的 course2md

macOS ZIP 是同一应用的备用分发格式。Intel Mac 与 Linux ARM64 本次提供独立 CLI，没有对应的预编译 GUI。GitHub 自动生成的 Source code 压缩包是源码，不能直接当应用打开。

GUI 和 CLI 都需要外部视频工具：ffmpeg（包含 ffprobe）；在线视频另需 yt-dlp。macOS 可运行 brew install ffmpeg yt-dlp；Windows 可运行 winget install --id Gyan.FFmpeg -e 与 winget install --id yt-dlp.yt-dlp -e；Ubuntu 可运行 sudo apt install ffmpeg yt-dlp。安装后重新打开应用或终端，让 PATH 更新生效。

首次打开 GUI：按引导选择笔记目录和识别方式 → 在「设置 → 运行环境」确认依赖 → 添加链接或本地视频 → 生成笔记。Bilibili 可从「设置 → 连接账号」扫码登录。Apple 原生识别首次下载模型；本地 GPU/CPU 识别需额外安装 llama-server 及模型；云端 API 需配置自己的端点、密钥与模型。有可用字幕时默认优先使用字幕。详细依赖见中文安装指南。

CLI 安装

• macOS / Homebrew：brew install mizorewww/tap/course2md。升级使用 brew update && brew upgrade course2md。
• Arch / CachyOS：yay -S course2md-bin（CLI 包）。
• macOS / Linux 脚本安装：先按安装指南准备依赖，再运行 curl -fsSL https://raw.githubusercontent.com/mizorewww/course2md/v1.7.0/install.sh | bash。脚本下载最新正式版到 ~/bin，请将该目录加入 PATH；脚本检查依赖，非 Apple Silicon 平台还要求 llama-server。
• Windows x64：下载 course2md-windows-x86_64.exe，改名为 course2md.exe，放入已加入 PATH 的目录。PowerShell 在当前目录执行时使用 ./course2md.exe。
• 手动下载：macOS 提供 course2md-macos-arm64 / course2md-macos-x86_64；Linux 提供 course2md-linux-x86_64 / course2md-linux-aarch64。Unix 下载后改名为 course2md 并赋予执行权限。Apple Silicon 还需下载 mlx-macos-arm64.metallib，改名为 mlx.metallib，与 CLI 放在同一目录。

安装后验证并开始转换：

course2md --version
course2md doctor
course2md ./lecture.mp4

首次交互运行会引导配置识别后端。包管理器可能稍晚同步；如果版本仍旧，请用本 Release 的对应文件安装。

升级

退出旧 GUI 后替换应用或完整解压新版目录，避免混用新旧 GUI/CLI 文件。已有共享配置和课程输出继续使用；无需删除配置、登录凭据或模型缓存。独立 CLI 与 GUI 分别升级，并用 course2md --version 和 GUI「关于」确认版本。

English installation guide

Choose GUI for a desktop window, or CLI for terminals and scripts. GUI packages bundle the matching engine; the Homebrew course2md formula, AUR course2md-bin and install.sh install only the standalone CLI. Installing the GUI does not add course2md to your shell PATH.

• GUI package managers: brew install --cask mizorewww/tap/course2md-gui (Apple Silicon) or yay -S course2md-gui-bin (Arch x64). These install the desktop app and video tools.
• GUI manual downloads: use the platform download table above. On Apple Silicon, open the DMG and drag the app to Applications. On Windows/Linux, extract the entire archive and keep the desktop executable beside its bundled CLI. Intel Mac and Linux ARM64 have standalone CLI builds only. “Source code” archives are for developers.
• Dependencies: install ffmpeg/ffprobe; online videos also need yt-dlp. Restart the app/terminal after installing tools. Local GPU/CPU recognition additionally needs llama-server and models; Apple-native recognition downloads models on first use; cloud recognition requires your API configuration.
• First launch: complete the setup guide, check Settings → Runtime environment, add a URL or local video, then generate notes. Bilibili QR login is available in account settings.
• CLI: brew install mizorewww/tap/course2md (macOS), yay -S course2md-bin (Arch), or use the standalone release binary for your OS/architecture. Rename it to course2md (course2md.exe on Windows) and add its directory to PATH. On Unix, make it executable. Apple Silicon manual installs also require mlx-macos-arm64.metallib, renamed to mlx.metallib, beside the CLI.
• Verify: run course2md --version, course2md doctor, then course2md ./lecture.mp4. See the full installation guide for backend setup.
• Upgrade: quit the old app and replace the whole app/archive. Upgrade standalone CLI separately. Existing settings, notes and model caches remain usable. Package-manager updates may follow the GitHub release with a short delay.

Full Changelog: v1.6.0...v1.7.0

v1.6.0

Native desktop

The desktop app now uses GPUI + GPUI Component on macOS, Windows and Linux. The Tauri client has been removed.

• A lighter neutral palette with restrained blue accents, clearer typography and compact navigation.
• A simpler conversion form, expandable options and always-accessible start / cancel / save actions.
• Automatic reading after conversion, a searchable course library with thumbnails, and document / screenshot / file views.
• Settings grouped by purpose, environment readiness checks and preserved input when returning to a task.
• Development tracks upstream main; this release uses the exact tested GPUI and component revisions recorded in desktop/sources.lock.json.

Reliability

Fixes include temporary-file collisions, interrupted checkpoints, concurrent output/model writers, transcript timing, model aliases, multipart ASR uploads, JSON repair inside strings, local video timestamp links, and child-process cleanup. CLI and desktop share configuration resolution.

Downloads

• macOS Apple Silicon: course2md-gui-macos-arm64.dmg; drag the app to Applications.
• Windows x64: course2md-desktop-windows-AMD64.zip; extract and launch course2md-desktop.exe.
• Linux x64: course2md-desktop-linux-x86_64.tar.gz; extract and launch course2md-desktop.
• Standalone CLI binaries remain available for the existing platforms.

Desktop packages include the CLI. Video processing requires ffmpeg/ffprobe; online videos also require yt-dlp. Offline speech recognition requires the selected backend's runtime and models. Existing course output and CLI configuration remain usable.

Full Changelog: v1.5.0...v1.6.0

v1.5.0

Full Changelog: v1.4.1...v1.5.0

v1.4.1

Full Changelog: v1.4.0...v1.4.1

v1.4.0

Full Changelog: v1.3.0...v1.4.0

v1.3.0

Full Changelog: v1.2.0...v1.3.0

v1.2.0 — 段落组织 / 视频总结 / 推理模型兼容

course2md v1.2.0

阅读体验与 LLM 稳定性版本：段落组织 + 视频总结 + 推理模型兼容。
本版本两项核心改进来自社区贡献，感谢 @QiuShunan 与 @1Cookie2gavh 🎉

✨ 新特性

段落组织（#6，感谢 @QiuShunan 的首个贡献）

• 同一截图下、短停顿（<3.5s）内的连续 ASR 片段合并为自然段落——
  文稿不再是 VAD 碎片流水账；LLM 校对单位随之升级为段落
• 独立语气词条目（「嗯」「啊」）自动过滤，无需 LLM
• 跨页文本只在句读/空格处切分，找不到自然断点整段保留（不词中截断）
• HTML 去掉「……」对话式包裹；timeline.jsonl 完整保留原始事件供溯源

视频总结（#7，感谢 @1Cookie2gavh）

• course2md summarize <目录>：为已有输出生成 TL;DR / 核心要点 /
  带时间戳大纲，就地写入 course.md/html（幂等，--force 覆盖，
  -o 导出独立 <标题>.summary.md）
• [llm] summarize = true 转换后自动总结；超长视频 map-reduce
• 幻觉防护：仅以带时间戳字幕为输入、temperature=0、结构化 JSON 输出

推理模型润色兼容（#7）

• json_object 响应格式（端点不支持时自动降级重试）
• max_tokens 16384（reasoning 不再吃光正文预算）
• 解析三级容错：严格 → 尾逗号清理 → 逐对象扫描跳坏项
• 失败批次拆半递归重试；Section 级 4 路并发润色（长视频约 1/4 耗时）
• DeepSeek V4 Flash 等推理模型从「必现失败」到稳定可用

其他

• course2md remove [--asr]：清除 LLM/STT API 凭据（分享/提交前）

🔧 移植时修复（#7 代码审查）

宽容扫描方向反了会漏掉首对象；严格解析含坏项时早退跳过降级；
json_object 无降级路径；contains_summary 标题误判；CI 编译错误
与 clippy 违规。全部已带回归测试。

📦 安装

brew upgrade mizorewww/tap/course2md
# 或下载下方对应平台二进制

完整变更见 CHANGELOG.md。

Full Changelog: v1.1.0...v1.2.0

v1.1.0 — 视觉润色 / 进度条修复 / 交互编辑

course2md v1.1.0

两个交互体验修复 + LLM 视觉润色增强。

✨ 新特性

• LLM 视觉润色 --llm-vision（或配置 vision = true）
  按节附对应幻灯片截图，模型参照画面纠正技术词汇拼写；端点不支持图片时
  该批自动降级纯文本。llm setup 交互式询问模型视觉能力。
  实测：ASR 乱码 "Neo Vimcuber needs." → 带图润色后 "Neovim, Kubernetes."，
  原文保留在 raw 字段溯源。
  👉 实现 #5 — 感谢 @mizorewww 的提议
• 纯语气词条目删除：仅由「啊/嗯/对吧」等构成的条目整条删除（原文进 raw）。

🐛 修复

• ASR 进度条恢复原地更新：llama-server 的 slot 日志（stderr 继承终端）
  此前插在进度条重绘之间，把每次更新顶成新起一行。改为 piped + 后台 drain，
  失败诊断自动附 stderr 尾部缓存。
  👉 修复 #4 — 感谢 @mizorewww 的报告（含 pty 复现定位）
• llm setup / 模型选择支持方向键编辑：裸 read_line 不处理
  ←/→/Home/End 转义序列。改用 dialoguer 行编辑。
  👉 修复 #3 — 感谢 @mizorewww 的报告

📦 安装

brew upgrade mizorewww/tap/course2md
# 或下载下方对应平台二进制

完整变更见 CHANGELOG.md。

v1.0.0 — 首个正式版（字幕优先 / doctor / 运行溯源）

course2md v1.0.0 — 首个正式版

把网课视频变成图文并茂的 Markdown / HTML 笔记。
本版本以「正确性审计 + 架构收敛」为主题：修复全部已知的静默错误结果与数据丢失类缺陷。

✨ 新特性

• 平台字幕优先 --transcript-source auto|subtitle|asr（默认 auto）
  平台人工字幕 > 自动字幕 > 本地 ASR；命中字幕时完全不抽音频、不加载模型。
  本地视频支持同名 .srt/.vtt sidecar 字幕。
  👉 实现 #1 — 感谢 @kernerydel 的建议
• course2md doctor：环境体检——依赖工具、平台后端（CoreML/NPU）、
  配置文件（含权限告警）、模型缓存状态，一次命令定位大多数环境问题。
• run.json 运行溯源：每次运行记录版本、转写来源、provider/模型、统计与耗时。
  「这份文稿到底是什么模型跑的」从此可查。
• structured.json 增加 schema_version 与 generator；Section 增加 end 时间。
• --resume / --no-resume 互斥参数真正生效。

🐛 修复

• --no-resume 此前完全无效（声明了但从未被读取）
• --no-download 不再删除用户已有视频（此前结束时会误删非本次下载的 media.mp4）
• checkpoint 运行身份：换模型/后端/切分长度后，旧进度自动作废重算，
  不再产出「混用两个模型」的转写文本；空语音 chunk 也计入进度，不再重复识别；
  写盘失败不再标记完成；中间行损坏硬报错而非静默跳过
• NPU 后端三连修：内嵌 Python worker 语法错误（--provider npu 此前完全无法启动）、
  硬编码 <|zh|> 强制中文（英文课产生中文幻觉转写）、Qwen 失败静默回退 Whisper
• GGUF 下载尊重 HF_ENDPOINT 镜像（此前硬编码 huggingface.co）
  👉 Fixes #2 — 感谢 @little-q-exist 的详细报告与根因分析
• 预检校验：max_speech=0 panic、--formats 拼错跑到最后才报错、
  provider×模型不兼容被静默忽略、api 缺 key 切完音频才发现——全部提前到毫秒级失败
• 相似度阈值文案方向修正（实际语义：阈值越高越敏感、截图越多）
• 配置路径展开 ~；配置未知字段直接报错；~/.config 权限告警

🔧 重构

• provider / slide_mode / formats 裸字符串 → typed enum（CLI/TOML/运行时同源）
• ManagedChild 子进程生命周期（kill-on-drop，修复 NPU worker 进程泄漏）
• 四个 ASR 后端的重复 chunk 循环收敛为统一执行器
• 跨页文本切点吸附句读，不再词中切断；模型选择器去除不可复现的营销话术

⚠️ 迁移提示

• 1.0 前的 ASR checkpoint 会在下次运行时自动作废重算（保证转写来源可追溯）
• --transcript-source auto 成为默认：有平台字幕的视频不再走本地 ASR；
  如需旧行为请传 --transcript-source asr

📦 安装

# macOS (Homebrew)
brew install mizorewww/tap/course2md

# 或直接下载下方对应平台二进制

完整变更见 CHANGELOG.md。

🙏 感谢 @kernerydel 与 @little-q-exist —— 本版本的两个用户可见改进均来自你们的 issue。