從這裡開始 · 架構選擇器
選擇整合層級
保留既有架構，並只採用已經擁有產品所需 runtime mechanics 的最低 Heddle 層級。
客製化深度
獨立的 Level 1–5
託管深度
獨立的 Level A–F
文件狀態
權威參考
前置假設
- 你知道產品已經擁有哪些 server、transport 與 UI layers
- 你希望 Heddle 負責可重用 Agent mechanics，但不成為 application framework
Heddle 負責
- 對話語意、工具、追蹤、產物與核准生命週期
- 選用的行程內 run identity、重播、取消與遠端 protocol correctness
產品端負責
- 既有 server 與 client framework choices
- 身分、授權、對外 API、持久化政策、部署與 UI
依產品端目前已有的部分選擇
| 既有產品形態 | 從這裡開始 | 狀態 |
|---|---|---|
| 只有 TypeScript 行程 | runQuickstartConversationCli | 支援的 SDK 邊界與可執行範例 |
| 本機行程需要產品工具或 MCP | Quickstart 加 host extensions | 可執行範例 |
| 行程已經負責輸出或本機 UI | createConversationEngine | 支援的 SDK 邊界 |
| Server、worker 或 Electron backend | @roackb2/heddle/hosted | 支援的邊界與可執行 service 範例 |
| Express + REST/SSE | @roackb2/heddle/hosted/http-sse | 支援的 helper 與可執行 Express 範例 |
| 任意傳輸上的遠端 JavaScript client | @roackb2/heddle-remote | 支援的 browser-safe protocol package |
| 使用慣例 REST/SSE contract 的瀏覽器 | @roackb2/heddle-remote/http-sse | 支援的 helper 與可執行 client 範例 |
| React/Vite 產品 | Remote client 加 React reference | 可執行 reference，不是 React SDK |
| Fastify、Hono、Nest、tRPC、WebSocket 或 IPC | Hosted service 加產品端 adapter | 調整指南 |
| Multi-process 或 serverless active runs | Hosted service 加 shared routing/delivery | 架構指南 |
客製化與託管是兩個不同決定
Root @roackb2/heddle package 提供漸進式客製化階梯：
- 建立可持久化對話；
- 加入工具、MCP 與能力專屬 context；
- 調整輸出並處理結果；
- 接管 session、核准與生命週期；
- 注入正式環境的 session 與 artifact storage。
託管是選用的第二個維度。只有 execution 需要獨立定址、取消或重新連線時，才加入 /hosted；只有事件會跨越傳輸邊界時，才加入 remote package。
套件進入點的假設
| Import | 新增的假設 |
|---|---|
@roackb2/heddle | Node host 需要 curated conversation SDK |
@roackb2/heddle/hosted | 一個長駐行程負責 active runs 與有界重播 |
@roackb2/heddle/hosted/http-sse | 產品選擇 conventional Node HTTP/SSE framing |
@roackb2/heddle-remote | JavaScript client 使用經驗證的 run envelopes |
@roackb2/heddle-remote/http-sse | Client 選擇 conventional REST/SSE resource |
@roackb2/heddle/advanced | Node host 需要 lower-level runtime assembly |
Advanced entrypoint 不會自動加入 hosted 或 remote transport。
停在傳輸中立邊界
使用 tRPC、Fastify、Hono、Nest、WebSocket、Electron IPC 或 queue 時，請停在 transport-neutral run service，並在產品既有 framework 內實作 adapter。保留 stable run identity、ordered sequence、cursor replay、explicit cancellation 與 exactly one terminal event。
實作前請繼續閱讀責任邊界；如果你從零開始評估，則前往第一個 Agent 教學。