DeepSeek Harness API 网关是什么？DSH plugin 的 @Remote 暴露机制

DeepSeek Harness 的 Typert API 网关负责把 Host 侧服务安全地暴露给 Client：用 @Remote 与 @RemoteScope 选择哪些方法对外开放，用 TypertLookupMap 声明 Host 对象与 wire identity 的关联（来源）。 界面上的每个操作，背后都是一次「浏览器 → Host」的调用；能调什么、调到哪个对象上，正是由这条受控通道决定的。这篇讲这套暴露机制怎么工作、插件怎么接；前端模块怎么加载见《DeepSeek Harness 前端插件怎么加载》，整棵树的分层见《DeepSeek Harness 架构是怎样的》。

为什么需要 API 网关

Host 与 Client 分处两个世界：后端跑在 Node 里，界面跑在浏览器里，两者之间既不能直接互相引用对象，也不该把所有能力无差别地摊开——API 网关就是为这条跨界调用设计的受控通道（来源）。 把问题拆开：

1. 两个世界无法直接互调：浏览器拿不到 Node 的对象引用，Node 也不能直接渲染页面；调用必须经过某种序列化与路由，这正是网关要做的事。
2. 能力不能全摊开：后端服务里难免有只该内部使用的方法，如果全部自动暴露，等于把内部结构变成了对外接口。
3. 跨进程的对象需要身份：当暴露的不只是一个方法、而是一个对象上的能力时，网关必须知道「这个请求该落到哪个实例上」，否则无法路由。
4. 协议不该由每个插件各写一遍：统一在 Typert 之上，插件只要按约定标注与实现，就能获得一致的暴露与路由行为，而不必自建通信层。

DeepSeek Harness 的 API 网关做什么

DeepSeek Harness 的 API 网关负责把 Host 侧的服务安全地暴露给 Client，让前端能调用后端的受控方法（来源）。 三个要点：

1. 受控暴露：不是所有方法都能被前端调用，可调用的范围由标注决定——默认可调用集合很窄，对外开放是显式动作。
2. 基于 Typert：网关运行在 Typert 机制之上，插件不必自建一套通信协议，也就避免了各插件之间协议不一的碎片化。
3. 服务 Web GUI 联通：它与前端模块一后一前，共同支撑界面调用后端能力；没有它，界面就只能是一张静态页面。

怎么选择暴露的方法与对象

在 DeepSeek Harness 里，@Remote 与 @RemoteScope 用来选择哪些方法对 Client 开放，TypertLookupMap 则声明 Host 对象与 wire identity 的关联（来源）。 拆开看：

1. @Remote 决定「暴露哪些方法」：被标注的方法才经由网关对外开放；未标注的部分保持内部可见性，这构成了网关的安全下限。
2. @RemoteScope 决定暴露的范围：用于圈定一组能力的适用边界——一组相关方法可以一并按某个作用域开放，而不是逐个零散授权。
3. TypertLookupMap 决定「路由回哪个实例」：它把 Host 对象与网络身份对应起来，请求据此找到正确目标；这是跨进程暴露对象时不可省略的一环。

wire identity 为什么重要

在跨进程暴露里，「对象」不能像在同一进程内那样靠引用传递，必须给它一个可被寻址的网络身份（wire identity）——TypertLookupMap 声明的正是 Host 对象与这个身份之间的对应关系（来源）。 三点理解：

1. 没有身份就无法路由：请求在网络上只带得走一个标识，网关要根据它还原出「这是哪个对象」，映射缺失就会路由失败。
2. 映射是显式登记的：身份与对象的关联不是猜出来的，而是声明在查找表里；因此它是可审查的，而不是隐式约定。
3. 它是暴露对象能力的前提：只有先建立身份，调用才能落到正确的实例上，对象级的能力暴露才有意义。

插件怎么接入网关

DSH plugin 通过 ctx.typert.lookups 等入口接入网关，并把需要暴露的服务按 TypertRemoteService 的约定实现（来源）。 两点理解：

1. 登记到查找表：ctx.typert.lookups 是插件登记自身服务的入口，登记后才能被网关解析到；这一步与在包声明里标注前端入口是两件不同的事，两半都要做才构成完整的前后端联通。
2. 按远程服务约定实现：实现 TypertRemoteService，插件能力就能以受控方法的形式供 Client 调用——约定统一，插件之间不必协商各自的通信方式。需要前后端联通的插件，可在「设置 → 插件市场」即 DSH Plugin Hub 里找现成实现参考。

网关与前端模块怎么配合

API 网关与 client 模块系统是 Web GUI 前后端联通的左右手：前者决定「界面能调用哪些后端能力、调用落到哪个对象」，后者决定「页面要加载哪些前端模块」（来源）。 用一个顺序串起来：

1. 先有前端模块：插件的界面代码经 dsh.client 声明进入 entry 图，在页面上被加载出来。
2. 再由网关接上后端：界面里的操作经 @Remote 标注的方法跨到 Host 侧，由查找表路由到正确的服务实例。
3. 两半都做才完整：只声明前端、不接网关，界面就没有数据来源；只暴露后端、不供前端模块，能力就没有入口被触发。
4. 排查时分段看：界面元素不出现，先查前端模块；界面出现但点了没反应，再查网关这一侧。

理解 API 网关的注意事项

把网关看成「Host 与 Client 之间的受控通道」，就不会和前端加载混淆。

1. 暴露要显式标注：不标注的方法不对外开放，这是网关的安全下限。
2. 对象要靠查找表路由：跨进程暴露离不开身份映射，缺了就找不到目标实例。
3. 作用域用于成组开放：@RemoteScope 圈定一组能力的适用边界，而不是零散授权。
4. 与前端模块分工：模块管加载，网关管调用，两件事都要做才联通。
5. 插件按约定实现：走 ctx.typert 与 TypertRemoteService，不自建通信协议。
6. 它是 Web GUI 联通的一环：无界面场景未必涉及；界面出问题先分段判断落在哪一侧。
7. 整棵树的坐标见《DeepSeek Harness 架构是怎样的》；前端加载见《DeepSeek Harness 前端插件怎么加载》。

来源：DeepSeek Harness 官方文档 - API 网关、官方文档 - Client 模块子系统。