zophos

← Notes · 21-工具的契約:loop 只透過一個介面驅動每個工具.md

工具的契約:loop 只透過一個介面驅動每個工具

一個工具對外宣告它能做什麼,對內接受一個固定的呼叫契約——收到參數、一個取消訊號、一個輸出管道,回傳一個結果(或一個會變成結果的錯誤)。loop 靠這個契約驅動每一個工具,所以它對 bash、read、edit 一無所知。

agent loop 那篇講了工具是「模型的詞彙表」——每個工具報自己的名字、說明、參數 schema,模型照這個決定要呼叫什麼。這篇講另一面:工具被呼叫時的契約——它收到什麼、回傳什麼,以及為甚麼這個固定契約讓 loop 不必認識任何一個具體工具。


宣告:同一個東西,告訴模型也執行

一個工具報三件事給模型:名字、一句說明、參數的 schema。loop 把這些收集起來送給模型,模型就知道它能呼叫什麼。而實際去做那件事的,是同一個工具物件的「執行」方法。

告知和執行在同一個物件上,所以不會各寫一份、對不上(這點 agent loop 講過,是「單一事實源」)。這篇從這裡往下,看那個「執行」方法的契約。


呼叫:收到參數、一個取消訊號、一個輸出管道

loop 要跑一個工具時,遞給它三樣東西:

  • 參數:模型填的那包 JSON。
  • 一個取消訊號。 跟整個回合賽跑的同一個訊號。一個會卡很久的工具(像跑一個外部命令)要自己拿它去賽跑,取消到了就收手、殺掉子程序(見取消)。一個瞬間就做完的工具(讀個小檔)可以不理它。
  • 一個輸出管道。 一個「邊做邊吐」用的 callback。會在做完之前就產生輸出的工具(像跑命令,一段段吐),就往這個管道送;大多數工具做得太快、用不到,直接忽略(這些 chunk 怎麼被畫面和模型各自投影,是一串事件,兩種投影的題目)。

這三樣——參數、取消訊號、輸出管道——是 loop 遞給每一個工具的,不分哪一個。


回傳:一個結果,或一個會變成結果的錯誤

工具執行完,回一個結果字串。如果它失敗了(命令跑錯、檔案不存在),回一個錯誤——而 loop 把那個錯誤轉成一個結果(一個標記為 error 的 tool result),餵回給模型。工具呼叫了一個不存在的名字,也一樣:變成一個「no such tool」的結果。

所以 loop 從不因為一個工具而崩掉。工具的失敗不是例外,是模型下一輪要看到、要自己繞過的輸入(這就是 agent loop 的「模型的錯誤是輸入」)。唯一會讓 loop 真的回 error 中斷的,是連不上 provider 這種基礎設施失敗。


所以 loop 對任何一個工具一無所知

把上面合起來:loop 要跑工具時,按名字找到那個物件,遞給它 (參數, 取消訊號, 輸出管道),收回 (結果,或錯誤→結果)。它不知道 bash 跟 read 跟 edit 有甚麼不同——對它來說全都是「一個實作了這個契約的黑盒」。

這就是契約的價值:loop 裡沒有「如果是 bash 就…、如果是 edit 就…」的分支。 加一個新工具,只要實作那三個宣告 + 一個執行方法,loop 一行都不用改。工具各自知道怎麼讀檔、怎麼跑命令、怎麼改檔(edit 的比對規則就全在 edit 工具自己裡面);loop 只管按契約驅動。


總結

  1. 宣告和執行在同一個物件上。 名字/說明/schema 告訴模型能做什麼,執行方法實際去做——單一事實源,不會對不上(見 agent loop)。

  2. 呼叫契約:收到 (參數, 取消訊號, 輸出管道)。 取消訊號讓慢工具能中途收手(見取消);輸出管道讓工具邊做邊吐(見投影)。這三樣遞給每一個工具。

  3. 回傳一個結果,或一個會變成結果的錯誤。 工具失敗、甚至名字不存在,都變成餵回模型的結果;loop 從不因工具崩掉(「模型的錯誤是輸入」)。只有連不上 provider 才中斷。

  4. loop 對具體工具一無所知。 全都是「實作了契約的黑盒」,按名字驅動;loop 裡沒有 per-tool 分支,加工具不動 loop。