← Все статьи

API и хелперы

Инструменты осмотра страницы AI Helper — query_page и list_structure

17 мая 2026 · автор JustZix Team

ИИ-ассистент хорош ровно настолько, насколько хорошо то, что он может видеть. AI Helper работает не из расплывчатого описания страницы — у него есть инструменты, чтобы посмотреть на реальный DOM и на вашу существующую библиотеку JustZix. Эта статья охватывает два инструмента осмотра: query_page и list_structure.

Стартовый контекст

Каждое сообщение, которое вы отправляете, уже несёт URL страницы, заголовок и HTML-фрагмент. Этого достаточно для простых запросов. Но фрагмент есть фрагмент — для точного селектора модели часто нужно посмотреть ближе на конкретную часть страницы. Именно для этого нужны инструменты осмотра.

query_page — посмотреть на живой DOM

Модель передаёт CSS-селектор; инструмент запускает его на текущей странице и возвращает количество совпадений плюс HTML совпадений.

@@JZ_TOOL@@ {"tool": "query_page", "args": {"selector": "header .nav"}} @@END@@

result:
  matches: 1
  html: "<nav class=\"nav\"> ... </nav>"

Это превращает гадание в проверку. Вместо написания CSS для структуры, которую она воображает, модель может подтвердить, что там на самом деле есть: существует ли .nav, один он или пять, какие классы несут дочерние элементы, находится ли кнопка внутри обёртки. С этим селектор, который она пишет, нацелен на реальную страницу.

Как модель его использует

• Подтвердить, что элемент существует — запросить селектор, проверить, что счётчик не нулевой.
• Сузить селектор — начать широко, прочитать возвращённый HTML, затем запросить что-то более конкретное.
• Проверить уникальность — счётчик 1 означает, что селектор конкретен; счётчик 30 означает, что он слишком широк для точечной правки.
• Прочитать структуру — увидеть отношения родитель/потомок перед написанием селектора :has() или потомкового селектора.

За один агентный ход модель может вызвать query_page несколько раз, уточняя по мере того, как узнаёт — всё в рамках бюджета 8 шагов.

list_structure — прочитать ваши существующие правила

Второй инструмент смотрит не на страницу, а на вашу библиотеку JustZix. list_structure возвращает ваши папки, группы и правила вместе с их идентификаторами.

@@JZ_TOOL@@ {"tool": "list_structure", "args": {}} @@END@@

result:
  folders:
    - id: f_12  "News sites"
      groups:
        - id: g_3  "Layout fixes"
          rules:
            - id: r_88  "Hide sidebar ads"
            - id: r_90  "Wider article column"

Зачем модели это нужно:

• Избежать дубликатов — если похожее правило уже существует, модель может указать вам на него вместо создания ещё одного.
• Размещать новое разумно — новое правило для новостного сайта может пойти в вашу существующую папку «News sites», а не рассыпать правила вразнобой.
• Использовать настоящие идентификаторы — create_group и create_rule требуют родительский идентификатор; list_structure — это то, откуда берутся эти идентификаторы.

Он только для чтения. Видеть вашу структуру — не то же самое, что менять её — создание папки, группы или правила всё равно требует инструментов создания и вашего явного подтверждения.

Почему осмотр по необходимости лучше выгрузки всей страницы

Очевидной альтернативой было бы отправить модели весь HTML страницы заранее. AI Helper намеренно так не делает. Осмотр по необходимости выигрывает по реальным причинам:

Современное веб-приложение может быть сотнями килобайт HTML. Запихивать всё это в контекст медленно, дорого и часто контрпродуктивно — сигнал тонет в шуме. Сфокусированный query_page для .cookie-banner даёт модели ровно те несколько строк, которые ей нужны.

Свежесть тоже важна

Страницы не статичны. Меню открываются, появляются модальные окна, контент подгружается с опозданием. Поскольку query_page выполняется в момент вызова, модель читает DOM таким, какой он прямо сейчас — включая элементы, которых не было, когда вы впервые открыли чат. Одноразовая выгрузка страницы так не может.

Осмотр питает рабочий процесс

Эти инструменты — первый шаг большего агентного процесса: осмотреть с помощью query_page и list_structure, протестировать в панели TEMP, попросить вас проверить, затем сохранить. Хороший осмотр — это то, что делает поздние шаги точными — селектор правильный, потому что модель действительно посмотрела.

Смотри также

• Полный агентный процесс вызова инструментов
• Знакомьтесь, AI Helper — обзор
• Постройте правило с AI Helper, шаг за шагом

Осмотр по необходимости — это то, что держит AI Helper точным и дешёвым. Скачайте JustZix, добавьте ключ и попросите его посмотреть на хитрый элемент.