DeepSeek Harness: агентная обвязка на плагинах

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

Под капотом — Cordis, плагиновый фреймворк, где каждая часть продукта регистрирует сервисы, события и обратимые эффекты в общем контексте. Это позволяет собрать собственную конфигурацию агента: лёгкий headless-режим для скриптов, полноценный Web-интерфейс для разработчика или собственную поверхность на основе SDK.

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

Что это

DeepSeek Harness — открытая платформа для сборки и запуска ИИ-агентов. Вместо готового приложения она предлагает набор взаимозаменяемых частей: сеанс агента, журнал событий, реестр инструментов, адаптеры моделей, песочницу, систему разрешений и сам цикл принятия решений. Каждая часть оформлена как плагин Cordis и может быть добавлена, удалена или переопределена.

Платформа поставляется в виде npm-пакета `@deepseek-ai/dsh`, который запускает выбранный профиль. Профиль — это упорядоченный набор слоёв плагинов, который собирает конкретную конфигурацию: Web-интерфейс, headless-скрипт, собственный CLI или автоматический сервер по протоколу ACP.

Ключевая идея — нет привилегированного ядра, которое нельзя заменить. Хотите другой цикл мышления — подменяете плагин `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()`.

Профили и 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

Когда использовать

Пример

Самый быстрый способ познакомиться с 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.