DeepSeek Harness: руководство по coding agent

DeepSeek Harness — агент для программирования и среда выполнения агентов с открытым кодом от DeepSeek AI. Он предоставляет цикл агента, инструменты, доступ к workspace, сессии, разрешения и интерфейс вокруг модели. Сама модель по-прежнему приходит от API-провайдера. Сначала разберём, что делает DeepSeek code harness, а затем подключим его к OmniAKey через официальный сценарий собственного провайдера.

Что такое DeepSeek Harness?

DeepSeek Harness, или dsh, — не новая языковая модель. Это программный слой, который превращает модель в агента: даёт ей возможность понимать workspace, вызывать инструменты, редактировать файлы, запускать команды, сохранять сессии и запрашивать подтверждение операций.

Главный принцип архитектуры — everything is a plugin. Harness построен на плагинной системе Cordis, поэтому модели, инструменты, skills, сессии, sandbox, хранилище, циклы, планировщик и даже UI можно заменять и компоновать через конфигурацию.

Единый поток событий — это больше, чем история чата. Resume, fork, search и replay работают с тем же журналом сессии, поэтому можно разобрать выполнение, в котором агент сделал много tool calls до финального ответа.

Чем этот инструмент не является

• Это не DeepSeek V4 Pro и не другая модель. Harness и модель — разные уровни.
• Это пока не стабильный production-релиз. Проект называет его developer preview и предупреждает о несовместимых изменениях.
• При быстром запуске через npm это не облачный сервис: Web UI по умолчанию слушает только локальный loopback.
• Открытый код не делает inference бесплатным. Репозиторий использует MIT, а API-вызовы оплачиваются у выбранного провайдера.

Настройки DeepSeek Harness для OmniAKey

Полная конфигурация перед подробными шагами:

Суффикс /v1 является частью Base URL. Не используйте только домен, не дублируйте /v1/v1 и не вставляйте полный путь /chat/completions: Harness добавляет путь операции сам.

Шаг 1. Установите и запустите DeepSeek Harness

Установите Node.js, откройте терминал в каталоге проекта, который должен видеть агент, и выполните официальную npm-команду:

npx @deepseek-ai/dsh web

Текущая команда запускает Web UI по адресу:

http://127.0.0.1:3080

Если порт 3080 занят, Web profile принимает другой порт:

npx @deepseek-ai/dsh web --port 3081

Каталог запуска dsh становится исходным filesystem location, но composer недоступен, пока вы не добавите и не выберете workspace в интерфейсе. Выбирайте репозиторий осознанно: агент может получить инструменты файловой системы и shell согласно активной политике разрешений.

Шаг 2. Создайте отдельный API-ключ OmniAKey

Откройте dashboard API-ключей OmniAKey и создайте отдельный ключ для Harness. Такой ключ проще ограничить, заменить, отозвать и проверить, чем общий credential для нескольких инструментов.

Не помещайте секрет в репозиторий, историю shell, скриншоты, issues или чаты. Web UI сохраняет ключ как write-only: по официальной документации он попадает в $DSH_HOME/.credentials.yaml, settings содержат только ссылку на credential, а страница получает лишь замаскированное описание.

Шаг 3. Добавьте OmniAKey как custom provider

При первом запуске примите Internal Testing Notice кнопкой Continue. Следующий onboarding-диалог предлагает только официальный DeepSeek API key; нажмите Configure later, потому что OmniAKey нужно добавить как custom provider, а не как встроенный официальный маршрут.

В Harness откройте Settings → Models, нажмите Add a custom provider и заполните:

1. Provider ID: omniakey. Идентификатор должен начинаться со строчной латинской буквы.
2. Display name: OmniAKey.
3. Base URL: https://api.omniakey.com/v1.
4. API protocol: openai-completions.
5. API key: отдельный ключ OmniAKey.

В текущей архитектуре Provider ID постоянен: его используют сохранённые сессии, defaults, requests и credential references. Display name, Base URL, protocol, key и список моделей можно редактировать.

Шаг 4. Получите и выберите модели

В разделе Model catalog нажмите Fetch available models. Для custom OpenAI-compatible provider Harness делает запрос GET /models с Bearer-аутентификацией к Base URL, который сейчас виден в форме. Для нашей настройки это endpoint OmniAKey GET /v1/models.

Выберите только нужные модели. Для такого workflow разумно начать с двух ID:

Тот же провайдер открывает поддерживаемые OmniAKey модели Claude, GPT, Gemini, Grok и GLM. Копируйте точные ID из актуального каталога моделей: это идентификаторы, а не приблизительные alias.

Если discovery недоступен, Model ID можно добавить вручную. Для создания custom provider Harness требует хотя бы одну модель.

Шаг 5. Сохраните и выполните безопасную проверку

Сохраните провайдер, выберите проект через Choose workspace, создайте новую сессию и укажите OmniAKey / deepseek-v4-pro или OmniAKey / deepseek-v4-flash.

Начните с узкого read-only prompt:

Прочитай package.json и перечисли доступные scripts. Не изменяй файлы и не запускай команды.

