Ai đó đưa cho bạn một mẫu Word và một thời hạn. Dữ liệu nào nó cần? Câu trả lời thường là mở nó, cuộn, đoán, chạy, đọc lỗi, và chạy lại. Với GroupDocs.Assembly.Mcp chạy cục bộ (dnx GroupDocs.Assembly.Mcp --yes), Claude Desktop, Cursor hoặc Copilot hỏi trực tiếp mẫu: get_template_fields trả về mọi thẻ, tên dữ liệu mà nó sử dụng và một khung JSON để điền, mà không chạy engine, và khi một lần chạy thất bại, lỗi sẽ cho biết cần thay đổi gì:

Mẫu order-lines.docx cần dữ liệu gì? Nếu nó không thể tạo ra, hãy cho tôi biết lý do và cách sửa mẫu.

Phiên bản từng bước với cấu hình và khắc phục sự cố có trong tài liệu: Cách tìm hiểu mẫu cần gì và tại sao nó thất bại.

Tại sao cần kiểm tra trước khi điền?

Bởi vì thử và sai là cách tốn kém để hiểu một schema. Một agent đoán tên trường từ văn bản hiển thị của tài liệu sẽ đoán CustomerName khi mẫu đọc customer.Name, và mỗi lần đoán sai tốn một vòng phản hồi và một lỗi gây nhầm lẫn. Mẫu không phải là văn xuôi; nó là một chương trình với hợp đồng dữ liệu, và hợp đồng này có thể được đọc.

Đó là tất cả những gì get_template_fields làm. Nó phân tích các thẻ <<…>>, xác định các tên, và xây dựng khung skeleton:

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

Ghi chú này trung thực về phương pháp: đây là kiểm tra tĩnh. Một trường được tạo bên trong một phép chiếu Select sẽ không được theo dõi. Đối với một hợp đồng bình thường, mẫu thư hoặc hoá đơn, khung skeleton chính là những gì cần điền.

Khung skeleton cũng thay đổi cách trò chuyện với bạn. Thay vì “Tôi đã cố gắng tạo đơn hàng nhưng thất bại”, agent có thể nói “mẫu này cần một danh sách các dòng, mỗi dòng có tiêu đề và số lượng; tôi đã tìm thấy ba dòng trong email của bạn, đây là chúng”, và chỉ sau đó mới tạo. Kiểm tra là rẻ, không cần dữ liệu và không chạm vào gì, vì vậy nó là lời gọi đầu tiên phù hợp cho bất kỳ mẫu nào mà agent chưa từng thấy, và lại là lời gọi phù hợp mỗi khi ai đó chỉnh sửa mẫu.

Ba lỗi, ba câu trả lời

vấn đề mẫu          điều server nói          cách sửa
------------------------  ----------------------------  -------------------
{{name}} placeholders     "2 placeholder(s) '{{...}}'.  viết <<[name]>>
                          ... không xử lý cú pháp
                          đó"
<<foreach>> chưa đóng  "Kết thúc bất ngờ của mẫu.  thêm <</foreach>>
                          Một thẻ khối chưa được đóng"
dữ liệu thiếu một trường        "Mẫu đọc 'Email',  thêm nó, hoặc dữ liệu không có trường này" allowMissingMembers

Cú pháp sai. Nhiều mẫu trong thực tế được viết cho các engine khác và sử dụng {{name}}. GroupDocs.Assembly để lại chúng dưới dạng văn bản, và việc kiểm tra cho biết điều đó trước khi ai đó lãng phí một lần chạy:

-> get_template_fields {"template":{"filePath":"shipping-notice.docx"}}
<- { "tagCount": 0, "notes": [ "Không tìm thấy thẻ <<…>> nào: ...",
     "Mẫu chứa 2 placeholder(s) '{{…}}'. GroupDocs.Assembly
      không xử lý cú pháp đó và để lại dưới dạng văn bản; viết
      <<[name]>> thay thế." ] }

Khối chưa đóng. order-lines.docx của chúng tôi mở một <<foreach>> và không bao giờ đóng nó. Việc kiểm tra liệt kê các thẻ một cách vui vẻ; việc tạo ra không như vậy:

-> assemble_document {"template":{"filePath":"order-lines.docx"},
     "dataJson":"{\"lines\":[{\"Title\":\"Cable\",\"Quantity\":2}]}"}
<- Lắp ráp tài liệu thất bại cho 'order-lines.docx': ...
   Kết thúc bất ngờ của mẫu. Một thẻ khối chưa được đóng: mọi
   <<foreach>> cần <</foreach>> và mọi <<if>> cần <</if>>.

Trường thiếu. Khi dữ liệu thiếu một thứ mà mẫu đọc, lỗi sẽ chỉ ra trường, nói rằng tên là phân biệt chữ hoa/thường và đề xuất tùy chọn: allowMissingMembers: true sẽ không xuất gì cho các thành viên thiếu và trả về danh sách rỗng thay vì thất bại.

Khi mẫu đầy lỗi

Một số mẫu có nhiều lỗi, và việc sửa chúng từng lần chạy thất bại một là chậm. inlineErrors: true biến mẫu thành báo cáo lỗi riêng: tài liệu được tạo và mỗi thẻ lỗi sẽ có thông điệp của nó được viết bên cạnh. Trên mẫu ví dụ từ GroupDocs.Assembly:

-> assemble_document {"template":{"filePath":"inline-error.docx"},
     "dataJson":"{\"name\":\"x\"}","inlineErrors":true}
<- Đã lắp ráp 'inline-error.docx' ... Mẫu có lỗi: mỗi lỗi
   được viết vào đầu ra bên cạnh thẻ của nó, bắt đầu bằng 'Error!'

Đầu ra chứa << var [name] Error! An assignment operator is expected. >>, tại vị trí trong tài liệu nơi thẻ nằm. Mở tệp, sửa mọi thẻ được đánh dấu, chạy lại mà không có cờ.

Những gì kiểm tra không thể thấy

Các mẫu Outlook nhị phân là ngoại lệ. Các thẻ của tệp .msg không thể đọc được nếu không tạo ra nó, và server thông báo điều đó thay vì trả về danh sách rỗng trông giống như “không có trường”:

-> get_template_fields {"template":{"filePath":"contracts-table.msg"}}
<- { "readable": false, "notes": [ "Không thể đọc thẻ từ mẫu .msg nếu không tạo ra nó. Lưu mẫu dưới dạng DOCX, XLSX,
     PPTX hoặc EML để kiểm tra, hoặc tạo nó bằng assemble_document
     và inlineErrors=true để xem trường nào thất bại." ] }

Một bẫy nữa chúng tôi gặp: danh sách trống trong dữ liệu không có kiểu thành viên. Mẫu hợp đồng của chúng tôi nhân item.Quantity * item.UnitPrice; với "items": [] và allowMissingMembers: true, việc tạo vẫn thất bại với “Không thể áp dụng toán tử ‘’ cho các toán hạng kiểu ‘System.Object’ và ‘System.Object’”*. Yêu cầu agent kiểm tra danh sách không rỗng trước khi tạo, và hỏi bạn mẫu hợp đồng trống nên như thế nào.

Giới hạn trung thực

  • Kiểm tra là tĩnh: các phép chiếu Select và GroupBy không được theo dõi, và các mẫu .msg không thể đọc được.
  • Mẫu là đầu vào đáng tin cậy; các thẻ hình ảnh và tài liệu tải các đường dẫn và URL mà biểu thức của chúng trả về.
  • Chế độ đánh giá: mọi đầu ra bắt đầu bằng “Evaluation Only. Created with GroupDocs.Assembly 26.7…”.
  • Ngày: truyền 2026-11-12T00:00:00 và định dạng trong mẫu bằng :"d MMMM yyyy"; một chuỗi chỉ ngày đã bị dịch một ngày trên máy UTC+2, và "12.11.2026" được đọc là 11 tháng 12.

Câu hỏi thường gặp

Làm sao để tôi biết một mẫu Word cần những trường nào?
Yêu cầu agent gọi get_template_fields trên mẫu. Bạn sẽ nhận được các thẻ, tên dữ liệu và một khung JSON, cục bộ, mà không cần tạo bất kỳ thứ gì.

Tại sao mẫu của tôi in {{name}} thay vì giá trị?
Bởi vì các thẻ của GroupDocs.Assembly là <<[name]>>. Việc kiểm tra của server đánh dấu các placeholder {{…}} và nói nên viết gì thay thế.

Markdown có thể là một mẫu không?
Có. product-readme.md của chúng tôi với các thẻ <<[product]>> và <<[description]>> đã được kiểm tra như một tệp Word và tạo trực tiếp thành DOCX.

Đi sâu hơn