Skip to content

Новые форматы вывода (csv, ndjson, name, markdown, --columns): 14 развилок до кода #561

Closed

Description

@bim-ba

О чём решение

Новые форматы вывода, решённые в #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.key
DE-1,Fix,open
Error: -o csv prints a listing; this command returns one object field,value
key,DE-1
summary,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 table
table(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) понадобится в списке исключений возможен без пометки
Новая проверка без решения владельца да, это оно нет

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

  1. columns в MCP для экономии токенов (Р10-Б) — отдельной развилкой после замера: сколько токенов весит типичный список и сколько экономит проекция. Сейчас довод качественный.
  2. Своя шапка столбца (--columns KEY:key,STATUS:status.key, Р7-Б) — добавляется позже без поломки, если понадобится.
  3. -o name у sync печатает пути файлов: ycli sync status -o name | xargs git add.
  4. --columns без значения печатает список доступных столбцов команды и ничего не запрашивает — чтобы не ходить в schema.
  5. Строка в справке --columns у команд Трекера: чем она отличается от --fields (тот режет ответ на стороне сервиса, этот — на печати).

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

«Всё по рекомендации» или номера, где иначе; и какие пункты сверху брать.

Activity

  1. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    Замер к Р10 (E5): ответ списка в MCP весит до ~206 тыс. токенов — меняю рекомендацию

    Мерили вывод -o json с лимитом по умолчанию (500), живые данные; токены = символы / 4, на кириллице это нижняя граница.

    Список Элементов Целиком Три поля Осталось
    tracker issues list 500 ~206 тыс. токенов key, id, summary — ~12,7 тыс. 6 %
    datalens entries list --scope widget 437 ~72 тыс. key, entryId, name — ~18 тыс. 25 %
    datalens entries list --scope dataset 23 ~3,6 тыс. ~0,7 тыс. 18 %
    wiki pages descendants-list 1 45 символов — у элемента и так 2 поля

    Проверила код сервера: предела на размер ответа инструмента нет (есть только предел на размер схемы). Значит, сегодня tracker_issues_list без limit отдаёт агенту 500 задач по 36 полей — ответ, который не помещается в окно большинства клиентов. Число 500 для MCP решено в #502 до этого замера.

    Р10 теперь не «ничего». Варианты:

    Что Пример Цена
    А Ничего — агент получает ~206 тыс. токенов или сам догадывается дать limit
    Б Параметр columns у инструментов-списков tracker_issues_list(queue="DE", columns=["key","summary"]) ответ с частью полей не проходит схему полной модели — нужна форма «частичный элемент»
    В Меньший лимит по умолчанию в MCP tracker_issues_list(queue="DE") → 50 задач и next одна настройка; меняет решение #502 (500) только для MCP
    Г Б и В вместе обе цены

    Рекомендация: В сейчас (одна настройка, чинит проблему на всех 46 листингах сразу, и агент уже умеет продолжать по next), Б — отдельной развилкой, когда будет решена форма частичного ответа. Число для В предлагаю 50: 50 задач Трекера ≈ 20 тыс. токенов.

    Р13 (BOM) измерить нечем: ни LibreOffice, ни Excel на машине нет; остаётся «из общеизвестного поведения».

  2. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    Р12 снят решением в #538 (6 — Б): -o json печатает тот же объект {items, truncated, next, total}, что инструмент, поэтому машинный токен есть и без сводки — ndjson печатает только элементы, обрыв говорится в stderr. Остальные развилки в силе.

  3. bim-ba commented on Oct 8, 2026

    @bim-ba
    OwnerAuthor

    P10 - я бы сделал поддержку формата и колонок и в CLI и в MCP (это display-слои, в отличие от SDK)
    P12 - блин, не знаю как правильнее бы это сделать, потому что я в другом Issue сказал что типа для JSON мы всегда будем выводить обернутый объект в выводе: {items, truncated, next, total}, а тут в ndjson вот так, мб откатить решение по JSON или как-то по другому подумать на счет JSON и NDJSON форматов?


    и еще я думаю, тут у нас так много проблем и кода будет тупо из-за того что мы фичу --columns хотим добавить, мб пока отложить ее в техдолг и не делать? и назвать ее как-нибудь типа --show или --fields (лучше)?

  4. bim-ba commented on Oct 10, 2026

    @bim-ba
    OwnerAuthor

    Ответ архитектора на три пункта владельца (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 попадает во второй:

    Сорт Форматы Что в stdout Где обрыв и токен
    Документ json, yaml один объект {items, truncated, next, total} в самом объекте: jq -r .next
    Строки pretty, csv, markdown, ndjson, name по строке на элемент в stderr, готовой командой

    ndjson — это «по строке на элемент» по определению формата; обёртка в нём возможна только лишней последней строкой, от которой jq -c .key даёт null. Кому нужен токен машинно — берёт -o json.

    Р10 — форматы в MCP предлагаю отложить вместе с выбором полей, а лимит уменьшить сейчас. Инструмент отдаёт структурный ответ, который клиент сверяет со схемой; csv или markdown из инструмента — это текст вместо объекта, то есть та же «вторая форма ответа», что и частичный элемент. Обе идеи — одна задача техдолга «компактный ответ инструмента». А измеренную проблему (до ~206 тыс. токенов на tracker_issues_list) закрывает одна настройка: лимит по умолчанию в MCP 50 вместо 500, дальше агент идёт по next.

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

    1. Остальные развилки (Р1–Р5, Р11, Р13, Р14) — «по рекомендации» или номера, где иначе.
    2. Лимит по умолчанию в MCP 50 — да / нет.
    3. Форматы в MCP — отложить в техдолг вместе с выбором полей (рекомендую) или делать сейчас.
  5. bim-ba commented on Oct 10, 2026

    @bim-ba
    OwnerAuthor
    1. да, по остальным я согласен с тобой
    2. ок
    3. да, давай отложим пока
  6. bim-ba commented on Oct 10, 2026

    @bim-ba
    OwnerAuthor

    Решено (владелец, 2026-10-10), все развилки закрыты, метка снята:

    Что Решение
    Р1–Р5, Р11, Р13, Р14 по рекомендации из сводки
    Р12 А: ndjson печатает только элементы, обрыв — в stderr; json и yaml несут объект {items, truncated, next, total} (#538, 6 — Б)
    Выбор полей (Р6–Р9) отложен в техдолг; имя выбирается там (--fields занято у команд Трекера и Вики)
    Р10: лимит по умолчанию в MCP 50 вместо 500, отдельным PR после #534; меняет #502 в этой точке, только для MCP
    Р10: форматы и выбор полей в MCP отложены в техдолг вместе с выбором полей — задача «компактный ответ инструмента»

    Исполнение: два PR после #534 — таблицы (csv, markdown) с ndjson; name. E5.

  7. bim-ba commented on Oct 10, 2026

    @bim-ba
    OwnerAuthor

    Построено и лежит в main: csv, markdown, ndjson — #568; name — #569 и #572 (DataLens); лимит 50 для MCP — #566. Отложенное вашим решением (выбор полей, форматы в MCP) и пробел -o name у завёрнутых ответов DataLens записаны в #575. Закрываю.

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