تشخيصات JSON في Zero: أخطاء مترجم مهيكلة للوكلاء

الميزة الرئيسية

أبرز ما يميّز Zero ليس قطعة صياغة. هو الطريقة التي يتحدّث بها المترجم مع من — أو ما — يقرأ مخرجاته.

شغّل برنامجًا معطوبًا عبر zero check --json وستحصل على تغذية يستطيع الوكيل قراءتها مباشرة:

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier",
            "line": 3,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

هذه كتلة صغيرة لكنها مُحمَّلة بالمعلومات. لنفكّك كل حقل والخيارات التصميمية وراءه.

تشريح التشخيص

التشخيص كائن مهيكل يصف مشكلة واحدة في المصدر. الحقول التقليدية:

• code — مُعرِّف مستقرّ (مثل NAM003). يعني الشيء نفسه دومًا، بصرف النظر عن إصدار المترجم.
• message — وصف مقروء للبشر. قد تتغيّر صياغته عبر الإصدارات؛ المعنى مُثبَّت بـ code، لا بالرسالة.
• line (وحقول موقع أخرى) — أين تقع المشكلة.
• repair — بيانات اختيارية مهيكلة تصف إصلاحًا يعتقد المترجم أنه سيحلّ التشخيص. شكل هذا الحقل نفسه موثَّق ومستقرّ.

الشكل العلوي يتضمّن قيمة منطقية ok للتشغيل ككلّ ومصفوفة diagnostics؛ حتى عندما ينجح التشغيل، قد تحتوي المصفوفة على تحذيرات أو ملاحظات.

رموز أخطاء مستقرّة

العقد على code هو الجزء الأكثر إثارة للدهشة. NAM003 اليوم تعني "مُعرِّف غير معروف". NAM003 الشهر القادم والعام القادم ستعني أيضًا "مُعرِّف غير معروف". يستطيع الوكلاء (والبشر) الاعتماد على ذلك.

هذا مهمّ لأن النماذج اللغوية والأدوات تميل إلى تخزين أو حفظ ما رأته. لو انجرف معنى NAM003 مع كل إصدار، لأصبح كل بحث مُخزَّن غير آمن. تثبيت الرمز يُبقي:

• بيانات تدريب الوكيل صالحة عبر الإصدارات.
• التوثيق قابلًا للفهرسة بحسب الرمز.
• خطوط أنابيب الأدوات مستقرّة.

‏message المقروءة للبشر حرّة في التغيّر مع تحسين الفريق للصياغة. code هو المُعرِّف الحامل للحمولة.

بيانات الإصلاح

حقل repair، عندما يكون حاضرًا، يُخبر المستهلك بنوع الإصلاح الذي يعتقد المترجم أنه سيعمل:

{
    "code": "NAM003",
    "message": "unknown identifier",
    "line": 3,
    "repair": { "id": "declare-missing-symbol" }
}

‏declare-missing-symbol هنا هو نوع الإصلاح — النية عالية المستوى. للحصول على التعديلات الفعلية، استدعِ zero fix --plan --json. يُعيد ذلك خطّة تتضمّن مسار الملف، ونطاقات البايتات للتعديل، والنصّ الجديد:

