zophos

← Notes · 05-介面的減法:穿名字的型別、沒人聽的事件.md

介面的減法:穿名字的型別、沒人聽的事件

一個型別、事件或欄位,要嘛帶著別處拿不到的東西,要嘛有人真的用它——否則它只是讓人多讀一行

agent loop 的核心是一組介面:工具怎麼被呼叫(Tool trait)、輸出怎麼流出來(事件串流)、驅動端能呼叫什麼(harness 的方法)。這上面的每一個型別、每一個事件、每一個欄位,都是讀的人——還有未來的插件作者——必須理解的東西。預設應該是只留會用到的。


失敗一:穿名字的型別(什麼都沒多帶)

OutputChunk 原本是 { stream, text }——stream(stdout 還是 stderr)是真資料,一對有意義的欄位撐得起一個型別。合併 pipe 之後 stream 沒了,只剩 { text }:一個單欄位、沒有任何方法的包裝,就是一個穿了名字的字串。

OutputChunk { text }      →      text

把它收掉成字串,什麼都不失去——工具吐出的還是那段文字,消費端讀的還是那段文字。

  • 辨認的訊號:單欄位、無方法的包裝。它沒有把任何東西「綁在一起」,也沒有任何行為。
  • 「留著當 API 擴充點」是假的:擴充點其實是外層的事件。id(哪一次工具呼叫)早就放在 ToolOutput { id, text } 上、由 harness 加——證明「加料是 harness 的事」。未來的 metadata(timestamp、序號)會跟 id 一樣加在事件上,永遠不會加進 chunk,因為工具只知道自己那段文字。所以 chunk 沒有未來的欄位可長。

失敗二:沒人聽的事件(帶了訊號,但沒人用、又推導得出來)

ExchangeStarted(每趟請求開頭)和 MessageStarted(一段回覆的第一個字之前)標記的是真實的邊界。問題是兩個都不及格:

  1. 沒有消費者:兩個前端都忽略它們(CLI 回空字串、TUI 落進 catch-all)。
  2. 可以推導:想顯示「正在等 provider」的轉圈圈,消費者自己追蹤就好——開始一回合、或每個 ToolFinished 之後就是在等,收到任何內容事件就停。MessageStarted 同理(某個邊界之後的第一個 TextDelta 就是新回覆)。

一個事件要掙得位置,得有人真的對它反應,而且不能便宜地推導出來。這兩個兩項都不過,砍掉;哪天前端真要轉圈圈,on_event(&...) 一行加回來。


兩種 YAGNI 不一樣

這兩個失敗該分開看,因為「砍掉的代價」不同:

穿名字的型別 沒人聽的事件
帶了資料嗎 帶了,但字串就有 帶了一個訊號
有人用嗎 有(讀 .text) 沒有
砍掉失去什麼 什麼都不失去 失去一個(可推導、沒人用的)能力
該怎麼辦 直接收掉,零風險 判斷:推導很痛嗎?消費者快來了嗎?

OutputChunk 是純粹的間接層,砍了零損失;ExchangeStarted 砍了會少一個能力——只是那個能力現在沒人要、而且推導得出來。別把兩種當成同一種。


正面的那一半:把「繞路的狀態」變成「形狀」

介面的減法不只是刪東西。有時候一個東西該不該存在,答案是「換個形狀它就不必存在」。

harness 曾經有一個 stash:last_compaction 欄位加上 take_last_compaction 方法。它不是型別也不是事件,是一團狀態,存在的唯一理由是把資料跨過一個介面沒表達出來的控制流邊界——壓縮發生在回合中途,而核心每次跑一步的函式 run_turn 只回傳 Result<()>,裝不下壓縮的結果,只好先藏起來、等驅動端事後來拿。取消也一樣:用 Err 往上拋,半段回覆會隨 error unwind 丟掉,所以也先藏。

解法不是「管好這個 stash」,是給那件事一個形狀:讓 run_turn 回傳 TurnOutcome,壓縮變成 Compacted(驅動端存了再續跑)、取消變成 Cancelled。stash 的兩個成員一起消失,而且更正確——壓縮在發生當下就持久化,任何退出路徑都不會留下沒存的東西。

一團「只為了搬資料而存在」的狀態,往往是介面少了一個形狀的訊號。補上形狀,狀態就不需要了。


又中了幾次:原則會一直回來

寫完這篇之後,同樣兩種失敗又各冒出好幾次——證明它不是一次性的清理,是個會反覆用到的判準。

又一個沒人聽的事件。 每次收到 provider 回報的 token 用量,迴圈就發一個「usage 事件」給前端顯示。但兩個前端都把它丟掉(一個渲染成空字串,一個落進 catch-all 什麼都不做)。而真正要用這個用量的地方——context 預算——是在迴圈內部直接從 provider 的回應拿的,跟這個發給前端的事件是兩條不相干的路。沒有消費者、資料又另有來源,砍掉。

又幾個穿名字的型別。 有個只裝「跑了幾回合」的計數器 struct,削到只剩一個 u32 欄位——那函式直接收 &mut u32 就好。有個內部、只有一個呼叫者的「這次交換的結果」列舉,折成 Option<T>:None 就代表「再跑一輪」。還有個表示 token 用量的型別,砍到只剩一個總數,就收成一層 newtype(struct Usage(u64))。每一個都是「包了名字卻沒多帶東西」,拆掉就好。

判準沒變,只是東西會一直長出來——所以這篇的重點從來不是那幾個例子,是那把尺。


判準

一個型別、事件或欄位,掙得它的位置,條件是其中之一:

  • 帶著別處拿不到的資料(OutputChunk 的 stream 曾經符合;只剩 text 就不符合);
  • 是個有人真的拿去做事、而且無法便宜推導的訊號(ExchangeStarted 兩項都不符合)。

兩者皆非,就砍。加回來通常是一行,而一個「只裝會用到的東西」的介面,是插件作者——或三個月後的你——有辦法一次讀完的介面。


總結

  1. 預設最小介面:每個型別、事件、欄位只該帶會用到的東西。多出來的,是讀的人要理解、插件作者要相依的負擔。

  2. 兩種失敗,兩種處置:什麼都沒多帶的包裝(直接收掉,零損失);帶了訊號卻沒人用、又推導得出來的事件(砍掉,一行可復原)。

  3. 繞路的狀態是介面缺形狀的訊號:一團只為了跨越控制流搬資料的 stash,與其管好它,不如給那件事一個回傳的形狀,狀態就不必存在,而且更正確。

  4. 這不是語言問題:穿名字的字串、沒人聽的事件,Python/TS 的 agent 一樣會長出來。判準是介面設計,不是哪個語言的語法。