DeepSeek Harness (dsh) — практическое руководство по официальному агентному фреймворку DeepSeek

DeepSeek Harness (dsh) — официальный агентный фреймворк DeepSeek с публичным репозиторием. Он превращает языковую модель в агента, который работает с файлами и терминалом, вызывает инструменты, ведёт план, сохраняет сессии и делегирует задачи субагентам. Harness можно запускать через Web UI, в режиме без браузерного интерфейса и из Python-приложения. Материал пригодится, если вы хотите безопасно запустить агента, подключить свою модель или встроить его в Python-процесс.

Что такое agent harness

Сама LLM получает текст и генерирует текст. Чтобы модель могла открыть репозиторий, изменить файл, запустить тест, вызвать инструмент, запросить разрешение и продолжить работу после результата команды, вокруг неё нужен исполнительный слой — agent harness.

Harness определяет:

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

Качество агента зависит от всей связки: модели, системного контекста, инструментов, разрешений, профиля и цикла выполнения. Поэтому при сравнении моделей полезно сохранять одинаковые workspace, задачи и настройки Harness.

Публичные релизы и совместимость

На официальной странице релизов на момент проверки указаны v0.1.5-alpha.1, 216 тысяч звёзд и 25,5 тысячи форков репозитория. Релизы остаются предварительными и выходят часто.

Перед обновлением читайте примечания ко всем пропущенным версиям. В ветке 0.1.2 старый ApiProxy удалён в пользу Remote gateway, а Code Mode переименован в PTC mode. В v0.1.3-alpha.1 изменились API хранения сессий и формат V2. В v0.1.5-alpha.1 журнал переведён на формат V3, а Agent API и Inbox API получили несовместимые изменения.

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

Что умеет текущий DeepSeek Harness

Запуск через Web UI

Для первого запуска нужен Node.js и API-ключ выбранной модели. Запустите Web UI способом, указанным в корневом README проекта. Для npm launcher используется:

npx @deepseek-ai/dsh web

Откройте URL, напечатанный командой. Не подставляйте адрес вручную, если launcher сообщил другой порт или путь.

Подключение модели

1. Откройте Settings → Models.
2. В карточке DeepSeek вставьте API key.
3. Сохраните настройки.
4. Выберите модель в composer.

Изменения модели применяются со следующего запроса без перезапуска сервера. Ключ доступен интерфейсу только для записи: после сохранения Web UI получает сокращённое описание, а не исходный секрет. Harness хранит credential в $DSH_HOME/.credentials.yaml, а основные настройки содержат ссылку на него.

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

Выбор workspace

Нажмите Choose workspace, добавьте нужную директорию и выберите её. Пока workspace не выбран, composer остаётся заблокированным.

Для первого теста используйте отдельный clone репозитория или временную папку. Не выбирайте домашний каталог или директорию с секретами.

Безопасная первая задача:

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

После read-only проверки можно перейти к минимальному изменению:

Найди один простой failing test, исправь его минимальным изменением и запусти только относящийся к нему тест. Перед действиями вне workspace запроси разрешение.

Как проверить установку

Проверьте пять наблюдаемых результатов:

1. URL, напечатанный командой запуска, открывается в браузере.
2. В Settings → Models модель отображается как настроенная.
3. Workspace выбран, а composer доступен.
4. Агент способен прочитать файл и содержательно его описать.
5. Операция, требующая approval при активной политике разрешений, показывает запрос на подтверждение.

Если все пункты выполняются, работают launcher, provider, workspace и основной агентный цикл.

OpenAI, Anthropic и собственные точки доступа

DeepSeek Harness не ограничен моделями DeepSeek.

В Settings → Models → Add provider можно добавить catalog provider, например OpenAI или Anthropic. Для корпоративного gateway, self-hosted сервера или отсутствующего в каталоге провайдера выберите Add a custom provider и укажите:

• постоянный lowercase Provider ID;
• base URL;
• API protocol;
• credential;
• минимум одну модель.

Provider ID используется в запросах, сохранённых сессиях, defaults и ссылках на credentials. Для переименования документация рекомендует создать нового provider и удалить старого.

Model discovery для OpenAI-compatible endpoint вызывает GET /models. Если endpoint не поддерживает этот метод, модели добавляются вручную.

