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

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

DeepSeek Harness превращает любую задачу в плагин, объединяя AI‑агентов, CI/CD и инфраструктуру. Примеры и рекомендации для AI‑агентов.

Принцип «Все как плагин» в DeepSeek Harness

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

Как объявляются плагины

Во-первых, плагин описывается в манифесте YAML, где указываются метаданные — название, версия, список зависимостей и точка входа. Пример манифеста для плагина, который запускает агент‑проверку конфигураций Nginx:

yamlКопировать
name: nginx-config-check
version: "1.0.0"
description: "Проверка корректности конфигураций Nginx через AI‑агент"
entrypoint: "python main.py"
dependencies:
  - "deepseek-harness-core>=2.3"
  - "pyyaml>=6.0"

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

bashКопировать
dsh plugin add ./plugins/nginx-config-check.yaml

После добавления плагин появляется в каталоге ~/.local/share/dsh/plugins/ и становится доступным через CLI‑команду dsh run nginx-config-check.

Практический пример из статьи «Навыки реальных инженеров: практические практики из .agents» показывает, как в реальном проекте плагин был использован для автоматической валидации Docker‑Compose файлов, что повысило предсказуемость сборки статья.

Схема взаимодействия между агентами и сервисами

Схема взаимодействия построена на трёх уровнях:

1. Агент — выполняет логику, описанную в коде плагина, и взаимодействует с Harness через API.
2. Harness — оркестрирует запуск агентов, передаёт им переменные окружения и собирает результаты в artefacts.
3. Сервис — предоставляет API или CLI‑интерфейс, который агент вызывает для выполнения конкретных задач (например, проверка портов, деплой контейнеров).

Пример конфигурации Harness (файл harness.yaml), которая связывает агент nginx-check с сервисом nginx:

tomlКопировать
[agents]
  nginx-check = {
    image = "python:3.11-slim",
    command = "python /app/main.py",
    environment = {
      "NGINX_CONF_PATH" = "/etc/nginx/conf.d"
    }
  }

[services]
  nginx = {
    url = "http://localhost:80",
    token = "s3cr3t-token"
  }

[workflow]
  steps = [
    "run nginx-check",
    "notify Slack"
  ]

В этом workflow агент nginx-check запускается первым, после чего при успешном завершении отправляется уведомление в Slack.

Если мы посмотрим на схему взаимодействия, видно, что агент получает конфигурацию через переменную NGINX_CONF_PATH, а затем использует curl или nginx -t для проверки. Пример кода внутри main.py:

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

def check_config(path):
    result = subprocess.run(
        ["nginx", "-t", "-c", path],
        capture_output=True,
        text=True
    )
    if result.returncode != 0:
        raise RuntimeError(f"Nginx config error: {result.stderr}")
    print("Конфигурация Nginx валидна")

if __name__ == "__main__":
    conf_path = os.getenv("NGINX_CONF_PATH")
    check_config(conf_path)

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

Для более детального описания схемы взаимодействия см. материал «Simantic: симуляция прошивок для AI‑агентов» здесь, где показано, как симуляция окружений позволяет тестировать плагины в изолированных контейнерах.

Таким образом, объявление плагина и его интеграция в существующую инфраструктуру реализуются через стандартизированные манифесты и конфигурационные файлы, а взаимодействие между агентами и сервисами обеспечивается чёткой схемой, описанной в harness.yaml. Это позволяет построить надёжные и предсказуемые пайплайны, где AI‑агенты работают как обычные сервисы в CI/CD‑процессе.

Компоненты и API DeepSeek Harness

Компоненты и API DeepSeek Harness

### Модуль core: базовый интерфейс

Во-первых, модуль core задаёт унифицированный контракт для всех плагинов. Он содержит базовый тип HarnessPlugin, набор методов жизненного цикла и описание параметров, передаваемых в каждый вызов.

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

goКопировать
package core

import "context"

// HarnessPlugin – базовый интерфейс плагина.
type HarnessPlugin interface {
    // Name возвращает уникальное имя плагина, используемое в конфигурации.
    Name() string

    // Run выполняет плагин в контексте текущего задания.
    // Параметры содержат данные, полученные от Harness (например, переменные окружения, артефакты).
    Run(ctx context.Context, params *PluginParams) error
}

// PluginParams – структура с параметрами, передаваемыми в плагин.
type PluginParams struct {
    // ID задания, уникальный для текущего запуска.
    JobID string

    // Параметры, специфичные для конкретного плагина.
    // Например, URL API, пути к файлам, флаги конфигурации.
    Config map[string]interface{}
}

