独立(仓外)插件的前后端通信:Typert Remote 之外的正确做法是什么?

[zhang-guo-wen]

背景
我在为 DeepSeek Harness 写一个独立插件(不在 deepseek-harness monorepo 内,是自建仓库 + 自建 npm 包名),它同时有:

• host 侧:需要写组合文件——给某个 agent(或全局)增/改/禁用一行 mcp-client(即作者化 MCP 配置);
• client 侧:一个设置页(浏览器),负责 MCP 的增/改/开关 UI,以及一个只读列表(读 ctx.remote.pluginInventory)。
  我遇到的困惑
  client 要让 host 做"写文件"这件事,似乎两条路,但各有一个我不确定的地方:
  A) 系统推荐的 Typert Remote — host 提供 @Remote('addMcp') 的服务,client 用 ctx.remote.<命名空间>.addMcp(...) 调用。但从 packages/api/remotes/client 看,ctx.remote 是构建期 codegen 出来的一份静态列表(agentPresets/commands/settings/pluginInventory/llm/...)。独立插件不在 Harness 构建里,不会出现在这份列表,所以 ctx.remote.claudeCompatMcp 是 undefined → 客户端调不到。
  B) 用 ctx.webServer 注册普通 HTTP 路由 — host 用 ctx.webServer.register({kind:'exact', path, handler}),client 直接 fetch('/api/...')(webhook-github 就是这么做)。这条路不需要 codegen,独立包可用。
  想问的问题

1. 对仓外/独立插件,官方推荐的前后端通信方式是什么?Typert Remote 是否有支持仓外插件的运行时注册/发现路径(比如 ClientRemote.$mount + ctx.typert registry),还是只能构建期 codegen?
2. 用 ctx.webServer + fetch 做 client→host 的写操作,是合理/推荐的做法吗?有没有需要注意的约束(路由冲突、鉴权/同源、host 绑定、响应格式)?
3. 有没有"运行时动态暴露一个 Remote"的官方 API,让独立插件也能被 ctx.remote 调用?还是说设计上就只支持一等包?
   现状(供参考)
   我目前用 B(ctx.webServer.register + fetch)做通了 MCP 的增/改/禁用,显示复用 pluginInventory。想确认这是不是符合 Harness 预期的做法,还是应该走 Typert Remote 的某种运行时路径。

[PerryLink]

结论先说：Typert Remote 不是"只能构建期 codegen"。packages/api/remotes/src/client/index.ts 里那份 namespace 数组是一等包的装配清单（把 14 个官方 namespace 挂到 ctx.remote），不是"只有它们才能被调用"的白名单。仓外插件走同一套 Typert 通道完全可行，只是产物要自己生成、exports 要自己声明。

一、证据（0.1.5-alpha.1 线源码）

1. contribution 是纯数据：TypertContribution = { package, face, schemas, model, invocations }（packages/typert/registry/src/types.ts），不依赖任何构建期全局状态。
2. 宿主侧运行时注册是公开 API：ctx.typert.register(contribution): TypertDisposer（packages/typert/registry/src/index.ts）。
3. 自动注册覆盖仓外包：packages/typert/loader/src/index.ts 的 typert-loader 跟随 Loader entry 挂载，解析该 entry 的 package.json；只要它导出 ./typert，就 import 其 host 产物并 ctx.typert.register(manifest)，entry 卸载时撤销。解析锚点是 ctx.baseUrl（cordis.yml 所在目录），所以通过 profile 安装的第三方包一样会被扫到；只有"嵌套在别的 entry 后面"的包才需要在 Config.packages 里显式点名。该文件头注释还明确写了：手写 wire schema 的 contribution 可以直接 ctx.typert.register()。
4. 客户端是运行时挂载：await ctx.remote.$mount(contribution)（packages/api/remotes/src/client/index.ts）。你的 client 插件在自己的 apply 里调用即可，不需要进 monorepo。
5. 生成器本来就支持仓外：packages/typert/generator 内有 .typert-unscoped-external-* fixture 和 tsdown-plugin.ts——官方已经在为"不在 monorepo 里的包"生成产物。
6. 包侧只需两个 exports（照抄 packages/host/plugin-inventory/package.json）：

