Skip to content

С next и обязательным параметром тела: не давать или повторять (14 листингов) #559

Closed

Description

@bim-ba

О чём решение

Правило из #502: «с next не даётся ничего, кроме лимита». Живая проверка #534 показала, что на 14 листингах из 46 оно невыполнимо: у них есть обязательный параметр, который идёт не в адрес, а в тело запроса. Нужно решить, что делать с обязательным параметром при продолжении. #534 (единые limit / next / «всё» на трёх поверхностях) до ответа не сливается.

Слова

  • Листинг — операция, которая отдаёт список по частям.
  • Токен (next) — непрозрачная строка, которую команда печатает, когда список не кончился. В ней уже лежит весь следующий запрос: адрес, строка запроса, тело, место остановки.
  • Параметр адреса — тот, что попадает в путь: ISSUE-1 в /issues/ISSUE-1/comments. Сверяется с токеном сейчас.
  • Параметр тела — тот, что уходит в тело или в строку запроса: текст поиска, id воркбука в DataLens (там все операции — POST с именем метода в пути).

Что сломано сейчас (#534, организация 8526809)

$ ycli tracker issues search "Queue: YCLIPAGE" --limit 2
YCLIPAGE-1008, YCLIPAGE-1007
stopped at 2 of 1008; go on with --next <токен>

$ ycli tracker issues search --next <токен>          # делаю, что велено
Error: Missing argument 'QUERY'.                       # нельзя

$ ycli tracker issues search "Queue: OTHER" --next <токен>
… 500 задач из YCLIPAGE                                # другой текст молча выброшен

Затронуто 14 листингов, одинаково на CLI, MCP и SDK: tracker issues search (текст запроса), tracker gaps search (пользователи), wiki pages descendants-list (slug) и 11 листингов DataLens (workbooks entries-list — id воркбука, entries revisions-list — id записи и т. д.). У остальных 17 листингов с обязательным параметром он в адресе, там всё работает.

Варианты

А. С next обязательный параметр тела не даётся

$ ycli tracker issues search --next <токен>
$ ycli datalens workbooks entries-list --next <токен>      # без id воркбука
$ ycli tracker comments list ISSUE-1 --next <токен>        # параметр адреса повторяется
$ ycli tracker issues search "Queue: X" --next <токен>     # отказ: с next — только лимит
# SDK и схема MCP: параметр перестаёт быть обязательным
def search(self, body: IssueSearch | None = None, *, limit=…, next: str | None = None) -> Listing[Issue]
tracker.issues.search()          # проверка типов молчит, отказ при вызове: «не хватает body»

Б. То же поведение, но через переделку ядра

Описание листинга делится на «адрес» и «фильтр», фильтр при next не строится. Снаружи как А, внутри меняется форма Paged и построение у всех 46 листингов — переделка только что слитых #525 и #551.

В. Обязательное повторяется, расхождение с токеном — отказ

Правило звучит иначе: «с next повтори команду как была, без необязательных параметров».

$ ycli tracker issues search "Queue: YCLIPAGE" --limit 2
stopped at 2 of 1008; go on with:
  ycli tracker issues search "Queue: YCLIPAGE" --next <токен>   # подсказка — готовая команда

$ ycli datalens workbooks entries-list WB1 --next <токен>       # как в REST: «чей список» повторяется
$ ycli tracker comments list ISSUE-1 --next <токен>

$ ycli tracker issues search "Queue: OTHER" --next <токен>
Error: this token continues another listing (query differs); nothing was sent
def search(self, body: IssueSearch, *, limit=…, next: str | None = None) -> Listing[Issue]   # как сейчас

Сравнение

А Б В
Правило одной фразой «с next — только лимит» (у параметра адреса исключение: он повторяется) то же «с next — та же команда без необязательных параметров»
Команды REST и DataLens выглядят одинаково нет: comments list ISSUE-1 --next и entries-list --next нет да
Сигнатура SDK говорит, что обязательно нет, у 14 методов X | None = None нет да
Схема инструмента MCP говорит агенту, что обязательно нет: required у 14 инструментов пустеет нет да
Забыл параметр без next отказ при вызове, свой текст то же отказ типом / схемой, как везде
Другой параметр с тем же токеном отказ отказ отказ с названием расхождения
Правка 14 методов × 3 поверхности + ветка в 14 клиентах форма Paged, 46 листингов одна сверка в ядре + текст подсказки
Риск — большой объём сверка «построенное совпало с токеном» однажды ломалась на размере страницы; нужно сверять запрос до пагинации

Рекомендация

В, если проба подтвердит, что сверка делается на запросе до пагинации без списка имён (E4 пробует, результат допишу сюда). Причины: сигнатура и схема MCP остаются честными (агент видит, что query обязателен), подсказка становится командой, которую можно скопировать, а REST и DataLens перестают различаться — «чей это список» повторяется и там, и там. Цена: фраза правила из #502 меняется.

Если проба покажет, что сверка без исключений не делается, — А (рекомендация E4): правило #502 остаётся дословным, цена — 14 сигнатур теряют «обязательно».

Б не рекомендую: тот же результат, что А, ценой переделки слитого.

Что бы я добавила сверху

  1. Подсказка — всегда готовая команда (в любом варианте): go on with: ycli … --next <токен>, а в MCP — поле next_call с именем инструмента и аргументами. Сейчас печатается только флаг.
  2. Отказ называет расхождение: «токен от tracker issues search, а вызвана tracker issues list» вместо общего «устаревший токен».
  3. ycli next <токен> — одна команда, которая сама находит операцию по токену (в нём есть метод и путь). Тогда повторять нечего вообще. Это отдельная развилка, не сейчас: токену придётся знать имя операции.

Что нужно от вас

Один ответ: «А», «Б» или «В»; и по пунктам сверху — какие брать.

Activity

  1. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    Проба варианта В (E4): выходит без списка имён

    Рекомендация В больше не условная.

    Вопрос Ответ пробы
    Сколько листингов измерено 45 из 46 вызовом (с limit=2, limit=777 и «всё»), 46-й прочитан по коду
    Мешает ли размер страницы сверке у 8 из 46 (все — один вид пагинации Трекера, где размер страницы кладёт сама операция); после переноса размера в пагинацию, как у остальных видов, — у 0 из 46
    Нужно ли менять токен нет, нынешних полей хватает
    Как сверяется всё, что дал вызывающий, должно лежать в запросе из токена с тем же значением (вложенность, не равенство)
    Объём около 60 строк в 5 местах ядра и CLI плюс 8 однотипных правок; сигнатуры SDK и схемы MCP не меняются
    Против варианта А 14 методов × 3 поверхности и смена сигнатур

    Побочная польза: SDK получает ту же защиту. Сейчас в нём другой фильтр с тем же токеном молча выбрасывается; при В — отказ.

    Одно не измерено: forms notifications list (единственный листинг, где сервис сам отдаёт ссылку на следующую страницу). Если сервис в ссылке вернёт другой размер страницы, сверка ложно откажет на второй странице. Лечится тем же переносом размера страницы; проверю вживую до слияния.

    E4 возражение против В снял.

  2. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    ну да, вариант В наверное самый нормальный, это маленькое удобство UI/UX/DX может стоить нам перелопаченной кодовой базы и типов данных и самое главное SDK, поэтому я за вариант В оставить обязательные аргументы и просто кидать токен через --next

  3. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    Решено (владелец, 2026-10-08): В — обязательные параметры повторяются вместе с --next, необязательные с ним не даются; повторённое, расходящееся с токеном, — отказ с названием расхождения; подсказка печатает готовую команду. Пункт 3 сверху (ycli next <токен>) — отдельная развилка позже. Исполнение — в #534 (E4), по плану пробы: размер страницы переезжает в пагинацию у 8 листингов Трекера, сверка на вложенность запроса до пагинации в запрос токена; forms notifications list проверяется вживую до слияния.

  4. bim-ba commented on Oct 10, 2026

    @bim-ba
    OwnerAuthor

    Решение В построено в #534 и лежит в main; подсказка несёт --profile, привязка токена к организации — в #567. Закрываю.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions