Pastukhov Code > Документация > Валидация > Управление моделями через хуки

Технологии извлечения и анализа данных

Управление моделями через хуки

Хуки — это уровень обеспечения системы валидации Pastukhov Code. Пока навыки направляют поведение модели через инструкции, хуки обеспечивают соблюдение правил, блокируя конкретные вызовы инструментов до их выполнения. Наиболее impactful использование хуков — предотвращение запуска моделью команд сборки и линтинга вручную — поскольку автоматические сборки справляются с этим более эффективно, каждая ручная сборка, которую пытается сделать модель, — это потерянное время и токены.

Hooks dialog

События и типы хуков

Хуки организованы по типам событий. Pastukhov Code поддерживает два события:

  • PreToolUse — Запускается перед выполнением инструмента. Здесь определяются правила запрета и команды перед выполнением. Хуки могут нацеливаться на конкретные инструменты: Bash, Edit, Write, Read, Glob, Grep, Agent, NotebookEdit и другие
  • UserPromptSubmit — Запускается, когда пользователь отправляет промпт ИИ. Используйте это для валидации или изменения пользовательского ввода перед обработкой

Хуки запрета

Хуки запрета блокируют выполнение инструмента, сопоставляя паттерны с вводом инструмента. Для инструментов Bash паттерн сопоставляется со строкой команды. Для инструментов, не относящихся к Bash, используйте .* как catch-all паттерн, чтобы полностью запретить инструмент.

Каждый хук запрета имеет четыре поля:

  • Pattern — Текст или паттерн regex для сопоставления с вводом инструмента
  • Regex — Когда включено, паттерн рассматривается как регулярное выражение (без учета регистра). Когда отключено, он сопоставляется как подстрока
  • Message — Сообщение об отказе, показанное пользователю, когда хук срабатывает

Хуки выполнения

Хуки выполнения запускают команду оболочки перед выполнением инструмента. Они получают контекст о вызове инструмента через stdin как JSON и могут возвращать структурированный вывод, который влияет на поведение модели. Переменная окружения $CLAUDE_PROJECT_DIR доступна в команде.

Предотвращение ручных сборок

Это самое impactful использование хуков в Pastukhov Code. Когда настроены автоматические сборки, модель никогда не должна пытаться собирать, линтовать или запускать проект вручную. Без этих хуков модель регулярно запускает команды сборки и линтинга после каждого редактирования — тратя время и токены на действия, которые система сборки уже выполняет.

preToolUse:
  Bash:
    - type: deny
      pattern: "dotnet build"
      message: "Don't build projects manually - it's done automatically"
    - type: deny
      pattern: "npm run build"
      message: "Don't build projects manually - it's done automatically"
    - type: deny
      pattern: "npm run link"
      message: "Don't lint projects manually - it's done automatically"
    - type: deny
      pattern: "npx svelte-check"
      message: "Don't lint projects manually - it's done automatically"
    - type: deny
      pattern: "npm run check"
      message: "Don't lint projects manually - it's done automatically"
    - type: deny
      pattern: "npm run dev"
      message: "Don't start projects manually - it's done automatically"
    - type: deny
      pattern: "dotnet run"
      message: "Don't start projects manually - it's done automatically"
userPromptSubmit: {}

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

Интеграция с Claude Code

Конфигурации хуков, хранящиеся в .pastukhov/hooks.yml, автоматически синхронизируются с собственной системой хуков Claude Code. Процесс синхронизации преобразует определения YAML в формат JSON и записывает их в .claude/settings.local.json, чтобы хуки вступили в силу при следующем промпте пользователя в чате.

Поток синхронизации работает следующим образом:

  1. При запуске и после каждого сохранения HooksService читает конфигурацию YAML
  2. Каждое определение хука преобразуется в формат JSON Claude Code с автоматическим разрешением пути к исполняемому файлу
  3. Хуки дедуплицируются по команде, чтобы избежать конфликтов
  4. JSON записывается в .claude/settings.local.json
  5. Текущие запущенные сессии используют старые хуки до отправки следующего промпта пользователя

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

Другие цели валидации

Помимо предотвращения ручных сборок, хуки служат другим целям валидации:

  • Блокировка разрушительных операций — Запрет rm -rf, force push или других опасных команд, которые могут вызвать необратимый ущерб даже внутри контейнера
  • Обеспечение соблюдения политик, специфичных для проекта — Блокировка записей в конкретные защищенные файлы, предотвращение редактирования файлов конфигурации или запрет изменений в тестовых фикстурах
  • Пользовательская логика валидации — Хуки выполнения могут запускать команды оболочки перед выполнением инструмента, позволяя проверку перед коммитом, валидацию формата или пользовательские защиты

Валидация конфигурации автоматически проверяет hooks.yml при сохранении, предупреждая о неизвестных типах событий и свойствах. Ошибки ссылаются на соответствующий раздел в .pastukhov/README.md.

Эффективные паттерны валидации

  • Всегда запрещайте ручные сборки, когда настроены автоматические сборки — Это самая impactful конфигурация хуков. Добавьте правила запрета для каждой команды сборки и линтинга, которую модель может попробовать
  • Используйте сопоставление подстрок для простых паттернов — pattern: "npm run build" с regex: false ловит любую команду, содержащую эту подстроку, включая с дополнительными флагами
  • Используйте regex для сложных паттернов — Включите regex: true, когда вам нужно сопоставление без учета регистра или синтаксис паттернов, например rm\s+-rf
  • Тестируйте хуки после сохранения — Хуки вступают в силу при следующем промпте пользователя. Отправьте тестовый промпт и убедитесь, что хук блокирует ожидаемые команды

Полный справочник по хукам см. в Хуки. Для системы сборки, хуки которой предотвращают ручной запуск, см. Сборка и развертывание. Для изоляции Docker, которая делает хуки сетью безопасности, а не шлюзом, см. Изоляция Docker и пропуск разрешений.

← Изоляция Docker и пропуск разрешений

Аналитика и наблюдаемость →