DeepSeek Harness API Gateway 遠端呼叫指南

DeepSeek Harness API Gateway 是 Host Business Service 與 Client Code 之間的型別安全橋梁。它利用 Typert Descriptor，只公開明確標記的方法，產生實際的 Client Function 與型別，再透過既有 /api Connection 完成呼叫。設計重點不是讓 Client 任意操作 Host，而是讓跨處理程序邊界清楚、可驗證也可審查。

本文依據 DeepSeek Harness 官方中文 API Gateway 文件 改寫。實作 Remote Method 時，請同步查看官方文件與目前原始碼。

API Gateway 解決什麼問題

Host 可以存取檔案、Session、Tool 和其他高權限資源，瀏覽器 Client 不該直接 Import 或操作這些物件。Gateway 選擇性發布 Business API，同時保留 Argument 與 Result 的型別資訊。

這項設計提供：

• 明確列出的 Remote Method Allowlist；
• 由產生器建立 Client Contract，減少手寫 Request Wrapper；
• 統一的 Runtime Transport，可以在邊界驗證 Descriptor 與輸入。

Gateway 不是傳送任意 Host Object 的捷徑。某個物件在同一 Process 內安全可用，不代表它的 Prototype、Open Handle 或內部狀態可以跨連線序列化。

@Remote 與 @RemoteScope

Typert 把 Remote API 分成：

• @Remote：標記 Root Host Service；
• @RemoteScope：標記與某個 Cordis Scope 綁定的行為。

只有明確 Decorate 的 Method 才會公開。即使 Helper 在 TypeScript 是 public，沒有標記仍屬於 Host 內部。這項限制能避免重構 Class 時，因新增 Method 而意外擴大 Client 權限。

Scoped API 適合從屬於特定 Agent 或 Context 的操作。產生後，Client 通常從 ctx.remote.<namespace> 或 agentCtx.remote.<namespace> 呼叫。

Service 實作與 Object Identity

Remote Service 通常繼承 TypertRemoteService，或透過 bindTypertRemote 綁定，讓 Service Definition、產生 Descriptor 和 Runtime Handler 串在一起。

複雜 Host Object 不應整個序列化。比較穩妥的方式是只傳遞穩定 ID，再由 Host Lookup Map 取回物件。這樣能保留 Ownership Boundary，也避免把只能在 Process 內使用的 Handle 或 Method 傳給 Client。

Argument 與 Response 優先採用可驗證的 Plain Data。若 Client 需要行為，可以回傳資料，再由 Client 自己處理呈現與互動。

Client 是產生函式，不是動態 Proxy

Client API 是實際產生的 Function，不是執行期間臨時拼出 Method 的 JavaScript Proxy。Concrete Function 對自動完成、靜態型別檢查、Build Analysis 和錯誤定位都更有利。

Generation Pipeline 刻意維持嚴格：Host Descriptor 改變後，必須先更新 Client Contribution，後續 Layer 才能編譯。因此 Root Build 採 Host → Client → Web 的順序。完整環境設定請參考 DeepSeek Harness 開發指南。

Runtime Request 格式

Runtime Call 會重用 Connection 與 /api Route，概念上的端點是：

POST /api/<namespace>/<method>

Payload 形式為：

{ "args": [] }

Descriptor 負責 Argument 和 Result 的 Encoding 與 Validation。因此 Namespace 與 Method Name 都是 Remote Contract 的一部分；即使 Host 內部邏輯沒變，直接更名仍可能讓既有 Client Call 失效。

Cooperative Cancellation

當 Remote Function 最後一個參數是 signal: AbortSignal，這項呼叫可以支援協作式取消。位置與型別都是 Convention。Host Implementation 還必須把 Signal 傳進可取消工作，並在長時間 Loop 中檢查。

取消並非強制終止整個 Process。若 Implementation 等候外部操作時完全忽略 Signal，Client 即使提出取消，工作仍可能持續到外部操作回傳。

安全邊界與輸入驗證

即使 Client UI 與 Host 來自同一專案，也應把 Client Request 視為不可信輸入。在 Host 端驗證 Descriptor、Argument、Object ID 與 Authorization Context；TypeScript 型別在編譯後不會自動提供 Runtime 保護。

公開 Method 前，請確認：

• Client 是否真的需要完整能力，還是只需要較小操作；
• 每個 Argument 能否序列化並在 Runtime 驗證；
• Object ID 是否可能越過目前 Agent Scope；
• 長時間操作是否應支援取消；
• Response 是否會洩漏檔案路徑、憑證或私人 Session Data。

Scope 與 Service 背景可查閱 架構解析 及 核心術語表。

API Gateway 錯誤排查

如果 Client 找不到 Method，先確認 Host Method 是否有明確標記，以及 Generation 是否在 Client Build 前完成。Method 存在但呼叫失敗，再檢查 Namespace、Method、Argument Encoding、Host Lookup 和 Runtime Descriptor Validation。取消失效時，要同時確認最後一個 AbortSignal 與執行耗時工作的下游程式碼。

先分辨 Contract 尚未產生，還是 Runtime Transport 失敗，才能避免在 API 根本不存在時反覆除錯 UI。

官方原文

本文依據 DeepSeek Harness 官方 API Gateway 文件（中文） 獨立整理，查核日期為 2026-08-20。Decorator、Generated Contribution 與 Transport 細節，以官方文件及原始碼為準。