تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

تحسين جودة الرموز البرمجية: مراجعة الرموز البرمجية بمساعدة الذكاء الاصطناعي باستخدام Antigravity CLI وSDK

1. مقدمة

تغيّر عملية الترميز المستند إلى الذكاء الاصطناعي دور المطوّر من مؤلف إلى منظّم ومراجع، إذ يستخدم وكلاء الذكاء الاصطناعي لكتابة الرموز البرمجية من الطلبات المكتوبة بلغة طبيعية. نعتمد على إعداد السياق المثالي ونثق في قدرة وكلاء الذكاء الاصطناعي على تنفيذ جميع المهام نيابةً عنّا، بدءًا من إعداد مستندات المواصفات إلى ضمان استيفاء الرمز البرمجي لجميع المتطلبات. المخاطرة: في دورات التكرار السريع، تتم الموافقة على الرموز الوظيفية بدون مراجعة شاملة للأمان. غالبًا ما تنتج الوكلاء الحديثون رموزًا برمجية آمنة تلقائيًا، ولكن "غالبًا" لا تعني "دائمًا"، كما أنّ الثغرات الأمنية المتراكمة لا يمكن رصدها من خلال المراجعة اليدوية.

يتناول هذا الدرس التطبيقي حول الترميز هذه المشاكل من خلال تعليم طريقتَين لاستخدام Antigravity كمراجع: بشكل تفاعلي أثناء التطوير باستخدام واجهة سطر الأوامر (تراجع الرمز البرمجي وتصلحه ثم تنشئ طلب سحب)، وبشكل تلقائي في عملية الدمج المستمر باستخدام حزمة تطوير البرامج (يراجع الوكيل كل طلب سحب وينشر النتائج كتعليق).

المواضيع التي سنتناولها

لقد استخدمت ميزة "الترميز المستند إلى الأجواء" لإنشاء تطبيق Leads CRM، وهو عبارة عن وكيل الذكاء الاصطناعي أنشأ لك الحزمة الكاملة: خلفية Express، وقاعدة بيانات SQLite، وواجهة React الأمامية. وهي تعمل. بعد ذلك، طلبت من الوكيل إضافة ميزتَين جديدتَين: وظيفة البحث عن العملاء المحتملين ووظيفة الاستيراد/التصدير المجمّع مع إحصاءات المشرف. قدّم الوكيل الردّين بسرعة. يتم تشغيل الرمز البرمجي، وتعمل الميزات، وتصبح طلبات الدمج جاهزة.

لكن المشكلة هي أنّك لم تكتب هذا الرمز. لقد وافقت على ذلك. كيف تعرف أنّ نقطة نهاية البحث ليست عرضة لهجوم حقن SQL؟ كيف تعرف أنّ مسار المشرف لا يحتوي على كلمة مرور مبرمَجة؟ لا حاجة إلى ذلك، فقراءة كل سطر من الرمز الذي أنشأه الذكاء الاصطناعي يلغي ميزة السرعة التي دفعتك إلى استخدام البرمجة الوصفية في المقام الأول.

تقدّم لك تجربة البرمجة هذه طريقتَين لحلّ هذه المشكلة:

الحالة 1 – مراجعة تفاعلية: يمكنك الاطّلاع على فرع ميزات يتضمّن ثغرات أمنية، واستخدام Antigravity CLI المحسّن بمهارات الوكيل لمراجعة الاختلافات، وإصلاح المشاكل، وإنشاء طلب سحب نظيف.
الحالة 2 – مراجعة مبرمَجة: يمكنك إعداد GitHub Action يستند إلى Antigravity SDK، وتتمثّل وظيفته في مراجعة طلبات السحب تلقائيًا، ونشر النتائج المنظَّمة كتعليقات، والردّ عندما يطرح المطوّرون أسئلة متابعة حول المراجعة.

ما ستتعلمه

