البناء على زد بأدوات البرمجة بالذكاء الاصطناعي: التوثيق و Server MCP وAgent Skill

ثلاث طرق لتعطي الـ Agent الخاص بك سياق زد

وكلاء البرمجة بالذكاء الاصطناعي يكتبون كود زد أسرع عندما يقرؤون توثيق زد بدل التخمين من معرفتهم العامة. وتوفر زد ثلاث طرق لتعطيهم هذا السياق:

• التوثيق بصيغة Markdown: يقدّم docs.zid.sa صفحاته كملفات .md، ويسردها في فهرس llms.txt.
• Server MCP للتوثيق zid-open-apis-mcp، ويتيح لأي بيئة تطوير تدعم MCP جلب التوثيق أثناء المهمة.
• Zid AI Agent Skill: مجموعة تعليمات مفتوحة المصدر تعلّم الـ Agent أنماط زد في OAuth وتعدد المتاجر ومعالجة الأخطاء.

توثيق يقرؤه الـ Agent الخاص بك مباشرة

الملف https://docs.zid.sa/llms.txt فهرس نصي للتوثيق من جزأين، Docs وAPI Docs، وكل عنصر فيه معنون بموقعه في قائمة التوثيق. وكل عنصر يربط بنسخة Markdown من الصفحة، وكثير من عناصر الـ API يضم وصفًا للنقطة في سطر واحد.

ونسخة .md من صفحة أي نقطة تتضمن تعريف OpenAPI الخاص بها: الطريقة والمسار والـ Headers المطلوبة و Scope OAuth وأمثلة الاستجابات. وهذا بالضبط ما يحتاجه الـ Agent، بلا HTML حوله.

# فهرس صفحات التوثيق، وكل صفحة مربوطة بنسخة .md
curl -sL https://docs.zid.sa/llms.txt

# صفحة نقطة واحدة بصيغة Markdown (هنا نقطة Me من Account API)
curl -sL https://docs.zid.sa/me-33664055e0.md

وعمليًا، ضع رابط .md للنقطة في طلبك واطلب من الـ Agent أن يلتزم به. وهو الأسلوب نفسه الذي تستخدمه زد في طلبات ترحيل الثيمات، إذ تسرد روابط التوثيق التي يعمل الـ Agent انطلاقًا منها.

Server MCP للتوثيق

صفحة Our custom MCP server توثّق الإعداد. المتطلبات: Node.js بالإصدار 18 أو أعلى (ويُنصح بأحدث إصدار LTS)، وبيئة تطوير تدعم MCP. وتذكر الصفحة Cursor وVS Code مع إضافة Cline، وغيرهما. أضف الـ Server إلى ملف JSON الخاص بـ Servers MCP في بيئتك:

{
  "mcpServers": {
    "zid-open-apis-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "zid-open-apis-mcp"
      ]
    }
  }
}

وللتحقق، اسأل الذكاء الاصطناعي في وضع Agent: Based on the open apis doc, explain how merchant onboarding works. ويعمل الاتصال إذا استند الرد إلى توثيق الـ API. ولا تذكر الصفحة خطوات خاصة بأدوات أخرى، ففي أي عميل MCP آخر أضف الأمر نفسه npx -y zid-open-apis-mcp من إعدادات MCP في ذلك العميل.

Zid AI Agent Skill

أعلنت زد عن المهارة في سجل تحديثات الشركاء في 8 سبتمبر 2026، مفتوحة المصدر ومتاحة عبر توثيق زد وGitHub. وهي مكتوبة بـ Markdown فقط، بلا بيئة تشغيل أو SDK أو حزمة تثبّتها. نقطة الدخول هي SKILL.md، وتدعمها ملفات مرجعية لا يحمّلها الـ Agent إلا عند الحاجة: oauth-flow.md وmulti-tenant-architecture.md وerror-handling.md وendpoint-index.md وtroubleshooting-tools.md.

ولتثبيتها في Claude Code، انسخها إلى مجلد المهارات في المشروع أو المجلد العام، ثم أعد تشغيل Claude Code أو أعد تحميله:

# للمشروع الحالي (من جذر المشروع)
git clone https://github.com/zidsa/zid-agent-skill.git .claude/skills/zid-api-integration

# أو لكل المشاريع
git clone https://github.com/zidsa/zid-agent-skill.git ~/.claude/skills/zid-api-integration

• Claude: يشير التوثيق إلى ملف .skill مجهّز في Repository Zid Agent Skill على GitHub. ووقت كتابة هذا المقال لا توجد في الـ Repository إصدارات (releases) بعد، ويذكر ملف README أنه يمكنك ضغط المجلد بنفسك. ثم أضفه عبر مسار المهارات المخصصة في مساحة عملك.
• opencode والوكلاء الآخرون: انسخ الـ Repository أو نزّله في مجلد باسم zid-api-integration، ثم ضعه في المجلد الذي يقرأ منه الـ Agent المهارات.

ويذكر التوثيق أنه يمكن استخدام المهارة و Server MCP معًا. فالمهارة توجّه طريقة تصميم الـ Agent للتكامل وكتابته، و Server MCP يساعده على جلب التوثيق أثناء المهمة.

اجعل التوثيق المباشر هو المرجع

قاعدة المهارة نفسها: توثيق مطوّري زد هو المرجع، وإذا اختلف مع المهارة فالتوثيق هو الصحيح. وقبل أن يكتب الـ Agent أي API Call API أو يطلقه، اطلب منه مطابقته مع صفحة النقطة في التوثيق:

• طريقة HTTP والرابط.
• Scopes OAuth المطلوبة.
• Headers الـ Authentication: طلبات Merchant API تحتاج عمومًا Authorization وX-Manager-Token معًا، ولا تغني إحداهما عن الأخرى.
• Parameters المسار والاستعلام، وبنية جسم الطلب.
• بنية الاستجابة والقيم المدعومة وسلوك حدود الطلبات واستجابات الأخطاء.

وإذا أنتج الـ Agent نقطة لا تجدها في التوثيق فلا تستخدمها، واطلب منه أولًا أن يجدها في التوثيق المباشر. وإذا لم تُحمَّل المهارة، فتأكد أن المجلد يحتوي SKILL.md، وأن بنية المجلدات لم تُسطَّح أو يُغيَّر اسمها، وأنك أعدت تشغيل الـ Agent، أو قل له ببساطة: Use the Zid API integration skill for this task.

لمطوّري الثيمات

يطبّق دليل Moving to Vitrin Using LLMs الفكرة نفسها على الثيمات. ويقدّم طلبين جاهزين: الأول يحوّل ثيم Twig إلى Jinja اعتمادًا على قائمة روابط من توثيق Vitrin، والثاني يحدّث الإعدادات إلى مساراتها الجديدة store.settings.*.

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