{
    "diagnostic": { "code": "NAM003", "line": 3 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

(أسماء الحقول والشكل الدقيق قد يختلفان في إصدار سلسلة أدواتك — المبدأ "بيانات مهيكلة، لا نصّ أدبي".)

الوكيل الذي يقرأ الخطّة لديه بضعة خيارات:

1. تطبيق التعديلات كما هي.
2. تطبيق التعديلات مع تعديلات.
3. رفض الخطّة واللجوء إلى إصلاح مختلف.

في كل حالة، يعمل الوكيل على بيانات مهيكلة بدلًا من محاولة تفسير اقتراح إنجليزي. هذا هو الفرق بين خطط الإصلاح وتلميحات "هل قصدت ...؟" في مترجم نموذجي.

كيف يستخدم الوكيل هذا فعليًا

حلقة مبسَّطة من البداية إلى النهاية قد يُشغّلها الوكيل:

1. يُولّد أو يُعدّل ملف Zero.
2. يُشغّل zero check --json ضدّه.
3. إن كانت النتيجة { "ok": true, ... }، يمضي قدمًا.
4. وإلّا، لكل تشخيص:
   • يبحث عن code لفهم ما هو الخطأ (بـ zero explain أو جدول محلي).
   • إن قُدّم repair وبدا آمنًا، يستدعي zero fix --plan --json للحصول على التعديلات.
   • يُطبّق (أو يحاكي) التعديلات.
5. يعود إلى الخطوة 2.

قارن هذا بالعمل من رسالة أدبية: على الوكيل تحليل النصّ الإنجليزي، واستخراج رقم سطر محتمل، وتخمين نوع الإصلاح، واستنتاج نصّ الإدراج أو الاستبدال الدقيق. كل خطوة ضبابية. مسار JSON يستبدل كل خطوة ببحث في مخطّط موثَّق.

أبعد من الأخطاء: الرسم البياني والحجم

‏--json ليس فقط للتشخيصات. أوامر أخرى تكشف بيانات مهيكلة بنفس الطريقة:

• zero graph --json — يُصدر رسم اعتماديات الحزمة كبيانات مهيكلة. مفيد لفهم ما يعتمد على ماذا، وللوكلاء الذين يريدون الاستدلال على مواقع الاستدعاء قبل لمسها.
• zero size --json — يُبلّغ بحجم المنتجات المُترجَمة على القرص، مُفصَّلًا بحسب الهدف. البيانات نفسها التي يراها البشر في zero size، لكن قابلة للتحليل.

هذه الأشكال جزء من التصميم: في أي وقت يكون لدى المترجم بيانات مفيدة، تكون متاحة كـ JSON لتستهلكها الأدوات دون كشط الشاشة.

كيف يبدو المخطّط

أسماء الحقول والأشكال الدقيقة موثَّقة في مستودع Zero وستتطوّر ما دام المشروع قبل الإصدار 1.0. الفئات التي تستطيع توقّعها:

• بيانات التشغيل الوصفية — ok، version، التوقيت.
• التشخيصات — code، message، الموقع (ملف/سطر/عمود/نطاقات بايتات)، الخطورة (خطأ/تحذير/ملاحظة)، repair اختياري.
• خطط الإصلاح — عند الجلب، قائمة التعديلات المهيكلة.

إن كنت تبني أدوات على هذا السطح، فالنمط الآمن هو قراءة الحقول التي تعرفها، وتجاهل الحقول غير المعروفة بأناقة، واتّخاذ القرارات السلوكية بناءً على code.

جولة سريعة من البداية إلى النهاية

افترض أن مصدرك يستخدم مُعرِّفًا لم يُعلَن:

pub fun main(world: World) -> Void raises {
    check world.out.write(answer())   // 'answer' غير مُعرَّف في أي مكان
}

تشغيل zero check --json يُنتج شيئًا مثل:

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier 'answer'",
            "line": 2,
            "column": 27,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

‏zero fix --plan --json يُعيد التعديل:

{
    "diagnostic": { "code": "NAM003", "line": 2 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

‏zero fix (بدون --plan) يُطبّق التعديل على المصدر، وبعدها يُعيد zero check ok: true. كل خطوة معاملة منفصلة قابلة للفحص.

لماذا يهمّ هذا أبعد من الوكلاء

الخصائص نفسها — مخرجات مهيكلة، ورموز مستقرّة، وخطط إصلاح — تجعل الحياة أسهل أيضًا لـ:

• المحرّرات وبيئات التطوير المتكاملة. خطوط متعرّجة ولمبات تعمل على مُعرِّفات repair بدلًا من نصّ مُحلَّل.
• خطوط CI. الإخفاقات تُسجَّل بـ code لسهولة البحث ولوحات المعلومات.
• أدوات تعديل الشيفرة. إصلاحات بالجملة تستهدف رمزًا، لا تعبيرًا نمطيًا على الرسائل.

صُمّم النظام مع وضع الوكلاء في الذهن، لكن الأدوات الموجَّهة للبشر تنال نفس الفوائد.

التالي: التصميم الموجَّه للوكلاء

نظام التشخيص هو المثال الأكثر ملموسية على فلسفة Zero الموجَّهة للوكلاء. التوثيق التالي، التصميم الموجَّه للوكلاء، يبتعد قليلًا إلى المبادئ الكامنة — مساحة سطحية صغيرة، أدوات حتمية، تأثيرات صريحة — وكيف يكسب كلٌّ منها مكانه.