Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
189 lines (135 loc) · 19.9 KB

TROUBLESHOOTING.md

File metadata and controls

189 lines (135 loc) · 19.9 KB

Устранение неполадок gac

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | हिन्दी | Tiếng Việt | Français | Русский | Español | Português | Norsk | Svenska | Deutsch | Nederlands | Italiano

Это руководство охватывает общие проблемы и решения для установки, настройки и запуска gac.

Содержание

1. Проблемы с настройкой

Проблема: Команда uvx не найдена

  • Установите uv, следуя инструкциям на astral.sh/uv
  • Убедитесь, что uv установлен и находится в вашем $PATH
  • Перезапустите терминал после установки

2. Проблемы с конфигурацией

Проблема: gac не может найти ваш API-ключ или модель

  • Если вы новичок, запустите uvx gac init для интерактивной настройки вашего поставщика, модели и API-ключей
  • Убедитесь, что ваш .gac.env или переменные окружения установлены правильно
  • Запустите uvx gac --log-level=debug чтобы увидеть, какие конфигурационные файлы загружаются и отладить проблемы с конфигурацией
  • Проверьте наличие опечаток в именах переменных (например, GAC_GROQ_API_KEY)

Проблема: Изменения в пользовательском уровне $HOME/.gac.env не применяются

  • Убедитесь, что вы редактируете правильный файл для вашей ОС:
    • На macOS/Linux: $HOME/.gac.env (обычно /Users/<your-username>/.gac.env или /home/<your-username>/.gac.env)
    • На Windows: $HOME/.gac.env (обычно C:\Users\<your-username>\.gac.env или используйте %USERPROFILE%)
  • Запустите uvx gac --log-level=debug чтобы подтвердить загрузку конфигурации пользовательского уровня
  • Перезапустите терминал или перезапустите вашу оболочку для перезагрузки переменных окружения
  • Если всё ещё не работает, проверьте наличие опечаток и прав доступа к файлу

Проблема: Изменения в уровне проекта .gac.env не применяются

  • Убедитесь, что ваш проект содержит файл .gac.env в корневом каталоге (рядом с вашей папкой .git)
  • Запустите uvx gac --log-level=debug чтобы подтвердить загрузку конфигурации уровня проекта
  • Если вы редактируете .gac.env, перезапустите терминал или перезапустите вашу оболочку для перезагрузки переменных окружения
  • Если всё ещё не работает, проверьте наличие опечаток и прав доступа к файлу

Проблема: Невозможно установить или изменить язык для сообщений коммитов

  • Запустите uvx gac language (или uvx gac lang) для интерактивного выбора из 25+ поддерживаемых языков
  • Используйте флаг -l <language> для переопределения языка для одного коммита (например, uvx gac -l zh-CN, uvx gac -l Spanish)
  • Проверьте вашу конфигурацию с помощью uvx gac config show чтобы увидеть текущую настройку языка
  • Настройка языка хранится в GAC_LANGUAGE в вашем файле .gac.env

3. Ошибки поставщика/API

Проблема: Ошибки аутентификации или API

  • Убедитесь, что вы установили правильные API-ключи для вашей выбранной модели (например, ANTHROPIC_API_KEY, GROQ_API_KEY)
  • Дважды проверьте ваш API-ключ и статус аккаунта поставщика
  • Для Ollama и LM Studio подтвердите, что URL API соответствует вашему локальному экземпляру. API-ключи нужны только если вы включили аутентификацию.
  • Для истечения токена Claude Code: Выполните uvx gac auth для быстрой повторной аутентификации и обновления вашего токена. Ваш браузер откроется автоматически для OAuth.
  • Для истечения токена ChatGPT OAuth: Выполните uvx gac auth chatgpt login для повторной аутентификации. Ваш браузер откроется автоматически для OAuth.
  • Для других проблем OAuth с Claude Code, см. руководство по настройке Claude Code для полного устранения неполадок.
  • Для других проблем OAuth с ChatGPT, см. руководство по настройке ChatGPT OAuth для полного устранения неполадок.
  • Для истечения токена сеанса GitHub Copilot: Выполните uvx gac auth copilot login для повторной аутентификации через Device Flow. Токены сеанса автоматически обновляются из кэшированного OAuth-токена.
  • Для других проблем OAuth с GitHub Copilot, см. руководство по настройке GitHub Copilot для полного устранения неполадок.

Проблема: Модель недоступна или не поддерживается

  • Streamlake использует ID конечных точек вывода вместо имён моделей. Убедитесь, что вы предоставляете ID конечной точки из их консоли.
  • Проверьте, что имя модели правильное и поддерживается вашим поставщиком
  • Проверьте документацию поставщика для доступных моделей

4. Проблемы с группировкой коммитов

Проблема: Флаг --group работает не так, как ожидается

  • Флаг --group автоматически анализирует индексированные изменения и может создавать несколько логических коммитов
  • LLM может решить, что один коммит имеет смысл для вашего набора индексированных изменений, даже с --group
  • Это намеренное поведение - LLM группирует изменения на основе логических отношений, а не только количества
  • Убедитесь, что у вас проиндексировано несколько несвязанных изменений (например, исправление ошибки + добавление функции) для лучших результатов
  • Используйте uvx gac --show-prompt для отладки того, что видит LLM

Проблема: Коммиты сгруппированы неправильно или не сгруппированы, когда ожидалось

  • Группировка определяется анализом LLM ваших изменений
  • LLM может создать один коммит, если определит, что изменения логически связаны
  • Попробуйте добавлять подсказки с -h "hint" для направления логики группировки (например, -h "отделить исправление ошибки от рефакторинга")
  • Просмотрите сгенерированные группы перед подтверждением
  • Если группировка плохо работает для вашего случая использования, коммитьте изменения отдельно

