Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

إنشاء مهارات Google Antigravity

1. مقدمة

‫Google Antigravity هي منصة تطوير قائمة على وكلاء الذكاء الاصطناعي ومصمَّمة لمساعدتك في التطوير في عصر الوكلاء. تعمل Antigravity كمركز تحكّم مركزي لوكلاء الذكاء الاصطناعي، وتوفّر منصة موحّدة لإطلاق أنشطتهم وتتبُّعها وتنظيمها.

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

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

تم تثبيت Antigravity وضبط إعداداته.
فهم أساسي لـ Google Antigravity يُنصح بإكمال الدرس التطبيقي حول الترميز: بدء استخدام Google Antigravity.

2. أهمية المهارات

تطوّرت وكلاء الذكاء الاصطناعي الحديثة من مستمعين بسيطين إلى محلّلين معقّدين يتكاملون مع أنظمة الملفات المحلية والأدوات الخارجية (عبر خوادم MCP). ومع ذلك، يؤدي تحميل الوكيل بشكل عشوائي بقواعد بيانات كاملة ومئات الأدوات إلى تشبّع السياق و "تضخّم الأدوات". حتى مع توفّر قدرة استيعاب كبيرة، يؤدي إدخال 40,000 إلى 50,000 رمز مميز من الأدوات غير المستخدَمة إلى الذاكرة النشطة إلى حدوث تأخير كبير وإهدار مالي و "تدهور في السياق"، ما يؤدي إلى تشوّش النموذج بسبب البيانات غير ذات الصلة.

الحل: مهارات الوكيل

لحلّ هذه المشكلة، قدّمت شركة Anthropic ميزة "مهارات الوكيل"، ما أدّى إلى تغيير البنية من تحميل السياق المتكامل إلى الكشف التدريجي. بدلاً من إجبار النموذج على "تذكُّر" كل سير عمل محدّد (مثل عمليات نقل البيانات أو عمليات تدقيق الأمان) في بداية الجلسة، يتم تجميع هذه الإمكانات في وحدات نمطية يمكن اكتشافها.

كيفية العمل

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

3- مهارات الوكيل وAntigravity

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

ما هي المهارة في Antigravity؟

في سياق Google Antigravity، المهارة هي حزمة مستندة إلى دليل تحتوي على ملف تعريف (SKILL.md) ومواد عرض اختيارية داعمة (نصوص برمجية ومراجع وقوالب).

وهي آلية لتوسيع إمكانات التطبيق عند الطلب.

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

المهارات مقابل المنظومة المتكاملة (الأدوات والقواعد وسير العمل)

في حين أنّ بروتوكول سياق النموذج (MCP) يعمل كـ "أيدي" الوكيل، ما يوفّر اتصالات قوية ودائمة بأنظمة خارجية مثل GitHub أو PostgreSQL، تعمل "المهارات" كـ "عقول" توجّه هذه الاتصالات.

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

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

4. إنشاء المهارات

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

بنية الدليل

يبدو دليل المهارات النموذجي على النحو التالي:

my-skill/
├── SKILL.md # The definition file
├── scripts/ # [Optional] Python, Bash, or Node scripts
     ├── run.py
     └── util.sh
├── references/ # [Optional] Documentation or templates
     └── api-docs.md
└── assets/ # [Optional] Static assets (images, logos)

يفصل هذا الهيكل بين المشاكل بفعالية. يتم فصل المنطق (scripts) عن التعليمات (SKILL.md) والمعرفة (references)، ما يعكس ممارسات هندسة البرامج العادية.

ملف تعريف SKILL.md

الملف SKILL.md هو العقل المدبّر للمهارة. فهي تحدّد للوكيل ماهية المهارة ومتى يجب استخدامها وكيفية تنفيذها.

يتألف من جزأين:

YAML Frontmatter
نص Markdown

YAML Frontmatter

هذه هي طبقة البيانات الوصفية. وهو الجزء الوحيد من المهارة الذي يتم فهرسته بواسطة جهاز التوجيه عالي المستوى الخاص بالوكيل. عندما يرسل المستخدم طلبًا، يطابق الوكيل الطلب دلاليًا مع حقول الوصف الخاصة بجميع المهارات المتاحة.

