DeepSeek Harness API/Typert/SDK/ACP：跨进程调用和自动化协议

模块定位

Agent runtime 不只给 Web UI 用。DeepSeek Harness 还需要支持浏览器远程调用、SDK 客户端、ACP 自动化 server、hook bridges。相关模块包括：

packages/api/*
packages/typert/*
packages/sdk/*
packages/acp/*
packages/hooks/*
docs/api-gateway.md

API Gateway

packages/api/gateway 组合 host-side BFF 和 Typert RPC gateway。它让 Host service 可以以受控方式暴露给 Client 或外部调用方。

核心问题是：浏览器和外部进程不能直接持有 Cordis Context 或 live service object，所以需要一个 wire contract。

Typert

Typert 是类型图生成、artifact 加载和 runtime registry。它负责把 Host 上声明的 Remote 方法转成 Client 可用的类型和运行时贡献。

flowchart LR
  A["Host service @Remote"] --> B["Typert generator"]
  B --> C["Host reflection artifacts"]
  B --> D["Client remote declarations"]
  D --> E["ctx.remote / agentCtx.remote"]

这个机制让 Client 侧能拿到类型安全的 remote 方法，而不是手写字符串 API。

SDK

packages/sdk 是 out-of-process runtime SDK：

protocol：JSON-RPC 协议。
client：TypeScript client。
server：server plugin。

它服务于外部程序控制 Harness runtime，比如创建 session、发送消息、读取状态等。

ACP

packages/acp/acp 实现 automation-only Agent Client Protocol server。它适合外部自动化系统接入，而不是 Web GUI 人工操作。

ACP demo 在 packages/examples/acp-demo 和 examples/ 下。

Hooks

packages/hooks 提供 Claude Code / Codex hook bridges 和共享 wire protocol library。它们把其他 agent surface 的事件或控制流接入 Harness。

为什么需要这么多层

因为它们服务不同边界：

边界	方案
浏览器 ↔ Host	API gateway + Typert remotes
外部 TS 程序 ↔ Harness	SDK JSON-RPC
自动化 client ↔ Agent	ACP
其他产品 hook ↔ Harness	hooks bridge

把它们混成一个 HTTP API 会让类型、权限、生命周期和 session ownership 变得混乱。

常见坑

第一，Host/Client TypeScript aggregate 是分开的。不要把两边的 Cordis Context merge 放进同一个 TS program。

第二，生成的 remote contracts 是构建产物。改 Remote 类型后要跑相关生成/校验。

第三，ACP 是 automation-only，不等同于 Web UI 协议。

第四，SDK 是进程外边界，必须考虑 wire validation 和 durable identity。

继续读源码

docs/api-gateway.md
packages/api/README.md
packages/typert/README.md
packages/sdk/README.md
packages/acp/README.md