كيف يمكن أن يؤدي ترميز الأجواء إلى حدوث مخاطر أمنية ولماذا ترصد المراجعة المبرمَجة ما لا ترصده المراجعة اليدوية؟
كيفية تثبيت مهارات الوكيل التي يديرها المنتدى واستخدامها لمنح Antigravity CLI خبرة كبيرة في مراجعة الأمان والرموز البرمجية
كيفية استخدام واجهة سطر الأوامر بشكل تفاعلي لمراجعة الاختلاف بين فرع الميزة، وإصلاح الثغرات الأمنية، وإنشاء طلب سحب نظيف
كيفية استخدام Antigravity SDK لإنشاء وكيل مراجعة رموز برمجية للقراءة فقط باستخدام سياسات الأمان التعريفية وخطافات مراحل النشاط
كيفية نشر وكيل المراجعة كإجراء GitHub يراجع طلبات السحب وينشر النتيجة كتعليق على طلب السحب

المتطلبات الأساسية

حساب Google Cloud
حساب على GitHub
معرفة أساسية بـ Terminal وVersion Control وCI/CD

2. إعداد البيئة

تتضمّن هذه الخطوة إنشاء نسخة من مستودع تطبيق Leads CRM، واستنساخها في Cloud Shell، وإعداد Antigravity CLI، والمصادقة.

إنشاء نسخة طبق الأصل من المستودع

يجب أن يكون لديك نسخة من المستودع لأنّك ستدفع عمليات الالتزام وتنشئ طلبات سحب باستخدام GitHub Actions.

الانتقال إلى المستودع التالي

بعد ذلك، انقر على إنشاء نسخة طبق الأصل. في صفحة إنشاء النسخة المتفرّعة، أزِل العلامة من المربّع "نسخ الفرع main فقط"، لأنّك تحتاج إلى فروع الميزات الأخرى (feature/lead-search وfeature/bulk-operations) المضمّنة في نسختك المتفرّعة.

فتح Cloud Shell

افتح Cloud Shell في المتصفّح. توفّر Cloud Shell بيئة تم ضبطها مسبقًا تتضمّن جميع الأدوات التي تحتاج إليها لإكمال هذا الدرس التطبيقي حول الترميز. انقر على تفويض عندما يُطلب منك ذلك

بعد ذلك، انقر على عرض -> وحدة طرفية لفتح الوحدة الطرفية.يجب أن تبدو واجهتك مشابهة لما يلي

ستكون هذه هي واجهتنا الرئيسية، مع وضع بيئة التطوير المتكاملة في الأعلى والوحدة الطرفية في الأسفل.

المصادقة باستخدام GitHub

لا تتضمّن Cloud Shell تلقائيًا بيانات اعتماد GitHub، ولكنها تتضمّن واجهة سطر الأوامر gh مثبّتة. إعداد المصادقة حتى تتمكّن من إرسال عمليات الالتزام وإنشاء طلبات سحب لاحقًا:

gh auth login

اختيار Github.com

اختَر HTTPS ( أو يمكنك اختيار آلية أخرى إذا كنت معتادًا عليها).

بعد ذلك، اختَر Y

بعد ذلك، اختَر Login with a web browser

**,**سيُطلب منك نسخ الرمز الصالح لمرة واحدة وإدخاله عند فتح صفحة تسجيل الدخول في المتصفّح، ويمكنك النقر على Ctrl + Click على عنوان URL في نافذة الأوامر لفتح عنوان URL الخاص بـ 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

هذا يعني أنّك أعددت بنجاح مصادقة حسابك على Github في 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 CLI بعد، يمكنك الانتقال إلى هذا الدرس التطبيقي حول الترميز للاطّلاع على عملية المصادقة بتفصيل أكبر.

في هذه المرحلة، يجب أن يتوفّر لديك ما يلي:

تم استنساخ المستودع المتفرّع
ظهور كلا الفرعين اللذين يتضمّنان الميزات
الأمر agy متاح وتمت المصادقة عليه

