疑難排解與速查
卡住、出錯、忘記名詞的時候開這頁查。查完就關，繼續回「製作影片實戰流程」工作。
0卡住怎麼辦（給你 & 給 AI 的規矩）
- AI 回報某步驟失敗 → 它會告訴你「死在第幾步、錯誤訊息、建議怎麼修」。你通常只要回一句「照你建議的修，然後重錄」。
- 同一個地方 AI 試 3 次還不過 → 停下來，記下現象，回報 Raymond。不要讓 AI 無限重試（浪費額度）。
- 影片內容錯了（演錯步驟、字幕怪） → 改
01-draft.md或02-outline.md的文字，重新叫 AI 產。 - 系統本身壞了（不是影片問題） → 例如按鈕點了沒反應、頁面 500，這是產品 bug，回報 Raymond，不是你這邊能修的。
判斷「叫 AI 再試」還是「回報 Raymond」的簡單原則：影片/程式層的問題（selector 找不到、字幕怪、錄到一半掛）先讓 AI 修；產品本身壞了（頁面錯誤、按了沒反應）或 AI 試 3 次還不過，就停下來回報。
1常見症狀速查
「誰處理」欄的意思：你自己＝照「怎麼辦」做就能解，不用麻煩任何人；叫 AI 修＝把症狀（或整段錯誤訊息）貼給 AI，它會自己查程式修；先等＝不是故障。任何一條照做後還是不行，就回到上面的規矩——AI 試 3 次不過或疑似產品本身壞了，回報 Raymond。
| 症狀 | 多半是什麼 | 誰處理 | 怎麼辦 |
|---|---|---|---|
| 影片變成「未登入」畫面，或錄影一開始就說「找不到 XX 角色的登入狀態」 | 該角色的登入狀態沒存過、或存過但過期了 | 你自己 | 重跑 npm run auth:save -- --role <角色>（見「環境準備」第 5 步） |
npm run ... 說找不到指令 |
不在專案資料夾下 | 你自己 | 先 cd 到 compliance-manager-test 再打指令 |
| 錄影說找不到章節 / tag | tag 拼錯，或章節的程式檔不在該在的資料夾 | 你自己 | 跟 AI 要正確的 @chapter-... tag，照它給的貼；照貼還是找不到就整句錯誤丟給 AI 查 |
| 冒煙測試過了、正式錄影的導覽卡位置卻不對 | 冒煙會跳過導覽視覺，本來就驗不到 | 叫 AI 修 | 正常現象；把「第幾秒、哪張卡不對」講給 AI 修 |
| AI 錄到一半停住很久 | 完整錄影本來就要 5-10 分鐘 | 先等 | 超過 15 分鐘再問 AI 狀況 |
AI 回報一串紅字，裡面有 ... is not a function |
程式檔開頭少了必要的標記 | 叫 AI 修 | 把整段錯誤貼給 AI（它會補 @showcase 標記） |
| 錄影卡在登入那一步不動，最後說等不到（Timeout） | 產品的登入頁改版了，自動登入的程式還沒跟上 | 叫 AI 修 | 跟 AI 說「存登入狀態時卡在登入頁」，它會對照最新頁面修 |
| 影片裡說明卡片一閃一閃、還沒讀完就消失 | 程式控制顯示時間的 bug | 叫 AI 修 | 講「第幾秒的說明卡在閃」 |
| 兩張全螢幕投影片之間畫面黑一下 | 程式切換投影片的 bug | 叫 AI 修 | 講「第幾秒兩張全螢幕中間有黑屏」 |
| 影片右邊（或下面）有一條黑塊 | 錄影解析度設定跑掉了 | 叫 AI 修 | 直接把症狀講給 AI |
| 影片演「新增 XX」時系統跳出「名稱已存在」 | 之前錄影留下的舊資料跟這次要建的同名 | 叫 AI 修 | 跟 AI 說「錄影時名稱撞名」，它會改成自動編號避開 |
| 錄完發現系統裡多了兩筆同名資料 | 冒煙＋正式各跑了一次，各建了一筆（冒煙只跳過視覺，操作是真的跑） | 叫 AI 清 | 正常現象；跟 AI 說「把錄影多建的那筆刪掉」（自己進頁面刪也行） |
更多疑難雜症（給 AI 看的技術層排查）在
training/sop/producer-guide.md的「常見故障與排查」。你不用讀它——AI 卡住時提醒它去讀就好。
2完整文件地圖（要深入時再看）
這個站是「入門」，下面是權威細節，做熟了再翻：
| 文件 | 什麼時候看 |
|---|---|
training/README.md |
想看整體資料夾結構、Act 索引 |
training/sop/producer-guide.md |
權威製作指南，含當前進度、所有踩過的坑 |
training/sop/workflow.md |
七階段工作流程細節 |
training/sop/chapter-authoring-protocol.md |
AI 接手時照這份做（工具無關） |
training/sop/markup-language.md |
大綱裡 [字幕][說明][全螢幕] 這些標記的意思 |
training/guides/training-style-guide.md |
旁白用詞、字級、節奏規範 |
training/guides/training-video-production.md |
把多支章節合成一支完整課程片 |
.claude/commands/training-chapter.md |
/training-chapter 指令的完整定義 |
名詞速查
| 名詞 | 白話解釋 |
|---|---|
| 章節 / chapter | 一支 3-8 分鐘的教學影片單位 |
| 三件套 | 每章的 draft / outline / status 三個檔 |
| draft | 白話腳本（你出需求、AI 起草） |
| outline | AI 把 draft 整理成的結構化大綱 |
| feature 檔 | AI 寫的自動化程式（你不用碰） |
| overlay / 教學視覺 | 疊在影片上的字幕、說明卡片、高亮框 |
| record / 錄影 | 讓瀏覽器自動照腳本操作並錄成 mp4 |
| 冒煙測試 / smoke | 跳過教學視覺、只驗流程跑不跑得過的快速測試 |
| auth state | 存好的登入狀態，讓影片不用每次演登入 |
| Act | 一「幕」，一組相關章節（PM 旅程、稽核旅程…） |
| 首腦 / 小弟 | 都是 AI：首腦拆工派工管進度、小弟執行分到的段落 |
| 終端機 / Terminal | 跟電腦用打字下指令的視窗 |
| session | 一個 AI 對話視窗；多 session＝同時開好幾個 AI 分頭做事 |