# Настройка фильтрации инструментов — руководство пользователя

English version: see [filtering-guide.en.md](<filtering-guide.en.md>).

Это руководство охватывает установку, настройку, проверку и откат. Описан плагин для **DSH 0.2.1-rc.2**.

## Что делает плагин

Плагин ограничивает инструменты только у **основного агента** — того, с которым вы общаетесь в чате. При маске `hide` выбранные схемы исчезают из запроса модели; при `block` схемы остаются видимыми, но вызовы выбранных инструментов блокируются. Субагенты используют собственный агент-пресет: маска плагина на них не распространяется.

Важно: это ограничение видимости или вызовов, а не sandbox и не авторизация. Подробности — в [SECURITY.md](<../SECURITY.md>).

## Две функции: ограничение tools и расширенные права

В плагине две независимые функции: ограничение инструментов основного агента (фильтрация, матрица «пресет → профиль») и расширенные права субагентов (эскалация, тумблер «Расширенные права субагентов», `subagentEscalation`). Расширенные права по умолчанию выключены. Функции не зависят друг от друга и работают в трёх режимах:

- **только ограничение tools** — фильтр обрезает набор основного агента, субагенты работают со своим набором без эскалации;
- **только расширенные права** — фильтр не настроен; субагент, которому не хватает инструмента, запрашивает расширенный доступ, и пользователь одобряет каждый вызов панелью над блоком ввода;
- **обе функции** — ограничение и эскалация включены одновременно: скрытые у основного агента инструменты остаются доступны субагентам, а при нехватке у самого субагента включается путь одобрения.

## Шаг 0. Установка и первая активация

01. В Plugin Manager вызовите `plugin_manager` → `install_bundle` и укажите архив пакета `.tgz` или каталог распакованного пакета. Для обновления установите таким же способом последнюю версию. Вручную редактировать профиль или распаковывать пакет в папку DSH не нужно.
02. Если DSH попросит перезапуск, перезапустите приложение. У плагина есть собственная иконка и русские/английские метаданные в Plugin Manager.
03. При первой активации плагин сканирует установленный DSH. Пока матрица связок пуста, фильтрация не меняет поведение пресетов.

## Шаг 1. Первый запуск: сканирование

При первой активации плагин сканирует установленный DSH. В карточке настройки появится сводка палитры: сколько инструментов **можно отключить** и сколько **нельзя отключить**. Числа зависят от состава инструментов вашей установки.

Пока связок в матрице нет — фильтрация не применяется ни к одному пресету.

## Шаг 2. Посмотреть свой набор и профили

Откройте карточку плагина в Plugin Manager → Configure:

- Матрица «пресет → профиль» показывает пресеты двумя алфавитными блоками: дефолтные и кастомные. Одному пресету назначается один профиль; профиль можно использовать для нескольких пресетов.
- Переключатель «Фильтрация включена» и статус (агенты с маской, скрыто схем); переключатель «Файловая диагностика» — вкл/выкл запись лога шагов фильтрации (путь файла показан в блоке «Диагностика»); тумблер «Расширенные права субагентов» — вкл/выкл эскалации прав субагентов через одобрение пользователя.
- В разделе «Профили» можно создать, редактировать или копировать профиль в модальном окне. Встроен профиль `balanced` (административные инструменты); пользовательские профили добавляются отдельно, а имя, совпадающее с `balanced`, переопределяет его. Редактор показывает включённые, отключённые и неуправляемые инструменты; проблемные имена (опечатки, «ограничитель отклонит маску») — с активным чекбоксом и пометкой: снятие отметки и сохранение убирает имя из профиля.
- Пакеты-шаблоны помогают начать настройку: «Градиент» (`strict`, `soft`), «По назначению» (`focus`, `no-web`, `no-admin`, `minimal`) и «Слойные» (`no-web`, `no-admin`, `no-dev-skills`).
- Переключатель языка задаёт русский, английский или язык приложения. Под выполненным действием отображается временный статус.
- В блоке сканирования смотрите палитру инструментов; для технической сводки раскройте «Диагностика». Список доступных имён также формируется сканированием в UI.

## Шаг 3. Включить фильтрацию (связка «пресет → профиль»)

В матрице выберите пресет и профиль, затем нажмите «Связать». Для смены профиля выберите новый и нажмите «Заменить»; «Снять» удаляет связку. Изменения применяются на лету. Пресеты вне матрицы работают без маски.

Пресет может быть ещё не привязан в момент создания сессии. После выбора пресета плагин применит актуальную связку; это поддерживается начиная с версии 0.3.1.

Параметры конфигурации, если вы настраиваете их не через карточку:

| Поле | Назначение |
|---|---|
| `enabled` | Включает (`true`, по умолчанию) или выключает фильтрацию. |
| `behavior` | `auto` (по умолчанию) выбирает безопасный режим по истории; `hide` скрывает схемы (см. сноску о рисках), `block` оставляет схемы видимыми, но блокирует выбранные вызовы. |
| `language` | `auto` (по умолчанию), `ru` или `en` — язык интерфейса. |
| `debugLog` | `false` (по умолчанию) — файловая диагностика шагов фильтрации; подробности — раздел «Файловая диагностика». |
| `profiles` | Объект «имя профиля → `{ mode, tools }`». `mode: deny` отключает перечисленные инструменты, `mode: allow` оставляет только перечисленные. |
| `presets` | Объект «id пресета → имя профиля»; пустой объект означает, что фильтр ни к чему не применяется. |
| `subagentEscalation` | `false` (по умолчанию) — `true` включает право субагентов запрашивать расширенный доступ с обязательным одобрением пользователя; `false` — субагенты работают без эскалации. |

