mirror of
https://github.com/deepseek-ai/deepseek-harness.git
synced 2026-08-29 04:26:38 +00:00
Tianyi Cui
7a11f5fde3
Record sdk-minimal as the narrow repository-owned exception to base-first profile composition: callers still launch only dsh and cannot provide an arbitrary Cordis tree, while the shipped bundle may own a complete explicit roster. Cross-link the launcher, profile-bundle, Python-runtime, minimal-agent, snapshot, and telemetry decisions; the supersession audit keeps each older note active because its remaining rationale is independent. Update the CLI, architecture, Python tutorial/reference, example, runtime-wheel reference, and bundle documentation. The docs distinguish the full sdk profile from sdk-minimal, explain explicit-home/plugin/patch customization, state the minimal permission and persistence choices, and retain the separately packaged web profile and frontend assets for direct dsh use. Correct dsh-base descriptions to cover base-backed profiles, make SDK startup configuration visible in the generated config catalog, add sdk-minimal to the module graph, and regenerate the base-composition graph. English and Chinese pairs are re-recorded at the exact reviewed contents.
109 lines
5.5 KiB
Markdown
109 lines
5.5 KiB
Markdown
# Get started with the Python SDK
|
|
|
|
English | [中文](python-sdk.zh.md)
|
|
|
|
This tutorial installs the published Python SDK, runs the shipped standalone minimal profile, 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-minimal` profile, installed plugins, and uncompressed JSONL 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()
|
|
with DeepSeekHarness(
|
|
provider="deepseek-official",
|
|
model="deepseek-v4-flash",
|
|
max_tokens=49_152,
|
|
cwd=str(workspace),
|
|
dsh_home=str(dsh_home),
|
|
profile="sdk-minimal",
|
|
env={"DSH_MODEL": "deepseek-v4-flash"},
|
|
) 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-minimal` process lazily and reuses it until context-manager exit. The profile, its persistent patch, the home patch, and any 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-minimal --dump-default-config >/dev/null
|
|
dsh plugin --profile sdk-minimal add file:/absolute/path/to/my-plugin-bundle
|
|
```
|
|
|
|
The first command initializes the shipped standalone 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-minimal/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 profile
|
|
|
|
| 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 |
|
|
| Runtime context and compaction | Absent |
|
|
| Session persistence | Uncompressed JSONL under `<dsh_home>/sessions` |
|
|
|
|
The profile's sole bundle inserts the complete tree over an empty root and does not include `dsh-base`; later base-profile tools therefore cannot appear implicitly. It contains the SDK protocol, one environment-configured DeepSeek adapter, local execution, and persistence, while settings, managed credentials, telemetry, Web tools, subagents, local instruction discovery, and compaction are absent. It pins `danger-full-access`, so persistent Bash and the editor can modify any path visible to the runtime; use a disposable checkout or container. The PTY implementation makes this example POSIX-only.
|
|
|
|
The installed wheel still packages the full `web` profile and frontend assets. Run `dsh web` against an explicit `DSH_HOME` when a Python SDK deployment also needs the browser application; `web` is a separate CLI application and cannot serve a Python SDK client.
|
|
|
|
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 [bundle reference](../../../packages/bundle/sdk-minimal/README.md) owns the exact tree, and the [example reference](../../../examples/python-sdk-agent/README.md) owns the runnable program. 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.
|