هر گفتگوی جدید با یک عامل آغاز می‌شود که اسناد شما را فراموش کرده است. می‌تواند آن‌ها را دوباره بخواند، که هزینهٔ زمان و زمینه را دارد، یا می‌تواند به چیزی که به‌خاطر می‌سپارد مراجعه کند. GroupDocs.Search.Mcp یک فهرست متنی کامل نام‌دار روی دیسک، به‌صورت محلی، نگه می‌دارد که بین جلسات و راه‌اندازی مجدد کانتینر باقی می‌ماند، بنابراین Claude Desktop، Cursor یا Copilot هر جلسه را با اسناد پروژه که از پیش جست‌پذیر هستند، آغاز می‌کنند و با یک فراخوانی هنگام تغییر فایل‌ها آن‌ها را به‌روز می‌کنند:

من برخی قراردادها را ویرایش کردم. فهرست قراردادها را به‌روز کن، سپس به من بگو کدام قراردادها اکنون جریمه‌ای را ذکر می‌کنند.

نسخهٔ گام‌به‌گام با پیکربندی و عیب‌یابی در مستندات موجود است: How to keep a document index current as files change.

معنی «حافظه» برای یک عامل چیست؟

در عمل دو چیز: وضعیتی که خارج از گفت‌وگو باقی می‌ماند، و روشی ارزان برای حفظ صحت آن وضعیت. تاریخچهٔ چت هر دو را انجام نمی‌دهد: با پایان جلسه تمام می‌شود و وقتی سندی تغییر می‌کند، هیچ‌چیزی آن را به‌روز نمی‌کند. یک فهرست جست‌وجو برای اسناد مناسب‌تر است. این فهرست کنار اسناد روی دیسک زندگی می‌کند، بدون بارگذاری آن‌ها پاسخ می‌دهد «کدام فایل‌ها X را می‌گویند» و می‌تواند به‌صورت افزایشی به‌روز شود.

session 1    add_to_index --> index "contracts" --+
                                                 |  kept on disk in
session 2    search, get_text_fragments <--------+  /data/.groupdocs-search-
             (nothing is re-read)                    index/contracts
files edit   update_index --> re-reads changed, added, deleted files only
new project  create_index {"indexName":"legal-2026"} --> a separate index

به‌روزرسانی چگونه کار می‌کند؟

update_index فهرست را با فایل‌های روی دیسک مقایسه می‌کند و فقط مواردی را که تغییر کرده‌اند دوباره می‌خواند. این چیزی است که سرور در آزمایش ما پس از افزودن یک بند جریمه به یک قرارداد بین دو فراخوانی برگرداند:

-> get_index_info {"indexName":"contracts"}
<- { "documentCount": 5, "indexedPaths": [ "contracts" ],
     "documentsWithErrors": [], "status": "Ready" }

-> update_index {"indexName":"contracts"}
<- Index 'contracts' updated: 0 added, 1 updated, 0 removed;
   5 document(s) in the index.

-> search {"query":"penalty","indexName":"contracts"}
<- documentsFound 3, including the edited initech-nda.docx

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

چرا یک فهرست برای هر پروژه؟

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

-> create_index {"indexName":"legal-2026"}
<- Index 'legal-2026' created. Add documents with add_to_index
   (indexName: 'legal-2026').

هر فهرست یک پوشه تحت /data/.groupdocs-search-index است و get_index_info بدون نام همهٔ آن‌ها را فهرست می‌کند. به‌طور معمول نیازی به create_index به‌صورت صریح ندارید، زیرا add_to_index در اولین استفاده یک فهرست ایجاد می‌کند، اما نام‌گذاری عمدی آن‌ها همان چیزی است که «یک فهرست» را به «حافظهٔ این پروژه» تبدیل می‌کند.

یک قاعده دربارهٔ حذف

موتور مسیرهایی را که اضافه شده‌اند حذف می‌کند، نه فایل‌های منفرد داخل آن‌ها. سرور این را به‌وضوح می‌گوید وقتی سعی می‌کنید:

-> remove_from_index {"documentPath":"contracts/hooli-supply-terms.txt",...}
<- Removal failed for 'contracts/hooli-supply-terms.txt':
   'contracts/hooli-supply-terms.txt' is inside the indexed folder
   'contracts'. GroupDocs.Search removes whole indexed paths only: ...

بنابراین برای آن طراحی کنید: اگر انتظار دارید بخشی از یک مجموعه را بعداً حذف کنید، مثلاً یک سال، یک مشتری یا پیش‌نویس‌ها، آن بخش‌ها را به‌عنوان مسیرهای جداگانه (contracts/2025, contracts/2026) فهرست کنید و هر کدام می‌توانند به‌صورت مستقل حذف شوند. حذف یک فایل روی دیسک و اجرای update_index نیز آن را حذف می‌کند.

