紀錄只 append:log 是真相,context 是它的投影
對話記在一個只增不改的 log 裡;壓縮和取消不是去改它,是各 append 一筆。模型看到的 context,是這個 log 重算出來的投影。
一個 coding agent 的 session 要能存檔、重開、回看。最直覺的做法,是把「現在要餵給模型的那串訊息」直接寫到檔案,每次更新就覆寫。但這串訊息會被壓縮(把舊的換成摘要)、會被取消(半截的回合)——如果檔案跟著它變,那些「被折疊掉」的歷史就真的從磁碟上消失了。
這篇講另一種存法:磁碟上是一個只 append 的 log,模型看到的 context 是從這個 log 重算出來的。壓縮、取消都不去改已經寫下的東西,只各自 append 一筆。
一個只 append 的 log
每一行是一筆 entry(一個 JSON 物件,JSONL 格式),只有四種:
- 訊息:一則對話(使用者的 prompt、模型的回覆、工具的呼叫與結果)。
- 壓縮:帶著「摘要」和「保留下來的近期 tail」。
- 中斷:一個被取消的回合,帶著半截回覆(如果有)。
- 模型:之後的回合用哪個 provider、哪個模型。只在換了的時候記一筆。
第四種是後來加的。有一次一個 session 裡,模型說它「重新讀過原始碼」了,但那一輪它一個工具都沒呼叫,是憑記憶在講。回頭查時才發現 log 裡沒有記是哪個模型,根本無從追究。
關鍵是 append-only:寫下去的東西永遠不刪、不改。壓縮尤其反直覺——它不是把舊訊息從檔案裡刪掉換成摘要,而是把一筆「壓縮」entry append 在那些舊訊息後面,舊訊息原封不動留在檔案裡。所以完整的原始對話永遠在磁碟上,即使它早就被折出了模型的 context。
為什麼值得這樣?append-only 的檔案不會「改到中間一半當機就壞掉」(只在結尾加行;結尾本身還是會壞,見下文);而且「人要回看完整歷史」和「模型要精簡的 context」這兩個需求,可以從同一份檔案各取所需。
一個 log,兩種投影
同一個 log,兩種讀法:
- 給模型的視圖(replay):重建「下一次請求要送的那串訊息」。這是有損的——壓縮會把它涵蓋的舊訊息換成摘要,中斷的回合整個跳過。
- 給人的視圖(原始 entry):回看歷史(
/history)要的,每一筆照原樣、不折不跳。
一串事件,兩種投影那篇講的是「同一個事件串,畫面和模型各投影一次」;這裡是同一個招用在儲存上:一份 append-only log,一個給模型的有損投影、一個給人的完整投影。不需要為「歷史時間軸」另立一個型別——entry 本身已經帶了所有該顯示的東西。
replay 怎麼重算
從頭掃一遍 entry,維護一個累加器:
messages = []
for entry in log {
訊息 → messages.push(它)
壓縮 → messages = [摘要, ...保留的 tail] // 重設,不是 append
中斷 → 跳過
模型 → 跳過 // 給人看的,不是對話
}
兩個地方不是單純 append:
- 壓縮是「重設」,不是「append」。 碰到一筆壓縮,就把累加到目前的 messages 整個換成
[摘要, ...保留的 tail]。這就是為什麼有好幾筆壓縮時,只有最後一筆算數:它的「保留 tail」已經把它之前值得留的都帶上了,先前累加的東西該丟就丟。最後一筆壓縮之後的訊息,再照常往後累加。 - 中斷整筆跳過。 一個被取消的回合,那段沒說完的回覆不該變成下一回合的 context(見取消)。但它仍記在 log 裡——「發生過」是永久事實,只是不回放。
所以:磁碟上什麼都在,是 replay 決定模型看到什麼。壓縮「取代」、中斷「消失」,都發生在這個重算裡,不在磁碟上。
複製,不要指標
那筆「壓縮」entry 裡的「保留 tail」,是把保留的訊息整個複製一份存進去,不是存一個「指回 log 裡第幾筆」的索引。
索引看起來更省(不必重複存)。但它會壞:壓縮執行的當下,有些要保留的訊息還沒有自己的 log entry——例如觸發這一輪的那句 prompt,是在壓縮跑之前就被推進 messages 的,可能還沒落盤。這時索引要指向「還不存在的 entry」,就得各種偏移修正,很容易算錯。
複製的代價是同一則訊息可能在磁碟上出現兩次(一次在它自己的訊息 entry、一次在某筆壓縮的保留 tail 裡)。但這個重複很便宜,換來的是永遠不用去推敲「這個索引現在還指對嗎」。
對一個只 append 的 log,用索引往回指是個陷阱:被指的東西可能還沒寫下、或語意已經變了。複製當下的快照,省掉所有這類推理。
(後來 log 改成每一輪就寫,見下一節,上面那個「prompt 還沒落盤」的例子在現在的程式裡已經不會發生。但快照仍然是對的選擇:它不依賴「什麼時候寫」這個細節,而這個細節剛剛才變過一次。)
什麼時候寫
log 原本要等整個回合結束才寫:使用者的 prompt、這個回合裡每一輪工具的呼叫與結果,全部在回合結束時一次 append。一個回合可能跑幾十輪工具、好幾分鐘;這段時間裡關掉終端機或 process 被殺,這些全都不在紀錄裡——檔案早就被工具改了,接回 session 的模型卻不知道自己做過。
現在改成三個時間點:prompt 一送出就寫;每跑完一輪工具就把這輪的呼叫與結果寫進去;回合結束(或被取消、失敗)時把剩下的寫完。要做到這一點,核心得在每輪之間把控制權交回外殼,所以迴圈從核心搬到了外殼(見 agent loop)。中途斷掉,最多只丟正在跑的那一輪。
結尾也會壞
append-only 不會改壞中間,但最後一行會壞:寫到一半 process 就死了,留下半行。
一個具體的版本是:寫一筆 entry 原本分成兩次寫入——先寫 JSON,再寫換行。process 剛好死在兩次之間,就留下一行沒有換行的紀錄;下一次 append 的內容會黏在它後面,兩筆變成一行解析不了的東西。修法有兩層:
- 一筆 entry 一次寫完,內容和換行一起。一般大小的紀錄,在 Linux 上幾乎不可能只寫進一半。
- 開檔時修尾巴。 每筆 entry 都以換行結尾,所以最後一個換行之後如果還有東西,那就是一次被打斷的寫入:切掉它,log 就能繼續 append。但如果那段尾巴本身能解析——例如有人手動編輯時刪掉了最後的換行——那它是完整的一筆,補一個換行留下來,不切。
中間某一行如果壞了(手動編輯、磁碟錯誤),讀檔時跳過它並告訴使用者是第幾行,不讓一行壞掉就打不開整個 session。剩下的風險都很少見:一筆很大的 entry(例如帶著幾百 KB 保留 tail 的壓縮)寫到一半被強制終止、磁碟滿了、斷電——這些就接受。
一個 session,一個寫入者
最後一個洞:同一個 session 被開了兩次。兩個終端機都用同一個 id 接回 session,兩個 process 各自往同一個 log append,兩段對話就交錯寫進同一個檔案。更糟的是,其中一邊寫下的壓縮 entry 在 replay 時會「重設」累加器,把另一邊的訊息從模型的視圖裡抹掉。
所以開 session 時,先對 log 檔拿一把作業系統的檔案鎖,拿不到就直接回報「這個 session 已經在另一個 Zophos 開著」。鎖跟著 session 的生命週期,process 結束就自動釋放。它要在「修尾巴」之前拿:否則可能把另一個 process 正寫到一半的 entry 當成壞掉的尾巴切掉。
但「在另一個視窗接著用同一個 session」是合理的需求。要讓兩個 process 安全地寫同一個 log,紀錄就得換一種格式:每一筆都帶著自己的 id 和上一筆的 id,整份紀錄變成一棵樹。兩邊同時追加只會長出兩條分支,各自順著上一筆的 id 還原。Zophos 的 log 是一條線,replay 照檔案順序讀,兩邊一交錯,對話就壞了。
把 log 改成樹,要動 replay、壓縮、/history,還要讀得懂舊檔,換到的只是「兩個視窗寫同一個檔案」。Zophos 用的是最便宜的做法:fork。要開的 session 被鎖住時,先問使用者要不要 fork;同意就把 log 檔複製成一個新的 id 再打開,兩邊從此各寫各的檔案。啟動時用 --session 指定,或在執行中用 /resume 切換,都走這條路。鎖沒有被繞過:同一個檔案仍然只有一個寫入者。
Zophos 也沒有 /rewind(把對話退回到某一點)。log 只 append,要退回得新增一種 entry 讓 replay 認得;退回點落在壓縮之前時,語意也不清楚。最關鍵的是,工具已經改過的檔案、跑過的指令不會跟著還原,只退對話會讓人以為一切都回去了。要讓 rewind 名副其實,得連檔案一起存 checkpoint,Zophos 沒有這一層。要重來,開新 session 或 fork 都比較乾淨。
總結
-
log 是真相,context 是投影。 對話記成一個只增不改的 entry log;壓縮、取消都是 append 一筆,不是改寫。模型看到的那串訊息,是從 log 重算出來的,不是磁碟上的主本。
-
一個 log,兩種投影。
replay給模型(有損:壓縮取代、中斷跳過),原始 entry 給人(回看歷史,完整)。同一份資料,兩種讀法——跟事件的兩種投影同一個招,用在儲存上。 -
壓縮「取代」、中斷「消失」,都在 replay 裡,不在磁碟上。 磁碟永遠留著完整原始對話;是重算決定模型看到什麼。
-
複製,不要指標。 保留的 tail 存成快照而非索引——因為 append-only log 裡,被指的東西可能還沒落盤。重複存的那點磁碟,換來永遠不用推敲索引有沒有失效。
-
每一輪就寫,不要等回合結束。 process 隨時可能被結束;留得下來的只有已經寫進去的。prompt 一送出就寫、每輪工具結束就寫,中斷最多丟一輪。
-
append-only 的結尾也會壞,開檔時修。 一筆一次寫完;最後一個換行之後的殘段切掉,但能解析的補回換行留下;中間的壞行跳過並回報。
-
一個 session 只能有一個寫入者。 開檔就鎖,拿不到就拒絕;而且要在修尾巴之前拿。