واجهات الوكلاء

• في المجموعة ذات الإصدارات، يسرد /llms.txt في الجذر صفحات الإصدار الافتراضي، فيصل الوكيل الذي يبدأ منه إلى التوثيق الحالي بطلب واحد، ويربط فهرس كل إصدار (/3.x/llms.txt و /2.x/llms.txt) مع حالته.
• في المجموعة متعددة اللغات، لكل لغة فهرسها: /ar/llms.txt و /ar/3.x/llms.txt.
• يبقى llms.txt صغيرًا. يبقى كل ملف دون agents.llms_txt_limit حرفًا (50,000 افتراضيًا، وهو حدّ AFDocs). وحين يتجاوزه إصدار، تنتقل كل مجموعة عليا في التنقل إلى ملف خاص بها، مثل /3.x/get-started/llms.txt، ويربطها الفهرس. ولا تُحذف الأوصاف إلا كحلّ أخير.
• يُبَثّ llms-full.txt تدفقيًا، فلا يحتاج الإصدار الكبير أبدًا إلى أن يتسع في الذاكرة. ويحوّل /llms-full.txt في جذر المجموعة ذات الإصدارات إلى ملف الإصدار الافتراضي. وبعد agents.llms_full_limit حرفًا (400,000 افتراضيًا) ينقسم الإصدار حسب مجموعات التنقل، مثل llms.txt، وكل ما يُستبعد يُذكر برابط، ولا يُقصّ بصمت أبدًا. وتبقى نسخ Markdown و MCP الطريقة الأفضل لقراءة صفحة واحدة.

لا تستخدم ترويسته إلا مفاتيح Agent Skills القابلة للنقل، name و description، فيستطيع أي وكيل تحميله.

---
name: larecipe
description: 'Use when working with LaRecipe: ... Explains how to search and read the LaRecipe docs (MCP tools, llms.txt and a Markdown version of every page) and lists the key pages.'
---

# LaRecipe

## Read the docs

1. Search first: call `search_docs` on the MCP server at https://larecipe.saleem.dev/mcp, or scan the index at https://larecipe.saleem.dev/llms.txt.
2. Read whole pages as Markdown: call `read_page`, or add `.md` to any page URL.
3. Answer from the pages you read, and cite their URLs.

يمكن لمجموعة المستودع أن تقدّم مهاراتها الخاصة في مجلد skills/ في جذر توثيقها، مجلد لكل مهارة:

docs/
├── larecipe.json
├── skills/
│   └── billing-integration/
│       ├── SKILL.md
│       └── references/
│           └── webhooks.md
└── 3.x/

تُقدَّم كل مهارة في /skills/{name}/SKILL.md، مع ملفات references/ و scripts/ و assets/ بجوارها. والمهارة المكتوبة بيد التي تحمل اسم المهارة المولَّدة تحلّ محل skill.md. ويفحص php artisan larecipe:validate كل SKILL.md وفق مواصفة Agent Skills (skills.spec).

يسرد /.well-known/agent-skills/index.json كل مهارة لكل مجموعة عامة في الموقع، كلٌّ منها مع رابطها وبصمة sha256 للبايتات المقدَّمة بالضبط، فتستطيع أدوات مثل npx skills add https://larecipe.saleem.dev أن تجدها وتتحقق منها.

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "larecipe",
      "type": "skill-md",
      "description": "Use when working with LaRecipe: ...",
      "url": "https://larecipe.saleem.dev/skill.md",
      "digest": "sha256:b688d79694302d4ae0866b9c855ef418c38dae9714691a1e6065278581184c39"
    }
  ]
}

الرابط .md أو الطلب بـ text/markdown لصفحة غير موجودة يحصل على 404 حقيقي مع محتوى Markdown قصير: المسار الذي طلبه، وحتى خمس صفحات مشابهة من مرتّب نتائج البحث، وفهرس التوثيق.

# Page not found

There is no page at `/agents/mcp-server` in LaRecipe.

