Сначала определите сценарий расширения — инструмент, провайдер модели, интерфейс или рабочий процесс, — затем соберите минимальный плагин и только после этого добавляйте связанный набор функций. На этой неделе зафиксируйте проверенную ревизию master, создайте отдельный профиль для эксперимента и доведите одну функцию до загрузки, обнаружения и диагностируемого отказа.

Этот материал нужен вам, если вы:

  • превращаете внутренний скрипт в инструмент для DeepSeek Harness;
  • подключаете собственный модельный endpoint или командный шлюз;
  • отвечаете за общий удалённый Mac-стенд и приёмку плагинов небольшой команды.

По состоянию на 18 августа 2026 года DeepSeek Harness остаётся проектом в статусе developer preview. Официальный репозиторий предупреждает о возможных совместимость-ломающих изменениях, поэтому ниже приведена не обещанная стабильная спецификация API, а схема принятия решений. Перед каждым выпуском сверяйте её с актуальной master-веткой.

01

Последнее обновление и границы проверки

Последнее обновление: 18 августа 2026 года. Данные сверены с README, руководством по разработке, архитектурным документом, package.json и руководством по внесению изменений официального репозитория.

В текущей документации подтверждены следующие факты:

  • DeepSeek Harness использует плагинную архитектуру, где модельный адаптер, реестр инструментов, журнал сессии и агентский цикл также представлены как плагины.
  • Архитектура построена поверх Cordis. Плагины добавляют сервисы, типизированные события и обратимые эффекты в общий контекст.
  • Профиль является именованной композицией слоёв и bundle.
  • В репозитории заявлена поддержка Node.js 22.19+ и 24+. CI охватывает Node.js 22.19, 24 и 26.
  • В package.json закреплён pnpm@11.7.0.
  • Запуск Web UI из пакета выполняется командой npx @deepseek-ai/dsh web; по умолчанию интерфейс доступен на 127.0.0.1:3080.

Проверяйте эти сведения в официальном README DeepSeek Harness. В preview-проекте меняются имена пакетов, поля манифеста, точки регистрации и команды. Поэтому поведение стороннего плагина нельзя автоматически считать официальной гарантией.

Кодовую структуру и роли компонентов сверяйте с официальной архитектурной документацией, а команды сборки и тестов — с руководством по разработке.

02

Четыре границы расширения

Официальная архитектура описывает DeepSeek Harness как дерево плагинов. Это полезнее, чем искать универсальный шаблон: сначала вы определяете, какой слой хотите изменить.

Инструмент

Выбирайте инструмент, если агенту нужно вызвать одну внешнюю способность:

  • проверить статус внутреннего сервиса;
  • найти запись в базе;
  • запустить безопасную команду;
  • получить данные из корпоративного API;
  • преобразовать файл по формальному контракту.

Один инструмент должен иметь одну понятную ответственность. Если в одном пакете одновременно находятся поиск тикетов, изменение прав и публикация отчёта, тестировать разрешения и откатывать ошибки будет сложнее. В developer preview это особенно рискованно: изменение одной регистрации может нарушить весь набор.

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

Разделяйте плагины, если:

  • функции включаются разными командами;
  • доступ к сети нужен только части возможностей;
  • одна функция может быть отключена без потери остальных;
  • разные инженеры отвечают за разные интеграции.

Успешный сигнал: плагин загрузился, инструмент появился в доступном наборе, корректный ввод вернул ожидаемый результат, а неверный ввод дал ошибку с названием поля, причиной и безопасным способом исправления.

Резервный путь: если регистрация нестабильна, временно оставьте чистый инструмент без Web UI, фоновых задач и сложной конфигурации. Сначала докажите контракт вызова, затем расширяйте поверхность.

Провайдер модели

Модельный плагин решает другую задачу. Он не просто добавляет очередную функцию агенту, а отвечает за маршрут к модели, список моделей, параметры endpoint и обработку ответа.

Не смешивайте в одном пакете:

  • адаптер провайдера;
  • бизнес-инструменты;
  • пользовательские настройки интерфейса;
  • сценарии длительного рабочего процесса.

Такое смешение создаёт скрытую связанность. Например, замена endpoint начинает требовать изменения UI, профиля и тестов инструментов.

Ключевые параметры должны приходить из окружения или конфигурации. В текущем руководстве приведены DEEPSEEK_API_KEY и необязательный DEEPSEEK_BASE_URL; реальный API-тест пропускается, если ключ не задан. Это следует проверять по примеру конфигурации из официального руководства.

