Вызов Python SDK DeepSeek Harness

Веб-интерфейс предназначен для того, чтобы на него смотрели люди, но если вам нужно вызвать его из программыdshВ этот момент нужен SDK.

В этой главе рассматривается Python SDK: как его установить, как запускать встроенные примеры в репозитории и как вызывать его в собственных программах.


Какую проблему решает Python SDK?

SDK превращает dsh в вызов в одну строку внутри вашей программы, а не в страницу в браузере.

DeepSeekHarnessЭто основной класс Python SDK, использующий менеджер контекста для управления жизненным циклом среды выполнения.

Вход в блок with лениво запускает встроенную среду выполнения; выход автоматически освобождает её, а между ними run можно вызывать многократно.

Подходящие сценарии: пакетная обработка задач, интеграция dsh в собственный продукт и управление Агентами в тестах.

После установки SDK среда выполнения не требует наличия Node.js в системе — процесс Python несёт собственную копию.


Предварительные требования

У SDK есть явные системные требования — сначала проверьте их.

ЗависимостьТребование
Python3.10 или выше
GitУстановлено
Операционная системаLinux x64, Linux arm64 или macOS 14+ arm64
Конечная точка APIКонечная точка API, совместимая с DeepSeek, и учётные данные
Рабочее пространствоИзолированное рабочее пространство, которое агент может изменять

Установка SDK

Клонируйте репозиторий, чтобы получить примеры для запуска, создайте виртуальное окружение, затем установите SDK и встроенный рантайм той же версии.

$ 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

Виртуальное окружение изолирует SDK от других пакетов Python в системе — это официально рекомендуемый подход.

После установки рантайм не требует наличия Node.js в системе.


Запустите встроенные примеры из репозитория

Репозиторий включает пример minimal.py; его запуск эквивалентен проверке всего конвейера SDK.

Сначала задайте учётные данные в окружении.

$ export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# export DSH_MODEL=deepseek-v4-flash
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

Если модель предоставляется не через стандартную конечную точку DeepSeek, а через OpenAI-совместимый прокси, вам также нужно задать DEEPSEEK_BASE_URL.

Затем запустите задачу для изолированного рабочего пространства и каталога сессии.

$ python examples/jsonrpc-agent/minimal.py \
  --workspace /absolute/path/to/workspace \
  --session-root /absolute/path/to/sessions \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

Скрипт выведет окончательный ответ ассистента.

Каталог сессии получает журналы JSONL, которые включают собранные запросы к модели и вызовы инструментов.


Использование SDK в собственной программе

Встроенный пример в репозитории на самом деле представляет собой лёгкую обёртку вокруг вызова SDK ниже; суть — всего два шага.

Пример

# Путь к файлу: эквивалентная запись examples/jsonrpc-agent/minimal.py
from pathlib import Path

from deepseek_harness import DeepSeekHarness

# Абсолютный путь к примеру объединённого файла конфигурации (.cordis.yml описывает, какие плагины запускать)
config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()

# Рабочее пространство, доступное агенту, должно быть абсолютным путём.
workspace = Path("/absolute/path/to/workspace").resolve()

Каталог для сохранения журналов сессии и состояния, должен быть абсолютным путём
sessions = Path("/absolute/path/to/sessions").resolve()

# Менеджер контекста: лениво запускает встроенную среду выполнения при входе и автоматически освобождает её при выходе.
with DeepSeekHarness(
    provider="deepseek-official",   # Использовать официальный провайдер DeepSeek
    model="deepseek-v4-flash",      # Имя модели, а также значение по умолчанию в SDK
    max_tokens=49_152,              # Максимальное количество токенов на один ответ
    cwd=str(workspace),             # Установить workspace как рабочую директорию агента
    session_root=str(sessions),     # Куда записывать журналы сессий
    cordis=str(config),             # С какой конфигурации пакета начинать запуск
) as harness:
    # Отправить задачу; session_id используется для идентификации этого постоянного диалога
    result = harness.run(
        "Изучите репозиторий example-demo и исправьте падающие тесты.",
        session_id="example-001",
    )