---
name: database-inspector
description: Use this skill when the user asks to query the database, check table schemas, or inspect user data in the local PostgreSQL instance.
---

الحقول الرئيسية:

الاسم: هذا الحقل غير إلزامي. يجب أن يكون المعرّف فريدًا ضمن النطاق. يُسمح باستخدام الأحرف الصغيرة والواصلات (مثل postgres-query وpr-reviewer). إذا لم يتم توفيرها، سيتم ضبطها تلقائيًا على اسم الدليل.
الوصف: هذا الحقل إلزامي وهو الأهم. وهي تعمل كـ "عبارة التفعيل". يجب أن يكون الوصف كافيًا لكي تتعرّف نماذج اللغات الكبيرة على الصلة الدلالية. الوصف الغامض، مثل "أدوات قاعدة البيانات"، غير كافٍ. وصف دقيق مثل "تنفيذ طلبات بحث SQL للقراءة فقط في قاعدة بيانات PostgreSQL المحلية لاسترداد بيانات المستخدم أو المعاملات يضمن خيار "استخدام هذا الخيار لتصحيح أخطاء حالات البيانات" أن يتم اختيار المهارة بشكل صحيح.

The Markdown Body

يحتوي النص على التعليمات. هذه هي "هندسة الطلبات" التي يتم حفظها في ملف. عند تفعيل المهارة، يتم إدخال هذا المحتوى في قدرة استيعاب الوكيل.

يجب أن يتضمّن نص الرسالة ما يلي:

الهدف: بيان واضح لما تحقّقه المهارة.
التعليمات: منطق مفصّل.
أمثلة: أمثلة قليلة على المدخلات والمخرجات لتوجيه أداء النموذج
القيود: قواعد "عدم التنفيذ" (مثل "عدم تنفيذ طلبات بحث DELETE").

مثال على نص ملف SKILL.md:

Database Inspector

Goal
To safely query the local database and provide insights on the current data state.

Instructions
- Analyze the user's natural language request to understand the data need.
- Formulate a valid SQL query.
 - CRITICAL: Only SELECT statements are allowed.
- Use the script scripts/query_runner.py to execute the SQL.
 - Command: python scripts/query_runner.py "SELECT * FROM..."
- Present the results in a Markdown table.

Constraints
- Never output raw user passwords or API keys.
- If the query returns > 50 rows, summarize the data instead of listing it all.

دمج النصوص البرمجية

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

يتم وضع النصوص في الدليل الفرعي scripts/. تشير SKILL.md إليها من خلال المسار النسبي.

5- مهارات التأليف

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

يمكنك تنزيل المهارات من مستودع Github هنا: https://github.com/rominirani/antigravity-skills.

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

استخدام Antigravity أو Antigravity CLI

يمكن تحديد المهارات على مستويين، ما يتيح استخدام المهارات الخاصة بالمشاريع والمستخدمين، أي المهارات العامة:

النطاق العام (~/.gemini/config/skills/): متاح في جميع منتجات Antigravity (‫Antigravity وAntigravity IDE وAntigravity CLI) والمشاريع. تتوفّر هذه المهارات في جميع المشاريع على جهاز المستخدم. هذا الخيار مناسب للأدوات المساعدة العامة، مثل "تنسيق JSON" أو "إنشاء معرّفات فريدة عالميًا" أو "مراجعة نمط الرمز" أو الدمج مع أدوات الإنتاجية الشخصية.
نطاق المشروع/مساحة العمل (<project-root>/.agents/skills/): سيؤدي ذلك إلى إتاحة المهارة ضمن مشروع معيّن فقط. وهي مثالية للنصوص البرمجية الخاصة بالمشاريع، مثل التفعيل في بيئة معيّنة أو إدارة قاعدة البيانات لهذا التطبيق أو إنشاء رمز النص النموذجي لإطار عمل خاص.

تثبيت "المهارات" في Antigravity أو Antigravity CLI

في هذا البرنامج التعليمي، ما علينا سوى اتّباع الخطوات التالية (يمكنك اتّباع طريقتك أيضًا):

