تنظیم بافت ابزار یک عامل

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

ببینید یک اجرا واقعاً چه می‌فرستد

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

دو بخش اینجا اهمیت دارند:

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

اگر بخش به‌تعویق‌افتاده خالی است، تعویق برای این سرور خاموش است. --tool-deferral را در CLI مربوط به cc_server بررسی کنید.

تغییر اینکه کدام ابزارها از ابتدا بارگذاری می‌شوند

مجموعهٔ ساکن سیاست است، نه پیکربندی — در ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) زندگی می‌کند و به هر اجرا اعمال می‌شود:

• residentBuiltins — واژگان فایل و شل.
• residentDiscovery — search_tools و list_my_tools. این‌ها را حذف نکنید؛ آن‌ها راه رسیدن عامل به هر چیز دیگری هستند.
• residentMcpTools — همان اندک ابزارهای Control Center که ارزش اسکیمای‌شان را در هر درخواست دارند.
• یک بلوک به‌ازای هر حالت، برای ابزارهایی که یک حالت مشخص تقریباً در هر نوبت به کار می‌برد.

دو قاعده هنگام ویرایش آن:

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

نام واقعی ابزار را به کار ببرید. نام ساکنی که با هیچ ابزاری مطابقت ندارد بی‌اثر است: نه خطایی، نه هشداری؛ ابزار به‌سادگی به تعویق می‌افتد. test/tooling/resident_tool_names_test.dart این را می‌گیرد و همچنین هر حالت را زیر 40 ابزار ساکن نگه می‌دارد، که همین هدف این کار است — فراتر از آن باند، دقت انتخاب ابزار به‌طور قابل‌سنجش بدتر می‌شود.

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

عیب‌یابی یک انتخاب نامناسب ابزار

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

1. آیا نگاه کرد؟

هر اجرا ابزارهای به‌تعویق‌افتاده‌ای را که بارگذاری کرده، و اینکه چه چیزی آن را برانگیخته ثبت می‌کند — یک فراخوانی مستقیم با نام، یا یک جست‌وجوی search_tools. جریان رویدادهای اجرا را باز کنید (تنظیمات → فضای کاری → عامل‌ها → عامل → گزارش‌ها → نمایش) و به دنبال [harness] loaded N deferred tool(s) بگردید.

• چیزی ثبت نشده، و عامل گفته که آن قابلیت وجود ندارد — هرگز نگاه نکرده است. این یک مشکل پرامپت است، نه مشکل بازیابی: نمایهٔ به‌تعویق‌افتاده در پرامپت سیستمی آن است، همراه با دستوری که می‌گوید تا وقتی جست‌وجو خالی برنگردد، قابلیت را غایب اعلام نکن.
• یک جست‌وجو ثبت شده، ولی چیزی بارگذاری نشده — یک خطای بازیابی واقعی. به گام 2 بروید.
• ابزارها بارگذاری شده‌اند، ولی ابزار اشتباه به کار رفته — ابزارهایی که پیدا کرده بیش از حد به هم شبیه‌اند. به گام 3 بروید.

2. رفع یک خطای بازیابی

search_tools بر پایهٔ نام‌ها، توصیف‌ها و نام آرگومان‌ها تطبیق می‌دهد. یک خطای بازیابی تقریباً همیشه یعنی توصیف شامل واژه‌هایی که عامل به کار برده نیست.

آن‌ها را اضافه کنید. توصیف‌ها همان نمایهٔ بازیابی‌اند، پس آن‌ها را بلندتر کنید، نه کوتاه‌تر — واژگانی را بنویسید که یک اپراتور واقعاً تایپ می‌کند (“assign”، “hand off”، “give to”)، نه فقط اسم داخلی را. کوتاه کردن یک توصیف برای صرفه‌جویی در توکن، هم اصابت جست‌وجو را از شما می‌گیرد و هم دقت انتخاب را، و در مقابل اسکیما تقریباً چیزی ذخیره نمی‌کند.

اگر ابزار درست وجود دارد ولی رتبه‌اش پایین است، آرگومان limit برای همین است؛ توصیف خودِ ابزار به عامل می‌گوید جست‌وجویی را که نزدیک به نظر می‌رسد ولی نتیجه نمی‌دهد گسترده‌تر کند.

3. رفع ابزارهای هم‌شکل

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

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

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

بررسی اینکه کش پرامپت کار می‌کند

نرخ اصابت کش در مشاهده‌پذیری → بینش‌ها زیر عنوان نرخ کش دیده می‌شود. یک گفتگوی طولانی و سالم بالا می‌نشیند؛ اگر پیوسته پایین باشد، چیزی هر نوبت پیشوند را بازنویسی می‌کند.

دلایل رایج، به ترتیب احتمال:

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

خاموش کردن تعویق با --tool-deferral=off یک آزمون A/B معتبر برای جدا کردن این است که آیا تغییر رفتار از سطح دوسطحی آمده است. این کار دقیقاً همان درخواست پیش از تعویق را بازتولید می‌کند، پس اگر رفتار با خاموش بودن آن هم ادامه داشت، سطح مقصر نیست.