cassieliang6709/tech-explainer-video

技術解說影片

三道關，每關都要使用者明確說「可以」才進入下一關。使用者全域設定裡的「不用確認直接做」不適用於這三道關，這是使用者為這個 skill 特別要求的審閱流程。使用者說「先別配音/先別做」就停在當前階段。

預設值（使用者沒說就按這個，寫進 script.md 的 front matter）：

• 受眾：會 Python、相關課程基本忘光了的大學生。寫法按 references/kepu-style.md：先具體後抽象，「如果讓你來設計」，一張物理圖貫穿全片，每集新術語不超過 6 個；暫存器、原始碼級細節放進每集末尾的「進階」章
• 目標：看完能用 PyTorch 寫出來
• 結構：三部分，數學原理 → 要用到的 PyTorch 工具 → 統一 coding
• 每集內部用「總—分—總」：開頭先給本集要回答的問題和小節地圖，主體逐節展開（畫面角落顯示路線圖、當前小節高亮），結尾每節一句話收回結論再預告下一集
• 時長：每集 8–12 分鐘（2026-10-24 使用者改：集數少、投稿少、不易撞平台限額），一個主題通常 2 集，最多 3 集
• 比喻：允許，但只講一個點：一句話講完馬上回到正題，一個概念最多一個（kepu-style.md 第 5 條）
• 音色：voice: volc（火山引擎預設音色 zh_female_vv_uranus_bigtts）；~/.volc_tts.env 缺憑證時 tts.py 自動退回 edge-tts 曉伊並提示

階段 0：收集材料

使用者提到筆記（如 Obsidian）就先找到並通讀，以筆記的結構、結論和數字為準。

階段 1：大綱（在對話裡給）

第一行寫一句話立項：「這期讓 X 的人看完能 Y」。每集再給一行封面鉤子 + 右側視覺（見 references/cover-guide.md），和大綱一起審。 按 references/outline-template.md 寫簡短表格：每章要解決的問題、新概念、落地的程式碼、時長，以及分集方案和不講的內容。 先讀 references/kepu-style.md。開頭、節奏、術語和結尾按 references/script-guide.md 裡的「開頭公式」「節奏」「術語與門檻」「結尾公式」來設計；大綱裡就標出每個高潮點放在哪一章。 寫數學部分時，先給出要計算的目標（例如 out_i = Σⱼ aᵢⱼ vⱼ），再推出每個組件，讓點積、softmax、縮放都是「被需要才出現」。

階段 2：程式碼 → 逐字稿 → 檢查 → 批註 → 定稿

寫稿原則：先講設計動機，再講機制，最後講結果。優先講清「原來遇到什麼問題 → 設計者想解決什麼 → 為什麼選這個辦法 → 它如何工作」。允許補步驟、例子和必要的精確性，但每次只引入理解當前原理所必需的新概念；新術語第一次出現時，用已有知識或具體例子解釋。進階章按該章預設的知識基礎調整。

1. 寫教學程式碼 py/tutorial.py 並真實執行，用 show(key, value) 導出 py/values.json。螢幕上的所有數值、形狀、True/False 都從這裡來。
   • 小例子要有可解釋的含義時，手工設定權重，程式碼註解和旁白裡都說明「手工設定，真實模型靠訓練」。
   • 演示「為什麼」時用真實對照：例如結合律有無 softmax 的 allclose、縮放前後 softmax 雅可比範數。