⚠ **Риск режима `hide`:** фиксированное скрытие схем не защищает от ошибок строгих
провайдеров — если в истории чата остались вызовы скрываемых инструментов, ходы могут
завершаться ошибкой «Провайдер вернул некорректный вызов инструмента». Режим `auto`
сам выбирает безопасное поведение по истории; фиксируйте `hide` только когда история
чиста либо провайдер мягкий.

Пример конфигурации фильтра для пресета основного агента (фрагмент `config`; замените
`main-preset` на реальный id, полный набор полей — в таблице выше):

~~~yaml
presets:
  main-preset: lean-main
profiles:
  lean-main:
    mode: deny
    tools: [plugin_manager, security_audit]
~~~

На DSH 0.2.1-rc.2 у конфигурации субагента больше нет полей `toolFilter` и `persona`. Инструменты субагента задаёт его собственный агент-пресет. Например, отдельному пресету субагента веб-поиска назначьте инструменты `web_search`, `web_fetch` и `read`. Изменение списка tools в агент-пресете может наследоваться дочерними субагентами; маска этого плагина, напротив, применяется только к основному агенту.

## Шаг 4. Проверить

Для проверки после установки или изменения конфигурации перезапустите DSH и откройте **новую сессию** с нужным пресетом. DSH пинит ревизии плагина в существующих сессиях, поэтому именно новая сессия после перезапуска надёжно проверяет текущую версию.

Проверьте, что:

01. Инструменты из профиля скрыты или их вызовы блокируются — согласно выбранному `behavior`.
02. В карточке изменился статус, а под «Диагностика» отображаются счётчики `presets · profiles · tools: N`.
03. Субагент веб-поиска, которому назначен собственный пресет с `web_search`, `web_fetch` и `read`, по-прежнему может выполнить поиск. Маска фильтра плагина действует только на основной агент.

Для существующей истории с вызовами выбранных инструментов режим `auto` сохраняет согласованность с провайдером: временно оставляет схемы видимыми, но блокирует вызовы; после очистки истории (например, сжатия) переходит к скрытию схем. Если история чистая, схемы скрываются сразу.

## Шаг 5. Откат

- В матрице нажмите «Снять» у нужного пресета — маска снимается на лету.
- Выключите переключатель «Фильтрация включена», чтобы временно отключить фильтр целиком; в конфигурации этому соответствует `enabled: false`.
- Если меняете конфигурацию вручную, пустая матрица `presets: {}` снимает все связки. Изменения конфигурации и матрицы применяются на лету; для проверки обновлённой версии плагина откройте новую сессию после перезапуска DSH.

## Настройка под себя (custom-профиль)

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

~~~yaml
presets:
  standard: my-profile
profiles:
  my-profile:
    mode: deny
    tools: [web_search, web_fetch, plugin_manager]
~~~

- Для `deny` перечисленные инструменты отключаются; для `allow` доступны только перечисленные. Имена выбирайте из палитры сканирования.
- Glob-шаблоны (например, `team_task_*`) не поддерживаются — используйте точные имена.
- `run_code` — зарезервированное имя: добавлять его в профиль нельзя. Свои профили с именем, совпадающим со встроенным, заменяют его настройки.

## Диагностика

- Палитра сканирования показывает `✅` инструменты, которые можно отключить, и `⚠` — которые нельзя отключить. В предупреждениях `⚠ нельзя отключить (N)` перечислены неуправляемые инструменты, включая own-layer и зарезервированные имена вроде `run_code`; фильтр не может на них повлиять.
- `❌` у имени в предупреждениях означает, что имя инструмента не найдено: проверьте написание или доступность инструмента в DSH — либо нажмите «Убрать имя из профиля» прямо в предупреждении (имя исчезнет из всех профилей). Неизвестный профиль в ручной конфигурации не применяется; сообщение о нём выводится как предупреждение проверки конфигурации в журнал DSH.
- «Диагностика» раскрывает технические данные, включая путь файла лога и счётчики `presets · profiles · tools: N`.
- Статус под блоком показывает результат последнего действия. Для технических подробностей применения откройте диагностический лог DSH.

### Файловая диагностика (`debugLog`)

Опция `debugLog` (boolean, по умолчанию `false`) включает запись диагностического лога шагов фильтрации в файл `<DSH_HOME>/logs/agent-tool-filter-debug.log` (фолбэк без `DSH_HOME` — `<os.tmpdir()>/agent-tool-filter-debug.log`). Переключается тумблером «Файловая диагностика» в настройках плагина, применяется сразу. Переменная окружения `ATF_DEBUG_LOG` — принудительный override: включает лог независимо от опции и задаёт путь файла (например, `ATF_DEBUG_LOG=C:\temp\atf.log`).

## Частые вопросы

- **Инструмент не отключается.** Проверьте его статус в палитре. Инструменты с `⚠` нельзя ограничить маской; также проверьте правильность имени профиля и связки в матрице.
- **Изменения не видны в текущей сессии.** Матрица, тумблер и профиль применяются на лету. Но после обновления плагина для проверки используйте новую сессию после перезапуска DSH: существующая сессия может продолжать работать с закреплённой ревизией плагина.
- **Как дать субагенту web-доступ?** Назначьте ему собственный агент-пресет с нужными инструментами. Маска плагина действует только на основной агент; правки состава инструментов в пресете могут наследоваться субагентами, поэтому ограничивайте их собственный набор именно настройкой их пресета.

## Особенности web-среды

В старых чатах с вызовами скрываемых инструментов в истории авто-режим держит guard (защита от ошибок строгих провайдеров); hide включается после компакции/смены пресета/перезапуска и не раньше, чем история перестанет упоминать скрытые имена. Подробно — раздел «Особенности работы в web-среде» в README.