Некоторые gateways отличаются от API OpenAI формой запросов. Например, reasoning-модель может отправлять системный промпт с ролью developer, а лимит ответа передавать в поле max_completion_tokens. Если сервер ожидает другую форму, задайте совместимость в $DSH_HOME/settings.yaml:

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY # Имя переменной с ключом.
      api: openai-completions # Протокол API провайдера.
      baseURL: https://gateway.example/v1 # Базовый URL gateway.
      compat:
        supportsDeveloperRole: false # Не отправлять системный промпт как developer.
        maxTokensField: max_tokens # Использовать поле max_tokens вместо max_completion_tokens.
      models:
        - id: my-model

Модели с изображениями

Модель custom provider, добавленная вручную, по умолчанию считается text-only. Поддержку изображений нужно объявить в $DSH_HOME/settings.yaml:

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY # Переменная окружения с ключом.
      api: openai-completions # Совместимый протокол API.
      baseURL: https://gateway.example/v1 # Базовый URL сервера.
      models:
        - id: vision-preview
          input: [text, image] # Эта модель принимает текст и изображения.

Если endpoint фактически не принимает изображения, provider отклонит запрос. Поля input и defaultInput декларируют возможности маршрута, но не проверяют сервер автоматически.

Официальная документация DeepSeek API на 8 сентября перечисляет модели deepseek-v4-flash, deepseek-v4-pro и экспериментальную vision-модель deepseek-v4-flash-vision-exp. При этом документация Harness по провайдерам отдельно предупреждает, что нативный DeepSeek chat-completions route в Harness считается text-only и не может быть превращён в vision-route через настройку input. Для изображений используйте маршрут и конфигурацию, которые прямо поддерживают эту модель.

Дополнительный контекст: DeepSeek API и SDK и DeepSeek — линейка открытых моделей и API.

Запуск без Web UI (headless)

Для задачи без браузерного интерфейса используйте профиль headless:

dsh --profile headless "run the tests and summarize the failures"

Без глобальной установки:

npx @deepseek-ai/dsh --profile headless "inspect the repository and summarize the test failures"

Во время выполнения прогресс выводится в stderr, а stdout сохраняется для финального ответа. Это упрощает интеграцию со скриптами и CI.

Headless mode подходит для:

• анализа результатов тестов;
• периодической проверки репозитория;
• подготовки отчётов;
• автоматизированных задач в изолированном workspace.

Python SDK

Официальный пакет устанавливается командой:

python -m pip install deepseek-harness-sdk

Нужны Python 3.10+, Git, совместимая точка доступа DeepSeek и credential, а также изолированные workspace и Harness home. Опубликованы runtime wheels для Linux x64/arm64, Windows x64, macOS arm64 и, начиная с v0.1.3-alpha.1, macOS x64. Обычный запуск SDK не требует системной установки Node.js.

Актуальная схема встраивания:

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',
) as harness:
    result = harness.run(
        'Inspect the repository and fix the failing tests.',
        session_id='example-001',
    )

print(result.final_response)

SDK лениво запускает bundled-процесс dsh --profile sdk-minimal и переиспользует его до выхода из context manager. DEEPSEEK_API_KEY и при необходимости DEEPSEEK_BASE_URL можно передать через переменные окружения.

Профиль sdk-minimal включает persistent Bash на Linux/macOS или PowerShell на Windows и файловый редактор. Он не включает Web UI, managed credentials, telemetry, Web tools, subagents, автоматическое обнаружение локальных инструкций и context compaction.

Используйте новый session_id для независимой задачи. Повторное использование Harness home и идентификатора продолжает ту же durable conversation и связанные с ней ресурсы.

Журналы минимального профиля хранятся как несжатые JSONL-файлы в каталоге sessions/. После обновления до формата V3 старые поддерживаемые журналы мигрируют в новые файлы с сохранением оригиналов. Обратное чтение обновлённой сессии старой версией не поддерживается.

Профили и плагины

Профиль (profile) задаёт набор компонентов, из которых собирается конкретный режим Harness. Состав профиля определяет доступные инструменты, провайдер, хранение сессий и дополнительные возможности.

Для sdk-minimal документация показывает отдельный файл исправлений конфигурации $DSH_HOME/profiles/sdk-minimal/cordis.patch.yml. Из Python можно передавать patch-файлы только для конкретного запуска.

Пример подготовки home и установки plugin bundle:

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

Первая команда инициализирует поставляемый standalone-профиль. Вторая передаёт управление пакетами в pnpm и сохраняет пакет, который экспортирует слой dsh.bundle. pnpm нужен для этой операции управления, но не для запуска уже установленного SDK.

В ветках 0.1.3–0.1.5 менялись Session persistence API, Agent API, Inbox API и форматы журналов. Plugin, рассчитанный на старую версию, может потребовать адаптации.

Безопасность

