2026-07-11 14:08:24 +08:00
|
|
|
|
# DeepSeek Harness Python SDK
|
|
|
|
|
|
|
|
|
|
|
|
[English](README.md) | 中文
|
|
|
|
|
|
|
2026-08-10 19:30:46 +08:00
|
|
|
|
通过 JSON-RPC stdio 驱动 DeepSeek Harness 的 Python 子进程 SDK。运行时继承常规的 DeepSeek Harness 环境变量（如 `DEEPSEEK_BASE_URL` 与 `DEEPSEEK_API_KEY`），调用方可以直接使用真实模型端点，也可以把这些变量指向本地代理。
|
2026-07-11 14:08:24 +08:00
|
|
|
|
|
2026-08-10 19:45:54 +08:00
|
|
|
|
请从 PyPI 安装 `deepseek-harness-sdk` 分发包；导入模块仍为 `deepseek_harness`：
|
|
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
|
python -m pip install deepseek-harness-sdk
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
安装 `deepseek-harness-sdk` 会同时安装版本完全相同的 `deepseek-harness-runtime-bin` 平台 wheel 包。因此常规入口不需要传可执行文件参数：
|
2026-07-13 16:34:16 +08:00
|
|
|
|
|
|
|
|
|
|
```py
|
|
|
|
|
|
from deepseek_harness import DeepSeekHarness
|
|
|
|
|
|
|
fix(sdk): harden runtime lifecycle and JSON-RPC
Keep DeepSeekHarness.run() reusable, but make ownership of its lazy
runtime process explicit. Document the context-manager/close contract and
update every construction example to use a context manager so repeated runs
remain valid without encouraging leaked subprocesses.
Contain notification predicate failures at the subscription boundary. Remove
only the subscriber whose callback raised, deliver that exception through its
queue, and continue dispatching to healthy subscribers so arbitrary callback
code cannot terminate the shared reader thread or strand later requests.
Enforce one in-flight prompt per server session with an atomic activePrompt
guard. Route overlap through the existing -32603 handler-error response and
clear the guard in finally, preserving parallel prompts across sessions and
sequential reuse without changing JSON-RPC request or notification shapes.
Use StringDecoder for line framing so a UTF-8 code point split across Buffer
chunks is not corrupted. Add a queued-write flush barrier, and make memoized
shutdown await it before disposal and exit while retaining exactly-once
cleanup when shutdown calls race or flushing fails.
Cover callback isolation, same-session exclusion, cross-session concurrency,
split multibyte input, delayed writes, racing shutdown, and flush failure with
deterministic tests.
2026-07-13 20:53:20 +08:00
|
|
|
|
with DeepSeekHarness() as harness:
|
|
|
|
|
|
result = harness.run("Say hi.")
|
2026-07-13 16:34:16 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
fix(sdk): harden runtime lifecycle and JSON-RPC
Keep DeepSeekHarness.run() reusable, but make ownership of its lazy
runtime process explicit. Document the context-manager/close contract and
update every construction example to use a context manager so repeated runs
remain valid without encouraging leaked subprocesses.
Contain notification predicate failures at the subscription boundary. Remove
only the subscriber whose callback raised, deliver that exception through its
queue, and continue dispatching to healthy subscribers so arbitrary callback
code cannot terminate the shared reader thread or strand later requests.
Enforce one in-flight prompt per server session with an atomic activePrompt
guard. Route overlap through the existing -32603 handler-error response and
clear the guard in finally, preserving parallel prompts across sessions and
sequential reuse without changing JSON-RPC request or notification shapes.
Use StringDecoder for line framing so a UTF-8 code point split across Buffer
chunks is not corrupted. Add a queued-write flush barrier, and make memoized
shutdown await it before disposal and exit while retaining exactly-once
cleanup when shutdown calls race or flushing fails.
Cover callback isolation, same-session exclusion, cross-session concurrency,
split multibyte input, delayed writes, racing shutdown, and flush failure with
deterministic tests.
2026-07-13 20:53:20 +08:00
|
|
|
|
`DeepSeekHarness` 会保留延迟启动的运行时子进程，以供多次调用复用。请像上例一样将其用作上下文管理器，或在用完后显式调用 `close()`。
|
|
|
|
|
|
|
2026-07-21 15:23:45 +08:00
|
|
|
|
默认情况下，SDK 启动 `deepseek-harness-runtime-bin` 包内置的单文件 `dsh-jsonrpc-agent` 可执行程序，并通过 `DSH_CORDIS_CONFIG` 注入该包的默认配置（stdio JSON-RPC 服务器、`agent-core`、预载的 DeepSeek 适配器、配有显式组合语义检查点策略的 JSONL 会话持久化、本地 bash）。要运行自己的插件组合，请在配置里保留 `@deepseek-ai/dsh-jsonrpc` 条目，并传入 Cordis 配置路径。
|
2026-07-11 14:08:24 +08:00
|
|
|
|
|
|
|
|
|
|
```py
|
|
|
|
|
|
from deepseek_harness import DeepSeekHarness
|
|
|
|
|
|
|
|
|
|
|
|
with DeepSeekHarness(
|
2026-07-29 16:36:07 +08:00
|
|
|
|
provider="deepseek-official",
|
2026-07-11 14:08:24 +08:00
|
|
|
|
model="deepseek-v4-flash",
|
2026-07-28 17:36:44 +08:00
|
|
|
|
max_tokens=49_152,
|
2026-07-19 22:19:42 +08:00
|
|
|
|
cordis="examples/jsonrpc-agent/cordis.yml",
|
2026-07-11 14:08:24 +08:00
|
|
|
|
) as harness:
|
|
|
|
|
|
result = harness.run("Make the requested code change.")
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-08-05 12:46:38 +08:00
|
|
|
|
`provider` 用于选择当前 Cordis 组合已注册的提供方路由；`model` 是该适配器解析的模型 ID。`max_tokens` 是可选的正整数，用于限制根 agent（智能体）及其进程内后代每次请求的输出 token；省略时由提供方默认值控制。压缩摘要继续使用压缩插件单独配置的上限。内置默认组合注册 `deepseek-official`。自定义组合可以挂载 `llm-pi-ai`，在其中配置各提供方的凭据与端点，再选择 pi-ai 已安装目录中的任意提供方/模型组合。
|
2026-07-14 21:57:52 +08:00
|
|
|
|
|
2026-08-10 19:53:51 +08:00
|
|
|
|
[Python SDK 教程](../../docs/user/guide/python-sdk.md)使用完整的独立 Cordis 文件演示安装方式、直接调用 SDK，以及在不使用 Web UI 的情况下运行 agent。
|
2026-08-10 19:30:46 +08:00
|
|
|
|
|
2026-08-09 12:35:06 +08:00
|
|
|
|
`Session.run()` 拥有一个从提示词进入持久 inbox 时开始、到整个 agent 下一次进入空闲状态为止的活动区间，并返回 `RunResult(session_id, final_response, events, notifications, session_root)`。结果不携带提示词级状态或轮次原因：`final_response` 是该区间内根会话最后提交的助手文本，并非因果上归属于该提示词的输出。steering（中途引导）、注入的上下文和其他排队工作都可能在进入空闲状态前参与其中。
|
2026-07-30 16:48:28 +08:00
|
|
|
|
|
|
|
|
|
|
`HarnessClient` 会在运行时进程的生命周期内保留已发现的 subagent（子 agent）祖先关系。每次执行 `Session.run()` 时，`RunResult.notifications` 与 `on_notification` 会按协议传输顺序收到根会话及所有已知后代的通知，其中包括嵌套 subagent 的生命周期事件与会话事件。`RunResult.events` 只包含根会话事件，因此后代消息不会覆盖根会话回复。底层 `session_prompt()` 会立即返回已排队消息的 `MessageId`；绕过 `Session.run()` 的调用方必须自行负责后续的活动边界。
|
2026-07-11 14:08:24 +08:00
|
|
|
|
|
2026-07-14 16:21:41 +08:00
|
|
|
|
同样的行为也可以通过 `DSH_CORDIS_CONFIG` 为运行时子进程选定。注入逻辑位于 `HarnessClient.start()`，因此底层客户端的默认启动也具有此行为：当启动解析到内置运行时，且 `cordis` 与非空的 `DSH_CORDIS_CONFIG` 均未设置时（运行时把空值视为缺省，注入检查与之一致），使用内置的默认配置；显式给出 `runtime_bin`、`bridge_bin` 或 `launch_args_override` 则完全禁用注入。运行时载体（生产用 exe 与仅限开发的 `node` 闭包）及其获取方式见 [sdk-runtime README](../sdk-runtime/README.md)。
|
2026-07-13 16:34:16 +08:00
|
|
|
|
|
docs(i18n): align single-exe terminology
Add canonical Chinese bindings for build target, deploy root, peer
dependency, serving surface, wheel, wrapper, and VFS so future translations
have one source of truth. Apply the existing runtime, plugin, artifact, and
pipeline bindings throughout every Chinese counterpart touched by this PR.
Require the first Chinese use of peer dependency to retain the English term
so readers can map it back to the package-manager concept without
reintroducing mixed prose throughout the document.
Rewrite mixed-language prose where the English term is not an identifier,
while retaining package names, paths, flags, pkg, single-exe, and other
literal names exactly. Explain VFS on first use and keep technical constraints
readable without inventing compatibility terminology.
Describe single-executable worker support as implemented behavior, including
the filesystem-string entry contract and CommonJS worker artifact required by
the pkg loader, and remove the obsolete bundled-but-unsupported limitation.
Regenerate pairing fingerprints and the generated catalog reference so the
mechanical documentation gates validate the revised English and Chinese
pairs. This keeps the terminology table authoritative and prevents the two
languages from drifting as the runtime documentation evolves.
2026-07-13 21:03:25 +08:00
|
|
|
|
`cwd` 与 `runtime_cwd` 会在启动子进程、注入环境变量和协议握手前解析为绝对路径。公开 API 只暴露真正生效的选项：部署的角色设定与持久化配置归 `cordis.yml` 管理，而 `session_root` 继续作为设置 `DSH_SESSION_ROOT` 的高层便捷选项。
|