# Вывести финальный ответ ассистента
print(result.final_response)

DeepSeekHarness лениво запускает встроенную среду выполнения и продолжает использовать её повторно до выхода из контекстного менеджера.

Один и тот же harness может вызывать run несколько раз внутри блока with, а среда выполнения запускается только один раз.


Повторно используйте идентификатор сеанса: сохраняйте процессы Bash

Это наиболее легко упускаемое из виду и наиболее полезное правило SDK.

Повторное использование одного и того же harness и session id сохраняет процессы Bash, принадлежащие этой сессии.

Включая её рабочий каталог, экспортированные переменные и функции оболочки — всё это переносится в следующий вызов.

Пример

# Первый вызов: экспортируйте переменную в example-workspace
result = harness.run(
    "Выполните `cd /repo && export EXAMPLE_MODE=dev` и подтвердите.",
    session_id="example-session",
)
print(result.final_response)

# Второй вызов: повторно используйте тот же идентификатор сессии, экспортированная переменная всё ещё там
result = harness.run(
    "Выведите значение EXAMPLE_MODE.",
    session_id="example-session",
)
print(result.final_response)

Независимые задачи должны использовать новый идентификатор сессии; повторно используйте исходный идентификатор только тогда, когда следующему вызову нужно продолжить тот же постоянный диалог.


Обзор примеров комбинаций

Комбинация, стоящая за minimal.py, — это намеренно минимальная конфигурация; давайте пройдёмся по каждому пункту, чтобы увидеть, что он делает.

СвойствоЗначение
Системный промптDSH_SYSTEM_PROMPT;未SettingswhenUsage Вы — полезный ассистент-программист.
Модель, используемая в minimal.py--model, затем DSH_MODEL и, наконец, deepseek-v4-flash
Инструменты, ориентированные на модельТолько постоянные bash и str_replace_editor
Тайм-аут Bash300 секунд
Лимит вывода редактора16,000 символов
Сжатие контекстаЗакрыто
файловая системаГолый локальный бэкенд; редактор использует абсолютные пути и может получить доступ к любому пути, видимому процессу среды выполнения.
Сохранение диалогаНесжатый JSONL в DSH_SESSION_ROOT

Эта комбинация пропускает такие плагины, как идентичность обвязки, текст промпта рабочей области, навыки, одноразовый Bash, инструменты задач и сжатие контекста.

Общий поток вызовов выглядит следующим образом.

Python SDK 调用流程图


Граница danger-full-access

В этом примере комбинации используется предустановка разрешений danger-full-access, и вы должны ясно понимать её границы.

danger-full-access можно запускать только в одноразовой рабочей копии или контейнере.

Bash и редактор могут изменять любой путь, доступный процессу среды выполнения; песочница не выступает в роли страховочной сетки.

Постоянный бэкенд PTY требует среды терминала POSIX, поэтому эта комбинация не поддерживает агентов Windows.

Иными словами, прежде чем использовать его для запуска реальных проектов, сначала убедитесь, что вас не расстроит, если это окружение сломается.


Итоговая самопроверка

Краткое резюме в одном предложении: Python SDK оборачивает среду выполнения с помощью контекстного менеджера DeepSeekHarness и отправляет задачи через run(prompt, session_id).

Проверьте своё понимание с помощью трёх быстрых вопросов.

  1. Что сохраняется при повторном использовании одного и того же session id?
  2. В каких ситуациях следует использовать новый session id?
  3. Какие инструменты minimal.py включает для модели по умолчанию?

Эталонный ответ: процесс Bash для этой сессии сохраняется, включая рабочий каталог, экспортированные переменные и функции оболочки.

Используйте новый id для независимых задач; повторно используйте его только тогда, когда нужно продолжить тот же постоянный диалог.

Сохранять только два инструмента: bash и str_replace_editor

Другие расширения