DeepSeek Harness: всё как плагин в DeepSeek
Статья рассказывает об архитектуре DeepSeek Harness, где каждый компонент — плагин. Рассматриваются преимущества, настройки и интеграция.
Введение
Введение
Обзор
DeepSeek Harness — это плагинная архитектура для AI-агентов, которая позволяет гибко собирать рабочие конфигурации из отдельных компонентов. Представьте это как модульный конструктор: каждый компонент — это самостоятельный плагин, который можно подключить, отключить или заменить без переписывания всего стека.
С практической точки зрения, это решение устраняет проблему "монолитных" AI-стеков, где все компоненты жестко связаны. С помощью Harness вы получаете предсказуемую конфигурацию: каждый плагин выполняет одну конкретную задачу, а взаимодействие между ними описано в конфигурационном файле.
yaml# dsh.yaml — базовая конфигурация DeepSeek Harness
version: "1.0"
plugins:
- name: "cordis"
version: "2.1.0"
enabled: true
config:
endpoint: "ws://localhost:8080"
model: "deepseek-cordis"
- name: "dsh-plugin"
version: "0.9.3"
enabled: true
config:
log_level: "info"
cache_size: "512MB"
Преимущество в предсказуемости проявляется при масштабировании: добавление нового агента — это просто запись нового плагина в конфигурационном файле, а не перестройка всего стека. Это позволяет быстро тестировать гипотезы и откатываться к стабильной конфигурации, если что-то пошло не так.
Для тех, кто знаком с контейнерными подходами, это похоже на Docker Compose: каждый сервис (плагин) имеет свои зависимости, а оркестрацией управляет общий конфигурационный файл.
Почему это важно
В современных AI-решениях часто встречаются проблемы с жесткой связанностью компонентов: изменить один плагин значит рисковать стабильностью всего стека. DeepSeek Harness решает эту проблему, предоставляя:
- Модульность: каждый компонент — автономный плагин
- Предсказуемость: конфигурация описана явно, а не скрыта в коде
- Гибкость: легко заменить или обновить отдельные компоненты
- Тестирование: можно протестировать новый плагин без влияния на остальные
Быстрый старт
bash# Установка DeepSeek Harness
pip install deepseek-harness
# Инициализация нового проекта
dsh init my-project
cd my-project
# Добавление плагина Cordis для работы с графами знаний
dsh add cordis --version 2.1.0
# Включение AI-агента с плагином
dsh enable dsh-plugin
Ключевые концепции
- Плагин — это автономный компонент, который предоставляет конкретную функциональность
- Хаб — центр управления плагинами, который отслеживает зависимости и управляет жизненным циклом
- Конфигурация — YAML-файл, в котором описаны используемые плагины и их параметры
С чего начать
- Определите, какие плагины вам нужны для конкретной задачи
- Создайте конфигурационный файл
dsh.yaml - Подключите необходимые плагины с помощью
dsh add - Настройте параметры каждого плагина
- Запустите агент с помощью
dsh run
Для более глубокого изучения архитектуры рекомендуем:
- Graphify: Создание знаний из кода в виде графов
- Навыки реальных инженеров: коллекция из .agents
- DeepSeek Harness: Плагинная архитектура для AI-агентов
Если вам нужен практический пример интеграции с другими инструментами, посмотрите:
Архитектура плагинов
Архитектура плагинов
DeepSeek Harness строится по принципу «ядро плюс плагины». Ядро отвечает только за жизненный цикл: загружает манифесты, разрешает зависимости и маршрутизирует события между компонентами. Вся бизнес-логика — работа с LLM, доступ к файловой системе, вывод в терминал — вынесена в отдельные плагины. Такой подход даёт предсказуемость: если что-то ломается, вы знаете точно, в каком плагине искать проблему, а не копаетесь в монолите.
Компоненты
С практической точки зрения архитектура состоит из четырёх частей.
Ядро (dsh-core) — загрузчик плагинов и шина событий. Оно не знает, что такое «агент» или «ревью кода», оно только выполняет контракт плагина: инициализация, запуск, остановка, передача сообщений.
Реестр плагинов — локальный каталог с манифестами. Каждый плагин описывается файлом dsh-plugin.yaml, где указаны имя, версия, точка входа и зависимости.
Конфигурационный слой — YAML-файлы и переменные окружения. Я рекомендую держать конфиг рядом с кодом плагина, а не размазывать его по системе.
CLI-интерфейс (dsh) — точка входа для управления. Через него устанавливают, включают и отключают плагины.
Пример манифеста плагина cordis:
yamlname: cordis
version: "1.2.0"
type: agent
entrypoint: cordis.plugin:DeepSeekAgent
api_version: v1
depends:
- dsh-core >= 0.9.0
- dsh-llm-provider >= 0.5.0
permissions:
- fs.read
- network.outbound
Посмотреть установленные плагины и их статус можно командой:
bash# Проверяем, какие плагины активны и какая версия ядра
dsh plugin list
Пример вывода:
NAME VERSION STATUS TYPE
cordis 1.2.0 active agent
dsh-llm 0.5.1 active provider
dsh-fs 0.3.0 active storage
Если вы пишете собственный плагин, начните с манифеста — без него ядро не загрузит модуль, даже если код написан верно.
Типы плагинов
Все плагины делятся на четыре категории по назначению.
Агентные плагины (ai-agents) реализуют логику конкретного агента: общаются с моделью, вызывают инструменты, принимают решения. Пример — плагин cordis для код-ревью или автоматизации задач.
Интеграционные плагины подключают внешние системы: базы данных, хранилища, API. Они не принимают решений, только передают данные между агентом и ресурсом.
Интерфейсные плагины отвечают за то, как пользователь взаимодействует с Harness: CLI, HTTP API, веб-интерфейс.
Посредники (middleware) — сквозная логика: логирование, аутентификация, ограничение частоты запросов. Они обёртывают вызовы между компонентами.
Пример конфигурации агента с инструментами:
yamlagents:
- name: code-reviewer
plugin: cordis
model: deepseek-chat
temperature: 0,2
system_prompt: |
Ты — старший код-ревьюер. Проверяй pull request на соответствие
стандарту кодирования и предлагай конкретные правки.
tools:
- name: grep
plugin: dsh-fs
- name: read_file
plugin: dsh-fs
Пример подключения посредников для логирования и авторизации:
yamlmiddleware:
- plugin: dsh-logger
level: info
output: journald
- plugin: dsh-auth
strategy: api_key
header: X-DSH-Token
Если мы посмотрим на реальную практику, агентные плагины чаще всего становятся точкой расширения. Например, через плагин cordis можно подключить анализ кода, а для построения графов зависимостей удобно использовать Graphify: Создание знаний из кода в виде графов — он тоже встраивается как плагин и передаёт данные в общую шину Harness.
Коллекцию готовых навыков для агентов можно найти в Навыки реальных инженеров: коллекция из .agents — полезно, если не хотите писать каждый инструмент с нуля.
Общая концепция плагинной архитектуры описана в DeepSeek Harness: Плагинная архитектура для AI-агентов.
Использование плагинов
Использование плагинов
Настройка
Плагины в DeepSeek Harness подключаются через один файл манифеста — dsh.yaml. Это не GUI с галочками, а обычный текстовый конфиг, который правится вручную. Я предпочитаю именно такой подход: когда конфиг лежит в репозитории, его можно версионировать, ревьюить и откатывать.
Вот минимальный пример манифеста с двумя плагинами — cordis для сбора контекста и dsh-plugin для выполнения задач:
yaml# dsh.yaml
version: "1"
plugins:
- name: cordis
source: local
path: ./plugins/cordis
config:
index_path: /var/lib/dsh/cordis/index
embed_model: bge-m3
chunk_size: 512
- name: dsh-plugin
source: registry
version: "0.4.1"
config:
endpoint: http://localhost:8080
timeout: 30
retry_count: 3
После правки файла плагины нужно загрузить в рантайм. Команда dsh plugin load читает манифест и инициализирует каждый компонент:
bashdsh plugin load --config ./dsh.yaml
Если плагин тянет зависимости из внешнего реестра, убедитесь, что у сервера есть доступ к сети и открыт порт 443. В противном случае загрузка упадёт с ошибкой таймаута, и отлаживать придётся сетевой слой, а не сам плагин.
Примеры интеграции
Плагины взаимодействуют между собой через общую шину событий. Один плагин публикует событие, другой — подписывается и обрабатывает. Это напоминает обмен сообщениями в очередях: отправитель не знает, кто получит сообщение, а получатель не знает, кто его прислал.
Ниже пример интеграции cordis с dsh-plugin. Плагин cordis индексирует код репозитория и кладёт эмбеддинги в векторное хранилище. Когда агенту нужно ответить на вопрос по кодовой базе, он запрашивает контекст у cordis, а затем передаёт его в dsh-plugin для генерации ответа.
Конфиг cordis с путями к индексу:
yaml# plugins/cordis/config.yaml
index:
path: /var/lib/dsh/cordis/index
rebuild_interval: "1h"
watch_paths:
- /opt/app/src
- /opt/app/lib
embedding:
model: bge-m3
device: cuda
batch_size: 32
Запуск индексации вручную:
bashdsh plugin exec cordis --action index --path /opt/app/src
Теперь пример вызова dsh-plugin с контекстом, собранным cordis. Агент передаёт запрос и ссылку на индекс, плагин возвращает сгенерированный ответ:
bashdsh plugin exec dsh-plugin \
--query "Как работает аутентификация в модуле billing?" \
--context-source cordis \
--index /var/lib/dsh/cordis/index
Если нужно интегрировать свой плагин, достаточно реализовать интерфейс dsh.Plugin и зарегистрировать его в манифесте. Ниже скелет на Python — точка входа, метод handle и регистрация в реестре:
python# plugins/my_plugin/__init__.py
from dsh import Plugin, PluginContext, Event
class MyPlugin(Plugin):
name = "my_plugin"
def handle(self, event: Event, ctx: PluginContext) -> Event:
# Обработка события от другого плагина
return Event(
type="response",
payload={"result": "ok"}
)
def register():
return MyPlugin()
После добавления плагина в dsh.yaml он станет доступен для вызова через dsh plugin exec my_plugin. Предсказуемость конфигурации здесь ключевая: если плагин описан в манифесте, он будет вести себя одинаково на разработке, стейджинге и продакшене.
Связанные материалы:
- DeepSeek Harness: Плагинная архитектура для AI-агентов
- Навыки реальных инженеров: коллекция из .agents
- Graphify: Создание знаний из кода в виде графов
FAQ
Как добавить плагин?
Для добавления нового плагина в DeepSeek Harness выполните следующие шаги:
bash# 1. Создайте директорию плагина
mkdir -p ~/.config/deepseek/plugins/my-plugin
# 2. Добавьте файл конфигурации плагина
cat > ~/.config/deepseek/plugins/my-plugin/config.yaml << 'EOF'
name: my-plugin
version: 1.0.0
description: "Плагин для обработки специальных запросов"
entry_point: main.py
author: Алексей Кузнецов
EOF
# 3. Создайте основной файл плагина
cat > ~/.config/deepseek/plugins/my-plugin/main.py << 'EOF'
import dsh
from dsh.api import Plugin
class MyPlugin(Plugin):
def __init__(self):
super().__init__(
name="my-plugin",
version="1.0.0",
description="Обработка специальных запросов"
)
def handle_request(self, request):
# Реализация обработки запроса
if request.type == "special":
return self.process_special(request.data)
return None
def process_special(self, data):
# Логика обработки специальных данных
return {"result": "processed", "data": data}
EOF
# 4. Зарегистрируйте плагин
dsh plugin register ~/.config/deepseek/plugins/my-plugin/config.yaml
Пример использования:
pythonfrom dsh.api import PluginManager
# Инициализируйте плагин-менеджер
manager = PluginManager()
# Загрузите все доступные плагины
manager.load_plugins()
# Используйте плагин
result = manager.execute_plugin("my-plugin", {"type": "special", "data": "test_data"})
Что такое точка расширения?
Точка расширения в DeepSeek Harness — это определенное место в архитектуре, где плагин может внедрить свою функциональность. Это аналог интерфейса API, но с более гибкой архитектурой.
Основные типы точек расширения:
python# 1. Точка обработки запросов
class RequestHandlerExtension:
def handle(self, request):
"""Обрабатывает входящие запросы"""
pass
# 2. Точка валидации данных
class ValidationExtension:
def validate(self, data):
"""Валидирует данные перед обработкой"""
pass
# 3. Точка логирования
class LoggingExtension:
def log(self, level, message, context=None):
"""Логирует события"""
pass
# 4. Точка мониторинга
class MonitoringExtension:
def metrics(self):
"""Возвращает метрики производительности"""
pass
Пример реализации точки расширения:
pythonfrom dsh.api import ExtensionPoint
class CustomExtensionPoint(ExtensionPoint):
def __init__(self):
super().__init__(
name="custom-processing",
description="Пользовательская точка обработки"
)
def register_handler(self, handler):
"""Регистрирует обработчик"""
self.handlers.append(handler)
def execute(self, data):
"""Выполняет обработку через все зарегистрированные обработчики"""
results = []
for handler in self.handlers:
result = handler(data)
results.append(result)
return results
Практический пример:
python# Создайте пользовательскую точку расширения
ext_point = CustomExtensionPoint()
# Зарегистрируйте обработчики
ext_point.register_handler(lambda x: x * 2)
ext_point.register_handler(lambda x: x + 10)
# Выполните обработку
result = ext_point.execute(5)
# Результат: [10, 15]
Где найти документацию?
Документация DeepSeek Harness доступна в нескольких местах:
Основная документация:
Руководства по интеграции:
Примеры и шаблоны:
Для разработчиков плагинов:
bash# Просмотр встроенной документации
dsh docs --plugins
# Генерация документации плагина
dsh docs generate ~/.config/deepseek/plugins/my-plugin/
# Просмотр примеров интеграции
dsh examples --all
Полезные ресурсы:
- GitHub репозиторий: DeepSeek/DeepSeek-Harness
- Discord сообщество: deepseek.dev/discord
- Telegram канал: t.me/deepseek_harness
Совет: Для быстрого старта ознакомьтесь с примером плагина в репозитории и используйте dsh init для создания нового плагина с базовой структурой.
Если у вас возникнут конкретные вопросы по интеграции или настройке, не стесняйтесь обращаться — я помогу решить любую задачу предсказуемым способом.
Часто задаваемые вопросы
Как DeepSeek Harness отличается от традиционных монолитных AI-стеков?
В монолитных стеках компоненты жёстко связаны, изменение одного может нарушить весь стек. В Harness каждый компонент — самостоятельный плагин, который можно подключить, отключить или заменить без переписывания кода. Это похоже на Docker Compose: каждый сервис описан отдельно, а оркестрация задана в конфигурационном файле. Такой подход обеспечивает предсказуемость и упрощает тестирование гипотез.
Какие типичные сценарии использования DeepSeek Harness?
Harness подходит для быстрого прототипирования новых AI-агентов: достаточно добавить плагин в конфигурацию dsh.yaml. Он также полезен при масштабировании existing-стека — добавление нового агента не требует перестройства всего стека. Ещё один сценарий — ротация моделей: плагин cordis можно заменить на другой без изменения остального стека. Это позволяет экспериментировать с конфигурациями и откатываться к стабильной версии.
Как обеспечивается предсказуемость конфигурации в Harness?
Предсказуемость достигается за счтом явного описания каждого плагина в YAML-файле: версия, параметры, зависимости. Конфигурация хранится отдельно от кода, что позволяет проверить её перед применением. Если что-то работает не так, можно вернуться к предыдущей версии файла, не перестраивая систему. Такой подход аналогичен управлению инфраструктурой через код: каждый шаг документирован и повторяем.
Какие инструменты подходят для разработки и отладки плагинов в Harness?
Для разработки плагинов удобны редакторы YAML, такие как VS Code с расширениями для YAML. Отладку помогает вести логирование через конфигурационный параметр log_level, а мониторинг — через Prometheus/Grafana, если плагин экспортирует метрики. Ещё полезен локальный тестовый стенд: можно запустить плагин на порту 8080 и проверить взаимодействие через curl. Такой же подход используется при отладке systemd-сервисов — сначала локально, потом в проде.