Skip to content
Back to search

bilibili-douyin-notes

把B站/抖音/YouTube/小红书视频整理成Markdown课堂笔记,并支持已有课程复习。用户发来视频链接或分享口令要求做笔记、总结、转文字,或针对已有课程说“考考我 / 复习这门课 / 我哪些没掌握”时使用;复习不需要视频URL。产出经质量门禁校验的课堂笔记,或基于已有笔记逐题自测、回看与经用户同意的掌握标记。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lucky-luor--bilibili-douyin-notes/badge.svg)](/listings/lucky-luor--bilibili-douyin-notes)

HTML

<a href="/listings/lucky-luor--bilibili-douyin-notes"><img src="/api/listings/lucky-luor--bilibili-douyin-notes/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

本 skill 遵循 **Agent Skills 规范**(`SKILL.md`),任何支持该规范的 AI Agent 均可安装。 支持的安装路径:

- `~/.claude/skills/` —— Claude Code - `~/.zcode/skills/` —— ZCode - `~/.agents/skills/` —— DSH、Codex 等多种 Agent 共用的通用 skills 路径

其他兼容 Agent 放入其各自的 skills 目录即可。

> 🧩 **DeepSeek Harness(DSH)用户**:推荐安装插件版 [dsh-video-notes](https://github.com/lucky-Luor/dsh-video-notes),一条命令装好,随插件升级: > `npx -y @deepseek-ai/dsh plugin --profile web add github:lucky-Luor/dsh-video-notes`

# 1. 克隆到你的 agent 的 skills 目录(以 ZCode 为例)
git clone https://github.com/lucky-Luor/bilibili-douyin-notes.git ~/.zcode/skills/bilibili-douyin-notes

# 2. 安装 Python 依赖(按需:各平台流程所需依赖见 requirements.txt 内注释)
pip install -r requirements.txt

# (可选)只装测试依赖:tests/ 离线可跑,无需 faster-whisper / av / gmssl(numpy / pillow 仍需安装)
pip install -r requirements-dev.txt

# 3. (可选)扫码登录B站,自动获取 AI 字幕
python scripts/bili_fetch.py --login   # 生成二维码 PNG 图片并打印路径,B站 App 扫码即登录,SESSDATA 自动写入 config.json
                                       # 无 B站App:cp config.example.json config.json 后按文件内注释手动填写
# 4. 环境自检:逐项给出 ✅ / ⚠️ / ❌ 和修复命令(--platform douyin 只查抖音相关项,--json 供智能体解析)
python scripts/doctor.py

> **路径说明**:`SKILL.md` 中示例命令的 `<skill安装目录>` 为占位符,使用时请替换为 > 本 skill 的实际安装路径(脚本内部均基于 `__file__` 相对定位,改路径不影响运行)。

<details> <summary>最小依赖说明</summary>

| 组件 | 用途 | 是否必需 | |---|---|---| | `faster-whisper` | 语音识别兜底 | 做无字幕视频笔记时必需 | | `av`(PyAV) | 音频解码 / 视频抽帧 | 同上(faster-whisper 依赖链会带上) | | `gmssl` | 抖音 a_bogus 签名(SM3) | 仅抖音链接需要 | | `yt-dlp` / `youtube-transcript-api` | YouTube 元数据、字幕与音频(建议另装 deno) | 仅 YouTube 链接需要 | | `numpy` / `pillow` | 截图画质初筛(像素占比法 QC) | 仅截图流程需要 |

</details>

在 Claude Code 里接国产模型

Claude 官方服务不支持中国大陆。可以让 Claude Code 改用国产模型,本 skill 不需要任何改动。三家都提供 Anthropic 兼容接口,只要设置两个环境变量,把 Key 填进 `ANTHROPIC_AUTH_TOKEN`(不要同时设置 `ANTHROPIC_API_KEY`):

| 模型 | `ANTHROPIC_BASE_URL` | 官方文档(模型名以文档为准) | |---|---|---| | DeepSeek | `https://api.deepseek.com/anthropic` | [DeepSeek:Integrate with Claude Code](https://api-docs.deepseek.com/quick_start/agent_integrations/claude_code/) | | Kimi | `https://api.moonshot.cn/anthropic` | [在 Claude Code 中使用 Kimi](https://platform.kimi.com/docs/guide/claude-code-kimi) | | 智谱 GLM | `https://open.bigmodel.cn/api/anthropic` | [智谱:Claude API 兼容](https://docs.bigmodel.cn/cn/guide/develop/claude/introduction) |

# 以 DeepSeek 为例(Windows PowerShell 把 export 换成 $env:NAME="值")
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<你的 DeepSeek API Key>
claude

各家的模型名更新很快,`ANTHROPIC_MODEL` 等变量请按上面的官方文档填写。笔记质量取决于所接的模型,质量门禁 `validate_note.py` 会兜住格式下限。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 302 lines
  1. ---
  2. name: bilibili-douyin-notes
  3. description: 把B站/抖音/YouTube/小红书视频整理成Markdown课堂笔记,并支持已有课程复习。用户发来视频链接或分享口令要求做笔记、总结、转文字,或针对已有课程说“考考我 / 复习这门课 / 我哪些没掌握”时使用;复习不需要视频URL。产出经质量门禁校验的课堂笔记,或基于已有笔记逐题自测、回看与经用户同意的掌握标记。
  4. ---
  5. # B站/抖音/YouTube/小红书视频 → Markdown 课堂笔记
  6. ## 触发条件
  7. - 做笔记:用户消息中包含 bilibili.com / b23.tv / BV号 / douyin.com / v.douyin.com / iesdouyin.com / youtube.com / youtu.be(含 /shorts/、/live/)/ xiaohongshu.com / xhslink.com 链接(或抖音、小红书分享口令文本),且要求总结、做笔记、整理复习资料、提取视频内容等。
  8. - 复习已有课程:用户说“考考我 / 复习这门课 / 我哪些没掌握”等,直接进入“复习模式”,**不以视频URL为必要条件**。课程目录从上下文确定;无法确定时只问目录。
  9. ## 平台分流(制作新笔记时先看链接属于哪个平台)
  10. - **B站** → `bili_fetch.py`:走官方API,优先字幕,按需下载音频/视频流
  11. - **抖音** → `douyin_fetch.py`:游客身份(无需登录/SESSDATA),下载视频到本地供语音识别(只用于本地转写,用完可清理),一般无字幕 → 必走第二步ASR(抖音视频短,耗时可忽略)。需要 `pip install gmssl`;`abogus.py` 为 GPLv3 代码(源自 Evil0ctal/Douyin_TikTok_Download_API 经 BiliNote 移植),分发需保留其许可头
  12. - **YouTube** → `yt_fetch.py`:默认优先原语言人工字幕 → 中文人工字幕 → 原语言自动字幕 → 原有兜底(yt-dlp json3 字幕 → 无字幕交 ASR);显式 `--lang` 覆盖默认语言优先级。有字幕时不下载任何媒体;需要 `pip install yt-dlp youtube-transcript-api`,并建议安装 [deno](https://deno.com)(yt-dlp 解 YouTube JS 挑战所需)
  13. - **小红书** → `xhs_fetch.py`:免登录、无签名,手机 UA 请求分享页并解析内嵌 `__INITIAL_STATE__`,下载视频到本地(默认 h264 转码流,`--origin` 下载体积大得多的原片);**只支持视频笔记**,图文笔记脚本直接提示退出;链接必须带 `xsec_token`(让用户从 App「分享 → 复制链接」整段发来);一般无字幕 → 必走第二步 ASR
  14. - 四个平台的 metadata.json 字段一致,第二/三步脚本自动兼容:B站分P按 `bvid/cid` 按需下载,抖音分P带 `media_path` 直接用本地视频文件
  15. ## 工具位置
  16. - 脚本目录:本 skill 安装目录下的 `scripts/`(命令中的 `<skill安装目录>` 占位符请替换为本 skill 实际安装路径)
  17. - 配置文件:本 skill 安装目录下的 `config.json`(存放 SESSDATA;截图上传语雀用的 OSS 配置写在 `oss` 字段)
  18. - 参考资产:
  19. - `references/note-template.md` —— 课堂笔记模板 v4 / v4-obsidian(语雀 / Obsidian 版式、骨架、语法契约、时间戳规范)
  20. - `references/asr-glossary.json` —— ASR 术语纠错词表(真实错法→正确写法)
  21. - `references/anchors.json` —— 截图关键词锚点表(按视频 ID 隔离;仅在不用 `--shots` 清单时兜底)
  22. ## 工作流程
  23. ### 第零步:环境自检(每个会话第一次处理视频前跑一次)
  24. ```bash
  25. python "<skill安装目录>/scripts/doctor.py" --platform <本次链接的平台> --json
  26. ```
  27. - 平台取 `bilibili` / `douyin` / `youtube` / `xiaohongshu`;退出码 1 表示有 FAIL
  28. - 有 `FAIL`:先把对应的 `fix` 原样告诉用户并停下,修好再开工;不要跳过自检硬跑
  29. - 只有 `WARN`:可以开工,开工前用一句话说明影响(如“没有显卡,这个无字幕视频大约要 X 分钟”“YouTube 连不上,需要代理”)
  30. - `skill 文件` 为 FAIL(被加密软件处理过)时,提示用户用 `git clone` 重新安装,不要尝试自己修文件
  31. ### 整门课模式(B站,先于第一步判断)
  32. 用户发来 B站链接或 BV号,环境自检通过后,先建立课程清单:
  33. ```bash
  34. python "<skill安装目录>/scripts/course_plan.py" plan "<链接>" "<课程目录>"
  35. ```
  36. 1. 读取 stdout **最后一行 JSON**;`course:false` 表示单P无合集,继续下面的原单视频流程。`course:true` 时,把 `confirm_text` **原样发给用户**,并转述 `hint_optional`;用户没有回复,不能调用 `start` 或开始抓取、转写、写笔记。
  37. 2. 用户选好范围后调用 `start "<课程目录>" --all`、`--first 3` 或 `--range 5-12`;标题明显为英文原声课且没有“中字 / 中英 / 配音”提示时,启动前先确认是否英文转写(见第一步)。用户选择另一种组织范围时加 `--scope pages|season`。多分P有合集时默认只做当前视频;单P有合集默认展开,也可选择只做当前视频。超过 200 集或 100 小时的清单禁止 `--all`,只能选前若干集或指定范围。模板默认取 `config.note_template`,也可在 `start` 显式选择 `--template v4|v4-obsidian`;ASR 语言用 `--asr-lang zh|en|auto`。例如:
  38. ```bash
  39. # 语雀版式,中文转写
  40. python "<skill安装目录>/scripts/course_plan.py" start "<课程目录>" --first 3 --template v4 --asr-lang zh
  41. # Obsidian 版式,英文转写;需要自动检测时将 en 改为 auto
  42. python "<skill安装目录>/scripts/course_plan.py" start "<课程目录>" --first 3 --template v4-obsidian --asr-lang en
  43. ```
  44. 3. 串行循环 `next "<课程目录>"`。`status:next` 的 `steps` 给出 fetch / transcribe / note 步骤;`skip:true` 不执行。优先按 `argv` 参数数组执行,避免含空格路径或特殊字符经过 shell 二次解释;`cmd` 是展示用命令。
  45. 4. fetch 后重新检查**本集**的 `subtitle_detail` 和正式文本:`cc/ai` 且正式文本存在可跳过转写;其它无字幕状态走单集 ASR。`ai_mismatch` 的存疑文本不可用于笔记。读取转写逐集 JSON,进程退出码非 0 或 JSON `status:error` 都算失败;`nothing_to_do` 时也必须确认目标页及正式文本存在,不能直接视为成功。需要恢复元数据时按三段提示处理。
  46. 5. 每集按第三步的全部规则独立制作笔记,模板以 `next` 返回的 `note.template`(`v4` / `v4-obsidian`)为准,使用 `note_path`。`existing_note:true` 时在原文件上修正;除文件缺失外,不要整篇重写。只读这一集的正式转写稿,不要把前面各集的全文持续留在上下文。英文课正文首次出现的术语写作 **中文(Original)**,概念卡用中文卡名并加 `+ 原文:Original`;原本中文课程、或卡名本身是纯外文专名时免加原文行。截图仅用户明确要求时执行。按 `nav_cmd` 填深链,再按 `validate_cmd` 做最终门禁,确认 errors 为 0;两个命令都带本集 `--page N` 和选定模板。
  47. 6. 成功后 `mark "<课程目录>" <序号> done --note "<笔记路径>"`;`mark done` 还会执行进程内门禁,拒绝时按报告修正后重试,不能凭先前校验结果强记 done。一集任何步骤失败(含门禁修正后仍失败),用该步的“原因 / 下一步”调用 `mark "<课程目录>" <序号> failed --reason "<原因>" --next-step "<下一步>"`,**继续下一集,不停下来反复询问用户**。课程批处理不强制扫码登录,可将可选登录建议留给用户;失败集可稍后补跑。
  48. 7. 每次 `mark` 把摘要的 `progress` 原样转告用户。`next` 返回 `status:finished` 时,把 `receipt_text` **原样转述**,保留其中的完成数、失败集、课程索引、概念表、课程自测和补跑信息,不自行编造回执。仅当 `cache.bytes > 0` 时询问是否清理缓存;用户同意后才执行 `python "<skill安装目录>/scripts/course_plan.py" clean "<课程目录>" --apply`,`cache.bytes = 0` 时不询问。
  49. 8. 中途被打断时再次 `next` 会先复查已 done 的集,再交出待处理集(含原来的 running 集)。笔记 SHA 与模板未变化时复用缓存、跳过检查;笔记改坏或缺失时退回 pending,保留 `planned_note` 供原位修复。已有草稿不会自动成为 done。需要手动复查时用 `verify "<课程目录>"`,它与 `next` 共享 SHA 校验缓存,并非强制全量检查;`index "<课程目录>"` 刷新课程索引,`status "<课程目录>"` 只读查询、不触发复查。`mark "<课程目录>" <序号> pending` 可把失败集放回待处理,再调用 `next`。`plan` 刷新同源同模式清单会保留结果;切换模式用 `start --scope`。不要把转写 `.done` 与课程笔记的 done 状态混为一谈。
  50. 课程目录中的 `course.json` 是课程进度的唯一状态来源;`videos/<BV号>/` 复用单视频抓取产物,同 BV 只抓取一次,`notes/` 每集一篇。默认最多探测 60 集字幕、间隔 0.3 秒;`plan --probe-all` 全探,`--no-probe` 跳过,未探测或失败按需要 ASR 保守估算。预估按六核笔记本 CPU,ASR 初值为视频时长的 0.2 倍;笔记整理初值按 I4 前15集样本的差值中位数校准为每集60秒(不含ASR,长课与不同机器可能偏离)。后续剩余时间使用已完成集的有效平均耗时修正。
  51. ### 复习模式(已有课程,无需视频URL)
  52. > 课程复习命令与使用方法见下文;验证结果和待完成项目见 [I5 验收记录](docs/verification/I5-概念表.md)。
  53. 复习只读已有单集笔记,不重新抓取、转写或修改原笔记,不新增依赖。课程进度仍以 `course.json` 为准;掌握状态以 `概念表.md` 的勾选为入口,`course.json.mastery` 只作备份。
  54. 1. 确定含 `course.json` 的课程目录,运行下面的 `--unmastered`,读取返回 JSON 的概念与已有题目。用户只问“哪些没掌握”时只列概念名;要求自测时一次只出一道题,**先不展示答案、定义或其它会泄题的内容**,等用户作答。
  55. 2. 用户答完后,对照该题已有答案说明对错与遗漏,附该题的回看链接和笔记链接。没有回看深链时给对应笔记链接并说明无时间点,不推测时间或拼造链接。
  56. 3. 用户答对,或说“这个我会了”,问一句“要标记为已掌握吗?”,**同意后才运行 `--master`**;拒绝或未回复则不标记。标记后再继续下一题。用户要求取消掌握时用 `--unmaster`。
  57. 4. 不一次列出所有答案,不自行出笔记里没有的题或改写参考答案。没有可用题目时如实说明;没有已完成笔记时按提示先完成至少一集。返回 `truncated:true` 表示最多返回了 50 个概念,不能声称已覆盖全部。
  58. ```bash
  59. python "<skill安装目录>/scripts/course_plan.py" concepts "<课程目录>" --unmastered # 只读获取没掌握的概念与题目,答案仅用于答后核对
  60. python "<skill安装目录>/scripts/course_plan.py" concepts "<课程目录>" # 生成或刷新概念表与课程自测
  61. python "<skill安装目录>/scripts/course_plan.py" concepts "<课程目录>" --master "机会成本" # 用户同意后标记掌握并刷新
  62. python "<skill安装目录>/scripts/course_plan.py" concepts "<课程目录>" --unmaster "机会成本" # 按用户要求取消掌握并刷新
  63. python "<skill安装目录>/scripts/course_plan.py" concepts "<课程目录>" --check # 只检查、不写文件,有错误时退出码为1
  64. ```
  65. `--check`、`--unmastered`、`--master/--unmaster` 三组互斥。生成汇总课程内所有 `done` 且有笔记路径的条目,不受本次范围限制;只汇总已有概念和题目,不合并改写定义。`概念表.md` 的 `+ [ ]` 改为 `+ [x]` 即已掌握,重新生成保留勾选;文件读不出时拒绝覆盖,按三段提示处理。
  66. `课程自测.md` 的答案不折叠,手动自测先遮住答案。至少勾选一个概念并重新生成后,没掌握的题才单列在最前;“全部题目”仍保留所有题。课程索引和完成回执提供两个文件的入口;刷新失败时转述 `review_warning`,不要把旧文件当作已更新结果。内测用法见 [复习版内测](docs/dev/复习版内测.md)。
  67. ### 第一步:抓取元数据 + 字幕(B站 / YouTube)或下载视频(抖音 / 小红书)
  68. B站标题明显指向英文原声课(如 Lecture / MIT / Stanford / CS61A),且没有“中字 / 中英 / 配音”等提示时,先问用户是否按英文转写;确认后再启动转写,课程模式在 `start` 选择 `--asr-lang en`(需要自动检测时用 `auto`)。不要只凭平台或中文字幕推断音频语言。
  69. ```bash
  70. # B站(也支持 b23.tv 短链)
  71. python "<skill安装目录>/scripts/bili_fetch.py" "<视频链接>" "<工作目录>/bili-notes-<BV号>"
  72. # B站只探元数据:不抓字幕、不建目录、不写任何文件(先确认视频可访问/时长/分P数时用)
  73. python "<skill安装目录>/scripts/bili_fetch.py" --probe "<视频链接>"
  74. # 抖音(也支持 v.douyin.com 短链和整段分享口令文本)
  75. python "<skill安装目录>/scripts/douyin_fetch.py" "<链接或口令>" "<工作目录>/douyin-notes-<视频ID>"
  76. # YouTube(watch / youtu.be / shorts / live / embed 链接或 11 位 ID 均可)
  77. python "<skill安装目录>/scripts/yt_fetch.py" "<视频链接>" "<工作目录>/yt-notes-<视频ID>"
  78. # 可选:--lang zh-Hans,en(字幕语言优先级)--download(无字幕时下载音频供 ASR)
  79. # --cookies <cookies.txt> / --cookies-from-browser chrome(风控/年龄限制)--proxy http://127.0.0.1:7890
  80. # 小红书(xhslink.com 短链 / explore / discovery/item 链接或整段分享文本,必须带 xsec_token)
  81. python "<skill安装目录>/scripts/xhs_fetch.py" "<分享链接或分享文本>" "<工作目录>/xhs-notes-<笔记ID>"
  82. ```
  83. - 两个脚本都自动生成 `<输出目录>/metadata.json`,stdout 最后一行是 JSON 摘要。
  84. - **B站**:每个分P的字幕 `.txt`(带 `[mm:ss]` 时间戳),按摘要里每个分P的 **`subtitle_detail` 字段六值分流(cc / ai / ai_mismatch / none / api_empty / error,其中 cc 与 ai 处置相同)**:
  85. - `cc` / `ai` → 已拿到官方/AI字幕,直接进入第三步生成笔记(AI 字幕已由脚本自动做"内容↔标题 ASCII 词"交叉校验,错位时会判为 `ai_mismatch` 而不是 `ai`);
  86. - `ai_mismatch` → AI 字幕整体错位(返回了 ai 状态但内容是别的音频,实测有配成无关电影对白的案例):**不可信,直接进入第二步 ASR 兜底**,不要用该字幕生成笔记;存疑字幕已另存 `*.ai字幕存疑.txt` 备查,摘要带 `hint_mismatch` 时可向用户提一句;
  87. - `none` → 该分P确实没有字幕,直接进入第二步 ASR,不用再折腾;**但若摘要带 `hint_optional`(未配置登录态时可能出现),转述给用户**:「若该视频本应有 AI 字幕,可扫码登录(`--login`)后重跑,通常能跳过语音识别」——由用户判断要不要扫,不强制;
  88. - `api_empty` → 接口没返回可用字幕URL(`sessdata_loaded:false` 时常见,AI字幕需要登录):**主动询问用户「要现在扫码登录B站吗?」,确认后代跑 `python "<skill安装目录>/scripts/bili_fetch.py" --login`(脚本生成二维码 PNG 图片并打印路径,把路径给用户打开扫码即登录,SESSDATA 自动写入 config.json)后重跑一次 fetch**;用户拒绝或重跑后仍是 `api_empty` 才走第二步 ASR 兜底;
  89. - `error` → 查看摘要里的 error 信息(可能是视频失效/风控),重试一次或直接告知用户。
  90. - **抖音**:视频已下载到 `<输出目录>/media_p01.mp4`(仅供本地转写,本地已存在则跳过下载),无字幕,直接进入第二步 ASR。
  91. - **YouTube**:默认按原语言人工字幕 → 中文人工字幕 → 原语言自动字幕 → 原有兜底选择;显式 `--lang` 覆盖默认语言优先级。结合 `audio_lang` / `subtitle_lang` 判断是否为原语言课程及术语表达,不因选到中文字幕就抹去英文原声课的原文术语。按摘要里分P的 `subtitle_detail` 分流:
  92. - `manual` / `auto` / `ytdlp_manual` / `ytdlp_auto` → 已写出 `01_<标题>.txt`(`[mm:ss]` 格式,自动字幕已去滚动重复)+ `.done` 标记,直接进入第三步;英文原声或英文字幕课程按第三步的中文正文、双语术语与概念卡规则撰写;
  93. - `none` → 无可用字幕:加 `--download` 重跑(下载音频到 `media_p01.m4a`),再进入第二步 ASR;
  94. - `blocked` → YouTube 拒绝了当前 IP:先建议用户配 `--proxy` 或 `--cookies-from-browser` 重跑;仍不行再 `--download` 走 ASR;
  95. - `error` → 看 stderr 日志,重试一次或告知用户。
  96. - 没有 `media_path` 的 YouTube 分P不能直接跑第二步(脚本不会去 B站接口下载),务必先 `--download`。
  97. - **小红书**:视频已下载到 `<输出目录>/media_p01.mp4`(本地已存在则跳过下载),无字幕,直接进入第二步 ASR;时间索引与抖音一样无深链(保持纯文本)。
  98. ### 第二步(兜底):语音识别转写
  99. 仅对缺字幕的分P转写(脚本自动跳过已有文本的分P):
  100. ```bash
  101. # 只转写第N个分P(推荐先转1个试听质量/估算耗时)
  102. python "<skill安装目录>/scripts/bili_transcribe.py" "<工作目录>/bili-notes-<BV号>/metadata.json" --page 1
  103. # 转写所有缺字幕的分P
  104. python "<skill安装目录>/scripts/bili_transcribe.py" "<工作目录>/bili-notes-<BV号>/metadata.json"
  105. ```
  106. 注意事项:
  107. - **设备与降级链**:自动检测 CUDA(有 NVIDIA GPU 用 float16,否则 CPU int8 + 批量推理);cuda 加载失败自动回退 cpu,批量推理不可用自动回退逐段,高阶模型(medium/large)加载失败自动降一档直到 small——**每次落级都打印原因(stderr 警告 + JSON `fallback_reasons`),不静默**。检测异常时可用 `--device cpu` / `--device cuda` 强制指定;`--model` 未指定时读 config.json 的 `asr_model`(再默认 small),`asr_cpu_threads` 可调 CPU 线程数。
  108. - **术语偏好注入**:脚本自动读词表(仓库层 + 用户层),把高频术语的正确词注入 ASR 的 initial_prompt——转写时就写对,比事后纠错更准。
  109. - **耗时**:CPU int8 下 small 模型实测约为视频时长的 0.2 倍(6 核笔记本 CPU,批量推理 + 静音过滤;更老的 CPU 会慢一些,有 NVIDIA GPU 时更快),转写前按“时长 × 0.2”告知用户预计时间,先转第 1 个分P后按实际耗时修正;长视频或对质量不满意时用 `--model medium` 重转(**先删对应的 txt**,否则脚本会跳过)。
  110. - 首次运行会下载模型(small≈480MB,自动走 hf-mirror.com 镜像)。
  111. - ASR 文稿没有标点分段质量保证,技术术语常被转错——生成笔记前用 `references/asr-glossary.json` 词表对照校正(见第三步第2条)。
  112. ### 第二步半(可选,只在用户要“带截图”时做):抽取重点截图
  113. 用户没提截图就跳过本步。要截图时,**先完成第三步的正文,再回来按小节定截图**——
  114. 脚本负责剔除空画面、找出写完且没被挡住的画面;**哪一张对得上图注由 Agent 看图决定**。
  115. (2026-11 盲评:只按讲话时刻截图,能佐证图注的只有 68%;脚本出候选网格、Agent 看图挑选,达到 95%,
  116. 见 `docs/verification/W4-截图重设计.md`。)
  117. 1. 正文写完后,为需要画面佐证的小节(PPT 关键页、架构图、代码演示、对比表、板书推导)写截图清单
  118. `<工作目录>/shots.json`,每小节 0~2 张、宁缺毋滥:
  119. ```json
  120. {"shots": [
  121. {"page": 1, "section": 2, "range": ["04:30", "06:10"], "caption": "开闭原则两层含义", "name": "two-meanings"}
  122. ]}
  123. ```
  124. `page` 分P号、`section` 笔记 `## N.` 小节号、`range` 这一小节在转写稿里的**讲解时间段**
  125. (起点是这部分内容开始讲的时间行,终点是下一部分开始前最后一行;两端都必须是该分P**转写稿里真实存在的时刻**,
  126. 先 grep 确认,偏差超过 ±5s 的条目进 `failed`,reason=`range_not_in_transcript`)、
  127. `caption` 图注、`name` 文件名(可选,缺省用 caption)。可以另写 `t`(你认为最能说明图注的时刻),它会作为一张额外候选。
  128. 2. 生成候选网格:
  129. ```bash
  130. python "<skill安装目录>/scripts/bili_screenshot.py" "<工作目录>/metadata.json" "<工作目录>" "<工作目录>/images" --shots "<工作目录>/shots.json" --candidates
  131. ```
  132. 每条清单得到一张带编号的网格 `images/_candidates/p<页>_<label>.jpg`(编号从 1 起,从左到右、从上到下,按时间先后排列),
  133. 编号与时刻记在 `images/_candidates/candidates.json`。脚本每秒看一帧、按画面切段(擦黑板、翻页、镜头切换),
  134. 每段在“讲解期间”和“讲解结束后 30 秒内”各挑一张写得最全、没被挡住的;整段只有讲师在讲(黑板、投影是空的)时
  135. 不出候选,记 `no_content: true`。这一步要把整集视频看一遍,每 10 分钟视频约需 20~40 秒。
  136. 3. **看图选编号(必做,不能跳过)**:逐张打开网格,按图注挑一张,在清单这一条写 `"pick": <编号>`:
  137. | 情况 | 处理 |
  138. |---|---|
  139. | 有一格能看清图注说的内容(PPT、类图、代码、板书) | 写它的编号;多格都行时选内容最完整、最清楚的 |
  140. | 图注描述的是**分几步出现**的内容(动画逐步展开的 PPT、分步推导的板书) | 选**所有部分都已出现的最后一帧**,不要选只出现前几步的 |
  141. | 每格都对不上(只有讲师、黑板空、画面是别的内容、还没写出来),或 `no_content: true` | 从清单删掉这一条,不嵌入笔记 |
  142. 然后不带 `--candidates` 再跑一次出图:
  143. ```bash
  144. python "<skill安装目录>/scripts/bili_screenshot.py" "<工作目录>/metadata.json" "<工作目录>" "<工作目录>/images" --shots "<工作目录>/shots.json"
  145. ```
  146. 输出 `images/p<页>_s<小节>_<name>.png` + `images/manifest.json`(记录 section)。写了 `range` 却没写 `pick` 的条目不出图
  147. (reason=`need_pick`)。结束时 stderr 打一句**回执**(同时写进 `manifest.json` 的 `summary.receipt`),
  148. 如“截图 6 张,剔除坏帧 0 张”。**交付时把这句原样告诉用户**,并说明看图时删掉了几条,例如“截图 5 张(看图删掉 2 条:只有讲师在讲)”。
  149. **一张截图都没出时脚本以非 0 退出码报错**(原因 / 影响 / 下一步),按“下一步”处理后重跑;用户要了截图,不能静默交付一篇没有图的笔记,处理不了就明确告诉用户。
  150. 4. 嵌入:选中的截图以 `![<caption>](images/xxx.png)` 嵌入**清单里写的那个小节**、它佐证的要点旁边;
  151. 一集里一张可用的都没有时,直接告诉用户“第 X 集以口头讲解为主,没有可截的画面”,不要硬凑。
  152. 交付前删掉 `images/_candidates/`(候选网格不进笔记、不上传)。
  153. **备用写法(只写 `t`、不写 `range`)**:脚本在 `t` 往后取 3 张候选择优直接出图,不经过候选网格。
  154. 这种方式只按讲话时刻截图,画面常常对不上图注,出图后**必须逐张打开看**:对不上的在转写稿里往后找这部分讲完的时刻
  155. (通常晚 30–90 秒)改 `t` 重跑一次,仍不行就删掉。只在视频很长、来不及整集分析时使用。
  156. 脚本行为:
  157. - **多帧择优(只写 `t` 的备用写法)**:每个时刻向后取 3 张候选(间隔 4s),优先画质合格帧,再挑与相邻候选差异最小
  158. (画面已静止,避开 PPT 翻页过渡)的一张;
  159. - **去重**:同一分P里与已选截图是同一画面(感知哈希接近且像素差小)的不落盘,记入进度 JSON 的 `duplicates`;
  160. - **画质 QC**:亮度用像素占比法(近黑>97% 判 dark、近白>98.5% 判 bright——白底 PPT 不会误判),
  161. 清晰度用拉普拉斯方差(<10 判 blurry);每帧 `qc` 字段非 `ok` 时由 Agent 视觉复核决定是否采用;
  162. - B站下载 480p DASH 视频抽帧后即删(填了 SESSDATA 自动取更高画质);抖音 / 小红书复用本地视频不联网;
  163. - **不给 `--shots` 时**退回关键词锚点:查 `references/anchors.json` 中**本视频 ID** 的条目
  164. (按视频隔离,别的课程的锚点不会串用),没有就用 `auto_anchors()` 从转写稿提取高频词——
  165. 这种方式与小节无关、定位粗糙,仅作兜底;
  166. - 截图文件名默认可中文;需要 ASCII 文件名时加 `--ascii-names`。
  167. ### 第三步:生成课堂笔记
  168. > **使用场景定位(2026-10-21,v4)**:本 skill 解决的是“看完课不用自己做笔记”——
  169. > 产出的是**课后复习资料**,正文按技术知识体系组织、阅读连贯:**正文零时间戳、
  170. > 零考试向标签**(讲解体:小节先抛场景或问题、以段落展开、节末「记住这个就够了」收尾,关键术语加粗);视频时间戳只存在于文末的
  171. > “视频时间索引”,供回看原片时跳转。默认 v4 为**可直接导入语雀**的纯 Markdown:
  172. > 无 frontmatter、无一级标题、答案与时间索引不折叠。`v4-obsidian` 变体增加 frontmatter,
  173. > 目录改用精确标题的 Wiki 链接,其它 v4 正文规则不变。
  174. 模板默认取 `config.note_template`,用户可显式选择;课程以 `start --template` 保存、`next` 返回的 `note.template` 为准。英文课结合 `audio_lang` / `subtitle_lang` 与用户确认的语言判断,正文首次出现的术语写成 **中文(Original)**,概念卡用中文卡名并加 `+ 原文:Original`;原本中文课程或卡名本身是纯外文专名时免加原文行,详见模板。
  175. 1. 读取 metadata.json(分P结构、时长)+ 各分P转写/字幕文本。
  176. 2. **ASR 术语校正(工具化,不是凭感觉)**:先跑
  177. `python "<skill安装目录>/scripts/apply_glossary.py" "<转写稿.txt>"`(默认 dry-run,按类别分组只出报告不改文件),按报告核对命中项,确认后再加 `--apply` 落盘(自动留 `.bak` 备份,命中词条 hits 自动累加)。词表分两层:仓库层 `references/asr-glossary.json`(编程/美食/游戏/通用大类)+ 用户层(输出目录 `glossary.user.json` 或 `~/.zcode/bdn-glossary.user.json`,同键用户层优先);候选词命中只报告(标 `[候选]`)永不替换。**维护闭环**:发现词表未覆盖的新错法 → `--add "错法=正确词" --category 编程`(或 `--candidate` 先入候选、`--promote "错法"` 转正);`--list` 查看全部;`--categories`/`--topic` 控制启用范围。注意:转写阶段已自动把高频术语注入 initial_prompt(见第二步),词表越丰富转写越准。
  178. 3. **长视频分块(写死流程,禁止跳过)**:单分P转写稿超过约 2 万字时——用 `scripts/transcript_chunk.py` 分块(默认 15000 字/块、末尾重叠 2 段,输出 `chunks/` 目录)→ **map**:逐块提炼该块要点清单 → **reduce**:把各块要点按小节层级合并汇总成最终笔记。**reduce 去重**:重叠区会在相邻块产生重复内容,合并时按 `[mm:ss]` 时间戳唯一化——同一时刻的要点/锚点只保留一次,跨块重复的锚点去重后再排进小节(该去重仅作用于分块合并的中间产物;正文按 v4 规则仍然禁时刻)。禁止跳过分块直接全文阅读长转写稿。
  179. 4. 按 `references/note-template.md`(**v4 / v4-obsidian 模板**)生成一份 MD 文件,保存到用户工作目录,命名 `<序号>-<主题>.md`(如 `2.13-业务流程建模.md`;序号取课程选集号,或按用户已有笔记递增如 `01`;主题取视频标题关键词——文件名即语雀文档标题)。生成前必读该模板文件。以下为 v4 硬性要求;`v4-obsidian` 仅将开头换成模板规定的 frontmatter(闭合后紧接核心主线引语块),目录换成 `+ [[#精确正文标题]]`,其它规则相同:
  180. - **无 frontmatter、无 `#` 一级标题**:文件第一行就是引语块 `> 核心主线:<一句话知识主线>`(行尾两个空格换行),下一行 `> 本讲目标:读完你能回答「…」「…」`(lecture 建议写 2~3 个问题),再下一行 `> 课程来源:<视频标题>(B站 BVxxx,UP主:xxx,约 N 分钟)`,有代码仓库再加 `> 课程代码:`;笔记类型取 metadata.json 顶层 `suggested_note_type`(技术密度高的短片可改为 lecture,此时第 6、7 步加 `--note-type lecture`)。**三种类型**:`lecture` 完整课堂结构;`short` 同结构的精简版;`brief` 轻量笔记——抖音 / 小红书 ≤5 分钟的单条视频由抓取脚本自动建议,用户说“简短一点 / 轻量笔记”时任何平台都可在第 6、7 步加 `--note-type brief`;brief 只写开头引语块 + `## 要点`(3~7 条能复述的话)+ 可选的细节 / 概念卡(≤3 张,不写「出现」)/ 自测题(≤2 道)/ 时间索引,不写目录和编号小节,**没内容的小节整节删掉**,结构与门禁见 `references/note-template.md` 第六之一节;课程模式不用 brief(脚本自动按 short);以下规则中 brief 不适用的项以第六之一节为准;
  181. - **目录**:`+ [N. 小节名](#锚点)` 不带时刻,末尾固定列出 本讲知识地图 / 本讲小结 / 概念卡片 / 自测题(面试速答)/ 视频时间索引;
  182. - **小节(讲解体)**:`## N. 小节名`(禁时刻后缀),**开头先抛场景、问题或朴素做法(朴素做法写进行文、不加标签,讲者没对比过就不硬造),不先给结论、不写 `**核心思想:**`**;以段落展开(一段 1~4 句),列表只用于 3 项以上并列或步骤(用 `+`),对比用表格,流程可用 ```` ```plain ```` 箭头图(语雀不认 `text`),长节可用 `### N.M` 再分;术语先用大白话解释再加粗命名;讲者的比喻写 `**打个比方:**`,笔记自补的比喻写 `**打个比方(笔记补充):**` 并尽量说明边界;**最后一行固定为 `> **记住这个就够了**:<一句话结论>`**;每小节 ≥3 行实质内容;**禁止三词标签前缀(核心必考/重点掌握/了解即可及任何变体)、禁止行内 `[mm:ss]`**;小节之间可用 `---` 分隔;
  183. - **代码块**:真实语言 fence;来源标注可选——来自克隆仓库写 `# 来源:仓库 <子项目>/<文件路径>`(注释符随语言),按视频讲解组织的可写 `# 按视频讲解还原` 或不写;任何代码块内禁时刻;
  184. - **概念卡片**:`### 概念名`(禁标签后缀)+ `+ 定义:` / `+ 出现:` / `+ 依赖:` / `+ 易混:` 四行;`出现` 写作 `第 N 节「小节名」、第 M 节「小节名」`(≥2 个小节,节名与正文小节标题一致),禁时刻;
  185. - **本讲小结**(知识地图之后、概念卡片之前;lecture 建议必备,short 可省):表格「机制/概念 | 解决什么问题 | 一句话」≥2 行 + `**学完能说的 3 句话:**` 下恰好 3 条编号句子;
  186. - **自测题(面试速答,不折叠)**:标题 `## 自测题(面试速答)`;`N. <题干>?(对应:概念名)`(概念必须在概念卡片集合内:lecture 必须、short 可选),空一行后写 `**答案:** <一段 2~6 句>`——**先说结论、再说原因、最后举例**,串联相关小节的内容,写在同一段里,内容取自转写稿(补充部分标「(视频中未展开,笔记补充)」);**不用 `<details>`**,禁时刻;lecture 4~7 道(short 2~3 道);选题主打高频原理与面试易错点,禁 yes/no 题干;
  187. - **mermaid 知识地图 = 概念关系图,不是目录树**:` ```mermaid ` 代码块,推荐 `graph TD`;`R((主题))` 为根,**节点用概念卡片里的概念**(每张概念卡都要出现),小节名放在分组标题上而不是当节点,分组行写成 `subgraph 分组名`(**不要写 `subgraph S1[分组名]`,语雀会报 Parse error**;标题不含空格、括号);**边带关系标签**表达概念之间怎么关联——`A -->|依赖| B`、`A -->|推出| B`、`A -->|组成| B`、`A -.->|易混| B`,lecture 带标签边 ≥ 概念卡数 − 1,关系尽量与概念卡「依赖 / 易混」一致;节点标签禁半角 ( ) [ ] { } 与引号、≤12 字(需要括号用全角);导入语雀后自动渲染为图;
  188. - **视频时间索引**:文末最后一节,前接 `---`,**不折叠、不写 NAV 标记**;模型只写条目 `+ [mm:ss] <与正文一级小节同名>`(一级章节一条),**不写 URL**;时刻必须取自转写稿真实时间行(允许 ±5s 内小幅前移,禁止虚构);lecture 必须有本节,short 可整体省略。
  189. 5. 笔记中引用的代码/命令必须以视频文稿内容为准;文稿未讲到的细节不要编造,可标注"(视频中未展开,建议补充)"。若视频简介里有代码仓库,克隆下来读取源码,把笔记中的代码示例换成仓库中的真实代码(首选做法)。
  190. 6. **填充时间索引深链(v4 笔记默认执行)**:
  191. `python "<skill安装目录>/scripts/note_nav.py" "<笔记.md>" --template v4 --meta "<metadata.json>" --txt-dir "<转写稿目录>"`
  192. (每个选集单独一份笔记时加 `--page <分P号>`)脚本幂等地把「## 视频时间索引」节内的 `+ [mm:ss] 标题` 条目原位填充为 `+ [mm:ss](URL) 标题`(B站生成 `?p=N&t=S` 深链,YouTube 生成 `watch?v=<id>&t=<秒>s` 深链,抖音 / 小红书无深链保持纯文本);`note_type=short` 跳过本步;brief 有时间索引就照常填链;找不到时间索引节时 warning 跳过。v3 老笔记(frontmatter 写 v3)按 NAV 标记填链;v1 / v2 已不再支持。模型输出不含 URL,脚本输出不含自由文本,职责不重叠。
  193. 7. **质量门禁**:生成后运行
  194. `python "<skill安装目录>/scripts/validate_note.py" "<笔记.md>" --template v4 --meta "<metadata.json>" --txt-dir "<转写稿目录>"`
  195. 单视频选择 Obsidian 时,第 6、7 步的模板都显式改为 `--template v4-obsidian`,例如:
  196. ```bash
  197. python "<skill安装目录>/scripts/note_nav.py" "<笔记.md>" --template v4-obsidian --meta "<metadata.json>" --txt-dir "<转写稿目录>"
  198. python "<skill安装目录>/scripts/validate_note.py" "<笔记.md>" --template v4-obsidian --meta "<metadata.json>" --txt-dir "<转写稿目录>"
  199. ```
  200. (每个选集单独一份笔记时加 `--page <分P号>`)errors 必须为 0 才交付;warnings 酌情处理(如精简篇幅)。没有 frontmatter 的笔记默认按 v4 检查(`--template v4` 可省略);v4 下出现 frontmatter / 一级标题、正文时刻、标签残留、`<details>` 折叠或 NAV 标记、时间索引缺失(lecture)、自测数量越界、概念卡「出现」格式非法等均为 error。`v4-obsidian` 需按模板提供 frontmatter 与 Wiki 目录,其它 v4 门禁不变。frontmatter 写 `template_version: v3` 的老笔记按 v3 规则检查;写 v1 / v2 或缺版本号会直接报 `VERSION` 错误(v1 / v2 规则已移除)。报告 JSON 的 `errors` / `warnings` 为**对象数组**(每项含 `check` 检查编号与 `line` 行号)。
  201. 8. **截图上传 OSS(仅带截图的笔记)**:语雀导入 Markdown 不会上传本地图片,交付前先预演
  202. `python "<skill安装目录>/scripts/upload_images.py" "<笔记.md>"`(列出将上传的图片与目标 OSS 链接,不联网不改文件),
  203. 确认后加 `--apply`:按内容哈希命名上传(远端已有则跳过,可重复执行),再把笔记里的 `images/...` 原位改写为 OSS 链接(留 `.bak` 备份)。
  204. OSS 配置读 `config.json` 的 `oss` 字段或环境变量 `OSS_ENDPOINT / OSS_BUCKET / OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET / OSS_PREFIX / OSS_PUBLIC_BASE_URL`
  205. (也可 `--env-file <xxx.env>`);Bucket 需公共读或经 CDN 可公开访问。**门禁要在上传前跑**(上传后图片是网络链接,位置与图注校验会跳过);
  206. 缺配置时脚本只列出缺哪些键,不要向用户索要密钥明文,让用户自己填进 config.json 或环境变量。
  207. 9. **媒体清理(单视频交付后按缓存询问;整门课按课程步骤 7 处理)**:若输出目录存在缓存媒体(抖音的 `media_p01.mp4` 等本地视频,或残留的 `.part`/`.audio_*`/`.video_*` 临时文件),**询问用户「是否清理缓存的视频/音频文件?重新做笔记会重新下载」**:确认 → 先跑
  208. `python "<skill安装目录>/scripts/clean_media.py" "<输出目录>"`
  209. 把将删除的清单给用户过目,再执行 `--apply` 实删;拒绝 → 跳过并说明缓存保留的意义(重跑截图/转写不再联网)。B站的临时音频/视频在流程中已自动删除,通常无残留。
  210. ## 笔记模板
  211. **完整骨架与语法契约以 `references/note-template.md` 为准(生成前必读)**——全文含
  212. lecture 完整骨架、时间戳规范、语法契约、short 差异表、截图嵌入规范、生成流程。
  213. 结构层次速览(节点内容以 `<…>` 占位):
  214. ```markdown
  215. > 核心主线:<一句话知识主线> # 文件第一行;无 frontmatter、无 # 标题(文件名 <序号>-<主题>.md 即标题)
  216. > 本讲目标:读完你能回答「…」「…」
  217. > 课程来源:<视频标题等> # 有仓库再加 > 课程代码:<仓库地址>
  218. ## 目录 # + [N. 小节名](#锚点) 不带时刻;末尾固定列出 本讲知识地图 / 本讲小结 / 概念卡片 / 自测题(面试速答)/ 视频时间索引
  219. ## N. 小节名 ×N # 场景/问题开头 → 段落展开(术语加粗、表格、代码块、打个比方、本节截图)→ 最后一行 > **记住这个就够了**:<一句话>
  220. ## 本讲知识地图 # mermaid graph TD 概念关系图:节点=概念卡,subgraph 分组,边带关系标签
  221. ## 本讲小结 # 表格 机制/概念 | 解决什么问题 | 一句话(≥2 行)+ **学完能说的 3 句话:** 1. 2. 3.
  222. ## 概念卡片 # ### <概念名>:+ 定义 / + 出现:第 N 节「小节名」 / + 依赖 / + 易混
  223. ## 自测题(面试速答)# 不折叠:题干后空一行写 **答案:** 一段 2~6 句(结论→原因→例子),lecture 4~7 道 / short 2~3 道
  224. ---
  225. ## 视频时间索引 # 不折叠、无 NAV 标记;条目 + [mm:ss] <章节名>,URL 由 note_nav.py 填充
  226. ```
  227. ## 常见问题
  228. 脚本失败时统一输出三段:`原因:` / `影响:` / `下一步:`(必要时附 `详情:`)。**把这三段原样转告用户,按“下一步”处理**,不要只说“脚本报错了”。单集失败的进度 JSON 另有 `reason` / `impact` / `next_step` / `rerun` 字段,`rerun` 是只补跑这一集的命令。
  229. | 现象 | 处理 |
  230. |---|---|
  231. | 分P `subtitle_detail` 为 `api_empty` | 主动询问用户「要现在扫码登录B站吗?」,确认后代跑 `bili_fetch.py --login`(生成二维码 PNG 图片并打印路径)后重跑;用户拒绝或重跑后仍 `api_empty` 才走 ASR |
  232. | 分P `subtitle_detail` 为 `ai_mismatch` | AI 字幕整体错位(内容是别的音频,看着通顺但与视频无关),fetch 已自动判出并按无字幕处理;直接走 ASR,不要试图沿用存疑字幕 |
  233. | 提示“请求被B站风控拦截”(HTTP 412) | 云服务器 / 机房 IP 上常见,脚本不会重复请求:换到家用网络或在本机运行;等几分钟再试 |
  234. | playurl 下载失败/音频为空 | 按提示的“下一步”处理(多为风控或需要登录);单集失败照 `rerun` 补跑这一集 |
  235. | faster-whisper 首次运行卡在下载 | 检查 HF_ENDPOINT 是否为 https://hf-mirror.com,或手动 `pip install -U huggingface_hub` |
  236. | 转写文本术语错乱 | 用 `references/asr-glossary.json` 对照校正;词表未覆盖的新错法按同样格式补进词表 `map`,下次自动生效 |
  237. | `subtitle_detail` 为 `error` | 看该分P的 `reason` / `next_step`:这一集会改走语音识别;想重取字幕按 `rerun` 重跑 |
  238. | 转写质量差(长视频尤甚) | 先删对应 txt,再用 `--model medium` 重转;有 NVIDIA GPU 时脚本会自动用 CUDA float16,也可 `--device cuda` 强制 |
  239. | 抖音提示“作品不可见” | 作品已删除、设为私密或仅粉丝可见(平台返回了 `filter_detail`),不是签名问题:告知用户换链接 |
  240. | 抖音提示“签名算法已被平台升级” / HTTP 403 | 参考 Evil0ctal/Douyin_TikTok_Download_API 或 JefferyHcool/BiliNote 更新 `abogus.py` / `WEB_SIGN_SALT`,或提 issue |
  241. | 抖音 / 小红书提示“下载的文件过小” | 多半被风控或下载地址过期:等几分钟重跑 fetch 脚本重新解析(本地已有完整 mp4 会自动跳过下载) |
  242. | YouTube 报 "Sign in to confirm you're not a bot" / `blocked` | 云服务器 IP 常被 YouTube 拒绝:加 `--cookies-from-browser chrome`(或导出 cookies.txt 用 `--cookies`),必要时 `--proxy` 或在 config.json 配 `youtube_proxy` |
  243. | YouTube 缺格式 / 下载失败 | 升级 `pip install -U yt-dlp` 并安装 deno(2025 年起 YouTube 需要 JS 运行时解挑战) |
  244. | YouTube 年龄限制视频 | youtube-transcript-api 拿不到,需 `--cookies`/`--cookies-from-browser` 让 yt-dlp 回退取字幕 |
  245. | 小红书提示缺少 xsec_token / 被重定向 / 无笔记数据 | 让用户在 App「分享 → 复制链接」把整段文本发来(token 有时效,过期重新复制);笔记需公开可见 |
  246. | 小红书提示风控验证(HTTP 461/471) | 请求过频触发验证码:稍后重试,或在 config.json 配 `xhs_cookie`(浏览器登录后复制 Cookie) |
  247. | 小红书提示「这是图文笔记」 | 本工具只处理视频笔记,告知用户换视频笔记链接 |
  248. | YouTube 正在直播 / 预告 | 脚本直接提示退出,等直播结束、回放生成后再试 |
  249. | 环境缺依赖 | B站流程需 faster-whisper + av;抖音流程另需 `pip install gmssl`;YouTube 流程另需 `pip install yt-dlp youtube-transcript-api`;小红书流程无额外依赖 |
README.md · README · 468 lines
  1. <div align="center">
  2. # bilibili-douyin-notes
  3. **把 B站 / 抖音 / YouTube / 小红书视频一键整理成 Markdown 课堂笔记的 AI Agent Skill**
  4. 四平台视频 · 字幕抓取 · 本地语音识别 · 重点截图 · 笔记模板 —— 免登录可用,不调任何付费 API
  5. [![CI](https://github.com/lucky-Luor/bilibili-douyin-notes/actions/workflows/ci.yml/badge.svg)](https://github.com/lucky-Luor/bilibili-douyin-notes/actions/workflows/ci.yml)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  7. [![Platform](https://img.shields.io/badge/平台-B站%20%7C%20抖音%20%7C%20YouTube%20%7C%20小红书-green.svg)]()
  8. [![Python](https://img.shields.io/badge/Python-3.10%2B-yellow.svg)]()
  9. [![Agent Skills](https://img.shields.io/badge/规范-Agent%20Skills%20(SKILL.md)-orange.svg)]()
  10. 简体中文 | [English](README_EN.md)
  11. </div>
  12. > 💬 对 AI 说一句「帮我把这个视频做成课堂笔记:<B站/抖音/YouTube/小红书链接>」,就能得到下面这样的笔记 👇
  13. > (完整示例:[李宏毅机器学习 · 局部最小值与鞍点](examples/01-局部最小值与鞍点.md);课程节选:[可汗微观经济学 · 前15集](examples/可汗微观经济学-前15集/课程索引.md))
  14. <p align="center"><a href="examples/01-局部最小值与鞍点.md"><img src="docs/images/note-preview.png" alt="课堂笔记效果预览:讲解体正文、知识地图与本讲小结(点击查看完整示例)" width="760"></a></p>
  15. > 📜 **仅限个人学习使用**:只处理公开视频、全部在本机运行、不收集任何数据;请勿用于传播或商用。详见[使用声明与数据去向](#-使用声明与数据去向)。
  16. ---
  17. ## ✨ 功能特性
  18. - **多平台支持**:B站(`bilibili.com` / `b23.tv` 短链 / BV号)、抖音(`douyin.com` / `v.douyin.com` / `iesdouyin.com` 链接 / 分享口令文本)、YouTube(`youtube.com` / `youtu.be` / Shorts 链接,优先取官方/自动字幕)与小红书(`xiaohongshu.com` / `xhslink.com` 视频笔记分享链接)
  19. - **整门课**:发一个B站分P或合集链接,先列清单、报预估并确认范围,再逐集出笔记;支持课程索引、完成回执、续跑门禁复查、单集失败后继续及补跑
  20. - **课程概念表与课程自测**:跨集汇总已有概念与题目,可勾选已掌握、保留勾选并回看原课;对 Agent 说“考考我”,一次一题复习,无需重新提供视频URL
  21. - **字幕优先**:自动抓取B站官方/AI字幕(可选登录),零成本秒出文稿
  22. - **ASR 兜底**:无字幕时用 faster-whisper 本地语音识别(CPU int8,国内走 hf-mirror 镜像),**不调任何付费 API**
  23. - **重点截图**:先按画面切段(擦黑板、翻页、镜头切换),剔除只有讲师在讲的空画面,为每个小节挑出写完、没被挡住的候选帧拼成带编号的网格,由 Agent 按图注看图选编号再出图(2026-11 盲评:能佐证图注的截图从 68% 提到 95%);只给时刻的旧写法仍可用
  24. - **抖音免登录**:游客身份访问公开视频,无需账号 Cookie;视频只用于本地转写,用完可清理
  25. - **小红书免登录**:解析分享页内嵌数据直接下载视频笔记,无签名、无需账号(仅支持视频笔记,不支持图文与评论)
  26. - **课堂笔记模板**:讲解体正文(小节先抛场景或问题,以段落展开,节末用“记住这个就够了”收尾)+ 关键术语加粗 + 真实代码引用 + 知识地图 + 本讲小结 + 概念卡片 + 自测题(面试速答),文末附可回看跳转的视频时间索引;v4 用于语雀直导,v4-obsidian 提供 frontmatter 与 Wiki 目录
  27. - **原语言术语**:英文课用中文整理,正文首次出现术语保留 **中文(Original)**,中文概念卡附原文,便于对照原课
  28. - **短视频轻量笔记**:抖音、小红书 5 分钟以内的视频默认出 `brief` 轻量笔记——几条能复述的要点加可选细节,不硬凑小节;其它平台说“简短一点”也能用(课程模式不使用)
  29. ## 🧩 工作流程
  30. ```
  31. 视频链接(B站/抖音/YouTube/小红书)
  32. │
  33. ▼
  34. ┌─────────────────────┐
  35. │ 第一步:抓取 │ B站:元数据 + 官方字幕(SESSDATA 可选)
  36. │ (按平台分流) │ 抖音:元数据 + 视频下载供转写(免登录)
  37. │ │ YouTube:元数据 + 官方/自动字幕(无字幕下载音频)
  38. │ │ 小红书:元数据 + 视频下载(免登录)
  39. └─────────────────────┘
  40. │ 有字幕?──────否───┐
  41. ▼ 是 ▼
  42. ┌──────────────┐ ┌──────────────────────┐
  43. │ 直接用字幕文本 │ │ 第二步:faster-whisper │
  44. └──────────────┘ │ 本地 ASR 转写 │
  45. │ └──────────────────────┘
  46. ▼ │
  47. ┌─────────────────────┐ │
  48. │ 第二步半(可选) │◄──┘
  49. │ 重点截图(PyAV 抽帧) │
  50. └─────────────────────┘
  51. │
  52. ▼
  53. ┌─────────────────────┐
  54. │ 第三步:AI 按模板 │ 课堂笔记 .md
  55. │ 生成课堂笔记 │ (小节+要点加粗+代码+知识地图+概念卡片+自测题)
  56. └─────────────────────┘
  57. ```
  58. ## ⚡ 快速开始
  59. ```bash
  60. # 一行安装(Claude Code;其他 Agent 把路径换成对应的 skills 目录)
  61. git clone https://github.com/lucky-Luor/bilibili-douyin-notes.git ~/.claude/skills/bilibili-douyin-notes && pip install -r ~/.claude/skills/bilibili-douyin-notes/requirements.txt
  62. ```
  63. 装好后先跑一次环境自检,按提示修好失败项:
  64. ```bash
  65. python ~/.claude/skills/bilibili-douyin-notes/scripts/doctor.py
  66. ```
  67. 然后直接对 AI 说:**「帮我把这个视频做成课堂笔记:https://www.bilibili.com/video/BVxxxx」**。详细安装与可选配置见下文。
  68. ## 📦 安装
  69. 本 skill 遵循 **Agent Skills 规范**(`SKILL.md`),任何支持该规范的 AI Agent 均可安装。
  70. 支持的安装路径:
  71. - `~/.claude/skills/` —— Claude Code
  72. - `~/.zcode/skills/` —— ZCode
  73. - `~/.agents/skills/` —— DSH、Codex 等多种 Agent 共用的通用 skills 路径
  74. 其他兼容 Agent 放入其各自的 skills 目录即可。
  75. > 🧩 **DeepSeek Harness(DSH)用户**:推荐安装插件版 [dsh-video-notes](https://github.com/lucky-Luor/dsh-video-notes),一条命令装好,随插件升级:
  76. > `npx -y @deepseek-ai/dsh plugin --profile web add github:lucky-Luor/dsh-video-notes`
  77. ```bash
  78. # 1. 克隆到你的 agent 的 skills 目录(以 ZCode 为例)
  79. git clone https://github.com/lucky-Luor/bilibili-douyin-notes.git ~/.zcode/skills/bilibili-douyin-notes
  80. # 2. 安装 Python 依赖(按需:各平台流程所需依赖见 requirements.txt 内注释)
  81. pip install -r requirements.txt
  82. # (可选)只装测试依赖:tests/ 离线可跑,无需 faster-whisper / av / gmssl(numpy / pillow 仍需安装)
  83. pip install -r requirements-dev.txt
  84. # 3. (可选)扫码登录B站,自动获取 AI 字幕
  85. python scripts/bili_fetch.py --login # 生成二维码 PNG 图片并打印路径,B站 App 扫码即登录,SESSDATA 自动写入 config.json
  86. # 无 B站App:cp config.example.json config.json 后按文件内注释手动填写
  87. ```
  88. ```bash
  89. # 4. 环境自检:逐项给出 ✅ / ⚠️ / ❌ 和修复命令(--platform douyin 只查抖音相关项,--json 供智能体解析)
  90. python scripts/doctor.py
  91. ```
  92. > **路径说明**:`SKILL.md` 中示例命令的 `<skill安装目录>` 为占位符,使用时请替换为
  93. > 本 skill 的实际安装路径(脚本内部均基于 `__file__` 相对定位,改路径不影响运行)。
  94. <details>
  95. <summary>最小依赖说明</summary>
  96. | 组件 | 用途 | 是否必需 |
  97. |---|---|---|
  98. | `faster-whisper` | 语音识别兜底 | 做无字幕视频笔记时必需 |
  99. | `av`(PyAV) | 音频解码 / 视频抽帧 | 同上(faster-whisper 依赖链会带上) |
  100. | `gmssl` | 抖音 a_bogus 签名(SM3) | 仅抖音链接需要 |
  101. | `yt-dlp` / `youtube-transcript-api` | YouTube 元数据、字幕与音频(建议另装 deno) | 仅 YouTube 链接需要 |
  102. | `numpy` / `pillow` | 截图画质初筛(像素占比法 QC) | 仅截图流程需要 |
  103. </details>
  104. ### 在 Claude Code 里接国产模型
  105. Claude 官方服务不支持中国大陆。可以让 Claude Code 改用国产模型,本 skill 不需要任何改动。三家都提供 Anthropic 兼容接口,只要设置两个环境变量,把 Key 填进 `ANTHROPIC_AUTH_TOKEN`(不要同时设置 `ANTHROPIC_API_KEY`):
  106. | 模型 | `ANTHROPIC_BASE_URL` | 官方文档(模型名以文档为准) |
  107. |---|---|---|
  108. | DeepSeek | `https://api.deepseek.com/anthropic` | [DeepSeek:Integrate with Claude Code](https://api-docs.deepseek.com/quick_start/agent_integrations/claude_code/) |
  109. | Kimi | `https://api.moonshot.cn/anthropic` | [在 Claude Code 中使用 Kimi](https://platform.kimi.com/docs/guide/claude-code-kimi) |
  110. | 智谱 GLM | `https://open.bigmodel.cn/api/anthropic` | [智谱:Claude API 兼容](https://docs.bigmodel.cn/cn/guide/develop/claude/introduction) |
  111. ```bash
  112. # 以 DeepSeek 为例(Windows PowerShell 把 export 换成 $env:NAME="值")
  113. export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
  114. export ANTHROPIC_AUTH_TOKEN=<你的 DeepSeek API Key>
  115. claude
  116. ```
  117. 各家的模型名更新很快,`ANTHROPIC_MODEL` 等变量请按上面的官方文档填写。笔记质量取决于所接的模型,质量门禁 `validate_note.py` 会兜住格式下限。
  118. ## ⚙️ 配置
  119. 复制 `config.example.json` 为同目录 `config.json`:
  120. ```jsonc
  121. {
  122. "SESSDATA": "" // B站登录 cookie;留空也能用(官方CC字幕+ASR兜底均可)
  123. }
  124. ```
  125. 获取方式(推荐):`python scripts/bili_fetch.py --login`,生成二维码 PNG 图片并打印路径,B站 App 扫码即登录,
  126. SESSDATA 自动写入 config.json;二维码过期自动换新。手动路径:浏览器登录 bilibili.com →
  127. F12 → Application → Cookies → 复制 `SESSDATA`。该文件已被 `.gitignore` 排除,不会被提交
  128. (含登录凭据,请勿分享)。抖音、小红书流程无需任何配置;YouTube 被风控时可配 `youtube_proxy`,小红书可选配 `xhs_cookie`。
  129. ### 转写性能(可选配置)
  130. CPU 转写慢时可在 config.json 调整:`asr_model`(tiny~large-v3,高阶加载失败自动降一档)、
  131. `asr_device`(auto/cpu/cuda,cuda 失败自动回退 cpu)、`asr_cpu_threads`(0=自动)。
  132. 每次降级都会打印原因,不静默。整理完成后可让 AI 询问你是否清理缓存的媒体文件
  133. (`scripts/clean_media.py`,默认只列清单、`--apply` 实删)。
  134. ### 笔记模板与语言
  135. `config.note_template` 指定默认模板(`v4` / `v4-obsidian`),课程也可在 `start --template` 显式选择。v4 保持无 frontmatter 的语雀直导格式;v4-obsidian 增加元信息,并用 `+ [[#精确正文标题]]` 生成目录,其它正文、概念卡、自测题和时间索引规则相同。完整规范见 [笔记模板](references/note-template.md)。
  136. 正文采用讲解体,开头引语块写明本讲目标,知识地图后附“本讲小结”,自测题答案按“结论 → 原因 → 例子”写成一段。这些新写法由门禁给出 warning 提示;原有 error 规则不变,旧笔记不会因此无法通过。为兼容语雀导入,知识地图子图写成 `subgraph 分组名`(不带编号和方括号),纯文本代码块的语言标注用 `plain`(不用 `text`)。
  137. B站标题明显是英文原声课(如 Lecture / MIT / Stanford / CS61A),又没有“中字 / 中英 / 配音”等提示时,Agent 会先问是否按英文转写。YouTube 默认选择原语言人工字幕 → 中文人工字幕 → 原语言自动字幕 → 原有兜底,显式 `--lang` 可覆盖默认语言优先级。结合 `audio_lang` / `subtitle_lang` 判断课程语言;英文课正文首次出现术语写 **中文(Original)**,中文概念卡加 `+ 原文:Original`,原本中文课程或纯外文专名卡名免加原文行。
  138. ## 🚀 使用
  139. 安装后直接对 AI 说:
  140. > 帮我把这个视频做成课堂笔记:https://www.bilibili.com/video/BVxxxx
  141. >
  142. > 总结一下这个抖音视频:https://v.douyin.com/xxxx/
  143. >
  144. > 把这个 YouTube 视频整理成笔记:https://www.youtube.com/watch?v=xxxx
  145. >
  146. > 这个小红书视频做个笔记:<App 里「分享 → 复制链接」得到的整段文本>
  147. 整门课先规划,Agent 原样展示确认文案,等你选择后再开工。以下示例只确认前 3 集,`next` 输出本集要执行的步骤:
  148. ```bash
  149. python scripts/course_plan.py plan "<B站链接>" "<课程目录>"
  150. python scripts/course_plan.py start "<课程目录>" --first 3 --template v4 --asr-lang zh
  151. python scripts/course_plan.py next "<课程目录>"
  152. ```
  153. 若选择 Obsidian 与英文原声,在 `start` 改用 `--template v4-obsidian --asr-lang en`;自动检测转写语言用 `--asr-lang auto`。模板未显式指定时取 `config.note_template`。
  154. 每集按 `next` 返回的 `note.template`、`note_path` 和命令制作笔记;`existing_note:true` 时在原文件修正,除文件缺失外不整篇重写。转写退出码非 0 或 JSON `status:error` 都算失败。写完笔记、填深链并通过门禁后,由 Agent 调用 `mark … done --note …`,该命令还会执行进程内门禁,拒绝时按报告修正。仍失败则 `mark … failed --reason … --next-step …` 后继续下一集。
  155. 续跑 `next` 会先复查已 done 的笔记;笔记 SHA 与模板未变时复用缓存、跳过检查,改坏或缺失则退回 pending、保留 `planned_note` 供修复,不会自动把草稿标成 done。`verify` 可手动复查,与 `next` 共享 SHA 缓存,不能当作强制全量检查;`index` 刷新课程索引;`status` 只读查询。`mark … pending` 可安排失败集补跑。
  156. ```bash
  157. # 手动复查、刷新索引、只读查看进度
  158. python scripts/course_plan.py verify "<课程目录>"
  159. python scripts/course_plan.py index "<课程目录>"
  160. python scripts/course_plan.py status "<课程目录>"
  161. ```
  162. `next` 返回 `status:finished` 时,Agent 原样转述 `receipt_text` 完成回执(包含课程索引、概念表、课程自测与失败集补跑信息)。只有 `cache.bytes > 0` 才询问是否清理缓存,用户同意后执行 `python scripts/course_plan.py clean "<课程目录>" --apply`;为 0 时不询问。
  163. 多分P默认只做当前视频;展开合集用 `--scope season`。超过 200 集或 100 小时的清单只允许选择范围,详见 [SKILL.md](SKILL.md)“整门课模式”。
  164. ### 课程复习
  165. 课程模型与 CLI 已在本地实现可用。已有课程至少完成一集后,在项目根目录执行;复习不新增依赖,只读取原笔记,兼容已有 `course.json`。
  166. 当前完整离线测试与 UTF-8 模式均为 869 项通过;I5 验收时为 854 项通过、5 项跳过。15 集程序验收通过。40 篇离线性能用例耗时约 0.09 秒;40 集未实测,按用户决定以 15 集验收。详细结果与待完成项目见 [I5 验收记录](docs/verification/I5-概念表.md)。
  167. ```bash
  168. python scripts/course_plan.py concepts "<课程目录>" # 生成或刷新概念表.md、课程自测.md
  169. python scripts/course_plan.py concepts "<课程目录>" --unmastered # 只读列出没掌握的概念与对应题目
  170. python scripts/course_plan.py concepts "<课程目录>" --master "机会成本" # 标记已掌握并刷新,可重复传入名称
  171. python scripts/course_plan.py concepts "<课程目录>" --unmaster "机会成本" # 取消掌握标记并刷新
  172. python scripts/course_plan.py concepts "<课程目录>" --check # 只检查、不写文件,有错误时退出码为1
  173. ```
  174. `--check`、`--unmastered`、`--master/--unmaster` 三组互斥。汇总包含所有已完成且有笔记路径的集,不受当前所选范围限制。课程索引和完成回执提供两个复习文件的入口;`mark`、`verify`、`next` 结束及 `index` 会顺带刷新,失败时返回 `review_warning`。
  175. 在 `概念表.md` 把 `+ [ ]` 改为 `+ [x]` 即标记已掌握,重新生成保留勾选,`course.json` 保存备份;文件读不出时拒绝覆盖。`课程自测.md` 答案不折叠,手动自测先遮住答案;至少勾选一个概念并刷新后,没掌握的题会单列在最前,全部题目仍保留。
  176. 对 Agent 说“考考我这门课”或“我哪些没掌握”,上下文中给出课程目录即可,无需视频URL。Agent 先用 `--unmastered`,一次只出一道已有题,先不泄露答案;答后对照原答案说明对错,附回看和笔记链接,无时间点时只给笔记。答对或说“这个我会了”后,仍须征得同意才标记掌握。详见 [复习版内测说明](docs/dev/复习版内测.md)。
  177. 也可以直接手动调用脚本(详见 [SKILL.md](SKILL.md) 的工作流程章节):
  178. ```bash
  179. # 先探元数据:不抓字幕、不写文件(确认视频可访问/时长/分P数)
  180. python scripts/bili_fetch.py --probe "<视频链接>"
  181. # B站:抓取元数据与字幕
  182. python scripts/bili_fetch.py "<视频链接>" "<输出目录>"
  183. # 抖音:抓取元数据并下载视频供本地转写(免登录)
  184. python scripts/douyin_fetch.py "<链接或分享口令>" "<输出目录>"
  185. # YouTube:抓取元数据与字幕(无字幕时加 --download 下载音频)
  186. python scripts/yt_fetch.py "<视频链接>" "<输出目录>"
  187. # 小红书:抓取元数据并下载视频(免登录,链接需带 xsec_token)
  188. python scripts/xhs_fetch.py "<分享链接或分享文本>" "<输出目录>"
  189. # 无字幕时:本地语音识别
  190. python scripts/bili_transcribe.py "<输出目录>/metadata.json"
  191. # ASR 术语校正:先 dry-run 看报告,确认后 --apply(自动留 .bak)
  192. python scripts/apply_glossary.py "<输出目录>/01_分P名.txt"
  193. # (可选,带截图时)写完正文后按小节写 shots.json,再按清单抽帧(需 ASCII 文件名时加 --ascii-names)
  194. python scripts/bili_screenshot.py "<输出目录>/metadata.json" "<输出目录>" "<输出目录>/images" --shots "<输出目录>/shots.json"
  195. # 时间索引深链填充(v4 笔记默认执行,short 跳过;brief 有索引才填)
  196. python scripts/note_nav.py "<笔记.md>" --template v4 --meta "<输出目录>/metadata.json" --txt-dir "<输出目录>"
  197. # 生成笔记后的质量门禁(errors 为 0 才交付)
  198. python scripts/validate_note.py "<笔记.md>" --template v4 --meta "<输出目录>/metadata.json" --txt-dir "<输出目录>"
  199. # 单视频 Obsidian 变体:深链和门禁必须使用同一模板
  200. python scripts/note_nav.py "<笔记.md>" --template v4-obsidian --meta "<输出目录>/metadata.json" --txt-dir "<输出目录>"
  201. python scripts/validate_note.py "<笔记.md>" --template v4-obsidian --meta "<输出目录>/metadata.json" --txt-dir "<输出目录>"
  202. # (可选,带截图时)截图上传阿里云 OSS 并改写为 OSS 链接,便于导入语雀(默认预演,--apply 实际执行)
  203. python scripts/upload_images.py "<笔记.md>" --apply
  204. ```
  205. ## 📁 目录结构
  206. ```
  207. ├── SKILL.md # Agent Skills 规范定义:触发条件、工作流程(含整门课与复习模式)、笔记模板
  208. ├── scripts/
  209. │ ├── doctor.py # 环境自检:依赖 / 模型 / 设备 / 编码 / 加密软件 / 网络风控
  210. │ ├── course_plan.py # 整门课规划、续跑复查、课程索引、回执与询问式清理
  211. │ ├── course_review.py # 课程概念表与课程自测:跨集解析、合并与检查
  212. │ ├── bili_fetch.py # B站:元数据 + 字幕抓取(--probe 只探元数据)
  213. │ ├── douyin_fetch.py # 抖音:元数据 + 视频下载供转写(游客身份)
  214. │ ├── yt_fetch.py # YouTube:元数据 + 字幕三级回退(无字幕按需下载音频)
  215. │ ├── xhs_fetch.py # 小红书:视频笔记元数据 + 视频下载(免登录)
  216. │ ├── bili_transcribe.py # faster-whisper 本地 ASR 兜底(多平台兼容)
  217. │ ├── bili_screenshot.py # 重点截图(shots.json 清单 → 候选网格 → 按编号出图 / 关键词兜底 + 去重 + 像素占比法 QC)
  218. │ ├── _frames.py # 截图候选:按画面切段、剔除空画面、挑写完且没被挡住的代表帧
  219. │ ├── upload_images.py # 截图上传阿里云 OSS 并改写笔记链接(导入语雀用)
  220. │ ├── transcript_chunk.py# 长转写稿分块(map-reduce 前置)
  221. │ ├── apply_glossary.py # ASR 术语校正(dry-run 报告 / --apply 落盘)
  222. │ ├── note_nav.py # 时间索引深链填充
  223. │ ├── clean_media.py # 询问式媒体清理(默认只列清单、--apply 实删)
  224. │ ├── validate_note.py # 笔记质量门禁(errors 为 0 才交付)
  225. │ ├── smoke_local.py # 本机定时冒烟:拉最新代码、跑真实链接探针、存报告
  226. │ ├── smoke_probe.py # 真实链接冒烟探针(只取元数据和字幕,不下载视频)
  227. │ ├── asr_bench.py # 语音识别基准:对比模型 / 线程数 / 批大小的耗时与一致度
  228. │ ├── _hints.py # 统一失败提示:原因 / 影响 / 下一步
  229. │ ├── _net.py # 公共 HTTP 请求:只重试网络类错误,4xx 直接提示
  230. │ ├── _pyav_compat.py # faster-whisper 与新版 PyAV 的兼容层
  231. │ ├── ensure_abogus.py # abogus.py 缺失时从上游固定 commit 下载(SHA-256 校验)
  232. │ └── abogus.py # 抖音 a_bogus 签名算法(GPLv3,按需下载,不入仓库)
  233. ├── tests/ # 离线 pytest 测试(不联网、无需重依赖)
  234. ├── examples/ # 单篇样例与可汗微观经济学前15集节选
  235. ├── docs/
  236. │ ├── images/ # README 配图
  237. │ ├── dev/ # 开发文档:冒烟、错误分支清单、复习版内测说明
  238. │ └── verification/ # 各迭代验收记录
  239. ├── references/
  240. │ ├── anchors.json # 截图关键词锚点表(按视频 ID 隔离,仅在不用 --shots 清单时兜底)
  241. │ ├── asr-glossary.json # ASR 技术术语校正表
  242. │ ├── glossary-user.example.json # 用户层词表示例
  243. │ ├── smoke_urls.json # 冒烟测试链接清单
  244. │ └── note-template.md # 课堂笔记模板(v4 / v4-obsidian 规范)
  245. ├── config.example.json # 配置模板(SESSDATA)
  246. └── LICENSE # MIT
  247. ```
  248. [可汗微观经济学前15集节选](examples/可汗微观经济学-前15集/课程索引.md)按“课程目录 → 课程索引 + 逐集笔记”组织,包含15篇中文笔记,覆盖原课前1小时59分1秒;[来源与许可说明](examples/可汗微观经济学-前15集/README.md)单独列出。复习入口:[概念表](examples/可汗微观经济学-前15集/概念表.md)(跨集概念、掌握勾选与回看)和 [课程自测](examples/可汗微观经济学-前15集/课程自测.md)(已有题目、答案与回看)。用户将本次范围缩减为前15集,因此这是课程节选,不是71集整课样例;[I4验收记录](docs/verification/I4-课程版.md)列出了已验证结果及尚未完成的界面抽查。
  249. ## ❓ 常见问题
  250. <details>
  251. <summary><b>PowerShell 5.1 显示 NativeCommandError,是脚本失败了吗?</b></summary>
  252. 不一定。PowerShell 5.1 可能把原生命令正常写到 stderr 的进度或警告显示为 `NativeCommandError`。请结合进程退出码(命令结束后立即查看 `$LASTEXITCODE`)和 stdout 最后一行 JSON 判断;退出码非 0 或 JSON `status:error` 都应按失败处理,不能仅凭 stderr 的红字判断。
  253. </details>
  254. <details>
  255. <summary><b>需要什么环境?</b></summary>
  256. Python 3.10+,以及任意一个支持 Agent Skills(`SKILL.md`)规范的 AI Agent,如 Claude Code、Codex、ZCode。不需要 GPU,也不需要任何付费 API。不确定装没装好,运行 `python scripts/doctor.py` 自检。
  257. </details>
  258. <details>
  259. <summary><b>脚本报编码错误 / 生成的笔记打开是乱码?</b></summary>
  260. 如果电脑装了文件加密(防泄密)软件,用资源管理器、PowerShell 甚至 `git clone` 写出的 `.md`、`.txt` 文件都可能被加密(实测 `.py`、`.json` 不受影响),Python 和 pip 读出来就是乱码。`doctor.py` 会检查出这种情况。
  261. - **根本解决**:请 IT 把 `python.exe` 和你的 AI Agent 加入加密软件白名单;重新 `git clone` 不一定有用
  262. - **`pip install -r requirements.txt` 报 `UnicodeDecodeError`**:说明 `requirements.txt` 被加密了,改用直接列出包名的命令:
  263. ```bash
  264. pip install faster-whisper ctranslate2 av numpy pillow qrcode gmssl "yt-dlp>=2026.8.19" "youtube-transcript-api>=1.2.0" oss2
  265. ```
  266. </details>
  267. <details>
  268. <summary><b>一定要登录 B站吗?</b></summary>
  269. 不用。不登录也能抓官方 CC 字幕,没有字幕时自动走本地语音识别。扫码登录(`python scripts/bili_fetch.py --login`)后可以拿到 B站 AI 字幕,多数视频能跳过语音识别,速度快很多。抖音、小红书完全不需要登录;YouTube 一般也不需要,遇到风控时再配 cookies / 代理。
  270. </details>
  271. <details>
  272. <summary><b>语音识别太慢怎么办?</b></summary>
  273. 默认的 `small` 模型在 6 核笔记本 CPU 上实测约为视频时长的 0.2 倍(26 分钟的课约 4 分钟)。赶时间可以在 `config.json` 里把 `asr_model` 设为 `base`,速度约快 3 倍,但识别质量明显下降(实测和 `small` 的文字一致度只有 0.72~0.79),术语错得更多;有 NVIDIA 显卡时设置 `asr_device: "cuda"`。也可以先只转写一个分P(`--page 1`)估算耗时。
  274. </details>
  275. <details>
  276. <summary><b>术语识别错了(比如 IoC 被识别成别的词)?</b></summary>
  277. 用 `scripts/apply_glossary.py` 做术语校正:先 dry-run 看报告,确认后 `--apply`。发现新的错法可以用 `--add "错法=正确词"` 补进词表,越用越准。
  278. </details>
  279. <details>
  280. <summary><b>抖音链接报 403?</b></summary>
  281. 通常是平台更新了签名算法,参见下方「已知限制」里关于 `abogus.py` 的说明,或提一个 [Issue](https://github.com/lucky-Luor/bilibili-douyin-notes/issues) 告诉我。
  282. </details>
  283. <details>
  284. <summary><b>YouTube 提示 "Sign in to confirm you're not a bot"?</b></summary>
  285. YouTube 会拦截部分服务器 IP。给 `yt_fetch.py` 加 `--cookies-from-browser chrome`(或 `--cookies cookies.txt`),必要时加 `--proxy`;并保持 `yt-dlp` 为最新版、安装 deno。
  286. </details>
  287. <details>
  288. <summary><b>小红书链接打不开 / 提示 xsec_token?</b></summary>
  289. 小红书必须用带 `xsec_token` 的完整分享链接(App 里「分享 → 复制链接」),只有笔记 ID 不行;token 有时效,过期就重新复制一次。只支持视频笔记,图文笔记会直接提示。
  290. </details>
  291. <details>
  292. <summary><b>生成的笔记长什么样?</b></summary>
  293. 看 [examples/](examples/) 目录里的完整示例,包含小节要点、对比表格、知识地图、概念卡片、自测题和可跳转的视频时间索引。
  294. </details>
  295. ## 📜 使用声明与数据去向
  296. - **仅限个人学习**:本工具用于把公开课程整理成自己的学习笔记。请勿用于搬运、传播、二次分发或任何商业用途;使用时请遵守各平台的用户协议,尊重创作者的版权。
  297. - **只处理公开内容**:不支持、也不打算支持付费内容、大会员内容和私有收藏夹;B站 SESSDATA 只是抓字幕的可选兜底,不登录也能用。
  298. - **数据去向**:
  299. - 抓取、语音识别、截图都在你自己的电脑上完成;本项目不收集任何使用数据,也不会把视频、字幕或笔记上传到本项目的服务器(本项目没有服务器)。
  300. - 下载的视频 / 音频只用于本地语音识别和截图,笔记完成后可用 `clean_media.py` 清理(智能体会先问你)。
  301. - 截图默认只保存在本地;只有你自己配置了 OSS 并执行 `upload_images.py --apply`,才会上传到**你自己的**存储桶。
  302. - 笔记由你自己的 AI 智能体生成,字幕和转写文本会按该智能体的规则发给它所接入的模型服务。
  303. - **平台通知**:如收到平台方的通知或异议,维护者会在 48 小时内下线相关模块,并在本 README 说明。
  304. ## 🛡️ 平台支持等级
  305. 一个人维护四个平台,资源先保证 B站。
  306. | 等级 | 平台 | 承诺 |
  307. |---|---|---|
  308. | 一级 | B站 | 平台改版导致失效后 **7 天内修复**;每周两次真实链接冒烟测试,发版前必跑 |
  309. | 二级 | YouTube、抖音、小红书 | **尽力维护**:失效会在 issue 里确认和跟进,但不承诺修复时间;抖音签名、小红书页面结构都由平台控制,可能临时不可用 |
  310. 失效时脚本会输出“原因 / 影响 / 下一步”三段提示,并告诉你是链接本身的问题(换链接即可)还是平台变化(需要等修复)。遇到失效请提 issue,附上链接和这段提示。
  311. ## ⚠️ 已知限制
  312. - 无字幕视频需要本地语音识别:CPU int8 实测约为视频时长的 0.2 倍(6 核笔记本 CPU;更老的 CPU 会慢一些),有 NVIDIA GPU 时更快
  313. - ASR 转写的技术术语可能出错(如 IoC、Starter),生成笔记时建议结合上下文或代码仓库校正
  314. - 抖音依赖平台签名算法,平台升级时可能临时失效(表现为 detail 接口 403),需跟进上游项目更新签名实现
  315. - 抖音签名的 `abogus.py` 依赖上游仓库(BiliNote)托管:下载 URL 已固定到上游具体 commit 并做 SHA-256 校验;上游更新签名算法时,可用环境变量 `BILINOTE_ABOGUS_SHA=<新commit>` 临时指向新 revision,或按 `scripts/ensure_abogus.py` 文件头的手动安装步骤放置文件
  316. - YouTube 可能拦截服务器 / 云主机 IP,需要 cookies 或代理;`yt-dlp` 需随 YouTube 变化及时升级
  317. - 小红书依赖分享页内嵌数据结构,平台改版时可能临时失效;频繁请求会触发验证码(461/471),仅支持视频笔记
  318. - 仅支持公开可访问的视频
  319. ## 📄 许可证
  320. 本仓库主体采用 [MIT](LICENSE) 协议开源。
  321. **例外:`scripts/abogus.py` 不在本仓库中。** 本仓库不包含、也不分发该 GPLv3 组件;
  322. 由使用者在自己的机器上按需获取,按其自身条款使用。该文件是抖音 a_bogus 签名算法
  323. 代码,源自 [TikTokDownloader](https://github.com/JoeanAmier/TikTokDownloader)
  324. (经 [Evil0ctal/Douyin_TikTok_Download_API](https://github.com/Evil0ctal/Douyin_TikTok_Download_API)
  325. 与 [BiliNote](https://github.com/JefferyHcool/BiliNote) 移植)。`scripts/ensure_abogus.py`
  326. 在**首次使用抖音功能时**从上游仓库的**固定 commit** 下载到本地,下载内容必须通过
  327. SHA-256 校验与关键字校验(ghproxy 镜像仅作为传输通道,同样必须过校验);
  328. 也可设置环境变量 `BILINOTE_ABOGUS_SHA` 指向其他 revision(详见 `scripts/ensure_abogus.py`
  329. 文件头说明)。下载后的该文件遵循其自身的 **GPLv3** 条款(上游文件头的 GPLv3/Apache-2.0
  330. 声明自相矛盾,本项目按更严格的 GPLv3 处理)。
  331. > 手动安装(网络受限时):从 BiliNote 仓库的
  332. > `backend/app/downloaders/douyin_helper/abogus.py`
  333. > 下载文件,放到本 skill 的 `scripts/abogus.py` 即可。
  334. ## 🙏 致谢
  335. - [JoeanAmier/TikTokDownloader](https://github.com/JoeanAmier/TikTokDownloader) —— `abogus.py` 原始作者
  336. - [Evil0ctal/Douyin_TikTok_Download_API](https://github.com/Evil0ctal/Douyin_TikTok_Download_API) —— 抖音 Web API 签名与 x-secsdk-web-signature 方案参考
  337. - [JefferyHcool/BiliNote](https://github.com/JefferyHcool/BiliNote) —— 多平台下载器架构、YouTube 字幕优先策略参考
  338. - [jdepoix/youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api) / [yt-dlp](https://github.com/yt-dlp/yt-dlp) —— YouTube 字幕与音频获取
  339. - [ReaJason/xhs](https://github.com/ReaJason/xhs) —— 小红书笔记页内嵌数据解析思路(MIT)
  340. - [JoeanAmier/XHS-Downloader](https://github.com/JoeanAmier/XHS-Downloader) —— 小红书视频地址选择思路参考(仅参考思路,未使用其代码)
  341. - [faster-whisper](https://github.com/SYSTRAN/faster-whisper) —— 本地语音识别引擎
  342. <div align="center">
  343. **如果这个 skill 帮你省下了记笔记的时间,欢迎点个 ⭐ Star 支持一下!**
  344. 用它生成了满意的笔记?欢迎在 [Issues](https://github.com/lucky-Luor/bilibili-douyin-notes/issues) 晒出来,遇到问题或有新想法也欢迎反馈 🙌
  345. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.