Ktoś przekazuje ci szablon Worda i termin. Jakich danych potrzebuje? Zwykle odpowiedzią jest otworzyć go, przewinąć, zgadnąć, uruchomić, odczytać błąd i uruchomić ponownie. Przy uruchomionym lokalnie GroupDocs.Assembly.Mcp (dnx GroupDocs.Assembly.Mcp --yes), Claude Desktop, Cursor lub Copilot pytają szablon bezpośrednio: get_template_fields zwraca wszystkie znaczniki, nazwy danych, których używa, oraz szkielet JSON do wypełnienia, bez uruchamiania silnika, a gdy uruchomienie się nie powiedzie, błąd mówi, co zmienić:

Jakich danych potrzebuje order-lines.docx? Jeśli nie uda się wygenerować, powiedz mi dlaczego i jak naprawić szablon.

Wersja krok po kroku z konfiguracją i rozwiązywaniem problemów znajduje się w dokumentacji: Jak dowiedzieć się, czego potrzebuje szablon i dlaczego nie powiódł się.

Dlaczego sprawdzać przed wypełnieniem?

Ponieważ metoda prób i błędów jest kosztownym sposobem poznania schematu. Agent, który zgaduje nazwy pól na podstawie widocznego tekstu dokumentu, zgadnie CustomerName, gdy szablon odczytuje customer.Name, a każdy błędny strzał kosztuje dodatkowy cykl i mylący błąd. Szablon nie jest prozą; to program z kontraktem danych, a kontrakt można odczytać.

To wszystko, co robi get_template_fields. Parsuje znaczniki <<…>>, wyznacza nazwy i buduje szkielet:

-> 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." ] }

Uwaga jest szczera co do metody: jest to statyczna inspekcja. Pole wygenerowane wewnątrz projekcji Select nie jest śledzone. Dla zwykłego kontraktu, listu lub szablonu faktury, szkielet jest dokładnie tym, co należy wypełnić.

Szkielet również zmienia rozmowę z tobą. Zamiast „próbowałem wygenerować zamówienie i nie udało się”, agent może powiedzieć „ten szablon potrzebuje listy wierszy, każdy z tytułem i ilością; znalazłem trzy w twoim e‑mailu, oto one”, i dopiero wtedy wygenerować. Inspekcja jest tania, nie wymaga danych i nie modyfikuje niczego, więc jest właściwym pierwszym krokiem dla każdego szablonu, którego agent nie widział wcześniej, oraz właściwym krokiem ponownie, gdy ktoś edytował szablon od tego czasu.

Trzy niepowodzenia, trzy odpowiedzi

problem szablonu          co mówi serwer                rozwiązanie
------------------------  ----------------------------  -------------------
{{name}} placeholder'y    "2 '{{...}}' placeholder(y).  napisz <<[name]>>
                          ... nie przetwarza tej
                          składni"
<<foreach>> nie zamknięty "Unexpected end of template.  add <</foreach>>
                          Tag bloku nie jest zamknięty"
dane nie zawierają pola   "The template reads 'Email',  add it, or
                          which the data does not have" allowMissingMembers

Zła składnia. Wiele szablonów w praktyce zostało napisanych dla innych silników i używa {{name}}. GroupDocs.Assembly pozostawia je jako tekst, a inspekcja informuje o tym, zanim ktoś zmarnuje uruchomienie:

-> 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." ] }

Nie zamknięty blok. Nasz order-lines.docx otwiera <<foreach>> i nigdy go nie zamyka. Inspekcja wymienia znaczniki z zadowoleniem; generowanie nie:

-> 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>>.

Brakujące pole. Gdy dane nie zawierają czegoś, co odczytuje szablon, błąd podaje nazwę pola, informuje, że nazwy są rozróżniane pod względem wielkości liter i oferuje przełącznik: allowMissingMembers: true nie zwraca nic dla brakujących elementów i pustych list zamiast zakończenia błędem.

Kiedy szablon jest pełen błędów

Niektóre szablony mają kilka błędów, a naprawianie ich po jednym nieudanym uruchomieniu jest wolne. inlineErrors: true zamienia szablon w własny raport błędów: dokument jest generowany, a każdy wadliwy znacznik otrzymuje swoją wiadomość napisaną obok niego. Na przykładowym szablonie z przykładów 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!'

Wyjście zawiera << var [name] Error! An assignment operator is expected. >> w miejscu dokumentu, w którym znajduje się znacznik. Otwórz plik, napraw każdy oznaczony znacznik, uruchom ponownie bez flagi.

Co inspekcja nie może zobaczyć

Binarnymi szablonami Outlooka są wyjątkiem. Znaczniki pliku .msg nie mogą być odczytane bez jego generowania, a serwer informuje o tym zamiast zwracać pustą listę wyglądającą jak „brak pól”:

-> 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." ] }

Jeszcze jedna pułapka, na którą natrafiliśmy: lista pusta w danych nie ma typów elementów. Nasz szablon kontraktu mnoży item.Quantity * item.UnitPrice; przy "items": [] i allowMissingMembers: true, generowanie nadal kończyło się błędem “Can not apply operator ‘’ to operands of type ‘System.Object’ and ‘System.Object’”*. Niech agent sprawdzi, czy lista nie jest pusta przed generowaniem, i zapyta cię, jak powinien wyglądać pusty kontrakt.

Szczere ograniczenia

  • Inspekcja jest statyczna: projekcje Select i GroupBy nie są śledzone, a szablony .msg nie mogą być odczytane.
  • Szablony są zaufanym wejściem; znaczniki obrazu i dokumentu ładują ścieżki i URL‑e zwracane przez ich wyrażenia.
  • Tryb oceny: każdy wynik zaczyna się od “Evaluation Only. Created with GroupDocs.Assembly 26.7…”.
  • Daty: podaj 2026-11-12T00:00:00 i formatuj w szablonie przy pomocy :"d MMMM yyyy"; ciąg zawierający tylko datę został przesunięty o dzień na maszynie UTC+2, a "12.11.2026" został odczytany jako 11 grudnia.

FAQ

Jak mogę zobaczyć, jakie pola potrzebuje szablon Word?
Poproś agenta, aby wywołał get_template_fields na nim. Otrzymasz znaczniki, nazwy danych i szkielet JSON, lokalnie, bez generowania czegokolwiek.

Dlaczego mój szablon wyświetla {{name}} zamiast wartości?
Ponieważ znaczniki GroupDocs.Assembly to <<[name]>>. Inspekcja serwera oznacza placeholdery {{…}} i mówi, co napisać zamiast tego.

Czy Markdown może być szablonem?
Tak. Nasz product-readme.md z znacznikami <<[product]>> i <<[description]>> został zinspekcjonowany jak plik Word i wygenerowany bezpośrednio do DOCX.

Zagłęb się