Продвинутый

DeepSeek Harness: всё как плагин в DeepSeek

Алексей Кузнецов
Алексей Кузнецов
Системный администратор3 ноября 2026 г.11 мин чтения

Статья рассказывает об архитектуре DeepSeek Harness, где каждый компонент — плагин. Рассматриваются преимущества, настройки и интеграция.

DeepSeek Harness: всё как плагин в DeepSeek

Статья рассказывает об архитектуре DeepSeek Harness, где каждый компонент — плагин. Рассматриваются преимущества, настройки и интеграция.

Введение

Введение

Обзор

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

С практической точки зрения, это решение устраняет проблему "монолитных" AI-стеков, где все компоненты жестко связаны. С помощью Harness вы получаете предсказуемую конфигурацию: каждый плагин выполняет одну конкретную задачу, а взаимодействие между ними описано в конфигурационном файле.

yaml
# dsh.yaml — базовая конфигурация DeepSeek Harness
version: "1.0"
plugins:
  - name: "cordis"
    version: "2.1.0"
    enabled: true
    config:
      endpoint: "ws://localhost:8080"
      model: "deepseek-cordis"
  - name: "dsh-plugin"
    version: "0.9.3"
    enabled: true
    config:
      log_level: "info"
      cache_size: "512MB"

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

Для тех, кто знаком с контейнерными подходами, это похоже на Docker Compose: каждый сервис (плагин) имеет свои зависимости, а оркестрацией управляет общий конфигурационный файл.

Почему это важно

В современных AI-решениях часто встречаются проблемы с жесткой связанностью компонентов: изменить один плагин значит рисковать стабильностью всего стека. DeepSeek Harness решает эту проблему, предоставляя:

  • Модульность: каждый компонент — автономный плагин
  • Предсказуемость: конфигурация описана явно, а не скрыта в коде
  • Гибкость: легко заменить или обновить отдельные компоненты
  • Тестирование: можно протестировать новый плагин без влияния на остальные

Быстрый старт

bash
# Установка DeepSeek Harness
pip install deepseek-harness

# Инициализация нового проекта
dsh init my-project
cd my-project

# Добавление плагина Cordis для работы с графами знаний
dsh add cordis --version 2.1.0

# Включение AI-агента с плагином
dsh enable dsh-plugin

Ключевые концепции

  • Плагин — это автономный компонент, который предоставляет конкретную функциональность
  • Хаб — центр управления плагинами, который отслеживает зависимости и управляет жизненным циклом
  • Конфигурация — YAML-файл, в котором описаны используемые плагины и их параметры

С чего начать

  1. Определите, какие плагины вам нужны для конкретной задачи
  2. Создайте конфигурационный файл dsh.yaml
  3. Подключите необходимые плагины с помощью dsh add
  4. Настройте параметры каждого плагина
  5. Запустите агент с помощью dsh run

Для более глубокого изучения архитектуры рекомендуем:

Если вам нужен практический пример интеграции с другими инструментами, посмотрите:

Архитектура плагинов

Архитектура плагинов

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

Компоненты

С практической точки зрения архитектура состоит из четырёх частей.

Ядро (dsh-core) — загрузчик плагинов и шина событий. Оно не знает, что такое «агент» или «ревью кода», оно только выполняет контракт плагина: инициализация, запуск, остановка, передача сообщений.

Реестр плагинов — локальный каталог с манифестами. Каждый плагин описывается файлом dsh-plugin.yaml, где указаны имя, версия, точка входа и зависимости.

Конфигурационный слой — YAML-файлы и переменные окружения. Я рекомендую держать конфиг рядом с кодом плагина, а не размазывать его по системе.

CLI-интерфейс (dsh) — точка входа для управления. Через него устанавливают, включают и отключают плагины.

Пример манифеста плагина cordis:

yaml
name: cordis
version: "1.2.0"
type: agent
entrypoint: cordis.plugin:DeepSeekAgent
api_version: v1
depends:
  - dsh-core >= 0.9.0
  - dsh-llm-provider >= 0.5.0
permissions:
  - fs.read
  - network.outbound

Посмотреть установленные плагины и их статус можно командой:

bash
# Проверяем, какие плагины активны и какая версия ядра
dsh plugin list

Пример вывода:

NAME        VERSION  STATUS   TYPE
cordis      1.2.0    active   agent
dsh-llm     0.5.1    active   provider
dsh-fs      0.3.0    active   storage

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

Типы плагинов

Все плагины делятся на четыре категории по назначению.

Агентные плагины (ai-agents) реализуют логику конкретного агента: общаются с моделью, вызывают инструменты, принимают решения. Пример — плагин cordis для код-ревью или автоматизации задач.

Интеграционные плагины подключают внешние системы: базы данных, хранилища, API. Они не принимают решений, только передают данные между агентом и ресурсом.

Интерфейсные плагины отвечают за то, как пользователь взаимодействует с Harness: CLI, HTTP API, веб-интерфейс.

Посредники (middleware) — сквозная логика: логирование, аутентификация, ограничение частоты запросов. Они обёртывают вызовы между компонентами.

