Продвинутый

DeepSeek Harness: Полный плагин для LLM-агентов

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

Обзор DeepSeek Harness и концепции плагин-архитектуры для LLM-агентов. Показано, как интеграция компонентов позволяет создать гибкую систему с открытым API.

DeepSeek Harness: Полный плагин для LLM-агентов

Обзор DeepSeek Harness и концепции плагин-архитектуры для LLM-агентов. Показано, как интеграция компонентов позволяет создать гибкую систему с открытым API.

Плагин-архитектура DeepSeek Harness

Плагин-архитектура DeepSeek Harness

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

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

Модульность и расширяемость

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

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

С практической точки зрения, плагин описывается манифестом. Вот пример для плагина cordis, который отвечает за взаимодействие с внешней базой знаний:

yaml
name: cordis
version: "0.1.0"
entrypoint: cordis.plugin:CordisPlugin
requires:
  - dsh-core >= 0.4.0
permissions:
  - llm:generate
  - vector-store:read
  - vector-store:write

Поле requires указывает минимальную версию ядра. Если на сервере установлен dsh-core 0.3.9, плагин не загрузится — система предупредит о несовместимости ещё до запуска. Это защищает от ситуации, когда после обновления ядра перестаёт работать половина плагинов, а причинана.

Код плагина на Python выглядит так:

python
from dsh import Plugin, PluginContext, Message

class CordisPlugin(Plugin):
    name = "cordis"
    version = "0.1.0"

    def setup(self, context: PluginContext):
        self.store = context.vector_store
        self.logger.info("Плагин cordis инициализирован")

    def handle(self, message: Message) -> Message:
        if message.intent != "knowledge_search":
            return message
        
        results = self.store.search(message.text, limit=5)
        message.context["knowledge"] = results
        return message

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

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

Интеграция с существующими системами

Harness не требует сносить текущую инфраструктуру и строить всё с нуля. Плагины могут встраиваться в уже работающие сервисы: логи уходят в Loki или journald, метрики — в Prometheus, а сам процесс управляется через systemd.

Ниже пример unit-файла для запуска Harness в качестве системной службы. Я всегда пишу конфиги руками — GUI для тех, кто не знает, где лежит конфиг.

ini
[Unit]
Description=DeepSeek Harness daemon
After=network.target
Wants=network.target

[Service]
Type=simple
User=dsh
Group=dsh
EnvironmentFile=/etc/dsh/env
ExecStart=/usr/local/bin/dsh-server --config /etc/dsh/config.yaml
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
ProtectSystem=full
ReadWritePaths=/var/lib/dsh /var/log/dsh

[Install]
WantedBy=multi-user.target

Файл конфигурации сервера:

yaml
server:
  bind: "0.0.0.0:8080"
  read_timeout: 30s
  write_timeout: 60s

plugins:
  - name: cordis
    path: /opt/dsh/plugins/cordis
    config:
      index_path: /var/lib/dsh/cordis/index
      similarity_threshold: 0.75
  - name: dsh-plugin
    path: /opt/dsh/plugins/dsh-plugin
    enabled: true

logging:
  driver: journald
  level: info

telemetry:
  prometheus:
    enabled: true
    path: /metrics

После применения конфига перезагружаем демон:

bash
sudo systemctl daemon-reload
sudo systemctl enable --now dsh
sudo systemctl status dsh

Если мы посмотрим на логи, они уйдут в journald, и их можно читать стандартными средствами:

bash
journalctl -u dsh -f

Для доступа извне я ставлю перед Harness Nginx. Это отдельный сервис, который занимается TLS и раздачей статики, а Harness фокусируется на бизнес-логике агентов.

nginx
upstream dsh_backend {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name dsh.vinnie-puh.home;

    ssl_certificate /etc/letsencrypt/live/dsh.vinnie-puh.home/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/dsh.vinnie-puh.home/privkey.pem;

    location /api/v1/ {
        proxy_pass http://dsh_backend;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 60s;
    }

    location /metrics {
        proxy_pass http://dsh_backend;
        allow 192.168.1.0/24;
        deny all;
    }
}

Имя сервера vinnie-puh — не случайность. Домашние сервера я называю в честь персонажей советских мультфильмов, так проще запомнить, какой узел за что отвечает.

Интеграция с существующим мониторингом не требует дополнительных агентов. Плагин dsh-plugin отдаёт метрики в формате Prometheus, и достаточно добавить endpoint в конфиг скраббера:

yaml
scrape_configs:
  - job_name: 'deepseek-harness'
    static_configs:
      - targets: ['dsh.vinnie-puh.home:8080']

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

