DeepSeek Harness: Всё как Плагин — Архитектура и Применение

DeepSeek Harness: Всё как Плагин — Архитектура и Применение

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

Архитектура DeepSeek Harness

Архитектура DeepSeek Harness

Плагин как базовый элемент

DeepSeek Harness рассматривает любой самостоятельный компонент как плагин.
Плагин – это самостоятельный модуль, который реализует один well‑defined интерфейс (например, загрузку данных, трансформацию, отправку запросов).

Такое построение позволяет:

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

Пример описания плагина (файл plugin.yaml):

yamlКопировать
name: my_data_source
version: "1.0"
description: "Чтение CSV‑файлов из локального хранилища"
entrypoint: "python -m my_data_source"
dependencies:
  - pandas>=2.0
config:
  path: "/opt/data/input.csv"

В коде плагина реализуется класс, наследующий базовый интерфейс PluginBase:

pythonКопировать
class MyDataSource(PluginBase):
    def load(self) -> pd.DataFrame:
        return pd.read_csv(self.config["path"])

Агент, использующий этот плагин, получает его по имени:

yamlКопировать
agents:
  - name: data_processor
    plugin: my_data_source
    steps:
      - load: my_data_source
      - transform: my_transform

Таким образом, плагин – это фундаментальный строительный блок, а не «дополнительный модуль», а часть ядра архитектуры.

Связь с AI‑агентами

AI‑агенты в DeepSeek Harness состоят из цепочки steps, где каждый step может быть обычным скриптом или плагином.
Плагин обеспечивает внешний доступ (к базе, API, файловой системе) и тем самым расширяет возможности агента без необходимости писать код «с нуля».

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

yamlКопировать
agents:
  - name: analytics_agent
    plugins:
      - data_source: my_data_source
      - storage: my_sqlite_store
    steps:
      - load: my_data_source
      - enrich: my_transform
      - store: my_sqlite_store
      - analyze: my_llm

В данном примере:

• my_data_source – плагин, читающий CSV‑файл.
• my_transform – плагин, преобразующий данные.
• my_sqlite_store – плагин‑хранилище, доступный через SQL.
• my_llm – плагин, вызывающий LLM‑модель для анализа.

Как это выглядит в коде (Python‑интерфейс агента):

pythonКопировать
class AnalyticsAgent(AgentBase):
    def __init__(self, config):
        self.plugins = {
            "my_data_source": MyDataSource(config["plugins"]["my_data_source"]),
            "my_sqlite_store": SQLiteStore(config["plugins"]["my_sqlite_store"]),
        }

    def run(self):
        df = self.plugins["my_data_source"].load()
        df = self.plugins["my_transform"].enrich(df)
        self.plugins["my_sqlite_store"].save(df)
        result = self.plugins["my_llm"].analyze(df)
        return result

Таким образом, AI‑агент использует плагины как «мосты» к реальному миру, а DeepSeek Harness обеспечивает единый порядок инициализации, мониторинг жизненного цикла и автоматическое восстановление при падении плагина.

Для более детального ознакомления с практикой создания агентов и подбором подходящих плагинов см. Набор навыков для работы с AI-агентами.

---

Если требуется добавить новый плагин, достаточно разместить его в директории plugins/ и описать в plugin.yaml. Все остальные части системы автоматически его подхватят.

Интеграция с инфраструктурой

Docker и Docker Compose

Во-первых, Docker позволяет упаковать любой компонент — модуль, сервис или плагин — в изолированный контейнер. Это упрощает как локальную отладку, так и развёртывание в домашней лаборатории.

С Docker Compose можно описать всю стэк‑инфраструктуру в одном файле, задав зависимости между сервисами. Например, для AI‑агента, который работает на Python и использует модель из отдельного контейнера, удобно объявить два сервиса:

yamlКопировать
version: "3.9"
services:
  agent:
    build: ./agent
    volumes:
      - ./agent:/app
    environment:
      - MODEL_URL=http://model-service:8000
    depends_on:
      - model-service

  model-service:
    image: deepseek/model:latest
    ports:
      - "8000:8000"

Команды для запуска и проверки состояния:

shКопировать
docker compose up -d          # собрать и запустить контейнеры
docker compose ps             # увидеть статус сервисов
docker compose exec agent bash   # выполнить оболочку внутри контейнера‑агента