Пример конфигурации агента с инструментами:

yaml
agents:
  - name: code-reviewer
    plugin: cordis
    model: deepseek-chat
    temperature: 0,2
    system_prompt: |
      Ты — старший код-ревьюер. Проверяй pull request на соответствие
      стандарту кодирования и предлагай конкретные правки.
    tools:
      - name: grep
        plugin: dsh-fs
      - name: read_file
        plugin: dsh-fs

Пример подключения посредников для логирования и авторизации:

yaml
middleware:
  - plugin: dsh-logger
    level: info
    output: journald
  - plugin: dsh-auth
    strategy: api_key
    header: X-DSH-Token

Если мы посмотрим на реальную практику, агентные плагины чаще всего становятся точкой расширения. Например, через плагин cordis можно подключить анализ кода, а для построения графов зависимостей удобно использовать Graphify: Создание знаний из кода в виде графов — он тоже встраивается как плагин и передаёт данные в общую шину Harness.

Коллекцию готовых навыков для агентов можно найти в Навыки реальных инженеров: коллекция из .agents — полезно, если не хотите писать каждый инструмент с нуля.

Общая концепция плагинной архитектуры описана в DeepSeek Harness: Плагинная архитектура для AI-агентов.

Использование плагинов

Использование плагинов

Настройка

Плагины в DeepSeek Harness подключаются через один файл манифеста — dsh.yaml. Это не GUI с галочками, а обычный текстовый конфиг, который правится вручную. Я предпочитаю именно такой подход: когда конфиг лежит в репозитории, его можно версионировать, ревьюить и откатывать.

Вот минимальный пример манифеста с двумя плагинами — cordis для сбора контекста и dsh-plugin для выполнения задач:

yaml
# dsh.yaml
version: "1"

plugins:
  - name: cordis
    source: local
    path: ./plugins/cordis
    config:
      index_path: /var/lib/dsh/cordis/index
      embed_model: bge-m3
      chunk_size: 512

  - name: dsh-plugin
    source: registry
    version: "0.4.1"
    config:
      endpoint: http://localhost:8080
      timeout: 30
      retry_count: 3

После правки файла плагины нужно загрузить в рантайм. Команда dsh plugin load читает манифест и инициализирует каждый компонент:

bash
dsh plugin load --config ./dsh.yaml

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

Примеры интеграции

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

Ниже пример интеграции cordis с dsh-plugin. Плагин cordis индексирует код репозитория и кладёт эмбеддинги в векторное хранилище. Когда агенту нужно ответить на вопрос по кодовой базе, он запрашивает контекст у cordis, а затем передаёт его в dsh-plugin для генерации ответа.

Конфиг cordis с путями к индексу:

yaml
# plugins/cordis/config.yaml
index:
  path: /var/lib/dsh/cordis/index
  rebuild_interval: "1h"
  watch_paths:
    - /opt/app/src
    - /opt/app/lib

embedding:
  model: bge-m3
  device: cuda
  batch_size: 32

Запуск индексации вручную:

bash
dsh plugin exec cordis --action index --path /opt/app/src

Теперь пример вызова dsh-plugin с контекстом, собранным cordis. Агент передаёт запрос и ссылку на индекс, плагин возвращает сгенерированный ответ:

bash
dsh plugin exec dsh-plugin \
  --query "Как работает аутентификация в модуле billing?" \
  --context-source cordis \
  --index /var/lib/dsh/cordis/index

Если нужно интегрировать свой плагин, достаточно реализовать интерфейс dsh.Plugin и зарегистрировать его в манифесте. Ниже скелет на Python — точка входа, метод handle и регистрация в реестре:

python
# plugins/my_plugin/__init__.py
from dsh import Plugin, PluginContext, Event

class MyPlugin(Plugin):
    name = "my_plugin"

    def handle(self, event: Event, ctx: PluginContext) -> Event:
        # Обработка события от другого плагина
        return Event(
            type="response",
            payload={"result": "ok"}
        )

def register():
    return MyPlugin()

После добавления плагина в dsh.yaml он станет доступен для вызова через dsh plugin exec my_plugin. Предсказуемость конфигурации здесь ключевая: если плагин описан в манифесте, он будет вести себя одинаково на разработке, стейджинге и продакшене.

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

FAQ

Как добавить плагин?

Для добавления нового плагина в DeepSeek Harness выполните следующие шаги:

bash
# 1. Создайте директорию плагина
mkdir -p ~/.config/deepseek/plugins/my-plugin

# 2. Добавьте файл конфигурации плагина
cat > ~/.config/deepseek/plugins/my-plugin/config.yaml << 'EOF'
name: my-plugin
version: 1.0.0
description: "Плагин для обработки специальных запросов"
entry_point: main.py
author: Алексей Кузнецов
EOF

# 3. Создайте основной файл плагина
cat > ~/.config/deepseek/plugins/my-plugin/main.py << 'EOF'
import dsh
from dsh.api import Plugin

