DeepSeek Harness Agent Framework: плагины и процессы

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

Быстрое решение — оценивать DeepSeek Harness Agent Framework по границам модулей: модель, инструменты, сессия, Agent Loop и интерфейс должны заменяться через отдельные точки расширения. Для сложных инструментальных задач это сильная сторона; для простого чата такой уровень архитектуры чаще создаёт лишние обязательства.

Кому пригодится этот разбор:

• инженерам AI Agent, которым нужно понимать внутренние контракты DeepSeek Harness;
• сопровождающим фреймворка, которые планируют писать или проверять сторонние плагины;
• техническим руководителям, выбирающим между собственным циклом выполнения и готовым Harness.

Последняя проверка выполнена 17 августа 2026 года. Архитектурные выводы нужно сверять с официальным репозиторием DeepSeek Harness, его документацией, каталогом исходников и журналом изменений. Если исходный код, документация и фактическая конфигурация расходятся, для решения о внедрении приоритет имеет исполняемый код конкретной версии.

Сначала определите границы, а не список функций

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

• адаптер модели отвечает за формат сообщений, поток вывода и границу провайдера;
• реестр инструментов управляет доступными capability и их схемами;
• сессионное хранилище сохраняет события, сообщения и результаты;
• Agent Loop определяет порядок рассуждения, вызова инструментов и завершения turn;
• слой интерфейса отображает состояние, но не должен владеть бизнес-логикой выполнения;
• политика sandbox и подтверждений ограничивает потенциально опасные действия.

Такая схема важнее количества готовых инструментов. Если вы заменяете провайдера модели, но не меняете механизм формирования истории, это замена адаптера. Если вы добавляете новый инструмент, но он обязан импортировать внутренние объекты цикла, граница уже слабее. Если новый интерфейс читает события журнала и управляет Agent через публичный контекст, расширение выглядит более устойчивым.

Понятие Harness здесь полезно рассматривать как отдельный слой между моделью и рабочей средой. Оно отвечает не только за отправку prompt, но и за выбор инструмента, передачу результата, сохранение состояния, ограничения доступа и решение о продолжении задачи. Общую идею такого слоя можно сопоставить с исследованием архитектуры agent harness, но выводы о конкретном DeepSeek Harness следует делать только по его исходному коду, а не переносить из научной работы автоматически.

Для оценки компонента используйте четыре вопроса:

1. Есть ли отдельный интерфейс или service definition?
2. Может ли провайдер быть заменён без копирования потребителя?
3. Записываются ли модельные входы и результаты в журнал?
4. Есть ли понятный механизм остановки, отката или повторной загрузки?

Если на два последних вопроса нет ответа, перед вами скорее подключаемая функция, чем полноценная архитектурная граница.

Первый этап: разберите дерево загрузки плагинов

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

Для каждого плагина нужно зафиксировать:

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

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

Типичная последовательность загрузки выглядит так:

1. профиль выбирает набор bundles;
2. bundle добавляет конфигурационные строки и код, который они монтируют;
3. профиль применяет собственный patch;
4. пользовательский patch меняет или дополняет конфигурацию;
5. временный overlay используется для отдельного запуска или теста.

В документации подобных систем patch часто нацелен на конкретную строку по идентификатору и заменяет её конфигурацию целиком либо добавляет новую строку. Это важное ограничение для эксплуатации. Если вы рассчитываете на глубокое объединение вложенных параметров, можно незаметно потерять ключ API, политику доступа или настройки тайм-аута.

Посмотреть реально загружаемое дерево нужно отдельной командой, если она предусмотрена вашей версией CLI:

dsh --profile web --dump-config

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

Плагин, который регистрирует инструмент, может выглядеть независимым, но всё равно зависеть от:

• конкретной версии схемы событий;
• структуры сообщения модели;
• способа записи результата;
• механизма подтверждения;
• жизненного цикла Agent;
• формата состояния сессии.

Поэтому «загрузка без ошибки» — только первый тест. Настоящая проверка начинается с выгрузки, повторной загрузки, отмены активного вызова и восстановления после перезапуска.

Второй этап: проверьте, что именно можно заменить

У DeepSeek Harness есть несколько разных уровней заменяемости. Их нельзя объединять в одно обещание.

Адаптер модели. Новый провайдер должен подключаться через отдельную границу LLM. Он обязан соблюдать формат сообщений, потоковую передачу, обработку ошибок и правила работы с tool call. Для сравнения можно использовать официальное описание вызова инструментов DeepSeek API: оно показывает, что модельный ответ и результат функции должны быть представлены как связанные сообщения, а не как произвольный текст.

