Кلاسيك التوثيق مصمم للإنسان: HTML مُعرض، تظليل للشفرة، شريط جانبي، بحث. لكن بشكل متزايد، ما يزور الـ docs ليس إنسانًا بل وكيلًا - Claude، Cursor، ChatGPT - الذي يزعجه كل هذا العرض. هو يحتاج نصًا نظيفًا وعقدًا قابلًا للقراءة الآلية.
صممنا التوثيق ليناسب الاثنين. إليك ما يحدث تحت الغطاء.
.md-نسخة لكل صفحة
Section titled “.md-نسخة لكل صفحة”كل صفحة من محتوى التوثيق لديها نسخة خام من Markdown بنفس المسار مع لاحقة .md. إذا فتحت /agent-setup - يوجد أيضًا /agent-setup.md، نفس النص بدون غلاف HTML، استيرادات MDX مقطوعة، تُعاد كـ text/markdown.
هذا يغذي عمليتين في قائمة الصفحة: Copy as Markdown (يضع النص النظيف في الحافظة لتلصقه في الدردشة مع النموذج) و View as Markdown (يفتح نسخة .md مباشرة). الوكيل لا يحتاج إلى تحليل DOM - هو يحصل على النص الجاهز.
قائمة منسدلة للإجراءات في أعلى الصفحة
Section titled “قائمة منسدلة للإجراءات في أعلى الصفحة”في الزاوية العلوية اليمنى من كل صفحة - قائمة إجراءات مصممة خصيصًا لتدفق عمل الوكيل:
- Copy as Markdown - نص الصفحة النظيف في الحافظة
- View as Markdown - فتح نسخة
.md - Open in ChatGPT - إرسال الصفحة إلى ChatGPT بنقرة واحدة
- Open in Claude - نفس الشيء لـ Claude
- Connect MCP - الانتقال إلى إعداد خادم MCP
llms.txt و llms-full.txt
Section titled “llms.txt و llms-full.txt”وفقًا للمعيار llmstxt.org نقدم ملفين:
/llms.txt- فهرس جميع صفحات التوثيق، مُجمّع في أقسام (API Reference, Use Cases, Examples, Products). خريطة للوكيل لتحديد من أين يبدأ./llms-full.txt- كل التوثيق في ملف نصي عادي واحد. للفهرسة غير المتصلة بالإنترنت في قاعدة متجهية أو لإدراجه مرة واحدة في سياق النموذج.
إذا كنت تبني RAG فوق API الخاص بنا، llms-full.txt هو مجموعة جاهزة، لا تحتاج إلى زحف الموقع.
مواصفات قابلة للقراءة الآلية
Section titled “مواصفات قابلة للقراءة الآلية”العقد يُقدم بعدة صيغ لأدوات مختلفة:
/v1/openapi.json- مواصفة OpenAPI 3.1 القياسية مع أمثلة و code-samples. لتوليد كود العملاء وأي أداة OpenAPI.- Swagger-аліаси -
/v1/swagger.json,/v1/v3/api-docsوغيرها تعيد توجيه 301 إلى الأصل، حتى لا تواجه الأدوات التي تبحث عن المسارات التقليدية مشاكل. - Postman-колекція -
/postman/astroway-api.jsonللاستيراد إلى Postman بنقرة واحدة.
/agent-setup لعملاء محددين
Section titled “/agent-setup لعملاء محددين”الصفحة /agent-setup/ ليست دليلًا عامًا واحدًا، بل تعليمات منفصلة لسبعة عملاء: Claude Desktop، Claude Code، Cursor، VS Code، Windsurf، Cline، Codex. كل واحدة توفر تكوينًا دقيقًا ومثال curl tools/list للتحقق من الاتصال قبل كتابة الكود.
تجربة داخلية try-it
Section titled “تجربة داخلية try-it”في صفحات دليل API، كل عملية تحتوي على ودجت try-it مدمج: تضع مفتاح sandbox، تعدل جسم الطلب، تضغط «Send» - وترى الاستجابة الفعلية دون مغادرة الـ docs. الطريقة، المسار، ومثال الجسم مأخوذة من snippet curl المُولد مسبقًا، لذا لا يقوم الودجت بإرسال طلبات إضافية إلى openapi.json.
لماذا كل هذا
Section titled “لماذا كل هذا”فكرة بسيطة: إذا كان منتجك هو API، يجب أن يكون التوثيق مناسبًا ليس فقط للقراءة بالعين، بل للاستهلاك من قبل الوكيل. نصف التكاملات اليوم تبدأ عندما يرسل المطور رابط الـ docs إلى Claude أو Cursor ويطلب «اتصل بهذا». جعلنا الأمر بحيث يكون في النهاية نصًا نظيفًا وعقدًا آليًا، وليس HTML يحتاج إلى تحليل.
جرّب بنفسك: افتح أي صفحة من الـ docs، اضغط على قائمة الإجراءات في أعلى اليمين - وسترى «Open in Claude».
نفس Swiss Ephemeris الموجود في Solar Fire - في 4 أسطر من الكود.
مفتاح مجاني بدون بطاقة. 5000 استدعاء شهرياً حتى الدفعة الأولى.