[позже] Диагностика (общая)

Глава 12. Диагностика и устранение проблем: что делать, когда что-то пошло не так

Вы прошли долгий путь. Установили DSH, настроили профили, подключили GitHub и сервер, научились писать промпты и даже запустили несколько реальных сценариев. Но рано или поздно вы столкнётесь с ситуацией, когда агент сделает не то, зависнет, выдаст ошибку или потратит слишком много токенов.

Это нормально. DeepSeek Harness — экспериментальный инструмент, и ошибки неизбежны. Важно не паниковать, а знать, как диагностировать проблему и что делать.

Эта глава — ваш «скорый помощник» по отладке. Все советы проверены на практике и написаны простым языком для маркетолога.

12.1. Первый шаг: не паниковать, смотреть логи

Когда агент делает что-то странное, не перезапускайте сразу и не закрывайте терминал. Сначала посмотрите на Trajectory — это полный лог всех действий агента.

Как открыть Trajectory:
1. В веб-интерфейсе откройте историю сессии (обычно слева или в меню).
2. Найдите нужную сессию (по дате и времени).
3. Нажмите на кнопку с иконкой списка или «Trajectory».
4. Вы увидите пошаговый лог: каждый запрос к модели, каждый вызов инструмента, каждый ответ.

Что вы увидите в Trajectory и о чём это говорит:

Правило: прежде чем задавать вопрос в чат поддержки или писать разработчикам, посмотрите Trajectory. Там обычно видно, где именно агент «споткнулся».

12.2. Частые ошибки и их решения

Вот список самых частых проблем, с которыми сталкиваются пользователи DSH, и что с ними делать.

Проблема 1: Агент не видит файлы или папки

Симптомы:
- Агент отвечает «файл не найден», хотя вы точно знаете, что он есть.
- Агент создаёт файлы в неправильном месте.

Причины:
- Не выбрана рабочая область (workspace).
- Пути указаны относительно, а агент «думает» в другой директории.

Что делать:
1. Проверьте, что в веб-интерфейсе выбрана правильная рабочая область (Settings → Workspace).
2. Укажите абсолютный путь в промпте: вместо файл.txt напишите /home/user/project/файл.txt.
3. Попросите агента показать текущую директорию: «Выполни команду pwd и покажи содержимое папки».

Проблема 2: Агент зависает или уходит в бесконечный цикл

Симптомы:
- Агент долго думает (более 2-3 минут).
- Агент повторяет одни и те же действия (читает один и тот же файл, запускает одну команду).
- В Trajectory видно, что шаги растут без остановки.

Причины:
- Слишком сложная или расплывчатая задача.
- Агент не может принять решение.
- Баг в плагине или модели.

Что делать:
1. Остановите сессию — в веб-интерфейсе есть кнопка «Stop».
2. Откройте Trajectory, посмотрите, на каком шаге зацикливание.
3. Уточните промпт: «Сделай не более 5 шагов» или «Если не можешь найти файл, остановись и сообщи».
4. Установите лимит шагов в профиле (max_steps: 15), чтобы агент не уходил в бесконечность.

Проблема 3: Ошибка подключения к GitHub

Симптомы:
- Агент не может клонировать репозиторий.
- Агент не может запушнуть изменения.
- Ошибка аутентификации.

Что делать:
1. Проверьте, что плагин GitHub установлен и настроен (Глава 4).
2. Зайдите в настройки GitHub и проверьте, действителен ли ваш токен (не истёк ли срок).
3. Переподключите GitHub через OAuth заново.
4. Проверьте права токена: нужен доступ repo (для приватных репозиториев) и workflow (если используете Actions).

Проблема 4: Не подключается к серверу (SSH)

Симптомы:
- Ошибка Connection refused, Host key verification failed или Permission denied.

Что делать:
1. Проверьте IP-адрес и порт сервера (обычно 22).
2. Проверьте имя пользователя и пароль/ключ.
3. Если используете ключ, убедитесь, что публичный ключ скопирован на сервер (~/.ssh/authorized_keys).
4. Проверьте, открыт ли порт 22 в файерволе сервера.
5. Попробуйте вручную подключиться по SSH из терминала: ssh пользователь@IP. Если не подключается — проблема на стороне сервера.

Проблема 5: Слишком много токенов, расходы зашкаливают

Симптомы:
- Баланс на платформе DeepSeek быстро тает.
- В Trajectory видно, что каждый шаг съедает 10 000+ токенов.

Что делать:
1. Установите лимиты в профиле: max_steps: 10, max_tokens: 30000.
2. Используйте дешёвую модель (DeepSeek-V4-Flash вместо Pro).
3. Убедитесь, что вы не используете PTC-режим для простых задач.
4. Сократите промпт — уберите лишние слова, давайте только суть.
5. Используйте плагины для мониторинга бюджета (Глава 10).

