宿主层与 SDK API

2026-08-14

2026-09-07

文章摘要

|

入门08：宿主层与 SDK API

宿主层就是"AI 和外部世界之间的桥梁"。你可以把它想象成前端的 BFF（Backend For Frontend）层——对外提供 HTTP 接口，对内调度 Agent 干活。

1. 宿主层架构

2. WebServer — HTTP 服务器

相当于 Express 或 Koa 的 router——注册路由、处理请求、支持 WebSocket。

代码位置：packages/host/webserver/src/index.ts

class WebServer extends Service {
  // 精确匹配路由（就像 router.get('/api/health', handler)）
  exact(method: string, path: string, handler: Handler): void

  // 前缀匹配路由（就像 router.use('/api', handler)）
  prefix(method: string, path: string, handler: Handler): void

  // WebSocket 路由
  ws(path: string, handler: WsHandler): void

  // 修改 HTML 页面（用于注入脚本等）
  transformIndex(transform: (html: string) => string): void
}

实际用法：

// 注册一个健康检查接口
ctx.webServer.exact('GET', '/api/health', async (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' })
  res.end(JSON.stringify({ status: 'ok' }))
})

// 注册 WebSocket，用于实时推送
ctx.webServer.ws('/api/events', (ws, req) => {
  ws.on('message', (data) => {
    console.log('收到 WebSocket 消息:', data)
  })
})

3. ApiProxy — API 网关

相当于前端的 API 网关层——统一封装了 Agent 创建、消息发送、会话管理等操作，外部不用关心内部细节。

代码位置：packages/host/apiproxy/src/index.ts

class ApiProxyService extends Service {
  // 依赖一大堆核心服务
  static inject = [
    'agents', 'sessions', 'llm', 'tools',
    'subagents', 'sessionQuery', ...
  ]

  // 创建 Agent
  async createAgent(options: CreateAgentOptions): Promise<AgentHandle>

  // 恢复 Agent（重启后继续聊天）
  async resumeAgent(options: ResumeAgentOptions): Promise<AgentHandle>

  // 发送消息
  async sendMessage(agentId: string, message: string): Promise<MessageResult>

  // 列出会话
  listSessions(): Promise<SessionInfo[]>
}

完整调用流程

4. JSON-RPC SDK

除了 HTTP API，Harness 还提供了基于 JSON-RPC 的 SDK，通过 stdin/stdout 通信。就像 Node.js 的 child_process 通过管道通信一样。

协议层

代码位置：packages/sdk/protocol/src/index.ts

// JSON-RPC 请求格式
interface JsonRpcRequest {
  jsonrpc: '2.0'
  id: string
  method: string      // 方法名
  params: unknown[]   // 参数
}

TypeScript 客户端

就像封装好的 axios 实例——开箱即用。

代码位置：packages/sdk/client/src/index.ts

class DeepSeekHarness {
  constructor(options?: ClientOptions)

  // 创建新会话
  async createSession(): Promise<Session>

  // 发送消息
  async sendMessage(sessionId: string, message: string): Promise<Result>

  // 监听事件（像 socket.on('message', handler)）
  on(event: string, handler: (data: any) => void): void

  async close(): Promise<void>
}

// 使用示例
const harness = new DeepSeekHarness()
await harness.createSession()

harness.on('message', (msg) => {
  console.log('收到回复:', msg)
})

await harness.sendMessage('你好！')

Python SDK

from deepseek_harness import DeepSeekHarness

# 就像用 requests 库一样简单
with DeepSeekHarness() as harness:
    session = harness.create_session()
    result = session.send("帮我列出当前目录文件")
    print(result)

5. ACP 协议（Agent Client Protocol）

标准化 Agent 通信协议，让第三方工具也能接入。就像 WebSocket 有标准协议一样，ACP 定义了 Agent 之间怎么通信。

代码位置：packages/acp/acp/src/index.ts

支持的请求：

方法	干啥的
`initialize`	握手，交换能力信息
`newSession`	创建新会话
`prompt`	发送提示词
`cancel`	取消当前操作
`shutdown`	关闭服务器

6. 子 Agent 系统

就像开子线程——主 Agent 太忙了，可以创建子 Agent 去干具体的活，干完回来汇报。

代码位置：packages/subagent/subagent/src/index.ts

class SubagentService extends Service {
  // 启动子 Agent
  async start(provider: string, options: SubagentOptions): Promise<SubagentRun>

  // 启动可延续的子 Agent（可以继续对话）
  async startContinuable(provider: string, options: SubagentOptions): Promise<SubagentRun>

  // 继续对话
  async followup(runId: string, message: string): Promise<SubagentResult>
}

三种子 Agent 创建方式：

方式	说明	像什么
`spawn-in-process`	在当前进程创建	开个新线程
`fork`	分叉进程	开个新进程
`acp`	通过 ACP 连接外部	调另一个服务

7. MCP 客户端桥接

连接外部 MCP（Model Context Protocol）服务器，扩展工具能力。就像用 npm 安装一个包，就多了一个 API 可用。

代码位置：packages/mcp/mcp-client/src/index.ts

class McpClient extends Service {
  // 连接 MCP 服务器
  async connect(transport: 'stdio' | 'sse', options: ConnectionOptions): Promise<void>

  // 连接后，工具自动注册到 ctx.tools
  // 命名格式: mcp__<服务器名>__<工具名>
}