أحدهم يسلمك قالب 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 لا يُتبع. بالنسبة لعقد عادي، أو قالب رسالة أو فاتورة، تكون الهيكلية هي بالضبط ما يجب تعبئته.

تُغيّر الهيكلية أيضًا طريقة الحوار معك. بدلاً من «حاولت توليد الطلب وفشل»، يمكن للوكيل أن يقول «هذا القالب يحتاج إلى قائمة من السطور، كل سطر يحتوي على عنوان وكمية؛ وجدت ثلاثة في بريدك، إليك», ثم يُولّد فقط. الفحص رخيص، لا يحتاج إلى بيانات ولا يلمس شيئًا، لذا فهو النداء الأول الصحيح لأي قالب لم يره الوكيل من قبل، والنداء الصحيح مرة أخرى كلما قام أحدهم بتحرير القالب.

ثلاث حالات فشل، ثلاث حلول

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 ديسمبر.

الأسئلة المتكررة

كيف أرى ما الحقول التي يحتاجها قالب Word؟
اطلب من الوكيل استدعاء get_template_fields عليه. ستحصل على العلامات، وأسماء البيانات، وهيكلية JSON، محليًا، دون توليد أي شيء.

لماذا يطبع قلمي {{name}} بدلًا من القيمة؟
لأن علامات GroupDocs.Assembly هي <<[name]>>. يُشير فحص الخادم إلى علامات {{…}} ويخبرك بما يجب كتابته بدلاً منها.

هل يمكن أن يكون Markdown قالبًا؟
نعم. تم فحص ملف product-readme.md الذي يحتوي على علامات <<[product]>> و<<[description]>> كملف Word وتم توليده مباشرةً إلى DOCX.

تعمق أكثر