代理主機協定原則

代理主機協定 (AHP) 是用於代理體驗的狀態同步協定。它允許用戶端和主機共享代理工作階段的權威、可重播視圖，而不需要用戶端了解特定的代理執行時間、工具詞彙、檔案系統模型、模型提供者或 UI 框架。

與 ACP 等點對點代理協定相比，AHP 將同步、重新連線和多用戶端協調視為一流的協定問題。 AHP 不能取代主機下方的代理協定；它是一個或多個代理實作之上面向用戶端的層。

原則

AHP 是狀態 - 第一個

AHP 標準化了共享狀態、有序操作、快照、訂閱和重播。用戶端從包含狀態的通道進行渲染，並透過純 reducer應用協定操作來更新該狀態。

因此，協定新增應該首先詢問狀態和用戶端需要呈現或協調哪些持久的狀態，而不是先詢問哪個後端事件。短暫通知對於路由和短暫訊號很有用，但使用者可見的工作階段事實應該可以從狀態恢復。

AHP 是主機權威且用戶端回應

主機擁有每個包含狀態的通道的權威狀態。用戶端可以樂觀地應用自己的操作以獲得即時回饋，然後在主機按伺服器順序回顯接受或拒絕的操作時進行協調。

這使得多個用戶端共享相同的工作階段，而無需將用戶端轉變為事實來源。當衝突發生時，主機會對結果進行排序，並且所有用戶端收斂到同一個狀態。

AHP 很容易逐步採用

最小的主機應該能夠透過根和工作階段通道、工作階段建立、基本輪次和狀態更新來提供有用的代理體驗。最小的用戶端應該能夠為工作階段呈現並提供交互，而無需實作所有高級功能。

協定新增應盡可能是附加的。高階主機和用戶端可以協商或忽略選用功能，而簡單的實作則繼續與它們所理解的協定部分進行互通。

AHP 對同步有自己的看法，而不是代理實作

AHP 對狀態權限、操作順序、通道路由、重播和協調有強烈的意見。它不應包含特定的代理循環、工具、模型提供者、工具模式、身份驗證系統、儲存後端或檔案系統假設。

相同的協定應該支援由 Git 儲存庫支援的傳統程式碼庫、沒有本機檔案系統的雲端工作區、僅限瀏覽器的用戶端、IDE 整合、CLI 和託管代理服務。

AHP 是面向通道的

AHP 中的每個推播式互動都限定在 URI 尋址的通道內。根狀態、工作階段、終端、變更集和未來的中繼資源都使用相同的基本訂閱和路由模型。

新的協定表面應刻意適應此模型：選擇擁有狀態或訊號的通道，使從方法和頂級通道 URI 進行路由成為可能，並避免與特定用戶端視圖的隱藏耦合。

AHP 是針對用戶端的示範模型

AHP 描述了顯示就緒的工作階段狀態和交互原語，用戶端可用於建立代理體驗。它不是實作代理循環、定義模型推理方式或將特定於後端的工具名稱公開為用戶端合約的地方。

主機將特定於代理的事件轉換為 AHP 操作和狀態。用戶端應該能夠從協定欄位而不是特定於提供者的元資料或私有工具詞彙表中呈現核心體驗。

AHP 保持逃脫艙口明確

該協定允許提供者特定的元資料、模型配置、自訂和未來的擴展點。這些對於實驗和特定於主機的完善很重要，但對於基線體驗來說不應該需要它們。

如果某個功能對於互通用戶端來說是必需的，那麼它應該從逃生艙過渡到類型化協定狀態或功能門控行為。

AHP 透過相容性和功能不斷發展

只要可行，新功能應該為舊的或較小的實作保留有用的行為。可選欄位、忽略的未知元資料和功能檢查優於強制每個用戶端和主機立即升級的變更。

當協定正在積極開發時，可能仍需要進行重大更改，但長期方向是用戶端可以測試功能並優雅降級的協定。

設計測試

在評估協定新增時，詢問：

• 最小的用戶端可以忽略這一點並且仍然呈現連貫的工作階段嗎？
• 持久的、使用者可見的結果是否在狀態中表示，而不僅僅是在臨時通知中？
• 主持人是否仍然擁有排序和解決衝突的權威？
• 這是否暴露了應該保留在主機邊界後面的代理實作細節？
• 該功能是否適合現有管道，或是否需要新的 URI 尋址管道？
• 用戶端能否透過功能或可選的狀態發現支援？
• 特定於提供者的元資料是增強功能而不是要求？

反目標

AHP 故意不定義：

• 代理如何推理、計劃、呼叫工具或管理上下文。
• 所需的模型提供者、模型路由器或憑證流。
• 通用後端工具註冊表或工具架構。
• 所需的 UI 佈局、編輯器整合或用戶端框架。
• 要求每個工作區都有一個本機檔案系統或 Git 儲存庫。
• 代理到代理協調語意。
• ACP 或其他下游代理協定的替代品。