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

DeepSeek Harness (dsh) — официальный open-source agent harness от DeepSeek: программный слой, который превращает языковую модель в рабочего агента с файлами, терминалом, инструментами, планом, сессиями и субагентами. Проект уже можно запускать локально через Web UI, использовать в headless-режиме и встраивать в Python-приложения.

Что такое agent harness и зачем DeepSeek делает свой

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

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

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

Поэтому один и тот же model checkpoint в разных агентных средах может показывать заметно разное качество.

В случае DeepSeek это не только продуктовая идея. В официальной карточке DeepSeek-V4-Flash-0731 прямо указано, что Code Agent benchmarks для модели запускались в minimal mode DeepSeek Harness с max reasoning effort, temperature = 1.0 и top_p = 0.95.

Например, в этой конфигурации DeepSeek публикует для V4-Flash-0731:

Это важный контекст: опубликованный результат coding-модели уже зависит от связки модель + harness, а не только от весов модели.

Независимое исследование StateM, опубликованное 15 августа 2026 года, показывает тот же эффект с другой стороны. Авторы изменяли исполнительную систему вокруг моделей и сообщают, что DeepSeek-V4 Flash вырос на Terminal-Bench 2.1 с официальных 82.7 до 88.1% при стандартных таймаутах. Это не benchmark DeepSeek Harness и не прямое сравнение двух продуктов, но хороший пример того, насколько сильно организация агентного цикла влияет на итог.

Как появился DeepSeek Harness

Публично проект начал проявляться ещё до открытия исходников.

23 июня 2026 года South China Morning Post писал, что DeepSeek формирует отдельную Harness-команду для работы над агентным слоем вокруг базовых моделей. Команду возглавил Cui Tianyi, ранее работавший software engineer в Jane Street; в DeepSeek он пришёл в марте 2026 года.

31 июля Harness впервые оказался напрямую связан с публичными результатами V4-Flash-0731: DeepSeek указал его minimal mode в примечании к Code Agent benchmarks.

3 августа SCMP сообщил о наборе разработчиков open-source agent harness-проектов в закрытое тестирование. На тот момент даты публичного релиза ещё не было.

К середине августа официальный deepseek-ai/deepseek-harness стал публичным, а пакет @deepseek-ai/dsh можно запускать напрямую через npm.

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

Самый быстрый запуск через Web UI

Для первого знакомства нужен Node.js и API-ключ модели.

В терминале выполните:

npx @deepseek-ai/dsh web

После запуска откройте:

http://127.0.0.1:3080

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

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

Ключ не возвращается обратно в Web UI в открытом виде. Harness хранит его в $DSH_HOME/.credentials.yaml, а в основных settings остаётся ссылка на credential.

Изменение модели начинает действовать со следующего запроса. Уже начатая сессия после первого запроса сохраняет модель, записанную в собственном session log.

Выбор workspace

После первого запуска нажмите Choose workspace и укажите папку, с которой разрешено работать агенту.

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

Пример безопасной первой задачи:

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

Затем можно перейти к изменению файла:

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

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

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

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

Если все пять пунктов выполняются, базовая связка launcher → model provider → workspace → agent loop работает.

Подключение OpenAI, Anthropic и своих endpoints

DeepSeek Harness не привязан только к моделям DeepSeek.

В Settings → Models → Add provider можно добавить поддерживаемого catalog provider. Документация отдельно упоминает Anthropic и OpenAI.

Для корпоративного gateway, self-hosted сервера или провайдера, которого нет в каталоге, используйте Add a custom provider. Нужно задать:

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

Provider ID лучше выбирать сразу правильно. Он используется в запросах, сохранённых сессиях, defaults и ссылках на credentials; простое переименование после этого не предусмотрено.

Для OpenAI-compatible endpoint Harness может попробовать получить модели через GET /models. Если endpoint такого метода не предоставляет, список моделей вводится вручную.

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

Для custom provider модель, введённая вручную, по умолчанию считается text-only. Если endpoint поддерживает изображения, это надо явно указать в $DSH_HOME/settings.yaml:

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: vision-preview
          input: [text, image]

Это декларация возможностей, а не автоматическая проверка endpoint. Если указать image, а сервер на самом деле не принимает изображения, запрос будет отклонён самим provider.

