document-worker

Сервис работы с офисными документами: инструменты, устройство, зависимости и ограничения.

Сервис переписан

Сервис переведён с Python на Node.js и TypeScript. Прежняя версия только читала документы и предоставляла один инструмент. Текущая читает Word, Excel и PowerPoint, а Word и Excel ещё и изменяет. Ниже описана текущая версия.

Назначение

Читает, изменяет и создаёт офисные документы в файлах чата. Результат записывает в чат.

В платформе источник называется Doc Worker, адрес http://eap-document-worker-mcp_eva:8001/mcp, транспорт Streamable HTTP.

Инструменты

69 инструментов, модель видит 68. Делятся на три семейства по префиксу имени.

Префикс	Формат	Чтение	Изменение
doc_	Word	да	да
xls_	Excel	да	да
ppt_	PowerPoint	да	нет

Плюс скрытый от модели init_eva_session.

Word: чтение

doc_read_document, doc_get_document_info, doc_search_text, doc_list_images, doc_read_comments, doc_get_page_layout, doc_read_header_footer, doc_read_footnotes.

Чтение возвращает содержимое с номерами блоков и подсказками об оформлении. Номера блоков затем используются инструментами правки.

Word: изменение

doc_replace_texts, doc_edit_paragraphs, doc_insert_paragraphs, doc_delete_paragraphs, doc_format_text, doc_set_paragraph_formats, doc_highlight_text, doc_set_headings, doc_insert_table, doc_edit_table_cells, doc_set_page_layout, doc_apply_document_preset.

Word: комментарии и правки

doc_add_comment, doc_add_comments, doc_reply_to_comment, doc_delete_comment, doc_accept_all_changes, doc_reject_all_changes.

Word: создание

doc_create_document создаёт пустой документ. doc_create_from_markdown создаёт документ из разметки Markdown, либо из строки, либо из файла разметки в чате.

Разделение назначения задано в описаниях самих инструментов

Создание из разметки предназначено для новых документов. В описании прямо сказано не использовать его для правки существующего документа: для этого есть инструменты изменения.

Excel

Чтение: xls_get_workbook_info, xls_read_sheet, xls_read_cell, xls_search_cells, xls_get_sheet_properties, xls_list_named_ranges, xls_list_data_validations, xls_list_images.

Запись данных: xls_write_cell, xls_write_cells, xls_write_row, xls_write_rows, xls_clear_cells, xls_create_workbook.

Оформление: xls_format_cells, xls_format_cells_bulk, xls_set_column_width, xls_set_column_widths, xls_set_row_height, xls_set_row_heights, xls_merge_cells, xls_unmerge_cells.

Структура: xls_insert_rows, xls_delete_rows, xls_insert_columns, xls_delete_columns, xls_add_sheet, xls_rename_sheet, xls_delete_sheet, xls_copy_sheet.

Прочее: xls_set_freeze_panes, xls_set_auto_filter, xls_remove_auto_filter, xls_add_data_validation, xls_remove_data_validation, xls_add_named_range, xls_delete_named_range.

PowerPoint

ppt_get_info, ppt_read_slide, ppt_list_shapes. Обзор презентации, содержимое одного слайда по номеру с нуля, список фигур. Байты изображений не возвращаются.

Как передаётся файл

Все инструменты работы с документами принимают параметр artifact_key: имя файла в чате, например report.docx, либо полный ключ этого чата. Идентификатор файла передавать не нужно.

Правки записываются по тому же ключу, то есть перезаписывают исходный файл. После первого чтения сервис держит рабочую копию файла у себя, чтобы серия правок не приводила к повторным загрузкам.

Следствие для документации

Если имя результата совпадает с именем источника, исходный файл заменяется. Поэтому в пользовательской документации написано, что имя результата стоит задавать явно.

Ответы приходят в общем формате: признак успеха, результат, предупреждения, ошибки, подсказки модели, код ошибки.

Что за ним стоит

Составляющая	Значение
Среда исполнения	Node.js и TypeScript
Word	Библиотека @knorq/docx-mcp-server
Excel	Библиотека @knorq/xlsx-mcp-server
PowerPoint	Библиотека ts-pptx, только чтение
Модели машинного обучения	Не используются
Внешние сервисы	Только доступ к файлам чата

Доступ к файлам чата обязателен, режима работы без него нет. Секреты приходят только через привязку сессии.

Ограничения

Ограничение	Значение	Переменная
Размер документа	50 МиБ	DW_MAX_DOC_BYTES
Таймаут обращения к хранилищу	20 секунд	DW_HTTP_TIMEOUT
Рабочих копий файлов одновременно	8	DW_MAX_WORKING_FILES
Суммарный размер рабочих копий	100 МиБ	DW_MAX_WORKING_BYTES

PDF не поддерживается: для него используется сервис OCR. Форматы doc, xls и ppt не поддерживаются, только новые форматы.

Устройство

src/
  main.ts        выбор транспорта, http или stdio
  config.ts      настройки из файла и переменных DW_*
  logging.ts     скрытие ключей доступа в логах
  shared/        общий формат ответа и ошибки
  session/       привязка сессии и кэш рабочих копий
  storage/       правила имён, клиент и работа с файлами чата
  engines/       движки Word, Excel, PowerPoint
  tools/         привязка сессии и семейства doc_, xls_, ppt_

Развёртывание

Параметр	Значение
Транспорт	Streamable HTTP, поддерживается и stdio
Порт	8001
Адрес	http://<хост>:8001/mcp
Запуск	pnpm build и pnpm start, либо pnpm dev
Docker	Есть файл для compose

Переменные окружения: DW_TRANSPORT, DW_HOST, DW_PORT, DW_HTTP_TIMEOUT, DW_MAX_DOC_BYTES, DW_MAX_WORKING_FILES, DW_MAX_WORKING_BYTES, DW_EDIT_AUTHOR, DW_LOG_LEVEL, DW_NAME, DW_SETTINGS.

Несекретные настройки лежат в файле настроек сервиса, указания для модели там же. Отдельный документ docs/AGENT_PLAYBOOK.md описывает, как модели правильно работать с документами и таблицами.