DeepSeek Harness Java SDK

Java SDK for DeepSeek Harness — 一个“一切皆插件”的开源 Agent 运行时。本 SDK 将运行时作为子进程管理，并通过基于标准输入/输出（stdio）的新行分隔 JSON-RPC 2.0 协议与之通信。

• 内置 Windows x64 运行时二进制，开箱即用，无需额外安装
• 支持任意 OpenAI 兼容的第三方模型提供方（通过自动生成的 pi-ai 适配器路由）
• 会话持久化、会话延续、子代理结果收集
• 启动即 initialize 握手，失败时输出退出码与 stderr 尾部，便于诊断

环境要求

• JDK 17+
• Windows x64（内置运行时为 dsh-jsonrpc-agent-pkg-win-x64.exe）
• 使用自定义模型提供方时需要一个 OpenAI 兼容的 API 地址与 API Key
• 目前只支持windows

安装

将本项目安装到本地 Maven 仓库：

mvn clean install

然后在你的项目中引入依赖：

<dependency>
    <groupId>com.deepseek</groupId>
    <artifactId>deepseek-harness-java-sdk</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

快速开始

import com.deepseek.harness.DeepSeekHarness;
import com.deepseek.harness.model.HarnessConfig;
import com.deepseek.harness.model.RunResult;

public class Example {
    public static void main(String[] args) {
        HarnessConfig config = HarnessConfig.builder()
                .provider("deepseek-official")
                .model("deepseek-v4-flash")
                .apiKey(System.getenv("GLM_API_KEY"))
                .maxTokens(49152)
                .build();

        try (DeepSeekHarness harness = new DeepSeekHarness(config)) {
            RunResult result = harness.run("检查这个仓库并修复失败的测试。");
            System.out.println("Response: " + result.getFinalResponse());
            System.out.println("Finish reason: " + result.getFinishReason());
        }
    }
}

完整示例见 src/main/java/com/deepseek/harness/example/Example.java。

配置项（HarnessConfig）

可用 HarnessConfig.builder()（推荐）或 HarnessConfig 上的 setter：

字段	说明	默认值
provider	模型提供方标识。deepseek-official 使用内置适配器；其他值会自动生成 OpenAI 兼容路由	deepseek-official
model	模型名，例如 deepseek-v4-flash	deepseek-v4-flash
maxTokens	单次生成的最大 token 数（自定义提供方路由的默认值）	32768
cwd	工作区目录：agent 的 bash/文件系统工作目录，也是会话持久化命名空间来源	进程当前目录
sessionRoot	会话持久化根目录	./.harness-sessions
apiKey	API Key（写入 DEEPSEEK_API_KEY 环境变量传给运行时）	无
baseUrl	自定义提供方的 OpenAI 兼容 API 地址（deepseek-official 不需要）	无
cordis	自定义 cordis.yml 路径（覆盖内置/生成的配置）	内置配置
systemPrompt	系统提示词（写入 DSH_SYSTEM_PROMPT）	无
runtimeBin	自定义运行时可执行文件路径	内置二进制
addEnvironment(k, v)	追加任意环境变量传给运行时进程	无

自定义模型提供方

内置运行时只打包了 deepseek-official 适配器。配置其他提供方时，SDK 会读取内置 cordis.yml 并生成一个挂载 @deepseek-ai/dsh-llm-pi-ai 适配器、声明 OpenAI 兼容路由的新配置文件（临时目录，形如 cordis-<provider>.yml）。

HarnessConfig config = HarnessConfig.builder()
        .provider("glm")
        .baseUrl("https://open.bigmodel.cn/api/paas/v4")
        .model("glm-4-flash")
        .apiKey(System.getenv("GLM_API_KEY"))
        .build();

生成自定义路由要求同时配置 provider、baseUrl、model；API Key 始终通过 DEEPSEEK_API_KEY 环境变量注入。自定义提供方路由的 contextWindow 固定为 262144，maxTokens 默认为 32768（可用 maxTokens 覆盖）。

会话与持久化

每次 run() 会使用一个会话 ID（未指定则自动生成 session-<uuid>）。使用相同会话 ID 连续调用 run() 可延续同一会话的上下文。

会话事件以压缩 JSONL 持久化到磁盘，目录结构：

<sessionRoot>/--<workspaceKey>--/session-<id>/session.jsonl.zstd

其中 --<workspaceKey>-- 是运行时按会话工作区路径自动生成的命名空间（分隔符替换为 -，非法字符转义），由 cwd 决定；sessionRoot 只决定其父目录。未配置 sessionRoot 时默认使用项目下的 ./.harness-sessions。

工作原理

运行时是独立子进程，双方通过 newline-delimited JSON-RPC over stdio 通信（dsh-sdk-protocol）：

1. DeepSeekHarness 启动子进程并完成 initialize 握手（cwd/provider/model/maxTokens），以此作为就绪信号——不依赖固定延迟。
2. run(prompt) 发送 session/prompt，然后从自己的订阅中同步收集事件，直到收到对应会话的 session.status = idle。
3. 该协议没有逐条 prompt 的结果响应，最终回复由流式事件推导：
   • finalResponse 来自 assistant/chunk 事件中 text-delta/block-end 的文本拼接；
   • finishReason 来自 turn/end 事件的 reason.kind（如 completed）。
4. close()/stop() 发送 shutdown 并终止进程。

DeepSeekHarness 实现 AutoCloseable，推荐使用 try-with-resources。

API 摘要

• run(String prompt) — 执行一个任务
• run(String prompt, String sessionId) — 使用指定会话执行（null 则新建）
• run(String prompt, Map<String, Object> options) — options 中可带 sessionId
• getSession(String sessionId) — 查看某会话已观察到的事件
• getNotificationLog() — 原始通知日志
• isRunning() — 运行时是否存活
• stop() / close() — 停止/释放运行时与临时文件

RunResult：getFinalResponse()、getFinishReason()、getEvents()（会话事件列表）、getMetadata()（含 sessionId、eventCount）。

运行时选择顺序

1. config.runtimeBin（显式指定）
2. 内置二进制（从 jar 资源解压到临时目录，复用已有解压文件）
3. dsh-jsonrpc-agent（PATH 中可用的已安装运行时）

启动失败时 HarnessException 会携带退出码和 stderr 尾部；若未找到 Node.js 也会有提示（仅在使用外部运行时、非内置二进制时需要）。

日志

使用 SLF4J，可自行接入 logback / log4j2 等实现。运行时 stderr 会转发到 debug 级别日志并保留最后 20 行用于错误报告。

依赖

• Jackson 2.15.3
• SLF4J 2.0.9
• 运行时二进制：src/main/resources/dsh-jsonrpc-agent-pkg-win-x64.exe