С практической точки зрения такой подход позволяет:

• Явно описать, какие данные нужны плагину, без «магических» полей.
• Упростить тестирование – можно передавать мок‑контекст и проверять, что Run вызывается с ожидаемыми параметрами.
• Позволить использовать один и тот же механизм для разных сред (локальная машина, CI‑провайдер, облачная функция).

Для подключения плагина в конфигурацию Harness используется простой YAML‑файл, где указывается имя, путь к исполняемому файлу и параметры конфигурации. Пример:

yamlКопировать
plugins:
  - name: "data-fetcher"
    entrypoint: "github.com/example/data-fetcher"
    config:
      api_url: "https://api.example.com"
      timeout_sec: 30

После загрузки конфигурации Harness автоматически создаёт экземпляр HarnessPlugin и вызывает его Run в нужном контексте.

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

### Расширения: примеры плагинов для AI‑агентов

Расширения – это готовые плагины, которые решают типичные задачи AI‑агентов: получение данных, деплой моделей, анализ логов, взаимодействие с внешними сервисами. Ниже рассмотрены три реальных примера, которые уже используются в продакшене.

1. Плагин «data-fetcher» – собирает данные из внешнего API, преобразует их в удобный формат и сохраняет в объектное хранилище (например, MinIO или S3).

bashКопировать
dsh plugin run data-fetcher --config data-fetcher.yaml

yamlКопировать
plugins:
  - name: "data-fetcher"
    entrypoint: "github.com/example/data-fetcher"
    config:
      api_url: "https://api.example.com/v1/records"
      dest_bucket: "my-bucket"
      dest_prefix: "fetcher/"
      auth_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6..."

2. Плагин «model-deployer» – автоматизирует развертывание моделей в Kubernetes (k3s, Rancher) через Helm‑чарты.

bashКопировать
dsh plugin run model-deployer --config model-deployer.yaml

yamlКопировать
plugins:
  - name: "model-deployer"
    entrypoint: "github.com/example/model-deployer"
    config:
      namespace: "ai-services"
      chart_path: "charts/model-1.2.0.tgz"
      values_file: "values-prod.yaml"
      image_tag: "registry.example.com/ai/model:1.2.0"

3. Плагин «log-analyzer» – парсит логи Prometheus‑compatible, ищет ошибки, формирует отчёт и отправляет его в Slack.

bashКопировать
dsh plugin run log-analyzer --config log-analyzer.yaml

yamlКопировать
plugins:
  - name: "log-analyzer"
    entrypoint: "github.com/example/log-analyzer"
    config:
      log_dir: "/var/log/harness"
      error_pattern: "ERROR|CRITICAL"
      slack_webhook: "https://hooks.slack.com/services/XXX/YYY/ZZZ"

Ссылка: практические рекомендации по созданию и использованию плагинов – Навыки реальных инженеров: практические практики из .agents.

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

Ссылка: Набор навыков для работы с AI-агентами – полезные приёмы и шаблоны.

Справедливости ради, если требуется симуляция взаимодействия агентов с инфраструктурой, стоит обратить внимание на проект Simantic, где показана модель симуляции прошивок для AI‑агентов.

Ссылка: Simantic: симуляция прошивок для AI-агентов.

Справедливости ради, для автономной разработки на Rust, где часто используют собственные плагины, полезен пример из Claw-Code.

Ссылка: Автономная разработка на Rust с помощью Claw-Code.

Итого, модуль core задаёт чёткий контракт, а готовые расширения позволяют сразу решать типовые задачи AI‑агентов без написания кода с нуля. Всё, что остаётся – подобрать подходящий плагин, настроить параметры и включить его в pipeline CI/CD.

Если понадобится более детальная информация о конкретных плагинах – см. ссылки выше, а также официальную документацию DeepSeek Harness в разделе API Reference.

Применение в CI/CD и инфраструктуре

Применение в CI/CD и инфраструктуре

DeepSeek Harness удобно встраивается в существующие пайплайны CI/CD и в инфраструктурные решения. Ниже показаны типичные сценарии, которые позволяют превратить любой AI‑агент в самостоятельный плагин, управляемый через GitHub Actions, Proxmox VE и Kubernetes.

Интеграция с GitHub Actions