5. Безопасность и обнаружение секретов

Важно: Сканирование секретов выполняется перед любым вызовом AI API. Если секрет обнаружен, рабочий процесс немедленно прерывается и вызов API не происходит. Сканер использует сопоставление шаблонов на основе регулярных выражений (не LLM), поэтому сканирование быстрое и полностью локальное — ваш код никогда не отправляется в модель ИИ для обнаружения секретов.

Проблема: Ложное срабатывание: сканирование секретов обнаруживает не-секреты

  • Сканировщик безопасности ищет шаблоны регулярных выражений, которые напоминают API-ключи, токены и пароли
  • Если вы коммитите примеры кода, тестовые фикстуры или документацию с заглушками для ключей, вы можете видеть ложные срабатывания
  • Используйте --skip-secret-scan чтобы обойти сканирование, если вы уверены, что изменения безопасны
  • Рассмотрите исключение тестовых/примеров файлов из коммитов или используйте чётко отмеченные заглушки

Проблема: Сканирование секретов не обнаруживает реальные секреты

  • Сканер использует сопоставление шаблонов на основе регулярных выражений (не LLM) и может не отловить все типы секретов
  • Всегда просматривайте ваши индексированные изменения с помощью git diff --staged перед коммитом
  • Рассмотрите использование дополнительных инструментов безопасности, таких как git-secrets или gitleaks для комплексной защиты
  • Сообщайте о пропущенных шаблонах как о проблемах для помощи в улучшении обнаружения

Проблема: Нужно отключить сканирование секретов постоянно

  • Установите GAC_SKIP_SECRET_SCAN=true в вашем файле .gac.env
  • Используйте uvx gac config set GAC_SKIP_SECRET_SCAN true
  • Примечание: Отключайте только если у вас есть другие меры безопасности на месте

6. Проблемы с хуками pre-commit и lefthook

Проблема: Хуки pre-commit или lefthook не работают и блокируют коммиты

  • Используйте uvx gac --no-verify чтобы временно пропустить все хуки pre-commit и lefthook
  • Исправьте основные проблемы, вызывающие сбой хуков
  • Рассмотрите настройку хуков pre-commit в .pre-commit-config.yaml или хуков lefthook в .lefthook.yml чтобы они были менее строгими для вашего рабочего процесса

Проблема: Хуки pre-commit или lefthook занимают слишком много времени или мешают рабочему процессу

  • Используйте uvx gac --no-verify чтобы временно пропустить все хуки pre-commit и lefthook
  • Рассмотрите настройку хуков pre-commit в .pre-commit-config.yaml или хуков lefthook в .lefthook.yml для оптимизации производительности
  • Просмотрите конфигурацию ваших хуков для оптимизации производительности

7. Общие проблемы рабочего процесса

Проблема: Нет изменений для коммита / ничего не индексировано

  • gac требует индексированных изменений для генерации сообщения коммита
  • Используйте git add <files> для индексации изменений или используйте uvx gac -a для автоматической индексации всех изменений
  • Проверьте git status чтобы увидеть, какие файлы были изменены
  • Используйте uvx gac diff чтобы увидеть отфильтрованный вид ваших изменений

Проблема: Сообщение коммита не такое, как ожидалось

  • Используйте интерактивную систему обратной связи: введите r для пересоздания, e для редактирования (встроенная TUI, или внешний редактор через GAC_EDITOR), или предоставьте обратную связь на естественном языке
  • Добавьте контекст с -h "ваша подсказка" для направления LLM
  • Используйте -o для более простых однострочных сообщений или -v для более подробных сообщений
  • Используйте --show-prompt чтобы увидеть, какую информацию получает LLM

Проблема: gac работает слишком медленно

  • Используйте uvx gac -y чтобы пропустить подсказку подтверждения
  • Используйте uvx gac -q для тихого режима с меньшим выводом
  • Рассмотрите использование более быстрых/дешёвых моделей для рутинных коммитов
  • Используйте uvx gac --no-verify чтобы пропустить хуки, если они замедляют вас

Проблема: Невозможно редактировать или предоставлять обратную связь после генерации сообщения

  • В подсказке введите e чтобы войти в режим редактирования (встроенная TUI с горячими клавишами vi/emacs; установите GAC_EDITOR для использования предпочитаемого редактора)
  • Введите r для регенерации без обратной связи
  • Или просто введите вашу обратную связь напрямую (например, "сделай короче", "сфокусируйся на исправлении ошибки")
  • Нажмите Enter на пустом вводе чтобы увидеть подсказку снова

8. Общая отладка

  • Используйте uvx gac init для сброса или обновления вашей конфигурации в интерактивном режиме
  • Используйте uvx gac --log-level=debug для детального вывода отладки и логирования
  • Используйте uvx gac --show-prompt чтобы увидеть, какая подсказка отправляется в LLM
  • Используйте uvx gac --help чтобы увидеть все доступные флаги командной строки
  • Используйте uvx gac config show чтобы увидеть все текущие значения конфигурации
  • Проверьте логи на наличие сообщений об ошибках и трассировок стека
  • Проверьте основной README.md для функций, примеров и инструкций быстрого старта

Всё ещё сталкиваетесь с проблемами?

  • Поищите существующие проблемы или создайте новую в GitHub репозитории
  • Включите детали о вашей ОС, версии Python, версии gac, поставщике и выводе ошибок
  • Чем больше деталей вы предоставите, тем быстрее ваша проблема может быть решена

Где получить дополнительную помощь

  • Для функций и примеров использования смотрите основной README.md
  • Для пользовательских системных подсказок смотрите CUSTOM_SYSTEM_PROMPTS.md
  • Для руководства по содействию смотрите CONTRIBUTING.md
  • Для информации о лицензии смотрите ../LICENSE