| name | bilibili-douyin-notes |
|---|---|
| description | 把B站/抖音/YouTube/小红书视频整理成Markdown课堂笔记,并支持已有课程复习。用户发来视频链接或分享口令要求做笔记、总结、转文字,或针对已有课程说“考考我 / 复习这门课 / 我哪些没掌握”时使用;复习不需要视频URL。产出经质量门禁校验的课堂笔记,或基于已有笔记逐题自测、回看与经用户同意的掌握标记。 |
B站/抖音/YouTube/小红书视频 → Markdown 课堂笔记
触发条件
- 做笔记:用户消息中包含 bilibili.com / b23.tv / BV号 / douyin.com / v.douyin.com / iesdouyin.com / youtube.com / youtu.be(含 /shorts/、/live/)/ xiaohongshu.com / xhslink.com 链接(或抖音、小红书分享口令文本),且要求总结、做笔记、整理复习资料、提取视频内容等。
- 复习已有课程:用户说“考考我 / 复习这门课 / 我哪些没掌握”等,直接进入“复习模式”,不以视频URL为必要条件。课程目录从上下文确定;无法确定时只问目录。
平台分流(制作新笔记时先看链接属于哪个平台)
- B站 →
bili_fetch.py:走官方API,优先字幕,按需下载音频/视频流 - 抖音 →
douyin_fetch.py:游客身份(无需登录/SESSDATA),下载视频到本地供语音识别(只用于本地转写,用完可清理),一般无字幕 → 必走第二步ASR(抖音视频短,耗时可忽略)。需要pip install gmssl;abogus.py为 GPLv3 代码(源自 Evil0ctal/Douyin_TikTok_Download_API 经 BiliNote 移植),分发需保留其许可头 - YouTube →
yt_fetch.py:默认优先原语言人工字幕 → 中文人工字幕 → 原语言自动字幕 → 原有兜底(yt-dlp json3 字幕 → 无字幕交 ASR);显式--lang覆盖默认语言优先级。有字幕时不下载任何媒体;需要pip install yt-dlp youtube-transcript-api,并建议安装 deno(yt-dlp 解 YouTube JS 挑战所需) - 小红书 →
xhs_fetch.py:免登录、无签名,手机 UA 请求分享页并解析内嵌__INITIAL_STATE__,下载视频到本地(默认 h264 转码流,--origin下载体积大得多的原片);只支持视频笔记,图文笔记脚本直接提示退出;链接必须带xsec_token(让用户从 App「分享 → 复制链接」整段发来);一般无字幕 → 必走第二步 ASR - 四个平台的 metadata.json 字段一致,第二/三步脚本自动兼容:B站分P按
bvid/cid按需下载,抖音分P带media_path直接用本地视频文件
工具位置
- 脚本目录:本 skill 安装目录下的
scripts/(命令中的<skill安装目录>占位符请替换为本 skill 实际安装路径) - 配置文件:本 skill 安装目录下的
config.json(存放 SESSDATA;截图上传语雀用的 OSS 配置写在oss字段) - 参考资产:
references/note-template.md—— 课堂笔记模板 v4 / v4-obsidian(语雀 / Obsidian 版式、骨架、语法契约、时间戳规范)references/asr-glossary.json—— ASR 术语纠错词表(真实错法→正确写法)references/anchors.json—— 截图关键词锚点表(按视频 ID 隔离;仅在不用--shots清单时兜底)
工作流程
第零步:环境自检(每个会话第一次处理视频前跑一次)
python "<skill安装目录>/scripts/doctor.py" --platform <本次链接的平台> --json
- 平台取
bilibili/douyin/youtube/xiaohongshu;退出码 1 表示有 FAIL - 有
FAIL:先把对应的fix原样告诉用户并停下,修好再开工;不要跳过自检硬跑 - 只有
WARN:可以开工,开工前用一句话说明影响(如“没有显卡,这个无字幕视频大约要 X 分钟”“YouTube 连不上,需要代理”) skill 文件为 FAIL(被加密软件处理过)时,提示用户用git clone重新安装,不要尝试自己修文件
整门课模式(B站,先于第一步判断)
用户发来 B站链接或 BV号,环境自检通过后,先建立课程清单:
python "<skill安装目录>/scripts/course_plan.py" plan "<链接>" "<课程目录>"
- 读取 stdout 最后一行 JSON;
course:false表示单P无合集,继续下面的原单视频流程。course:true时,把confirm_text原样发给用户,并转述hint_optional;用户没有回复,不能调用start或开始抓取、转写、写笔记。 - 用户选好范围后调用
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。例如:# 语雀版式,中文转写 python "<skill安装目录>/scripts/course_plan.py" start "<课程目录>" --first 3 --template v4 --asr-lang zh # Obsidian 版式,英文转写;需要自动检测时将 en 改为 auto python "<skill安装目录>/scripts/course_plan.py" start "<课程目录>" --first 3 --template v4-obsidian --asr-lang en
- 串行循环
next "<课程目录>"。status:next的steps给出 fetch / transcribe / note 步骤;skip:true不执行。优先按argv参数数组执行,避免含空格路径或特殊字符经过 shell 二次解释;cmd是展示用命令。 - fetch 后重新检查本集的
subtitle_detail和正式文本:cc/ai且正式文本存在可跳过转写;其它无字幕状态走单集 ASR。ai_mismatch的存疑文本不可用于笔记。读取转写逐集 JSON,进程退出码非 0 或 JSONstatus:error都算失败;nothing_to_do时也必须确认目标页及正式文本存在,不能直接视为成功。需要恢复元数据时按三段提示处理。 - 每集按第三步的全部规则独立制作笔记,模板以
next返回的note.template(v4/v4-obsidian)为准,使用note_path。existing_note:true时在原文件上修正;除文件缺失外,不要整篇重写。只读这一集的正式转写稿,不要把前面各集的全文持续留在上下文。英文课正文首次出现的术语写作 中文(Original),概念卡用中文卡名并加+ 原文:Original;原本中文课程、或卡名本身是纯外文专名时免加原文行。截图仅用户明确要求时执行。按nav_cmd填深链,再按validate_cmd做最终门禁,确认 errors 为 0;两个命令都带本集--page N和选定模板。 - 成功后
mark "<课程目录>" <序号> done --note "<笔记路径>";mark done还会执行进程内门禁,拒绝时按报告修正后重试,不能凭先前校验结果强记 done。一集任何步骤失败(含门禁修正后仍失败),用该步的“原因 / 下一步”调用mark "<课程目录>" <序号> failed --reason "<原因>" --next-step "<下一步>",继续下一集,不停下来反复询问用户。课程批处理不强制扫码登录,可将可选登录建议留给用户;失败集可稍后补跑。 - 每次
mark把摘要的progress原样转告用户。next返回status:finished时,把receipt_text原样转述,保留其中的完成数、失败集、课程索引、概念表、课程自测和补跑信息,不自行编造回执。仅当cache.bytes > 0时询问是否清理缓存;用户同意后才执行python "<skill安装目录>/scripts/course_plan.py" clean "<课程目录>" --apply,cache.bytes = 0时不询问。 - 中途被打断时再次
next会先复查已 done 的集,再交出待处理集(含原来的 running 集)。笔记 SHA 与模板未变化时复用缓存、跳过检查;笔记改坏或缺失时退回 pending,保留planned_note供原位修复。已有草稿不会自动成为 done。需要手动复查时用verify "<课程目录>",它与next共享 SHA 校验缓存,并非强制全量检查;index "<课程目录>"刷新课程索引,status "<课程目录>"只读查询、不触发复查。mark "<课程目录>" <序号> pending可把失败集放回待处理,再调用next。plan刷新同源同模式清单会保留结果;切换模式用start --scope。不要把转写.done与课程笔记的 done 状态混为一谈。
课程目录中的 course.json 是课程进度的唯一状态来源;videos/<BV号>/ 复用单视频抓取产物,同 BV 只抓取一次,notes/ 每集一篇。默认最多探测 60 集字幕、间隔 0.3 秒;plan --probe-all 全探,--no-probe 跳过,未探测或失败按需要 ASR 保守估算。预估按六核笔记本 CPU,ASR 初值为视频时长的 0.2 倍;笔记整理初值按 I4 前15集样本的差值中位数校准为每集60秒(不含ASR,长课与不同机器可能偏离)。后续剩余时间使用已完成集的有效平均耗时修正。
复习模式(已有课程,无需视频URL)
课程复习命令与使用方法见下文;验证结果和待完成项目见 I5 验收记录。
复习只读已有单集笔记,不重新抓取、转写或修改原笔记,不新增依赖。课程进度仍以 course.json 为准;掌握状态以 概念表.md 的勾选为入口,course.json.mastery 只作备份。
- 确定含
course.json的课程目录,运行下面的--unmastered,读取返回 JSON 的概念与已有题目。用户只问“哪些没掌握”时只列概念名;要求自测时一次只出一道题,先不展示答案、定义或其它会泄题的内容,等用户作答。 - 用户答完后,对照该题已有答案说明对错与遗漏,附该题的回看链接和笔记链接。没有回看深链时给对应笔记链接并说明无时间点,不推测时间或拼造链接。
- 用户答对,或说“这个我会了”,问一句“要标记为已掌握吗?”,同意后才运行
--master;拒绝或未回复则不标记。标记后再继续下一题。用户要求取消掌握时用--unmaster。 - 不一次列出所有答案,不自行出笔记里没有的题或改写参考答案。没有可用题目时如实说明;没有已完成笔记时按提示先完成至少一集。返回
truncated:true表示最多返回了 50 个概念,不能声称已覆盖全部。
python "<skill安装目录>/scripts/course_plan.py" concepts "<课程目录>" --unmastered # 只读获取没掌握的概念与题目,答案仅用于答后核对
python "<skill安装目录>/scripts/course_plan.py" concepts "<课程目录>" # 生成或刷新概念表与课程自测
python "<skill安装目录>/scripts/course_plan.py" concepts "<课程目录>" --master "机会成本" # 用户同意后标记掌握并刷新
python "<skill安装目录>/scripts/course_plan.py" concepts "<课程目录>" --unmaster "机会成本" # 按用户要求取消掌握并刷新
python "<skill安装目录>/scripts/course_plan.py" concepts "<课程目录>" --check # 只检查、不写文件,有错误时退出码为1
--check、--unmastered、--master/--unmaster 三组互斥。生成汇总课程内所有 done 且有笔记路径的条目,不受本次范围限制;只汇总已有概念和题目,不合并改写定义。概念表.md 的 + [ ] 改为 + [x] 即已掌握,重新生成保留勾选;文件读不出时拒绝覆盖,按三段提示处理。
课程自测.md 的答案不折叠,手动自测先遮住答案。至少勾选一个概念并重新生成后,没掌握的题才单列在最前;“全部题目”仍保留所有题。课程索引和完成回执提供两个文件的入口;刷新失败时转述 review_warning,不要把旧文件当作已更新结果。内测用法见 复习版内测。
第一步:抓取元数据 + 字幕(B站 / YouTube)或下载视频(抖音 / 小红书)
B站标题明显指向英文原声课(如 Lecture / MIT / Stanford / CS61A),且没有“中字 / 中英 / 配音”等提示时,先问用户是否按英文转写;确认后再启动转写,课程模式在 start 选择 --asr-lang en(需要自动检测时用 auto)。不要只凭平台或中文字幕推断音频语言。
# B站(也支持 b23.tv 短链)
python "<skill安装目录>/scripts/bili_fetch.py" "<视频链接>" "<工作目录>/bili-notes-<BV号>"
# B站只探元数据:不抓字幕、不建目录、不写任何文件(先确认视频可访问/时长/分P数时用)
python "<skill安装目录>/scripts/bili_fetch.py" --probe "<视频链接>"
# 抖音(也支持 v.douyin.com 短链和整段分享口令文本)
python "<skill安装目录>/scripts/douyin_fetch.py" "<链接或口令>" "<工作目录>/douyin-notes-<视频ID>"
# YouTube(watch / youtu.be / shorts / live / embed 链接或 11 位 ID 均可)
python "<skill安装目录>/scripts/yt_fetch.py" "<视频链接>" "<工作目录>/yt-notes-<视频ID>"
# 可选:--lang zh-Hans,en(字幕语言优先级)--download(无字幕时下载音频供 ASR)
# --cookies <cookies.txt> / --cookies-from-browser chrome(风控/年龄限制)--proxy http://127.0.0.1:7890
# 小红书(xhslink.com 短链 / explore / discovery/item 链接或整段分享文本,必须带 xsec_token)
python "<skill安装目录>/scripts/xhs_fetch.py" "<分享链接或分享文本>" "<工作目录>/xhs-notes-<笔记ID>"
- 两个脚本都自动生成
<输出目录>/metadata.json,stdout 最后一行是 JSON 摘要。 - B站:每个分P的字幕
.txt(带[mm:ss]时间戳),按摘要里每个分P的subtitle_detail字段六值分流(cc / ai / ai_mismatch / none / api_empty / error,其中 cc 与 ai 处置相同):cc/ai→ 已拿到官方/AI字幕,直接进入第三步生成笔记(AI 字幕已由脚本自动做"内容↔标题 ASCII 词"交叉校验,错位时会判为ai_mismatch而不是ai);ai_mismatch→ AI 字幕整体错位(返回了 ai 状态但内容是别的音频,实测有配成无关电影对白的案例):不可信,直接进入第二步 ASR 兜底,不要用该字幕生成笔记;存疑字幕已另存*.ai字幕存疑.txt备查,摘要带hint_mismatch时可向用户提一句;none→ 该分P确实没有字幕,直接进入第二步 ASR,不用再折腾;但若摘要带hint_optional(未配置登录态时可能出现),转述给用户:「若该视频本应有 AI 字幕,可扫码登录(--login)后重跑,通常能跳过语音识别」——由用户判断要不要扫,不强制;api_empty→ 接口没返回可用字幕URL(sessdata_loaded:false时常见,AI字幕需要登录):主动询问用户「要现在扫码登录B站吗?」,确认后代跑python "<skill安装目录>/scripts/bili_fetch.py" --login(脚本生成二维码 PNG 图片并打印路径,把路径给用户打开扫码即登录,SESSDATA 自动写入 config.json)后重跑一次 fetch;用户拒绝或重跑后仍是api_empty才走第二步 ASR 兜底;error→ 查看摘要里的 error 信息(可能是视频失效/风控),重试一次或直接告知用户。
- 抖音:视频已下载到
<输出目录>/media_p01.mp4(仅供本地转写,本地已存在则跳过下载),无字幕,直接进入第二步 ASR。 - YouTube:默认按原语言人工字幕 → 中文人工字幕 → 原语言自动字幕 → 原有兜底选择;显式
--lang覆盖默认语言优先级。结合audio_lang/subtitle_lang判断是否为原语言课程及术语表达,不因选到中文字幕就抹去英文原声课的原文术语。按摘要里分P的subtitle_detail分流:manual/auto/ytdlp_manual/ytdlp_auto→ 已写出01_<标题>.txt([mm:ss]格式,自动字幕已去滚动重复)+.done标记,直接进入第三步;英文原声或英文字幕课程按第三步的中文正文、双语术语与概念卡规则撰写;none→ 无可用字幕:加--download重跑(下载音频到media_p01.m4a),再进入第二步 ASR;blocked→ YouTube 拒绝了当前 IP:先建议用户配--proxy或--cookies-from-browser重跑;仍不行再--download走 ASR;error→ 看 stderr 日志,重试一次或告知用户。- 没有
media_path的 YouTube 分P不能直接跑第二步(脚本不会去 B站接口下载),务必先--download。
- 小红书:视频已下载到
<输出目录>/media_p01.mp4(本地已存在则跳过下载),无字幕,直接进入第二步 ASR;时间索引与抖音一样无深链(保持纯文本)。
第二步(兜底):语音识别转写
仅对缺字幕的分P转写(脚本自动跳过已有文本的分P):
# 只转写第N个分P(推荐先转1个试听质量/估算耗时)
python "<skill安装目录>/scripts/bili_transcribe.py" "<工作目录>/bili-notes-<BV号>/metadata.json" --page 1
# 转写所有缺字幕的分P
python "<skill安装目录>/scripts/bili_transcribe.py" "<工作目录>/bili-notes-<BV号>/metadata.json"
注意事项:
- 设备与降级链:自动检测 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 线程数。 - 术语偏好注入:脚本自动读词表(仓库层 + 用户层),把高频术语的正确词注入 ASR 的 initial_prompt——转写时就写对,比事后纠错更准。
- 耗时:CPU int8 下 small 模型实测约为视频时长的 0.2 倍(6 核笔记本 CPU,批量推理 + 静音过滤;更老的 CPU 会慢一些,有 NVIDIA GPU 时更快),转写前按“时长 × 0.2”告知用户预计时间,先转第 1 个分P后按实际耗时修正;长视频或对质量不满意时用
--model medium重转(先删对应的 txt,否则脚本会跳过)。 - 首次运行会下载模型(small≈480MB,自动走 hf-mirror.com 镜像)。
- ASR 文稿没有标点分段质量保证,技术术语常被转错——生成笔记前用
references/asr-glossary.json词表对照校正(见第三步第2条)。
第二步半(可选,只在用户要“带截图”时做):抽取重点截图
用户没提截图就跳过本步。要截图时,先完成第三步的正文,再回来按小节定截图——
脚本负责剔除空画面、找出写完且没被挡住的画面;哪一张对得上图注由 Agent 看图决定。
(2026-11 盲评:只按讲话时刻截图,能佐证图注的只有 68%;脚本出候选网格、Agent 看图挑选,达到 95%,
见 docs/verification/W4-截图重设计.md。)
正文写完后,为需要画面佐证的小节(PPT 关键页、架构图、代码演示、对比表、板书推导)写截图清单
<工作目录>/shots.json,每小节 0~2 张、宁缺毋滥:{"shots": [ {"page": 1, "section": 2, "range": ["04:30", "06:10"], "caption": "开闭原则两层含义", "name": "two-meanings"} ]}
page分P号、section笔记## N.小节号、range这一小节在转写稿里的讲解时间段 (起点是这部分内容开始讲的时间行,终点是下一部分开始前最后一行;两端都必须是该分P转写稿里真实存在的时刻, 先 grep 确认,偏差超过 ±5s 的条目进failed,reason=range_not_in_transcript)、caption图注、name文件名(可选,缺省用 caption)。可以另写t(你认为最能说明图注的时刻),它会作为一张额外候选。生成候选网格:
python "<skill安装目录>/scripts/bili_screenshot.py" "<工作目录>/metadata.json" "<工作目录>" "<工作目录>/images" --shots "<工作目录>/shots.json" --candidates
每条清单得到一张带编号的网格
images/_candidates/p<页>_<label>.jpg(编号从 1 起,从左到右、从上到下,按时间先后排列), 编号与时刻记在images/_candidates/candidates.json。脚本每秒看一帧、按画面切段(擦黑板、翻页、镜头切换), 每段在“讲解期间”和“讲解结束后 30 秒内”各挑一张写得最全、没被挡住的;整段只有讲师在讲(黑板、投影是空的)时 不出候选,记no_content: true。这一步要把整集视频看一遍,每 10 分钟视频约需 20~40 秒。看图选编号(必做,不能跳过):逐张打开网格,按图注挑一张,在清单这一条写
"pick": <编号>:| 情况 | 处理 | |---|---| | 有一格能看清图注说的内容(PPT、类图、代码、板书) | 写它的编号;多格都行时选内容最完整、最清楚的 | | 图注描述的是分几步出现的内容(动画逐步展开的 PPT、分步推导的板书) | 选所有部分都已出现的最后一帧,不要选只出现前几步的 | | 每格都对不上(只有讲师、黑板空、画面是别的内容、还没写出来),或
no_content: true| 从清单删掉这一条,不嵌入笔记 |然后不带
--candidates再跑一次出图:python "<skill安装目录>/scripts/bili_screenshot.py" "<工作目录>/metadata.json" "<工作目录>" "<工作目录>/images" --shots "<工作目录>/shots.json"
输出
images/p<页>_s<小节>_<name>.png+images/manifest.json(记录 section)。写了range却没写pick的条目不出图 (reason=need_pick)。结束时 stderr 打一句回执(同时写进manifest.json的summary.receipt), 如“截图 6 张,剔除坏帧 0 张”。交付时把这句原样告诉用户,并说明看图时删掉了几条,例如“截图 5 张(看图删掉 2 条:只有讲师在讲)”。 一张截图都没出时脚本以非 0 退出码报错(原因 / 影响 / 下一步),按“下一步”处理后重跑;用户要了截图,不能静默交付一篇没有图的笔记,处理不了就明确告诉用户。嵌入:选中的截图以
嵌入清单里写的那个小节、它佐证的要点旁边; 一集里一张可用的都没有时,直接告诉用户“第 X 集以口头讲解为主,没有可截的画面”,不要硬凑。 交付前删掉images/_candidates/(候选网格不进笔记、不上传)。
备用写法(只写 t、不写 range):脚本在 t 往后取 3 张候选择优直接出图,不经过候选网格。
这种方式只按讲话时刻截图,画面常常对不上图注,出图后必须逐张打开看:对不上的在转写稿里往后找这部分讲完的时刻
(通常晚 30–90 秒)改 t 重跑一次,仍不行就删掉。只在视频很长、来不及整集分析时使用。
脚本行为:
- 多帧择优(只写
t的备用写法):每个时刻向后取 3 张候选(间隔 4s),优先画质合格帧,再挑与相邻候选差异最小 (画面已静止,避开 PPT 翻页过渡)的一张; - 去重:同一分P里与已选截图是同一画面(感知哈希接近且像素差小)的不落盘,记入进度 JSON 的
duplicates; - 画质 QC:亮度用像素占比法(近黑>97% 判 dark、近白>98.5% 判 bright——白底 PPT 不会误判),
清晰度用拉普拉斯方差(<10 判 blurry);每帧
qc字段非ok时由 Agent 视觉复核决定是否采用; - B站下载 480p DASH 视频抽帧后即删(填了 SESSDATA 自动取更高画质);抖音 / 小红书复用本地视频不联网;
- 不给
--shots时退回关键词锚点:查references/anchors.json中本视频 ID 的条目 (按视频隔离,别的课程的锚点不会串用),没有就用auto_anchors()从转写稿提取高频词—— 这种方式与小节无关、定位粗糙,仅作兜底; - 截图文件名默认可中文;需要 ASCII 文件名时加
--ascii-names。
第三步:生成课堂笔记
使用场景定位(2026-10-21,v4):本 skill 解决的是“看完课不用自己做笔记”—— 产出的是课后复习资料,正文按技术知识体系组织、阅读连贯:正文零时间戳、 零考试向标签(讲解体:小节先抛场景或问题、以段落展开、节末「记住这个就够了」收尾,关键术语加粗);视频时间戳只存在于文末的 “视频时间索引”,供回看原片时跳转。默认 v4 为可直接导入语雀的纯 Markdown: 无 frontmatter、无一级标题、答案与时间索引不折叠。
v4-obsidian变体增加 frontmatter, 目录改用精确标题的 Wiki 链接,其它 v4 正文规则不变。
模板默认取 config.note_template,用户可显式选择;课程以 start --template 保存、next 返回的 note.template 为准。英文课结合 audio_lang / subtitle_lang 与用户确认的语言判断,正文首次出现的术语写成 中文(Original),概念卡用中文卡名并加 + 原文:Original;原本中文课程或卡名本身是纯外文专名时免加原文行,详见模板。
读取 metadata.json(分P结构、时长)+ 各分P转写/字幕文本。
ASR 术语校正(工具化,不是凭感觉):先跑
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(见第二步),词表越丰富转写越准。长视频分块(写死流程,禁止跳过):单分P转写稿超过约 2 万字时——用
scripts/transcript_chunk.py分块(默认 15000 字/块、末尾重叠 2 段,输出chunks/目录)→ map:逐块提炼该块要点清单 → reduce:把各块要点按小节层级合并汇总成最终笔记。reduce 去重:重叠区会在相邻块产生重复内容,合并时按[mm:ss]时间戳唯一化——同一时刻的要点/锚点只保留一次,跨块重复的锚点去重后再排进小节(该去重仅作用于分块合并的中间产物;正文按 v4 规则仍然禁时刻)。禁止跳过分块直接全文阅读长转写稿。按
references/note-template.md(v4 / v4-obsidian 模板)生成一份 MD 文件,保存到用户工作目录,命名<序号>-<主题>.md(如2.13-业务流程建模.md;序号取课程选集号,或按用户已有笔记递增如01;主题取视频标题关键词——文件名即语雀文档标题)。生成前必读该模板文件。以下为 v4 硬性要求;v4-obsidian仅将开头换成模板规定的 frontmatter(闭合后紧接核心主线引语块),目录换成+ [[#精确正文标题]],其它规则相同:- 无 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 不适用的项以第六之一节为准; - 目录:
+ [N. 小节名](#锚点)不带时刻,末尾固定列出 本讲知识地图 / 本讲小结 / 概念卡片 / 自测题(面试速答)/ 视频时间索引; - 小节(讲解体):
## N. 小节名(禁时刻后缀),开头先抛场景、问题或朴素做法(朴素做法写进行文、不加标签,讲者没对比过就不硬造),不先给结论、不写**核心思想:**;以段落展开(一段 1~4 句),列表只用于 3 项以上并列或步骤(用+),对比用表格,流程可用```plain箭头图(语雀不认text),长节可用### N.M再分;术语先用大白话解释再加粗命名;讲者的比喻写**打个比方:**,笔记自补的比喻写**打个比方(笔记补充):**并尽量说明边界;最后一行固定为> **记住这个就够了**:<一句话结论>;每小节 ≥3 行实质内容;禁止三词标签前缀(核心必考/重点掌握/了解即可及任何变体)、禁止行内[mm:ss];小节之间可用---分隔; - 代码块:真实语言 fence;来源标注可选——来自克隆仓库写
# 来源:仓库 <子项目>/<文件路径>(注释符随语言),按视频讲解组织的可写# 按视频讲解还原或不写;任何代码块内禁时刻; - 概念卡片:
### 概念名(禁标签后缀)++ 定义:/+ 出现:/+ 依赖:/+ 易混:四行;出现写作第 N 节「小节名」、第 M 节「小节名」(≥2 个小节,节名与正文小节标题一致),禁时刻; - 本讲小结(知识地图之后、概念卡片之前;lecture 建议必备,short 可省):表格「机制/概念 | 解决什么问题 | 一句话」≥2 行 +
**学完能说的 3 句话:**下恰好 3 条编号句子; - 自测题(面试速答,不折叠):标题
## 自测题(面试速答);N. <题干>?(对应:概念名)(概念必须在概念卡片集合内:lecture 必须、short 可选),空一行后写**答案:** <一段 2~6 句>——先说结论、再说原因、最后举例,串联相关小节的内容,写在同一段里,内容取自转写稿(补充部分标「(视频中未展开,笔记补充)」);不用<details>,禁时刻;lecture 4~7 道(short 2~3 道);选题主打高频原理与面试易错点,禁 yes/no 题干; - mermaid 知识地图 = 概念关系图,不是目录树:
```mermaid代码块,推荐graph TD;R((主题))为根,节点用概念卡片里的概念(每张概念卡都要出现),小节名放在分组标题上而不是当节点,分组行写成subgraph 分组名(不要写subgraph S1[分组名],语雀会报 Parse error;标题不含空格、括号);边带关系标签表达概念之间怎么关联——A -->|依赖| B、A -->|推出| B、A -->|组成| B、A -.->|易混| B,lecture 带标签边 ≥ 概念卡数 − 1,关系尽量与概念卡「依赖 / 易混」一致;节点标签禁半角 ( ) [ ] { } 与引号、≤12 字(需要括号用全角);导入语雀后自动渲染为图; - 视频时间索引:文末最后一节,前接
---,不折叠、不写 NAV 标记;模型只写条目+ [mm:ss] <与正文一级小节同名>(一级章节一条),不写 URL;时刻必须取自转写稿真实时间行(允许 ±5s 内小幅前移,禁止虚构);lecture 必须有本节,short 可整体省略。
- 无 frontmatter、无
笔记中引用的代码/命令必须以视频文稿内容为准;文稿未讲到的细节不要编造,可标注"(视频中未展开,建议补充)"。若视频简介里有代码仓库,克隆下来读取源码,把笔记中的代码示例换成仓库中的真实代码(首选做法)。
填充时间索引深链(v4 笔记默认执行):
python "<skill安装目录>/scripts/note_nav.py" "<笔记.md>" --template v4 --meta "<metadata.json>" --txt-dir "<转写稿目录>"(每个选集单独一份笔记时加--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,脚本输出不含自由文本,职责不重叠。质量门禁:生成后运行
python "<skill安装目录>/scripts/validate_note.py" "<笔记.md>" --template v4 --meta "<metadata.json>" --txt-dir "<转写稿目录>"单视频选择 Obsidian 时,第 6、7 步的模板都显式改为--template v4-obsidian,例如:python "<skill安装目录>/scripts/note_nav.py" "<笔记.md>" --template v4-obsidian --meta "<metadata.json>" --txt-dir "<转写稿目录>" python "<skill安装目录>/scripts/validate_note.py" "<笔记.md>" --template v4-obsidian --meta "<metadata.json>" --txt-dir "<转写稿目录>"
(每个选集单独一份笔记时加
--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行号)。截图上传 OSS(仅带截图的笔记):语雀导入 Markdown 不会上传本地图片,交付前先预演
python "<skill安装目录>/scripts/upload_images.py" "<笔记.md>"(列出将上传的图片与目标 OSS 链接,不联网不改文件), 确认后加--apply:按内容哈希命名上传(远端已有则跳过,可重复执行),再把笔记里的images/...原位改写为 OSS 链接(留.bak备份)。 OSS 配置读config.json的oss字段或环境变量OSS_ENDPOINT / OSS_BUCKET / OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET / OSS_PREFIX / OSS_PUBLIC_BASE_URL(也可--env-file <xxx.env>);Bucket 需公共读或经 CDN 可公开访问。门禁要在上传前跑(上传后图片是网络链接,位置与图注校验会跳过); 缺配置时脚本只列出缺哪些键,不要向用户索要密钥明文,让用户自己填进 config.json 或环境变量。媒体清理(单视频交付后按缓存询问;整门课按课程步骤 7 处理):若输出目录存在缓存媒体(抖音的
media_p01.mp4等本地视频,或残留的.part/.audio_*/.video_*临时文件),询问用户「是否清理缓存的视频/音频文件?重新做笔记会重新下载」:确认 → 先跑python "<skill安装目录>/scripts/clean_media.py" "<输出目录>"把将删除的清单给用户过目,再执行--apply实删;拒绝 → 跳过并说明缓存保留的意义(重跑截图/转写不再联网)。B站的临时音频/视频在流程中已自动删除,通常无残留。
笔记模板
完整骨架与语法契约以 references/note-template.md 为准(生成前必读)——全文含
lecture 完整骨架、时间戳规范、语法契约、short 差异表、截图嵌入规范、生成流程。
结构层次速览(节点内容以 <…> 占位):
> 核心主线:<一句话知识主线> # 文件第一行;无 frontmatter、无 # 标题(文件名 <序号>-<主题>.md 即标题)
> 本讲目标:读完你能回答「…」「…」
> 课程来源:<视频标题等> # 有仓库再加 > 课程代码:<仓库地址>
## 目录 # + [N. 小节名](#锚点) 不带时刻;末尾固定列出 本讲知识地图 / 本讲小结 / 概念卡片 / 自测题(面试速答)/ 视频时间索引
## N. 小节名 ×N # 场景/问题开头 → 段落展开(术语加粗、表格、代码块、打个比方、本节截图)→ 最后一行 > **记住这个就够了**:<一句话>
## 本讲知识地图 # mermaid graph TD 概念关系图:节点=概念卡,subgraph 分组,边带关系标签
## 本讲小结 # 表格 机制/概念 | 解决什么问题 | 一句话(≥2 行)+ **学完能说的 3 句话:** 1. 2. 3.
## 概念卡片 # ### <概念名>:+ 定义 / + 出现:第 N 节「小节名」 / + 依赖 / + 易混
## 自测题(面试速答)# 不折叠:题干后空一行写 **答案:** 一段 2~6 句(结论→原因→例子),lecture 4~7 道 / short 2~3 道
---
## 视频时间索引 # 不折叠、无 NAV 标记;条目 + [mm:ss] <章节名>,URL 由 note_nav.py 填充
常见问题
脚本失败时统一输出三段:原因: / 影响: / 下一步:(必要时附 详情:)。把这三段原样转告用户,按“下一步”处理,不要只说“脚本报错了”。单集失败的进度 JSON 另有 reason / impact / next_step / rerun 字段,rerun 是只补跑这一集的命令。
| 现象 | 处理 |
|---|---|
分P subtitle_detail 为 api_empty | 主动询问用户「要现在扫码登录B站吗?」,确认后代跑 bili_fetch.py --login(生成二维码 PNG 图片并打印路径)后重跑;用户拒绝或重跑后仍 api_empty 才走 ASR |
分P subtitle_detail 为 ai_mismatch | AI 字幕整体错位(内容是别的音频,看着通顺但与视频无关),fetch 已自动判出并按无字幕处理;直接走 ASR,不要试图沿用存疑字幕 |
| 提示“请求被B站风控拦截”(HTTP 412) | 云服务器 / 机房 IP 上常见,脚本不会重复请求:换到家用网络或在本机运行;等几分钟再试 |
| playurl 下载失败/音频为空 | 按提示的“下一步”处理(多为风控或需要登录);单集失败照 rerun 补跑这一集 |
| faster-whisper 首次运行卡在下载 | 检查 HF_ENDPOINT 是否为 https://hf-mirror.com,或手动 pip install -U huggingface_hub |
| 转写文本术语错乱 | 用 references/asr-glossary.json 对照校正;词表未覆盖的新错法按同样格式补进词表 map,下次自动生效 |
subtitle_detail 为 error | 看该分P的 reason / next_step:这一集会改走语音识别;想重取字幕按 rerun 重跑 |
| 转写质量差(长视频尤甚) | 先删对应 txt,再用 --model medium 重转;有 NVIDIA GPU 时脚本会自动用 CUDA float16,也可 --device cuda 强制 |
| 抖音提示“作品不可见” | 作品已删除、设为私密或仅粉丝可见(平台返回了 filter_detail),不是签名问题:告知用户换链接 |
| 抖音提示“签名算法已被平台升级” / HTTP 403 | 参考 Evil0ctal/Douyin_TikTok_Download_API 或 JefferyHcool/BiliNote 更新 abogus.py / WEB_SIGN_SALT,或提 issue |
| 抖音 / 小红书提示“下载的文件过小” | 多半被风控或下载地址过期:等几分钟重跑 fetch 脚本重新解析(本地已有完整 mp4 会自动跳过下载) |
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 |
| YouTube 缺格式 / 下载失败 | 升级 pip install -U yt-dlp 并安装 deno(2025 年起 YouTube 需要 JS 运行时解挑战) |
| YouTube 年龄限制视频 | youtube-transcript-api 拿不到,需 --cookies/--cookies-from-browser 让 yt-dlp 回退取字幕 |
| 小红书提示缺少 xsec_token / 被重定向 / 无笔记数据 | 让用户在 App「分享 → 复制链接」把整段文本发来(token 有时效,过期重新复制);笔记需公开可见 |
| 小红书提示风控验证(HTTP 461/471) | 请求过频触发验证码:稍后重试,或在 config.json 配 xhs_cookie(浏览器登录后复制 Cookie) |
| 小红书提示「这是图文笔记」 | 本工具只处理视频笔记,告知用户换视频笔记链接 |
| YouTube 正在直播 / 预告 | 脚本直接提示退出,等直播结束、回放生成后再试 |
| 环境缺依赖 | B站流程需 faster-whisper + av;抖音流程另需 pip install gmssl;YouTube 流程另需 pip install yt-dlp youtube-transcript-api;小红书流程无额外依赖 |
