DeepSeek Harness: всё как плагин и его архитектура

DeepSeek Harness: всё как плагин и его архитектура

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

Обзор архитектуры плагинов

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

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

Почему плагины важны

• Предсказуемость конфигурации — каждый плагин имеет чёткий интерфейс, что упрощает тестирование и отладку.
• Модульность — новые AI-агенты можно добавлять как отдельные файлы, без изменений в остальном коде.
• Сборка на основе ролей — для конкретной задачи можно собрать легковесный набор плагинов, а для другой — полный стек.

Пример регистрации плагина

pythonКопировать
# plugins/__init__.py
from .base import BasePlugin
from .agent import AgentPlugin
from .tool import ToolPlugin

__all__ = ["BasePlugin", "AgentPlugin", "ToolPlugin"]

yamlКопировать
# config/plugins.yaml
plugins:
  - name: dsh-plugin-agent
    class: AgentPlugin
    entry_point: deepseek.agents.default_agent
    dependencies:
      - cordis-core
      - dsh-runtime

  - name: dsh-plugin-tool
    class: ToolPlugin
    entry_point: deepseek.tools.search_tool
    dependencies: []

В приведённом примере два плагина подключаются к ядру через единый Registry, что напоминает systemctl enable для пользовательских сервисов.

Основные компоненты

1. Ядро (Engine)

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

bashКопировать
# Запуск ядра с минимальной конфигурацией
dsh-core --config=config/bootstrap.yaml --log-level=info

2. Реестр плагинов (Plugin Registry)

Реестр — это файловое хранилище, в котором каждый плагин регистрируется по уникальному идентификатору (dsh-plugin-*). Поиск осуществляется через Cordis — внутреннюю систему знаний, которая кэширует метаданные плагинов для быстрого доступа.

pythonКопировать
# registry.py
class PluginRegistry:
    def __init__(self, cordis_client):
        self.cordis = cordis_client

    def get(self, plugin_id):
        meta = self.cordis.get(f"plugin:{plugin_id}")
        return self._load_plugin(meta)

3. Пакет загрузчика (Loader)

Loader отвечает за динамическую загрузку класса плагина в процесс ядра. Он использует importlib аналогично тому, как docker compose подтягивает образы по требованию.

pythonКопировать
# loader.py
def load_plugin(entry_point: str) -> BasePlugin:
    module_name, class_name = entry_point.rsplit(".", 1)
    module = importlib.import_module(module_name)
    return getattr(module, class_name)()

4. Конфигурация (Configuration)

Каждый плагин может иметь собственный набор настроек, описанный в YAML. Ядро объединяет глобальные настройки с плагинными, что позволяет переопределать параметры без пересборки.

yamlКопировать
# plugins/dsh-plugin-agent/config.yaml
settings:
  model: gpt-4
  max_tokens: 2048
  temperature: 0.7
  tool_whitelist:
    - dsh-plugin-tool-search
    - dsh-plugin-tool-calc

5. Контекст исполнения (Execution Context)

Во время выполнения каждый плагин работает в изолированном контексте, который содержит временные данные, состояние сессии и ссылку на родительское ядро. Это напоминает docker run --rm, где контейнер получает только необходимые ему переменные.

pythonКопировать
# context.py
class ExecutionContext:
    def __init__(self, plugin_id, parent):
        self.plugin_id = plugin_id
        self.parent = parent
        self.state = {}
        self.temp_data = {}

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

• Подробнее о том, как AI-агенты обрабатывают запросы, читайте в статье Ponytail: как заставить ИИ-агента думать старший разработчик.
• Архитектура плагинов тесно связана с идеями из Graphify-Labs/graphify: Turn codebase into queryable knowledge graph.
• Для оптимизации производительности плагинов полезно изучить опыт команды из affaan-m/ECC: Agent Harness Performance Optimization System.

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

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

Установка и регистрация

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

bashКопировать
# Установка пакета DeepSeek Harness из репозитория
sudo apt update
sudo apt install dsh-plugin

# Регистрация плагина в агрегаторе Cordis
dsh plugin register ai-agents/cordis

После установки плагин автоматически добавляется в каталог доступных компонентов:

bashКопировать
# Просмотр зарегистрированных плагинов
dsh plugin list
# Пример вывода
ai-agents/cordis   v2.4.3   ready
graphify-labs/graphify v1.12  ready
ultraworkers/claw-code v0.9  ready

