Хуки

Хуки позволяют вам внедрить пользовательскую логику в рабочий процесс Careti в ключевые моменты. Думайте о них как об автоматизированных контрольных точках, где вы можете проверить операции перед выполнением, контролировать использование инструментов по мере его происхождения и формировать то, как Careti принимает решения.

Хуки запускаются автоматически, когда происходят определённые события во время разработки. Они получают подробную информацию о каждой операции, могут заблокировать проблемные действия перед их выполнением, и могут внедрить контекст, который направляет будущие решения AI.

Настоящая мощь приходит из комбинирования этих возможностей. Вы можете:

• Остановить операции перед тем, как они вызовут проблемы (например, создание файлов .js в проекте TypeScript)
• Учиться из того, что происходит, и развивать знание проекта с течением времени
• Контролировать производительность и ловить проблемы по мере их возникновения
• Отслеживать всё в целях аналитики или соответствия
• Запускать внешние инструменты или сервисы в правильные моменты

⚠️Warning

Хуки в настоящее время поддерживаются только на macOS и Linux. Поддержка Windows недоступна.

Как начать

Включение хуков в Careti просто. Вот что вам нужно сделать:

Включить хуки в параметрах

Откройте параметры Careti и установите флажок "Enable Hooks".

Вы можете найти этот параметр следующим образом:

1. Откройте Careti
2. Нажмите кнопку "Settings" в верхнем правом углу
3. Нажмите на раздел "Feature" в левом меню навигации.
4. Прокрутите вниз до тех пор, пока не увидите флажок "Enable Hooks" и установите его.

Выберите размещение хука

Решите, где разместить ваши хуки:

Для личных или организационных хуков:

• Создайте хуки в ~/Documents/.agents/hooks/
• Они автоматически применяются ко всем рабочим областям

Для хуков, специфичных для проекта:

• Создайте хуки в .agents/hooks/ в корневом каталоге вашего проекта
• Они применяются только к определённой рабочей области
• Фиксируйте их в контроль версии, чтобы ваша команда могла их использовать тоже

Создайте свой первый хук

Файлы хуков должны иметь точные имена без расширений файлов. Например, для создания хука TaskStart:

# Создать файл хука
vim .agents/hooks/TaskStart

Добавьте ваш скрипт (должен начинаться с shebang)

#!/usr/bin/env bash

# Сохраните введённый ввод в переменную
input=$(cat)

# Дамп всего полезного груза JSON
echo "$input" | jq .

# Получить тип поля
echo "$input" | jq -r '.timestamp | type'

Этот пример скрипта демонстрирует ключевые механики ввода/вывода хука: чтение полезного груза JSON из stdin с помощью input=$(cat), и использование jq для инспекции структуры данных и типов полей, которые ваш хук получает. Это помогает вам понять, какие данные доступны перед созданием более сложной логики хука.

Сделайте его исполняемым

chmod +x .agents/hooks/TaskStart

Протестируйте свой хук

Запустите задачу в Careti и проверьте, выполняется ли ваш хук.

💡Tip

Начните с простого хука, который просто регистрирует информацию, перед тем как строить сложную логику валидации. Это помогает вам понять структуру данных и время выполнения.

Что вы можете построить

После того, как вы поймёте основы, хуки открывают творческие возможности:

• Логирование и мониторинг: Отслеживайте все операции AI для целей аудита, аналитики или соответствия регуляциям
• Проверка и валидация: Остановите нежелательные операции перед их выполнением
• Контроль инструментов: Управляйте доступом к инструментам и отслеживайте использование
• Интеграция с внешними системами: Запускайте webhooks, запускайте CI/CD конвейеры, отправляйте уведомления
• Формирование знаний: Вводите контекст, который управляет будущими решениями AI

Примеры хуков

Вот несколько распространённых примеров, которые помогут вам начать:

Простой логирующий хук

Этот хук записывает все входящие события в файл для целей аудита:

#!/usr/bin/env bash

input=$(cat)

# Добавить в лог с временной меткой
echo "[$(date +'%Y-%m-%d %H:%M:%S')] $input" >> ~/.agents/hooks/audit.log

# Вывести оригинальный ввод (допустить операцию)
echo "$input"

Хук валидации TypeScript проекта

Этот хук предотвращает создание файлов .js в проектах TypeScript:

#!/usr/bin/env bash

input=$(cat)

# Получить тип события и целевой файл
event=$(echo "$input" | jq -r '.event')
filename=$(echo "$input" | jq -r '.data.path' 2>/dev/null)

# Если это создание файла .js в проекте TypeScript, заблокировать его
if [[ "$event" == "FileCreated" && "$filename" == *.js ]]; then
  if [[ -f "tsconfig.json" ]]; then
    # Возвратить ошибку для блокирования операции
    echo '{"error": "Cannot create .js files in TypeScript projects"}'
    exit 1
  fi
fi

# Дать разрешение на операцию
echo "$input"

Хук интеграции Slack

Этот хук отправляет уведомления в Slack, когда возникают важные события:

#!/usr/bin/env bash

input=$(cat)
event=$(echo "$input" | jq -r '.event')

# Отправить в Slack только для значимых событий
if [[ "$event" == "ToolCalled" ]]; then
  tool=$(echo "$input" | jq -r '.data.toolName')

  curl -X POST -H 'Content-type: application/json' \
    --data "{\"text\": \"Careti used tool: $tool\"}" \
    $SLACK_WEBHOOK_URL
fi

# Разрешить операцию
echo "$input"

Доступные хуки

Careti поддерживает следующие точки хука:

• TaskStart - Запускается, когда пользователь отправляет новую задачу
• MessageAdded - Запускается, когда было добавлено сообщение (AI или пользователь)
• ToolCalled - Запускается перед выполнением инструмента
• FileModified - Запускается при изменении файла
• CommandExecuted - Запускается перед выполнением команды
• ContextUpdated - Запускается при обновлении контекста AI

Каждый хук получает JSON payload с деталями события, включая временные метки, пути файлов, имена инструментов и другую полезную информацию.

Лучшие практики

• Начните простым: Тестируйте с логированием, прежде чем добавлять сложную логику
• Будьте быстрыми: Хуки должны выполняться быстро, чтобы не замедлять ваш рабочий процесс
• Обрабатывайте ошибки правильно: Возвращайте JSON ошибки с соответствующими кодами выхода для блокирования операций
• Протестируйте тщательно: Убедитесь, что ваши хуки работают на локальной машине перед фиксированием в контроль версии
• Ведите документацию: Наружите документацию о том, что делает ваш хук и почему, особенно для командных хуков