3- المشكلة: الثغرات الأمنية المخفية في الميزات المستندة إلى الاهتزاز

إليك السيناريو: استخدم أحد أعضاء الفريق وكيل الذكاء الاصطناعي لإضافة ميزتَين إلى تطبيق Leads CRM، وهما وظيفة البحث عن العملاء المحتملين وعمليات الاستيراد/التصدير المجمّعة. تعمل كلتا الميزتين. وتم شحن كليهما بسرعة بدون مراجعة الأمان. ستراجع كلا الفرعين قبل دمجهما، أحدهما بشكل تفاعلي باستخدام واجهة سطر الأوامر، والآخر تلقائيًا باستخدام 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

يضيف هذا الفرع نقاط نهاية للاستيراد والتصدير المجمّعَين ولوحة بيانات إحصاءات المشرف. تشمل الثغرات الأمنية هنا بيانات اعتماد المشرف المضمّنة في الرمز البرمجي، ونقاط نهاية المشرف غير المصادَق عليها، وعدم التحقّق من صحة البيانات عند الاستيراد المُجمَّع، وثغرة path traversal في معالجة أسماء ملفات التصدير.

...
+  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" });
+    }
...

يضيف كلا الفرعين ميزات عملية. وكلاهما يواجه مشاكل متعلّقة بالأمان. والسؤال هو كيفية رصدها، إما يدويًا باستخدام واجهة سطر الأوامر (الحالة 1) أو تلقائيًا باستخدام GitHub Action (الحالة 2).

4. الحالة 1 : مراجعة تفاعلية باستخدام Antigravity CLI

تكون مراجعة واجهة سطر الأوامر التفاعلية مفيدة جدًا بعد جلسة ترميز سريع، أو مراجعة الرمز الذي كتبته للتو، أو مراجعة طلب سحب الرمز الذي أرسله زملاؤك في الفريق. إذا كنّا نتحدّث عن الترميز حسب الأجواء، أنشأ وكيل الذكاء الاصطناعي رمز الميزة بسرعة، ولكن قد لا تفهم تمامًا كل سطر تم إنشاؤه، وقد يكون الوكيل محسّنًا من أجل الوظائف، وليس بالضرورة الأمان، وذلك حسب إعدادات السياق أثناء تطوير الميزة.

في هذا السيناريو، لدينا رموز برمجية تتضمّن ثغرات أمنية، وسنستخدم Antigravity CLI مع مهارات مراجعة الرموز البرمجية لمراجعة الرموز بشكل تفاعلي. يرصد نمط "المراجعة بين الوكلاء" الثغرات الأمنية التي قد تمرّ بدون رصد عندما يتحوّل دور المطوّر من كتابة الرموز البرمجية إلى الموافقة على الرموز البرمجية التي ينشئها الذكاء الاصطناعي. وينطبق ذلك أيضًا عند مراجعة الرمز المكتوب يدويًا أو فرع أحد أعضاء الفريق قبل إخضاعه لعملية التكامل المستمر. يمكنك التحكّم في المحادثة: اطلب من الوكيل التركيز على ملفات معيّنة، أو البحث بشكل أعمق عن نتيجة معيّنة، أو تطبيق الإصلاحات على الفور.

بدون مهارات الوكيل، يمكن أن يراجع Antigravity CLI الرمز البرمجي، ولكنّه يعتمد على معرفته التدريبية العامة، ما قد يؤدي إلى عدم رصد الأنماط الخاصة بالمجال أو تطبيق معايير مراجعة غير متسقة على مستوى الجلسات. تمنح مهارات الوكيل الوكيل دليلًا إرشاديًا منظَّمًا: مراجعة خماسية المحاور للجودة، وتصنيف الخطورة لتحديد الأولويات. تصبح المراجعة قابلة للتكرار وشاملة بغض النظر عن طريقة صياغة الطلب.

