Project 04. 用運行反饋修正 agent 的行為

相關講義：L07. 為什麼 agent 會多做或少做 · L08. 為什麼功能清單是 harness 原語本篇範本檔案：templates/

你要做什麼

前三個項目關注的是"讓 agent 把活幹完"。這個項目關注的是"出了問題怎麼修"——而且不是你修，是讓 agent 自己通過運行時信號來修。

你要做兩件事。第一，給知識庫應用加上運行時可觀測性：啟動日誌、導入和索引的日誌、問答失敗時的用戶可見錯誤狀態。第二，在倉庫裡編碼架構約束，讓 agent 不可能靜默地跨層違規（main / preload / renderer / services 之間的邊界）。

然後你會在代碼裡埋一個運行時 bug，讓 agent 去修。跑兩次：一次不給日誌和約束，看 agent 怎麼修；一次給好日誌和架構規則，看差別。

用什麼工具

Claude Code 或 Codex
Git
Node.js + Electron
日誌庫（如 electron-log 或簡單的 console 封裝）
結構化檢查工具（ESLint 自定義規則、guard 腳本、或測試）

具體步驟

準備工作

基於 P03 完成後的代碼，從同一個 commit 出發。
創建兩個分支：p04-baseline 和 p04-improved。
在兩個分支中埋入同一個運行時 bug（比如：索引時 chunk 大小讀取錯誤導致問答返回空結果）。
記錄 bug 的位置和表現，但不要告訴 agent bug 在哪。

第一次運行（弱 harness）

切到 p04-baseline 分支。

啟動 agent，告訴它"問答功能返回空結果，請修復"。
倉庫裡沒有運行時日誌，沒有架構約束檔案。
記錄 agent 花了多久找到根因、怎麼確認修復的、修復過程中是否引入了新的層邊界違規。
修復後重啟應用，確認是否能幹淨啟動。

第二次運行（強 harness）

切到 p04-improved 分支。在啟動 agent 之前，先在倉庫裡準備好：

運行時日誌：啟動時打印初始化步驟，導入時打印檔案數量和 chunk 結果，索引時打印進度，問答失敗時打印錯誤原因。
架構約束：在 AGENTS.md 裡明確寫 Electron 四層邊界（main / preload / renderer / services），說明哪些調用路徑是允許的。用 ESLint 規則或 guard 腳本檢查違規。
乾淨狀態要求：最終交付前必須能幹淨重啟。

然後啟動 agent：

先讓 agent 加上日誌和結構化檢查（這是任務的一部分）。
然後告訴它"問答功能返回空結果，請修復"。
這次 agent 有日誌可以看，有架構規則可以參照。
記錄診斷速度、修復質量、是否引入了邊界違規。
修復後重啟應用，確認乾淨啟動。

怎麼衡量結果

指標	說明
根因定位時間	從開始到 agent 準確描述 bug 原因
修復確認時間	從定位到驗證修復成功
邊界違規數	修復過程中引入的跨層違規次數
日誌有用性	日誌是否直接指向了失敗原因
乾淨重啟	修復後是否能幹淨重啟、無報錯

要交什麼

弱 harness 的調試記錄：診斷過程、修復 diff、啟動證據
強 harness 的調試記錄：同上，加上日誌和架構約束檔案
結構化檢查產物（lint 規則、guard 腳本、或測試檔案）
一份對比筆記：重點比較診斷速度和修復健壯性

對應講義