DeepSeek Harness 源码解析 · 第 35 讲
DeepSeek Harness 源码解析系列 第 35 讲：SDK（TypeScript + Python） 基于 DeepSeek Harness 源码 · 2026-09-18 💡 本讲一句话： SDK 不是"远程 API 客户端"，而是"进程管理器 + 协议翻译器"——它 spawn 一个完整的 harness runtime 子进程，用一行一帧的 JSON-RPC 把 prompt 塞进去、把事件流接出来；读完你能看懂 initialize/session/prompt/shutdown 四个方法背后的全部状态机，以及 TS 与 Python 两个孪生实现各自踩过的坑。 一、一根 stdio 管道：SDK 如何驱动一个完整 runtime 前几讲我们一直在 harness 的"里面"看世界：agent loop、工具执行、会话持久化。但真实世界里，很多调用方根本不想装 Node、不想理解 cordis.yml——他们只想 harness.run("帮我修这个 bug") 。SDK 就是为这种调用方准备的：它把整个 runtime（LLM、工具、沙箱、持久化）装进一个子进程，自己只留三件事—— 管进程、说协议、收事件 。 源码上这是 packages/sdk/ 下的三个 npm 包加一个 Python 孪生实现，分工非常干净： 包 角色 关键文件 @deepseek-ai/dsh-sdk-protocol 线协议：wire 类型 + 行分隔 JSON-RPC 传输层（两端共享） protocol/src/types.ts、transport.ts @deepseek-ai/dsh-sdk-jsonrpc-server runtime 侧：cordis 插件，把 ctx 事件翻译成通知、把请求派发给 agent server/src/server.ts、index.ts @deepseek-ai/dsh-sdk-client TS 客户端：spawn/拆除子进程 + DeepSeekHarness.run() 高层 API client/src/client.ts、api.ts、dispose.ts deepseek-harness（Python） Python 孪生 SDK + bundled runtime 解析器（exe/node 双载体） python/sdk/src/deepseek_harness/api.py、client.py 注意一个刻意的设计：客户端（TS/Python） 运行在任何 harness context 之外 ，所以它不能走 dsh-subprocess 服务去 spawn——client.ts 的模块注释（第 8-10 行）明确写着这是"seam's documented exception for SDK-managed transports"。SDK 自己直接 spawn() ，自己实现拆除阶梯。这个例外是文档化的，不是偷懒。 二、线协议：只有 3 个请求、4 种通知 整个 SDK 的"表面积"小得惊人。protocol/src/types.ts 第 92-105 行把全部方法定义在两张映射表里： 📄 packages/sdk/protocol/src/types.ts (第 92-105 行) /** Server-to-client notifications by JSON-RPC method name. */ // 注释：服务端→客户端的 4 种通知，按方法名索引载荷类型 export interface HarnessSdkNotificationMap { // 通知映射表：方法名 → 载荷接口 'session.event': SessionEventNotification // 会话日志事件流：每记录一条事件就推一次 'session.status': SessionStatusNotification // agent 整体状态迁移（idle/running） 'subagent.started': SubagentStartedNotification // 子代理会话创建，带父子 id 'subagent.finished': SubagentFinishedNot…