# التطوير مع وكلاء الذكاء الاصطناعي

كل صفحة متوفرة أيضًا بصيغة `Markdown`. الملفات أدناه تعطي وكيل البرمجة الحقائق نفسها التي تعطيك إياها هذه الصفحات.

## ما يوجد هنا للآلات[​](#ما-يوجد-هنا-للآلات "رابط مباشر إلى ما يوجد هنا للآلات")

| المورد                 | العنوان                                                                   | استخدمه لـ                                                                                          |
| ---------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| الفهرس                 | `https://dzbuild.dev/llms.txt`                                            | قائمة الصفحات بسطر واحد لكل صفحة. ألصقها في محادثة أو وجّه وكيلاً إليها.                            |
| الموقع كله             | `https://dzbuild.dev/llms-full.txt`                                       | كل الصفحات في ملف `Markdown` واحد.                                                                  |
| أي صفحة بصيغة Markdown | عنوان الصفحة مع `.md`، مثل `https://dzbuild.dev/ar/oauth.md`              | صفحة واحدة دون قوائم التنقل. الصفحات الفرنسية والإنجليزية تعمل بالطريقة نفسها تحت `/fr/` وفي الجذر. |
| مهارة الوكيل           | `https://dzbuild.dev/skills/dzbuild-apps/SKILL.md`                        | الحقائق والقواعد التي يحتاجها الوكيل لبناء تطبيق `DZBuild`.                                         |
| قالب AGENTS.md         | `https://dzbuild.dev/agents/AGENTS.md`                                    | ملف بداية لمستودع تطبيقك.                                                                           |
| وصف OpenAPI            | `https://dzbuild.dev/openapi/dzbuild-apps-v1.json`                        | كل عملية يستطيع رمز التثبيت استدعاءها، مع معاملاتها وصلاحياتها وشكل ردودها.                         |
| التطبيق النموذجي       | [dzbuild-app-starter](https://github.com/DZBuild-com/dzbuild-app-starter) | ثلاثة قوالب `Cloudflare Worker` جاهزة ومثال بـ `Node.js`، ولكل منها اختبارات.                       |

تحمل كل صفحة `HTML` أيضاً الوسم `<link rel="alternate" type="text/markdown">` الذي يشير إلى نسختها `Markdown`، فيجد أي برنامج يقرأ الصفحة النسخة الخام بنفسه.

## أعطِ وكيلك المهارة[​](#أعطِ-وكيلك-المهارة "رابط مباشر إلى أعطِ وكيلك المهارة")

يتبع ملف المهارة صيغة `Agent Skills`: وصف قصير يخبر الوكيل متى يستخدمها، ثم التعليمات. يقرأ `Claude Code` المهارات من `.claude/skills/` في مشروعك أو من `~/.claude/skills/` على جهازك:

```
mkdir -p .claude/skills/dzbuild-apps

curl -sSf https://dzbuild.dev/skills/dzbuild-apps/SKILL.md -o .claude/skills/dzbuild-apps/SKILL.md
```

أما الوكلاء الذين يقرؤون ملف `AGENTS.md` في جذر المستودع (`Codex` و`Cursor` وغيرهما)، فابدأ من القالب وأبقِ قواعد مشروعك تحته:

```
curl -sSf https://dzbuild.dev/agents/AGENTS.md -o AGENTS.md
```

يكرر الملفان قواعد هذا الموقع، فيعمل وكيلك من الحقائق نفسها التي تعمل بها.

## أعطِ وكيلك التوثيق كخادم MCP[​](#أعطِ-وكيلك-التوثيق-كخادم-mcp "رابط مباشر إلى أعطِ وكيلك التوثيق كخادم MCP")

تعطي الحزمة `@dzbuild/docs-mcp` أي عميل `MCP` هذه الصفحات ومرجع الواجهة البرمجية، مقروءة من `dzbuild.dev`، دون أي بيانات اعتماد. تجد في صفحة [/agents/connect](https://dzbuild.dev/ar/ar/agents/connect) الأمر أو الإعداد الخاص بـ `Claude Code` و`Codex` و`Cursor` و`Claude Desktop`.

## اسأل عن صفحة واحدة[​](#اسأل-عن-صفحة-واحدة "رابط مباشر إلى اسأل عن صفحة واحدة")

تحت كل صفحة شريط فيه **عرض بصيغة Markdown** و**نسخ Markdown** و**فتح في ChatGPT** و**فتح في Claude**. يفتح الخياران الأخيران محادثة جديدة تبدأ بقراءة تلك الصفحة. الرسالة التي تُرسل هي:

```
Read https://dzbuild.dev/ar/oauth.md so I can ask questions about it.
```

وإذا كانت لديك مهمة لا سؤال، فأعطِ الوكيل الفهرس والمهارة معاً، ثم صف ما يفعله التطبيق للتاجر:

```
Read https://dzbuild.dev/llms.txt and https://dzbuild.dev/skills/dzbuild-apps/SKILL.md.

Build a DZBuild app in Node.js that installs on a store through the OAuth flow,

stores one token per store, verifies webhooks, and posts a message to our Slack

channel when an order is confirmed. Secrets come from environment variables.
```

## توليد عميل من وصف OpenAPI[​](#توليد-عميل-من-وصف-openapi "رابط مباشر إلى توليد عميل من وصف OpenAPI")

الوصف بصيغة `OpenAPI 3.1`. استورده في `Postman` أو `Insomnia`، أو ولّد الأنواع وعميلاً:

```
curl -sO https://dzbuild.dev/openapi/dzbuild-apps-v1.json

npx openapi-typescript dzbuild-apps-v1.json -o dzbuild-apps-v1.d.ts
```

يسرد مخطط الأمان `dzOAuth` في الملف كل صلاحية مع وصفها. يعلن الملف أن الخادم هو `https://api.dzbuild.app`، وهو المضيف الذي يستدعيه تطبيقك.

## أبقِ الأسرار خارج المحادثة[​](#أبقِ-الأسرار-خارج-المحادثة "رابط مباشر إلى أبقِ الأسرار خارج المحادثة")

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

* يعيش سرّ العميل وسرّ التوقيع وكل رمز تثبيت في متغيرات البيئة أو مخزن أسرار على خادمك. لا تلصقها في رسالة أو مستودع أو سطر سجل.
* إذا وصل سرّ إلى محادثة أو `commit`، فجدّده من منصة المطورين. يتوقف سرّ العميل القديم فوراً؛ تبقى الرموز الصادرة تعمل، وتجديد سرّ التوقيع يغيّره لكل التثبيتات دفعة واحدة، فانشر القيمة الجديدة فوراً.
* يجب ألا يسجّل الوكيل الدخول إلى لوحة تحكم `DZBuild` باسم التاجر، ولا يؤتمتها، ولا يستخرج صفحات المتاجر. تصل بيانات المتجر عبر واجهة `REST` وإشعارات `webhook` فقط، كما تنص [قواعد الأمان](https://dzbuild.dev/ar/ar/security.md).
* تُقارن روابط إعادة التوجيه حرفاً بحرف. سجّل في منصة المطورين الرابط الدقيق الذي ترسله شيفرتك، بـ `https`، وبالشرطة المائلة نفسها في النهاية.

## ما يخطئ فيه المساعدون دون التوثيق[​](#ما-يخطئ-فيه-المساعدون-دون-التوثيق "رابط مباشر إلى ما يخطئ فيه المساعدون دون التوثيق")

تتكرر هذه الأخطاء عندما يُكتب التطبيق من معرفة عامة بـ `OAuth` أو `webhook`. الصفحات المرتبطة تحسم كل واحد منها.

* توقّع `expires_in` ورمز تحديث. رموز التثبيت لا تحمل أياً منهما؛ تعمل حتى يزيل التاجر التطبيق أو يثبّته من جديد. انظر [المفاهيم الأساسية](https://dzbuild.dev/ar/ar/concepts.md).
* إرسال عملية كتابة دون `Idempotency-Key`. ترد طلبات `POST` و`PATCH` و`DELETE` بـ `400` من دونه. انظر [حدود معدّل الطلبات](https://dzbuild.dev/ar/ar/rate-limits.md).
* تحليل متن `webhook` قبل فحص التوقيع. يغطي `HMAC` البايتات الخام، فالمتن المعاد تسلسله لا يطابق أبداً. انظر [إشعارات Webhook](https://dzbuild.dev/ar/ar/webhooks.md).
* تسجيل `webhook` عبر `POST /v1/webhooks`. تحصل التطبيقات هناك على `403`؛ يُضبط رابط `webhook` مرة واحدة على التطبيق في منصة المطورين. انظر [مرجع الواجهة البرمجية](https://dzbuild.dev/ar/ar/api-reference.md).
* طلب كل الصلاحيات. يرى التاجر سطراً لكل مورد على شاشة الموافقة، وتقارن المراجعة الصلاحيات بما يقوله وصف التطبيق. انظر [الصلاحيات](https://dzbuild.dev/ar/ar/scopes.md).
* بناء مبدّل متاجر داخل رمز واحد. يصل الرمز إلى متجره فقط؛ استخدم رمز كل متجر من قائمة `stores` في رد نقطة الرمز. انظر [OAuth](https://dzbuild.dev/ar/ar/oauth.md).