Учебный гайд: Примеры хуков Qwen Code

Тема: Примеры хуков Qwen Code

Уровень сложности: Средний

Расчётное время изучения: 4-6 часов (теория + практика)

Предварительные требования: Базовое знание Python (синтаксис, работа с файлами, JSON)

Понимание работы командной строки и Bash

Опыт работы с Qwen Code или аналогичными AI-ассистентами программирования

Знакомство с концепцией хуков (hooks) в программных системах

Базовые навыки работы с Git и системами контроля версий

Цели обучения: Настроить и активировать три типа хуков Qwen Code (pre_tool_guard, log_tool_result, inject_sdd_context) согласно примерам из документации

Модифицировать скрипт pre_tool_guard.py для добавления пользовательских опасных команд в список блокировки

Анализировать и расширять систему логирования инструментов через log_tool_result.py для нужд конкретного проекта

Интегрировать контекст SDD-файлов проекта в рабочий процесс через inject_sdd_context.py

Вручную объединять настройки из settings-workflow.example.json с существующим .qwen/settings.json без потери конфигурации

Обзор: Данный учебный гайд посвящён практическому освоению системы хуков в Qwen Code — механизма расширения функциональности AI-ассистента программирования. Хуки позволяют перехватывать и модифицировать поведение инструментов на различных этапах их выполнения: до запуска (pre-), после выполнения (post-), а также внедрять дополнительный контекст в рабочий процесс. Материал основан на трёх production-ready примерах из части 17 учебника: системе безопасности pre_tool_guard.py, системе аудита log_tool_result.py и механизме контекстного обогащения inject_sdd_context.py. Изучение этих примеров даст вам навыки создания собственных хуков для решения реальных задач: от предотвращения случайного удаления данных до автоматической документации действий AI-ассистента.

Ключевые концепции: Хук (hook): Точка расширения в архитектуре Qwen Code, представляющая собой исполняемый скрипт (обычно на Python), который вызывается в определённый момент жизненного цикла инструмента. Хуки позволяют модифицировать поведение системы без изменения её ядра, реализуя принцип инверсии управления (Inversion of Control).

Pre-tool хук: Хук, выполняющийся ДО запуска инструмента. Используется для валидации, блокировки опасных операций, запроса дополнительных подтверждений. В примере pre_tool_guard.py реализована защита от выполнения деструктивных Bash-команд.

Post-tool хук: Хук, выполняющийся ПОСЛЕ завершения работы инструмента. Применяется для логирования, анализа результатов, уведомлений, постобработки данных. Пример log_tool_result.py демонстрирует компактное журналирование событий в формате JSON Lines.

Контекстный хук (context injection): Хук, внедряющий дополнительную информацию в контекст разговора с AI. Пример inject_sdd_context.py автоматически добавляет памятку о структуре SDD-файлов (Software Design Document), помогая модели следовать архитектурным решениям проекта.

Settings-workflow.example.json: Пример конфигурационного файла, демонстрирующий синтаксис подключения нескольких хуков одновременно. Содержит структуру hooks с указанием пути, типа события и приоритета выполнения.

Json lines (jsonl): Формат текстового файла, где каждая строка представляет отдельный валидный JSON-объект. Используется в log_tool_result.py для компактного и удобно парсируемого логирования: новые события просто дописываются в конец файла без необходимости перезаписи всей структуры.

Sdd (software design document): Документ описания архитектуры программного обеспечения. В контексте хука inject_sdd_context.py — это метаинформация о проекте, которую AI должен учитывать при генерации кода, чтобы сохранять консистентность с принятыми проектными решениями.

Исполняемые права (chmod +x): Атрибут файловой системы Unix-подобных ОС, позволяющий запускать скрипт как программу. Критически важен для хуков Qwen Code, поскольку система вызывает их напрямую через механизм exec.

Ручное слияние настроек: Процесс интеграции примерной конфигурации в существующий settings.json без автоматических инструментов слияния. Требует внимательности для сохранения текущих настроек пользователя и корректного соблюдения JSON-синтаксиса.

Практические упражнения: Название: Установка и активация базового хука безопасности