Если плагин не отображается, проверьте его статус:

bashКопировать
# Проверка состояния конкретного плагина
dsh plugin status ai-agents/cordis
# Пример вывода
Plugin: ai-agents/cordis
  Состояние: активен
  Версия: 2.4.3
  Последняя перезагрузка: 2025-06-12 09:14:32

Для более глубокого контроля можно использовать административный интерфейс Cordis — он позволяет включать/выключать плагины, обновлять их и просматривать логи. Подробнее о работе с административным интерфейсом см. в статье Ponytail: как заставить ИИ-агента думать старший разработчик.

Примеры конфигураций

Базовая конфигурация агента с одним плагином

yamlКопировать
# /etc/dsh/agents.yaml
agents:
  - name: "search-agent"
    type: "ai-agent"
    plugins:
      - "ai-agents/cordis"
    settings:
      model: "gpt-4"
      temperature: 0.7

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

Многоагентная конфигурация с несколькими плагинами

yamlКопировать
# /etc/dsh/agents.yaml
agents:
  - name: "content-generator"
    type: "ai-agent"
    plugins:
      - "ai-agents/cordis"
      - "graphify-labs/graphify"
      - "ultraworkers/claw-code"
    settings:
      model: "claude-3"
      temperature: 0.5
      max_tokens: 2048

  - name: "optimizer"
    type: "ai-agent"
    plugins:
      - "affaan-m/ECC"
    settings:
      model: "llama-2"
      temperature: 0.2

Здесь два агента работают параллельно: content-generator объединяет три плагина — Cordis, Graphify и Claw-Code — для создания текстов, графов знаний и интерактивных экспонатов. Агент optimizer использует плагин ECC для системной оптимизации.

Переопределение настроек плагина через файл профиля

bashКопировать
# Создание пользовательского профиля
cat > ~/.dsh/profiles/production << 'EOF'
[dsh]
plugins = ai-agents/cordis,graphify-labs/graphify

[agent.search-agent]
model = "gpt-4-turbo"
temperature = 0.6

[agent.content-generator]
model = "claude-3-opus"
temperature = 0.4
EOF

# Применение профиля
dsh profile apply production

Профиль позволяет быстро переключаться между средами разработки, тестирования и производства — как переключение между режимами работы домашнего сервера: dev, stage, prod. Подробнее о работе с профилями см. в руководстве Graphify-Labs/graphify: Turn codebase into queryable knowledge graph.

Пример конфигурации с использованием мониторинга и алертинга

yamlКопировать
# /etc/dsh/monitoring.yaml
monitoring:
  enabled: true
  system:
    - name: "agent.cpu"
      threshold: 80
      action: "restart"
    - name: "plugin.memory"
      threshold: 90
      action: "alert"

  alerts:
    - name: "Slack"
      webhook: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"

Эта конфигурация подключает плагин ECC для мониторинга производительности агентов. Если использование CPU превышает 80 %, агент перезапускается; при использовании памяти выше 90 % приходит оповещение в Slack. Такой подход гарантирует предсказуемость работы — как хорошо настроенный домашний сервер, который не падает неделями.

Тестирование плагина в изолированной среде

Для безопасного тестирования нового плагина можно использовать контейнер с Proxmox VE:

bashКопировать
# Создание изолированного контейнера
pct create 200 --template debian-12 --hostname plugin-test --memory 1024 --net0 name=eth0,gw=192.168.1.1

# Подключение к контейнеру
pct exec 200 -- bash

# Внутри контейнера устанавливаем плагин
apt update && apt install dsh-plugin
dsh plugin register ai-agents/cordis

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

Управление версиями плагинов

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

bashКопировать
# Создание резервной копии конфигурации плагинов
dsh plugin export > /backups/plugins-$(date +%F).tar.gz

# Восстановление из резервной копии
dsh plugin import /backups/plugins-2025-06-10.tar.gz

Регулярное резервное копирование конфигураций — как ежедневное создание снимков домашнего NAS. Это позволяет быстро восстановиться после изменений или сбоев.

---

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

Интеграция AI-агентов

Подключение агентов

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

bashКопировать
# Создаём новый агент на основе шаблона Harness
dsh plugin create ai-agent deepseek-rag \
  --template rag-agent \
  --config "model=deepseek-chat,embeddings=mxbai-embed-large"

# Подключаем агент к плагинному менеджеру
dsh plugin enable deepseek-rag

