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

كل صفحة متوفرة أيضًا بصيغة 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	ثلاثة قوالب 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

تعطي الحزمة @dzbuild/docs-mcp أي عميل MCP هذه الصفحات ومرجع الواجهة البرمجية، مقروءة من dzbuild.dev، دون أي بيانات اعتماد. تجد في صفحة /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 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، وبالشرطة المائلة نفسها في النهاية.

ما يخطئ فيه المساعدون دون التوثيق

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

• توقّع expires_in ورمز تحديث. رموز التثبيت لا تحمل أياً منهما؛ تعمل حتى يزيل التاجر التطبيق أو يثبّته من جديد. انظر المفاهيم الأساسية.
• إرسال عملية كتابة دون Idempotency-Key. ترد طلبات POST وPATCH وDELETE بـ 400 من دونه. انظر حدود معدّل الطلبات.
• تحليل متن webhook قبل فحص التوقيع. يغطي HMAC البايتات الخام، فالمتن المعاد تسلسله لا يطابق أبداً. انظر إشعارات Webhook.
• تسجيل webhook عبر POST /v1/webhooks. تحصل التطبيقات هناك على 403؛ يُضبط رابط webhook مرة واحدة على التطبيق في منصة المطورين. انظر مرجع الواجهة البرمجية.
• طلب كل الصلاحيات. يرى التاجر سطراً لكل مورد على شاشة الموافقة، وتقارن المراجعة الصلاحيات بما يقوله وصف التطبيق. انظر الصلاحيات.
• بناء مبدّل متاجر داخل رمز واحد. يصل الرمز إلى متجره فقط؛ استخدم رمز كل متجر من قائمة stores في رد نقطة الرمز. انظر OAuth.