README.zh.md 4.3 KB
DeepSeek Harness Python SDK
English | 中文
用于通过 stdio 上按行分隔的 JSON-RPC 驱动 DeepSeek Harness 的 Python 子进程 SDK。安装 deepseek-harness-sdk 时，会同时安装当前平台上版本完全相同的 deepseek-harness-runtime-bin wheel。
python -m pip install deepseek-harness-sdk
启动运行时
Python SDK 没有独立的应用入口。它以 --profile sdk 启动内置的 dsh CLI；所选 profile 负责 JSON-RPC 服务器、agent 组合、凭据、持久化、工具和关闭流程。
每次启动都必须显式指定 Harness home。请传入 dsh_home，或在子进程环境中提供非空的 DSH_HOME。SDK 刻意不会发现 ~/.dsh。
from deepseek_harness import DeepSeekHarness
with DeepSeekHarness(
dsh_home="/absolute/path/to/isolated-dsh-home",
cwd="/absolute/path/to/workspace",
) as harness:
result = harness.run("Say hi.", session_id="example-001")
print(result.final_response)
DeepSeekHarness 延迟启动运行时，并在调用 close() 或退出上下文管理器前复用该进程。cwd 是 agent workspace；runtime_cwd 独立选择子进程工作目录。两者都会在启动前转成绝对路径。provider、model 和可选的正整数 max_tokens 通过 JSON-RPC 初始化发送。base_url 与 api_key 会显式覆盖子进程环境中的 DEEPSEEK_BASE_URL 与 DEEPSEEK_API_KEY。
自定义插件
持久自定义属于 dsh profile。使用运行时 wheel 提供的 dsh 命令初始化随附的 SDK profile，并安装外部 bundle：
export DSH_HOME=/absolute/path/to/isolated-dsh-home
dsh --profile sdk --dump-default-config >/dev/null
dsh plugin --profile sdk add file:/absolute/path/to/my-plugin-bundle
file: 形式会把本地 bundle 安装到 profile 包树中，使其 peer import 可以到达内置安装后备。Profile manifest 会记录已安装依赖与有序 bundle 层；$DSH_HOME/profiles/sdk/cordis.patch.yml 是持久用户 patch。只有管理外部包时，dsh plugin 才需要 pnpm。运行 SDK 不需要系统 Node.js。
对于单次调用的变更，可传入一个或多个 patch 文件。它们会转成绝对路径，并在 profile 层与 home patch 层之后按顺序传给 CLI：
with DeepSeekHarness(
dsh_home="/absolute/path/to/isolated-dsh-home",
profile="sdk",
patches=("/absolute/path/to/first.patch.yml", "/absolute/path/to/last.patch.yml"),
) as harness:
result = harness.run("Make the requested code change.")
profile 可以选择另一个已存在的 profile，但该组合必须保留 @deepseek-ai/dsh-sdk-app 或另一个 @deepseek-ai/dsh-sdk-jsonrpc-server 配置项。配置错误会在 CLI 启动或 SDK 初始化时失败；不存在完整配置回退。dsh_bin 可以选择另一个 dsh 可执行程序，同时保持相同的 profile 语法。任意 argv 替换仅是内部 fake-runtime 测试适配器，不属于公开 API。
结果与通知
Session.run() 的活动区间从提示词被持久 inbox 接收时开始，到整个 agent 下一次进入 idle 时结束，并返回 RunResult(session_id, final_response, finish_reason, events, notifications)。final_response 是该区间内根会话最后提交的 assistant 文本。finish_reason 是最后一个根会话 turn/end 的 kind，例如 completed、max-tokens 或 error；没有轮次结束时为 None。缺少字符串 data.reason.kind 的 turn/end 违反协议，并会抛出 SdkProtocolError。
HarnessClient 会在运行时进程的整个生命周期内保留已发现的子 agent 祖先关系。在 Session.run() 期间，RunResult.notifications 与 on_notification 按协议顺序接收根会话和已知后代的通知。RunResult.events 只包含根会话事件，因此后代输出不会替换根响应。底层 session_prompt() 会立即返回已排队消息的 id；绕过 Session.run() 的调用方自行负责后续活动边界。
所选 home 保存 profile、插件、凭据、设置和会话。需要隔离这些资源时应使用新的 home；独立工作应使用新的 session id。同时复用 harness 与 session id 会延续持久对话和会话资源。