В GitHub Actions удобно использовать готовый плагин dsh-plugin, который реагирует на события workflow_dispatch и запускает агентов DeepSeek Harness. Пример workflow выглядит так:

yamlКопировать
name: DeepSeek Harness CI

on:
  workflow_dispatch:
    inputs:
      agent_name:
        description: 'Имя AI‑агента'
        required: true

jobs:
  run-harness:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install DeepSeek Harness
        run: |
          curl -sSL https://example.com/dsh-plugin.sh | bash -s install

      - name: Configure Harness plugin
        env:
          DSH_AGENT: ${{ github.event.inputs.agent_name }}
        run: |
          dsh config set --agent "$DSH_AGENT" --mode auto

      - name: Execute agent task
        run: |
          dsh run --agent "$DSH_AGENT" --task "analyze-logs" \
            --output /tmp/result.json
        # При необходимости можно добавить аллерты через Alertmanager

Почему так?

• Проверка окружения – сначала убеждаемся, что порт 443 свободен (curl -s http://localhost:443).
• Установка плагина – скрипт автоматически добавляет dsh в PATH и инициализирует конфигурацию.
• Запуск задачи – агент получает входные параметры через переменные окружения, а результат сохраняется в файл, который дальше можно передать в downstream‑job.

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

Развёртывание в Proxmox и Kubernetes

DeepSeek Harness может работать как часть инфраструктурного стека, управляя виртуальными машинами в Proxmox VE и контейнерами в Kubernetes. Ниже пример конфигурации для Proxmox, где агент разворачивается в отдельном LXC‑контейнере, а затем подключается к стораджу TrueNAS.

bashКопировать
# 1. Создаём LXC‑контейнер
pct create 101 ubuntu:22.04 --memory 4096 --swap 1024 --rootfs local-lvm:20G

# 2. Устанавливаем Docker и dsh‑plugin внутри контейнера
pct enter 101 -- bash -c "
  apt-get update && apt-get install -y docker.io curl
  curl -sSL https://example.com/dsh-plugin.sh | bash -s install
  dsh config set --mode server
"

# 3. Запускаем контейнер и подключаем TrueNAS NFS‑share
pct start 101
pct exec 101 -- bash -c "
  echo '10.0.0.5:/data  /data  nfs  rw,hard,intr  0 0' >> /etc/fstab
  mount -a
  dsh run --agent my-agent --task 'sync-photos' --output /data/backup
"

Для Kubernetes используется обычный Deployment с образом deepseek/harness-agent. Пример манифеста:

yamlКопировать
apiVersion: apps/v1
kind: Deployment
metadata:
  name: harness-agent
spec:
  replicas: 2
  selector:
    matchLabels:
      app: harness-agent
  template:
    metadata:
      labels:
        app: harness-agent
    spec:
      containers:
        - name: agent
          image: deepseek/harness-agent:latest
          env:
            - name: DSH_AGENT
              value: "analyzer"
          command: ["dsh", "run", "--agent", "$DSH_AGENT", "--task", "process-data"]
          volumeMounts:
            - name: nfs-share
              mountPath: /data
      volumes:
        - name: nfs-share
          nfs:
            server: 10.0.0.5
            path: /data
            readOnly: false

Ключевые моменты

• Predictable configuration – все параметры задаются через переменные и манифесты, а не «на коленке».
• Мониторинг – после запуска можно добавить Prometheus‑exporter, чтобы отследить статус задач.
• Автоматическое обновление – при изменении конфигурации dsh автоматически перезапускает агент, что обеспечивает предсказуемость.

См. Автономная разработка на Rust с помощью Claw-Code для примеров написания собственного агента, если стандартные шаблоны не подходят.

Таким образом, DeepSeek Harness соединяет AI‑агентов с CI/CD и инфраструктурой, делая процесс развертывания предсказуемым и воспроизводимым.

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

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

Тестирование — первый уровень уверенности в том, что плагин работает корректно в изолированном окружении. На практике удобно комбинировать unit‑тесты, которые проверяют отдельные функции, и интеграционные тесты, запускающие плагин в контейнере вместе с harness‑CLI.

Unit‑тесты.
Для изоляции используйте обычный pytest (или unittest). Пример теста для функции, возвращающей конфигурацию плагина:

pythonКопировать
# tests/test_plugin.py
import plugin_logic  # ваш модуль с бизнес‑логикой

def test_generate_config():
    result = plugin_logic.generate_config(
        name="example",
        version="1.0.0",
        image="nginx:1.25"
    )
    assert result["image"] == "nginx:1.25"
    assert result["name"] == "example"

Запуск происходит в виртуальном окружении, без необходимости поднимать весь стек harness‑CI.

Интеграционные тесты.
Для проверки взаимодействия плагина с harness‑CLI удобно использовать Docker‑Compose. Пример docker-compose.yml, который поднимает harness‑сервер и ваш плагин:

yamlКопировать
# docker-compose.yml
version: "3.8"
services:
  harness:
    image: harness/agent:latest
    ports:
      - "8080:8080"
    environment:
      - HARNESS_API_KEY=test_key
  plugin:
    build: ./my_plugin   # Dockerfile, который копирует ваш код и зависимостки
    depends_on:
      - harness
    environment:
      - HARNESS_API_KEY=test_key

Запуск:

bashКопировать
docker compose up -d
# После поднятия отправляем запрос через CLI
harness plugin run --url http://localhost:8080 --plugin my_plugin

Если тест проходит, значит плагин успешно взаимодействует с API harness‑а.

CI‑интеграция.
В GitHub Actions (или GitLab CI) добавьте шаг, который собирает образ плагина, запускает docker compose up и выполняет тесты. Пример шага для GitHub Actions:

yamlКопировать
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build plugin image
        run: docker build -t my_plugin ./my_plugin
      - name: Run integration tests
        run: |
          docker compose up -d
          sleep 10   # ждём старта harness
          pytest tests/
          docker compose down

Ссылка на Навыки реальных инженеров: практические практики из .agents описывает подробный процесс организации тестов в CI, что можно адаптировать под ваш проект.

---

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

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

Экспорт метрик.
Harness‑плагин может expose метрики в формате Prometheus через HTTP‑эндпоинт /metrics. Пример кода на Go (используется клиент promhttp):

goКопировать
package main

import (
    "net/http"
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promhttp"
)

var requestCounter = prometheus.NewCounter(prometheus.CounterOpts{
    Name: "harness_plugin_requests_total",
    Help: "Total number of requests processed by the plugin",
})

func init() {
    prometheus.MustRegister(requestCounter)
}

func handler(w http.ResponseWriter, r *http.Request) {
    requestCounter.Inc()
    // ваш основной обработчик...
    w.Write([]byte("ok"))
}

func main() {
    http.HandleFunc("/metrics", handler)
    http.Handle("/metrics", promhttp.Handler())
    http.ListenAndServe(":9090", nil)
}

В harness.yaml указываем, что плагин должен слушать порт 9090:

yamlКопировать
plugins:
  - name: my_plugin
    image: my_plugin:latest
    ports:
      - "9090:9090"

После запуска в Prometheus добавляем запрос:

scrape_configs:
  - job_name: 'harness_plugin'
    static_configs:
      - targets: ['host.docker.internal:9090']

Логирование.
Harness поддерживает отправку логов в Loki через стандартный syslog‑формат. Пример конфигурации в docker-compose.yml:

yamlКопировать
  plugin:
    image: my_plugin:latest
    environment:
      - LOG_LEVEL=info
    logging:
      driver: "loki"
      options:
        loki-url: "http://loki:3100/api/loki/api/v1/push"

В коде используйте структурированный вывод, например, через logrus в Go или log в Python, чтобы каждый запрос имел поле plugin_name, request_id и status.

Алертинг.
В Alertmanager создайте правило, которое срабатывает, если harness_plugin_requests_total превышает порог за 5‑минутный период. Пример правила:

yamlКопировать
groups:
  - name: harness.rules
    rules:
      - alert: HighPluginRequestRate
        expr: increase(harness_plugin_requests_total[5m]) > 1000
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Слишком высокий поток запросов к плагину"
          description: "Текущий рост запросов за 5 минут: {{ $value }}"

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

• Предсказуемость: фиксируйте версии зависимостей в requirements.txt (Python) или go.mod. Это избавит от «плохих» сюрпризов при пересборке.
• Тестируемость: держите конфигурацию плагина в отдельном файле (config.yaml), а не в коде. Пример:

yamlКопировать
# config.yaml
plugin:
  name: "example"
  version: "1.2.0"
  image: "nginx:1.25"

• Обратная связь: включайте в логирование пользовательские теги (user_id, tenant) — это упрощает поиск проблем в Loki.

См. подробнее в Набор навыков для работы с AI-агентами, где описаны подходы к мониторингу и логированию в реальных проектах.

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