Purview 是什麼

Purview 實作了 MCP GUI Bridge Protocol v0.1.0。它位於你真正的 GUI 與 MCP 客戶端之間，對外提供應用程式的一份投影：一組視窗，每個視窗承載語義化的內容區塊（欄位、表格、清單、提示、媒體……）以及動作。

你永遠不需要自己組裝協定訊息。你只負責描述視窗並讓它保持最新；剩下的由函式庫對外提供。

為什麼叫 Purview

英文裡的 purview 指一個人被允許看到、被允許決定的範圍——常見搭配是 within the purview of（在……的職權範圍之內）。這恰好就是投影的含義：投影就是 agent 對你的應用程式所擁有的 purview。你放進投影的內容，agent 才讀得到；你公開出來的動作，agent 才呼叫得到。其餘的一切並不是被一道權限檢查擋在門外——它根本不會出現在協定訊息裡。

這個詞裡還藏著 view，這正是故事的另一半：agent 拿到的始終是你 GUI 的一份檢視，而不是 GUI 本身。它無法點擊你的按鈕，也無法越過投影去碰你的元件；它只能透過你定義的動作，請求某件事發生。

三個核心理念

核心不綁定框架。 purview crate 不連結任何 GUI 工具組。它只透過你在啟動時註冊的一個閉包來抵達主執行緒。

語義化，而非像素。 Agent 讀到的是結構化的內容區塊——帶標籤的欄位、具型別的列——而不是一張需要它費力解讀的螢幕擷圖。

協定由函式庫掌管。 動態 tools/list、模態鏈、樂觀並行、遮蔽、通知：全部由你維護的那份投影推導得出。

我該用哪個 crate？

Crate	使用時機
purview	總是需要。它是核心：投影、協定、伺服器。
purview-gpui	你的 UI 用的是 gpui。它省去執行緒調度的樣板程式碼——參見 使用 purview-gpui。

心智模型

只有兩條流向，而把它們分清楚是最重要的一個習慣：

讀取側（GUI → 函式庫）。 你 UI 的變更事件透過你保留的具型別控制柄，把值推入投影。這是內容區塊唯一會改變的地方。

寫入側（Agent → GUI）。 每個動作都會變成一個 MCP 工具。它的處理器觸發真正的業務邏輯或 GUI 操作；它不會直接修改投影——變更會經由讀取側流回來。

為何重要

如果處理器直接寫入投影，那麼 Agent 驅動的變更與人類驅動的變更就會走不同路徑，最終必然互相矛盾。把所有變更都匯入同一個方法——本指南的範例都只用單一的 sync() 或 bump()——投影就不可能產生偏離。

你會持有的三樣東西

控制柄	來自	用途
AppHandle<Cx>	build()	開啟視窗；讀取快照
Window<Cx>	app.open(title)	摘要、內容區塊、動作、模態、關閉
內容區塊控制柄	win.blocks().fields(..) 等	之後更新該內容區塊

它們全部都可以廉價地 clone，都是 Send + Sync，並且只持有共用核心的弱引用——所以你可以把它們存放在 GUI 元件裡，並從任何執行緒呼叫。一旦核心被釋放，它們的操作就會安全地變成無作用的空操作。