Agent 事故教訓庫
> W2-A4 交付物。真實踩過的坑，格式：症狀 → 根因 → 修復 → 預防檢查項。用途：(1) 月檢的檢查清單來源 (2) 對外「我們怎麼管自己的 agent」的實戰素材 (3) 新 agent 上線前的風險對照表。
1. Skill 自動覆寫人工編輯
症狀：auto-commit skill 把未完成的 PR 合進 main，破壞主分支；人工編輯的 skill 內容被自動改寫覆蓋。
根因：Hermes 自我改進機制會自動精煉 skill，沒有「人工編輯鎖」；skill 內含的隱藏錯誤假設（只改 develop 分支的規則）被遺漏。
修復：重要 skill 改寫後人工 review；對關鍵 skill 設防護（不自動覆寫）。
預防檢查項：月檢時比對 skill 修改時間與上次 review 時間；skill 有無被自動改寫紀錄。2. cronjob update model/provider 不生效
症狀：用 cronjob action=update 改 model/provider，job 實際執行仍用舊模型。
根因：cron 工具的 update 對 model/provider 欄位不生效（工具限制）。
修復：直接編輯 /opt/data/cron/jobs.json 改欄位。
預防檢查項：改 model 後確認 jobs.json 實際內容；月檢抽查 model 欄位與 config 預設是否一致。3. VPS 崩潰 restore 抹除記憶與報告
症狀：VPS 連續三天崩潰，restore 8/4 backup 後，任務變形蟲報告原始檔、相關對話、memory 全部消失；Drive 備份也沒有。
根因：備份策略只靠 VPS 快照/本機，未 push 到 GitHub；重要產出沒有異地副本。
修復：重建報告（撈 git 歷史）；確立「重要產出必 commit + push GitHub」鐵律；gdrive 備份改 md5 manifest。
預防檢查項：重要產出當天是否已 push；restore 演練是否定期做。4. 早上 9 點 VPS 崩潰：nginx 舊設定佔 port 80
症狀：每天上午 containers 掛掉、HTTPS 全掛（Traefik Restarting 崩潰循環）。
根因：/etc/nginx/sites-enabled/openmontage-worker 舊設定 listen 80（server_name 是主機名），與 Traefik 搶 port 80。
修復：移出 sites-enabled；nginx 只聽 8090。
預防檢查項：ss -tlnp | grep ':80 ' 確認只有 Traefik；月檢檢查 nginx sites-enabled 內容。5. Terminal guard 崩潰（embedded null char）
症狀：含 python3 -c "..." 或「絕對路徑腳本 + 分號」的命令被 lifecycle guard 擋下，報 embedded null char 錯誤。
根因：guard 對內嵌命令與分號組合的解析 bug。
修復：cd 到專案目錄後用單一相對路徑命令（python3 script.py），或寫 script 檔執行。
預防檢查項：複雜 shell 命令一律先寫成 script 檔。6. YouTube VPS IP 被封
症狀：免登入抓不到字幕（transcript RequestBlocked / yt-dlp LOGIN_REQUIRED）。
根因：VPS IP 被 YouTube bot-block。
修復：請用戶貼內容；youtube-transcript-api 新版用 .fetch() 實例方法。
預防檢查項：抓取失敗時先判斷是否 IP 封鎖，不要重試撞牆。7. VPS Chromium 中文 PDF 亂碼
症狀：VPS 生成的 PDF 中文全變亂碼。
根因：容器缺中文字型（fonts-noto-cjk）。
修復：安裝字型後嵌入字體（2MB+ 才正常）。
預防檢查項：任何 VPS PDF 產出前確認字型；產出後抽看一頁。8. Cron script 內 npx 卡互動（timeout 1hr）
症狀：cron script 內跑 npx xxx 卡住 1 小時後 timeout。
根因：無 stdin 環境下 npx 的安裝確認互動提示卡住。
修復：npx 一律加 --yes。
預防檢查項：script 內所有 npx 確認有 --yes。9. Google Drive 備份漏傳 119 檔
症狀：備份用 git diff 判斷變更，漏傳 119 個檔案。
根因：git diff 無法正確反映所有變更（非 ASCII 檔名、untracked 等）。
修復：改用 md5 manifest（.gdrive_backup_manifest.json）比對變更；完整性驗證用 gdrive_backup_verify.py。
預防檢查項：備份後跑 verify；月檢抽比 manifest 與實際檔案數。10. .env 的 PYTHONPATH 陷阱
症狀：把 PYTHONPATH 加到 .env 無效。
根因：dotenv 在 Python startup 後才載入，對 sys.path 太晚。
修復：用 wrapper script 在啟動前 export PYTHONPATH。
預防檢查項：環境變數生效時機一律用 wrapper script 驗證。11. hermes config set mcp_servers OVERWRITE
症狀：hermes config set mcp_servers '{...}' 把整個區塊覆蓋，其他 server 全消失。
根因：config set 對 dict 型欄位是整塊覆寫。
修復：JSON 須包含所有既有 server；或直接編輯 config.yaml。
預防檢查項：改 config 前備份；改後確認其他區塊未遺失。12. Firecrawl rate bucket 共用（429）
症狀：一次並行丟 5 個 web_search 就 429（"Consumed (req/min): N / Remaining: 0"）。
根因：web_search 與 web_extract 共用同一個 Firecrawl rate bucket（~11 req/min）。
修復：單批呼叫維持 2-3 個以內；429 錯誤訊息含 reset 時間戳，sleep ~50s 後重試。
預防檢查項：研究任務批次化；429 當作正常節流而非失敗重試。13. X Basic API 限制
症狀：xurl recent search 只回 7 天資料；min_faves 參數 Basic 方案不可用。
根因：X API Basic 方案的權限限制。
修復：搜尋策略避開 min_faves；7 天內資料為主；雙數日閘門節省額度。
預防檢查項：X 查詢設計符合 Basic 權限；每月額度追蹤（~45 次/月）。14. 電子報期數標錯
症狀：W30 期標題寫「第 30 期」實際是第 7 期；emoji 混用；HTML title 帶 emoji。
根因：期數 ≠ 週數，人工/自動生成時直接拿週數當期數。
修復：建立統一對照表（newsletter-issue-metadata skill）；emoji 統一 🦞；HTML title 不帶 emoji。
預防檢查項：發送前對照期數表；HTML title 檢查。15. read_img_vision.py 硬編碼誤讀
症狀：圖像 QA 讀到舊圖內容（誤判）。
根因：script 硬編碼讀 /tmp/img_b64.txt，殘留舊圖未清。
修復：一般圖像 QA 自行 inline base64 呼叫，不用該 script。
預防檢查項：vision script 使用前確認輸入來源。16. Next.js static export 中文 slug 404
症狀：Build 成功但所有中文 slug 頁面 404（英文 slug 正常）。
根因：Next.js 16.2.9 Turbopack 對 output: export + generateStaticParams 的 CJK slug 編碼 bug。
修復：slug 改 ASCII-safe hash；或降級 Next.js 15。
預防檢查項：發布含中文 slug 的頁面後逐一 curl 驗證。
用法：新 agent 上線前對照「預防檢查項」；月檢時抽查；對外文章引用時挑 3-4 筆最具故事性的。