DeepSeek Harness: Плагинная архитектура для AI-инструментов
DeepSeek Harness превращает каждый компонент в плагин, позволяя гибко собирать AI-пайплайны с помощью простого интерфейса и расширяемой архитектуры.
Введение
Что такое DeepSeek Harness
DeepSeek Harness — это фреймворк для сборки AI-инструментов на основе плагинной архитектуры. Он превращает каждый компонент AI-системы в самостоятельный плагин, что позволяет гибко собирать пайплайны из готовых блоков без необходимости переписывать код.
Если вам когда-либо приходилось вручную подключать LLM, парсеры, инструменты или системы памяти, вы знаете, как быстро это становится похожим на интеграцию через "мостик". DeepSeek Harness решает эту проблему: каждый компонент становится плагином, который можно подключить одним параметром конфигурации.
Основные концепции
- Плагины как интерфейсы: Каждый плагин реализует единый контракт, что позволяет заменять реализации без изменения остального кода
- Конфигурация как код: Пайплайн описывается YAML-файлом, который можно хранить в Git и контролировать через CI/CD
- Расширяемость через плагины: Сообщество может писать плагины для специфических задач — от парсинга документов до интеграции с external API
- Типобезопасность: Плагины проверяются статически, что предотвращает ошибки на этапе выполнения
yaml# Пример конфигурации пайплайна
pipeline:
name: "Document Analyzer"
version: "1.0"
plugins:
- name: "DocumentLoader"
type: "input"
config:
source: "s3://bucket/docs/"
format: "pdf"
- name: "TextExtractor"
type: "processor"
config:
model: "tesseract"
language: "en"
- name: "Summarizer"
type: "processor"
config:
model: "gpt-4"
max_tokens: 500
- name: "OutputWriter"
type: "output"
config:
destination: "redis"
key_prefix: "summary:"
Архитектура плагинов
DeepSeek Harness использует подход "компонент-плагин". Каждый плагин — это автономный модуль с:
- Определением контракта: Какие данные он принимает и возвращает
- Фабрикой конфигурации: Парсер YAML-конфигурации плагина
- Хуковыми точками: Точки расширения для переопределения поведения
- Инструментами мониторинга: Логирование, метрики и трейсинг
bash# Установка плагина из репозитория
dsh plugin install gh:deepseek-plugins/document-ai
# Создание нового плагина
dsh plugin create --name="my-custom-tool" --type="processor"
Сравнение с традиционными подходами
| Традиционный подход | DeepSeek Harness |
|---|---|
| Ручное кодирование интеграций | Конфигурация через YAML |
| Жёстко связанная архитектура | Плагины как автономные модули |
| Трудно тестировать отдельные компоненты | Каждый плагин тестируется изолированно |
| Замена компонента требует переписывания кода | Замена — это смена конфигурации |
Если вы когда-либо писали скрипт, который "склеивал" несколько AI-инструментов вместе, вы поймёте, почему это раздражает. DeepSeek Harness делает этот процесс предсказуемым и повторяемым.
Пример использования: Анализ документооборота
Рассмотрим задачу: загрузить контракты из S3, извлечь текст, summarize ключевые пункты и сохранить результаты в базу данных.
python# Пример плагина на Python
from dsh import plugin
@plugin(name="ContractProcessor", type="processor")
class ContractProcessor:
async def process(self, data):
# Извлечение текста из PDF
text = await self.extract_text(data["file_path"])
# Генерация сводки
summary = await self.summarize(text)
return {"summary": summary, "metadata": data.metadata}
async def extract_text(self, path):
# Реализация извлечения текста
pass
async def summarize(self, text):
# Реализация суммирования
pass
Где найти больше информации
- Подробное руководство по установке и базовым концепциям — в статье Ponytail: как заставить ИИ-агента думать старший разработчик
- Примеры продвинутой оптимизации производительности плагинов — в ECC: Agent Harness Performance Optimization System
- Реальный кейс использования AI-агента, который думает как опытный разработчик — в AI-агент мыслит как опытный разработчик в современном кон...
DeepSeek Harness — это не просто ещё один фреймворк для AI-инструментов. Это платформа, которая делает сборку AI-систем предсказуемой, тестируемой и повторяемой — как сборка программного обеспечения. Если вам когда-либо приходилось "склеивать" AI-инструменты вручную, вы поймёте, почему это важно.
Архитектура плагинов
Архитектура плагинов
Принцип работы плагинов
DeepSeek Harness реализует архитектуру на основе плагина — каждый компонент системы регистрируется как самостоятельный плагин с определенным интерфейсом. Механизм работы включает три фазы:
-
Регистрация — плагин внедряет себя в реестр через специальный декоратор
register_plugin. Регистратор проверяет уникальность имени и совместимость интерфейсов. -
Загрузка — лоадер сканирует директорию
plugins/и загружает плагины в порядке зависимостей. Для каждого плагина создается экземпляр с инициализацией конфигурации изconfig/plugin_name.yaml. -
Интеграция — плагин регистрируется в конвейерном диспетчере, где его методы становятся доступными через
Настройка и расширение
Настройка и расширение
DeepSeek Harness — это модульная архитектура, которая превращает каждый компонент в плагин. Это позволяет собирать AI-пайплайны как конструктор: берешь нужные блоки, соединяешь их и получаешь работающую систему.
bash# Инициализация нового плагина
mkdir deepseek-plugins
cd deepseek-plugins
cat > my-plugin/plugin.json << 'EOF'
{
"name": "my-plugin",
"version": "1.0.0",
"description": "Пользовательский плагин для DeepSeek Harness",
"entrypoint": "src/main.rs",
"dependencies": []
}
EOF
Интеграция пользовательских плагинов
Подход DeepSeek Harness основан на простом интерфейсе плагинов. Каждый плагин — это отдельный Rust-крейт, который реализует Plugin трейт.
rust// src/lib.rs плагина
use deepseek_harness::{Plugin, PluginContext};
pub struct MyPlugin;
impl Plugin for MyPlugin {
fn name(&self) -> &str {
"my-plugin"
}
fn version(&self) -> &str {
"1.0.0"
}
fn execute(&self, context: &PluginContext) -> Result<String, Box<dyn std::error::Error>> {
// Основная логика плагина
let input = context.input.as_str();
let processed = format!("[MyPlugin] Обработано: {}", input);
// Передаем результат следующему плагину
context.next(&processed)
}
}
Конфигурация плагинов хранится в YAML-файле harness.yml:
yaml# harness.yml
plugins:
- name: "core-parser"
enabled: true
config:
max_tokens: 1024
model: "gpt-4"
- name: "my-plugin"
enabled: true
config:
threshold: 0.7
output_format: "json"
- name: "logger-plugin"
enabled: true
config:
log_level: "info"
file: "/var/log/deepseek.log"
Для загрузки пользовательских плагинов используется команда:
bash# Загрузка и компиляция плагинов
cargo build --release
cp target/release/*.so ~/.config/deepseek/plugins/
# Активация плагинов через конфигурационный файл
deepseek-cli --config harness.yml --load-plugins
Мониторинг и отладка плагинов
Мониторинг плагинов в DeepSeek Harness основан на Prometheus-метриках. Каждый плагин может экспортировать свои показатели.
rust// Метрики плагина
use prometheus::{IntCounter, Histogram};
pub struct PluginMetrics {
pub executions: IntCounter,
pub execution_duration: Histogram,
}
impl PluginMetrics {
fn new() -> Self {
Self {
executions: IntCounter::new("plugin_executions_total", "Общее количество выполнений").unwrap(),
execution_duration: Histogram::new(vec![0.001, 0.01, 0.1, 1.0]).unwrap(),
}
}
}
Экспорт метрик осуществляется через HTTP:
bash# Запуск плагина с метриками
RUST_LOG=info ./target/release/my_plugin --metrics-port 9090
# Проверка метрик
curl http://localhost:9090/metrics
Для отладки используется встроенный дампер состояния:
bash# Просмотр состояния всех плагинов
deepseek-cli --plugin-status
# Логирование выполнения плагинов
deepseek-cli --log-level debug --log-file /var/log/deepseek/debug.log
Отладочная консоль позволяет просматривать состояние каждого плагина в реальном времени:
bash# Запуск консоли мониторинга
deepseek-monitor --port 8080
# Веб-интерфейс доступен по адресу http://localhost:8080
# Здесь отображаются:
# - Статистика выполнения плагинов
# - Графики производительности
# - Журналы ошибок
# - Конфигурация плагинов
Связанные материалы:
- 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-агент мыслит как опытный разработчик в современном кон...
FAQ
Как добавить новый плагин?
Добавление нового плагина в Harness обычно сводится к трём шагам:
- Создайте плагинный класс — унаследуйте от
DshPlugin(илиCordisPlugin, если вы используете модуль cordis). - Зарегистрируйте плагин — укажите его в конфигурации
pluginsвconfig.yaml. - Подключите плагин к точке подключения — используйте аннотацию
@Connectsили укажите точку в конфигурацииplugin-manifest.json.
Пример плагина
yaml# plugins/my-plugin.yaml
plugin:
name: "my-plugin"
version: "1.0.0"
entry: "MyPlugin"
connects:
- "ai-agent.tools"
python# plugins/my_plugin.py
from dsh import DshPlugin
class MyPlugin(DshPlugin):
def __init__(self):
super().__init__("my-plugin")
self.description = "Выполняет клеверирование данных перед отправкой"
def execute(self, context: dict) -> dict:
# Пример: добавляем временную метку к входящим данным
context["processed_at"] = datetime.utcnow().isoformat()
return {"result": "ok", "data": context}
Регистрация плагина в конфигурации
yaml# config.yaml
plugins:
- path: "plugins/my-plugin.yaml"
enabled: true
Что такое точка подключения плагина?
Точка подключения — это именованный хук, который плагин может переопределить или расширить. Harness поддерживает несколько типов точек:
| Тип точки | Типичное назначение | Пример |
|---|---|---|
ai-agent.tools | Доступные инструменты для AI-агента | Плагины, предоставляющие функции анализа, поиска или выполнения команд |
ai-agent.hooks.pre | Выполняется перед основным циклом агента | Логирование, проверка подлинности, фильтрация контекста |
ai-agent.hooks.post | Выполняется после завершения работы агента | Сбор метрик, очистка ресурсов |
ai-agent.middlewares | Плагины, изменяющие поток данных | Токенизация, нормализация, обогащение контекстных данных |
Плагины подключаются к точке с помощью аннотации @Connects или записи в plugin-manifest.json. Когда агент выполняет свою работу, он запрашивает зарегистрированные плагины для каждой точки и вызывает их в определённом порядке (порядок определяется приоритетом, указанным в конфигурации).
Пример подключения к точке
python# plugins/logging-plugin.py
from dsh import DshPlugin, Connects
@Connects("ai-agent.hooks.pre")
class LoggingPlugin(DshPlugin):
def __init__(self):
super().__init__("logging-plugin")
self.description = "Регистрирует входящие запросы агента"
def execute(self, context: dict) -> dict:
logger.info(f"Agent executing: {context.get('query')}")
return context
Где найти примеры плагинов?
Репозиторий Harness включает несколько демонстрационных плагинов, которые показывают различные модели использования:
- [Пример плагина "echo" — базовый плагин, возвращающий данные без изменений] (
cordis/examples/echo-plugin) - [Плагин "search" — подключается к точке ai-agent.tools] (
dsh/examples/search-plugin) - [Плагин "metrics" — собирает данные для Prometheus] (
dsh/examples/metrics-plugin)
Эти примеры находятся в репозитории cordis и dsh и содержат полные файлы конфигурации, исходный код плагинов и инструкции по их локальному запуску.
Как клонировать и запустить примеры
bash# Клонируйте репозиторий Harness
git clone https://github.com/deepseek-ai/harness.git
cd harness
# Перейдите в каталог примеров
cd examples
# Запустите конкретный пример (например, echo-plugin)
./run.sh echo-plugin
Каждый скрипт run.sh создаёт изолированную среду с помощью Docker Compose, загружает необходимые зависимости и запускает плагин в локальном экземпляре Harness, чтобы вы могли протестировать его поведение напрямую.
Полезные ссылки
- 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-агент мыслит как опытный разработчик в современном кон...