Аналогично, если в проекте уже есть агент, который ведёт себя как старший разработчик, его можно обернуть в плагин Harness и получить централизованное управление вызовами. Опыт с такими агентами описан в материале про Ponytail и в разборе поведения ИИ-агента.

Для оптимизации работы самого harness полезно посмотреть на систему оптимизации производительности от affaan-m — там описаны подходы к снижению задержек и расхода ресурсов.

Если же задача связана с управлением физическими экспонатами через агента, пример на Rust показывает, как можно вынести логику агента за пределы Python-стека: Agent-managed museum exhibit in Rust.

Плагин-архитектура DeepSeek Harness не обещает универсальное решение. Она даёт инструмент, с помощью которого можно собрать систему под свои задачи, не ломая существующую инфраструктуру. Главное — чётко разделить ответственность между ядром и плагинами и не пренебрегать мониторингом.

Практика использования

Настройка плагинов

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

Пример манифеста плагина dsh-plugin:

yaml
name: cordis-knowledge-plugin
version: "0.1.0"
entrypoint: src/plugin.py
api:
  - name: search_codebase
    description: Поиск по графу знаний кодовой базы
    input:
      type: object
      properties:
        query:
          type: string
    output:
      type: array
      items:
        type: string
permissions:
  - fs.read
  - network.outbound

После создания манифеста плагин устанавливается через CLI-утилиту DSH:

bash
dsh plugin install ./cordis-knowledge-plugin
dsh plugin enable cordis-knowledge-plugin

Во-первых, проверьте, что порт, на котором слушает плагин, не занят другим сервисом. В конфиге хоста это выглядит так:

yaml
plugins:
  cordis-knowledge-plugin:
    host: 127.0.0.1
    port: 8081
    timeout: 30
    retries: 3

Если вы уже используете Graphify-Labs/graphify: Turn codebase into queryable knowledge graph для построения графа знаний из кодовой базы, плагин может запрашивать его через HTTP и возвращать агенту уже структурированные результаты, а не сырой текст.

Ограничения и решения

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

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

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

Изоляция. Ошибка в плагине не должна вывести из строя весь агент. DSH запускает плагины в отдельных процессах с ограничением по памяти и CPU. В конфиге это задаётся так:

yaml
sandbox:
  memory_limit: "512m"
  cpu_limit: 1.0
  network: false

Если плагину всё же нужен сетевой доступ (например, для запроса к Ponytail: как заставить ИИ-агента думать старший разработчик, где агент рассуждает как старший разработчик), включайте его явно и добавляйте таймауты:

yaml
plugins:
  ponytail-reasoning:
    network: true
    timeout: 10
    circuit_breaker:
      threshold: 5
      reset_timeout: 60

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

Применение в реальных проектах

Применение в реальных проектах

Кейс: автоматизация работы с LLM

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

yaml
# config.yaml — конфигурация агента для обработки запросов
version: 1
agent:
  name: "support-bot"
  model: "deepseek-chat"
  plugins:
    - name: "intent-classifier"
      endpoint: "http://localhost:8080/classify"
      timeout: 30
    - name: "context-extractor"
      endpoint: "http://localhost:8080/extract"
      timeout: 45
    - name: "response-generator"
      endpoint: "http://localhost:8080/generate"
      timeout: 60

  workflow:
    - step: "parse_input"
      plugin: "intent-classifier"
      input: "{{ user_query }}"
    - step: "enrich_context"
      plugin: "context-extractor"
      input: "{{ parsed_intent }}"
    - step: "generate_reply"
      plugin: "response-generator"
      input: "{{ enriched_context }}"

Вот как это работает на практике. Агент получает запрос от пользователя, классификатор определяет его intent (support, billing, technical), экстрактор собирает релевантный контекст из базы знаний, а генератор формирует ответ. Всё это — через единый API, без необходимости писать отдельные сервисы для каждой задачи.

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

bash
# preprocess.py — очистка входных данных перед отправкой
import re
import json

def clean_query(text: str) -> str:
    # удалить лишние пробелы, спецсимволы, нормализовать кодировку
    text = re.sub(r'\s+', ' ', text.strip())
    # заменить латинские символы на кириллические, где это уместно
    text = text.replace('ch', 'ч').replace('sh', 'ш')
    return text

def process_request(raw: str) -> dict:
    cleaned = clean_query(raw)
    return {
        "original": raw,
        "cleaned": cleaned,
        "timestamp": datetime.utcnow().isoformat()
    }

# Пример использования
if __name__ == "__main__":
    sample = "  Помогите, у меня проблемы с оплатой!  "
    print(json.dumps(process_request(sample), ensure_ascii=False, indent=2))

Результат — предсказуемость работы агента, о которой я часто говорю. Каждый этап имеет чёткое определение входных/выходных данных, что упрощает отладку и масштабирование.

Советы по оптимизации

  1. Кэширование частых запросов — если один и тот же запрос приходит повторно (например, «статус заказа #12345»), кэшируйте ответы классификатора и генератора. Это снижает нагрузку на модели и ускоряет время отклика.

    yaml
    # cache-config.yaml
    cache:
      enabled: true
      backend: "redis"
      ttl: 3600  # секунды
      keys:
        - "intent-classifier:*"
        - "response-generator:*"
    
  2. Балансировка нагрузки между плагинами — если у вас несколько экземпляров агента, используйте простой round-robin или weighted-схему. Это предотвращает перегрузку одного плагина, особенно при работе с интенсивными задачами.

    python
    # load_balancer.py — простой балансировщик для плагинов
    import random
    from typing import List, Callable
    
    class PluginBalancer:
        def __init__(self, plugins: List[Callable]):
            self.plugins = plugins
    
        def dispatch(self, data: dict) -> dict:
            # равномерный выбор (можно доработать под weighted-схему)
            plugin = random.choice(self.plugins)
            return plugin(data)
    
  3. Мониторинг предсказуемости — добавьте простой метрикс для отслеживания ошибок классификации и качества сгенерированных ответов. Это помогает выявить дрейф моделей или проблемы с данными на раннем этапе.

    yaml
    # monitoring.yaml — конфигурация Prometheus-метрик
    metrics:
      - name: "plugin_errors_total"
        help: "Общее количество ошибок в плагинах"
        labels: ["plugin", "error_type"]
      - name: "plugin_response_time_seconds"
        help: "Время ответа плагинов"
        labels: ["plugin"]
    
  4. Граничение ресурсов — для плагинов, работающих с большими объемами данных, установите лимиты на CPU и память. Это предотвращает «захват» системы другими процессами.

    bash
    # Пример cgroup-лимитов для плагина intent-classifier
    #!/bin/bash
    cd /sys/fs/cgroup/memory/
    mkdir app/intent-classifier
    echo "4G" > app/intent-classifier/memory.limit_in_bytes
    echo "$$" > app/intent-classifier/cgroup.procs
    
  5. Версионирование конфигураций — храните все конфигурации агента в git. Это позволяет откатываться к предыдущим версиям, если новый плагин внезапно начинает давать сбой.

    bash
    # Пример коммита конфигурации
    git add config.yaml cache-config.yaml monitoring.yaml
    git commit -m "Обновление плагинов: intent-classifier v2.1, response-generator v1.3"
    

Эти приёмы проверены на практике — мы применяем их в production-системах уже несколько лет. Главное — помнить о предсказуемости: каждый этап должен иметь чёткое определение, а ошибки должны регистрироваться, а не игнорироваться.

Для дальнейшего изучения обратите внимание на Ponytail: как заставить ИИ-агента думать старший разработчик, где подробно описан подход к архитектуре агентов, и Graphify-Labs/graphify: Turn codebase into queryable knowledge graph, показывающий, как интегрировать графовые базы знаний с LLM-агентами.

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

Как добавить новый плагин в DeepSeek Harness?

Создайте YAML-манифест с полями name, version, entrypoint, requires и permissions, затем положите файл в каталог плагинов, который сканирует ядро при старте. Ядро проверит совместимость версии dsh-core и зарегистрирует точки входа, указанные в манифесте. После перезапуска агента плагин станет доступен для маршрутизации запросов.

Что делать, если плагин не загружается из-за версии ядра?

Проверьте поле requires в манифесте и сравните его с установленной версией dsh-core. Если ядро старше, чем требует плагин, обновите ядро до подходящей версии или найдите более старую версию плагина. Сигнал о несовместимости появляется ещё до запуска, поэтому проблема видна в логах при старте.

Можно ли использовать несколько плагинов для одной точки входа?

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

Как отлаживать плагин, если агент не вызывает нужный инструмент?

Включите подробное логирование для ядра и для конкретного плагина, чтобы видеть, какие запросы приходят и какие ответы возвращаются. Проверьте права в разделе permissions манифеста — без права llm:generate или tool:call плагин не сможет выполнить действие. Если логи показывают, что запрос не доходит до плагина, проблема скорее всего в маршрутизации ядра, а не в самом плагине.

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

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