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

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

Что такое agent harness

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

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

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

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

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

На официальной странице релизов на момент проверки указаны v0.1.7-rc.2, около 236 тысяч звёзд и 28,3 тысячи форков репозитория. Релизы остаются предварительными и выходят часто. Публикация в npm отстаёт от GitHub: тег latest указывает на 0.1.5-rc.3, а ветка 0.1.7 раздаётся через теги next и alpha, поэтому для воспроизводимой установки версию стоит фиксировать явно.

Перед обновлением читайте примечания ко всем пропущенным версиям. В ветке 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 получили несовместимые изменения. Адаптер DeepSeek теперь работает только по Messages protocol: если вы вручную настраивали старый официальный base URL или endpoint Chat Completions, уберите переопределение или смените его на https://api.deepseek.com/anthropic.

Поддерживаемые исторические сессии мигрируют в актуальный формат журнала с сохранением оригиналов; в ветке 0.1.7 это V4. Пользовательские обработчики журналов нужно адаптировать, а обновлённые сессии нельзя читать после отката на старую версию. В v0.1.6-alpha.2 зависимости плагинов переведены на разрешение во время выполнения с поддержкой runtime-выгрузки: авторам плагинов нужно проверить логику загрузки и выгрузки.

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

Desktop-приложение для Windows и macOS

24 сентября 2026 года DeepSeek выпустил официальное desktop-приложение Harness. Это Electron-оболочка вокруг полного Web UI: dsh, Node.js и pnpm встроены в установщик, поэтому для запуска достаточно скачать пакет и открыть приложение — без терминала, установки Node.js и отдельного браузера. По документации в репозитории, оболочка и runtime всегда выпускаются одной общей версией, а обновления устанавливаются как единый подписанный пакет.

Доступные сборки (проверено 25 сентября 2026 года):

В репозитории заявлена и сборочная цель macOS x64 (Intel); Linux desktop-версией не поддерживается.

При первом запуске приложение показывает короткий онбординг: знакомит с доступной квотой и помогает выбрать сценарий использования и детализацию отображения работы агента; прерванный онбординг можно продолжить. Рабочая директория по умолчанию и пустая сессия создаются автоматически.

Что важно знать о поведении приложения:

• закрытие окна не останавливает задачи: агент продолжает работу в фоне, окно возвращается через область уведомлений в Windows или Dock в macOS;
• при выходе с активными задачами или включёнными напоминаниями приложение предупреждает о последствиях;
• Office-задачи используют встроенные runtime и библиотеки, включая LibreOffice и Python-пакеты для документов;
• поддерживается вход в аккаунт DeepSeek с квотой: задачи за счёт аккаунта и за счёт API-ключа разведены по отдельным модельным входам.

Отложенные задачи и напоминания

Начиная с v0.1.7-rc.2 в Web UI и desktop-приложении можно включить отложенные задачи: агент создаёт напоминания, хранит историю запусков и восстанавливает расписание после перезапуска; минимальный интервал повтора — одна минута. По умолчанию функция выключена. Подробности — в официальном руководстве по напоминаниям.

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

Если устанавливать Node.js не хочется, начните с desktop-приложения из предыдущего раздела. Для запуска Web UI нужны Node.js (^22.19.0 или ≥24) и API-ключ выбранной модели. Запустите Web UI способом, указанным в корневом README проекта. Для npm launcher используется:

npx @deepseek-ai/dsh web

Команда без явной версии ставит пакет из npm-тега latest, который на 25 сентября 2026 года указывает на 0.1.5-rc.3. Актуальная линейка 0.1.7 распространяется через тег next:

npx @deepseek-ai/dsh@next web

По умолчанию Web UI поднимается на http://127.0.0.1:3080, а напечатанный командой URL содержит одноразовый token, который браузер обменивает на подписанную сессионную cookie. Откройте URL, напечатанный командой. Не подставляйте адрес вручную, если launcher сообщил другой порт или путь, и не передавайте ссылку с token третьим лицам.

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

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

Новые сессии по умолчанию используют DeepSeek-V4.1-Flash (deepseek-flash), если в конфигурации явно не задана другая модель. Изменения модели применяются со следующего запроса без перезапуска сервера. Ключ доступен интерфейсу только для записи: после сохранения 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 и основной агентный цикл. В desktop-приложении первый пункт заменяется простым наблюдением: окно открылось, а онбординг завершён.

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: openai-completions, openai-responses или anthropic-messages;
• credential;
• минимум одну модель.

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

Model discovery (кнопка Fetch available models) читает распространённые форматы листинга: GET /models для OpenAI-compatible endpoint, объект models и нативный список моделей Anthropic. Если 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

Для reasoning-моделей за gateway уровни рассуждения объявляются параметром reasoningEfforts, а для DeepSeek-моделей, которые рассуждают по умолчанию, используется compat.thinkingFormat: deepseek; обе настройки задаются в $DSH_HOME/settings.yaml. На собственном маршруте DeepSeek уровни off, low, high и max уже встроены, а уровень по умолчанию задаёт llm-deepseek.reasoningEffort.

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

Модель 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 декларируют возможности маршрута, но не проверяют сервер автоматически. В v0.1.6-alpha.2 исправлена ошибка, из-за которой vision-модели pi-ai распознавались как text-only; тип входа такой модели можно скорректировать вручную.