تستخدم هذه الخطوة Antigravity CLI مع مهارات الوكيل لمراجعة الفرع feature/lead-search وإصلاح الثغرات الأمنية وإنشاء طلب سحب نظيف.

الاطّلاع على فرع الميزة

أولاً، لنغيّر الفرع إلى الفرع Case 1:

git checkout feature/lead-search

بعد ذلك، لنرقّي Antigravity CLI باستخدام مهارات الوكيل لإجراء المراجعة.

ما هي مهارات الوكيل؟

المهارات هي ملفات markdown تعريفية تمنح الوكيل خبرة متخصّصة. بعد تثبيتها، تصبح أوامر شرطية (مثل /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 المهارات

تشغيل مراجعة الرمز البرمجي لاختلافات الميزات

استدعِ مهارة الأمان واطلب منها مراجعة فرعك. اكتب الطلب التالي:

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 (استبدِلها باسمك وعنوان بريدك الإلكتروني) إذا لم يسبق لك إجراء ذلك:

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 كمثال.

5- الحالة 2 : المراجعة الآلية باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ Antigravity - الجزء 1 (إنشاء الوكيل)

تنشئ هذه الخطوة وكيل مراجعة مبرمَجة باستخدام Antigravity SDK، وتنشره كإجراء GitHub، وتختبره مقابل فرع الميزة الثاني. يراجع الوكيل طلبات الدمج عند الطلب وينشر النتائج كتعليقات على طلبات الدمج.

أسباب استخدام المراجعة المبرمَجة

تعمل المراجعة التفاعلية لواجهة سطر الأوامر (الحالة 1) عندما يراجع المطوّر بشكل نشط. تحتاج الفِرق إلى مراجعة يتم إجراؤها تلقائيًا على كل طلب سحب، ما يتيح رصد المشاكل من أي مساهم أو أداة أو في أي وقت. توفّر حزمة تطوير البرامج (SDK) الخاصة بـ Antigravity (google-antigravity) بيئة تشغيل الوكيل نفسها التي توفّرها واجهة سطر الأوامر، وذلك كمكتبة Python. يتم ضبط السياسات وخطافات الإجراءات في الرمز البرمجي.

GitHub Actions هي منصة مدمجة في GitHub لعمليات الدمج المستمر/التطوير المستمر (CI/CD). وهي تنفّذ سير العمل، أي النصوص البرمجية المبرمَجة المحدّدة في YAML، استجابةً لأحداث المستودع، مثل فتح طلب سحب أو إرسال عملية دمج أو نشر تعليق. يتم تشغيل مهام سير العمل على أجهزة افتراضية مستضافة على GitHub ويمكنها الوصول إلى رمز المستودع. في هذه الحالة، يمكنك استخدام GitHub Action لتشغيل وكيل مراجعة أمان في كل مرة يتم فيها إنشاء طلب سحب.

في ما يلي طريقة عمل عملية المراجعة المبرمَجة:

توفّر حزمة تطوير البرامج (SDK) الخاصة بـ Antigravity (google-antigravity) بيئة تشغيل الوكيل نفسها التي توفّرها واجهة سطر الأوامر، وذلك كمكتبة Python. يمكنك كتابة نص برمجي بلغة Python يضبط الوكيل باستخدام السياسات وخطافات الويب، وتشغيله داخل GitHub Action، ونشر النتائج كتعليق على طلب السحب.

الحصول على مفتاح Gemini API

قبل البدء، سنحتاج إلى مفتاح Gemini API الذي ستستخدمه حزمة Antigravity SDK. انتقِل إلى مفتاح واجهة برمجة التطبيقات في Google AI Studio وأنشئ مفتاح واجهة برمجة تطبيقات، ويمكنك نسخ مفتاح واجهة برمجة التطبيقات متى احتجت إلى ذلك.

سيتم استخدام هذا المفتاح عند تشغيل وكيل المراجعة محليًا وكأحد أسرار GitHub Actions لاحقًا

الجزء (أ): إنشاء وكيل المراجعات

الآن، بالنسبة إلى الحالة 2، لنبدّل دليل العمل الحالي إلى الفرع feature/bulk-operations:

git checkout feature/bulk-operations

هذا هو فرع الميزة الثاني من السيناريو، وهو يضيف نقاط نهاية للاستيراد والتصدير المجمّع ولوحة بيانات إحصاءات المشرف إلى تطبيق إدارة علاقات العملاء.

إعداد مشروع Python

لا يتوفّر حزمة تطوير البرامج (SDK) الخاصة بـ Antigravity حاليًا إلا في Python، لذا سنحتاج إلى بيئة Python لتطويرها. سنستخدم uv لإدارة مشاريع Python. ‫uv هي حزمة Python سريعة وأداة لإدارة المشاريع مكتوبة بلغة Rust ( المستندات). يستخدم هذا الدرس التطبيقي حول الترميز هذه الطريقة لسرعتها وبساطتها. إذا كنت تستخدم Cloud Shell لهذا البرنامج التعليمي، سيتم تثبيته مسبقًا في الجهاز الظاهري. يمكنك الاطّلاع على هذا الفيديو التعليمي إذا أردت تثبيته على جهازك.

ابدأ مشروع Python لوكيل المراجعة باستخدام uv:

uv init code_review_agent
uv add --project code_review_agent google-antigravity==0.1.7

سيتم إنشاء دليل جديد code_review_agent يحتوي على ملفات وكيل مراجعة الرموز البرمجية الضرورية.

تثبيت مهارات المراجعة

يجب أن يتمتّع المراجع بالمهارات نفسها المتعلّقة بالأمان ومراجعة الرموز البرمجية المستخدَمة في الحالة 1. ثبِّتها في 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: ينفّذ الوكيل الأمر git diff main...HEAD لمراجعة الرمز الذي تم تغييره فقط، وليس قاعدة الرموز البرمجية بأكملها.
الناتج المنظَّم مع خيار احتياطي: تفرض response_schema=ReviewResult بنية JSON من خلال أداة الإنهاء في حزمة تطوير البرامج (SDK). في حال تعذّر تحليل الردّ، تحاول سلسلة الاحتياط تحليل text() كملف JSON، ثم تعرض النص الأولي.
الإجراء الاحتياطي للمصادقة: يستخدم GEMINI_API_KEY إذا كان متاحًا، وإلا يعود إلى Vertex AI من خلال بيانات الاعتماد التلقائية للتطبيق.
إخراج الملف: يكتب النتائج بتنسيق Markdown إلى code_review.md، ويقرأ GitHub Action هذا الملف وينشره كتعليق على طلب السحب لاحقًا.

اختبار وكيل المراجعات

اختبِر من جذر المشروع. سيقرأ حزمة تطوير البرامج (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

6. Case 2 : Automated Review with Antigravity SDK - Part 2 ( Configuring Github Actions)

قبل البدء، لنحذف ملف 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
            });

