Yichen Jiang
fee12f1af0
The native adapter's route was named deepseek, colliding with pi-ai's catalog provider of the same name, so the two DeepSeek paths could never be mounted side by side. The web settings page needs both configurable at once. Compositions, fixtures, goldens, scaffolding defaults, and docs all move together (pre-release, no shim); TUI/session-query-spill/ missing-credential goldens re-recorded through their keyless refresh modes because provider-name length shifts box padding and spill truncation points.
3.5 KiB
DeepSeek Harness Python SDK
English | 中文
通过 JSON-RPC stdio 驱动 DeepSeek Harness 的 Python 子进程 SDK。运行时继承常规的 DeepSeek Harness 环境变量（如 DEEPSEEK_BASE_URL 与 DEEPSEEK_API_KEY），调用方可以直接用真实模型端点，也可以在跑基准测试时把它们指向本地代理。
安装 deepseek-harness 会同时安装版本完全相同的 deepseek-harness-runtime-bin 平台 wheel 包。因此常规入口不需要传可执行文件参数：
from deepseek_harness import DeepSeekHarness
with DeepSeekHarness() as harness:
result = harness.run("Say hi.")
DeepSeekHarness 会保留延迟启动的运行时子进程，以供多次调用复用。请像上例一样将其用作上下文管理器，或在用完后显式调用 close()。
默认情况下，SDK 启动 deepseek-harness-runtime-bin 包内置的单文件 dsh-jsonrpc-agent 可执行程序，并通过 DSH_CORDIS_CONFIG 注入该包的默认配置（stdio JSON-RPC 服务器、agent-core、预载的 DeepSeek 适配器、配有显式组合语义检查点策略的 JSONL 会话持久化、本地 bash）。要运行自己的插件组合，请在配置里保留 @deepseek-ai/dsh-jsonrpc 条目，并传入 Cordis 配置路径。
from deepseek_harness import DeepSeekHarness
with DeepSeekHarness(
provider="deepseek-official",
model="deepseek-v4-flash",
max_tokens=49_152,
cordis="examples/jsonrpc-agent/cordis.yml",
) as harness:
result = harness.run("Make the requested code change.")
provider 用于选择当前 Cordis 组合已注册的提供方路由；model 是该适配器解析的模型 ID。max_tokens 是可选的正整数，用于限制根 agent 及其进程内后代每次请求的输出 token；省略时由提供方默认值控制。压缩摘要继续使用压缩插件单独配置的上限。内置默认组合注册 deepseek-official。自定义组合可以挂载 llm-pi-ai，在其中配置各提供方的凭据与端点，再选择 pi-ai 已安装目录中的任意提供方/模型组合。
HarnessClient 会在运行时进程的生命周期内保留已发现的 subagent（子 agent）祖先关系。每次执行 Session.run() 时，TurnResult.notifications 与 on_notification 会按线上的原始顺序收到根会话及所有已知后代的通知，其中包括嵌套 subagent 的生命周期与会话事件。TurnResult.events 仍只保存根会话的完整事件流，TurnResult.final_response 则取该会话最后一个 assistant/message 的文本内容，因此后代消息不会覆盖根会话回复。
同样的行为也可以通过 DSH_CORDIS_CONFIG 为运行时子进程选定。注入逻辑位于 HarnessClient.start()，因此底层客户端的默认启动也具有此行为：当启动解析到内置运行时，且 cordis 与非空的 DSH_CORDIS_CONFIG 均未设置时（运行时把空值视为缺省，注入检查与之一致），使用内置的默认配置；显式给出 runtime_bin、bridge_bin 或 launch_args_override 则完全禁用注入。运行时载体（生产用 exe 与仅限开发的 node 闭包）及其获取方式见 sdk-runtime README。
cwd 与 runtime_cwd 会在启动子进程、注入环境变量和协议握手前解析为绝对路径。公开 API 只暴露真正生效的选项：部署的角色设定与持久化配置归 cordis.yml 管理，而 session_root 继续作为设置 DSH_SESSION_ROOT 的高层便捷选项。