Большинство инструментов для агентов поставляются как готовые приложения: в них уже встроен цикл мышления, фиксированный набор действий и собственные правила работы с памятью. Пользователь может выбрать модель и подключить несколько инструментов, но не поменять само устройство агента. DeepSeek Harness идёт другим путём: цикл агента, доступ к моделям, инструменты и хранение собираются из отдельных плагинов, которые можно менять, отключать или заменять.
Под капотом — Cordis, плагиновый фреймворк, где каждая часть продукта регистрирует сервисы, события и обратимые эффекты в общем контексте. Это позволяет собрать собственную конфигурацию агента: лёгкий headless-режим для скриптов, полноценный Web-интерфейс для разработчика или собственную поверхность на основе SDK.
Важно: DeepSeek Harness сейчас находится в стадии раннего предварительного доступа для разработчиков. API и форматы могут меняться без сохранения совместимости.
Что это
DeepSeek Harness — открытая платформа для сборки и запуска ИИ-агентов. Вместо готового приложения она предлагает набор взаимозаменяемых частей: сеанс агента, журнал событий, реестр инструментов, адаптеры моделей, песочницу, систему разрешений и сам цикл принятия решений. Каждая часть оформлена как плагин Cordis и может быть добавлена, удалена или переопределена.
Платформа поставляется в виде npm-пакета `@deepseek-ai/dsh`, который запускает выбранный профиль. Профиль — это упорядоченный набор слоёв плагинов, который собирает конкретную конфигурацию: Web-интерфейс, headless-скрипт, собственный CLI или автоматический сервер по протоколу ACP.
| Составляющая | Роль в Harness | Ключевой сервис |
|---|---|---|
| Сеанс и журнал | Хранит всё, что видит модель: сообщения, вызовы инструментов, результаты | ctx.sessions |
| Сборка промпта | Собирает системный промпт и схемы инструментов из вкладок плагинов | ctx.systemPrompt |
| Реестр инструментов | Регистрирует инструменты и управляет их выполнением | ctx.tools |
| Агент и цикл | Публичный интерфейс агента и драйвер, который им управляет | ctx.agents, ctx.agentLoop |
| Модели | Абстрактный сервис вызова моделей и провайдерные адаптеры | ctx.llm |
| Песочница | Ограничивает файловые и процессные операции агента | ctx.fs, ctx.sandbox |
| Разрешения | Управляет одобрением опасных действий и политиками доступа | ctx.interaction |
| Субагенты | Позволяет агенту делегировать задачи другим агентам | ctx.subagent |
Ключевая идея — нет привилегированного ядра, которое нельзя заменить. Хотите другой цикл мышления — подменяете плагин `agent-loop`. Хотите свой источник моделей — регистрируете адаптер на `ctx.llm`. Хотите другой интерфейс — не трогаете движок, а добавляете собственный пакет клиента.
Инсайт: в Harness всё, что доходит до модели, обязано попасть в журнал сеанса. Это позволяет восстановить историю, повторить диалог, ответвить его или проанализировать позже.
Зачем нужно
Harness решает задачи, которые обычно приходится решать заново в каждом агентном проекте:
- Сборка агента из блоков — не нужно писать цикл мышления, систему инструментов и хранение с нуля.
- Замена компонентов без переписывания — плагины регистрируются через единый контекст, поэтому новый адаптер или цикл встраиваются, а не ломают код.
- Единый журнал событий — всё общение агента с моделью и инструментами записывается последовательно, а история строится из журнала.
- Разные режимы запуска — один и тот же набор плагинов может работать через Web UI, одноразовый headless-скрипт или внешний API.
- Изоляция и разрешения — файловые операции и запуск процессов могут ограничиваться политиками, а опасные действия требуют одобрения.
Как устроено
Архитектура Harness построена на трёх понятиях: сервисы, события и профили.
Сервисы и контекст
Каждый плагин предоставляет сервис под своим ключом в общем контексте `ctx`. Другие плагины обращаются к возможностям по ключу, а не импортируют конкретную реализацию. Плагин может объявить зависимости через `inject`: фреймворк дождётся нужных сервисов и только потом загрузит его.
export const name = "my-tool-plugin"
export const inject = ["tools"]
export function apply(ctx) {
// ctx.tools уже готов
ctx.tools.register(/* ... */)
}События и режимы рассылки
События — точки расширения. Сервисы могут слушать или перехватывать их. В Cordis четыре режима рассылки: emit, waterfall, parallel и serial. Waterfall особенно важен: слушатель получает управление, может изменить запрос и передать дальше через `next()`.
| Режим | Ожидание слушателей | Порядок | Возвращаемое значение |
|---|---|---|---|
| emit | Нет | По порядку регистрации | Нет |
| waterfall | Нет | По порядку регистрации | Да |
| parallel | Да | Параллельно | Нет |
| serial | Да | По порядку регистрации | Да |
Профили и bundle
Профиль — это именованная конфигурация, хранящаяся в домашнем каталоге Harness. Он содержит список bundle — слоёв плагинов, — собственные плагины и файл `cordis.patch.yml`. При запуске слои накладываются друг на друга: сначала bundle профиля, потом профильный патч, затем пользовательский патч из домашнего каталога, наконец патч из командной строки.
Готовые профили: `web` — браузерный интерфейс, `headless` — одноразовый запуск без сервера. Можно создавать собственные профили и устанавливать в них плагины через `dsh plugin`.
Цикл агента
Работа агента разбита на turns и steps. Turn — это один пользовательский запрос и вся работа, которую агент выполняет, чтобы на него ответить. Step — один вызов модели плюс все инструменты, которые модель вызвала в ответ. Один turn может содержать несколько step, если модель просит инструменты, получает результаты и думает дальше.
turn/start
step/start
user/message
agent/request -> llm/stream -> assistant/message
tool/call* -> tools/execute -> tool/result*
step/end
turn/endКогда использовать
| Ситуация | Подходит / не подходит | Почему |
|---|---|---|
| Нужен собственный агентный продукт | Подходит | Можно собрать цикл, инструменты и интерфейс под свои задачи |
| Нужен локальный чат с моделью | Не лучший выбор | Проще взять готовый клиент, не требующий сборки профилей |
| Нужно исследовать или отлаживать цикл агента | Подходит | Все события записаны, профили позволяют подменять компоненты |
| Команда не готова к TypeScript и плагинам | Не подходит | Harness требует понимания Cordis, TypeScript и npm-экосистемы |
| Нужен headless-запуск в CI/CD | Подходит | Профиль headless запускает одну задачу и печатает ответ в stdout |
| Нужна многопользовательская SaaS-платформа | Требует доработки | Из коробки Harness — локальный инструмент, масштабирование и авторизацию придётся добавлять |
Пример
Самый быстрый способ познакомиться с Harness — запустить Web UI из npm. После установки Node.js достаточно одной команды:
npx @deepseek-ai/dsh webСервер поднимается на `http://127.0.0.1:3080\`, и браузер открывается автоматически. При запуске через SSH браузер не открывается — URL печатается в терминале. Перед первой работой нужно указать рабочий каталог в интерфейсе и добавить ключ DeepSeek в настройках моделей.
Headless-режим удобен для скриптов. Он принимает задачу как обычное сообщение, выполняет её и печатает результат:
dsh --profile headless "Summarize this repository and list main packages"Для сборки из исходников клонируйте репозиторий, установите зависимости через pnpm, соберите проект и запустите профиль:
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh webСовет: для запуска из исходников нужен Node.js версии 22.19 или новее, либо 24+. Сборка требует pnpm 11.7.0, который активируется через corepack.
Ограничения
Ограничения
Технические границы, которые нужно учитывать перед выбором Harness.
Ранний предварительный доступ — Платформа активно меняется: форматы на диске, API плагинов и структура профилей могут сломать совместимость.
Производитель пока не гарантирует плавный переход между версиями.
Требуется экосистема Node.js — Для разработки плагинов нужен TypeScript, pnpm, понимание модульной системы и сборки.
Быстрый старт из npm возможен без этого, но кастомизация потребует погружения.
Web UI не работает без сборки фронтенда — Профиль web требует заранее собранных артефактов браузерной части.
Если запускать из исходников без `pnpm run build`, активация профиля завершится ошибкой.
Многопользовательский режим не входит в поставку — Harness ориентирован на локальную работу одного пользователя или CI-задачу.
Совместный доступ, роли и масштабирование серверной части придётся делать самостоятельно.
Ключ DeepSeek нужен для реальных вызовов — Без API-ключа headless-демонстрации и Web UI не смогут обращаться к моделям DeepSeek.
Некоторые тесты и сценарии работают без ключа, но полноценная работа требует ключа.
Антипаттерны
Антипаттерны
Ошибочные ходы, которые приводят к нестабильной сборке.
Рассматривать Harness как готовый чат — Это не альтернатива ChatGPT или веб-версии DeepSeek.
Инструмент раскрывает себя, когда нужно собрать собственного агента, а не просто поговорить с моделью.
Менять пакеты под капотом без чтения архитектуры — `packages/core/` и `packages/llm/` — связная система.
Прямое изменение привилегированных пакетов без понимания Cordis приведёт к непредсказуемым сбоям.
Игнорировать журнал сеанса — В Harness история строится из журнала событий.
Если пытаться хранить состояние агента отдельно, теряется возможность воспроизведения и ответвления диалога.
Добавлять плагины без обратимых эффектов — Cordis откатывает регистрации при выгрузке плагина только если они созданы через `ctx.effect()` или аналогичные помощники.
Ручная подписка на события и глобальные переменные останутся после остановки профиля.
Полагаться на стабильность API — Пока продукт в предварительном доступе, внутренние контракты могут меняться.
Не стоит строить на них долгосрочную интеграцию без готовности следить за изменениями.
Чеклист
Чеклист
Проверяемые действия перед запуском Harness.
DeepSeek Harness выигрывает там, где важна не сама модель, а контур вокруг неё: как агент думает, какие инструменты использует, как хранит память и как отчитывается о проделанном. Если этот контур нужно контролировать — Harness даёт для этого плагиновую основу.
Цель агента определена — Записано, какую задачу агент решает и как измеряется качество.
Без этого сложно выбрать профиль и набор инструментов.
Окружение Node.js готово — Установлен Node.js 22.19+, corepack активирован, pnpm 11.7.0 доступен.
Для запуска из исходников проект собран через `pnpm run build`.
Ключ API добавлен — В Web UI введён ключ DeepSeek или настроен собственный провайдер.
Headless-режим может работать без ключа в демонстрационных сценариях, но не для реальных задач.
Рабочий каталог выбран — В Web UI выбран проект, с которым агент будет работать.
Без рабочего каталога композитор сеанса недоступен.
Понятен выбранный профиль — Известно, какие bundle входят в профиль и какой патч применяется поверх них.
Команда `dsh —dump-config` показывает итоговое дерево плагинов.
Планируется обновление компонентов
— Если проект рассчитан на длительную эксплуатацию, учтён риск ломающих изменений в ранних версиях.
Ссылки
Ссылки
- Документация: DeepSeek Harness — сайт
- Репозиторий: deepseek-ai/deepseek-harness
- Документация: Архитектура Harness