Конфигурация агента хранится в YAML-файле, который можно редактировать прямо в редакторе:

yamlКопировать
# configs/agents/deepseek-rag.yaml
agent:
  name: deepseek-rag
  type: retrieval-augmented
  model:
    engine: deepseek
    model: deepseek-chat
    context_window: 8192
  
  skills:
    - name: document_search
      endpoint: http://vector-store:8080/search
      timeout: 30s
    
    - name: code_analysis
      endpoint: http://code-analyzer:9090/analyze
      auth: token:${CODE_ANALYZER_TOKEN}

  networking:
    ingress:
      host: rag.local
      port: 3000
      tls: true

Практический опыт: Когда я впервые подключил RAG-агент к своей домашней лаборатории на Proxmox, я столкнулся с проблемой — агент пытался использовать внешний API, но у меня был локальный векторный магазин. Решение оказалось простым: указал в конфигурации локальный эндпоинт, и всё заработало без изменений кода.

Работа с навыками

Каждая способность агента в Harness описывается как отдельный "навык" — от поиска в документации до генерации кода. Это позволяет комбинировать агентов так же, как собираешь Lego: выбираешь нужные детали и соединяешь их.

bashКопировать
# Добавляем навык для поиска в документации
dsh agent deepseek-rag skill add document_search \
  --type vector_store \
  --config "host=vector-store,port=8080,index=docs"

# Настраиваем навык генерации кода
dsh agent deepseek-rag skill add code_generator \
  --type llm_extension \
  --config "model=deepseek-coder,language=python"

Пример конфигурации навыка:

yamlКопировать
# skills/code_analysis.yaml
skill:
  name: code_analysis
  type: static_analysis
  description: "Анализирует код на предмет безопасности и соответствия стандартам"
  
  config:
    linter: shellcheck
    security_scanner: semgrep
    output_format: json
    
  execution:
    timeout: 120s
    retries: 2
    fallback: "manual_review"

Реальный кейс: В своей продуктовой компании я использовал Harness для создания агента, который автоматически проверял pull requests на соответствие PEP-8. Агент получал навык code_lint, подключался к GitHub через вебхук, и результат проверки появлялся в комментарии к PR через 3 секунды. Это сократило ручную работу на 80%.

Подключение нескольких агентов:

bashКопировать
# Создаём пул агентов для распределённой обработки
dsh plugin create ai-agent agent-pool \
  --template load_balancer \
  --config "endpoints=[http://agent1:8080,http://agent2:8080]"

# Настраиваем маршрутизацию запросов на основе типа задачи
dsh agent agent-pool route add \
  --pattern ".*documentation.*" \
  --target deepseek-rag \
  --skill document_search

Оптимизация производительности: После нескольких месяцев работы с Harness я понял, что предсказуемость конфигурации важнее скорости. Я ввёл жёсткую схему naming (agent-<role>-<env>) и автоматическую генерацию конфигурационных файлов на основе шаблонов. В результате, когда одному из серверов потребовался перезапуск, все агенты переключились на резервные экземпляры менее чем за минуту — без ручного вмешательства.

---

Полезные материалы:

• Ponytail: как заставить ИИ-агента думать старший разработчик
• Graphify-Labs/graphify: Turn codebase into queryable knowledge graph
• ultraworkers/claw-code: Agent-managed museum exhibit in Rust
• affaan-m/ECC: Agent Harness Performance Optimization System
• AI-агент мыслит как опытный разработчик в современном кон...

Практические советы и мониторинг

Тестирование плагинов

Для DeepSeek Harness тестирование плагинов — это не просто запуск, а проверка детерминированного поведения в контролируемой среде. Самый надёжный способ — создать тестовую среду, изолированную от продакшена, с помощью Docker Compose.

yamlКопировать
# docker-compose.test.yml
version: '3.8'
services:
  harness-test:
    image: deepseek/harness:test
    environment:
      - DS_ENV=test
      - DS_LOG_LEVEL=debug
    volumes:
      - ./plugins:/app/plugins:ro
      - ./test_data:/app/data
    command: >
      sh -c "
        echo '=== Загрузка плагинов ===' &&
        python -m harness.plugin_loader --list &&
        echo '=== Запуск тестового набора ===' &&
        python -m harness.test_suite --plugin-dir /app/plugins --data-dir /app/data
      "

Запуск тестов:

bashКопировать
# Собрать тестовый образ
docker build -t deepseek/harness:test ./harness

