zophos

← Notes · 25-跨前端共用指令:在指令邊界反向,不在迴圈邊界.md

跨前端共用指令:在指令邊界反向,不在迴圈邊界

兩個前端——一個樸素的逐行 CLI、一個全螢幕 TUI——處理同一組斜線指令(/help、/config、換模型……)。它們各寫了一份,重複了。直覺的去重是「抽一個共用主迴圈,兩邊都用它」。但這是錯的接縫:兩個迴圈的控制流本質不同,硬合會讓抽象漏。對的接縫不是迴圈,是指令:定義一個小小的前端介面,指令邏輯只依賴它,而每個前端各自留著自己的迴圈。

(後來 CLI 拿掉了,只剩 TUI。那個前端介面為甚麼還留著、以及這篇哪一部分要修正,見文末〈後來〉。)

一個互動式 agent 的外殼,骨架大概是:讀一行輸入 → 如果是斜線指令就處理掉、否則當成一輪對話送進核心 → 渲染結果 → 回到讀輸入。

當你有兩個前端時,這個骨架出現了兩份。斜線指令(顯示設定、壓縮上下文、換 provider……)在兩邊各寫一次,只有「怎麼輸出」不一樣:一邊 println,一邊往畫面推一個區塊再重繪。這個重複真實存在,該去掉。

問題是:在哪裡去掉。


錯的接縫:共用迴圈

最直覺的去重,是把整個主迴圈抽成一份共用程式,讓 CLI 和 TUI 都「驅動」它、只在輸出時各自分流。

但兩個迴圈的控制流不是同一種東西:

  • 逐行 CLI:讀一行(阻塞在標準輸入)、用作業系統的中斷信號處理 Ctrl+C。
  • 全螢幕 TUI:泵一個事件串流(原始模式鍵盤、Ctrl+C 是一個按鍵事件而不是信號),中間還夾著捲動、滑鼠、每一步重繪。

要把這兩種塞進一個共用迴圈,那個共用介面就得長出「讀下一個提交、但也要處理捲動 / 滑鼠 / 重繪」這種方法——TUI 的事件迴圈比「讀一行」豐富太多。於是介面會膨脹成兩個前端需求的聯集,變成一個會漏的抽象(見純核心,不純外殼:這兩個殼本來就該各自不同)。

所以:不要統一迴圈。


對的接縫:指令

真正重複的不是迴圈的控制流,是指令處理。所以接縫畫在那裡:

定義一個薄的前端介面——故意只有三件事:輸出一塊文字、渲染一個串流事件、讀一行輸入(讀秘密時遮罩)。然後:

  • 一份指令邏輯,只依賴這個介面:run_command(line, 前端, …)。
  • 每個前端各自留著自己的迴圈,收到一行提交時,把自己當成那個介面傳進去呼叫 run_command。

重繪、捲動、狀態列這些 TUI 專屬的細節,關在它自己的介面實作裡,不外漏到介面上。


依賴朝內:在指令邊界反向

這個安排的關鍵,是依賴的方向。原本是兩個前端各自「擁有」指令邏輯;現在反過來:

CLI ─┐
     ├─▶ 前端介面 (trait) ◀── run_command(指令集)
TUI ─┘
  • CLI、TUI 依賴介面與 run_command。
  • 指令集只依賴那個介面。
  • 誰都不依賴具體的 CLI 或 TUI——指令程式碼裡一行都不提它們。

這和換模型、加工具用的是同一招(見插樁點):核心定義契約、具體實作反過來插進來。這裡只是把同一條界線,延伸到了指令這一層。

而「反向」要畫在指令邊界,不是迴圈邊界——指令邏輯確實兩邊相同,可以共用;迴圈的控制流兩邊不同,該各留。分寸就在這條線上。


守住:讓介面保持小

這種抽象有一個失敗模式:介面為了遷就某一邊,慢慢長大。

一旦前端介面開始冒出 scroll()、status_line()、redraw() 這種只有 TUI 需要的方法,它就在漏了——那些東西該留在各自的實作裡,不該爬上契約。

一個可操作的準則:六個小指令,介面超過四五個方法就停下來問值不值得。小介面是這個切法能成立的前提;它一膨脹,你就滑回了「共用迴圈」那個錯的接縫,只是換了層皮。