2. 按 references/kepu-style.md 和 references/script-guide.md 寫 script/script.md（格式見下），過一遍兩份自查清單。 每句「畫：」寫清觀眾要看到的變化，以及這幅畫幫助理解什麼；先確定表達目標，不鎖定製作工具。畫面可用網頁畫布、Remotion、Manim、Blender 或更合適的工具實現，具體在定稿後按鏡頭選擇。需要用到數值、程式碼或形狀的畫面仍須與 py/values.json、py/tutorial.py 一致。 按集核時長：每集編號行字數 ÷ 4.5 ÷ 60，再加約 0.5 分鐘章節卡和停頓，超過 12 分鐘就在這一步調整分集（不要等配完音才發現超長）。
3. 完成初稿後，依序做零基礎檢查、事實核對和語言潤色： 3b. 零基礎門檻檢查（必做）：另起一個 agent，只給它 script.md 和一句設定「你會寫 Python，本主題的課基本忘光了」， 不給程式碼、不給筆記。讓它逐句標出：①聽不懂的詞或推理跳步；②一句中引入太多新東西、需要倒回去重看的地方；③畫面描述和旁白對不上的地方。 要求指出具體缺哪一步解釋，尤其檢查能否順著「問題 → 設計動機 → 機制 → 結果」聽懂。可以建議補步驟、例子或必要的精確性，但不要為補細節引入與主線無關的新概念。逐條修改後，用相同條件再檢查，直到沒有①②類標記；③類也須修正。記錄修改清單，發稿時一併給使用者。進階章按該章預設的知識基礎檢查。 3c. 事實核對（必做）：另起一個 agent，給它 script.md 和筆記，只標事實錯誤或會造成錯誤理解的說法，並說明依據；不要求補充知識點、邊界條件或額外細節。允許教學性簡化；如果觀眾可能把簡化說法當成嚴格定義，就在旁白裡簡短說明「這裡做了簡化」。修正時優先換成同樣簡單但準確的說法，不堆限定語。與 3b 衝突時，尋找既準確又好懂的表達；不能保留事實錯誤，也不要讓精確性蓋過講解主線。事實修改影響了理解或畫面時，重做相應的 3b 檢查。 3d. 用 humanizer-zh skill 逐句潤色編號行和「讀：」行（去 AI 味）。保留數值、術語、程式碼和「畫：」行的含義，不擅自增刪知識點。潤色後複核程式碼結果、畫面描述和旁白是否一致，並重新核算每集時長。
4. 把檔案發給使用者（SendUserFile），請使用者在句子下面用 > 開頭寫批註（Obsidian 的 > [!批註] 也行）。 想在 Obsidian 裡批註就複製到使用者 vault，改完再讀回。
5. 處理批註：逐條改 → 刪掉已處理的批註行 → 在對話裡列出每條怎麼改的 → 再請使用者看，直到使用者說定稿。
6. 定稿前不配音、不製作正式畫面。為驗證複雜鏡頭能否實現，可以做短小樣；小樣不替代逐字稿審閱。

script.md 格式

---
title: Attention → MHA → GQA
subtitle: 從數學原理到 PyTorch 實現
audience: 有一定電腦基礎的大學生
voice: volc
volc_speaker: zh_female_vv_uranus_bigtts
volc_resource: seed-tts-2.0
episodes: ch0,ch1,ch2,ep1_end | ep2_start,ch3,ch4,ep2_end | ep3_start,ch5,ch6
episode_titles: 第一集標題 | 第二集標題 | 第三集標題
---

## ch0 | 開場
1. 字幕原文，一句一個畫面節拍。
   - 讀：TTS 念法（和字幕不同時才寫；符號寫成讀法，讀 háng 的「行」寫成「航」）
   - 畫：這一句螢幕上出現什麼（必填，畫面 agent 照此實現）
> 批註：使用者寫在這裡

## ep1_end | 下集預告
1. 下一集講……
   - 畫：EP1 結束卡

• 章節 id：ch0, ch1, …；分集的片頭/片尾用 epK_start / epK_end，畫面由通用 EpCard 自動生成，新增的句子也要給使用者審。
• 總分總：epK_start 寫 2–3 句：①本集要回答的問題 ②「這一集講 N 件事：……」（與本集的章節一一對應）； epK_end 寫 2–3 句：每章一句結論 + 下一集預告。第 1 集的開場章節（ch0）同樣要包含本地圖。 front matter 的 episodes 決定地圖裡有哪些小節，小節名取各章標題。
• 字幕不用手動拆短，tts.py 會按標點拆成 ≤22 字寬的短條。

階段 3：生成影片

逐鏡頭選擇能把原理講清的製作方式：二維關係、程式碼和數據可用網頁畫布、Remotion 或 Manim；空間結構和鏡頭運動可用 Blender 等三維工具。也可用更合適的新工具，不為使用某個工具增加講解複雜度。現有 template/ 是 Remotion 合成與交付管線；其他工具製作的鏡頭先輸出影片或圖像素材，驗證能接入該管線並保持字幕、配音、節拍同步，再用於正式章節。references/visual-guide.md 和 references/agent-brief.md 中的組件、路徑與命令只適用於 Remotion 章節，其他工具沿用其版式、配色、真實數據和畫面自檢原則。

