یک عامل هوش مصنوعی باید قبل از رندر یک صفحه از یک سند سه سؤال بپرسد: چند صفحه دارد، هر صفحه چقدر بزرگ است و آیا به رمز عبور نیاز دارد یا نه. سرور GroupDocs.Viewer.Mcp اولین دو سؤال را با یک فراخوانی ارزان (get_view_info) که به‌صورت محلی روی ماشین شما اجرا می‌شود، پاسخ می‌دهد و سؤال مربوط به رمز عبور در پرامپت حل می‌شود. سپس عامل فقط صفحاتی را که مهم هستند رندر می‌کند:

سند contract.docx چه تعداد صفحه دارد و اندازه صفحه‌ها چیست؟

نسخه گام‌به‌گام همراه با پیکربندی و عیب‌یابی در مستندات موجود است: چگونه قبل از رندر کردن صفحات یک سند، تعداد صفحات آن را بررسی کنیم.

چرا ابتدا بررسی کنیم؟

هر صفحه‌ای که ابزار render_page تولید می‌کند به‌صورت PNG درون‌خطی به عامل باز می‌گردد و اغلب چند صد کیلوبایت حجم دارد. عاملی که برای یافتن یک جدول یک فایل ۶۰ صفحه‌ای رندر می‌کند، هزینه ۵۹ تصویر غیرضروری را از نظر زمان و پنجره زمینه می‌پردازد. ابزار بررسی، get_view_info، هیچ چیزی رندر نمی‌کند. این ابزار یک شیء JSON کوچک برمی‌گرداند، بنابراین تصمیم دربارهٔ رندر کردن بر پایهٔ واقعیت‌ها و نه حدس‌ها گرفته می‌شود.

این الگو در هر کلاینتی قابل استفاده است: Claude Desktop، Claude Code، Cursor، VS Code با GitHub Copilot یا Windsurf. این یک عادت است که در پرامپت می‌گذارید، نه ویژگی‌ای که پیکربندی می‌کنید.

سؤال ۱: چند صفحه وجود دارد؟

get_view_info مقدار pageCount را برمی‌گرداند. این تنها محافظ در برابر یک لبهٔ تیز مستند شده است: render_page شماره صفحه را نسبت به سند بررسی نمی‌کند. اگر صفحهٔ ۴۰ را از فایلی ۱۲ صفحه‌ای درخواست کنید، همچنان تصویری به نام <name>_page40.png دریافت می‌کنید که صفحه‌ای نیست که شماره ۴۰ داشته باشد.

یک پرامپتی که این محافظ را می‌سازد:

گزارش چند صفحه دارد؟ سپس آخرین صفحه را نشان بده.

برای صفحات گسترده شمارش حتی مهم‌تر است. موتور صفحه‌ها را از یک شیت تقسیم می‌کند و تعداد آن می‌تواند بسیار بیشتر از آنچه شیت نشان می‌دهد باشد. دانستن این عدد از ابتدا، عامل را از رندر کردن همهٔ آن‌ها جلوگیری می‌کند.

سؤال ۲: اندازه هر صفحه چقدر است؟

اندازهٔ صفحات این PDF چه است — Letter یا A4؟

پاسخ برای هر صفحه number، width و height را به‌واحد پوینت لیست می‌کند. ۶۱۲ در ۷۹۲ برابر با US Letter است؛ حدود ۵۹۵ در ۸۴۲ برابر با A4. سندی که یک صفحهٔ افقی در میان صفحات عمودی دارد، این صفحه را در لیست اندازه‌ها نشان می‌دهد و معمولاً همان جدول یا نقاشی‌ای است که کاربر به دنبال آن است.

دو فیلد دیگر، name و visible، در جایی که فرمت آن‌ها را دارد پر می‌شوند؛ برای مثال نام‌های ورک‌شیت‌ها و اسلایدها یا شیت‌های مخفی. در غیر این صورت مقدارشان null و true است.

سؤال ۳: آیا فایل به رمز عبور نیاز دارد؟

get_view_info فیلد حفاظتی ندارد، بنابراین نوع فایل و تعداد صفحات نمی‌توانند بگویند آیا به رمز عبور نیاز است یا نه. فایلی که با رمز عبور محافظت شده است، در هر فراخوانی به هر دو ابزار نیاز به رمز عبور دارد. این را در پرامپت از ابتدا بدهید:

رمز عبور contract.pdf در پیام من است. تعداد صفحات را بررسی کن، سپس صفحهٔ ۲ را نشان بده.

