Repository navigation
Description
Что это
Живое тестирование (волна 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
bim-ba commentedon Oct 8, 2026
1 - Б сейчас, потом согласен, можно подумать над В и вырезать легаси всякие
2 - А
3 - Б хороший вариант
4 - В
5 - вообще мне нравится вариант В, типа покрыть эту систему тоже нашей системой пагинации, ток я не понял в чем прикол этой операции то вообще? типа "очистить скролл"? а нахера это нужно то вообще? ну вариант А наверное тоже подойдет, а у нас много таких операций которые есть в SDK, но и нет в CLI и MCP?
6 - чет я тут не понял, можешь подробнее с примерами показать как это работает? типа в терминале мы набираем
-o jsonи у нас выводится JSON массив в ответе, а в stderr пишется plaintext-ом токен продолжения? а почему не в самом JSON объекте это видно? типа у всех объектов всегда унифицированный результат -{items, truncated, next, total}вообще всегда и везде? давай подумаем еще?bim-ba commentedon Oct 8, 2026
Решено (владелец, 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 его нечем вызвать.nexttracker.issues.scroll_clear({...})только из Pythonycli tracker issues scroll-clear --next <токен>Рекомендацию меняю на В: пятнадцатое исключение с новой причиной хуже, чем маленькая правка, а «всё, что про продолжение списка, — через
next» становится правилом без дыр.6. Что печатает
-o jsonу списков — с примерамиДа, у всех списков результат один и тот же на MCP и в SDK:
{items, truncated, next, total}(total— где сервис его называет, иначеnull). Одиночные объекты как были, это только про 110 команд-списков. Сегодняшнее решение (#502) — в CLI массив, обрыв строкой в stderr. Вот как это выглядит на трёх поверхностях приlimit 2из 1008 задач:А (как решено в #502):
Б (тот же объект, что у инструмента):
Табличные форматы (
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.-o jsonи ответ инструмента — одно и то жеjq -r .nextjq '.[]'.items[]у 110 команд (ломающий релиз)ndjson(#561, Р12)ndjsonпечатает только элементыРекомендация меняется на Б. Я советовала А из-за привычки
ghи совместимости скриптов, но ваше правило «CLI и MCP — зеркало» сильнее обеих причин, ломающие релизы разрешены, а машинный токен без разбора текста появляется сам. Это меняет решение #502 только в этой точке и снимает Р12 в #561.Нужно от вас: 5 — А или В; 6 — А или Б.
bim-ba commentedon Oct 8, 2026
5 - В хорошая идея
6 - Б
bim-ba commentedon Oct 8, 2026
Решено (владелец, 2026-10-08): 5 — В (прокрутка закрывается по токену
next; токен прокрутки из заголовка попадает вnext), 6 — Б (-o json/-o yamlпечатают тот же объект{items, truncated, next, total}, что отдают инструмент и SDK; табличные форматы печатают строки, обрыв — в stderr). Меняет #502 в этой точке и снимает Р12 в #561. Исполнение: 6 — в #534, 5 — отдельным PR после него.bim-ba commentedon Oct 8, 2026
К исполнению 5 — В (заметка архитектора): токен прокрутки сервис отдаёт заголовком и в запрос следующей страницы не принимает (документация: «X-Scroll-Token — значение не используется в текущей версии API v3»), поэтому в наш токен
nextон попадает отдельным полемkept— «что способ листания сохранил из ответа сверх запроса», пустым у всех видов, кроме прокрутки. Версия токена поднимается. Отдельный PR после #534.docs(datalens): `htmlpages create` says that creating publishes (#564)
fix(tracker): `projects create` no longer demands `--queues`, which t…
feat(core): a 412 comes with a hint: read the current version and run…
feat!: every listing takes `limit`, everything and `next` on the SDK,…
feat!: every listing takes `limit`, everything and `next` on the SDK,…
feat!: every listing takes `limit`, everything and `next` on the SDK,…
feat!: a token names its organization, and a scroll is released by th…
feat!: a token names its organization, and a scroll is released by th…
feat!: a token names its organization, and a scroll is released by th…
feat(forms)!: `forms answers list` is a listing like every other, and…
bim-ba commentedon Oct 10, 2026
Все шесть решений построены и лежат в main: 1 — #563, 2 — #564, 3 — #574 (вторая команда названа
columns-list, по формеintegrations-list), 4 — #565, 5 — #567, 6 — #534. Закрываю.