الخطوة 1: نفِّذ git clone من https://github.com/rominirani/antigravity-skills

الخطوة 2: استنادًا إلى ما إذا كنت تستخدم Antigravity أو Antigravity CLI، يمكنك الانتقال إلى المجلد antigravity-skills/skills_tutorial.

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

git-commit-formatter
license-header-adder
database-schema-validator
json-to-pydantic

في مجلد المهارات المستهدَفة للمنتج (نطاق المشروع أو النطاق العام).

الخطوة 4: إذا كنت تستخدم Antigravity أو Antigravity CLI ، انسخها إلى <project-root>/.agents/skills/ (نطاق المشروع).

إذا كنت قد أطلقت Antigravity، يمكنك طرح سؤال بسيط "ما هي المهارات المتاحة؟" وسيجيبك بالمعلومات نفسها. يمكنك الاطّلاع على المهارات الأربع المُدرَجة هناك. قد تتوفّر لك مهارات إضافية أيضًا، إذا كنت قد ثبّتها في بيئتك.

وبالمثل، إذا كنت تستخدم Antigravity CLI، يمكنك إدخال الأمر التالي /skills وسيتم عرض المهارات الأربع. في ما يلي عيّنة:

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

المستوى 1 : أداة التوجيه الأساسية ( git-commit-formatter)

لنعتبر هذا المثال بمثابة "مرحبًا بالعالم" في المهارات.

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

git-commit-formatter/
└── SKILL.md  (Instructions only)

يظهر الملف SKILL.md أدناه:

---
name: git-commit-formatter
description: Formats git commit messages according to Conventional Commits specification. Use this when the user asks to commit changes or write a commit message.
---

Git Commit Formatter Skill

When writing a git commit message, you MUST follow the Conventional Commits specification.

Format
`<type>[optional scope]: <description>`

Allowed Types
- **feat**: A new feature
- **fix**: A bug fix
- **docs**: Documentation only changes
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, etc)
- **refactor**: A code change that neither fixes a bug nor adds a feature
- **perf**: A code change that improves performance
- **test**: Adding missing tests or correcting existing tests
- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation

Instructions
1. Analyze the changes to determine the primary `type`.
2. Identify the `scope` if applicable (e.g., specific component or file).
3. Write a concise `description` in an imperative mood (e.g., "add feature" not "added feature").
4. If there are breaking changes, add a footer starting with `BREAKING CHANGE:`.

Example
`feat(auth): implement login with google`

كيفية تشغيل هذا المثال في Antigravity

تفترض الخطوات أدناه أنّ لديك Git متاحًا على جهازك المحلي وتم إعداده بشكل صحيح.

بافتراض أنّك شغّلت Antigravity أو Antigravity CLI، اتّبِع الخطوات التالية:

الخطوة 1: إعداد مستودع Git تجريبي

اطلب من الوكيل إعداد دليل نظيف ومعزول لاختبار عمليات Git.

طلبك:

Create a folder named git_test in the workspace, initialize a git repository inside it, and create an initial file auth.py with def login(): pass. Stage this file and make an initial commit.

سينشئ الوكيل الدليل، ويهيئ المستودع، ويجهّز الملف، ويحفظه مع رسالة مثل "initial commit".

الخطوة 2: إجراء تغيير في الرمز

اطلب من الوكيل تعديل الرمز ليكون هناك تغيير يمكن تنفيذه.

طلبك:

In the git_test folder, modify auth.py to add Google Login functionality.

سيعدّل الوكيل الملف لإضافة ميزة جديدة، ما يجعله جاهزًا لمرحلة الالتزام.

الخطوة 3: إعداد التغييرات وتنفيذها

فعِّل مهارة git-commit-formatter من خلال الطلب من الوكيل إعداد التغييرات وإنشاء عملية إيداع.

طلبك:

Stage the changes in the git_test folder and commit them. Make sure to format the commit message using the Conventional Commits skill.

سيشغّل الوكيل git add auth.py، ويحلّل الاختلاف لتحديد أنّه تمت إضافة ميزة جديدة إلى الوحدة auth، ويصيغ رسالة التزام تقليدية مثل feat(auth): implement google login قبل تشغيل git commit.

