bili-note

# Bili Note 把 B站视频和图文动态变成可检索、可复用的 Markdown 知识笔记。视频优先拿字幕；字幕拿不到时再转写音频；图文优先抓正文、图片和代码块；用户要评论区时抓取评论并过滤无关讨论。 联网或登录态操作必须先使用 `web-access`。 网页 AI 字幕支持两条路线：Chrome 使用 `web-access`，Edge 使用开启远程调试的 Chromium DevTools Protocol 直连。两条路线都让已登录的 B站页面自己请求字幕接口，不读取或复制 Cookie/profile。Playwright 临时浏览器不属于受支持路线。 Bili Note 与 DyNote 共享可复用本地资源。默认共享目录是 `%USERPROFILE%\.cache\rimagination-notes`，Qwen3-ASR 环境默认是 `%USERPROFILE%\.cache\rimagination-notes\qwen3-asr-venv`。如果任一 skill 已经安装过 Qwen3-ASR，另一个 skill 必须优先复用，不要重复安装。Hugging Face、Whisper 和 faster-whisper 缓存按本机通用缓存复用。 ## 字幕密度与视觉理解 B 站视频优先拿字幕，但字幕/转写不等于完整理解。长视频如果字幕字数明显偏少，可能说明核心信息在画面、PPT、板书、代码演示、屏幕操作或无解说片段中。 - 每次视频运行都必须先做轻量预检，再询问用户是否开启“关键帧视觉理解”。预检只读取元数据、分P信息和已有字幕文件，不下载视频；它会显示时长、字幕字数、字幕密度和画面依赖建议。收到明确的 `on` 或 `off` 后才能进入后续流程。询问时说明：`on` 会抽取最多 12 帧，先合成为一张 4×3 联系图，再按需要打开单帧，视觉输入会增加 tokens；`off` 只走字幕、转写、评论和元数据路线，节省视觉输入 tokens。 - 用户选择 `on` 时，给 `run_bili_note.py` 传 `--visual-review on`；选择 `off` 时传 `--visual-review off`。脚本默认 `--visual-review ask`，直接在终端运行也会在轻量预检后停下来等待选择。 - 关键帧理解选择只对视频运行生效。图文/动态已有图片材料，按图文视觉理解流程处理。 - 归档后必须读取 `metadata/note_budget.json`。如果 `visual_dependency.needs_visual_review=true`，不要把稀疏字幕写成完整学习笔记。 - 这种情况下，先采用更合适的技术：抽取代表性关键帧或截图，再做 OCR 或多模态视觉理解；必要时重新抓网页 AI 字幕或补本地自动语音识别。 - 如果当前接入的模型或工具不能看图，必须告诉用户：关键帧理解属于高级视觉能力，需要多模态模型、OCR 工具或人工查看；当前只能基于字幕/元数据生成有限笔记并标注覆盖范围。 - 最终笔记和用户回复要转述 `visual_dependency.warnings`，并说明是否已经补了视觉证据。 关键帧视觉理解采用低成本的两阶段读取：先看一张 4×3 联系图建立全片画面地图；联系图中出现文字、代码、图表或界面细节时，再依据工作目录的 `keyframes_manifest.json` 打开对应单帧。归档后对应路径是 `archive_dir/metadata/keyframes_manifest.json`。不要默认把 12 张完整图片全部送入模型。 选择 `on` 后，先查看 `keyframes/contact_sheet.png`，再结合 `keyframes/README.md` 和工作目录的 `keyframes_manifest.json` 定位时间点。把视觉观察写入材料包的 `metadata/visual_review.md`，每条关联 `KF-Pxx-xx`、分P、时间和观察结论；不确定的画面标记为待核实。关键帧证据可通过 `indexes/关键帧索引.jsonl` 和总证据索引回查。 ## 依赖与环境检查 默认路线尽量零第三方 Python 依赖：视频元数据、公开字幕、图文正文、图片清单、评论、归档、证据索引和笔记预算都用标准库完成。网页 AI 字幕和音频转写是增强路线，不是启动门槛。 第一次使用、换机器、用户怀疑依赖不全，或准备使用网页 AI 字幕 / 音频转写兜底时，先运行： ```powershell $skill = "$env:USERPROFILE\.codex\skills\bili-note" $py = "python" & $py "$skill\scripts\check_environment.py" ``` 根据检查结果选择路线： - `public_subtitles_comments_archive=OK`：优先走默认字幕/图文、评论和归档流程。 - `browser_ai_subtitles=OK`：当公开接口只有 `ai-zh` 且 `subtitle_url` 为空时，走 Chrome + `web-access` 网页 AI 字幕。 - `edge_browser_ai_subtitles=OK`：需要 Edge 远程调试端口和 `websocket-client`，总入口加 `--browser edge`。 - `audio_asr_fallback=OK`：只有字幕和网页 AI 字幕都不可得、且用户确实需要完整转写时，才走音频转写。中文或未指定语言优先共享 Qwen3-ASR；明确外语视频优先 Whisper 系后端。 - 某个增强能力缺失时，只说明该路线暂不可用；不要把它说成整个 skill 不可用。 - 网页登录态只通过已授权的 Chrome `web-access` 页面或 Edge 远程调试页面使用；不要读取或复制 Cookie/profile，不要强制结束用户浏览器进程。两种浏览器路线都不可用时就跳过网页 AI 字幕并说明覆盖范围。 ## 默认流程 1. 读清用户要什么：视频或图文链接、是否要评论区、保存路径、是否需要全文材料或只要提炼。 2. 如果是首次使用、依赖状态不明、字幕抓取失败或用户要求音频转写，先用 `check_environment.py` 判断当前可走路线。 3. 如果是视频，先让总入口完成轻量预检；它只抓元数据和字幕，不下载视频。根据预检结果向用户说明建议，并完成关键帧视觉理解询问；用户选择后把 `--visual-review on` 或 `--visual-review off` 传给总入口。 4. 优先用 `run_bili_note.py` 一键完成可自动化部分。它会自动识别 `/video/BV...`、`/opus/...`、`/dynamic/...` 或纯 opus id。 5. 如果是图文/动态，走 `extract_bilibili_opus.py` 路线：抓正文、标题、作者、发布时间、图片、代码块、图文证据索引；用户加 `--comments` 时抓图文评论。 6. 如果是视频，优先下载字幕： - 普通字幕 URL 可用时，直接用 `--download-subtitles`。 - 如果普通接口显示 `ai-zh` 但 `subtitle_url` 为空，不要说“没有字幕”；改走“网页 AI 字幕”流程。 - 如果字幕仍不可得，再按需要下载音频并用本地自动语音识别转写。中文优先 Qwen3-ASR，明确外语优先 Whisper 系后端。 7. 用户要求评论区时，用 `--comments` 抓取主评论和子评论；写入笔记时过滤打卡、求资料、广告、闲聊等技术无关内容。 8. 归档原始材料：把完整字幕或图文正文、图片、完整评论、元数据和 JSONL 索引存到知识库旁边的长期目录。 9. 用户选择 `on` 时，在写前定标前查看 `keyframes/contact_sheet.png`，必要时查看对应单帧，并保存 `metadata/visual_review.md`。 10. 写前定标：必须先读取 `metadata/note_budget.json`，把推荐字数区间、压缩比目标、写作粒度、互动质量倍率、证据块数量和 `visual_dependency` 作为本次笔记的写作目标。视频按时长、字幕字数、证据块、评论量和互动质量定标；图文按正文长度、图片/代码/证据块、评论量和互动质量定标。 - 如果 `visual_dependency.risk` 是 `medium` 或 `high`，先补关键帧/OCR/多模态视觉理解，或明确告诉用户当前缺少视觉理解能力，不能写成完整解析。 11. 按预算写 Markdown：默认写成“学习型笔记”，目标是让人或 Agent 像学完一节课或读完一篇教程一样获得概念、方法、判断标准、实践步骤和自测题；根据预算决定详略，不要把长课和短视频写成差不多字数。来源、覆盖范围和归档路径放到后半部分。正文证据默认用论文式编号 `[1][2]`，不直接堆长证据 ID。 12. 写后验收：用 `score_bili_note.py` 校验笔记字数、压缩比、每分钟/每篇笔记密度和证据引用比例。评分只做 QA 和微调，不代替写前定标；太短时优先补“学习收获、知识地图、概念卡、实战流程、坑点、自测题”，不要只堆分P摘要或段落摘要。 ## 常用命令 在 PowerShell 中先设定 skill 路径： ```powershell $skill = "$env:USERPROFILE\.codex\skills\bili-note" $py = "python" ``` ### 0. 检查依赖和可用路线 ```powershell & $py "$skill\scripts\check_environment.py" ``` 需要给其他脚本读取时输出 JSON： ```powershell & $py "$skill\scripts\check_environment.py" --json ``` ### 1. 一键提取和归档 默认先用总入口。它会自动跳过已有输出，适合断点续跑。 ```powershell & $py "$skill\scripts\run_bili_note.py" "https://www.bilibili.com/video/BVxxxx/" ` --work-dir ".\tmp_bili_extract" ` --archive-dir "D:\knowledge\知识库\Rag技术\原始材料\BVxxxx_视频短标题" ` --visual-review on ` --comments ``` 如果用户选择关闭，把上面的 `--visual-review on` 改为 `--visual-review off`。每次视频运行都重新询问，不能沿用上一次选择。 图文/动态也用同一个入口： ```powershell & $py "$skill\scripts\run_bili_note.py" "https://www.bilibili.com/opus/1194341967364882439" ` --work-dir ".\tmp_bili_opus" ` --archive-dir "D:\knowledge\知识库\Rag技术\原始材料\O1194341967364882439_图文短标题" ` --comments ``` 如果只想保存图文正文和图片 URL，不下载图片文件，加： ```powershell --no-download-images ``` 如果普通接口没有字幕，但网页播放器能拿到 AI 字幕，Chrome 先用 `web-access` 打开已登录页面并取得 target id，然后加： ```powershell --browser-target "CDP_TARGET_ID" ``` 运行后先看： - `bili_note_run_report.md`：本次跑了什么、跳过了什么、下一步读哪里。 - `visual_preflight.json`：询问前的时长、字幕密度、风险和建议，方便复核本次选择依据。 - `keyframes/contact_sheet.png`：开启关键帧视觉理解时生成的 4×3 联系图。 - `keyframes_manifest.json`：工作目录中的关键帧编号、分P、时间和单帧路径。 - `archive_dir/metadata/keyframes_manifest.json`：归档后的关键帧清单。 - `archive_dir/metadata/visual_review.md`：视觉模型对关键帧的观察结果，由 Agent 在理解后写入。 - `archive_dir/indexes/证据索引.jsonl`：写总结时可引用的图文/字幕/评论证据块。 - `archive_dir/indexes/图文全集.md`：完整图文正文合集。 - `archive_dir/indexes/字幕全集.md`：完整字幕合集。 - `archive_dir/metadata/note_budget.json`：推荐笔记字数、压缩比、写作粒度和字幕稀疏时的画面依赖提示。 - `archive_dir/metadata/visual_preflight.json`：归档后的关键帧选择预检记录。 ### 2. 抓元数据和分P目录 ```powershell & $py "$skill\scripts\extract_bilibili.py" "BVxxxx" --out ".\tmp_bili_extract" ``` ### 3. 下载普通公开字幕 ```powershell & $py "$skill\scripts\extract_bilibili.py" "BVxxxx" --out ".\tmp_bili_extract" --parts all --download-subtitles ``` ### 4. 下载网页 AI 字幕 当 `subtitle_probe.json` 里有 `ai-zh`，但 `subtitle_url` 为空时，使用这条路线。Chrome 需要 `web-access` 的 `/targets` 和 `/eval` 代理接口；Edge 使用直接 CDP 路线。 Chrome 路线： 1. 用 `web-access` 打开已登录 Chrome 中的 B站视频页，确认页面已加载。 2. 查看浏览器 target id： ```powershell curl.exe -s http://localhost:3456/targets ``` 3. 下载 AI 字幕： ```powershell & $py "$skill\scripts\fetch_browser_ai_subtitles.py" --target "CDP_TARGET_ID" --out ".\tmp_bili_extract" ``` Edge 路线： 1. 用 `--remote-debugging-port=9222` 启动 Edge 独立实例，在其中登录 B 站并打开视频页。 2. 安装可选依赖：`python -m pip install websocket-client`。 3. 运行总入口： ```powershell & $py "$skill\scripts\run_bili_note.py" "BVxxxx" ` --work-dir ".\tmp_bili_extract" ` --browser edge ` --subtitle-mode browser ``` 也可以直接运行字幕脚本；它会优先选择 Edge 中 URL 包含 `bilibili.com` 的页面： ```powershell & $py "$skill\scripts\fetch_browser_ai_subtitles.py" ` --browser edge ` --edge-cdp-url "http://127.0.0.1:9222" ` --out ".\tmp_bili_extract" ``` 输出包括： - `browser_ai_subtitle_urls.json`：每个分P的 AI 字幕 URL。 - `browser_ai_subtitle_manifest.json`：下载清单。 - `browser_ai_subtitles\*.txt`：纯文本字幕。 - `browser_ai_subtitles\*.srt`：SRT 字幕。 - `browser_ai_subtitles\*.subtitle.json`：B站原始字幕 JSON。 这条路线让 B站页面自己用登录态请求 `/x/player/wbi/v2`，不读取、不打印浏览器 cookie。 如果下载到的 AI 字幕明显乱码、内容与标题或课程主题不相干，不要把它当作可靠全文。优先标注“AI 字幕质量不可用”，再考虑 ASR 兜底；若 ASR 也不可用，只能基于分P标题、简介、评论和元数据生成有限学习指南，并明确局限。 ### 5. 抓评论区 ```powershell & $py "$skill\scripts\extract_bilibili.py" "BVxxxx" --out ".\tmp_bili_extract" --comments ``` 图文评论用总入口或图文脚本： ```powershell & $py "$skill\scripts\extract_bilibili_opus.py" "https://www.bilibili.com/opus/1194341967364882439" --out ".\tmp_bili_opus" --comments ``` 抓取后检查 `comments.md` 和 `comments_raw.json`。写入最终笔记时，只保留与内容主题相关的评论、纠错、技术补充、实践经验和有价值问题。 ### 6. 音频转写兜底 只有在字幕和网页 AI 字幕都不可用时才用本地自动语音识别。长视频不要默认全量转写，除非用户明确要求。中文或未指定语言默认 `--asr-backend auto` 会优先共享 Qwen3-ASR；明确外语视频时用 Whisper 系后端。 ```powershell & $py "$skill\scripts\extract_bilibili.py" "BVxxxx" --out ".\tmp_bili_extract" --parts "1,10,38" --download-audio --transcribe --asr-backend auto --asr-model base ``` 首次使用 Qwen3-ASR 前先安装共享环境： ```powershell & $py "$skill\scripts\setup_qwen_asr_env.py" & $py "$skill\scripts\check_environment.py" ``` 中文视频可显式指定 Qwen3-ASR： ```powershell & $py "$skill\scripts\extract_bilibili.py" "BVxxxx" --out ".\tmp_bili_extract" --parts "1,10,38" --download-audio --transcribe --asr-backend qwen3-asr ``` ### 7. 归档完整材料 把临时提取目录整理成长期材料包。这个步骤默认要做，方便后续根据总结继续提问和回查证据。 ```powershell & $py "$skill\scripts\archive_bili_materials.py" --extract-dir ".\tmp_bili_extract" --archive-dir "D:\knowledge\知识库\Rag技术\原始材料\BVxxxx_视频短标题" ``` 长期材料包包含： - `articles/图文全文.md`：完整图文 Markdown。 - `articles/图文全文.txt`：完整图文纯文本。 - `images/`：图文图片和图片清单。 - `indexes/图文全集.md`：合并后的完整图文正文。 - `indexes/图文全集.jsonl`：按图文内容块切分，适合检索和问答。 - `indexes/图文证据索引.md`：图文证据块，适合给总结加引用。 - `indexes/图文证据索引.jsonl`：图文证据块，适合程序检索。 - `subtitles/txt/`：每个分P的完整纯文本字幕。 - `subtitles/srt/`：每个分P的完整 SRT 字幕和时间轴。 - `subtitles/json/`：B站原始字幕 JSON。 - `comments/comments_raw.json`：完整评论原始结构。 - `comments/评论全集.md`：完整评论 Markdown。 - `indexes/字幕全集.md`：合并后的完整字幕，适合人工阅读。 - `indexes/字幕全集.jsonl`：按字幕片段切分，适合检索和问答。 - `indexes/字幕证据索引.md`：按时间段合并的字幕证据块，适合给总结加引用。 - `indexes/字幕证据索引.jsonl`：按时间段合并的字幕证据块，适合程序检索。 - `indexes/评论全集.jsonl`：按评论/回复切分，适合检索和问答。 - `indexes/评论证据索引.jsonl`：按评论/回复生成的证据块。 - `indexes/证据索引.jsonl`：图文/字幕证据和评论证据的合并索引。 - `metadata/`：内容元数据、字幕清单、图文清单、评论清单。 - `metadata/note_budget.json`：按内容信息量和互动质量生成的笔记预算，用于控制长短视频、长短图文的提炼粒度，并提示字幕稀疏时的视觉补证需求。 ### 8. 写前读取预算，写后验收信噪比 写笔记前先看预算。预算是本次笔记的目标，不是写完后才补救的报告： ```powershell Get-Content -Encoding UTF8 "D:\knowledge\知识库\Rag技术\原始材料\BVxxxx_视频短标题\metadata\note_budget.json" ``` 重点先确定： - 推荐字数区间：`recommended_note_chars_min` 到 `recommended_note_chars_max`。 - 写作粒度：`granularity` 和 `writing_guidance`。 - 信息量基准：视频看 `duration_minutes`、`subtitle_chars`，图文看 `content_chars`、`reading_minutes_estimate`。 - 字幕密度：视频看 `subtitle_chars_per_minute` 和 `visual_dependency`；长视频字幕过少时先补关键帧/OCR/多模态视觉理解。 - 质量倍率：`quality_multiplier` 和 `quality_metrics`，用于判断是否值得保留更多细节。 - 证据规模：`all_evidence_blocks`，用于决定关键判断需要覆盖多少证据。 写完最终 Markdown 后，用归档目录里的预算给笔记打分： ```powershell & $py "$skill\scripts\score_bili_note.py" ` --archive-dir "D:\knowledge\知识库\Rag技术\原始材料\BVxxxx_视频短标题" ` --note-path "D:\knowledge\知识库\Rag技术\观点X：视频短标题.md" ` --out "D:\knowledge\知识库\Rag技术\原始材料\BVxxxx_视频短标题\metadata\note_score.json" ``` 也可以直接把评分结果写入笔记正文： ```powershell & $py "$skill\scripts\update_note_budget_section.py" ` --archive-dir "D:\knowledge\知识库\Rag技术\原始材料\BVxxxx_视频短标题" ` --note-path "D:\knowledge\知识库\Rag技术\观点X：视频短标题.md" ``` 重点看： - `status`：`too_short` 表示遗漏风险高，`too_long` 表示可能重复堆料，`ok` 表示落在写前推荐区间。 - `quality_multiplier`：点赞、收藏、投币、评论、弹幕、分享、播放量和发布距今天数形成的互动质量倍率。 - `actual_compression_ratio`：笔记字数 / 字幕字数。长视频应允许更高总字数，但仍要保持压缩。 - `note_chars_per_minute`：每分钟视频对应多少笔记字。长课程不应和短视频接近同一个总字数。 - `evidence_reference_ratio`：笔记中引用的证据块占比。关键判断要能回查图文证据 `O...`、字幕证据 `Pxx@...` 或评论证据 `C...`；正文用统一数字编号，文末编号脚注和 reference-style 链接定义必须指向含完整证据 ID 的归档文件。 ## 笔记写法 默认输出必须是“学习型笔记”，不是目录搬运、分P流水账或证据清单。读完后应有“我真的学会了一些东西”的获得感。 ### 推荐结构 1. `# 标题` 2. `## 学完你应该获得什么`：用 5-8 条写清楚读者学完后能理解、判断或完成什么。 3. `## 一句话总论`：说明视频最核心的判断，避免只复述标题。 4. `## 适用场景与前置知识`：这套内容适合谁、不适合谁，读者需要先知道什么。 5. `## 知识地图`：把核心概念、模块、流程和它们之间的关系讲清楚。课程型视频要有模块表；短观点视频要有论证链。 6. `## 核心概念卡`：每个重要概念都写成“是什么、为什么重要、怎么用、常见误区、相关证据”。 7. `## 方法或流程`：把原内容中的操作、架构、决策流程、参数选择、评估方法抽成可复用步骤。 8. `## 关键洞察`：写作者真正想表达的判断，区分“事实描述、经验判断、推荐做法、限制条件”。 9. `## 实践清单`：给出可以照着做的步骤、检查项、失败信号和排错方向。 10. `## 坑点与反例`：整理视频和评论区提到的踩坑、争议、误区、边界条件。 11. `## 自测题`：写 5-10 个问题和简短答案，帮助人或 Agent 检查是否学会。 12. `## 证据与原文位置`：只放关键证据引用，不要让证据淹没学习内容。 13. `## 来源、覆盖与局限`：URL、BVID、UP、发布时间、字幕/评论覆盖、原始材料路径和局限放在后面。 ### 写作标准 - 先解释“为什么”和“怎么迁移使用”，再列“他说了什么”。 - 对课程型长视频，按学习模块组织，不要按分P机械压缩。每个模块至少包含：学习目标、核心概念、关键步骤、常见坑、可操作结论。 - 对观点型短视频，按“问题背景 -> 作者判断 -> 论据 -> 适用边界 -> 对用户的启发”组织。 - 对技术教程和图文长文，保留架构、数据流、代码思路、配置项、图片结论、评估方式和排错路径。 - 如果长视频字幕/转写密度过低，先补视觉证据；没有多模态视觉能力时，明确把当前笔记标为“基于字幕/元数据的有限整理”。 - 评论区只写有学习价值的内容：纠错、补充案例、实践经验、替代方案、争议点。 - 证据引用服务于学习，不要把笔记写成引用列表。正文默认使用统一的论文式数字编号，例如 `[1][2]`；图文证据、字幕证据、评论证据共用一套编号，按正文首次出现顺序递增。不要在正文段落里直接塞很长的 `O<opus_id>-E001`、`Pxx@hh:mm:ss-hh:mm:ss` 或 `C<rpid>`。 - 在 `## 来源、覆盖与局限` 之前放 `## 证据脚注`。脚注用有序列表写明编号和证据链接，例如 `1. [图文证据 E006](原始材料/O.../indexes/图文证据索引.md#O...-E006)`；列表后再放 reference-style 链接定义，例如 `[1]: 原始材料/O.../indexes/图文证据索引.md#O...-E006 "图文证据 E006"`，让正文里的 `[1]` 也能点击跳转。 - 保留 `## 证据与原文位置` 作为证据总览，但总览里也只写 `[1]`、`[2]` 这样的编号，不再直接显示长证据 ID。 - 写前先按 `note_budget.json` 定标，再开始写笔记；写后评分只用于验收和微调，不要把主要长度决策推迟到评分阶段。