سيتم تشغيل سير العمل تلقائيًا عند فتح طلب سحب أو تعديله. يتم استخراج فرع طلب السحب مع سجلّ git الكامل (المطلوب لـ git diff main...HEAD)، وتشغيل وكيل المراجعة الذي يكتب النتائج في code_review.md، ونشر محتوى الملف كتعليق على طلب السحب.

لنلتزم الآن بجميع التغييرات ونرسلها إلى مستودع GitHub البعيد، فنحن على استعداد لاختبار عملية الدمج هذه.

git add .
git commit -m "Add AI code security-quality review agent and GitHub Action"
git push origin feature/bulk-operations

7. الحالة 2 : المراجعة الآلية باستخدام Antigravity SDK - الجزء 3 (اختبار المراجعة الآلية للرمز البرمجي)

الآن، ننتقل إلى صفحة الويب الخاصة بالمستودع المتفرّع https://github.com/<YOUR_GITHUB_USERNAME>/leads-crm-app-demo وننقر على Settings

بعد ذلك، في اللوحة اليمنى، ابحث عن Secrets and variables وانقر على Actions

بعد ذلك، انقر على New repository secret لإعداد GEMINI_API_KEY secret.

بعد ذلك، انقر على Pull Request وأنشئ طلب سحب جديدًا من الفرع feature/bulk_operations إلى الفرع main في المستودع الخاص بك.

