Кто‑то передаёт вам шаблон Word и срок сдачи. Какие данные нужны? Обычный ответ — открыть файл, пролистать, догадаться, запустить, прочитать ошибку и запустить снова. С запущенным локально GroupDocs.Assembly.Mcp (dnx GroupDocs.Assembly.Mcp --yes) Claude Desktop, Cursor или Copilot могут обратиться к шаблону напрямую: get_template_fields возвращает каждый тег, имена данных, которые он использует, и JSON‑скелет для заполнения, без запуска движка, а когда запуск не удаётся, ошибка указывает, что изменить:

Какие данные нужны файлу order-lines.docx? Если он не генерируется, скажите, почему и как исправить шаблон.

Пошаговая версия с конфигурацией и отладкой описана в документации: How to find out what a template needs and why it failed.

Почему стоит проверять шаблон перед заполнением?

Потому что проба‑и‑ошибка — дорогой способ узнать схему. Агент, который угадывает имена полей по видимому тексту документа, назовёт CustomerName, когда в шаблоне написано customer.Name, и каждая неверная догадка стоит раунда запроса и запутанной ошибки. Шаблон — не проза; это программа с контрактом данных, и контракт можно прочитать.

Именно это делает get_template_fields. Он разбирает теги <<…>>, определяет имена и формирует скелет:

-> get_template_fields {"template":{"filePath":"order-lines.docx"}}
<- { "tagCount": 3,
     "dataSourceNames": [ "lines" ],
     "fields": [ "lines[].Title", "lines[].Quantity" ],
     "dataSkeleton": { "lines": [ { "Title": "", "Quantity": "" } ] },
     "notes": [ "fields and dataSkeleton are inferred from the tags,
       not from the engine; values computed by Select/GroupBy
       projections are not followed." ] }

Примечание откровенно о методе: это статический осмотр. Поле, полученное внутри проекции Select, не отслеживается. Для обычного контракта, письма или шаблона счёта‑фактуры скелет — именно то, что нужно заполнить.

Скелет также меняет диалог с вами. Вместо «Я попытался сгенерировать заказ, но он не удался», агент может сказать «этот шаблон требует список строк, каждая из которых имеет заголовок и количество; я нашёл три такие строки в вашем письме, вот они», и только после этого генерировать. Осмотр дешёв, не требует данных и ничего не меняет, поэтому это правильный первый шаг для любого шаблона, который агент ещё не видел, и правильный шаг каждый раз, когда кто‑то отредактировал шаблон.

Три сбоя, три решения

проблема шаблона          что говорит сервер          исправление
------------------------  ----------------------------  -------------------
{{name}} placeholders     "2 '{{...}}' placeholder(s).  write <<[name]>>
                          ... does not process that
                          syntax"
<<foreach>> never closed  "Unexpected end of template.  add <</foreach>>
                          A block tag is not closed"
data lacks a field        "The template reads 'Email',  add it, or
                          which the data does not have" allowMissingMembers

Неправильный синтаксис. Многие шаблоны в дикой природе писались для других движков и используют {{name}}. GroupDocs.Assembly оставляет их как текст, и осмотр сообщает об этом до того, как кто‑то потратит время на запуск:

-> get_template_fields {"template":{"filePath":"shipping-notice.docx"}}
<- { "tagCount": 0, "notes": [ "No <<…>> tags were found: ...",
     "The template contains 2 '{{…}}' placeholder(s). GroupDocs.Assembly
      does not process that syntax and leaves it as text; write
      <<[name]>> instead." ] }

Незакрытый блок. Наш order-lines.docx открывает <<foreach>> и никогда не закрывает его. Осмотр перечисляет теги без проблем; генерация — нет:

-> assemble_document {"template":{"filePath":"order-lines.docx"},
     "dataJson":"{\"lines\":[{\"Title\":\"Cable\",\"Quantity\":2}]}"}
<- Document assembly failed for 'order-lines.docx': ...
   Unexpected end of template. A block tag is not closed: every
   <<foreach>> needs <</foreach>> and every <<if>> needs <</if>>.

Отсутствующее поле. Когда в данных нет того, что читает шаблон, ошибка указывает поле, сообщает, что имена чувствительны к регистру, и предлагает переключатель: allowMissingMembers: true выводит ничего для отсутствующих членов и пустые списки вместо ошибки.

Когда шаблон полон ошибок

Некоторые шаблоны содержат несколько ошибок, и исправлять их по одной неудачной попытке — медленно. inlineErrors: true превращает шаблон в собственный отчёт об ошибках: документ генерируется, а каждый ошибочный тег получает своё сообщение рядом с ним. На примере шаблона из примеров GroupDocs.Assembly:

-> assemble_document {"template":{"filePath":"inline-error.docx"},
     "dataJson":"{\"name\":\"x\"}","inlineErrors":true}
<- Assembled 'inline-error.docx' ... The template has errors: each one
   is written into the output next to its tag, starting with 'Error!'

В выводе появляется << var [name] Error! An assignment operator is expected. >> в том месте документа, где находится тег. Откройте файл, исправьте каждый отмеченный тег и запустите снова без флага.

Что осмотр не может увидеть

Бинарные шаблоны Outlook — исключение. Теги в файле .msg нельзя прочитать без генерации, и сервер сообщает об этом, а не возвращает пустой список, выглядящий как «нет полей»:

-> get_template_fields {"template":{"filePath":"contracts-table.msg"}}
<- { "readable": false, "notes": [ "Tags cannot be read from a .msg
     template without generating it. Save the template as DOCX, XLSX,
     PPTX or EML to inspect it, or generate it with assemble_document
     and inlineErrors=true to see which fields fail." ] }

Ещё одна ловушка: список, пустой в данных, не имеет типов членов. Наш шаблон контракта умножает item.Quantity * item.UnitPrice; при "items": [] и allowMissingMembers: true генерация всё равно падает с “Can not apply operator ‘’ to operands of type ‘System.Object’ and ‘System.Object’”*. Попросите агента проверять, что список не пуст, перед генерацией, и уточните, как должен выглядеть пустой контракт.

Честные ограничения

  • Осмотр статичен: проекции Select и GroupBy не отслеживаются, а шаблоны .msg нельзя прочитать.
  • Шаблоны — доверенный ввод; теги изображений и документов загружают пути и URL, которые возвращают их выражения.
  • Режим оценки: каждый вывод начинается с «Evaluation Only. Created with GroupDocs.Assembly 26.7…».
  • Даты: передайте 2026-11-12T00:00:00 и форматируйте в шаблоне с :"d MMMM yyyy"; строка только с датой смещалась на день на машине UTC+2, а "12.11.2026" читалась как 11 декабря.

FAQ

Как увидеть, какие поля нужны шаблону Word?
Попросите агента вызвать get_template_fields для него. Вы получите теги, имена данных и JSON‑скелет локально, без генерации чего‑либо.

Почему мой шаблон выводит {{name}} вместо значения?
Потому что теги GroupDocs.Assembly — <<[name]>>. Осмотр сервера помечает заполнители {{…}} и подсказывает, что писать вместо них.

Можно ли использовать Markdown как шаблон?
Да. Наш product-readme.md с тегами <<[product]>> и <<[description]>> был проверен так же, как Word‑файл, и сразу сгенерирован в DOCX.

Углубиться