Нативный DeepSeek chat-completions route в текущей документации Harness считается text-only.

Headless mode для скриптов и автоматизации

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

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

Он создаёт свежую persisted session, выполняет задачу, печатает финальный ответ и завершается.

Если запускаете пакет без глобальной установки, тот же launcher можно вызвать через npx:

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

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

• CI-задач;
• периодического анализа репозитория;
• автоматической проверки тестов;
• сборки отчётов;
• собственного pipeline вокруг агента.

Python SDK

Официальный Python-пакет называется:

pip install deepseek-harness-sdk

В текущей документации указаны Python 3.10+, Git, Linux x64/arm64 или macOS 14+ на Apple Silicon и отдельный workspace, который агенту разрешено изменять. Bundled runtime не требует системной установки Node.js.

Минимальная схема использования:

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/sessions").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 и тот же session_id, сохраняется не только разговор, но и session-owned Bash process: рабочая директория shell, экспортированные переменные и shell functions продолжают жить между вызовами.

Это удобно для длинных workflow, но означает, что session ID становится частью состояния задачи. Для независимой работы создавайте новый ID.

Почему архитектура Cordis здесь важнее Web UI

Самая интересная часть DeepSeek Harness находится под интерфейсом.

Проект построен на Cordis и придерживается принципа everything is a plugin. Model adapter, tool registry, session log и сам agent loop не являются неприкосновенным монолитным ядром — они подключаются через общую plugin-систему.

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

Плагинами и композициями можно менять или добавлять:

• model providers;
• tools;
• shell и terminal backends;
• filesystem и sandbox;
• background jobs;
• context injection;
• interception запросов, tool calls и turns;
• UI-интеграции;
• session forks;
• subagents.

Для разных композиций используются profiles. В поставке есть как минимум web и headless.

Посмотреть итоговую конфигурацию профиля можно без запуска:

dsh --profile web --dump-config

А управлять plugin dependencies профиля — через:

dsh plugin --profile web <pnpm args>

Именно поэтому DeepSeek Harness правильнее рассматривать как агентный runtime / framework, а Web UI — как одну из его сборок.

Как устроены сессии

Session log в DSH append-only и является источником контекста для последующей работы. В нём сохраняются durable events, из которых затем собирается model-visible состояние.

Для практического использования это означает две вещи:

1. Сессия — не просто история сообщений в интерфейсе, а часть runtime state.
2. Если следующая задача должна быть независимой, создайте новую сессию, а не продолжайте старую автоматически.

В минимальном Python-примере лог хранится как обычный JSONL без сжатия. Это удобно для отладки и анализа agent trajectories.

Безопасность: главный блок, который нельзя пропускать

Agent harness получает гораздо больше возможностей, чем обычный чат. Он читает файлы, выполняет команды и может действовать на основании текста, который сам только что обнаружил в репозитории или документе.

В официальном Python-примере минимальная композиция использует режим danger-full-access. Документация прямо рекомендует запускать её только в disposable checkout или контейнере: Bash и editor могут менять любой путь, который доступен runtime process.

17 августа 2026 года вышло отдельное исследование Security Assessment of DeepSeek Harness with A.I.G, посвящённое indirect prompt injection в DSH.

Авторы провели 14 560 контролируемых запусков по 16 каналам поступления внешнего контента, двум типам носителей и 35 целям атаки. В их экспериментальной конфигурации самые высокие наблюдавшиеся показатели успешности составили:

• 25.5% по rule-based judge для hidden-Unicode attack через файл;
• 17.0% по semantic judge для fake-completion attack в текстовом режиме;
• 16.0% по rule-based judge для атаки через skills channel в файловом режиме.

Эти проценты относятся к конкретному исследовательскому стенду и не означают, что «каждый четвёртый запрос DSH взламывается». Работа показывает более практичную вещь: контент, который читает агент, нельзя автоматически считать инструкцией, которой разрешено управлять чувствительными действиями.

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

