Перейти к содержимому

Решение проблем (Troubleshooting)

Ошибки авторизации: API-ключ не найден (DEEPSEEK_API_KEY Not Found)

Симптомы

  • В веб-интерфейсе блокируется создание сессий.
  • В логах headless-режима или консоли выводится ошибка: dsh: AUTH: Authentication Fails, Your api key: ****alid is invalid (процесс завершается с кодом ошибки 1).
  • Ошибка MISSING_CREDENTIAL при попытке отправить запрос к модели.

Причина и логика поиска ключей (Credentials Chain)

Рантайм dsh осуществляет поиск API-ключей по строгой цепочке приоритетов:

  1. Переменные окружения текущего терминала (например, DEEPSEEK_API_KEY).
  2. Файл защищённых учётных записей $DSH_HOME/.credentials.yaml.
  3. Локальный файл .env в текущей рабочей директории вызова.
  4. Файл $DSH_HOME/.env.

Если ни один из этих источников не содержит валидный ключ, dsh блокирует вызовы API. В headless-режиме ключ маскируется звёздочками (****alid) в потоке ошибок stderr, чтобы предотвратить его утечку в логи систем мониторинга.

Решение

  • Для интерактивного Web UI: перейдите в Settings → Models, вставьте ваш ключ в поле DeepSeek (или другого провайдера) и сохраните. Ключ запишется в $DSH_HOME/.credentials.yaml в зашифрованном/скрытом (write-only) формате.

  • Для Headless-автоматизации и CI/CD: передавайте ключ напрямую через переменные окружения терминала при запуске команды.

    # Linux/macOS
export DEEPSEEK_API_KEY="sk-..."

    # Windows (PowerShell)
$env:DEEPSEEK_API_KEY="sk-..."

  • Проверка активности ключа: выполните команду echo $DEEPSEEK_API_KEY (или echo $env:DEEPSEEK_API_KEY на Windows), чтобы убедиться, что переменная успешно экспортирована в текущую сессию терминала.

Ошибки логики (Reasoning): 400 Reasoning Content Error

Симптомы

  • Модель начинает выполнять задачу, совершает один или несколько шагов, после чего сессия падает с ошибкой HTTP 400 Bad Request или сообщением об ошибке reasoning_content.
  • В логах шлюза/прокси появляется ошибка: Responses API 400: hook/developer message between function_call and its output -> 'No tool output found for tool call'.

Причина

Флагманские модели DeepSeek (такие как V4-Pro, V4-Flash или R1) используют Thinking Mode (режим глубоких рассуждений). В этом режиме модель генерирует скрытые токены мыслительного процесса, которые отдаются API в специальном поле reasoning_content.

Согласно строгому контракту API DeepSeek:

  1. Если шаг ассистента содержит вызов инструмента (Tool Call) и блок reasoning_content, клиент обязан вернуть этот блок reasoning_content целиком в следующем запросе в составе истории сообщений.
  2. Если вы используете сторонний прокси-сервер, кастомный адаптер, шлюз или внешнюю систему логирования, которая срезает, модифицирует или теряет поле reasoning_content при передаче истории обратно на сервер, API DeepSeek немедленно вернёт ошибку HTTP 400.
  3. Также запрещено вставлять какие-либо служебные/системные сообщения или сообщения разработчика (developer/system/user) в промежутке между вызовом инструмента моделью и возвратом результата его выполнения.

Решение

  • Используйте официальные адаптеры dsh: рантайм-сервис ctx.llm в dsh спроектирован с учётом этого инварианта и автоматически сохраняет и передаёт структуру reasoning_content.

  • Проверьте настройки кастомного шлюза: если вы перенаправляете запросы через сторонние шлюзы (например, OpenRouter, LiteLLM, vLLM), убедитесь, что они поддерживают и прозрачно транслируют поле reasoning_content.

  • Альтернативное решение (отключение рассуждений): если ваша инфраструктура принципиально не может сохранять reasoning_content между ходами, переведите модель в Non-thinking Mode. Для этого в конфигурационном файле $DSH_HOME/settings.yaml (или при запуске через llama.cpp / vllm) принудительно отключите генерацию рассуждений:

    # settings.yaml
llm-pi-ai:
  providers:
    my-custom-gateway:
      compat:
        supportsDeveloperRole: false
      # Отключение thinking в аргументах шаблона
      customArgs:
        enable_thinking: false

    Или передайте аргумент запуска --chat-template-kwargs '{"enable_thinking":false}'.

