託管與連接
在既有產品中託管 Heddle
Heddle 負責持久對話與執行機制，但不要求你的產品改用特定伺服器框架、傳輸方式、身分提供者、資料庫或 UI。
客製化深度
進階生命週期
託管深度
依宿主條件選擇
文件狀態
支援的 SDK 邊界
前置假設
- Agent 執行環境位於 Node.js 20+ 的 TypeScript/ESM 宿主中。
- 你的產品可以提供穩定的對話 ID，並決定誰可以存取。
- 你希望保留既有的 API、驗證、狀態管理與前端技術選擇。
Heddle 負責
- 持久對話、回合、壓縮、租約、追蹤紀錄、產物、工具與核准流程。
- 選用託管層後，提供可定址的執行 ID、依序活動、有界重播、明確取消與終結狀態。
- 選用遠端套件後，提供遠端 envelope 驗證、游標規則、重複與缺口處理，以及有界的重新連線計算。
產品端負責
- 身分、多租戶、授權、穩定的產品對話 ID 與存取政策。
- 伺服器框架、路由或 procedure、對外 schema、錯誤、CORS、限制、稽核與部署。
- UI 狀態、訊息、工具呈現、重試體驗、通知，以及最終結果如何套用至產品。
兩個彼此獨立的選擇
Heddle 的公開介面把客製化深度與託管條件分開。你可以在單一行程中使用完整對話引擎而不公開網路 API，也可以加入託管與遠端層級，同時保留已建立的產品行為。
相依方向應維持如下：
產品 UI 與客戶端狀態
|
@roackb2/heddle-remote + 選用的 HTTP/SSE 客戶端
|
你的傳輸轉接器、身分驗證與對外 schema
|
你的應用服務與組合根
================ HEDDLE SDK 邊界 ================
ConversationRunService
|
ConversationEngine
|
模型、工具、宿主擴充與 MCP邊界上方的應用服務仍是你的程式碼。它把經過驗證的產品身分對應到穩定對話 ID，使用產品工具與憑證建立引擎，並決定哪些內部資料可以成為對外輸出。
選擇最小且符合需求的層級
| 你的產品已經具備 | 從這裡開始 | 支援層級 |
|---|---|---|
| TypeScript 行程，尚無 Agent UI | runQuickstartConversationCli | 支援的 SDK 進入點 |
| 自有的本機輸出或生命週期 | @roackb2/heddle 的 createConversationEngine | 支援的 SDK 進入點 |
| 伺服器、worker 或 Electron 後端 | @roackb2/heddle/hosted 的 ConversationRunService | 支援且可直接執行 |
| 使用 REST 與 SSE 的 Express | @roackb2/heddle/hosted/http-sse | 支援的 helper 與可執行 Express 參考 |
| 透過任意傳輸層連線的遠端 JavaScript 客戶端 | @roackb2/heddle-remote | 支援的傳輸層中立套件 |
| 使用慣例 REST/SSE contract 的瀏覽器 | @roackb2/heddle-remote/http-sse | 支援且可直接執行 |
| React/Vite 前端 | Hosted React 範例 | 可執行的參考產品，不是 React SDK |
| tRPC、Fastify、Hono、Nest、WebSocket、IPC 或 queue | 託管服務加上你的轉接器 | 調整指南 |
| 多行程或 serverless 執行 | 託管服務加上共享路由或傳遞機制 | 架構指南 |
不要只因為參考範例使用 Express 或 React 就安裝它們。若產品已有其他伺服器或客戶端架構，應停在傳輸層中立的託管服務。
持久邊界
對話是持久狀態；執行（run）則是針對該對話的一次可定址工作。兩者分開後，HTTP request 可以在接受執行後立即回傳，模型與工具仍能繼續工作；客戶端可以中斷並重新連線而不重啟工作；後續回合也能重用同一個持久對話。
每個產品對話應使用一個穩定的 Heddle session ID。不要在每次 prompt 中重播另一份產品對話紀錄、建立第二套宿主 run ID，或在 Heddle 執行串流外再加一條行程內事件匯流排。這些平行路徑會產生互相衝突的事實來源。
依需求繼續
- 若工作必須超過單次 request，或需要取消、核准與可重新連線的訂閱端，請閱讀長駐執行服務。
- 若慣例 REST/SSE contract 符合你的伺服器，請閱讀 Node HTTP/SSE。
- 若不受信任的事件會跨越網路邊界，請閱讀遠端客戶端。
- 在把生命週期轉換到既有框架前，先閱讀調整至其他技術棧。
- 在把參考範例當成已部署服務前，完成正式環境檢查表。