Tutorial 3 Your First Agent Task ar

الدرس 3 · مهمتك الأولى مع الوكيل

🌎 اللغة: العربية — شاهد كل اللغات الـ33

الهدف: أضف أمرا جديدا كليا إلى الأداة — من البداية إلى النهاية — بتوجيه وكيلك. سنضيف lockedin endorse: يزكّي غرباء تماما لمهارات شبه مؤكد أنهم لا يملكونها. على طابع العلامة.

هذا قلب الدرس. ستتمرن على الحلقة الحقيقية: مواصفات ← اختبارات ← تنفيذ ← بوابة خضراء ← مراجعة.

← السابق: الدرس 2 كيف تعمل الشيفرة · التالي: الدرس 4 التوجيه والمراجعة

---

الخطوة 0 — قرّر كيف يبدو «المنجز»

قبل أن توجّه أي شيء، اكتب المواصفات بنفسك بلغة واضحة. الطلبات الغامضة تنتج شيفرة غامضة — من إنسان أو وكيل.

endorse يطبع 5–7 أسطر، كل سطر يزكّي شخصا مختارا عشوائيا (أعد استخدام مجمّع NAMES القائم) لأجل مهارة كلمة طنانة مختارة عشوائيا (مجمّع جديد). ينتهي بجملة ساخرة واحدة. يجب أن يكون قابلا للوصول عبر lockedin endorse، وعبر /endorse داخل الجلسة، وأن يظهر في help. كل العشوائية يجب أن تستخدم المساعدَين المُبَذَّرَين pick/shuffle حتى تبقى المخرجات حتمية. npm test يجب أن يبقى أخضر، وينبغي أن يوجد اختبار جديد يثبّت ثابتا واحدا على الأقل.

تلك الفقرة هي ما ستسلّمه للوكيل. لاحظ أنها تسمّي القيود من الفصل 2 (العشوائية المُبَذَّرة، وبوابة الاختبار، وعادة الثوابت).

الخطوة 1 — اطلب من الوكيل أن يخطط، لا أن يبرمج

ابدأ بطلب خطة. هذه فرصتك لالتقاط نهج سيئ قبل أن يتغير أي ملف.

«أريد إضافة أمر endorse إلى LockedIn CLI. إليك المواصفات: [paste your spec]. قبل كتابة الشيفرة، أخبرني أي الملفات ستغيّر وما نهجك، حتى أوافق عليه. اتبع الأنماط القائمة لأمر مثل connect.»

الخطة الجيدة تذكر: مجمّع SKILLS جديد + renderEndorse() في src/lockedin.js، وربطه في dispatch() وhandleSlash()، وإضافة صف إلى renderHelp()، وتصدير الدالة/المجمّع الجديد، وإضافة اختبارات في كلا ملفي الاختبار. إن أغفلت الخطة قاعدة العشوائية المُبَذَّرة أو الاختبارات، قل ذلك الآن.

الخطوة 2 — الاختبار أولا

اطلب من الوكيل كتابة الاختبارات قبل التنفيذ. الاختبار أولا يحوّل مواصفاتك إلى شيء قابل للتنفيذ، ويبقي الوكيل صادقا.

«رائع. أولا، أضف اختبارات فاشلة فقط: اختبار وحدة يثبت أن renderEndorse() يُرجع نصا يذكر مهارة معروفة و5 تزكيات على الأقل، واختبار في cli.test.js يثبت أن lockedin endorse يخرج بالرمز 0 ويطبع تزكية. استخدم بذرة ثابتة. لا تنفّذ renderEndorse بعد — لنرَ الاختبارات تفشل أولا.»

شغّلها وشاهدها تفشل للسبب الصحيح (الدالة غير موجودة بعد):

npm test

الخطوة 3 — دع الوكيل ينفّذ

الآن أعطِ الضوء الأخضر للتنفيذ:

«الآن نفّذه ليُنجِح تلك الاختبارات، متبعا نمط connect. أضف مجمّع SKILLS فيه ~25 مهارة كلمة طنانة، وrenderEndorse() يُرجع سلسلة نصية، واربط dispatch وhandleSlash، وأضف صف help، وصدّر ما أضفته. استخدم pick/shuffle فقط للعشوائية.»

ما ينتجه الوكيل ينبغي أن يشبه كثيرا بقية الملف. مثلا، مجمّع SKILLS وعارض:

const SKILLS = [
  'قيادة الفكر', 'التآزر', 'السرد', 'الأجواء',
  'القيلولة الاستراتيجية', 'مواءمة أصحاب المصلحة', 'الصراحة الجذرية', /* ...~25 total... */
];

function renderEndorse() {
  const people = shuffle(NAMES).slice(0, 5 + Math.floor(rand() * 3)); // 5–7
  const skills = shuffle(SKILLS);
  const out = [''];
  people.forEach((n, i) =>
    out.push('  ✔ زكّيت ' + n + ' لمهارة ' + skills[i % skills.length]));
  out.push('', '  لقد زكّيت 6 غرباء لمهارات لا يمكنك التحقق منها. سيزكّونك بدورهم خلال ساعة.');
  return out.join('\n');
}

…زائد سطر واحد في كل من dispatch() وhandleSlash()، وصف في renderHelp()، وإضافة SKILLS, renderEndorse إلى module.exports.

الخطوة 4 — البوابة

npm test

خضراء؟ لقد شحنت للتو ميزة مع وكيل، بأسلوب الاختبار أولا. ليست خضراء؟ هذا طبيعي — اذهب إلى حلقة التكرار في الفصل 4 وأخبر الوكيل بالضبط ما الذي فشل.

ثم افحص الشيء الحقيقي بعينيك (الاختبارات تفحص النص، لكن ينبغي أن تنظر رغم ذلك):

node bin/lockedin.js endorse
LOCKEDIN_SEED=1 node bin/lockedin.js endorse   # reproducible

الخطوة 5 — راجع قبل أن تقبل

لا تقبل أبدا فرقا لم تقرأه. تصفّح بحثا عن هذه الأمور تحديدا:

• هل اتبع النمط؟ الأمر الجديد ينبغي أن يحاكي connect — بلا اعتماديات جديدة، وبلا console.log داخل src/.
• عشوائية مُبَذَّرة فقط؟ ابحث في الفرق عن Math.random. ينبغي ألا يوجد أي منها.
• هل لمس شيئا ما كان ينبغي؟ التغيير ينبغي أن يكون إضافيا؛ والأسطر غير ذات الصلة ينبغي ألا تتحرك.
• هل الاختبار الجديد ذو معنى؟ ينبغي أن يفشل إن كسر أحدهم لاحقا الميزة — لا أن يؤكد true فحسب.

إن كان أي شيء غير سليم، اطلب إصلاحا (الفصل 4). إن كان جيدا، فقد انتهيت.

---

✅ جرّبه مع وكيلك

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

• «اجعل endorse يقبل اسما اختياريا: lockedin endorse Ada ينبغي أن يزكّي Ada تحديدا. أضف اختبارا، وأبقِ البوابة خضراء.»

بنيت الآن ميزة من البداية إلى النهاية. الفصل الأخير عن أداء ذلك بسلاسة — التوجيه والمراجعة كمهندس قائد.

التالي: الدرس 4 التوجيه والمراجعة