"exports": {
  "./typert": { "types": "./lib/typert.host.d.ts", "default": "./lib/typert.host.js" },
  "./remote": { "types": "./lib/typert.remote-client.d.ts", "default": "./lib/typert.remote-client.js" }
}

生成产物导出的 TYPERT（host 面）/ TYPERT_REMOTE（client 面）就是 contribution 本身。

二、推荐做法

首选 Typert，三步：

1. devDependency 加 @deepseek-ai/dsh-typert-generator，在 tsdown 配置里挂它的插件，@Remote('addMcp') 按一等包同样的写法标注；
2. package.json 补上 ./typert、./remote 两个 exports，并把产物加进 files；
3. host 半不用写代码（typert-loader 自动注册）；client 半在 apply 里 ctx.remote.$mount(TYPERT_REMOTE)。

不想引生成器也可以：手写 TypertContribution 字面量 + ctx.typert.register()，loader 文档明确支持这个场景，代价是 schema/model/invocations 全手写、没有类型生成。

三、B 方案（ctx.webServer + fetch）能不能用？

能用，官方自己也这么用（webhook-github、open-in-app、client-hmr），但它的定位是 HTTP 端点，不是业务 RPC：

• 路由唯一性要自己保证：同一 exact path 重复 register 会抛错（packages/host/webserver/tests/webserver.spec.ts 有断言），所以插件间路由冲突要自己规避。
• 鉴权不会自动给你：connection 的浏览器认证只包在它自己注册的 /api prefix 路由里（packages/client/connection/src/index.ts 中 route = { kind: 'prefix', path: API_PATH, handler } 内做 requestRejection）。你自己 register 的 exact 路由不经过那道检查，"设置页只能被已认证浏览器调用"这件事需要你自己实现（校验 Host/Origin，或把写操作放到受保护的通道上）。
• 没有 Typert 的契约层：没有 strict zod 校验、没有统一的 RemoteError 语义、没有 method signature 检查，参数与结果的编解码全部自理。

所以：webhook / 静态资源 / 流式下载用 webServer；设置页读写这类业务调用优先 Typert。你现在 B 能跑通，但长期维护（类型、校验、错误语义、鉴权）迁到 Typert 更划算。

pluginInventory 只读复用没问题——它是已挂载的 pluginInventory/list namespace，客户端直接读即可，不需要额外注册。

如果这个说明解决了你的疑问，可以把它标记为答案，方便后来遇到同样问题的插件作者检索到。

[zhang-guo-wen]

感谢这篇分析 —— 核心结论我认同,而且我按 0.1.5-alpha.1 源码核对了:TypertContribution 是纯数据、ctx.typert.register() 是公开 API、typert-loader 会跟随 loader entry 自动 import ./typert 并注册(锚点 ctx.baseUrl,profile 装的第三方包也能扫到)、client 端 $mount(contribution) 是运行时挂载、生成器也确实有仓外 fixture。所以"仓外插件能走 Typert、不用进 monorepo"这个判定是对的。我也同意:设置页这类业务读写,用 Typert 比 ctx.webServer + fetch 更划算(后者不自动带鉴权、没有统一 RemoteError 契约)。
我们在自己的合并插件里也是按这条路落地的,hoster 端 extends TypertRemoteService + @Remote('addMcp'/'editMcp'/'disableMcp'),client 端 await ctx.remote.$mount(TYPERT_REMOTE) 后 ctx.get('remote.') 调用,确实通了。
但有两点实测补充,可能对后来人有价值:

