דיאגנוסטיקות 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 היום פירושו "unknown identifier". NAM003 בחודש הבא ובשנה הבאה גם יהיה פירושו "unknown identifier". סוכנים (ובני אדם) יכולים לסמוך על זה.

זה חשוב כי מודלי שפה וכלים נוטים לשמור במטמון או לשנן את מה שראו. אם המשמעות של 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. לדחות את התוכנית ולחפש תיקון אחר.

בכל המקרים, הסוכן פועל על נתונים מובנים במקום לנסות לפרש הצעה באנגלית. זה ההבדל בין תוכניות תיקון לבין רמזי "did you mean ...?" בקומפיילר טיפוסי.

איך סוכן משתמש בזה בפועל

לולאה פשוטה מקצה לקצה שסוכן עשוי להריץ:

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, כך שקל לחפש אותם ולבנות מהם דשבורדים.
• כלי code-mod. תיקונים גורפים שמכוונים לקוד, לא לביטוי רגולרי על הודעות.

המערכת עוצבה עם סוכנים בראש, אבל גם כלים שמיועדים לבני אדם מקבלים את אותם יתרונות.

הבא בתור: עיצוב Agent-First

מערכת הדיאגנוסטיקות היא הדוגמה המוחשית ביותר לפילוסופיית ה-agent-first של Zero. המסמך הבא, עיצוב agent-first, מתרחק שוב אל העקרונות שבבסיס: משטח קטן, כלים דטרמיניסטיים, אפקטים מפורשים, ואיך כל אחד מהם מצדיק את מקומו.