class MyPlugin(Plugin):
    def __init__(self):
        super().__init__(
            name="my-plugin",
            version="1.0.0",
            description="Обработка специальных запросов"
        )
    
    def handle_request(self, request):
        # Реализация обработки запроса
        if request.type == "special":
            return self.process_special(request.data)
        return None
    
    def process_special(self, data):
        # Логика обработки специальных данных
        return {"result": "processed", "data": data}
EOF

# 4. Зарегистрируйте плагин
dsh plugin register ~/.config/deepseek/plugins/my-plugin/config.yaml

Пример использования:

python
from dsh.api import PluginManager

# Инициализируйте плагин-менеджер
manager = PluginManager()

# Загрузите все доступные плагины
manager.load_plugins()

# Используйте плагин
result = manager.execute_plugin("my-plugin", {"type": "special", "data": "test_data"})

Что такое точка расширения?

Точка расширения в DeepSeek Harness — это определенное место в архитектуре, где плагин может внедрить свою функциональность. Это аналог интерфейса API, но с более гибкой архитектурой.

Основные типы точек расширения:

python
# 1. Точка обработки запросов
class RequestHandlerExtension:
    def handle(self, request):
        """Обрабатывает входящие запросы"""
        pass

# 2. Точка валидации данных
class ValidationExtension:
    def validate(self, data):
        """Валидирует данные перед обработкой"""
        pass

# 3. Точка логирования
class LoggingExtension:
    def log(self, level, message, context=None):
        """Логирует события"""
        pass

# 4. Точка мониторинга
class MonitoringExtension:
    def metrics(self):
        """Возвращает метрики производительности"""
        pass

Пример реализации точки расширения:

python
from dsh.api import ExtensionPoint

class CustomExtensionPoint(ExtensionPoint):
    def __init__(self):
        super().__init__(
            name="custom-processing",
            description="Пользовательская точка обработки"
        )
    
    def register_handler(self, handler):
        """Регистрирует обработчик"""
        self.handlers.append(handler)
    
    def execute(self, data):
        """Выполняет обработку через все зарегистрированные обработчики"""
        results = []
        for handler in self.handlers:
            result = handler(data)
            results.append(result)
        return results

Практический пример:

python
# Создайте пользовательскую точку расширения
ext_point = CustomExtensionPoint()

# Зарегистрируйте обработчики
ext_point.register_handler(lambda x: x * 2)
ext_point.register_handler(lambda x: x + 10)

# Выполните обработку
result = ext_point.execute(5)
# Результат: [10, 15]

Где найти документацию?

Документация DeepSeek Harness доступна в нескольких местах:

Основная документация:

Руководства по интеграции:

Примеры и шаблоны:

Для разработчиков плагинов:

bash
# Просмотр встроенной документации
dsh docs --plugins

# Генерация документации плагина
dsh docs generate ~/.config/deepseek/plugins/my-plugin/

# Просмотр примеров интеграции
dsh examples --all

Полезные ресурсы:

  1. GitHub репозиторий: DeepSeek/DeepSeek-Harness
  2. Discord сообщество: deepseek.dev/discord
  3. Telegram канал: t.me/deepseek_harness

Совет: Для быстрого старта ознакомьтесь с примером плагина в репозитории и используйте dsh init для создания нового плагина с базовой структурой.


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

Часто задаваемые вопросы

Как DeepSeek Harness отличается от традиционных монолитных AI-стеков?

В монолитных стеках компоненты жёстко связаны, изменение одного может нарушить весь стек. В Harness каждый компонент — самостоятельный плагин, который можно подключить, отключить или заменить без переписывания кода. Это похоже на Docker Compose: каждый сервис описан отдельно, а оркестрация задана в конфигурационном файле. Такой подход обеспечивает предсказуемость и упрощает тестирование гипотез.

Какие типичные сценарии использования DeepSeek Harness?

Harness подходит для быстрого прототипирования новых AI-агентов: достаточно добавить плагин в конфигурацию dsh.yaml. Он также полезен при масштабировании existing-стека — добавление нового агента не требует перестройства всего стека. Ещё один сценарий — ротация моделей: плагин cordis можно заменить на другой без изменения остального стека. Это позволяет экспериментировать с конфигурациями и откатываться к стабильной версии.

Как обеспечивается предсказуемость конфигурации в Harness?

Предсказуемость достигается за счтом явного описания каждого плагина в YAML-файле: версия, параметры, зависимости. Конфигурация хранится отдельно от кода, что позволяет проверить её перед применением. Если что-то работает не так, можно вернуться к предыдущей версии файла, не перестраивая систему. Такой подход аналогичен управлению инфраструктурой через код: каждый шаг документирован и повторяем.

Какие инструменты подходят для разработки и отладки плагинов в Harness?

Для разработки плагинов удобны редакторы YAML, такие как VS Code с расширениями для YAML. Отладку помогает вести логирование через конфигурационный параметр log_level, а мониторинг — через Prometheus/Grafana, если плагин экспортирует метрики. Ещё полезен локальный тестовый стенд: можно запустить плагин на порту 8080 и проверить взаимодействие через curl. Такой же подход используется при отладке systemd-сервисов — сначала локально, потом в проде.

Поделиться:TelegramX / TwitterVK

Читайте также