1. Node 不解析装饰器。仓外包如果 host 侧用 @Remote 且用 tsdown 构建,默认不会降级装饰器,产物里是裸 @Remote,Node 直接 SyntaxError。harness 自身构建会降级(生成器的 tsdown 插件顺手做了这件事),但仓外包没这层。我们补了一个 ts.transpileModule 的 transform 只处理含装饰器的文件。分析里"挂生成器插件"顺带解决了这个,但如果你用"手写 contribution、不挂生成器"这条路线,这一步得自己补。
2. 生成器对"合并包"不友好。分析说挂生成器插件是"三步",这对host 只管 host 的干净包(如参考的 dsh-mcp-mgr)成立。但我们的是一个包同时含 host(src/index.ts)+ client(src/client/),tsconfig.json 是 client 面(jsx/DOM),外加十来个 @deepseek-ai/* 依赖没装 —— 我把生成器插件挂上后,WorkspaceTypertGenerator 直接崩了(Cannot read properties of undefined (reading 'kind'))。要跑通得再配一个独立的 host tsconfig + 给依赖补 stub/path 映射,而且生成的 typert.host.js/remote-client.js 会跟 harness 的 Typert 版本强绑定,以后升级要重新对齐。
   所以我们的取舍:采用分析里"不想引生成器也可以"那条 —— 不跑生成器,但在 host 侧手写 TypertContribution 并 ctx.typert.register(),复用同一份 InvocationDescriptor[](client $mount 用的就是它)。这样:

• 走的是同一条"正统"Typert 通道,host registry 真正知道这个 namespace(治好了我们之前 disableMcp → HTTP 404 的问题);
• 不背生成器的类型分析脆弱性和版本耦合,编译/维护都更可控;
• 代价只是"@Remote 加方法时同步补一条 descriptor",局部、可读。
  一句话:机制层面你的分析完全成立,我们踩的坑是仓外合并包 + 装饰器 + 生成器这三件事叠加,所以选了更轻的"手写 contribution + ctx.typert.register()"作为落地方式,而不是挂生成器。

[zhang-guo-wen]

我看这个是不是也是在讨论这个问题
#5618
#5695
还有另外一个仓库 https://github.com/yangfch3/dsh-mcp-mgr 的一个实现，我让AI分析了一下
它们在说什么
#5618 和 #5695 都在讲同一个根因:Typert 生成器 WorkspaceTypertGenerator.isTypeMetaSymbol() 现在只认两种情况的 @Remote / TypertRemoteService 元数据:

1. 该声明属于已注册的 DSH 工作区包且包名恰好是 @deepseek-ai/dsh-typert-protocol;
2. 声明写在 declare module '@deepseek-ai/dsh-typert-protocol'(ambient)里。
   而一个独立发布的外部插件,是从 node_modules 里 import 官方 @deepseek-ai/dsh-typert-protocol 的——这两种都不满足。于是生成时发生:publishes Remote artifacts but has no Remote methods,直接拒绝生成,@Remote 方法全部不被发现。
   这正是我之前说"独立包拿不到 Typert"的那层原因,它不是瞎猜,是真实存在的生成器限制,而且目前没被合并(两个 Discussion 都还是 0 回复的提案)。
   关键:dsh-mcp-mgr 是怎么做到的?
   它没有改 harness 源码,而是用了另一个绕法 —— 把 @deepseek-ai/dsh-typert-protocol 整包 vendor 进自己的 workspace:
   packages/vendor-typert-protocol/package.json
   { "name": "@deepseek-ai/dsh-typert-protocol", ... } ← 包名照抄,让生成器认为是"已注册工作区包"
   然后 tsconfig.host.json 用 paths + references 把 @deepseek-ai/dsh-typert-protocol 映射到这份 vendored 源码:
   "paths": {
   "@deepseek-ai/dsh-typert-protocol": ["./packages/vendor-typert-protocol/src/index.ts"]
   }
   这样生成器分析时看到的是工作区内的协议源码(registrationForFile 命中 @deepseek-ai/dsh-typert-protocol),@Remote 就被认出来了。而运行时插件仍靠 peerDependencies 用真正的 npm 协议包。结果:harness 一行不动,独立包也能走 Typert Remote。
   对我们要做的事意味着什么
   我们"把 MCP 通信改回 Typert Remote"只有两条路:

• A. 照抄 dsh-mcp-mgr 的 vendor 绕法(推荐):在 dsh-claude-compat 里加一个 packages/vendor-typert-protocol,配 tsconfig paths + gen.mjs,host 继承 TypertRemoteService、client 用 $mount。不碰你本机 harness,符合你"官方底座永远干净"的约束。
• B. 改 harness 生成器加"外部包身份等于 @deepseek-ai/dsh-typert-protocol"的精确判断(Proposal: recognize the published Typert protocol in external plugins #5618/Proposal: recognize official Typert protocol metadata in third-party plugin packages #5695 的提议)。受益所有外部插件,但要改 harness 源码,且上游未接受。

[argszero]

@zhang-guo-wen 你这个问题问得非常好——它正好问到了 DSH 双层能力模型（构建期 codegen 的 Remote vs 运行时可用的 webServer）的边界。我按你 Q1/Q2/Q3 逐一给源级结论（当前基线 0.1.5-alpha.1）：

Q1/Q3：Typert Remote 对仓外/独立插件是「构建期 codegen 专用」，没有运行时动态暴露

你判断 ctx.remote 是构建期 codegen 出来的静态列表——对。要确认的是「存不存在运行时注册路径」，答案是没有给仓外插件用的。

• ctx.remote 的类型是 packages/api/gateway/src/client/index.ts:102 的 ClientRemote extends TypertClientRemote，它由 packages/typert/generator 从 host 包的 @Remote('addMcp') 注解生成 /remote 工件。remotes/client/index.ts:156 的 ctx.remote.$mount(contribution) 挂载的是 TypertRemoteContribution（packages/typert/protocol/src/types.ts:299）：

  export interface TypertRemoteContribution {
    readonly package: string
    readonly descriptors: readonly InvocationDescriptor[]   // ← 构建期生成
  }

• 关键点：descriptors 必须作为生成工件存在。仓外插件不在 Harness 构建里，所以它 host 侧的 @Remote 注解永远不会被 codegen，也就没有 descriptors 可 mount → ctx.remote.<你的命名空间> 在类型和运行时都是 undefined。
• 我看过 TypertRemoteRegistry（types.ts:307/442）：它的 register(contribution) 确实是运行时注册，但接的也是 TypertRemoteContribution，即仍然要求你手动提供生成好的 descriptors。registry 本身不会凭空给一个运行时新脚本造 descriptors。所以「运行时动态暴露一个新 Remote 命名空间给 ctx.remote」在目前设计上不存在——它就是为一等包/构建期产物服务的。

一句话：Remote 路线要 codegen，仓外插件进不了构建期 → 走不通。

Q2：ctx.webServer + fetch 是正确的、推荐的做法，webhook-github 就是官方先例

你走 Option B 是对的方向。ctx.webServer 是 Cordis 运行时服务，不是构建期 codegen——所以仓外插件和树内包一样能用。证据：packages/webhook/webhook-github/src/index.ts:14 就是 export const inject = ['webServer', 'webhookRuntime', 'credentials']，然后 ctx.webServer.register({kind:'exact', path, handler})。这是官方树内包用 webServer 注册 HTTP 路由并暴露给 client 的先例，独立包完全可复用。

几个你问的注意点：

1. 路由冲突：注册前先检查/或选一个不会跟 api/* 已有前缀撞的路径。DSH 网关挂 /api，建议你用自己的命名空间前缀（如 /mcp-config/）。
2. 鉴权/同源：webServer.register 暴露的是走同一 origin；client 端 fetch 是同源的，天然带同 cookie。如果这个写操作要改 agent 的配置文件（MCP 那类敏感面），DHS 已有 credentials/permission 体系，建议在 handler 里走同样的授权校验（webhook-github 用 WebhookHttpError(401,'invalid webhook signature') 的模式，说明 handler 里可以自定义鉴权与错误码）。不要把「可写配置」的端点对未授权 client 全放开。
3. 响应格式：返回 JSON（respond(response, code, ...)），且注意必须是 lossless JSON（webhook-github handler 就有 WebhookHttpError(400, '... must be a lossless JSON')）——DSH 全栈对「什么能过 wire」的 lossless-JSON 约束是一致的，读写都按这个来。

一句话总结

对「仓外独立插件 + host 写配置 + client 读 pluginInventory」这种组合：不要试图走 Typert Remote（那是构建期 codegen、仓外进不去），走 ctx.webServer.register + 同源 fetch（webhook-github 是现成官方先例，$inject 里带上 webServer 即可）。你的方案 B 是符合 Harness 预期的，且 pluginInventory 复用也没问题。

如果你愿意，我可以把这套「仓外插件前后端通信」的判别（build-time codegen vs runtime webServer）补进插件作者的参考里——目前这块契约在文档里确实分散（api/remotes/README.md 讲 Remote、webhook/ 讲 webServer，但没串成「什么场景走哪条」）。你回复里提一句要不要，我按需整理。