Similar pages:

- [The MCP server](https://larecipe.saleem.dev/3.x/agents/mcp.md): ...

Docs index: https://larecipe.saleem.dev/llms.txt

والصفحة الموجودة المخفية عن المستدعي تحصل على الإجابة نفسها بالضبط، فلا يؤكد الـ 404 أبدًا وجود صفحة خاصة. وطلبات HTML لصفحات غير موجودة تحصل على الاقتراحات نفسها في صفحة «غير موجودة».

كل استجابة لصفحة، HTML كانت أو Markdown، تحمل ترويسات توجّه الوكلاء إلى الواجهات الأخرى:

Vary: Accept
Link: <https://larecipe.saleem.dev/3.x/index.md>; rel="alternate"; type="text/markdown", <https://larecipe.saleem.dev/3.x/llms.txt>; rel="describedby"; type="text/plain", <https://larecipe.saleem.dev/mcp>; rel="mcp", <https://larecipe.saleem.dev/skill.md>; rel="describedby"; type="text/markdown"; title="skill"
ETag: "80ff5bd7412bd994f7dc"
Last-Modified: Sat, 17 Oct 2026 15:22:00 GMT

• تخبر Vary: Accept الذاكرات المؤقتة بأن الرابط نفسه يجيب بـ HTML أو Markdown.
• تعلن Link عن نسخة Markdown، و llms.txt الخاص بالإصدار، ونقطة نهاية MCP، و skill.md، لأي عميل يقرأ الترويسات. ولا يظهر الرابط إلا حين تكون واجهته مفعّلة.
• تسمح ETag و Last-Modified للوكلاء وللذاكرات المؤقتة بإعادة التحقق بتكلفة قليلة. والطلب الذي يحمل If-None-Match مطابقًا يحصل على 304.
• ويحوي متن كل صفحة أيضًا رابطًا إلى llms.txt الخاص بالإصدار، مخفيًا عن النظر وعن لوحة المفاتيح، للوكلاء الذين يقرؤون HTML ولا يقرؤون ترويساته.

ومدة التخزين المؤقت المسموحة لكل استجابة، للزوار والقرّاء المسجّلين والصفحات الخاصة، مذكورة في صفحة الأمان.

يسرد /sitemap.xml كل صفحة عامة في مجموعة عامة، مع lastmod وبدائل hreflang لترجماتها. وخريطة الموقع ملف عام، لذا لا تسرد إلا ما يجوز للزائر رؤيته: تجيب المجموعات الخاصة بـ 404، وتُستبعد الإصدارات الخاصة والصفحات الخاصة والصفحات المخفية وصفحات noindex.

الوكلاء الذين يستطيعون جلب رابط لكن لا يملكون عميل MCP يستطيعون البحث عبر GET /ask?q= (وفي المجموعة ذات البادئة، /docs/ask?q=). وهي متوقفة افتراضيًا؛ فعّلها بـ agents.ask_endpoint:

// config/larecipe.php
'agents' => [
    'ask_endpoint' => true,
],

تجيب بصفحات مرتّبة بصيغة JSON (title و url و markdown_url و heading و snippet و description و score)، باستخدام المرتّب نفسه وقواعد الوصول نفسها التي تستخدمها أداة MCP المسمّاة search_docs. و version و locale و limit (حتى 20) معاملات استعلام اختيارية.

كل جلب لهذه الملفات يطلق حدث Laravel (MarkdownServed و LlmsTxtServed و SkillServed) مع نوع الطلب، فتصل حركة الوكلاء التي لا تراها التحليلات في المتصفح أبدًا إلى أدواتك. راجع التحليلات والأحداث.

ويقيّم php artisan larecipe:doctor كل هذا من داخل التطبيق، كما يقيّمه AFDocs من خارجه: تطابق Markdown، وحجم llms.txt وروابطه، وسلوك 404، والترويسات، وإعادات التوجيه. راجع التحقق و doctor.