Справедливо и с практической точки зрения: если добавить новый плагин, достаточно создать каталог с Dockerfile и добавить сервис в файл docker-compose.yml. При этом не требуется менять конфигурацию других компонентов – Docker Compose сам позаботится о сетевых связях и зависимостях.

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

---

Kubernetes и k3s

В k3s (лёгком дистрибутиве Kubernetes) плагины обычно разворачиваются как Deployments или StatefulSets. Это позволяет задавать репликацию, стратегии обновления и привязывать конфигурацию через ConfigMap или Secret.

Пример Deployment для плагина‑агента, который использует общий сервис модели:

yamlКопировать
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ai-agent
spec:
  replicas: 2
  selector:
    matchLabels:
      app: ai-agent
  template:
    metadata:
      labels:
        app: ai-agent
    spec:
      containers:
        - name: agent
          image: registry.example.com/ai-agent:latest
          env:
            - name: MODEL_URL
              value: "http://model-service.default.svc.cluster.local:8000"
          volumeMounts:
            - name: plugin-code
              mountPath: /app
      volumes:
        - name: plugin-code
          configMap:
            name: ai-agent-config

Создание ConfigMap для конфигураций плагина:

shКопировать
kubectl create configmap ai-agent-config --from-file=./agent/config.yaml

Команды для управления:

shКопировать
kubectl apply -f deployment.yaml      # развернуть или обновить Deployment
kubectl get pods -l app=ai-agent       # проверить статус подов
kubectl logs -f deployment/ai-agent   # смотреть логи в реальном времени

С практической точки зрения, k3s идеален для домашней лаборатории из трёх нод (например, на Raspberry Pi) – он лёгок в установке, требует минимум ресурсов и сохраняет «предсказуемость» конфигураций, о которой часто говорим в системных вопросах.

Если нужно масштабировать несколько плагинов, удобно использовать набор навыков для работы с AI‑агентами – там описаны подходы к автоскейлингу и мониторингу через Prometheus и Grafana.

---

Таким образом, Docker Compose подходит для быстрого прототипирования и локального тестирования, тогда как Kubernetes / k3s обеспечивает более надёжное и масштабируемое развёртывание в реальной инфраструктуре. Выбор инструмента зависит от размера лаборатории, требований к отказоустойчивости и уровня автоматизации.

Практические примеры использования

Создание простого плагина

Во-первых, для любого компонента в DeepSeek Harness нужен манифест, описывающий его возможности. Создаём директорию my_plugin и помещаем в неё файл manifest.yaml:

yamlКопировать
name: my_plugin
version: "1.0"
description: Плагин‑пример, выводящий список активных Docker‑контейнеров.
author: "Алексей Кузнецов"
entrypoint: ["python", "handler.py"]

Далее пишем основной обработчик handler.py. Он получает от Harness запрос о текущих контейнерах и формирует ответ:

pythonКопировать
import subprocess
import json

def main():
    # Получаем список контейнеров через docker CLI
    result = subprocess.run(
        ["docker", "ps", "--format", "{{.Names}}"],
        capture_output=True,
        text=True,
        check=True,
    )
    containers = result.stdout.strip().splitlines()
    # Формируем JSON‑ответ
    response = json.dumps({"containers": containers})
    print(response)  # Harness ожидает stdout с JSON

if __name__ == "__main__":
    main()

Собираем образ и проверяем работу:

bashКопировать
docker build -t my_plugin:latest .
docker run --rm my_plugin:latest

Если в выводе появится JSON‑массив с именами контейнеров, плагин готов к использованию. Такой подход позволяет быстро прототипировать любой скрипт‑обёртку под нужный API.

Статья Набор навыков для работы с AI-агентами описывает похожие шаги в контексте агентов‑помощников.

---

Интеграция с TrueNAS и ZFS

С практической точки зрения интеграция выглядит так: плагин получает доступ к API TrueNAS (если используется SCALE) или к системным утилитам (если SCALE — Linux‑база). Ниже пример плагина, который периодически проверяет состояние ZFS‑пула и отправляет метрики в Harness.

manifest.yaml (для TrueNAS SCALE):

yamlКопировать
name: zfs_monitor
version: "1.0"
description: Плагин, отслеживающий состояние ZFS‑пулов и отправляющий метрики в Harness.
author: "Алексей Кузнецов"
entrypoint: ["python", "zfs_handler.py"]
schedule: "*/5 * * * *"   # каждые 5 минут

zfs_handler.py:

pythonКопировать
import subprocess
import json
import requests
import os

