ilyautov doc2md — конвертация документов в Markdown до чтения агентом
Зачем
Агент обычно читает .docx, .xlsx, .pptx, .pdf каждый своим отдельным ридером — на пачке из 10-20 файлов это десятки лишних вызовов инструментов и разный формат вывода под каждый тип. doc2md прогоняет всё через один конвертер и на выходе всегда получается чистый GitHub-Flavored Markdown, независимо от того, что было на входе.
Это не замена скиллам docx/pdf/xlsx/pptx для точечной работы с одним файлом (правки, форматирование, извлечение изображений — там нужны они). doc2md — для случая «прочитать содержимое пачки документов и дальше с ней работать», особенно когда документов много и формат смешанный.
Три способа подать файлы на вход
- Путь(и), которые назвал пользователь. Передать как есть, можно несколько через пробел.
- Файл прислали в чат. Cowork кладёт вложения в папку uploads текущей сессии — путь виден в системном контексте. Передать этот путь напрямую, отдельно скачивать не нужно.
- Целая папка. Передать путь к папке — скрипт рекурсивно найдёт внутри всё поддерживаемое и сконвертирует.
Быстрый старт
Основной, кросс-платформенный вариант (Windows/macOS/Linux, нужен только Node.js — он и так требуется для npx/anydoc):
node <папка скилла>/scripts/convert.js договор.docx
node <папка скилла>/scripts/convert.js ~/Downloads/акты/ -o ~/Downloads/акты-md/
node <папка скилла>/scripts/convert.js a.pdf b.xlsx "отчёт за март.pptx"
На Unix (macOS/Linux/WSL/Git Bash) можно и через bash-версию — поведение идентично:
bash <папка скилла>/scripts/convert.sh договор.docx
Без -o каждый <имя>.<расширение>.md пишется рядом с исходником (например, отчёт.docx → отчёт.docx.md — расширение сохраняется в имени намеренно, иначе отчёт.docx и отчёт.csv в одной папке лягут в один и тот же отчёт.md и один перезапишет другой). С -o папка/ все результаты собираются в одном месте.
⚠️ При
-o папка/вывод плоский: два файла с одинаковым именем из разных подпапок (a/отчёт.docxиb/отчёт.docx) дадут одинотчёт.docx.md, второй перезапишет первый. Если в дереве возможны тёзки — конвертируй без-o(рядом с исходниками) либо по подпапкам отдельными вызовами.
Для одного файла и разового вызова можно и напрямую, без скрипта:
npx -y @firecrawl/anydoc report.docx -o report.docx.md
Скрипт convert.js нужен для пакетного случая (папка, список файлов) и для честной сводки по результатам, single-file вызов ничего не добавляет к прямому npx.
Поддерживаемые форматы
| Группа | Расширения |
|---|---|
| Word | .doc .docx .docm |
| PowerPoint | .ppt .pps .pot .pptx .pptm .ppsx .ppsm |
| Excel | .xls .xlsx .xlsm .xlsb |
| OpenDocument | .odt .ods .odp |
| Прочее | .rtf .epub .csv .pdf |
Что скрипт делает, а что нет
- Конвертирует файл(ы), печатает построчный статус (
OK/ПРОПУСК/ОШИБКА) и итоговую сводку: сколько успешно, сколько пропущено, сколько ошибок вызова. - Различие ПРОПУСК vs ОШИБКА.
OK— код возврата anydoc0.ОШИБКА— не удалось даже запуститьnpx/anydoc (нет в PATH, код126/127): это отказ окружения, а не «файл нечитаем», и OCR тут не поможет.ПРОПУСК— anydoc запустился, но файл не сконвертировался (любой другой ненулевой код): почти всегда скан/шифр/битый файл, в строку выводится stderr от anydoc как есть. - Сканы и PDF-картинки без текстового слоя anydoc не читает — это не баг, а ограничение движка (нет OCR внутри). Такие файлы попадают в «ПРОПУСК», batch на этом не падает. Для них: сначала OCR через скилл
pdf(шаг «сделать PDF searchable»), потом повторный прогон. - Зашифрованные/защищённые паролем файлы — туда же, в «ПРОПУСК», с текстом ошибки от anydoc.
- Не удаляет и не трогает исходники. Не перезаписывает существующие
.md, если явно не совпало имя (тогда перезапишет — как обычная запись файла).
Контракт кодов возврата anydoc формально не задокументирован. Скрипт держится консервативной трактовки выше (
0=OK,126/127=ошибка окружения, прочее=пропуск). При первом боевом прогоне на заведомо битом/зашифрованном файле стоит перепроверить, что anydoc действительно отдаёт на них ненулевой код, и при необходимости уточнить трактовку.
После конвертации
Для больших документов не пересказывай .md в контекст целиком — прочитай оглавление/начало, дальше ищи (grep) по конкретным разделам. На пачке из десятков файлов это ощутимая экономия токенов относительно построчного чтения каждого через штатный формат-специфичный ридер.
Установка
Ничего ставить не нужно: npx -y @firecrawl/anydoc сам скачивает нужный бинарник под платформу при первом запуске (нужен Node 18+, в песочнице Cowork уже есть). Для постоянного использования без повторной загрузки каждый раз: npm install -g @firecrawl/anydoc.
Протестировано (06.08.2026, песочница Cowork, Node 22, Linux/macOS)
.csvс кириллицей → чистая GFM-таблица, без искажений..docxс заголовком, абзацем и таблицей на русском → корректный Markdown, кириллица не потеряна.- Папка с двумя файлами одного имени, разных расширений (
test.csv+test.docx) → найдена и починена коллизия имён до релиза: без сохранения расширения в имени.mdоба ложились в один файл и второй перезаписывал первый. - Путь с пробелами и кириллицей в имени файла → работает.
- Несуществующий путь в списке аргументов → пропускается с понятным сообщением, batch не падает.
scripts/convert.js(кросс-платформенная Node-версия): та же батарея тестов повторена и прошла — рекурсивный обход папки, коллизия имён, кириллица в.docx/.csv, вложенная подпапка, несуществующий путь.- Синтаксис-гейт обеих версий (
node --check,bash -n) и smoke-тесты (--help, несуществующий путь) гоняются в CI на каждый PR.
Не тестировал: .pptx, .xlsx, .pdf, .epub, реальную пачку документов клиента, файлы за пределами тестовой песочницы. Живой запуск на Windows не делал — в песочнице нет Windows-окружения. convert.js написан без shell-специфичного синтаксиса и с shell:true для npx на win32 (известная особенность Node — без этого npx на Windows не резолвится), но это рассуждение о корректности, а не проверка. Файлы со спецсимволами & ^ % в имени на Windows не проверялись. При первом боевом использовании на Windows — перепроверить и дополнить эту секцию, не выдавать непроверенное за проверенное.
Источник
Обёртка над github.com/firecrawl/anydoc (MIT, Rust). По собственному бенчмарку авторов (⚠️ вендорские цифры, независимо не перепроверялись) против libreoffice/unstructured/markitdown/pandoc/docling/mammoth на 100 документах — anydoc первым местом по качеству на всех 14 форматах и на два порядка быстрее (медиана 4.4 мс/документ против 100+ мс у конкурентов). Апстрим публикует свой минимальный skill (npx skills add firecrawl/anydoc) — он умеет то же самое для одного файла за раз, без пакетной обработки, без сводки по batch и без русской документации. Этот скилл достраивает именно то, чего там нет.