Реестр инструментов. Инструмент регистрируется в отдельном каталоге, после чего его описание и схема участвуют в сборке запроса к модели. Здесь расширяемость выше, чем при жёстко зашитом списке функций: плагин может добавлять capability, не меняя весь Agent Loop.

Agent Loop. Цикл может быть выделен в самостоятельный пакет или сервис, но это не делает его полностью независимым. Новый цикл должен соблюдать события шага, запрос модели, вызовы инструментов, продолжение turn, остановку, отмену и запись результата.

Сессия. Сессионный слой владеет журналом событий. Это не только память последнего сообщения. Из журнала могут производиться история модели, восстановление, fork, транскрипт, телеметрия и данные для интерфейса.

Интерфейс. Web и headless — разные способы запуска одного исполнительного контура. UI не должен считаться владельцем состояния задачи. Если плагин работает только через экранные действия, его перенос в headless-режим будет затруднён.

Практический вывод: компонент можно считать заменяемым только тогда, когда у него есть собственная точка регистрации, определённый жизненный цикл и понятный потребитель. Один зарегистрированный класс ещё не образует полноценный seam.

Третий этап: восстановите цепочку вызова инструмента

Надёжность AI Agent определяется не тем, смогла ли модель однажды выбрать функцию. Важнее, что происходит после ошибочного аргумента, тайм-аута или частичного результата.

Поток можно представить так:

запрос пользователя
  → сборка prompt и схем инструментов
  → подготовка шага Agent
  → запрос модели
  → поток ответа
  → tool/call
  → предварительная проверка
  → проверка разрешений
  → выполнение
  → постобработка
  → запись tool/result
  → следующая итерация

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

Ошибка выбора

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

Ошибка схемы

Аргумент нужно проверять до запуска побочного действия. Для этого можно использовать формальный контракт, совместимый с JSON Schema; базовые типы, обязательные поля, ограничения и дополнительные свойства описаны в официальной документации JSON Schema.

Ошибку полезно разделять на несколько классов:

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

Такой формат позволяет циклу понять, нужно ли повторить действие, запросить подтверждение или завершить задачу.

Ошибка разрешений

Инструмент может иметь доступ к файлам, сети и подпроцессам, который модель не должна получать автоматически. Регистрация capability не заменяет sandbox или ручного подтверждения.

Ошибка повторения

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

Ошибка возврата

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

Именно здесь проходит граница между демонстрацией и эксплуатацией. Вызов инструмента должен иметь схему, проверку прав, тайм-аут, нормализованную ошибку и запись результата.

Четвёртый этап: отделите Agent Loop от рабочего процесса

AI Agent workflow часто смешивают с детерминированным workflow. Это две разные модели управления.

Открытый Agent Loop позволяет модели выбирать следующий инструмент, уточнять контекст, реагировать на результат и продолжать работу, пока система не сочтёт turn завершённым. Такой режим подходит для исследования репозитория, диагностики и задач, где заранее неизвестен порядок действий.

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

При проектировании зафиксируйте следующие точки:

1. Условие остановки. Что считается выполненным результатом, а что — очередным запросом?
2. Переход между фазами. Может ли модель перескочить проверку перед записью?
3. Подтверждение человека. Какие действия блокируются до явного разрешения?
4. Сжатие контекста. Какие события можно свернуть, а какие нельзя удалять?
5. Восстановление. Откуда продолжится задача после перезапуска процесса?
6. Отмена. Как остановить текущий инструмент и что будет записано в журнал?

Если задача должна выполнять фиксированную последовательность, используйте Agent Loop только там, где нужна интерпретация или выбор параметров. Не отдавайте модели контроль над переходами, которые связаны с правами, публикацией, удалением данных или финансовыми последствиями.

Пятый этап: используйте журнал как источник истины

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

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

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

• идентификатор сессии и turn;
• версию профиля и плагинов;
• собранные секции prompt;
• доступные схемы инструментов;
• решение о вызове;
• фактические аргументы;
• результат или структурированную ошибку;
• факт подтверждения человеком;
• причину остановки;
• созданные артефакты.

Для наблюдаемости полезно разделять логи приложения, события агента и телеметрию выполнения. Документация OpenTelemetry по трассировке помогает выстроить связь между одной задачей, отдельными шагами и внешними вызовами. Это не специфическая функция DeepSeek Harness, а рекомендуемый внешний ориентир для проектирования trace-контекста.