الخطوة 4: التحقّق من سجلّ Git

اطلب من الوكيل استرداد سجلّ git حتى تتمكّن من التأكّد من تسجيل عملية الإيداع المنسَّقة بنجاح.

طلبك:

Show me the git log in the git_test folder.

سيُشغّل الوكيل الأمر git log -n 5 ويعرض الناتج الذي يوضّح رسالة الالتزام المنسَّقة.

المستوى 2: استخدام مواد العرض (license-header-adder)

هذا هو نمط "المراجع".

قد يحتاج كل ملف مصدر في مشروع تابع لشركة إلى عنوان ترخيص Apache 2.0 محدّد يتألف من 20 سطرًا. إنّ وضع هذا النص الثابت مباشرةً في الطلب (أو SKILL.md) هو أمر غير فعّال. يستهلك الرموز المميزة في كل مرة تتم فيها فهرسة المهارة، وقد "يهلوس" النموذج أخطاء إملائية في النص القانوني. من الممارسات الجيدة نقل النص الثابت إلى ملف نص عادي في مجلد resources/. تطلب المهارة من الوكيل قراءة هذا الملف عند الحاجة فقط.

ستعثر على الملفات في المجلد license-header-adder ضمن الدليل skills.

license-header-adder/
├── SKILL.md
└── resources/
   └── HEADER_TEMPLATE.txt  (The heavy text)

يظهر الملف SKILL.md أدناه:

---
name: license-header-adder
description: Adds the standard open-source license header to new source files. Use involves creating new code files that require copyright attribution.
---

# License Header Adder Skill

This skill ensures that all new source files have the correct copyright header.

## Instructions

1. **Read the Template**:
  First, read the content of the header template file located at `resources/HEADER_TEMPLATE.txt`.

2. **Prepend to File**:
  When creating a new file (e.g., `.py`, `.java`, `.js`, `.ts`, `.go`), prepend the `target_file` content with the template content.

3. **Modify Comment Syntax**:
  - For C-style languages (Java, JS, TS, C++), keep the `/* ... */` block as is.
  - For Python, Shell, or YAML, convert the block to use `#` comments.
  - For HTML/XML, use `<!-- ... -->`.

كيفية تشغيل هذا المثال في Antigravity

بافتراض أنّك شغّلت Antigravity أو Antigravity CLI، اتّبِع الخطوات التالية:

الخطوة 1: إنشاء ملف Python باستخدام رمز نموذجي

طلبك:

Create a new file my_script.py with the following python code:

def hello():
   print("Hello, World!")

