Установка и настройка DeepSeek Harness: плагинная архитектура для AI-агентов

Пошаговое руководство по развёртыванию DeepSeek Harness (dsh) — фреймворка для построения AI-агентов на TypeScript, где вся функциональность реализована через плагины на базе Cordis.

Средний

Алексей Кузнецов

Системный администратор18 октября 2026 г.5 мин чтения

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
corepack prepare pnpm@latest --activate
pnpm install

pnpm run build
pnpm --filter @deepseek/harness-cli run build
./packages/cli/bin/dsh --help

mkdir -p ~/my-harness-project
cd ~/my-harness-project
cat > harness.config.yaml << 'EOF'
runtime:
  name: "my-agent"
  version: "0.1.0"
  plugins:
    - "@deepseek/harness-plugin-llm"
    - "@deepseek/harness-plugin-memory"
    - "@deepseek/harness-plugin-tools"
  settings:
    logLevel: "info"
    dataDir: "./data"
EOF

cd ~/my-harness-project
~/deepseek-harness/packages/cli/bin/dsh init --config harness.config.yaml

mkdir -p ~/my-harness-project/plugins/echo-bot/src
cat > ~/my-harness-project/plugins/echo-bot/src/index.ts << 'EOF'
import { Plugin, Context, Command } from '@deepseek/harness-core';

@Plugin.define()
export class EchoBotPlugin extends Plugin {
  @Command.define('echo', { description: 'Повторить сообщение' })
  async echo(ctx: Context, message: string) {
    return ctx.send(message);
  }
}
EOF

cd ~/my-harness-project/plugins/echo-bot
cat > package.json << 'EOF'
{
  "name": "echo-bot",
  "version": "0.1.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc"
  },
  "peerDependencies": {
    "@deepseek/harness-core": "workspace:*"
  }
}
EOF

cat > tsconfig.json << 'EOF'
{
  "extends": "@deepseek/harness-tsconfig/base",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}
EOF

pnpm install
pnpm run build

cd ~/my-harness-project
sed -i '/plugins:/a\    - "./plugins/echo-bot"' harness.config.yaml

cd ~/my-harness-project
~/deepseek-harness/packages/cli/bin/dsh dev --config harness.config.yaml

> echo "Привет, Harness!"
Привет, Harness!

cd ~/my-harness-project
cat > .env << 'EOF'
LLM_PROVIDER=openai
LLM_API_KEY=sk-ваш-ключ
LLM_MODEL=gpt-4o-mini
LLM_BASE_URL=https://api.openai.com/v1
EOF
chmod 600 .env

cd ~/my-harness-project
~/deepseek-harness/packages/cli/bin/dsh build --output ./dist --config harness.config.yaml

sudo tee /etc/systemd/system/harness-agent.service > /dev/null << 'EOF'
[Unit]
Description=DeepSeek Harness Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=harness
WorkingDirectory=/opt/harness-agent
ExecStart=/opt/harness-agent/dist/index.js
EnvironmentFile=/opt/harness-agent/.env
Restart=on-failure
RestartSec=5
MemoryLimit=2G
CPUQuota=200%
StandardOutput=journal
StandardError=journal
SyslogIdentifier=harness-agent

[Install]
WantedBy=multi-user.target
EOF

sudo useradd -r -s /bin/false -d /opt/harness-agent harness
sudo mkdir -p /opt/harness-agent
sudo cp -r ~/my-harness-project/dist ~/my-harness-project/.env /opt/harness-agent/
sudo chown -R harness:harness /opt/harness-agent
sudo systemctl daemon-reload
sudo systemctl enable --now harness-agent

cat > /etc/promtail/config.yml << 'EOF'
clients:
  - url: http://loki:3100/loki/api/v1/push
positions:
  filename: /tmp/positions.yaml