Проблема: Скопируйте файл pre_tool_guard.py из примеров в директорию .qwen/hooks/, сделайте его исполняемым, вручную добавьте соответствующую секцию в ваш .qwen/settings.json. Проверьте работу: запустите Qwen Code и попросите выполнить команду 'rm -rf /tmp/test'. Убедитесь, что хук блокирует выполнение. Затем добавьте в список запрещённых команд 'dd if=/dev/zero of=/dev/sda' и проверьте блокировку этой команды.

Решение: 1. Создайте директорию: mkdir -p ~/.qwen/hooks/

1. Скопируйте скрипт: cp pre_tool_guard.py ~/.qwen/hooks/
2. Сделайте исполняемым: chmod +x ~/.qwen/hooks/pre_tool_guard.py
3. Откройте ~/.qwen/settings.json в редакторе
4. Добавьте секцию hooks (или расширьте существующую):

{ "hooks": [ { "path": "~/.qwen/hooks/pre_tool_guard.py", "event": "pre_tool", "tool": "Bash", "priority": 100 } ] }

1. Сохраните файл, проверьте валидность JSON
2. Запустите Qwen Code, запросите выполнение 'rm -rf /tmp/test'
3. Убедитесь в блокировке по сообщению хука
4. Отредактируйте pre_tool_guard.py: добавьте 'dd if=/dev/zero of=/dev/sda' в список dangerous_commands
5. Перезапустите Qwen Code, проверьте блокировку новой команды

Сложность: beginner

Название: Расширение системы логирования с фильтрацией

Проблема: Активируйте хук log_tool_result.py. Создайте сценарий, при котором за 10 минут работы с Qwen Code накапливается лог. Затем модифицируйте хук: добавьте фильтрацию — записывайте только события инструмента Bash и только если команда выполнялась дольше 1 секунды. Проверьте, что отфильтрованный лог содержит только нужные записи.

Решение: 1. Установите log_tool_result.py по аналогии с первым упражнением

1. Добавьте в settings.json хук с event: "post_tool"
2. Выполните разнообразные задачи: чтение файлов, Bash-команды, поиск
3. Проверьте накопленный лог: cat ~/.qwen/hooks/logs/tool-events.jsonl | jq .
4. Создайте резервную копию оригинального хука
5. Модифицируйте скрипт: добавьте проверку в начало функции обработки:

if tool_name != 'Bash': return if result.get('duration_ms', 0) < 1000: return

1. Сохраните, сделайте исполняемым заново
2. Очистите лог: > ~/.qwen/hooks/logs/tool-events.jsonl
3. Повторите сценарий работы
4. Проверьте, что в логе только долгие Bash-команды
5. Сравните объёмы логов до и после фильтрации

Сложность: intermediate

Название: Создание комплексного SDD-контекста для команды

Проблема: Разработайте систему из трёх SDD-файлов для вашего проекта: архитектура.md, api-контракты.md, стиль-кода.md. Настройте inject_sdd_context.py для автоматического внедрения релевантного контекста в зависимости от типа запроса пользователя. Если запрос содержит 'API' или 'endpoint' — внедряйте api-контракты.md, если 'рефакторинг' или 'стиль' — стиль-кода.md, в остальных случаях — архитектура.md. Проверьте работу на тестовых запросах.

Решение: 1. Создайте директорию проекта: mkdir -p ~/my-project/sdd/

1. Создайте три файла с осмысленным содержимым (по 5-10 пунктов каждый)
2. Скопируйте inject_sdd_context.py в ~/.qwen/hooks/
3. Модифицируйте логику выбора файла:

import re def select_sdd(user_message): msg_lower = user_message.lower() if any(kw in msg_lower for kw in ['api', 'endpoint', 'rest']): return 'api-контракты.md' elif any(kw in msg_lower for kw in ['рефакторинг', 'стиль', 'форматирование']): return 'стиль-кода.md' else: return 'архитектура.md'

1. Обновите основную функцию хука для использования select_sdd
2. Настройте в settings.json хук с event: "pre_tool" или "pre_message" (в зависимости от версии Qwen Code)
3. Тестируйте последовательно:

• "Создай API endpoint для пользователей" → должен подтянуть api-контракты.md
• "Отрефактори этот модуль по стилю проекта" → стиль-кода.md
• "Как организовать базу данных?" → архитектура.md

1. Проверьте через отладочный вывод или лог, какой файл был выбран
2. Документируйте правила выбора в README проекта

Сложность: intermediate

Название: Резервное копирование и восстановление настроек при слиянии

Проблема: У вас уже настроен сложный .qwen/settings.json с кастомными промптами, предпочтениями модели и одним legacy-хуком. Получите settings-workflow.example.json из учебника и корректно интегрируйте все три новых хука, сохранив существующую конфигурацию. Создайте скрипт-валидатор, который проверит целостность итогового JSON и отсутствие дубликатов в массиве hooks.

Решение: 1. Создайте резервную копию: cp ~/.qwen/settings.json ~/.qwen/settings.json.backup.$(date +%s)

1. Изучите текущую структуру: cat ~/.qwen/settings.json | jq 'keys'
2. Изучите settings-workflow.example.json: cat settings-workflow.example.json | jq '.hooks'
3. Создайте промежуточный файл merge.json
4. Вручную объедините: скопируйте корневые поля из обоих файлов
5. Для массива hooks: извлеките существующие, добавьте новые с корректными приоритетами
6. Убедитесь в уникальности комбинаций (path + event + tool):

jq '.hooks | group_by(.path, .event, .tool) | map(select(length > 1)) | length' merge.json Результат должен быть 0

1. Проверьте валидность JSON: python3 -c "import json; json.load(open('merge.json'))"
2. Создайте скрипт validate-settings.py для автоматизации проверок
3. Примените: cp merge.json ~/.qwen/settings.json
4. Запустите Qwen Code, проверьте работу всех хуков
5. В случае ошибки — откатитесь из бэкапа

Сложность: advanced

Кейсы: Название: Внедрение хуков безопасности в финтех-стартапе

Сценарий: Команда из 8 разработчиков в финтех-стартапе активно использовала Qwen Code для ускорения разработки микросервисов. За первый месяц произошло два инцидента: один раз AI-ассистент предложил и почти выполнил команду 'DROP TABLE transactions CASCADE' в рабочей базе данных разработчика, другой раз — 'kubectl delete namespace production' из-за неоднозначного контекста в запросе. Руководство потребовало внедрить многоуровневую систему защиты без существенного замедления рабочего процесса.

Задача: Основные сложности: (1) Существующий pre_tool_guard.py из примеров покрывал только очевидно опасные команды rm -rf, mkfs, dd, но не знал о специфике финтех-инфраструктуры (kubectl, psql, liquibase). (2) Разработчики сопротивлялись дополнительным подтверждениям, считая их «тормозами». (3) Нужна была централизованная система аудита для расследования инцидентов. (4) Команда работала с чувствительными данными, поэтому логи нельзя было отправлять во внешние системы.

Решение: Команда адаптировала три хука из учебника в комплексную систему: (1) Расширила pre_tool_guard.py: добавила паттерны для SQL-команд (DROP, TRUNCATE без WHERE), kubectl-операций (delete, drain, taint), и специфичных утилит (liquibase dropAll, flyway clean). Реализовала градацию опасности: «блокировка» для катастрофических команд, «требование явного подтверждения» для рискованных, «предупреждение» для потенциально проблемных. (2) Настроила log_tool_result.py с локальным хранением в зашифрованном разделе, добавила маскирование чувствительных данных (PAN, CVV) через regex-замену перед записью. (3) Создала inject_sdd_context.py с корпоративными стандартами: при работе с БД — памятка о запрете прямых операций без миграций, при работе с k8s — правила namespace-изоляции. Внедрили постепенно: сначала в режиме логирования без блокировок (неделя наблюдения), затем мягкие предупреждения, финально — полная блокировка.

Результат: За 6 месяцев работы системы: предотвращено 23 потенциально опасных операции (14 — SQL-команды без миграций, 7 — kubectl-операции в production-контексте, 2 — попытки очистки данных). Среднее время на подтверждение «серой зоны» команд — 8 секунд, что команда посчитала приемлемым. Аудиторский след позволил за 15 минут восстановить хронологию инцидента с тестовыми данными клиентов. Разработчики отмечили, что контекст SDD сократил время объяснения архитектурных решений новым членам команды на 30%. Система стала эталоном для других команд в холдинге.

Извлечённые уроки: Начинайте внедрение хуков безопасности в режиме audit-only: логируйте без блокировки, чтобы измерить реальную частоту опасных сценариев и избежать ложных срабатываний

Адаптируйте списки опасных команд под специфику вашей инфраструктуры: универсальный pre_tool_guard.py — только отправная точка

Градация реакции (блокировка / подтверждение / предупреждение) критически важна для баланса безопасности и скорости разработки

Локальное логирование с маскированием решает конфликт между потребностью в аудите и требованиями информационной безопасности

Контекстные хуки (inject_sdd_context) работают как «пассивная защита»: предотвращают ошибки до их совершения, снижая нагрузку на активные блокировки

Связанные концепции: Pre-tool хук

Post-tool хук

Контекстный хук (Context injection)

Ручное слияние настроек

JSON Lines (JSONL)

Название: Оптимизация логирования в распределённой команде разработки

Сценарий: Распределённая команда из 15 разработчиков в трёх часовых поясах работала над крупным open-source проектом с использованием Qwen Code. Координаторы столкнулись с проблемой: при возникновении ошибок в коде, сгенерированном AI, невозможно было восстановить, какие именно инструменты и с какими параметрами выполнялись. Стандартные логи Qwen Code были недостаточно детальными, а разработчики забывали вручную документировать сложные сессии.

Задача: Ключевые проблемы: (1) Стандартный log_tool_result.py писал локально на машине каждого разработчика, что делало агрегацию невозможной. (2) Объём логов рос линейно, через месяц файл tool-events.jsonl достигал 500 МБ, что замедляло чтение. (3) Логи не содержали идентификатора сессии, затрудняя корреляцию событий. (4) Некоторые инструменты (например, многократный поиск по коду) генерировали «шум» — сотни бесполезных записей. (5) Требовалось соблюдение приватности: логи не должны содержать содержимого файлов с секретами.

Решение: Команда создала эволюцию стандартного хука: (1) Добавила в лог сессионный идентификатор (UUID4, генерируемый при старте Qwen Code через переменную окружения QWEN_SESSION_ID). (2) Реализовала ротацию логов: ежедневное создание нового файла tool-events-YYYY-MM-DD.jsonl с архивацией старых через gzip. (3) Добавила фильтрацию по типу инструмента: логировались только Bash, Edit, Write — инструменты, изменяющие состояние системы. Read, Search, Glob исключались как неизменяющие. (4) Внедрила санитизацию: перед записью проверялось содержимое на соответствие паттернам секретов (AWS keys, tokens via regex), при совпадении — замена на [REDACTED]. (5) Создала опциональную синхронизацию: при наличии переменной QWEN_LOG_SYNC_URL анонимизированные логи отправлялись в центральный S3-совместимый бакет для агрегации.

Результат: Система логирования стала прозрачной и масштабируемой: средний размер активного лог-файла снизился с 500 МБ до 12 МБ. Время поиска по логам сократилось с минут до секунд благодаря ежедневной сегментации. 94% сессий успешно коррелировались по session_id при эскалации проблем. Выявлены 3 систематические ошибки в поведении AI (циклический вызов одного инструмента), которые были исправлены в апстриме. Система санитизации прошла аудит безопасности с нулём утечек за 4 месяца работы. Код хука был вынесен в отдельный open-source репозиторий, получивший 340 звёзд.

Извлечённые уроки: Ротация и сегментация логов обязательны для долгосрочной работы: монолитный JSONL-файл не масштабируется

Сессионные идентификаторы превращают локальные логи в трассируемую систему: инвестиция в одну строку кода даёт порядок в анализе

Фильтрация по «изменяющим состоянию» инструментам снижает шум на 80-90% без потери критической информации

Санитизация должна быть proactive, не reactive: встраивайте проверку паттернов секретов до первого инцидента

