多入口与 Typert：一个内核，五张面孔

先玩再讲。下面左边是入口，右边是内核。五个标签是五张面孔，选一个，点播放：看这个入口披着什么皮、发出什么样的报文，再看内核的会话日志里落下什么事件。然后换一个入口重播一遍，盯住右边那排事件，这就是本课要讲的全部。

上一批课讲过，DSH 的一切功能都是 Cordis 插件，进程启动时按一份 cordis.yml 把插件挂成一棵树。这个设计在本课收获回报：所谓「入口」，就是一份不同的 cordis.yml。仓库的 examples/ 目录下躺着现成的三份：headless、JSON-RPC、ACP，翻开对比会发现它们大同小异，DeepSeek 适配器、bash 执行器、JSONL 会话持久化、压缩、文件系统工具这些内核插件三份全有，差异集中在最上面几行：JSON-RPC 入口多挂一个 sdk-jsonrpc-server，ACP 入口多挂一个 acp-demo 协议桥和沙箱策略，headless 干脆什么服务器都不挂，进程本身就是入口。

Web 面孔的皮厚一点，但仍然是插件：host-webserver 是个纯粹的 node:http 载体，文档明说它不属于 agent loop、不了解任何 harness 概念（docs/subsystems/web-server.zh.md）；frontend-static 认领回退席位当 SPA 服务器；client-modules 用 tapIndex 往 index.html 里注入启动清单 window.__DSH_BOOT__，浏览器端照单加载各插件的前端模块。HTTP API 面孔则是一条链：api-remotes 做身份解析，api-gateway 做参数解码和方法调用，connection 独占 /api 路由的 RPC 信封，最后落回同一个 webserver（docs/api-gateway.zh.md）。

Python SDK 最能说明「皮」有多薄。pip install deepseek-harness-sdk 会连带装一个平台 wheel，里面是单文件可执行的 dsh-jsonrpc-agent；SDK 启动它当子进程，通过 DSH_CORDIS_CONFIG 注入默认组合，然后在 stdio 上说 JSON-RPC（python/sdk/README.zh.md）。所以 Python SDK 和 JSON-RPC 入口是同一张面孔的两种穿法，Python 这层只是把协议包成了 harness.run("…")。

大纲里那道边界条件题的答案就藏在配置注释里。JSON-RPC 示例的第 2 行写着 stdout 保留给 JSON-RPC，禁止加 console logger 或终端 UI；ACP 示例同样声明整棵树不挂 stdout 日志和 HMR，因为 stdout 载着 ACP 的 JSON-RPC（两份 cordis.yml 的开头注释）。道理一句话：这两种协议把 stdout 当传输线，往上面混打一行日志，对端的解析器就断线了。日志走 ctx.logger 另寻出路，这是协议入口的铁律。

翻开 examples/jsonrpc-agent/cordis.yml，第 1 行注释说明这是给捆绑运行时用的无人值守部署，第 2 行就是那条铁律的原文：stdout 保留给 JSON-RPC，不要加 console logger 或终端 UI。往下看，协议桥 sdk-jsonrpc-server 只是插件列表里普通的第一项，连它的配置都走环境变量注入。一个入口的全部家当就这么多：一份配置，顶部几行是它的脸，其余全是和别的入口共用的内核。

出处：examples/jsonrpc-agent/cordis.yml 第 1 至 7 行，核对日期 2026-08-13。

五张面孔里，Web 和 HTTP API 这两张要跨进程调用 Host 里的业务方法，这就需要一层 RPC。DSH 没用现成框架，自研了 Typert。业务开发者要做的事少到只剩一个装饰器：在服务方法上标 @Remote('create')，构建时 Typert 分析 TypeScript 类型图，生成三样东西：校验参数的 Zod schema、描述调用的 descriptor、给浏览器端用的类型声明。不需要手写路由表、参数转换、客户端 stub，改一处方法签名，重新构建后所有端的调用约定同步更新（docs/subsystems/typert.zh.md、packages/typert/generator/README.zh.md）。

为什么现成方案不行？因为要跨 wire 的东西里有 Cordis 特有的概念，通用 schema 生成器没有词汇描述它们。三个例子。第一，Host 和浏览器是两个独立的 TypeScript Program，同名的 Cordis Context 在两边的类型合并结果不一样，一份 schema 喂两边行不通。第二，业务方法的参数可能是 Agent 这样的活对象，它不能被序列化过 wire，Typert 用 lookup 机制把 agent 参数改写成 wire 字段 agentId，Gateway 收到请求后先把 id 解析回活对象再调方法。第三，客户端的 ctx.remote.goals 是随插件挂载卸载的活服务，最后一个方法撤回，整个 namespace 跟着卸载，这是 OpenAPI 那种静态描述表达不了的生命周期（Typert Gateway Agent Note 2026-08-02）。

还有一条值得记住的纪律：descriptor 是本地反射信息，不上 wire。Host 和客户端各自在构建时生成彼此对应的 descriptor，请求里只发 endpoint 和具名参数；取消信号作为带外的 carrier signal 注入，绝不混进业务参数（docs/subsystems/typert.zh.md 的调用 descriptor 一节）。生成器还很固执：遇到表达不了的类型投影直接报错，绝不把源类型展平弱化了蒙混过去。这和前两课的「拒绝解读」一脉相承，说不清楚的事宁可不做。

Goal 服务的真实代码。一个装饰器加一个薄适配，JSDoc 里那句「从 wire identity 解析出的活 Agent」就是 lookup 机制在业务侧的样子：

  /**
   * Create one Goal through the remote boundary.
   * @param agent - exact live Agent resolved from the wire identity.
   * @param request - objective and optional round cap.
   * @returns the created Goal identity.
   */
  @Remote('create')
  remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult {
    const view = this.create(agent, request)
    return { ref: { id: view.id, revision: view.revision } }
  }