Repository navigation
Description
О чём решение
Новые форматы вывода, решённые в #498: -o csv | ndjson | name | markdown и выбор столбцов --columns, общие для всех команд. E5 написала план и замерила кодовую базу; до кода осталось 14 развилок. Ниже — сводка с моей рекомендацией по каждой, потом каждая с примерами. Можно ответить «всё по рекомендации, кроме …».
Слова
- Команда-список — команда, которая возвращает список объектов (их 110 из 481).
- Ключ API — имя поля, как его отдаёт Яндекс и как печатает
-o jsonсегодня:createdAt. Имя поля модели — как оно зовётся в Python:created_at. - Составной адрес — объект, которому для обращения нужны два значения: комментарий = ключ задачи + id комментария.
Что показали замеры
| Факт | Число |
|---|---|
Метка Identity() из #498 стоит на аргументах операций, а не на полях ответа |
9 штук, только у видов sync; у 101 из 110 команд-списков брать имя неоткуда |
Моделей-элементов без key / id / slug / name |
26 из 105 (DataLens: workbook_id…; пользователи Трекера: uid) |
| Моделей со вложенными объектами или списками | 77 из 105 |
Имя --columns уже занято своим смыслом |
2 команды |
| Имя поля модели ≠ ключ API | Трекер 329 из 1006 полей, DataLens 2422 из 7810 |
Сводка: рекомендации
| № | Вопрос | Рекомендую | Почему одной фразой |
|---|---|---|---|
| Р1 | Откуда -o name знает поле-имя |
А, и той же меткой Identity() на поле ответа, без второй метки |
типизированная метка, покрывает и 26 моделей без key/id; список имён (В) — ровно то, чего вы не хотите |
| Р2 | -o name у составного адреса |
А (только свой идентификатор) | родителя вызывающий уже знает: … comments list DE-1 -o name | xargs -n1 ycli tracker comments get DE-1 |
| Р2 | -o name у объекта без имени |
Г (отказ до запроса) | скрипт узнаёт, что формат не подошёл |
| Р3 | csv / markdown для одного объекта |
А (таблица из одной строки) | одно правило на все 481 команду |
| Р4 | Вложенные поля в таблице | А; список — текстом JSON | объекты раскладываются как в pretty сегодня, список разбирается обратно |
| Р5 | Столбцы без --columns |
Б (поля модели) | шапка не зависит от данных, можно печатать по мере получения страниц |
| Р6 | Как --columns называет поле |
А (ключ API) | то же имя, что человек видит в -o json и в шапке |
| Р7 | Язык пути в --columns |
А (имена через точку) | опечатка ловится до запроса, нет новой зависимости |
| Р8 | На что действует --columns |
А (на все форматы) | одна фраза «какие поля печатать», заменяет | jq |
| Р9 | --columns занято у двух команд |
Б (переименовать параметры этих двух команд) | опция значит одно везде; поломка у двух редких команд |
| Р10 | MCP | А (ничего) | форматы — печать CLI; columns для экономии токенов — отдельная идея, ниже |
| Р11 | SDK | А (ничего) | нет новой публичной поверхности |
| Р12 | ndjson: где сводка про обрыв |
А (только элементы, обрыв в stderr) | jq -c .key работает на каждой строке; согласуется с #559. Связано с открытым п. 6 в #538 — ответ должен быть один на оба |
| Р13 | csv: BOM |
А (чистый UTF-8) | BOM ломает первую ячейку в трубе; поведение Excel не измерено |
| Р13 | csv: формулы из чужого текста |
В (как есть) + строка в документации | файл равен данным сервиса; вариант Г портит отрицательные числа |
| Р14 | Проверка «сериализация в одном месте» ловит и csv |
А | иначе второй сериализатор появится без пометки |
Число PR: три (таблицы и ndjson; name; --columns), после слияния #534.
Развилки с примерами (план E5)
Р1. Откуда формат знает, какое поле — имя объекта (-o name)
В #498 сказано «из той же метки Identity()». Измерено: эта метка стоит на аргументах операций (9 штук), а не на полях ответа, и у 101 из 110 команд-списков её нет вовсе.
| А. Типизированная метка на поле ответа | Б. Метка Identity() на аргументе + сопоставление с полем ответа |
В. Соглашение по именам полей | |
|---|---|---|---|
| Запись | key: Annotated[KeyStr, Name()] в модели |
issue_key: Annotated[str, Identity()] у get; формат ищет в ответе поле с тем же именем или ключом |
формат берёт первое из key, id, slug |
| Правок в моделях | около 105 моделей, по одной строке | метка на аргументах ~110 операций + правило сопоставления (issue_key ↔ key) |
ноль |
26 моделей без key/id/slug/name |
метка ставится на workbook_id, uid, path — работает |
не сопоставляется без таблицы соответствий | не работает, нужен список исключений |
| Проверка | общий тест: у элемента каждой команды-списка есть ровно одна метка либо причина отсутствия | то же | нет |
| Форма | типизированный объект в Annotated |
типизированный объект + правило имён | список имён |
# А и Б снаружи одинаковы; В расходится на DataLens
$ ycli datalens workbooks list -o name
wb-7f3a… # А, Б: поле workbook_id помечено
Error: `-o name`: the items of this command have no name # В: нет ни key, ни id, ни slugР2. Что печатает -o name у объекта с составным адресом и у объекта без имени
Комментарий задачи адресуется двумя значениями (ключ задачи и id комментария); у forms access list (права) имени нет вообще.
| А. Только собственный идентификатор | Б. Весь адрес, через пробел | В. Весь адрес одной строкой-путём | |
|---|---|---|---|
tracker comments list DE-1 -o name |
8841 |
DE-1 8841 |
DE-1/8841 |
Годится в xargs следующей команде |
нет: comments get нужен и ключ задачи |
да: xargs -n2 ycli tracker comments get |
нет, нужен разбор |
Совпадает с путём файла в sync |
нет | нет | да (tracker/queues/DE/triggers/16) |
Модель без имени (5 команд forms access …, tracker gaps search, списки привязок доступа DataLens):
| Г. Отказ до запроса | Д. Пустой вывод | Е. Строка JSON на элемент | |
|---|---|---|---|
| Пример | Error: -o name: the items of this command have no name; nothing was sent (код выхода 2) |
ничего, код 0 | {"access":"write","users":[…]} |
| Скрипт узнаёт, что формат не подошёл | да | нет | нет |
Р3. Таблица (csv, markdown) для одиночного объекта
tracker issues get DE-1 -o csv — результат не список.
| А. Таблица из одной строки | Б. Отказ | В. Два столбца «поле / значение» | |
|---|---|---|---|
| Пример | key,summary,status.keyDE-1,Fix,open |
Error: -o csv prints a listing; this command returns one object |
field,valuekey,DE-1summary,Fix |
| Одно правило на все 481 команду | да | нет: формат работает у 110 | да, но у списка и у объекта разная форма |
ycli … get -o csv >> all.csv в цикле |
да (шапка повторяется) | нет | нет |
ndjson у одиночного объекта — одна строка, name — одна строка (решено в #498 для создания); тут прочтение одно.
Р4. Вложенные поля в csv и markdown
У 77 из 105 моделей есть вложенные объекты или списки. Пример элемента: {"key":"DE-1","status":{"key":"open","display":"Открыт"},"tags":["a","b"],"followers":[{"id":"1"},{"id":"2"}]}.
| А. Объект — столбцами через точку, список — текстом JSON | Б. Всё вложенное — текстом JSON в одной ячейке | В. Вложенного в таблице нет, пока его не назвали в --columns |
|
|---|---|---|---|
| Шапка | key,status.key,status.display,tags,followers |
key,status,tags,followers |
key |
| Строка | DE-1,open,Открыт,"[""a"",""b""]","[{""id"":""1""},…]" |
DE-1,"{""key"":""open"",…}","[""a"",""b""]",… |
DE-1 |
Совпадает с pretty сегодня |
да (он так раскладывает объекты; список скаляров — через запятую) | нет | нет |
| Число столбцов у задачи Трекера | десятки | равно числу полей верхнего уровня | мало |
| Ячейка читается человеком в Excel | да, кроме списков объектов | нет | да |
Подвопрос к А: список скаляров (tags) — текстом JSON (["a","b"], разбирается обратно) или через запятую (a, b, как в pretty, обратно не разбирается, если в значении есть запятая).
Р5. Какие столбцы у таблицы, когда --columns не дано
А. Объединение ключей всех элементов (как pretty) |
Б. Поля, объявленные моделью | |
|---|---|---|
| Пустой список | пустой вывод, шапки нет | шапка есть |
| Шапка зависит от данных | да: вчера 12 столбцов, сегодня 13 | нет: одна и та же при любом ответе |
| Столбцы, пустые у всех | отбрасываются | остаются |
| Печать по мере получения страниц | нет: нужен весь список в памяти | да |
| Поле, которого нет в модели (сервис добавил) | видно | не видно (как и в остальных форматах? — нет: json его печатает, если модель разрешает лишние поля) |
Р6. Как --columns называет поле — один ответ на всё
Сегодня вывод печатает ключи API (ARCH-4): в -o json у задачи createdAt, в SDK — issue.created_at.
| А. Ключ API | Б. Имя поля модели | |
|---|---|---|
| Пример | --columns key,createdAt,status.key |
--columns key,created_at,status.key |
То же, что в -o json и в документации Яндекса |
да | нет |
То же, что в SDK и в ycli schema по именам полей |
нет | да |
| Шапка csv | key,createdAt,status.key |
key,created_at,status.key — и тогда шапка расходится с ключами -o json у 329 полей Трекера и 2422 DataLens |
| Один стиль во всех сервисах | нет: Tracker createdAt, Wiki created_at (как и весь вывод сегодня) |
да: везде snake_case |
Третьего варианта («принимать оба») не даю: владелец просил один ответ.
Р7. Язык пути в --columns
| А. Имена и путь через точку | Б. То же плюс своя шапка | В. Выражение JMESPath | |
|---|---|---|---|
| Пример | --columns key,status.key |
--columns KEY:key,STATUS:status.key (как kubectl -o custom-columns) |
--columns 'key,status.key,length(followers)' |
| Элемент списка, срез, функция | нет | нет | да |
| Новая зависимость в поставке | нет | нет | да: jmespath (сейчас только в dev) |
| Ошибка в имени ловится до запроса | да: имя сверяется с моделью | да | нет: выражение проверяется только на данных |
Р8. На какие форматы действует --columns
| А. На все форматы: это проекция результата | Б. Только на таблицы (csv, markdown, pretty) |
|
|---|---|---|
-o json --columns key,summary |
[{"key":"DE-1","summary":"Fix"}] |
отказ: --columns works with csv, markdown and pretty |
-o ndjson --columns key |
{"key":"DE-1"} |
отказ |
| Смысл опции одной фразой | «какие поля печатать» | «какие столбцы у таблицы» |
Заменяет | jq '{key,summary}' |
да | нет |
Рядом с --fields Трекера (отбор на стороне сервиса) |
две опции про одно, на разных сторонах; нужна фраза в справке | не пересекаются |
Р9. Имя --columns занято у двух команд
wiki grids columns create --columns '<JSON>' и datalens datasets data-get --columns <guid> — их собственные параметры. По нынешнему правилу глобальная опция с занятым именем на такой команде просто отсутствует.
| А. Оставить как есть | Б. Переименовать параметры двух команд | В. Другое имя глобальной опции | |
|---|---|---|---|
| Что видит человек | на двух командах --columns значит другое и столбцы вывода выбрать нельзя |
wiki grids columns create --body-columns …, datasets data-get --guid …; --columns везде одно |
--show key,summary (или --only) везде; --columns у двух команд прежнее |
| Ломающее изменение | нет | да, у двух команд (релизы с поломкой разрешены) | нет |
| Имя из принятой идеи 22 | да | да | нет |
Р10. Что видит MCP
Модуль вывода сервер не использует; инструмент отдаёт структурный ответ, формат выбирает клиент.
| А. Ничего | Б. Параметр columns у инструментов-списков |
В. Отдельный инструмент-проекция | |
|---|---|---|---|
| Пример | — | tracker_issues_list(queue="DE", columns=["key","summary"]) → элементы из двух полей |
— (не предлагаю, показан для полноты: result_project(tool=…, columns=…) требует хранить результат) |
| Зачем | форматы — печать CLI | агент получает меньше токенов на длинных списках | — |
| Зеркало CLI ↔ MCP (ARCH-1 сверяет аргументы) | --columns — глобальная опция печати, в зеркало не входит, как --format |
входит: параметр на 110 инструментах, добавляется в одном месте (как limit в #534) |
— |
| Проверка схемы ответа | не меняется | меняется: ответ с частью полей не проходит схему полной модели — нужна форма «частичный элемент» | — |
Р11. Что видит SDK
| А. Ничего | Б. Публичная функция таблицы | |
|---|---|---|
| Пример | for issue in tracker.issues.list(...) — и дальше свой код |
from ycli.output import tabletable(tracker.issues.list(...), columns=["key", "summary"]).to_csv() |
| Новая публичная поверхность | нет | да, с обещанием совместимости |
| Одно место сериализации (ARCH-4) | да, cli/output.py |
модуль переезжает из cli/ в общий слой |
Р12. ndjson: где сводка про обрыв списка
Связано с #538, п. 6 (открыт): там рекомендована сводка последней строкой ndjson. #559 при этом ведёт подсказку в stderr.
| А. Только элементы; обрыв — в stderr | Б. Последняя строка — сводка, всегда | В. Сводка последней строкой, только если список оборван | |
|---|---|---|---|
| stdout | {"key":"DE-1"}{"key":"DE-2"} |
{"key":"DE-1"}{"key":"DE-2"}{"_listing":{"truncated":true,"next":"…","total":913}} |
как Б при обрыве, как А без него |
| Токен продолжения машинно | разбором stderr | tail -1 | jq -r ._listing.next |
то же, но строки может не быть |
jq -c .key по всем строкам |
работает | последняя строка даёт null |
иногда даёт null |
У sync (в #498: «сводка последней строкой») |
сводки нет | та же форма: {"_summary":{"written":12,"skipped":3}} |
— |
Р13. csv и Excel: кириллица и формулы
| А. Чистый UTF-8 | Б. UTF-8 с BOM | |
|---|---|---|
ycli … -o csv > a.csv, двойной щелчок в Excel |
кириллица кракозябрами | читается |
… -o csv | head -1 | cut -d, -f1 |
key |
key — первый столбец с невидимым символом |
Отдельно: значение ячейки приходит из сервиса (заголовок задачи пишет любой участник). Заголовок =HYPERLINK(…) Excel выполнит как формулу.
| В. Печатать как есть | Г. Ячейку, начинающуюся с =, +, -, @, печатать с апострофом впереди |
|
|---|---|---|
| Данные в файле равны данным сервиса | да | нет: '=1+1; отрицательное число -5 тоже получает апостроф, если не различать числа |
| Файл безопасно открыть в Excel | нет | да |
Р14. Проверка ARCH-4 и новый сериализатор
Проверка test_arch4_serialization_confined_to_output ловит json.dumps, yaml.safe_dump, pydantic_core.to_json, .model_dump_json() вне output.py. csv.writer в её списке нет.
А. Добавить csv.writer / csv.DictWriter в список проверки |
Б. Не трогать проверку | |
|---|---|---|
| Что это | правка инварианта и его теста в одном PR (правило ARCHITECTURE.md), с тестом-укусом |
— |
csv вне output.py |
запрещён; sync/formats.py (будущий вид «таблица Вики» в CSV, #316) понадобится в списке исключений |
возможен без пометки |
| Новая проверка без решения владельца | да, это оно | нет |
Что бы я добавила сверху
columnsв MCP для экономии токенов (Р10-Б) — отдельной развилкой после замера: сколько токенов весит типичный список и сколько экономит проекция. Сейчас довод качественный.- Своя шапка столбца (
--columns KEY:key,STATUS:status.key, Р7-Б) — добавляется позже без поломки, если понадобится. -o nameуsyncпечатает пути файлов:ycli sync status -o name | xargs git add.--columnsбез значения печатает список доступных столбцов команды и ничего не запрашивает — чтобы не ходить вschema.- Строка в справке
--columnsу команд Трекера: чем она отличается от--fields(тот режет ответ на стороне сервиса, этот — на печати).
Что нужно от вас
«Всё по рекомендации» или номера, где иначе; и какие пункты сверху брать.
Activity
bim-ba commentedon Oct 8, 2026
Замер к Р10 (E5): ответ списка в MCP весит до ~206 тыс. токенов — меняю рекомендацию
Мерили вывод
-o jsonс лимитом по умолчанию (500), живые данные; токены = символы / 4, на кириллице это нижняя граница.tracker issues listkey, id, summary— ~12,7 тыс.datalens entries list --scope widgetkey, entryId, name— ~18 тыс.datalens entries list --scope datasetwiki pages descendants-listПроверила код сервера: предела на размер ответа инструмента нет (есть только предел на размер схемы). Значит, сегодня
tracker_issues_listбезlimitотдаёт агенту 500 задач по 36 полей — ответ, который не помещается в окно большинства клиентов. Число 500 для MCP решено в #502 до этого замера.Р10 теперь не «ничего». Варианты:
limitcolumnsу инструментов-списковtracker_issues_list(queue="DE", columns=["key","summary"])tracker_issues_list(queue="DE")→ 50 задач иnextРекомендация: В сейчас (одна настройка, чинит проблему на всех 46 листингах сразу, и агент уже умеет продолжать по
next), Б — отдельной развилкой, когда будет решена форма частичного ответа. Число для В предлагаю 50: 50 задач Трекера ≈ 20 тыс. токенов.Р13 (BOM) измерить нечем: ни LibreOffice, ни Excel на машине нет; остаётся «из общеизвестного поведения».
bim-ba commentedon Oct 8, 2026
Р12 снят решением в #538 (6 — Б):
-o jsonпечатает тот же объект{items, truncated, next, total}, что инструмент, поэтому машинный токен есть и без сводки —ndjsonпечатает только элементы, обрыв говорится в stderr. Остальные развилки в силе.bim-ba commentedon Oct 8, 2026
P10 - я бы сделал поддержку формата и колонок и в CLI и в MCP (это display-слои, в отличие от SDK)
P12 - блин, не знаю как правильнее бы это сделать, потому что я в другом Issue сказал что типа для JSON мы всегда будем выводить обернутый объект в выводе:
{items, truncated, next, total}, а тут в ndjson вот так, мб откатить решение по JSON или как-то по другому подумать на счет JSON и NDJSON форматов?и еще я думаю, тут у нас так много проблем и кода будет тупо из-за того что мы фичу
--columnsхотим добавить, мб пока отложить ее в техдолг и не делать? и назвать ее как-нибудь типа--showили--fields(лучше)?bim-ba commentedon Oct 10, 2026
Ответ архитектора на три пункта владельца (2026-10-10)
Отложить выбор полей — согласна, записываю как решённое. С ним уходят пять развилок из четырнадцати (Р6–Р9 и вариант Б в Р10) и третий PR. Остаётся два PR: таблицы и
ndjson;name.Имя
--fieldsзанято. Около 18 команд Трекера и Вики уже несут--fieldsсо смыслом «сервис отдаёт только эти поля» (ycli tracker issues get DE-1 --fields key,summary). Это шире, чем конфликт--columns(2 команды). Имя выберем в задаче техдолга, не сейчас; запасные —--show,--only.Р12 — откатывать решение по JSON не нужно, противоречия нет. Правило из #538 (6 — Б) уже делит форматы на два сорта, и
ndjsonпопадает во второй:json,yaml{items, truncated, next, total}jq -r .nextpretty,csv,markdown,ndjson,namendjson— это «по строке на элемент» по определению формата; обёртка в нём возможна только лишней последней строкой, от которойjq -c .keyдаётnull. Кому нужен токен машинно — берёт-o json.Р10 — форматы в MCP предлагаю отложить вместе с выбором полей, а лимит уменьшить сейчас. Инструмент отдаёт структурный ответ, который клиент сверяет со схемой;
csvилиmarkdownиз инструмента — это текст вместо объекта, то есть та же «вторая форма ответа», что и частичный элемент. Обе идеи — одна задача техдолга «компактный ответ инструмента». А измеренную проблему (до ~206 тыс. токенов наtracker_issues_list) закрывает одна настройка: лимит по умолчанию в MCP 50 вместо 500, дальше агент идёт поnext.Что нужно от вас
bim-ba commentedon Oct 10, 2026
bim-ba commentedon Oct 10, 2026
Решено (владелец, 2026-10-10), все развилки закрыты, метка снята:
ndjsonпечатает только элементы, обрыв — в stderr;jsonиyamlнесут объект{items, truncated, next, total}(#538, 6 — Б)--fieldsзанято у команд Трекера и Вики)Исполнение: два PR после #534 — таблицы (
csv,markdown) сndjson;name. E5.feat(mcp)!: a listing tool gives 50 items when no `limit` is asked (#566
feat(cli): `-o csv`, `-o markdown` and `-o ndjson` print a table or o…
feat(cli): `-o name` prints the identifier of each object, what the c…
bim-ba commentedon Oct 10, 2026
Построено и лежит в main:
csv,markdown,ndjson— #568;name— #569 и #572 (DataLens); лимит 50 для MCP — #566. Отложенное вашим решением (выбор полей, форматы в MCP) и пробел-o nameу завёрнутых ответов DataLens записаны в #575. Закрываю.