بدون رمز عبور فراخوانی شکست می‌خورد و عامل می‌تواند به‌جای حدس زدن از شما رمز عبور را بپرسد. اگر فراخوانی شکست بخورد، get_view_info متنی که با View-info lookup failed for شروع می‌شود به‌همراه نوع استثنا و پیام آن برمی‌گرداند، بنابراین عامل می‌تواند دلیل را بخواند و رمز عبور یا نام صحیح فایل را درخواست کند.

یک پرامپت قابل استفاده مجدد «بررسی‑سپس‑رندر»

قبل از رندر کردن هر چیزی از فایلی که در زیر نام‌گذاری شده، نوع فایل، تعداد صفحات و اندازهٔ صفحات را بررسی کن. آنچه پیدا کردی به من بگو، سپس فقط صفحاتی را که برای پاسخ به سؤال من لازم است رندر کن. فایل: contract.docx. سؤال: بند خاتمه کجا قرار دارد؟

عامل get_view_info را فراخوانی می‌کند، نوع فایل و تعداد صفحات را گزارش می‌دهد، صفحات مورد نیاز را انتخاب می‌کند و برای هر یک render_page را صدا می‌زند. ابزار get_license_status سومین ابزار روی سرور است؛ وقتی نیاز دارید بدانید آیا صفحات رندر شده واترمارک خواهند داشت یا نه، از آن استفاده کنید.

جلسهٔ نمونه

یک تصویر بر پایهٔ شکل پاسخ مستند شده، نه یک اسکرین‌شات واقعی.

You:   Inspect report.pdf before rendering anything.

Agent: [calls get_view_info on report.pdf]
       report.pdf: Portable Document Format File (.pdf), 2 pages.
       Page 1: 612 x 792 points (US Letter). Page 2: 612 x 792 points.
       Which page would you like me to render?

عامل چه تصمیمی می‌گیرد و موتور چه کاری انجام می‌دهد؟

گام عامل موتور
انتخاب فایل نام فایل را از پرامپت شما می‌گیرد آن را در پوشهٔ ذخیره‌سازی پیدا می‌کند، اگر نام مطابقت نداشته باشد فهرست فایل‌های موجود را نشان می‌دهد
بررسی تصمیم می‌گیرد کدام سؤال‌ها مهم هستند نوع فایل، تعداد صفحات و اندازهٔ صفحات را برمی‌گرداند
انتخاب صفحات سؤال شما را به شمارهٔ صفحات نگاشت می‌کند هیچ کاری انجام نمی‌دهد
رندر برای هر صفحهٔ انتخاب‌شده render_page را فراخوانی می‌کند PNG تولید می‌کند

محدودیت‌های صادقانه

  • حالت ارزیابی. صفحات رندر شده دارای واترمارک ارزیابی هستند و یک فرآیند سرور حداکثر ۱۵ سند را باز می‌کند. بپرسید «آیا سرور Viewer لایسنس دارد؟» تا عامل قبل از اعتماد به خروجی get_license_status را فراخوانی کند.
  • تعداد صفحات به‌جای انتخاب صفحات برای شما عمل نمی‌کند. get_view_info می‌گوید چه صفحاتی وجود دارند، نه کدام یک پاسخ را دارند. برای این کار، یک صفحهٔ فهرست یا چند گزینهٔ محتمل را رندر کنید.
  • فقط PNG. گزینهٔ فرمت روی render_page وجود ندارد.

پرسش‌های متداول

چگونه یک عامل هوش مصنوعی می‌تواند تعداد صفحات یک PDF را به‌دست آورد؟ اگر سرور Viewer متصل باشد، Claude می‌تواند get_view_info را فراخوانی کند و pageCount را بدون رندر کردن چیزی بخواند. پاسخ از خود سند می‌آید، نه از حدس.

آیا ابزار MCP اطلاعات سند می‌تواند به عامل بگوید کدام صفحات را رندر کند؟ بله. ابتدا تعداد صفحات و اندازه‌ها را بدهید، سپس بگویید به دنبال چه چیزی هستید. ابزار فقط صفحاتی را که به سؤال پاسخ می‌دهند رندر می‌کند.

آیا بررسی یک سند آن را در جایی آپلود می‌کند؟ نه. سرور فایل را از پوشه‌ای که پیکربندی کرده‌اید می‌خواند و یک شیء JSON کوچک به کلاینت شما برمی‌گرداند.

عمیق‌تر بروید