عیب‌یابی یک عامل
این راهنما نشان می‌دهد چگونه بفهمید چرا یک عامل دیگر اجرا تولید نمی‌کند.
از بالا به پایین کار کنید: نخست اجراهای خود عامل، سپس بک‌اند آن، بعد سرور و در آخر میزبان.
۱. تاریخچهٔ اجرای عامل را بررسی کنید
بخش با عنوان “۱. تاریخچهٔ اجرای عامل را بررسی کنید”تنظیمات → فضای کاری → عامل‌ها → عامل را انتخاب کنید → گزارش‌ها.
هر اجرا یک نشان وضعیت، یک مدت‌زمان (در حین اجرا «در حال اجرا…»)، زمان شروع و پایانش، PID و آداپتوری که به کار برده نشان می‌دهد. نمایش جریان رویداد خام آن اجرا را باز می‌کند. توقف یک فرایند در حال اجرا را می‌کشد و اجرا را «Killed by user» علامت می‌زند؛ کشتن در حال اجرا در سربرگ همین کار را برای همهٔ اجراهای در جریان آن عامل انجام می‌دهد.
آن را این‌گونه بخوانید:
- هیچ اجرایی نیست — اعزام هرگز رخ نداده است. منشن‌ها در کادر پیام ترکیبی از
@و نویسه‌های واژه‌ای (حروف، رقم، زیرخط) هستند. تطبیق، مطابق دقیق یا پیشوندی روی نام عامل است، پس@code-reviewerبه‌صورتcodeتجزیه می‌شود و همچنان می‌تواند عاملی به نامcode-reviewerرا بیدار کند. نامی که فاصله دارد را نمی‌توان به‌صورت یک توکن منشن کرد. سپس به گام ۲ بروید. - اجرایی که فوراً با خطا پایان یافته — نمایش را باز کنید. ناکامی در راه‌اندازی بک‌اند اینجا به‌صورت یک خطای فرایند نمایان می‌شود.
- اجرایی که در «در حال اجرا…» گیر کرده — متوقفش کنید، سپس مهلت سکوت عامل را در زبانهٔ تنظیمات بررسی کنید. مهلتی که تنظیم نشده باشد از پیش‌فرض هر حالت استفاده می‌کند.
- اجرای کامل‌شده‌ای بدون خروجی مفید — وضعیت در گزارش اجرا برای اجرایی که بدون تحویل‌دادنی اعلام‌شده‌اش پایان یافته، همچنان
completedمی‌ماند؛ نشانهٔ قابل اعتماد متن خلاصه است، نه نشان وضعیت.
زبانهٔ گزارش‌ها هیچ هزینه‌ای نشان نمی‌دهد. برای هزینه‌کرد، از جدول هر عامل در مشاهده‌پذیری → بینش‌ها استفاده کنید.
۲. بک‌اند عامل را بررسی کنید
بخش با عنوان “۲. بک‌اند عامل را بررسی کنید”تنظیمات → سرور → ارائه‌دهندگان مدل (/settings/server/providers).
فهرست اجراکننده‌های تشخیص‌داده‌شده هر آداپتور را همراه با نتیجهٔ کاوش آن نشان می‌دهد — نسخهٔ نصب‌شده، «در حال بررسی…» یا «یافت نشد» — به‌همراه مسیر حل‌شده و برچسب‌های قابلیت برای CLI یافته‌شده. برای کاوش دوباره، در سربرگ صفحه روی تازه‌سازی کلیک کنید.
کاوش روی ماشینی اجرا می‌شود که cc_server را میزبانی می‌کند، نه روی ماشینی که اکنون به آن نگاه می‌کنید. اگر با کلاینت وب یا دستگاهی جفت‌شده کار می‌کنید، «یافت نشد» یعنی CLI روی میزبان سرور وجود ندارد.
دو چیز را تأیید کنید:
- عامل اصلاً آداپتور تنظیم‌شده دارد. عاملی با آداپتور خالی به Control Center (built-in) اعزام می‌شود و گزارش اجرا
cc-harnessرا ثبت می‌کند، پس رونوشت نام چیزی را که اجرا شده مشخص می‌کند. اگر مدل هم نداشته باشد، پیش‌فرض خود را از Anthropic می‌پرسد — که باNo credential for provider "anthropic"شکست می‌خورد، مگر اینکه حساب Anthropic متصل کرده باشید. عامل‌های متخصص اولیه بدون آداپتور عرضه می‌شوند. - آداپتور داخلی مدل دارد. فهرست مدل‌های آن به‌صورت زنده از ارائه‌دهنده‌هایی می‌آید که پایین‌تر در همین صفحه متصل شده‌اند، پس ارائه‌دهنده‌ای که اعتبارنامهٔ ذخیره‌شده ندارد صفر مدل اضافه می‌کند.
خودِ فهرست آداپتورها ثابت است — هیچ راهی برای ثبت آداپتور جدید وجود ندارد. چیزی که می‌توانید برای هر آداپتور اینجا تغییر دهید، آرگومان‌های راه‌اندازی و متغیرهای محیطی آن است. توجه کنید که بازنویسی محیطی هر آداپتور، هنگام حل اعتبارنامه‌ها بی‌صدا از حساب ارائه‌دهندهٔ متصل پیشی می‌گیرد.
۳. سرور را بررسی کنید
بخش با عنوان “۳. سرور را بررسی کنید”تنظیمات → سرور → اتصال و وضعیت (/settings/server/connection) نشان می‌دهد این کلاینت با کدام سرور صحبت می‌کند و آن سرور چه چیزی گزارش می‌دهد.
برای سرور بدون رابط، GET /healthz همان اطلاعات را بدون کلاینت می‌دهد. طبق طراحی احراز هویت نمی‌خواهد و برای CORS باز است:
curl http://localhost:9030/healthzاین درخواست وضعیت سرور، مدت فعالیت برحسب ثانیه، تعداد اتصال‌های زنده، پورت مقیدشده، نسخهٔ ساخت و git SHA، نسخهٔ شمای فضای کاری، نسخهٔ کاتالوگ RPC، شناسه، نام و اثر انگشت هویت سرور، اینکه bind ناامن است یا نه، و یک بلوک codeGraph با شمارنده‌های watching / indexing / pending را برمی‌گرداند. وقتی کشی ترافیک دیده باشد، بلوک caches را هم شامل می‌شود؛ یک سرور دمو demo: true را اضافه می‌کند.
دو نکته که وقتی تغییری «در تست‌ها کار می‌کند ولی در برنامه نه» ارزش دانستن دارند:
- دسکتاپ یک باینری از پیش ساخته‌شدهٔ
cc_serverرا در اولویت نسبت به سورس اجرا می‌کند. یک عملیات RPC یا ابزار MCP جدید تا زمانی که باینری دوباره ساخته نشود پدیدار نمی‌شود و اگر git SHA فرزند با git SHA برنامه تفاوت داشته باشد، هنگام راه‌اندازی هشدار ثبت می‌شود. - دسکتاپ سروری را که در ۲۰ ثانیه بنر آمادگی‌اش را چاپ نکرده باشد می‌کشد و به صفحهٔ خطا می‌افتد.
۴. میزبان را بررسی کنید
بخش با عنوان “۴. میزبان را بررسی کنید”تنظیمات → سرور → تشخیص و حریم خصوصی (/settings/server/diagnostics) صفحهٔ سطح میزبان است. این موارد را در خود دارد:
- سندباکس — کلید اصلی، بک‌اند تشخیص‌داده‌شده و یک راهنمای نصب. فقط بک‌اند تشخیص‌داده‌شده از سرور می‌آید؛ هشدار پایین را ببینید. هیچ کنترل بازنشانی‌ای وجود ندارد.
- جستجوی معنایی — چرخهٔ عمر مدل جاسازی روی دستگاه: نصب‌شده، در حال بارگیری با درصد، نصب‌نشده، یا خطای نصب. تا وقتی نصب نشده باشد، حافظه و جستجوی کد فقط کلیدواژه‌ای می‌مانند.
- رفتار سیستم — هنگام اجرای عامل‌ها رایانه را بیدار نگه دارید.
- سطح گزارش — پیش از بازتولید یک خطا آن را بالا ببرید.
- حریم خصوصی — اینکه محتوای خام diff ممکن است به مدل عامل فرستاده شود یا نه و اینکه گزارش‌های خرابی ارسال می‌شوند یا نه.
خرابی‌های رایج
بخش با عنوان “خرابی‌های رایج”اجرا هرگز شروع نمی‌شود و آداپتور «یافت نشد» نشان می‌دهد
بخش با عنوان “اجرا هرگز شروع نمی‌شود و آداپتور «یافت نشد» نشان می‌دهد”CLI را روی میزبان سرور نصب کنید، سپس در صفحهٔ ارائه‌دهندگان مدل روی تازه‌سازی کلیک کنید. یا عامل را به آداپتور داخلی تغییر دهید که به CLI نیازی ندارد و در همان صفحه یک ارائه‌دهنده وصل کنید.
عامل نمی‌تواند push کند یا pull request باز کند
بخش با عنوان “عامل نمی‌تواند push کند یا pull request باز کند”ببینید git یا عامل چه چاپ کرده است. Control Center policy: … یعنی یک قاعدهٔ کنش آن را رد کرده یا یک تأیید بی‌پاسخ مانده است: پوش به یک ریموت و باز کردن یک pull request را در تنظیمات → فضای کاری → مجوزهای عامل بررسی کنید. اگر git بگوید Control Center هیچ اعتبارنامهٔ GitHubی ندارد که بتواند پوش کند، GitHub App را روی آن مخزن نصب کنید، یا GitHub را متصل کنید.
جستجوی معنایی چیز مفیدی برنمی‌گرداند
بخش با عنوان “جستجوی معنایی چیز مفیدی برنمی‌گرداند”تنظیمات → سرور → تشخیص و حریم خصوصی → جستجوی معنایی را بررسی کنید. تا وقتی مدل جاسازی نصب نشده باشد، جستجو فقط کلیدواژه‌ای است. سطرهایی که پیش از نصب مدل نوشته شده‌اند هرگز بعداً پر نمی‌شوند، پس حتی پس از نصب هم فقط کلیدواژه‌ای می‌مانند.
سرور اصلاً بالا نمی‌آید
بخش با عنوان “سرور اصلاً بالا نمی‌آید”کتابخانه‌های بومی الزامی‌اند و هیچ حالت تنزل‌یافته‌ای وجود ندارد. نبودن یک dylib باعث می‌شود cc_server از شروع امتناع کند و مقصر را در خطا نام ببرد. کتابخانه‌های بومی را با scripts/natives/build_natives.sh آماده کنید و باینری سرور را دوباره بسازید.
یک کنش بی‌صدا رد می‌شود
بخش با عنوان “یک کنش بی‌صدا رد می‌شود”تصمیم گاردریل prompt بدون اتصال هیچ تأییدکننده‌ای، طبق طراحی رد می‌شود. قواعد فضای کاری را زیر تنظیمات → فضای کاری → مجوزهای عامل بررسی کنید.