При контекстном сжатии нельзя удалять события, необходимые для аудита действий и восстановления состояния. Сжатый prompt и полный журнал должны быть разными артефактами: первый оптимизирует следующий запрос, второй сохраняет историю исполнения.

Шестой этап: изолируйте права и сторонние плагины

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

Проверьте отдельно:

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

Для сетевых инструментов полезно сопоставить собственную модель разрешений с архитектурой Model Context Protocol. MCP не заменяет изоляцию процесса, но хорошо показывает, почему транспорт, сервер, клиент, capability и жизненный цикл соединения нужно рассматривать раздельно.

Проверку рисков удобно вести по модели угроз, а не по списку галочек. NIST AI Risk Management Framework предлагает общий ориентир для идентификации, оценки и управления рисками AI-систем. В вашем случае отдельными объектами оценки будут модель, плагин, инструмент, секрет, журнал и рабочая директория.

Для первого теста стороннего расширения используйте отдельный профиль, минимальный набор секретов и чистую рабочую директорию. Не подключайте его сразу к рабочему журналу: ошибка конфигурационного patch может заменить целую строку настроек, а не только один вложенный параметр.

Сравните варианты перед внедрением

Эта матрица показывает, почему DeepSeek Harness не следует автоматически выбирать для любого AI Agent. Его преимущество появляется там, где вам действительно нужны замена компонентов, длительное состояние, разные интерфейсы и контролируемый конвейер инструментов.

Контрольная последовательность внедрения

Если вы проверяете фреймворк для команды, действуйте по следующей последовательности:

1. Зафиксируйте версию и исходную конфигурацию. Не считайте обновления обратно совместимыми, пока это не подтверждено тестами и журналом изменений.
2. Снимите дерево профиля. Запустите команду диагностики конфигурации, если она доступна в вашей версии CLI, и сохраните вывод вместе с исходным кодом.
3. Выберите один seam. Начните с адаптера модели или безопасного read-only инструмента, а не с одновременной замены цикла, хранения и UI.
4. Опишите контракт. Укажите входную схему, разрешения, тайм-аут, типы ошибок, результат и условие повторного вызова.
5. Проверьте журнал. Убедитесь, что модельный контекст, tool call и результат восстанавливаются после перезапуска.
6. Проведите негативные тесты. Подайте неверный JSON, истёкший секрет, недоступный файл, зависший процесс и повторную доставку одного события.
7. Проверьте отмену. Установите, прекращается ли подпроцесс и остаётся ли в журнале понятная причина остановки.
8. Сравните headless и Web. Один и тот же плагин не должен менять семантику задачи только из-за интерфейса запуска.
9. Ограничьте права. Дайте тестовому расширению отдельную директорию и минимальные сетевые и файловые разрешения.
10. Подготовьте откат. Храните предыдущий bundle, patch и журнал миграции до каждого обновления.

Где DeepSeek Harness оправдан, а где будет избыточен

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

Он не является очевидным выбором для:

• простого чата без инструментов;
• одного синхронного вызова функции;
• короткого stateless API;
• строго регламентированного процесса, где порядок шагов важнее автономности;
• системы, в которой нельзя регулярно проверять сторонние зависимости и совместимость обновлений.

Для производственной среды ответ на вопрос «подходит ли DeepSeek Harness» должен быть условным. Архитектурно он интересен, если предоставляет отдельные seams для адаптера модели, реестра инструментов, Agent Loop, сессии, sandbox и интерфейса. Но эти границы нужно подтвердить исходным кодом конкретной версии, интеграционными тестами и испытанием восстановления. Наличие плагина само по себе не доказывает безопасную заменяемость.

Если вашей команде нужна удалённая среда для проверки плагинов, журналов и длительных Agent-задач, отдельно проверьте сетевую задержку, постоянство диска, доступ к терминалу и условия удалённой отладки. Для временной проверки можно рассмотреть аренду Mac для удалённого AI-разработчика, а при распределённой команде — сопоставить условия аренды Mac mini в восточной части США. Такой подход практичнее покупки отдельного устройства, если вы ещё не подтвердили длительную нагрузку и требования к физическим интерфейсам.

Ваша текущая среда — локальный ноутбук или обычная виртуальная машина — может оказаться неудобной из-за нестабильного удалённого доступа, ограничений на фоновые процессы и отсутствия постоянного рабочего окружения для восстановления задач. Kvmkit разумно рассматривать именно как временный Mac-контур для проверки плагинов, журналирования и удалённой отладки: сначала подтвердите требования, затем решайте, нужен ли вам постоянный сервер, собственный Mac или аренда на период эксперимента.

Частые вопросы