معرفی «دستیار توسعه‌دهنده Google Ads API» نسخه ۳.۰.۰

چهارشنبه، ۱۰ ژوئن ۲۰۲۶

با خوشحالی انتشار نسخه ۳.۰.۰ از دستیار توسعه‌دهنده Google Ads API را اعلام می‌کنیم. این نسخه اصلی نقطه عطف مهمی در تکامل «دستیار» است که بر مدرن‌سازی معماری، بهبود قابلیت اطمینان، و طراحی مدولارتر تمرکز دارد.

با این نسخه، «دستیار» را به چارچوب عامل Google Antigravity منتقل می‌کنیم و به معماری مبتنی بر مهارت تغییر می‌دهیم. این تغییرات باعث می‌شود «دستیار» قوی‌تر شود، نگهداری آن آسان‌تر شود، و استفاده از کد کاهش یابد.

چه چیزهایی در نسخه ۳.۰.۰ جدید است؟

۱. با پشتیبانی چارچوب Antigravity

«دستیار توسعه‌دهنده Google Ads API» از gemini-cli به چارچوب عامل Antigravity (نسخه ۳.۰.۰) منتقل شده است. این ارتقای چارچوب زیربنایی، محیط اجرایی ساختاریافته‌تر و قابل‌اعتمادتری را فراهم می‌کند. همراه با این، ساختار دایرکتوری و فایل پروژه به‌روز شده است تا کاملاً برای Antigravity آماده باشد.

پشتیبانی از gemini-cli در ۱۸ ژوئن ۲۰۲۶ به‌پایان می‌رسد، همان‌طور که در این اعلامیه وبلاگ Google به‌تفصیل شرح داده شده است.

۲. معماری ماژولار مبتنی بر مهارت

قابلیت‌های اصلی «دستیار» را به مهارت‌ها منتقل کرده‌ایم. به‌جای تکیه بر دستورالعمل‌های گسترده و بدون ساختار در فایل بافت، «دستیار» اکنون دایرکتوری‌های ابزار تخصصی و آزمایش‌شده (مهارت‌ها) را به‌صورت پویا درصورت نیاز بار می‌کند. این کار «توهمات» را به‌شدت کاهش می‌دهد و تضمین می‌کند که تکالیف بااستفاده از رویه‌های دقیق و درستی‌سنجی‌شده اجرا می‌شوند.

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

  • اعتبارسنجی GAQL‏ (validate_gaql): به مهارت اختصاصی منتقل شد. اکنون شامل بررسی‌های بهبودیافته پُرسمان ایستا برای بخش‌های تاریخ، فیلترهای تک‌روزه click_view، و مرزهای change_status است.
  • عیب‌یابی تبدیل‌ها (troubleshoot_conversions): جایگزین conversions_support_package قدیمی می‌شود. این گواهینامه همه اسکریپت‌های خلاصه بارگذاری و عیب‌یابی تبدیل و آزمون‌ها را در یک فهرست مهارت منسجم و واحد ادغام می‌کند.
  • فرمان‌های ساختاریافته (explain و step_by_step): به مهارت‌هایی تبدیل شده‌اند تا طرح‌بندی‌های ساختاریافته و ثابتی را برای توضیحات اعمال کنند.
  • نگاشت حساب جدید (get_cids_under_mcc): مهارتی جدید برای بازیابی همه حساب‌های فرزند تحت «حساب مدیر» (MCC).
  • بازرسی شیء جدید (inspect_object): مهارتی جدید برای جستجوی پویا و سریع پیام‌های Protobuf و Enums، برای کمک به اطمینان از اینکه «دستیار» همیشه از ساختارهای صحیح استفاده می‌کند.
  • فیلتر فهرستگان جدید PMax‏ (pmax_listing_filter): مهارتی جدید برای استانداردسازی اصلاحات درخت استثنای صفحه وب گروه فهرستگان برای پویش‌های «بیشینه‌سازی عملکرد».

۳. ثبات و دقت بهبودیافته