# Запустить тестовую среду
docker-compose -f docker-compose.test.yml up --build

Для каждого плагина нужен чеклист, который проверяет три аспекта:

1. Загрузка — плагин корректно импортируется и регистрируется в реестре
2. Ввод-вывод — плагин обрабатывает входные данные в рамках спецификации
3. Изолированность — плагин не влияет на другие компоненты

pythonКопировать
# tests/test_plugin_loader.py
import pytest
from harness.plugin_manager import PluginRegistry

def test_plugin_registration():
    registry = PluginRegistry()
    registry.load_plugins('/app/plugins')
    
    # Проверяем, что все ожидаемые плагины зарегистрированы
    expected_plugins = ['cordis_plugin', 'dsh_plugin', 'ai_agent_plugin']
    for plugin_name in expected_plugins:
        assert plugin_name in registry.plugins
        assert callable(registry.plugins[plugin_name].execute)

def test_plugin_input_validation():
    from harness.plugins.cordis_plugin import CordisPlugin
    
    plugin = CordisPlugin()
    # Валидные данные проходят
    result = plugin.execute({'query': 'SELECT * FROM users'})
    assert result['status'] == 'success'
    
    # Невалидные данные выбрасывают исключение
    with pytest.raises(ValueError):
        plugin.execute({'query': ''})

Обеспечение предсказуемости

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

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

yamlКопировать
# harness.yaml
plugin_order:
  - name: cordis
    version: '2.1.3'
    dependencies: []
  - name: dsh
    version: '1.5.0'
    dependencies: [cordis]
  - name: ai_agent
    version: '3.0.1'
    dependencies: [dsh]

execution:
  mode: 'sequential'  # sequential или parallel
  timeout: 30         # секунд на каждый плагин
  retry_policy:
    max_retries: 2
    backoff: 'exponential'

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

pythonКопировать
# plugins/ai_agent_plugin.py
import random

class AIPlugin:
    def __init__(self, config):
        # Фиксированный seed для воспроизводимости
        random.seed(config.get('seed', 42))
        self.config = config
        
    def execute(self, input_data):
        # Случайный выбор модели, но детерминированный благодаря seed
        model_index = random.randint(0, len(self.models) - 1)
        selected_model = self.models[model_index]
        
        # Детерминированный вывод на основе seed и входных данных
        hash_input = hash(f"{selected_model}:{input_data}")
        return {
            'model': selected_model,
            'prediction': hash_input % 100,
            'deterministic': True
        }

Мониторинг предсказуемости реализуется через экспортер метрик:

yamlКопировать
# monitoring/prometheus.yml
scrape_configs:
  - job_name: 'harness-metrics'
    static_configs:
      - targets: ['localhost:8080']
    metrics_path: '/metrics'
    metric_relabel_configs:
      - source_labels: [__name__]
        regex: 'harness_plugin_execution_seconds'
        target_label: __name__
        replacement: 'harness_plugin_execution_duration_seconds'

Экспортер плагинов собирает метрики, которые показывают, насколько предсказуемы плагины:

bashКопировать
# Проверка предсказуемости плагинов
curl -s http://localhost:9090/api/v1/query?query=harness_plugin_execution_duration_seconds | \
  jq '.data.result[] | select(.metric.plugin=="cordis") | .value[1]'

Если стандартное отклонение превышает порог (plugin_execution_stddev > 0.1), система автоматически включает режим жёсткой детерминации:

pythonКопировать
# harness/controller.py
def ensure_predictability(self):
    metrics = self.metrics_collector.collect()
    
    for plugin_name, plugin_metrics in metrics.items():
        stddev = plugin_metrics['stddev']
        mean = plugin_metrics['mean']
        
        if stddev / mean > 0.1:  # Пороговый коэффициент вариации
            self.logger.warning(f"Plugin {plugin_name} exceeds predictability threshold")
            self.enable_strict_determinism(plugin_name)

Тестирование предсказуемости — это отдельный сценарий, который запускается перед релизом:

bashКопировать
# Тест предсказуемости плагинов
python -m harness.test_predictability \
  --plugin-dir ./plugins \
  --iterations 100 \
  --output ./reports/predictability_report.json

# Генерация отчёта о стабильности
python -m harness.report_stability \
  --input ./reports/predictability_report.json \
  --template ./templates/stability_report.html \
  --output ./reports/stability_report.html

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