Skip to content

Шесть мест, где сервис или единое правило не сходятся с командой: решения по находкам живого тестирования #538

Closed

Description

@bim-ba

Что это

Живое тестирование (волна 1, #413) и единая пагинация (#502) подняли шесть мест, где нужно ваше слово: сервис ведёт себя не так, как обещает наша команда, или единое правило не ложится. Дефекты, которые решений не требуют, уже чинятся отдельно (#533, #536, #537). Всё ниже измерено E5 на временных объектах в тестовой организации; объекты удалены.

Ответ в виде «1 — …, 2 — …, … 6 — …». Срочного здесь нет.

1. tracker projects create --queues KEY: обязательный флаг, который ничего не делает

Измерено: команда завершается успехом; в ответе queues: null; projects queues-list <id> → пусто; projects get <id> --expand queues → queues: null. Тело уходит с "queues": "KEY" — строкой, как объявлено в нашей модели. Это старый API проектов (/v2/projects).

Вариант
А Оставить флаг, в справке сказать прямо: «сервис принимает поле и ничего с ним не делает (измерено)»
Б Сделать флаг необязательным и сказать то же
В Убрать projects create из старого API совсем: проекты создаются через сущности (tracker entities create project), там очереди привязываются

Рекомендация: Б сейчас (обязательный флаг, который ничего не делает, — обман), а В — вопросом в ревью #459: нужен ли нам вообще старый API проектов рядом с сущностями.

2. datalens htmlpages create сразу публикует

Измерено: после создания savedId == publishedId; последующее update --mode save двигает только сохранённую версию. То есть «создать черновик» у HTML-страницы нельзя: создание и есть публикация. Имя при этом уходит в key, а entry.name в ответе пустое (в списке записей имя есть).

Вариант
А Только сказать в справке: «создание сразу публикует; черновик получается первым же update --mode save»
Б Сказать и считать это причиной не делать вид «HTML-страница» для sync, пока не решим ветки (вы решили: sync работает с опубликованным, #486)

Рекомендация: А. Для sync это как раз удобно: файл в git = опубликованное.

3. forms answers list не ложится в единый список

Все списки получают три ручки (limit, «всё», next, #502). У ответов формы сервис в одном ответе отдаёт и строки-ответы, и описание столбцов; наша команда возвращает их вместе. В «список элементов» это не превращается, не потеряв столбцы.

Вариант Пример
А Оставить исключением: без next, с пометкой причины как сейчас
Б Разделить: forms answers list — список ответов с тремя ручками; столбцы — отдельной командой forms answers columns ycli forms answers list ID --limit 100 + ycli forms answers columns ID
В Список ответов, а столбцы — полем результата рядом с total result.columns

Рекомендация: Б. Столбцы — это описание формы, оно не меняется от страницы к странице; тогда исключений из правила про списки не остаётся (второе, wiki comments thread-list, — составная операция и уйдёт с @flow).

4. Повторять ли запрос, когда Трекер отвечает 412 «попробуйте ещё раз»

Измерено: запуск и архивация спринта время от времени отвечают 412 «Спринт: не удалось сохранить изменения, попробуйте ещё раз» при только что прочитанной версии — 3 раза из 5 в плохие минуты, 0 из 5 через четверть часа; от порядка шагов не зависит. В тестах шаг теперь повторяется (#532). Вопрос — про сам ycli.

Вариант
А Не повторять: 412 по смыслу — «у вас устаревшая версия», повтор с той же версией обычно бессмыслен; отличить этот случай можно только по тексту ответа
Б Повторять запись спринта при 412 с этим текстом, до N раз
В Не повторять, но в подсказке к ошибке сказать: «сервис просит повторить: запустите команду ещё раз»

Рекомендация: В. Повтор записи по тексту ошибки — это правило с исключением и разбор текста; подсказка честно передаёт слова сервиса и ничего не делает за спиной.

5. tracker issues scroll-clear недостижим из CLI

Команде нужна пара «идентификатор и токен прокрутки», которую ни одна команда не печатает; с единым next (#502) пользователь эту пару вообще не видит. Прокрутка сама закрывается по сроку (60 секунд по измерению при таком TTL).

Вариант
А Убрать команду и инструмент; операция остаётся в SDK для тех, кто ведёт прокрутку сам
Б Оставить как есть
В Научить закрывать прокрутку по токену next

Рекомендация: А. Команда, которую нельзя вызвать, — мёртвый код на двух поверхностях; закрытие по сроку делает её ненужной.

6. Что печатает -o json у списков

Вы решили (#502): об обрыве списка CLI говорит строкой в stderr, а stdout остаётся прежним — массивом. У MCP и SDK результат списка — объект {items, truncated, next, total}. То есть -o json и ответ инструмента теперь разной формы.

А. -o json — массив (как решено) Б. -o json — тот же объект, что у инструмента
Зеркало CLI и MCP нет да
Скрипты с ycli … -o json | jq '.[]' работают ломаются у 47 команд (.items[])
Токен продолжения в машинном виде только разбором stderr jq -r .next
Привычно (gh, kubectl list) gh — массив kubectl — объект с items

Рекомендация: А, и добавить способ взять токен без разбора текста: -o ndjson (уже принят, #498) последней строкой отдаёт сводку {"truncated": true, "next": "…", "total": 913}. Массив остаётся массивом, а машинный токен есть.

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

  • К п. 2 и 4: такие измеренные «сервис ведёт себя не так» собирать в одну таблицу на сайте («что мы знаем о сервисах сверх их документации») — она выводится из пометок (measured) в докстрингах; сейчас эти факты разбросаны по справке 467 команд.

Activity

  1. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    1 - Б сейчас, потом согласен, можно подумать над В и вырезать легаси всякие
    2 - А
    3 - Б хороший вариант
    4 - В
    5 - вообще мне нравится вариант В, типа покрыть эту систему тоже нашей системой пагинации, ток я не понял в чем прикол этой операции то вообще? типа "очистить скролл"? а нахера это нужно то вообще? ну вариант А наверное тоже подойдет, а у нас много таких операций которые есть в SDK, но и нет в CLI и MCP?
    6 - чет я тут не понял, можешь подробнее с примерами показать как это работает? типа в терминале мы набираем -o json и у нас выводится JSON массив в ответе, а в stderr пишется plaintext-ом токен продолжения? а почему не в самом JSON объекте это видно? типа у всех объектов всегда унифицированный результат - {items, truncated, next, total} вообще всегда и везде? давай подумаем еще?

  2. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    Решено (владелец, 2026-10-08): 1 — Б (флаг необязательный, в справке «сервис принимает поле и ничего с ним не делает»; вырезать старый API проектов — вопрос ревью #459), 2 — А, 3 — Б (после слияния #534, на его Listing), 4 — В. Пункты 5 и 6 открыты, ниже ответы на ваши вопросы.

    5. Что такое «очистить прокрутку» и сколько операций есть только в SDK

    Что это. Обычный поиск задач Трекера не отдаёт больше 10 000 результатов. Для большего есть прокрутка: сервис держит у себя снимок результатов поиска и выдаёт его кусками; на каждый кусок он возвращает пару «id прокрутки + её токен». «Очистить» — сказать сервису: снимок больше не нужен, можешь освободить память. Если не сказать, он освобождает сам, когда истечёт срок (--scroll-ttl-millis; E5 намерила 60 с при таком TTL). Нужно только тому, кто открывает много прокруток подряд и не хочет ждать срока. Есть ли у сервиса предел открытых прокруток — в документации не нашла (couldn't verify).

    Почему В дороже, чем кажется. В нашем токене next лежит только id прокрутки (он идёт в строку запроса); токен прокрутки сервис отдаёт отдельным заголовком, и мы его сейчас не читаем. Для В надо читать второй заголовок и класть его в next — небольшая правка в одном классе пагинации, но она нужна ради одной команды.

    Сколько операций есть в SDK, но не в CLI и MCP: ноль. Это проверка ARCH-1: у каждой операции клиента должны быть и команда, и инструмент, иначе тест красный. Разрешённых исключений 14, и все они «есть в SDK и CLI, нет в MCP» по одной причине: байты файла (скачать вложение, миниатюру, превью, ключи формы; загрузить файл с диска) не проходят через результат инструмента. scroll-clear сегодня есть на всех трёх поверхностях — просто из CLI его нечем вызвать.

    А. Убрать команду и инструмент, оставить в SDK В. Закрывать по токену next
    Пример tracker.issues.scroll_clear({...}) только из Python ycli tracker issues scroll-clear --next <токен>
    Исключение ARCH-1 ещё одно, пятнадцатое, с новой причиной («нечем вызвать») нет
    Правка удалить 2 обёртки второй заголовок в токен + команда с одним флагом

    Рекомендацию меняю на В: пятнадцатое исключение с новой причиной хуже, чем маленькая правка, а «всё, что про продолжение списка, — через next» становится правилом без дыр.

    6. Что печатает -o json у списков — с примерами

    Да, у всех списков результат один и тот же на MCP и в SDK: {items, truncated, next, total} (total — где сервис его называет, иначе null). Одиночные объекты как были, это только про 110 команд-списков. Сегодняшнее решение (#502) — в CLI массив, обрыв строкой в stderr. Вот как это выглядит на трёх поверхностях при limit 2 из 1008 задач:

    А (как решено в #502):

    $ ycli tracker issues search "Queue: DE" --limit 2 -o json
    [{"key":"DE-1008",…},{"key":"DE-1007",…}]                       # stdout
    stopped at 2 of 1008; go on with --next eyJ2Ijox…  (or --all)   # stderr, текстом
    $ ycli … -o json | jq '.[].key'                                  # массив, как у gh
    $ ycli … -o json 2>&1 >/dev/null | grep -o 'next [^ ]*'          # токен — только разбором текста

    Б (тот же объект, что у инструмента):

    $ ycli tracker issues search "Queue: DE" --limit 2 -o json
    {"items":[{"key":"DE-1008",…},{"key":"DE-1007",…}],"truncated":true,"next":"eyJ2Ijox…","total":1008}
    $ ycli … -o json | jq '.items[].key'                             # как у kubectl
    $ ycli … -o json | jq -r .next                                   # токен машинно
    $ ycli … --all -o json
    {"items":[… все 1008 …],"truncated":false,"next":null,"total":1008}

    Табличные форматы (pretty, и будущие csv, markdown, ndjson, name из #561) в обоих вариантах печатают строки-элементы, а обрыв говорят в stderr: в таблице конверту места нет. Готовая команда продолжения в stderr (#559) остаётся для человека в обоих вариантах.

    MCP в обоих вариантах: tracker_issues_search(body={"query":"Queue: DE"}, limit=2) → {"items":[…],"truncated":true,"next":"…","total":1008}. SDK: listing = tracker.issues.search(IssueSearch(query=…), limit=2); for issue in listing: …; потом listing.next.

    А. Массив + stderr Б. Один объект везде
    -o json и ответ инструмента — одно и то же нет да
    Токен продолжения из скрипта разбор текста stderr jq -r .next
    Скрипты с jq '.[]' работают меняются на .items[] у 110 команд (ломающий релиз)
    Правило одной фразой «структурные форматы печатают список» «структурные форматы печатают результат как он есть; табличные — строки»
    Сводка последней строкой ndjson (#561, Р12) нужна, иначе токена машинно нет не нужна: ndjson печатает только элементы

    Рекомендация меняется на Б. Я советовала А из-за привычки gh и совместимости скриптов, но ваше правило «CLI и MCP — зеркало» сильнее обеих причин, ломающие релизы разрешены, а машинный токен без разбора текста появляется сам. Это меняет решение #502 только в этой точке и снимает Р12 в #561.

    Нужно от вас: 5 — А или В; 6 — А или Б.

  3. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    5 - В хорошая идея
    6 - Б

  4. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    Решено (владелец, 2026-10-08): 5 — В (прокрутка закрывается по токену next; токен прокрутки из заголовка попадает в next), 6 — Б (-o json / -o yaml печатают тот же объект {items, truncated, next, total}, что отдают инструмент и SDK; табличные форматы печатают строки, обрыв — в stderr). Меняет #502 в этой точке и снимает Р12 в #561. Исполнение: 6 — в #534, 5 — отдельным PR после него.

  5. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    К исполнению 5 — В (заметка архитектора): токен прокрутки сервис отдаёт заголовком и в запрос следующей страницы не принимает (документация: «X-Scroll-Token — значение не используется в текущей версии API v3»), поэтому в наш токен next он попадает отдельным полем kept — «что способ листания сохранил из ответа сверх запроса», пустым у всех видов, кроме прокрутки. Версия токена поднимается. Отдельный PR после #534.

  6. bim-ba commented on Oct 10, 2026

    @bim-ba
    OwnerAuthor

    Все шесть решений построены и лежат в main: 1 — #563, 2 — #564, 3 — #574 (вторая команда названа columns-list, по форме integrations-list), 4 — #565, 5 — #567, 6 — #534. Закрываю.

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