Agent harness читает файлы, запускает команды и может обрабатывать внешний контент. Текст внутри репозитория, документации, issue или веб-страницы может содержать indirect prompt injection — инструкции, которые пытаются заставить агента выполнить нежелательное действие.

Официальное предупреждение DeepSeek сообщает, что Harness не проходил независимого security audit, а sandboxing, approvals и permission controls не гарантируют изоляцию.

Нужно учитывать текущие defaults:

• публичный WebFetch включён по умолчанию и использует встроенную SSRF-защиту; публичные запросы не требуют отдельного approval на каждый вызов;
• release notes указывают web_fetch как возможность по умолчанию для Python SDK, Headless, ACP и custom profiles, но профиль sdk-minimal в документации отдельно описан без Web tools. Проверяйте итоговый состав конкретного профиля;
• официальный DeepSeek adapter может передавать имена и версии включённых плагинов; это отключается настройкой;
• incremental Session-log upload доступен как опция и по умолчанию выключен;
• для сетевого доступа к Web UI используется одноразовый token из URL запуска.

Минимальные правила безопасной работы

• Используйте отдельный workspace и Harness home.
• Начинайте работу с незнакомым репозиторием в read-only режиме.
• Не запускайте danger-full-access на основной машине без изоляции.
• Сохраняйте approvals для опасных операций.
• Не размещайте production secrets в доступной агенту директории.
• Проверяйте источник и код каждого plugin.
• Для CI используйте контейнер и минимальный набор credentials.
• Считайте файлы, веб-страницы, issues и документацию недоверенными данными.
• Перед обновлением проверяйте release notes и совместимость формата сессий.

Ограничения developer preview

На 8 сентября 2026 года нужно учитывать следующее:

• breaking changes продолжают появляться в alpha-релизах;
• plugin API, persistence API и форматы session log активно развиваются;
• обновлённые сессии V3 нельзя читать после downgrade;
• нативный DeepSeek route в Harness остаётся text-only, хотя официальный API уже перечисляет отдельную экспериментальную vision-модель;
• возможности custom vision-моделей объявляются в YAML и не проверяются автоматически;
• Windows и macOS x64 runtime появились недавно, поэтому критичные сценарии стоит проверять отдельно;
• результат зависит от конкретного профиля, инструментов, лимитов, модели и числа agent/tool cycles.

Полезные сценарии

Локальный coding-агент

Задача: изучить репозиторий, исправить локальную ошибку или выполнить рефакторинг.

Запустите Web UI, выберите отдельный workspace и начните с read-only анализа. Наблюдаемый результат — агент находит структуру проекта и команды тестирования; после разрешённого изменения соответствующий тест проходит. Сценарий не подходит для основной рабочей директории с секретами без дополнительной изоляции.

Сравнение нескольких моделей

Задача: сравнить модели при одинаковом наборе инструментов.

Добавьте DeepSeek, OpenAI, Anthropic или собственный gateway и выполняйте одинаковую задачу в отдельных сессиях. Сравнивайте финальный результат, число циклов, ошибки инструментов и расход токенов. Отдельные сессии нужны, чтобы история одной модели не влияла на другую.

Headless-анализ в CI

Задача: сгруппировать ошибки после тестов и подготовить отчёт.

Запускайте профиль headless в disposable checkout и передавайте ему логи. Успешный результат — финальный отчёт в stdout при прогрессе в stderr. Автоматическое исправление кода стоит включать только после проверки permission policy и изоляции.

Python-пайплайн

Задача: встроить агента в собственный сервис или обработчик событий.

Создайте отдельные workspace, dsh_home и session ID, вызовите DeepSeekHarness.run() и передайте final_response следующему этапу. Для параллельных независимых задач нельзя переиспользовать один session ID.

Собственная агентная сборка

Задача: оставить только необходимые инструменты или заменить части runtime.

Используйте profiles, patch-файлы и plugins. Результат проверяется через вывод конфигурации профиля и минимальную тестовую задачу. После обновления DSH отдельно проверяйте совместимость плагинов с актуальными API.

Чеклист перед реальной работой

Официальные точки входа

• Документация DeepSeek Harness
• Руководство по Web UI
• Настройка providers
• Руководство по Python SDK
• Официальный репозиторий
• Примечания к релизам
• DeepSeek API Docs

Следующий шаг

DeepSeek API и SDK

Связанные материалы

• Статья: Локальные модели в работе: Mac Studio, DAWalka и DeepSeek
• Блог: Сделали pimenov.ai agent-ready: что реально внедрили и зачем
• База знаний: OpenAI Codex — облачный coding-агент для параллельной разработки

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov