Настройка DeepSeek Harness Hooks: сначала блокировка // Блог NOVAKVM

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

Эта статья предназначена для трёх групп:

разработчиков агентов, которым нужна проверка до или после вызова инструмента;
платформенных инженеров, которым важно единообразно доставлять конфигурацию между проектами;
специалистов по удалённым средам, которым требуется подтверждать работу Hook после перезапуска, смены каталога и запуска без интерактивного терминала.

[ SECTION_01 ] Что именно должен контролировать первый Hook

Перед настройкой нужно выбрать одну контрольную цель. В DeepSeek Harness это особенно важно, поскольку архитектура строится вокруг подключаемых плагинов, а конфигурация рабочего профиля собирается слоями. Официальная архитектура описывает отдельные плагины для инструментов, цикла агента, хранения сессий, политик подтверждения и совместимых Hook-мостов. Поэтому Hook — это точка управления в конвейере Harness, а не полноценная граница безопасности операционной системы. Архитектура DeepSeek Harness и порядок слоёв конфигурации

На практике встречаются четыре разные задачи:

Разрешение или запрет вызова. Например, блокировка операции записи вне рабочей области.
Запись результата. Сохранение имени инструмента, итогового статуса и краткой причины.
Остановка шага агента. Запрет продолжения после определённого события.
Добавление контекста. Передача агенту предупреждения, статуса проверки или исправляющей инструкции.

Первый Hook лучше посвятить только разрешению или запрету. Если сразу добавить журналирование, изменение входных параметров и автоматический повтор, будет трудно определить причину сбоя. Кроме того, официальная модель инструментов не предполагает произвольного переписывания уже зарегистрированных аргументов: решение до выполнения должно согласовываться с журналом, интерфейсом и фактическим вызовом. Описание конвейера выполнения инструментов и решений до запуска

Где находится файл конфигурации DeepSeek Harness Hooks?

В текущем официальном каталоге конфигурации Hook-мост получает путь через поле configPath. Относительный путь разрешается относительно каталога, из которого запущен процесс, а конфигурация читается один раз при загрузке. Отдельное автоматическое обнаружение файла для каждого рабочего каталога сессии пока обозначено как незавершённое направление. Поэтому нельзя считать, что файл в каталоге проекта будет найден автоматически при каждом новом запуске. Актуальный каталог конфигурации плагинов

Это создаёт первое скрытое ограничение:

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

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

[ SECTION_02 ] Первый этап: проверить окружение до добавления правила

Подготовка должна быть короткой, но воспроизводимой. Официальное руководство разработки указывает, что текущая ветка требует Node.js 22.19 или новее либо Node.js 24 и новее. Для работы с репозиторием также нужен Git 2.26 или новее, а менеджер пакетов закреплён через Corepack и pnpm@11.7.0. Эти параметры относятся к сборке и разработке из исходников; при запуске готовой поставки набор зависимостей может отличаться. Требования к окружению в официальном руководстве разработки

Проверка перед установкой Hook:

node --version
pnpm --version
git --version
pwd

Дальше нужно определить, где Harness хранит домашний каталог. Для части плагинов официальная документация использует $DSH_HOME, а если переменная не задана — ~/.dsh. Это не означает, что любой Hook автоматически ищется именно там. Это лишь важная граница между каталогом Harness и конкретным configPath.

Сначала сохраните безопасный снимок действующей конфигурации:

dsh --profile web --dump-config > dsh-config.before-hooks.txt

Команда --dump-config рекомендована официальной архитектурной документацией для проверки фактического дерева плагинов, которое загружается машиной. Не следует редактировать предполагаемый файл, пока не подтверждено, что нужный Hook-плагин действительно присутствует в выведенном дереве.

Важно: не переносите формат Hooks из другого агента без сверки текущего исходного кода. Совпадающее имя события вроде PreToolUse ещё не доказывает одинаковый формат входа, кодов завершения или политики тайм-аута.

[ SECTION_03 ] Минимальный перехват и одно правило сопоставления

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

Алгоритм подключения:

Создайте отдельную ветку или копию профиля.
Укажите абсолютный configPath, если запуск выполняется из нескольких рабочих каталогов.
Подключите один Hook к одному событию перед выполнением инструмента.
Используйте одно правило сопоставления имени инструмента.
Скрипт должен прочитать входной JSON, записать только безопасное резюме и вернуть однозначное решение.
Проверьте один совпавший вызов и один вызов, который не должен совпасть.
Повторите оба вызова после полного перезапуска процесса.

Название PreToolUse следует использовать только тогда, когда его поддерживает конкретный адаптер текущего DeepSeek Harness. В официальной модели самого инструментария эквивалентная внутренняя точка называется tools/pre-execute. Она принимает решение allow, deny или ask; вариант отказа содержит причину, а вариант запроса требует доступного сервиса подтверждения. Типы решений до выполнения инструмента

Не нужно демонстрировать в конфигурации непроверенные ключи. Без актуального файла Hook Protocol нельзя надёжно утверждать, называется ли поле matcher, match, command, timeout или иначе. В статье допустимо показывать только проверенную часть процесса: путь к конфигурации, выбранное событие, имя скрипта и ожидаемый результат. Сами ключи нужно брать из исходника установленной версии.

Как Hook может остановить опасную команду?

Логика должна находиться до запуска инструмента. Скрипт получает структурированный вход, проверяет имя инструмента и безопасные свойства аргументов, затем возвращает отказ с причиной. Проверять только наличие слова в строке недостаточно: команда может использовать другой синтаксис, переменную, вложенный вызов или альтернативный путь.

Для команды оболочки безопаснее проверять сразу несколько признаков:

тип инструмента;
рабочий каталог;
разрешённый корень проекта;
наличие запрещённых параметров;
допустимый набор аргументов;
вид операции — чтение, запись, удаление или сетевой вызов.

Однако Hook не должен быть единственным барьером. Политика песочницы, отдельный пользователь, ограниченный рабочий каталог и отсутствие секретов в окружении должны продолжать работать независимо от результата Hook.

[ SECTION_04 ] Второй этап: проверить вход, результат и отсутствие совпадения

Минимальный тест должен оставить три записи:

входное событие с именем инструмента и безопасным набором аргументов;
принятое решение;
отметку о том, что правило не сработало для другого инструмента.

Не записывайте полный payload, если в нём могут быть токены, пути клиентов, содержимое файлов или переменные окружения. Для аудита обычно достаточно идентификатора сессии, имени инструмента, хеша рабочего каталога, результата и короткой причины. Официальная модель сессий хранит события в журнале добавления, а для Hook-моста предусматривает отдельные записи hook/invoked и hook/result. Это позволяет проверять факт вызова и результат через событийный журнал, а не по одному тексту конфигурации. Событийная модель сессий и Hook-записи

Проверка должна отвечать на четыре вопроса:

Был ли Hook вызван?
Какой инструмент и рабочий каталог он получил?
Какое решение вернул скрипт?
Дошёл ли вызов до фактического инструмента?

Если ответ на четвёртый вопрос неизвестен, нельзя считать тест успешным. Запись о запуске Hook сама по себе не доказывает, что инструмент был разрешён или заблокирован.

[ SECTION_05 ] Третий этап: выяснить стратегию сбоя

Продолжит ли Agent работу после ошибки Hook?

Это нельзя надёжно вывести из JSON-конфигурации. Нужно отдельно проверить исключение скрипта, ненулевой код завершения, недоступный интерпретатор и превышение тайм-аута. Для каждого случая фиксируется не предположение, а фактическая запись hook/result, состояние вызова инструмента и состояние следующего шага агента.

Минимальный набор проверок:

скрипт возвращает явное разрешение;
скрипт возвращает явный отказ;
скрипт завершается с ошибкой;
скрипт не отвечает в пределах настроенного времени;
после отказа запускается безопасная восстановительная задача.

Официальный каталог указывает значение тайм-аута по умолчанию 600 000 миллисекунд для Hook-конфигураций, если конкретный Hook не задаёт собственное значение. Это параметр адаптера, а не универсальное правило всех Hook-протоколов. Его нужно сверять с установленной версией и не считать доказательством поведения при ошибке. Поля тайм-аута и результата Hook в каталоге конфигурации

Безопасная политика для первого этапа — отказ при неясности. Если скрипт завершился ошибкой, ответ не распознан, процесс не стартовал или журнал не записался, вызов не следует автоматически разрешать. Только после отдельного теста можно решить, допустимо ли предупреждение вместо блокировки для низкорисковых операций.

Практическое правило: отсутствие записи о решении — это не разрешение. Если система не может доказать, почему вызов разрешён, действие должно вернуться в безопасное состояние.

[ SECTION_06 ] Расширение на Bash и запись файлов

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

У Bash есть собственные границы исполнения. В каталоге конфигурации указаны рабочий каталог, тайм-аут переднего плана, максимальный тайм-аут для переопределения, лимит вывода и параметры завершения процесса. Следовательно, Hook-проверка команды и фактическая политика запуска — разные уровни. Конфигурация локального Bash-исполнителя

Проверьте следующие ограничения:

рабочая область не выходит за разрешённый корень;
секреты не передаются в аргументах;
переменные окружения ограничены;
пути нормализуются до сопоставления;
симлинки не обходят разрешённую директорию;
длинный вывод не попадает целиком в журнал;
тайм-аут инструмента не маскирует тайм-аут Hook.

Слишком широкое правило блокирует обычную работу. Слишком узкое пропускает варианты с другим регистром, относительным путём или альтернативным именем инструмента. Поэтому сначала сопоставляйте только имя инструмента, затем добавляйте один признак аргументов и снова проверяйте разрешённый и запрещённый сценарии.

[ SECTION_07 ] Перенос конфигурации на удалённый Mac

После локальной проверки удалённый Mac нужно считать новой средой, а не копией рабочего компьютера. На нём отдельно проверяются скрипт, интерпретатор, права доступа, рабочий каталог и переменные окружения.

Порядок переноса:

Передайте версионируемый файл конфигурации без секретов.
Передайте сам Hook-скрипт и зафиксируйте его хеш.
Установите требуемый интерпретатор или используйте путь, доступный в неинтерактивном запуске.
Проверьте права чтения и исполнения.
Убедитесь, что рабочий каталог существует после подключения.
Запустите процесс с тем же профилем и тем же абсолютным configPath.
Повторите совпавший и несовпавший вызовы.
Перезапустите Harness и проверьте результат ещё раз.
Проверьте запуск без открытого терминала.
Сохраните только краткий итог без ключей и клиентских путей.

Особое внимание уделяется разнице между интерактивной оболочкой и фоновым процессом. Путь к node, python или другому рантайму может присутствовать в профиле терминала, но отсутствовать в окружении службы. Поэтому команда, работающая вручную по SSH, не считается доказательством работы в режиме постоянной сессии.

После перезапуска нужно проверить не только наличие файла. Нужно подтвердить, что процесс снова загрузил тот же путь, Hook получил новый вызов, журнал содержит результат, а безопасная задача не была заблокирована из-за изменившегося рабочего каталога.

Сохранятся ли Hooks после перезапуска удалённого Mac?

Да, только если конфигурация подключается при каждом запуске процесса, скрипт и его рантайм доступны, а путь не зависит от временного каталога. Сам факт сохранения файла на диске не гарантирует повторного подключения. В текущем каталоге DeepSeek Harness путь Hook-конфигурации читается на уровне процесса, поэтому после перезапуска нужно повторно проверить фактически загруженное дерево и события вызова.

Для удалённого размещения полезно сверить доступные варианты аренды Mac через NOVAKVM и заранее выбрать среду, где можно контролировать рабочий каталог, перезапуск и хранение журналов. Для теста конкретной конфигурации также можно использовать страницу заказа Mac mini для удалённой разработки, но параметры Hook всё равно следует проверять внутри самой поставки.

[ SECTION_08 ] Четыре доказательства перед расширением доступа

Финальная проверка должна состоять не из общего списка «всё работает», а из четырёх самостоятельных записей:

Разрешённая задача. Hook срабатывает, решение однозначно разрешает вызов, инструмент возвращает результат.
Запрещённая задача. Hook возвращает отказ, инструмент не запускается, причина сохраняется без чувствительных данных.
Аварийный Hook. Скрипт завершается ошибкой или превышает лимит времени, фактическое поведение записывается.
Восстановительная задача. После отказа или сбоя разрешённая безопасная операция выполняется штатно.

В каждой записи укажите версию профиля, рабочую область, событие, имя инструмента, решение, результат и действие отката. Если проверка проводится на удалённом Mac, добавьте состояние до и после перезапуска. Не подменяйте эти данные заранее подготовленным шаблоном: смысл теста именно в том, чтобы зафиксировать реальные границы текущего запуска.

Вариант внедрения	Что проверяется	Сильная сторона	Главный риск	Решение
Один Hook на низкорисковый инструмент	Вызов, совпадение, журнал	Легко повторить	Низкое покрытие	Лучший старт
Hook для Bash	Команда, каталог, аргументы, тайм-аут	Контроль действий агента	Сложное сопоставление	Добавлять после базового теста
Hook для записи файлов	Путь, режим, рабочая область	Защита исходников	Ложные блокировки	Внедрять по одному корню
Набор Hooks на удалённом Mac	Зависимости, перезапуск, фоновой запуск	Подходит для постоянной среды	Труднее искать причину сбоя	Только после четырёх доказательств

Оценка готовности должна быть условной:

если четыре сценария подтверждены журналом — можно расширять охват;
если не проверен сбой — сохраняйте режим отказа;
если после перезапуска нет hook/invoked и hook/result — не открывайте дополнительные инструменты;
если правило блокирует разрешённые задачи — сначала сузьте сопоставление, а не отключайте защиту целиком;
если скрипт требует секретов — перенесите проверку в отдельный защищённый сервис или измените дизайн.

Встроенные Hooks удобны для политики на уровне конвейера, но они не заменяют системные права, изоляцию процессов и контроль секретов. Текущая версия DeepSeek Harness находится в режиме developer preview, поэтому официальное описание прямо предупреждает о возможных несовместимых изменениях. Конфигурацию следует сверять с исходным каталогом и релизом перед каждым обновлением. Официальный репозиторий DeepSeek Harness и статус developer preview

Если локальный Hook уже прошёл разрешённую, запрещённую, аварийную и восстановительную задачи, следующий разумный шаг — сопоставить его с чек-листом поставки удалённого Mac: наличие рантайма, абсолютный путь, права, восстановление после перезапуска и срок хранения журналов. По сравнению с локальным компьютером удалённая среда снимает зависимость от рабочего места, но добавляет ответственность за доставку скриптов, фоновые процессы и контроль доступа. Случайный Linux-сервер или временный контейнер может оказаться менее удобным для задач, где важны macOS-окружение и повторяемое подключение. Поэтому для краткосрочного теста, миграции или удалённого запуска разумно сначала взять Mac в аренду через NOVAKVM, подтвердить четыре сценария и только затем переводить Hook в постоянный режим.

Настройка DeepSeek Harness Hooks: сначала блокировка