HARNESS_URL = os.getenv("HARNESS_URL")
API_TOKEN   = os.getenv("HARNESS_TOKEN")

def get_zpool_status():
    # Выполняем zpool status в JSON‑формате
    result = subprocess.run(
        ["zpool", "status", "-J"],
        capture_output=True,
        text=True,
        check=True,
    )
    return json.loads(result.stdout)

def send_metric(metric_name, value):
    url = f"{HARNESS_URL}/metrics"
    payload = {"name": metric_name, "value": value}
    headers = {"Authorization": f"Bearer {API_TOKEN}"}
    requests.post(url, json=payload, headers=headers)

def main():
    data = get_zpool_status()
    for pool in data["pools"]:
        state = pool["state"]
        if state != "ONLINE":
            # отправляем тревогу, если пул не в онлайн‑режиме
            send_metric("zfs_pool_state", 0)
        else:
            # отправляем показатель здоровья пула
            capacity = pool["capacity"]
            send_metric("zfs_pool_capacity", capacity)

if __name__ == "__main__":
    main()

Развёртывание (пример для Docker‑контейнера на TrueNAS SCALE):

bashКопировать
docker build -t zfs_monitor:latest .
docker run -d \
  --name zfs_monitor \
  -e HARNESS_URL="https://harness.myhome.lan" \
  -e HARNESS_TOKEN="y token" \
  -v /etc/zfs:/etc/zfs:ro \
  zfs_monitor:latest

Плагин будет запускаться по расписанию, собирать данные zpool status и передавать их в Harness. В дашборде Harness можно построить график «Health of ZFS pools», а при переходе в состояние DEGRADED получить автоматическое оповещение.

Подробнее о работе с TrueNAS API в статье Simantic: симуляция прошивок для AI-агентов — подход схож, только вместо прошивок мы опрашиваем состояние пулов.

---

Во-первых, создав базовый плагин, вы получаете шаблон, который легко адаптировать под любые задачи. Во‑вторых, интеграция с TrueNAS и ZFS демонстрирует, как использовать системные утилиты и API для получения реальных метрик. Если понадобится расширить функциональность — добавляйте новые команды в handler.py, а манифест обновляйте без перезапуска всего сервиса. Такой подход обеспечивает предсказуемость и упрощает поддержку как в домашней лаборатории, так и в продакшн‑окружениях.

Лучшие практики и рекомендации

### Мониторинг и логирование

Мониторинг — ключевой элемент обеспечения предсказуемости работы AI‑агентов.
В своей практике я использую сочетание Prometheus для метрик, Grafana для визуализации и Loki для централизованного сбора логов.

Метрики

yamlКопировать
# prometheus.yml (отрывок)
scrape_configs:
  - job_name: 'harness-agent'
    static_configs:
      - targets: ['harness-agent:9090']
    metrics_path: '/metrics'
    relabel_configs:
      - source_labels: [__address__]
        target_label: instance
        replacement: '{{ $labels.instance }}'

Alert‑правила (пример):

yamlКопировать
# alerts.yaml
groups:
  - name: harness.rules
    rules:
      - alert: HighLatency
        expr: avg(http_request_duration_seconds{job="harness-agent"}) > 0.5
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "Задержка запросов превышает 500 мс"
          description: "Среднее время отклика > 0.5 с за последние 2 минуты."

Логи
Для централизации логов удобно отправлять вывод агента в Loki через Promtail. Пример docker‑compose:

yamlКопировать
# docker-compose.yml (часть сервиса)
services:
  harness-agent:
    image: myorg/harness-agent:latest
    ports:
      - "9090:9090"
    volumes:
      - ./logs:/app/logs
    environment:
      - LOKI_URL=http://loki:3100/loki/api/v1/push
  promtail:
    image: grafana/promtail:latest
    volumes:
      - /var/log:/var/log
      - ./loki-config.yaml:/etc/promtail/config.yml
    command: -config.file=/etc/promtail/config.yml

Практические рекомендации

• Собирайте только нужные метрики – лишний поток данных усложняет алертинг.
• Настраивайте уровни тревоги — на этапе разработки задайте пороги, а не после появления инцидентов.
• Храните логи в течение 30 дней — это достаточно для расследования, но не приводит к росту хранилища.

Подробные практики из реального опыта см. в статье «Навыки реальных инженеров: практические практики из .agents» .

---

### Автоматизация деплоя

Автоматизация — это не просто «запуск скрипта», а полностью проверенный процесс, который гарантирует одинаковую предсказуемость среды на всех нодах.

