語言EN繁
首頁
文件

可執行的參考產品

在執行 protocol 上建立產品 UI

React 範例展示 Heddle 遠端 protocol 上方仍需由產品擁有的完整生命週期。它是參考應用程式，不是 React component package，也不是強制的前端架構。

客製化深度

產品 UI

託管深度

React、Vite 與 React Query 參考

文件狀態

可執行參考範例

前置假設

  • 託管服務、對外 schema 與 REST/SSE API 已經可用。
  • 瀏覽器支援 streaming `fetch`，而且產品可以維持穩定的對話 ID。
  • 範例中的 React、Vite、React Query 與 AI Elements 適合你的評估，或可以轉換到既有前端技術棧。
Heddle 負責
  • 對話持久化、run identity、依序重播、取消、終結語意、protocol validation 與 HTTP/SSE mechanics。
  • 透過 remote consumer 提供 cursor、duplicate、gap、terminal 與 reconnect 計算。
產品端負責
  • 經驗證的對話存取、server session endpoint、對外欄位 allowlist 與瀏覽器儲存選擇。
  • Server-state query、optimistic message、活動呈現、retry/error UX、通知與視覺設計。
  • 部署、無障礙決策、產品結果套用，以及 Agent 周邊的所有業務流程。

這個參考產品驗證了什麼

Hosted example 的最後一個階段是在 REST/SSE protocol 上建立的小型可執行產品，示範：

  • 穩定的 session identity 與 server-backed message hydration；
  • 接受 user prompt 後立刻以 optimistic UI 呈現；
  • Assistant text 與安全的 tool/lifecycle activity 分開顯示；
  • 瀏覽器 reload 後重新發現 active run；
  • 有界重新連線、可見 failure 與手動 retry；
  • 明確 stop 與可見的 cancelled terminal；
  • 收到 terminal 後重新讀取 durable message；
  • 第二個 prompt 延續同一個 persisted session；
  • 只在 idle 狀態允許 reset，並使用無障礙 confirmation。

分開 server state 與 live run state

參考產品使用 React Query 從宿主 API 讀取持久對話，而 run 是另一個 live resource。啟動 run 後，client 會把 accepted runId 寫入 cached conversation，並加入 optimistic user message。收到 terminal 後，client 會清除 active run，再從 server 重新取得 durable message。

這個分工可避免瀏覽器把 streamed text 當成持久對話紀錄。若 terminal 已到達但 refresh 失敗，UI 會回報明確的 reconciliation error，而不是假裝串流內容已經持久化。

同時保存游標與畫面投影

可在 reload 後復原的 client，必須同時 checkpoint 傳遞進度與已呈現給使用者的投影：

TypeScript
type RunCheckpoint = {
  runId: string
  afterSequence: number
  assistantText: string
  activities: ActivityView[]
}

如果只還原 afterSequence，server 會跳過已接受的 event，但畫面無法重建那些 event 所產生的 assistant text 與 activity。請原子地推進 cursor 與 rendered projection。使用儲存資料前先驗證，丟棄 malformed checkpoint，並在 storage unavailable 時清楚降級。

收到 terminal 或 reset conversation 後要清除 checkpoint。如果 server 回報的 active run 與 stored checkpoint 不同，請丟棄舊 checkpoint，不要把一個 run 的 projection 套用到另一個 run。

組合 remote client，不要把 UI state 放進 protocol

Product client 公開 Heddle 的 start、subscribe 與 cancel 操作，並另外實作宿主專屬的 conversation read/reset call。Session API 不應被塞進 generic run client。

React hook 擁有真正的瀏覽器生命週期：component unmount 時 abort subscription、依序接受 event、render 後保存 checkpoint、排程 retry、terminal 後 refresh、stop 與 reset。底層 Heddle remote service 仍保持 framework-neutral。

呈現與無障礙

生成的 Markdown 應透過安全 Markdown component 呈現，不要直接使用 raw HTML 或純文字。Assistant prose 與 tool/lifecycle summary 應分開，避免不小心顯示敏感 input 或 result。清楚呈現 loading、starting、running、stopping、error 與 ready state；status 使用 live region；生命週期前置條件不成立時停用 submit/reset action。

參考產品包含精簡的 AI Elements message component，但刻意省略 syntax highlighting、數學式、Mermaid 與 CJK plugin。只加入產品真正需要的呈現能力。

替換範例技術選擇

React、Vite、React Query、local storage、AI Elements 與視覺設計都是可替換的宿主決策。如果產品已使用 Next.js、Vue、Svelte、Solid、Redux、Zustand、XState 或其他 query library，請在原架構中保留生命週期 invariant，不必安裝範例技術棧。

Build-time bearer token 只用於受到限制的本機 demo server，而且瀏覽器可以看見。正式環境 authentication 必須使用產品既有的 session 或 token design。參考產品不會替你發明 approval、billing、rate-limit 或 deployment policy。

驗證邊界

此範例會隨 Heddle build 一起編譯，重要的 checkpoint validation 與安全 activity projection 也有 unit test。它不是官方 React SDK，也不代表每一條產品流程都有完整的 browser end-to-end coverage。

權威來源