۱. مقدمه
کدنویسی Vibe - استفاده از عاملهای هوش مصنوعی برای نوشتن کد از زبان طبیعی - نقش توسعهدهنده را از نویسنده به هماهنگکننده و بررسیکننده تغییر میدهد. ما به آمادهسازی زمینه بینقص تکیه میکنیم و به عاملهای هوش مصنوعی اعتماد میکنیم تا همه کارها را برای ما انجام دهند، ممکن است از تهیه اسناد مشخصات شروع شود تا اطمینان حاصل شود که کد تمام الزامات را برآورده میکند. خطر: در چرخههای تکرار سریع، کد عملکردی بدون بررسی کامل امنیتی تأیید میشود. عاملهای مدرن اغلب به طور پیشفرض کد امن تولید میکنند، اما "اغلب" همیشه "نیست" و آسیبپذیریهای انباشته شده از بررسی دستی عبور میکنند.
این آزمایشگاه کد با آموزش دو رویکرد برای استفاده از Antigravity به عنوان بررسیکننده، به این مسائل میپردازد: به صورت تعاملی در طول توسعه با CLI (شما بررسی میکنید، اصلاح میکنید، سپس PR میکنید) و به صورت خودکار در ادغام مداوم با SDK (عامل هر درخواست Pull را بررسی میکند و نتایج را به عنوان نظر ارسال میکند)
آنچه بررسی خواهید کرد
شما یک برنامه مدیریت ارتباط با مشتری (CRM) برای سرنخها را با استفاده از ویبره کدنویسی کردهاید - یک عامل هوش مصنوعی تمام امکانات را برای شما ساخته است: بکاند اکسپرس، پایگاه داده SQLite، فرانتاند React. کار میکند. سپس از عامل خواستهاید دو ویژگی جدید اضافه کند: یک تابع جستجوی سرنخ و واردات/صادرات انبوه با آمار مدیریتی. عامل هر دو را به سرعت تحویل داده است. کد اجرا میشود، عملکرد ویژگیها و روابط عمومیها آماده هستند.
اما مشکل اینجاست: شما این کد را ننوشتهاید. شما آن را تأیید کردهاید. از کجا میدانید که نقطه پایانی جستجو در برابر تزریق SQL آسیبپذیر نیست؟ از کجا میدانید که مسیر ادمین رمز عبور رمزگذاریشده ندارد؟ شما ندارید - و خواندن هر خط از کد تولید شده توسط هوش مصنوعی، مزیت سرعتی را که در وهله اول شما را به vibe-code تبدیل کرده بود، از بین میبرد.
این codelab دو راه برای حل این مسئله به شما ارائه میدهد:
- مورد ۱ – بررسی تعاملی : یک شاخه ویژگی با آسیبپذیریها را بررسی کنید، از Antigravity CLI که با مهارتهای عامل بهبود یافته است برای بررسی تفاوتها، رفع مشکلات و ایجاد یک PR تمیز استفاده کنید.
- مورد ۲ – بررسی خودکار : یک GitHub Action با پشتیبانی Antigravity SDK راهاندازی کنید که به طور خودکار PRها را بررسی کند، یافتههای ساختاریافته را به عنوان نظر ارسال کند و وقتی توسعهدهندگان سوالات تکمیلی در مورد بررسی میپرسند، پاسخ دهد.
آنچه یاد خواهید گرفت
- چگونه کدگذاری vibe ممکن است خطرات امنیتی ایجاد کند و چرا بررسی خودکار آنچه را که بررسی دستی از دست میدهد، آشکار میکند
- نحوه نصب و استفاده از مهارتهای عامل (agent) تحت مدیریت جامعه برای ایجاد امنیت عمیق و تخصص در بررسی کد در Antigravity CLI
- نحوه استفاده تعاملی از رابط خط فرمان (CLI) برای بررسی تفاوتهای شاخه ویژگی، رفع آسیبپذیریها و ایجاد یک PR تمیز
- نحوه استفاده از Antigravity SDK برای ساخت یک عامل بررسی کد فقط خواندنی با سیاستهای ایمنی اعلانی و قلابهای چرخه عمر
- نحوه استقرار عامل بررسی به عنوان یک اقدام GitHub که PRها را بررسی میکند و نتیجه را به عنوان نظر PR ارسال میکند
پیشنیازها
- یک حساب کاربری گوگل کلود
- یک حساب کاربری گیتهاب
- آشنایی اولیه با ترمینال، کنترل نسخه و CI/CD
۲. تنظیمات محیطی
این مرحله، مخزن برنامه Leads CRM را منشعب میکند، آن را در Cloud Shell شبیهسازی میکند، Antigravity CLI را راهاندازی میکند و احراز هویت را انجام میدهد.
مخزن را فورک کنید
شما به یک کپی از مخزن خودتان نیاز دارید زیرا قرار است کامیتها را ارسال کنید و با استفاده از GitHub Actions، PR ایجاد کنید.
به مخزن زیر بروید
سپس، روی Fork کلیک کنید. در صفحه ایجاد fork، تیک گزینه "Copy the main branch only" را بردارید - شما به شاخههای ویژگی دیگر ( feature/lead-search و feature/bulk-operations ) که در fork شما گنجانده شدهاند، نیاز دارید.
پوسته ابری را باز کنید
Cloud Shell را در مرورگر خود باز کنید. Cloud Shell یک محیط از پیش پیکربندی شده با تمام ابزارهای مورد نیاز برای این آزمایشگاه کد را فراهم میکند. در صورت درخواست، روی تأیید (Authorize) کلیک کنید.
سپس روی « مشاهده » -> « ترمینال » کلیک کنید تا ترمینال باز شود. رابط کاربری شما باید شبیه به این باشد.
این رابط اصلی ما خواهد بود، IDE در بالا، ترمینال در پایین
احراز هویت با گیتهاب
به طور پیشفرض، Cloud Shell اعتبارنامههای GitHub را به صورت پیشفرض پیکربندی نکرده است، با این حال از قبل رابط خط فرمان gh را نصب کرده است. احراز هویت را تنظیم کنید تا بتوانید بعداً کامیتها را ارسال کرده و PRها را ایجاد کنید:
gh auth login
Github.com را انتخاب کنید
HTTPS را انتخاب کنید (یا اگر از قبل با مکانیسم دیگری آشنا هستید، میتوانید آن را انتخاب کنید)
سپس، Y را انتخاب کنید
سپس، Login with a web browser را انتخاب کنید
**،**از شما خواسته میشود که کد یکبار مصرف را کپی کرده و هنگام باز کردن صفحه ورود در مرورگر، آن را وارد کنید. میتوانید در ترمینال روی URL Ctrl + Click تا آدرس https://github.com/login/device باز شود. از شما خواسته میشود حسابی را که میخواهید وارد آن شوید انتخاب کرده و کد را وارد کنید.
پس از آن، به صفحه کنسول Cloud Shell برگردید و خروجی ترمینال را مانند این مشاهده خواهید کرد.
✓ Authentication complete. - gh config set -h github.com git_protocol https ✓ Configured git protocol ! Authentication credentials saved in plain text ✓ Logged in as alphinside-joonix
این یعنی شما با موفقیت احراز هویت حساب گیتهاب خود را روی Cloud Shell تنظیم کردهاید.
مخزن فورک شده خود را کلون کنید
در مرحله بعد، بیایید مخزن فورک شده شما را کلون کنیم. <YOUR_GITHUB_USERNAME> را با نام کاربری GitHub خود جایگزین کنید:
git clone https://github.com/<YOUR_GITHUB_USERNAME>/leads-crm-app-demo.git
cloudshell workspace leads-crm-app-demo && cd leads-crm-app-demo
شاخههای ویژگی را تأیید کنید
پس از آن، تأیید کنید که هر دو شاخه ویژگی با آسیبپذیریهای از پیش ساخته شده باید در ریموت در دسترس باشند:
git branch -a | grep feature/
باید خروجی زیر را مشاهده کنید
remotes/origin/feature/bulk-operations remotes/origin/feature/bulk-operations-solution remotes/origin/feature/email-composer remotes/origin/feature/lead-search
تأیید رابط خط فرمان ضد جاذبه (Antigravity CLI)
در مرحله بعد، بیایید بررسی کنیم که Antigravity CLI از قبل در Cloud Shell نصب شده است. تأیید کنیم که در دسترس است:
agy --version
شما باید نسخه Antigravity CLI نصب شده را ببینید، مثلاً 1.0.13
حال، اگر هنوز رابط خط فرمان Antigravity را احراز هویت نکردهاید، میتوانید به این آزمایشگاه کد مراجعه کنید تا فرآیند احراز هویت را با جزئیات بیشتری مشاهده کنید.
در این مرحله باید موارد زیر را داشته باشید:
- مخزن فورک شده کلون شد
- هر دو شاخه قابل مشاهده هستند
- دستور
agyدر دسترس و احراز هویت شده است
۳. مشکل - آسیبپذیریهای پنهان در ویژگیهای Vibe-Coded
این سناریو است: یکی از اعضای تیم از یک عامل هوش مصنوعی برای اضافه کردن دو ویژگی به برنامه Leads CRM استفاده کرد - یک تابع جستجوی سرنخ و عملیات واردات/صادرات انبوه. هر دو ویژگی کار میکنند. هر دو به سرعت و بدون بررسی امنیتی ارسال شدند. شما قرار است هر دو شاخه را قبل از ادغام بررسی کنید - یکی به صورت تعاملی با CLI، یکی به صورت خودکار با یک GitHub Action.
اولین شاخه ویژگی را بررسی کنید
تفاوت بین feature/lead-search را بررسی کنید:
git diff main...origin/feature/lead-search
این شاخه یک نقطه پایانی جستجو اضافه میکند. تفاوت را اسکن کنید - باید مشکلاتی مانند الحاق رشته در کوئریهای SQL، اعتبارسنجی ورودی از دست رفته، گزارش اشکالزدایی که جزئیات کوئری را فاش میکند و پیامهای خطای خام که در معرض کلاینت قرار میگیرند را تشخیص دهید.
+ app.get("/api/leads/search", (req, res) => {
+ const query = req.query.q as string;
+
+ if (!query) {
+ return res.status(400).json({ error: "Search query is required" });
+ }
...
بررسی شاخه ویژگی دوم
git diff main...origin/feature/bulk-operations
این شاخه، نقاط پایانی واردات/صادرات انبوه و یک داشبورد آمار مدیریتی را اضافه میکند. آسیبپذیریهای موجود در اینجا شامل اعتبارنامههای مدیریتی کدگذاری شده، نقاط پایانی مدیریتی احراز هویت نشده، عدم اعتبارسنجی ورودی در واردات انبوه و ریسک پیمایش مسیر در مدیریت نام فایل خروجی است.
...
+ const ADMIN_PASSWORD = "admin123";
+
+ app.post("/api/admin/import", (req, res) => {
+ const { password, leads } = req.body;
+
+ if (password !== ADMIN_PASSWORD) {
+ return res.status(401).json({ error: "Invalid admin password" });
+ }
...
هر دو شاخه ویژگیهای کاربردی اضافه میکنند. هر دو مشکلات امنیتی دارند. سوال این است که چگونه میتوان آنها را تشخیص داد - به صورت دستی با CLI (مورد 1) یا به صورت خودکار با یک GitHub Action (مورد 2).
۴. مورد ۱: بررسی تعاملی با رابط خط فرمان Antigravity
بررسی تعاملی CLI درست بعد از یک جلسه vibe-coding، بررسی کدی که به تازگی نوشتهاید یا بررسی درخواست pull همتیمیهایتان، بسیار ارزشمند است. اگر در مورد vibe-coding صحبت میکنیم، یک عامل هوش مصنوعی کد ویژگی شما را سریع تولید میکند - اما ممکن است شما هر خطی را که تولید میکند به طور کامل درک نکنید و عامل ممکن است برای عملکرد، و نه لزوماً برای امنیت، بسته به پیکربندی زمینه در حین توسعه ویژگی، بهینه شده باشد.
در این سناریو، ما کدهایی با آسیبپذیریهای امنیتی داریم و از Antigravity CLI به همراه مهارتهای بررسی کد برای بررسی تعاملی کد استفاده خواهیم کرد. این الگوی عامل-بررسی-عامل، آسیبپذیریهایی را که هنگام تغییر نقش توسعهدهنده از نوشتن کد به تأیید کد تولید شده توسط هوش مصنوعی از قلم میافتند، شناسایی میکند. همچنین هنگام بررسی کد نوشته شده دستی خودتان یا شاخه همتیمی قبل از عبور از CI اعمال میشود. شما مکالمه را کنترل میکنید: از عامل میخواهید که روی فایلهای خاص تمرکز کند، عمیقتر به یک یافته بپردازد یا فوراً اصلاحات را اعمال کند.
بدون مهارتهای عامل، Antigravity CLI همچنان میتواند کد را بررسی کند - اما به دانش آموزشی عمومی خود متکی است که ممکن است الگوهای خاص دامنه را از دست بدهد یا معیارهای بررسی متناقضی را در جلسات مختلف اعمال کند. مهارتهای عامل، یک دفترچه راهنمای ساختاریافته به عامل میدهد: بررسی پنج محوره برای کیفیت، برچسبگذاری شدت برای اولویتبندی. بررسی صرف نظر از نحوه بیان درخواست شما، تکرارپذیر و کامل میشود.
این مرحله از رابط خط فرمان Antigravity به همراه مهارتهای عامل برای بررسی شاخه feature/lead-search ، رفع آسیبپذیریها و ایجاد یک PR پاک استفاده میکند.
شاخه ویژگیها را بررسی کنید
ابتدا، بیایید شاخه خود را به شاخه Case 1 تغییر دهیم:
git checkout feature/lead-search
در مرحله بعد، بیایید Antigravity CLI خود را با مهارتهای عامل ارتقا دهیم تا بررسی کنیم.
مهارتهای عامل چیست؟
مهارتها فایلهای علامتگذاری اعلانی هستند که به عامل، تخصص ویژهای میدهند. پس از نصب، به دستورات اسلش تبدیل میشوند (مثلاً /code-review-and-quality ). آنها را به عنوان دستورالعملهای امنیتی یک مهندس ارشد در نظر بگیرید که به یک عامل همه منظوره ارائه میدهند.
مهارتها بین عاملها (Antigravity، Claude Code، Cursor و غیره) قابل حمل هستند و از طریق Git قابل اشتراکگذاری میباشند. برای Antigravity CLI، مهارتهای فضای کاری (پروژه/محلی) در مسیر .agents/skills/ در ریشه پروژه قرار دارند. در حالی که مهارتهای سراسری در مسیر ~/.gemini/config/skills/ قرار دارند. برای اطلاعات بیشتر به این مستندات مراجعه کنید.
برای نمایش قابلیتهای مهارتهای عامل، این آزمایشگاه کد از مهارت بررسی کد از addyosmani/agent-skills استفاده خواهد کرد:
-
code-review-and-quality– بررسی پنج محوره (صحت، خوانایی، معماری، امنیت، عملکرد) با برچسبگذاری شدت.
مهارت بررسی کد توسط عامل را نصب کنید
با استفاده از دستور زیر، مهارت مورد نظر به طور پیشفرض در مسیر .agents/skills/ در دایرکتوری کاری فعلی نصب خواهد شد - یک نصب در سطح فضای کاری. این بدان معناست که آنها بخشی از مخزن میشوند و میتوانند در کنار کد شما کامیت شوند، بنابراین هر توسعهدهنده (و خط لوله CI) در پروژه به طور خودکار مهارتهای بررسی یکسانی را دریافت میکند.
npx skills add addyosmani/agent-skills --skill code-review-and-quality -y
جزئیات مهارتی که میتوان در فایل .agents/skills/code-review-and-quality/SKILL.md بررسی کرد، به شرح زیر است:
name: code-review-and-quality description: Conducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensions before it enters the main branch.
قابلیتهای کلیدی:
- بررسیها در پنج محور: صحت، خوانایی، معماری، امنیت و عملکرد
- یافتهها را بر اساس شدت برچسبگذاری میکند تا بتوانید ابتدا مشکلات اساسی را برطرف کنید
- استاندارد تأیید را اعمال میکند: «وقتی که قطعاً سلامت کلی کد را بهبود میبخشد، حتی اگر بینقص نباشد، تأیید میشود»
حالا آمادهایم تا کمی اجرا انجام دهیم. بیایید مهارت را در Antigravity CLI بررسی کنیم.
AGY را راه اندازی کنید و مهارت ها را تأیید کنید
بیایید Antigravity CLI را اجرا کنیم
agy --dangerously-skip-permissions
سپس دستور زیر را اجرا کنید
/skills
شما باید دو مهارت را به این شکل در زیر مهارتهای Workspace skills) مشاهده کنید.
بررسی کد تفاوت ویژگی را اجرا کنید
مهارت امنیتی را فراخوانی کنید و از آن بخواهید شاخه شما را بررسی کند. این دستور را تایپ کنید:
Review the git diff between main and my current branch. Find any issues based on the agent skills that are appropriate for this. Write the findings and plan to fix them to code_review.md in the current working directory. Do not apply fixes yet.
این عامل، مهارت code-review-and-quality مرتبط را تشخیص داده و آن را به طور خودکار فعال میکند. این عامل، تفاوتها را میخواند، آسیبپذیریها را شناسایی میکند و یافتهها را به همراه یک طرح اصلاح پیشنهادی در code_review.md مینویسد.
پس از اتمام اسکن، باید فایل code_review.md ایجاد شده در دایرکتوری کاری خود را مشاهده کنید و میتوانید آن را در ویرایشگر بررسی کنید.
هر یافته و راهحل پیشنهادی را بررسی کنید. هنگامی که از طرح راضی بودید، از نماینده بخواهید آن را اعمال کند:
Apply the proposed fixes from code_review.md
عامل، طرح را میخواند و هر اصلاح برنامهریزیشده را روی فایلهای منبع اعمال میکند.
حالا، اگر بخواهید، میتوانید با نصب وابستگیها و اجرای آن، بررسی کنید که آیا برنامه پس از رفع مشکل به درستی اجرا میشود یا خیر.
npm install
npm run dev
برنامه باید به درستی اجرا شود. در غیر این صورت، میتوانید مراحل را تکرار کنید و از Antigravity CLI بخواهید که آن را اصلاح کند.
متعهد شوید و یک روابط عمومی ایجاد کنید
حالا، اگر بخواهید میتوانید تغییرات را به مخزن خودتان ارسال کنید. قبل از رفتن به مورد بعدی، ابتدا تغییرات را در شاخه فعلی ثبت میکنیم.
ابتدا باید هویت گیت شما را پیکربندی کنیم (اگر این کار را نکردهاید، نام و ایمیل خودتان را جایگزین کنید):
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
سپس تغییرات را کامیت کنید
git add .
git commit -m "fix: address security vulnerabilities in lead search feature"
اکنون، شما قبلاً از Antigravity CLI به عنوان یک بررسیکننده تعاملی استفاده کردهاید. این مهارتها به آن یک روش ساختاریافته - بررسی کد پنج محوره - دادهاند. این روش زمانی کار میکند که شما توسعهدهندهای باشید که کد تولید شده توسط هوش مصنوعی، کد خودتان یا کد همتیمیتان را بررسی میکند. در بخش بعدی، ما تمام این جریان را خودکار خواهیم کرد تا آن را به عنوان یک فرآیند خودکار مقیاسپذیر در مخزن کد شما با استفاده از Github به عنوان مثال، تبدیل کنیم.
۵. مورد ۲: بررسی خودکار با Antigravity SDK - بخش ۱ (ایجاد عامل)
این مرحله یک عامل بررسی خودکار با استفاده از Antigravity SDK میسازد، آن را به عنوان یک GitHub Action مستقر میکند و آن را در برابر شاخه ویژگی دوم آزمایش میکند. عامل PRها را بر اساس تقاضا بررسی میکند و یافتهها را به عنوان نظرات PR ارسال میکند.
چرا بررسی خودکار
بررسی تعاملی CLI (مورد ۱) زمانی کار میکند که یک توسعهدهنده به طور فعال بررسی کند. تیمها به یک بررسی نیاز دارند که به طور خودکار در هر PR اجرا شود - و مشکلات را از هر مشارکتکننده، هر ابزاری، در هر زمانی دریافت کند. کیت توسعه نرمافزار Antigravity ( google-antigravity ) همان زمان اجرای عامل CLI را به عنوان یک کتابخانه پایتون ارائه میدهد. سیاستها و قلابها در کد پیکربندی شدهاند.
GitHub Actions پلتفرم داخلی GitHub برای ادغام مداوم/توسعه مداوم (CI/CD) است. این پلتفرم، گردشهای کاری - اسکریپتهای خودکار تعریف شده در YAML - را در پاسخ به رویدادهای مخزن مانند باز کردن یک PR، ارسال یک commit یا ارسال نظر اجرا میکند. گردشهای کاری روی ماشینهای مجازی میزبانی شده توسط GitHub اجرا میشوند و به کد مخزن دسترسی دارند. در این حالت، شما از یک GitHub Action برای اجرای یک عامل بررسی امنیتی هر بار که یک PR ایجاد میشود، استفاده میکنید.
نحوهی عملکرد جریان بررسی خودکار به این صورت است:
کیت توسعه نرمافزار آنتیگراویتی ( google-antigravity ) همان زمان اجرای عامل (agent runtime) را مانند رابط خط فرمان (CLI) و به عنوان یک کتابخانه پایتون ارائه میدهد. شما یک اسکریپت پایتون مینویسید که عامل را با سیاستها و هوکها پیکربندی میکند، آن را درون یک اکشن گیتهاب اجرا میکنید و نتایج را به عنوان یک نظر PR ارسال میکنید.
دریافت کلید API جمینی
قبل از شروع، به کلید API Gemini نیاز داریم تا توسط Antigravity SDK استفاده شود. به Google AI Studio API Key بروید و یک کلید API ایجاد کنید و هر زمان که نیاز داشتید میتوانید کلید API را کپی کنید.
این کلید هنگام اجرای عامل بررسی به صورت محلی و بعداً به عنوان یک راز GitHub Actions استفاده خواهد شد.
بخش الف: عامل بررسی را بسازید
حالا، برای مورد ۲، بیایید دایرکتوری کاری فعلی شما را به شاخه feature/bulk-operations تغییر دهیم:
git checkout feature/bulk-operations
این دومین شاخه ویژگی از سناریو است - نقاط پایانی واردات/صادرات انبوه و یک داشبورد آمار مدیریتی را به برنامه CRM اضافه میکند.
پروژه پایتون را تنظیم کنید
کیت توسعه نرمافزار Antigravity در حال حاضر فقط با پایتون موجود است، بنابراین برای توسعه آن به یک محیط پایتون نیاز داریم. ما از uv برای مدیریت پروژه پایتون خود استفاده خواهیم کرد. uv یک بسته سریع پایتون و مدیریت پروژه است که با زبان Rust نوشته شده است ( docs ). این codelab از آن برای سرعت و سادگی استفاده میکند. اگر از cloudshell برای این آموزش استفاده میکنید، از قبل در نمونه نصب شده است. اگر میخواهید آن را برای سیستم محلی خود نصب کنید، به این آموزش مراجعه کنید.
با استفاده از uv یک پروژه پایتون برای عامل بررسی راهاندازی کنید:
uv init code_review_agent
uv add --project code_review_agent google-antigravity==0.1.7
این دستور یک دایرکتوری جدید code_review_agent ایجاد میکند که شامل فایلهای عامل بررسی کد مورد نیاز ما خواهد بود.
مهارتهای مرور را نصب کنید
عامل بررسی به همان مهارتهای امنیتی و بررسی کد که در مورد ۱ استفاده شد، نیاز دارد. آنها را در code_review_agent/skills/ نصب کنید تا عامل SDK آنها را در زمان اجرا بارگذاری کند:
npx skills add addyosmani/agent-skills --skill code-review-and-quality -y
cp -r .agents/skills code_review_agent/skills
عامل بررسی را ایجاد کنید
حالا، بیایید code_review_agent/review_agent.py را ایجاد کنیم. دستور زیر را اجرا کنید.
cloudshell edit code_review_agent/review_agent.py
سپس، محتوای زیر را در فایل کپی کنید
#!/usr/bin/env python3
import asyncio
import json
import os
import sys
import pydantic
from google.antigravity import Agent, LocalAgentConfig, CapabilitiesConfig
from google.antigravity.hooks import hooks, policy
from google.antigravity import types
class Finding(pydantic.BaseModel):
file: str
line: int
severity: str
category: str
description: str
proposed_fix: str = ""
class ReviewResult(pydantic.BaseModel):
findings: list[Finding]
SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
OUTPUT_FILE = "code_review.md"
SKILLS_PATHS = [
os.path.join(SCRIPT_DIR, "skills", "code-review-and-quality"),
]
review_policies = [
policy.deny_all(),
policy.allow("view_file"),
policy.allow("list_directory"),
policy.allow("search_directory"),
policy.allow("find_file"),
policy.allow("run_command"),
policy.allow("finish"),
]
@hooks.post_tool_call
async def log_tool_results(data: types.ToolResult):
result_str = str(data.result) if data.result else ""
preview = result_str[:200] + "..." if len(result_str) > 200 else result_str
print(f"[audit] tool={data.name} result_len={len(result_str)} error={data.error} preview={preview}", flush=True)
@hooks.pre_tool_call_decide
async def enforce_safe_tools(data: types.ToolCall) -> types.HookResult:
print(f"[audit] calling tool={data.name} args_keys={list(data.args.keys())}", flush=True)
if data.name == "run_command":
cmd = str(data.args.get("CommandLine", ""))
if not cmd.startswith("git "):
return types.HookResult(
allow=False,
message=f"Only git commands are allowed. Blocked: {cmd}"
)
return types.HookResult(allow=True)
async def review_code(target_dir: str) -> dict:
prompt = f"""Run `git diff main...HEAD -- ':!.github' ':!code_review_agent'` in {target_dir} to get the changes on this branch.
Review ONLY the changed code for security vulnerabilities and code quality issues.
"""
config_kwargs = dict(
system_instructions=(
"You are a code review agent. "
"You review code diffs for vulnerabilities and quality issues using the loaded skills. "
"You can run git commands to inspect the diff. "
"You NEVER modify files."
),
response_schema=ReviewResult,
skills_paths=SKILLS_PATHS,
policies=review_policies,
hooks=[log_tool_results, enforce_safe_tools],
)
if os.environ.get("GEMINI_API_KEY"):
config_kwargs["api_key"] = os.environ["GEMINI_API_KEY"]
else:
config_kwargs["vertex"] = True
config_kwargs["project"] = os.environ.get("GOOGLE_CLOUD_PROJECT")
config_kwargs["location"] = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
config = LocalAgentConfig(**config_kwargs)
async with Agent(config) as agent:
response = await agent.chat(prompt)
last_step = -1
final_text_chunks = []
async for chunk in response.chunks:
if isinstance(chunk, types.ToolCall):
final_text_chunks.clear()
if hasattr(chunk, "text") and hasattr(chunk, "step_index"):
if chunk.step_index != last_step:
final_text_chunks.clear()
last_step = chunk.step_index
final_text_chunks.append(chunk.text)
final_text = "".join(final_text_chunks)
if final_text:
print(final_text)
data = await response.structured_output()
if data and "findings" in data:
return {"findings": data["findings"]}
try:
parsed = json.loads(final_text)
if isinstance(parsed, list):
return {"findings": parsed}
if isinstance(parsed, dict) and "findings" in parsed:
return {"findings": parsed["findings"]}
except json.JSONDecodeError:
pass
return {"findings": final_text}
SEVERITY_EMOJI = {"critical": "🔴", "high": "🟠", "medium": "🟡", "low": "🔵"}
def format_markdown(result: dict) -> str:
findings = result.get("findings", [])
if isinstance(findings, str):
return f"## AI Security Review\n\n{findings}\n"
if not findings:
return "## AI Security Review\n\nNo security issues found.\n"
lines = ["## AI Security Review\n"]
for f in findings:
emoji = SEVERITY_EMOJI.get(f.get("severity", "").lower(), "⚪")
lines.append(f"### {emoji} [{f.get('severity', 'unknown').upper()}] {f.get('category', '')}\n")
lines.append(f"**{f.get('file', '')}:{f.get('line', '')}**\n")
lines.append(f"{f.get('description', '')}\n")
proposed_fix = f.get('proposed_fix', '')
if proposed_fix:
lines.append(f"**Proposed fix:** {proposed_fix}\n")
lines.append("---\n*Powered by Antigravity SDK*")
return "\n".join(lines)
if __name__ == "__main__":
target = sys.argv[1] if len(sys.argv) > 1 else "."
result = asyncio.run(review_code(target))
markdown = format_markdown(result)
with open(OUTPUT_FILE, "w") as f:
f.write(markdown)
print(f"Review written to {OUTPUT_FILE}")
print(json.dumps(result, indent=2))
تصمیمات کلیدی طراحی در این عامل را مرور کنید:
- سیاستهای پیشفرض را رد میکند :
policy.deny_all()همه چیز را مسدود میکند، سپس به طور خاص ابزارهای خواندن فایل فقط باز وrun_command(برای git) را مجاز میکند. - اجرا در دو لایه : سیاستها در سطح چارچوب محدود میشوند، و هوک
enforce_safe_toolsیک لایه دوم فراهم میکند - فقط دستوراتgitرا از طریقrun_commandمجاز میداند. - بررسی محدودهی تغییرات در گیت : عامل، دستور
git diff main...HEADرا اجرا میکند تا فقط کد تغییر یافته را بررسی کند، نه کل کدبیس را. - خروجی ساختاریافته با قابلیت جایگزینی :
response_schema=ReviewResultساختار JSON را از طریق ابزار تکمیل SDK اعمال میکند. اگر تجزیه با شکست مواجه شود، زنجیره جایگزینی سعی میکندtext()به صورت JSON تجزیه کند، سپس متن خام را برمیگرداند. - Auth fallback : در صورت وجود
GEMINI_API_KEYاستفاده میکند، در غیر این صورت از طریق Application Default Credentials به Vertex AI برمیگردد. - خروجی فایل : یافتههای نشانهگذاری قالببندیشده را در
code_review.mdمینویسد - GitHub Action این فایل را میخواند و بعداً آن را به عنوان یک نظر PR ارسال میکند.
عامل بررسی را آزمایش کنید
از ریشه پروژه تست کنید. SDK، GEMINI_API_KEY از محیط میخواند، از این رو کلید را در محیط قرار میدهیم.
export GEMINI_API_KEY=YOUR_API_KEY
سپس دستور زیر را برای اجرای آن به صورت محلی اجرا کنید
uv run --project code_review_agent code_review_agent/review_agent.py .
هنگام اجرا، خروجی کنسولی نمایش داده میشود که توضیح میدهد در حال حاضر از چه ابزارهایی استفاده میکند. و میتوانید متوجه شوید که به مهارتهای عامل security-and-hardening و code-review-and-quality دسترسی دارد.
[audit] calling tool=view_file args_keys=['AbsolutePath', 'IsSkillFile'] [audit] tool=view_file result_len=47 error=None preview=Read security and hardening skill documentation [audit] calling tool=view_file args_keys=['AbsolutePath', 'IsSkillFile'] [audit] tool=view_file result_len=48 error=None preview=Read code review and quality skill documentation [audit] calling tool=run_command args_keys=['CommandLine', 'Cwd', 'WaitMsBeforeAsync'] ...
عامل git diff main...HEAD را اجرا میکند، فقط کد تغییر یافته را بررسی میکند، یافتههای قالببندی شده را در code_review.md مینویسد و JSON ساختاریافته را در کنسول چاپ میکند. میتوانید code_review.md نوشته شده را در ویرایشگر مانند تصویر زیر بررسی کنید.
به صورت محلی از قبل کار میکند، حالا بیایید به بخش بعدی برویم. ایجاد پیکربندی Github Action
۶. مورد ۲: بررسی خودکار با Antigravity SDK - بخش ۲ (پیکربندی اقدامات گیتهاب)
قبل از شروع، اگر فایل code_review.md که قبلاً تولید شده است وجود دارد، آن را حذف میکنیم.
rm -f code_review.md
حالا، باید فایل پیکربندی YAML مربوط به Github Action را ایجاد کنیم.
mkdir -p .github/workflows
cloudshell edit .github/workflows/code_review.yml
سپس محتوای زیر را به فایل اضافه کنید
name: AI Code Security and Quality Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
container:
image: ghcr.io/astral-sh/uv:python3.12-bookworm
steps:
- name: Install git
run: apt-get update && apt-get install -y git
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run security review
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
run: |
git config --global --add safe.directory $GITHUB_WORKSPACE
uv run --project code_review_agent code_review_agent/review_agent.py .
- name: Post findings as PR comment
if: always()
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const body = fs.readFileSync('code_review.md', 'utf8');
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.payload.pull_request.number,
body: body
});
این گردش کار به طور خودکار با باز شدن یا بهروزرسانی یک PR آغاز میشود. این گردش کار، شاخه PR را با تاریخچه کامل گیت (که برای git diff main...HEAD مورد نیاز است) بررسی میکند، عامل بررسی را اجرا میکند که یافتهها را در code_review.md مینویسد و محتوای فایل را به عنوان یک نظر PR ارسال میکند.
حالا بیایید همه تغییرات را ثبت کنیم و آن را به گیتهاب ریموت ارسال کنیم، ما آمادهایم تا این ادغام را آزمایش کنیم.
git add .
git commit -m "Add AI code security-quality review agent and GitHub Action"
git push origin feature/bulk-operations
۷. مورد ۲: بررسی خودکار با Antigravity SDK - بخش ۳ (آزمایش بررسی خودکار کد)
حالا، به صفحه وب مخزن فورک شده شما به https://github.com/<YOUR_GITHUB_USERNAME>/leads-crm-app-demo میرویم و روی Settings کلیک میکنیم.
سپس، در پنل سمت چپ، Secrets and variables را پیدا کنید و روی آن کلیک کرده و Actions انتخاب کنید.
پس از آن، روی « New repository secret کلیک کنید تا راز GEMINI_API_KEY پیکربندی کنید.
پس از آن، Pull Request انتخاب کنید و یک Pull Request جدید از شاخه feature/bulk_operations به شاخه main مخزن خودتان ایجاد کنید.
پس از ایجاد درخواست pull، اقدامات Github اجرا میشوند که میتوانید آنها را در منوی Checks یا نزدیک دکمه Merge pull request بررسی کنید.
میتوانید روی اقدامات در حال اجرا کلیک کنید تا جزئیات را ببینید و پس از اتمام، نتایج بررسی به صورت نظر درخواست Pull مانند تصویر زیر ارسال میشود.
۸. جمعبندی
تبریک میگویم!
شما دو گردش کار کامل بررسی کد برای شناسایی آسیبپذیریهای امنیتی در ویژگیهای کدگذاری شده با vibe ایجاد کردید:
- مورد ۱ (تعاملی) : رابط خط فرمان آنتیگراویتی (Antigravity CLI) با مهارتهای عامل، یک تفاوت شاخه ویژگی را بررسی کرد، تزریق SQL و سایر آسیبپذیریها را شناسایی کرد، آنها را با پیروی از الگوهای OWASP برطرف کرد و یک PR بینقص تولید کرد.
- مورد ۲ (خودکار) : کیت توسعه نرمافزار Antigravity از یک GitHub Action پشتیبانی میکند که به طور خودکار هر PR را بررسی میکند و یافتههای امنیتی ساختاریافته را به عنوان نظرات PR ارسال میکند.
آنچه آموختهاید
- چگونه کدگذاری vibe خطرات امنیتی ایجاد میکند و چرا بررسی خودکار آنچه را که بررسی دستی از دست میدهد، آشکار میکند
- نحوه نصب و استفاده از مهارتهای عامل برای ارائه تخصص امنیتی ساختاریافته به Antigravity CLI
- چگونه به صورت تعاملی تفاوتهای یک شاخه ویژگی را بررسی کنیم، مشکلات را برطرف کنیم و یک PR تمیز ایجاد کنیم
- نحوه ساخت یک عامل بررسی فقط خواندنی با Antigravity SDK با استفاده از سیاستهای انکار پیشفرض و قلابهای چرخه عمر
- نحوه استقرار یک خط لوله بررسی خودکار به عنوان یک اقدام GitHub با پشتیبانی پیگیری تعاملی
تمیز کردن
روابط عمومیها را ببندید
به هر PR در فورک خود در گیتهاب بروید و روی بستن درخواست pull کلیک کنید. PR مربوط به feature/bulk-operations را ادغام نکنید - هنوز حاوی کد آسیبپذیر وصله نشده است.
مخزن انشعاب یافته را حذف کنید (اختیاری)
اگر دیگر به این شاخه نیاز ندارید، به شاخه خود در گیتهاب بروید: تنظیمات -> به منطقه خطر بروید -> این مخزن را حذف کنید .
قدم بعدی چیست؟
- افزونهها و مهارتهای Antigravity CLI - ایجاد مهارتها و افزونههای سفارشی
- مجوزهای رابط خط فرمان آنتیگراویتی و محیط امن (Sandbox) - سیاستهای دقیق ابزار و محیط امن در سطح سیستمعامل
- قلابها و سیاستهای Antigravity SDK - الگوهای پیشرفته (محدود کردن سرعت، بازیابی خطا، میانافزار)
- نمونههای کیت توسعه نرمافزار Antigravity -
agent_middleware.pyبرای الگوهای عملیاتی