نگه‌داشتن به‌روز بدون درخواست

create_index (optional)
      |
      v
add_to_index ---> search ---> get_text_fragments
      ^              ^
      |              |  get_index_info: counts, paths, status
update_index  (files changed on disk)
      |
remove_from_index  (only a path that was given to add_to_index)

سه روش عملی برای خودکار کردن به‌روزرسانی:

  1. در دستورالعمل‌های عامل. یک خط در CLAUDE.md یا AGENTS.md، «قبل از پاسخ‌گویی، اگر ممکن است فایل‌ها تغییر کرده باشند update_index را برای فهرست این پروژه فراخوانی کن»، باعث می‌شود عامل این کار را در ابتدای هر جلسه انجام دهد.
  2. برنامه‌ریزی‌شده. هر خودکاری که قابلیت MCP داشته باشد می‌تواند هر شب update_index را فراخوانی کند؛ وقتی تغییرات کم باشد، فراخوانی سریع است.
  3. پس از یک کپی انبوه. یک فراخوانی تمام فایل‌های اضافه‌شده را می‌گیرد.

فهرست‌ها همچنین پس از ارتقا باقی می‌مانند: فهرست‌های ساخته‌شده توسط GroupDocs.Search 22.7 تا 26.8 در اولین استفاده تبدیل می‌شوند و یک نسخهٔ پشتیبان در کنار آن‌ها نگه‌داری می‌شود.

آنچه عامل تصمیم می‌گیرد و آنچه فهرست انجام می‌دهد

عامل تصمیم می‌گیرد فهرست انجام می‌دهد
اینکه سؤال به کدام فهرست تعلق دارد هر فهرست نام‌دار را در پوشهٔ مخصوص خود نگه می‌دارد
زمانیکه ممکن است فایل‌ها تغییر کرده باشند فقط فایل‌های تغییر‑یافته، اضافه‑شده و حذف‑شده را دوباره می‌خواند
کدام کلمات برای جستجو و چه گونهٔ تغییرات را امتحان کند کلمات، عبارات، بازه‌ها را مطابقت می‌دهد؛ اصطلاحاتی که پیدا کرده گزارش می‌کند
مقدار زمینه‌ای که باید نقل قول شود بخش‌هایی را با تعداد واژگان درخواست‌شده در اطرافشان برمی‌گرداند
چه چیزی به شما بگوید هیچ‌چیز: تعدادها، مسیرها و متن را برمی‌گرداند، هرگز نتیجه‌گیری نمی‌کند

این جداسازی عمدی است. قضاوت با مدل می‌ماند و حقایقی که مدل بر پایهٔ آن استدلال می‌کند، از ابزاری می‌آید که خروجی آن را می‌توانید بررسی کنید.

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

  • در حالت ارزیابی یک فهرست حداکثر ۱۰۰ سند را نگه می‌دارد و یک جستجو حداکثر ۱۰ نتیجه برمی‌گرداند. قبل از اعتماد به فهرست به‌عنوان منبع حقیقت، get_license_status را فراخوانی کنید.
  • فهرست فقط در صورتی باقی می‌ماند که /data (یا حجم فهرست) یک پوشهٔ میزبان سوار شده باشد؛ در غیر این صورت با حذف کانتینر ناپدید می‌شود.
  • فهرست شامل متن اسناد است: همانند اسناد آن را محافظت و پس از استفاده از بین ببرید.
  • فقط Docker؛ در لینوکس --user "$(id -u):$(id -g)" اضافه کنید تا کانتینر بتواند فهرست را بنویسد.

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

آیا عامل بین جلسات اسناد من را به‌خاطر می‌سپارد؟
با یک فهرست پایدار، بله: فهرست روی دیسک می‌ماند و جلسهٔ بعدی بدون دوباره خواندن چیزی، در آن جستجو می‌کند.

آیا هنگام تغییر فایل‌ها باید فهرست را دوباره بسازم؟
نه. update_index فقط فایل‌های تغییر‑یافته، اضافه‑شده و حذف‑شده را دوباره می‌خواند.

آیا می‌توان فهرست را از اسناد فقط‑خواند جدا نگه داشتم؟
بله. اسناد را به‌صورت فقط‑خواند سوار کنید، یک پوشهٔ قابل نوشتن را در /index سوار کنید و GROUPDOCS_MCP_INDEX_PATH=/index را تنظیم کنید.

برای مطالعهٔ عمیق‌تر