DeepSeek Harness TypeScript SDK

English | 中文

DeepSeek Harness（dsh，DeepSeek 开源的 AI agent harness）的 TypeScript / Node.js SDK：以子进程方式驱动运行时，通过 stdio 上的换行分隔 JSON-RPC 运行 agent turn。这是一个独立实现，参考了上游仓库的 packages/sdk/{protocol,client}，并对齐官方 Python SDK（python/sdk）的 API 设计。

运行时会继承 DEEPSEEK_BASE_URL、DEEPSEEK_API_KEY 等标准 DeepSeek Harness 环境变量，因此既可以直连真实模型端点，也可以把这些变量指向本地代理。

安装

npm install @openma/deepseek-harness-sdk

快速开始

import { DeepSeekHarness } from '@openma/deepseek-harness-sdk'

await using harness = new DeepSeekHarness()
const result = await harness.run('Say hi.')
console.log(result.finalResponse)

DeepSeekHarness 惰性启动运行时子进程并在多次调用间复用。像上面那样使用 await using，或在结束时显式调用 close()，确保子进程始终被回收。

特性

• 高层 turns API —— DeepSeekHarness.run() 发送 prompt，返回最终 assistant 响应、结束原因和整段活动区间的事件/通知流
• 低层协议客户端 —— HarnessClient 提供原始 JSON-RPC 请求、通知订阅和 session 树过滤
• 忠实还原官方协议 —— 独立镜像上游 wire 类型与 run 语义，与官方 Python SDK（PyPI 的 deepseek-harness-sdk）API 对齐
• 健壮的进程所有权 —— 惰性启动、协议 shutdown、stdin-EOF → SIGTERM → SIGKILL 收尾阶梯，附退出码 + stderr 尾部诊断
• Subagent 感知 —— 通过 subagent.started 谱系发现后代会话并随根会话一起流式输出，根事件保持权威
• 零运行时依赖 —— Node.js ≥ 20、ESM、全程严格 TypeScript 类型

运行时选择

SDK 会启动一个服务于 SDK 协议的 DeepSeek Harness 运行时进程（其插件组合中必须包含 @deepseek-ai/dsh-sdk-jsonrpc-server）。启动方式按以下顺序解析：

1. launchArgsOverride —— 完整 argv，原样使用。
2. runtimeBin —— 单个运行时可执行文件（例如打包好的 dsh-jsonrpc-agent-pkg-<platform>-<arch>）。
3. 环境变量 DSH_RUNTIME_BIN。
4. 已安装的 @deepseek-ai/dsh-sdk-jsonrpc-demo npm 包，以 node <bin.js> 方式启动。若该包附带默认组合（runtime/cordis.yml），且你没有设置任何非空配置，则其路径会通过 DSH_CORDIS_CONFIG 注入，实现零配置运行。

运行时本身始终要求显式的 Cordis 组合，没有配置会直接报错退出。因此使用路径 1–3（以及无内置默认配置的路径 4）时，请通过 cordis 选项或 DSH_CORDIS_CONFIG 传入配置。上游 jsonrpc-agent 示例 提供了完整的独立组合。

import { DeepSeekHarness } from '@openma/deepseek-harness-sdk'

await using harness = new DeepSeekHarness({
  provider: 'deepseek-official',
  model: 'deepseek-v4-flash',
  maxTokens: 49_152,
  cwd: '/absolute/path/to/workspace',
  sessionRoot: '/absolute/path/to/sessions',
  cordis: 'examples/jsonrpc-agent/cordis.yml',
  runtimeBin: '/path/to/dsh-jsonrpc-agent',
})
const result = await harness.run('Make the requested code change.', { sessionId: 'example-001' })
console.log(result.finalResponse, result.finishReason)

provider 选择所选 Cordis 组合注册的 provider 路由；model 是该适配器解析的模型 id。maxTokens 是可选的正整数单请求输出 token 上限，作用于根 agent 及其进程内后代；省略则由 provider 默认值控制。

选项