Проблема 6: Агент игнорирует мои инструкции

Симптомы:
- Вы сказали «не удаляй файлы», а агент их удалил.
- Вы сказали «используй только Python», а агент пишет на JavaScript.

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

Что делать:
1. Уточните промпт с помощью структуры из Главы 7: цель, ресурсы, шаги, ограничения, обработка ошибок.
2. Повторите ограничение несколько раз: «ОЧЕНЬ ВАЖНО: не удаляй никакие файлы».
3. Проверьте профиль — может быть, там указан другой язык или режим.
4. Попросите агента подтвердить понимание перед началом: «Подтверди, что ты понял задачу и что ты не будешь удалять файлы».

12.3. Инструменты для отладки

Кроме встроенной Trajectory, есть несколько плагинов и команд, которые помогают диагностировать проблемы.

Команда для быстрой диагностики:

dsh --profile web --dump-config > config_report.txt

Сохраняет все настройки в файл — можно отправить в поддержку или изучить самому.

12.4. Что делать, если ничего не помогает

Бывают ситуации, когда вы перепроверили всё, а агент всё равно не работает. Вот план действий:

1. Перезапустите DSH — закройте терминал и запустите dsh web заново. Иногда помогает сброс состояния.
2. Создайте новый профиль — dsh plugin --profile test и повторите настройку с нуля. Возможно, текущий профиль повреждён.
3. Проверьте обновления — npm update -g @deepseek-ai/dsh — возможно, баг уже исправлен в новой версии.
4. Задайте вопрос в сообществе — есть официальный Discord, GitHub Issues, а также русскоязычные каналы. Опишите:
   - Что вы хотели сделать
   - Что сделали
   - Что увидели (ошибку или странное поведение)
   - Приложите Trajectory или вывод --dump-config
5. Временно вернитесь к Cursor — если задача критичная и срочная, не рискуйте. Используйте DSH для экспериментов, а важное делайте в привычном инструменте.

12.5. Лучшие практики для профилактики проблем

Чтобы ошибки случались реже, следуйте этим правилам:

1. Всегда начинайте с малого. Дайте простую задачу, убедитесь, что агент её понял, потом усложняйте.
2. Тестируйте в безопасной среде. Создайте отдельный тестовый репозиторий и тестовый сервер.
3. Сохраняйте успешные промпты. Как только у вас получился хороший результат — сохраните промпт в отдельный файл. Вы сможете использовать его как шаблон.
4. Регулярно обновляйте плагины. dsh plugin --profile web update — это исправляет баги.
5. Включайте лимиты. max_steps и max_tokens в профиле — это ваша страховка от бесконечных циклов и больших счетов.
6. Смотрите Trajectory после каждой сложной задачи. Даже если всё прошло успешно, полезно увидеть, как агент рассуждал.

12.6. Итоговый чек-лист по устранению неполадок

Если что-то пошло не так, пройдите по пунктам:

1. [ ] Посмотрел ли я Trajectory? (где именно ошибка?)
2. [ ] Проверил ли я рабочую область (workspace)?
3. [ ] Проверил ли я API-ключ и баланс?
4. [ ] Убедился ли я, что плагины установлены и подключены?
5. [ ] Есть ли у меня лимиты на шаги и токены?
6. [ ] Если ошибка с сервером/GitHub — подключается ли вручную?
7. [ ] Если ошибка с промптом — достаточно ли он чёткий?
8. [ ] Не пора ли перезапустить DSH или создать новый профиль?
9. [ ] Если ничего не помогает — обратился ли я в сообщество с логами?

12.7. Финальное слово по учебнику

Вы прошли основной курс. На практике важнее чек-лист, чем пафос:

• умеете запустить DSH и читать Trajectory / /cost;
• правила проектов лежат в git (AGENTS.md, plan.md), а не только в исчезнувшем чате Cursor;
• GitHub и SSH узкие; main и root не «по умолчанию»;
• любая задача закрывается приёмкой (ветка, URL, секреты), а не словом «готово».

DSH — сырой инструмент. Он может продолжить ваши проекты, если вы держите дисциплину. Надёжность даёт не harness, а ваши лимиты, изоляция и проверка результата. Если что-то сломалось — вернитесь к главе «Страховка» и блоку безопасности сервера.

Что дальше? Приложения

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

Приложение А — Шпаргалка по основным терминам (на русском и английском).
Приложение Б — Команды для терминала (все, что вы использовали в главах).
Приложение В — Шаблоны промптов для частых задач.
Приложение Г — Список проверенных плагинов с описаниями.
Приложение Д — Часто задаваемые вопросы (FAQ).