後來:只剩一個前端

CLI 後來拿掉了。理由跟這篇的切法無關,是成本:接下來要打磨介面,兩個前端就代表每個顯示功能都要做兩次。這已經在發生——一個「工具輸出印兩次」的 bug 只出在 CLI;回看歷史的 /history 兩邊各寫了一套;輸入 API key 時 TUI 會遮成星號,CLI 不會。而 CLI 沒有 TUI 做不到的事:它是互動式的逐行介面,不是能塞進腳本的一次性模式;發行的安裝包也本來就只帶 TUI。

代價也記下來:TUI 會攔下滑鼠事件,選取文字要按住 Shift 再拖曳;它畫在終端機的另一個畫面上,離開後對話不會留在終端機裡(session 檔和 /history 仍有完整紀錄)。

那前端介面要不要跟著拆?它現在只剩一個實作,照「只有一個實作的介面就是多餘的」這條標準該刪,後來的程式審查也這樣標過。我們留著,但理由不是「以後可能會有 GUI」:

  • 它守的是依賴方向,這跟前端有幾個無關。 指令程式碼只認這個介面,不需要知道 TUI 的內部,斜線指令的邏輯就不會跟畫面渲染纏在一起。它也只有二十來行,拆掉省不了甚麼。
  • 它反而不是未來 GUI 會用的接縫。 這個介面只涵蓋「斜線指令需要的輸入輸出」。第二個前端真正需要共用的,是迴圈裡一段跟畫面無關的流程:把 prompt 放進對話並寫進 log、讓回合跟取消賽跑、每輪工具結束或中途壓縮時先存檔再重新進入、回合結束或失敗時收尾。這段現在跟畫面程式碼混在同一個迴圈裡。

這修正了這篇的一部分結論。「別統一迴圈」仍然對——讀輸入、處理按鍵、重繪,兩種前端本質不同。但迴圈裡夾著一段跟前端無關的回合驅動,那段是可以共用的,前面把整個迴圈都歸成「各留各的」,切得太粗了。只是現在只有一個前端,先把它抽出來就是在猜第二個前端的形狀;等第二個前端真的動工,再把它抽成一個共用函式。

介面本身也從三件事長到了五件:多了一個「從幾個選項裡挑一個」(換 provider、管理 MCP server 的選單用),「讀一行」和「讀秘密」拆成兩個方法。這兩個都還是指令層的語意,不是捲動、重繪那種只有 TUI 才有的東西,仍在「四五個方法」那條線內。

/compact 不在共用指令裡,由 TUI 的迴圈自己處理,跟 /history 一樣。壓縮可能要跑好幾分鐘,使用者要能用 Ctrl+C 取消,這就得讓它跟按鍵賽跑,而那是迴圈的事,不是指令的事。所以介面上沒有「渲染一個串流事件」,現在是四件:輸出文字、讀一行、讀秘密、從選項裡挑一個。這也是上面那條線:要跟取消賽跑的東西屬於迴圈,放進共用指令就得把迴圈的能力搬上介面。


總結

  1. 重複在指令,不在迴圈。 兩個前端對同一組斜線指令各寫一份;真正能共用的是指令邏輯。

  2. 別統一迴圈。 逐行讀 + 信號,對上事件串流 + 捲動 / 重繪——控制流本質不同。硬合會把共用介面撐成兩邊需求的聯集,變成會漏的抽象。

  3. 在指令邊界反向依賴。 一個薄前端介面(輸出文字 / 渲染事件 / 讀一行),指令集只依賴它,每個前端實作它、各留自己的迴圈。依賴朝內,指令程式碼不提任何具體前端(同插樁點、純核心外殼的那條界線)。

  4. 讓介面保持小。 它一長出前端專屬的方法就是在漏;守住幾個方法,否則你只是把「共用迴圈」換皮換回來。

  5. 只剩一個前端時,介面留著是為了依賴方向,不是為了未來。 CLI 拿掉之後,這個介面只有一個實作,但它仍讓指令邏輯不碰畫面。第二個前端真正要共用的,是迴圈裡跟畫面無關的那段回合驅動——「別統一迴圈」切得太粗了,只是那段要等第二個前端出現再抽。