Csv Xlsx

---
name: csv-xlsx
description: Собрать .xlsx из CSV/TSV - таблица в Excel, несколько файлов = несколько листов: "сделай xlsx", "переведи csv в excel", "книга с листами". Документы - `md-docx`, слайды - `md-pptx`.
---

# csv-xlsx

Сборка .xlsx из CSV/TSV без зависимостей: zip + SpreadsheetML руками, как md-docx. Скрипт-эталон - `scripts/csv-xlsx.py` (top-level папка `scripts/` в корне проекта). Не нужен openpyxl - канонические скрипты stdlib-only.

## Когда применять

- Таблица уходит человеку, который откроет ее в Excel/Numbers/LibreOffice (заказчик, бухгалтерия, команда).
- Несколько CSV надо собрать в одну книгу листами.
- Данные уже есть или легко выгружаются в CSV/TSV - остальное скрипт сделает сам (типизация, шапка, ширины).

## Когда НЕ применять

- Таблица для чтения в чате/доке - обычный markdown, конвертация не нужна.
- Google Sheets проекта - там свой канал (MCP), не файл.
- Сложная верстка (объединенные ячейки, диаграммы, сводные) - скрипт этого не умеет намеренно; такое делается руками в Excel или отдельным инструментом.

## CLI

```bash
python3 scripts/csv-xlsx.py data.csv                       # data.xlsx рядом
python3 scripts/csv-xlsx.py a.csv b.tsv --out отчет.xlsx   # два листа (имена - из имен файлов)
python3 scripts/csv-xlsx.py план.csv --formulas            # "=..." писать формулами
python3 scripts/csv-xlsx.py dump.csv --delimiter "|"       # принудительный разделитель (обычно не нужен)
python3 scripts/csv-xlsx.py сырье.csv --no-header          # первая строка - данные
```

Автор и заголовок файла - по `rules/document-metadata.md`: `--author` -> `DOC_AUTHOR` -> `XLSX_AUTHOR` -> `dwl`; `--title` / имя выходного файла. Проверка - распаковать `docProps/core.xml` (`unzip -p out.xlsx docProps/core.xml`).

## Что скрипт делает с данными (знать, чтобы не удивляться)

- **Типизация консервативная.** Числа пишутся числами, но "007", телефоны с пробелами и id длиннее 15 цифр остаются текстом: Excel молча съедает ведущие нули и обнуляет хвост длинных чисел - "число как текст" безопаснее. Даты - только строгий `YYYY-MM-DD` (календарно валидный), остальное текст.
- **Формулы по умолчанию - текст.** Ячейка `=SUM(...)` оживает только с флагом `--formulas`. Это защита от CSV injection: файл из внешнего источника с `=HYPERLINK(...)` не должен стать живой формулой без явного намерения. Включая `--formulas` на чужих данных - просмотри их глазами. С флагом формулы пишутся без кэша значений, пересчет при открытии включен (`fullCalcOnLoad`) - Excel посчитает сам; сам скрипт формулы НЕ вычисляет.
- **Шапка** (первая строка) - жирная и закрепленная; `--no-header`, если ее нет. Ячейки шапки никогда не типизируются - "2026-01-01" в шапке остается названием колонки.
- **Кодировка - по содержимому.** BOM utf-32/utf-16 (экспорт Excel "Unicode Text") распознается первым, без BOM - utf-8; не utf-8 - cp1251 (дефолт русского Excel) с пометкой в stderr.
- **Разделитель - консервативно.** По расширению (запятая; у `.tsv` таб). Разбор с одинаковой шириной строк больше одной колонки не переигрывается никогда (`;` в кавычках запятую не собьет). Неубедительный разбор - одна колонка или рваная ширина - переигрывается остальными кандидатами из `,` `;` `\t` `|` с требованием одинаковой ширины и пометкой в stderr: так сам собирается `;`-экспорт русского Excel, включая десятичные запятые ("чай;12,50"). Не вышло и переразобрать, а вся таблица - одна колонка при живом другом разделителе - предупреждение, молча склеенную колонку скрипт не отдает. Явный `--delimiter` главнее всего и переразбор выключает; честному одноколоночному файлу с консистентным `;` в тексте нужен явный `--delimiter ","`.
- **Перенос строки внутри ячейки** сохраняется и **показывается**: такой ячейке ставится стиль с `wrapText`, иначе Excel склеивает строки в одну, хотя сам символ в файле лежит (поймано живой проверкой в Excel на Mac, 06.08.2026 - в XML перенос был, на экране его не было).
- **Имена листов** - из имен файлов, приведенные к правилам Excel (без `[]:*?/\`, до 31 символа, уникальные).
- Ширина колонок - по содержимому с потолком; control-символы, запрещенные в XML, вычищаются.

## Верификация результата

Как у md-docx: файл бинарный, глазами его смотрит пользователь. Агенту - структурная проверка: распаковать zip, убедиться что нужные значения в `xl/worksheets/sheet1.xml` (числа как `<v>`, текст как `<is><t>`), автор в `docProps/core.xml`. Не пересказывать содержимое книги по памяти исходного CSV.

## Ограничения (намеренные)

- Один тип входа - CSV/TSV. Нужен xlsx из markdown-таблицы - выгрузи ее в CSV (это одна команда для агента), не расширяй скрипт.
- Нет объединенных ячеек, стилей по ячейкам, нескольких шапок, диаграмм. Появилась регулярная нужда - обсуждай отдельный инструмент, не дописывай этот.
- Перезапись существующего .xlsx - как в md-pdf: перед перезаписью файла, который делал не ты, сначала копия в scratchpad.

## Связанные файлы

- `scripts/csv-xlsx.py` в корне проекта - эталонный скрипт.
- Скиллы-соседи по документам: `md-docx` (Word), `md-pdf` (PDF), `md-pptx` (презентации).
- `rules/document-metadata.md` - свойства генерируемых документов.