DeepSeek Harness: Полный плагин для LLM-агентов
Обзор DeepSeek Harness и концепции плагин-архитектуры для LLM-агентов. Показано, как интеграция компонентов позволяет создать гибкую систему с открытым API.
Плагин-архитектура DeepSeek Harness
Плагин-архитектура DeepSeek Harness
DeepSeek Harness — это фреймворк для сборки LLM-агентов, где ядро отвечает за оркестрацию, а вся функциональность вынесена в плагины. Подобный подход не нов: в Linux ядро не знает ничего о файловой системе, пока не подгружен драйвер. В Harness то же самое — ядро не знает, какую модель вызывать или куда писать логи, пока администратор не подключит нужный плагин.
Для инженера это значит одно: можно заменить один компонент, не трогая остальные. Если завтра появится более подходящая модель, достаточно обновить плагин, а не переписывать агента с нуля.
Модульность и расширяемость
Каждый плагин в Harness — это отдельный модуль с чётко оговоренным интерфейсом. Ядро предоставляет точки входа: генерация текста, вызов инструментов, работа с контекстом, хранение истории. Плагин реализует одну или несколько таких точек и регистрирует себя в системе при старте.
Во-первых, модульность даёт предсказуемость. Вы точно знаете, какой плагин отвечает за запрос к LLM, а какой — за запись в векторную базу. Если что-то ломается, искать проблему нужно в одном месте, а не по всему коду агента.
С практической точки зрения, плагин описывается манифестом. Вот пример для плагина cordis, который отвечает за взаимодействие с внешней базой знаний:
yamlname: 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 выглядит так:
pythonfrom 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
Файл конфигурации сервера:
yamlserver:
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
После применения конфига перезагружаем демон:
bashsudo systemctl daemon-reload
sudo systemctl enable --now dsh
sudo systemctl status dsh
Если мы посмотрим на логи, они уйдут в journald, и их можно читать стандартными средствами:
bashjournalctl -u dsh -f
Для доступа извне я ставлю перед Harness Nginx. Это отдельный сервис, который занимается TLS и раздачей статики, а Harness фокусируется на бизнес-логике агентов.
nginxupstream 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 в конфиг скраббера:
yamlscrape_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:
yamlname: 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:
bashdsh plugin install ./cordis-knowledge-plugin
dsh plugin enable cordis-knowledge-plugin
Во-первых, проверьте, что порт, на котором слушает плагин, не занят другим сервисом. В конфиге хоста это выглядит так:
yamlplugins:
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. В конфиге это задаётся так:
yamlsandbox:
memory_limit: "512m"
cpu_limit: 1.0
network: false
Если плагину всё же нужен сетевой доступ (например, для запроса к Ponytail: как заставить ИИ-агента думать старший разработчик, где агент рассуждает как старший разработчик), включайте его явно и добавляйте таймауты:
yamlplugins:
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))
Результат — предсказуемость работы агента, о которой я часто говорю. Каждый этап имеет чёткое определение входных/выходных данных, что упрощает отладку и масштабирование.
Советы по оптимизации
-
Кэширование частых запросов — если один и тот же запрос приходит повторно (например, «статус заказа #12345»), кэшируйте ответы классификатора и генератора. Это снижает нагрузку на модели и ускоряет время отклика.
yaml# cache-config.yaml cache: enabled: true backend: "redis" ttl: 3600 # секунды keys: - "intent-classifier:*" - "response-generator:*" -
Балансировка нагрузки между плагинами — если у вас несколько экземпляров агента, используйте простой 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) -
Мониторинг предсказуемости — добавьте простой метрикс для отслеживания ошибок классификации и качества сгенерированных ответов. Это помогает выявить дрейф моделей или проблемы с данными на раннем этапе.
yaml# monitoring.yaml — конфигурация Prometheus-метрик metrics: - name: "plugin_errors_total" help: "Общее количество ошибок в плагинах" labels: ["plugin", "error_type"] - name: "plugin_response_time_seconds" help: "Время ответа плагинов" labels: ["plugin"] -
Граничение ресурсов — для плагинов, работающих с большими объемами данных, установите лимиты на 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 -
Версионирование конфигураций — храните все конфигурации агента в 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 плагин не сможет выполнить действие. Если логи показывают, что запрос не доходит до плагина, проблема скорее всего в маршрутизации ядра, а не в самом плагине.