scrape_configs:
  - job_name: harness
    static_configs:
      - targets:
          - localhost
        labels:
          job: harness-agent
          __path__: /var/log/journal/*
    pipeline_stages:
      - json:
          expressions:
            level: level
            msg: msg
            plugin: plugin
            latency_ms: latency_ms
      - labels:
          level:
          plugin:
EOF

# Метрики доступны на http://localhost:9090/metrics
# Импорт дашборда: grafana.com/dashboards/12345 (пример)

cd ~/deepseek-harness
git pull origin main
pnpm install
pnpm run build

# Blue-green деплой
sudo cp -r ~/my-harness-project/dist /opt/harness-agent-new
sudo cp ~/my-harness-project/.env /opt/harness-agent-new/
sudo systemctl start harness-agent-blue
# Проверка health-check
curl -f http://localhost:9091/health
sudo sed -i 's/harness-agent-green/harness-agent-blue/' /etc/nginx/upstreams/harness.conf
sudo nginx -s reload
sudo systemctl stop harness-agent-green

Установка и настройка DeepSeek Harness: плагинная архитектура для AI-агентов

Пошаговое руководство по развёртыванию DeepSeek Harness (dsh) — фреймворка для построения AI-агентов на TypeScript, где вся функциональность реализована через плагины на базе Cordis.

Предварительные требования

• Node.js 20+ (LTS) и npm 10+
• TypeScript 5+ (базовое понимание системы типов)
• Опыт работы с асинхронным кодом на TypeScript
• Понимание концепции плагинной архитектуры
• Git для клонирования репозитория

Шаг 1: Клонирование репозитория и установка зависимостей

Начинаем с получения исходного кода. DeepSeek Harness — монорепозиторий на pnpm, поэтому стандартный npm install не сработает корректно. Используем pnpm, как предусмотрено авторами.

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
corepack prepare pnpm@latest --activate
pnpm install

Шаг 2: Сборка проекта и проверка работоспособности CLI

После установки зависимостей собираем TypeScript в JavaScript. В монорепозиториях это критически важный шаг — без сборки внутренние пакеты не резолвятся. Проверяем, что бинарник dsh доступен.

pnpm run build
pnpm --filter @deepseek/harness-cli run build
./packages/cli/bin/dsh --help

Шаг 3: Создание конфигурационного файла проекта

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

mkdir -p ~/my-harness-project
cd ~/my-harness-project
cat > harness.config.yaml << 'EOF'
runtime:
  name: "my-agent"
  version: "0.1.0"
  plugins:
    - "@deepseek/harness-plugin-llm"
    - "@deepseek/harness-plugin-memory"
    - "@deepseek/harness-plugin-tools"
  settings:
    logLevel: "info"
    dataDir: "./data"
EOF

Шаг 4: Инициализация рабочего пространства через CLI

Команда init создаёт структуру директорий, генерирует package.json с правильными зависимостями и подготавливает среду для разработки плагинов. Это аналог npm init, но с учётом специфики Harness.

cd ~/my-harness-project
~/deepseek-harness/packages/cli/bin/dsh init --config harness.config.yaml

Шаг 5: Написание первого плагина: эхо-бот

Плагин в Harness — это класс, реализующий интерфейс Plugin из пакета @deepseek/harness-core. Каждый плагин объявляет свои команды, события и зависимости через декораторы. Создаём плагин, отвечающий на сообщения эхом — это «Hello World» для проверки пайплайна.

mkdir -p ~/my-harness-project/plugins/echo-bot/src
cat > ~/my-harness-project/plugins/echo-bot/src/index.ts << 'EOF'
import { Plugin, Context, Command } from '@deepseek/harness-core';

@Plugin.define()
export class EchoBotPlugin extends Plugin {
  @Command.define('echo', { description: 'Повторить сообщение' })
  async echo(ctx: Context, message: string) {
    return ctx.send(message);
  }
}
EOF

Шаг 6: Сборка и регистрация плагина

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

cd ~/my-harness-project/plugins/echo-bot
cat > package.json << 'EOF'
{
  "name": "echo-bot",
  "version": "0.1.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc"
  },
  "peerDependencies": {
    "@deepseek/harness-core": "workspace:*"
  }
}
EOF

cat > tsconfig.json << 'EOF'
{
  "extends": "@deepseek/harness-tsconfig/base",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}
EOF

pnpm install
pnpm run build

cd ~/my-harness-project
sed -i '/plugins:/a\    - "./plugins/echo-bot"' harness.config.yaml

Шаг 7: Запуск агента в режиме разработки

Команда dev запускает агент с файловым вотчером — при изменении исходников плагины пересобираются и перезагружаются без рестарта процесса. Это ускоряет итеративную разработку. Логи пишутся в stdout с цветным форматированием.

cd ~/my-harness-project
~/deepseek-harness/packages/cli/bin/dsh dev --config harness.config.yaml

Шаг 8: Тестирование плагина через интерактивную консоль

В запущенном агенте доступна REPL-консоль. Вводим команду echo с аргументом — плагин должен вернуть то же сообщение. Это проверяет цепочку: парсинг команды → диспетчеризация → выполнение хендлера → отправка ответа.

> echo "Привет, Harness!"
Привет, Harness!

Шаг 9: Настройка LLM-провайдера через переменные окружения

Плагин @deepseek/harness-plugin-llm требует API-ключи. Никогда не храним секреты в конфиге — используем .env файл с правами 600. Поддерживаются OpenAI-совместимые эндпоинты, включая локальные модели через Ollama или vLLM.

cd ~/my-harness-project
cat > .env << 'EOF'
LLM_PROVIDER=openai
LLM_API_KEY=sk-ваш-ключ
LLM_MODEL=gpt-4o-mini
LLM_BASE_URL=https://api.openai.com/v1
EOF
chmod 600 .env

Шаг 10: Создание продакшн-сборки и systemd-юнита

Для продакшена собираем автономный бандл с помощью esbuild (встроен в CLI). Затем создаём systemd-юнит с правильными зависимостями, лимитами памяти и автозапуском. Systemd — лучшее, что случилось с Linux после самого Linux: предсказуемость управления процессами, логирование в journald, перезапуск при падении.

cd ~/my-harness-project
~/deepseek-harness/packages/cli/bin/dsh build --output ./dist --config harness.config.yaml

sudo tee /etc/systemd/system/harness-agent.service > /dev/null << 'EOF'
[Unit]
Description=DeepSeek Harness Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=harness
WorkingDirectory=/opt/harness-agent
ExecStart=/opt/harness-agent/dist/index.js
EnvironmentFile=/opt/harness-agent/.env
Restart=on-failure
RestartSec=5
MemoryLimit=2G
CPUQuota=200%
StandardOutput=journal
StandardError=journal
SyslogIdentifier=harness-agent

[Install]
WantedBy=multi-user.target
EOF

sudo useradd -r -s /bin/false -d /opt/harness-agent harness
sudo mkdir -p /opt/harness-agent
sudo cp -r ~/my-harness-project/dist ~/my-harness-project/.env /opt/harness-agent/
sudo chown -R harness:harness /opt/harness-agent
sudo systemctl daemon-reload
sudo systemctl enable --now harness-agent

Шаг 11: Настройка логирования и мониторинга через Loki/Prometheus

Harness пишет структурированные логи в JSON. Настраиваем promtail для отправки в Loki, а метрики (latency, token usage, error rate) экспортируются на /metrics в формате Prometheus. Grafana-дашборд импортируется из репозитория фреймворка.

cat > /etc/promtail/config.yml << 'EOF'
clients:
  - url: http://loki:3100/loki/api/v1/push
positions:
  filename: /tmp/positions.yaml
scrape_configs:
  - job_name: harness
    static_configs:
      - targets:
          - localhost
        labels:
          job: harness-agent
          __path__: /var/log/journal/*
    pipeline_stages:
      - json:
          expressions:
            level: level
            msg: msg
            plugin: plugin
            latency_ms: latency_ms
      - labels:
          level:
          plugin:
EOF

# Метрики доступны на http://localhost:9090/metrics
# Импорт дашборда: grafana.com/dashboards/12345 (пример)

Шаг 12: Обновление фреймворка и плагинов без простоев

Обновления применяются через git pull в репозитории фреймворка, затем pnpm install && pnpm run build. Для zero-downtime деплоя используем blue-green: поднимаем второй инстанс на другом порту, проверяем health-check, переключаем nginx upstream. systemd-юнит обновляется атомарно через systemctl reload.

cd ~/deepseek-harness
git pull origin main
pnpm install
pnpm run build

# Blue-green деплой
sudo cp -r ~/my-harness-project/dist /opt/harness-agent-new
sudo cp ~/my-harness-project/.env /opt/harness-agent-new/
sudo systemctl start harness-agent-blue
# Проверка health-check
curl -f http://localhost:9091/health
sudo sed -i 's/harness-agent-green/harness-agent-blue/' /etc/nginx/upstreams/harness.conf
sudo nginx -s reload
sudo systemctl stop harness-agent-green