DeepSeek Harness API Gateway 远程调用指南

DeepSeek Harness API Gateway 是 Host 业务服务与 Client 代码之间的类型安全桥梁。它通过 Typert 描述符只暴露明确标记的方法，生成具体的 Client 函数和类型，并复用现有 /api 连接完成调用。它的重点不是“让前端能调用所有 Host 方法”，而是把跨进程边界变得明确、可验证、可审查。

本文依据 DeepSeek Harness 官方中文 API Gateway 文档 二次编写。实现远程方法时，请同时查阅官方原文与当前源码。

API Gateway 解决什么问题

Host 能访问文件、Session、工具和其他高权限资源，浏览器 Client 不应直接导入或操纵这些对象。Gateway 选择性发布业务接口，同时保留参数与返回值的类型信息。

这种设计带来三个直接好处：

• 远程方法采用显式白名单；
• Client 契约由代码生成，不必手写重复的请求封装；
• Runtime 可以在统一传输层校验描述符与输入。

Gateway 并不适合传输任意 Host 对象。进程内安全可用的对象，可能包含原型、文件句柄或无法序列化的状态，跨过连接后就不再成立。

@Remote 与 @RemoteScope

Typert 把远程接口分为两类：

• @Remote 标记根级 Host Service；
• @RemoteScope 标记与某个 Cordis Scope 绑定的行为。

只有被明确标记的方法才会对外暴露。即使 TypeScript 中的 Helper 是 public，没有对应标记也仍属于 Host 内部。这项约束非常重要：日常重构 Class 时，不会因为新增一个方法就意外扩大 Client 权限。

Scoped API 适合属于特定 Agent 或 Context 的调用。生成后，Client 通常通过 ctx.remote.<namespace> 或 agentCtx.remote.<namespace> 访问。

Service 实现与对象身份

远程 Service 通常继承 TypertRemoteService，或使用 bindTypertRemote 绑定。它们把 Service Definition、生成描述符与运行时 Handler 连接起来。

复杂 Host 对象不要整体序列化。更稳妥的方式是只传递稳定 ID，再由 Host Lookup Map 找回真实对象。这样可以保留所有权边界，也能避免把进程内句柄和对象方法错误地发送给 Client。

参数和响应应优先使用可校验的普通数据。如果 Client 需要行为，可返回数据，再由 Client 自己负责交互和展示逻辑。

Client 使用生成函数而非 Proxy

Client API 是实际生成的具体函数，并非运行时动态“猜出”方法的 JavaScript Proxy。具体函数对自动补全、静态类型检查、构建分析和错误定位都更友好。

生成管线是严格的：Host 描述发生变化后，要先更新生成的 Client Contribution，依赖层才能继续编译。因此根构建采用 Host → Client → Web 的顺序。完整环境与检查命令可查看 DeepSeek Harness 开发指南。

远程请求格式

运行时调用复用 Connection 和 /api 路由，概念上的地址是：

POST /api/<namespace>/<method>

请求体形如：

{ "args": [] }

描述符负责参数和结果的编码与校验。因此 Namespace 与 Method Name 都是远程契约的一部分；即使 Host 内部逻辑没变，随意更名也会导致已有 Client 调用失效。

如何支持协作式取消

如果远程函数的最后一个参数是 signal: AbortSignal，该调用可以支持协作式取消。参数位置和类型都属于约定。Host 实现还必须把 Signal 继续传给可取消的底层任务，并在长循环中主动检查。

这里的“取消”不是强制结束整个进程。如果实现等待某项外部操作时完全忽略 Signal，Client 虽然发出了取消请求，工作仍可能等到外部操作结束。

安全边界与输入校验

即使 Client UI 与 Host 来自同一项目，也应把每次 Client 请求视为不可信输入。在 Host 侧校验描述符、参数、对象 ID 与授权 Context。TypeScript 类型在编译后不会自动提供运行时保护。

暴露方法前，应逐项确认：

• Client 是否真的需要整项能力，还是只需要更窄的操作；
• 每个参数能否序列化并进行运行时校验；
• 对象 ID 会不会越过当前 Agent Scope；
• 长操作是否应该支持取消；
• 响应是否可能泄露文件路径、凭证或私人会话数据。

Scope、Service 和插件边界可进一步阅读 架构解析 与 核心术语表。

API Gateway 报错怎么排查

如果 Client 根本找不到方法，先检查 Host 方法是否明确标记，以及生成步骤是否在 Client 构建前完成。方法存在但调用失败，则检查 Namespace、Method、参数编码、Host 对象查找与运行时描述符校验。取消不生效时，要同时验证末尾 AbortSignal 与真正执行耗时操作的下游代码。

先区分“契约没有生成”和“运行时传输失败”，可以避免在接口根本不存在时反复调试 UI。

官方原文

本文依据 DeepSeek Harness 官方 API Gateway 文档（中文） 独立整理，核对日期为 2026-08-20。装饰器、生成产物与传输细节以官方文档和源码为准。