xiaoge_distill 兩日產出 · 使用者手冊

1本次完成了什麼

權證小哥知識蒸餾線從 Gooaye 專案搬出成為獨立 repo，並把當日暴露的四個同型缺陷全數修掉、流程收斂成可重複執行的 skill。

起點是一個放量請求：把《哥有籌必爆》從 6 集試跑放大到全部 56 集。放量本身成功了——但過程中同一種缺陷在四個不同階段各爆一次，暴露出這條管線真正的弱點不在功能，而在錯誤處理的爆炸半徑。

核心問題：單一項目失敗會連坐整批

當某個共通原因讓每一項都失敗時，逐項容錯的迴圈會忠實地把每一項都記成失敗、燒光重試額度——幾秒內整個佇列進入終態，需要人工把整份 manifest 復原。

修正前

yt-dlp 不在 PATH → 49 集重試額度在幾秒內全數燒光
擷圖為永遠拿不到的集數各下載 200MB 影片
尾段最後一秒取不到畫面 → 同集已成功的 35 張全部作廢
LLM 全數卡片被丟棄仍標記完成 → 空結果固化、該集永久消失

修正後

連續失敗達 3 次即停機，爆炸半徑限制在少數幾集
終態集數直接排除於擷圖佇列之外
尾段餘數不足 3 秒不補幀，已成功的圖保留
有產出但全被丟棄 → 退回佇列重跑，下次自癒

四道機械防線

防線	判定	行為
`MAX_CONSECUTIVE_FAILURES`	WARN	連續 3 次一般失敗 → worker 自行結束，其餘維持 pending
`UNWEAVABLE_STATUSES`	PASS	終態集數不進擷圖佇列，不下載影片
`MIN_TAIL_REMAINDER_SEC`	PASS	餘數 < 3 秒不補尾幀，避免整集作廢
`DailyQuotaExceeded`	FAIL	額度用盡 → 攔在逐集容錯之前、乾淨結束，一集都不記失敗

其他主要變更

專案搬遷獨立：366MB 資料以檔數＋總位元組雙重比對搬遷，彙整實跑數字與搬遷前逐項一致。
時間戳不再採信 LLM 自報：改由引文在逐字稿的實際定位推導，修掉「卡片指向不存在截圖」的問題。
LLM 設定收攏：模型正本單一化為 gemini-3.1-flash-lite，每日 100 次呼叫上限採預約制。
PR #196 合併回 Gooaye：youtube_transcribe.py 有了唯一正本，含地端 model_size 簽名修正與迴歸測試。
series 欄位與單支影片入口：支援非播放清單的其他系列影片。

品質佐證：目前共 3,082 項測試（2026-10-26 pytest --collect-only 實測；舊值 2,465 項（10-16）、1469 項，當時全綠；python -m pytest tests/ -q；本手冊產出當下為 310 項）。每道守衛皆做過反向驗證——拔掉修正確認測試轉紅、還原後再綠。手冊規模（2026-10-26）：影片 57 集全數萃取、五來源（影片 769＋教材 63＋課程 142＋PPA 訂閱 351＋外部筆記 11）共 1,336 張規則卡 → 1,024 條唯一規則（904 條判斷規則＋120 條基礎知識）、187 條跨來源／重複提及（mention_count≥2，舊值 138）、2,628 張幀圖、影片引文驗證通過 97%（746／769 張；全來源 1,336 張中 1,226 張通過）（2026-10-25：1,102 卡 → 870 規則、138 條重複；2026-10-13：1,080 卡 → 850 規則、137 條重複；2026-10-01：四來源 963 張規則卡 → 764 條唯一規則、120 條跨來源重複、97%；10-01 處置神器課程併入前：926 卡 → 736 規則、113 條跨來源重複；09-30 會員 17 集重萃前：863 卡 → 717 規則、83 條跨來源重複、96%）。（產出當下：40 集、653 卡 → 572 規則、49 條跨集重複、2,306 幀圖。）

