deepseek-harness-sdk-go

DeepSeek Harness Go SDK

English | 中文

用于驱动 DeepSeek Harness 的 Go SDK。SDK 把 Harness 运行时作为子进程启动， 通过 stdio 上按行分帧的 JSON-RPC 2.0 协议通信。它是该协议的 clean-room Go 实现，分层结构和活动区间语义与 上游 Python SDK 保持对等。

环境要求

• Go 1.26 或更高版本。
• 使用内置运行时下载器时，平台为 macOS arm64/x64、Linux amd64/arm64 或 Windows amd64。
• 显式配置 DSHHome，或提供非空的 DSH_HOME 环境变量。
• DEEPSEEK_API_KEY 环境变量；如果所选 profile 使用其他凭据方式或本地模型代理，则不需要。

安装

go get github.com/theoneLee/deepseek-harness-sdk-go

SDK 目标是 DeepSeek Harness 项目发布的单文件运行时。如果没有显式指定可执行程序， 第一次 Start 或 Run 会从 PyPI 风格索引解析对应平台的 wheel，校验 SHA-256， 解压到缓存，并在后续启动中复用。 当前默认目标是运行时 0.1.5-alpha.1，对应上游 dsh-v0.1.5-alpha.1 tag。 自动启动依赖对应版本的 runtime wheel 已发布到索引；在官方 wheel 尚未公开时， 请使用 DSHBin，或通过 RuntimeIndexURL 指向包含该版本 wheel 的内部索引。

快速开始

package main

import (
	"fmt"

	deepseekharness "github.com/theoneLee/deepseek-harness-sdk-go"
)

func main() {
	harness := deepseekharness.NewDeepSeekHarness(deepseekharness.DeepSeekHarnessConfig{
		DSHHome: "/absolute/path/to/dsh-home",
	})
	defer harness.Close()

	result, err := harness.Run("Say hi.")
	if err != nil {
		panic(err)
	}
	fmt.Println(result.FinalResponse)
}

DeepSeekHarness 会惰性启动运行时，并在多次运行之间保留子进程。不再使用时请调用 Close，以便及时回收运行时。

配置

harness := deepseekharness.NewDeepSeekHarness(deepseekharness.DeepSeekHarnessConfig{
	Provider:    "deepseek-official",
	Model:       "deepseek-v4-flash",
	ReasoningEffort: "max",
	MaxTokens:   49_152,
	DSHHome:     "/absolute/path/to/dsh-home",
	Profile:     "sdk",
	Patches:     []string{"/absolute/path/to/patch.yml"},
})
defer harness.Close()

运行时默认继承父进程环境。Env 会为子进程覆盖环境变量；BaseURL 与 APIKey 是 DEEPSEEK_BASE_URL 和 DEEPSEEK_API_KEY 的便捷字段。CWD 用于 initialize 载荷； RuntimeCWD 控制子进程工作目录。DSHHome 会覆盖子进程的 DSH_HOME；未配置时， 子进程必须继承非空的 DSH_HOME。Profile 默认为 sdk，每个 Patches 条目会转成 绝对路径的 --patch 参数。ReasoningEffort 会写入 initialize 的 reasoningEffort， MaxTokens == 0 时不会发送 maxTokens。

initialize 握手使用独立的 30 秒默认超时，可通过 InitializeTimeoutSeconds 调整； RequestTimeoutSeconds 控制普通请求。

启动通道按以下顺序选择，越靠前越明确：

1. LaunchArgsOverride。
2. Command 与 Args。
3. DSHBin。
4. RuntimeBin 或 BridgeBin（旧版兼容别名）。
5. DSH_RUNTIME_BIN（旧版兼容覆盖项）。
6. 内置运行时下载器。

DSHBin 和内置下载器会追加 --profile <Profile> 以及有序的 --patch <绝对路径> 参数，并要求显式 Harness home。新 runtime 不再下载默认 cordis.yml，运行时配置由 profile 管理。LaunchArgsOverride 保留给 fake runtime 等测试适配，并绕过 home 校验。

会话与结果

session, err := harness.StartSession("session-reuse")
if err != nil {
	panic(err)
}

result, err := session.Run(
	deepseekharness.BlocksInput([]deepseekharness.JSONObject{
		{"type": "text", "text": "Inspect this task."},
	}),
	func(notification deepseekharness.Notification) {
		if notification.Method == "session.event" {
			// 按需渲染或持久化事件。
		}
	},
)

Run 会等待提示词持久写入 agent/inbox/spliced 的回执，然后收集通知，直到根会话 下一次进入 idle。通过 subagent.started 发现的后代会话通知也会被包含在内。 RunResult.Events 只包含根会话事件。FinalResponse 是该活动区间内最后提交的根会话 助手文本；FinishReason 是该区间最后一个 turn/end 的 reason kind（如果存在）。 这些字段描述的是 Run 所拥有的活动区间，不代表某项输出只在因果上归属于刚提交的提示词。

回调会在 inbox receipt 之后对每一条收集到的通知调用。没有轮次结束时，FinishReason 为 nil。

低层客户端

高级集成可以直接使用 HarnessClient 的协议接口：

client := deepseekharness.NewHarnessClient(deepseekharness.HarnessClientOptions{
	DSHBin:  "/path/to/dsh",
	DSHHome: "/absolute/path/to/dsh-home",
	Profile: "sdk",
})
defer client.Close()

if err := client.Start(); err != nil {
	panic(err)
}
_, err := client.Initialize(deepseekharness.InitializeParams{
	CWD: "./workspace", Provider: "deepseek-official", Model: "deepseek-v4-flash",
	ReasoningEffort: "max",
})

客户端支持 Request、Notify、SessionPrompt、Subscribe、 SubscribeSessionTree、NextNotification、NextRequest、Respond 与 RespondError。server-to-client 请求会排队等待调用方应答；没有任何订阅匹配的通知 可通过 NextNotification 获取。

错误

错误是可用于 errors.As 的具体类型：JsonRpcError、RequestTimeoutError、 ProtocolError、TransportClosedError、RuntimeResolveError 与 IOError。 TransportClosedError 会在可用时携带进程退出码，以及 stderr 最后 400 行。

开发

gofmt -w *.go
go vet ./...
go test -race ./...

GitHub Actions 会在 Linux 和 macOS 上执行格式检查、vet、race 测试和普通测试。发布从 匹配的 v* tag 创建；计划中的对等工作见 ROADMAP.md。 后续跟进官方 tag 时，请按 tag 更新 runbook 执行。

代码贡献指南

完整的分支、提交和 Pull Request 流程见 CONTRIBUTING.md。

与 DeepSeek Harness 的关系

本仓库负责 Go SDK。运行时由 DeepSeek Harness 项目 以 deepseek-harness-runtime-bin 发布。SDK 遵循文档化的 stdio JSON-RPC 协议， 并随着 Python SDK 的演进同步其公共行为。