export DEEPSEEK_API_KEY="ваш-ключ"
export DEEPSEEK_BASE_URL="https://ваш-endpoint"

Не помещайте ключ в TypeScript, тестовые fixtures, README или пример конфигурации, который автоматически копируется в рабочий профиль.

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

Резервный путь: добавьте mock-адаптер или тестовый маршрут без сетевого вызова. Если модельная интеграция блокирует разработку инструмента, сначала проверяйте структуру ответа и обработку ошибок на локальных данных.

Web UI и удалённое взаимодействие

Плагин с интерфейсом требует уже не только регистрации сервиса. Вы должны проверить границу между Host и Client.

В официальной структуре отдельные TypeScript-агрегаты обслуживают Host и Client. Обычный пакет регистрируется ровно в одном агрегате: Host-пакеты — в tsconfig.host.json, Client-пакеты — в tsconfig.client.json. При этом обычный Client-плагин может получить Node-загрузчик и браузерный bundle во время Client-фазы сборки. Подробности приведены в описании структуры проекта и фаз сборки.

Практически это означает:

  • серверная логика не должна случайно попасть в браузерный bundle;
  • ключи и сетевые полномочия нельзя импортировать в клиентский код;
  • удалённый метод должен иметь проверяемый контракт;
  • браузерная часть должна корректно переживать недоступность сервера;
  • сначала проверяется Host, затем удалённый контракт, затем Client.

Официальная последовательность сборки в текущей документации выглядит так:

tsc -b tsconfig.host.json
tsdown --env.DSH_BUILD_FACE host
tsc -b tsconfig.client.json
tsdown --env.DSH_BUILD_FACE client
pnpm run build:web

Плагин, который использует удалённый интерфейс, нельзя считать готовым только потому, что он компилируется в редакторе.

Успешный сигнал: Host собирается отдельно, удалённый контракт генерируется, Client получает нужные типы, Web UI отображает состояние загрузки и ошибку соединения.

Резервный путь: выпустите серверную версию без UI. Это лучше, чем блокировать всю интеграцию из-за нестабильной браузерной части.

Если после подключения интерфейса появились белый экран, ошибки удалённого метода или проблемы с загрузкой ресурсов, сначала используйте отдельный материал о диагностике Web UI DeepSeek Harness, а не переписывайте всю бизнес-логику.

Рабочий процесс

Рабочий процесс — не повод копировать проект под каждый эксперимент. В архитектуре профили складывают bundle и patch-слои. Профиль хранит установленные внешние плагины и собственный cordis.patch.yml; дополнительные изменения могут приходить из домашнего уровня и через --patch.

Разделите как минимум три режима:

  • экспериментальный — новые плагины и частые изменения;
  • тестовый — фиксированные версии и воспроизводимая конфигурация;
  • рабочий — только проверенные bundle и минимальные права.

Не позволяйте нескольким инженерам менять один глобальный patch-файл. В нём быстро появляются несовместимые настройки, которые трудно связать с конкретным плагином.

Успешный сигнал: каждый профиль запускается независимо, состав bundle можно восстановить, а отключение одного плагина не меняет остальные режимы.

Резервный путь: временно удалите новый слой из профиля и вернитесь к последней проверенной композиции. Такой откат должен быть процедурой, а не ручным поиском по нескольким конфигурационным файлам.

03

Условия выбора структуры

Используйте этот список до начала реализации. Отмечайте каждый пункт в issue или release-документе.

  • [ ] Если требуется одна внешняя операция с чётким входом и выходом, выбрана структура инструментального плагина. Иначе перейдите к следующему условию.
  • [ ] Если меняются endpoint, каталог моделей, авторизация или формат ответа модели, выбрана структура провайдерного плагина. Бизнес-инструменты не включены без отдельного обоснования.
  • [ ] Если основная ценность находится в браузерном экране, удалённом методе или интерактивном состоянии, выбрана Host/Client-структура. Если UI не обязателен, реализация начинается с серверного плагина.
  • [ ] Если нужно собрать несколько уже проверенных компонентов в разные режимы работы, используются профиль и bundle. Исходный проект не копируется под каждый режим.
  • [ ] Если разные части требуют разных разрешений, версий или владельцев, они разделены на независимые плагины.
  • [ ] Если функция не может пройти smoke-тест без пяти внешних сервисов, создан mock-контракт, а дополнительные интеграции отложены.
  • [ ] Если плагин должен пережить больше одного цикла обновления preview, в документации зафиксированы commit, версия пакета и дата повторной проверки.
  • [ ] Для каждого расширения записаны успешный сигнал и способ отката.

