التحقق و doctor

فحصان للقراءة فقط، من دون ذكاء اصطناعي. شغّل larecipe:validate بعد كل تغيير في التوثيق لتتأكد من أنه صحيح، و larecipe:doctor بعد النشر لتتأكد مما يحصل عليه الوكلاء من تطبيقك.

php artisan larecipe:validate
php artisan larecipe:doctor

يقرأ larecipe:validate كل صفحة عبر أداة التصيير الحقيقية، ويبلّغ عن الروابط المعطّلة، وأخطاء المخطط، والمكوّنات المجهولة، والمقتطفات المفقودة، والمراجع الحية التي لم تعد تُحَل، وغير ذلك. ويخرج بالرمز 1 حين يجد خطأً، فيستطيع CI أن يتوقف عنده. أما التحذيرات فلا تُفشله أبدًا. ويشغّله وكيل البرمجة قبل كل push.

كل مشكلة تذكر مستواها وقاعدتها وصفحتها وسطرها، مع إصلاح حين يعرف LaRecipe إصلاحًا:

  ERROR  links.broken  3.x/agents/mcp line 220
         Link to ../sources/docs-migrations.md: there is no page at "sources/docs-migrations".
         Fix: Fix the link, or write the page it points to.

هذه المشكلة من هذا الموقع نفسه، أثناء كتابة هذا التوثيق: الصفحة التي يشير إليها الرابط كانت التالية في الدور.

larecipe:validate

من دون خيارات، يفحص كل إصدار وكل لغة في كل مجموعة توثيق. ضيّق نطاقه، أو اطلب التقرير الذي يقرؤه الوكلاء:

php artisan larecipe:validate --set=docs --docs-version=3.x
php artisan larecipe:validate --json

خيار الإصدار هو --docs-version لأن Symfony يحجز --version للتطبيق. وإن طلبت مجموعة أو إصدارًا غير موجود، يخرج الأمر بالرمز 2.

لكل مشكلة معرّف قاعدة ثابت، مثل links.broken أو components.unknown. ولا يختلف التحقق والتصيير أبدًا: قواعد المكوّنات والمقتطفات والمراجع والعناصر النائبة تأتي مباشرة من أداة التصيير، التي تبلّغ عن كل مشكلة تصادفها أثناء تصيير الصفحة.

{
    "ok": false,
    "summary": { "pages": 41, "errors": 48, "warnings": 3 },
    "issues": [
        {
            "level": "error",
            "rule": "links.broken",
            "set": "docs",
            "page": "3.x/operate/validation",
            "file": "3.x/operate/validation.md",
            "line": 8,
            "message": "Link to caching.md#the-cache-stor: anchor #the-cache-stor not found.",
            "fix": "Use #the-cache-store."
        }
    ]
}

php artisan larecipe:validate [--set [SET]] [--docs-version [DOCS-VERSION]] [--json]

في CI

تكفي خطوة واحدة. رمز الخروج يُفشل المهمة عند الأخطاء:

- run: php artisan larecipe:validate

مع GitHub Actions، يستطيع المثبّت أن يكتب سير عمل جاهزًا يذكر أيضًا الصفحات التي تركها pull request قديمة: راجع فحص CI.

larecipe:doctor

يقيّم doctor كل مجموعة توثيق كما تقيّم فحوص AFDocs موقع توثيق للوكلاء، لكن من داخل تطبيقك: نسخ Markdown، و llms.txt وروابطه، وصفحات 404، وترويسات الاكتشاف، وعمليات إعادة التوجيه، و skill.md، ونقطة نهاية MCP، ومخزن الذاكرة المؤقتة. يرسل طلبات حقيقية عبر نواة HTTP في التطبيق، بوكيل المستخدم LaRecipe-Doctor/1.0، فلا يحتاج إلى خادم يعمل، ويرى الوسائط (middleware) والترويسات ومعالج الاستثناءات لديك تمامًا كما يراها وكيل. وتُبنى عناوين URL من APP_URL.

كل فحص إما ينجح أو يحذّر أو يفشل أو يُتخطّى، مع إصلاح لكل ملاحظة، وتحصل المجموعة على درجة من A إلى D. ولا يخرج الأمر بالرمز 1 إلا حين يفشل فحص. يحصره --set في مجموعة واحدة، ويطبع --json التقرير.

  docs http://127.0.0.1:8780/

  PASS  llms.txt: llms.txt is served and every index is under 50,000 characters.
  PASS  llms.txt links: 10 sampled llms.txt links resolve to Markdown.
  WARN  Markdown twins: Only 93% of the words on http://127.0.0.1:8780/3.x are in its Markdown.
        Fix: Give custom components a Markdown form (LaRecipe::component(...)->markdown(...)).
  PASS  Missing pages: A missing page is a real 404, with a Markdown body for agents.
  PASS  Discovery hints: Pages send Link headers to their Markdown twin and llms.txt, and link to llms.txt in the page.
  PASS  Redirects: 1 redirects land on a page.
  PASS  skill.md: skill.md is served as the "larecipe" skill.
  PASS  MCP endpoint: http://127.0.0.1:8780/mcp serves search_docs, read_page, list_pages, submit_feedback.
  SKIP  Cache store: Repository sets read from files; no cache store is needed.

  Agent readiness: A (94 / 100)

php artisan larecipe:doctor [--set [SET]] [--json]

أيهما ومتى

قد تجتاز الصفحة التحقق وتفشل مع ذلك في doctor: خادم وسيط يحذف ترويسات Link، أو معالج استثناءات يحوّل 404 إلى صفحة خطأ ناعمة، لا يظهران أبدًا في المحتوى.

التالي

• النشر: أين يأتي كل من الأمرين في عملية النشر.
• فحص CI: تعمّق مع سير عمل GitHub Actions الجاهز.
• واجهات الوكلاء: الملفات التي يفحصها doctor.