بعد إنشاء طلب السحب، سيتم تشغيل Github Actions التي يمكنك فحصها في قائمة Checks أو بالقرب من الزر Merge pull request.

يمكنك النقر على "الإجراءات" الجارية للاطّلاع على التفاصيل، وعند الانتهاء، سيتم نشر نتائج المراجعة كتعليق على طلب السحب كما هو موضّح أدناه.

8. الخاتمة

تهانينا!

لقد أنشأت سيرَي عمل كاملَين لمراجعة الرموز البرمجية بهدف رصد الثغرات الأمنية في الميزات التي تتضمّن رموزًا برمجية:

الحالة 1 (تفاعلية): راجعت Antigravity CLI مع مهارات الوكيل فرقًا في فرع ميزة، وحدّدت ثغرة حقن لغة الاستعلامات البنيوية (SQL) وغيرها من الثغرات الأمنية، وأصلحتها باتّباع أنماط OWASP، وأنتجت طلب سحب نظيفًا.
الحالة 2 (آلية): شغّلت حزمة تطوير البرامج (SDK) من Antigravity إحدى ميزات GitHub التي تراجع تلقائيًا كل طلب سحب، وتنشر نتائج الأمان المنظَّمة كتعليقات على طلب السحب.

ما تعلّمته

كيف يؤدي ترميز المشاعر إلى حدوث مخاطر أمنية ولماذا ترصد المراجعة المبرمَجة الأخطاء التي لا ترصدها المراجعة اليدوية؟
كيفية تثبيت مهارات الوكيل واستخدامها لمنح Antigravity CLI خبرة أمنية منظَّمة
كيفية مراجعة الاختلاف بين فرع الميزة والفرع الرئيسي بشكل تفاعلي، وحلّ المشاكل، وإنشاء طلب سحب نظيف
كيفية إنشاء وكيل مراجعة للقراءة فقط باستخدام Antigravity SDK من خلال سياسات الرفض التلقائي وخطافات مراحل النشاط
طريقة تنفيذ مسار مراجعة مبرمَجة كإجراء GitHub مع إمكانية المتابعة التفاعلية

إخلاء مساحة

إغلاق طلبات الدمج

انتقِل إلى كل طلب سحب في نسختك المتفرعة على GitHub وانقر على إغلاق طلب السحب. لا تدمج طلب السحب feature/bulk-operations، لأنّه لا يزال يحتوي على الرمز البرمجي المعرَّض للاختراق الذي لم يتم تصحيحه.

حذف المستودع المتفرّع (اختياري)

إذا لم تعُد بحاجة إلى النسخة المتفرّعة، انتقِل إلى نسختك المتفرّعة على GitHub: الإعدادات -> انتقِل إلى منطقة الخطر -> حذف هذا المستودع.

الخطوات التالية

إضافات ومهارات Antigravity CLI: لإنشاء مهارات وإضافات مخصّصة
Antigravity CLI Permissions &Sandbox: سياسات الأدوات الدقيقة ووضع الحماية على مستوى نظام التشغيل
عمليات الربط والسياسات في حزمة Antigravity SDK: أنماط متقدّمة (الحدّ من المعدّل، واسترداد الأخطاء، والبرامج الوسيطة)
أمثلة على Antigravity SDK – agent_middleware.py لأنماط الإنتاج