Docker Compose используется для локального тестирования и небольших кластеров. Пример docker‑compose.yml для композиции из нескольких плагинов:

yamlКопировать
# docker-compose.yml (полный пример)
version: "3.8"

services:
  harness-core:
    image: myorg/harness-core:latest
    ports:
      - "8080:8080"
    environment:
      - DB_URL=postgres://user:pass@db:5432/harness
    depends_on:
      - db

  plugin-a:
    image: myorg/plugin-a:latest
    environment:
      - HARNESS_URL=http://harness-core:8080
    depends_on:
      - harness-core

  plugin-b:
    image: myorg/plugin-b:latest
    environment:
      - HARNESS_URL=http://harness-core:8080
    depends_on:
      - harness-core

  db:
    image: postgres:15
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

CI/CD — автоматический пайплайн, который собирает образ, пушит его в реестр и обновляет манифест в кластере. Пример GitHub Actions:

yamlКопировать
# .github/workflows/deploy.yml
name: Deploy Harness Plugin

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build image
        run: docker build -t myorg/harness-plugin-a:${{ github.sha }} .
      - name: Push image
        run: docker push myorg/harness-plugin-a:${{ github.sha }}
  deploy:
    needs: build
    runs-on: размещение на домашних серверах   # ваш сервер с Docker
    steps:
      - name: Update compose
        run: |
          sed -i "s|myorg/harness-plugin-a:latest|myorg/harness-plugin-a:${{ github.sha }}|" docker-compose.yml
      - name: Restart service
        run: docker compose up -d

Kubernetes — для больших сред удобно использовать Helm‑чарты. Минимальный пример Chart.yaml:

yamlКопировать
apiVersion: v2
name: harness-plugin-a
description: Helm chart for Harness plugin A
type: application
version: 0.1.0
appVersion: "1.0"

yamlКопировать
# values.yaml
replicaCount: 3

image:
  repository: myorg/harness-plugin-a
  tag: "1.0"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

Рекомендации

• Не используйте GUI‑инструменты для деплоя — все операции фиксируются в коде, что упрощает аудит.
• Включайте health‑check в манифесте, чтобы система автоматически откатывала плохие версии.
• Документируйте каждый шаг — описание переменных окружения, сетевых зависимостей и порядка запуска.

Подробный набор навыков для работы с AI‑агентами можно посмотреть в .

---

Alexey Kuznetsov
Системный инженер, 12 лет опыта в построении надёжных инфраструктур.

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

Как DeepSeek Harness отличается от традиционных подходов к созданию AI‑агентов?

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

Что такое плагин в DeepSeek Harness и как он работает?

Плагин – это отдельный модуль, реализующий один well‑defined интерфейс (например, загрузку данных, трансформацию или отправку запросов). Он описан в файле plugin.yaml, где указывается имя, версия, описание, entrypoint и зависимости. Код плагина наследует базовый класс PluginBase и реализует методы, такие как load, transform или send. Агент получает плагин по имени и вызывает его в рамках своей цепочки шагов.

Как добавить новый плагин в уже существующий агент без изменения кода агента?

Нужно лишь добавить описание нового плагина в файл plugin.yaml и указать его имя в секции plugin конкретного шага агента. После перезапуска или перезагрузки конфигурации Harness автоматически подхватит новый плагин, не требуя изменения кода агента. Это позволяет расширять функциональность системы «на лету», сохраняя предсказуемость и изоляцию компонентов.

Какие типы шагов (steps) поддерживает DeepSeek Harness и как они взаимодействуют с плагинами?

DeepSeek Harness поддерживает как обычные скрипты, так и плагины в виде шагов. Каждый шаг имеет фиксированную точку входа (например, load, transform, send) и может принимать в качестве аргументов имя плагина, которое будет инстанцировано и выполнено. Плагин предоставляет внешний доступ к данным или сервисам, а скрипт‑шаг использует полученные результаты для дальнейшей обработки, создавая гибкую и расширяемую цепочку обработки.

Где хранить конфигурацию плагинов и как обеспечить их версионирование?

Конфигурация плагинов лучше размещать в отдельном каталоге проекта, например plugins/, где каждый плагин имеет свой файл plugin.yaml. Версионирование достигается через указание версии в этом файле (version: "1.0") и хранение файлов в системе контроля версий (Git). При обновлении плагина создаётся новая версия файла, а старые версии сохраняются, что позволяет откатываться при необходимости.