有人交給你一個 Word 範本和一個截止日期。它需要什麼資料?通常的做法是打開它、滾動、猜測、執行、閱讀錯誤,然後再執行一次。使用本機執行的 GroupDocs.Assembly.Mcp(dnx GroupDocs.Assembly.Mcp --yes),Claude Desktop、Cursor 或 Copilot 直接詢問範本:get_template_fields 會回傳每個標籤、它使用的資料名稱以及要填寫的 JSON 骨架,無需執行引擎,而當執行失敗時,錯誤會說明需要更改什麼:

order-lines.docx 需要什麼資料?如果無法產生,請告訴我原因以及如何修正範本。

包含設定與故障排除的逐步說明請參考文件:如何找出範本需要什麼以及為何失敗。

為什麼在填寫之前先檢查?

因為反覆試驗是學習結構的高成本方式。若代理程式從文件的可見文字猜測欄位名稱,當範本寫成 customer.Name 時,它可能會猜測成 CustomerName,每一次錯誤的猜測都會產生一次往返並導致混亂的錯誤。範本不是散文;它是一個帶有資料合約的程式,而合約是可以被讀取的。

這就是 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 投影內產生的欄位不會被追蹤。對於一般的合約、信件或發票範本,骨架正好就是要填寫的內容。

骨架也會改變與你的對話。代理程式不再說「我嘗試產生訂單卻失敗了」,而是說「此範本需要一個包含多筆資料的清單,每筆資料都有標題與數量;我在你的電子郵件中找到三筆,這裡是它們」,然後才進行產生。檢查成本低、無需資料且不會改動任何內容,因此對於代理程式未見過的任何範本都是正確的第一步,同時在有人編輯範本之後再次執行也是正確的做法。

三種失敗,三種解答

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

錯誤的語法。 許多實際使用的範本是為其他引擎編寫的,使用 {{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 月 12 日。

常見問題

我如何查看 Word 範本需要哪些欄位?
請讓代理程式對其呼叫 get_template_fields。您會取得標籤、資料名稱以及 JSON 骨架,全部在本機完成,且不會產生任何文件。

為什麼我的範本會印出 {{name}} 而不是值?
因為 GroupDocs.Assembly 的標籤是 <<[name]>>。伺服器的檢查會標示 {{…}} 佔位符,並說明應改寫為何。

Markdown 可以作為範本嗎?
可以。我們的 product-readme.md 內含 <<[product]>> 與 <<[description]>> 標籤,已像 Word 檔案一樣被檢查,並直接產生成 DOCX。

深入了解