DeepSeek Harness: власний провайдер через JoinGonka Gateway

Харнес — це все, що оточує модель в агентній роботі: цикл «запит → виклик інструменту → результат → наступний крок», інструменти для файлів і термінала, права та підтвердження, журнал сесії, стиснення контексту. DeepSeek Harness збирає це з плагінів: архітектура «everything is a plugin» побудована на фреймворку Cordis, і будь-який вузол — від інструменту до адаптера моделі — замінюється без правки ядра. Код відкритий під ліцензією MIT.

Встановлення не потрібне — достатньо Node.js (лінійка 22 починаючи з 22.19 або 24 і новіше):

npx @deepseek-ai/dsh web

Команда піднімає Web UI на http://127.0.0.1:3080 і відкриває його в браузері; при запуску по SSH адреса лише друкується в терміналі. Прапорець --no-open запускає сервер без браузера, --port змінює порт. Каталог, з якого запущено dsh, стає робочим за замовчуванням, але сесію інтерфейс почне лише після явного вибору workspace.

Модельний шар складається з двох адаптерів. Прямий ходить в офіційний API вендора. Багатопровайдерний — dsh-llm-pi-ai — побудований на бібліотеці pi-ai, тій самій, що лежить в основі термінального агента Pi; через нього підключаються і вбудовані постачальники з каталогу, і будь-які свої endpoint. Тому імена полів у налаштуваннях — api, contextWindow, maxTokens — збігаються з тими, що знайомі по Pi.

Про зрілість. README проєкту починається з попередження: developer preview, швидкі ітерації, ламкі зміни. Окремий документ SAFETY.md уточнює, що аудит безпеки не проводився, а агент виконує команди, згенеровані моделлю. Практичний висновок простий: запускайте dsh у контейнері, віртуальній машині або під окремим обліковим записом і тримайте резервні копії всього, до чого він може дотягнутися.

Крок 1: ключ. Зареєструйтеся на gate.joingonka.ai/register: після підтвердження адреси на рахунок надійдуть 3M безкоштовних токенів. У кабінеті відкрийте розділ «API-ключі» та створіть ключ із префіксом jg-. Зручно завести для харнеса окремий ключ — тоді його трафік буде видно в статистиці окремим рядком.

Крок 2: перший екран. Після повідомлення про тестовий статус (кнопка Continue) dsh запропонує ввести ключ офіційного API («Add an API key to get started»). Він не обов'язковий: натисніть Configure later.

Крок 3: провайдер. Відкрийте Settings → Models і виберіть Add a custom provider. Поля форми:

Крок 4: моделі. У блоці Models натисніть Fetch available models: dsh запросить у шлюзу список і відкриє вікно «Choose models to add». У нашому прогоні в ньому опинилися всі три моделі мережі — MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 і zai-org/GLM-5.3-Flash, — а після Add selected харнес сам проставив кожній вікно контексту й стелю відповіді — за даними шлюзу. Залишається натиснути Create provider.

Крок 5: вибір моделі. Закрийте налаштування, натисніть Choose workspace і додайте каталог проєкту. Моделі нового провайдера з'являться в селекторі; вибрана стає моделлю за замовчуванням для нових сесій.

Ключ dsh зберігає окремо від налаштувань: у файлі ~/.dsh/.credentials.yaml з правами лише для власника. У settings.yaml залишається лише ім'я посилання на нього — у нашому прогоні JOINGONKA_API_KEY, за ідентифікатором провайдера.

Який протокол вибрати. Шлюз говорить усіма трьома, різняться базова адреса й побічні зручності:

Один провайдер у dsh говорить однією мовою, тому другий протокол — це другий провайдер з іншим Provider ID. Для щоденної роботи достатньо першого варіанта; у нашому прогоні агентний цикл із викликом інструментів відпрацював на всіх трьох.

Форма Models пише у звичайний YAML-документ — $DSH_HOME/settings.yaml, за замовчуванням ~/.dsh/settings.yaml. Його можна редагувати напряму: кнопка Open configuration file у шапці налаштувань відкриває файл, а адаптери перечитують його під час наступного запиту — перезапуск не потрібен. Повний варіант для мережі Gonka:

# ~/.dsh/settings.yaml
llm-pi-ai:
  providers:
    joingonka:
      displayName: JoinGonka Gateway
      apiKeyEnv: JOINGONKA_API_KEY
      api: openai-completions
      baseURL: https://gate.joingonka.ai/v1
      models:
        - id: deepseek-ai/DeepSeek-V4-Flash-0731
          name: DeepSeek V4 Flash
          contextWindow: 380000
          maxTokens: 32768
        - id: zai-org/GLM-5.3-Flash
          name: GLM-5.3 Flash
          contextWindow: 390000
          maxTokens: 8192
          reasoningEfforts:
            off: low
            high: high
        - id: MiniMaxAI/MiniMax-M2.7
          name: MiniMax M2.7
          contextWindow: 200000
          maxTokens: 8192
agent-default-model:
  provider: joingonka
  model: deepseek-ai/DeepSeek-V4-Flash-0731

Що тут важливо:

• apiKeyEnv — не ключ, а ім'я посилання на нього. Значення dsh шукає по черзі: змінна середовища на момент запуску, потім .credentials.yaml (туди пише форма), потім .env у каталозі запуску, потім ~/.dsh/.env. Якщо налаштовуєте харнес без браузера, достатньо рядка JOINGONKA_API_KEY=jg-your-key у ~/.dsh/.env з правами 600. Змінну, експортовану після старту, вже запущений процес не побачить.
• contextWindow і maxTokens задавайте явно. Моделі, про яку dsh нічого не знає, він приписує 262 144 і 32 768 токенів — реальним лімітам це не відповідає. Заданий maxTokens заодно стає лімітом відповіді за замовчуванням для кожного запиту.
• reasoningEfforts — рівні міркування для меню Effort. У моделі, вписаної вручну, рівнів немає, і меню для неї не з'являється. У GLM-5.3 Flash перемикач двійковий: значення low вимикає міркування, будь-яке інше залишає його повним. Тому рівню off зіставлено low, а high передається як є. У нашому прогоні з off блоків міркування не було зовсім, з high вони повернулися.
• agent-default-model — модель для нових агентів, включно з режимом headless. Те саме робить вибір моделі в інтерфейсі; сюди ж можна додати reasoningEffort.

Перемикачі compat, які документація dsh радить для строгих шлюзів (supportsDeveloperRole: false, maxTokensField: max_tokens), тут не знадобляться: JoinGonka Gateway приймає і роль developer, і поле max_completion_tokens.

Інсталятор npx @joingonka/setup цей харнес не налаштовує: усе підключення зводиться до форми з попереднього розділу або до YAML-фрагмента вище.

Найшвидше перевірити зв'язку — це разовий запуск із каталогу з кодом. Покладіть поряд невеликий файл з очевидною помилкою і попросіть її знайти:

cd /path/to/project
npx @deepseek-ai/dsh --profile headless "Read calc.py and tell me in one sentence whether it has a bug."

Фінальна відповідь друкується в stdout, хід міркувань — у stderr з позначкою dsh: reasoning:. Агент має сам викликати інструмент читання файлу й відповісти по суті: у нашому запуску кожна з трьох моделей мережі назвала хибний рядок. Отже, повний цикл «запит → виклик інструменту → результат → відповідь» через шлюз збирається коректно.

Друга половина перевірки — на боці шлюзу. У кабінеті відкрийте «Використання»: там видно запити по годинах і днях, розбивку за моделями та за ключами. З'явився рядок з ключем харнеса й свіжим часом останнього запиту — трафік справді йде через шлюз.

Якщо щось пішло не так, діагноз зазвичай читається прямо з повідомлення:

Ціна у всіх моделей мережі одна, тому вибір — про поведінку, а не про бюджет. Нижче — ліміти та те, як моделі поводилися в нашому прогоні dsh на одній і тій самій задачі: прочитати файл і знайти в ньому помилку.

Рекомендація за замовчуванням — DeepSeek V4 Flash: агентна робота швидко впирається в обсяг контексту та довжину правки, а тут запас за обома параметрами. Коли задача вимагає подумати над заплутаною логікою, перемикайтеся на GLM-5.3 Flash і тримайте рівень міркування high; для швидких правок той самий провайдер віддає її з рівнем off. MiniMax M2.7 — рівний варіант для коротких задач, коли видимий хід міркувань не заважає. Модель змінюється в селекторі інтерфейсу або рядком model у блоці agent-default-model.

Склад мережі визначається голосуванням учасників і з часом змінюється; актуальний список разом із лімітами завжди віддає GET https://gate.joingonka.ai/v1/models — ним же користується кнопка Fetch available models.

Агентні інструменти витрачають токени інакше, ніж чат: до кожної вашої фрази харнес додає системний промпт і описи всіх інструментів, а потім веде багатокроковий діалог з моделлю. У нашому прогоні завдання «прочитай файл і знайди помилку» зайняло два-три кроки і від 14 до 22 тисяч токенів, причому майже все це вхід: близько семи тисяч токенів йде з кожним кроком ще до вашого запитання. Це нормальна плата за автономність — і саме тому вирішує ціна за токен.

Через JoinGonka Gateway токени коштують $0.0069 за мільйон на вході та $0.021 за мільйон на виході — ціна однакова для всіх моделей мережі і підставляється на цій сторінці з живого джерела. Порядок величин за цінами на вересень 2026:

Оплата йде за фактичні витрати, без підписки і без квот на кількість запитів; залишок і витрати по днях видно в кабінеті.

Версія. Поки проект у статусі developer preview, після кожного оновлення перевіряйте, що провайдер на місці, а для відтворюваності фіксуйте версію прямо в команді: npx @deepseek-ai/[email protected] web.

Права. Нові сесії за замовчуванням працюють у режимі Workspace Write — запис у межах робочого каталогу; операції понад політику інтерфейс просить підтвердити. Режим змінюється в Settings → General.

Повтори. При разовій мережевій помилці dsh повторює запит сам — за документацією до п'яти разів, — тому короткий сплеск навантаження в мережі зазвичай проходить непомітно.

Приватність. Шлюз не зберігає вміст промптів і відповідей: у статистиці залишаються тільки агрегати витрат. Файли проекту агент читає локально, на вашій машині.

Якщо потрібна робота з картинками — скріншот інтерфейсу, схема на фото — заведіть поруч другого провайдера з моделлю, що вміє зір: dsh тримає кілька провайдерів одночасно, а моделі мережі Gonka текстові.

DeepSeek Harness — не єдиний агент, який випускає сама лабораторія-розробник моделей: у Z.ai, авторів GLM, є середовище ZCode, а у MiniMax — термінальний MiniMax Code. Обидва підключаються до того ж шлюзу з тим же ключем.