ما حدث (شرح): استدعى الوكيل أداة كتابة الملفات (write_to_file) لإنشاء ملف جديد باسم my_script.py مباشرةً في دليل مساحة العمل النشطة وكتابة دالة Python الأساسية فيه. بالإضافة إلى ذلك، أدّى الطلب إلى تفعيل المهارة "license-header-adder". عثر الوكيل على ملف نموذج الترخيص (HEADER_TEMPLATE.txt) وقرأه، وعدّل أسلوب التعليق من تعليقات على شكل كتل بأسلوب C (/* ... */) إلى تعليقات بأسلوب Python (#)، وأضافه في أعلى الملف باستخدام الأداة replace_file_content.

الخطوة 2: التحقّق من محتوى الملف

اطّلِع على الملف my_script.py. سيحتوي على عنوان الترخيص في الأعلى.

المستوى 3: التعلّم من خلال الأمثلة (json-to-pydantic)

نمط "التلقين ببضع أمثلة"

يتضمّن تحويل البيانات غير المنظَّمة (مثل استجابة JSON API) إلى رموز برمجية منظَّمة (مثل نماذج Pydantic) عشرات القرارات. كيف يجب تسمية الفئات؟ هل يجب استخدام Optional؟ ‫snake_case أو camelCase؟ إنّ كتابة هذه القواعد الخمسين باللغة الإنجليزية أمر مملّ وعُرضة للأخطاء.

النماذج اللغوية الكبيرة هي محركات مطابقة أنماط.

إنّ إنشاء مهارة باستخدام مثال ذهبي (Input -> Output) يكون غالبًا أكثر فعالية من التعليمات المطوّلة.

انتقِل إلى مجلد json-to-pydantic/ الذي يحتوي على ملفات المهارة، كما هو موضّح أدناه:

json-to-pydantic/
├── SKILL.md
└── examples/
   ├── input_data.json   (The Before State)
   └── output_model.py   (The After State)

يظهر الملف SKILL.md أدناه:

---
name: json-to-pydantic
description: Converts JSON data snippets into Python Pydantic data models.
---

# JSON to Pydantic Skill

This skill helps convert raw JSON data or API responses into structured, strongly-typed Python classes using Pydantic.

Instructions

1. **Analyze the Input**: Look at the JSON object provided by the user.
2. **Infer Types**:
  - `string` -> `str`
  - `number` -> `int` or `float`
  - `boolean` -> `bool`
  - `array` -> `List[Type]`
  - `null` -> `Optional[Type]`
  - Nested Objects -> Create a separate sub-class.
 
3. **Follow the Example**:
  Review `examples/` to see how to structure the output code. notice how nested dictionaries like `preferences` are extracted into their own class.
 
  - Input: `examples/input_data.json`
  - Output: `examples/output_model.py`

Style Guidelines
- Use `PascalCase` for class names.
- Use type hints (`List`, `Optional`) from `typing` module.
- If a field can be missing or null, default it to `None`.

في المجلد /examples، يوجد ملف JSON وملف الإخراج، أي ملف Python. يمكنك الاطّلاع على كليهما أدناه:

input_data.json

{
   "user_id": 12345,
   "username": "jdoe_88",
   "is_active": true,
   "preferences": {
       "theme": "dark",
       "notifications": [
           "email",
           "push"
       ]
   },
   "last_login": "2024-03-15T10:30:00Z",
   "meta_tags": null
}

output_model.py

from pydantic import BaseModel, Field
from typing import List, Optional

class Preferences(BaseModel):
   theme: str
   notifications: List[str]

class User(BaseModel):
   user_id: int
   username: str
   is_active: bool
   preferences: Preferences
   last_login: Optional[str] = None
   meta_tags: Optional[List[str]] = None

كيفية تشغيل هذا المثال في Antigravity

بافتراض أنّك شغّلت Antigravity أو Antigravity CLI، اتّبِع الخطوات التالية:

الخطوة 1: إنشاء ملف JSON يتضمّن بيانات نموذجية

اطلب من الوكيل إنشاء ملف جديد product.json يحتوي على حمولة JSON الأولية.

طلبك:

Create a new file product.json with the following JSON:

{
 "product": "Widget",
 "cost": 10.99,
 "stock": null
}

الخطوة 2: تحويل JSON إلى نموذج Pydantic

فعِّل مهارة json-to-pydantic لتحويل بيانات JSON إلى فئة Pydantic منظَّمة.

طلبك:

Convert the JSON in product.json to a Pydantic model and save it to product_model.py.

الخطوة 3: التحقّق من الناتج

اطّلِع على الملف product_model.py. سيحتوي على نموذج Pydantic المكتمل.

المستوى 4: المنطق الإجرائي (database-schema-validator)

هذا هو نمط "استخدام الأدوات".

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

لنفوّض عملية التحقّق هذه إلى نص برمجي مستند إلى بيانات محدّدة. ستوجّه database-schema-validator مهارتنا الوكيل لتشغيل نص Python البرمجي الذي كتبناه. يوفّر النص البرمجي قيمة ثنائية (صحيح/خطأ).

database-schema-validator/
├── SKILL.md
└── scripts/
   └── validate_schema.py  (The Validator)

يظهر الملف SKILL.md أدناه:

---
name: database-schema-validator
description: Validates SQL schema files for compliance with internal safety and naming policies.
---

# Database Schema Validator Skill

This skill ensures that all SQL files provided by the user comply with our strict database standards.

Policies Enforced
1. **Safety**: No `DROP TABLE` statements.
2. **Naming**: All tables must use `snake_case`.
3. **Structure**: Every table must have an `id` column as PRIMARY KEY.

Instructions

1. **Do not read the file manually** to check for errors. The rules are complex and easily missed by eye.
2. **Run the Validation Script**:
  Use the `run_command` tool to execute the python script provided in the `scripts/` folder against the user's file.
 
  `python scripts/validate_schema.py <path_to_user_file>`

3. **Interpret Output**:
  - If the script returns **exit code 0**: Tell the user the schema looks good.
  - If the script returns **exit code 1**: Report the specific error messages printed by the script to the user and suggest fixes.

يظهر الملف validate_schema.py أدناه:

import sys
import re

def validate_schema(filename):
   """
   Validates a SQL schema file against internal policy:
   1. Table names must be snake_case.
   2. Every table must have a primary key named 'id'.
   3. No 'DROP TABLE' statements allowed (safety).
   """
   try:
       with open(filename, 'r') as f:
           content = f.read()
          
       lines = content.split('\n')
       errors = []
      
       # Check 1: No DROP TABLE
       if re.search(r'DROP TABLE', content, re.IGNORECASE):
           errors.append("ERROR: 'DROP TABLE' statements are forbidden.")
          
       # Check 2 & 3: CREATE TABLE checks
       table_defs = re.finditer(r'CREATE TABLE\s+(?P<name>\w+)\s*\((?P<body>.*?)\);', content, re.DOTALL | re.IGNORECASE)
      
       for match in table_defs:
           table_name = match.group('name')
           body = match.group('body')
          
           # Snake case check
           if not re.match(r'^[a-z][a-z0-9_]*$', table_name):
               errors.append(f"ERROR: Table '{table_name}' must be snake_case.")
              
           # Primary key check
           if not re.search(r'\bid\b.*PRIMARY KEY', body, re.IGNORECASE):
               errors.append(f"ERROR: Table '{table_name}' is missing a primary key named 'id'.")

       if errors:
           for err in errors:
               print(err)
           sys.exit(1)
       else:
           print("Schema validation passed.")
           sys.exit(0)
          
   except FileNotFoundError:
       print(f"Error: File '{filename}' not found.")
       sys.exit(1)

if __name__ == "__main__":
   if len(sys.argv) != 2:
       print("Usage: python validate_schema.py <schema_file>")
       sys.exit(1)
      
   validate_schema(sys.argv[1])

كيفية تشغيل هذا المثال في Antigravity

بافتراض أنّك شغّلت Antigravity أو Antigravity CLI، اتّبِع الخطوات التالية:

الخطوة 1: إنشاء ملف JSON يتضمّن بيانات نموذجية

اطلب من الموظف إنشاء ملف جديد bad_schema.sql يحتوي على عدة انتهاكات للسياسة.

طلبك:

Create a new file bad_schema.sql with the following SQL:

DROP TABLE IF EXISTS legacy_users;

CREATE TABLE userProfile (
    id INT PRIMARY KEY,
    bio TEXT
);

CREATE TABLE posts (
    title TEXT,
    content TEXT,
    created_at TIMESTAMP
);

CREATE TABLE comments (
    id INT PRIMARY KEY,
    post_id INT,
    body TEXT
);

يخالف ملف المخطط أعلاه السياسات الثلاث: فهو يستخدم عبارة DROP TABLE محظورة، ويستخدم camelCase لاسم الجدول userProfile، وينسى المفتاح الأساسي id في الجدول posts.

الخطوة 2: التحقّق من صحة مخطط SQL

فعِّل مهارة database-schema-validator لتشغيل نص Python البرمجي الخاص بالتحقّق من صحة الملف.

طلبك:

Validate bad_schema.sql using the database-schema-validator skill.

الخطوة 3: التحقّق من الناتج

سيُبلغ الموظف عن تعذُّر تنفيذ العملية ويعرض الأخطاء المحدّدة التي رصدتها البرمجة النصية مباشرةً في المحادثة. يظهر الناتج النموذجي أدناه:

Suggested Fixes:

Remove the line DROP TABLE IF EXISTS legacy_users; as dropping tables is forbidden by safety policy.

Rename the table userProfile to use snake_case (e.g., user_profile).

Add a primary key column named id to the posts table definition.

6. مجموعة أدوات المطوّرين (مهارات واجهة سطر الأوامر للوكلاء)

نمط "الإجراء ومراحل النشاط"

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

بدلاً من إجبار مساعد الترميز على تخمين بنى الدليل أو كتابة إعدادات الوكيل النموذجية من البداية، تجمع مهارات واجهة سطر الأوامر للوكلاء خبرة دورة الحياة هذه في مهارات وكيل محددة.

توفّر مهارات Agent CLI (واجهة سطر الأوامر) أتمتة مبسطة تركّز على المطوّرين مباشرةً في نافذة الأوامر على جهازك، ما يقلّل الفجوة بين الرمز الأولي والتنفيذ المستقل. في حين تركّز حزمة تطوير الوكلاء (ADK) على إطار العمل الآلي، ما يمنحك حِزم تطوير البرامج وواجهات برمجة التطبيقات والمخططات الهيكلية لإنشاء وكلاء الذكاء الاصطناعي وتنسيقهم، توفّر مهارات Agent CLI القوة التشغيلية. تتيح هذه الأداة للمطوّرين إنشاء نماذج أولية للوكلاء واختبارها ونشرها محليًا باستخدام حلقات ملاحظات سريعة، مع تجاوز عبء واجهة المستخدم الثقيل تمامًا.

يمكن أن تعمل مهارات Agent CLI، عند ربطها بـ Google Cloud، كقناة مباشرة إلى البنية الأساسية على مستوى المؤسسة. بدلاً من النقر على وحدات التحكّم، يمكنك استخدام أوامر واجهة سطر الأوامر لتجميع عمليات سير عمل الوكيل على الفور وإدارة أذونات الوصول ونشرها في أنظمة Google Cloud المتكاملة (مثل Vertex AI أو Cloud Run). ويحوّل ذلك مهام بنية السحابة المعقّدة إلى أوامر بسيطة وقابلة للتكرار في الوحدة الطرفية، ما يسهّل كثيرًا دمج الوكلاء المستقلين في مسارات نشر الدمج المستمر/النشر المستمر الحالية.

كيفية التثبيت

تأكَّد من تثبيت Python 3.11+ وNode.js وأداة إدارة الحِزم uv. بعد ذلك، شغِّل أمر الإعداد في الوحدة الطرفية:

uvx google-agents-cli setup

يؤدي هذا الأمر إلى تثبيت ملف agents-cli الثنائي وتسجيل مهاراته المتخصصة في إنشاء نماذج أولية وتقييمها ضمن بيئة مساعد البرمجة.

ملاحظة: سيتم تثبيت المهارات في مجلد ~/.agents/skills، الذي يمكن لتطبيق Antigravity الاطّلاع عليه. إذا أردت رؤية هذه المهارات في واجهة سطر الأوامر Antigravity، عليك نقلها إلى المجلد ~/.gemini/antigravity-cli/skills (النطاق العام).

يمكنك التأكّد من تحميل المهارات في Antigravity من خلال السؤال ببساطة عن المهارات المتاحة. يظهر أدناه نموذج استجابة لمهارات Agent CLI التي ثبّتناها للتو.

جولة تفصيلية خطوة بخطوة

بعد اكتمال عملية uvx google-agents-cli setup، يمكنك تشغيل وكيل الذكاء الاصطناعي والتفاعل معه واختباره بالكامل على جهازك المحلي.

الخطوة 1: إنشاء مشروع وكيل جديد وتهيئته

نفِّذ أمر الإنشاء لإنشاء بنية موحّدة. بعد إنشاء المشروع، يجب تثبيت تبعياته قبل تنفيذ أي مهام.

# 1. Create a lightweight prototype project structure
agents-cli create weather-assistant --prototype --yes

# 2. Move into the directory and install required ADK dependencies
cd weather-assistant
agents-cli install

ما يحدث وراء الكواليس: يؤدي ذلك إلى إنشاء مساحة عمل نظيفة تتضمّن app/agent.py (التعليمات البرمجية الأساسية) وpyproject.toml (البيانات الوصفية للحزمة) وagents-cli-manifest.yaml (أداة تتبُّع المشروع).

الخطوة 2: تنفيذ طلب بحث تجريبي محلي

تنفيذ اختبار سريع ومباشر لسطر الأوامر على الوكيل تأكَّد من تصدير GEMINI_API_KEY في الجهاز إذا كنت لا تستخدم بيانات الاعتماد التلقائية للتطبيق (ADC) من Google Cloud. يمكنك الحصول على مفتاح Gemini API من هنا. بعد الحصول على المفتاح، يمكنك تصديره في الوحدة الطرفية باستخدام الأمر التالي:

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

أدخِل الأمر التالي في الوحدة الطرفية:

agents-cli run "How are you?"

ما يحدث وراء الكواليس: تعمل واجهة سطر الأوامر على تهيئة دورة حياة "حزمة تطوير الوكيل" (ADK) بالكامل في الذاكرة على جهازك. ويوجّه الطلب بشكل آمن من خلال بيانات الاعتماد المحلية ويسجّل الردّ على البث المباشر مباشرةً في سطر الأوامر.

الخطوة 3: بدء "ملعب الويب التفاعلي"

يمكنك تشغيل ساحة اللعب المضمّنة والمحلية المستندة إلى الويب للتفاعل مع وكيلك بشكل مرئي.

agents-cli playground

ما يحدث وراء الكواليس: تبدأ واجهة سطر الأوامر تشغيل خادم واجهة مستخدم على الويب في حزمة تطوير التطبيقات (ADK)، ويمكن الوصول إليه عادةً على http://localhost:8080 أو http://127.0.0.1:8000، مع إمكانية إعادة التحميل السريع. من واجهة الويب، انقر على التطبيق في القائمة المنسدلة اختيار تطبيق في أعلى الصفحة، وتفاعَل مع الوكيل في واجهة المحادثة على يسار تطبيق الويب.

7. تثبيت مهارات الوكيل باستخدام npx skills

‫npx skills هي أداة سطر أوامر طوّرتها Vercel Labs وتعمل كمدير حِزم لوكلاء الذكاء الاصطناعي (مثل Antigravity وClaude Code وGitHub Copilot وCursor وCline). وهي واجهة سطر الأوامر لمنظومة مهارات الوكيل المفتوحة.

إذا كنت تريد تنزيل "مهارات الوكيل" وتثبيتها باستخدام حزمة npx skills، يُرجى العِلم أنّها تضع "المهارات" في المجلد ~/.agents/skills. على الرغم من أنّ هذه الصفحة تشير إلى أنّ أدوات مثل Antigravity ستستند إلى المهارات من هذا المجلد، يُرجى العِلم أنّه في وقت كتابة هذه المقالة، تستند أداة Antigravity إلى المهارات من هذا المجلد، ولكن لا تستند إليها أداة Antigravity CLI. كما ذكرنا سابقًا، عليك نسخ هذه المهارات المثبَّتة في المجلد ~/.agents/skills إلى نطاق المشروع أو النطاق العام لمجلدات المهارات في Antigravity CLI، أي

نطاق المشروع: يقع في <project-root>/.agent/skills/.
النطاق العالمي: يقع في ~/.gemini/antigravity-cli/skills/.

8. تهانينا

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

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

أنت الآن على استعداد للسماح لـ Antigravity بالتعامل مع المهام الصعبة في مشاريعك وكتابة الرمز البرمجي بالطريقة التي تريدها.

الحصول على شارة "وكلاء الذكاء الاصطناعي في 5 أيام" على Kaggle

هل أكملت هذا المختبر كجزء من دورة تدريبية مكثّفة لمدة 5 أيام حول وكلاء الذكاء الاصطناعي: ترميز المشاعر باستخدام Google في Kaggle؟ احصل على شارة "وكلاء الذكاء الاصطناعي في 5 أيام".

9- المستندات المرجعية

درس تطبيقي حول الترميز : بدء استخدام Google Antigravity
الموقع الإلكتروني الرسمي : https://antigravity.google/
المستندات: https://antigravity.google/docs
تنزيل : https://antigravity.google/download
مستندات مهارات Antigravity: https://antigravity.google/docs/skills