Qualcuno ti consegna un modello Word e una scadenza. Quali dati vuole? La risposta abituale è aprirlo, scorrere, indovinare, eseguirlo, leggere l’errore e rieseguirlo. Con GroupDocs.Assembly.Mcp in esecuzione locale (dnx GroupDocs.Assembly.Mcp --yes), Claude Desktop, Cursor o Copilot interrogano direttamente il modello: get_template_fields restituisce ogni tag, i nomi dei dati che utilizza e uno scheletro JSON da compilare, senza eseguire il motore, e quando un’esecuzione fallisce, l’errore indica cosa modificare:
Quali dati richiede order-lines.docx? Se non verrà generato, dimmi perché e come correggere il modello.
La versione passo‑passo con configurazione e risoluzione dei problemi è nella documentazione: Come scoprire di cosa ha bisogno un modello e perché è fallito.
Perché ispezionare prima di riempire?
Perché il tentativo‑errore è il modo costoso per apprendere uno schema. Un agente che indovina i nomi dei campi dal testo visibile di un documento indovinerà CustomerName quando il modello contiene customer.Name, e ogni errore di indovinamento comporta un round‑trip e un errore confuso. Un modello non è prosa; è un programma con un contratto di dati, e il contratto può essere letto.
Questo è tutto ciò che fa get_template_fields. Analizza i tag <<…>>, ricava i nomi e costruisce lo scheletro:
-> 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." ] }
La nota è onesta sul metodo: questa è un’ispezione statica. Un campo prodotto all’interno di una proiezione Select non viene seguito. Per un normale contratto, lettera o modello di fattura, lo scheletro è esattamente ciò che bisogna compilare.
Lo scheletro cambia anche la conversazione con te. Invece di “Ho provato a generare l’ordine e ha fallito”, l’agente può dire “questo modello richiede un elenco di righe, ciascuna con un titolo e una quantità; ne ho trovate tre nella tua email, eccole”, e solo allora generare. L’ispezione è economica, non richiede dati e non tocca nulla, quindi è la prima chiamata corretta per qualsiasi modello che l’agente non abbia ancora visto, e la chiamata corretta di nuovo ogni volta che qualcuno ha modificato il modello da allora.
Tre errori, tre soluzioni
template problem what the server says the fix
------------------------ ---------------------------- -------------------
{{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
La sintassi errata. Molti modelli in circolazione sono stati scritti per altri motori e usano {{name}}. GroupDocs.Assembly li lascia come testo, e l’ispezione lo segnala prima che qualcuno sprechi un’esecuzione:
-> 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." ] }
Il blocco non chiuso. Il nostro order-lines.docx apre un <<foreach>> e non lo chiude mai. L’ispezione elenca i tag felicemente; la generazione no:
-> 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>>.
Il campo mancante. Quando i dati non contengono qualcosa che il modello legge, l’errore indica il campo, afferma che i nomi sono sensibili al maiuscolo/minuscolo e offre l’opzione: allowMissingMembers: true non produce output per i membri mancanti e restituisce liste vuote invece di fallire. Questo suggerimento è più ampio del motore, come mostra la sezione successiva: una lista vuota fallisce comunque quando il modello esegue operazioni aritmetiche sui suoi membri.
Quando il modello è pieno di errori
Alcuni modelli hanno diversi errori, e correggerli uno per volta con esecuzioni fallite è lento. inlineErrors: true trasforma il modello nel proprio report di errore: il documento viene generato e ogni tag difettoso riceve il proprio messaggio scritto accanto. Sul modello di esempio proveniente dagli esempi di 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!'
L’output contiene << var [name] Error! An assignment operator is expected. >>, nel punto del documento in cui si trova il tag. Apri il file, correggi ogni tag contrassegnato, riesegui senza il flag.
Cosa l’ispezione non può vedere
I modelli binari di Outlook sono l’eccezione. I tag di un file .msg non possono essere letti senza generarlo, e il server lo segnala invece di restituire una lista vuota che sembra “nessun campo”:
-> 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." ] }
Un’altra trappola che abbiamo incontrato: una lista vuota nei dati non ha tipi di membri. Il nostro modello di contratto moltiplica item.Quantity * item.UnitPrice; con "items": [] e allowMissingMembers: true, la generazione falliva comunque con “Can not apply operator ‘’ to operands of type ‘System.Object’ and ‘System.Object’”*. La guardia ovvia, <<if [items.Any()]>> intorno alla tabella, non ha aiutato: il motore controlla ogni espressione prima di eseguirne una. Ciò che ha funzionato è stato tenere l’aritmetica fuori dalla riga. Con l’importo già nei dati (<<[item.Amount]>>), la stessa lista vuota e allowMissingMembers: true hanno prodotto il documento, e <<if [items.Count() == 0]>>No services ordered.<</if>> ha stampato la sua riga. Altrimenti, fai in modo che l’agente verifichi che una lista non sia vuota prima di generare, e chiedi a te come dovrebbe apparire un contratto vuoto.
Limiti onesti
- L’ispezione è statica: le proiezioni
SelecteGroupBynon sono seguite, e i modelli.msgnon possono essere letti. - I modelli sono input fidato; i tag immagine e documento caricano i percorsi e gli URL restituiti dalle loro espressioni.
- Modalità di valutazione: ogni output inizia con “Evaluation Only. Created with GroupDocs.Assembly 26.7…”.
- Date: passa
2026-11-12T00:00:00e formatta nel modello con:"d MMMM yyyy"; una stringa solo data è stata spostata di un giorno su una macchina UTC+2, e"12.11.2026"è stata interpretata come 11 dicembre.
FAQ
Come faccio a vedere quali campi richiede un modello Word?
Chiedi all’agente di chiamare get_template_fields su di esso. Ottieni i tag, i nomi dei dati e uno scheletro JSON, localmente, senza generare nulla.
Perché il mio modello stampa {{name}} invece del valore?
Perché i tag di GroupDocs.Assembly sono <<[name]>>. L’ispezione del server segnala i segnaposto {{…}} e indica cosa scrivere al loro posto.
Il Markdown può essere un modello?
Sì. Il nostro product-readme.md con i tag <<[product]>> e <<[description]>> è stato ispezionato come un file Word e generato direttamente in DOCX.
Approfondisci
- Documentazione, guida canonica: Come scoprire di cosa ha bisogno un modello e perché è fallito
- Hub della documentazione: GroupDocs.Assembly MCP Server
- Pagina prodotto GroupDocs.Assembly MCP — installazione con un click per VS Code e Cursor, configurazioni per tutti gli altri client
- Inizia qui: Lascia che il modello riempia i dati, non scriva il documento
- Correlato: Cento PDF personalizzati da un unico prompt: mail merge con un agente AI
- Correlato: Il grafico proviene dal modello, i numeri provengono dai dati
- Correlato: Il tuo repository ha già i dati; lascia che l’agente crei il PDF
- On-premise e modello di sicurezza: 3 architetture per l’elaborazione AI dei documenti, e quella che mantiene i file all’interno della tua rete
- Domande: Forum GroupDocs Assembly
- Fonte: GroupDocs.Assembly.Mcp su GitHub