DeepSeek Harness 远程调用两条路:Typert 与 Gateway 各管什么场景
Typert 和 API Gateway 都能「从外面调到一个能力」,所以经常被当成二选一。 其实它们在不同层:Typert 解决「怎么找到并调用一个能力」,Gateway 解决「把哪个能力暴露给谁」(来源)。先分清层,再谈选型。
DeepSeek Harness 两条路的定位:能力调用 vs 网关暴露
一句话:Typert 是内部远程调用,Gateway 是外部接口层。 Typert 关注能力寻址、描述与调用;Gateway 关注暴露面、入口与边界。(来源)
这个分层带来两个结论:
- Typert 不负责对外暴露 — 它能让调用方找到能力,但不决定谁能从外部访问;
- Gateway 不负责能力发现 — 它把已经选定的能力暴露出去,不替调用方做 lookup。
把两者混在一起,常见结果是「能力能调,但外部访问没有边界」或「网关暴露了,但调用方不知道参数形状」。前者是安全问题,后者是契约问题。
判断方法:问「调用方是谁」。内部插件、同进程或受控进程,用 Typert;外部系统、浏览器或第三方,用 Gateway 或 Web server 路由。
DeepSeek Harness Typert 三层:lookup、descriptor、call
Typert 的调用链分三层,每层解决一个问题。 官方把它拆成 lookup、descriptor 与 call(来源)。
| 层 | 做什么 | 失败时的表现 |
|---|---|---|
| lookup | 按名称/标识找到能力 | 找不到、名字错、作用域不对 |
| descriptor | 读取参数与结果描述 | 参数形状不明、编码不匹配 |
| call | 发起调用并处理流/取消 | 调用失败、流中断、取消未生效 |
lookup 失败通常不是「能力不存在」,而是「名字或作用域不对」。descriptor 失败则更像「版本不匹配」:调用方按旧描述传参,提供方已经改了形状。
call 层要处理三件事:结果编码、流式响应、取消。只测「调用成功」不够,还要测「中途取消」与「流断开」,否则上线后才暴露。
Typert 的价值在于把这三层标准化:调用方不需要知道提供方在哪个进程,只需要知道能力名与描述。
DeepSeek Harness API Gateway 的暴露面与鉴权
Gateway 的职责是「暴露哪一扇门」,不是「能力怎么实现」。 官方把 Gateway 描述为把能力暴露为外部接口的层(来源)。
三个必须明确的问题:
- 暴露哪些能力 — 不是所有内部能力都该对外;暴露面越小,风险越低;
- 谁可以调用 — 认证、授权、限流、审计分别放在哪一层;
- 失败怎么返回 — 统一错误形状,避免泄露内部实现细节。
Gateway 不自带「安全」这个属性。能被 Gateway 暴露,只说明它可达;是否安全,取决于鉴权、网络边界与输入校验。
一个常见错误是把内部管理能力也暴露出去,理由是「反正有鉴权」。鉴权只回答「谁能调」,不回答「该不该暴露」;两者要分开判断。
DeepSeek Harness 四种场景选型
四种场景覆盖大多数选择,按调用方与边界判断即可。 对照如下(来源):
| 场景 | 调用方 | 推荐路径 |
|---|---|---|
| 同进程插件互调 | 插件 | 直接用 Context/Service,不需要 Typert |
| 跨进程内部调用 | 受控进程 | Typert |
| 浏览器/客户端调用 | Web 页面 | Web server 路由或 Gateway |
| 第三方系统集成 | 外部服务 | API Gateway,配鉴权与限流 |
第一种最容易被过度设计:同进程插件之间已经有 Service 与 Registry,不需要再走远程调用。加一层 Typert 只会增加序列化与错误面。
第二种是 Typert 的主场:调用方需要按能力名寻址,不想绑定具体进程或实现。第三种更偏 HTTP 路由,Typert 的 descriptor 在这里不是必须的。第四种才需要 Gateway 的暴露面与治理。
选型时先定调用方,再定边界,最后定协议。顺序反了,容易出现「为了用 Typert 而用 Typert」。
DeepSeek Harness 权限与资源边界
两条路都要回答「谁在调用、能碰什么」,但答案位置不同。 Typert 的权限通常在能力注册与调用层处理;Gateway 的权限在入口与暴露面处理(来源)。
三个边界建议:
- 能力级权限 — 某个能力是否允许被远程调用,应在注册时明确;
- 调用方身份 — 调用方是谁,是否有权调用该能力;
- 资源范围 — 调用能访问哪些文件、会话或工作区。
Typert 的调用方可能是内部进程,身份相对可信,但也不能假设「内部就等于无限权限」。Gateway 的调用方可能完全不可信,输入校验与限流必须前置。
一个实用原则:权限判断放在最靠近资源的一层,暴露面只做必要的粗粒度拦截。两层都做细粒度判断,容易不一致;只做一层,又可能被绕过。
DeepSeek Harness 验证:同一能力两条路各跑一次
验证选型,最好的方法是把同一个能力用两条路各跑一次,比较差异。 四步(来源):
- Typert 调用 — 按能力名 lookup、读 descriptor、调用成功,再测取消与流断开;
- Gateway 调用 — 从外部入口调用同一能力,确认鉴权、限流与错误形状;
- 权限对照 — 同一调用方在两条路上的权限是否一致,是否有绕过路径;
- 失败对照 — 能力不存在、参数错误、超时三种失败,两条路的返回是否都可解释。
四步走完,你会清楚两条路各自多做了什么、少了什么。只测成功路径,选型问题通常要上线后才暴露。
旧文 develop-typert-rpc 讲 Typert 的 lookup/descriptor/call,dsh-api-gateway-explained 讲 Gateway 暴露机制,develop-web-server-routes 讲 HTTP 路由;本篇补的是两条路的选型。先定调用方,再定层。
常见问题
DeepSeek Harness 的 Typert 负责能力寻址、描述与调用,API Gateway 负责把选定能力暴露给外部调用方。前者是内部远程调用机制,后者是外部接口层。
DeepSeek Harness 里,当调用方需要按能力名寻址、复用描述符与流式调用时用 Typert;只需要一个固定 HTTP 端点、由外部系统按路径调用时,用 API Gateway 或 Web server 路由更直接。
DeepSeek Harness 的 Gateway 负责暴露面与调用边界,鉴权仍需按部署配置处理;不要把「能被 Gateway 暴露」等同于「已经安全」。
DeepSeek Harness 里,Typert 的能力寻址可以跨越进程边界,但跨机器还依赖连接与传输层配置。跨机器场景应同时检查 Gateway、Web server 与网络边界,而不是只看 Typert。
相关术语
- Typert
- Typert 是 DeepSeek Harness 的能力远程调用机制,包含 lookup、descriptor 与 call 三层,用于按能力名寻址并调用远程实现。— DeepSeek Harness 官方文档 - Typert
- API Gateway
- API Gateway 是 DeepSeek Harness 把能力暴露为外部接口的层,负责请求入口、暴露面与调用边界。— DeepSeek Harness 官方文档 - API Gateway
- lookup
- lookup 是 Typert 的第一层,按能力名或标识找到可调用的对象。— DeepSeek Harness 官方文档 - Typert
- descriptor
- descriptor 是 Typert 的描述层,说明参数、结果与编码方式,让调用方知道怎么调用。— DeepSeek Harness 官方文档 - Typert
来源
- DeepSeek Harness 官方文档 - Typert· deepseek-harness
- DeepSeek Harness 官方文档 - API Gateway· deepseek-harness