2產出清單、存放位置與範圍

重點先講：本次沒有任何全域產出。所有東西都在專案內或該專案專屬的記憶目錄，不會自動套用到你的其他專案。

產出	檔案 / 位置	範圍
五階段管線程式碼	`D:\xiaoge_distill\scripts\xiaoge\`（8 支）	專案內
測試	`D:\xiaoge_distill\tests\unit\`（310 項）	專案內
手冊成品	`D:\xiaoge_distill\data\xiaoge\notes\`（五篇 MD）	專案內
專案指南	`CLAUDE.md`、`README.md`、`CHANGELOG.md`	專案內
設計與實作計劃	`docs\plans\`（雙來源設計、實作計劃）	專案內
解說頁 / 計劃頁 / 本手冊	`docs\*.html`	專案內
pipeline skill	`D:\xiaoge_distill\.claude\skills\YT影片線-pipeline\`	專案內 · 只在本專案可用
專案記憶（2 則）	`~\.claude\projects\D--xiaoge-distill\memory\`	此專案專屬
PR #196	Gooaye repo · merge `35982ac`	另一個 repo · 已進 master

是全域的嗎？不是。全域檔 ~\.claude\CLAUDE.md 與 ~\.claude\skills\ 本次完全沒動。/YT影片線-pipeline 放在專案的 .claude\skills\，只有在 D:\xiaoge_distill 開 session 時才會出現；記憶檔也是專案專屬。若哪天想讓某條經驗跨專案生效，要另外寫進全域 ~\.claude\CLAUDE.md。

順帶修正的一件事搬遷後記憶檔仍掛在 Gooaye 專案底下，新專案的 session 載不到。本次已搬到 D--xiaoge-distill 並拆成兩則（環境與缺陷模式／決策與待辦），Gooaye 端只留一行指路。

3對未來開發的幫助

可複用的技術範式

先問爆炸半徑：新增任何批次階段前先問「這裡單一項目失敗，會不會連坐整批？」四個缺陷都是同一個盲點的不同外衣。這個問句可以直接搬到任何逐項處理的管線。
例外型別即是分流：DailyQuotaExceeded 刻意不繼承 RuntimeError，因為呼叫端的逐項容錯多半寫 except Exception。兩個 except 的順序就是防線本身——順序寫反等於防線不存在。
存在 ≠ 完整：判斷「處理過了嗎」一律看內容不看旗標。逐字稿驗字數、幀圖驗非 0 byte、規則卡驗非空陣列——讓空的項目下次自癒，而不是把空結果固化。
不採信 LLM 自報的事實：能由既有資料推導的（時間戳、頁碼），就自己算並覆寫 LLM 的宣稱。寧可沒有時間戳，也不要一個看起來合理但錯誤的。
耗時操作必須在鎖外：檔案鎖有過期機制，把數分鐘的網路呼叫包進鎖內，鎖會被另一個 worker 判定過期搶走——比沒鎖更糟。

流程教訓

反向驗證不是形式：宣稱守衛有效前，把它拔掉、確認測試轉紅、再還原。本次每道防線都這樣驗過，其中一次驗出「測試通過只是因為 fixture 剛好沒觸發」。
資料完整性要同時比檔數與總位元組：只比檔數對「檔案還在但內容被清空」完全盲目。
狀態旗標會騙人：全量跑完後做內容層複驗，抓到一集標記完成、規則卡卻是空的——從狀態完全看不出來。
環境相依要寫進工具，不要靠記憶：兩個直譯器不可混用、ffmpeg 必須用靜態 binary、長批次要起獨立行程——這些都寫進 skill 了。

想變成全專案通用？上面「可複用的技術範式」前三條其實適用於任何資料管線。若要讓它們在所有專案生效，需寫進全域 ~\.claude\CLAUDE.md；目前只寫在本專案的 CLAUDE.md 與專案記憶裡。

4你如何使用這次成果

日常操作只需要記一個指令。其餘（守衛、額度、內容複驗）都是自動生效，不用手動介入。

A. 自動生效，不用做任何事

四道防線在每次跑管線時自動運作。看到 worker 提早結束並印出「連續失敗達上限」，那是防線正常工作——先查環境，不要急著重設狀態重跑。
每日 100 次 LLM 額度自動計數、換日歸零。撞到上限會乾淨結束，隔天原地續跑。
模型已是 gemini-3.1-flash-lite，不需手動指定。

轉錄→ 擷圖→ 圖文編織→ 規則萃取→ 彙整手冊

深色標記＝本次有防線或設定變更的環節。

B. 加一支新影片（最常用）

在 D:\xiaoge_distill 開 session，直接用 skill：

/YT影片線-pipeline https://www.youtube.com/watch?v=xxxxx

它會問系列名（如「兆華艾綸說」），然後跑完五階段並回報。若要補播放清單的新集數，不帶參數即可；只想看進度用 --status。

C. 手動驗證（想自己確認時）

# 測試
python -m pytest tests/ -q

# 今日 LLM 額度還剩多少
./.venv/Scripts/python.exe -c "import sys; sys.path.insert(0,'scripts/xiaoge'); import llm_config as lc; print(lc.remaining(), '/', lc.DAILY_CALL_LIMIT)"

# 手冊規模
./.venv/Scripts/python.exe -c "import json,sys,collections; sys.path.insert(0,'scripts/xiaoge'); import paths; c=[x for f in paths.resolve('rule_cards').glob('*.json') for x in json.load(open(f,encoding='utf-8'))]; print(len(c),'卡 →',len(collections.Counter(x['rule_id'] for x in c)),'條規則')"

兩件事要留意

金鑰：.env 需有 GOOGLE_API_KEY（萃取）與 GROQ_API_KEY（雲端轉錄）。缺 groq 只會降級成只用地端，不會中止。
舊 worktree 還在：<使用者目錄>\gooaye-xiaoge 與分支 feat/xiaoge-knowledge 是搬遷安全網，待你確認新專案跑順後才刪。清除當下務必重掃 reparse point——git worktree remove 與 robocopy /MIR 都會穿透 junction 刪進目標。

5附錄速查

關鍵常數

名稱	值	擋什麼
`MAX_CONSECUTIVE_FAILURES`	3	環境故障燒光整個佇列的重試額度
`MIN_TAIL_REMAINDER_SEC`	3	尾段取不到畫面害整集擷圖作廢
`DAILY_CALL_LIMIT`	100	LLM 每日呼叫超支
`QUOTE_VERIFY_THRESHOLD`	0.8	≥ 此值標記引文已驗證
`QUOTE_REJECT_THRESHOLD`	0.5	< 此值整張卡丟棄（幻覺）
`QUOTE_MIN_ANCHOR`	8	0.5–0.8 之間的引文，命中處要有這麼多字與逐字稿連續相同才保留（2026-09-25）

名詞白話

manifest：記錄每集處理到哪一階段的唯一狀態正本。所有階段都只跟它對話，所以中斷後能續跑。
規則卡：一條可重用的交易判斷邏輯，含條件、動作、理由，以及可回溯的原話、時間戳與截圖。
mention_count：同一條規則跨幾集被講過。講得越多代表越核心，各篇依此排序。
members_only：YouTube 頻道付費會員限定的集數，永遠拿不到。與「失敗」刻意分開標記。

下一步（已規劃未執行）

/教材線-pipeline：把 PDF 教材走同樣流程。計劃已定案於 docs\plans\2026-08-02-pipeline-implementation-plan.md。
兩條線各自成熟後，才規劃「跨來源 mention_count」；再之後才思考「量化交易判斷規則」。順序不可跳。