Ограничения контекста: лимиты контекстного окна (Context-Length Limits)

Симптомы

  • Ошибка Context-length error во время длинных автономных сессий.
  • Резкое падение скорости генерации ответов или лавинообразный рост стоимости токенов.

Причина

DeepSeek Harness маниакально следует принципу «Model-visible means logged» (Всё, что видит модель, должно быть записано в лог). dsh записывает в SQLite-базу всю историю сессии, включая гигантские выводы Bash-команд, содержимое прочитанных файлов и системные промпты. В результате размер контекста на один шаг (Turn) может мгновенно вырасти с 4К до 100К+ токенов, упираясь в жёсткий лимит модели (например, 128К).

Решение

  • Используйте автоматическое сжатие контекста (Context Compaction): убедитесь, что в профиле dsh активен плагин @deepseek-ai/dsh-compaction-basic. При заполнении контекстного окна на 80% (thresholdRatio: 0.8) dsh автоматически запускает фоновую модель для суммаризации ранней истории, высвобождая до 60–70% контекста без потери ключевого прогресса.

  • Настройте усечение результатов инструментов (Pruner): ограничьте размер вывода тяжёлых терминальных утилит в settings.yaml с помощью плагина @deepseek-ai/dsh-compaction-tool-result-pruner:

    # settings.yaml
"@deepseek-ai/dsh-compaction-tool-result-pruner":
  thresholdChars: 8192  # Обрезать вывод, если он превышает 8 КБ текста
  headChars: 4096       # Сохранить первые 4 КБ
  tailChars: 1024       # Сохранить последние 1 КБ

  • Используйте PTC (Code) Mode: если вам нужно выполнить тяжёлый рефакторинг со множеством шагов, переключитесь из Standard Mode в PTC Mode. В этом режиме модель генерирует единую TypeScript-программу, которая выполняет все операции локально внутри рантайма, отправляя в контекст только конечный результат, что экономит до 90% токенов.

Искажённые потоковые вызовы: Malformed Streaming Tool Calls

Симптомы

  • Агент прерывает работу с ошибками валидации аргументов вызова функций.
  • Инструменты падают с синтаксическими ошибками JSON (SyntaxError: Unexpected token...).

Причина

При стриминге (потоковом выводе токенов) DeepSeek возвращает аргументы вызова функций в виде множества мелких фрагментов (deltas). Стриминговые фрагменты от разных инструментов могут приходить вперемешку, нарушая хронологический порядок. Если ваш клиент или прокси-сервер просто склеивает входящий текст подряд без учёта индексов, результирующий JSON-объект аргументов гарантированно окажется сломанным и искажённым.

Решение

  • Сборка строго по индексам (tool_call.index): на стороне приёма стриминга обязательно агрегируйте фрагменты аргументов (deltas), группируя их строго по значению tool_call.index, как предписывает спецификация вызова инструментов в dsh.
  • Используйте готовый пайплайновый парсер dsh: по возможности доверьте разбор стриминга внутреннему сервису ctx.tools из официального бандла @deepseek-ai/dsh-tools, который гарантирует корректную сборку параллельных и асинхронных вызовов.

PTC-режим: сбои на уровне Worker-потока

PTC-режим (в кодовой базе dsh известный как Code Mode) представляет собой альтернативный способ работы ИИ-агента. Вместо пошагового выполнения команд по ReAct-циклу (think → act → observe) модель генерирует цельную программу на TypeScript, которая пакетно оркеструет вызовы инструментов через специальное Code Mode SDK.

