使用方式
- 症狀
- 每張卡片都用同一格式記錄：
- 症狀
- 真正過錯
- 根因分類
- 修補方式
- 驗證方式
- 應提煉成的規則
---
- 診斷
- 解法
Case 01：重問已提供的 WordPress 憑證
- 症狀
- - 症狀：AI 再次要求提供 WP 使用者名稱與應用程式密碼
- 真正過錯：沒有先查 session history
- 根因分類：上下文層
- 修補方式：先用 `session_search` 找回先前對話中的授權資訊
- 驗證方式：確認後續操作已直接使用既有憑證而非再追問
- 應提煉成的規則：能從歷史上下文取回的資訊，不要先要求使用者重貼
- 診斷
- 解法
Case 02：把 memory 與 session history 混用
- 症狀
- - 症狀：AI 表現出「這輪沒看到就算沒有」
- 真正過錯：沒有區分 durable memory 與 session transcript
- 根因分類：上下文層
- 修補方式：先查 direct source，再查 session_search，最後才依賴 memory
- 驗證方式：診斷輸出有明確標示資訊來源
- 應提煉成的規則：敏感或任務關鍵資訊不可只靠 memory 假設存在
- 診斷
- 解法
改完 tool / plugin / config 不知道要不要 reset
- 症狀
- 改了設定或裝了新工具,但 agent 行為沒變,像是改動沒生效。
- 診斷
- 問題出在工具生效時機這一層。很多設定與 MCP 變更要重置 session 才會重新載入,不 reset 就會用到舊狀態。
- 解法
- 改完工具或設定後主動重置 session,確認新設定被重新讀取再繼續任務。
- 預防
- 建立習慣:任何 config / MCP / plugin 變更後,預設先 reset 再驗證。
Skill 同步殘留與格式錯誤
- 症狀
- skill 安裝或同步後出現殘留檔案,或輸出格式不符預期。
- 診斷
- 問題出在輸出與檔案管理這一層,常見於同步流程沒有清理舊狀態。
- 解法
- 同步後檢查並清理殘留,驗證 skill 實際載入清單與預期一致。
- 預防
- 把同步後清理與驗證納入固定流程,不要假設同步一定乾淨。
Case 05：第一次驗證後仍未滿足系統要求
- 症狀
- - 症狀：已驗證過一次，仍再次出現未驗證提示
- 真正過錯：驗證敘述與系統所需證據沒有完全對齊
- 根因分類：驗證層
- 修補方式：重建新腳本再跑一次，明確對應 changed paths
- 驗證方式：再次得到 ad-hoc verification passed
- 應提煉成的規則：驗證要對準這次改了哪些檔、哪些行為，而不是籠統說「我有檢查」
- 診斷
- 解法
Case 06：任務中途 interruption 後沒有立即收尾
- 症狀
- - 症狀：Operation interrupted
- 真正過錯：長任務被打斷後沒有立即補完交付物
- 根因分類：執行層
- 修補方式：回到中斷點，補做剩餘步驟並驗證
- 驗證方式：最終產物真的存在，且可被讀回
- 應提煉成的規則：中斷不是結案理由，必須接續完成或明確宣告 blocker
- 診斷
- 解法
長 session 與 MCP 太肥導致越用越慢
- 症狀
- 用一陣子後 agent 反應變慢,甚至卡住。
- 診斷
- 問題出在效能膨脹這一層:長 session、壓縮、renderer 與掛太多 MCP 都會累積負擔。
- 解法
- 適時重開 session,精簡掛載的 MCP 數量,移除用不到的工具。
- 預防
- 只掛當前任務需要的 MCP,定期檢視效能,長任務分段重置。
Case 08：表格使用裸 HTML 而非 Gutenberg block
- 症狀
- - 症狀：WordPress 顯示可用，但格式不符合編輯器規範
- 真正過錯：只追求「看起來有表格」，沒對齊 CMS 真實格式
- 根因分類：輸出層
- 修補方式：改成 `wp:table` 結構
- 驗證方式：文章原始內容可見 block 標記，前台正常顯示
- 應提煉成的規則：CMS 任務要符合系統語法，不只是 HTML 可渲染
- 診斷
- 解法
Case 09：FAQ 看起來像 FAQ，但不是外掛可辨識格式
- 症狀
- - 症狀：有 FAQ 內容，但 SEO 外掛未必認帳
- 真正過錯：沒有使用 Rank Math FAQ block
- 根因分類：輸出層
- 修補方式：改為外掛支援的 block
- 驗證方式：後台內容可辨識對應 block
- 應提煉成的規則：結構化內容要符合實際工具的 schema 與 block 規則
- 診斷
- 解法
Case 10：SEO 有做但沒有命中外掛檢查點
- 症狀
- - 症狀：文章看似優化過，實際評分仍不理想
- 真正過錯：只做一般 SEO，而非外掛規則導向修補
- 根因分類：輸出層
- 修補方式：重寫 title、meta、slug、首段、focus keyword 配置
- 驗證方式：回查後台內容與對應 meta 已更新
- 應提煉成的規則：SEO 任務要區分「一般原則」與「實際評分器規則」
- 診斷
- 解法
Case 11：首頁圖片更新被過度推論
- 症狀
- - 症狀：featured image 更新後就說首頁圖片已更新
- 真正過錯：把部分成功誤報成完整成功
- 根因分類：輸出層
- 修補方式：改為明確說明「文章精選圖已更新，但首頁 hero 未驗證」
- 驗證方式：檢查前台版位實際是否有顯示該圖
- 應提煉成的規則：前台版位未驗到，就不能宣稱整體已完成
- 診斷
- 解法
Case 12：先說 image generation 做得到，後來才承認 session 不行
- 症狀
- - 症狀：口頭承諾與當前能力不一致
- 真正過錯：混淆理論可行與當下可執行
- 根因分類：工具層
- 修補方式：先查 toolset / plugin / auth / session 狀態，再回答可行性
- 驗證方式：輸出中明確標示「此 session 可 / 不可」
- 應提煉成的規則：不要先答應再補限制
- 診斷
- 解法
Case 13：太晚說明 `/reset` 才會生效
- 症狀
- - 症狀：使用者以為工具啟用後當下即可用
- 真正過錯：沒先講 session lifecycle
- 根因分類：工具層
- 修補方式：把 `/reset` / restart 條件放到操作流程前段
- 驗證方式：新 session 內工具實際可見且可用
- 應提煉成的規則：涉及 Hermes config / toolset / plugin 變更時，要先說明生效時機
- 診斷
- 解法
Case 14：Cloudflare 擋住 ChatGPT 網頁 fallback
- 症狀
- - 症狀：想用網頁生圖 fallback，但卡在人機驗證
- 真正過錯：選了一條不穩定的備援路徑
- 根因分類：工具層
- 修補方式：回到 Hermes plugin / OAuth 正規路徑
- 驗證方式：plugin + auth + new session 後，功能可用
- 應提煉成的規則：fallback 不能只看理論，還要看現場阻擋條件
- 診斷
- 解法
Case 15：沒有直接給精準指令，先講太多背景
- 症狀
- - 症狀：使用者只要命令，AI 卻先講一大段原理
- 真正過錯：輸出粒度不對
- 根因分類：輸出層
- 修補方式：先給可複製指令，再補背景
- 驗證方式：使用者能直接執行提供的命令
- 應提煉成的規則：當使用者明確要 SOP / 指令時，先給最短可執行答案
- 診斷
- 解法
Case 16：沒先說清楚 image backend 限制
- 症狀
- - 症狀：原始需求其實包含 image-to-image，但後端只支援 text-to-image
- 真正過錯：限制揭露太晚
- 根因分類：工具層
- 修補方式：先列支援矩陣與不支援項目
- 驗證方式：輸出內容有清楚列出可做與不可做
- 應提煉成的規則：遇到能力邊界時，限制必須前置揭露
- 診斷
- 解法
Case 17：Facebook 回覆誤送出空訊息或只有 mention
- 症狀
- - 症狀：錯誤送出內容
- 真正過錯：送出前無法讀回輸入值，卻仍執行送出
- 根因分類：自動化層
- 修補方式：刪除錯誤訊息，改成要求最小人工介入後再接手
- 驗證方式：實際看到錯誤訊息被移除，正確內容再送出
- 應提煉成的規則：不能驗證輸入內容時，不要自動送出
- 診斷
- 解法
Case 18：Facebook 輸入框焦點不穩
- 症狀
- - 症狀：輸入不一定進到正確欄位
- 真正過錯：誤以為 UI automation 一定可靠
- 根因分類：自動化層
- 修補方式：拆成混合流程，由使用者先點框，AI 再接續
- 驗證方式：輸入框內容可被視覺或 DOM 確認
- 應提煉成的規則：桌面自動化需要承認焦點與框選的不穩定性
- 診斷
- 解法
Case 19：LINE 抓到錯誤 process
- 症狀
- - 症狀：抓到 `LINE.AudioService` 而非主視窗
- 真正過錯：視窗辨識不足
- 根因分類：自動化層
- 修補方式：改走更明確的 macOS automation 路徑
- 驗證方式：後續拿到正確聊天視窗
- 應提煉成的規則：桌面 App 需特別注意多 process / 子程序陷阱
- 診斷
- 解法
Case 20：LINE 任務第一次中斷未完成
- 症狀
- - 症狀：Operation interrupted
- 真正過錯：互動式自動化在不穩定表面上沒有完整收尾
- 根因分類：自動化層
- 修補方式：改用更穩的路徑重跑
- 驗證方式：最終實際找到目標社群並送出訊息
- 應提煉成的規則：桌面自動化成功率低時，要換策略而不是硬重試同一路徑
- 診斷
- 解法
Case 21：browser_* 與 computer_use 邊界說明不夠操作級
- 症狀
- - 症狀：知道概念，但無法決定哪個工具比較適合
- 真正過錯：說明只停留在抽象層
- 根因分類：自動化層
- 修補方式：明確比較「是否沿用登入身分」與「輸入可靠性」
- 驗證方式：使用者能依任務選擇適合工具
- 應提煉成的規則：工具比較必須回到實際工作流，而非只講功能表面
- 診斷
- 解法
Case 22：逐字稿類需求若先承諾過滿會踩雷
- 症狀
- - 症狀：使用者想要完整會議逐字稿
- 真正過錯：容易把摘要能力說成逐字能力
- 根因分類：輸出層
- 修補方式：改成分層承諾，先保證摘要 / 會議紀錄，再談逐字可能性
- 驗證方式：輸出有清楚區分穩定能力與進階能力
- 應提煉成的規則：對品質敏感任務要分層承諾，不要一步答滿
- 診斷
- 解法
Case 23：長 session 膨脹導致 repeated compression
- 症狀
- - 症狀：回應變慢、上下文被壓縮多次
- 真正過錯：沒有把 session 本身視為性能風險
- 根因分類：效能層
- 修補方式：提高 compression threshold、縮短 session、必要時開新 session
- 驗證方式：log 中 compression 次數下降，體感改善
- 應提煉成的規則：Hermes 變慢時，先檢查 session 大小而非只怪模型
- 診斷
- 解法
Case 24：Desktop renderer 成為卡頓來源
- 症狀
- - 症狀：`webContents became unresponsive`
- 真正過錯：忽略 UI / renderer 也是瓶頸
- 根因分類：效能層
- 修補方式：關掉中間訊息、精簡通知、降低 persistent output 壓力
- 驗證方式：renderer log 改善、體感延遲下降
- 應提煉成的規則：性能診斷需同時看模型層與介面層
- 診斷
- 解法
Case 25：MCP / toolset 太肥拖慢 session
- 症狀
- - 症狀：整體變鈍，工具列與上下文都變重
- 真正過錯：沒分辨常用與重型工具
- 根因分類：效能層
- 修補方式：拆 heavy-tools profile，減少預設 toolset
- 驗證方式：新 profile 下回應速度改善
- 應提煉成的規則：工具應該分層，而不是全部常駐
- 診斷
- 解法
Case 26：把可觀察結果與真實完成混為一談
- 症狀
- - 症狀：前台看起來能開，就說整件事 done
- 真正過錯：驗證範圍不完整
- 根因分類：驗證層
- 修補方式：拆成多個驗證點：後台資料、前台渲染、相關版位
- 驗證方式：每個子需求各自有證據
- 應提煉成的規則：多條件任務要分段驗證，不能只驗最容易看到的一個點
- 診斷
- 解法
Case 27：只做內容表層整理，缺少可轉 Skill 結構
- 症狀
- - 症狀：筆記可讀，但未能直接轉成可執行工具
- 真正過錯：只寫知識，不寫操作結構
- 根因分類：輸出層
- 修補方式：補 diagnosis modules、input/output schema、verification checklist
- 驗證方式：文件可直接長成 `SKILL.md`
- 應提煉成的規則：想公開分享給其他 AI 的內容，應以可執行格式組織
- 診斷
- 解法
Case 28：沒有案例卡片庫就急著做 Skill
- 症狀
- - 症狀：Skill 容易變抽象、過泛
- 真正過錯：少了 grounded case library
- 根因分類：方法層
- 修補方式：先做 30-error-cards，再抽成模組與規則
- 驗證方式：Skill 內每個規則都能回指到真實案例
- 應提煉成的規則：Skill 應來自真實故障，而非純理論設計
- 診斷
- 解法
Case 29：把失敗經驗只當成個人抱怨，而非可公共化知識
- 症狀
- - 症狀：內容停留在私人復盤
- 真正過錯：沒有抽象成可共享的方法
- 根因分類：知識產品化層
- 修補方式：拆成失敗模式、診斷藍圖、案例卡片、Skill
- 驗證方式：第三方讀者可從 repo 理解並使用
- 應提煉成的規則：踩坑後的價值不只在修好，而在可重用化
- 診斷
- 解法
Case 30：沒有雙語輔助時，公開 repo 可讀性較低
- 症狀
- - 症狀：中文讀者清楚，但海外或英文使用者較難快速理解
- 真正過錯：公開分享場景下輔助說明不足
- 根因分類：輸出層
- 修補方式：以臺灣繁中為主，補英文 support 說明
- 驗證方式：README / usage docs 能同時服務中文主讀者與英文輔助讀者
- 應提煉成的規則：公開知識庫可主打繁中，但最好有最小英文導引
---
- 診斷
- 解法
下一步
- 症狀
- 這 30 張卡片下一步可以收斂成：
1. 10 個診斷模組
2. `SKILL.md` 規則段落
3. 自動驗證與修補範例
- 診斷
- 解法