قوانین و الزامات سخت‌گیرانه‌تری را برای کمک به اطمینان از تولید کد با کیفیت بالا و اعتبارسنجی پُرسمان معرفی کرده‌ایم:

  • نسخه‌بندی صریح API: مهارت‌های حیاتی مانند get_cids_under_mcc، validate_gaql، و troubleshoot_conversions اکنون به یک آرگومان صریح api_version نیاز دارند که ابهام را ازبین می‌برد.
  • قوانین سخت‌گیرانه GAQL:
    • قاعده‌ای به AGENTS.md اضافه شد تا از استفاده از توابع تجمیعی SQL (مانند SUM، COUNT، و AVG) در پُرسمان‌های GAQL جلوگیری شود، زیرا این توابع پشتیبانی نمی‌شوند.
    • قاعده‌ای اضافه شد تا ابتدا یادداشت‌های انتشار سایت توسعه‌دهنده Google Ads API را برای نسخه فعلی API بررسی کند تا مطمئن شود «دستیار» از اسناد به‌روز استفاده می‌کند.
    • پیکربندی ساده‌شده: AGENTS.md ساده شده است که منجر به پنجره زمینه اولیه کوچک‌تر می‌شود. اسناد تبدیل تکراری به‌نفع مهارت‌های برنامه‌نویسی برداشته شده است.

۴. بهبودهای «تجربه توسعه‌دهنده» (DX)

چندین بهبود در کیفیت زندگی ایجاد کرده‌ایم تا چرخه توسعه شما سریع‌تر و روان‌تر شود:

  • محیط مجازی پایدار (.venv): محیط مجازی دیگر در پایان جلسه حذف نمی‌شود. در زمان راه‌اندازی، «دستیار» نسخه Python سیستم شما را بررسی می‌کند؛ فقط درصورتی .venv را بازسازی می‌کند که نسخه جدیدتری از Python دردسترس باشد.
  • ذخیره هوشمند نسخه میانای برنامه‌سازی کاربردی در حافظه نهان: «دستیار» اکنون نسخه فعلی Google Ads API را با TTL (زمان بقا) ۱۹ ساعت در حافظه نهان ذخیره می‌کند و با اجتناب از بررسی‌های زائد شبکه، زمان راه‌اندازی را کاهش می‌دهد.
  • اشکال‌زدایی بهتر با گزارش‌های دائمی: پیام‌های گزارش اکنون شامل مُهر تاریخ و زمان هستند. فایل گزارش در دایرکتوری .agents/ نوشته می‌شود و دیگر در هر اجرا بازنشانی نمی‌شود، و سابقه را برای عیب‌یابی حفظ می‌کند.

چرا باید ارتقا دهید؟

ارتقا به نسخه ۳.۰.۰ عمدتاً درباره قابلیت اطمینان و ساختار است. با انتقال به چارچوب Antigravity و تبدیل ویژگی‌ها به «مهارت‌های» واحدی، «دستیار» را قابل‌پیش‌بینی‌تر و ازنظر منابع کارآمدتر کرده‌ایم.

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

شروع‌به‌کار

اولین نصب

  1. نصب Antigravity CLI: دستورالعمل‌های موجود در https://antigravity.google/ را دنبال کنید.
  2. کلون کردن «دستیار»: 
    git clone https://github.com/googleads/google-ads-api-developer-assistant.git
  3. دستورگان نصب را اجرا کنید:
    • Linux/macOS: ./install.sh را اجرا کنید (به‌طور پیش‌فرض از Python پشتیبانی می‌کند، برای زبان‌های دیگر از پرچم‌هایی مثل --php یا --ruby استفاده کنید).
    • Windows: PowerShell را باز کنید و .\install.ps1 را اجرا کنید.

ارتقا از نسخه ۲.x

  1. هرگونه کد یا داده سفارشی را از saved/ در مکانی امن خارج از دایرکتوری پروژه کپی کنید.
  2. کلون محلی «دستیار» را حذف کنید.
  3. همسانه‌سازی کردن مخزن:
git clone https://github.com/googleads/google-ads-api-developer-assistant.git
  1. دستورگان نصب (install.sh یا install.ps1) را اجرا کنید تا محیط جدید Antigravity راه‌اندازی شود.

Bob Hancock، تیم Google Ads API

برچسب‌ها: google-ads-api، release