Doc2md

doc2md — конвертация документов в Markdown до чтения агентом

Зачем

Агент обычно читает .docx, .xlsx, .pptx, .pdf каждый своим отдельным ридером — на пачке из 10-20 файлов это десятки лишних вызовов инструментов и разный формат вывода под каждый тип. doc2md прогоняет всё через один конвертер и на выходе всегда получается чистый GitHub-Flavored Markdown, независимо от того, что было на входе.

Это не замена скиллам docx/pdf/xlsx/pptx для точечной работы с одним файлом (правки, форматирование, извлечение изображений — там нужны они). doc2md — для случая «прочитать содержимое пачки документов и дальше с ней работать», особенно когда документов много и формат смешанный.

Три способа подать файлы на вход

1. Путь(и), которые назвал пользователь. Передать как есть, можно несколько через пробел.
2. Файл прислали в чат. Cowork кладёт вложения в папку uploads текущей сессии — путь виден в системном контексте. Передать этот путь напрямую, отдельно скачивать не нужно.
3. Целая папка. Передать путь к папке — скрипт рекурсивно найдёт внутри всё поддерживаемое и сконвертирует.

Быстрый старт

Основной, кросс-платформенный вариант (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 — код возврата anydoc 0. ОШИБКА — не удалось даже запустить 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 и без русской документации. Этот скилл достраивает именно то, чего там нет.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ilyautov
• Source: ilyautov/doc2md
• License: MIT
• Homepage: https://ilyautov.github.io/doc2md/

Install and usage instructions live in the source repository linked above.