Open-source подход к развитию хуков создаёт network effect: внешние вклады улучшают вашу систему без прямых затрат

Связанные концепции: Post-tool хук

JSON Lines (JSONL)

Исполняемые права (chmod +x)

Советы по изучению: Начинайте с единственного хука: установите pre_tool_guard.py, убедитесь в его работе, только затем добавляйте остальные. Параллельная установка всех трёх увеличивает вероятность конфигурационной ошибки в 3-4 раза

Ведите «лабораторный журнал» — отдельный файл, куда записывайте каждое изменение в settings.json с датой и результатом проверки. Это спасёт при откате после ошибки слияния

Используйте jq для валидации и изучения JSON-структур: jq '.' settings.json проверяет синтаксис, jq '.hooks | length' считает хуки, jq '.hooks[] | select(.event=="pre_tool")' фильтрует по типу

Создайте тестовую «песочницу» — изолированный проект с копией .qwen/, где можно экспериментировать без риска поломать рабочую конфигурацию

Для понимания потока данных добавьте временно в каждый хук отладочный вывод в stderr: print(f"DEBUG: hook triggered for {tool_name}", file=sys.stderr). Удалите после отладки

Изучайте исходные скрипты построчно, не копируя слепо. Попробуйте предсказать, что делает следующая строка, прежде чем прочитать комментарий — это ускорит понимание архитектуры

Практикуйте ручное слияние на простых примерах: возьмите два маленьких JSON-файла, объедините в блокноте, проверьте валидатором. Навык пригодится при обновлении версий Qwen Code

Для аудиального восприятия: читайте скрипты вслух, объясняя логику воображаемому собеседнику. Это активирует другие каналы памяти и выявляет пробелы в понимании

Создайте чек-лист проверки хука: исполняемые права? корректный shebang? валидный JSON в settings? правильный event? уникальность в массиве hooks? — и прогоняйте перед каждым запуском

При модификации хуков используйте систему контроля версий: инициализируйте git в ~/.qwen/hooks/, коммитьте каждое рабочее состояние. Откат на предыдущий коммит быстрее ручного восстановления

Дополнительные ресурсы: Официальная документация qwen code (часть 17): Исходный учебник, содержащий settings-workflow.example.json и три reference-реализации хуков — отправная точка для всех модификаций

Json lines specification: https://jsonlines.org/ — формальное описание формата, используемого в log_tool_result.py, с примерами парсинга на разных языках

Python subprocess module documentation: https://docs.python.org/3/library/subprocess.html — глубокое понимание механизмов запуска и взаимодействия с внешними процессами, лежащих в основе хуков

Jq manual: https://stedolan.github.io/jq/manual/ — незаменимый инструмент для работы с JSON-конфигурациями и логами в командной строке

«secure by design» (manning publications): Книга о принципах проектирования безопасных систем, применимых к архитектуре хуков — особенно глава о fail-safe defaults и defense in depth

Git hooks documentation: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks — параллельная экосистема хуков для сравнения паттернов и лучших практик

Open-source репозиторий enhanced-qwen-hooks: Гипотетическое сообщественное расширение стандартных хуков с дополнительными примерами и тестами (ищите по ключевым словам в GitHub)

Резюме: Система хуков Qwen Code представляет собой мощный механизм расширения AI-ассистента программирования через три ключевых точки внедрения: предварительная валидация (pre_tool_guard.py), постфактум аудит (log_tool_result.py) и контекстное обогащение (inject_sdd_context.py). Освоение этих примеров требует понимания не только синтаксиса Python и JSON, но и архитектурных принципов: инверсии управления, градации реакции на события, баланса безопасности и удобства. Критически важным навыком является ручное слияние конфигураций — операция, требующая внимательности и системного подхода. Успешное применение хуков трансформирует Qwen Code из пассивного инструмента в активно управляемую систему с корпоративными политиками безопасности, прозрачным аудитом и консистентной архитектурной дисциплиной. Начинайте с простого, документируйте каждый шаг, используйте контроль версий для скриптов — и вы получите надёжную инфраструктуру, масштабируемую от индивидуальной разработки до распределённых команд.