@@ -19,9 +19,9 @@ with DeepSeekHarness() as harness:
result = harness . run ( " Say hi. " )
```
`DeepSeekHarness` 会保留延迟 启动的运行时子进程，以供 多次调用复用。请像上例一样将其用作上下文管理器，或在用完后显式调用 `close()` 。
`DeepSeekHarness` 会保留其按需 启动的运行时子进程，以便在 多次调用之间 复用。请像上例一样将其用作上下文管理器，或在使 用完毕 后显式调用 `close()` 。
默认情况下， `deepseek-harness-runtime-bin` 包内置的单文件 `dsh-jsonrpc-agent` 可执行程序 ，并通过 `DSH_CORDIS_CONFIG` 注入该包的默认配置（ ` agent- core` 配有 显式组合语义检查点策略的 JSONL 会话持久化、 本地 bash） 里 保留 `@deepseek-ai/dsh-sdk-jsonrpc-server` 条目 ，并传入 Cordis 配置路径。
默认情况下， 会 启动 `deepseek-harness-runtime-bin` 包内置的单文件可执行程序 `dsh-jsonrpc-agent` ，并通过 `DSH_CORDIS_CONFIG` 注入该包的默认配置，其中包括 stdio JSON-RPC 服务器、agent core（智能体核心） 、预载的 DeepSeek 适配器、采用 显式组合语义检查点策略的 JSONL 会话持久化，以及 本地 bash。要运行自己的插件组合， 中 保留 `@deepseek-ai/dsh-sdk-jsonrpc-server` 配置项 ，并传入 Cordis 配置文件 路径。
``` py
from deepseek_harness import DeepSeekHarness
@@ -35,14 +35,14 @@ with DeepSeekHarness(
result = harness . run ( " Make the requested code change. " )
```
`provider` 用于选择当前 Cordis 组合已 注册的提供方路由；`model` 是该适配器解析的模型 ID。`max_tokens` 是可选的正整数，用于限制根 agent（智能体） 及其进程内后代每次请求的 输出 token；省略时 由提供方默认值控制 。压缩摘要继续使用压缩插件单独配置的上限。内置默认组合注册 `deepseek-official` 。自定义组合可以挂载 `llm-pi-ai` ，在其中配置各提供方的凭据与 端点，再 选择 pi-ai 已安装目录中 的任意提供方/模型组合。
`provider` 选择指定 Cordis 组合所 注册的提供方路由；`model` 是该适配器解析出 的模型 ID。`max_tokens` 是一个 可选的正整数，用于限制根 agent 及其进程内后代在 每次请求中 输出的 token 数量；省略该参数时， 由提供方的 默认行为决定输出上限 。压缩摘要继续使用压缩插件单独配置的上限。内置默认组合注册 `deepseek-official` 。自定义组合可以挂载 `llm-pi-ai` ，在其中配置各提供方专属 的凭据和 端点，并 选择 pi-ai 已安装 catalog 中存在 的任意提供方/模型组合。
[Python SDK 教程 ](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/python-sdk.md )提供不 使用 Web UI 的顺序 安装与 首次运行路径。 [`jsonrpc-agent` 示例 ](https://github.com/deepseek-ai/deepseek-harness/blob/master/examples/jsonrpc-agent/README.md )归属该教程使用的完整独立 Cordis 文件 。
[Python SDK 教程 ](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/python-sdk.md )提供一套无需 使用 Web UI、按步骤完成 安装和 首次运行的流程。该教程所用的完整独立 Cordis 配置文件位于 [`jsonrpc-agent` 示例 ](https://github.com/deepseek-ai/deepseek-harness/blob/master/examples/jsonrpc-agent/README.md )中 。
`Session.run()` 拥有一个从 提示词进入 持久 inbox 时开始、 到整个 agent 下一次进入空闲状态为止的活动区间 ，并返回 `RunResult(session_id, final_response, finish_reason, events, notifications, session_root)` 。`final_response` 是该区间内根会话最后提交的助手文本。`finish_reason` 是该区间内根会话最后一个 `turn/end` 的 `kind` ，例如 `completed` 、`max-tokens` 或 `error` ；没有轮次结束时为 `None` 。缺少字符串 `data.reason.kind` 的 `turn/end` 违反运行时协议，并会抛出 `SdkProtocolError` 。两个结果字段描述的都是自有活动区间，而不是 因果上归属于该提示词的输出或结束原因 。steering（ ） 都 可能在进入空闲状态前参与其中 。
`Session.run()` 的活动区间从其 提示词被 持久 inbox 接收 时开始， 时结束 ，并返回 `RunResult(session_id, final_response, finish_reason, events, notifications, session_root)` 。`final_response` 是该区间内根会话最后提交的助手文本。`finish_reason` 是该区间内根会话最后一个 `turn/end` 的 `kind` ，例如 `completed` 、`max-tokens` 或 `error` ；没有轮次结束时为 `None` 。缺少字符串 `data.reason.kind` 的 `turn/end` 违反运行时协议，并会抛出 `SdkProtocolError` 。这 两个结果字段描述的是 `Session.run()` 所界定的活动区间，并不表示某项输出或结束原因在 因果上归属于该提示词。steering（ ） ，也 可能在 agent 进入空闲状态前参与这段活动 。
`HarnessClient` 会在运行时进程的生命周期内保留已发现的 subagent（子 agent） 系。每次执行 `Session.run()` 时，`RunResult.notifications` 与 `on_notification` 会按协议传输顺序收到根会话及所有已知后代的通知，其中包括嵌套 subagent 的生命周期事件与会话事件。`RunResult.events` 只包含根会话事件，因此后代消息不会覆盖根会话回复。底层 `session_prompt()` 会立即返回已排队消息的 `MessageId` ；绕过 `Session.run()` 的调用方必须自行负责后续的活动边界。
`HarnessClient` 会在运行时进程的整个 生命周期内保留已发现的 subagent 谱 系。每次执行 `Session.run()` 时，`RunResult.notifications` 与 `on_notification` 会按协议传输顺序收到根会话及所有已知后代的通知，其中包括嵌套 subagent 的生命周期事件与会话事件。`RunResult.events` 只包含根会话事件，因此后代消息不会覆盖根会话回复。底层 `session_prompt()` 会立即返回已排队消息的 `MessageId` ；绕过 `Session.run()` 的调用方必须自行负责后续的活动边界。
同样的行为 也可以通过 `DSH_CORDIS_CONFIG` 为运行时子进程选定 。注入逻辑位于 `HarnessClient.start()` ，因此底层客户端的 默认启动也具有此 行为：当启动 解析到 内置运行时，且 `cordis` 与 非空的 `DSH_CORDIS_CONFIG` 均未设置时 （运行时把 空值视为缺省 ，注入检查与之一致）， 使用内置的 默认配置；显式给出 `runtime_bin` 、`bridge_bin` 或 `launch_args_override` 则 完全禁用注入。运行时载体（生产用 exe 与仅限开发的 `node` 闭包）及其获取方式见 [sdk-runtime README ](https://github.com/deepseek-ai/deepseek-harness/blob/master/python/sdk-runtime/README.md )。
也可以通过 `DSH_CORDIS_CONFIG` 为运行时子进程指定配置 。注入逻辑位于 `HarnessClient.start()` ，因此底层客户端按 默认方式 启动时 也具有该 行为：如果启动方式最终 解析为 内置运行时，且既没有设置 `cordis` ，也没有设置 非空的 `DSH_CORDIS_CONFIG` （运行时将 空值视为未设置 ，注入检查也是如此），系统就会 使用内置默认配置；显式指定 `runtime_bin` 、`bridge_bin` 或 `launch_args_override` 时，则会 完全禁用该 注入。运行时载体（生产用 exe 与仅限开发的 `node` 闭包）及其获取方式见 [sdk-runtime README ](https://github.com/deepseek-ai/deepseek-harness/blob/master/python/sdk-runtime/README.md )。
`cwd` 与 `runtime_cwd` 会在启动子进程、注入环境变量和协议握手前解析为绝对路径。公开 API 只暴露真正生效的选项：部署的角色设定与 持久化配置归 `cordis.yml` 管理，而 `session_root` 继续作 为设置 `DSH_SESSION_ROOT` 的高层便捷选项 。
`cwd` 与 `runtime_cwd` 会在启动子进程、注入环境变量和协议握手前解析为绝对路径。公开 API 只暴露由 SDK 直接应用的选项：部署 persona 和 持久化配置应在 `cordis.yml` 中定义； `session_root` 则保留 为设置 `DSH_SESSION_ROOT` 的高层便捷参数 。
Yichen Jiang