DeepSeek/deepseek-harness
1
0
Fork 0
mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(sdk): add minimal Python example

Browse Source
This commit is contained in:
Yichen Jiang
2026-08-10 19:30:46 +08:00
parent 86d5dd4384
commit 20139a3fb7
21 changed files with 421 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/user/guide/python-sdk-minimal.i18n.yaml Normal file
View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/user/guide/python-sdk-minimal.md
python-sdk-minimal.md: 9d46278aeec625afdf30678806bc90104be00b66
python-sdk-minimal.zh.md: ec06a205c680c1d7a83be5f949c7ff4d719defe4

95
docs/user/guide/python-sdk-minimal.md Normal file
View File

@@ -0,0 +1,95 @@
# Run the minimal agent with the Python SDK
English | [中文](python-sdk-minimal.zh.md)
This tutorial runs the minimal agent without the Web UI. The checked-in Cordis composition fixes the system prompt, tool catalog, persistent-shell behavior, and compaction policy so SDK runs use the same model-facing contract as the Web `minimal` preset.
## Prerequisites
- Python 3.10 or newer
- Linux x64, Linux arm64, or macOS arm64
- A DeepSeek-compatible API endpoint and credential
- An isolated workspace that the agent may modify
Create a virtual environment and install the SDK with its same-version bundled runtime:
```sh
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness
```
The runtime wheel contains the JSON-RPC executable and every plugin used by the complete [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml), so an installed SDK does not need Node.js.
## Run the checked-in example
Set the credential in the environment. Set `DEEPSEEK_BASE_URL` as well when the model is served by an OpenAI-compatible proxy rather than the default DeepSeek endpoint.
```sh
export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
```
Run one task from the repository checkout:
```sh
python examples/jsonrpc-agent/minimal.py \
--workspace /absolute/path/to/workspace \
--session-root /absolute/path/to/trajectories \
--session-id example-001 \
"Inspect the repository and fix the failing tests."
```
The script prints the final assistant response. The session root receives the JSONL trajectory, including the assembled model request and every tool call.
## Use the SDK in your own program
The example is a thin wrapper around this SDK call:
```python
from pathlib import Path
from deepseek_harness import DeepSeekHarness
config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions = Path("/absolute/path/to/trajectories").resolve()
with DeepSeekHarness(
provider="deepseek-official",
model="deepseek-v4-flash",
max_tokens=49_152,
cwd=str(workspace),
session_root=str(sessions),
cordis=str(config),
) as harness:
result = harness.run(
"Inspect the repository and fix the failing tests.",
session_id="example-001",
)
print(result.final_response)
```
`DeepSeekHarness` starts the bundled JSON-RPC runtime lazily and reuses it until the context manager exits. Reusing the same harness and session id across calls also preserves the session-owned Bash process, including its working directory, exported variables, and shell functions.
## Contract reproduced by the configuration
| Surface | Fixed value |
|---|---|
| System prompt | `You are a helpful software engineer assistant.` |
| Model-facing tools | Persistent `bash` and `str_replace_editor` only |
| Bash timeout | 300 seconds |
| Editor output limit | 16,000 characters |
| Compaction | Trigger ratio `0.8`, retain `20,480` tokens, summary cap `8,192` tokens, one retry |
| Session persistence | Uncompressed JSONL under `DSH_SESSION_ROOT` |
The configuration omits harness identity, workspace prompt text, skills, one-shot Bash, task tools, and every other model-facing plugin. Filesystem policy facts are logged as runtime user context rather than appended to the system prompt. The editor requires absolute paths as an unconditional current contract, so the obsolete `requireAbsolutePath` option is absent.
## Keep runs reproducible
For comparable trajectories, pin the Harness commit and Python package version together, retain the exact Cordis file, and record the provider, model, endpoint, `max_tokens`, task input, workspace state, and session id for every run. Start independent runs with a clean workspace and a fresh session id; reuse a session only when multi-turn state is intentional.
The composition uses `danger-full-access`. Run it only inside a disposable checkout or container: Bash and the editor can modify any path allowed to the runtime process. The persistent PTY backend requires a POSIX terminal substrate and is not a Windows agent surface.
For the complete SDK lifecycle and result contract, see the [Python SDK reference](../../../python/sdk/README.md). For Cordis composition syntax, see [Configuration](./config.md).

95
docs/user/guide/python-sdk-minimal.zh.md Normal file
View File

