多節點架構

概述

多節點架構使多台裝置協同工作，實現**「A 裝置對話、B 裝置執行」**的分散式體驗。Gateway 作為中央調度樞紐，管理所有節點的註冊、發現和智慧路由。

架構總覽

                      
                      ┌─────────┐   WebSocket   ┌─────────────┐   WebSocket   ┌──────────┐
│ Web 端   │ ◄────────────► │   Gateway    │ ◄────────────► │ APP 節點 A│
│(Browser) │               │  (Node.js)   │               │ (macOS)  │
└─────────┘               │              │               └──────────┘
                          │  - 節點註冊    │
                          │  - 智慧路由    │               ┌──────────┐
                          │  - 訊息轉發    │ ◄────────────► │ APP 節點 B│
                          │  - 權限驗證    │               │(Windows) │
                          └─────────────┘               └──────────┘

                    

節點類型

節點註冊資訊

每個節點連接 Gateway 時註冊以下資訊：

節點可見範圍

account 級節點：使用者在多台裝置上登入，可以在任意裝置間調度任務。

enterprise 級節點：組織內的共享執行資源，所有成員都可以透過 Gateway 使用。

Gateway 智慧路由

當 Web 端使用者發起對話時，Gateway 使用三級降級策略選擇最合適的執行節點：

第一級：LLM 語意路由

使用 OpenAI API 分析使用者意圖，匹配最佳節點：

LLM 回傳：{nodeId, confidence, reason}

安全措施：

• 節點描述作為 DATA 處理，不作為指令執行
• 防止透過節點描述進行提示注入

注意：目前 LLM 路由尚未設定模型，會自動降級到第二級。

第二級：BM25 關鍵字匹配

基於 BM25 演算法對使用者查詢和節點描述進行關鍵字匹配：

回傳得分最高的節點，或 null（無匹配）。

第三級：最近連接兜底

按 connectedAtMs 時間戳選擇最近連接的節點，確保始終有兜底結果。

遠端執行

對話流程

                      
                      1. Web 端傳送 chat.send 到 Gateway
2. Gateway 執行智慧路由，選擇目標節點
3. Gateway 轉發訊息到 APP 節點
4. APP 節點啟動 Agent Loop 執行任務
5. 執行過程中的串流事件透過 chat.event 回傳
6. Web 端即時渲染執行過程

                    

遠端工具呼叫

                      
                      1. 主 Agent 透過 dispatch_multi_node_agent 指定遠端節點
2. Gateway 傳送 node.invoke.request 到目標節點
3. 遠端節點啟動獨立 Agent Loop
4. 完成後透過 node.invoke.result 回傳結果

                    

附件 Hoisting（2026-04 更新）NEW

跨節點派發時，如果訊息包含內聯 base64 附件（圖片、文件等），系統會自動上傳到雲端儲存並改為 URL 引用：

• 原因：避免 Gateway RPC 訊息過大導致傳輸失敗
• 時機：遠端派發前自動執行，使用者無感知
• OS 路徑歸一化：跨作業系統（macOS/Windows/Linux）派發時自動轉換路徑分隔符

權限彈窗分發規則

跨節點執行時，工具權限彈窗「在哪一端展示」是關鍵的產品決策 —— 需要在「使用者能及時回應」和「防止越權觸發敏感操作」之間取得平衡。

同帳號場景（呼叫方與執行方為同一帳號）

不同帳號場景（enterprise node 跨帳號呼叫）

• node-D 是 enterprise 類型節點（同組織內可被其他使用者發現），目前登入 user001
• node-E（登入 user002，APP 或 Web 端均可）透過 Gateway 向 node-D 傳送訊息
• 若 node-D 執行中需要工具權限：
  • 彈窗僅在 node-D 本機介面顯示，不跨端分發到 node-E
  • 無人回應超過 5 分鐘預設拒絕

設計動機

實施提醒：node-A APP → node-B APP 的同帳號跨端分發鏈路目前不存在。涉及該路徑的需求需新增 Gateway 路由 + APP 端接收/展示邏輯，不要預設它已可用。

跨帳號 Gateway 隔離 NEW

除了權限彈窗的位置規則外，資料存取本身也有隔離：

個人記憶隔離

當節點以 enterprise 範圍被跨帳號呼叫時：

• 帳戶級記憶（userId 綁定）：❌ 不可存取
• 企業級記憶（orgId 綁定）：✅ 可存取
• 會話級記憶（本次會話）：✅ 可存取

透過 isRemoteSession 標誌在記憶查詢時強制過濾 —— 跨帳號呼叫者無法透過 memory_query 讀取目標節點所有者的個人記憶。

為什麼這樣設計

• 隱私保護：你的個人偏好、工作習慣、帳戶資訊不能被同事透過呼叫你的節點讀取
• 企業共享：組織的技術棧、規範等企業知識仍正常共享，不影響協作
• 合規需求：滿足 GDPR 等隱私法規對「最小權限」的要求

對話圖示區分

會話清單中不同來源的對話顯示不同圖示：

基於 isLocalInitiated、targetNodeId 和 sourceChannel 欄位判斷。

WebSocket 協定

連接握手

                      
                      1. Client → Gateway: connect.challenge
2. Gateway → Client: challenge（含 nonce）
3. Client → Gateway: connect（含簽名的 JWT）
4. Gateway → Client: hello-ok（確認連接）

                    

心跳保活

• tick 機制：定期心跳維持連接
• 斷線重連：指數退避重試
• 過期清理：Gateway 定期清理過期節點會話

流量控制

• Delta 節流：SSE 串流事件 150ms 聚合，減少 WebSocket 幀數
• Run TTL：10 分鐘逾時，每小時清理過期 Run

對使用者意味著什麼

多節點架構讓你可以在任何地方發起任務，讓最合適的裝置來執行。

典型場景：

• 在咖啡廳用手機瀏覽器（Web 端）發起一個需要存取辦公室電腦檔案的任務 → Gateway 自動把任務路由到辦公室的 APP 節點執行
• 團隊裡一台高效能伺服器（macOS Pro）始終開著 APP 設為 enterprise → 所有團隊成員都可以從自己的瀏覽器把重活派發過去

你能感受到的體驗：

• 在 Web 端發起對話時，系統自動選擇一個線上的 APP 節點來執行
• 會話清單中會顯示不同的圖示，讓你知道對話是本機執行還是遠端執行
• 如果沒有 APP 節點線上，Web 端會提示無法執行需要 Agent 能力的任務
• 多台電腦都安裝了 APP 時，可以手動選擇在哪台電腦上執行

你需要注意的：

• Web 端無法獨立執行 Agent 任務，需要至少一個 APP 節點線上
• 遠端執行的對話有網路延遲（取決於 Gateway 和節點間的網路品質）
• 設定節點為 enterprise 範圍時，團隊成員可以將任務派發到你的裝置上 —— 但你的個人記憶不會被存取到

相關文件

• Work 節點管理 — 管理介面查看線上節點
• 執行時安全 — 節點 — 節點安全設定
• 子代理 — 跨節點派發 — dispatch_multi_node_agent
• 三維記憶系統 — 跨帳號記憶隔離