选项	作用
provider / model / maxTokens	initialize 握手中发送的路由（默认 deepseek-official / deepseek-v4-flash）
cwd	Agent 工作区，解析为绝对路径；作为 wire cwd 发送并注入 DSH_CWD
runtimeCwd	运行时进程自身的工作目录（默认与 cwd 相同）
sessionRoot	注入 DSH_SESSION_ROOT（JSONL 会话目录）
cordis	注入 DSH_CORDIS_CONFIG（Cordis 组合路径）
env	合并到继承的父进程环境之上的变量
baseUrl / apiKey	注入 DEEPSEEK_BASE_URL / DEEPSEEK_API_KEY
runtimeBin / launchArgsOverride	显式运行时启动（禁用默认解析与配置注入）
requestTimeoutMs	单请求超时；undefined 表示无限等待（一个 turn 可能合理地长时间运行）
shutdownTimeoutMs	close() 内协议 shutdown 交换的时限（默认 1000）
disposeEofGraceMs / disposeGraceMs	stdin-EOF → SIGTERM → SIGKILL 收尾阶梯的宽限窗口

运行语义

HarnessSession.run() 拥有一段活动区间：从该 prompt 的持久化收件回执开始，到 agent 下一次整体空闲为止，返回 RunResult { sessionId, finalResponse, finishReason, events, notifications, sessionRoot }。

• finalResponse 是区间内根会话最后一条已提交的 assistant 文本。
• finishReason 是区间内根会话最后一条 turn/end 的 kind——completed、max-tokens、error 等；没有 turn 结束时为 undefined。turn/end 缺少字符串 data.reason.kind 属于协议违规，会抛出 SdkProtocolError。
• events 只包含根会话事件，后代消息不会顶替根会话的响应。
• notifications（以及 onNotification 观察者）按 wire 顺序接收根会话及所有已发现后代的通知，包括嵌套 subagent 生命周期与会话事件。

两个结果字段描述的是这段被拥有的区间，而非因果上归属于该 prompt 的输出：steering、注入的上下文和其他排队任务都可能在空闲前贡献内容。

const session = harness.session('session-001')  // 稳定 id，跨多次 run 复用
const first = await session.run('Inspect the repository.')
const second = await session.run('Now fix the failing tests.', {
  onNotification: (notification) => console.error(notification.method),
})

低层客户端

HarnessClient 是 DeepSeekHarness 之下的低层 JSON-RPC 客户端：拥有子进程、说 wire 协议、把通知扇出到各订阅。低层 prompt() 立即返回排队消息 id；绕过 run() 的调用方需要自己承担后续活动边界。

import { HarnessClient } from '@openma/deepseek-harness-sdk'

const client = new HarnessClient({ command: '/path/to/dsh-jsonrpc-agent', env: { ...process.env, DSH_CORDIS_CONFIG: 'cordis.yml' } })
await client.initialize({ cwd: process.cwd(), provider: 'deepseek-official', model: 'deepseek-v4-flash' })
const subscription = client.subscribeSessionTree('session-a')
const messageId = await client.prompt('session-a', [{ type: 'text', text: 'Say hi.' }])
for await (const notification of subscription) {
  console.log(notification.method)
  if (notification.method === 'session.status' && notification.params.status === 'idle') break
}
await client.close()

所有错误均继承自 HarnessError：TransportClosedError（运行时消失，附退出码与 stderr 尾部）、RequestTimeoutError、SdkProtocolError（wire 形状违规）、JsonRpcResponseError（协议错误响应，保留 code/data）、RuntimeResolutionError（找不到运行时）。

Wire 协议

请求：initialize → { serverInfo }、session/prompt → { messageId }、shutdown → {}。服务端通知：session.event、session.status、subagent.started、subagent.finished。具名负载类型见 src/protocol.ts；serverInfo.name 保持 wire 稳定值 deepseek-harness-sdk-runtime。

开发

npm install
npm run typecheck
npm test        # 针对脚本化 fake runtime 运行；无需网络或模型
npm run build

许可证

MIT