Если вы не можете поставить эти отметки без предположений, граница плагина ещё не определена. В таком состоянии нельзя начинать разработку набора функций: сначала сократите область ответственности.

04

Минимальный каркас dsh-plugin

Не принимайте название dsh-plugin за гарантию фиксированного формата. Официальный репозиторий рекомендует добавлять эту тему к репозиторию для обнаружения, но конкретные поля и точки загрузки нужно сверять с текущей веткой проекта.

Для первого внешнего плагина держите структуру небольшой:

my-dsh-plugin/
├── package.json
├── src/
│   └── index.ts
├── test/
│   └── plugin.test.ts
├── tsconfig.json
├── build.config.ts
└── README.md

Это рабочая организация проекта, а не обещанный официальный шаблон. В package.json должна быть описана роль проекта в экосистеме DeepSeek Harness через актуальное поле dsh. Для bundle и профиля документация указывает соответственно dsh.bundle и dsh.profile. Проверяйте реальные поля в официальном package.json проекта и в архитектурном документе.

В src/index.ts оставьте только:

  1. создание или получение сервиса;
  2. регистрацию одной способности;
  3. валидацию входа;
  4. диагностируемый результат;
  5. корректное снятие эффекта при выгрузке.

В TypeScript не начинайте с универсального слоя абстракций. Сначала зафиксируйте входной объект, выходной объект и ошибки. Для инструмента полезно проверить четыре результата:

  • плагин виден в загрузчике;
  • инструмент виден агенту;
  • валидный вызов даёт результат;
  • невалидный вызов не падает с необработанным исключением.

Если минимальный проект не загружается, дополнительные сервисы, UI и профильные patch-файлы только увеличат область поиска.

05

Профили и конфигурационные слои

Чтобы загрузить плагин в конкретный профиль, сначала определите, как он поставляется:

  • как самостоятельный внешний пакет;
  • как часть bundle;
  • как строка в составе профиля;
  • как локальный checkout для проверки.

Затем действуйте по порядку:

  1. Зафиксируйте имя профиля и его назначение.
  2. Установите плагин только в этот профиль.
  3. Проверьте package.json плагина и соответствующее поле dsh.
  4. Откройте профильный cordis.patch.yml.
  5. Проверьте порядок bundle.
  6. Запустите профиль в чистой оболочке.
  7. Посмотрите фактическое дерево загрузки, а не только исходный файл конфигурации.

Архитектура описывает порядок слоёв: bundle профиля, профильный patch, домашний patch и временный overlay через --patch. Patch заменяет конфигурацию строки целиком или добавляет новую строку. Это важная деталь: частичное ожидание слияния может привести к потере полей, если вы заменили всю запись.

Для автоматизированной проверки из исходного checkout официальное руководство показывает запуск headless-режима с профилем:

pnpm dsh --profile headless "summarize this workspace"

Не переносите эту команду на внешний плагин как универсальную команду установки. Она подтверждает запуск профиля из исходного дерева, но не заменяет проверку текущего механизма установки внешних пакетов.

Важно. В preview-проекте профиль, bundle и API могут измениться независимо друг от друга. Записывайте commit, версию пакета, используемый профиль и дату проверки в README или release notes.

06

FAQ: частые решения перед началом работы

Какие расширения поддерживает DeepSeek Harness

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

Что считать минимальной структурой проекта

Минимум — это пакет с описанием роли в package.json, исходным TypeScript-кодом, точкой загрузки, конфигурацией сборки и тестом запуска. Не добавляйте Web UI, удалённые методы и несколько инструментов до первого успешного smoke-теста. Если официальная документация обновила структуру, приоритет имеют её поля и примеры, а не старый шаблон.

Как не сломать нужный профиль

Профиль должен быть отдельным объектом для эксперимента, теста или эксплуатации. Устанавливайте внешнюю зависимость в конкретный профиль и проверяйте итоговое дерево слоёв. Если после подключения меняется поведение базового инструмента, удалите новый слой, восстановите последнюю рабочую композицию и только потом изучайте конфликт patch-файлов.

Какие проверки обязательны до публикации