Для собственного маршрута DeepSeek ручная настройка больше не нужна. Начиная с серии 0.1.5 адаптер DeepSeek поддерживает DeepSeek-V4.1-Flash (deepseek-flash) с текстом и изображениями, а в v0.1.6-alpha.1 маршрут по умолчанию переведён на Messages protocol с повторным использованием загруженных изображений через Files API. Официальная документация DeepSeek API на 25 сентября 2026 года перечисляет deepseek-flash (DeepSeek-V4.1-Flash, с нативным пониманием изображений) и deepseek-v4-pro. Прежние идентификаторы deepseek-v4-flash и deepseek-v4-flash-vision-exp ещё принимаются, но сами модели выведены из эксплуатации: их запросы обслуживает DeepSeek-V4.1-Flash по цене Flash. В v0.1.6-alpha.2 обе устаревшие модели удалены из списка моделей Harness по умолчанию.

Дополнительный контекст: 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. Начиная с v0.1.6-alpha.1 headless-профиль умеет принимать задачу из стандартного ввода, продолжать существующую сессию флагом --session-id и выводить события выполнения построчным JSON через --json.

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, macOS arm64 (macOS 14+), Windows x64 и macOS x64; wheel для Intel-Mac добавлен в серии 0.1.5. Обычный запуск 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 или pwsh на Windows. Начиная с серии 0.1.5 файловый редактор str_replace_editor в него по умолчанию не входит и подключается явным patch-файлом; пример приведён в руководстве по Python SDK. Профиль не включает Web UI, managed credentials, telemetry, Web tools, subagents, автоматическое обнаружение локальных инструкций и context compaction.

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

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

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

Профиль (profile) задаёт набор компонентов, из которых собирается конкретный режим Harness. Состав профиля определяет доступные инструменты, провайдер, хранение сессий и дополнительные возможности. С v0.1.6-alpha.2 профиль можно запустить короткой командой dsh <profile>, а плагинами управлять через страницу Plugins в Web UI: установка, настройка, включение и отключение без перезапуска.

Для 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 не гарантируют изоляцию.

Конкретный прецедент — CVE-2026-82533: в версиях до 0.1.1-rc.2 включительно локальный интерфейс Harness принимал вызовы без аутентификации, и агент мог одной shell-командой перевести собственную сессию в danger-full-access, отключив sandbox и approvals. Исправление вошло в 0.1.2-alpha.1: локальный интерфейс потребовал обязательную аутентификацию по одноразовому token, а на npm первой исправленной сборкой стала 0.1.2-alpha.2. Не используйте сборки старше ветки 0.1.2 и проверяйте версию, которую поставляют сторонние wrapper-сборки.

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

• публичный WebFetch включён по умолчанию, и публичные запросы не требуют отдельного approval на каждый вызов. Штатный провайдер dsh-web-fetch-http ограничивает длину URL, размер ответа, таймауты и редиректы, но, по результатам независимого разбора, не ограничивает адрес назначения: модель может обратиться к loopback- и LAN-адресам. Учитывайте это при изоляции;
• release notes указывают web_fetch как возможность по умолчанию для Python SDK, Headless, ACP и custom profiles, но профиль sdk-minimal в документации отдельно описан без Web tools. Проверяйте итоговый состав конкретного профиля;
• официальный DeepSeek adapter может передавать имена и версии включённых плагинов; это отключается настройкой;
• с v0.1.6-alpha.1 при работе через официальный API DeepSeek адаптер может отправлять события сессии вместе с запросами: функция экспериментальная, по умолчанию включена и отключается в конфигурации;
• для сетевого доступа к Web UI используется одноразовый token из URL запуска;
• вокруг Harness уже появились неофициальные desktop-обёртки, их runtime и установщики не проверены DeepSeek: приложение стоит ставить только с официального домена download.deepseek.com.

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

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

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

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

• breaking changes продолжают появляться в alpha-релизах;
• plugin API, persistence API и форматы session log активно развиваются: в ветке 0.1.6 зависимости плагинов переведены на runtime-разрешение, а Client Sessions получили поддержку нескольких экземпляров с изменением API;
• в ветке 0.1.7 журнал сессий обновлён до формата V4 с пакетным инструментом миграции для разработчиков; обновлённые сессии нельзя читать после downgrade;
• возможности custom vision-моделей объявляются в YAML и не проверяются автоматически;
• экспериментальные Browser Use, Computer Use, Auto review, Agent Team и голосовой ввод нестабильны и требуют явного включения;
• при работе через официальный API DeepSeek события сессии по умолчанию могут отправляться вместе с запросами; если это критично, отключите настройку заранее;
• Windows и macOS x64 runtime появились недавно, поэтому критичные сценарии стоит проверять отдельно;
• desktop-приложение — первая публичная сборка: Linux не поддерживается, а страница загрузки на официальном сайте ещё не оформлена;
• результат зависит от конкретного профиля, инструментов, лимитов, модели и числа agent/tool cycles.

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

Запуск без терминала

Задача: попробовать Harness без установки Node.js и командной строки.

Скачайте desktop-установщик для своей платформы с официального домена download.deepseek.com, установите и запустите приложение. Пройдите онбординг, войдите в аккаунт DeepSeek или добавьте API-ключ в настройках моделей и отправьте первую read-only задачу из раздела «Как проверить установку». Наблюдаемый результат — агент содержательно описывает выбранную рабочую директорию, а действия, требующие подтверждения, показывают запрос разрешения. Сценарий не подходит для Linux: desktop-сборки для него нет.

Локальный 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
• Документация desktop-приложения
• Настройка providers
• Напоминания и отложенные задачи
• Руководство по Python SDK
• Официальный репозиторий
• Примечания к релизам
• Официальное предупреждение о безопасности (SAFETY.md)
• DeepSeek API Docs

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

DeepSeek API и SDK

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

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