VideoBook：把一個影片做成一本圖文電子書
使用者給一個 YouTube / Bilibili 連結，產出一本可線上閱讀的技術電子書：
output/<video_id>/book.md + book.html（內嵌播放器卡片、截圖點擊放大、Mermaid 圖），
可選 transcript.corrected.txt 字幕校訂對照稿，並可發佈到 GitHub Pages 供他人閱讀。
本 skill 是編排層，並且自包含：agent 需要的指令全部在本目錄內（SKILL.md + references/），
不依賴倉庫裡的 instructions.md / README.md（那兩份面向人類讀者，保持原樣、不由本 skill 維護）。
唯一的外部依賴是流水線的可執行代碼 src/*.py：命令與參數一律以腳本 --help 為準，不要重寫腳本邏輯。
易變數據（例如 src/make_corrected.py 裡的錯詞 MAP）不要複製進 skill，只寫規則並指向源檔案；
唯一例外是第二步的排版指令，本目錄自帶同源副本 references/stitcher-prompt.md（倉庫版本優先）。
前置條件（首次執行必讀）
- 工作目錄 = videobook 倉庫根目錄（判據：存在
src/dump_transcript.py與prompts/）， 所有相對路徑（output/<video_id>/...）都相對它解析。倉庫不在本地時先git clone https://github.com/Luke-Evan/videobook.git到使用者存放程式碼專案的目錄 （不要放臨時目錄，也不要另建 projects 目錄），再cd進去。 - Python >= 3.10（推薦 3.12）。裝依賴：
uv sync（用 uv 時）或pip install -r requirements.txt。 執行統一走倉庫環境的直譯器：uv run python src/xxx.py或.venv/Scripts/python.exe src/xxx.py。 - 一次性登入：
python src/capture_frames.py --setup-profile彈出專用 Chrome（資料目錄.capture-profile/）， 掃碼登入 B 站 / YouTube 後關窗即可，登入態長期復用。登入帳號的會員檔位 = 截圖清晰度上限。 - 海外影片：終端要代理（抓字幕），瀏覽器也要全域代理（否則生成頁面裡的 YouTube iframe 是一片黑塊）。
- 需要沙箱外/提權的命令見總覽表最後一列；純本地步驟沙箱內即可。
流水線總覽
| 步 | 做什麼 | 命令 | 細節 | 提權 |
|---|---|---|---|---|
| 1 | 提取字幕 | python src/dump_transcript.py "<URL>" | references/transcript.md | B 站需 |
| 1b | 平台無字幕時本地 ASR 兜底 | python src/asr_transcript.py <video_id> | references/transcript.md | 否（耗時長） |
| 1.5 | 課程官方講義 + 4K 幻燈片（預設執行，課程無主頁才跳過） | python src/course_assets.py <video_id> --course-url <課程主頁> | references/course-assets.md | 渲染需 |
| 2 | 大模型把字幕改寫成 book.md | 按排版指令生成（references/stitcher-prompt.md，倉庫 prompts/stitcher_system.md 存在時以它為準） | references/writing.md | 否 |
| 2b | 字幕校訂對照稿（可選） | python src/make_corrected.py <video_id> | references/correction.md | 否 |
| 3 | 截幀並把佔位符物化為圖片 | python src/capture_frames.py <video_id> "<URL>" | references/capture.md | 是 |
| 4 | 渲染 HTML + 起本地預覽 | python src/post_process.py "<URL>" output/<id>/book.md 然後 python -m http.server 8080 --directory output/<id> | — | 否 |
| 5 | 告知使用者結果、詢問大檔案清理 | — | 見下方「交付」 | — |
| 6 | 發佈成品到 pages 分支（可選） | python src/publish.py <video_id> 然後 git push origin pages | references/publish.md | 否（push 需網路） |
報錯、畫質不對、字幕抓不到、ASR 中斷等問題先查 references/troubleshooting.md。
鐵律（不可協商）
- 字幕覆蓋率 < 50%（退出碼 3）不得進入第二步：先修登入態/代理，或轉 ASR 兜底。
- 截圖畫面必須來自已登入瀏覽器裡的平台播放器，第三步任何方式都不得下載影片/音訊檔案（ffmpeg 抽幀只是最後兜底）。禁用方式清單見
references/capture.md。 - cookies 只寫系統臨時目錄、用完即刪，絕不落倉庫，也不要在工作區手放
cookies.txt。 output/不受任何 git 操作影響；成品只發佈到 orphan 分支pages，main只放程式碼。- 校訂稿保真：逐段保留講師原詞與順序，只做 ASR 錯詞替換 + 口癖清理；禁刪段、禁多行、禁大幅改寫（校驗層會直接拒絕）。
- 寫書保真底線：書面化不等於摘要化；保留類比、案例、推導鏈；編者補充必須標註「編者說明」。
- 課程資料版權：講義與幻燈片歸講師（常見 CC BY-NC），書首資訊塊與文末必須保留出處連結、作者署名與許可名。
- 幻燈片覆蓋鐵律：
slides_text.md裡每一頁在書中恰好出現一次，交稿前--audit必須 PASS。 - 刪除大檔案（
audio.m4a、video_source.mp4等）前必須問使用者，得到確認再刪。 - 生成或修改 HTML 時，文字與背景對比度不低於 WCAG AA 的 4.5:1。
- 各步冪等可重跑：佔位符物化前腳本自動備份
book.tagged.md，只要它還在，重跑第三步即可恢復截圖。
交付（第五步要一次性說清）
output/<video_id>/book.md的位置；- 預覽地址
http://localhost:8080/book.html，關閉服務在終端按Ctrl+C； - YouTube 影片需瀏覽器能存取 YouTube（代理），B 站影片可直接看；
- 截圖清晰度取決於
.capture-profile/裡登入帳號的檔位；要更清晰就換帳號登入後重跑第三步； - 用了課程官方資料時，說明書中幻燈片插圖是官方 4K 渲染圖（書首已註明來源與 CC 許可），演示幀仍是影片幀，
course/目錄可整體刪除不影響閱讀； - 詢問是否刪除流程中產生的大媒體檔案（鐵律 9）。
本目錄內容（按需讀取，不要一次性全讀）
| 檔案 | 什麼時候讀 |
|---|---|
references/transcript.md | 第一步抓字幕；平台無字幕要轉本地 ASR |
references/writing.md | 第二步把字幕改寫成 book.md |
references/stitcher-prompt.md | 第二步的排版指令原文（倉庫 prompts/stitcher_system.md 存在時以倉庫版本為準） |
references/course-assets.md | 課程有官方主頁時的第 1.5 步、覆蓋鐵律、幻燈片升級 |
references/correction.md | 生成字幕校訂對照稿與 AI 行級訂正提案 |
references/capture.md | 第三步截幀：優先級、明確禁用的方式、QA 習慣 |
references/publish.md | 第六步發佈到 pages 分支 |
references/troubleshooting.md | 任何報錯、畫質異常、字幕抓不到、提權被拒 |
維護約定
- 本 skill 與流水線程式碼同倉庫版本化：改了
src/*.py的參數、步驟順序或鐵律，必須同步改本目錄。 - 倉庫的
instructions.md與README.md面向人類讀者，保持原樣、不由本 skill 維護， 不要為了讓 skill 生效去改它們；內容與本目錄重疊時，agent 以本目錄為準。 - 同步
references/stitcher-prompt.md時，在檔案頭的來源註記裡更新提交號。 - 他人安裝：
skill-installer用--repo Luke-Evan/videobook --path skills/videobook； 或 clone 後把本目錄複製/軟鏈到~/.codex/skills/（僅 Codex）或~/.agents/skills/（跨 agent）。 - 本目錄不含 cookies、登入態、
output/產物或任何媒體檔案，可安全公開散佈。