mirror of
https://github.com/deepseek-ai/deepseek-harness.git
synced 2026-08-29 04:26:38 +00:00
Tianyi Cui
c2ad69344f
Give the SDK JSON-RPC server a per-root tool filter and let deployments mark the configured persona as the complete system prompt. The checked-in minimal overlay now names only bash and str_replace_editor, so later global tools and unrelated guidance from dsh-base cannot appear implicitly. Keep the shared SDK host services and packaged Web capability intact. Only workspace instructions, compaction, and the conflicting one-shot Bash row remain disabled. Unit coverage pins the configuration paths, and a real dsh profile smoke proves the assembled prompt and exact two-tool request.
109 lines
5.1 KiB
Markdown
109 lines
5.1 KiB
Markdown
# Get started with the Python SDK
|
|
|
|
English | [中文](python-sdk.zh.md)
|
|
|
|
This tutorial installs the published Python SDK, runs the checked-in minimal profile overlay, and shows how to customize the same `dsh` profile from your own program.
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.10 or newer
|
|
- Git
|
|
- Linux x64, Linux arm64, or macOS 14 or newer on arm64
|
|
- A DeepSeek-compatible API endpoint and credential
|
|
- An isolated workspace and an isolated Harness home
|
|
|
|
## Install the SDK
|
|
|
|
```sh
|
|
git clone https://github.com/deepseek-ai/deepseek-harness.git
|
|
cd deepseek-harness
|
|
python -m venv .venv
|
|
. .venv/bin/activate
|
|
python -m pip install deepseek-harness-sdk
|
|
```
|
|
|
|
The installation includes a matching native runtime wheel and the `dsh` command. Normal SDK execution needs no system Node.js. Repository contributors who build the artifacts should use the [Python contributor workflow](../../../python/development.md).
|
|
|
|
## Run the checked-in example
|
|
|
|
Export the credential and, when needed, a compatible proxy endpoint:
|
|
|
|
```sh
|
|
export DEEPSEEK_API_KEY=sk-your-key-here
|
|
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
|
|
```
|
|
|
|
Run one task with explicit workspace and home paths:
|
|
|
|
```sh
|
|
python examples/python-sdk-agent/minimal.py \
|
|
--workspace /absolute/path/to/disposable-workspace \
|
|
--dsh-home /absolute/path/to/example-dsh-home \
|
|
--session-id example-001 \
|
|
"Inspect the repository and fix the failing tests."
|
|
```
|
|
|
|
The script prints the final assistant response. The selected home receives the generated `sdk` profile, settings, credentials if you add them, installed plugins, and Zstandard session logs under `sessions/`. The example and SDK never silently read `~/.dsh`.
|
|
|
|
## Use the SDK in your program
|
|
|
|
```python
|
|
from pathlib import Path
|
|
|
|
from deepseek_harness import DeepSeekHarness
|
|
|
|
workspace = Path("/absolute/path/to/disposable-workspace").resolve()
|
|
dsh_home = Path("/absolute/path/to/example-dsh-home").resolve()
|
|
patch = Path("examples/python-sdk-agent/minimal.patch.yml").resolve()
|
|
|
|
with DeepSeekHarness(
|
|
provider="deepseek-official",
|
|
model="deepseek-v4-flash",
|
|
max_tokens=49_152,
|
|
cwd=str(workspace),
|
|
dsh_home=str(dsh_home),
|
|
profile="sdk",
|
|
patches=(str(patch),),
|
|
) as harness:
|
|
result = harness.run(
|
|
"Inspect the repository and fix the failing tests.",
|
|
session_id="example-001",
|
|
)
|
|
|
|
print(result.final_response)
|
|
```
|
|
|
|
The SDK starts the bundled `dsh --profile sdk` process lazily and reuses it until context-manager exit. The profile, its persistent patch, the home patch, and the ordered `patches` tuple form the application configuration. There is no separate Python runtime bin or complete-config option.
|
|
|
|
## Install or define plugins
|
|
|
|
Use `dsh plugin` for dependencies and bundle layers that should persist in this home:
|
|
|
|
```sh
|
|
export DSH_HOME=/absolute/path/to/example-dsh-home
|
|
dsh --profile sdk --dump-default-config >/dev/null
|
|
dsh plugin --profile sdk add file:/absolute/path/to/my-plugin-bundle
|
|
```
|
|
|
|
The first command initializes the shipped SDK profile. The second forwards package management to `pnpm`, then records any installed package that exports a `dsh.bundle` layer. Install `pnpm` only for this management command; launching the installed SDK does not need it. Edit `$DSH_HOME/profiles/sdk/cordis.patch.yml` for persistent row changes, or pass patch files from Python for per-launch changes.
|
|
|
|
Another `profile` is valid when it includes `@deepseek-ai/dsh-sdk-app` or another JSON-RPC server row. Missing server rows, unresolved plugins, and invalid patches fail during startup instead of falling back to another composition.
|
|
|
|
## Understand the minimal overlay
|
|
|
|
| Property | Value |
|
|
|---|---|
|
|
| System prompt | `DSH_SYSTEM_PROMPT`, falling back to `You are a helpful software engineer assistant.` |
|
|
| Model in `minimal.py` | `--model`, then `DSH_MODEL`, then `deepseek-v4-flash` |
|
|
| Model-facing tools | Persistent `bash` and `str_replace_editor` only |
|
|
| Bash timeout | 300 seconds |
|
|
| Editor output limit | 16,000 characters |
|
|
| Context compaction | Disabled |
|
|
| Session persistence | Zstandard JSONL under `<dsh_home>/sessions` |
|
|
|
|
The overlay allowlists persistent Bash and the editor for every SDK-created root agent, so later base-profile tools cannot appear implicitly. It suppresses unrelated prompt sections and runtime-context messages, disables local instruction discovery and compaction, and retains the SDK application's protocol, persistence, policy, settings, credentials, and providers. Persistent Bash and the editor can modify any path visible to the runtime, so use a disposable checkout or container. The PTY implementation makes this example POSIX-only.
|
|
|
|
Use a fresh home when profiles, plugins, credentials, settings, and sessions must be isolated. Use a fresh session id for independent work; reuse a harness, home, and id only to continue the same durable conversation and session-owned resources.
|
|
|
|
The [example reference](../../../examples/python-sdk-agent/README.md) owns the checked-in overlay. The [Python SDK reference](../../../python/sdk/README.md) covers lifecycle, results, notifications, and low-level behavior; the [dsh CLI reference](../../../apps/cli/reference/README.md) covers profile layering.
|