@@ -0,0 +1,95 @@
# 使用 Python SDK 运行极简 agent（智能体）
[English](python-sdk-minimal.md) | 中文
本教程介绍如何在不使用 Web UI 的情况下运行极简 agent。仓库内置的 Cordis 组合固定了系统提示词、工具目录、持久 shell 行为和压缩（compaction）策略，因此 SDK 运行与 Web `minimal` preset 使用相同的面向模型约定。
## 前置要求
- Python 3.10 或更高版本
- Linux x64、Linux arm64 或 macOS arm64
- DeepSeek 兼容的 API 端点与凭据
- agent 可以修改的隔离 workspace
请创建虚拟环境，并安装 SDK 及其同版本内置运行时：
```sh
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness
```
运行时 wheel 包含 JSON-RPC 可执行文件，以及完整 [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml) 使用的每个插件，因此安装后的 SDK 不需要 Node.js。
## 运行仓库内置示例
请在环境中设置凭据。如果模型不是由默认 DeepSeek 端点提供，而是通过 OpenAI 兼容代理提供，还需要设置 `DEEPSEEK_BASE_URL`。
```sh
export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
```
从仓库 checkout 运行一个任务：
```sh
python examples/jsonrpc-agent/minimal.py \
--workspace /absolute/path/to/workspace \
--session-root /absolute/path/to/trajectories \
--session-id example-001 \
"Inspect the repository and fix the failing tests."
```
脚本会打印 assistant 的最终回复。会话根目录会收到 JSONL 运行轨迹，其中包含组装后的模型请求与每次工具调用。
## 在自己的程序中使用 SDK
该示例是以下 SDK 调用的轻量包装层：
```python
from pathlib import Path
from deepseek_harness import DeepSeekHarness
config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions = Path("/absolute/path/to/trajectories").resolve()
with DeepSeekHarness(
provider="deepseek-official",
model="deepseek-v4-flash",
max_tokens=49_152,
cwd=str(workspace),
session_root=str(sessions),
cordis=str(config),
) as harness:
result = harness.run(
"Inspect the repository and fix the failing tests.",
session_id="example-001",
)
print(result.final_response)
```
`DeepSeekHarness` 会延迟启动内置 JSON-RPC 运行时，并持续复用，直至退出上下文管理器。在多次调用中复用同一个 harness 和 session id，还会保留该会话拥有的 Bash 进程，包括其工作目录、已导出的变量与 shell 函数。
## 配置复现的约定
| 方面 | 固定值 |
|---|---|
| 系统提示词 | `You are a helpful software engineer assistant.` |
| 面向模型的工具 | 仅持久 `bash` 与 `str_replace_editor` |
| Bash 超时 | 300 秒 |
| 编辑器输出上限 | 16,000 个字符 |
| 压缩 | 触发比例 `0.8`、保留 `20,480` 个 token、摘要上限 `8,192` 个 token、重试 1 次 |
| 会话持久化 | `DSH_SESSION_ROOT` 下未压缩的 JSONL |
该配置省略了 harness 身份、workspace 提示词文本、skill（技能）、一次性 Bash、任务工具和其他所有面向模型的插件。文件系统策略事实记录为运行时用户上下文，而不会追加到系统提示词中。编辑器无条件要求绝对路径，因此配置中没有已经废弃的 `requireAbsolutePath` 选项。
## 保持运行可复现
为了让运行轨迹可复现且便于比较，请配套固定 Harness commit 与 Python 包版本，保留确切的 Cordis 文件，并为每次运行记录提供方、模型、端点、`max_tokens`、任务输入、workspace 状态和 session id。独立运行应使用干净的 workspace 和新的 session id；只有有意保留多轮状态时才复用会话。
该组合使用 `danger-full-access`。只能在可丢弃的 checkout 或容器内运行：Bash 与编辑器可以修改运行时进程有权访问的任何路径。持久 PTY 后端需要 POSIX 终端环境，因此该模式不适用于 Windows agent。
完整的 SDK 生命周期与结果约定见 [Python SDK 参考](../../../python/sdk/README.md)。Cordis 组合语法见[配置](./config.md)。

4
docs/user/guide/quickstart.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/user/guide/quickstart.md
quickstart.md: ce196641f205324334533c025b4ac1dc791f857d
quickstart.zh.md: 3a5d6d0748ec0c7ec83c74570d0fad1e8d66a97c
quickstart.md: 13d5b2196282394619747e36ecddfa1d87f61c8d
quickstart.zh.md: 3d775db9280b43bbee2de37f7327fe8d2bd3a121

1
docs/user/guide/quickstart.md
View File

@@ -57,6 +57,7 @@ Open `http://127.0.0.1:3080`. The agent can read and write files, run commands,
## Next steps
- [Run the minimal agent with Python](./python-sdk-minimal.md) — use the fixed two-tool composition without the Web UI
- [Configure models](./providers.md) — reach providers beyond DeepSeek, and custom gateways
- [Configuration](./config.md) — understand the `cordis.yml` format
- [Develop a plugin](../develop/basic/) — build your own tool or backend

1
docs/user/guide/quickstart.zh.md
View File

@@ -57,6 +57,7 @@ pnpm run dsh web
## 下一步
- [使用 Python 运行极简 agent](./python-sdk-minimal.md) — 无需 Web UI，即可使用固定的双工具组合
- [配置模型](./providers.md) — 接入 DeepSeek 之外的提供方与自定义网关
- [配置文件](./config.md) — 了解 `cordis.yml` 的格式
- [开发插件](../develop/basic/) — 编写自己的工具或后端