DSH Python SDK config: profile patches and editor patch

DeepSeek Harness Python SDK configuration is not one file; it is four layers: the profile, the profile’s persistent patch, the home patch, and the patches tuple passed to DeepSeekHarness. The tuple is the usual reason a change “disappears next time”—it was never persistent. This article separates the layers, then shows how to add str_replace_editor back.

DeepSeek Harness: What each layer controls

The final tree applies the profile, profile patch, home patch, and per-run patches in order; later layers win. Map them:(source)

One rule matters more than the rest: a patch replaces the entire config of the target row, not individual keys. When editing one field, copy the full row first or the other fields disappear.

from pathlib import Path
from deepseek_harness import DeepSeekHarness

workspace = Path("/srv/work/demo").resolve()
dsh_home = Path("/srv/dsh-home/demo").resolve()

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    dsh_home=str(dsh_home),
    profile="sdk-minimal",
    patches=("/srv/dsh-home/demo/patches/editor.patch.yml",),
) as harness:
    result = harness.run("Inspect the repository.", session_id="demo-001")

DeepSeek Harness: Persist a change

To keep a change across restarts, write it into $DSH_HOME/profiles/sdk-minimal/cordis.patch.yml. Steps:(source)

1. Initialize the profile — dsh --profile sdk-minimal --dump-default-config >/dev/null. Expected: the profile directory and default combination exist.
2. Edit cordis.patch.yml — write only the rows you need; do not paste the whole tree. Expected: the file parses as YAML.
3. Dump the effective tree — dsh --profile sdk-minimal --dump-config. Expected: your change appears with its source file.
4. Run the SDK again — construct DeepSeekHarness. Expected: the new setting applies without the constructor tuple.

If step 3 does not show the change, check DSH_HOME first. The SDK only reads the home you pass; it does not silently read ~/.dsh.

DeepSeek Harness: Apply a one-off patch

Use the patches tuple for changes that should not outlive the process. Three good uses:(source)

1. Temporary timeout bump — a longer budget for one job. Expected: the setting disappears when the process exits.
2. Temporary tool mount — enable str_replace_editor for one debugging run. Expected: other jobs do not see it.
3. A/B comparison — run the same home with two patch files. Expected: results are comparable and neither pollutes the other.

Use absolute paths; order is stacking order. A later patch overrides the same target row from an earlier patch.

DeepSeek Harness: Add str_replace_editor

sdk-minimal does not mount str_replace_editor by default; add it with an editor.patch.yml. The official insert:(source)

- insert:
    - id: tool-str-replace-editor
      name: '@deepseek-ai/dsh-tool-str-replace-editor'

Three ways to use it:

1. Per run — save as /srv/dsh-home/demo/patches/editor.patch.yml and pass patches=("/srv/dsh-home/demo/patches/editor.patch.yml",). Expected: the next run exposes str_replace_editor.
2. Persistent — merge the same insert into profiles/sdk-minimal/cordis.patch.yml. Expected: every startup includes the tool.
3. Standard sdk profile — the same patch applies to sdk. Expected: switching profile="sdk" still exposes the tool.

The local filesystem backend resolves relative paths against the runtime working directory and does not confine access to it. Enable the editor only with a sandbox or a disposable checkout.

DeepSeek Harness: Patch replaces the whole config

The official rule is “replace the target row’s entire config”, not deep merge. If the original row has apiKeyEnv, api, and baseURL, a patch that writes only api removes the other two. Copy the full row, change one field, then verify with --dump-config. (source)

DeepSeek Harness: Which configuration path to choose

Persistent profile patch, home patch, and constructor patches solve different problems. Compare:(source)

1. Profile persistent patch — for “this SDK app should always behave this way”. Cost: switching homes loses it.
2. Home patch — for “every SDK profile on this machine should inherit this”. Cost: broad blast radius during debugging.
3. Constructor patches — for “this one run only”. Cost: easy to forget, which silently restores defaults.

A practical rule: validate in the constructor tuple, then move the stable change into the profile patch. That keeps experiments out of long-lived environments.

DeepSeek Harness FAQ

Does editing cordis.patch.yml hot-reload the SDK? No. Construct DeepSeekHarness again. Persistent patches are read at startup, and a running harness does not watch the file.

Why did my other fields disappear when I changed one field? Because the patch replaced the entire config. Copy the original row first, then change one field.

Can profile point at a directory I created? Yes, but it must include @deepseek-ai/dsh-sdk-app or another JSON-RPC server entry. A missing server entry fails startup and does not fall back.

The short version: decide how long the change should live before choosing a layer. One run goes in patches; a lasting change goes in cordis.patch.yml.