Окно чтения: limit, offset, filter

Все инструменты чтения принимают три параметра окна. limit — сколько строк готового ответа вернуть (по умолчанию 200, максимум 1000), offset — с какой строки начать, filter — регулярное выражение, которое оставляет только нужное. Окно режет уже готовый markdown, как чтение файла по строкам.

Правила

Сначала фильтр, потом окно. offset и limit считаются по строкам, оставшимся после filter.
Фильтр без учёта регистра. Там, где инструмент понимает элементы — метаданные, дерево модуля, форма, макет, схема СКД, граф вызовов, — фильтр отбирает элементы и сохраняет путь к ним. В остальных случаях он оставляет строки ответа с совпадениями и заголовки их секций.
Шапка закреплена. Заголовок и дайджест > Σ повторяются на каждой странице — агент не теряет, что читает.
Строка *lines* в конце появляется, только когда окно или фильтр сработали. Нет строки — ответ полный.
Блоки кода не рвутся. Если страница начинается или заканчивается внутри блока кода, окно добавляет недостающую ограду.

Строка lines

последняя строка ответа

*lines: 1–200 of 845 (offset=0, next=200, filter=Номенклатура)*

1–200 of 845 — показаны строки 1–200 из 845 после фильтра;
next=200 — значение offset для следующей страницы; на последней странице его нет;
filter=… — эхо фильтра;
cached 12s — страница взята из кэша, ей 12 секунд.

Кэш страниц

Листать дёшево: ответ строится один раз, а следующие страницы (offset > 0) отдаются из кэша. Запрос с offset=0 всегда пересчитывает ответ заново — это точка свежести. Любая запись или действие очищает кэш. Страница из кэша помечена cached Ns, так что агент видит возраст данных.

Примеры

аргументы metadata_read

{ "project": "УТ2020", "fqn": "Catalog.Контрагенты", "filter": "ИНН|КПП" }

аргументы search — следующая страница

{ "operation": "text", "query": "ВызватьИсключение", "limit": 100, "offset": 100 }

Исключение: переменные отладчика

debug_read читает живую коллекцию из отладчика, и каждая ячейка — отдельное вычисление. Поэтому строки таблицы значений листаются своим параметром rows="21-40" (с единицы, по умолчанию 1-20, не больше 50 за раз), а окно limit/offset работает уже поверх полученного ответа. Ответы debug_read не кэшируются.

Типичные ошибки

Огромный limit вместо фильтра. Сначала сузьте фильтром или адресом, потом листайте.
Листание без первой страницы. Кэш привязан к набору аргументов; если поменяли filter, начните с offset=0.