• Используйте отдельный workspace для агента.
• Для незнакомых репозиториев начинайте с read-only анализа.
• Не давайте danger-full-access обычной рабочей машине без необходимости.
• Сохраняйте approval перед опасными командами.
• Не держите production secrets в workspace, который агент свободно читает.
• Не ставьте случайный plugin только потому, что он доступен через pnpm.
• Для CI используйте контейнер и минимальный набор credentials.
• Файлы, веб-страницы, issues и документацию из внешних источников считайте untrusted input.

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

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

• DeepSeek прямо предупреждает о возможных breaking compatibility changes.
• Интерфейс, plugin API и структура конфигурации ещё активно развиваются.
• Нативный DeepSeek chat route в текущей конфигурации text-only.
• Возможности vision для вручную добавленных моделей надо объявлять в YAML.
• Минимальная Python-композиция с persistent PTY не поддерживает Windows agents; это ограничение конкретного примера/runtime composition, а не утверждение обо всех будущих режимах DSH.
• Официальные benchmark-цифры V4 показывают работу модели в специально заданном minimal mode и не являются обещанием такого же результата на вашем репозитории.
• Стоимость реальной агентной работы зависит от выбранного provider, модели, длины контекста и числа tool/agent cycles.

Практические сценарии

Локальный coding-агент для репозитория

Запустите Web UI в корне проекта, выберите workspace и поручите агенту исследование, исправление теста или рефакторинг. Это самый простой сценарий для знакомства.

Один harness, несколько моделей

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

Headless-анализ в CI

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

Python-пайплайн

SDK подходит, если Harness должен быть не пользовательским приложением, а частью собственного сервиса: например, запускаться по событию, работать с заранее подготовленным workspace и возвращать структурированный результат в следующий этап pipeline.

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

Cordis-профили и plugins позволяют собрать специализированный runtime: оставить только нужные tools, заменить provider, добавить собственные interception hooks и изменить политику выполнения без переписывания всего Harness.

Быстрый чеклист перед реальной работой

Что читать вне GitHub

Если интересует контекст проекта, а не только исходный код и README, сейчас наиболее полезны эти источники:

• DeepSeek-V4-Flash-0731 — официальный model card на Hugging Face — показывает, что Code Agent benchmarks DeepSeek запускались через minimal mode Harness и фиксирует параметры оценки.
• DeepSeek Harness Python SDK — PyPI — официальный пакет DeepSeek; на 19 августа актуальный pre-release 0.1.0rc7, опубликованный 18 августа.
• Сторонний пакет deepseek-harness — PyPI — существовал с мая 2026 года и не является официальным SDK DeepSeek; полезно знать, чтобы не установить пакет по ошибке.
• SCMP, 3 августа 2026: DeepSeek beefs up agentic AI with harness tests — контекст закрытого тестирования и команды Cui Tianyi.
• SCMP, 23 июня 2026: DeepSeek’s Harness team races to recruit talent — ранняя история отдельной Harness-команды.
• Security Assessment of DeepSeek Harness with A.I.G — независимое исследование indirect prompt injection на 14 560 запусках.
• StateM: Harness Scaling — независимая работа о том, насколько сильно изменение harness может влиять на результат той же модели.
• DeepSeek Harness: Everything We Know Before the Official Release — полезный снимок состояния на 1 августа и предупреждение об одноимённых сторонних проектах. Часть информации о «ещё не выпущенном» Harness уже устарела после публичного релиза, поэтому используйте материал только как исторический источник.

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

• DeepSeek Harness — официальный репозиторий
• DeepSeek-V4-Flash-0731 — Hugging Face
• DeepSeek API Platform

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

Лимиты Codex: почему OpenAI ходит по тонкому льду и как выживать прямо сейчас

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

• Статья: Семь перерождений pimenov.ai: от ночного эксперимента с OpenClaw до рабочей системы на Codex
• Блог: Сделали pimenov.ai agent-ready: что реально внедрили и зачем
• База знаний: OpenAI Codex — облачный coding-агент для параллельной разработки

DeepSeek Harness полезно смотреть не только как ещё один coding-agent интерфейс, а как открытую лабораторию, где хорошо видно, из каких частей сегодня собирается рабочий ИИ-агент. Это особенно интересно тем, кто строит собственные агентные процессы и хочет меньше зависеть от одной модели или одной оболочки.

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