Hao程式筆記

AG Day 44 技術手冊：常見維運情境 執行需求：CPU 可跑 。AG Day 42（ 原文連結 ）把 README 與架構圖做好了，AG Day 43（ 原文連結 ）整理了已知限制與除錯日誌，但這些都是「靜態」指引。今天的任務是處理「動態」議題：research-agent 在 production 環境上跑了一段時間之後，會陸續碰到磁碟空間吃緊、API 額度快用完、套件出新版本、LLM 模型升級、依賴服務變慢等情境。這些都不是 bug，而是「隨著時間必然會發生的狀態變化」，需要預先準備對應的處理流程。今天會把這些情境整理成一份可照著做的維運手冊 docs/runbook.md ，每一個情境都附上「症狀、診斷、處理、預防」四步驟，並在 README 留下指向入口。所有處理步驟都能在本機 CPU 上完成，不需要 API 金鑰或 Docker；真實部署時的指令會標示但不會硬性要求。 引言 「程式上線只是開始，維運才是日常」這句話在 AI Agent 系統裡尤其真實。相較於傳統的 CRUD 應用，Agent 系統多了兩個會隨時間變動的維度：模型版本（每幾個月就有新模型釋出，且通常會取代舊模型）與外部依賴（Tavily、Langfuse、OpenAI／Anthropic 任一家的 API 都可能偶爾降級或限流）。當這些維度變動時，系統的行為也會跟著變——可能是延遲上升、可能是某條流程的失敗率增加、也可能是某個工具呼叫的格式突然不相容。如果沒有預先準備好對應的處理流程，等到真的出事才開始查，會非常慌亂。 這份維運手冊的設計原則是「每一條都能照著做」。意思是：每一個情境都列出具體的指令（不是抽象的建議）、具體的輸出（讓你判斷指令是否成功）、具體的後續動作（指令成功後下一步該做什麼）。這跟 AG Day 43 的除錯日誌不同——除錯日誌是「事後紀錄」，維運手冊是「事中處理」。兩者搭配起來，就能涵蓋「事前預防（README 限制）→ 事中處理（runbook）→ 事後紀錄（debug-log）」的完整生命週期。 原理／觀念 為什麼要分「症狀」「診斷」「處理」「預防」 維運手冊的常見錯誤是只寫「怎麼處理」而不寫「怎麼判斷是不是這個問題」。一個典型的慘案是「線上服務慢」的時候，值班同事直接照 runbook 把服務重啟，結果根本沒解決問題，反而把快取清...

AG Day 43 已知限制與除錯日誌 執行需求：CPU 可跑 。AG Day 42（ 原文連結 ）寫好了 README 與架構圖，也準備了接手清單與 smoke test，但有一塊刻意留白：這個專案目前「做不到」哪些事。一個誠實的技術專案不只說明能做到什麼，也應該明列做不到什麼。沒有這份限制清單，新成員很容易對專案抱持過高期待，跑下去才發現某個情境根本還沒支援。今天的任務是把這 45 天累積下來的「已知限制」整理成一份正式的 docs/limitations.md ，並建立一份「除錯日誌」範本 docs/debug-log.md ，讓日後碰到問題時能用一致格式留下紀錄，逐漸累積成專案自己的除錯手冊。這項工作完全在本機 CPU 上完成，不需要 API 金鑰或 Docker。 引言 寫軟體最危險的心態是「沒看到 bug 就是沒問題」。對一個 AI Agent 系統來說，這個心態尤其危險——LLM 的輸出本來就有機率性，今天跑出來的結果不一定明天還能重現；外部服務（Tavily、Langfuse）會偶爾逾時；檢索結果會被模型誤解。如果沒有系統化地記錄「什麼情境下會壞」，等到 production 出事才開始找原因，往往已經錯過最佳除錯時機。我們今天的做法是建立兩份互相搭配的紀錄檔： docs/limitations.md 列舉「目前已知做不到的事」， docs/debug-log.md 是「事後填寫的除錯紀錄」。前者是設計階段就決定的邊界，後者是營運階段才浮現的真實案例。 這份 limitations.md 對接手的人非常重要，因為它會直接告訴新成員：「不要把這個專案用在哪些情境」。例如：我們目前不支援多語言研究（僅繁體中文最佳，英文可用但需要另外評估）、不支援圖片或音訊輸入、不支援即時串流到對話介面（雖然 AG Day 19 已經做過內部串流）、不支援分散式部署（單機 SQLite 是瓶頸）。這些限制不會在程式碼裡以錯誤訊息的形式出現，新成員必須事先讀過這份清單，才能選對工具與場景。 原理／觀念 為什麼要分「設計時限制」與「執行時雷點」 限制分成兩種： 設計時限制 （design limitation）是這個版本刻意沒做的功能，例如「不支援多語言」「不支援分散式部署」； 執行時雷點 （runtime pitfall）是程式有做但容易在...

AG Day 42 文件與交接：README 與架構圖 執行需求：CPU 可跑 。AG Day 38（ 原文連結 ）把 research-agent 變成 FastAPI 服務，AG Day 39（ 原文連結 ）把它裝進容器，AG Day 40（ 原文連結 ）做出 CLI 與 Streamlit 前端，AG Day 41（ 原文連結 ）做了一輪壓測看承載量。現在這個專案已經是一個「能跑、能部署、有介面」的完整系統，但對一位新接手的同事來說，他打開 research-agent/ 目錄看到的只是一堆檔案：不知道該先讀哪一個、不知道每個指令是做什麼的、不知道 RESEARCH_AGENT_MODEL 沒設會發生什麼事。今天的任務是把這一切整理成一份「接手的人讀完就能動手」的說明——一份好的 README、一張能一眼看懂模組與資料流向的架構圖、一份把所有環境變數、指令、輸出位置列清楚的交接清單。這些都不需要 API 金鑰、不需要 Docker，只要文字編輯器就能完成，是這個系列最「安靜」卻也最決定專案壽命的一篇。 引言 在軟體工程裡有句常聽到的話：「程式碼會被讀很多次，但只會被寫幾次。」對一個花了四十多篇才長出來的專案來說更是如此——我們花了 AG Day 6 手刻代理迴圈、AG Day 11 引入 LangGraph、AG Day 18 拆子圖、AG Day 28 接上 MCP、AG Day 29 拆多代理、AG Day 30 定義通訊協議，每一步都加進了新概念、新檔案、新環境變數。如果沒有一份 README，新成員只能從 git log 一路爬，或直接問作者。作者如果在、還能回答；作者如果轉換了，專案就變成孤兒。今天我們要把這件事徹底處理好：寫出一份新成員讀 30 分鐘就能動手改的 README，畫出一張能掛在專案首頁的架構圖，並建立一份對應 AG Day 43（ 原文連結 ）已知限制的對照索引。 README 不是「抽象宣言」，而是一份具體的契約：寫下「這個專案是什麼、要解決什麼問題、怎麼跑起來、常見問題在哪裡」。架構圖也不是裝飾品，而是把模組邊界、資料流向、外部依賴視覺化的方式，讓新成員在三秒之內知道「這個系統有幾塊、資料從哪裡進、會從哪裡出」。今天會用 Python 內建的 graphviz 介面包裝（透過 subprocess 呼叫 ...