1. 把 template/ 複製到使用者指定目錄（預設 ~/Videos/<主題>，先問一句），放入 py/、script/。 依賴只裝一份：系列（多個專案放在同一個父目錄，如 ~/Videos/nudgecode-演算法/<章>/）在父目錄裝一次 node_modules（拷一份 template 的 package.json 過去 npm install），各專案 ln -s ../node_modules node_modules；單個專案就在專案裡裝。 npm install 同一時刻只跑一個，並發會把包裝壞。裝完檢查 node_modules/react-dom/index.js 存在（npm 快取裡這個包壞過，缺檔案就從別的專案拷一份同版本的）。
2. python3 tools/md2json.py（有未處理批註會拒絕）→ python3 tools/scaffold.py → python3 tools/tts.py 生成 public/audio/*、src/timeline.json，配音會快取，只重新合成改過的句子。
3. 自己先做開場和第 1 章，確立畫風（先做最難的那個鏡頭；節奏、轉場參考 references/plotome-lessons.md）。Remotion 鏡頭用 node tools/stills.mjs ch1 && tools/sheet.sh ch1 檢查；外部工具製作的鏡頭檢查原素材及接入後的合成幀，把預覽發給使用者看。 系列裡畫風已經被使用者確認過（例如同系列的第一個專案），就不再單獨請使用者看，直接繼續。 stills.mjs 複用 out/bundle（tools/bundle.mjs，原始檔變了才重新打包），不再每次在 $TMPDIR 新建一個 ~90 MB 的打包目錄。
4. 使用者認可後，其餘章節分給多個 agent 在一條訊息裡同時啟動（每個 1–2 章）：
   • Remotion 章節：把 references/agent-brief.md 填好寫成專案根目錄的 AGENT_BRIEF.md，把 references/visual-guide.md 複製成 VISUAL_GUIDE.md。外部工具鏡頭另寫簡短任務說明，約定素材格式、時長、檔案位置和接入 Remotion 的責任，不套用只允許改 ChN.tsx 的限制。
   • 改了旁白就給相關 agent 發 SendMessage，說明哪幾句變了、timeline 已更新。
5. 所有章節回來後，主會話逐章檢查合成幀：重疊、壓字幕、畫面和「畫：」是否一致、數值是否來自 values.json；外部素材還要檢查導入後的時長與節拍。
6. npx tsc 通過後，背景執行 tools/render.sh：逐集輸出 out/epK.mp4 + out/epK.srt + out/covers/epK.jpg，並標準化到 -16 LUFS，每分鐘影片約需 1 分鐘渲染。 渲染期間不要動音訊和程式碼：混音在最後一步才讀音訊，中途覆蓋會把新舊音訊混在一起。 render.sh 用全機鎖（lockf /tmp/remotion-render.lock）保證同一時刻只渲染一集：幾個專案同時渲染不會更快（CPU 已滿）， 只會多佔記憶體和磁碟。多個專案可以同時啟動 render.sh，它們會自動排隊。
7. 封面：按 references/cover-guide.md 每集寫 src/covers/CoverEpK.tsx 並在 src/covers/index.ts 登記（黑底、鉤子大字 + 黃底高亮、右側大視覺）；render.sh 會自動出 out/covers/epK.jpg，沒登記的集用兜底版。把所有封面拼成一張圖發給使用者看。單獨重出：npx remotion still out/bundle cover-epK out/covers/epK.jpg。
8. 交付：用 SendUserFile 發各集 mp4、srt、封面和 py/tutorial.py。請使用者自己讀一遍 srt，往往能發現問題。
9. 需要發佈時，轉到 video-publish skill。發佈前過一遍 references/plotome-lessons.md 的合規清單（AI 標註、音樂授權、署名）。

系列批次製作（多個專案並行）

• 同時開的 session 控制在 3–4 個：開太多會很快撞到用量上限，火山 TTS 也會報並發超限（tts.py 已帶退避重試、並發 2）。
• 並行只放在寫稿和做畫面；渲染交給 render.sh 的全機鎖排隊。
• 磁碟：每章 out/bundle 約 90 MB，截圖 out/check 幾十 MB，成片每集十幾 MB。開新一批前看一眼 df -h， $TMPDIR/remotion-webpack-bundle-* 是舊版腳本留下的臨時打包，可以清。
• 使用者同意「渲完一批 → 直接上傳 → 刪成片」時，見 video-publish 的「批次流水線」。

主會話調度流水線（知識庫 2026-10-30 ~ 11-03 跑通，兩篇一批）

1. 寫稿階段 agent（每篇一個，兩篇同時）：大綱 → tutorial 真實執行導出 values.json → 逐字稿 → 零基礎檢查（另起 agent，最多 8 輪，之後按最後一輪全改）→ 事實核對（另起 agent 對照筆記）→ humanizer → 按集核時長 → 複製 template、軟鏈 node_modules → md2json / scaffold / tts → 寫 AGENT_BRIEF.md、VISUAL_GUIDE.md、共享物理圖部件 src/lib/<名>.tsx（先定佈局常數）→ 做 ch0、ch1。彙報裡要列「筆記與實測不符處」。
2. 主會話看 ch0/ch1 拼圖，畫風沒問題就繼續，不再等使用者。
3. 畫面 fan-out：把 references/agent-brief.md 填成一份共享 brief 寫到 /tmp/claude-501/brief_<篇>.txt（第二篇用 sed 換路徑/部件名/鎖名再追加「本專案補充」）， 每個 agent 的 prompt 只有一句「先用 Read 完整讀 brief 並嚴格照做，你負責 chX、chY」，每個 2–3 章，封面交給最後一個 agent。一條訊息裡同時啟動。
4. 收集已知問題：每個畫面 agent 回來時，把它報的「已知問題 / 不在 values.json 的數 / 改後未復看」記下來。
5. 全片複查 agent（每篇一個，模板 references/review-brief.md）：把第 4 步彙總的問題逐條寫進「已知待修」。
6. 渲染：兩篇各自背景起 tools/render.sh，全機鎖自動排隊；用一個背景 until 迴圈等 out/ep3.mp4 出現。
7. 抽查（主會話自己做，不信報告）：每集 ffmpeg -af volumedetect（正常 mean 約 −19 dB、max ≤ −1.2 dB）； 每篇取一集 -vf "fps=1/60,scale=480:-1,tile=4x3" 拼一張網格用 Read 看；確認 out/covers/ 三張都在。
8. 上傳：out/parts/P<k> <鉤子>：<主題>.mp4 硬連結 + out/upload_meta.md（含簡介補充一段），再按 video-publish 的「追加到已有稿件」排隊。傳完更新 PROGRESS.md 和看板，把簡介段落發給使用者。

撞用量上限 / 中斷

• 用量上限會把正在跑的 agent 全部殺掉。恢復後用 SendMessage 給每個 agent 發「繼續」，它帶著上下文接著做；不要重開新 agent（會重複勞動、互相覆蓋）。
• 同時在跑的 agent 控制在 ~12 個以內（兩篇 × 5–6 個畫面 agent）。

筆記與實測不符

• 知識庫筆記（vault）唯讀。實測和筆記對不上時，影片按實測講，在彙報裡逐條列給使用者，由使用者決定是否改筆記。

定稿後再改

• 改旁白：改 script.md → md2json → tts（只重新合成改過的句子）→ 檢查受影響章節的畫面。
• 句子數變了會讓畫面錯位：已經做好畫面的章節盡量只改措辭，不增刪句子；要加內容就加成新的一句章節（如 epK_start）。
• 畫面 agent 只按 visual 實現，有疑問向主會話彙報，不自行改旁白。

音色

• 火山引擎預設音色（預設，voice: volc）：zh_female_vv_uranus_bigtts，資源 seed-tts-2.0，GQA 那期使用者選定的，效果明顯好於 edge-tts。 front matter 不寫 volc_speaker 就用它。憑證在 ~/.volc_tts.env（已配好），只需要 VOLC_APPID / VOLC_TOKEN；可選 VOLC_SPEED 語速（1.0 正常）。
• 換音色：front matter 寫 volc_speaker: <音色 ID>。預設音色自動用 seed-tts-2.0；S_ 開頭的複刻音色自動用 seed-icl-2.0（或 env 裡的 VOLC_RESOURCE）。 也可以用 volc_resource 顯式指定；寫 v1 走舊版介面，此時可再設 VOLC_CLUSTER（預設 volcano_icl）。
• 使用者的複刻音色（env 裡的 VOLC_SPEAKER_ID，S_ 開頭）目前報 resource ID is mismatched with speaker，要先在火山控制檯確認音色版本、訓練狀態、所屬 appid，跑通前不要用。
• 不列印 env 檔案內容。新專案先 --only 合成一集裡的幾句試聽，再配全片。
• edge-tts（備選）：voice: zh-CN-XiaoyiNeural，其他可選 YunxiNeural、YunyangNeural、XiaoxiaoNeural。火山憑證缺失時 tts.py 自動用曉伊。
• 換音色只需重跑 tts.py，畫面按節拍自動對齊，抽查拼圖即可。

英文配音（2026-11-03）

• edge-tts en-US-AndrewMultilingualNeural：使用者試聽 9 個音色後選定。免費、不用 key，但走的是 Edge 朗讀的非官方介面：會限流/斷連（tts 要重試），條款上商用不明確，介面哪天變了就要換。front matter voice: en-US-AndrewMultilingualNeural。
• 火山 seed-tts-2.0 的 en_male_tim_uranus_bigtts、en_female_dacey_uranus_bigtts 可用（備選）；seed-tts-1.0 的 *_mars_bigtts 英文音色在本帳號 403（未開通）。中文音色 vv 也能讀英文，但口音明顯。
• 試聽：同一段 ~20 秒英文開場白，每個音色出一條 mp3，再用 ffmpeg concat（每條後 apad 1.2 秒）拼成一條合集發給使用者。

中英雙語（試點中）

• 試點專案 ~/Videos/知識庫/llm-13-rag-agent-en：新寫的英文口語旁白（不是中譯英），每句帶中文譯文，底部兩行字幕（上英文、下中文略小），畫面標籤用英文。
• 字幕組件和 md2json 的具體改法等試點做完再寫回這裡和 template。
• 英文版不要追加進中文合集；發佈去處（B 站新稿件 / YouTube）由使用者定。

檔案一覽（template/）

檔案	作用
tools/md2json.py	script.md → script.json（檢查批註、解析分集）
tools/scaffold.py	生成章節佔位組件和 src/chapters/index.ts
tools/tts.py	逐句配音、拆短字幕、寫 timeline.json；支援 edge-tts / 火山引擎
tools/stills.mjs + sheet.sh	每句 80% 處截圖並拼成 3×3 拼圖（SCALE=1 出全尺寸）
tools/render.sh	逐集渲染 + 合併字幕 + 響度標準化
src/lib/beat.tsx	節拍同步（useBeat）、章節標題卡、字幕
src/lib/ui.tsx	CodePanel / Matrix / Fade / Tag / H / Tex（KaTeX 公式）
src/lib/EpCard.tsx	分集片頭片尾卡
src/lib/Cover.tsx + src/covers/	封面部件（CoverFrame / Hl / CodeVisual / BigNumber）+ 每集定製封面登記
src/lib/algo.tsx	演算法類組件：陣列格子、dict、trace 表、題面卡
tools/bundle.mjs	打包一次複用 out/bundle
src/lib/library.tsx	可選：張量「圖書館」比喻組件（Building / Corridor）

參考文件

• references/script-guide.md：逐字稿寫法；outline-template.md：大綱表
• references/visual-guide.md / agent-brief.md：畫面規範、畫面 agent 說明
• references/cover-guide.md：封面規範
• references/plotome-lessons.md：節奏、轉場、音樂、合規（借鑑 plotome）
• references/production-retro-2026-10.md：nudgecode 13 章批次製作復盤，坑和對策
• references/production-retro-2026-11.md：知識庫兩篇一批的調度流水線復盤
• references/review-brief.md：全片複查 agent 模板
• rethinkfun-style.md / cishoon-style.md：使用者喜歡的 UP 主分析

踩過的坑

• macOS say 太機械，用 edge-tts。
• 程式碼和符號要在「讀：」裡寫成讀法；多音字「行」(háng) 寫成「航」。
• 講真實模型的數字前核對它的結構（例如 Llama-2-70B 本身是 GQA，按 64 頭算 10 GB 要說「假設用 MHA」）。
• 隨機初始化的注意力太平均，沒有意義：要嘛手工設定權重，要嘛換隨機種子挑對比明顯的。
• 截圖用 tools/stills.mjs（只打包一次），比 remotion still 快得多；首次渲染會下載 headless Chrome。
• Bash 裡不要寫沒有輸入的 cat > file，會一直等 stdin 卡住。
• 截圖在每句 80% 處：80% 之後才出現的動畫（紅叉、晚出的大字）截不到，要單獨截或把出現時間提前。
• 畫面 agent 並行時，別人章節的語法錯誤會讓 bundle 失敗：等一兩分鐘重試，不要去改別人的檔案。
• 複查 agent 曾「清理」舊截圖：brief 裡必須寫「不刪除任何檔案（截圖覆蓋可以）」。
• 磁碟：每篇專案約 0.5 GB，成片每集十幾 MB；渲染中寫滿會報 No space left on device。開新一批前 df -h，低於 ~15 GB 先列可清的分組（各工具快取、conda clean 等）給使用者選，刪除要使用者同意。
• 章節標題卡和片頭片尾卡每集多出約 10 秒，按 TTS 實測時長 + 10 秒估成片時長。
• 畫面 agent 會順手登記 src/covers/index.ts：這是做封面必需的，允許。
• 背景等待渲染不要用 pgrep -f render.sh：等待命令自己的命令列裡也有這個詞，pgrep 永遠匹配到自己，空轉幾個小時。只等 out/epK.mp4 出現（或日誌裡的報錯）。