Так вы проверите workspace, provider, key, точный Model ID и базовый response path до разрешения изменений или shell-команд. Текстовый ответ ещё не доказывает работу всех форматов tool calling, поэтому перед большим refactor проверьте одну обратимую задачу с инструментом.

Настройки модели применяются к следующему запросу без перезапуска. Но уже начавшаяся сессия сохраняет модель в своём журнале. После смены провайдера или модели создайте новую сессию для однозначного теста.

Опционально: конфигурация через settings.yaml

Для первого запуска Web UI понятнее. В контролируемой локальной среде можно определить profile в $DSH_HOME/settings.yaml, ссылаясь на переменную окружения:

export OMNIAKEY_API_KEY="your-omniakey-api-key"

llm-pi-ai:
  providers:
    omniakey:
      displayName: OmniAKey
      apiKeyEnv: OMNIAKEY_API_KEY
      api: openai-completions
      baseURL: https://api.omniakey.com/v1
      models:
        - id: deepseek-v4-pro
        - id: deepseek-v4-flash

Ключ должен находиться в окружении процесса, который запускает dsh. Не заменяйте apiKeyEnv буквальным секретом в YAML. Официальная справка dsh-llm-pi-ai рекомендует credential reference, чтобы секрет не попадал в settings.

Зачем подключать OmniAKey?

Harness поддерживает custom gateways, а OmniAKey превращает эту точку расширения в один переиспользуемый provider.

• Одна настройка для нескольких семейств. Меняйте точный Model ID в picker без отдельного gateway profile для каждого поставщика.
• Обнаружение моделей. Harness читает OpenAI-совместимый список OmniAKey вместо ручного ввода ID.
• Отдельные операционные ограничения. Собственный ключ Harness получает свой лимит, ротацию и usage trail.
• Явная идентичность модели. Политика OmniAKey запрещает скрытую подмену: выполняется запрошенная модель, а недоступный upstream даёт видимую ошибку.
• Оплата API вместо ещё одной подписки на агента. Баланс предоплачивается, usage тарифицируется по токенам; актуальные модели и цены остаются в каталоге.

Это не означает, что OmniAKey всегда лучше официального ключа. Прямой endpoint подходит, если нужна только собственная учётная запись провайдера. OmniAKey особенно полезен, когда одна установка Harness должна использовать выбранные DeepSeek и другие семейства через один ключ и Base URL.

Устранение ошибок

Fetch available models возвращает 401

Проверьте, что key создан в OmniAKey, не содержит пробелов, активен и используется вместе с точным https://api.omniakey.com/v1. Discovery использует Bearer-аутентификацию.

Провайдер возвращает 404

Сначала исправьте Base URL. Частые ошибки: нет /v1, есть двойной /v1/v1 или указан полный https://api.omniakey.com/v1/chat/completions.

UNKNOWN_MODEL

Модели нет в сохранённом списке provider. Повторите discovery или добавьте точный ID из каталога OmniAKey, затем выберите его в новой сессии.

MISSING_CREDENTIAL

Сохраните key через Settings → Models либо убедитесь, что OMNIAKEY_API_KEY доступна именно процессу запуска Harness. Переменная в другом терминале уже работающий процесс не изменит.

Смена модели не сработала

Начните новую сессию. После первого запроса существующая сессия сохраняет provider и model в append-only log.

Текст работает, а tool call нет

Это разные проверки. Начните с read-only tool task, изучите Trajectory и определите точный сбой до повышения permissions или limits. Некорректный tool call не исправляется заменой рабочего API key.

Частые вопросы

Этот агент бесплатный?

Исходный код распространяется по MIT. Inference модели оплачивается отдельно через официальный API, OmniAKey или другого provider.

Можно использовать DeepSeek V4 Pro через OmniAKey?

Да. Добавьте OmniAKey как custom provider openai-completions и выберите точный ID deepseek-v4-pro. Для более дешёвого маршрута доступен deepseek-v4-flash.

Можно вставить ключ OmniAKey во встроенную карточку DeepSeek?

Используйте Add a custom provider. Встроенная карточка настраивает официальный маршрут DeepSeek, а custom provider — документированный путь для gateway с нужными OmniAKey полями Base URL, protocol и model list.

Один provider может запускать Claude, GPT или Gemini?

Да, если модель поддерживается OpenAI-совместимой поверхностью OmniAKey. Получите текущий список и добавьте точные ID. Возможности протокола различаются, поэтому проверяйте tool behavior выбранной модели.

Где хранится API key?

Ключи из Models page записываются как write-only в $DSH_HOME/.credentials.yaml; settings сохраняют reference. Для YAML используйте apiKeyEnv и передавайте секрет окружению процесса.

Готов ли Harness к стабильному production workflow?

Пока относитесь к нему как к объекту оценки. Официальная документация указывает developer preview и будущие несовместимые изменения. Фиксируйте версии, сохраняйте конфигурацию без секретов и перепроверяйте guide после обновления.

Проверенные источники

• Страница DeepSeek Harness
• GitHub README DeepSeek Harness
• Официальный Web UI quick start
• Официальная настройка моделей и custom provider
• Справка dsh-llm-pi-ai
• OpenAI-совместимый API OmniAKey
• Текущий каталог OmniAKey