Поскольку код модели исполняется локально внутри среды dsh, эта архитектура имеет специфические точки отказа. Сгенерированный моделью TypeScript-код запускается в изолированном фоновом потоке Node.js с помощью плагина @deepseek-ai/dsh-code-runtime-worker-thread. Для предотвращения зависания хост-системы плагин накладывает жёсткие ограничения на выполнение, выход за которые приводит к фатальным ошибкам:

  • Превышение лимита активного времени процессора (computeMs):
    • Симптом: выполнение аварийно прерывается с ошибкой типа timeout.
    • Причина: скрипт модели ушёл в бесконечный синхронный цикл (например, while(true)). Рантайм dsh измеряет не астрономическое время выполнения, а чистую загрузку событийного цикла через Node.js API worker.performance.eventLoopUtilization(). Если это значение превышает лимит computeMs (например, при сложных вычислениях), воркер останавливается.
  • Таймаут по общему «настенному» времени (maxWallMs):
    • Симптом: выполнение зависает и затем принудительно останавливается.
    • Причина: скрипт модели ожидает асинхронное обещание (Promise), которое никогда не разрешится (deadlock). Ограничение maxWallMs служит предохранителем для асинхронных зависаний, которые не фиксируются через метрику загрузки процессора.
  • Сбой из-за переполнения кучи (worker-exit):
    • Симптом: рантайм сообщает о внезапном завершении потока с кодом ошибки worker-exit.
    • Причина: скрипт модели превысил максимальный объём памяти кучи (maxOldGenerationSizeMb), что вызвало аварийное завершение процесса (OOM) на уровне Node.js.
  • Превышение размера сериализованного вывода (maxOutputBytes):
    • Симптом: ошибка переполнения буфера вывода.
    • Причина: сгенерированный код выводит в лог слишком тяжёлые массивы данных или возвращает избыточно большой JSON-объект, превышающий установленный в байтах лимит maxOutputBytes.

PTC-режим: ошибки сборки промпта и логические ошибки SDK

Ошибка отсутствия рантайма (ctx.codeRuntime)

  • Симптом: фатальный сбой сборки системного промпта при запуске сессии.
  • Причина: режим PTC требует обязательного наличия в Cordis-контексте сервиса ctx.codeRuntime с поддержкой генерации SDK (TypeScript). Если этот плагин был принудительно отключён в cordis.patch.yml или не загрузился из-за транзакционного сбоя boot-тракта, запуск PTC-режима блокируется.

Конфликт имён инструментов в toolOrder

  • Симптом: ошибка валидации конфигурации при старте.
  • Причина: в режиме 'code' модель видит только один мета-инструмент — run_code, а все нативные утилиты скрыты внутри SDK. Если в настройках профиля (например, в блоке toolOrder плагина dsh-system-prompt) вручную прописаны нативные имена (например, str_replace_editor), рантайм выдаёт ошибку, так как нативные вызовы инструментов запрещены при активном режиме генерации кода.

Превышение лимита параллельных вызовов (maxParallelSubCalls)

  • Симптом: ошибка параллельного исполнения инструментов внутри скрипта.
  • Причина: кодовое SDK позволяет модели выполнять асинхронные вызовы нескольких инструментов одновременно (например, параллельно читать три файла). Лимит параллельности по умолчанию равен 10 (maxParallelSubCalls). Если модель генерирует код с избыточным распараллеливанием, dsh блокирует вызовы во избежание перегрузки файловой системы или гонки ресурсов.

Конфликт эксклюзивных блокировок (Exclusive Barriers)

  • Симптом: скрипт падает с ошибкой блокировки ресурсов.
  • Причина: нативные инструменты dsh делятся на конкурентно-безопасные и эксклюзивные (например, терминал Bash требует монопольного владения). Если модель внутри программы пытается запустить эксклюзивный инструмент параллельно с другими утилитами, рантайм прерывает исполнение для соблюдения контракта безопасности.

Методы диагностики и лечения

  1. Инспекция сгенерированного TS-кода через Trajectory View: откройте вкладку Trajectory в Web UI dsh. Каждое событие запуска run_code содержит точный текст сгенерированной TypeScript-программы, переданные ей аргументы, поток stdout/stderr исполнения воркера и подробный трассировочный стек ошибок в случае падения.
  2. Корректировка лимитов в settings.yaml: если модель часто упирается в лимиты памяти или времени на сложных задачах, увеличьте бюджет воркера в глобальной конфигурации — шаблон приведён в разделе настройки settings.yaml.
  3. Перезапуск воркера при зависании: если сессия воркера полностью заблокирована бесконечным ожиданием, воспользуйтесь функцией Fork на предыдущем (зелёном) шаге таймлайна в Trajectory View, чтобы начать выполнение по новой траектории с исправленными вводными инструкциями.

Настройка settings.yaml

Где находится settings.yaml?

По умолчанию глобальный конфигурационный файл находится по пути:

  • $DSH_HOME/settings.yaml (если переменная окружения не задана, dsh ищет его по пути ~/.dsh/settings.yaml).
  • Если вы запускаете dsh через интеграцию с Ollama, настройки будут считываться и сохраняться в ~/.ollama/launch/dsh/settings.yaml.

Параметры настройки PTC в settings.yaml