Минимальный набор — typecheck, загрузка, обнаружение способности, валидный и невалидный вызов, проверка разрешений, чистая установка, запуск без секретов в репозитории и удаление. Для Web UI добавьте Host-сборку, генерацию удалённого контракта, Client-сборку и проверку недоступного endpoint. Зафиксируйте проверенную ревизию и дату.

07

Пять шагов от скрипта до приёмки

Шаг 1. Зафиксируйте границу

Опишите одной фразой, что делает плагин. Например: «получает состояние сборки по идентификатору». Если в описание входят ещё изменение сборки, уведомление команды и запись отчёта, разделите функции.

Шаг 2. Создайте чистое окружение

Для исходного checkout используйте подтверждённую последовательность:

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
pnpm install
pnpm run typecheck

Официальное руководство указывает Node.js 22.19+ или 24+, Corepack и pnpm 11.7.0. После чистого клонирования pnpm run typecheck должен завершиться успешно. В случае изменения требований сверяйтесь с официальным руководством по локальной разработке, а не со старым lockfile.

Шаг 3. Проверьте один контракт

Сделайте один вход, один выход и несколько явных ошибок. Не добавляйте автоматические повторы, фоновые очереди и сетевой кэш, пока базовый вызов не проходит стабильно.

Шаг 4. Подключите профиль

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

Шаг 5. Проведите чистую установку и откат

Удалите локальные артефакты, установите зависимости заново, загрузите профиль, выполните позитивный и негативный тест. Затем отключите плагин и убедитесь, что базовый профиль продолжает работать.

Если команда запускает такие проверки регулярно, руководство по приёмке среды разработки AI Agent поможет вынести Node.js, pnpm, ключи, логи и правила доступа за пределы ноутбука конкретного инженера.

08

Приёмка перед выпуском

Перед публикацией проверяйте не только «компилируется ли код». Включите в release checklist следующие пункты:

  • pnpm run typecheck проходит на чистом дереве;
  • сборка не использует случайные локальные файлы;
  • плагин загружается в целевой профиль;
  • способность обнаруживается под ожидаемым именем;
  • неверный ввод возвращает диагностируемую ошибку;
  • сетевые и файловые разрешения минимальны;
  • API Key отсутствует в Git;
  • endpoint и каталог моделей задаются конфигурацией или окружением;
  • Web UI не получает серверные секреты;
  • Host и Client проверяются раздельно;
  • чистая установка повторяет результат разработчика;
  • отключение плагина восстанавливает рабочий профиль;
  • README содержит проверенный commit, пакетную версию и дату повторной проверки.

Официальная разработка использует раздельные Host и Client агрегаты, а корневая сборка проходит через несколько зависимых фаз. Поэтому ошибка в типах может проявиться раньше, чем проблема браузерного bundle. Не заменяйте полный typecheck одним запуском UI.

Для команды полезно также запускать pnpm run build перед проверками, которые используют собранные артефакты. Свежий checkout не содержит готовых JavaScript-файлов и деклараций до выполнения сборки.

При открытии pull request сверяйте требования с официальным руководством по внесению изменений. Даже если плагин хранится отдельно, такой review помогает проверить документацию, тестовое покрытие, формат коммитов и порядок воспроизведения.

09

Когда нужен постоянный Mac-стенд

Локальный ноутбук удобен для первого прототипа, но у него есть четыре слабых места:

  • окружение меняется вместе с личными пакетами и настройками;
  • профиль может случайно содержать незакоммиченные изменения;
  • удалённая приёмка Web UI зависит от доступности конкретного разработчика;
  • длительные тесты прерываются закрытием крышки, перезагрузкой или сменой сети.

Если вы собираете один инструмент раз в месяц, локальная машина обычно достаточна. Если плагины строятся ежедневно, тестируются несколькими инженерами и должны оставаться доступными после окончания рабочего дня, отдельный удалённый Mac даёт более предсказуемую точку входа. В этом случае стоит заранее изучить варианты удалённой аренды Mac для разработки и правила сохранения рабочего окружения.

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

Если сейчас вы распределяете разработку по личным Mac, получаете разные версии Node.js, теряете контекст после отключения и вручную восстанавливаете профили, переход на аренду Mac через VpsMesh может быть практичнее покупки отдельного устройства под каждый эксперимент. Сначала завершите минимальный плагин и измерьте частоту сборок, число участников и длительность тестов. Если эти показатели требуют постоянной доступности, переносите уже проверенный процесс на сохраняемую удалённую среду, а не арендуйте её вслепую.