Для тонкой настройки PTC-режима вам понадобятся два ключевых плагина: @deepseek-ai/dsh-tools (управляет стилем вызова инструментов) и @deepseek-ai/dsh-code-runtime-worker-thread (задаёт ограничения для песочницы выполнения кода).

Готовый шаблон конфигурации, который вы можете вставить в ваш settings.yaml:

# settings.yaml

# 1. Настройка презентации инструментов и параллельности
"@deepseek-ai/dsh-tools":
  # Способ предоставления инструментов модели:
  # 'code' — модель видит только run_code и генерирует TS-скрипт (PTC режим).
  # 'native' — классический ReAct-цикл (пошаговый вызов).
  # 'both' — предоставляет оба интерфейса.
  mode: "code"

  # Максимальное количество параллельно выполняемых инструментов (асинхронных sub-calls)
  # внутри сгенерированной ИИ программы. По умолчанию равен 10.
  # Установка значения в 1 вернёт модель к строго последовательному исполнению.
  maxParallelSubCalls: 10

# 2. Настройка лимитов песочницы исполнения TS-кода (Worker Thread)
"@deepseek-ai/dsh-code-runtime-worker-thread":
  # Бюджет чистого процессорного времени (Active CPU Time) в миллисекундах.
  # Измеряет время, когда поток реально занят вычислениями (Event Loop utilization).
  # Предотвращает зависания при уходе ИИ-кода в бесконечные циклы.
  computeMs: 15000

  # Жёсткий лимит астрономического времени (Wall-Clock Time) в миллисекундах.
  # Защита от вечного ожидания асинхронных Promises, которые никогда не разрешатся.
  # Максимально допустимое значение: 2147483647 (около 24.9 дней).
  maxWallMs: 60000

  # Ограничение на максимальный размер возвращаемых данных (JSON, логи, массивы) в байтах.
  # Предотвращает переполнение буфера обмена между воркером и основной средой.
  maxOutputBytes: 1048576 # 1 МБ

  # Максимальный объём выделяемой оперативной памяти (V8 Heap Size) в Мегабайтах.
  # Если TS-скрипт модели превысит этот лимит, поток аварийно завершится с ошибкой 'worker-exit'.
  maxOldGenerationSizeMb: 512

Дополнительная оптимизация контекста при PTC

Поскольку модель в PTC-режиме может генерировать длинные цепочки вызовов инструментов, возвращаемые результаты могут быстро засорить контекстное окно. Чтобы этого не происходило, рекомендуется настроить автоматическое урезание слишком больших текстовых ответов от локальных инструментов:

# Настройка детерминированного прунера результатов работы инструментов
"@deepseek-ai/dsh-compaction-tool-result-pruner":
  # Срабатывать, если размер текстового вывода инструмента превышает данный лимит символов:
  thresholdChars: 8192

  # Сколько символов сохранить от начала вывода:
  headChars: 4096

  # Сколько символов сохранить от конца вывода (для логов ошибок терминала):
  tailChars: 1024

Как проверить, применились ли изменения?

Вам не нужно перезапускать сервер dsh при редактировании settings.yaml вручную, так как система поддерживает автоматическое горячее перечитывание конфигурации Cordis.

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

dsh --profile web --dump-config

Эта команда выведет полное собранное дерево конфигурации с указанием того, какие именно строки были переопределены вашим локальным патчем.

Быстрый справочник по системным ошибкам рантайма (CLI & Systemd)

Наблюдаемая ошибка / Код сбоя Вероятная причина Быстрое решение / Команда
Error: listen EADDRINUSE ... :3080 Порт 3080 уже занят другим процессом dsh (например, зависшим фоновым npx). Найдите и убейте процесс: sudo ss -lntp | grep 3080, затем kill -9 <PID>.
EACCES: permission denied У пользователя нет прав на чтение/запись в проектной папке или в каталоге $DSH_HOME. Восстановите права владельца: sudo chown -R $USER:$USER ~/.dsh.
profile "xxx" does not exist Попытка запустить несуществующий профиль. Автоматически инициализируются только web и headless. Создайте новый профиль вручную перед использованием: dsh plugin --profile <имя> add dsh-base.
No matching distribution found for deepseek-harness-sdk Пакет Python SDK ещё не опубликован в глобальный репозиторий PyPI или операционная система не поддерживается (Windows). Используйте нативный CLI-интерфейс dsh --profile headless в качестве альтернативы на Windows.